1 c Copyright (C) 1988-2021 Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
7 @chapter Extensions to the C Language Family
8 @cindex extensions, C language
9 @cindex C language extensions
12 GNU C provides several language features not found in ISO standard C@.
13 (The @option{-pedantic} option directs GCC to print a warning message if
14 any of these features is used.) To test for the availability of these
15 features in conditional compilation, check for a predefined macro
16 @code{__GNUC__}, which is always defined under GCC@.
18 These extensions are available in C and Objective-C@. Most of them are
19 also available in C++. @xref{C++ Extensions,,Extensions to the
20 C++ Language}, for extensions that apply @emph{only} to C++.
22 Some features that are in ISO C99 but not C90 or C++ are also, as
23 extensions, accepted by GCC in C90 mode and in C++.
26 * Statement Exprs:: Putting statements and declarations inside expressions.
27 * Local Labels:: Labels local to a block.
28 * Labels as Values:: Getting pointers to labels, and computed gotos.
29 * Nested Functions:: Nested function in GNU C.
30 * Nonlocal Gotos:: Nonlocal gotos.
31 * Constructing Calls:: Dispatching a call to another function.
32 * Typeof:: @code{typeof}: referring to the type of an expression.
33 * Conditionals:: Omitting the middle operand of a @samp{?:} expression.
34 * __int128:: 128-bit integers---@code{__int128}.
35 * Long Long:: Double-word integers---@code{long long int}.
36 * Complex:: Data types for complex numbers.
37 * Floating Types:: Additional Floating Types.
38 * Half-Precision:: Half-Precision Floating Point.
39 * Decimal Float:: Decimal Floating Types.
40 * Hex Floats:: Hexadecimal floating-point constants.
41 * Fixed-Point:: Fixed-Point Types.
42 * Named Address Spaces::Named address spaces.
43 * Zero Length:: Zero-length arrays.
44 * Empty Structures:: Structures with no members.
45 * Variable Length:: Arrays whose length is computed at run time.
46 * Variadic Macros:: Macros with a variable number of arguments.
47 * Escaped Newlines:: Slightly looser rules for escaped newlines.
48 * Subscripting:: Any array can be subscripted, even if not an lvalue.
49 * Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
50 * Variadic Pointer Args:: Pointer arguments to variadic functions.
51 * Pointers to Arrays:: Pointers to arrays with qualifiers work as expected.
52 * Initializers:: Non-constant initializers.
53 * Compound Literals:: Compound literals give structures, unions
55 * Designated Inits:: Labeling elements of initializers.
56 * Case Ranges:: `case 1 ... 9' and such.
57 * Cast to Union:: Casting to union type from any member of the union.
58 * Mixed Labels and Declarations:: Mixing declarations, labels and code.
59 * Function Attributes:: Declaring that functions have no side effects,
60 or that they can never return.
61 * Variable Attributes:: Specifying attributes of variables.
62 * Type Attributes:: Specifying attributes of types.
63 * Label Attributes:: Specifying attributes on labels.
64 * Enumerator Attributes:: Specifying attributes on enumerators.
65 * Statement Attributes:: Specifying attributes on statements.
66 * Attribute Syntax:: Formal syntax for attributes.
67 * Function Prototypes:: Prototype declarations and old-style definitions.
68 * C++ Comments:: C++ comments are recognized.
69 * Dollar Signs:: Dollar sign is allowed in identifiers.
70 * Character Escapes:: @samp{\e} stands for the character @key{ESC}.
71 * Alignment:: Determining the alignment of a function, type or variable.
72 * Inline:: Defining inline functions (as fast as macros).
73 * Volatiles:: What constitutes an access to a volatile object.
74 * Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler.
75 * Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
76 * Incomplete Enums:: @code{enum foo;}, with details to follow.
77 * Function Names:: Printable strings which are the name of the current
79 * Return Address:: Getting the return or frame address of a function.
80 * Vector Extensions:: Using vector instructions through built-in functions.
81 * Offsetof:: Special syntax for implementing @code{offsetof}.
82 * __sync Builtins:: Legacy built-in functions for atomic memory access.
83 * __atomic Builtins:: Atomic built-in functions with memory model.
84 * Integer Overflow Builtins:: Built-in functions to perform arithmetics and
85 arithmetic overflow checking.
86 * x86 specific memory model extensions for transactional memory:: x86 memory models.
87 * Object Size Checking:: Built-in functions for limited buffer overflow
89 * Other Builtins:: Other built-in functions.
90 * Target Builtins:: Built-in functions specific to particular targets.
91 * Target Format Checks:: Format checks specific to particular targets.
92 * Pragmas:: Pragmas accepted by GCC.
93 * Unnamed Fields:: Unnamed struct/union fields within structs/unions.
94 * Thread-Local:: Per-thread variables.
95 * Binary constants:: Binary constants using the @samp{0b} prefix.
99 @section Statements and Declarations in Expressions
100 @cindex statements inside expressions
101 @cindex declarations inside expressions
102 @cindex expressions containing statements
103 @cindex macros, statements in expressions
105 @c the above section title wrapped and causes an underfull hbox.. i
106 @c changed it from "within" to "in". --mew 4feb93
107 A compound statement enclosed in parentheses may appear as an expression
108 in GNU C@. This allows you to use loops, switches, and local variables
109 within an expression.
111 Recall that a compound statement is a sequence of statements surrounded
112 by braces; in this construct, parentheses go around the braces. For
116 (@{ int y = foo (); int z;
123 is a valid (though slightly more complex than necessary) expression
124 for the absolute value of @code{foo ()}.
126 The last thing in the compound statement should be an expression
127 followed by a semicolon; the value of this subexpression serves as the
128 value of the entire construct. (If you use some other kind of statement
129 last within the braces, the construct has type @code{void}, and thus
130 effectively no value.)
132 This feature is especially useful in making macro definitions ``safe'' (so
133 that they evaluate each operand exactly once). For example, the
134 ``maximum'' function is commonly defined as a macro in standard C as
138 #define max(a,b) ((a) > (b) ? (a) : (b))
142 @cindex side effects, macro argument
143 But this definition computes either @var{a} or @var{b} twice, with bad
144 results if the operand has side effects. In GNU C, if you know the
145 type of the operands (here taken as @code{int}), you can avoid this
146 problem by defining the macro as follows:
149 #define maxint(a,b) \
150 (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
153 Note that introducing variable declarations (as we do in @code{maxint}) can
154 cause variable shadowing, so while this example using the @code{max} macro
155 produces correct results:
157 int _a = 1, _b = 2, c;
161 this example using maxint will not:
163 int _a = 1, _b = 2, c;
167 This problem may for instance occur when we use this pattern recursively, like
171 #define maxint3(a, b, c) \
172 (@{int _a = (a), _b = (b), _c = (c); maxint (maxint (_a, _b), _c); @})
175 Embedded statements are not allowed in constant expressions, such as
176 the value of an enumeration constant, the width of a bit-field, or
177 the initial value of a static variable.
179 If you don't know the type of the operand, you can still do this, but you
180 must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}).
182 In G++, the result value of a statement expression undergoes array and
183 function pointer decay, and is returned by value to the enclosing
184 expression. For instance, if @code{A} is a class, then
193 constructs a temporary @code{A} object to hold the result of the
194 statement expression, and that is used to invoke @code{Foo}.
195 Therefore the @code{this} pointer observed by @code{Foo} is not the
198 In a statement expression, any temporaries created within a statement
199 are destroyed at that statement's end. This makes statement
200 expressions inside macros slightly different from function calls. In
201 the latter case temporaries introduced during argument evaluation are
202 destroyed at the end of the statement that includes the function
203 call. In the statement expression case they are destroyed during
204 the statement expression. For instance,
207 #define macro(a) (@{__typeof__(a) b = (a); b + 3; @})
208 template<typename T> T function(T a) @{ T b = a; return b + 3; @}
218 has different places where temporaries are destroyed. For the
219 @code{macro} case, the temporary @code{X} is destroyed just after
220 the initialization of @code{b}. In the @code{function} case that
221 temporary is destroyed when the function returns.
223 These considerations mean that it is probably a bad idea to use
224 statement expressions of this form in header files that are designed to
225 work with C++. (Note that some versions of the GNU C Library contained
226 header files using statement expressions that lead to precisely this
229 Jumping into a statement expression with @code{goto} or using a
230 @code{switch} statement outside the statement expression with a
231 @code{case} or @code{default} label inside the statement expression is
232 not permitted. Jumping into a statement expression with a computed
233 @code{goto} (@pxref{Labels as Values}) has undefined behavior.
234 Jumping out of a statement expression is permitted, but if the
235 statement expression is part of a larger expression then it is
236 unspecified which other subexpressions of that expression have been
237 evaluated except where the language definition requires certain
238 subexpressions to be evaluated before or after the statement
239 expression. A @code{break} or @code{continue} statement inside of
240 a statement expression used in @code{while}, @code{do} or @code{for}
241 loop or @code{switch} statement condition
242 or @code{for} statement init or increment expressions jumps to an
243 outer loop or @code{switch} statement if any (otherwise it is an error),
244 rather than to the loop or @code{switch} statement in whose condition
245 or init or increment expression it appears.
246 In any case, as with a function call, the evaluation of a
247 statement expression is not interleaved with the evaluation of other
248 parts of the containing expression. For example,
251 foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz();
255 calls @code{foo} and @code{bar1} and does not call @code{baz} but
256 may or may not call @code{bar2}. If @code{bar2} is called, it is
257 called after @code{foo} and before @code{bar1}.
260 @section Locally Declared Labels
262 @cindex macros, local labels
264 GCC allows you to declare @dfn{local labels} in any nested block
265 scope. A local label is just like an ordinary label, but you can
266 only reference it (with a @code{goto} statement, or by taking its
267 address) within the block in which it is declared.
269 A local label declaration looks like this:
272 __label__ @var{label};
279 __label__ @var{label1}, @var{label2}, /* @r{@dots{}} */;
282 Local label declarations must come at the beginning of the block,
283 before any ordinary declarations or statements.
285 The label declaration defines the label @emph{name}, but does not define
286 the label itself. You must do this in the usual way, with
287 @code{@var{label}:}, within the statements of the statement expression.
289 The local label feature is useful for complex macros. If a macro
290 contains nested loops, a @code{goto} can be useful for breaking out of
291 them. However, an ordinary label whose scope is the whole function
292 cannot be used: if the macro can be expanded several times in one
293 function, the label is multiply defined in that function. A
294 local label avoids this problem. For example:
297 #define SEARCH(value, array, target) \
300 typeof (target) _SEARCH_target = (target); \
301 typeof (*(array)) *_SEARCH_array = (array); \
304 for (i = 0; i < max; i++) \
305 for (j = 0; j < max; j++) \
306 if (_SEARCH_array[i][j] == _SEARCH_target) \
307 @{ (value) = i; goto found; @} \
313 This could also be written using a statement expression:
316 #define SEARCH(array, target) \
319 typeof (target) _SEARCH_target = (target); \
320 typeof (*(array)) *_SEARCH_array = (array); \
323 for (i = 0; i < max; i++) \
324 for (j = 0; j < max; j++) \
325 if (_SEARCH_array[i][j] == _SEARCH_target) \
326 @{ value = i; goto found; @} \
333 Local label declarations also make the labels they declare visible to
334 nested functions, if there are any. @xref{Nested Functions}, for details.
336 @node Labels as Values
337 @section Labels as Values
338 @cindex labels as values
339 @cindex computed gotos
340 @cindex goto with computed label
341 @cindex address of a label
343 You can get the address of a label defined in the current function
344 (or a containing function) with the unary operator @samp{&&}. The
345 value has type @code{void *}. This value is a constant and can be used
346 wherever a constant of that type is valid. For example:
354 To use these values, you need to be able to jump to one. This is done
355 with the computed goto statement@footnote{The analogous feature in
356 Fortran is called an assigned goto, but that name seems inappropriate in
357 C, where one can do more than simply store label addresses in label
358 variables.}, @code{goto *@var{exp};}. For example,
365 Any expression of type @code{void *} is allowed.
367 One way of using these constants is in initializing a static array that
368 serves as a jump table:
371 static void *array[] = @{ &&foo, &&bar, &&hack @};
375 Then you can select a label with indexing, like this:
382 Note that this does not check whether the subscript is in bounds---array
383 indexing in C never does that.
385 Such an array of label values serves a purpose much like that of the
386 @code{switch} statement. The @code{switch} statement is cleaner, so
387 use that rather than an array unless the problem does not fit a
388 @code{switch} statement very well.
390 Another use of label values is in an interpreter for threaded code.
391 The labels within the interpreter function can be stored in the
392 threaded code for super-fast dispatching.
394 You may not use this mechanism to jump to code in a different function.
395 If you do that, totally unpredictable things happen. The best way to
396 avoid this is to store the label address only in automatic variables and
397 never pass it as an argument.
399 An alternate way to write the above example is
402 static const int array[] = @{ &&foo - &&foo, &&bar - &&foo,
404 goto *(&&foo + array[i]);
408 This is more friendly to code living in shared libraries, as it reduces
409 the number of dynamic relocations that are needed, and by consequence,
410 allows the data to be read-only.
411 This alternative with label differences is not supported for the AVR target,
412 please use the first approach for AVR programs.
414 The @code{&&foo} expressions for the same label might have different
415 values if the containing function is inlined or cloned. If a program
416 relies on them being always the same,
417 @code{__attribute__((__noinline__,__noclone__))} should be used to
418 prevent inlining and cloning. If @code{&&foo} is used in a static
419 variable initializer, inlining and cloning is forbidden.
421 @node Nested Functions
422 @section Nested Functions
423 @cindex nested functions
424 @cindex downward funargs
427 A @dfn{nested function} is a function defined inside another function.
428 Nested functions are supported as an extension in GNU C, but are not
429 supported by GNU C++.
431 The nested function's name is local to the block where it is defined.
432 For example, here we define a nested function named @code{square}, and
437 foo (double a, double b)
439 double square (double z) @{ return z * z; @}
441 return square (a) + square (b);
446 The nested function can access all the variables of the containing
447 function that are visible at the point of its definition. This is
448 called @dfn{lexical scoping}. For example, here we show a nested
449 function which uses an inherited variable named @code{offset}:
453 bar (int *array, int offset, int size)
455 int access (int *array, int index)
456 @{ return array[index + offset]; @}
459 for (i = 0; i < size; i++)
460 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
465 Nested function definitions are permitted within functions in the places
466 where variable definitions are allowed; that is, in any block, mixed
467 with the other declarations and statements in the block.
469 It is possible to call the nested function from outside the scope of its
470 name by storing its address or passing the address to another function:
473 hack (int *array, int size)
475 void store (int index, int value)
476 @{ array[index] = value; @}
478 intermediate (store, size);
482 Here, the function @code{intermediate} receives the address of
483 @code{store} as an argument. If @code{intermediate} calls @code{store},
484 the arguments given to @code{store} are used to store into @code{array}.
485 But this technique works only so long as the containing function
486 (@code{hack}, in this example) does not exit.
488 If you try to call the nested function through its address after the
489 containing function exits, all hell breaks loose. If you try
490 to call it after a containing scope level exits, and if it refers
491 to some of the variables that are no longer in scope, you may be lucky,
492 but it's not wise to take the risk. If, however, the nested function
493 does not refer to anything that has gone out of scope, you should be
496 GCC implements taking the address of a nested function using a technique
497 called @dfn{trampolines}. This technique was described in
498 @cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX
499 C++ Conference Proceedings, October 17-21, 1988).
501 A nested function can jump to a label inherited from a containing
502 function, provided the label is explicitly declared in the containing
503 function (@pxref{Local Labels}). Such a jump returns instantly to the
504 containing function, exiting the nested function that did the
505 @code{goto} and any intermediate functions as well. Here is an example:
509 bar (int *array, int offset, int size)
512 int access (int *array, int index)
516 return array[index + offset];
520 for (i = 0; i < size; i++)
521 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
525 /* @r{Control comes here from @code{access}
526 if it detects an error.} */
533 A nested function always has no linkage. Declaring one with
534 @code{extern} or @code{static} is erroneous. If you need to declare the nested function
535 before its definition, use @code{auto} (which is otherwise meaningless
536 for function declarations).
539 bar (int *array, int offset, int size)
542 auto int access (int *, int);
544 int access (int *array, int index)
548 return array[index + offset];
555 @section Nonlocal Gotos
556 @cindex nonlocal gotos
558 GCC provides the built-in functions @code{__builtin_setjmp} and
559 @code{__builtin_longjmp} which are similar to, but not interchangeable
560 with, the C library functions @code{setjmp} and @code{longjmp}.
561 The built-in versions are used internally by GCC's libraries
562 to implement exception handling on some targets. You should use the
563 standard C library functions declared in @code{<setjmp.h>} in user code
564 instead of the builtins.
566 The built-in versions of these functions use GCC's normal
567 mechanisms to save and restore registers using the stack on function
568 entry and exit. The jump buffer argument @var{buf} holds only the
569 information needed to restore the stack frame, rather than the entire
570 set of saved register values.
572 An important caveat is that GCC arranges to save and restore only
573 those registers known to the specific architecture variant being
574 compiled for. This can make @code{__builtin_setjmp} and
575 @code{__builtin_longjmp} more efficient than their library
576 counterparts in some cases, but it can also cause incorrect and
577 mysterious behavior when mixing with code that uses the full register
580 You should declare the jump buffer argument @var{buf} to the
581 built-in functions as:
585 intptr_t @var{buf}[5];
588 @deftypefn {Built-in Function} {int} __builtin_setjmp (intptr_t *@var{buf})
589 This function saves the current stack context in @var{buf}.
590 @code{__builtin_setjmp} returns 0 when returning directly,
591 and 1 when returning from @code{__builtin_longjmp} using the same
595 @deftypefn {Built-in Function} {void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val})
596 This function restores the stack context in @var{buf},
597 saved by a previous call to @code{__builtin_setjmp}. After
598 @code{__builtin_longjmp} is finished, the program resumes execution as
599 if the matching @code{__builtin_setjmp} returns the value @var{val},
602 Because @code{__builtin_longjmp} depends on the function return
603 mechanism to restore the stack context, it cannot be called
604 from the same function calling @code{__builtin_setjmp} to
605 initialize @var{buf}. It can only be called from a function called
606 (directly or indirectly) from the function calling @code{__builtin_setjmp}.
609 @node Constructing Calls
610 @section Constructing Function Calls
611 @cindex constructing calls
612 @cindex forwarding calls
614 Using the built-in functions described below, you can record
615 the arguments a function received, and call another function
616 with the same arguments, without knowing the number or types
619 You can also record the return value of that function call,
620 and later return that value, without knowing what data type
621 the function tried to return (as long as your caller expects
624 However, these built-in functions may interact badly with some
625 sophisticated features or other extensions of the language. It
626 is, therefore, not recommended to use them outside very simple
627 functions acting as mere forwarders for their arguments.
629 @deftypefn {Built-in Function} {void *} __builtin_apply_args ()
630 This built-in function returns a pointer to data
631 describing how to perform a call with the same arguments as are passed
632 to the current function.
634 The function saves the arg pointer register, structure value address,
635 and all registers that might be used to pass arguments to a function
636 into a block of memory allocated on the stack. Then it returns the
637 address of that block.
640 @deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})
641 This built-in function invokes @var{function}
642 with a copy of the parameters described by @var{arguments}
645 The value of @var{arguments} should be the value returned by
646 @code{__builtin_apply_args}. The argument @var{size} specifies the size
647 of the stack argument data, in bytes.
649 This function returns a pointer to data describing
650 how to return whatever value is returned by @var{function}. The data
651 is saved in a block of memory allocated on the stack.
653 It is not always simple to compute the proper value for @var{size}. The
654 value is used by @code{__builtin_apply} to compute the amount of data
655 that should be pushed on the stack and copied from the incoming argument
659 @deftypefn {Built-in Function} {void} __builtin_return (void *@var{result})
660 This built-in function returns the value described by @var{result} from
661 the containing function. You should specify, for @var{result}, a value
662 returned by @code{__builtin_apply}.
665 @deftypefn {Built-in Function} {} __builtin_va_arg_pack ()
666 This built-in function represents all anonymous arguments of an inline
667 function. It can be used only in inline functions that are always
668 inlined, never compiled as a separate function, such as those using
669 @code{__attribute__ ((__always_inline__))} or
670 @code{__attribute__ ((__gnu_inline__))} extern inline functions.
671 It must be only passed as last argument to some other function
672 with variable arguments. This is useful for writing small wrapper
673 inlines for variable argument functions, when using preprocessor
674 macros is undesirable. For example:
676 extern int myprintf (FILE *f, const char *format, ...);
677 extern inline __attribute__ ((__gnu_inline__)) int
678 myprintf (FILE *f, const char *format, ...)
680 int r = fprintf (f, "myprintf: ");
683 int s = fprintf (f, format, __builtin_va_arg_pack ());
691 @deftypefn {Built-in Function} {size_t} __builtin_va_arg_pack_len ()
692 This built-in function returns the number of anonymous arguments of
693 an inline function. It can be used only in inline functions that
694 are always inlined, never compiled as a separate function, such
695 as those using @code{__attribute__ ((__always_inline__))} or
696 @code{__attribute__ ((__gnu_inline__))} extern inline functions.
697 For example following does link- or run-time checking of open
698 arguments for optimized code:
701 extern inline __attribute__((__gnu_inline__)) int
702 myopen (const char *path, int oflag, ...)
704 if (__builtin_va_arg_pack_len () > 1)
705 warn_open_too_many_arguments ();
707 if (__builtin_constant_p (oflag))
709 if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1)
711 warn_open_missing_mode ();
712 return __open_2 (path, oflag);
714 return open (path, oflag, __builtin_va_arg_pack ());
717 if (__builtin_va_arg_pack_len () < 1)
718 return __open_2 (path, oflag);
720 return open (path, oflag, __builtin_va_arg_pack ());
727 @section Referring to a Type with @code{typeof}
730 @cindex macros, types of arguments
732 Another way to refer to the type of an expression is with @code{typeof}.
733 The syntax of using of this keyword looks like @code{sizeof}, but the
734 construct acts semantically like a type name defined with @code{typedef}.
736 There are two ways of writing the argument to @code{typeof}: with an
737 expression or with a type. Here is an example with an expression:
744 This assumes that @code{x} is an array of pointers to functions;
745 the type described is that of the values of the functions.
747 Here is an example with a typename as the argument:
754 Here the type described is that of pointers to @code{int}.
756 If you are writing a header file that must work when included in ISO C
757 programs, write @code{__typeof__} instead of @code{typeof}.
758 @xref{Alternate Keywords}.
760 A @code{typeof} construct can be used anywhere a typedef name can be
761 used. For example, you can use it in a declaration, in a cast, or inside
762 of @code{sizeof} or @code{typeof}.
764 The operand of @code{typeof} is evaluated for its side effects if and
765 only if it is an expression of variably modified type or the name of
768 @code{typeof} is often useful in conjunction with
769 statement expressions (@pxref{Statement Exprs}).
770 Here is how the two together can
771 be used to define a safe ``maximum'' macro which operates on any
772 arithmetic type and evaluates each of its arguments exactly once:
776 (@{ typeof (a) _a = (a); \
777 typeof (b) _b = (b); \
778 _a > _b ? _a : _b; @})
781 @cindex underscores in variables in macros
782 @cindex @samp{_} in variables in macros
783 @cindex local variables in macros
784 @cindex variables, local, in macros
785 @cindex macros, local variables in
787 The reason for using names that start with underscores for the local
788 variables is to avoid conflicts with variable names that occur within the
789 expressions that are substituted for @code{a} and @code{b}. Eventually we
790 hope to design a new form of declaration syntax that allows you to declare
791 variables whose scopes start only after their initializers; this will be a
792 more reliable way to prevent such conflicts.
795 Some more examples of the use of @code{typeof}:
799 This declares @code{y} with the type of what @code{x} points to.
806 This declares @code{y} as an array of such values.
813 This declares @code{y} as an array of pointers to characters:
816 typeof (typeof (char *)[4]) y;
820 It is equivalent to the following traditional C declaration:
826 To see the meaning of the declaration using @code{typeof}, and why it
827 might be a useful way to write, rewrite it with these macros:
830 #define pointer(T) typeof(T *)
831 #define array(T, N) typeof(T [N])
835 Now the declaration can be rewritten this way:
838 array (pointer (char), 4) y;
842 Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
843 pointers to @code{char}.
846 In GNU C, but not GNU C++, you may also declare the type of a variable
847 as @code{__auto_type}. In that case, the declaration must declare
848 only one variable, whose declarator must just be an identifier, the
849 declaration must be initialized, and the type of the variable is
850 determined by the initializer; the name of the variable is not in
851 scope until after the initializer. (In C++, you should use C++11
852 @code{auto} for this purpose.) Using @code{__auto_type}, the
853 ``maximum'' macro above could be written as:
857 (@{ __auto_type _a = (a); \
858 __auto_type _b = (b); \
859 _a > _b ? _a : _b; @})
862 Using @code{__auto_type} instead of @code{typeof} has two advantages:
865 @item Each argument to the macro appears only once in the expansion of
866 the macro. This prevents the size of the macro expansion growing
867 exponentially when calls to such macros are nested inside arguments of
870 @item If the argument to the macro has variably modified type, it is
871 evaluated only once when using @code{__auto_type}, but twice if
872 @code{typeof} is used.
876 @section Conditionals with Omitted Operands
877 @cindex conditional expressions, extensions
878 @cindex omitted middle-operands
879 @cindex middle-operands, omitted
880 @cindex extensions, @code{?:}
881 @cindex @code{?:} extensions
883 The middle operand in a conditional expression may be omitted. Then
884 if the first operand is nonzero, its value is the value of the conditional
887 Therefore, the expression
894 has the value of @code{x} if that is nonzero; otherwise, the value of
897 This example is perfectly equivalent to
903 @cindex side effect in @code{?:}
904 @cindex @code{?:} side effect
906 In this simple case, the ability to omit the middle operand is not
907 especially useful. When it becomes useful is when the first operand does,
908 or may (if it is a macro argument), contain a side effect. Then repeating
909 the operand in the middle would perform the side effect twice. Omitting
910 the middle operand uses the value already computed without the undesirable
911 effects of recomputing it.
914 @section 128-bit Integers
915 @cindex @code{__int128} data types
917 As an extension the integer scalar type @code{__int128} is supported for
918 targets which have an integer mode wide enough to hold 128 bits.
919 Simply write @code{__int128} for a signed 128-bit integer, or
920 @code{unsigned __int128} for an unsigned 128-bit integer. There is no
921 support in GCC for expressing an integer constant of type @code{__int128}
922 for targets with @code{long long} integer less than 128 bits wide.
925 @section Double-Word Integers
926 @cindex @code{long long} data types
927 @cindex double-word arithmetic
928 @cindex multiprecision arithmetic
929 @cindex @code{LL} integer suffix
930 @cindex @code{ULL} integer suffix
932 ISO C99 and ISO C++11 support data types for integers that are at least
933 64 bits wide, and as an extension GCC supports them in C90 and C++98 modes.
934 Simply write @code{long long int} for a signed integer, or
935 @code{unsigned long long int} for an unsigned integer. To make an
936 integer constant of type @code{long long int}, add the suffix @samp{LL}
937 to the integer. To make an integer constant of type @code{unsigned long
938 long int}, add the suffix @samp{ULL} to the integer.
940 You can use these types in arithmetic like any other integer types.
941 Addition, subtraction, and bitwise boolean operations on these types
942 are open-coded on all types of machines. Multiplication is open-coded
943 if the machine supports a fullword-to-doubleword widening multiply
944 instruction. Division and shifts are open-coded only on machines that
945 provide special support. The operations that are not open-coded use
946 special library routines that come with GCC@.
948 There may be pitfalls when you use @code{long long} types for function
949 arguments without function prototypes. If a function
950 expects type @code{int} for its argument, and you pass a value of type
951 @code{long long int}, confusion results because the caller and the
952 subroutine disagree about the number of bytes for the argument.
953 Likewise, if the function expects @code{long long int} and you pass
954 @code{int}. The best way to avoid such problems is to use prototypes.
957 @section Complex Numbers
958 @cindex complex numbers
959 @cindex @code{_Complex} keyword
960 @cindex @code{__complex__} keyword
962 ISO C99 supports complex floating data types, and as an extension GCC
963 supports them in C90 mode and in C++. GCC also supports complex integer data
964 types which are not part of ISO C99. You can declare complex types
965 using the keyword @code{_Complex}. As an extension, the older GNU
966 keyword @code{__complex__} is also supported.
968 For example, @samp{_Complex double x;} declares @code{x} as a
969 variable whose real part and imaginary part are both of type
970 @code{double}. @samp{_Complex short int y;} declares @code{y} to
971 have real and imaginary parts of type @code{short int}; this is not
972 likely to be useful, but it shows that the set of complex types is
975 To write a constant with a complex data type, use the suffix @samp{i} or
976 @samp{j} (either one; they are equivalent). For example, @code{2.5fi}
977 has type @code{_Complex float} and @code{3i} has type
978 @code{_Complex int}. Such a constant always has a pure imaginary
979 value, but you can form any complex value you like by adding one to a
980 real constant. This is a GNU extension; if you have an ISO C99
981 conforming C library (such as the GNU C Library), and want to construct complex
982 constants of floating type, you should include @code{<complex.h>} and
983 use the macros @code{I} or @code{_Complex_I} instead.
985 The ISO C++14 library also defines the @samp{i} suffix, so C++14 code
986 that includes the @samp{<complex>} header cannot use @samp{i} for the
987 GNU extension. The @samp{j} suffix still has the GNU meaning.
989 @cindex @code{__real__} keyword
990 @cindex @code{__imag__} keyword
991 To extract the real part of a complex-valued expression @var{exp}, write
992 @code{__real__ @var{exp}}. Likewise, use @code{__imag__} to
993 extract the imaginary part. This is a GNU extension; for values of
994 floating type, you should use the ISO C99 functions @code{crealf},
995 @code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and
996 @code{cimagl}, declared in @code{<complex.h>} and also provided as
997 built-in functions by GCC@.
999 @cindex complex conjugation
1000 The operator @samp{~} performs complex conjugation when used on a value
1001 with a complex type. This is a GNU extension; for values of
1002 floating type, you should use the ISO C99 functions @code{conjf},
1003 @code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
1004 provided as built-in functions by GCC@.
1006 GCC can allocate complex automatic variables in a noncontiguous
1007 fashion; it's even possible for the real part to be in a register while
1008 the imaginary part is on the stack (or vice versa). Only the DWARF
1009 debug info format can represent this, so use of DWARF is recommended.
1010 If you are using the stabs debug info format, GCC describes a noncontiguous
1011 complex variable as if it were two separate variables of noncomplex type.
1012 If the variable's actual name is @code{foo}, the two fictitious
1013 variables are named @code{foo$real} and @code{foo$imag}. You can
1014 examine and set these two fictitious variables with your debugger.
1016 @node Floating Types
1017 @section Additional Floating Types
1018 @cindex additional floating types
1019 @cindex @code{_Float@var{n}} data types
1020 @cindex @code{_Float@var{n}x} data types
1021 @cindex @code{__float80} data type
1022 @cindex @code{__float128} data type
1023 @cindex @code{__ibm128} data type
1024 @cindex @code{w} floating point suffix
1025 @cindex @code{q} floating point suffix
1026 @cindex @code{W} floating point suffix
1027 @cindex @code{Q} floating point suffix
1029 ISO/IEC TS 18661-3:2015 defines C support for additional floating
1030 types @code{_Float@var{n}} and @code{_Float@var{n}x}, and GCC supports
1031 these type names; the set of types supported depends on the target
1032 architecture. These types are not supported when compiling C++.
1033 Constants with these types use suffixes @code{f@var{n}} or
1034 @code{F@var{n}} and @code{f@var{n}x} or @code{F@var{n}x}. These type
1035 names can be used together with @code{_Complex} to declare complex
1038 As an extension, GNU C and GNU C++ support additional floating
1039 types, which are not supported by all targets.
1041 @item @code{__float128} is available on i386, x86_64, IA-64, and
1042 hppa HP-UX, as well as on PowerPC GNU/Linux targets that enable
1043 the vector scalar (VSX) instruction set. @code{__float128} supports
1044 the 128-bit floating type. On i386, x86_64, PowerPC, and IA-64
1045 other than HP-UX, @code{__float128} is an alias for @code{_Float128}.
1046 On hppa and IA-64 HP-UX, @code{__float128} is an alias for @code{long
1049 @item @code{__float80} is available on the i386, x86_64, and IA-64
1050 targets, and supports the 80-bit (@code{XFmode}) floating type. It is
1051 an alias for the type name @code{_Float64x} on these targets.
1053 @item @code{__ibm128} is available on PowerPC targets, and provides
1054 access to the IBM extended double format which is the current format
1055 used for @code{long double}. When @code{long double} transitions to
1056 @code{__float128} on PowerPC in the future, @code{__ibm128} will remain
1057 for use in conversions between the two types.
1060 Support for these additional types includes the arithmetic operators:
1061 add, subtract, multiply, divide; unary arithmetic operators;
1062 relational operators; equality operators; and conversions to and from
1063 integer and other floating types. Use a suffix @samp{w} or @samp{W}
1064 in a literal constant of type @code{__float80} or type
1065 @code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{_float128}.
1067 In order to use @code{_Float128}, @code{__float128}, and @code{__ibm128}
1068 on PowerPC Linux systems, you must use the @option{-mfloat128} option. It is
1069 expected in future versions of GCC that @code{_Float128} and @code{__float128}
1070 will be enabled automatically.
1072 The @code{_Float128} type is supported on all systems where
1073 @code{__float128} is supported or where @code{long double} has the
1074 IEEE binary128 format. The @code{_Float64x} type is supported on all
1075 systems where @code{__float128} is supported. The @code{_Float32}
1076 type is supported on all systems supporting IEEE binary32; the
1077 @code{_Float64} and @code{_Float32x} types are supported on all systems
1078 supporting IEEE binary64. The @code{_Float16} type is supported on AArch64
1079 systems by default, and on ARM systems when the IEEE format for 16-bit
1080 floating-point types is selected with @option{-mfp16-format=ieee}.
1081 GCC does not currently support @code{_Float128x} on any systems.
1083 On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex
1084 types using the corresponding internal complex type, @code{XCmode} for
1085 @code{__float80} type and @code{TCmode} for @code{__float128} type:
1088 typedef _Complex float __attribute__((mode(TC))) _Complex128;
1089 typedef _Complex float __attribute__((mode(XC))) _Complex80;
1092 On the PowerPC Linux VSX targets, you can declare complex types using
1093 the corresponding internal complex type, @code{KCmode} for
1094 @code{__float128} type and @code{ICmode} for @code{__ibm128} type:
1097 typedef _Complex float __attribute__((mode(KC))) _Complex_float128;
1098 typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128;
1101 @node Half-Precision
1102 @section Half-Precision Floating Point
1103 @cindex half-precision floating point
1104 @cindex @code{__fp16} data type
1106 On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating
1107 point via the @code{__fp16} type defined in the ARM C Language Extensions.
1108 On ARM systems, you must enable this type explicitly with the
1109 @option{-mfp16-format} command-line option in order to use it.
1111 ARM targets support two incompatible representations for half-precision
1112 floating-point values. You must choose one of the representations and
1113 use it consistently in your program.
1115 Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format.
1116 This format can represent normalized values in the range of @math{2^{-14}} to 65504.
1117 There are 11 bits of significand precision, approximately 3
1120 Specifying @option{-mfp16-format=alternative} selects the ARM
1121 alternative format. This representation is similar to the IEEE
1122 format, but does not support infinities or NaNs. Instead, the range
1123 of exponents is extended, so that this format can represent normalized
1124 values in the range of @math{2^{-14}} to 131008.
1126 The GCC port for AArch64 only supports the IEEE 754-2008 format, and does
1127 not require use of the @option{-mfp16-format} command-line option.
1129 The @code{__fp16} type may only be used as an argument to intrinsics defined
1130 in @code{<arm_fp16.h>}, or as a storage format. For purposes of
1131 arithmetic and other operations, @code{__fp16} values in C or C++
1132 expressions are automatically promoted to @code{float}.
1134 The ARM target provides hardware support for conversions between
1135 @code{__fp16} and @code{float} values
1136 as an extension to VFP and NEON (Advanced SIMD), and from ARMv8-A provides
1137 hardware support for conversions between @code{__fp16} and @code{double}
1138 values. GCC generates code using these hardware instructions if you
1139 compile with options to select an FPU that provides them;
1140 for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp},
1141 in addition to the @option{-mfp16-format} option to select
1142 a half-precision format.
1144 Language-level support for the @code{__fp16} data type is
1145 independent of whether GCC generates code using hardware floating-point
1146 instructions. In cases where hardware support is not specified, GCC
1147 implements conversions between @code{__fp16} and other types as library
1150 It is recommended that portable code use the @code{_Float16} type defined
1151 by ISO/IEC TS 18661-3:2015. @xref{Floating Types}.
1154 @section Decimal Floating Types
1155 @cindex decimal floating types
1156 @cindex @code{_Decimal32} data type
1157 @cindex @code{_Decimal64} data type
1158 @cindex @code{_Decimal128} data type
1159 @cindex @code{df} integer suffix
1160 @cindex @code{dd} integer suffix
1161 @cindex @code{dl} integer suffix
1162 @cindex @code{DF} integer suffix
1163 @cindex @code{DD} integer suffix
1164 @cindex @code{DL} integer suffix
1166 As an extension, GNU C supports decimal floating types as
1167 defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal
1168 floating types in GCC will evolve as the draft technical report changes.
1169 Calling conventions for any target might also change. Not all targets
1170 support decimal floating types.
1172 The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and
1173 @code{_Decimal128}. They use a radix of ten, unlike the floating types
1174 @code{float}, @code{double}, and @code{long double} whose radix is not
1175 specified by the C standard but is usually two.
1177 Support for decimal floating types includes the arithmetic operators
1178 add, subtract, multiply, divide; unary arithmetic operators;
1179 relational operators; equality operators; and conversions to and from
1180 integer and other floating types. Use a suffix @samp{df} or
1181 @samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
1182 or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
1185 GCC support of decimal float as specified by the draft technical report
1190 When the value of a decimal floating type cannot be represented in the
1191 integer type to which it is being converted, the result is undefined
1192 rather than the result value specified by the draft technical report.
1195 GCC does not provide the C library functionality associated with
1196 @file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and
1197 @file{wchar.h}, which must come from a separate C library implementation.
1198 Because of this the GNU C compiler does not define macro
1199 @code{__STDC_DEC_FP__} to indicate that the implementation conforms to
1200 the technical report.
1203 Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
1204 are supported by the DWARF debug information format.
1210 ISO C99 and ISO C++17 support floating-point numbers written not only in
1211 the usual decimal notation, such as @code{1.55e1}, but also numbers such as
1212 @code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC
1213 supports this in C90 mode (except in some cases when strictly
1214 conforming) and in C++98, C++11 and C++14 modes. In that format the
1215 @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
1216 mandatory. The exponent is a decimal number that indicates the power of
1217 2 by which the significant part is multiplied. Thus @samp{0x1.f} is
1224 @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
1225 is the same as @code{1.55e1}.
1227 Unlike for floating-point numbers in the decimal notation the exponent
1228 is always required in the hexadecimal notation. Otherwise the compiler
1229 would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This
1230 could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
1231 extension for floating-point constants of type @code{float}.
1234 @section Fixed-Point Types
1235 @cindex fixed-point types
1236 @cindex @code{_Fract} data type
1237 @cindex @code{_Accum} data type
1238 @cindex @code{_Sat} data type
1239 @cindex @code{hr} fixed-suffix
1240 @cindex @code{r} fixed-suffix
1241 @cindex @code{lr} fixed-suffix
1242 @cindex @code{llr} fixed-suffix
1243 @cindex @code{uhr} fixed-suffix
1244 @cindex @code{ur} fixed-suffix
1245 @cindex @code{ulr} fixed-suffix
1246 @cindex @code{ullr} fixed-suffix
1247 @cindex @code{hk} fixed-suffix
1248 @cindex @code{k} fixed-suffix
1249 @cindex @code{lk} fixed-suffix
1250 @cindex @code{llk} fixed-suffix
1251 @cindex @code{uhk} fixed-suffix
1252 @cindex @code{uk} fixed-suffix
1253 @cindex @code{ulk} fixed-suffix
1254 @cindex @code{ullk} fixed-suffix
1255 @cindex @code{HR} fixed-suffix
1256 @cindex @code{R} fixed-suffix
1257 @cindex @code{LR} fixed-suffix
1258 @cindex @code{LLR} fixed-suffix
1259 @cindex @code{UHR} fixed-suffix
1260 @cindex @code{UR} fixed-suffix
1261 @cindex @code{ULR} fixed-suffix
1262 @cindex @code{ULLR} fixed-suffix
1263 @cindex @code{HK} fixed-suffix
1264 @cindex @code{K} fixed-suffix
1265 @cindex @code{LK} fixed-suffix
1266 @cindex @code{LLK} fixed-suffix
1267 @cindex @code{UHK} fixed-suffix
1268 @cindex @code{UK} fixed-suffix
1269 @cindex @code{ULK} fixed-suffix
1270 @cindex @code{ULLK} fixed-suffix
1272 As an extension, GNU C supports fixed-point types as
1273 defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point
1274 types in GCC will evolve as the draft technical report changes.
1275 Calling conventions for any target might also change. Not all targets
1276 support fixed-point types.
1278 The fixed-point types are
1279 @code{short _Fract},
1282 @code{long long _Fract},
1283 @code{unsigned short _Fract},
1284 @code{unsigned _Fract},
1285 @code{unsigned long _Fract},
1286 @code{unsigned long long _Fract},
1287 @code{_Sat short _Fract},
1289 @code{_Sat long _Fract},
1290 @code{_Sat long long _Fract},
1291 @code{_Sat unsigned short _Fract},
1292 @code{_Sat unsigned _Fract},
1293 @code{_Sat unsigned long _Fract},
1294 @code{_Sat unsigned long long _Fract},
1295 @code{short _Accum},
1298 @code{long long _Accum},
1299 @code{unsigned short _Accum},
1300 @code{unsigned _Accum},
1301 @code{unsigned long _Accum},
1302 @code{unsigned long long _Accum},
1303 @code{_Sat short _Accum},
1305 @code{_Sat long _Accum},
1306 @code{_Sat long long _Accum},
1307 @code{_Sat unsigned short _Accum},
1308 @code{_Sat unsigned _Accum},
1309 @code{_Sat unsigned long _Accum},
1310 @code{_Sat unsigned long long _Accum}.
1312 Fixed-point data values contain fractional and optional integral parts.
1313 The format of fixed-point data varies and depends on the target machine.
1315 Support for fixed-point types includes:
1318 prefix and postfix increment and decrement operators (@code{++}, @code{--})
1320 unary arithmetic operators (@code{+}, @code{-}, @code{!})
1322 binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/})
1324 binary shift operators (@code{<<}, @code{>>})
1326 relational operators (@code{<}, @code{<=}, @code{>=}, @code{>})
1328 equality operators (@code{==}, @code{!=})
1330 assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=},
1331 @code{<<=}, @code{>>=})
1333 conversions to and from integer, floating-point, or fixed-point types
1336 Use a suffix in a fixed-point literal constant:
1338 @item @samp{hr} or @samp{HR} for @code{short _Fract} and
1339 @code{_Sat short _Fract}
1340 @item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract}
1341 @item @samp{lr} or @samp{LR} for @code{long _Fract} and
1342 @code{_Sat long _Fract}
1343 @item @samp{llr} or @samp{LLR} for @code{long long _Fract} and
1344 @code{_Sat long long _Fract}
1345 @item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and
1346 @code{_Sat unsigned short _Fract}
1347 @item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and
1348 @code{_Sat unsigned _Fract}
1349 @item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and
1350 @code{_Sat unsigned long _Fract}
1351 @item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract}
1352 and @code{_Sat unsigned long long _Fract}
1353 @item @samp{hk} or @samp{HK} for @code{short _Accum} and
1354 @code{_Sat short _Accum}
1355 @item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum}
1356 @item @samp{lk} or @samp{LK} for @code{long _Accum} and
1357 @code{_Sat long _Accum}
1358 @item @samp{llk} or @samp{LLK} for @code{long long _Accum} and
1359 @code{_Sat long long _Accum}
1360 @item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and
1361 @code{_Sat unsigned short _Accum}
1362 @item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and
1363 @code{_Sat unsigned _Accum}
1364 @item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and
1365 @code{_Sat unsigned long _Accum}
1366 @item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum}
1367 and @code{_Sat unsigned long long _Accum}
1370 GCC support of fixed-point types as specified by the draft technical report
1375 Pragmas to control overflow and rounding behaviors are not implemented.
1378 Fixed-point types are supported by the DWARF debug information format.
1380 @node Named Address Spaces
1381 @section Named Address Spaces
1382 @cindex Named Address Spaces
1384 As an extension, GNU C supports named address spaces as
1385 defined in the N1275 draft of ISO/IEC DTR 18037. Support for named
1386 address spaces in GCC will evolve as the draft technical report
1387 changes. Calling conventions for any target might also change. At
1388 present, only the AVR, M32C, RL78, and x86 targets support
1389 address spaces other than the generic address space.
1391 Address space identifiers may be used exactly like any other C type
1392 qualifier (e.g., @code{const} or @code{volatile}). See the N1275
1393 document for more details.
1395 @anchor{AVR Named Address Spaces}
1396 @subsection AVR Named Address Spaces
1398 On the AVR target, there are several address spaces that can be used
1399 in order to put read-only data into the flash memory and access that
1400 data by means of the special instructions @code{LPM} or @code{ELPM}
1401 needed to read from flash.
1403 Devices belonging to @code{avrtiny} and @code{avrxmega3} can access
1404 flash memory by means of @code{LD*} instructions because the flash
1405 memory is mapped into the RAM address space. There is @emph{no need}
1406 for language extensions like @code{__flash} or attribute
1407 @ref{AVR Variable Attributes,,@code{progmem}}.
1408 The default linker description files for these devices cater for that
1409 feature and @code{.rodata} stays in flash: The compiler just generates
1410 @code{LD*} instructions, and the linker script adds core specific
1411 offsets to all @code{.rodata} symbols: @code{0x4000} in the case of
1412 @code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}.
1413 See @ref{AVR Options} for a list of respective devices.
1415 For devices not in @code{avrtiny} or @code{avrxmega3},
1416 any data including read-only data is located in RAM (the generic
1417 address space) because flash memory is not visible in the RAM address
1418 space. In order to locate read-only data in flash memory @emph{and}
1419 to generate the right instructions to access this data without
1420 using (inline) assembler code, special address spaces are needed.
1424 @cindex @code{__flash} AVR Named Address Spaces
1425 The @code{__flash} qualifier locates data in the
1426 @code{.progmem.data} section. Data is read using the @code{LPM}
1427 instruction. Pointers to this address space are 16 bits wide.
1434 @cindex @code{__flash1} AVR Named Address Spaces
1435 @cindex @code{__flash2} AVR Named Address Spaces
1436 @cindex @code{__flash3} AVR Named Address Spaces
1437 @cindex @code{__flash4} AVR Named Address Spaces
1438 @cindex @code{__flash5} AVR Named Address Spaces
1439 These are 16-bit address spaces locating data in section
1440 @code{.progmem@var{N}.data} where @var{N} refers to
1441 address space @code{__flash@var{N}}.
1442 The compiler sets the @code{RAMPZ} segment register appropriately
1443 before reading data by means of the @code{ELPM} instruction.
1446 @cindex @code{__memx} AVR Named Address Spaces
1447 This is a 24-bit address space that linearizes flash and RAM:
1448 If the high bit of the address is set, data is read from
1449 RAM using the lower two bytes as RAM address.
1450 If the high bit of the address is clear, data is read from flash
1451 with @code{RAMPZ} set according to the high byte of the address.
1452 @xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}.
1454 Objects in this address space are located in @code{.progmemx.data}.
1460 char my_read (const __flash char ** p)
1462 /* p is a pointer to RAM that points to a pointer to flash.
1463 The first indirection of p reads that flash pointer
1464 from RAM and the second indirection reads a char from this
1470 /* Locate array[] in flash memory */
1471 const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @};
1477 /* Return 17 by reading from flash memory */
1478 return array[array[i]];
1483 For each named address space supported by avr-gcc there is an equally
1484 named but uppercase built-in macro defined.
1485 The purpose is to facilitate testing if respective address space
1486 support is available or not:
1490 const __flash int var = 1;
1497 #include <avr/pgmspace.h> /* From AVR-LibC */
1499 const int var PROGMEM = 1;
1503 return (int) pgm_read_word (&var);
1505 #endif /* __FLASH */
1509 Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}}
1510 locates data in flash but
1511 accesses to these data read from generic address space, i.e.@:
1513 so that you need special accessors like @code{pgm_read_byte}
1514 from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}}
1515 together with attribute @code{progmem}.
1518 @b{Limitations and caveats}
1522 Reading across the 64@tie{}KiB section boundary of
1523 the @code{__flash} or @code{__flash@var{N}} address spaces
1524 shows undefined behavior. The only address space that
1525 supports reading across the 64@tie{}KiB flash segment boundaries is
1529 If you use one of the @code{__flash@var{N}} address spaces
1530 you must arrange your linker script to locate the
1531 @code{.progmem@var{N}.data} sections according to your needs.
1534 Any data or pointers to the non-generic address spaces must
1535 be qualified as @code{const}, i.e.@: as read-only data.
1536 This still applies if the data in one of these address
1537 spaces like software version number or calibration lookup table are intended to
1538 be changed after load time by, say, a boot loader. In this case
1539 the right qualification is @code{const} @code{volatile} so that the compiler
1540 must not optimize away known values or insert them
1541 as immediates into operands of instructions.
1544 The following code initializes a variable @code{pfoo}
1545 located in static storage with a 24-bit address:
1547 extern const __memx char foo;
1548 const __memx void *pfoo = &foo;
1552 On the reduced Tiny devices like ATtiny40, no address spaces are supported.
1553 Just use vanilla C / C++ code without overhead as outlined above.
1554 Attribute @code{progmem} is supported but works differently,
1555 see @ref{AVR Variable Attributes}.
1559 @subsection M32C Named Address Spaces
1560 @cindex @code{__far} M32C Named Address Spaces
1562 On the M32C target, with the R8C and M16C CPU variants, variables
1563 qualified with @code{__far} are accessed using 32-bit addresses in
1564 order to access memory beyond the first 64@tie{}Ki bytes. If
1565 @code{__far} is used with the M32CM or M32C CPU variants, it has no
1568 @subsection RL78 Named Address Spaces
1569 @cindex @code{__far} RL78 Named Address Spaces
1571 On the RL78 target, variables qualified with @code{__far} are accessed
1572 with 32-bit pointers (20-bit addresses) rather than the default 16-bit
1573 addresses. Non-far variables are assumed to appear in the topmost
1574 64@tie{}KiB of the address space.
1576 @subsection x86 Named Address Spaces
1577 @cindex x86 named address spaces
1579 On the x86 target, variables may be declared as being relative
1580 to the @code{%fs} or @code{%gs} segments.
1585 @cindex @code{__seg_fs} x86 named address space
1586 @cindex @code{__seg_gs} x86 named address space
1587 The object is accessed with the respective segment override prefix.
1589 The respective segment base must be set via some method specific to
1590 the operating system. Rather than require an expensive system call
1591 to retrieve the segment base, these address spaces are not considered
1592 to be subspaces of the generic (flat) address space. This means that
1593 explicit casts are required to convert pointers between these address
1594 spaces and the generic address space. In practice the application
1595 should cast to @code{uintptr_t} and apply the segment base offset
1596 that it installed previously.
1598 The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are
1599 defined when these address spaces are supported.
1603 @section Arrays of Length Zero
1604 @cindex arrays of length zero
1605 @cindex zero-length arrays
1606 @cindex length-zero arrays
1607 @cindex flexible array members
1609 Declaring zero-length arrays is allowed in GNU C as an extension.
1610 A zero-length array can be useful as the last element of a structure
1611 that is really a header for a variable-length object:
1619 struct line *thisline = (struct line *)
1620 malloc (sizeof (struct line) + this_length);
1621 thisline->length = this_length;
1624 Although the size of a zero-length array is zero, an array member of
1625 this kind may increase the size of the enclosing type as a result of tail
1626 padding. The offset of a zero-length array member from the beginning
1627 of the enclosing structure is the same as the offset of an array with
1628 one or more elements of the same type. The alignment of a zero-length
1629 array is the same as the alignment of its elements.
1631 Declaring zero-length arrays in other contexts, including as interior
1632 members of structure objects or as non-member objects, is discouraged.
1633 Accessing elements of zero-length arrays declared in such contexts is
1634 undefined and may be diagnosed.
1636 In the absence of the zero-length array extension, in ISO C90
1637 the @code{contents} array in the example above would typically be declared
1638 to have a single element. Unlike a zero-length array which only contributes
1639 to the size of the enclosing structure for the purposes of alignment,
1640 a one-element array always occupies at least as much space as a single
1641 object of the type. Although using one-element arrays this way is
1642 discouraged, GCC handles accesses to trailing one-element array members
1643 analogously to zero-length arrays.
1645 The preferred mechanism to declare variable-length types like
1646 @code{struct line} above is the ISO C99 @dfn{flexible array member},
1647 with slightly different syntax and semantics:
1651 Flexible array members are written as @code{contents[]} without
1655 Flexible array members have incomplete type, and so the @code{sizeof}
1656 operator may not be applied. As a quirk of the original implementation
1657 of zero-length arrays, @code{sizeof} evaluates to zero.
1660 Flexible array members may only appear as the last member of a
1661 @code{struct} that is otherwise non-empty.
1664 A structure containing a flexible array member, or a union containing
1665 such a structure (possibly recursively), may not be a member of a
1666 structure or an element of an array. (However, these uses are
1667 permitted by GCC as extensions.)
1670 Non-empty initialization of zero-length
1671 arrays is treated like any case where there are more initializer
1672 elements than the array holds, in that a suitable warning about ``excess
1673 elements in array'' is given, and the excess elements (all of them, in
1674 this case) are ignored.
1676 GCC allows static initialization of flexible array members.
1677 This is equivalent to defining a new structure containing the original
1678 structure followed by an array of sufficient size to contain the data.
1679 E.g.@: in the following, @code{f1} is constructed as if it were declared
1685 @} f1 = @{ 1, @{ 2, 3, 4 @} @};
1688 struct f1 f1; int data[3];
1689 @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
1693 The convenience of this extension is that @code{f1} has the desired
1694 type, eliminating the need to consistently refer to @code{f2.f1}.
1696 This has symmetry with normal static arrays, in that an array of
1697 unknown size is also written with @code{[]}.
1699 Of course, this extension only makes sense if the extra data comes at
1700 the end of a top-level object, as otherwise we would be overwriting
1701 data at subsequent offsets. To avoid undue complication and confusion
1702 with initialization of deeply nested arrays, we simply disallow any
1703 non-empty initialization except when the structure is the top-level
1704 object. For example:
1707 struct foo @{ int x; int y[]; @};
1708 struct bar @{ struct foo z; @};
1710 struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
1711 struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1712 struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
1713 struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1716 @node Empty Structures
1717 @section Structures with No Members
1718 @cindex empty structures
1719 @cindex zero-size structures
1721 GCC permits a C structure to have no members:
1728 The structure has size zero. In C++, empty structures are part
1729 of the language. G++ treats empty structures as if they had a single
1730 member of type @code{char}.
1732 @node Variable Length
1733 @section Arrays of Variable Length
1734 @cindex variable-length arrays
1735 @cindex arrays of variable length
1738 Variable-length automatic arrays are allowed in ISO C99, and as an
1739 extension GCC accepts them in C90 mode and in C++. These arrays are
1740 declared like any other automatic arrays, but with a length that is not
1741 a constant expression. The storage is allocated at the point of
1742 declaration and deallocated when the block scope containing the declaration
1748 concat_fopen (char *s1, char *s2, char *mode)
1750 char str[strlen (s1) + strlen (s2) + 1];
1753 return fopen (str, mode);
1757 @cindex scope of a variable length array
1758 @cindex variable-length array scope
1759 @cindex deallocating variable length arrays
1760 Jumping or breaking out of the scope of the array name deallocates the
1761 storage. Jumping into the scope is not allowed; you get an error
1764 @cindex variable-length array in a structure
1765 As an extension, GCC accepts variable-length arrays as a member of
1766 a structure or a union. For example:
1772 struct S @{ int x[n]; @};
1776 @cindex @code{alloca} vs variable-length arrays
1777 You can use the function @code{alloca} to get an effect much like
1778 variable-length arrays. The function @code{alloca} is available in
1779 many other C implementations (but not in all). On the other hand,
1780 variable-length arrays are more elegant.
1782 There are other differences between these two methods. Space allocated
1783 with @code{alloca} exists until the containing @emph{function} returns.
1784 The space for a variable-length array is deallocated as soon as the array
1785 name's scope ends, unless you also use @code{alloca} in this scope.
1787 You can also use variable-length arrays as arguments to functions:
1791 tester (int len, char data[len][len])
1797 The length of an array is computed once when the storage is allocated
1798 and is remembered for the scope of the array in case you access it with
1801 If you want to pass the array first and the length afterward, you can
1802 use a forward declaration in the parameter list---another GNU extension.
1806 tester (int len; char data[len][len], int len)
1812 @cindex parameter forward declaration
1813 The @samp{int len} before the semicolon is a @dfn{parameter forward
1814 declaration}, and it serves the purpose of making the name @code{len}
1815 known when the declaration of @code{data} is parsed.
1817 You can write any number of such parameter forward declarations in the
1818 parameter list. They can be separated by commas or semicolons, but the
1819 last one must end with a semicolon, which is followed by the ``real''
1820 parameter declarations. Each forward declaration must match a ``real''
1821 declaration in parameter name and data type. ISO C99 does not support
1822 parameter forward declarations.
1824 @node Variadic Macros
1825 @section Macros with a Variable Number of Arguments.
1826 @cindex variable number of arguments
1827 @cindex macro with variable arguments
1828 @cindex rest argument (in macro)
1829 @cindex variadic macros
1831 In the ISO C standard of 1999, a macro can be declared to accept a
1832 variable number of arguments much as a function can. The syntax for
1833 defining the macro is similar to that of a function. Here is an
1837 #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
1841 Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
1842 such a macro, it represents the zero or more tokens until the closing
1843 parenthesis that ends the invocation, including any commas. This set of
1844 tokens replaces the identifier @code{__VA_ARGS__} in the macro body
1845 wherever it appears. See the CPP manual for more information.
1847 GCC has long supported variadic macros, and used a different syntax that
1848 allowed you to give a name to the variable arguments just like any other
1849 argument. Here is an example:
1852 #define debug(format, args...) fprintf (stderr, format, args)
1856 This is in all ways equivalent to the ISO C example above, but arguably
1857 more readable and descriptive.
1859 GNU CPP has two further variadic macro extensions, and permits them to
1860 be used with either of the above forms of macro definition.
1862 In standard C, you are not allowed to leave the variable argument out
1863 entirely; but you are allowed to pass an empty argument. For example,
1864 this invocation is invalid in ISO C, because there is no comma after
1871 GNU CPP permits you to completely omit the variable arguments in this
1872 way. In the above examples, the compiler would complain, though since
1873 the expansion of the macro still has the extra comma after the format
1876 To help solve this problem, CPP behaves specially for variable arguments
1877 used with the token paste operator, @samp{##}. If instead you write
1880 #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
1884 and if the variable arguments are omitted or empty, the @samp{##}
1885 operator causes the preprocessor to remove the comma before it. If you
1886 do provide some variable arguments in your macro invocation, GNU CPP
1887 does not complain about the paste operation and instead places the
1888 variable arguments after the comma. Just like any other pasted macro
1889 argument, these arguments are not macro expanded.
1891 @node Escaped Newlines
1892 @section Slightly Looser Rules for Escaped Newlines
1893 @cindex escaped newlines
1894 @cindex newlines (escaped)
1896 The preprocessor treatment of escaped newlines is more relaxed
1897 than that specified by the C90 standard, which requires the newline
1898 to immediately follow a backslash.
1899 GCC's implementation allows whitespace in the form
1900 of spaces, horizontal and vertical tabs, and form feeds between the
1901 backslash and the subsequent newline. The preprocessor issues a
1902 warning, but treats it as a valid escaped newline and combines the two
1903 lines to form a single logical line. This works within comments and
1904 tokens, as well as between tokens. Comments are @emph{not} treated as
1905 whitespace for the purposes of this relaxation, since they have not
1906 yet been replaced with spaces.
1909 @section Non-Lvalue Arrays May Have Subscripts
1910 @cindex subscripting
1911 @cindex arrays, non-lvalue
1913 @cindex subscripting and function values
1914 In ISO C99, arrays that are not lvalues still decay to pointers, and
1915 may be subscripted, although they may not be modified or used after
1916 the next sequence point and the unary @samp{&} operator may not be
1917 applied to them. As an extension, GNU C allows such arrays to be
1918 subscripted in C90 mode, though otherwise they do not decay to
1919 pointers outside C99 mode. For example,
1920 this is valid in GNU C though not valid in C90:
1924 struct foo @{int a[4];@};
1930 return f().a[index];
1936 @section Arithmetic on @code{void}- and Function-Pointers
1937 @cindex void pointers, arithmetic
1938 @cindex void, size of pointer to
1939 @cindex function pointers, arithmetic
1940 @cindex function, size of pointer to
1942 In GNU C, addition and subtraction operations are supported on pointers to
1943 @code{void} and on pointers to functions. This is done by treating the
1944 size of a @code{void} or of a function as 1.
1946 A consequence of this is that @code{sizeof} is also allowed on @code{void}
1947 and on function types, and returns 1.
1949 @opindex Wpointer-arith
1950 The option @option{-Wpointer-arith} requests a warning if these extensions
1953 @node Variadic Pointer Args
1954 @section Pointer Arguments in Variadic Functions
1955 @cindex pointer arguments in variadic functions
1956 @cindex variadic functions, pointer arguments
1958 Standard C requires that pointer types used with @code{va_arg} in
1959 functions with variable argument lists either must be compatible with
1960 that of the actual argument, or that one type must be a pointer to
1961 @code{void} and the other a pointer to a character type. GNU C
1962 implements the POSIX XSI extension that additionally permits the use
1963 of @code{va_arg} with a pointer type to receive arguments of any other
1966 In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used
1967 to consume an argument of any pointer type.
1969 @node Pointers to Arrays
1970 @section Pointers to Arrays with Qualifiers Work as Expected
1971 @cindex pointers to arrays
1972 @cindex const qualifier
1974 In GNU C, pointers to arrays with qualifiers work similar to pointers
1975 to other qualified types. For example, a value of type @code{int (*)[5]}
1976 can be used to initialize a variable of type @code{const int (*)[5]}.
1977 These types are incompatible in ISO C because the @code{const} qualifier
1978 is formally attached to the element type of the array and not the
1983 transpose (int N, int M, double out[M][N], const double in[N][M]);
1987 transpose(3, 2, y, x);
1991 @section Non-Constant Initializers
1992 @cindex initializers, non-constant
1993 @cindex non-constant initializers
1995 As in standard C++ and ISO C99, the elements of an aggregate initializer for an
1996 automatic variable are not required to be constant expressions in GNU C@.
1997 Here is an example of an initializer with run-time varying elements:
2000 foo (float f, float g)
2002 float beat_freqs[2] = @{ f-g, f+g @};
2007 @node Compound Literals
2008 @section Compound Literals
2009 @cindex constructor expressions
2010 @cindex initializations in expressions
2011 @cindex structures, constructor expression
2012 @cindex expressions, constructor
2013 @cindex compound literals
2014 @c The GNU C name for what C99 calls compound literals was "constructor expressions".
2016 A compound literal looks like a cast of a brace-enclosed aggregate
2017 initializer list. Its value is an object of the type specified in
2018 the cast, containing the elements specified in the initializer.
2019 Unlike the result of a cast, a compound literal is an lvalue. ISO
2020 C99 and later support compound literals. As an extension, GCC
2021 supports compound literals also in C90 mode and in C++, although
2022 as explained below, the C++ semantics are somewhat different.
2024 Usually, the specified type of a compound literal is a structure. Assume
2025 that @code{struct foo} and @code{structure} are declared as shown:
2028 struct foo @{int a; char b[2];@} structure;
2032 Here is an example of constructing a @code{struct foo} with a compound literal:
2035 structure = ((struct foo) @{x + y, 'a', 0@});
2039 This is equivalent to writing the following:
2043 struct foo temp = @{x + y, 'a', 0@};
2048 You can also construct an array, though this is dangerous in C++, as
2049 explained below. If all the elements of the compound literal are
2050 (made up of) simple constant expressions suitable for use in
2051 initializers of objects of static storage duration, then the compound
2052 literal can be coerced to a pointer to its first element and used in
2053 such an initializer, as shown here:
2056 char **foo = (char *[]) @{ "x", "y", "z" @};
2059 Compound literals for scalar types and union types are also allowed. In
2060 the following example the variable @code{i} is initialized to the value
2061 @code{2}, the result of incrementing the unnamed object created by
2062 the compound literal.
2065 int i = ++(int) @{ 1 @};
2068 As a GNU extension, GCC allows initialization of objects with static storage
2069 duration by compound literals (which is not possible in ISO C99 because
2070 the initializer is not a constant).
2071 It is handled as if the object were initialized only with the brace-enclosed
2072 list if the types of the compound literal and the object match.
2073 The elements of the compound literal must be constant.
2074 If the object being initialized has array type of unknown size, the size is
2075 determined by the size of the compound literal.
2078 static struct foo x = (struct foo) @{1, 'a', 'b'@};
2079 static int y[] = (int []) @{1, 2, 3@};
2080 static int z[] = (int [3]) @{1@};
2084 The above lines are equivalent to the following:
2086 static struct foo x = @{1, 'a', 'b'@};
2087 static int y[] = @{1, 2, 3@};
2088 static int z[] = @{1, 0, 0@};
2091 In C, a compound literal designates an unnamed object with static or
2092 automatic storage duration. In C++, a compound literal designates a
2093 temporary object that only lives until the end of its full-expression.
2094 As a result, well-defined C code that takes the address of a subobject
2095 of a compound literal can be undefined in C++, so G++ rejects
2096 the conversion of a temporary array to a pointer. For instance, if
2097 the array compound literal example above appeared inside a function,
2098 any subsequent use of @code{foo} in C++ would have undefined behavior
2099 because the lifetime of the array ends after the declaration of @code{foo}.
2101 As an optimization, G++ sometimes gives array compound literals longer
2102 lifetimes: when the array either appears outside a function or has
2103 a @code{const}-qualified type. If @code{foo} and its initializer had
2104 elements of type @code{char *const} rather than @code{char *}, or if
2105 @code{foo} were a global variable, the array would have static storage
2106 duration. But it is probably safest just to avoid the use of array
2107 compound literals in C++ code.
2109 @node Designated Inits
2110 @section Designated Initializers
2111 @cindex initializers with labeled elements
2112 @cindex labeled elements in initializers
2113 @cindex case labels in initializers
2114 @cindex designated initializers
2116 Standard C90 requires the elements of an initializer to appear in a fixed
2117 order, the same as the order of the elements in the array or structure
2120 In ISO C99 you can give the elements in any order, specifying the array
2121 indices or structure field names they apply to, and GNU C allows this as
2122 an extension in C90 mode as well. This extension is not
2123 implemented in GNU C++.
2125 To specify an array index, write
2126 @samp{[@var{index}] =} before the element value. For example,
2129 int a[6] = @{ [4] = 29, [2] = 15 @};
2136 int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
2140 The index values must be constant expressions, even if the array being
2141 initialized is automatic.
2143 An alternative syntax for this that has been obsolete since GCC 2.5 but
2144 GCC still accepts is to write @samp{[@var{index}]} before the element
2145 value, with no @samp{=}.
2147 To initialize a range of elements to the same value, write
2148 @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
2149 extension. For example,
2152 int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
2156 If the value in it has side effects, the side effects happen only once,
2157 not for each initialized field by the range initializer.
2160 Note that the length of the array is the highest value specified
2163 In a structure initializer, specify the name of a field to initialize
2164 with @samp{.@var{fieldname} =} before the element value. For example,
2165 given the following structure,
2168 struct point @{ int x, y; @};
2172 the following initialization
2175 struct point p = @{ .y = yvalue, .x = xvalue @};
2182 struct point p = @{ xvalue, yvalue @};
2185 Another syntax that has the same meaning, obsolete since GCC 2.5, is
2186 @samp{@var{fieldname}:}, as shown here:
2189 struct point p = @{ y: yvalue, x: xvalue @};
2192 Omitted fields are implicitly initialized the same as for objects
2193 that have static storage duration.
2196 The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
2197 @dfn{designator}. You can also use a designator (or the obsolete colon
2198 syntax) when initializing a union, to specify which element of the union
2199 should be used. For example,
2202 union foo @{ int i; double d; @};
2204 union foo f = @{ .d = 4 @};
2208 converts 4 to a @code{double} to store it in the union using
2209 the second element. By contrast, casting 4 to type @code{union foo}
2210 stores it into the union as the integer @code{i}, since it is
2211 an integer. @xref{Cast to Union}.
2213 You can combine this technique of naming elements with ordinary C
2214 initialization of successive elements. Each initializer element that
2215 does not have a designator applies to the next consecutive element of the
2216 array or structure. For example,
2219 int a[6] = @{ [1] = v1, v2, [4] = v4 @};
2226 int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
2229 Labeling the elements of an array initializer is especially useful
2230 when the indices are characters or belong to an @code{enum} type.
2235 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
2236 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
2239 @cindex designator lists
2240 You can also write a series of @samp{.@var{fieldname}} and
2241 @samp{[@var{index}]} designators before an @samp{=} to specify a
2242 nested subobject to initialize; the list is taken relative to the
2243 subobject corresponding to the closest surrounding brace pair. For
2244 example, with the @samp{struct point} declaration above:
2247 struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
2250 If the same field is initialized multiple times, or overlapping
2251 fields of a union are initialized, the value from the last
2252 initialization is used. When a field of a union is itself a structure,
2253 the entire structure from the last field initialized is used. If any previous
2254 initializer has side effect, it is unspecified whether the side effect
2255 happens or not. Currently, GCC discards the side-effecting
2256 initializer expressions and issues a warning.
2259 @section Case Ranges
2261 @cindex ranges in case statements
2263 You can specify a range of consecutive values in a single @code{case} label,
2267 case @var{low} ... @var{high}:
2271 This has the same effect as the proper number of individual @code{case}
2272 labels, one for each integer value from @var{low} to @var{high}, inclusive.
2274 This feature is especially useful for ranges of ASCII character codes:
2280 @strong{Be careful:} Write spaces around the @code{...}, for otherwise
2281 it may be parsed wrong when you use it with integer values. For example,
2296 @section Cast to a Union Type
2297 @cindex cast to a union
2298 @cindex union, casting to a
2300 A cast to a union type is a C extension not available in C++. It looks
2301 just like ordinary casts with the constraint that the type specified is
2302 a union type. You can specify the type either with the @code{union}
2303 keyword or with a @code{typedef} name that refers to a union. The result
2304 of a cast to a union is a temporary rvalue of the union type with a member
2305 whose type matches that of the operand initialized to the value of
2306 the operand. The effect of a cast to a union is similar to a compound
2307 literal except that it yields an rvalue like standard casts do.
2308 @xref{Compound Literals}.
2310 Expressions that may be cast to the union type are those whose type matches
2311 at least one of the members of the union. Thus, given the following union
2315 union foo @{ int i; double d; @};
2322 both @code{x} and @code{y} can be cast to type @code{union foo} and
2323 the following assignments
2328 are shorthand equivalents of these
2330 z = (union foo) @{ .i = x @};
2331 z = (union foo) @{ .d = y @};
2334 However, @code{(union foo) FLT_MAX;} is not a valid cast because the union
2335 has no member of type @code{float}.
2337 Using the cast as the right-hand side of an assignment to a variable of
2338 union type is equivalent to storing in a member of the union with
2344 u = (union foo) x @equiv{} u.i = x
2345 u = (union foo) y @equiv{} u.d = y
2348 You can also use the union cast as a function argument:
2351 void hack (union foo);
2353 hack ((union foo) x);
2356 @node Mixed Labels and Declarations
2357 @section Mixed Declarations, Labels and Code
2358 @cindex mixed declarations and code
2359 @cindex declarations, mixed with code
2360 @cindex code, mixed with declarations
2362 ISO C99 and ISO C++ allow declarations and code to be freely mixed
2363 within compound statements. ISO C2X allows labels to be
2364 placed before declarations and at the end of a compound statement.
2365 As an extension, GNU C also allows all this in C90 mode. For example,
2375 Each identifier is visible from where it is declared until the end of
2376 the enclosing block.
2378 @node Function Attributes
2379 @section Declaring Attributes of Functions
2380 @cindex function attributes
2381 @cindex declaring attributes of functions
2382 @cindex @code{volatile} applied to function
2383 @cindex @code{const} applied to function
2385 In GNU C and C++, you can use function attributes to specify certain
2386 function properties that may help the compiler optimize calls or
2387 check code more carefully for correctness. For example, you
2388 can use attributes to specify that a function never returns
2389 (@code{noreturn}), returns a value depending only on the values of
2390 its arguments (@code{const}), or has @code{printf}-style arguments
2393 You can also use attributes to control memory placement, code
2394 generation options or call/return conventions within the function
2395 being annotated. Many of these attributes are target-specific. For
2396 example, many targets support attributes for defining interrupt
2397 handler functions, which typically must follow special register usage
2398 and return conventions. Such attributes are described in the subsection
2399 for each target. However, a considerable number of attributes are
2400 supported by most, if not all targets. Those are described in
2401 the @ref{Common Function Attributes} section.
2403 Function attributes are introduced by the @code{__attribute__} keyword
2404 in the declaration of a function, followed by an attribute specification
2405 enclosed in double parentheses. You can specify multiple attributes in
2406 a declaration by separating them by commas within the double parentheses
2407 or by immediately following one attribute specification with another.
2408 @xref{Attribute Syntax}, for the exact rules on attribute syntax and
2409 placement. Compatible attribute specifications on distinct declarations
2410 of the same function are merged. An attribute specification that is not
2411 compatible with attributes already applied to a declaration of the same
2412 function is ignored with a warning.
2414 Some function attributes take one or more arguments that refer to
2415 the function's parameters by their positions within the function parameter
2416 list. Such attribute arguments are referred to as @dfn{positional arguments}.
2417 Unless specified otherwise, positional arguments that specify properties
2418 of parameters with pointer types can also specify the same properties of
2419 the implicit C++ @code{this} argument in non-static member functions, and
2420 of parameters of reference to a pointer type. For ordinary functions,
2421 position one refers to the first parameter on the list. In C++ non-static
2422 member functions, position one refers to the implicit @code{this} pointer.
2423 The same restrictions and effects apply to function attributes used with
2424 ordinary functions or C++ member functions.
2426 GCC also supports attributes on
2427 variable declarations (@pxref{Variable Attributes}),
2428 labels (@pxref{Label Attributes}),
2429 enumerators (@pxref{Enumerator Attributes}),
2430 statements (@pxref{Statement Attributes}),
2431 and types (@pxref{Type Attributes}).
2433 There is some overlap between the purposes of attributes and pragmas
2434 (@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been
2435 found convenient to use @code{__attribute__} to achieve a natural
2436 attachment of attributes to their corresponding declarations, whereas
2437 @code{#pragma} is of use for compatibility with other compilers
2438 or constructs that do not naturally form part of the grammar.
2440 In addition to the attributes documented here,
2441 GCC plugins may provide their own attributes.
2444 * Common Function Attributes::
2445 * AArch64 Function Attributes::
2446 * AMD GCN Function Attributes::
2447 * ARC Function Attributes::
2448 * ARM Function Attributes::
2449 * AVR Function Attributes::
2450 * Blackfin Function Attributes::
2451 * BPF Function Attributes::
2452 * CR16 Function Attributes::
2453 * C-SKY Function Attributes::
2454 * Epiphany Function Attributes::
2455 * H8/300 Function Attributes::
2456 * IA-64 Function Attributes::
2457 * M32C Function Attributes::
2458 * M32R/D Function Attributes::
2459 * m68k Function Attributes::
2460 * MCORE Function Attributes::
2461 * MeP Function Attributes::
2462 * MicroBlaze Function Attributes::
2463 * Microsoft Windows Function Attributes::
2464 * MIPS Function Attributes::
2465 * MSP430 Function Attributes::
2466 * NDS32 Function Attributes::
2467 * Nios II Function Attributes::
2468 * Nvidia PTX Function Attributes::
2469 * PowerPC Function Attributes::
2470 * RISC-V Function Attributes::
2471 * RL78 Function Attributes::
2472 * RX Function Attributes::
2473 * S/390 Function Attributes::
2474 * SH Function Attributes::
2475 * Symbian OS Function Attributes::
2476 * V850 Function Attributes::
2477 * Visium Function Attributes::
2478 * x86 Function Attributes::
2479 * Xstormy16 Function Attributes::
2482 @node Common Function Attributes
2483 @subsection Common Function Attributes
2485 The following attributes are supported on most targets.
2488 @c Keep this table alphabetized by attribute name. Treat _ as space.
2491 @itemx access (@var{access-mode}, @var{ref-index})
2492 @itemx access (@var{access-mode}, @var{ref-index}, @var{size-index})
2494 The @code{access} attribute enables the detection of invalid or unsafe
2495 accesses by functions to which they apply or their callers, as well as
2496 write-only accesses to objects that are never read from. Such accesses
2497 may be diagnosed by warnings such as @option{-Wstringop-overflow},
2498 @option{-Wuninitialized}, @option{-Wunused}, and others.
2500 The @code{access} attribute specifies that a function to whose by-reference
2501 arguments the attribute applies accesses the referenced object according to
2502 @var{access-mode}. The @var{access-mode} argument is required and must be
2503 one of four names: @code{read_only}, @code{read_write}, @code{write_only},
2504 or @code{none}. The remaining two are positional arguments.
2506 The required @var{ref-index} positional argument denotes a function
2507 argument of pointer (or in C++, reference) type that is subject to
2508 the access. The same pointer argument can be referenced by at most one
2509 distinct @code{access} attribute.
2511 The optional @var{size-index} positional argument denotes a function
2512 argument of integer type that specifies the maximum size of the access.
2513 The size is the number of elements of the type referenced by @var{ref-index},
2514 or the number of bytes when the pointer type is @code{void*}. When no
2515 @var{size-index} argument is specified, the pointer argument must be either
2516 null or point to a space that is suitably aligned and large for at least one
2517 object of the referenced type (this implies that a past-the-end pointer is
2518 not a valid argument). The actual size of the access may be less but it
2521 The @code{read_only} access mode specifies that the pointer to which it
2522 applies is used to read the referenced object but not write to it. Unless
2523 the argument specifying the size of the access denoted by @var{size-index}
2524 is zero, the referenced object must be initialized. The mode implies
2525 a stronger guarantee than the @code{const} qualifier which, when cast away
2526 from a pointer, does not prevent the pointed-to object from being modified.
2527 Examples of the use of the @code{read_only} access mode is the argument to
2528 the @code{puts} function, or the second and third arguments to
2529 the @code{memcpy} function.
2532 __attribute__ ((access (read_only, 1))) int puts (const char*);
2533 __attribute__ ((access (read_only, 2, 3))) void* memcpy (void*, const void*, size_t);
2536 The @code{read_write} access mode applies to arguments of pointer types
2537 without the @code{const} qualifier. It specifies that the pointer to which
2538 it applies is used to both read and write the referenced object. Unless
2539 the argument specifying the size of the access denoted by @var{size-index}
2540 is zero, the object referenced by the pointer must be initialized. An example
2541 of the use of the @code{read_write} access mode is the first argument to
2542 the @code{strcat} function.
2545 __attribute__ ((access (read_write, 1), access (read_only, 2))) char* strcat (char*, const char*);
2548 The @code{write_only} access mode applies to arguments of pointer types
2549 without the @code{const} qualifier. It specifies that the pointer to which
2550 it applies is used to write to the referenced object but not read from it.
2551 The object referenced by the pointer need not be initialized. An example
2552 of the use of the @code{write_only} access mode is the first argument to
2553 the @code{strcpy} function, or the first two arguments to the @code{fgets}
2557 __attribute__ ((access (write_only, 1), access (read_only, 2))) char* strcpy (char*, const char*);
2558 __attribute__ ((access (write_only, 1, 2), access (read_write, 3))) int fgets (char*, int, FILE*);
2561 The access mode @code{none} specifies that the pointer to which it applies
2562 is not used to access the referenced object at all. Unless the pointer is
2563 null the pointed-to object must exist and have at least the size as denoted
2564 by the @var{size-index} argument. The object need not be initialized.
2565 The mode is intended to be used as a means to help validate the expected
2566 object size, for example in functions that call @code{__builtin_object_size}.
2567 @xref{Object Size Checking}.
2569 @item alias ("@var{target}")
2570 @cindex @code{alias} function attribute
2571 The @code{alias} attribute causes the declaration to be emitted as an alias
2572 for another symbol, which must have been previously declared with the same
2573 type, and for variables, also the same size and alignment. Declaring an alias
2574 with a different type than the target is undefined and may be diagnosed. As
2575 an example, the following declarations:
2578 void __f () @{ /* @r{Do something.} */; @}
2579 void f () __attribute__ ((weak, alias ("__f")));
2583 define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name
2584 for the target must be used. It is an error if @samp{__f} is not defined in
2585 the same translation unit.
2587 This attribute requires assembler and object file support,
2588 and may not be available on all targets.
2591 @itemx aligned (@var{alignment})
2592 @cindex @code{aligned} function attribute
2593 The @code{aligned} attribute specifies a minimum alignment for
2594 the first instruction of the function, measured in bytes. When specified,
2595 @var{alignment} must be an integer constant power of 2. Specifying no
2596 @var{alignment} argument implies the ideal alignment for the target.
2597 The @code{__alignof__} operator can be used to determine what that is
2598 (@pxref{Alignment}). The attribute has no effect when a definition for
2599 the function is not provided in the same translation unit.
2601 The attribute cannot be used to decrease the alignment of a function
2602 previously declared with a more restrictive alignment; only to increase
2603 it. Attempts to do otherwise are diagnosed. Some targets specify
2604 a minimum default alignment for functions that is greater than 1. On
2605 such targets, specifying a less restrictive alignment is silently ignored.
2606 Using the attribute overrides the effect of the @option{-falign-functions}
2607 (@pxref{Optimize Options}) option for this function.
2609 Note that the effectiveness of @code{aligned} attributes may be
2610 limited by inherent limitations in the system linker
2611 and/or object file format. On some systems, the
2612 linker is only able to arrange for functions to be aligned up to a
2613 certain maximum alignment. (For some linkers, the maximum supported
2614 alignment may be very very small.) See your linker documentation for
2615 further information.
2617 The @code{aligned} attribute can also be used for variables and fields
2618 (@pxref{Variable Attributes}.)
2620 @item alloc_align (@var{position})
2621 @cindex @code{alloc_align} function attribute
2622 The @code{alloc_align} attribute may be applied to a function that
2623 returns a pointer and takes at least one argument of an integer or
2625 It indicates that the returned pointer is aligned on a boundary given
2626 by the function argument at @var{position}. Meaningful alignments are
2627 powers of 2 greater than one. GCC uses this information to improve
2628 pointer alignment analysis.
2630 The function parameter denoting the allocated alignment is specified by
2631 one constant integer argument whose number is the argument of the attribute.
2632 Argument numbering starts at one.
2637 void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1)));
2641 declares that @code{my_memalign} returns memory with minimum alignment
2642 given by parameter 1.
2644 @item alloc_size (@var{position})
2645 @itemx alloc_size (@var{position-1}, @var{position-2})
2646 @cindex @code{alloc_size} function attribute
2647 The @code{alloc_size} attribute may be applied to a function that
2648 returns a pointer and takes at least one argument of an integer or
2650 It indicates that the returned pointer points to memory whose size is
2651 given by the function argument at @var{position-1}, or by the product
2652 of the arguments at @var{position-1} and @var{position-2}. Meaningful
2653 sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this
2654 information to improve the results of @code{__builtin_object_size}.
2656 The function parameter(s) denoting the allocated size are specified by
2657 one or two integer arguments supplied to the attribute. The allocated size
2658 is either the value of the single function argument specified or the product
2659 of the two function arguments specified. Argument numbering starts at
2660 one for ordinary functions, and at two for C++ non-static member functions.
2665 void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2)));
2666 void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2)));
2670 declares that @code{my_calloc} returns memory of the size given by
2671 the product of parameter 1 and 2 and that @code{my_realloc} returns memory
2672 of the size given by parameter 2.
2675 @cindex @code{always_inline} function attribute
2676 Generally, functions are not inlined unless optimization is specified.
2677 For functions declared inline, this attribute inlines the function
2678 independent of any restrictions that otherwise apply to inlining.
2679 Failure to inline such a function is diagnosed as an error.
2680 Note that if such a function is called indirectly the compiler may
2681 or may not inline it depending on optimization level and a failure
2682 to inline an indirect call may or may not be diagnosed.
2685 @cindex @code{artificial} function attribute
2686 This attribute is useful for small inline wrappers that if possible
2687 should appear during debugging as a unit. Depending on the debug
2688 info format it either means marking the function as artificial
2689 or using the caller location for all instructions within the inlined
2692 @item assume_aligned (@var{alignment})
2693 @itemx assume_aligned (@var{alignment}, @var{offset})
2694 @cindex @code{assume_aligned} function attribute
2695 The @code{assume_aligned} attribute may be applied to a function that
2696 returns a pointer. It indicates that the returned pointer is aligned
2697 on a boundary given by @var{alignment}. If the attribute has two
2698 arguments, the second argument is misalignment @var{offset}. Meaningful
2699 values of @var{alignment} are powers of 2 greater than one. Meaningful
2700 values of @var{offset} are greater than zero and less than @var{alignment}.
2705 void* my_alloc1 (size_t) __attribute__((assume_aligned (16)));
2706 void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8)));
2710 declares that @code{my_alloc1} returns 16-byte aligned pointers and
2711 that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
2715 @cindex @code{cold} function attribute
2716 The @code{cold} attribute on functions is used to inform the compiler that
2717 the function is unlikely to be executed. The function is optimized for
2718 size rather than speed and on many targets it is placed into a special
2719 subsection of the text section so all cold functions appear close together,
2720 improving code locality of non-cold parts of program. The paths leading
2721 to calls of cold functions within code are marked as unlikely by the branch
2722 prediction mechanism. It is thus useful to mark functions used to handle
2723 unlikely conditions, such as @code{perror}, as cold to improve optimization
2724 of hot functions that do call marked functions in rare occasions.
2726 When profile feedback is available, via @option{-fprofile-use}, cold functions
2727 are automatically detected and this attribute is ignored.
2730 @cindex @code{const} function attribute
2731 @cindex functions that have no side effects
2732 Calls to functions whose return value is not affected by changes to
2733 the observable state of the program and that have no observable effects
2734 on such state other than to return a value may lend themselves to
2735 optimizations such as common subexpression elimination. Declaring such
2736 functions with the @code{const} attribute allows GCC to avoid emitting
2737 some calls in repeated invocations of the function with the same argument
2743 int square (int) __attribute__ ((const));
2747 tells GCC that subsequent calls to function @code{square} with the same
2748 argument value can be replaced by the result of the first call regardless
2749 of the statements in between.
2751 The @code{const} attribute prohibits a function from reading objects
2752 that affect its return value between successive invocations. However,
2753 functions declared with the attribute can safely read objects that do
2754 not change their return value, such as non-volatile constants.
2756 The @code{const} attribute imposes greater restrictions on a function's
2757 definition than the similar @code{pure} attribute. Declaring the same
2758 function with both the @code{const} and the @code{pure} attribute is
2759 diagnosed. Because a const function cannot have any observable side
2760 effects it does not make sense for it to return @code{void}. Declaring
2761 such a function is diagnosed.
2763 @cindex pointer arguments
2764 Note that a function that has pointer arguments and examines the data
2765 pointed to must @emph{not} be declared @code{const} if the pointed-to
2766 data might change between successive invocations of the function. In
2767 general, since a function cannot distinguish data that might change
2768 from data that cannot, const functions should never take pointer or,
2769 in C++, reference arguments. Likewise, a function that calls a non-const
2770 function usually must not be const itself.
2774 @itemx constructor (@var{priority})
2775 @itemx destructor (@var{priority})
2776 @cindex @code{constructor} function attribute
2777 @cindex @code{destructor} function attribute
2778 The @code{constructor} attribute causes the function to be called
2779 automatically before execution enters @code{main ()}. Similarly, the
2780 @code{destructor} attribute causes the function to be called
2781 automatically after @code{main ()} completes or @code{exit ()} is
2782 called. Functions with these attributes are useful for
2783 initializing data that is used implicitly during the execution of
2786 On some targets the attributes also accept an integer argument to
2787 specify a priority to control the order in which constructor and
2788 destructor functions are run. A constructor
2789 with a smaller priority number runs before a constructor with a larger
2790 priority number; the opposite relationship holds for destructors. So,
2791 if you have a constructor that allocates a resource and a destructor
2792 that deallocates the same resource, both functions typically have the
2793 same priority. The priorities for constructor and destructor
2794 functions are the same as those specified for namespace-scope C++
2795 objects (@pxref{C++ Attributes}). However, at present, the order in which
2796 constructors for C++ objects with static storage duration and functions
2797 decorated with attribute @code{constructor} are invoked is unspecified.
2798 In mixed declarations, attribute @code{init_priority} can be used to
2799 impose a specific ordering.
2801 Using the argument forms of the @code{constructor} and @code{destructor}
2802 attributes on targets where the feature is not supported is rejected with
2806 @itemx copy (@var{function})
2807 @cindex @code{copy} function attribute
2808 The @code{copy} attribute applies the set of attributes with which
2809 @var{function} has been declared to the declaration of the function
2810 to which the attribute is applied. The attribute is designed for
2811 libraries that define aliases or function resolvers that are expected
2812 to specify the same set of attributes as their targets. The @code{copy}
2813 attribute can be used with functions, variables, or types. However,
2814 the kind of symbol to which the attribute is applied (either function
2815 or variable) must match the kind of symbol to which the argument refers.
2816 The @code{copy} attribute copies only syntactic and semantic attributes
2817 but not attributes that affect a symbol's linkage or visibility such as
2818 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
2819 and @code{target_clones} attribute are also not copied.
2820 @xref{Common Type Attributes}.
2821 @xref{Common Variable Attributes}.
2823 For example, the @var{StrongAlias} macro below makes use of the @code{alias}
2824 and @code{copy} attributes to define an alias named @var{alloc} for function
2825 @var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and
2826 @var{nothrow}. Thanks to the @code{__typeof__} operator the alias has
2827 the same type as the target function. As a result of the @code{copy}
2828 attribute the alias also shares the same attributes as the target.
2831 #define StrongAlias(TargetFunc, AliasDecl) \
2832 extern __typeof__ (TargetFunc) AliasDecl \
2833 __attribute__ ((alias (#TargetFunc), copy (TargetFunc)));
2835 extern __attribute__ ((alloc_size (1), malloc, nothrow))
2836 void* allocate (size_t);
2837 StrongAlias (allocate, alloc);
2841 @itemx deprecated (@var{msg})
2842 @cindex @code{deprecated} function attribute
2843 The @code{deprecated} attribute results in a warning if the function
2844 is used anywhere in the source file. This is useful when identifying
2845 functions that are expected to be removed in a future version of a
2846 program. The warning also includes the location of the declaration
2847 of the deprecated function, to enable users to easily find further
2848 information about why the function is deprecated, or what they should
2849 do instead. Note that the warnings only occurs for uses:
2852 int old_fn () __attribute__ ((deprecated));
2854 int (*fn_ptr)() = old_fn;
2858 results in a warning on line 3 but not line 2. The optional @var{msg}
2859 argument, which must be a string, is printed in the warning if
2862 The @code{deprecated} attribute can also be used for variables and
2863 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
2865 The message attached to the attribute is affected by the setting of
2866 the @option{-fmessage-length} option.
2868 @item error ("@var{message}")
2869 @itemx warning ("@var{message}")
2870 @cindex @code{error} function attribute
2871 @cindex @code{warning} function attribute
2872 If the @code{error} or @code{warning} attribute
2873 is used on a function declaration and a call to such a function
2874 is not eliminated through dead code elimination or other optimizations,
2875 an error or warning (respectively) that includes @var{message} is diagnosed.
2877 for compile-time checking, especially together with @code{__builtin_constant_p}
2878 and inline functions where checking the inline function arguments is not
2879 possible through @code{extern char [(condition) ? 1 : -1];} tricks.
2881 While it is possible to leave the function undefined and thus invoke
2882 a link failure (to define the function with
2883 a message in @code{.gnu.warning*} section),
2884 when using these attributes the problem is diagnosed
2885 earlier and with exact location of the call even in presence of inline
2886 functions or when not emitting debugging information.
2888 @item externally_visible
2889 @cindex @code{externally_visible} function attribute
2890 This attribute, attached to a global variable or function, nullifies
2891 the effect of the @option{-fwhole-program} command-line option, so the
2892 object remains visible outside the current compilation unit.
2894 If @option{-fwhole-program} is used together with @option{-flto} and
2895 @command{gold} is used as the linker plugin,
2896 @code{externally_visible} attributes are automatically added to functions
2897 (not variable yet due to a current @command{gold} issue)
2898 that are accessed outside of LTO objects according to resolution file
2899 produced by @command{gold}.
2900 For other linkers that cannot generate resolution file,
2901 explicit @code{externally_visible} attributes are still necessary.
2904 @cindex @code{flatten} function attribute
2905 Generally, inlining into a function is limited. For a function marked with
2906 this attribute, every call inside this function is inlined, if possible.
2907 Functions declared with attribute @code{noinline} and similar are not
2908 inlined. Whether the function itself is considered for inlining depends
2909 on its size and the current inlining parameters.
2911 @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
2912 @cindex @code{format} function attribute
2913 @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
2915 The @code{format} attribute specifies that a function takes @code{printf},
2916 @code{scanf}, @code{strftime} or @code{strfmon} style arguments that
2917 should be type-checked against a format string. For example, the
2922 my_printf (void *my_object, const char *my_format, ...)
2923 __attribute__ ((format (printf, 2, 3)));
2927 causes the compiler to check the arguments in calls to @code{my_printf}
2928 for consistency with the @code{printf} style format string argument
2931 The parameter @var{archetype} determines how the format string is
2932 interpreted, and should be @code{printf}, @code{scanf}, @code{strftime},
2933 @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or
2934 @code{strfmon}. (You can also use @code{__printf__},
2935 @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On
2936 MinGW targets, @code{ms_printf}, @code{ms_scanf}, and
2937 @code{ms_strftime} are also present.
2938 @var{archetype} values such as @code{printf} refer to the formats accepted
2939 by the system's C runtime library,
2940 while values prefixed with @samp{gnu_} always refer
2941 to the formats accepted by the GNU C Library. On Microsoft Windows
2942 targets, values prefixed with @samp{ms_} refer to the formats accepted by the
2943 @file{msvcrt.dll} library.
2944 The parameter @var{string-index}
2945 specifies which argument is the format string argument (starting
2946 from 1), while @var{first-to-check} is the number of the first
2947 argument to check against the format string. For functions
2948 where the arguments are not available to be checked (such as
2949 @code{vprintf}), specify the third parameter as zero. In this case the
2950 compiler only checks the format string for consistency. For
2951 @code{strftime} formats, the third parameter is required to be zero.
2952 Since non-static C++ methods have an implicit @code{this} argument, the
2953 arguments of such methods should be counted from two, not one, when
2954 giving values for @var{string-index} and @var{first-to-check}.
2956 In the example above, the format string (@code{my_format}) is the second
2957 argument of the function @code{my_print}, and the arguments to check
2958 start with the third argument, so the correct parameters for the format
2959 attribute are 2 and 3.
2961 @opindex ffreestanding
2962 @opindex fno-builtin
2963 The @code{format} attribute allows you to identify your own functions
2964 that take format strings as arguments, so that GCC can check the
2965 calls to these functions for errors. The compiler always (unless
2966 @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
2967 for the standard library functions @code{printf}, @code{fprintf},
2968 @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
2969 @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
2970 warnings are requested (using @option{-Wformat}), so there is no need to
2971 modify the header file @file{stdio.h}. In C99 mode, the functions
2972 @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
2973 @code{vsscanf} are also checked. Except in strictly conforming C
2974 standard modes, the X/Open function @code{strfmon} is also checked as
2975 are @code{printf_unlocked} and @code{fprintf_unlocked}.
2976 @xref{C Dialect Options,,Options Controlling C Dialect}.
2978 For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is
2979 recognized in the same context. Declarations including these format attributes
2980 are parsed for correct syntax, however the result of checking of such format
2981 strings is not yet defined, and is not carried out by this version of the
2984 The target may also provide additional types of format checks.
2985 @xref{Target Format Checks,,Format Checks Specific to Particular
2988 @item format_arg (@var{string-index})
2989 @cindex @code{format_arg} function attribute
2990 @opindex Wformat-nonliteral
2991 The @code{format_arg} attribute specifies that a function takes one or
2992 more format strings for a @code{printf}, @code{scanf}, @code{strftime} or
2993 @code{strfmon} style function and modifies it (for example, to translate
2994 it into another language), so the result can be passed to a
2995 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
2996 function (with the remaining arguments to the format function the same
2997 as they would have been for the unmodified string). Multiple
2998 @code{format_arg} attributes may be applied to the same function, each
2999 designating a distinct parameter as a format string. For example, the
3004 my_dgettext (char *my_domain, const char *my_format)
3005 __attribute__ ((format_arg (2)));
3009 causes the compiler to check the arguments in calls to a @code{printf},
3010 @code{scanf}, @code{strftime} or @code{strfmon} type function, whose
3011 format string argument is a call to the @code{my_dgettext} function, for
3012 consistency with the format string argument @code{my_format}. If the
3013 @code{format_arg} attribute had not been specified, all the compiler
3014 could tell in such calls to format functions would be that the format
3015 string argument is not constant; this would generate a warning when
3016 @option{-Wformat-nonliteral} is used, but the calls could not be checked
3017 without the attribute.
3019 In calls to a function declared with more than one @code{format_arg}
3020 attribute, each with a distinct argument value, the corresponding
3021 actual function arguments are checked against all format strings
3022 designated by the attributes. This capability is designed to support
3023 the GNU @code{ngettext} family of functions.
3025 The parameter @var{string-index} specifies which argument is the format
3026 string argument (starting from one). Since non-static C++ methods have
3027 an implicit @code{this} argument, the arguments of such methods should
3028 be counted from two.
3030 The @code{format_arg} attribute allows you to identify your own
3031 functions that modify format strings, so that GCC can check the
3032 calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
3033 type function whose operands are a call to one of your own function.
3034 The compiler always treats @code{gettext}, @code{dgettext}, and
3035 @code{dcgettext} in this manner except when strict ISO C support is
3036 requested by @option{-ansi} or an appropriate @option{-std} option, or
3037 @option{-ffreestanding} or @option{-fno-builtin}
3038 is used. @xref{C Dialect Options,,Options
3039 Controlling C Dialect}.
3041 For Objective-C dialects, the @code{format-arg} attribute may refer to an
3042 @code{NSString} reference for compatibility with the @code{format} attribute
3045 The target may also allow additional types in @code{format-arg} attributes.
3046 @xref{Target Format Checks,,Format Checks Specific to Particular
3050 @cindex @code{gnu_inline} function attribute
3051 This attribute should be used with a function that is also declared
3052 with the @code{inline} keyword. It directs GCC to treat the function
3053 as if it were defined in gnu90 mode even when compiling in C99 or
3056 If the function is declared @code{extern}, then this definition of the
3057 function is used only for inlining. In no case is the function
3058 compiled as a standalone function, not even if you take its address
3059 explicitly. Such an address becomes an external reference, as if you
3060 had only declared the function, and had not defined it. This has
3061 almost the effect of a macro. The way to use this is to put a
3062 function definition in a header file with this attribute, and put
3063 another copy of the function, without @code{extern}, in a library
3064 file. The definition in the header file causes most calls to the
3065 function to be inlined. If any uses of the function remain, they
3066 refer to the single copy in the library. Note that the two
3067 definitions of the functions need not be precisely the same, although
3068 if they do not have the same effect your program may behave oddly.
3070 In C, if the function is neither @code{extern} nor @code{static}, then
3071 the function is compiled as a standalone function, as well as being
3072 inlined where possible.
3074 This is how GCC traditionally handled functions declared
3075 @code{inline}. Since ISO C99 specifies a different semantics for
3076 @code{inline}, this function attribute is provided as a transition
3077 measure and as a useful feature in its own right. This attribute is
3078 available in GCC 4.1.3 and later. It is available if either of the
3079 preprocessor macros @code{__GNUC_GNU_INLINE__} or
3080 @code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
3081 Function is As Fast As a Macro}.
3083 In C++, this attribute does not depend on @code{extern} in any way,
3084 but it still requires the @code{inline} keyword to enable its special
3088 @cindex @code{hot} function attribute
3089 The @code{hot} attribute on a function is used to inform the compiler that
3090 the function is a hot spot of the compiled program. The function is
3091 optimized more aggressively and on many targets it is placed into a special
3092 subsection of the text section so all hot functions appear close together,
3095 When profile feedback is available, via @option{-fprofile-use}, hot functions
3096 are automatically detected and this attribute is ignored.
3098 @item ifunc ("@var{resolver}")
3099 @cindex @code{ifunc} function attribute
3100 @cindex indirect functions
3101 @cindex functions that are dynamically resolved
3102 The @code{ifunc} attribute is used to mark a function as an indirect
3103 function using the STT_GNU_IFUNC symbol type extension to the ELF
3104 standard. This allows the resolution of the symbol value to be
3105 determined dynamically at load time, and an optimized version of the
3106 routine to be selected for the particular processor or other system
3107 characteristics determined then. To use this attribute, first define
3108 the implementation functions available, and a resolver function that
3109 returns a pointer to the selected implementation function. The
3110 implementation functions' declarations must match the API of the
3111 function being implemented. The resolver should be declared to
3112 be a function taking no arguments and returning a pointer to
3113 a function of the same type as the implementation. For example:
3116 void *my_memcpy (void *dst, const void *src, size_t len)
3122 static void * (*resolve_memcpy (void))(void *, const void *, size_t)
3124 return my_memcpy; // we will just always select this routine
3129 The exported header file declaring the function the user calls would
3133 extern void *memcpy (void *, const void *, size_t);
3137 allowing the user to call @code{memcpy} as a regular function, unaware of
3138 the actual implementation. Finally, the indirect function needs to be
3139 defined in the same translation unit as the resolver function:
3142 void *memcpy (void *, const void *, size_t)
3143 __attribute__ ((ifunc ("resolve_memcpy")));
3146 In C++, the @code{ifunc} attribute takes a string that is the mangled name
3147 of the resolver function. A C++ resolver for a non-static member function
3148 of class @code{C} should be declared to return a pointer to a non-member
3149 function taking pointer to @code{C} as the first argument, followed by
3150 the same arguments as of the implementation function. G++ checks
3151 the signatures of the two functions and issues
3152 a @option{-Wattribute-alias} warning for mismatches. To suppress a warning
3153 for the necessary cast from a pointer to the implementation member function
3154 to the type of the corresponding non-member function use
3155 the @option{-Wno-pmf-conversions} option. For example:
3161 int debug_impl (int);
3162 int optimized_impl (int);
3164 typedef int Func (S*, int);
3166 static Func* resolver ();
3169 int interface (int);
3172 int S::debug_impl (int) @{ /* @r{@dots{}} */ @}
3173 int S::optimized_impl (int) @{ /* @r{@dots{}} */ @}
3175 S::Func* S::resolver ()
3177 int (S::*pimpl) (int)
3178 = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl;
3180 // Cast triggers -Wno-pmf-conversions.
3181 return reinterpret_cast<Func*>(pimpl);
3184 int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv")));
3187 Indirect functions cannot be weak. Binutils version 2.20.1 or higher
3188 and GNU C Library version 2.11.1 are required to use this feature.
3191 @itemx interrupt_handler
3192 Many GCC back ends support attributes to indicate that a function is
3193 an interrupt handler, which tells the compiler to generate function
3194 entry and exit sequences that differ from those from regular
3195 functions. The exact syntax and behavior are target-specific;
3196 refer to the following subsections for details.
3199 @cindex @code{leaf} function attribute
3200 Calls to external functions with this attribute must return to the
3201 current compilation unit only by return or by exception handling. In
3202 particular, a leaf function is not allowed to invoke callback functions
3203 passed to it from the current compilation unit, directly call functions
3204 exported by the unit, or @code{longjmp} into the unit. Leaf functions
3205 might still call functions from other compilation units and thus they
3206 are not necessarily leaf in the sense that they contain no function
3209 The attribute is intended for library functions to improve dataflow
3210 analysis. The compiler takes the hint that any data not escaping the
3211 current compilation unit cannot be used or modified by the leaf
3212 function. For example, the @code{sin} function is a leaf function, but
3213 @code{qsort} is not.
3215 Note that leaf functions might indirectly run a signal handler defined
3216 in the current compilation unit that uses static variables. Similarly,
3217 when lazy symbol resolution is in effect, leaf functions might invoke
3218 indirect functions whose resolver function or implementation function is
3219 defined in the current compilation unit and uses static variables. There
3220 is no standard-compliant way to write such a signal handler, resolver
3221 function, or implementation function, and the best that you can do is to
3222 remove the @code{leaf} attribute or mark all such static variables
3223 @code{volatile}. Lastly, for ELF-based systems that support symbol
3224 interposition, care should be taken that functions defined in the
3225 current compilation unit do not unexpectedly interpose other symbols
3226 based on the defined standards mode and defined feature test macros;
3227 otherwise an inadvertent callback would be added.
3229 The attribute has no effect on functions defined within the current
3230 compilation unit. This is to allow easy merging of multiple compilation
3231 units into one, for example, by using the link-time optimization. For
3232 this reason the attribute is not allowed on types to annotate indirect
3236 @item malloc (@var{deallocator})
3237 @item malloc (@var{deallocator}, @var{ptr-index})
3238 @cindex @code{malloc} function attribute
3239 @cindex functions that behave like malloc
3240 Attribute @code{malloc} indicates that a function is @code{malloc}-like,
3241 i.e., that the pointer @var{P} returned by the function cannot alias any
3242 other pointer valid when the function returns, and moreover no
3243 pointers to valid objects occur in any storage addressed by @var{P}.
3245 Independently, the form of the attribute with one or two arguments
3246 associates @code{deallocator} as a suitable deallocation function for
3247 pointers returned from the @code{malloc}-like function. @var{ptr-index}
3248 denotes the positional argument to which when the pointer is passed in
3249 calls to @code{deallocator} has the effect of deallocating it.
3251 Using the attribute with no arguments is designed to improve optimization.
3252 The compiler predicts that a function with the attribute returns non-null
3253 in most cases. Functions like @code{malloc} and @code{calloc} have this
3254 property because they return a pointer to uninitialized or zeroed-out
3255 storage. However, functions like @code{realloc} do not have this property,
3256 as they may return pointers to storage containing pointers to existing
3259 Associating a function with a @var{deallocator} helps detect calls to
3260 mismatched allocation and deallocation functions and diagnose them under
3261 the control of options such as @option{-Wmismatched-dealloc}. To indicate
3262 that an allocation function both satisifies the nonaliasing property and
3263 has a deallocator associated with it, both the plain form of the attribute
3264 and the one with the @var{deallocator} argument must be used. The same
3265 function can be both an allocator and a deallocator. Since inlining one
3266 of the associated functions but not the other could result in apparent
3267 mismatches, this form of attribute @code{malloc} is not accepted on inline
3268 functions. For the same reason, using the attribute prevents both
3269 the allocation and deallocation functions from being expanded inline.
3271 For example, besides stating that the functions return pointers that do
3272 not alias any others, the following declarations make @code{fclose}
3273 a suitable deallocator for pointers returned from all functions except
3274 @code{popen}, and @code{pclose} as the only suitable deallocator for
3275 pointers returned from @code{popen}. The deallocator functions must
3276 declared before they can be referenced in the attribute.
3282 __attribute__ ((malloc, malloc (fclose (1))))
3284 __attribute__ ((malloc, malloc (fclose (1))))
3285 FILE* fopen (const char*, const char*);
3286 __attribute__ ((malloc, malloc (fclose (1))))
3287 FILE* fmemopen(void *, size_t, const char *);
3288 __attribute__ ((malloc, malloc (pclose (1))))
3289 FILE* popen (const char*, const char*);
3290 __attribute__ ((malloc, malloc (fclose (1))))
3291 FILE* tmpfile (void);
3294 The warnings guarded by @option{-fanalyzer} respect allocation and
3295 deallocation pairs marked with the @code{malloc}. In particular:
3300 The analyzer will emit a @option{-Wanalyzer-mismatching-deallocation}
3301 diagnostic if there is an execution path in which the result of an
3302 allocation call is passed to a different deallocator.
3305 The analyzer will emit a @option{-Wanalyzer-double-free}
3306 diagnostic if there is an execution path in which a value is passed
3307 more than once to a deallocation call.
3310 The analyzer will consider the possibility that an allocation function
3311 could fail and return NULL. It will emit
3312 @option{-Wanalyzer-possible-null-dereference} and
3313 @option{-Wanalyzer-possible-null-argument} diagnostics if there are
3314 execution paths in which an unchecked result of an allocation call is
3315 dereferenced or passed to a function requiring a non-null argument.
3316 If the allocator always returns non-null, use
3317 @code{__attribute__ ((returns_nonnull))} to suppress these warnings.
3320 char *xstrdup (const char *)
3321 __attribute__((malloc (free), returns_nonnull));
3325 The analyzer will emit a @option{-Wanalyzer-use-after-free}
3326 diagnostic if there is an execution path in which the memory passed
3327 by pointer to a deallocation call is used after the deallocation.
3330 The analyzer will emit a @option{-Wanalyzer-malloc-leak} diagnostic if
3331 there is an execution path in which the result of an allocation call
3332 is leaked (without being passed to the deallocation function).
3335 The analyzer will emit a @option{-Wanalyzer-free-of-non-heap} diagnostic
3336 if a deallocation function is used on a global or on-stack variable.
3340 The analyzer assumes that deallocators can gracefully handle the @code{NULL}
3341 pointer. If this is not the case, the deallocator can be marked with
3342 @code{__attribute__((nonnull))} so that @option{-fanalyzer} can emit
3343 a @option{-Wanalyzer-possible-null-argument} diagnostic for code paths
3344 in which the deallocator is called with NULL.
3347 @cindex @code{no_icf} function attribute
3348 This function attribute prevents a functions from being merged with another
3349 semantically equivalent function.
3351 @item no_instrument_function
3352 @cindex @code{no_instrument_function} function attribute
3353 @opindex finstrument-functions
3356 If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are
3357 given, profiling function calls are
3358 generated at entry and exit of most user-compiled functions.
3359 Functions with this attribute are not so instrumented.
3361 @item no_profile_instrument_function
3362 @cindex @code{no_profile_instrument_function} function attribute
3363 The @code{no_profile_instrument_function} attribute on functions is used
3364 to inform the compiler that it should not process any profile feedback based
3365 optimization code instrumentation.
3368 @cindex @code{no_reorder} function attribute
3369 Do not reorder functions or variables marked @code{no_reorder}
3370 against each other or top level assembler statements the executable.
3371 The actual order in the program will depend on the linker command
3372 line. Static variables marked like this are also not removed.
3373 This has a similar effect
3374 as the @option{-fno-toplevel-reorder} option, but only applies to the
3377 @item no_sanitize ("@var{sanitize_option}")
3378 @cindex @code{no_sanitize} function attribute
3379 The @code{no_sanitize} attribute on functions is used
3380 to inform the compiler that it should not do sanitization of any option
3381 mentioned in @var{sanitize_option}. A list of values acceptable by
3382 the @option{-fsanitize} option can be provided.
3385 void __attribute__ ((no_sanitize ("alignment", "object-size")))
3386 f () @{ /* @r{Do something.} */; @}
3387 void __attribute__ ((no_sanitize ("alignment,object-size")))
3388 g () @{ /* @r{Do something.} */; @}
3391 @item no_sanitize_address
3392 @itemx no_address_safety_analysis
3393 @cindex @code{no_sanitize_address} function attribute
3394 The @code{no_sanitize_address} attribute on functions is used
3395 to inform the compiler that it should not instrument memory accesses
3396 in the function when compiling with the @option{-fsanitize=address} option.
3397 The @code{no_address_safety_analysis} is a deprecated alias of the
3398 @code{no_sanitize_address} attribute, new code should use
3399 @code{no_sanitize_address}.
3401 @item no_sanitize_thread
3402 @cindex @code{no_sanitize_thread} function attribute
3403 The @code{no_sanitize_thread} attribute on functions is used
3404 to inform the compiler that it should not instrument memory accesses
3405 in the function when compiling with the @option{-fsanitize=thread} option.
3407 @item no_sanitize_undefined
3408 @cindex @code{no_sanitize_undefined} function attribute
3409 The @code{no_sanitize_undefined} attribute on functions is used
3410 to inform the compiler that it should not check for undefined behavior
3411 in the function when compiling with the @option{-fsanitize=undefined} option.
3413 @item no_split_stack
3414 @cindex @code{no_split_stack} function attribute
3415 @opindex fsplit-stack
3416 If @option{-fsplit-stack} is given, functions have a small
3417 prologue which decides whether to split the stack. Functions with the
3418 @code{no_split_stack} attribute do not have that prologue, and thus
3419 may run with only a small amount of stack space available.
3421 @item no_stack_limit
3422 @cindex @code{no_stack_limit} function attribute
3423 This attribute locally overrides the @option{-fstack-limit-register}
3424 and @option{-fstack-limit-symbol} command-line options; it has the effect
3425 of disabling stack limit checking in the function it applies to.
3428 @cindex @code{noclone} function attribute
3429 This function attribute prevents a function from being considered for
3430 cloning---a mechanism that produces specialized copies of functions
3431 and which is (currently) performed by interprocedural constant
3435 @cindex @code{noinline} function attribute
3436 This function attribute prevents a function from being considered for
3438 @c Don't enumerate the optimizations by name here; we try to be
3439 @c future-compatible with this mechanism.
3440 If the function does not have side effects, there are optimizations
3441 other than inlining that cause function calls to be optimized away,
3442 although the function call is live. To keep such calls from being
3449 (@pxref{Extended Asm}) in the called function, to serve as a special
3453 @cindex @code{noipa} function attribute
3454 Disable interprocedural optimizations between the function with this
3455 attribute and its callers, as if the body of the function is not available
3456 when optimizing callers and the callers are unavailable when optimizing
3457 the body. This attribute implies @code{noinline}, @code{noclone} and
3458 @code{no_icf} attributes. However, this attribute is not equivalent
3459 to a combination of other attributes, because its purpose is to suppress
3460 existing and future optimizations employing interprocedural analysis,
3461 including those that do not have an attribute suitable for disabling
3462 them individually. This attribute is supported mainly for the purpose
3463 of testing the compiler.
3466 @itemx nonnull (@var{arg-index}, @dots{})
3467 @cindex @code{nonnull} function attribute
3468 @cindex functions with non-null pointer arguments
3469 The @code{nonnull} attribute may be applied to a function that takes at
3470 least one argument of a pointer type. It indicates that the referenced
3471 arguments must be non-null pointers. For instance, the declaration:
3475 my_memcpy (void *dest, const void *src, size_t len)
3476 __attribute__((nonnull (1, 2)));
3480 causes the compiler to check that, in calls to @code{my_memcpy},
3481 arguments @var{dest} and @var{src} are non-null. If the compiler
3482 determines that a null pointer is passed in an argument slot marked
3483 as non-null, and the @option{-Wnonnull} option is enabled, a warning
3484 is issued. @xref{Warning Options}. Unless disabled by
3485 the @option{-fno-delete-null-pointer-checks} option the compiler may
3486 also perform optimizations based on the knowledge that certain function
3487 arguments cannot be null. In addition,
3488 the @option{-fisolate-erroneous-paths-attribute} option can be specified
3489 to have GCC transform calls with null arguments to non-null functions
3490 into traps. @xref{Optimize Options}.
3492 If no @var{arg-index} is given to the @code{nonnull} attribute,
3493 all pointer arguments are marked as non-null. To illustrate, the
3494 following declaration is equivalent to the previous example:
3498 my_memcpy (void *dest, const void *src, size_t len)
3499 __attribute__((nonnull));
3503 @cindex @code{noplt} function attribute
3504 The @code{noplt} attribute is the counterpart to option @option{-fno-plt}.
3505 Calls to functions marked with this attribute in position-independent code
3510 /* Externally defined function foo. */
3511 int foo () __attribute__ ((noplt));
3514 main (/* @r{@dots{}} */)
3523 The @code{noplt} attribute on function @code{foo}
3524 tells the compiler to assume that
3525 the function @code{foo} is externally defined and that the call to
3526 @code{foo} must avoid the PLT
3527 in position-independent code.
3529 In position-dependent code, a few targets also convert calls to
3530 functions that are marked to not use the PLT to use the GOT instead.
3533 @cindex @code{noreturn} function attribute
3534 @cindex functions that never return
3535 A few standard library functions, such as @code{abort} and @code{exit},
3536 cannot return. GCC knows this automatically. Some programs define
3537 their own functions that never return. You can declare them
3538 @code{noreturn} to tell the compiler this fact. For example,
3542 void fatal () __attribute__ ((noreturn));
3545 fatal (/* @r{@dots{}} */)
3547 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
3553 The @code{noreturn} keyword tells the compiler to assume that
3554 @code{fatal} cannot return. It can then optimize without regard to what
3555 would happen if @code{fatal} ever did return. This makes slightly
3556 better code. More importantly, it helps avoid spurious warnings of
3557 uninitialized variables.
3559 The @code{noreturn} keyword does not affect the exceptional path when that
3560 applies: a @code{noreturn}-marked function may still return to the caller
3561 by throwing an exception or calling @code{longjmp}.
3563 In order to preserve backtraces, GCC will never turn calls to
3564 @code{noreturn} functions into tail calls.
3566 Do not assume that registers saved by the calling function are
3567 restored before calling the @code{noreturn} function.
3569 It does not make sense for a @code{noreturn} function to have a return
3570 type other than @code{void}.
3573 @cindex @code{nothrow} function attribute
3574 The @code{nothrow} attribute is used to inform the compiler that a
3575 function cannot throw an exception. For example, most functions in
3576 the standard C library can be guaranteed not to throw an exception
3577 with the notable exceptions of @code{qsort} and @code{bsearch} that
3578 take function pointer arguments.
3580 @item optimize (@var{level}, @dots{})
3581 @item optimize (@var{string}, @dots{})
3582 @cindex @code{optimize} function attribute
3583 The @code{optimize} attribute is used to specify that a function is to
3584 be compiled with different optimization options than specified on the
3585 command line. Valid arguments are constant non-negative integers and
3586 strings. Each numeric argument specifies an optimization @var{level}.
3587 Each @var{string} argument consists of one or more comma-separated
3588 substrings. Each substring that begins with the letter @code{O} refers
3589 to an optimization option such as @option{-O0} or @option{-Os}. Other
3590 substrings are taken as suffixes to the @code{-f} prefix jointly
3591 forming the name of an optimization option. @xref{Optimize Options}.
3593 @samp{#pragma GCC optimize} can be used to set optimization options
3594 for more than one function. @xref{Function Specific Option Pragmas},
3595 for details about the pragma.
3597 Providing multiple strings as arguments separated by commas to specify
3598 multiple options is equivalent to separating the option suffixes with
3599 a comma (@samp{,}) within a single string. Spaces are not permitted
3602 Not every optimization option that starts with the @var{-f} prefix
3603 specified by the attribute necessarily has an effect on the function.
3604 The @code{optimize} attribute should be used for debugging purposes only.
3605 It is not suitable in production code.
3607 @item patchable_function_entry
3608 @cindex @code{patchable_function_entry} function attribute
3609 @cindex extra NOP instructions at the function entry point
3610 In case the target's text segment can be made writable at run time by
3611 any means, padding the function entry with a number of NOPs can be
3612 used to provide a universal tool for instrumentation.
3614 The @code{patchable_function_entry} function attribute can be used to
3615 change the number of NOPs to any desired value. The two-value syntax
3616 is the same as for the command-line switch
3617 @option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with
3618 the function entry point before the @var{M}th NOP instruction.
3619 @var{M} defaults to 0 if omitted e.g.@: function entry point is before
3622 If patchable function entries are enabled globally using the command-line
3623 option @option{-fpatchable-function-entry=N,M}, then you must disable
3624 instrumentation on all functions that are part of the instrumentation
3625 framework with the attribute @code{patchable_function_entry (0)}
3626 to prevent recursion.
3629 @cindex @code{pure} function attribute
3630 @cindex functions that have no side effects
3632 Calls to functions that have no observable effects on the state of
3633 the program other than to return a value may lend themselves to optimizations
3634 such as common subexpression elimination. Declaring such functions with
3635 the @code{pure} attribute allows GCC to avoid emitting some calls in repeated
3636 invocations of the function with the same argument values.
3638 The @code{pure} attribute prohibits a function from modifying the state
3639 of the program that is observable by means other than inspecting
3640 the function's return value. However, functions declared with the @code{pure}
3641 attribute can safely read any non-volatile objects, and modify the value of
3642 objects in a way that does not affect their return value or the observable
3643 state of the program.
3648 int hash (char *) __attribute__ ((pure));
3652 tells GCC that subsequent calls to the function @code{hash} with the same
3653 string can be replaced by the result of the first call provided the state
3654 of the program observable by @code{hash}, including the contents of the array
3655 itself, does not change in between. Even though @code{hash} takes a non-const
3656 pointer argument it must not modify the array it points to, or any other object
3657 whose value the rest of the program may depend on. However, the caller may
3658 safely change the contents of the array between successive calls to
3659 the function (doing so disables the optimization). The restriction also
3660 applies to member objects referenced by the @code{this} pointer in C++
3661 non-static member functions.
3663 Some common examples of pure functions are @code{strlen} or @code{memcmp}.
3664 Interesting non-pure functions are functions with infinite loops or those
3665 depending on volatile memory or other system resource, that may change between
3666 consecutive calls (such as the standard C @code{feof} function in
3667 a multithreading environment).
3669 The @code{pure} attribute imposes similar but looser restrictions on
3670 a function's definition than the @code{const} attribute: @code{pure}
3671 allows the function to read any non-volatile memory, even if it changes
3672 in between successive invocations of the function. Declaring the same
3673 function with both the @code{pure} and the @code{const} attribute is
3674 diagnosed. Because a pure function cannot have any observable side
3675 effects it does not make sense for such a function to return @code{void}.
3676 Declaring such a function is diagnosed.
3678 @item returns_nonnull
3679 @cindex @code{returns_nonnull} function attribute
3680 The @code{returns_nonnull} attribute specifies that the function
3681 return value should be a non-null pointer. For instance, the declaration:
3685 mymalloc (size_t len) __attribute__((returns_nonnull));
3689 lets the compiler optimize callers based on the knowledge
3690 that the return value will never be null.
3693 @cindex @code{returns_twice} function attribute
3694 @cindex functions that return more than once
3695 The @code{returns_twice} attribute tells the compiler that a function may
3696 return more than one time. The compiler ensures that all registers
3697 are dead before calling such a function and emits a warning about
3698 the variables that may be clobbered after the second return from the
3699 function. Examples of such functions are @code{setjmp} and @code{vfork}.
3700 The @code{longjmp}-like counterpart of such function, if any, might need
3701 to be marked with the @code{noreturn} attribute.
3703 @item section ("@var{section-name}")
3704 @cindex @code{section} function attribute
3705 @cindex functions in arbitrary sections
3706 Normally, the compiler places the code it generates in the @code{text} section.
3707 Sometimes, however, you need additional sections, or you need certain
3708 particular functions to appear in special sections. The @code{section}
3709 attribute specifies that a function lives in a particular section.
3710 For example, the declaration:
3713 extern void foobar (void) __attribute__ ((section ("bar")));
3717 puts the function @code{foobar} in the @code{bar} section.
3719 Some file formats do not support arbitrary sections so the @code{section}
3720 attribute is not available on all platforms.
3721 If you need to map the entire contents of a module to a particular
3722 section, consider using the facilities of the linker instead.
3725 @itemx sentinel (@var{position})
3726 @cindex @code{sentinel} function attribute
3727 This function attribute indicates that an argument in a call to the function
3728 is expected to be an explicit @code{NULL}. The attribute is only valid on
3729 variadic functions. By default, the sentinel is expected to be the last
3730 argument of the function call. If the optional @var{position} argument
3731 is specified to the attribute, the sentinel must be located at
3732 @var{position} counting backwards from the end of the argument list.
3735 __attribute__ ((sentinel))
3737 __attribute__ ((sentinel(0)))
3740 The attribute is automatically set with a position of 0 for the built-in
3741 functions @code{execl} and @code{execlp}. The built-in function
3742 @code{execle} has the attribute set with a position of 1.
3744 A valid @code{NULL} in this context is defined as zero with any object
3745 pointer type. If your system defines the @code{NULL} macro with
3746 an integer type then you need to add an explicit cast. During
3747 installation GCC replaces the system @code{<stddef.h>} header with
3748 a copy that redefines NULL appropriately.
3750 The warnings for missing or incorrect sentinels are enabled with
3754 @itemx simd("@var{mask}")
3755 @cindex @code{simd} function attribute
3756 This attribute enables creation of one or more function versions that
3757 can process multiple arguments using SIMD instructions from a
3758 single invocation. Specifying this attribute allows compiler to
3759 assume that such versions are available at link time (provided
3760 in the same or another translation unit). Generated versions are
3761 target-dependent and described in the corresponding Vector ABI document. For
3762 x86_64 target this document can be found
3763 @w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}.
3765 The optional argument @var{mask} may have the value
3766 @code{notinbranch} or @code{inbranch},
3767 and instructs the compiler to generate non-masked or masked
3768 clones correspondingly. By default, all clones are generated.
3770 If the attribute is specified and @code{#pragma omp declare simd} is
3771 present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd}
3772 switch is specified, then the attribute is ignored.
3775 @cindex @code{stack_protect} function attribute
3776 This attribute adds stack protection code to the function if
3777 flags @option{-fstack-protector}, @option{-fstack-protector-strong}
3778 or @option{-fstack-protector-explicit} are set.
3780 @item no_stack_protector
3781 @cindex @code{no_stack_protector} function attribute
3782 This attribute prevents stack protection code for the function.
3784 @item target (@var{string}, @dots{})
3785 @cindex @code{target} function attribute
3786 Multiple target back ends implement the @code{target} attribute
3787 to specify that a function is to
3788 be compiled with different target options than specified on the
3789 command line. One or more strings can be provided as arguments.
3790 Each string consists of one or more comma-separated suffixes to
3791 the @code{-m} prefix jointly forming the name of a machine-dependent
3792 option. @xref{Submodel Options,,Machine-Dependent Options}.
3794 The @code{target} attribute can be used for instance to have a function
3795 compiled with a different ISA (instruction set architecture) than the
3796 default. @samp{#pragma GCC target} can be used to specify target-specific
3797 options for more than one function. @xref{Function Specific Option Pragmas},
3798 for details about the pragma.
3800 For instance, on an x86, you could declare one function with the
3801 @code{target("sse4.1,arch=core2")} attribute and another with
3802 @code{target("sse4a,arch=amdfam10")}. This is equivalent to
3803 compiling the first function with @option{-msse4.1} and
3804 @option{-march=core2} options, and the second function with
3805 @option{-msse4a} and @option{-march=amdfam10} options. It is up to you
3806 to make sure that a function is only invoked on a machine that
3807 supports the particular ISA it is compiled for (for example by using
3808 @code{cpuid} on x86 to determine what feature bits and architecture
3812 int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
3813 int sse3_func (void) __attribute__ ((__target__ ("sse3")));
3816 Providing multiple strings as arguments separated by commas to specify
3817 multiple options is equivalent to separating the option suffixes with
3818 a comma (@samp{,}) within a single string. Spaces are not permitted
3821 The options supported are specific to each target; refer to @ref{x86
3822 Function Attributes}, @ref{PowerPC Function Attributes},
3823 @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
3824 @ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
3827 @item symver ("@var{name2}@@@var{nodename}")
3828 @cindex @code{symver} function attribute
3829 On ELF targets this attribute creates a symbol version. The @var{name2} part
3830 of the parameter is the actual name of the symbol by which it will be
3831 externally referenced. The @code{nodename} portion should be the name of a
3832 node specified in the version script supplied to the linker when building a
3833 shared library. Versioned symbol must be defined and must be exported with
3837 __attribute__ ((__symver__ ("foo@@VERS_1"))) int
3843 Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
3846 One can also define multiple version for a given symbol.
3849 __attribute__ ((__symver__ ("foo@@VERS_2"), ("foo@@VERS_3")))
3850 int symver_foo_v1 (void)
3854 __attribute__ ((__symver__ ("bar@@VERS_2"))))
3855 __attribute__ ((__symver__ ("bar@@VERS_3"))))
3856 int symver_bar_v1 (void)
3861 This example creates an alias of @code{foo_v1} with symbol name
3862 @code{symver_foo_v1} which will be version @code{VERS_2} of @code{foo}.
3864 Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
3865 addition to creating a symbol version (as if
3866 @code{"@var{name2}@@@var{nodename}"} was used) the version will be also used
3867 to resolve @var{name2} by the linker.
3869 @item target_clones (@var{options})
3870 @cindex @code{target_clones} function attribute
3871 The @code{target_clones} attribute is used to specify that a function
3872 be cloned into multiple versions compiled with different target options
3873 than specified on the command line. The supported options and restrictions
3874 are the same as for @code{target} attribute.
3876 For instance, on an x86, you could compile a function with
3877 @code{target_clones("sse4.1,avx")}. GCC creates two function clones,
3878 one compiled with @option{-msse4.1} and another with @option{-mavx}.
3880 On a PowerPC, you can compile a function with
3881 @code{target_clones("cpu=power9,default")}. GCC will create two
3882 function clones, one compiled with @option{-mcpu=power9} and another
3883 with the default options. GCC must be configured to use GLIBC 2.23 or
3884 newer in order to use the @code{target_clones} attribute.
3886 It also creates a resolver function (see
3887 the @code{ifunc} attribute above) that dynamically selects a clone
3888 suitable for current architecture. The resolver is created only if there
3889 is a usage of a function with @code{target_clones} attribute.
3891 Note that any subsequent call of a function without @code{target_clone}
3892 from a @code{target_clone} caller will not lead to copying
3893 (target clone) of the called function.
3894 If you want to enforce such behaviour,
3895 we recommend declaring the calling function with the @code{flatten} attribute?
3898 @cindex @code{unused} function attribute
3899 This attribute, attached to a function, means that the function is meant
3900 to be possibly unused. GCC does not produce a warning for this
3904 @cindex @code{used} function attribute
3905 This attribute, attached to a function, means that code must be emitted
3906 for the function even if it appears that the function is not referenced.
3907 This is useful, for example, when the function is referenced only in
3910 When applied to a member function of a C++ class template, the
3911 attribute also means that the function is instantiated if the
3912 class itself is instantiated.
3914 For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
3915 will also save the function from linker garbage collection. To support
3916 this behavior, functions that have not been placed in specific sections
3917 (e.g. by the @code{section} attribute, or the @code{-ffunction-sections}
3918 option), will be placed in new, unique sections.
3920 This additional functionality requires Binutils version 2.36 or later.
3922 @item visibility ("@var{visibility_type}")
3923 @cindex @code{visibility} function attribute
3924 This attribute affects the linkage of the declaration to which it is attached.
3925 It can be applied to variables (@pxref{Common Variable Attributes}) and types
3926 (@pxref{Common Type Attributes}) as well as functions.
3928 There are four supported @var{visibility_type} values: default,
3929 hidden, protected or internal visibility.
3932 void __attribute__ ((visibility ("protected")))
3933 f () @{ /* @r{Do something.} */; @}
3934 int i __attribute__ ((visibility ("hidden")));
3937 The possible values of @var{visibility_type} correspond to the
3938 visibility settings in the ELF gABI.
3941 @c keep this list of visibilities in alphabetical order.
3944 Default visibility is the normal case for the object file format.
3945 This value is available for the visibility attribute to override other
3946 options that may change the assumed visibility of entities.
3948 On ELF, default visibility means that the declaration is visible to other
3949 modules and, in shared libraries, means that the declared entity may be
3952 On Darwin, default visibility means that the declaration is visible to
3955 Default visibility corresponds to ``external linkage'' in the language.
3958 Hidden visibility indicates that the entity declared has a new
3959 form of linkage, which we call ``hidden linkage''. Two
3960 declarations of an object with hidden linkage refer to the same object
3961 if they are in the same shared object.
3964 Internal visibility is like hidden visibility, but with additional
3965 processor specific semantics. Unless otherwise specified by the
3966 psABI, GCC defines internal visibility to mean that a function is
3967 @emph{never} called from another module. Compare this with hidden
3968 functions which, while they cannot be referenced directly by other
3969 modules, can be referenced indirectly via function pointers. By
3970 indicating that a function cannot be called from outside the module,
3971 GCC may for instance omit the load of a PIC register since it is known
3972 that the calling function loaded the correct value.
3975 Protected visibility is like default visibility except that it
3976 indicates that references within the defining module bind to the
3977 definition in that module. That is, the declared entity cannot be
3978 overridden by another module.
3982 All visibilities are supported on many, but not all, ELF targets
3983 (supported when the assembler supports the @samp{.visibility}
3984 pseudo-op). Default visibility is supported everywhere. Hidden
3985 visibility is supported on Darwin targets.
3987 The visibility attribute should be applied only to declarations that
3988 would otherwise have external linkage. The attribute should be applied
3989 consistently, so that the same entity should not be declared with
3990 different settings of the attribute.
3992 In C++, the visibility attribute applies to types as well as functions
3993 and objects, because in C++ types have linkage. A class must not have
3994 greater visibility than its non-static data member types and bases,
3995 and class members default to the visibility of their class. Also, a
3996 declaration without explicit visibility is limited to the visibility
3999 In C++, you can mark member functions and static member variables of a
4000 class with the visibility attribute. This is useful if you know a
4001 particular method or static member variable should only be used from
4002 one shared object; then you can mark it hidden while the rest of the
4003 class has default visibility. Care must be taken to avoid breaking
4004 the One Definition Rule; for example, it is usually not useful to mark
4005 an inline method as hidden without marking the whole class as hidden.
4007 A C++ namespace declaration can also have the visibility attribute.
4010 namespace nspace1 __attribute__ ((visibility ("protected")))
4011 @{ /* @r{Do something.} */; @}
4014 This attribute applies only to the particular namespace body, not to
4015 other definitions of the same namespace; it is equivalent to using
4016 @samp{#pragma GCC visibility} before and after the namespace
4017 definition (@pxref{Visibility Pragmas}).
4019 In C++, if a template argument has limited visibility, this
4020 restriction is implicitly propagated to the template instantiation.
4021 Otherwise, template instantiations and specializations default to the
4022 visibility of their template.
4024 If both the template and enclosing class have explicit visibility, the
4025 visibility from the template is used.
4027 @item warn_unused_result
4028 @cindex @code{warn_unused_result} function attribute
4029 The @code{warn_unused_result} attribute causes a warning to be emitted
4030 if a caller of the function with this attribute does not use its
4031 return value. This is useful for functions where not checking
4032 the result is either a security problem or always a bug, such as
4036 int fn () __attribute__ ((warn_unused_result));
4039 if (fn () < 0) return -1;
4046 results in warning on line 5.
4049 @cindex @code{weak} function attribute
4050 The @code{weak} attribute causes a declaration of an external symbol
4051 to be emitted as a weak symbol rather than a global. This is primarily
4052 useful in defining library functions that can be overridden in user code,
4053 though it can also be used with non-function declarations. The overriding
4054 symbol must have the same type as the weak symbol. In addition, if it
4055 designates a variable it must also have the same size and alignment as
4056 the weak symbol. Weak symbols are supported for ELF targets, and also
4057 for a.out targets when using the GNU assembler and linker.
4060 @itemx weakref ("@var{target}")
4061 @cindex @code{weakref} function attribute
4062 The @code{weakref} attribute marks a declaration as a weak reference.
4063 Without arguments, it should be accompanied by an @code{alias} attribute
4064 naming the target symbol. Alternatively, @var{target} may be given as
4065 an argument to @code{weakref} itself, naming the target definition of
4066 the alias. The @var{target} must have the same type as the declaration.
4067 In addition, if it designates a variable it must also have the same size
4068 and alignment as the declaration. In either form of the declaration
4069 @code{weakref} implicitly marks the declared symbol as @code{weak}. Without
4070 a @var{target} given as an argument to @code{weakref} or to @code{alias},
4071 @code{weakref} is equivalent to @code{weak} (in that case the declaration
4072 may be @code{extern}).
4075 /* Given the declaration: */
4076 extern int y (void);
4078 /* the following... */
4079 static int x (void) __attribute__ ((weakref ("y")));
4081 /* is equivalent to... */
4082 static int x (void) __attribute__ ((weakref, alias ("y")));
4084 /* or, alternatively, to... */
4085 static int x (void) __attribute__ ((weakref));
4086 static int x (void) __attribute__ ((alias ("y")));
4089 A weak reference is an alias that does not by itself require a
4090 definition to be given for the target symbol. If the target symbol is
4091 only referenced through weak references, then it becomes a @code{weak}
4092 undefined symbol. If it is directly referenced, however, then such
4093 strong references prevail, and a definition is required for the
4094 symbol, not necessarily in the same translation unit.
4096 The effect is equivalent to moving all references to the alias to a
4097 separate translation unit, renaming the alias to the aliased symbol,
4098 declaring it as weak, compiling the two separate translation units and
4099 performing a link with relocatable output (i.e.@: @code{ld -r}) on them.
4101 A declaration to which @code{weakref} is attached and that is associated
4102 with a named @code{target} must be @code{static}.
4104 @item zero_call_used_regs ("@var{choice}")
4105 @cindex @code{zero_call_used_regs} function attribute
4107 The @code{zero_call_used_regs} attribute causes the compiler to zero
4108 a subset of all call-used registers@footnote{A ``call-used'' register
4109 is a register whose contents can be changed by a function call;
4110 therefore, a caller cannot assume that the register has the same contents
4111 on return from the function as it had before calling the function. Such
4112 registers are also called ``call-clobbered'', ``caller-saved'', or
4113 ``volatile''.} at function return.
4114 This is used to increase program security by either mitigating
4115 Return-Oriented Programming (ROP) attacks or preventing information leakage
4118 In order to satisfy users with different security needs and control the
4119 run-time overhead at the same time, the @var{choice} parameter provides a
4120 flexible way to choose the subset of the call-used registers to be zeroed.
4121 The three basic values of @var{choice} are:
4125 @samp{skip} doesn't zero any call-used registers.
4128 @samp{used} only zeros call-used registers that are used in the function.
4129 A ``used'' register is one whose content has been set or referenced in
4133 @samp{all} zeros all call-used registers.
4136 In addition to these three basic choices, it is possible to modify
4137 @samp{used} or @samp{all} as follows:
4141 Adding @samp{-gpr} restricts the zeroing to general-purpose registers.
4144 Adding @samp{-arg} restricts the zeroing to registers that can sometimes
4145 be used to pass function arguments. This includes all argument registers
4146 defined by the platform's calling conversion, regardless of whether the
4147 function uses those registers for function arguments or not.
4150 The modifiers can be used individually or together. If they are used
4151 together, they must appear in the order above.
4153 The full list of @var{choice}s is therefore:
4157 doesn't zero any call-used register.
4160 only zeros call-used registers that are used in the function.
4163 only zeros call-used general purpose registers that are used in the function.
4166 only zeros call-used registers that are used in the function and pass arguments.
4169 only zeros call-used general purpose registers that are used in the function
4173 zeros all call-used registers.
4176 zeros all call-used general purpose registers.
4179 zeros all call-used registers that pass arguments.
4182 zeros all call-used general purpose registers that pass
4186 Of this list, @samp{used-arg}, @samp{used-gpr-arg}, @samp{all-arg},
4187 and @samp{all-gpr-arg} are mainly used for ROP mitigation.
4189 The default for the attribute is controlled by @option{-fzero-call-used-regs}.
4192 @c This is the end of the target-independent attribute table
4194 @node AArch64 Function Attributes
4195 @subsection AArch64 Function Attributes
4197 The following target-specific function attributes are available for the
4198 AArch64 target. For the most part, these options mirror the behavior of
4199 similar command-line options (@pxref{AArch64 Options}), but on a
4203 @item general-regs-only
4204 @cindex @code{general-regs-only} function attribute, AArch64
4205 Indicates that no floating-point or Advanced SIMD registers should be
4206 used when generating code for this function. If the function explicitly
4207 uses floating-point code, then the compiler gives an error. This is
4208 the same behavior as that of the command-line option
4209 @option{-mgeneral-regs-only}.
4211 @item fix-cortex-a53-835769
4212 @cindex @code{fix-cortex-a53-835769} function attribute, AArch64
4213 Indicates that the workaround for the Cortex-A53 erratum 835769 should be
4214 applied to this function. To explicitly disable the workaround for this
4215 function specify the negated form: @code{no-fix-cortex-a53-835769}.
4216 This corresponds to the behavior of the command line options
4217 @option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
4220 @cindex @code{cmodel=} function attribute, AArch64
4221 Indicates that code should be generated for a particular code model for
4222 this function. The behavior and permissible arguments are the same as
4223 for the command line option @option{-mcmodel=}.
4226 @itemx no-strict-align
4227 @cindex @code{strict-align} function attribute, AArch64
4228 @code{strict-align} indicates that the compiler should not assume that unaligned
4229 memory references are handled by the system. To allow the compiler to assume
4230 that aligned memory references are handled by the system, the inverse attribute
4231 @code{no-strict-align} can be specified. The behavior is same as for the
4232 command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
4234 @item omit-leaf-frame-pointer
4235 @cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
4236 Indicates that the frame pointer should be omitted for a leaf function call.
4237 To keep the frame pointer, the inverse attribute
4238 @code{no-omit-leaf-frame-pointer} can be specified. These attributes have
4239 the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
4240 and @option{-mno-omit-leaf-frame-pointer}.
4243 @cindex @code{tls-dialect=} function attribute, AArch64
4244 Specifies the TLS dialect to use for this function. The behavior and
4245 permissible arguments are the same as for the command-line option
4246 @option{-mtls-dialect=}.
4249 @cindex @code{arch=} function attribute, AArch64
4250 Specifies the architecture version and architectural extensions to use
4251 for this function. The behavior and permissible arguments are the same as
4252 for the @option{-march=} command-line option.
4255 @cindex @code{tune=} function attribute, AArch64
4256 Specifies the core for which to tune the performance of this function.
4257 The behavior and permissible arguments are the same as for the @option{-mtune=}
4258 command-line option.
4261 @cindex @code{cpu=} function attribute, AArch64
4262 Specifies the core for which to tune the performance of this function and also
4263 whose architectural features to use. The behavior and valid arguments are the
4264 same as for the @option{-mcpu=} command-line option.
4266 @item sign-return-address
4267 @cindex @code{sign-return-address} function attribute, AArch64
4268 Select the function scope on which return address signing will be applied. The
4269 behavior and permissible arguments are the same as for the command-line option
4270 @option{-msign-return-address=}. The default value is @code{none}. This
4271 attribute is deprecated. The @code{branch-protection} attribute should
4274 @item branch-protection
4275 @cindex @code{branch-protection} function attribute, AArch64
4276 Select the function scope on which branch protection will be applied. The
4277 behavior and permissible arguments are the same as for the command-line option
4278 @option{-mbranch-protection=}. The default value is @code{none}.
4280 @item outline-atomics
4281 @cindex @code{outline-atomics} function attribute, AArch64
4282 Enable or disable calls to out-of-line helpers to implement atomic operations.
4283 This corresponds to the behavior of the command line options
4284 @option{-moutline-atomics} and @option{-mno-outline-atomics}.
4288 The above target attributes can be specified as follows:
4291 __attribute__((target("@var{attr-string}")))
4299 where @code{@var{attr-string}} is one of the attribute strings specified above.
4301 Additionally, the architectural extension string may be specified on its
4302 own. This can be used to turn on and off particular architectural extensions
4303 without having to specify a particular architecture version or core. Example:
4306 __attribute__((target("+crc+nocrypto")))
4314 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
4315 extension and disables the @code{crypto} extension for the function @code{foo}
4316 without modifying an existing @option{-march=} or @option{-mcpu} option.
4318 Multiple target function attributes can be specified by separating them with
4319 a comma. For example:
4321 __attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
4329 is valid and compiles function @code{foo} for ARMv8-A with @code{crc}
4330 and @code{crypto} extensions and tunes it for @code{cortex-a53}.
4332 @subsubsection Inlining rules
4333 Specifying target attributes on individual functions or performing link-time
4334 optimization across translation units compiled with different target options
4335 can affect function inlining rules:
4337 In particular, a caller function can inline a callee function only if the
4338 architectural features available to the callee are a subset of the features
4339 available to the caller.
4340 For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
4341 or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
4342 can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
4343 because the all the architectural features that function @code{bar} requires
4344 are available to function @code{foo}. Conversely, function @code{bar} cannot
4345 inline function @code{foo}.
4347 Additionally inlining a function compiled with @option{-mstrict-align} into a
4348 function compiled without @code{-mstrict-align} is not allowed.
4349 However, inlining a function compiled without @option{-mstrict-align} into a
4350 function compiled with @option{-mstrict-align} is allowed.
4352 Note that CPU tuning options and attributes such as the @option{-mcpu=},
4353 @option{-mtune=} do not inhibit inlining unless the CPU specified by the
4354 @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
4355 architectural feature rules specified above.
4357 @node AMD GCN Function Attributes
4358 @subsection AMD GCN Function Attributes
4360 These function attributes are supported by the AMD GCN back end:
4363 @item amdgpu_hsa_kernel
4364 @cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN
4365 This attribute indicates that the corresponding function should be compiled as
4366 a kernel function, that is an entry point that can be invoked from the host
4367 via the HSA runtime library. By default functions are only callable only from
4368 other GCN functions.
4370 This attribute is implicitly applied to any function named @code{main}, using
4373 Kernel functions may return an integer value, which will be written to a
4374 conventional place within the HSA "kernargs" region.
4376 The attribute parameters configure what values are passed into the kernel
4377 function by the GPU drivers, via the initial register state. Some values are
4378 used by the compiler, and therefore forced on. Enabling other options may
4379 break assumptions in the compiler and/or run-time libraries.
4382 @item private_segment_buffer
4383 Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to
4387 Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the
4391 Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address
4394 @item kernarg_segment_ptr
4395 Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to
4396 locate the kernel arguments, "kernargs").
4399 Set @code{enable_sgpr_dispatch_id} flag.
4401 @item flat_scratch_init
4402 Set @code{enable_sgpr_flat_scratch_init} flag.
4404 @item private_segment_size
4405 Set @code{enable_sgpr_private_segment_size} flag.
4407 @item grid_workgroup_count_X
4408 Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to
4409 use OpenACC/OpenMP).
4411 @item grid_workgroup_count_Y
4412 Set @code{enable_sgpr_grid_workgroup_count_y} flag.
4414 @item grid_workgroup_count_Z
4415 Set @code{enable_sgpr_grid_workgroup_count_z} flag.
4417 @item workgroup_id_X
4418 Set @code{enable_sgpr_workgroup_id_x} flag.
4420 @item workgroup_id_Y
4421 Set @code{enable_sgpr_workgroup_id_y} flag.
4423 @item workgroup_id_Z
4424 Set @code{enable_sgpr_workgroup_id_z} flag.
4426 @item workgroup_info
4427 Set @code{enable_sgpr_workgroup_info} flag.
4429 @item private_segment_wave_offset
4430 Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on
4431 (required to locate the stack).
4433 @item work_item_id_X
4434 Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled).
4436 @item work_item_id_Y
4437 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable
4440 @item work_item_id_Z
4441 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use
4447 @node ARC Function Attributes
4448 @subsection ARC Function Attributes
4450 These function attributes are supported by the ARC back end:
4454 @cindex @code{interrupt} function attribute, ARC
4455 Use this attribute to indicate
4456 that the specified function is an interrupt handler. The compiler generates
4457 function entry and exit sequences suitable for use in an interrupt handler
4458 when this attribute is present.
4460 On the ARC, you must specify the kind of interrupt to be handled
4461 in a parameter to the interrupt attribute like this:
4464 void f () __attribute__ ((interrupt ("ilink1")));
4467 Permissible values for this parameter are: @w{@code{ilink1}} and
4468 @w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and
4469 @w{@code{firq}} for ARCv2 architecture.
4474 @cindex @code{long_call} function attribute, ARC
4475 @cindex @code{medium_call} function attribute, ARC
4476 @cindex @code{short_call} function attribute, ARC
4477 @cindex indirect calls, ARC
4478 These attributes specify how a particular function is called.
4479 These attributes override the
4480 @option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
4481 command-line switches and @code{#pragma long_calls} settings.
4483 For ARC, a function marked with the @code{long_call} attribute is
4484 always called using register-indirect jump-and-link instructions,
4485 thereby enabling the called function to be placed anywhere within the
4486 32-bit address space. A function marked with the @code{medium_call}
4487 attribute will always be close enough to be called with an unconditional
4488 branch-and-link instruction, which has a 25-bit offset from
4489 the call site. A function marked with the @code{short_call}
4490 attribute will always be close enough to be called with a conditional
4491 branch-and-link instruction, which has a 21-bit offset from
4495 @cindex @code{jli_always} function attribute, ARC
4496 Forces a particular function to be called using @code{jli}
4497 instruction. The @code{jli} instruction makes use of a table stored
4498 into @code{.jlitab} section, which holds the location of the functions
4499 which are addressed using this instruction.
4502 @cindex @code{jli_fixed} function attribute, ARC
4503 Identical like the above one, but the location of the function in the
4504 @code{jli} table is known and given as an attribute parameter.
4507 @cindex @code{secure_call} function attribute, ARC
4508 This attribute allows one to mark secure-code functions that are
4509 callable from normal mode. The location of the secure call function
4510 into the @code{sjli} table needs to be passed as argument.
4513 @cindex @code{naked} function attribute, ARC
4514 This attribute allows the compiler to construct the requisite function
4515 declaration, while allowing the body of the function to be assembly
4516 code. The specified function will not have prologue/epilogue
4517 sequences generated by the compiler. Only basic @code{asm} statements
4518 can safely be included in naked functions (@pxref{Basic Asm}). While
4519 using extended @code{asm} or a mixture of basic @code{asm} and C code
4520 may appear to work, they cannot be depended upon to work reliably and
4525 @node ARM Function Attributes
4526 @subsection ARM Function Attributes
4528 These function attributes are supported for ARM targets:
4532 @item general-regs-only
4533 @cindex @code{general-regs-only} function attribute, ARM
4534 Indicates that no floating-point or Advanced SIMD registers should be
4535 used when generating code for this function. If the function explicitly
4536 uses floating-point code, then the compiler gives an error. This is
4537 the same behavior as that of the command-line option
4538 @option{-mgeneral-regs-only}.
4541 @cindex @code{interrupt} function attribute, ARM
4542 Use this attribute to indicate
4543 that the specified function is an interrupt handler. The compiler generates
4544 function entry and exit sequences suitable for use in an interrupt handler
4545 when this attribute is present.
4547 You can specify the kind of interrupt to be handled by
4548 adding an optional parameter to the interrupt attribute like this:
4551 void f () __attribute__ ((interrupt ("IRQ")));
4555 Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
4556 @code{SWI}, @code{ABORT} and @code{UNDEF}.
4558 On ARMv7-M the interrupt type is ignored, and the attribute means the function
4559 may be called with a word-aligned stack pointer.
4562 @cindex @code{isr} function attribute, ARM
4563 Use this attribute on ARM to write Interrupt Service Routines. This is an
4564 alias to the @code{interrupt} attribute above.
4568 @cindex @code{long_call} function attribute, ARM
4569 @cindex @code{short_call} function attribute, ARM
4570 @cindex indirect calls, ARM
4571 These attributes specify how a particular function is called.
4572 These attributes override the
4573 @option{-mlong-calls} (@pxref{ARM Options})
4574 command-line switch and @code{#pragma long_calls} settings. For ARM, the
4575 @code{long_call} attribute indicates that the function might be far
4576 away from the call site and require a different (more expensive)
4577 calling sequence. The @code{short_call} attribute always places
4578 the offset to the function from the call site into the @samp{BL}
4579 instruction directly.
4582 @cindex @code{naked} function attribute, ARM
4583 This attribute allows the compiler to construct the
4584 requisite function declaration, while allowing the body of the
4585 function to be assembly code. The specified function will not have
4586 prologue/epilogue sequences generated by the compiler. Only basic
4587 @code{asm} statements can safely be included in naked functions
4588 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4589 basic @code{asm} and C code may appear to work, they cannot be
4590 depended upon to work reliably and are not supported.
4593 @cindex @code{pcs} function attribute, ARM
4595 The @code{pcs} attribute can be used to control the calling convention
4596 used for a function on ARM. The attribute takes an argument that specifies
4597 the calling convention to use.
4599 When compiling using the AAPCS ABI (or a variant of it) then valid
4600 values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
4601 order to use a variant other than @code{"aapcs"} then the compiler must
4602 be permitted to use the appropriate co-processor registers (i.e., the
4603 VFP registers must be available in order to use @code{"aapcs-vfp"}).
4607 /* Argument passed in r0, and result returned in r0+r1. */
4608 double f2d (float) __attribute__((pcs("aapcs")));
4611 Variadic functions always use the @code{"aapcs"} calling convention and
4612 the compiler rejects attempts to specify an alternative.
4614 @item target (@var{options})
4615 @cindex @code{target} function attribute
4616 As discussed in @ref{Common Function Attributes}, this attribute
4617 allows specification of target-specific compilation options.
4619 On ARM, the following options are allowed:
4623 @cindex @code{target("thumb")} function attribute, ARM
4624 Force code generation in the Thumb (T16/T32) ISA, depending on the
4628 @cindex @code{target("arm")} function attribute, ARM
4629 Force code generation in the ARM (A32) ISA.
4631 Functions from different modes can be inlined in the caller's mode.
4634 @cindex @code{target("fpu=")} function attribute, ARM
4635 Specifies the fpu for which to tune the performance of this function.
4636 The behavior and permissible arguments are the same as for the @option{-mfpu=}
4637 command-line option.
4640 @cindex @code{arch=} function attribute, ARM
4641 Specifies the architecture version and architectural extensions to use
4642 for this function. The behavior and permissible arguments are the same as
4643 for the @option{-march=} command-line option.
4645 The above target attributes can be specified as follows:
4648 __attribute__((target("arch=armv8-a+crc")))
4656 Additionally, the architectural extension string may be specified on its
4657 own. This can be used to turn on and off particular architectural extensions
4658 without having to specify a particular architecture version or core. Example:
4661 __attribute__((target("+crc+nocrypto")))
4669 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
4670 extension and disables the @code{crypto} extension for the function @code{foo}
4671 without modifying an existing @option{-march=} or @option{-mcpu} option.
4677 @node AVR Function Attributes
4678 @subsection AVR Function Attributes
4680 These function attributes are supported by the AVR back end:
4684 @cindex @code{interrupt} function attribute, AVR
4685 Use this attribute to indicate
4686 that the specified function is an interrupt handler. The compiler generates
4687 function entry and exit sequences suitable for use in an interrupt handler
4688 when this attribute is present.
4690 On the AVR, the hardware globally disables interrupts when an
4691 interrupt is executed. The first instruction of an interrupt handler
4692 declared with this attribute is a @code{SEI} instruction to
4693 re-enable interrupts. See also the @code{signal} function attribute
4694 that does not insert a @code{SEI} instruction. If both @code{signal} and
4695 @code{interrupt} are specified for the same function, @code{signal}
4696 is silently ignored.
4699 @cindex @code{naked} function attribute, AVR
4700 This attribute allows the compiler to construct the
4701 requisite function declaration, while allowing the body of the
4702 function to be assembly code. The specified function will not have
4703 prologue/epilogue sequences generated by the compiler. Only basic
4704 @code{asm} statements can safely be included in naked functions
4705 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4706 basic @code{asm} and C code may appear to work, they cannot be
4707 depended upon to work reliably and are not supported.
4710 @cindex @code{no_gccisr} function attribute, AVR
4711 Do not use @code{__gcc_isr} pseudo instructions in a function with
4712 the @code{interrupt} or @code{signal} attribute aka. interrupt
4713 service routine (ISR).
4714 Use this attribute if the preamble of the ISR prologue should always read
4718 in __tmp_reg__, __SREG__
4722 and accordingly for the postamble of the epilogue --- no matter whether
4723 the mentioned registers are actually used in the ISR or not.
4724 Situations where you might want to use this attribute include:
4727 Code that (effectively) clobbers bits of @code{SREG} other than the
4728 @code{I}-flag by writing to the memory location of @code{SREG}.
4730 Code that uses inline assembler to jump to a different function which
4731 expects (parts of) the prologue code as outlined above to be present.
4733 To disable @code{__gcc_isr} generation for the whole compilation unit,
4734 there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}.
4738 @cindex @code{OS_main} function attribute, AVR
4739 @cindex @code{OS_task} function attribute, AVR
4740 On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
4741 do not save/restore any call-saved register in their prologue/epilogue.
4743 The @code{OS_main} attribute can be used when there @emph{is
4744 guarantee} that interrupts are disabled at the time when the function
4745 is entered. This saves resources when the stack pointer has to be
4746 changed to set up a frame for local variables.
4748 The @code{OS_task} attribute can be used when there is @emph{no
4749 guarantee} that interrupts are disabled at that time when the function
4750 is entered like for, e@.g@. task functions in a multi-threading operating
4751 system. In that case, changing the stack pointer register is
4752 guarded by save/clear/restore of the global interrupt enable flag.
4754 The differences to the @code{naked} function attribute are:
4756 @item @code{naked} functions do not have a return instruction whereas
4757 @code{OS_main} and @code{OS_task} functions have a @code{RET} or
4758 @code{RETI} return instruction.
4759 @item @code{naked} functions do not set up a frame for local variables
4760 or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
4765 @cindex @code{signal} function attribute, AVR
4766 Use this attribute on the AVR to indicate that the specified
4767 function is an interrupt handler. The compiler generates function
4768 entry and exit sequences suitable for use in an interrupt handler when this
4769 attribute is present.
4771 See also the @code{interrupt} function attribute.
4773 The AVR hardware globally disables interrupts when an interrupt is executed.
4774 Interrupt handler functions defined with the @code{signal} attribute
4775 do not re-enable interrupts. It is save to enable interrupts in a
4776 @code{signal} handler. This ``save'' only applies to the code
4777 generated by the compiler and not to the IRQ layout of the
4778 application which is responsibility of the application.
4780 If both @code{signal} and @code{interrupt} are specified for the same
4781 function, @code{signal} is silently ignored.
4784 @node Blackfin Function Attributes
4785 @subsection Blackfin Function Attributes
4787 These function attributes are supported by the Blackfin back end:
4791 @item exception_handler
4792 @cindex @code{exception_handler} function attribute
4793 @cindex exception handler functions, Blackfin
4794 Use this attribute on the Blackfin to indicate that the specified function
4795 is an exception handler. The compiler generates function entry and
4796 exit sequences suitable for use in an exception handler when this
4797 attribute is present.
4799 @item interrupt_handler
4800 @cindex @code{interrupt_handler} function attribute, Blackfin
4801 Use this attribute to
4802 indicate that the specified function is an interrupt handler. The compiler
4803 generates function entry and exit sequences suitable for use in an
4804 interrupt handler when this attribute is present.
4807 @cindex @code{kspisusp} function attribute, Blackfin
4808 @cindex User stack pointer in interrupts on the Blackfin
4809 When used together with @code{interrupt_handler}, @code{exception_handler}
4810 or @code{nmi_handler}, code is generated to load the stack pointer
4811 from the USP register in the function prologue.
4814 @cindex @code{l1_text} function attribute, Blackfin
4815 This attribute specifies a function to be placed into L1 Instruction
4816 SRAM@. The function is put into a specific section named @code{.l1.text}.
4817 With @option{-mfdpic}, function calls with a such function as the callee
4818 or caller uses inlined PLT.
4821 @cindex @code{l2} function attribute, Blackfin
4822 This attribute specifies a function to be placed into L2
4823 SRAM. The function is put into a specific section named
4824 @code{.l2.text}. With @option{-mfdpic}, callers of such functions use
4829 @cindex indirect calls, Blackfin
4830 @cindex @code{longcall} function attribute, Blackfin
4831 @cindex @code{shortcall} function attribute, Blackfin
4832 The @code{longcall} attribute
4833 indicates that the function might be far away from the call site and
4834 require a different (more expensive) calling sequence. The
4835 @code{shortcall} attribute indicates that the function is always close
4836 enough for the shorter calling sequence to be used. These attributes
4837 override the @option{-mlongcall} switch.
4840 @cindex @code{nesting} function attribute, Blackfin
4841 @cindex Allow nesting in an interrupt handler on the Blackfin processor
4842 Use this attribute together with @code{interrupt_handler},
4843 @code{exception_handler} or @code{nmi_handler} to indicate that the function
4844 entry code should enable nested interrupts or exceptions.
4847 @cindex @code{nmi_handler} function attribute, Blackfin
4848 @cindex NMI handler functions on the Blackfin processor
4849 Use this attribute on the Blackfin to indicate that the specified function
4850 is an NMI handler. The compiler generates function entry and
4851 exit sequences suitable for use in an NMI handler when this
4852 attribute is present.
4855 @cindex @code{saveall} function attribute, Blackfin
4856 @cindex save all registers on the Blackfin
4857 Use this attribute to indicate that
4858 all registers except the stack pointer should be saved in the prologue
4859 regardless of whether they are used or not.
4862 @node BPF Function Attributes
4863 @subsection BPF Function Attributes
4865 These function attributes are supported by the BPF back end:
4869 @cindex @code{kernel helper}, function attribute, BPF
4870 use this attribute to indicate the specified function declaration is a
4871 kernel helper. The helper function is passed as an argument to the
4875 int bpf_probe_read (void *dst, int size, const void *unsafe_ptr)
4876 __attribute__ ((kernel_helper (4)));
4880 @node CR16 Function Attributes
4881 @subsection CR16 Function Attributes
4883 These function attributes are supported by the CR16 back end:
4887 @cindex @code{interrupt} function attribute, CR16
4888 Use this attribute to indicate
4889 that the specified function is an interrupt handler. The compiler generates
4890 function entry and exit sequences suitable for use in an interrupt handler
4891 when this attribute is present.
4894 @node C-SKY Function Attributes
4895 @subsection C-SKY Function Attributes
4897 These function attributes are supported by the C-SKY back end:
4902 @cindex @code{interrupt} function attribute, C-SKY
4903 @cindex @code{isr} function attribute, C-SKY
4904 Use these attributes to indicate that the specified function
4905 is an interrupt handler.
4906 The compiler generates function entry and exit sequences suitable for
4907 use in an interrupt handler when either of these attributes are present.
4909 Use of these options requires the @option{-mistack} command-line option
4910 to enable support for the necessary interrupt stack instructions. They
4911 are ignored with a warning otherwise. @xref{C-SKY Options}.
4914 @cindex @code{naked} function attribute, C-SKY
4915 This attribute allows the compiler to construct the
4916 requisite function declaration, while allowing the body of the
4917 function to be assembly code. The specified function will not have
4918 prologue/epilogue sequences generated by the compiler. Only basic
4919 @code{asm} statements can safely be included in naked functions
4920 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4921 basic @code{asm} and C code may appear to work, they cannot be
4922 depended upon to work reliably and are not supported.
4926 @node Epiphany Function Attributes
4927 @subsection Epiphany Function Attributes
4929 These function attributes are supported by the Epiphany back end:
4933 @cindex @code{disinterrupt} function attribute, Epiphany
4934 This attribute causes the compiler to emit
4935 instructions to disable interrupts for the duration of the given
4938 @item forwarder_section
4939 @cindex @code{forwarder_section} function attribute, Epiphany
4940 This attribute modifies the behavior of an interrupt handler.
4941 The interrupt handler may be in external memory which cannot be
4942 reached by a branch instruction, so generate a local memory trampoline
4943 to transfer control. The single parameter identifies the section where
4944 the trampoline is placed.
4947 @cindex @code{interrupt} function attribute, Epiphany
4948 Use this attribute to indicate
4949 that the specified function is an interrupt handler. The compiler generates
4950 function entry and exit sequences suitable for use in an interrupt handler
4951 when this attribute is present. It may also generate
4952 a special section with code to initialize the interrupt vector table.
4954 On Epiphany targets one or more optional parameters can be added like this:
4957 void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
4960 Permissible values for these parameters are: @w{@code{reset}},
4961 @w{@code{software_exception}}, @w{@code{page_miss}},
4962 @w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
4963 @w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
4964 Multiple parameters indicate that multiple entries in the interrupt
4965 vector table should be initialized for this function, i.e.@: for each
4966 parameter @w{@var{name}}, a jump to the function is emitted in
4967 the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
4968 entirely, in which case no interrupt vector table entry is provided.
4970 Note that interrupts are enabled inside the function
4971 unless the @code{disinterrupt} attribute is also specified.
4973 The following examples are all valid uses of these attributes on
4976 void __attribute__ ((interrupt)) universal_handler ();
4977 void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
4978 void __attribute__ ((interrupt ("dma0, dma1")))
4979 universal_dma_handler ();
4980 void __attribute__ ((interrupt ("timer0"), disinterrupt))
4981 fast_timer_handler ();
4982 void __attribute__ ((interrupt ("dma0, dma1"),
4983 forwarder_section ("tramp")))
4984 external_dma_handler ();
4989 @cindex @code{long_call} function attribute, Epiphany
4990 @cindex @code{short_call} function attribute, Epiphany
4991 @cindex indirect calls, Epiphany
4992 These attributes specify how a particular function is called.
4993 These attributes override the
4994 @option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
4995 command-line switch and @code{#pragma long_calls} settings.
4999 @node H8/300 Function Attributes
5000 @subsection H8/300 Function Attributes
5002 These function attributes are available for H8/300 targets:
5005 @item function_vector
5006 @cindex @code{function_vector} function attribute, H8/300
5007 Use this attribute on the H8/300, H8/300H, and H8S to indicate
5008 that the specified function should be called through the function vector.
5009 Calling a function through the function vector reduces code size; however,
5010 the function vector has a limited size (maximum 128 entries on the H8/300
5011 and 64 entries on the H8/300H and H8S)
5012 and shares space with the interrupt vector.
5014 @item interrupt_handler
5015 @cindex @code{interrupt_handler} function attribute, H8/300
5016 Use this attribute on the H8/300, H8/300H, and H8S to
5017 indicate that the specified function is an interrupt handler. The compiler
5018 generates function entry and exit sequences suitable for use in an
5019 interrupt handler when this attribute is present.
5022 @cindex @code{saveall} function attribute, H8/300
5023 @cindex save all registers on the H8/300, H8/300H, and H8S
5024 Use this attribute on the H8/300, H8/300H, and H8S to indicate that
5025 all registers except the stack pointer should be saved in the prologue
5026 regardless of whether they are used or not.
5029 @node IA-64 Function Attributes
5030 @subsection IA-64 Function Attributes
5032 These function attributes are supported on IA-64 targets:
5035 @item syscall_linkage
5036 @cindex @code{syscall_linkage} function attribute, IA-64
5037 This attribute is used to modify the IA-64 calling convention by marking
5038 all input registers as live at all function exits. This makes it possible
5039 to restart a system call after an interrupt without having to save/restore
5040 the input registers. This also prevents kernel data from leaking into
5044 @cindex @code{version_id} function attribute, IA-64
5045 This IA-64 HP-UX attribute, attached to a global variable or function, renames a
5046 symbol to contain a version string, thus allowing for function level
5047 versioning. HP-UX system header files may use function level versioning
5048 for some system calls.
5051 extern int foo () __attribute__((version_id ("20040821")));
5055 Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
5058 @node M32C Function Attributes
5059 @subsection M32C Function Attributes
5061 These function attributes are supported by the M32C back end:
5065 @cindex @code{bank_switch} function attribute, M32C
5066 When added to an interrupt handler with the M32C port, causes the
5067 prologue and epilogue to use bank switching to preserve the registers
5068 rather than saving them on the stack.
5070 @item fast_interrupt
5071 @cindex @code{fast_interrupt} function attribute, M32C
5072 Use this attribute on the M32C port to indicate that the specified
5073 function is a fast interrupt handler. This is just like the
5074 @code{interrupt} attribute, except that @code{freit} is used to return
5075 instead of @code{reit}.
5077 @item function_vector
5078 @cindex @code{function_vector} function attribute, M16C/M32C
5079 On M16C/M32C targets, the @code{function_vector} attribute declares a
5080 special page subroutine call function. Use of this attribute reduces
5081 the code size by 2 bytes for each call generated to the
5082 subroutine. The argument to the attribute is the vector number entry
5083 from the special page vector table which contains the 16 low-order
5084 bits of the subroutine's entry address. Each vector table has special
5085 page number (18 to 255) that is used in @code{jsrs} instructions.
5086 Jump addresses of the routines are generated by adding 0x0F0000 (in
5087 case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
5088 2-byte addresses set in the vector table. Therefore you need to ensure
5089 that all the special page vector routines should get mapped within the
5090 address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
5093 In the following example 2 bytes are saved for each call to
5094 function @code{foo}.
5097 void foo (void) __attribute__((function_vector(0x18)));
5108 If functions are defined in one file and are called in another file,
5109 then be sure to write this declaration in both files.
5111 This attribute is ignored for R8C target.
5114 @cindex @code{interrupt} function attribute, M32C
5115 Use this attribute to indicate
5116 that the specified function is an interrupt handler. The compiler generates
5117 function entry and exit sequences suitable for use in an interrupt handler
5118 when this attribute is present.
5121 @node M32R/D Function Attributes
5122 @subsection M32R/D Function Attributes
5124 These function attributes are supported by the M32R/D back end:
5128 @cindex @code{interrupt} function attribute, M32R/D
5129 Use this attribute to indicate
5130 that the specified function is an interrupt handler. The compiler generates
5131 function entry and exit sequences suitable for use in an interrupt handler
5132 when this attribute is present.
5134 @item model (@var{model-name})
5135 @cindex @code{model} function attribute, M32R/D
5136 @cindex function addressability on the M32R/D
5138 On the M32R/D, use this attribute to set the addressability of an
5139 object, and of the code generated for a function. The identifier
5140 @var{model-name} is one of @code{small}, @code{medium}, or
5141 @code{large}, representing each of the code models.
5143 Small model objects live in the lower 16MB of memory (so that their
5144 addresses can be loaded with the @code{ld24} instruction), and are
5145 callable with the @code{bl} instruction.
5147 Medium model objects may live anywhere in the 32-bit address space (the
5148 compiler generates @code{seth/add3} instructions to load their addresses),
5149 and are callable with the @code{bl} instruction.
5151 Large model objects may live anywhere in the 32-bit address space (the
5152 compiler generates @code{seth/add3} instructions to load their addresses),
5153 and may not be reachable with the @code{bl} instruction (the compiler
5154 generates the much slower @code{seth/add3/jl} instruction sequence).
5157 @node m68k Function Attributes
5158 @subsection m68k Function Attributes
5160 These function attributes are supported by the m68k back end:
5164 @itemx interrupt_handler
5165 @cindex @code{interrupt} function attribute, m68k
5166 @cindex @code{interrupt_handler} function attribute, m68k
5167 Use this attribute to
5168 indicate that the specified function is an interrupt handler. The compiler
5169 generates function entry and exit sequences suitable for use in an
5170 interrupt handler when this attribute is present. Either name may be used.
5172 @item interrupt_thread
5173 @cindex @code{interrupt_thread} function attribute, fido
5174 Use this attribute on fido, a subarchitecture of the m68k, to indicate
5175 that the specified function is an interrupt handler that is designed
5176 to run as a thread. The compiler omits generate prologue/epilogue
5177 sequences and replaces the return instruction with a @code{sleep}
5178 instruction. This attribute is available only on fido.
5181 @node MCORE Function Attributes
5182 @subsection MCORE Function Attributes
5184 These function attributes are supported by the MCORE back end:
5188 @cindex @code{naked} function attribute, MCORE
5189 This attribute allows the compiler to construct the
5190 requisite function declaration, while allowing the body of the
5191 function to be assembly code. The specified function will not have
5192 prologue/epilogue sequences generated by the compiler. Only basic
5193 @code{asm} statements can safely be included in naked functions
5194 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5195 basic @code{asm} and C code may appear to work, they cannot be
5196 depended upon to work reliably and are not supported.
5199 @node MeP Function Attributes
5200 @subsection MeP Function Attributes
5202 These function attributes are supported by the MeP back end:
5206 @cindex @code{disinterrupt} function attribute, MeP
5207 On MeP targets, this attribute causes the compiler to emit
5208 instructions to disable interrupts for the duration of the given
5212 @cindex @code{interrupt} function attribute, MeP
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 @cindex @code{near} function attribute, MeP
5220 This attribute causes the compiler to assume the called
5221 function is close enough to use the normal calling convention,
5222 overriding the @option{-mtf} command-line option.
5225 @cindex @code{far} function attribute, MeP
5226 On MeP targets this causes the compiler to use a calling convention
5227 that assumes the called function is too far away for the built-in
5231 @cindex @code{vliw} function attribute, MeP
5232 The @code{vliw} attribute tells the compiler to emit
5233 instructions in VLIW mode instead of core mode. Note that this
5234 attribute is not allowed unless a VLIW coprocessor has been configured
5235 and enabled through command-line options.
5238 @node MicroBlaze Function Attributes
5239 @subsection MicroBlaze Function Attributes
5241 These function attributes are supported on MicroBlaze targets:
5244 @item save_volatiles
5245 @cindex @code{save_volatiles} function attribute, MicroBlaze
5246 Use this attribute to indicate that the function is
5247 an interrupt handler. All volatile registers (in addition to non-volatile
5248 registers) are saved in the function prologue. If the function is a leaf
5249 function, only volatiles used by the function are saved. A normal function
5250 return is generated instead of a return from interrupt.
5253 @cindex @code{break_handler} function attribute, MicroBlaze
5254 @cindex break handler functions
5255 Use this attribute to indicate that
5256 the specified function is a break handler. The compiler generates function
5257 entry and exit sequences suitable for use in an break handler when this
5258 attribute is present. The return from @code{break_handler} is done through
5259 the @code{rtbd} instead of @code{rtsd}.
5262 void f () __attribute__ ((break_handler));
5265 @item interrupt_handler
5266 @itemx fast_interrupt
5267 @cindex @code{interrupt_handler} function attribute, MicroBlaze
5268 @cindex @code{fast_interrupt} function attribute, MicroBlaze
5269 These attributes indicate that the specified function is an interrupt
5270 handler. Use the @code{fast_interrupt} attribute to indicate handlers
5271 used in low-latency interrupt mode, and @code{interrupt_handler} for
5272 interrupts that do not use low-latency handlers. In both cases, GCC
5273 emits appropriate prologue code and generates a return from the handler
5274 using @code{rtid} instead of @code{rtsd}.
5277 @node Microsoft Windows Function Attributes
5278 @subsection Microsoft Windows Function Attributes
5280 The following attributes are available on Microsoft Windows and Symbian OS
5285 @cindex @code{dllexport} function attribute
5286 @cindex @code{__declspec(dllexport)}
5287 On Microsoft Windows targets and Symbian OS targets the
5288 @code{dllexport} attribute causes the compiler to provide a global
5289 pointer to a pointer in a DLL, so that it can be referenced with the
5290 @code{dllimport} attribute. On Microsoft Windows targets, the pointer
5291 name is formed by combining @code{_imp__} and the function or variable
5294 You can use @code{__declspec(dllexport)} as a synonym for
5295 @code{__attribute__ ((dllexport))} for compatibility with other
5298 On systems that support the @code{visibility} attribute, this
5299 attribute also implies ``default'' visibility. It is an error to
5300 explicitly specify any other visibility.
5302 GCC's default behavior is to emit all inline functions with the
5303 @code{dllexport} attribute. Since this can cause object file-size bloat,
5304 you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
5305 ignore the attribute for inlined functions unless the
5306 @option{-fkeep-inline-functions} flag is used instead.
5308 The attribute is ignored for undefined symbols.
5310 When applied to C++ classes, the attribute marks defined non-inlined
5311 member functions and static data members as exports. Static consts
5312 initialized in-class are not marked unless they are also defined
5315 For Microsoft Windows targets there are alternative methods for
5316 including the symbol in the DLL's export table such as using a
5317 @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
5318 the @option{--export-all} linker flag.
5321 @cindex @code{dllimport} function attribute
5322 @cindex @code{__declspec(dllimport)}
5323 On Microsoft Windows and Symbian OS targets, the @code{dllimport}
5324 attribute causes the compiler to reference a function or variable via
5325 a global pointer to a pointer that is set up by the DLL exporting the
5326 symbol. The attribute implies @code{extern}. On Microsoft Windows
5327 targets, the pointer name is formed by combining @code{_imp__} and the
5328 function or variable name.
5330 You can use @code{__declspec(dllimport)} as a synonym for
5331 @code{__attribute__ ((dllimport))} for compatibility with other
5334 On systems that support the @code{visibility} attribute, this
5335 attribute also implies ``default'' visibility. It is an error to
5336 explicitly specify any other visibility.
5338 Currently, the attribute is ignored for inlined functions. If the
5339 attribute is applied to a symbol @emph{definition}, an error is reported.
5340 If a symbol previously declared @code{dllimport} is later defined, the
5341 attribute is ignored in subsequent references, and a warning is emitted.
5342 The attribute is also overridden by a subsequent declaration as
5345 When applied to C++ classes, the attribute marks non-inlined
5346 member functions and static data members as imports. However, the
5347 attribute is ignored for virtual methods to allow creation of vtables
5350 On the SH Symbian OS target the @code{dllimport} attribute also has
5351 another affect---it can cause the vtable and run-time type information
5352 for a class to be exported. This happens when the class has a
5353 dllimported constructor or a non-inline, non-pure virtual function
5354 and, for either of those two conditions, the class also has an inline
5355 constructor or destructor and has a key function that is defined in
5356 the current translation unit.
5358 For Microsoft Windows targets the use of the @code{dllimport}
5359 attribute on functions is not necessary, but provides a small
5360 performance benefit by eliminating a thunk in the DLL@. The use of the
5361 @code{dllimport} attribute on imported variables can be avoided by passing the
5362 @option{--enable-auto-import} switch to the GNU linker. As with
5363 functions, using the attribute for a variable eliminates a thunk in
5366 One drawback to using this attribute is that a pointer to a
5367 @emph{variable} marked as @code{dllimport} cannot be used as a constant
5368 address. However, a pointer to a @emph{function} with the
5369 @code{dllimport} attribute can be used as a constant initializer; in
5370 this case, the address of a stub function in the import lib is
5371 referenced. On Microsoft Windows targets, the attribute can be disabled
5372 for functions by setting the @option{-mnop-fun-dllimport} flag.
5375 @node MIPS Function Attributes
5376 @subsection MIPS Function Attributes
5378 These function attributes are supported by the MIPS back end:
5382 @cindex @code{interrupt} function attribute, MIPS
5383 Use this attribute to indicate that the specified function is an interrupt
5384 handler. The compiler generates function entry and exit sequences suitable
5385 for use in an interrupt handler when this attribute is present.
5386 An optional argument is supported for the interrupt attribute which allows
5387 the interrupt mode to be described. By default GCC assumes the external
5388 interrupt controller (EIC) mode is in use, this can be explicitly set using
5389 @code{eic}. When interrupts are non-masked then the requested Interrupt
5390 Priority Level (IPL) is copied to the current IPL which has the effect of only
5391 enabling higher priority interrupts. To use vectored interrupt mode use
5392 the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
5393 the behavior of the non-masked interrupt support and GCC will arrange to mask
5394 all interrupts from sw0 up to and including the specified interrupt vector.
5396 You can use the following attributes to modify the behavior
5397 of an interrupt handler:
5399 @item use_shadow_register_set
5400 @cindex @code{use_shadow_register_set} function attribute, MIPS
5401 Assume that the handler uses a shadow register set, instead of
5402 the main general-purpose registers. An optional argument @code{intstack} is
5403 supported to indicate that the shadow register set contains a valid stack
5406 @item keep_interrupts_masked
5407 @cindex @code{keep_interrupts_masked} function attribute, MIPS
5408 Keep interrupts masked for the whole function. Without this attribute,
5409 GCC tries to reenable interrupts for as much of the function as it can.
5411 @item use_debug_exception_return
5412 @cindex @code{use_debug_exception_return} function attribute, MIPS
5413 Return using the @code{deret} instruction. Interrupt handlers that don't
5414 have this attribute return using @code{eret} instead.
5417 You can use any combination of these attributes, as shown below:
5419 void __attribute__ ((interrupt)) v0 ();
5420 void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
5421 void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
5422 void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
5423 void __attribute__ ((interrupt, use_shadow_register_set,
5424 keep_interrupts_masked)) v4 ();
5425 void __attribute__ ((interrupt, use_shadow_register_set,
5426 use_debug_exception_return)) v5 ();
5427 void __attribute__ ((interrupt, keep_interrupts_masked,
5428 use_debug_exception_return)) v6 ();
5429 void __attribute__ ((interrupt, use_shadow_register_set,
5430 keep_interrupts_masked,
5431 use_debug_exception_return)) v7 ();
5432 void __attribute__ ((interrupt("eic"))) v8 ();
5433 void __attribute__ ((interrupt("vector=hw3"))) v9 ();
5440 @cindex indirect calls, MIPS
5441 @cindex @code{long_call} function attribute, MIPS
5442 @cindex @code{short_call} function attribute, MIPS
5443 @cindex @code{near} function attribute, MIPS
5444 @cindex @code{far} function attribute, MIPS
5445 These attributes specify how a particular function is called on MIPS@.
5446 The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
5447 command-line switch. The @code{long_call} and @code{far} attributes are
5448 synonyms, and cause the compiler to always call
5449 the function by first loading its address into a register, and then using
5450 the contents of that register. The @code{short_call} and @code{near}
5451 attributes are synonyms, and have the opposite
5452 effect; they specify that non-PIC calls should be made using the more
5453 efficient @code{jal} instruction.
5457 @cindex @code{mips16} function attribute, MIPS
5458 @cindex @code{nomips16} function attribute, MIPS
5460 On MIPS targets, you can use the @code{mips16} and @code{nomips16}
5461 function attributes to locally select or turn off MIPS16 code generation.
5462 A function with the @code{mips16} attribute is emitted as MIPS16 code,
5463 while MIPS16 code generation is disabled for functions with the
5464 @code{nomips16} attribute. These attributes override the
5465 @option{-mips16} and @option{-mno-mips16} options on the command line
5466 (@pxref{MIPS Options}).
5468 When compiling files containing mixed MIPS16 and non-MIPS16 code, the
5469 preprocessor symbol @code{__mips16} reflects the setting on the command line,
5470 not that within individual functions. Mixed MIPS16 and non-MIPS16 code
5471 may interact badly with some GCC extensions such as @code{__builtin_apply}
5472 (@pxref{Constructing Calls}).
5474 @item micromips, MIPS
5475 @itemx nomicromips, MIPS
5476 @cindex @code{micromips} function attribute
5477 @cindex @code{nomicromips} function attribute
5479 On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
5480 function attributes to locally select or turn off microMIPS code generation.
5481 A function with the @code{micromips} attribute is emitted as microMIPS code,
5482 while microMIPS code generation is disabled for functions with the
5483 @code{nomicromips} attribute. These attributes override the
5484 @option{-mmicromips} and @option{-mno-micromips} options on the command line
5485 (@pxref{MIPS Options}).
5487 When compiling files containing mixed microMIPS and non-microMIPS code, the
5488 preprocessor symbol @code{__mips_micromips} reflects the setting on the
5490 not that within individual functions. Mixed microMIPS and non-microMIPS code
5491 may interact badly with some GCC extensions such as @code{__builtin_apply}
5492 (@pxref{Constructing Calls}).
5495 @cindex @code{nocompression} function attribute, MIPS
5496 On MIPS targets, you can use the @code{nocompression} function attribute
5497 to locally turn off MIPS16 and microMIPS code generation. This attribute
5498 overrides the @option{-mips16} and @option{-mmicromips} options on the
5499 command line (@pxref{MIPS Options}).
5502 @node MSP430 Function Attributes
5503 @subsection MSP430 Function Attributes
5505 These function attributes are supported by the MSP430 back end:
5509 @cindex @code{critical} function attribute, MSP430
5510 Critical functions disable interrupts upon entry and restore the
5511 previous interrupt state upon exit. Critical functions cannot also
5512 have the @code{naked}, @code{reentrant} or @code{interrupt} attributes.
5514 The MSP430 hardware ensures that interrupts are disabled on entry to
5515 @code{interrupt} functions, and restores the previous interrupt state
5516 on exit. The @code{critical} attribute is therefore redundant on
5517 @code{interrupt} functions.
5520 @cindex @code{interrupt} function attribute, MSP430
5521 Use this attribute to indicate
5522 that the specified function is an interrupt handler. The compiler generates
5523 function entry and exit sequences suitable for use in an interrupt handler
5524 when this attribute is present.
5526 You can provide an argument to the interrupt
5527 attribute which specifies a name or number. If the argument is a
5528 number it indicates the slot in the interrupt vector table (0 - 31) to
5529 which this handler should be assigned. If the argument is a name it
5530 is treated as a symbolic name for the vector slot. These names should
5531 match up with appropriate entries in the linker script. By default
5532 the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
5533 @code{reset} for vector 31 are recognized.
5536 @cindex @code{naked} function attribute, MSP430
5537 This attribute allows the compiler to construct the
5538 requisite function declaration, while allowing the body of the
5539 function to be assembly code. The specified function will not have
5540 prologue/epilogue sequences generated by the compiler. Only basic
5541 @code{asm} statements can safely be included in naked functions
5542 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5543 basic @code{asm} and C code may appear to work, they cannot be
5544 depended upon to work reliably and are not supported.
5547 @cindex @code{reentrant} function attribute, MSP430
5548 Reentrant functions disable interrupts upon entry and enable them
5549 upon exit. Reentrant functions cannot also have the @code{naked}
5550 or @code{critical} attributes. They can have the @code{interrupt}
5554 @cindex @code{wakeup} function attribute, MSP430
5555 This attribute only applies to interrupt functions. It is silently
5556 ignored if applied to a non-interrupt function. A wakeup interrupt
5557 function will rouse the processor from any low-power state that it
5558 might be in when the function exits.
5563 @cindex @code{lower} function attribute, MSP430
5564 @cindex @code{upper} function attribute, MSP430
5565 @cindex @code{either} function attribute, MSP430
5566 On the MSP430 target these attributes can be used to specify whether
5567 the function or variable should be placed into low memory, high
5568 memory, or the placement should be left to the linker to decide. The
5569 attributes are only significant if compiling for the MSP430X
5570 architecture in the large memory model.
5572 The attributes work in conjunction with a linker script that has been
5573 augmented to specify where to place sections with a @code{.lower} and
5574 a @code{.upper} prefix. So, for example, as well as placing the
5575 @code{.data} section, the script also specifies the placement of a
5576 @code{.lower.data} and a @code{.upper.data} section. The intention
5577 is that @code{lower} sections are placed into a small but easier to
5578 access memory region and the upper sections are placed into a larger, but
5579 slower to access, region.
5581 The @code{either} attribute is special. It tells the linker to place
5582 the object into the corresponding @code{lower} section if there is
5583 room for it. If there is insufficient room then the object is placed
5584 into the corresponding @code{upper} section instead. Note that the
5585 placement algorithm is not very sophisticated. It does not attempt to
5586 find an optimal packing of the @code{lower} sections. It just makes
5587 one pass over the objects and does the best that it can. Using the
5588 @option{-ffunction-sections} and @option{-fdata-sections} command-line
5589 options can help the packing, however, since they produce smaller,
5590 easier to pack regions.
5593 @node NDS32 Function Attributes
5594 @subsection NDS32 Function Attributes
5596 These function attributes are supported by the NDS32 back end:
5600 @cindex @code{exception} function attribute
5601 @cindex exception handler functions, NDS32
5602 Use this attribute on the NDS32 target to indicate that the specified function
5603 is an exception handler. The compiler will generate corresponding sections
5604 for use in an exception handler.
5607 @cindex @code{interrupt} function attribute, NDS32
5608 On NDS32 target, this attribute indicates that the specified function
5609 is an interrupt handler. The compiler generates corresponding sections
5610 for use in an interrupt handler. You can use the following attributes
5611 to modify the behavior:
5614 @cindex @code{nested} function attribute, NDS32
5615 This interrupt service routine is interruptible.
5617 @cindex @code{not_nested} function attribute, NDS32
5618 This interrupt service routine is not interruptible.
5620 @cindex @code{nested_ready} function attribute, NDS32
5621 This interrupt service routine is interruptible after @code{PSW.GIE}
5622 (global interrupt enable) is set. This allows interrupt service routine to
5623 finish some short critical code before enabling interrupts.
5625 @cindex @code{save_all} function attribute, NDS32
5626 The system will help save all registers into stack before entering
5629 @cindex @code{partial_save} function attribute, NDS32
5630 The system will help save caller registers into stack before entering
5635 @cindex @code{naked} function attribute, NDS32
5636 This attribute allows the compiler to construct the
5637 requisite function declaration, while allowing the body of the
5638 function to be assembly code. The specified function will not have
5639 prologue/epilogue sequences generated by the compiler. Only basic
5640 @code{asm} statements can safely be included in naked functions
5641 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5642 basic @code{asm} and C code may appear to work, they cannot be
5643 depended upon to work reliably and are not supported.
5646 @cindex @code{reset} function attribute, NDS32
5647 @cindex reset handler functions
5648 Use this attribute on the NDS32 target to indicate that the specified function
5649 is a reset handler. The compiler will generate corresponding sections
5650 for use in a reset handler. You can use the following attributes
5651 to provide extra exception handling:
5654 @cindex @code{nmi} function attribute, NDS32
5655 Provide a user-defined function to handle NMI exception.
5657 @cindex @code{warm} function attribute, NDS32
5658 Provide a user-defined function to handle warm reset exception.
5662 @node Nios II Function Attributes
5663 @subsection Nios II Function Attributes
5665 These function attributes are supported by the Nios II back end:
5668 @item target (@var{options})
5669 @cindex @code{target} function attribute
5670 As discussed in @ref{Common Function Attributes}, this attribute
5671 allows specification of target-specific compilation options.
5673 When compiling for Nios II, the following options are allowed:
5676 @item custom-@var{insn}=@var{N}
5677 @itemx no-custom-@var{insn}
5678 @cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II
5679 @cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II
5680 Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a
5681 custom instruction with encoding @var{N} when generating code that uses
5682 @var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of
5683 the custom instruction @var{insn}.
5684 These target attributes correspond to the
5685 @option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}}
5686 command-line options, and support the same set of @var{insn} keywords.
5687 @xref{Nios II Options}, for more information.
5689 @item custom-fpu-cfg=@var{name}
5690 @cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II
5691 This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}}
5692 command-line option, to select a predefined set of custom instructions
5694 @xref{Nios II Options}, for more information.
5698 @node Nvidia PTX Function Attributes
5699 @subsection Nvidia PTX Function Attributes
5701 These function attributes are supported by the Nvidia PTX back end:
5705 @cindex @code{kernel} attribute, Nvidia PTX
5706 This attribute indicates that the corresponding function should be compiled
5707 as a kernel function, which can be invoked from the host via the CUDA RT
5709 By default functions are only callable only from other PTX functions.
5711 Kernel functions must have @code{void} return type.
5714 @node PowerPC Function Attributes
5715 @subsection PowerPC Function Attributes
5717 These function attributes are supported by the PowerPC back end:
5722 @cindex indirect calls, PowerPC
5723 @cindex @code{longcall} function attribute, PowerPC
5724 @cindex @code{shortcall} function attribute, PowerPC
5725 The @code{longcall} attribute
5726 indicates that the function might be far away from the call site and
5727 require a different (more expensive) calling sequence. The
5728 @code{shortcall} attribute indicates that the function is always close
5729 enough for the shorter calling sequence to be used. These attributes
5730 override both the @option{-mlongcall} switch and
5731 the @code{#pragma longcall} setting.
5733 @xref{RS/6000 and PowerPC Options}, for more information on whether long
5734 calls are necessary.
5736 @item target (@var{options})
5737 @cindex @code{target} function attribute
5738 As discussed in @ref{Common Function Attributes}, this attribute
5739 allows specification of target-specific compilation options.
5741 On the PowerPC, the following options are allowed:
5746 @cindex @code{target("altivec")} function attribute, PowerPC
5747 Generate code that uses (does not use) AltiVec instructions. In
5748 32-bit code, you cannot enable AltiVec instructions unless
5749 @option{-mabi=altivec} is used on the command line.
5753 @cindex @code{target("cmpb")} function attribute, PowerPC
5754 Generate code that uses (does not use) the compare bytes instruction
5755 implemented on the POWER6 processor and other processors that support
5756 the PowerPC V2.05 architecture.
5760 @cindex @code{target("dlmzb")} function attribute, PowerPC
5761 Generate code that uses (does not use) the string-search @samp{dlmzb}
5762 instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
5763 generated by default when targeting those processors.
5767 @cindex @code{target("fprnd")} function attribute, PowerPC
5768 Generate code that uses (does not use) the FP round to integer
5769 instructions implemented on the POWER5+ processor and other processors
5770 that support the PowerPC V2.03 architecture.
5774 @cindex @code{target("hard-dfp")} function attribute, PowerPC
5775 Generate code that uses (does not use) the decimal floating-point
5776 instructions implemented on some POWER processors.
5780 @cindex @code{target("isel")} function attribute, PowerPC
5781 Generate code that uses (does not use) ISEL instruction.
5785 @cindex @code{target("mfcrf")} function attribute, PowerPC
5786 Generate code that uses (does not use) the move from condition
5787 register field instruction implemented on the POWER4 processor and
5788 other processors that support the PowerPC V2.01 architecture.
5792 @cindex @code{target("mulhw")} function attribute, PowerPC
5793 Generate code that uses (does not use) the half-word multiply and
5794 multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
5795 These instructions are generated by default when targeting those
5800 @cindex @code{target("multiple")} function attribute, PowerPC
5801 Generate code that uses (does not use) the load multiple word
5802 instructions and the store multiple word instructions.
5806 @cindex @code{target("update")} function attribute, PowerPC
5807 Generate code that uses (does not use) the load or store instructions
5808 that update the base register to the address of the calculated memory
5813 @cindex @code{target("popcntb")} function attribute, PowerPC
5814 Generate code that uses (does not use) the popcount and double-precision
5815 FP reciprocal estimate instruction implemented on the POWER5
5816 processor and other processors that support the PowerPC V2.02
5821 @cindex @code{target("popcntd")} function attribute, PowerPC
5822 Generate code that uses (does not use) the popcount instruction
5823 implemented on the POWER7 processor and other processors that support
5824 the PowerPC V2.06 architecture.
5826 @item powerpc-gfxopt
5827 @itemx no-powerpc-gfxopt
5828 @cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
5829 Generate code that uses (does not use) the optional PowerPC
5830 architecture instructions in the Graphics group, including
5831 floating-point select.
5834 @itemx no-powerpc-gpopt
5835 @cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
5836 Generate code that uses (does not use) the optional PowerPC
5837 architecture instructions in the General Purpose group, including
5838 floating-point square root.
5840 @item recip-precision
5841 @itemx no-recip-precision
5842 @cindex @code{target("recip-precision")} function attribute, PowerPC
5843 Assume (do not assume) that the reciprocal estimate instructions
5844 provide higher-precision estimates than is mandated by the PowerPC
5849 @cindex @code{target("string")} function attribute, PowerPC
5850 Generate code that uses (does not use) the load string instructions
5851 and the store string word instructions to save multiple registers and
5852 do small block moves.
5856 @cindex @code{target("vsx")} function attribute, PowerPC
5857 Generate code that uses (does not use) vector/scalar (VSX)
5858 instructions, and also enable the use of built-in functions that allow
5859 more direct access to the VSX instruction set. In 32-bit code, you
5860 cannot enable VSX or AltiVec instructions unless
5861 @option{-mabi=altivec} is used on the command line.
5865 @cindex @code{target("friz")} function attribute, PowerPC
5866 Generate (do not generate) the @code{friz} instruction when the
5867 @option{-funsafe-math-optimizations} option is used to optimize
5868 rounding a floating-point value to 64-bit integer and back to floating
5869 point. The @code{friz} instruction does not return the same value if
5870 the floating-point number is too large to fit in an integer.
5872 @item avoid-indexed-addresses
5873 @itemx no-avoid-indexed-addresses
5874 @cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
5875 Generate code that tries to avoid (not avoid) the use of indexed load
5876 or store instructions.
5880 @cindex @code{target("paired")} function attribute, PowerPC
5881 Generate code that uses (does not use) the generation of PAIRED simd
5886 @cindex @code{target("longcall")} function attribute, PowerPC
5887 Generate code that assumes (does not assume) that all calls are far
5888 away so that a longer more expensive calling sequence is required.
5891 @cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
5892 Specify the architecture to generate code for when compiling the
5893 function. If you select the @code{target("cpu=power7")} attribute when
5894 generating 32-bit code, VSX and AltiVec instructions are not generated
5895 unless you use the @option{-mabi=altivec} option on the command line.
5897 @item tune=@var{TUNE}
5898 @cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
5899 Specify the architecture to tune for when compiling the function. If
5900 you do not specify the @code{target("tune=@var{TUNE}")} attribute and
5901 you do specify the @code{target("cpu=@var{CPU}")} attribute,
5902 compilation tunes for the @var{CPU} architecture, and not the
5903 default tuning specified on the command line.
5906 On the PowerPC, the inliner does not inline a
5907 function that has different target options than the caller, unless the
5908 callee has a subset of the target options of the caller.
5911 @node RISC-V Function Attributes
5912 @subsection RISC-V Function Attributes
5914 These function attributes are supported by the RISC-V back end:
5918 @cindex @code{naked} function attribute, RISC-V
5919 This attribute allows the compiler to construct the
5920 requisite function declaration, while allowing the body of the
5921 function to be assembly code. The specified function will not have
5922 prologue/epilogue sequences generated by the compiler. Only basic
5923 @code{asm} statements can safely be included in naked functions
5924 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5925 basic @code{asm} and C code may appear to work, they cannot be
5926 depended upon to work reliably and are not supported.
5929 @cindex @code{interrupt} function attribute, RISC-V
5930 Use this attribute to indicate that the specified function is an interrupt
5931 handler. The compiler generates function entry and exit sequences suitable
5932 for use in an interrupt handler when this attribute is present.
5934 You can specify the kind of interrupt to be handled by adding an optional
5935 parameter to the interrupt attribute like this:
5938 void f (void) __attribute__ ((interrupt ("user")));
5941 Permissible values for this parameter are @code{user}, @code{supervisor},
5942 and @code{machine}. If there is no parameter, then it defaults to
5946 @node RL78 Function Attributes
5947 @subsection RL78 Function Attributes
5949 These function attributes are supported by the RL78 back end:
5953 @itemx brk_interrupt
5954 @cindex @code{interrupt} function attribute, RL78
5955 @cindex @code{brk_interrupt} function attribute, RL78
5956 These attributes indicate
5957 that the specified function is an interrupt handler. The compiler generates
5958 function entry and exit sequences suitable for use in an interrupt handler
5959 when this attribute is present.
5961 Use @code{brk_interrupt} instead of @code{interrupt} for
5962 handlers intended to be used with the @code{BRK} opcode (i.e.@: those
5963 that must end with @code{RETB} instead of @code{RETI}).
5966 @cindex @code{naked} function attribute, RL78
5967 This attribute allows the compiler to construct the
5968 requisite function declaration, while allowing the body of the
5969 function to be assembly code. The specified function will not have
5970 prologue/epilogue sequences generated by the compiler. Only basic
5971 @code{asm} statements can safely be included in naked functions
5972 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5973 basic @code{asm} and C code may appear to work, they cannot be
5974 depended upon to work reliably and are not supported.
5977 @node RX Function Attributes
5978 @subsection RX Function Attributes
5980 These function attributes are supported by the RX back end:
5983 @item fast_interrupt
5984 @cindex @code{fast_interrupt} function attribute, RX
5985 Use this attribute on the RX port to indicate that the specified
5986 function is a fast interrupt handler. This is just like the
5987 @code{interrupt} attribute, except that @code{freit} is used to return
5988 instead of @code{reit}.
5991 @cindex @code{interrupt} function attribute, RX
5992 Use this attribute to indicate
5993 that the specified function is an interrupt handler. The compiler generates
5994 function entry and exit sequences suitable for use in an interrupt handler
5995 when this attribute is present.
5997 On RX and RL78 targets, you may specify one or more vector numbers as arguments
5998 to the attribute, as well as naming an alternate table name.
5999 Parameters are handled sequentially, so one handler can be assigned to
6000 multiple entries in multiple tables. One may also pass the magic
6001 string @code{"$default"} which causes the function to be used for any
6002 unfilled slots in the current table.
6004 This example shows a simple assignment of a function to one vector in
6005 the default table (note that preprocessor macros may be used for
6006 chip-specific symbolic vector names):
6008 void __attribute__ ((interrupt (5))) txd1_handler ();
6011 This example assigns a function to two slots in the default table
6012 (using preprocessor macros defined elsewhere) and makes it the default
6013 for the @code{dct} table:
6015 void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
6020 @cindex @code{naked} function attribute, RX
6021 This attribute allows the compiler to construct the
6022 requisite function declaration, while allowing the body of the
6023 function to be assembly code. The specified function will not have
6024 prologue/epilogue sequences generated by the compiler. Only basic
6025 @code{asm} statements can safely be included in naked functions
6026 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6027 basic @code{asm} and C code may appear to work, they cannot be
6028 depended upon to work reliably and are not supported.
6031 @cindex @code{vector} function attribute, RX
6032 This RX attribute is similar to the @code{interrupt} attribute, including its
6033 parameters, but does not make the function an interrupt-handler type
6034 function (i.e.@: it retains the normal C function calling ABI). See the
6035 @code{interrupt} attribute for a description of its arguments.
6038 @node S/390 Function Attributes
6039 @subsection S/390 Function Attributes
6041 These function attributes are supported on the S/390:
6044 @item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
6045 @cindex @code{hotpatch} function attribute, S/390
6047 On S/390 System z targets, you can use this function attribute to
6048 make GCC generate a ``hot-patching'' function prologue. If the
6049 @option{-mhotpatch=} command-line option is used at the same time,
6050 the @code{hotpatch} attribute takes precedence. The first of the
6051 two arguments specifies the number of halfwords to be added before
6052 the function label. A second argument can be used to specify the
6053 number of halfwords to be added after the function label. For
6054 both arguments the maximum allowed value is 1000000.
6056 If both arguments are zero, hotpatching is disabled.
6058 @item target (@var{options})
6059 @cindex @code{target} function attribute
6060 As discussed in @ref{Common Function Attributes}, this attribute
6061 allows specification of target-specific compilation options.
6063 On S/390, the following options are supported:
6071 @item warn-framesize=
6083 @itemx no-packed-stack
6085 @itemx no-small-exec
6088 @item warn-dynamicstack
6089 @itemx no-warn-dynamicstack
6092 The options work exactly like the S/390 specific command line
6093 options (without the prefix @option{-m}) except that they do not
6094 change any feature macros. For example,
6097 @code{target("no-vx")}
6100 does not undefine the @code{__VEC__} macro.
6103 @node SH Function Attributes
6104 @subsection SH Function Attributes
6106 These function attributes are supported on the SH family of processors:
6109 @item function_vector
6110 @cindex @code{function_vector} function attribute, SH
6111 @cindex calling functions through the function vector on SH2A
6112 On SH2A targets, this attribute declares a function to be called using the
6113 TBR relative addressing mode. The argument to this attribute is the entry
6114 number of the same function in a vector table containing all the TBR
6115 relative addressable functions. For correct operation the TBR must be setup
6116 accordingly to point to the start of the vector table before any functions with
6117 this attribute are invoked. Usually a good place to do the initialization is
6118 the startup routine. The TBR relative vector table can have at max 256 function
6119 entries. The jumps to these functions are generated using a SH2A specific,
6120 non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD
6121 from GNU binutils version 2.7 or later for this attribute to work correctly.
6123 In an application, for a function being called once, this attribute
6124 saves at least 8 bytes of code; and if other successive calls are being
6125 made to the same function, it saves 2 bytes of code per each of these
6128 @item interrupt_handler
6129 @cindex @code{interrupt_handler} function attribute, SH
6130 Use this attribute to
6131 indicate that the specified function is an interrupt handler. The compiler
6132 generates function entry and exit sequences suitable for use in an
6133 interrupt handler when this attribute is present.
6135 @item nosave_low_regs
6136 @cindex @code{nosave_low_regs} function attribute, SH
6137 Use this attribute on SH targets to indicate that an @code{interrupt_handler}
6138 function should not save and restore registers R0..R7. This can be used on SH3*
6139 and SH4* targets that have a second R0..R7 register bank for non-reentrant
6143 @cindex @code{renesas} function attribute, SH
6144 On SH targets this attribute specifies that the function or struct follows the
6148 @cindex @code{resbank} function attribute, SH
6149 On the SH2A target, this attribute enables the high-speed register
6150 saving and restoration using a register bank for @code{interrupt_handler}
6151 routines. Saving to the bank is performed automatically after the CPU
6152 accepts an interrupt that uses a register bank.
6154 The nineteen 32-bit registers comprising general register R0 to R14,
6155 control register GBR, and system registers MACH, MACL, and PR and the
6156 vector table address offset are saved into a register bank. Register
6157 banks are stacked in first-in last-out (FILO) sequence. Restoration
6158 from the bank is executed by issuing a RESBANK instruction.
6161 @cindex @code{sp_switch} function attribute, SH
6162 Use this attribute on the SH to indicate an @code{interrupt_handler}
6163 function should switch to an alternate stack. It expects a string
6164 argument that names a global variable holding the address of the
6169 void f () __attribute__ ((interrupt_handler,
6170 sp_switch ("alt_stack")));
6174 @cindex @code{trap_exit} function attribute, SH
6175 Use this attribute on the SH for an @code{interrupt_handler} to return using
6176 @code{trapa} instead of @code{rte}. This attribute expects an integer
6177 argument specifying the trap number to be used.
6180 @cindex @code{trapa_handler} function attribute, SH
6181 On SH targets this function attribute is similar to @code{interrupt_handler}
6182 but it does not save and restore all registers.
6185 @node Symbian OS Function Attributes
6186 @subsection Symbian OS Function Attributes
6188 @xref{Microsoft Windows Function Attributes}, for discussion of the
6189 @code{dllexport} and @code{dllimport} attributes.
6191 @node V850 Function Attributes
6192 @subsection V850 Function Attributes
6194 The V850 back end supports these function attributes:
6198 @itemx interrupt_handler
6199 @cindex @code{interrupt} function attribute, V850
6200 @cindex @code{interrupt_handler} function attribute, V850
6201 Use these attributes to indicate
6202 that the specified function is an interrupt handler. The compiler generates
6203 function entry and exit sequences suitable for use in an interrupt handler
6204 when either attribute is present.
6207 @node Visium Function Attributes
6208 @subsection Visium Function Attributes
6210 These function attributes are supported by the Visium back end:
6214 @cindex @code{interrupt} function attribute, Visium
6215 Use this attribute to indicate
6216 that the specified function is an interrupt handler. The compiler generates
6217 function entry and exit sequences suitable for use in an interrupt handler
6218 when this attribute is present.
6221 @node x86 Function Attributes
6222 @subsection x86 Function Attributes
6224 These function attributes are supported by the x86 back end:
6228 @cindex @code{cdecl} function attribute, x86-32
6229 @cindex functions that pop the argument stack on x86-32
6231 On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
6232 assume that the calling function pops off the stack space used to
6233 pass arguments. This is
6234 useful to override the effects of the @option{-mrtd} switch.
6237 @cindex @code{fastcall} function attribute, x86-32
6238 @cindex functions that pop the argument stack on x86-32
6239 On x86-32 targets, the @code{fastcall} attribute causes the compiler to
6240 pass the first argument (if of integral type) in the register ECX and
6241 the second argument (if of integral type) in the register EDX@. Subsequent
6242 and other typed arguments are passed on the stack. The called function
6243 pops the arguments off the stack. If the number of arguments is variable all
6244 arguments are pushed on the stack.
6247 @cindex @code{thiscall} function attribute, x86-32
6248 @cindex functions that pop the argument stack on x86-32
6249 On x86-32 targets, the @code{thiscall} attribute causes the compiler to
6250 pass the first argument (if of integral type) in the register ECX.
6251 Subsequent and other typed arguments are passed on the stack. The called
6252 function pops the arguments off the stack.
6253 If the number of arguments is variable all arguments are pushed on the
6255 The @code{thiscall} attribute is intended for C++ non-static member functions.
6256 As a GCC extension, this calling convention can be used for C functions
6257 and for static member methods.
6261 @cindex @code{ms_abi} function attribute, x86
6262 @cindex @code{sysv_abi} function attribute, x86
6264 On 32-bit and 64-bit x86 targets, you can use an ABI attribute
6265 to indicate which calling convention should be used for a function. The
6266 @code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
6267 while the @code{sysv_abi} attribute tells the compiler to use the System V
6268 ELF ABI, which is used on GNU/Linux and other systems. The default is to use
6269 the Microsoft ABI when targeting Windows. On all other systems, the default
6270 is the System V ELF ABI.
6272 Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
6273 requires the @option{-maccumulate-outgoing-args} option.
6275 @item callee_pop_aggregate_return (@var{number})
6276 @cindex @code{callee_pop_aggregate_return} function attribute, x86
6278 On x86-32 targets, you can use this attribute to control how
6279 aggregates are returned in memory. If the caller is responsible for
6280 popping the hidden pointer together with the rest of the arguments, specify
6281 @var{number} equal to zero. If callee is responsible for popping the
6282 hidden pointer, specify @var{number} equal to one.
6284 The default x86-32 ABI assumes that the callee pops the
6285 stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
6286 the compiler assumes that the
6287 caller pops the stack for hidden pointer.
6289 @item ms_hook_prologue
6290 @cindex @code{ms_hook_prologue} function attribute, x86
6292 On 32-bit and 64-bit x86 targets, you can use
6293 this function attribute to make GCC generate the ``hot-patching'' function
6294 prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
6298 @cindex @code{naked} function attribute, x86
6299 This attribute allows the compiler to construct the
6300 requisite function declaration, while allowing the body of the
6301 function to be assembly code. The specified function will not have
6302 prologue/epilogue sequences generated by the compiler. Only basic
6303 @code{asm} statements can safely be included in naked functions
6304 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6305 basic @code{asm} and C code may appear to work, they cannot be
6306 depended upon to work reliably and are not supported.
6308 @item regparm (@var{number})
6309 @cindex @code{regparm} function attribute, x86
6310 @cindex functions that are passed arguments in registers on x86-32
6311 On x86-32 targets, the @code{regparm} attribute causes the compiler to
6312 pass arguments number one to @var{number} if they are of integral type
6313 in registers EAX, EDX, and ECX instead of on the stack. Functions that
6314 take a variable number of arguments continue to be passed all of their
6315 arguments on the stack.
6317 Beware that on some ELF systems this attribute is unsuitable for
6318 global functions in shared libraries with lazy binding (which is the
6319 default). Lazy binding sends the first call via resolving code in
6320 the loader, which might assume EAX, EDX and ECX can be clobbered, as
6321 per the standard calling conventions. Solaris 8 is affected by this.
6322 Systems with the GNU C Library version 2.1 or higher
6323 and FreeBSD are believed to be
6324 safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
6325 disabled with the linker or the loader if desired, to avoid the
6329 @cindex @code{sseregparm} function attribute, x86
6330 On x86-32 targets with SSE support, the @code{sseregparm} attribute
6331 causes the compiler to pass up to 3 floating-point arguments in
6332 SSE registers instead of on the stack. Functions that take a
6333 variable number of arguments continue to pass all of their
6334 floating-point arguments on the stack.
6336 @item force_align_arg_pointer
6337 @cindex @code{force_align_arg_pointer} function attribute, x86
6338 On x86 targets, the @code{force_align_arg_pointer} attribute may be
6339 applied to individual function definitions, generating an alternate
6340 prologue and epilogue that realigns the run-time stack if necessary.
6341 This supports mixing legacy codes that run with a 4-byte aligned stack
6342 with modern codes that keep a 16-byte stack for SSE compatibility.
6345 @cindex @code{stdcall} function attribute, x86-32
6346 @cindex functions that pop the argument stack on x86-32
6347 On x86-32 targets, the @code{stdcall} attribute causes the compiler to
6348 assume that the called function pops off the stack space used to
6349 pass arguments, unless it takes a variable number of arguments.
6351 @item no_caller_saved_registers
6352 @cindex @code{no_caller_saved_registers} function attribute, x86
6353 Use this attribute to indicate that the specified function has no
6354 caller-saved registers. That is, all registers are callee-saved. For
6355 example, this attribute can be used for a function called from an
6356 interrupt handler. The compiler generates proper function entry and
6357 exit sequences to save and restore any modified registers, except for
6358 the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87
6359 states, the GCC option @option{-mgeneral-regs-only} should be used to
6360 compile functions with @code{no_caller_saved_registers} attribute.
6363 @cindex @code{interrupt} function attribute, x86
6364 Use this attribute to indicate that the specified function is an
6365 interrupt handler or an exception handler (depending on parameters passed
6366 to the function, explained further). The compiler generates function
6367 entry and exit sequences suitable for use in an interrupt handler when
6368 this attribute is present. The @code{IRET} instruction, instead of the
6369 @code{RET} instruction, is used to return from interrupt handlers. All
6370 registers, except for the EFLAGS register which is restored by the
6371 @code{IRET} instruction, are preserved by the compiler. Since GCC
6372 doesn't preserve SSE, MMX nor x87 states, the GCC option
6373 @option{-mgeneral-regs-only} should be used to compile interrupt and
6376 Any interruptible-without-stack-switch code must be compiled with
6377 @option{-mno-red-zone} since interrupt handlers can and will, because
6378 of the hardware design, touch the red zone.
6380 An interrupt handler must be declared with a mandatory pointer
6384 struct interrupt_frame;
6386 __attribute__ ((interrupt))
6388 f (struct interrupt_frame *frame)
6394 and you must define @code{struct interrupt_frame} as described in the
6397 Exception handlers differ from interrupt handlers because the system
6398 pushes an error code on the stack. An exception handler declaration is
6399 similar to that for an interrupt handler, but with a different mandatory
6400 function signature. The compiler arranges to pop the error code off the
6401 stack before the @code{IRET} instruction.
6405 typedef unsigned long long int uword_t;
6407 typedef unsigned int uword_t;
6410 struct interrupt_frame;
6412 __attribute__ ((interrupt))
6414 f (struct interrupt_frame *frame, uword_t error_code)
6420 Exception handlers should only be used for exceptions that push an error
6421 code; you should use an interrupt handler in other cases. The system
6422 will crash if the wrong kind of handler is used.
6424 @item target (@var{options})
6425 @cindex @code{target} function attribute
6426 As discussed in @ref{Common Function Attributes}, this attribute
6427 allows specification of target-specific compilation options.
6429 On the x86, the following options are allowed:
6433 @cindex @code{target("3dnow")} function attribute, x86
6434 Enable/disable the generation of the 3DNow!@: instructions.
6438 @cindex @code{target("3dnowa")} function attribute, x86
6439 Enable/disable the generation of the enhanced 3DNow!@: instructions.
6443 @cindex @code{target("abm")} function attribute, x86
6444 Enable/disable the generation of the advanced bit instructions.
6448 @cindex @code{target("adx")} function attribute, x86
6449 Enable/disable the generation of the ADX instructions.
6453 @cindex @code{target("aes")} function attribute, x86
6454 Enable/disable the generation of the AES instructions.
6458 @cindex @code{target("avx")} function attribute, x86
6459 Enable/disable the generation of the AVX instructions.
6463 @cindex @code{target("avx2")} function attribute, x86
6464 Enable/disable the generation of the AVX2 instructions.
6467 @itemx no-avx5124fmaps
6468 @cindex @code{target("avx5124fmaps")} function attribute, x86
6469 Enable/disable the generation of the AVX5124FMAPS instructions.
6472 @itemx no-avx5124vnniw
6473 @cindex @code{target("avx5124vnniw")} function attribute, x86
6474 Enable/disable the generation of the AVX5124VNNIW instructions.
6477 @itemx no-avx512bitalg
6478 @cindex @code{target("avx512bitalg")} function attribute, x86
6479 Enable/disable the generation of the AVX512BITALG instructions.
6483 @cindex @code{target("avx512bw")} function attribute, x86
6484 Enable/disable the generation of the AVX512BW instructions.
6488 @cindex @code{target("avx512cd")} function attribute, x86
6489 Enable/disable the generation of the AVX512CD instructions.
6493 @cindex @code{target("avx512dq")} function attribute, x86
6494 Enable/disable the generation of the AVX512DQ instructions.
6498 @cindex @code{target("avx512er")} function attribute, x86
6499 Enable/disable the generation of the AVX512ER instructions.
6503 @cindex @code{target("avx512f")} function attribute, x86
6504 Enable/disable the generation of the AVX512F instructions.
6507 @itemx no-avx512ifma
6508 @cindex @code{target("avx512ifma")} function attribute, x86
6509 Enable/disable the generation of the AVX512IFMA instructions.
6513 @cindex @code{target("avx512pf")} function attribute, x86
6514 Enable/disable the generation of the AVX512PF instructions.
6517 @itemx no-avx512vbmi
6518 @cindex @code{target("avx512vbmi")} function attribute, x86
6519 Enable/disable the generation of the AVX512VBMI instructions.
6522 @itemx no-avx512vbmi2
6523 @cindex @code{target("avx512vbmi2")} function attribute, x86
6524 Enable/disable the generation of the AVX512VBMI2 instructions.
6528 @cindex @code{target("avx512vl")} function attribute, x86
6529 Enable/disable the generation of the AVX512VL instructions.
6532 @itemx no-avx512vnni
6533 @cindex @code{target("avx512vnni")} function attribute, x86
6534 Enable/disable the generation of the AVX512VNNI instructions.
6536 @item avx512vpopcntdq
6537 @itemx no-avx512vpopcntdq
6538 @cindex @code{target("avx512vpopcntdq")} function attribute, x86
6539 Enable/disable the generation of the AVX512VPOPCNTDQ instructions.
6543 @cindex @code{target("bmi")} function attribute, x86
6544 Enable/disable the generation of the BMI instructions.
6548 @cindex @code{target("bmi2")} function attribute, x86
6549 Enable/disable the generation of the BMI2 instructions.
6553 @cindex @code{target("cldemote")} function attribute, x86
6554 Enable/disable the generation of the CLDEMOTE instructions.
6557 @itemx no-clflushopt
6558 @cindex @code{target("clflushopt")} function attribute, x86
6559 Enable/disable the generation of the CLFLUSHOPT instructions.
6563 @cindex @code{target("clwb")} function attribute, x86
6564 Enable/disable the generation of the CLWB instructions.
6568 @cindex @code{target("clzero")} function attribute, x86
6569 Enable/disable the generation of the CLZERO instructions.
6573 @cindex @code{target("crc32")} function attribute, x86
6574 Enable/disable the generation of the CRC32 instructions.
6578 @cindex @code{target("cx16")} function attribute, x86
6579 Enable/disable the generation of the CMPXCHG16B instructions.
6582 @cindex @code{target("default")} function attribute, x86
6583 @xref{Function Multiversioning}, where it is used to specify the
6584 default function version.
6588 @cindex @code{target("f16c")} function attribute, x86
6589 Enable/disable the generation of the F16C instructions.
6593 @cindex @code{target("fma")} function attribute, x86
6594 Enable/disable the generation of the FMA instructions.
6598 @cindex @code{target("fma4")} function attribute, x86
6599 Enable/disable the generation of the FMA4 instructions.
6603 @cindex @code{target("fsgsbase")} function attribute, x86
6604 Enable/disable the generation of the FSGSBASE instructions.
6608 @cindex @code{target("fxsr")} function attribute, x86
6609 Enable/disable the generation of the FXSR instructions.
6613 @cindex @code{target("gfni")} function attribute, x86
6614 Enable/disable the generation of the GFNI instructions.
6618 @cindex @code{target("hle")} function attribute, x86
6619 Enable/disable the generation of the HLE instruction prefixes.
6623 @cindex @code{target("lwp")} function attribute, x86
6624 Enable/disable the generation of the LWP instructions.
6628 @cindex @code{target("lzcnt")} function attribute, x86
6629 Enable/disable the generation of the LZCNT instructions.
6633 @cindex @code{target("mmx")} function attribute, x86
6634 Enable/disable the generation of the MMX instructions.
6638 @cindex @code{target("movbe")} function attribute, x86
6639 Enable/disable the generation of the MOVBE instructions.
6643 @cindex @code{target("movdir64b")} function attribute, x86
6644 Enable/disable the generation of the MOVDIR64B instructions.
6648 @cindex @code{target("movdiri")} function attribute, x86
6649 Enable/disable the generation of the MOVDIRI instructions.
6653 @cindex @code{target("mwaitx")} function attribute, x86
6654 Enable/disable the generation of the MWAITX instructions.
6658 @cindex @code{target("pclmul")} function attribute, x86
6659 Enable/disable the generation of the PCLMUL instructions.
6663 @cindex @code{target("pconfig")} function attribute, x86
6664 Enable/disable the generation of the PCONFIG instructions.
6668 @cindex @code{target("pku")} function attribute, x86
6669 Enable/disable the generation of the PKU instructions.
6673 @cindex @code{target("popcnt")} function attribute, x86
6674 Enable/disable the generation of the POPCNT instruction.
6677 @itemx no-prefetchwt1
6678 @cindex @code{target("prefetchwt1")} function attribute, x86
6679 Enable/disable the generation of the PREFETCHWT1 instructions.
6683 @cindex @code{target("prfchw")} function attribute, x86
6684 Enable/disable the generation of the PREFETCHW instruction.
6688 @cindex @code{target("ptwrite")} function attribute, x86
6689 Enable/disable the generation of the PTWRITE instructions.
6693 @cindex @code{target("rdpid")} function attribute, x86
6694 Enable/disable the generation of the RDPID instructions.
6698 @cindex @code{target("rdrnd")} function attribute, x86
6699 Enable/disable the generation of the RDRND instructions.
6703 @cindex @code{target("rdseed")} function attribute, x86
6704 Enable/disable the generation of the RDSEED instructions.
6708 @cindex @code{target("rtm")} function attribute, x86
6709 Enable/disable the generation of the RTM instructions.
6713 @cindex @code{target("sahf")} function attribute, x86
6714 Enable/disable the generation of the SAHF instructions.
6718 @cindex @code{target("sgx")} function attribute, x86
6719 Enable/disable the generation of the SGX instructions.
6723 @cindex @code{target("sha")} function attribute, x86
6724 Enable/disable the generation of the SHA instructions.
6728 @cindex @code{target("shstk")} function attribute, x86
6729 Enable/disable the shadow stack built-in functions from CET.
6733 @cindex @code{target("sse")} function attribute, x86
6734 Enable/disable the generation of the SSE instructions.
6738 @cindex @code{target("sse2")} function attribute, x86
6739 Enable/disable the generation of the SSE2 instructions.
6743 @cindex @code{target("sse3")} function attribute, x86
6744 Enable/disable the generation of the SSE3 instructions.
6748 @cindex @code{target("sse4")} function attribute, x86
6749 Enable/disable the generation of the SSE4 instructions (both SSE4.1
6754 @cindex @code{target("sse4.1")} function attribute, x86
6755 Enable/disable the generation of the sse4.1 instructions.
6759 @cindex @code{target("sse4.2")} function attribute, x86
6760 Enable/disable the generation of the sse4.2 instructions.
6764 @cindex @code{target("sse4a")} function attribute, x86
6765 Enable/disable the generation of the SSE4A instructions.
6769 @cindex @code{target("ssse3")} function attribute, x86
6770 Enable/disable the generation of the SSSE3 instructions.
6774 @cindex @code{target("tbm")} function attribute, x86
6775 Enable/disable the generation of the TBM instructions.
6779 @cindex @code{target("vaes")} function attribute, x86
6780 Enable/disable the generation of the VAES instructions.
6783 @itemx no-vpclmulqdq
6784 @cindex @code{target("vpclmulqdq")} function attribute, x86
6785 Enable/disable the generation of the VPCLMULQDQ instructions.
6789 @cindex @code{target("waitpkg")} function attribute, x86
6790 Enable/disable the generation of the WAITPKG instructions.
6794 @cindex @code{target("wbnoinvd")} function attribute, x86
6795 Enable/disable the generation of the WBNOINVD instructions.
6799 @cindex @code{target("xop")} function attribute, x86
6800 Enable/disable the generation of the XOP instructions.
6804 @cindex @code{target("xsave")} function attribute, x86
6805 Enable/disable the generation of the XSAVE instructions.
6809 @cindex @code{target("xsavec")} function attribute, x86
6810 Enable/disable the generation of the XSAVEC instructions.
6814 @cindex @code{target("xsaveopt")} function attribute, x86
6815 Enable/disable the generation of the XSAVEOPT instructions.
6819 @cindex @code{target("xsaves")} function attribute, x86
6820 Enable/disable the generation of the XSAVES instructions.
6824 @cindex @code{target("amx-tile")} function attribute, x86
6825 Enable/disable the generation of the AMX-TILE instructions.
6829 @cindex @code{target("amx-int8")} function attribute, x86
6830 Enable/disable the generation of the AMX-INT8 instructions.
6834 @cindex @code{target("amx-bf16")} function attribute, x86
6835 Enable/disable the generation of the AMX-BF16 instructions.
6839 @cindex @code{target("uintr")} function attribute, x86
6840 Enable/disable the generation of the UINTR instructions.
6844 @cindex @code{target("hreset")} function attribute, x86
6845 Enable/disable the generation of the HRESET instruction.
6849 @cindex @code{target("kl")} function attribute, x86
6850 Enable/disable the generation of the KEYLOCKER instructions.
6854 @cindex @code{target("widekl")} function attribute, x86
6855 Enable/disable the generation of the WIDEKL instructions.
6859 @cindex @code{target("avxvnni")} function attribute, x86
6860 Enable/disable the generation of the AVXVNNI instructions.
6864 @cindex @code{target("cld")} function attribute, x86
6865 Enable/disable the generation of the CLD before string moves.
6867 @item fancy-math-387
6868 @itemx no-fancy-math-387
6869 @cindex @code{target("fancy-math-387")} function attribute, x86
6870 Enable/disable the generation of the @code{sin}, @code{cos}, and
6871 @code{sqrt} instructions on the 387 floating-point unit.
6875 @cindex @code{target("ieee-fp")} function attribute, x86
6876 Enable/disable the generation of floating point that depends on IEEE arithmetic.
6878 @item inline-all-stringops
6879 @itemx no-inline-all-stringops
6880 @cindex @code{target("inline-all-stringops")} function attribute, x86
6881 Enable/disable inlining of string operations.
6883 @item inline-stringops-dynamically
6884 @itemx no-inline-stringops-dynamically
6885 @cindex @code{target("inline-stringops-dynamically")} function attribute, x86
6886 Enable/disable the generation of the inline code to do small string
6887 operations and calling the library routines for large operations.
6889 @item align-stringops
6890 @itemx no-align-stringops
6891 @cindex @code{target("align-stringops")} function attribute, x86
6892 Do/do not align destination of inlined string operations.
6896 @cindex @code{target("recip")} function attribute, x86
6897 Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
6898 instructions followed an additional Newton-Raphson step instead of
6899 doing a floating-point division.
6901 @item general-regs-only
6902 @cindex @code{target("general-regs-only")} function attribute, x86
6903 Generate code which uses only the general registers.
6905 @item arch=@var{ARCH}
6906 @cindex @code{target("arch=@var{ARCH}")} function attribute, x86
6907 Specify the architecture to generate code for in compiling the function.
6909 @item tune=@var{TUNE}
6910 @cindex @code{target("tune=@var{TUNE}")} function attribute, x86
6911 Specify the architecture to tune for in compiling the function.
6913 @item fpmath=@var{FPMATH}
6914 @cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
6915 Specify which floating-point unit to use. You must specify the
6916 @code{target("fpmath=sse,387")} option as
6917 @code{target("fpmath=sse+387")} because the comma would separate
6920 @item indirect_branch("@var{choice}")
6921 @cindex @code{indirect_branch} function attribute, x86
6922 On x86 targets, the @code{indirect_branch} attribute causes the compiler
6923 to convert indirect call and jump with @var{choice}. @samp{keep}
6924 keeps indirect call and jump unmodified. @samp{thunk} converts indirect
6925 call and jump to call and return thunk. @samp{thunk-inline} converts
6926 indirect call and jump to inlined call and return thunk.
6927 @samp{thunk-extern} converts indirect call and jump to external call
6928 and return thunk provided in a separate object file.
6930 @item function_return("@var{choice}")
6931 @cindex @code{function_return} function attribute, x86
6932 On x86 targets, the @code{function_return} attribute causes the compiler
6933 to convert function return with @var{choice}. @samp{keep} keeps function
6934 return unmodified. @samp{thunk} converts function return to call and
6935 return thunk. @samp{thunk-inline} converts function return to inlined
6936 call and return thunk. @samp{thunk-extern} converts function return to
6937 external call and return thunk provided in a separate object file.
6940 @cindex @code{nocf_check} function attribute
6941 The @code{nocf_check} attribute on a function is used to inform the
6942 compiler that the function's prologue should not be instrumented when
6943 compiled with the @option{-fcf-protection=branch} option. The
6944 compiler assumes that the function's address is a valid target for a
6945 control-flow transfer.
6947 The @code{nocf_check} attribute on a type of pointer to function is
6948 used to inform the compiler that a call through the pointer should
6949 not be instrumented when compiled with the
6950 @option{-fcf-protection=branch} option. The compiler assumes
6951 that the function's address from the pointer is a valid target for
6952 a control-flow transfer. A direct function call through a function
6953 name is assumed to be a safe call thus direct calls are not
6954 instrumented by the compiler.
6956 The @code{nocf_check} attribute is applied to an object's type.
6957 In case of assignment of a function address or a function pointer to
6958 another pointer, the attribute is not carried over from the right-hand
6959 object's type; the type of left-hand object stays unchanged. The
6960 compiler checks for @code{nocf_check} attribute mismatch and reports
6961 a warning in case of mismatch.
6965 int foo (void) __attribute__(nocf_check);
6966 void (*foo1)(void) __attribute__(nocf_check);
6969 /* foo's address is assumed to be valid. */
6973 /* This call site is not checked for control-flow
6977 /* A warning is issued about attribute mismatch. */
6980 /* This call site is still not checked. */
6983 /* This call site is checked. */
6986 /* A warning is issued about attribute mismatch. */
6989 /* This call site is still checked. */
6997 @cindex @code{cf_check} function attribute, x86
6999 The @code{cf_check} attribute on a function is used to inform the
7000 compiler that ENDBR instruction should be placed at the function
7001 entry when @option{-fcf-protection=branch} is enabled.
7003 @item indirect_return
7004 @cindex @code{indirect_return} function attribute, x86
7006 The @code{indirect_return} attribute can be applied to a function,
7007 as well as variable or type of function pointer to inform the
7008 compiler that the function may return via indirect branch.
7010 @item fentry_name("@var{name}")
7011 @cindex @code{fentry_name} function attribute, x86
7012 On x86 targets, the @code{fentry_name} attribute sets the function to
7013 call on function entry when function instrumentation is enabled
7014 with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte
7015 nop sequence is generated.
7017 @item fentry_section("@var{name}")
7018 @cindex @code{fentry_section} function attribute, x86
7019 On x86 targets, the @code{fentry_section} attribute sets the name
7020 of the section to record function entry instrumentation calls in when
7021 enabled with @option{-pg -mrecord-mcount}
7025 On the x86, the inliner does not inline a
7026 function that has different target options than the caller, unless the
7027 callee has a subset of the target options of the caller. For example
7028 a function declared with @code{target("sse3")} can inline a function
7029 with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
7032 @node Xstormy16 Function Attributes
7033 @subsection Xstormy16 Function Attributes
7035 These function attributes are supported by the Xstormy16 back end:
7039 @cindex @code{interrupt} function attribute, Xstormy16
7040 Use this attribute to indicate
7041 that the specified function is an interrupt handler. The compiler generates
7042 function entry and exit sequences suitable for use in an interrupt handler
7043 when this attribute is present.
7046 @node Variable Attributes
7047 @section Specifying Attributes of Variables
7048 @cindex attribute of variables
7049 @cindex variable attributes
7051 The keyword @code{__attribute__} allows you to specify special properties
7052 of variables, function parameters, or structure, union, and, in C++, class
7053 members. This @code{__attribute__} keyword is followed by an attribute
7054 specification enclosed in double parentheses. Some attributes are currently
7055 defined generically for variables. Other attributes are defined for
7056 variables on particular target systems. Other attributes are available
7057 for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
7058 enumerators (@pxref{Enumerator Attributes}), statements
7059 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
7060 Other front ends might define more attributes
7061 (@pxref{C++ Extensions,,Extensions to the C++ Language}).
7063 @xref{Attribute Syntax}, for details of the exact syntax for using
7067 * Common Variable Attributes::
7068 * ARC Variable Attributes::
7069 * AVR Variable Attributes::
7070 * Blackfin Variable Attributes::
7071 * H8/300 Variable Attributes::
7072 * IA-64 Variable Attributes::
7073 * M32R/D Variable Attributes::
7074 * MeP Variable Attributes::
7075 * Microsoft Windows Variable Attributes::
7076 * MSP430 Variable Attributes::
7077 * Nvidia PTX Variable Attributes::
7078 * PowerPC Variable Attributes::
7079 * RL78 Variable Attributes::
7080 * V850 Variable Attributes::
7081 * x86 Variable Attributes::
7082 * Xstormy16 Variable Attributes::
7085 @node Common Variable Attributes
7086 @subsection Common Variable Attributes
7088 The following attributes are supported on most targets.
7092 @item alias ("@var{target}")
7093 @cindex @code{alias} variable attribute
7094 The @code{alias} variable attribute causes the declaration to be emitted
7095 as an alias for another symbol known as an @dfn{alias target}. Except
7096 for top-level qualifiers the alias target must have the same type as
7097 the alias. For instance, the following
7101 extern int __attribute__ ((alias ("var_target"))) var_alias;
7105 defines @code{var_alias} to be an alias for the @code{var_target} variable.
7107 It is an error if the alias target is not defined in the same translation
7110 Note that in the absence of the attribute GCC assumes that distinct
7111 declarations with external linkage denote distinct objects. Using both
7112 the alias and the alias target to access the same object is undefined
7113 in a translation unit without a declaration of the alias with the attribute.
7115 This attribute requires assembler and object file support, and may not be
7116 available on all targets.
7118 @cindex @code{aligned} variable attribute
7120 @itemx aligned (@var{alignment})
7121 The @code{aligned} attribute specifies a minimum alignment for the variable
7122 or structure field, measured in bytes. When specified, @var{alignment} must
7123 be an integer constant power of 2. Specifying no @var{alignment} argument
7124 implies the maximum alignment for the target, which is often, but by no
7125 means always, 8 or 16 bytes.
7127 For example, the declaration:
7130 int x __attribute__ ((aligned (16))) = 0;
7134 causes the compiler to allocate the global variable @code{x} on a
7135 16-byte boundary. On a 68040, this could be used in conjunction with
7136 an @code{asm} expression to access the @code{move16} instruction which
7137 requires 16-byte aligned operands.
7139 You can also specify the alignment of structure fields. For example, to
7140 create a double-word aligned @code{int} pair, you could write:
7143 struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
7147 This is an alternative to creating a union with a @code{double} member,
7148 which forces the union to be double-word aligned.
7150 As in the preceding examples, you can explicitly specify the alignment
7151 (in bytes) that you wish the compiler to use for a given variable or
7152 structure field. Alternatively, you can leave out the alignment factor
7153 and just ask the compiler to align a variable or field to the
7154 default alignment for the target architecture you are compiling for.
7155 The default alignment is sufficient for all scalar types, but may not be
7156 enough for all vector types on a target that supports vector operations.
7157 The default alignment is fixed for a particular target ABI.
7159 GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
7160 which is the largest alignment ever used for any data type on the
7161 target machine you are compiling for. For example, you could write:
7164 short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
7167 The compiler automatically sets the alignment for the declared
7168 variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
7169 often make copy operations more efficient, because the compiler can
7170 use whatever instructions copy the biggest chunks of memory when
7171 performing copies to or from the variables or fields that you have
7172 aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
7173 may change depending on command-line options.
7175 When used on a struct, or struct member, the @code{aligned} attribute can
7176 only increase the alignment; in order to decrease it, the @code{packed}
7177 attribute must be specified as well. When used as part of a typedef, the
7178 @code{aligned} attribute can both increase and decrease alignment, and
7179 specifying the @code{packed} attribute generates a warning.
7181 Note that the effectiveness of @code{aligned} attributes for static
7182 variables may be limited by inherent limitations in the system linker
7183 and/or object file format. On some systems, the linker is
7184 only able to arrange for variables to be aligned up to a certain maximum
7185 alignment. (For some linkers, the maximum supported alignment may
7186 be very very small.) If your linker is only able to align variables
7187 up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
7188 in an @code{__attribute__} still only provides you with 8-byte
7189 alignment. See your linker documentation for further information.
7191 Stack variables are not affected by linker restrictions; GCC can properly
7192 align them on any target.
7194 The @code{aligned} attribute can also be used for functions
7195 (@pxref{Common Function Attributes}.)
7197 @cindex @code{warn_if_not_aligned} variable attribute
7198 @item warn_if_not_aligned (@var{alignment})
7199 This attribute specifies a threshold for the structure field, measured
7200 in bytes. If the structure field is aligned below the threshold, a
7201 warning will be issued. For example, the declaration:
7208 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
7213 causes the compiler to issue an warning on @code{struct foo}, like
7214 @samp{warning: alignment 8 of 'struct foo' is less than 16}.
7215 The compiler also issues a warning, like @samp{warning: 'x' offset
7216 8 in 'struct foo' isn't aligned to 16}, when the structure field has
7217 the misaligned offset:
7220 struct __attribute__ ((aligned (16))) foo
7224 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
7228 This warning can be disabled by @option{-Wno-if-not-aligned}.
7229 The @code{warn_if_not_aligned} attribute can also be used for types
7230 (@pxref{Common Type Attributes}.)
7232 @item alloc_size (@var{position})
7233 @itemx alloc_size (@var{position-1}, @var{position-2})
7234 @cindex @code{alloc_size} variable attribute
7235 The @code{alloc_size} variable attribute may be applied to the declaration
7236 of a pointer to a function that returns a pointer and takes at least one
7237 argument of an integer type. It indicates that the returned pointer points
7238 to an object whose size is given by the function argument at @var{position-1},
7239 or by the product of the arguments at @var{position-1} and @var{position-2}.
7240 Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other
7241 sizes are disagnosed when detected. GCC uses this information to improve
7242 the results of @code{__builtin_object_size}.
7244 For instance, the following declarations
7247 typedef __attribute__ ((alloc_size (1, 2))) void*
7248 (*calloc_ptr) (size_t, size_t);
7249 typedef __attribute__ ((alloc_size (1))) void*
7250 (*malloc_ptr) (size_t);
7254 specify that @code{calloc_ptr} is a pointer of a function that, like
7255 the standard C function @code{calloc}, returns an object whose size
7256 is given by the product of arguments 1 and 2, and similarly, that
7257 @code{malloc_ptr}, like the standard C function @code{malloc},
7258 returns an object whose size is given by argument 1 to the function.
7260 @item cleanup (@var{cleanup_function})
7261 @cindex @code{cleanup} variable attribute
7262 The @code{cleanup} attribute runs a function when the variable goes
7263 out of scope. This attribute can only be applied to auto function
7264 scope variables; it may not be applied to parameters or variables
7265 with static storage duration. The function must take one parameter,
7266 a pointer to a type compatible with the variable. The return value
7267 of the function (if any) is ignored.
7269 If @option{-fexceptions} is enabled, then @var{cleanup_function}
7270 is run during the stack unwinding that happens during the
7271 processing of the exception. Note that the @code{cleanup} attribute
7272 does not allow the exception to be caught, only to perform an action.
7273 It is undefined what happens if @var{cleanup_function} does not
7278 @cindex @code{common} variable attribute
7279 @cindex @code{nocommon} variable attribute
7282 The @code{common} attribute requests GCC to place a variable in
7283 ``common'' storage. The @code{nocommon} attribute requests the
7284 opposite---to allocate space for it directly.
7286 These attributes override the default chosen by the
7287 @option{-fno-common} and @option{-fcommon} flags respectively.
7290 @itemx copy (@var{variable})
7291 @cindex @code{copy} variable attribute
7292 The @code{copy} attribute applies the set of attributes with which
7293 @var{variable} has been declared to the declaration of the variable
7294 to which the attribute is applied. The attribute is designed for
7295 libraries that define aliases that are expected to specify the same
7296 set of attributes as the aliased symbols. The @code{copy} attribute
7297 can be used with variables, functions or types. However, the kind
7298 of symbol to which the attribute is applied (either varible or
7299 function) must match the kind of symbol to which the argument refers.
7300 The @code{copy} attribute copies only syntactic and semantic attributes
7301 but not attributes that affect a symbol's linkage or visibility such as
7302 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
7303 attribute is also not copied. @xref{Common Function Attributes}.
7304 @xref{Common Type Attributes}.
7307 @itemx deprecated (@var{msg})
7308 @cindex @code{deprecated} variable attribute
7309 The @code{deprecated} attribute results in a warning if the variable
7310 is used anywhere in the source file. This is useful when identifying
7311 variables that are expected to be removed in a future version of a
7312 program. The warning also includes the location of the declaration
7313 of the deprecated variable, to enable users to easily find further
7314 information about why the variable is deprecated, or what they should
7315 do instead. Note that the warning only occurs for uses:
7318 extern int old_var __attribute__ ((deprecated));
7320 int new_fn () @{ return old_var; @}
7324 results in a warning on line 3 but not line 2. The optional @var{msg}
7325 argument, which must be a string, is printed in the warning if
7328 The @code{deprecated} attribute can also be used for functions and
7329 types (@pxref{Common Function Attributes},
7330 @pxref{Common Type Attributes}).
7332 The message attached to the attribute is affected by the setting of
7333 the @option{-fmessage-length} option.
7335 @item mode (@var{mode})
7336 @cindex @code{mode} variable attribute
7337 This attribute specifies the data type for the declaration---whichever
7338 type corresponds to the mode @var{mode}. This in effect lets you
7339 request an integer or floating-point type according to its width.
7341 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
7342 for a list of the possible keywords for @var{mode}.
7343 You may also specify a mode of @code{byte} or @code{__byte__} to
7344 indicate the mode corresponding to a one-byte integer, @code{word} or
7345 @code{__word__} for the mode of a one-word integer, and @code{pointer}
7346 or @code{__pointer__} for the mode used to represent pointers.
7349 @cindex @code{nonstring} variable attribute
7350 The @code{nonstring} variable attribute specifies that an object or member
7351 declaration with type array of @code{char}, @code{signed char}, or
7352 @code{unsigned char}, or pointer to such a type is intended to store
7353 character arrays that do not necessarily contain a terminating @code{NUL}.
7354 This is useful in detecting uses of such arrays or pointers with functions
7355 that expect @code{NUL}-terminated strings, and to avoid warnings when such
7356 an array or pointer is used as an argument to a bounded string manipulation
7357 function such as @code{strncpy}. For example, without the attribute, GCC
7358 will issue a warning for the @code{strncpy} call below because it may
7359 truncate the copy without appending the terminating @code{NUL} character.
7360 Using the attribute makes it possible to suppress the warning. However,
7361 when the array is declared with the attribute the call to @code{strlen} is
7362 diagnosed because when the array doesn't contain a @code{NUL}-terminated
7363 string the call is undefined. To copy, compare, of search non-string
7364 character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr},
7365 and other functions that operate on arrays of bytes. In addition,
7366 calling @code{strnlen} and @code{strndup} with such arrays is safe
7367 provided a suitable bound is specified, and not diagnosed.
7372 char name [32] __attribute__ ((nonstring));
7375 int f (struct Data *pd, const char *s)
7377 strncpy (pd->name, s, sizeof pd->name);
7379 return strlen (pd->name); // unsafe, gets a warning
7384 @cindex @code{packed} variable attribute
7385 The @code{packed} attribute specifies that a structure member should have
7386 the smallest possible alignment---one bit for a bit-field and one byte
7387 otherwise, unless a larger value is specified with the @code{aligned}
7388 attribute. The attribute does not apply to non-member objects.
7390 For example in the structure below, the member array @code{x} is packed
7391 so that it immediately follows @code{a} with no intervening padding:
7397 int x[2] __attribute__ ((packed));
7401 @emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
7402 @code{packed} attribute on bit-fields of type @code{char}. This has
7403 been fixed in GCC 4.4 but the change can lead to differences in the
7404 structure layout. See the documentation of
7405 @option{-Wpacked-bitfield-compat} for more information.
7407 @item section ("@var{section-name}")
7408 @cindex @code{section} variable attribute
7409 Normally, the compiler places the objects it generates in sections like
7410 @code{data} and @code{bss}. Sometimes, however, you need additional sections,
7411 or you need certain particular variables to appear in special sections,
7412 for example to map to special hardware. The @code{section}
7413 attribute specifies that a variable (or function) lives in a particular
7414 section. For example, this small program uses several specific section names:
7417 struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
7418 struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
7419 char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
7420 int init_data __attribute__ ((section ("INITDATA")));
7424 /* @r{Initialize stack pointer} */
7425 init_sp (stack + sizeof (stack));
7427 /* @r{Initialize initialized data} */
7428 memcpy (&init_data, &data, &edata - &data);
7430 /* @r{Turn on the serial ports} */
7437 Use the @code{section} attribute with
7438 @emph{global} variables and not @emph{local} variables,
7439 as shown in the example.
7441 You may use the @code{section} attribute with initialized or
7442 uninitialized global variables but the linker requires
7443 each object be defined once, with the exception that uninitialized
7444 variables tentatively go in the @code{common} (or @code{bss}) section
7445 and can be multiply ``defined''. Using the @code{section} attribute
7446 changes what section the variable goes into and may cause the
7447 linker to issue an error if an uninitialized variable has multiple
7448 definitions. You can force a variable to be initialized with the
7449 @option{-fno-common} flag or the @code{nocommon} attribute.
7451 Some file formats do not support arbitrary sections so the @code{section}
7452 attribute is not available on all platforms.
7453 If you need to map the entire contents of a module to a particular
7454 section, consider using the facilities of the linker instead.
7456 @item tls_model ("@var{tls_model}")
7457 @cindex @code{tls_model} variable attribute
7458 The @code{tls_model} attribute sets thread-local storage model
7459 (@pxref{Thread-Local}) of a particular @code{__thread} variable,
7460 overriding @option{-ftls-model=} command-line switch on a per-variable
7462 The @var{tls_model} argument should be one of @code{global-dynamic},
7463 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
7465 Not all targets support this attribute.
7468 @cindex @code{unused} variable attribute
7469 This attribute, attached to a variable, means that the variable is meant
7470 to be possibly unused. GCC does not produce a warning for this
7474 @cindex @code{used} variable attribute
7475 This attribute, attached to a variable with static storage, means that
7476 the variable must be emitted even if it appears that the variable is not
7479 When applied to a static data member of a C++ class template, the
7480 attribute also means that the member is instantiated if the
7481 class itself is instantiated.
7483 For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
7484 will also save the variable from linker garbage collection. To support
7485 this behavior, variables that have not been placed in specific sections
7486 (e.g. by the @code{section} attribute, or the @code{-fdata-sections} option),
7487 will be placed in new, unique sections.
7489 This additional functionality requires Binutils version 2.36 or later.
7491 @item vector_size (@var{bytes})
7492 @cindex @code{vector_size} variable attribute
7493 This attribute specifies the vector size for the type of the declared
7494 variable, measured in bytes. The type to which it applies is known as
7495 the @dfn{base type}. The @var{bytes} argument must be a positive
7496 power-of-two multiple of the base type size. For example, the declaration:
7499 int foo __attribute__ ((vector_size (16)));
7503 causes the compiler to set the mode for @code{foo}, to be 16 bytes,
7504 divided into @code{int} sized units. Assuming a 32-bit @code{int},
7505 @code{foo}'s type is a vector of four units of four bytes each, and
7506 the corresponding mode of @code{foo} is @code{V4SI}.
7507 @xref{Vector Extensions}, for details of manipulating vector variables.
7509 This attribute is only applicable to integral and floating scalars,
7510 although arrays, pointers, and function return values are allowed in
7511 conjunction with this construct.
7513 Aggregates with this attribute are invalid, even if they are of the same
7514 size as a corresponding scalar. For example, the declaration:
7517 struct S @{ int a; @};
7518 struct S __attribute__ ((vector_size (16))) foo;
7522 is invalid even if the size of the structure is the same as the size of
7525 @item visibility ("@var{visibility_type}")
7526 @cindex @code{visibility} variable attribute
7527 This attribute affects the linkage of the declaration to which it is attached.
7528 The @code{visibility} attribute is described in
7529 @ref{Common Function Attributes}.
7532 @cindex @code{weak} variable attribute
7533 The @code{weak} attribute is described in
7534 @ref{Common Function Attributes}.
7537 @cindex @code{noinit} variable attribute
7538 Any data with the @code{noinit} attribute will not be initialized by
7539 the C runtime startup code, or the program loader. Not initializing
7540 data in this way can reduce program startup times.
7542 This attribute is specific to ELF targets and relies on the linker
7543 script to place sections with the @code{.noinit} prefix in the right
7547 @cindex @code{persistent} variable attribute
7548 Any data with the @code{persistent} attribute will not be initialized by
7549 the C runtime startup code, but will be initialized by the program
7550 loader. This enables the value of the variable to @samp{persist}
7551 between processor resets.
7553 This attribute is specific to ELF targets and relies on the linker
7554 script to place the sections with the @code{.persistent} prefix in the
7555 right location. Specifically, some type of non-volatile, writeable
7558 @item objc_nullability (@var{nullability kind}) @r{(Objective-C and Objective-C++ only)}
7559 @cindex @code{objc_nullability} variable attribute
7560 This attribute applies to pointer variables only. It allows marking the
7561 pointer with one of four possible values describing the conditions under
7562 which the pointer might have a @code{nil} value. In most cases, the
7563 attribute is intended to be an internal representation for property and
7564 method nullability (specified by language keywords); it is not recommended
7567 When @var{nullability kind} is @code{"unspecified"} or @code{0}, nothing is
7568 known about the conditions in which the pointer might be @code{nil}. Making
7569 this state specific serves to avoid false positives in diagnostics.
7571 When @var{nullability kind} is @code{"nonnull"} or @code{1}, the pointer has
7572 no meaning if it is @code{nil} and thus the compiler is free to emit
7573 diagnostics if it can be determined that the value will be @code{nil}.
7575 When @var{nullability kind} is @code{"nullable"} or @code{2}, the pointer might
7576 be @code{nil} and carry meaning as such.
7578 When @var{nullability kind} is @code{"resettable"} or @code{3} (used only in
7579 the context of property attribute lists) this describes the case in which a
7580 property setter may take the value @code{nil} (which perhaps causes the
7581 property to be reset in some manner to a default) but for which the property
7582 getter will never validly return @code{nil}.
7586 @node ARC Variable Attributes
7587 @subsection ARC Variable Attributes
7591 @cindex @code{aux} variable attribute, ARC
7592 The @code{aux} attribute is used to directly access the ARC's
7593 auxiliary register space from C. The auxilirary register number is
7594 given via attribute argument.
7598 @node AVR Variable Attributes
7599 @subsection AVR Variable Attributes
7603 @cindex @code{progmem} variable attribute, AVR
7604 The @code{progmem} attribute is used on the AVR to place read-only
7605 data in the non-volatile program memory (flash). The @code{progmem}
7606 attribute accomplishes this by putting respective variables into a
7607 section whose name starts with @code{.progmem}.
7609 This attribute works similar to the @code{section} attribute
7610 but adds additional checking.
7613 @item @bullet{}@tie{} Ordinary AVR cores with 32 general purpose registers:
7614 @code{progmem} affects the location
7615 of the data but not how this data is accessed.
7616 In order to read data located with the @code{progmem} attribute
7617 (inline) assembler must be used.
7619 /* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */
7620 #include <avr/pgmspace.h>
7622 /* Locate var in flash memory */
7623 const int var[2] PROGMEM = @{ 1, 2 @};
7625 int read_var (int i)
7627 /* Access var[] by accessor macro from avr/pgmspace.h */
7628 return (int) pgm_read_word (& var[i]);
7632 AVR is a Harvard architecture processor and data and read-only data
7633 normally resides in the data memory (RAM).
7635 See also the @ref{AVR Named Address Spaces} section for
7636 an alternate way to locate and access data in flash memory.
7638 @item @bullet{}@tie{} AVR cores with flash memory visible in the RAM address range:
7639 On such devices, there is no need for attribute @code{progmem} or
7640 @ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all.
7641 Just use standard C / C++. The compiler will generate @code{LD*}
7642 instructions. As flash memory is visible in the RAM address range,
7643 and the default linker script does @emph{not} locate @code{.rodata} in
7644 RAM, no special features are needed in order not to waste RAM for
7645 read-only data or to read from flash. You might even get slightly better
7647 avoiding @code{progmem} and @code{__flash}. This applies to devices from
7648 families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for
7651 @item @bullet{}@tie{}Reduced AVR Tiny cores like ATtiny40:
7652 The compiler adds @code{0x4000}
7653 to the addresses of objects and declarations in @code{progmem} and locates
7654 the objects in flash memory, namely in section @code{.progmem.data}.
7655 The offset is needed because the flash memory is visible in the RAM
7656 address space starting at address @code{0x4000}.
7658 Data in @code{progmem} can be accessed by means of ordinary C@tie{}code,
7659 no special functions or macros are needed.
7662 /* var is located in flash memory */
7663 extern const int var[2] __attribute__((progmem));
7665 int read_var (int i)
7671 Please notice that on these devices, there is no need for @code{progmem}
7677 @itemx io (@var{addr})
7678 @cindex @code{io} variable attribute, AVR
7679 Variables with the @code{io} attribute are used to address
7680 memory-mapped peripherals in the io address range.
7681 If an address is specified, the variable
7682 is assigned that address, and the value is interpreted as an
7683 address in the data address space.
7687 volatile int porta __attribute__((io (0x22)));
7690 The address specified in the address in the data address range.
7692 Otherwise, the variable it is not assigned an address, but the
7693 compiler will still use in/out instructions where applicable,
7694 assuming some other module assigns an address in the io address range.
7698 extern volatile int porta __attribute__((io));
7702 @itemx io_low (@var{addr})
7703 @cindex @code{io_low} variable attribute, AVR
7704 This is like the @code{io} attribute, but additionally it informs the
7705 compiler that the object lies in the lower half of the I/O area,
7706 allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis}
7710 @itemx address (@var{addr})
7711 @cindex @code{address} variable attribute, AVR
7712 Variables with the @code{address} attribute are used to address
7713 memory-mapped peripherals that may lie outside the io address range.
7716 volatile int porta __attribute__((address (0x600)));
7720 @cindex @code{absdata} variable attribute, AVR
7721 Variables in static storage and with the @code{absdata} attribute can
7722 be accessed by the @code{LDS} and @code{STS} instructions which take
7727 This attribute is only supported for the reduced AVR Tiny core
7731 You must make sure that respective data is located in the
7732 address range @code{0x40}@dots{}@code{0xbf} accessible by
7733 @code{LDS} and @code{STS}. One way to achieve this as an
7734 appropriate linker description file.
7737 If the location does not fit the address range of @code{LDS}
7738 and @code{STS}, there is currently (Binutils 2.26) just an unspecific
7741 @code{module.c:(.text+0x1c): warning: internal error: out of range error}
7746 See also the @option{-mabsdata} @ref{AVR Options,command-line option}.
7750 @node Blackfin Variable Attributes
7751 @subsection Blackfin Variable Attributes
7753 Three attributes are currently defined for the Blackfin.
7759 @cindex @code{l1_data} variable attribute, Blackfin
7760 @cindex @code{l1_data_A} variable attribute, Blackfin
7761 @cindex @code{l1_data_B} variable attribute, Blackfin
7762 Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
7763 Variables with @code{l1_data} attribute are put into the specific section
7764 named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into
7765 the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
7766 attribute are put into the specific section named @code{.l1.data.B}.
7769 @cindex @code{l2} variable attribute, Blackfin
7770 Use this attribute on the Blackfin to place the variable into L2 SRAM.
7771 Variables with @code{l2} attribute are put into the specific section
7772 named @code{.l2.data}.
7775 @node H8/300 Variable Attributes
7776 @subsection H8/300 Variable Attributes
7778 These variable attributes are available for H8/300 targets:
7782 @cindex @code{eightbit_data} variable attribute, H8/300
7783 @cindex eight-bit data on the H8/300, H8/300H, and H8S
7784 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
7785 variable should be placed into the eight-bit data section.
7786 The compiler generates more efficient code for certain operations
7787 on data in the eight-bit data area. Note the eight-bit data area is limited to
7790 You must use GAS and GLD from GNU binutils version 2.7 or later for
7791 this attribute to work correctly.
7794 @cindex @code{tiny_data} variable attribute, H8/300
7795 @cindex tiny data section on the H8/300H and H8S
7796 Use this attribute on the H8/300H and H8S to indicate that the specified
7797 variable should be placed into the tiny data section.
7798 The compiler generates more efficient code for loads and stores
7799 on data in the tiny data section. Note the tiny data area is limited to
7800 slightly under 32KB of data.
7804 @node IA-64 Variable Attributes
7805 @subsection IA-64 Variable Attributes
7807 The IA-64 back end supports the following variable attribute:
7810 @item model (@var{model-name})
7811 @cindex @code{model} variable attribute, IA-64
7813 On IA-64, use this attribute to set the addressability of an object.
7814 At present, the only supported identifier for @var{model-name} is
7815 @code{small}, indicating addressability via ``small'' (22-bit)
7816 addresses (so that their addresses can be loaded with the @code{addl}
7817 instruction). Caveat: such addressing is by definition not position
7818 independent and hence this attribute must not be used for objects
7819 defined by shared libraries.
7823 @node M32R/D Variable Attributes
7824 @subsection M32R/D Variable Attributes
7826 One attribute is currently defined for the M32R/D@.
7829 @item model (@var{model-name})
7830 @cindex @code{model-name} variable attribute, M32R/D
7831 @cindex variable addressability on the M32R/D
7832 Use this attribute on the M32R/D to set the addressability of an object.
7833 The identifier @var{model-name} is one of @code{small}, @code{medium},
7834 or @code{large}, representing each of the code models.
7836 Small model objects live in the lower 16MB of memory (so that their
7837 addresses can be loaded with the @code{ld24} instruction).
7839 Medium and large model objects may live anywhere in the 32-bit address space
7840 (the compiler generates @code{seth/add3} instructions to load their
7844 @node MeP Variable Attributes
7845 @subsection MeP Variable Attributes
7847 The MeP target has a number of addressing modes and busses. The
7848 @code{near} space spans the standard memory space's first 16 megabytes
7849 (24 bits). The @code{far} space spans the entire 32-bit memory space.
7850 The @code{based} space is a 128-byte region in the memory space that
7851 is addressed relative to the @code{$tp} register. The @code{tiny}
7852 space is a 65536-byte region relative to the @code{$gp} register. In
7853 addition to these memory regions, the MeP target has a separate 16-bit
7854 control bus which is specified with @code{cb} attributes.
7859 @cindex @code{based} variable attribute, MeP
7860 Any variable with the @code{based} attribute is assigned to the
7861 @code{.based} section, and is accessed with relative to the
7862 @code{$tp} register.
7865 @cindex @code{tiny} variable attribute, MeP
7866 Likewise, the @code{tiny} attribute assigned variables to the
7867 @code{.tiny} section, relative to the @code{$gp} register.
7870 @cindex @code{near} variable attribute, MeP
7871 Variables with the @code{near} attribute are assumed to have addresses
7872 that fit in a 24-bit addressing mode. This is the default for large
7873 variables (@code{-mtiny=4} is the default) but this attribute can
7874 override @code{-mtiny=} for small variables, or override @code{-ml}.
7877 @cindex @code{far} variable attribute, MeP
7878 Variables with the @code{far} attribute are addressed using a full
7879 32-bit address. Since this covers the entire memory space, this
7880 allows modules to make no assumptions about where variables might be
7884 @cindex @code{io} variable attribute, MeP
7885 @itemx io (@var{addr})
7886 Variables with the @code{io} attribute are used to address
7887 memory-mapped peripherals. If an address is specified, the variable
7888 is assigned that address, else it is not assigned an address (it is
7889 assumed some other module assigns an address). Example:
7892 int timer_count __attribute__((io(0x123)));
7896 @itemx cb (@var{addr})
7897 @cindex @code{cb} variable attribute, MeP
7898 Variables with the @code{cb} attribute are used to access the control
7899 bus, using special instructions. @code{addr} indicates the control bus
7903 int cpu_clock __attribute__((cb(0x123)));
7908 @node Microsoft Windows Variable Attributes
7909 @subsection Microsoft Windows Variable Attributes
7911 You can use these attributes on Microsoft Windows targets.
7912 @ref{x86 Variable Attributes} for additional Windows compatibility
7913 attributes available on all x86 targets.
7918 @cindex @code{dllimport} variable attribute
7919 @cindex @code{dllexport} variable attribute
7920 The @code{dllimport} and @code{dllexport} attributes are described in
7921 @ref{Microsoft Windows Function Attributes}.
7924 @cindex @code{selectany} variable attribute
7925 The @code{selectany} attribute causes an initialized global variable to
7926 have link-once semantics. When multiple definitions of the variable are
7927 encountered by the linker, the first is selected and the remainder are
7928 discarded. Following usage by the Microsoft compiler, the linker is told
7929 @emph{not} to warn about size or content differences of the multiple
7932 Although the primary usage of this attribute is for POD types, the
7933 attribute can also be applied to global C++ objects that are initialized
7934 by a constructor. In this case, the static initialization and destruction
7935 code for the object is emitted in each translation defining the object,
7936 but the calls to the constructor and destructor are protected by a
7937 link-once guard variable.
7939 The @code{selectany} attribute is only available on Microsoft Windows
7940 targets. You can use @code{__declspec (selectany)} as a synonym for
7941 @code{__attribute__ ((selectany))} for compatibility with other
7945 @cindex @code{shared} variable attribute
7946 On Microsoft Windows, in addition to putting variable definitions in a named
7947 section, the section can also be shared among all running copies of an
7948 executable or DLL@. For example, this small program defines shared data
7949 by putting it in a named section @code{shared} and marking the section
7953 int foo __attribute__((section ("shared"), shared)) = 0;
7958 /* @r{Read and write foo. All running
7959 copies see the same value.} */
7965 You may only use the @code{shared} attribute along with @code{section}
7966 attribute with a fully-initialized global definition because of the way
7967 linkers work. See @code{section} attribute for more information.
7969 The @code{shared} attribute is only available on Microsoft Windows@.
7973 @node MSP430 Variable Attributes
7974 @subsection MSP430 Variable Attributes
7979 @cindex @code{upper} variable attribute, MSP430
7980 @cindex @code{either} variable attribute, MSP430
7981 These attributes are the same as the MSP430 function attributes of the
7982 same name (@pxref{MSP430 Function Attributes}).
7985 @cindex @code{lower} variable attribute, MSP430
7986 This option behaves mostly the same as the MSP430 function attribute of the
7987 same name (@pxref{MSP430 Function Attributes}), but it has some additional
7990 If @option{-mdata-region=}@{@code{upper,either,none}@} has been passed, or
7991 the @code{section} attribute is applied to a variable, the compiler will
7992 generate 430X instructions to handle it. This is because the compiler has
7993 to assume that the variable could get placed in the upper memory region
7994 (above address 0xFFFF). Marking the variable with the @code{lower} attribute
7995 informs the compiler that the variable will be placed in lower memory so it
7996 is safe to use 430 instructions to handle it.
7998 In the case of the @code{section} attribute, the section name given
7999 will be used, and the @code{.lower} prefix will not be added.
8003 @node Nvidia PTX Variable Attributes
8004 @subsection Nvidia PTX Variable Attributes
8006 These variable attributes are supported by the Nvidia PTX back end:
8010 @cindex @code{shared} attribute, Nvidia PTX
8011 Use this attribute to place a variable in the @code{.shared} memory space.
8012 This memory space is private to each cooperative thread array; only threads
8013 within one thread block refer to the same instance of the variable.
8014 The runtime does not initialize variables in this memory space.
8017 @node PowerPC Variable Attributes
8018 @subsection PowerPC Variable Attributes
8020 Three attributes currently are defined for PowerPC configurations:
8021 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
8023 @cindex @code{ms_struct} variable attribute, PowerPC
8024 @cindex @code{gcc_struct} variable attribute, PowerPC
8025 For full documentation of the struct attributes please see the
8026 documentation in @ref{x86 Variable Attributes}.
8028 @cindex @code{altivec} variable attribute, PowerPC
8029 For documentation of @code{altivec} attribute please see the
8030 documentation in @ref{PowerPC Type Attributes}.
8032 @node RL78 Variable Attributes
8033 @subsection RL78 Variable Attributes
8035 @cindex @code{saddr} variable attribute, RL78
8036 The RL78 back end supports the @code{saddr} variable attribute. This
8037 specifies placement of the corresponding variable in the SADDR area,
8038 which can be accessed more efficiently than the default memory region.
8040 @node V850 Variable Attributes
8041 @subsection V850 Variable Attributes
8043 These variable attributes are supported by the V850 back end:
8048 @cindex @code{sda} variable attribute, V850
8049 Use this attribute to explicitly place a variable in the small data area,
8050 which can hold up to 64 kilobytes.
8053 @cindex @code{tda} variable attribute, V850
8054 Use this attribute to explicitly place a variable in the tiny data area,
8055 which can hold up to 256 bytes in total.
8058 @cindex @code{zda} variable attribute, V850
8059 Use this attribute to explicitly place a variable in the first 32 kilobytes
8063 @node x86 Variable Attributes
8064 @subsection x86 Variable Attributes
8066 Two attributes are currently defined for x86 configurations:
8067 @code{ms_struct} and @code{gcc_struct}.
8072 @cindex @code{ms_struct} variable attribute, x86
8073 @cindex @code{gcc_struct} variable attribute, x86
8075 If @code{packed} is used on a structure, or if bit-fields are used,
8076 it may be that the Microsoft ABI lays out the structure differently
8077 than the way GCC normally does. Particularly when moving packed
8078 data between functions compiled with GCC and the native Microsoft compiler
8079 (either via function call or as data in a file), it may be necessary to access
8082 The @code{ms_struct} and @code{gcc_struct} attributes correspond
8083 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
8084 command-line options, respectively;
8085 see @ref{x86 Options}, for details of how structure layout is affected.
8086 @xref{x86 Type Attributes}, for information about the corresponding
8087 attributes on types.
8091 @node Xstormy16 Variable Attributes
8092 @subsection Xstormy16 Variable Attributes
8094 One attribute is currently defined for xstormy16 configurations:
8099 @cindex @code{below100} variable attribute, Xstormy16
8101 If a variable has the @code{below100} attribute (@code{BELOW100} is
8102 allowed also), GCC places the variable in the first 0x100 bytes of
8103 memory and use special opcodes to access it. Such variables are
8104 placed in either the @code{.bss_below100} section or the
8105 @code{.data_below100} section.
8109 @node Type Attributes
8110 @section Specifying Attributes of Types
8111 @cindex attribute of types
8112 @cindex type attributes
8114 The keyword @code{__attribute__} allows you to specify various special
8115 properties of types. Some type attributes apply only to structure and
8116 union types, and in C++, also class types, while others can apply to
8117 any type defined via a @code{typedef} declaration. Unless otherwise
8118 specified, the same restrictions and effects apply to attributes regardless
8119 of whether a type is a trivial structure or a C++ class with user-defined
8120 constructors, destructors, or a copy assignment.
8122 Other attributes are defined for functions (@pxref{Function Attributes}),
8123 labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator
8124 Attributes}), statements (@pxref{Statement Attributes}), and for variables
8125 (@pxref{Variable Attributes}).
8127 The @code{__attribute__} keyword is followed by an attribute specification
8128 enclosed in double parentheses.
8130 You may specify type attributes in an enum, struct or union type
8131 declaration or definition by placing them immediately after the
8132 @code{struct}, @code{union} or @code{enum} keyword. You can also place
8133 them just past the closing curly brace of the definition, but this is less
8134 preferred because logically the type should be fully defined at
8137 You can also include type attributes in a @code{typedef} declaration.
8138 @xref{Attribute Syntax}, for details of the exact syntax for using
8142 * Common Type Attributes::
8143 * ARC Type Attributes::
8144 * ARM Type Attributes::
8145 * MeP Type Attributes::
8146 * PowerPC Type Attributes::
8147 * x86 Type Attributes::
8150 @node Common Type Attributes
8151 @subsection Common Type Attributes
8153 The following type attributes are supported on most targets.
8156 @cindex @code{aligned} type attribute
8158 @itemx aligned (@var{alignment})
8159 The @code{aligned} attribute specifies a minimum alignment (in bytes) for
8160 variables of the specified type. When specified, @var{alignment} must be
8161 a power of 2. Specifying no @var{alignment} argument implies the maximum
8162 alignment for the target, which is often, but by no means always, 8 or 16
8163 bytes. For example, the declarations:
8166 struct __attribute__ ((aligned (8))) S @{ short f[3]; @};
8167 typedef int more_aligned_int __attribute__ ((aligned (8)));
8171 force the compiler to ensure (as far as it can) that each variable whose
8172 type is @code{struct S} or @code{more_aligned_int} is allocated and
8173 aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all
8174 variables of type @code{struct S} aligned to 8-byte boundaries allows
8175 the compiler to use the @code{ldd} and @code{std} (doubleword load and
8176 store) instructions when copying one variable of type @code{struct S} to
8177 another, thus improving run-time efficiency.
8179 Note that the alignment of any given @code{struct} or @code{union} type
8180 is required by the ISO C standard to be at least a perfect multiple of
8181 the lowest common multiple of the alignments of all of the members of
8182 the @code{struct} or @code{union} in question. This means that you @emph{can}
8183 effectively adjust the alignment of a @code{struct} or @code{union}
8184 type by attaching an @code{aligned} attribute to any one of the members
8185 of such a type, but the notation illustrated in the example above is a
8186 more obvious, intuitive, and readable way to request the compiler to
8187 adjust the alignment of an entire @code{struct} or @code{union} type.
8189 As in the preceding example, you can explicitly specify the alignment
8190 (in bytes) that you wish the compiler to use for a given @code{struct}
8191 or @code{union} type. Alternatively, you can leave out the alignment factor
8192 and just ask the compiler to align a type to the maximum
8193 useful alignment for the target machine you are compiling for. For
8194 example, you could write:
8197 struct __attribute__ ((aligned)) S @{ short f[3]; @};
8200 Whenever you leave out the alignment factor in an @code{aligned}
8201 attribute specification, the compiler automatically sets the alignment
8202 for the type to the largest alignment that is ever used for any data
8203 type on the target machine you are compiling for. Doing this can often
8204 make copy operations more efficient, because the compiler can use
8205 whatever instructions copy the biggest chunks of memory when performing
8206 copies to or from the variables that have types that you have aligned
8209 In the example above, if the size of each @code{short} is 2 bytes, then
8210 the size of the entire @code{struct S} type is 6 bytes. The smallest
8211 power of two that is greater than or equal to that is 8, so the
8212 compiler sets the alignment for the entire @code{struct S} type to 8
8215 Note that although you can ask the compiler to select a time-efficient
8216 alignment for a given type and then declare only individual stand-alone
8217 objects of that type, the compiler's ability to select a time-efficient
8218 alignment is primarily useful only when you plan to create arrays of
8219 variables having the relevant (efficiently aligned) type. If you
8220 declare or use arrays of variables of an efficiently-aligned type, then
8221 it is likely that your program also does pointer arithmetic (or
8222 subscripting, which amounts to the same thing) on pointers to the
8223 relevant type, and the code that the compiler generates for these
8224 pointer arithmetic operations is often more efficient for
8225 efficiently-aligned types than for other types.
8227 Note that the effectiveness of @code{aligned} attributes may be limited
8228 by inherent limitations in your linker. On many systems, the linker is
8229 only able to arrange for variables to be aligned up to a certain maximum
8230 alignment. (For some linkers, the maximum supported alignment may
8231 be very very small.) If your linker is only able to align variables
8232 up to a maximum of 8-byte alignment, then specifying @code{aligned (16)}
8233 in an @code{__attribute__} still only provides you with 8-byte
8234 alignment. See your linker documentation for further information.
8236 When used on a struct, or struct member, the @code{aligned} attribute can
8237 only increase the alignment; in order to decrease it, the @code{packed}
8238 attribute must be specified as well. When used as part of a typedef, the
8239 @code{aligned} attribute can both increase and decrease alignment, and
8240 specifying the @code{packed} attribute generates a warning.
8242 @cindex @code{warn_if_not_aligned} type attribute
8243 @item warn_if_not_aligned (@var{alignment})
8244 This attribute specifies a threshold for the structure field, measured
8245 in bytes. If the structure field is aligned below the threshold, a
8246 warning will be issued. For example, the declaration:
8249 typedef unsigned long long __u64
8250 __attribute__((aligned (4), warn_if_not_aligned (8)));
8261 causes the compiler to issue an warning on @code{struct foo}, like
8262 @samp{warning: alignment 4 of 'struct foo' is less than 8}.
8263 It is used to define @code{struct foo} in such a way that
8264 @code{struct foo} has the same layout and the structure field @code{x}
8265 has the same alignment when @code{__u64} is aligned at either 4 or
8266 8 bytes. Align @code{struct foo} to 8 bytes:
8269 struct __attribute__ ((aligned (8))) foo
8278 silences the warning. The compiler also issues a warning, like
8279 @samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8},
8280 when the structure field has the misaligned offset:
8283 struct __attribute__ ((aligned (8))) foo
8292 This warning can be disabled by @option{-Wno-if-not-aligned}.
8294 @item alloc_size (@var{position})
8295 @itemx alloc_size (@var{position-1}, @var{position-2})
8296 @cindex @code{alloc_size} type attribute
8297 The @code{alloc_size} type attribute may be applied to the definition
8298 of a type of a function that returns a pointer and takes at least one
8299 argument of an integer type. It indicates that the returned pointer
8300 points to an object whose size is given by the function argument at
8301 @var{position-1}, or by the product of the arguments at @var{position-1}
8302 and @var{position-2}. Meaningful sizes are positive values less than
8303 @code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses
8304 this information to improve the results of @code{__builtin_object_size}.
8306 For instance, the following declarations
8309 typedef __attribute__ ((alloc_size (1, 2))) void*
8310 calloc_type (size_t, size_t);
8311 typedef __attribute__ ((alloc_size (1))) void*
8312 malloc_type (size_t);
8316 specify that @code{calloc_type} is a type of a function that, like
8317 the standard C function @code{calloc}, returns an object whose size
8318 is given by the product of arguments 1 and 2, and that
8319 @code{malloc_type}, like the standard C function @code{malloc},
8320 returns an object whose size is given by argument 1 to the function.
8323 @itemx copy (@var{expression})
8324 @cindex @code{copy} type attribute
8325 The @code{copy} attribute applies the set of attributes with which
8326 the type of the @var{expression} has been declared to the declaration
8327 of the type to which the attribute is applied. The attribute is
8328 designed for libraries that define aliases that are expected to
8329 specify the same set of attributes as the aliased symbols.
8330 The @code{copy} attribute can be used with types, variables, or
8331 functions. However, the kind of symbol to which the attribute is
8332 applied (either varible or function) must match the kind of symbol
8333 to which the argument refers.
8334 The @code{copy} attribute copies only syntactic and semantic attributes
8335 but not attributes that affect a symbol's linkage or visibility such as
8336 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
8337 attribute is also not copied. @xref{Common Function Attributes}.
8338 @xref{Common Variable Attributes}.
8340 For example, suppose @code{struct A} below is defined in some third
8341 party library header to have the alignment requirement @code{N} and
8342 to force a warning whenever a variable of the type is not so aligned
8343 due to attribute @code{packed}. Specifying the @code{copy} attribute
8344 on the definition on the unrelated @code{struct B} has the effect of
8345 copying all relevant attributes from the type referenced by the pointer
8346 expression to @code{struct B}.
8349 struct __attribute__ ((aligned (N), warn_if_not_aligned (N)))
8350 A @{ /* @r{@dots{}} */ @};
8351 struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @};
8355 @itemx deprecated (@var{msg})
8356 @cindex @code{deprecated} type attribute
8357 The @code{deprecated} attribute results in a warning if the type
8358 is used anywhere in the source file. This is useful when identifying
8359 types that are expected to be removed in a future version of a program.
8360 If possible, the warning also includes the location of the declaration
8361 of the deprecated type, to enable users to easily find further
8362 information about why the type is deprecated, or what they should do
8363 instead. Note that the warnings only occur for uses and then only
8364 if the type is being applied to an identifier that itself is not being
8365 declared as deprecated.
8368 typedef int T1 __attribute__ ((deprecated));
8372 typedef T1 T3 __attribute__ ((deprecated));
8373 T3 z __attribute__ ((deprecated));
8377 results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
8378 warning is issued for line 4 because T2 is not explicitly
8379 deprecated. Line 5 has no warning because T3 is explicitly
8380 deprecated. Similarly for line 6. The optional @var{msg}
8381 argument, which must be a string, is printed in the warning if
8382 present. Control characters in the string will be replaced with
8383 escape sequences, and if the @option{-fmessage-length} option is set
8384 to 0 (its default value) then any newline characters will be ignored.
8386 The @code{deprecated} attribute can also be used for functions and
8387 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
8389 The message attached to the attribute is affected by the setting of
8390 the @option{-fmessage-length} option.
8392 @item designated_init
8393 @cindex @code{designated_init} type attribute
8394 This attribute may only be applied to structure types. It indicates
8395 that any initialization of an object of this type must use designated
8396 initializers rather than positional initializers. The intent of this
8397 attribute is to allow the programmer to indicate that a structure's
8398 layout may change, and that therefore relying on positional
8399 initialization will result in future breakage.
8401 GCC emits warnings based on this attribute by default; use
8402 @option{-Wno-designated-init} to suppress them.
8405 @cindex @code{may_alias} type attribute
8406 Accesses through pointers to types with this attribute are not subject
8407 to type-based alias analysis, but are instead assumed to be able to alias
8408 any other type of objects.
8409 In the context of section 6.5 paragraph 7 of the C99 standard,
8410 an lvalue expression
8411 dereferencing such a pointer is treated like having a character type.
8412 See @option{-fstrict-aliasing} for more information on aliasing issues.
8413 This extension exists to support some vector APIs, in which pointers to
8414 one vector type are permitted to alias pointers to a different vector type.
8416 Note that an object of a type with this attribute does not have any
8422 typedef short __attribute__ ((__may_alias__)) short_a;
8428 short_a *b = (short_a *) &a;
8432 if (a == 0x12345678)
8440 If you replaced @code{short_a} with @code{short} in the variable
8441 declaration, the above program would abort when compiled with
8442 @option{-fstrict-aliasing}, which is on by default at @option{-O2} or
8445 @item mode (@var{mode})
8446 @cindex @code{mode} type attribute
8447 This attribute specifies the data type for the declaration---whichever
8448 type corresponds to the mode @var{mode}. This in effect lets you
8449 request an integer or floating-point type according to its width.
8451 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
8452 for a list of the possible keywords for @var{mode}.
8453 You may also specify a mode of @code{byte} or @code{__byte__} to
8454 indicate the mode corresponding to a one-byte integer, @code{word} or
8455 @code{__word__} for the mode of a one-word integer, and @code{pointer}
8456 or @code{__pointer__} for the mode used to represent pointers.
8459 @cindex @code{packed} type attribute
8460 This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class}
8461 type definition, specifies that each of its members (other than zero-width
8462 bit-fields) is placed to minimize the memory required. This is equivalent
8463 to specifying the @code{packed} attribute on each of the members.
8465 @opindex fshort-enums
8466 When attached to an @code{enum} definition, the @code{packed} attribute
8467 indicates that the smallest integral type should be used.
8468 Specifying the @option{-fshort-enums} flag on the command line
8469 is equivalent to specifying the @code{packed}
8470 attribute on all @code{enum} definitions.
8472 In the following example @code{struct my_packed_struct}'s members are
8473 packed closely together, but the internal layout of its @code{s} member
8474 is not packed---to do that, @code{struct my_unpacked_struct} needs to
8478 struct my_unpacked_struct
8484 struct __attribute__ ((__packed__)) my_packed_struct
8488 struct my_unpacked_struct s;
8492 You may only specify the @code{packed} attribute on the definition
8493 of an @code{enum}, @code{struct}, @code{union}, or @code{class},
8494 not on a @code{typedef} that does not also define the enumerated type,
8495 structure, union, or class.
8497 @item scalar_storage_order ("@var{endianness}")
8498 @cindex @code{scalar_storage_order} type attribute
8499 When attached to a @code{union} or a @code{struct}, this attribute sets
8500 the storage order, aka endianness, of the scalar fields of the type, as
8501 well as the array fields whose component is scalar. The supported
8502 endiannesses are @code{big-endian} and @code{little-endian}. The attribute
8503 has no effects on fields which are themselves a @code{union}, a @code{struct}
8504 or an array whose component is a @code{union} or a @code{struct}, and it is
8505 possible for these fields to have a different scalar storage order than the
8508 This attribute is supported only for targets that use a uniform default
8509 scalar storage order (fortunately, most of them), i.e.@: targets that store
8510 the scalars either all in big-endian or all in little-endian.
8512 Additional restrictions are enforced for types with the reverse scalar
8513 storage order with regard to the scalar storage order of the target:
8516 @item Taking the address of a scalar field of a @code{union} or a
8517 @code{struct} with reverse scalar storage order is not permitted and yields
8519 @item Taking the address of an array field, whose component is scalar, of
8520 a @code{union} or a @code{struct} with reverse scalar storage order is
8521 permitted but yields a warning, unless @option{-Wno-scalar-storage-order}
8523 @item Taking the address of a @code{union} or a @code{struct} with reverse
8524 scalar storage order is permitted.
8527 These restrictions exist because the storage order attribute is lost when
8528 the address of a scalar or the address of an array with scalar component is
8529 taken, so storing indirectly through this address generally does not work.
8530 The second case is nevertheless allowed to be able to perform a block copy
8531 from or to the array.
8533 Moreover, the use of type punning or aliasing to toggle the storage order
8534 is not supported; that is to say, a given scalar object cannot be accessed
8535 through distinct types that assign a different storage order to it.
8537 @item transparent_union
8538 @cindex @code{transparent_union} type attribute
8540 This attribute, attached to a @code{union} type definition, indicates
8541 that any function parameter having that union type causes calls to that
8542 function to be treated in a special way.
8544 First, the argument corresponding to a transparent union type can be of
8545 any type in the union; no cast is required. Also, if the union contains
8546 a pointer type, the corresponding argument can be a null pointer
8547 constant or a void pointer expression; and if the union contains a void
8548 pointer type, the corresponding argument can be any pointer expression.
8549 If the union member type is a pointer, qualifiers like @code{const} on
8550 the referenced type must be respected, just as with normal pointer
8553 Second, the argument is passed to the function using the calling
8554 conventions of the first member of the transparent union, not the calling
8555 conventions of the union itself. All members of the union must have the
8556 same machine representation; this is necessary for this argument passing
8559 Transparent unions are designed for library functions that have multiple
8560 interfaces for compatibility reasons. For example, suppose the
8561 @code{wait} function must accept either a value of type @code{int *} to
8562 comply with POSIX, or a value of type @code{union wait *} to comply with
8563 the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
8564 @code{wait} would accept both kinds of arguments, but it would also
8565 accept any other pointer type and this would make argument type checking
8566 less useful. Instead, @code{<sys/wait.h>} might define the interface
8570 typedef union __attribute__ ((__transparent_union__))
8574 @} wait_status_ptr_t;
8576 pid_t wait (wait_status_ptr_t);
8580 This interface allows either @code{int *} or @code{union wait *}
8581 arguments to be passed, using the @code{int *} calling convention.
8582 The program can call @code{wait} with arguments of either type:
8585 int w1 () @{ int w; return wait (&w); @}
8586 int w2 () @{ union wait w; return wait (&w); @}
8590 With this interface, @code{wait}'s implementation might look like this:
8593 pid_t wait (wait_status_ptr_t p)
8595 return waitpid (-1, p.__ip, 0);
8600 @cindex @code{unused} type attribute
8601 When attached to a type (including a @code{union} or a @code{struct}),
8602 this attribute means that variables of that type are meant to appear
8603 possibly unused. GCC does not produce a warning for any variables of
8604 that type, even if the variable appears to do nothing. This is often
8605 the case with lock or thread classes, which are usually defined and then
8606 not referenced, but contain constructors and destructors that have
8607 nontrivial bookkeeping functions.
8609 @item vector_size (@var{bytes})
8610 @cindex @code{vector_size} type attribute
8611 This attribute specifies the vector size for the type, measured in bytes.
8612 The type to which it applies is known as the @dfn{base type}. The @var{bytes}
8613 argument must be a positive power-of-two multiple of the base type size. For
8614 example, the following declarations:
8617 typedef __attribute__ ((vector_size (32))) int int_vec32_t ;
8618 typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t;
8619 typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3];
8623 define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int}
8624 sized units. With @code{int} having a size of 4 bytes, the type defines
8625 a vector of eight units, four bytes each. The mode of variables of type
8626 @code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined
8627 to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be
8628 an array of three such vectors. @xref{Vector Extensions}, for details of
8629 manipulating objects of vector types.
8631 This attribute is only applicable to integral and floating scalar types.
8632 In function declarations the attribute applies to the function return
8635 For example, the following:
8637 __attribute__ ((vector_size (16))) float get_flt_vec16 (void);
8639 declares @code{get_flt_vec16} to be a function returning a 16-byte vector
8640 with the base type @code{float}.
8643 @cindex @code{visibility} type attribute
8644 In C++, attribute visibility (@pxref{Function Attributes}) can also be
8645 applied to class, struct, union and enum types. Unlike other type
8646 attributes, the attribute must appear between the initial keyword and
8647 the name of the type; it cannot appear after the body of the type.
8649 Note that the type visibility is applied to vague linkage entities
8650 associated with the class (vtable, typeinfo node, etc.). In
8651 particular, if a class is thrown as an exception in one shared object
8652 and caught in another, the class must have default visibility.
8653 Otherwise the two shared objects are unable to use the same
8654 typeinfo node and exception handling will break.
8656 @item objc_root_class @r{(Objective-C and Objective-C++ only)}
8657 @cindex @code{objc_root_class} type attribute
8658 This attribute marks a class as being a root class, and thus allows
8659 the compiler to elide any warnings about a missing superclass and to
8660 make additional checks for mandatory methods as needed.
8664 To specify multiple attributes, separate them by commas within the
8665 double parentheses: for example, @samp{__attribute__ ((aligned (16),
8668 @node ARC Type Attributes
8669 @subsection ARC Type Attributes
8671 @cindex @code{uncached} type attribute, ARC
8672 Declaring objects with @code{uncached} allows you to exclude
8673 data-cache participation in load and store operations on those objects
8674 without involving the additional semantic implications of
8675 @code{volatile}. The @code{.di} instruction suffix is used for all
8676 loads and stores of data declared @code{uncached}.
8678 @node ARM Type Attributes
8679 @subsection ARM Type Attributes
8681 @cindex @code{notshared} type attribute, ARM
8682 On those ARM targets that support @code{dllimport} (such as Symbian
8683 OS), you can use the @code{notshared} attribute to indicate that the
8684 virtual table and other similar data for a class should not be
8685 exported from a DLL@. For example:
8688 class __declspec(notshared) C @{
8690 __declspec(dllimport) C();
8694 __declspec(dllexport)
8699 In this code, @code{C::C} is exported from the current DLL, but the
8700 virtual table for @code{C} is not exported. (You can use
8701 @code{__attribute__} instead of @code{__declspec} if you prefer, but
8702 most Symbian OS code uses @code{__declspec}.)
8704 @node MeP Type Attributes
8705 @subsection MeP Type Attributes
8707 @cindex @code{based} type attribute, MeP
8708 @cindex @code{tiny} type attribute, MeP
8709 @cindex @code{near} type attribute, MeP
8710 @cindex @code{far} type attribute, MeP
8711 Many of the MeP variable attributes may be applied to types as well.
8712 Specifically, the @code{based}, @code{tiny}, @code{near}, and
8713 @code{far} attributes may be applied to either. The @code{io} and
8714 @code{cb} attributes may not be applied to types.
8716 @node PowerPC Type Attributes
8717 @subsection PowerPC Type Attributes
8719 Three attributes currently are defined for PowerPC configurations:
8720 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
8722 @cindex @code{ms_struct} type attribute, PowerPC
8723 @cindex @code{gcc_struct} type attribute, PowerPC
8724 For full documentation of the @code{ms_struct} and @code{gcc_struct}
8725 attributes please see the documentation in @ref{x86 Type Attributes}.
8727 @cindex @code{altivec} type attribute, PowerPC
8728 The @code{altivec} attribute allows one to declare AltiVec vector data
8729 types supported by the AltiVec Programming Interface Manual. The
8730 attribute requires an argument to specify one of three vector types:
8731 @code{vector__}, @code{pixel__} (always followed by unsigned short),
8732 and @code{bool__} (always followed by unsigned).
8735 __attribute__((altivec(vector__)))
8736 __attribute__((altivec(pixel__))) unsigned short
8737 __attribute__((altivec(bool__))) unsigned
8740 These attributes mainly are intended to support the @code{__vector},
8741 @code{__pixel}, and @code{__bool} AltiVec keywords.
8743 @node x86 Type Attributes
8744 @subsection x86 Type Attributes
8746 Two attributes are currently defined for x86 configurations:
8747 @code{ms_struct} and @code{gcc_struct}.
8753 @cindex @code{ms_struct} type attribute, x86
8754 @cindex @code{gcc_struct} type attribute, x86
8756 If @code{packed} is used on a structure, or if bit-fields are used
8757 it may be that the Microsoft ABI packs them differently
8758 than GCC normally packs them. Particularly when moving packed
8759 data between functions compiled with GCC and the native Microsoft compiler
8760 (either via function call or as data in a file), it may be necessary to access
8763 The @code{ms_struct} and @code{gcc_struct} attributes correspond
8764 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
8765 command-line options, respectively;
8766 see @ref{x86 Options}, for details of how structure layout is affected.
8767 @xref{x86 Variable Attributes}, for information about the corresponding
8768 attributes on variables.
8772 @node Label Attributes
8773 @section Label Attributes
8774 @cindex Label Attributes
8776 GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for
8777 details of the exact syntax for using attributes. Other attributes are
8778 available for functions (@pxref{Function Attributes}), variables
8779 (@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}),
8780 statements (@pxref{Statement Attributes}), and for types
8781 (@pxref{Type Attributes}). A label attribute followed
8782 by a declaration appertains to the label and not the declaration.
8784 This example uses the @code{cold} label attribute to indicate the
8785 @code{ErrorHandling} branch is unlikely to be taken and that the
8786 @code{ErrorHandling} label is unused:
8790 asm goto ("some asm" : : : : NoError);
8792 /* This branch (the fall-through from the asm) is less commonly used */
8794 __attribute__((cold, unused)); /* Semi-colon is required here */
8799 printf("no error\n");
8805 @cindex @code{unused} label attribute
8806 This feature is intended for program-generated code that may contain
8807 unused labels, but which is compiled with @option{-Wall}. It is
8808 not normally appropriate to use in it human-written code, though it
8809 could be useful in cases where the code that jumps to the label is
8810 contained within an @code{#ifdef} conditional.
8813 @cindex @code{hot} label attribute
8814 The @code{hot} attribute on a label is used to inform the compiler that
8815 the path following the label is more likely than paths that are not so
8816 annotated. This attribute is used in cases where @code{__builtin_expect}
8817 cannot be used, for instance with computed goto or @code{asm goto}.
8820 @cindex @code{cold} label attribute
8821 The @code{cold} attribute on labels is used to inform the compiler that
8822 the path following the label is unlikely to be executed. This attribute
8823 is used in cases where @code{__builtin_expect} cannot be used, for instance
8824 with computed goto or @code{asm goto}.
8828 @node Enumerator Attributes
8829 @section Enumerator Attributes
8830 @cindex Enumerator Attributes
8832 GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for
8833 details of the exact syntax for using attributes. Other attributes are
8834 available for functions (@pxref{Function Attributes}), variables
8835 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements
8836 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
8838 This example uses the @code{deprecated} enumerator attribute to indicate the
8839 @code{oldval} enumerator is deprecated:
8843 oldval __attribute__((deprecated)),
8856 @cindex @code{deprecated} enumerator attribute
8857 The @code{deprecated} attribute results in a warning if the enumerator
8858 is used anywhere in the source file. This is useful when identifying
8859 enumerators that are expected to be removed in a future version of a
8860 program. The warning also includes the location of the declaration
8861 of the deprecated enumerator, to enable users to easily find further
8862 information about why the enumerator is deprecated, or what they should
8863 do instead. Note that the warnings only occurs for uses.
8867 @node Statement Attributes
8868 @section Statement Attributes
8869 @cindex Statement Attributes
8871 GCC allows attributes to be set on null statements. @xref{Attribute Syntax},
8872 for details of the exact syntax for using attributes. Other attributes are
8873 available for functions (@pxref{Function Attributes}), variables
8874 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators
8875 (@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}).
8877 This example uses the @code{fallthrough} statement attribute to indicate that
8878 the @option{-Wimplicit-fallthrough} warning should not be emitted:
8885 __attribute__((fallthrough));
8893 @cindex @code{fallthrough} statement attribute
8894 The @code{fallthrough} attribute with a null statement serves as a
8895 fallthrough statement. It hints to the compiler that a statement
8896 that falls through to another case label, or user-defined label
8897 in a switch statement is intentional and thus the
8898 @option{-Wimplicit-fallthrough} warning must not trigger. The
8899 fallthrough attribute may appear at most once in each attribute
8900 list, and may not be mixed with other attributes. It can only
8901 be used in a switch statement (the compiler will issue an error
8902 otherwise), after a preceding statement and before a logically
8903 succeeding case label, or user-defined label.
8907 @node Attribute Syntax
8908 @section Attribute Syntax
8909 @cindex attribute syntax
8911 This section describes the syntax with which @code{__attribute__} may be
8912 used, and the constructs to which attribute specifiers bind, for the C
8913 language. Some details may vary for C++ and Objective-C@. Because of
8914 infelicities in the grammar for attributes, some forms described here
8915 may not be successfully parsed in all cases.
8917 There are some problems with the semantics of attributes in C++. For
8918 example, there are no manglings for attributes, although they may affect
8919 code generation, so problems may arise when attributed types are used in
8920 conjunction with templates or overloading. Similarly, @code{typeid}
8921 does not distinguish between types with different attributes. Support
8922 for attributes in C++ may be restricted in future to attributes on
8923 declarations only, but not on nested declarators.
8925 @xref{Function Attributes}, for details of the semantics of attributes
8926 applying to functions. @xref{Variable Attributes}, for details of the
8927 semantics of attributes applying to variables. @xref{Type Attributes},
8928 for details of the semantics of attributes applying to structure, union
8929 and enumerated types.
8930 @xref{Label Attributes}, for details of the semantics of attributes
8932 @xref{Enumerator Attributes}, for details of the semantics of attributes
8933 applying to enumerators.
8934 @xref{Statement Attributes}, for details of the semantics of attributes
8935 applying to statements.
8937 An @dfn{attribute specifier} is of the form
8938 @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
8939 is a possibly empty comma-separated sequence of @dfn{attributes}, where
8940 each attribute is one of the following:
8944 Empty. Empty attributes are ignored.
8948 (which may be an identifier such as @code{unused}, or a reserved
8949 word such as @code{const}).
8952 An attribute name followed by a parenthesized list of
8953 parameters for the attribute.
8954 These parameters take one of the following forms:
8958 An identifier. For example, @code{mode} attributes use this form.
8961 An identifier followed by a comma and a non-empty comma-separated list
8962 of expressions. For example, @code{format} attributes use this form.
8965 A possibly empty comma-separated list of expressions. For example,
8966 @code{format_arg} attributes use this form with the list being a single
8967 integer constant expression, and @code{alias} attributes use this form
8968 with the list being a single string constant.
8972 An @dfn{attribute specifier list} is a sequence of one or more attribute
8973 specifiers, not separated by any other tokens.
8975 You may optionally specify attribute names with @samp{__}
8976 preceding and following the name.
8977 This allows you to use them in header files without
8978 being concerned about a possible macro of the same name. For example,
8979 you may use the attribute name @code{__noreturn__} instead of @code{noreturn}.
8982 @subsubheading Label Attributes
8984 In GNU C, an attribute specifier list may appear after the colon following a
8985 label, other than a @code{case} or @code{default} label. GNU C++ only permits
8986 attributes on labels if the attribute specifier is immediately
8987 followed by a semicolon (i.e., the label applies to an empty
8988 statement). If the semicolon is missing, C++ label attributes are
8989 ambiguous, as it is permissible for a declaration, which could begin
8990 with an attribute list, to be labelled in C++. Declarations cannot be
8991 labelled in C90 or C99, so the ambiguity does not arise there.
8993 @subsubheading Enumerator Attributes
8995 In GNU C, an attribute specifier list may appear as part of an enumerator.
8996 The attribute goes after the enumeration constant, before @code{=}, if
8997 present. The optional attribute in the enumerator appertains to the
8998 enumeration constant. It is not possible to place the attribute after
8999 the constant expression, if present.
9001 @subsubheading Statement Attributes
9002 In GNU C, an attribute specifier list may appear as part of a null
9003 statement. The attribute goes before the semicolon.
9005 @subsubheading Type Attributes
9007 An attribute specifier list may appear as part of a @code{struct},
9008 @code{union} or @code{enum} specifier. It may go either immediately
9009 after the @code{struct}, @code{union} or @code{enum} keyword, or after
9010 the closing brace. The former syntax is preferred.
9011 Where attribute specifiers follow the closing brace, they are considered
9012 to relate to the structure, union or enumerated type defined, not to any
9013 enclosing declaration the type specifier appears in, and the type
9014 defined is not complete until after the attribute specifiers.
9015 @c Otherwise, there would be the following problems: a shift/reduce
9016 @c conflict between attributes binding the struct/union/enum and
9017 @c binding to the list of specifiers/qualifiers; and "aligned"
9018 @c attributes could use sizeof for the structure, but the size could be
9019 @c changed later by "packed" attributes.
9022 @subsubheading All other attributes
9024 Otherwise, an attribute specifier appears as part of a declaration,
9025 counting declarations of unnamed parameters and type names, and relates
9026 to that declaration (which may be nested in another declaration, for
9027 example in the case of a parameter declaration), or to a particular declarator
9028 within a declaration. Where an
9029 attribute specifier is applied to a parameter declared as a function or
9030 an array, it should apply to the function or array rather than the
9031 pointer to which the parameter is implicitly converted, but this is not
9032 yet correctly implemented.
9034 Any list of specifiers and qualifiers at the start of a declaration may
9035 contain attribute specifiers, whether or not such a list may in that
9036 context contain storage class specifiers. (Some attributes, however,
9037 are essentially in the nature of storage class specifiers, and only make
9038 sense where storage class specifiers may be used; for example,
9039 @code{section}.) There is one necessary limitation to this syntax: the
9040 first old-style parameter declaration in a function definition cannot
9041 begin with an attribute specifier, because such an attribute applies to
9042 the function instead by syntax described below (which, however, is not
9043 yet implemented in this case). In some other cases, attribute
9044 specifiers are permitted by this grammar but not yet supported by the
9045 compiler. All attribute specifiers in this place relate to the
9046 declaration as a whole. In the obsolescent usage where a type of
9047 @code{int} is implied by the absence of type specifiers, such a list of
9048 specifiers and qualifiers may be an attribute specifier list with no
9049 other specifiers or qualifiers.
9051 At present, the first parameter in a function prototype must have some
9052 type specifier that is not an attribute specifier; this resolves an
9053 ambiguity in the interpretation of @code{void f(int
9054 (__attribute__((foo)) x))}, but is subject to change. At present, if
9055 the parentheses of a function declarator contain only attributes then
9056 those attributes are ignored, rather than yielding an error or warning
9057 or implying a single parameter of type int, but this is subject to
9060 An attribute specifier list may appear immediately before a declarator
9061 (other than the first) in a comma-separated list of declarators in a
9062 declaration of more than one identifier using a single list of
9063 specifiers and qualifiers. Such attribute specifiers apply
9064 only to the identifier before whose declarator they appear. For
9068 __attribute__((noreturn)) void d0 (void),
9069 __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
9074 the @code{noreturn} attribute applies to all the functions
9075 declared; the @code{format} attribute only applies to @code{d1}.
9077 An attribute specifier list may appear immediately before the comma,
9078 @code{=} or semicolon terminating the declaration of an identifier other
9079 than a function definition. Such attribute specifiers apply
9080 to the declared object or function. Where an
9081 assembler name for an object or function is specified (@pxref{Asm
9082 Labels}), the attribute must follow the @code{asm}
9085 An attribute specifier list may, in future, be permitted to appear after
9086 the declarator in a function definition (before any old-style parameter
9087 declarations or the function body).
9089 Attribute specifiers may be mixed with type qualifiers appearing inside
9090 the @code{[]} of a parameter array declarator, in the C99 construct by
9091 which such qualifiers are applied to the pointer to which the array is
9092 implicitly converted. Such attribute specifiers apply to the pointer,
9093 not to the array, but at present this is not implemented and they are
9096 An attribute specifier list may appear at the start of a nested
9097 declarator. At present, there are some limitations in this usage: the
9098 attributes correctly apply to the declarator, but for most individual
9099 attributes the semantics this implies are not implemented.
9100 When attribute specifiers follow the @code{*} of a pointer
9101 declarator, they may be mixed with any type qualifiers present.
9102 The following describes the formal semantics of this syntax. It makes the
9103 most sense if you are familiar with the formal specification of
9104 declarators in the ISO C standard.
9106 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
9107 D1}, where @code{T} contains declaration specifiers that specify a type
9108 @var{Type} (such as @code{int}) and @code{D1} is a declarator that
9109 contains an identifier @var{ident}. The type specified for @var{ident}
9110 for derived declarators whose type does not include an attribute
9111 specifier is as in the ISO C standard.
9113 If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
9114 and the declaration @code{T D} specifies the type
9115 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
9116 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
9117 @var{attribute-specifier-list} @var{Type}'' for @var{ident}.
9119 If @code{D1} has the form @code{*
9120 @var{type-qualifier-and-attribute-specifier-list} D}, and the
9121 declaration @code{T D} specifies the type
9122 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
9123 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
9124 @var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for
9130 void (__attribute__((noreturn)) ****f) (void);
9134 specifies the type ``pointer to pointer to pointer to pointer to
9135 non-returning function returning @code{void}''. As another example,
9138 char *__attribute__((aligned(8))) *f;
9142 specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
9143 Note again that this does not work with most attributes; for example,
9144 the usage of @samp{aligned} and @samp{noreturn} attributes given above
9145 is not yet supported.
9147 For compatibility with existing code written for compiler versions that
9148 did not implement attributes on nested declarators, some laxity is
9149 allowed in the placing of attributes. If an attribute that only applies
9150 to types is applied to a declaration, it is treated as applying to
9151 the type of that declaration. If an attribute that only applies to
9152 declarations is applied to the type of a declaration, it is treated
9153 as applying to that declaration; and, for compatibility with code
9154 placing the attributes immediately before the identifier declared, such
9155 an attribute applied to a function return type is treated as
9156 applying to the function type, and such an attribute applied to an array
9157 element type is treated as applying to the array type. If an
9158 attribute that only applies to function types is applied to a
9159 pointer-to-function type, it is treated as applying to the pointer
9160 target type; if such an attribute is applied to a function return type
9161 that is not a pointer-to-function type, it is treated as applying
9162 to the function type.
9164 @node Function Prototypes
9165 @section Prototypes and Old-Style Function Definitions
9166 @cindex function prototype declarations
9167 @cindex old-style function definitions
9168 @cindex promotion of formal parameters
9170 GNU C extends ISO C to allow a function prototype to override a later
9171 old-style non-prototype definition. Consider the following example:
9174 /* @r{Use prototypes unless the compiler is old-fashioned.} */
9181 /* @r{Prototype function declaration.} */
9182 int isroot P((uid_t));
9184 /* @r{Old-style function definition.} */
9186 isroot (x) /* @r{??? lossage here ???} */
9193 Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
9194 not allow this example, because subword arguments in old-style
9195 non-prototype definitions are promoted. Therefore in this example the
9196 function definition's argument is really an @code{int}, which does not
9197 match the prototype argument type of @code{short}.
9199 This restriction of ISO C makes it hard to write code that is portable
9200 to traditional C compilers, because the programmer does not know
9201 whether the @code{uid_t} type is @code{short}, @code{int}, or
9202 @code{long}. Therefore, in cases like these GNU C allows a prototype
9203 to override a later old-style definition. More precisely, in GNU C, a
9204 function prototype argument type overrides the argument type specified
9205 by a later old-style definition if the former type is the same as the
9206 latter type before promotion. Thus in GNU C the above example is
9207 equivalent to the following:
9220 GNU C++ does not support old-style function definitions, so this
9221 extension is irrelevant.
9224 @section C++ Style Comments
9226 @cindex C++ comments
9227 @cindex comments, C++ style
9229 In GNU C, you may use C++ style comments, which start with @samp{//} and
9230 continue until the end of the line. Many other C implementations allow
9231 such comments, and they are included in the 1999 C standard. However,
9232 C++ style comments are not recognized if you specify an @option{-std}
9233 option specifying a version of ISO C before C99, or @option{-ansi}
9234 (equivalent to @option{-std=c90}).
9237 @section Dollar Signs in Identifier Names
9239 @cindex dollar signs in identifier names
9240 @cindex identifier names, dollar signs in
9242 In GNU C, you may normally use dollar signs in identifier names.
9243 This is because many traditional C implementations allow such identifiers.
9244 However, dollar signs in identifiers are not supported on a few target
9245 machines, typically because the target assembler does not allow them.
9247 @node Character Escapes
9248 @section The Character @key{ESC} in Constants
9250 You can use the sequence @samp{\e} in a string or character constant to
9251 stand for the ASCII character @key{ESC}.
9254 @section Determining the Alignment of Functions, Types or Variables
9256 @cindex type alignment
9257 @cindex variable alignment
9259 The keyword @code{__alignof__} determines the alignment requirement of
9260 a function, object, or a type, or the minimum alignment usually required
9261 by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}.
9263 For example, if the target machine requires a @code{double} value to be
9264 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
9265 This is true on many RISC machines. On more traditional machine
9266 designs, @code{__alignof__ (double)} is 4 or even 2.
9268 Some machines never actually require alignment; they allow references to any
9269 data type even at an odd address. For these machines, @code{__alignof__}
9270 reports the smallest alignment that GCC gives the data type, usually as
9271 mandated by the target ABI.
9273 If the operand of @code{__alignof__} is an lvalue rather than a type,
9274 its value is the required alignment for its type, taking into account
9275 any minimum alignment specified by attribute @code{aligned}
9276 (@pxref{Common Variable Attributes}). For example, after this
9280 struct foo @{ int x; char y; @} foo1;
9284 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
9285 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
9286 It is an error to ask for the alignment of an incomplete type other
9289 If the operand of the @code{__alignof__} expression is a function,
9290 the expression evaluates to the alignment of the function which may
9291 be specified by attribute @code{aligned} (@pxref{Common Function Attributes}).
9294 @section An Inline Function is As Fast As a Macro
9295 @cindex inline functions
9296 @cindex integrating function code
9298 @cindex macros, inline alternative
9300 By declaring a function inline, you can direct GCC to make
9301 calls to that function faster. One way GCC can achieve this is to
9302 integrate that function's code into the code for its callers. This
9303 makes execution faster by eliminating the function-call overhead; in
9304 addition, if any of the actual argument values are constant, their
9305 known values may permit simplifications at compile time so that not
9306 all of the inline function's code needs to be included. The effect on
9307 code size is less predictable; object code may be larger or smaller
9308 with function inlining, depending on the particular case. You can
9309 also direct GCC to try to integrate all ``simple enough'' functions
9310 into their callers with the option @option{-finline-functions}.
9312 GCC implements three different semantics of declaring a function
9313 inline. One is available with @option{-std=gnu89} or
9314 @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
9315 on all inline declarations, another when
9317 @option{-std=gnu99} or an option for a later C version is used
9318 (without @option{-fgnu89-inline}), and the third
9319 is used when compiling C++.
9321 To declare a function inline, use the @code{inline} keyword in its
9322 declaration, like this:
9332 If you are writing a header file to be included in ISO C90 programs, write
9333 @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
9335 The three types of inlining behave similarly in two important cases:
9336 when the @code{inline} keyword is used on a @code{static} function,
9337 like the example above, and when a function is first declared without
9338 using the @code{inline} keyword and then is defined with
9339 @code{inline}, like this:
9342 extern int inc (int *a);
9350 In both of these common cases, the program behaves the same as if you
9351 had not used the @code{inline} keyword, except for its speed.
9353 @cindex inline functions, omission of
9354 @opindex fkeep-inline-functions
9355 When a function is both inline and @code{static}, if all calls to the
9356 function are integrated into the caller, and the function's address is
9357 never used, then the function's own assembler code is never referenced.
9358 In this case, GCC does not actually output assembler code for the
9359 function, unless you specify the option @option{-fkeep-inline-functions}.
9360 If there is a nonintegrated call, then the function is compiled to
9361 assembler code as usual. The function must also be compiled as usual if
9362 the program refers to its address, because that cannot be inlined.
9365 Note that certain usages in a function definition can make it unsuitable
9366 for inline substitution. Among these usages are: variadic functions,
9367 use of @code{alloca}, use of computed goto (@pxref{Labels as Values}),
9368 use of nonlocal goto, use of nested functions, use of @code{setjmp}, use
9369 of @code{__builtin_longjmp} and use of @code{__builtin_return} or
9370 @code{__builtin_apply_args}. Using @option{-Winline} warns when a
9371 function marked @code{inline} could not be substituted, and gives the
9372 reason for the failure.
9374 @cindex automatic @code{inline} for C++ member fns
9375 @cindex @code{inline} automatic for C++ member fns
9376 @cindex member fns, automatically @code{inline}
9377 @cindex C++ member fns, automatically @code{inline}
9378 @opindex fno-default-inline
9379 As required by ISO C++, GCC considers member functions defined within
9380 the body of a class to be marked inline even if they are
9381 not explicitly declared with the @code{inline} keyword. You can
9382 override this with @option{-fno-default-inline}; @pxref{C++ Dialect
9383 Options,,Options Controlling C++ Dialect}.
9385 GCC does not inline any functions when not optimizing unless you specify
9386 the @samp{always_inline} attribute for the function, like this:
9389 /* @r{Prototype.} */
9390 inline void foo (const char) __attribute__((always_inline));
9393 The remainder of this section is specific to GNU C90 inlining.
9395 @cindex non-static inline function
9396 When an inline function is not @code{static}, then the compiler must assume
9397 that there may be calls from other source files; since a global symbol can
9398 be defined only once in any program, the function must not be defined in
9399 the other source files, so the calls therein cannot be integrated.
9400 Therefore, a non-@code{static} inline function is always compiled on its
9401 own in the usual fashion.
9403 If you specify both @code{inline} and @code{extern} in the function
9404 definition, then the definition is used only for inlining. In no case
9405 is the function compiled on its own, not even if you refer to its
9406 address explicitly. Such an address becomes an external reference, as
9407 if you had only declared the function, and had not defined it.
9409 This combination of @code{inline} and @code{extern} has almost the
9410 effect of a macro. The way to use it is to put a function definition in
9411 a header file with these keywords, and put another copy of the
9412 definition (lacking @code{inline} and @code{extern}) in a library file.
9413 The definition in the header file causes most calls to the function
9414 to be inlined. If any uses of the function remain, they refer to
9415 the single copy in the library.
9418 @section When is a Volatile Object Accessed?
9419 @cindex accessing volatiles
9420 @cindex volatile read
9421 @cindex volatile write
9422 @cindex volatile access
9424 C has the concept of volatile objects. These are normally accessed by
9425 pointers and used for accessing hardware or inter-thread
9426 communication. The standard encourages compilers to refrain from
9427 optimizations concerning accesses to volatile objects, but leaves it
9428 implementation defined as to what constitutes a volatile access. The
9429 minimum requirement is that at a sequence point all previous accesses
9430 to volatile objects have stabilized and no subsequent accesses have
9431 occurred. Thus an implementation is free to reorder and combine
9432 volatile accesses that occur between sequence points, but cannot do
9433 so for accesses across a sequence point. The use of volatile does
9434 not allow you to violate the restriction on updating objects multiple
9435 times between two sequence points.
9437 Accesses to non-volatile objects are not ordered with respect to
9438 volatile accesses. You cannot use a volatile object as a memory
9439 barrier to order a sequence of writes to non-volatile memory. For
9443 int *ptr = @var{something};
9445 *ptr = @var{something};
9450 Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed
9451 that the write to @var{*ptr} occurs by the time the update
9452 of @var{vobj} happens. If you need this guarantee, you must use
9453 a stronger memory barrier such as:
9456 int *ptr = @var{something};
9458 *ptr = @var{something};
9459 asm volatile ("" : : : "memory");
9463 A scalar volatile object is read when it is accessed in a void context:
9466 volatile int *src = @var{somevalue};
9470 Such expressions are rvalues, and GCC implements this as a
9471 read of the volatile object being pointed to.
9473 Assignments are also expressions and have an rvalue. However when
9474 assigning to a scalar volatile, the volatile object is not reread,
9475 regardless of whether the assignment expression's rvalue is used or
9476 not. If the assignment's rvalue is used, the value is that assigned
9477 to the volatile object. For instance, there is no read of @var{vobj}
9478 in all the following cases:
9483 vobj = @var{something};
9484 obj = vobj = @var{something};
9485 obj ? vobj = @var{onething} : vobj = @var{anotherthing};
9486 obj = (@var{something}, vobj = @var{anotherthing});
9489 If you need to read the volatile object after an assignment has
9490 occurred, you must use a separate expression with an intervening
9493 As bit-fields are not individually addressable, volatile bit-fields may
9494 be implicitly read when written to, or when adjacent bit-fields are
9495 accessed. Bit-field operations may be optimized such that adjacent
9496 bit-fields are only partially accessed, if they straddle a storage unit
9497 boundary. For these reasons it is unwise to use volatile bit-fields to
9500 @node Using Assembly Language with C
9501 @section How to Use Inline Assembly Language in C Code
9502 @cindex @code{asm} keyword
9503 @cindex assembly language in C
9504 @cindex inline assembly language
9505 @cindex mixing assembly language and C
9507 The @code{asm} keyword allows you to embed assembler instructions
9508 within C code. GCC provides two forms of inline @code{asm}
9509 statements. A @dfn{basic @code{asm}} statement is one with no
9510 operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}}
9511 statement (@pxref{Extended Asm}) includes one or more operands.
9512 The extended form is preferred for mixing C and assembly language
9513 within a function, but to include assembly language at
9514 top level you must use basic @code{asm}.
9516 You can also use the @code{asm} keyword to override the assembler name
9517 for a C symbol, or to place a C variable in a specific register.
9520 * Basic Asm:: Inline assembler without operands.
9521 * Extended Asm:: Inline assembler with operands.
9522 * Constraints:: Constraints for @code{asm} operands
9523 * Asm Labels:: Specifying the assembler name to use for a C symbol.
9524 * Explicit Register Variables:: Defining variables residing in specified
9526 * Size of an asm:: How GCC calculates the size of an @code{asm} block.
9530 @subsection Basic Asm --- Assembler Instructions Without Operands
9531 @cindex basic @code{asm}
9532 @cindex assembly language in C, basic
9534 A basic @code{asm} statement has the following syntax:
9537 asm @var{asm-qualifiers} ( @var{AssemblerInstructions} )
9540 The @code{asm} keyword is a GNU extension.
9541 When writing code that can be compiled with @option{-ansi} and the
9542 various @option{-std} options, use @code{__asm__} instead of
9543 @code{asm} (@pxref{Alternate Keywords}).
9545 @subsubheading Qualifiers
9548 The optional @code{volatile} qualifier has no effect.
9549 All basic @code{asm} blocks are implicitly volatile.
9552 If you use the @code{inline} qualifier, then for inlining purposes the size
9553 of the @code{asm} statement is taken as the smallest size possible (@pxref{Size
9557 @subsubheading Parameters
9560 @item AssemblerInstructions
9561 This is a literal string that specifies the assembler code. The string can
9562 contain any instructions recognized by the assembler, including directives.
9563 GCC does not parse the assembler instructions themselves and
9564 does not know what they mean or even whether they are valid assembler input.
9566 You may place multiple assembler instructions together in a single @code{asm}
9567 string, separated by the characters normally used in assembly code for the
9568 system. A combination that works in most places is a newline to break the
9569 line, plus a tab character (written as @samp{\n\t}).
9570 Some assemblers allow semicolons as a line separator. However,
9571 note that some assembler dialects use semicolons to start a comment.
9574 @subsubheading Remarks
9575 Using extended @code{asm} (@pxref{Extended Asm}) typically produces
9576 smaller, safer, and more efficient code, and in most cases it is a
9577 better solution than basic @code{asm}. However, there are two
9578 situations where only basic @code{asm} can be used:
9582 Extended @code{asm} statements have to be inside a C
9583 function, so to write inline assembly language at file scope (``top-level''),
9584 outside of C functions, you must use basic @code{asm}.
9585 You can use this technique to emit assembler directives,
9586 define assembly language macros that can be invoked elsewhere in the file,
9587 or write entire functions in assembly language.
9588 Basic @code{asm} statements outside of functions may not use any
9593 with the @code{naked} attribute also require basic @code{asm}
9594 (@pxref{Function Attributes}).
9597 Safely accessing C data and calling functions from basic @code{asm} is more
9598 complex than it may appear. To access C data, it is better to use extended
9601 Do not expect a sequence of @code{asm} statements to remain perfectly
9602 consecutive after compilation. If certain instructions need to remain
9603 consecutive in the output, put them in a single multi-instruction @code{asm}
9604 statement. Note that GCC's optimizers can move @code{asm} statements
9605 relative to other code, including across jumps.
9607 @code{asm} statements may not perform jumps into other @code{asm} statements.
9608 GCC does not know about these jumps, and therefore cannot take
9609 account of them when deciding how to optimize. Jumps from @code{asm} to C
9610 labels are only supported in extended @code{asm}.
9612 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
9613 assembly code when optimizing. This can lead to unexpected duplicate
9614 symbol errors during compilation if your assembly code defines symbols or
9617 @strong{Warning:} The C standards do not specify semantics for @code{asm},
9618 making it a potential source of incompatibilities between compilers. These
9619 incompatibilities may not produce compiler warnings/errors.
9621 GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which
9622 means there is no way to communicate to the compiler what is happening
9623 inside them. GCC has no visibility of symbols in the @code{asm} and may
9624 discard them as unreferenced. It also does not know about side effects of
9625 the assembler code, such as modifications to memory or registers. Unlike
9626 some compilers, GCC assumes that no changes to general purpose registers
9627 occur. This assumption may change in a future release.
9629 To avoid complications from future changes to the semantics and the
9630 compatibility issues between compilers, consider replacing basic @code{asm}
9631 with extended @code{asm}. See
9632 @uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert
9633 from basic asm to extended asm} for information about how to perform this
9636 The compiler copies the assembler instructions in a basic @code{asm}
9637 verbatim to the assembly language output file, without
9638 processing dialects or any of the @samp{%} operators that are available with
9639 extended @code{asm}. This results in minor differences between basic
9640 @code{asm} strings and extended @code{asm} templates. For example, to refer to
9641 registers you might use @samp{%eax} in basic @code{asm} and
9642 @samp{%%eax} in extended @code{asm}.
9644 On targets such as x86 that support multiple assembler dialects,
9645 all basic @code{asm} blocks use the assembler dialect specified by the
9646 @option{-masm} command-line option (@pxref{x86 Options}).
9647 Basic @code{asm} provides no
9648 mechanism to provide different assembler strings for different dialects.
9650 For basic @code{asm} with non-empty assembler string GCC assumes
9651 the assembler block does not change any general purpose registers,
9652 but it may read or write any globally accessible variable.
9654 Here is an example of basic @code{asm} for i386:
9657 /* Note that this code will not compile with -masm=intel */
9658 #define DebugBreak() asm("int $3")
9662 @subsection Extended Asm - Assembler Instructions with C Expression Operands
9663 @cindex extended @code{asm}
9664 @cindex assembly language in C, extended
9666 With extended @code{asm} you can read and write C variables from
9667 assembler and perform jumps from assembler code to C labels.
9668 Extended @code{asm} syntax uses colons (@samp{:}) to delimit
9669 the operand parameters after the assembler template:
9672 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9673 : @var{OutputOperands}
9674 @r{[} : @var{InputOperands}
9675 @r{[} : @var{Clobbers} @r{]} @r{]})
9677 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9678 : @var{OutputOperands}
9679 : @var{InputOperands}
9683 where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the
9686 The @code{asm} keyword is a GNU extension.
9687 When writing code that can be compiled with @option{-ansi} and the
9688 various @option{-std} options, use @code{__asm__} instead of
9689 @code{asm} (@pxref{Alternate Keywords}).
9691 @subsubheading Qualifiers
9695 The typical use of extended @code{asm} statements is to manipulate input
9696 values to produce output values. However, your @code{asm} statements may
9697 also produce side effects. If so, you may need to use the @code{volatile}
9698 qualifier to disable certain optimizations. @xref{Volatile}.
9701 If you use the @code{inline} qualifier, then for inlining purposes the size
9702 of the @code{asm} statement is taken as the smallest size possible
9703 (@pxref{Size of an asm}).
9706 This qualifier informs the compiler that the @code{asm} statement may
9707 perform a jump to one of the labels listed in the @var{GotoLabels}.
9711 @subsubheading Parameters
9713 @item AssemblerTemplate
9714 This is a literal string that is the template for the assembler code. It is a
9715 combination of fixed text and tokens that refer to the input, output,
9716 and goto parameters. @xref{AssemblerTemplate}.
9718 @item OutputOperands
9719 A comma-separated list of the C variables modified by the instructions in the
9720 @var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}.
9723 A comma-separated list of C expressions read by the instructions in the
9724 @var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}.
9727 A comma-separated list of registers or other values changed by the
9728 @var{AssemblerTemplate}, beyond those listed as outputs.
9729 An empty list is permitted. @xref{Clobbers and Scratch Registers}.
9732 When you are using the @code{goto} form of @code{asm}, this section contains
9733 the list of all C labels to which the code in the
9734 @var{AssemblerTemplate} may jump.
9737 @code{asm} statements may not perform jumps into other @code{asm} statements,
9738 only to the listed @var{GotoLabels}.
9739 GCC's optimizers do not know about other jumps; therefore they cannot take
9740 account of them when deciding how to optimize.
9743 The total number of input + output + goto operands is limited to 30.
9745 @subsubheading Remarks
9746 The @code{asm} statement allows you to include assembly instructions directly
9747 within C code. This may help you to maximize performance in time-sensitive
9748 code or to access assembly instructions that are not readily available to C
9751 Note that extended @code{asm} statements must be inside a function. Only
9752 basic @code{asm} may be outside functions (@pxref{Basic Asm}).
9753 Functions declared with the @code{naked} attribute also require basic
9754 @code{asm} (@pxref{Function Attributes}).
9756 While the uses of @code{asm} are many and varied, it may help to think of an
9757 @code{asm} statement as a series of low-level instructions that convert input
9758 parameters to output parameters. So a simple (if not particularly useful)
9759 example for i386 using @code{asm} might look like this:
9765 asm ("mov %1, %0\n\t"
9770 printf("%d\n", dst);
9773 This code copies @code{src} to @code{dst} and add 1 to @code{dst}.
9776 @subsubsection Volatile
9777 @cindex volatile @code{asm}
9778 @cindex @code{asm} volatile
9780 GCC's optimizers sometimes discard @code{asm} statements if they determine
9781 there is no need for the output variables. Also, the optimizers may move
9782 code out of loops if they believe that the code will always return the same
9783 result (i.e.@: none of its input values change between calls). Using the
9784 @code{volatile} qualifier disables these optimizations. @code{asm} statements
9785 that have no output operands and @code{asm goto} statements,
9786 are implicitly volatile.
9788 This i386 code demonstrates a case that does not use (or require) the
9789 @code{volatile} qualifier. If it is performing assertion checking, this code
9790 uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is
9791 unreferenced by any code. As a result, the optimizers can discard the
9792 @code{asm} statement, which in turn removes the need for the entire
9793 @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
9794 isn't needed you allow the optimizers to produce the most efficient code
9798 void DoCheck(uint32_t dwSomeValue)
9802 // Assumes dwSomeValue is not zero.
9812 The next example shows a case where the optimizers can recognize that the input
9813 (@code{dwSomeValue}) never changes during the execution of the function and can
9814 therefore move the @code{asm} outside the loop to produce more efficient code.
9815 Again, using the @code{volatile} qualifier disables this type of optimization.
9818 void do_print(uint32_t dwSomeValue)
9822 for (uint32_t x=0; x < 5; x++)
9824 // Assumes dwSomeValue is not zero.
9830 printf("%u: %u %u\n", x, dwSomeValue, dwRes);
9835 The following example demonstrates a case where you need to use the
9836 @code{volatile} qualifier.
9837 It uses the x86 @code{rdtsc} instruction, which reads
9838 the computer's time-stamp counter. Without the @code{volatile} qualifier,
9839 the optimizers might assume that the @code{asm} block will always return the
9840 same value and therefore optimize away the second call.
9845 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
9846 "shl $32, %%rdx\n\t" // Shift the upper bits left.
9847 "or %%rdx, %0" // 'Or' in the lower bits.
9852 printf("msr: %llx\n", msr);
9856 // Reprint the timestamp
9857 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
9858 "shl $32, %%rdx\n\t" // Shift the upper bits left.
9859 "or %%rdx, %0" // 'Or' in the lower bits.
9864 printf("msr: %llx\n", msr);
9867 GCC's optimizers do not treat this code like the non-volatile code in the
9868 earlier examples. They do not move it out of loops or omit it on the
9869 assumption that the result from a previous call is still valid.
9871 Note that the compiler can move even @code{volatile asm} instructions relative
9872 to other code, including across jump instructions. For example, on many
9873 targets there is a system register that controls the rounding mode of
9874 floating-point operations. Setting it with a @code{volatile asm} statement,
9875 as in the following PowerPC example, does not work reliably.
9878 asm volatile("mtfsf 255, %0" : : "f" (fpenv));
9882 The compiler may move the addition back before the @code{volatile asm}
9883 statement. To make it work as expected, add an artificial dependency to
9884 the @code{asm} by referencing a variable in the subsequent code, for
9888 asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
9892 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
9893 assembly code when optimizing. This can lead to unexpected duplicate symbol
9894 errors during compilation if your @code{asm} code defines symbols or labels.
9896 (@pxref{AssemblerTemplate}) may help resolve this problem.
9898 @anchor{AssemblerTemplate}
9899 @subsubsection Assembler Template
9900 @cindex @code{asm} assembler template
9902 An assembler template is a literal string containing assembler instructions.
9903 The compiler replaces tokens in the template that refer
9904 to inputs, outputs, and goto labels,
9905 and then outputs the resulting string to the assembler. The
9906 string can contain any instructions recognized by the assembler, including
9907 directives. GCC does not parse the assembler instructions
9908 themselves and does not know what they mean or even whether they are valid
9909 assembler input. However, it does count the statements
9910 (@pxref{Size of an asm}).
9912 You may place multiple assembler instructions together in a single @code{asm}
9913 string, separated by the characters normally used in assembly code for the
9914 system. A combination that works in most places is a newline to break the
9915 line, plus a tab character to move to the instruction field (written as
9917 Some assemblers allow semicolons as a line separator. However, note
9918 that some assembler dialects use semicolons to start a comment.
9920 Do not expect a sequence of @code{asm} statements to remain perfectly
9921 consecutive after compilation, even when you are using the @code{volatile}
9922 qualifier. If certain instructions need to remain consecutive in the output,
9923 put them in a single multi-instruction @code{asm} statement.
9925 Accessing data from C programs without using input/output operands (such as
9926 by using global symbols directly from the assembler template) may not work as
9927 expected. Similarly, calling functions directly from an assembler template
9928 requires a detailed understanding of the target assembler and ABI.
9930 Since GCC does not parse the assembler template,
9931 it has no visibility of any
9932 symbols it references. This may result in GCC discarding those symbols as
9933 unreferenced unless they are also listed as input, output, or goto operands.
9935 @subsubheading Special format strings
9937 In addition to the tokens described by the input, output, and goto operands,
9938 these tokens have special meanings in the assembler template:
9942 Outputs a single @samp{%} into the assembler code.
9945 Outputs a number that is unique to each instance of the @code{asm}
9946 statement in the entire compilation. This option is useful when creating local
9947 labels and referring to them multiple times in a single template that
9948 generates multiple assembler instructions.
9953 Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively)
9954 into the assembler code. When unescaped, these characters have special
9955 meaning to indicate multiple assembler dialects, as described below.
9958 @subsubheading Multiple assembler dialects in @code{asm} templates
9960 On targets such as x86, GCC supports multiple assembler dialects.
9961 The @option{-masm} option controls which dialect GCC uses as its
9962 default for inline assembler. The target-specific documentation for the
9963 @option{-masm} option contains the list of supported dialects, as well as the
9964 default dialect if the option is not specified. This information may be
9965 important to understand, since assembler code that works correctly when
9966 compiled using one dialect will likely fail if compiled using another.
9969 If your code needs to support multiple assembler dialects (for example, if
9970 you are writing public headers that need to support a variety of compilation
9971 options), use constructs of this form:
9974 @{ dialect0 | dialect1 | dialect2... @}
9977 This construct outputs @code{dialect0}
9978 when using dialect #0 to compile the code,
9979 @code{dialect1} for dialect #1, etc. If there are fewer alternatives within the
9980 braces than the number of dialects the compiler supports, the construct
9983 For example, if an x86 compiler supports two dialects
9984 (@samp{att}, @samp{intel}), an
9985 assembler template such as this:
9988 "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
9992 is equivalent to one of
9995 "btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */}
9996 "bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */}
9999 Using that same compiler, this code:
10002 "xchg@{l@}\t@{%%@}ebx, %1"
10006 corresponds to either
10009 "xchgl\t%%ebx, %1" @r{/* att dialect */}
10010 "xchg\tebx, %1" @r{/* intel dialect */}
10013 There is no support for nesting dialect alternatives.
10015 @anchor{OutputOperands}
10016 @subsubsection Output Operands
10017 @cindex @code{asm} output operands
10019 An @code{asm} statement has zero or more output operands indicating the names
10020 of C variables modified by the assembler code.
10022 In this i386 example, @code{old} (referred to in the template string as
10023 @code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset}
10024 (@code{%2}) is an input:
10029 __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
10030 "sbb %0,%0" // Use the CF to calculate old.
10031 : "=r" (old), "+rm" (*Base)
10038 Operands are separated by commas. Each operand has this format:
10041 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename})
10045 @item asmSymbolicName
10046 Specifies a symbolic name for the operand.
10047 Reference the name in the assembler template
10048 by enclosing it in square brackets
10049 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
10050 that contains the definition. Any valid C variable name is acceptable,
10051 including names already defined in the surrounding code. No two operands
10052 within the same @code{asm} statement can use the same symbolic name.
10054 When not using an @var{asmSymbolicName}, use the (zero-based) position
10056 in the list of operands in the assembler template. For example if there are
10057 three output operands, use @samp{%0} in the template to refer to the first,
10058 @samp{%1} for the second, and @samp{%2} for the third.
10061 A string constant specifying constraints on the placement of the operand;
10062 @xref{Constraints}, for details.
10064 Output constraints must begin with either @samp{=} (a variable overwriting an
10065 existing value) or @samp{+} (when reading and writing). When using
10066 @samp{=}, do not assume the location contains the existing value
10067 on entry to the @code{asm}, except
10068 when the operand is tied to an input; @pxref{InputOperands,,Input Operands}.
10070 After the prefix, there must be one or more additional constraints
10071 (@pxref{Constraints}) that describe where the value resides. Common
10072 constraints include @samp{r} for register and @samp{m} for memory.
10073 When you list more than one possible location (for example, @code{"=rm"}),
10074 the compiler chooses the most efficient one based on the current context.
10075 If you list as many alternates as the @code{asm} statement allows, you permit
10076 the optimizers to produce the best possible code.
10077 If you must use a specific register, but your Machine Constraints do not
10078 provide sufficient control to select the specific register you want,
10079 local register variables may provide a solution (@pxref{Local Register
10082 @item cvariablename
10083 Specifies a C lvalue expression to hold the output, typically a variable name.
10084 The enclosing parentheses are a required part of the syntax.
10088 When the compiler selects the registers to use to
10089 represent the output operands, it does not use any of the clobbered registers
10090 (@pxref{Clobbers and Scratch Registers}).
10092 Output operand expressions must be lvalues. The compiler cannot check whether
10093 the operands have data types that are reasonable for the instruction being
10094 executed. For output expressions that are not directly addressable (for
10095 example a bit-field), the constraint must allow a register. In that case, GCC
10096 uses the register as the output of the @code{asm}, and then stores that
10097 register into the output.
10099 Operands using the @samp{+} constraint modifier count as two operands
10100 (that is, both as input and output) towards the total maximum of 30 operands
10101 per @code{asm} statement.
10103 Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output
10104 operands that must not overlap an input. Otherwise,
10105 GCC may allocate the output operand in the same register as an unrelated
10106 input operand, on the assumption that the assembler code consumes its
10107 inputs before producing outputs. This assumption may be false if the assembler
10108 code actually consists of more than one instruction.
10110 The same problem can occur if one output parameter (@var{a}) allows a register
10111 constraint and another output parameter (@var{b}) allows a memory constraint.
10112 The code generated by GCC to access the memory address in @var{b} can contain
10113 registers which @emph{might} be shared by @var{a}, and GCC considers those
10114 registers to be inputs to the asm. As above, GCC assumes that such input
10115 registers are consumed before any outputs are written. This assumption may
10116 result in incorrect behavior if the @code{asm} statement writes to @var{a}
10118 @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a}
10119 ensures that modifying @var{a} does not affect the address referenced by
10120 @var{b}. Otherwise, the location of @var{b}
10121 is undefined if @var{a} is modified before using @var{b}.
10123 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
10124 instead of simply @samp{%2}). Typically these qualifiers are hardware
10125 dependent. The list of supported modifiers for x86 is found at
10126 @ref{x86Operandmodifiers,x86 Operand modifiers}.
10128 If the C code that follows the @code{asm} makes no use of any of the output
10129 operands, use @code{volatile} for the @code{asm} statement to prevent the
10130 optimizers from discarding the @code{asm} statement as unneeded
10131 (see @ref{Volatile}).
10133 This code makes no use of the optional @var{asmSymbolicName}. Therefore it
10134 references the first output operand as @code{%0} (were there a second, it
10135 would be @code{%1}, etc). The number of the first input operand is one greater
10136 than that of the last output operand. In this i386 example, that makes
10137 @code{Mask} referenced as @code{%1}:
10140 uint32_t Mask = 1234;
10149 That code overwrites the variable @code{Index} (@samp{=}),
10150 placing the value in a register (@samp{r}).
10151 Using the generic @samp{r} constraint instead of a constraint for a specific
10152 register allows the compiler to pick the register to use, which can result
10153 in more efficient code. This may not be possible if an assembler instruction
10154 requires a specific register.
10156 The following i386 example uses the @var{asmSymbolicName} syntax.
10158 same result as the code above, but some may consider it more readable or more
10159 maintainable since reordering index numbers is not necessary when adding or
10160 removing operands. The names @code{aIndex} and @code{aMask}
10161 are only used in this example to emphasize which
10162 names get used where.
10163 It is acceptable to reuse the names @code{Index} and @code{Mask}.
10166 uint32_t Mask = 1234;
10169 asm ("bsfl %[aMask], %[aIndex]"
10170 : [aIndex] "=r" (Index)
10171 : [aMask] "r" (Mask)
10175 Here are some more examples of output operands.
10182 asm ("mov %[e], %[d]"
10187 Here, @code{d} may either be in a register or in memory. Since the compiler
10188 might already have the current value of the @code{uint32_t} location
10189 pointed to by @code{e}
10190 in a register, you can enable it to choose the best location
10191 for @code{d} by specifying both constraints.
10193 @anchor{FlagOutputOperands}
10194 @subsubsection Flag Output Operands
10195 @cindex @code{asm} flag output operands
10197 Some targets have a special register that holds the ``flags'' for the
10198 result of an operation or comparison. Normally, the contents of that
10199 register are either unmodifed by the asm, or the @code{asm} statement is
10200 considered to clobber the contents.
10202 On some targets, a special form of output operand exists by which
10203 conditions in the flags register may be outputs of the asm. The set of
10204 conditions supported are target specific, but the general rule is that
10205 the output variable must be a scalar integer, and the value is boolean.
10206 When supported, the target defines the preprocessor symbol
10207 @code{__GCC_ASM_FLAG_OUTPUTS__}.
10209 Because of the special nature of the flag output operands, the constraint
10210 may not include alternatives.
10212 Most often, the target has only one flags register, and thus is an implied
10213 operand of many instructions. In this case, the operand should not be
10214 referenced within the assembler template via @code{%0} etc, as there's
10215 no corresponding text in the assembly language.
10220 The flag output constraints for the ARM family are of the form
10221 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
10222 conditions defined in the ARM ARM for @code{ConditionHolds}.
10226 Z flag set, or equal
10228 Z flag clear or not equal
10231 C flag set or unsigned greater than equal
10234 C flag clear or unsigned less than
10236 N flag set or ``minus''
10238 N flag clear or ``plus''
10240 V flag set or signed overflow
10244 unsigned greater than
10246 unsigned less than equal
10248 signed greater than equal
10252 signed greater than
10254 signed less than equal
10257 The flag output constraints are not supported in thumb1 mode.
10260 The flag output constraints for the x86 family are of the form
10261 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
10262 conditions defined in the ISA manual for @code{j@var{cc}} or
10263 @code{set@var{cc}}.
10267 ``above'' or unsigned greater than
10269 ``above or equal'' or unsigned greater than or equal
10271 ``below'' or unsigned less than
10273 ``below or equal'' or unsigned less than or equal
10278 ``equal'' or zero flag set
10280 signed greater than
10282 signed greater than or equal
10286 signed less than or equal
10307 ``not'' @var{flag}, or inverted versions of those above
10312 @anchor{InputOperands}
10313 @subsubsection Input Operands
10314 @cindex @code{asm} input operands
10315 @cindex @code{asm} expressions
10317 Input operands make values from C variables and expressions available to the
10320 Operands are separated by commas. Each operand has this format:
10323 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression})
10327 @item asmSymbolicName
10328 Specifies a symbolic name for the operand.
10329 Reference the name in the assembler template
10330 by enclosing it in square brackets
10331 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
10332 that contains the definition. Any valid C variable name is acceptable,
10333 including names already defined in the surrounding code. No two operands
10334 within the same @code{asm} statement can use the same symbolic name.
10336 When not using an @var{asmSymbolicName}, use the (zero-based) position
10338 in the list of operands in the assembler template. For example if there are
10339 two output operands and three inputs,
10340 use @samp{%2} in the template to refer to the first input operand,
10341 @samp{%3} for the second, and @samp{%4} for the third.
10344 A string constant specifying constraints on the placement of the operand;
10345 @xref{Constraints}, for details.
10347 Input constraint strings may not begin with either @samp{=} or @samp{+}.
10348 When you list more than one possible location (for example, @samp{"irm"}),
10349 the compiler chooses the most efficient one based on the current context.
10350 If you must use a specific register, but your Machine Constraints do not
10351 provide sufficient control to select the specific register you want,
10352 local register variables may provide a solution (@pxref{Local Register
10355 Input constraints can also be digits (for example, @code{"0"}). This indicates
10356 that the specified input must be in the same place as the output constraint
10357 at the (zero-based) index in the output constraint list.
10358 When using @var{asmSymbolicName} syntax for the output operands,
10359 you may use these names (enclosed in brackets @samp{[]}) instead of digits.
10362 This is the C variable or expression being passed to the @code{asm} statement
10363 as input. The enclosing parentheses are a required part of the syntax.
10367 When the compiler selects the registers to use to represent the input
10368 operands, it does not use any of the clobbered registers
10369 (@pxref{Clobbers and Scratch Registers}).
10371 If there are no output operands but there are input operands, place two
10372 consecutive colons where the output operands would go:
10375 __asm__ ("some instructions"
10376 : /* No outputs. */
10377 : "r" (Offset / 8));
10380 @strong{Warning:} Do @emph{not} modify the contents of input-only operands
10381 (except for inputs tied to outputs). The compiler assumes that on exit from
10382 the @code{asm} statement these operands contain the same values as they
10383 had before executing the statement.
10384 It is @emph{not} possible to use clobbers
10385 to inform the compiler that the values in these inputs are changing. One
10386 common work-around is to tie the changing input variable to an output variable
10387 that never gets used. Note, however, that if the code that follows the
10388 @code{asm} statement makes no use of any of the output operands, the GCC
10389 optimizers may discard the @code{asm} statement as unneeded
10390 (see @ref{Volatile}).
10392 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
10393 instead of simply @samp{%2}). Typically these qualifiers are hardware
10394 dependent. The list of supported modifiers for x86 is found at
10395 @ref{x86Operandmodifiers,x86 Operand modifiers}.
10397 In this example using the fictitious @code{combine} instruction, the
10398 constraint @code{"0"} for input operand 1 says that it must occupy the same
10399 location as output operand 0. Only input operands may use numbers in
10400 constraints, and they must each refer to an output operand. Only a number (or
10401 the symbolic assembler name) in the constraint can guarantee that one operand
10402 is in the same place as another. The mere fact that @code{foo} is the value of
10403 both operands is not enough to guarantee that they are in the same place in
10404 the generated assembler code.
10407 asm ("combine %2, %0"
10409 : "0" (foo), "g" (bar));
10412 Here is an example using symbolic names.
10415 asm ("cmoveq %1, %2, %[result]"
10416 : [result] "=r"(result)
10417 : "r" (test), "r" (new), "[result]" (old));
10420 @anchor{Clobbers and Scratch Registers}
10421 @subsubsection Clobbers and Scratch Registers
10422 @cindex @code{asm} clobbers
10423 @cindex @code{asm} scratch registers
10425 While the compiler is aware of changes to entries listed in the output
10426 operands, the inline @code{asm} code may modify more than just the outputs. For
10427 example, calculations may require additional registers, or the processor may
10428 overwrite a register as a side effect of a particular assembler instruction.
10429 In order to inform the compiler of these changes, list them in the clobber
10430 list. Clobber list items are either register names or the special clobbers
10431 (listed below). Each clobber list item is a string constant
10432 enclosed in double quotes and separated by commas.
10434 Clobber descriptions may not in any way overlap with an input or output
10435 operand. For example, you may not have an operand describing a register class
10436 with one member when listing that register in the clobber list. Variables
10437 declared to live in specific registers (@pxref{Explicit Register
10438 Variables}) and used
10439 as @code{asm} input or output operands must have no part mentioned in the
10440 clobber description. In particular, there is no way to specify that input
10441 operands get modified without also specifying them as output operands.
10443 When the compiler selects which registers to use to represent input and output
10444 operands, it does not use any of the clobbered registers. As a result,
10445 clobbered registers are available for any use in the assembler code.
10447 Another restriction is that the clobber list should not contain the
10448 stack pointer register. This is because the compiler requires the
10449 value of the stack pointer to be the same after an @code{asm}
10450 statement as it was on entry to the statement. However, previous
10451 versions of GCC did not enforce this rule and allowed the stack
10452 pointer to appear in the list, with unclear semantics. This behavior
10453 is deprecated and listing the stack pointer may become an error in
10454 future versions of GCC@.
10456 Here is a realistic example for the VAX showing the use of clobbered
10460 asm volatile ("movc3 %0, %1, %2"
10461 : /* No outputs. */
10462 : "g" (from), "g" (to), "g" (count)
10463 : "r0", "r1", "r2", "r3", "r4", "r5", "memory");
10466 Also, there are two special clobber arguments:
10470 The @code{"cc"} clobber indicates that the assembler code modifies the flags
10471 register. On some machines, GCC represents the condition codes as a specific
10472 hardware register; @code{"cc"} serves to name this register.
10473 On other machines, condition code handling is different,
10474 and specifying @code{"cc"} has no effect. But
10475 it is valid no matter what the target.
10478 The @code{"memory"} clobber tells the compiler that the assembly code
10480 reads or writes to items other than those listed in the input and output
10481 operands (for example, accessing the memory pointed to by one of the input
10482 parameters). To ensure memory contains correct values, GCC may need to flush
10483 specific register values to memory before executing the @code{asm}. Further,
10484 the compiler does not assume that any values read from memory before an
10485 @code{asm} remain unchanged after that @code{asm}; it reloads them as
10487 Using the @code{"memory"} clobber effectively forms a read/write
10488 memory barrier for the compiler.
10490 Note that this clobber does not prevent the @emph{processor} from doing
10491 speculative reads past the @code{asm} statement. To prevent that, you need
10492 processor-specific fence instructions.
10496 Flushing registers to memory has performance implications and may be
10497 an issue for time-sensitive code. You can provide better information
10498 to GCC to avoid this, as shown in the following examples. At a
10499 minimum, aliasing rules allow GCC to know what memory @emph{doesn't}
10500 need to be flushed.
10502 Here is a fictitious sum of squares instruction, that takes two
10503 pointers to floating point values in memory and produces a floating
10504 point register output.
10505 Notice that @code{x}, and @code{y} both appear twice in the @code{asm}
10506 parameters, once to specify memory accessed, and once to specify a
10507 base register used by the @code{asm}. You won't normally be wasting a
10508 register by doing this as GCC can use the same register for both
10509 purposes. However, it would be foolish to use both @code{%1} and
10510 @code{%3} for @code{x} in this @code{asm} and expect them to be the
10511 same. In fact, @code{%3} may well not be a register. It might be a
10512 symbolic memory reference to the object pointed to by @code{x}.
10515 asm ("sumsq %0, %1, %2"
10517 : "r" (x), "r" (y), "m" (*x), "m" (*y));
10520 Here is a fictitious @code{*z++ = *x++ * *y++} instruction.
10521 Notice that the @code{x}, @code{y} and @code{z} pointer registers
10522 must be specified as input/output because the @code{asm} modifies
10526 asm ("vecmul %0, %1, %2"
10527 : "+r" (z), "+r" (x), "+r" (y), "=m" (*z)
10528 : "m" (*x), "m" (*y));
10531 An x86 example where the string memory argument is of unknown length.
10535 : "=c" (count), "+D" (p)
10536 : "m" (*(const char (*)[]) p), "0" (-1), "a" (0));
10539 If you know the above will only be reading a ten byte array then you
10540 could instead use a memory input like:
10541 @code{"m" (*(const char (*)[10]) p)}.
10543 Here is an example of a PowerPC vector scale implemented in assembly,
10544 complete with vector and condition code clobbers, and some initialized
10545 offset registers that are unchanged by the @code{asm}.
10549 dscal (size_t n, double *x, double alpha)
10551 asm ("/* lots of asm here */"
10552 : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x)
10553 : "d" (alpha), "b" (32), "b" (48), "b" (64),
10554 "b" (80), "b" (96), "b" (112)
10556 "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39",
10557 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47");
10561 Rather than allocating fixed registers via clobbers to provide scratch
10562 registers for an @code{asm} statement, an alternative is to define a
10563 variable and make it an early-clobber output as with @code{a2} and
10564 @code{a3} in the example below. This gives the compiler register
10565 allocator more freedom. You can also define a variable and make it an
10566 output tied to an input as with @code{a0} and @code{a1}, tied
10567 respectively to @code{ap} and @code{lda}. Of course, with tied
10568 outputs your @code{asm} can't use the input value after modifying the
10569 output register since they are one and the same register. What's
10570 more, if you omit the early-clobber on the output, it is possible that
10571 GCC might allocate the same register to another of the inputs if GCC
10572 could prove they had the same value on entry to the @code{asm}. This
10573 is why @code{a1} has an early-clobber. Its tied input, @code{lda}
10574 might conceivably be known to have the value 16 and without an
10575 early-clobber share the same register as @code{%11}. On the other
10576 hand, @code{ap} can't be the same as any of the other inputs, so an
10577 early-clobber on @code{a0} is not needed. It is also not desirable in
10578 this case. An early-clobber on @code{a0} would cause GCC to allocate
10579 a separate register for the @code{"m" (*(const double (*)[]) ap)}
10580 input. Note that tying an input to an output is the way to set up an
10581 initialized temporary register modified by an @code{asm} statement.
10582 An input not tied to an output is assumed by GCC to be unchanged, for
10583 example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might
10584 use that register in following code if the value 16 happened to be
10585 needed. You can even use a normal @code{asm} output for a scratch if
10586 all inputs that might share the same register are consumed before the
10587 scratch is used. The VSX registers clobbered by the @code{asm}
10588 statement could have used this technique except for GCC's limit on the
10589 number of @code{asm} parameters.
10593 dgemv_kernel_4x4 (long n, const double *ap, long lda,
10594 const double *x, double *y, double alpha)
10603 /* lots of asm here */
10604 "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n"
10605 "#a0=%3 a1=%4 a2=%5 a3=%6"
10607 "+m" (*(double (*)[n]) y),
10615 "m" (*(const double (*)[n]) x),
10616 "m" (*(const double (*)[]) ap),
10624 "vs32","vs33","vs34","vs35","vs36","vs37",
10625 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"
10630 @anchor{GotoLabels}
10631 @subsubsection Goto Labels
10632 @cindex @code{asm} goto labels
10634 @code{asm goto} allows assembly code to jump to one or more C labels. The
10635 @var{GotoLabels} section in an @code{asm goto} statement contains
10637 list of all C labels to which the assembler code may jump. GCC assumes that
10638 @code{asm} execution falls through to the next statement (if this is not the
10639 case, consider using the @code{__builtin_unreachable} intrinsic after the
10640 @code{asm} statement). Optimization of @code{asm goto} may be improved by
10641 using the @code{hot} and @code{cold} label attributes (@pxref{Label
10644 If the assembler code does modify anything, use the @code{"memory"} clobber
10646 optimizers to flush all register values to memory and reload them if
10647 necessary after the @code{asm} statement.
10649 Also note that an @code{asm goto} statement is always implicitly
10650 considered volatile.
10652 Be careful when you set output operands inside @code{asm goto} only on
10653 some possible control flow paths. If you don't set up the output on
10654 given path and never use it on this path, it is okay. Otherwise, you
10655 should use @samp{+} constraint modifier meaning that the operand is
10656 input and output one. With this modifier you will have the correct
10657 values on all possible paths from the @code{asm goto}.
10659 To reference a label in the assembler template,
10660 prefix it with @samp{%l} (lowercase @samp{L}) followed
10661 by its (zero-based) position in @var{GotoLabels} plus the number of input
10662 operands. For example, if the @code{asm} has three inputs and references two
10663 labels, refer to the first label as @samp{%l3} and the second as @samp{%l4}).
10665 Alternately, you can reference labels using the actual C label name enclosed
10666 in brackets. For example, to reference a label named @code{carry}, you can
10667 use @samp{%l[carry]}. The label must still be listed in the @var{GotoLabels}
10668 section when using this approach.
10670 Here is an example of @code{asm goto} for i386:
10676 : /* No outputs. */
10677 : "r" (p1), "r" (p2)
10687 The following example shows an @code{asm goto} that uses a memory clobber.
10693 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
10694 : /* No outputs. */
10704 The following example shows an @code{asm goto} that uses an output.
10709 asm goto ("dec %0; jb %l[stop]"
10720 The following artificial example shows an @code{asm goto} that sets
10721 up an output only on one path inside the @code{asm goto}. Usage of
10722 constraint modifier @code{=} instead of @code{+} would be wrong as
10723 @code{factor} is used on all paths from the @code{asm goto}.
10729 asm goto ("cmp %1, 10; jb %l[lab]; mov 2, %0"
10735 return inp * factor; /* return 2 * inp or 0 if inp < 10 */
10739 @anchor{x86Operandmodifiers}
10740 @subsubsection x86 Operand Modifiers
10742 References to input, output, and goto operands in the assembler template
10743 of extended @code{asm} statements can use
10744 modifiers to affect the way the operands are formatted in
10745 the code output to the assembler. For example, the
10746 following code uses the @samp{h} and @samp{b} modifiers for x86:
10750 asm volatile ("xchg %h0, %b0" : "+a" (num) );
10754 These modifiers generate this assembler code:
10760 The rest of this discussion uses the following code for illustrative purposes.
10769 asm volatile goto ("some assembler instructions here"
10770 : /* No outputs. */
10771 : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42)
10772 : /* No clobbers. */
10777 With no modifiers, this is what the output from the operands would be
10778 for the @samp{att} and @samp{intel} dialects of assembler:
10780 @multitable {Operand} {$.L2} {OFFSET FLAT:.L2}
10781 @headitem Operand @tab @samp{att} @tab @samp{intel}
10790 @tab @code{OFFSET FLAT:.L3}
10802 The table below shows the list of supported modifiers and their effects.
10804 @multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}}
10805 @headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel}
10807 @tab Print an absolute memory reference.
10812 @tab Print the QImode name of the register.
10817 @tab print the opcode suffix of b.
10822 @tab Require a constant operand and print the constant expression with no punctuation.
10827 @tab print duplicated register operand for AVX instruction.
10829 @tab @code{%xmm0, %xmm0}
10830 @tab @code{xmm0, xmm0}
10832 @tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit.
10833 Otherwise mode is unspecified (VOIDmode).
10838 @tab Print the V16SFmode name of the register.
10843 @tab Print the QImode name for a ``high'' register.
10848 @tab Add 8 bytes to an offsettable memory reference. Useful when accessing the
10849 high 8 bytes of SSE values. For a memref in (%rax), it generates
10851 @tab @code{8(%rax)}
10854 @tab Print the SImode name of the register.
10859 @tab Print the label name with no punctuation.
10864 @tab print the opcode suffix of l.
10874 @tab Print raw symbol name (without syntax-specific prefixes).
10879 @tab If used for a function, print the PLT suffix and generate PIC code.
10880 For example, emit @code{foo@@PLT} instead of 'foo' for the function
10881 foo(). If used for a constant, drop all syntax-specific prefixes and
10882 issue the bare constant. See @code{p} above.
10884 @tab Print the DImode name of the register.
10889 @tab print the opcode suffix of q.
10894 @tab print embedded rounding and sae.
10896 @tab @code{@{rn-sae@}, }
10897 @tab @code{, @{rn-sae@}}
10899 @tab print only sae.
10901 @tab @code{@{sae@}, }
10902 @tab @code{, @{sae@}}
10904 @tab print a shift double count, followed by the assemblers argument
10905 delimiterprint the opcode suffix of s.
10910 @tab print the opcode suffix of s.
10915 @tab print the V8SFmode name of the register.
10920 @tab print the opcode suffix of t.
10925 @tab print naked full integer register name without %.
10930 @tab Print the HImode name of the register.
10935 @tab print the opcode suffix of w.
10940 @tab print the V4SFmode name of the register.
10945 @tab print "st(0)" instead of "st" as a register.
10950 @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}).
10955 @tab Like @code{z}, with special suffixes for x87 instructions.
10959 @anchor{x86floatingpointasmoperands}
10960 @subsubsection x86 Floating-Point @code{asm} Operands
10962 On x86 targets, there are several rules on the usage of stack-like registers
10963 in the operands of an @code{asm}. These rules apply only to the operands
10964 that are stack-like registers:
10968 Given a set of input registers that die in an @code{asm}, it is
10969 necessary to know which are implicitly popped by the @code{asm}, and
10970 which must be explicitly popped by GCC@.
10972 An input register that is implicitly popped by the @code{asm} must be
10973 explicitly clobbered, unless it is constrained to match an
10977 For any input register that is implicitly popped by an @code{asm}, it is
10978 necessary to know how to adjust the stack to compensate for the pop.
10979 If any non-popped input is closer to the top of the reg-stack than
10980 the implicitly popped register, it would not be possible to know what the
10981 stack looked like---it's not clear how the rest of the stack ``slides
10984 All implicitly popped input registers must be closer to the top of
10985 the reg-stack than any input that is not implicitly popped.
10987 It is possible that if an input dies in an @code{asm}, the compiler might
10988 use the input register for an output reload. Consider this example:
10991 asm ("foo" : "=t" (a) : "f" (b));
10995 This code says that input @code{b} is not popped by the @code{asm}, and that
10996 the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one
10997 deeper after the @code{asm} than it was before. But, it is possible that
10998 reload may think that it can use the same register for both the input and
11001 To prevent this from happening,
11002 if any input operand uses the @samp{f} constraint, all output register
11003 constraints must use the @samp{&} early-clobber modifier.
11005 The example above is correctly written as:
11008 asm ("foo" : "=&t" (a) : "f" (b));
11012 Some operands need to be in particular places on the stack. All
11013 output operands fall in this category---GCC has no other way to
11014 know which registers the outputs appear in unless you indicate
11015 this in the constraints.
11017 Output operands must specifically indicate which register an output
11018 appears in after an @code{asm}. @samp{=f} is not allowed: the operand
11019 constraints must select a class with a single register.
11022 Output operands may not be ``inserted'' between existing stack registers.
11023 Since no 387 opcode uses a read/write operand, all output operands
11024 are dead before the @code{asm}, and are pushed by the @code{asm}.
11025 It makes no sense to push anywhere but the top of the reg-stack.
11027 Output operands must start at the top of the reg-stack: output
11028 operands may not ``skip'' a register.
11031 Some @code{asm} statements may need extra stack space for internal
11032 calculations. This can be guaranteed by clobbering stack registers
11033 unrelated to the inputs and outputs.
11038 takes one input, which is internally popped, and produces two outputs.
11041 asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
11045 This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode,
11046 and replaces them with one output. The @code{st(1)} clobber is necessary
11047 for the compiler to know that @code{fyl2xp1} pops both inputs.
11050 asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
11053 @anchor{msp430Operandmodifiers}
11054 @subsubsection MSP430 Operand Modifiers
11056 The list below describes the supported modifiers and their effects for MSP430.
11058 @multitable @columnfractions .10 .90
11059 @headitem Modifier @tab Description
11060 @item @code{A} @tab Select low 16-bits of the constant/register/memory operand.
11061 @item @code{B} @tab Select high 16-bits of the constant/register/memory
11063 @item @code{C} @tab Select bits 32-47 of the constant/register/memory operand.
11064 @item @code{D} @tab Select bits 48-63 of the constant/register/memory operand.
11065 @item @code{H} @tab Equivalent to @code{B} (for backwards compatibility).
11066 @item @code{I} @tab Print the inverse (logical @code{NOT}) of the constant
11068 @item @code{J} @tab Print an integer without a @code{#} prefix.
11069 @item @code{L} @tab Equivalent to @code{A} (for backwards compatibility).
11070 @item @code{O} @tab Offset of the current frame from the top of the stack.
11071 @item @code{Q} @tab Use the @code{A} instruction postfix.
11072 @item @code{R} @tab Inverse of condition code, for unsigned comparisons.
11073 @item @code{W} @tab Subtract 16 from the constant value.
11074 @item @code{X} @tab Use the @code{X} instruction postfix.
11075 @item @code{Y} @tab Subtract 4 from the constant value.
11076 @item @code{Z} @tab Subtract 1 from the constant value.
11077 @item @code{b} @tab Append @code{.B}, @code{.W} or @code{.A} to the
11078 instruction, depending on the mode.
11079 @item @code{d} @tab Offset 1 byte of a memory reference or constant value.
11080 @item @code{e} @tab Offset 3 bytes of a memory reference or constant value.
11081 @item @code{f} @tab Offset 5 bytes of a memory reference or constant value.
11082 @item @code{g} @tab Offset 7 bytes of a memory reference or constant value.
11083 @item @code{p} @tab Print the value of 2, raised to the power of the given
11084 constant. Used to select the specified bit position.
11085 @item @code{r} @tab Inverse of condition code, for signed comparisons.
11086 @item @code{x} @tab Equivialent to @code{X}, but only for pointers.
11094 @subsection Controlling Names Used in Assembler Code
11095 @cindex assembler names for identifiers
11096 @cindex names used in assembler code
11097 @cindex identifiers, names in assembler code
11099 You can specify the name to be used in the assembler code for a C
11100 function or variable by writing the @code{asm} (or @code{__asm__})
11101 keyword after the declarator.
11102 It is up to you to make sure that the assembler names you choose do not
11103 conflict with any other assembler symbols, or reference registers.
11105 @subsubheading Assembler names for data:
11107 This sample shows how to specify the assembler name for data:
11110 int foo asm ("myfoo") = 2;
11114 This specifies that the name to be used for the variable @code{foo} in
11115 the assembler code should be @samp{myfoo} rather than the usual
11118 On systems where an underscore is normally prepended to the name of a C
11119 variable, this feature allows you to define names for the
11120 linker that do not start with an underscore.
11122 GCC does not support using this feature with a non-static local variable
11123 since such variables do not have assembler names. If you are
11124 trying to put the variable in a particular register, see
11125 @ref{Explicit Register Variables}.
11127 @subsubheading Assembler names for functions:
11129 To specify the assembler name for functions, write a declaration for the
11130 function before its definition and put @code{asm} there, like this:
11133 int func (int x, int y) asm ("MYFUNC");
11135 int func (int x, int y)
11141 This specifies that the name to be used for the function @code{func} in
11142 the assembler code should be @code{MYFUNC}.
11144 @node Explicit Register Variables
11145 @subsection Variables in Specified Registers
11146 @anchor{Explicit Reg Vars}
11147 @cindex explicit register variables
11148 @cindex variables in specified registers
11149 @cindex specified registers
11151 GNU C allows you to associate specific hardware registers with C
11152 variables. In almost all cases, allowing the compiler to assign
11153 registers produces the best code. However under certain unusual
11154 circumstances, more precise control over the variable storage is
11157 Both global and local variables can be associated with a register. The
11158 consequences of performing this association are very different between
11159 the two, as explained in the sections below.
11162 * Global Register Variables:: Variables declared at global scope.
11163 * Local Register Variables:: Variables declared within a function.
11166 @node Global Register Variables
11167 @subsubsection Defining Global Register Variables
11168 @anchor{Global Reg Vars}
11169 @cindex global register variables
11170 @cindex registers, global variables in
11171 @cindex registers, global allocation
11173 You can define a global register variable and associate it with a specified
11174 register like this:
11177 register int *foo asm ("r12");
11181 Here @code{r12} is the name of the register that should be used. Note that
11182 this is the same syntax used for defining local register variables, but for
11183 a global variable the declaration appears outside a function. The
11184 @code{register} keyword is required, and cannot be combined with
11185 @code{static}. The register name must be a valid register name for the
11188 Do not use type qualifiers such as @code{const} and @code{volatile}, as
11189 the outcome may be contrary to expectations. In particular, using the
11190 @code{volatile} qualifier does not fully prevent the compiler from
11191 optimizing accesses to the register.
11193 Registers are a scarce resource on most systems and allowing the
11194 compiler to manage their usage usually results in the best code. However,
11195 under special circumstances it can make sense to reserve some globally.
11196 For example this may be useful in programs such as programming language
11197 interpreters that have a couple of global variables that are accessed
11200 After defining a global register variable, for the current compilation
11204 @item If the register is a call-saved register, call ABI is affected:
11205 the register will not be restored in function epilogue sequences after
11206 the variable has been assigned. Therefore, functions cannot safely
11207 return to callers that assume standard ABI.
11208 @item Conversely, if the register is a call-clobbered register, making
11209 calls to functions that use standard ABI may lose contents of the variable.
11210 Such calls may be created by the compiler even if none are evident in
11211 the original program, for example when libgcc functions are used to
11212 make up for unavailable instructions.
11213 @item Accesses to the variable may be optimized as usual and the register
11214 remains available for allocation and use in any computations, provided that
11215 observable values of the variable are not affected.
11216 @item If the variable is referenced in inline assembly, the type of access
11217 must be provided to the compiler via constraints (@pxref{Constraints}).
11218 Accesses from basic asms are not supported.
11221 Note that these points @emph{only} apply to code that is compiled with the
11222 definition. The behavior of code that is merely linked in (for example
11223 code from libraries) is not affected.
11225 If you want to recompile source files that do not actually use your global
11226 register variable so they do not use the specified register for any other
11227 purpose, you need not actually add the global register declaration to
11228 their source code. It suffices to specify the compiler option
11229 @option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the
11232 @subsubheading Declaring the variable
11234 Global register variables cannot have initial values, because an
11235 executable file has no means to supply initial contents for a register.
11237 When selecting a register, choose one that is normally saved and
11238 restored by function calls on your machine. This ensures that code
11239 which is unaware of this reservation (such as library routines) will
11240 restore it before returning.
11242 On machines with register windows, be sure to choose a global
11243 register that is not affected magically by the function call mechanism.
11245 @subsubheading Using the variable
11247 @cindex @code{qsort}, and global register variables
11248 When calling routines that are not aware of the reservation, be
11249 cautious if those routines call back into code which uses them. As an
11250 example, if you call the system library version of @code{qsort}, it may
11251 clobber your registers during execution, but (if you have selected
11252 appropriate registers) it will restore them before returning. However
11253 it will @emph{not} restore them before calling @code{qsort}'s comparison
11254 function. As a result, global values will not reliably be available to
11255 the comparison function unless the @code{qsort} function itself is rebuilt.
11257 Similarly, it is not safe to access the global register variables from signal
11258 handlers or from more than one thread of control. Unless you recompile
11259 them specially for the task at hand, the system library routines may
11260 temporarily use the register for other things. Furthermore, since the register
11261 is not reserved exclusively for the variable, accessing it from handlers of
11262 asynchronous signals may observe unrelated temporary values residing in the
11265 @cindex register variable after @code{longjmp}
11266 @cindex global register after @code{longjmp}
11267 @cindex value after @code{longjmp}
11270 On most machines, @code{longjmp} restores to each global register
11271 variable the value it had at the time of the @code{setjmp}. On some
11272 machines, however, @code{longjmp} does not change the value of global
11273 register variables. To be portable, the function that called @code{setjmp}
11274 should make other arrangements to save the values of the global register
11275 variables, and to restore them in a @code{longjmp}. This way, the same
11276 thing happens regardless of what @code{longjmp} does.
11278 @node Local Register Variables
11279 @subsubsection Specifying Registers for Local Variables
11280 @anchor{Local Reg Vars}
11281 @cindex local variables, specifying registers
11282 @cindex specifying registers for local variables
11283 @cindex registers for local variables
11285 You can define a local register variable and associate it with a specified
11286 register like this:
11289 register int *foo asm ("r12");
11293 Here @code{r12} is the name of the register that should be used. Note
11294 that this is the same syntax used for defining global register variables,
11295 but for a local variable the declaration appears within a function. The
11296 @code{register} keyword is required, and cannot be combined with
11297 @code{static}. The register name must be a valid register name for the
11300 Do not use type qualifiers such as @code{const} and @code{volatile}, as
11301 the outcome may be contrary to expectations. In particular, when the
11302 @code{const} qualifier is used, the compiler may substitute the
11303 variable with its initializer in @code{asm} statements, which may cause
11304 the corresponding operand to appear in a different register.
11306 As with global register variables, it is recommended that you choose
11307 a register that is normally saved and restored by function calls on your
11308 machine, so that calls to library routines will not clobber it.
11310 The only supported use for this feature is to specify registers
11311 for input and output operands when calling Extended @code{asm}
11312 (@pxref{Extended Asm}). This may be necessary if the constraints for a
11313 particular machine don't provide sufficient control to select the desired
11314 register. To force an operand into a register, create a local variable
11315 and specify the register name after the variable's declaration. Then use
11316 the local variable for the @code{asm} operand and specify any constraint
11317 letter that matches the register:
11320 register int *p1 asm ("r0") = @dots{};
11321 register int *p2 asm ("r1") = @dots{};
11322 register int *result asm ("r0");
11323 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
11326 @emph{Warning:} In the above example, be aware that a register (for example
11327 @code{r0}) can be call-clobbered by subsequent code, including function
11328 calls and library calls for arithmetic operators on other variables (for
11329 example the initialization of @code{p2}). In this case, use temporary
11330 variables for expressions between the register assignments:
11334 register int *p1 asm ("r0") = @dots{};
11335 register int *p2 asm ("r1") = t1;
11336 register int *result asm ("r0");
11337 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
11340 Defining a register variable does not reserve the register. Other than
11341 when invoking the Extended @code{asm}, the contents of the specified
11342 register are not guaranteed. For this reason, the following uses
11343 are explicitly @emph{not} supported. If they appear to work, it is only
11344 happenstance, and may stop working as intended due to (seemingly)
11345 unrelated changes in surrounding code, or even minor changes in the
11346 optimization of a future version of gcc:
11349 @item Passing parameters to or from Basic @code{asm}
11350 @item Passing parameters to or from Extended @code{asm} without using input
11351 or output operands.
11352 @item Passing parameters to or from routines written in assembler (or
11353 other languages) using non-standard calling conventions.
11356 Some developers use Local Register Variables in an attempt to improve
11357 gcc's allocation of registers, especially in large functions. In this
11358 case the register name is essentially a hint to the register allocator.
11359 While in some instances this can generate better code, improvements are
11360 subject to the whims of the allocator/optimizers. Since there are no
11361 guarantees that your improvements won't be lost, this usage of Local
11362 Register Variables is discouraged.
11364 On the MIPS platform, there is related use for local register variables
11365 with slightly different characteristics (@pxref{MIPS Coprocessors,,
11366 Defining coprocessor specifics for MIPS targets, gccint,
11367 GNU Compiler Collection (GCC) Internals}).
11369 @node Size of an asm
11370 @subsection Size of an @code{asm}
11372 Some targets require that GCC track the size of each instruction used
11373 in order to generate correct code. Because the final length of the
11374 code produced by an @code{asm} statement is only known by the
11375 assembler, GCC must make an estimate as to how big it will be. It
11376 does this by counting the number of instructions in the pattern of the
11377 @code{asm} and multiplying that by the length of the longest
11378 instruction supported by that processor. (When working out the number
11379 of instructions, it assumes that any occurrence of a newline or of
11380 whatever statement separator character is supported by the assembler ---
11381 typically @samp{;} --- indicates the end of an instruction.)
11383 Normally, GCC's estimate is adequate to ensure that correct
11384 code is generated, but it is possible to confuse the compiler if you use
11385 pseudo instructions or assembler macros that expand into multiple real
11386 instructions, or if you use assembler directives that expand to more
11387 space in the object file than is needed for a single instruction.
11388 If this happens then the assembler may produce a diagnostic saying that
11389 a label is unreachable.
11391 @cindex @code{asm inline}
11392 This size is also used for inlining decisions. If you use @code{asm inline}
11393 instead of just @code{asm}, then for inlining purposes the size of the asm
11394 is taken as the minimum size, ignoring how many instructions GCC thinks it is.
11396 @node Alternate Keywords
11397 @section Alternate Keywords
11398 @cindex alternate keywords
11399 @cindex keywords, alternate
11401 @option{-ansi} and the various @option{-std} options disable certain
11402 keywords. This causes trouble when you want to use GNU C extensions, or
11403 a general-purpose header file that should be usable by all programs,
11404 including ISO C programs. The keywords @code{asm}, @code{typeof} and
11405 @code{inline} are not available in programs compiled with
11406 @option{-ansi} or @option{-std} (although @code{inline} can be used in a
11407 program compiled with @option{-std=c99} or a later standard). The
11409 @code{restrict} is only available when @option{-std=gnu99} (which will
11410 eventually be the default) or @option{-std=c99} (or the equivalent
11411 @option{-std=iso9899:1999}), or an option for a later standard
11414 The way to solve these problems is to put @samp{__} at the beginning and
11415 end of each problematical keyword. For example, use @code{__asm__}
11416 instead of @code{asm}, and @code{__inline__} instead of @code{inline}.
11418 Other C compilers won't accept these alternative keywords; if you want to
11419 compile with another compiler, you can define the alternate keywords as
11420 macros to replace them with the customary keywords. It looks like this:
11424 #define __asm__ asm
11428 @findex __extension__
11430 @option{-pedantic} and other options cause warnings for many GNU C extensions.
11432 prevent such warnings within one expression by writing
11433 @code{__extension__} before the expression. @code{__extension__} has no
11434 effect aside from this.
11436 @node Incomplete Enums
11437 @section Incomplete @code{enum} Types
11439 You can define an @code{enum} tag without specifying its possible values.
11440 This results in an incomplete type, much like what you get if you write
11441 @code{struct foo} without describing the elements. A later declaration
11442 that does specify the possible values completes the type.
11444 You cannot allocate variables or storage using the type while it is
11445 incomplete. However, you can work with pointers to that type.
11447 This extension may not be very useful, but it makes the handling of
11448 @code{enum} more consistent with the way @code{struct} and @code{union}
11451 This extension is not supported by GNU C++.
11453 @node Function Names
11454 @section Function Names as Strings
11455 @cindex @code{__func__} identifier
11456 @cindex @code{__FUNCTION__} identifier
11457 @cindex @code{__PRETTY_FUNCTION__} identifier
11459 GCC provides three magic constants that hold the name of the current
11460 function as a string. In C++11 and later modes, all three are treated
11461 as constant expressions and can be used in @code{constexpr} constexts.
11462 The first of these constants is @code{__func__}, which is part of
11465 The identifier @code{__func__} is implicitly declared by the translator
11466 as if, immediately following the opening brace of each function
11467 definition, the declaration
11470 static const char __func__[] = "function-name";
11474 appeared, where function-name is the name of the lexically-enclosing
11475 function. This name is the unadorned name of the function. As an
11476 extension, at file (or, in C++, namespace scope), @code{__func__}
11477 evaluates to the empty string.
11479 @code{__FUNCTION__} is another name for @code{__func__}, provided for
11480 backward compatibility with old versions of GCC.
11482 In C, @code{__PRETTY_FUNCTION__} is yet another name for
11483 @code{__func__}, except that at file scope (or, in C++, namespace scope),
11484 it evaluates to the string @code{"top level"}. In addition, in C++,
11485 @code{__PRETTY_FUNCTION__} contains the signature of the function as
11486 well as its bare name. For example, this program:
11489 extern "C" int printf (const char *, ...);
11495 printf ("__FUNCTION__ = %s\n", __FUNCTION__);
11496 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
11514 __PRETTY_FUNCTION__ = void a::sub(int)
11517 These identifiers are variables, not preprocessor macros, and may not
11518 be used to initialize @code{char} arrays or be concatenated with string
11521 @node Return Address
11522 @section Getting the Return or Frame Address of a Function
11524 These functions may be used to get information about the callers of a
11527 @deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level})
11528 This function returns the return address of the current function, or of
11529 one of its callers. The @var{level} argument is number of frames to
11530 scan up the call stack. A value of @code{0} yields the return address
11531 of the current function, a value of @code{1} yields the return address
11532 of the caller of the current function, and so forth. When inlining
11533 the expected behavior is that the function returns the address of
11534 the function that is returned to. To work around this behavior use
11535 the @code{noinline} function attribute.
11537 The @var{level} argument must be a constant integer.
11539 On some machines it may be impossible to determine the return address of
11540 any function other than the current one; in such cases, or when the top
11541 of the stack has been reached, this function returns an unspecified
11542 value. In addition, @code{__builtin_frame_address} may be used
11543 to determine if the top of the stack has been reached.
11545 Additional post-processing of the returned value may be needed, see
11546 @code{__builtin_extract_return_addr}.
11548 The stored representation of the return address in memory may be different
11549 from the address returned by @code{__builtin_return_address}. For example,
11550 on AArch64 the stored address may be mangled with return address signing
11551 whereas the address returned by @code{__builtin_return_address} is not.
11553 Calling this function with a nonzero argument can have unpredictable
11554 effects, including crashing the calling program. As a result, calls
11555 that are considered unsafe are diagnosed when the @option{-Wframe-address}
11556 option is in effect. Such calls should only be made in debugging
11559 On targets where code addresses are representable as @code{void *},
11561 void *addr = __builtin_extract_return_addr (__builtin_return_address (0));
11563 gives the code address where the current function would return. For example,
11564 such an address may be used with @code{dladdr} or other interfaces that work
11565 with code addresses.
11568 @deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr})
11569 The address as returned by @code{__builtin_return_address} may have to be fed
11570 through this function to get the actual encoded address. For example, on the
11571 31-bit S/390 platform the highest bit has to be masked out, or on SPARC
11572 platforms an offset has to be added for the true next instruction to be
11575 If no fixup is needed, this function simply passes through @var{addr}.
11578 @deftypefn {Built-in Function} {void *} __builtin_frob_return_addr (void *@var{addr})
11579 This function does the reverse of @code{__builtin_extract_return_addr}.
11582 @deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level})
11583 This function is similar to @code{__builtin_return_address}, but it
11584 returns the address of the function frame rather than the return address
11585 of the function. Calling @code{__builtin_frame_address} with a value of
11586 @code{0} yields the frame address of the current function, a value of
11587 @code{1} yields the frame address of the caller of the current function,
11590 The frame is the area on the stack that holds local variables and saved
11591 registers. The frame address is normally the address of the first word
11592 pushed on to the stack by the function. However, the exact definition
11593 depends upon the processor and the calling convention. If the processor
11594 has a dedicated frame pointer register, and the function has a frame,
11595 then @code{__builtin_frame_address} returns the value of the frame
11598 On some machines it may be impossible to determine the frame address of
11599 any function other than the current one; in such cases, or when the top
11600 of the stack has been reached, this function returns @code{0} if
11601 the first frame pointer is properly initialized by the startup code.
11603 Calling this function with a nonzero argument can have unpredictable
11604 effects, including crashing the calling program. As a result, calls
11605 that are considered unsafe are diagnosed when the @option{-Wframe-address}
11606 option is in effect. Such calls should only be made in debugging
11610 @node Vector Extensions
11611 @section Using Vector Instructions through Built-in Functions
11613 On some targets, the instruction set contains SIMD vector instructions which
11614 operate on multiple values contained in one large register at the same time.
11615 For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used
11618 The first step in using these extensions is to provide the necessary data
11619 types. This should be done using an appropriate @code{typedef}:
11622 typedef int v4si __attribute__ ((vector_size (16)));
11626 The @code{int} type specifies the @dfn{base type}, while the attribute specifies
11627 the vector size for the variable, measured in bytes. For example, the
11628 declaration above causes the compiler to set the mode for the @code{v4si}
11629 type to be 16 bytes wide and divided into @code{int} sized units. For
11630 a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the
11631 corresponding mode of @code{foo} is @acronym{V4SI}.
11633 The @code{vector_size} attribute is only applicable to integral and
11634 floating scalars, although arrays, pointers, and function return values
11635 are allowed in conjunction with this construct. Only sizes that are
11636 positive power-of-two multiples of the base type size are currently allowed.
11638 All the basic integer types can be used as base types, both as signed
11639 and as unsigned: @code{char}, @code{short}, @code{int}, @code{long},
11640 @code{long long}. In addition, @code{float} and @code{double} can be
11641 used to build floating-point vector types.
11643 Specifying a combination that is not valid for the current architecture
11644 causes GCC to synthesize the instructions using a narrower mode.
11645 For example, if you specify a variable of type @code{V4SI} and your
11646 architecture does not allow for this specific SIMD type, GCC
11647 produces code that uses 4 @code{SIs}.
11649 The types defined in this manner can be used with a subset of normal C
11650 operations. Currently, GCC allows using the following operators
11651 on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@.
11653 The operations behave like C++ @code{valarrays}. Addition is defined as
11654 the addition of the corresponding elements of the operands. For
11655 example, in the code below, each of the 4 elements in @var{a} is
11656 added to the corresponding 4 elements in @var{b} and the resulting
11657 vector is stored in @var{c}.
11660 typedef int v4si __attribute__ ((vector_size (16)));
11667 Subtraction, multiplication, division, and the logical operations
11668 operate in a similar manner. Likewise, the result of using the unary
11669 minus or complement operators on a vector type is a vector whose
11670 elements are the negative or complemented values of the corresponding
11671 elements in the operand.
11673 It is possible to use shifting operators @code{<<}, @code{>>} on
11674 integer-type vectors. The operation is defined as following: @code{@{a0,
11675 a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1,
11676 @dots{}, an >> bn@}}@. Vector operands must have the same number of
11679 For convenience, it is allowed to use a binary vector operation
11680 where one operand is a scalar. In that case the compiler transforms
11681 the scalar operand into a vector where each element is the scalar from
11682 the operation. The transformation happens only if the scalar could be
11683 safely converted to the vector-element type.
11684 Consider the following code.
11687 typedef int v4si __attribute__ ((vector_size (16)));
11692 a = b + 1; /* a = b + @{1,1,1,1@}; */
11693 a = 2 * b; /* a = @{2,2,2,2@} * b; */
11695 a = l + a; /* Error, cannot convert long to int. */
11698 Vectors can be subscripted as if the vector were an array with
11699 the same number of elements and base type. Out of bound accesses
11700 invoke undefined behavior at run time. Warnings for out of bound
11701 accesses for vector subscription can be enabled with
11702 @option{-Warray-bounds}.
11704 Vector comparison is supported with standard comparison
11705 operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be
11706 vector expressions of integer-type or real-type. Comparison between
11707 integer-type vectors and real-type vectors are not supported. The
11708 result of the comparison is a vector of the same width and number of
11709 elements as the comparison operands with a signed integral element
11712 Vectors are compared element-wise producing 0 when comparison is false
11713 and -1 (constant of the appropriate type where all bits are set)
11714 otherwise. Consider the following example.
11717 typedef int v4si __attribute__ ((vector_size (16)));
11719 v4si a = @{1,2,3,4@};
11720 v4si b = @{3,2,1,4@};
11723 c = a > b; /* The result would be @{0, 0,-1, 0@} */
11724 c = a == b; /* The result would be @{0,-1, 0,-1@} */
11727 In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where
11728 @code{b} and @code{c} are vectors of the same type and @code{a} is an
11729 integer vector with the same number of elements of the same size as @code{b}
11730 and @code{c}, computes all three arguments and creates a vector
11731 @code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in
11732 OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}.
11733 As in the case of binary operations, this syntax is also accepted when
11734 one of @code{b} or @code{c} is a scalar that is then transformed into a
11735 vector. If both @code{b} and @code{c} are scalars and the type of
11736 @code{true?b:c} has the same size as the element type of @code{a}, then
11737 @code{b} and @code{c} are converted to a vector type whose elements have
11738 this type and with the same number of elements as @code{a}.
11740 In C++, the logic operators @code{!, &&, ||} are available for vectors.
11741 @code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to
11742 @code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}.
11743 For mixed operations between a scalar @code{s} and a vector @code{v},
11744 @code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is
11745 short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}.
11747 @findex __builtin_shuffle
11748 Vector shuffling is available using functions
11749 @code{__builtin_shuffle (vec, mask)} and
11750 @code{__builtin_shuffle (vec0, vec1, mask)}.
11751 Both functions construct a permutation of elements from one or two
11752 vectors and return a vector of the same type as the input vector(s).
11753 The @var{mask} is an integral vector with the same width (@var{W})
11754 and element count (@var{N}) as the output vector.
11756 The elements of the input vectors are numbered in memory ordering of
11757 @var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The
11758 elements of @var{mask} are considered modulo @var{N} in the single-operand
11759 case and modulo @math{2*@var{N}} in the two-operand case.
11761 Consider the following example,
11764 typedef int v4si __attribute__ ((vector_size (16)));
11766 v4si a = @{1,2,3,4@};
11767 v4si b = @{5,6,7,8@};
11768 v4si mask1 = @{0,1,1,3@};
11769 v4si mask2 = @{0,4,2,5@};
11772 res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */
11773 res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */
11776 Note that @code{__builtin_shuffle} is intentionally semantically
11777 compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions.
11779 You can declare variables and use them in function calls and returns, as
11780 well as in assignments and some casts. You can specify a vector type as
11781 a return type for a function. Vector types can also be used as function
11782 arguments. It is possible to cast from one vector type to another,
11783 provided they are of the same size (in fact, you can also cast vectors
11784 to and from other datatypes of the same size).
11786 You cannot operate between vectors of different lengths or different
11787 signedness without a cast.
11789 @findex __builtin_convertvector
11790 Vector conversion is available using the
11791 @code{__builtin_convertvector (vec, vectype)}
11792 function. @var{vec} must be an expression with integral or floating
11793 vector type and @var{vectype} an integral or floating vector type with the
11794 same number of elements. The result has @var{vectype} type and value of
11795 a C cast of every element of @var{vec} to the element type of @var{vectype}.
11797 Consider the following example,
11799 typedef int v4si __attribute__ ((vector_size (16)));
11800 typedef float v4sf __attribute__ ((vector_size (16)));
11801 typedef double v4df __attribute__ ((vector_size (32)));
11802 typedef unsigned long long v4di __attribute__ ((vector_size (32)));
11804 v4si a = @{1,-2,3,-4@};
11805 v4sf b = @{1.5f,-2.5f,3.f,7.f@};
11806 v4di c = @{1ULL,5ULL,0ULL,10ULL@};
11807 v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */
11809 v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */
11810 v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */
11811 v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */
11812 v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */
11813 v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */
11816 @cindex vector types, using with x86 intrinsics
11817 Sometimes it is desirable to write code using a mix of generic vector
11818 operations (for clarity) and machine-specific vector intrinsics (to
11819 access vector instructions that are not exposed via generic built-ins).
11820 On x86, intrinsic functions for integer vectors typically use the same
11821 vector type @code{__m128i} irrespective of how they interpret the vector,
11822 making it necessary to cast their arguments and return values from/to
11823 other vector types. In C, you can make use of a @code{union} type:
11824 @c In C++ such type punning via a union is not allowed by the language
11826 #include <immintrin.h>
11828 typedef unsigned char u8x16 __attribute__ ((vector_size (16)));
11829 typedef unsigned int u32x4 __attribute__ ((vector_size (16)));
11839 for variables that can be used with both built-in operators and x86
11843 v128 x, y = @{ 0 @};
11844 memcpy (&x, ptr, sizeof x);
11846 x.mm = _mm_adds_epu8 (x.mm, y.mm);
11849 /* Instead of a variable, a compound literal may be used to pass the
11850 return value of an intrinsic call to a function expecting the union: */
11852 x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@});
11853 @c This could be done implicitly with __attribute__((transparent_union)),
11854 @c but GCC does not accept it for unions of vector types (PR 88955).
11858 @section Support for @code{offsetof}
11859 @findex __builtin_offsetof
11861 GCC implements for both C and C++ a syntactic extension to implement
11862 the @code{offsetof} macro.
11866 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
11868 offsetof_member_designator:
11870 | offsetof_member_designator "." @code{identifier}
11871 | offsetof_member_designator "[" @code{expr} "]"
11874 This extension is sufficient such that
11877 #define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member})
11881 is a suitable definition of the @code{offsetof} macro. In C++, @var{type}
11882 may be dependent. In either case, @var{member} may consist of a single
11883 identifier, or a sequence of member accesses and array references.
11885 @node __sync Builtins
11886 @section Legacy @code{__sync} Built-in Functions for Atomic Memory Access
11888 The following built-in functions
11889 are intended to be compatible with those described
11890 in the @cite{Intel Itanium Processor-specific Application Binary Interface},
11891 section 7.4. As such, they depart from normal GCC practice by not using
11892 the @samp{__builtin_} prefix and also by being overloaded so that they
11893 work on multiple types.
11895 The definition given in the Intel documentation allows only for the use of
11896 the types @code{int}, @code{long}, @code{long long} or their unsigned
11897 counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in
11898 size other than the C type @code{_Bool} or the C++ type @code{bool}.
11899 Operations on pointer arguments are performed as if the operands were
11900 of the @code{uintptr_t} type. That is, they are not scaled by the size
11901 of the type to which the pointer points.
11903 These functions are implemented in terms of the @samp{__atomic}
11904 builtins (@pxref{__atomic Builtins}). They should not be used for new
11905 code which should use the @samp{__atomic} builtins instead.
11907 Not all operations are supported by all target processors. If a particular
11908 operation cannot be implemented on the target processor, a warning is
11909 generated and a call to an external function is generated. The external
11910 function carries the same name as the built-in version,
11911 with an additional suffix
11912 @samp{_@var{n}} where @var{n} is the size of the data type.
11914 @c ??? Should we have a mechanism to suppress this warning? This is almost
11915 @c useful for implementing the operation under the control of an external
11918 In most cases, these built-in functions are considered a @dfn{full barrier}.
11920 no memory operand is moved across the operation, either forward or
11921 backward. Further, instructions are issued as necessary to prevent the
11922 processor from speculating loads across the operation and from queuing stores
11923 after the operation.
11925 All of the routines are described in the Intel documentation to take
11926 ``an optional list of variables protected by the memory barrier''. It's
11927 not clear what is meant by that; it could mean that @emph{only} the
11928 listed variables are protected, or it could mean a list of additional
11929 variables to be protected. The list is ignored by GCC which treats it as
11930 empty. GCC interprets an empty list as meaning that all globally
11931 accessible variables should be protected.
11934 @item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...)
11935 @itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...)
11936 @itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...)
11937 @itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...)
11938 @itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...)
11939 @itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...)
11940 @findex __sync_fetch_and_add
11941 @findex __sync_fetch_and_sub
11942 @findex __sync_fetch_and_or
11943 @findex __sync_fetch_and_and
11944 @findex __sync_fetch_and_xor
11945 @findex __sync_fetch_and_nand
11946 These built-in functions perform the operation suggested by the name, and
11947 returns the value that had previously been in memory. That is, operations
11948 on integer operands have the following semantics. Operations on pointer
11949 arguments are performed as if the operands were of the @code{uintptr_t}
11950 type. That is, they are not scaled by the size of the type to which
11951 the pointer points.
11954 @{ tmp = *ptr; *ptr @var{op}= value; return tmp; @}
11955 @{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand
11958 The object pointed to by the first argument must be of integer or pointer
11959 type. It must not be a boolean type.
11961 @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand}
11962 as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}.
11964 @item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...)
11965 @itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...)
11966 @itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...)
11967 @itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...)
11968 @itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...)
11969 @itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...)
11970 @findex __sync_add_and_fetch
11971 @findex __sync_sub_and_fetch
11972 @findex __sync_or_and_fetch
11973 @findex __sync_and_and_fetch
11974 @findex __sync_xor_and_fetch
11975 @findex __sync_nand_and_fetch
11976 These built-in functions perform the operation suggested by the name, and
11977 return the new value. That is, operations on integer operands have
11978 the following semantics. Operations on pointer operands are performed as
11979 if the operand's type were @code{uintptr_t}.
11982 @{ *ptr @var{op}= value; return *ptr; @}
11983 @{ *ptr = ~(*ptr & value); return *ptr; @} // nand
11986 The same constraints on arguments apply as for the corresponding
11987 @code{__sync_op_and_fetch} built-in functions.
11989 @emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch}
11990 as @code{*ptr = ~(*ptr & value)} instead of
11991 @code{*ptr = ~*ptr & value}.
11993 @item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
11994 @itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
11995 @findex __sync_bool_compare_and_swap
11996 @findex __sync_val_compare_and_swap
11997 These built-in functions perform an atomic compare and swap.
11998 That is, if the current
11999 value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into
12002 The ``bool'' version returns @code{true} if the comparison is successful and
12003 @var{newval} is written. The ``val'' version returns the contents
12004 of @code{*@var{ptr}} before the operation.
12006 @item __sync_synchronize (...)
12007 @findex __sync_synchronize
12008 This built-in function issues a full memory barrier.
12010 @item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...)
12011 @findex __sync_lock_test_and_set
12012 This built-in function, as described by Intel, is not a traditional test-and-set
12013 operation, but rather an atomic exchange operation. It writes @var{value}
12014 into @code{*@var{ptr}}, and returns the previous contents of
12017 Many targets have only minimal support for such locks, and do not support
12018 a full exchange operation. In this case, a target may support reduced
12019 functionality here by which the @emph{only} valid value to store is the
12020 immediate constant 1. The exact value actually stored in @code{*@var{ptr}}
12021 is implementation defined.
12023 This built-in function is not a full barrier,
12024 but rather an @dfn{acquire barrier}.
12025 This means that references after the operation cannot move to (or be
12026 speculated to) before the operation, but previous memory stores may not
12027 be globally visible yet, and previous memory loads may not yet be
12030 @item void __sync_lock_release (@var{type} *ptr, ...)
12031 @findex __sync_lock_release
12032 This built-in function releases the lock acquired by
12033 @code{__sync_lock_test_and_set}.
12034 Normally this means writing the constant 0 to @code{*@var{ptr}}.
12036 This built-in function is not a full barrier,
12037 but rather a @dfn{release barrier}.
12038 This means that all previous memory stores are globally visible, and all
12039 previous memory loads have been satisfied, but following memory reads
12040 are not prevented from being speculated to before the barrier.
12043 @node __atomic Builtins
12044 @section Built-in Functions for Memory Model Aware Atomic Operations
12046 The following built-in functions approximately match the requirements
12047 for the C++11 memory model. They are all
12048 identified by being prefixed with @samp{__atomic} and most are
12049 overloaded so that they work with multiple types.
12051 These functions are intended to replace the legacy @samp{__sync}
12052 builtins. The main difference is that the memory order that is requested
12053 is a parameter to the functions. New code should always use the
12054 @samp{__atomic} builtins rather than the @samp{__sync} builtins.
12056 Note that the @samp{__atomic} builtins assume that programs will
12057 conform to the C++11 memory model. In particular, they assume
12058 that programs are free of data races. See the C++11 standard for
12059 detailed requirements.
12061 The @samp{__atomic} builtins can be used with any integral scalar or
12062 pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral
12063 types are also allowed if @samp{__int128} (@pxref{__int128}) is
12064 supported by the architecture.
12066 The four non-arithmetic functions (load, store, exchange, and
12067 compare_exchange) all have a generic version as well. This generic
12068 version works on any data type. It uses the lock-free built-in function
12069 if the specific data type size makes that possible; otherwise, an
12070 external call is left to be resolved at run time. This external call is
12071 the same format with the addition of a @samp{size_t} parameter inserted
12072 as the first parameter indicating the size of the object being pointed to.
12073 All objects must be the same size.
12075 There are 6 different memory orders that can be specified. These map
12076 to the C++11 memory orders with the same names, see the C++11 standard
12077 or the @uref{http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki
12078 on atomic synchronization} for detailed definitions. Individual
12079 targets may also support additional memory orders for use on specific
12080 architectures. Refer to the target documentation for details of
12083 An atomic operation can both constrain code motion and
12084 be mapped to hardware instructions for synchronization between threads
12085 (e.g., a fence). To which extent this happens is controlled by the
12086 memory orders, which are listed here in approximately ascending order of
12087 strength. The description of each memory order is only meant to roughly
12088 illustrate the effects and is not a specification; see the C++11
12089 memory model for precise semantics.
12092 @item __ATOMIC_RELAXED
12093 Implies no inter-thread ordering constraints.
12094 @item __ATOMIC_CONSUME
12095 This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE}
12096 memory order because of a deficiency in C++11's semantics for
12097 @code{memory_order_consume}.
12098 @item __ATOMIC_ACQUIRE
12099 Creates an inter-thread happens-before constraint from the release (or
12100 stronger) semantic store to this acquire load. Can prevent hoisting
12101 of code to before the operation.
12102 @item __ATOMIC_RELEASE
12103 Creates an inter-thread happens-before constraint to acquire (or stronger)
12104 semantic loads that read from this release store. Can prevent sinking
12105 of code to after the operation.
12106 @item __ATOMIC_ACQ_REL
12107 Combines the effects of both @code{__ATOMIC_ACQUIRE} and
12108 @code{__ATOMIC_RELEASE}.
12109 @item __ATOMIC_SEQ_CST
12110 Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations.
12113 Note that in the C++11 memory model, @emph{fences} (e.g.,
12114 @samp{__atomic_thread_fence}) take effect in combination with other
12115 atomic operations on specific memory locations (e.g., atomic loads);
12116 operations on specific memory locations do not necessarily affect other
12117 operations in the same way.
12119 Target architectures are encouraged to provide their own patterns for
12120 each of the atomic built-in functions. If no target is provided, the original
12121 non-memory model set of @samp{__sync} atomic built-in functions are
12122 used, along with any required synchronization fences surrounding it in
12123 order to achieve the proper behavior. Execution in this case is subject
12124 to the same restrictions as those built-in functions.
12126 If there is no pattern or mechanism to provide a lock-free instruction
12127 sequence, a call is made to an external routine with the same parameters
12128 to be resolved at run time.
12130 When implementing patterns for these built-in functions, the memory order
12131 parameter can be ignored as long as the pattern implements the most
12132 restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory
12133 orders execute correctly with this memory order but they may not execute as
12134 efficiently as they could with a more appropriate implementation of the
12135 relaxed requirements.
12137 Note that the C++11 standard allows for the memory order parameter to be
12138 determined at run time rather than at compile time. These built-in
12139 functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather
12140 than invoke a runtime library call or inline a switch statement. This is
12141 standard compliant, safe, and the simplest approach for now.
12143 The memory order parameter is a signed int, but only the lower 16 bits are
12144 reserved for the memory order. The remainder of the signed int is reserved
12145 for target use and should be 0. Use of the predefined atomic values
12146 ensures proper usage.
12148 @deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memorder)
12149 This built-in function implements an atomic load operation. It returns the
12150 contents of @code{*@var{ptr}}.
12152 The valid memory order variants are
12153 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
12154 and @code{__ATOMIC_CONSUME}.
12158 @deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder)
12159 This is the generic version of an atomic load. It returns the
12160 contents of @code{*@var{ptr}} in @code{*@var{ret}}.
12164 @deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder)
12165 This built-in function implements an atomic store operation. It writes
12166 @code{@var{val}} into @code{*@var{ptr}}.
12168 The valid memory order variants are
12169 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}.
12173 @deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder)
12174 This is the generic version of an atomic store. It stores the value
12175 of @code{*@var{val}} into @code{*@var{ptr}}.
12179 @deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder)
12180 This built-in function implements an atomic exchange operation. It writes
12181 @var{val} into @code{*@var{ptr}}, and returns the previous contents of
12184 The valid memory order variants are
12185 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
12186 @code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}.
12190 @deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder)
12191 This is the generic version of an atomic exchange. It stores the
12192 contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value
12193 of @code{*@var{ptr}} is copied into @code{*@var{ret}}.
12197 @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)
12198 This built-in function implements an atomic compare and exchange operation.
12199 This compares the contents of @code{*@var{ptr}} with the contents of
12200 @code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write}
12201 operation that writes @var{desired} into @code{*@var{ptr}}. If they are not
12202 equal, the operation is a @emph{read} and the current contents of
12203 @code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true}
12204 for weak compare_exchange, which may fail spuriously, and @code{false} for
12205 the strong variation, which never fails spuriously. Many targets
12206 only offer the strong variation and ignore the parameter. When in doubt, use
12207 the strong variation.
12209 If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned
12210 and memory is affected according to the
12211 memory order specified by @var{success_memorder}. There are no
12212 restrictions on what memory order can be used here.
12214 Otherwise, @code{false} is returned and memory is affected according
12215 to @var{failure_memorder}. This memory order cannot be
12216 @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a
12217 stronger order than that specified by @var{success_memorder}.
12221 @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)
12222 This built-in function implements the generic version of
12223 @code{__atomic_compare_exchange}. The function is virtually identical to
12224 @code{__atomic_compare_exchange_n}, except the desired value is also a
12229 @deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder)
12230 @deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder)
12231 @deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder)
12232 @deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder)
12233 @deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder)
12234 @deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder)
12235 These built-in functions perform the operation suggested by the name, and
12236 return the result of the operation. Operations on pointer arguments are
12237 performed as if the operands were of the @code{uintptr_t} type. That is,
12238 they are not scaled by the size of the type to which the pointer points.
12241 @{ *ptr @var{op}= val; return *ptr; @}
12242 @{ *ptr = ~(*ptr & val); return *ptr; @} // nand
12245 The object pointed to by the first argument must be of integer or pointer
12246 type. It must not be a boolean type. All memory orders are valid.
12250 @deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder)
12251 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder)
12252 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder)
12253 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder)
12254 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder)
12255 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder)
12256 These built-in functions perform the operation suggested by the name, and
12257 return the value that had previously been in @code{*@var{ptr}}. Operations
12258 on pointer arguments are performed as if the operands were of
12259 the @code{uintptr_t} type. That is, they are not scaled by the size of
12260 the type to which the pointer points.
12263 @{ tmp = *ptr; *ptr @var{op}= val; return tmp; @}
12264 @{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand
12267 The same constraints on arguments apply as for the corresponding
12268 @code{__atomic_op_fetch} built-in functions. All memory orders are valid.
12272 @deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memorder)
12274 This built-in function performs an atomic test-and-set operation on
12275 the byte at @code{*@var{ptr}}. The byte is set to some implementation
12276 defined nonzero ``set'' value and the return value is @code{true} if and only
12277 if the previous contents were ``set''.
12278 It should be only used for operands of type @code{bool} or @code{char}. For
12279 other types only part of the value may be set.
12281 All memory orders are valid.
12285 @deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memorder)
12287 This built-in function performs an atomic clear operation on
12288 @code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0.
12289 It should be only used for operands of type @code{bool} or @code{char} and
12290 in conjunction with @code{__atomic_test_and_set}.
12291 For other types it may only clear partially. If the type is not @code{bool}
12292 prefer using @code{__atomic_store}.
12294 The valid memory order variants are
12295 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and
12296 @code{__ATOMIC_RELEASE}.
12300 @deftypefn {Built-in Function} void __atomic_thread_fence (int memorder)
12302 This built-in function acts as a synchronization fence between threads
12303 based on the specified memory order.
12305 All memory orders are valid.
12309 @deftypefn {Built-in Function} void __atomic_signal_fence (int memorder)
12311 This built-in function acts as a synchronization fence between a thread
12312 and signal handlers based in the same thread.
12314 All memory orders are valid.
12318 @deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr)
12320 This built-in function returns @code{true} if objects of @var{size} bytes always
12321 generate lock-free atomic instructions for the target architecture.
12322 @var{size} must resolve to a compile-time constant and the result also
12323 resolves to a compile-time constant.
12325 @var{ptr} is an optional pointer to the object that may be used to determine
12326 alignment. A value of 0 indicates typical alignment should be used. The
12327 compiler may also ignore this parameter.
12330 if (__atomic_always_lock_free (sizeof (long long), 0))
12335 @deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr)
12337 This built-in function returns @code{true} if objects of @var{size} bytes always
12338 generate lock-free atomic instructions for the target architecture. If
12339 the built-in function is not known to be lock-free, a call is made to a
12340 runtime routine named @code{__atomic_is_lock_free}.
12342 @var{ptr} is an optional pointer to the object that may be used to determine
12343 alignment. A value of 0 indicates typical alignment should be used. The
12344 compiler may also ignore this parameter.
12347 @node Integer Overflow Builtins
12348 @section Built-in Functions to Perform Arithmetic with Overflow Checking
12350 The following built-in functions allow performing simple arithmetic operations
12351 together with checking whether the operations overflowed.
12353 @deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
12354 @deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res)
12355 @deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res)
12356 @deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res)
12357 @deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res)
12358 @deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
12359 @deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
12361 These built-in functions promote the first two operands into infinite precision signed
12362 type and perform addition on those promoted operands. The result is then
12363 cast to the type the third pointer argument points to and stored there.
12364 If the stored result is equal to the infinite precision result, the built-in
12365 functions return @code{false}, otherwise they return @code{true}. As the addition is
12366 performed in infinite signed precision, these built-in functions have fully defined
12367 behavior for all argument values.
12369 The first built-in function allows arbitrary integral types for operands and
12370 the result type must be pointer to some integral type other than enumerated or
12371 boolean type, the rest of the built-in functions have explicit integer types.
12373 The compiler will attempt to use hardware instructions to implement
12374 these built-in functions where possible, like conditional jump on overflow
12375 after addition, conditional jump on carry etc.
12379 @deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
12380 @deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res)
12381 @deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res)
12382 @deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res)
12383 @deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res)
12384 @deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
12385 @deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
12387 These built-in functions are similar to the add overflow checking built-in
12388 functions above, except they perform subtraction, subtract the second argument
12389 from the first one, instead of addition.
12393 @deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
12394 @deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res)
12395 @deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res)
12396 @deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res)
12397 @deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res)
12398 @deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
12399 @deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
12401 These built-in functions are similar to the add overflow checking built-in
12402 functions above, except they perform multiplication, instead of addition.
12406 The following built-in functions allow checking if simple arithmetic operation
12409 @deftypefn {Built-in Function} bool __builtin_add_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12410 @deftypefnx {Built-in Function} bool __builtin_sub_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12411 @deftypefnx {Built-in Function} bool __builtin_mul_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12413 These built-in functions are similar to @code{__builtin_add_overflow},
12414 @code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that
12415 they don't store the result of the arithmetic operation anywhere and the
12416 last argument is not a pointer, but some expression with integral type other
12417 than enumerated or boolean type.
12419 The built-in functions promote the first two operands into infinite precision signed type
12420 and perform addition on those promoted operands. The result is then
12421 cast to the type of the third argument. If the cast result is equal to the infinite
12422 precision result, the built-in functions return @code{false}, otherwise they return @code{true}.
12423 The value of the third argument is ignored, just the side effects in the third argument
12424 are evaluated, and no integral argument promotions are performed on the last argument.
12425 If the third argument is a bit-field, the type used for the result cast has the
12426 precision and signedness of the given bit-field, rather than precision and signedness
12427 of the underlying type.
12429 For example, the following macro can be used to portably check, at
12430 compile-time, whether or not adding two constant integers will overflow,
12431 and perform the addition only when it is known to be safe and not to trigger
12432 a @option{-Woverflow} warning.
12435 #define INT_ADD_OVERFLOW_P(a, b) \
12436 __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0)
12439 A = INT_MAX, B = 3,
12440 C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B,
12441 D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0)
12445 The compiler will attempt to use hardware instructions to implement
12446 these built-in functions where possible, like conditional jump on overflow
12447 after addition, conditional jump on carry etc.
12451 @node x86 specific memory model extensions for transactional memory
12452 @section x86-Specific Memory Model Extensions for Transactional Memory
12454 The x86 architecture supports additional memory ordering flags
12455 to mark critical sections for hardware lock elision.
12456 These must be specified in addition to an existing memory order to
12460 @item __ATOMIC_HLE_ACQUIRE
12461 Start lock elision on a lock variable.
12462 Memory order must be @code{__ATOMIC_ACQUIRE} or stronger.
12463 @item __ATOMIC_HLE_RELEASE
12464 End lock elision on a lock variable.
12465 Memory order must be @code{__ATOMIC_RELEASE} or stronger.
12468 When a lock acquire fails, it is required for good performance to abort
12469 the transaction quickly. This can be done with a @code{_mm_pause}.
12472 #include <immintrin.h> // For _mm_pause
12476 /* Acquire lock with lock elision */
12477 while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE))
12478 _mm_pause(); /* Abort failed transaction */
12480 /* Free lock with lock elision */
12481 __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE);
12484 @node Object Size Checking
12485 @section Object Size Checking Built-in Functions
12486 @findex __builtin_object_size
12487 @findex __builtin___memcpy_chk
12488 @findex __builtin___mempcpy_chk
12489 @findex __builtin___memmove_chk
12490 @findex __builtin___memset_chk
12491 @findex __builtin___strcpy_chk
12492 @findex __builtin___stpcpy_chk
12493 @findex __builtin___strncpy_chk
12494 @findex __builtin___strcat_chk
12495 @findex __builtin___strncat_chk
12496 @findex __builtin___sprintf_chk
12497 @findex __builtin___snprintf_chk
12498 @findex __builtin___vsprintf_chk
12499 @findex __builtin___vsnprintf_chk
12500 @findex __builtin___printf_chk
12501 @findex __builtin___vprintf_chk
12502 @findex __builtin___fprintf_chk
12503 @findex __builtin___vfprintf_chk
12505 GCC implements a limited buffer overflow protection mechanism that can
12506 prevent some buffer overflow attacks by determining the sizes of objects
12507 into which data is about to be written and preventing the writes when
12508 the size isn't sufficient. The built-in functions described below yield
12509 the best results when used together and when optimization is enabled.
12510 For example, to detect object sizes across function boundaries or to
12511 follow pointer assignments through non-trivial control flow they rely
12512 on various optimization passes enabled with @option{-O2}. However, to
12513 a limited extent, they can be used without optimization as well.
12515 @deftypefn {Built-in Function} {size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
12516 is a built-in construct that returns a constant number of bytes from
12517 @var{ptr} to the end of the object @var{ptr} pointer points to
12518 (if known at compile time). To determine the sizes of dynamically allocated
12519 objects the function relies on the allocation functions called to obtain
12520 the storage to be declared with the @code{alloc_size} attribute (@pxref{Common
12521 Function Attributes}). @code{__builtin_object_size} never evaluates
12522 its arguments for side effects. If there are any side effects in them, it
12523 returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
12524 for @var{type} 2 or 3. If there are multiple objects @var{ptr} can
12525 point to and all of them are known at compile time, the returned number
12526 is the maximum of remaining byte counts in those objects if @var{type} & 2 is
12527 0 and minimum if nonzero. If it is not possible to determine which objects
12528 @var{ptr} points to at compile time, @code{__builtin_object_size} should
12529 return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
12530 for @var{type} 2 or 3.
12532 @var{type} is an integer constant from 0 to 3. If the least significant
12533 bit is clear, objects are whole variables, if it is set, a closest
12534 surrounding subobject is considered the object a pointer points to.
12535 The second bit determines if maximum or minimum of remaining bytes
12539 struct V @{ char buf1[10]; int b; char buf2[10]; @} var;
12540 char *p = &var.buf1[1], *q = &var.b;
12542 /* Here the object p points to is var. */
12543 assert (__builtin_object_size (p, 0) == sizeof (var) - 1);
12544 /* The subobject p points to is var.buf1. */
12545 assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1);
12546 /* The object q points to is var. */
12547 assert (__builtin_object_size (q, 0)
12548 == (char *) (&var + 1) - (char *) &var.b);
12549 /* The subobject q points to is var.b. */
12550 assert (__builtin_object_size (q, 1) == sizeof (var.b));
12554 There are built-in functions added for many common string operation
12555 functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk}
12556 built-in is provided. This built-in has an additional last argument,
12557 which is the number of bytes remaining in the object the @var{dest}
12558 argument points to or @code{(size_t) -1} if the size is not known.
12560 The built-in functions are optimized into the normal string functions
12561 like @code{memcpy} if the last argument is @code{(size_t) -1} or if
12562 it is known at compile time that the destination object will not
12563 be overflowed. If the compiler can determine at compile time that the
12564 object will always be overflowed, it issues a warning.
12566 The intended use can be e.g.@:
12570 #define bos0(dest) __builtin_object_size (dest, 0)
12571 #define memcpy(dest, src, n) \
12572 __builtin___memcpy_chk (dest, src, n, bos0 (dest))
12576 /* It is unknown what object p points to, so this is optimized
12577 into plain memcpy - no checking is possible. */
12578 memcpy (p, "abcde", n);
12579 /* Destination is known and length too. It is known at compile
12580 time there will be no overflow. */
12581 memcpy (&buf[5], "abcde", 5);
12582 /* Destination is known, but the length is not known at compile time.
12583 This will result in __memcpy_chk call that can check for overflow
12585 memcpy (&buf[5], "abcde", n);
12586 /* Destination is known and it is known at compile time there will
12587 be overflow. There will be a warning and __memcpy_chk call that
12588 will abort the program at run time. */
12589 memcpy (&buf[6], "abcde", 5);
12592 Such built-in functions are provided for @code{memcpy}, @code{mempcpy},
12593 @code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy},
12594 @code{strcat} and @code{strncat}.
12596 There are also checking built-in functions for formatted output functions.
12598 int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...);
12599 int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os,
12600 const char *fmt, ...);
12601 int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt,
12603 int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os,
12604 const char *fmt, va_list ap);
12607 The added @var{flag} argument is passed unchanged to @code{__sprintf_chk}
12608 etc.@: functions and can contain implementation specific flags on what
12609 additional security measures the checking function might take, such as
12610 handling @code{%n} differently.
12612 The @var{os} argument is the object size @var{s} points to, like in the
12613 other built-in functions. There is a small difference in the behavior
12614 though, if @var{os} is @code{(size_t) -1}, the built-in functions are
12615 optimized into the non-checking functions only if @var{flag} is 0, otherwise
12616 the checking function is called with @var{os} argument set to
12617 @code{(size_t) -1}.
12619 In addition to this, there are checking built-in functions
12620 @code{__builtin___printf_chk}, @code{__builtin___vprintf_chk},
12621 @code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}.
12622 These have just one additional argument, @var{flag}, right before
12623 format string @var{fmt}. If the compiler is able to optimize them to
12624 @code{fputc} etc.@: functions, it does, otherwise the checking function
12625 is called and the @var{flag} argument passed to it.
12627 @node Other Builtins
12628 @section Other Built-in Functions Provided by GCC
12629 @cindex built-in functions
12630 @findex __builtin_alloca
12631 @findex __builtin_alloca_with_align
12632 @findex __builtin_alloca_with_align_and_max
12633 @findex __builtin_call_with_static_chain
12634 @findex __builtin_extend_pointer
12635 @findex __builtin_fpclassify
12636 @findex __builtin_has_attribute
12637 @findex __builtin_isfinite
12638 @findex __builtin_isnormal
12639 @findex __builtin_isgreater
12640 @findex __builtin_isgreaterequal
12641 @findex __builtin_isinf_sign
12642 @findex __builtin_isless
12643 @findex __builtin_islessequal
12644 @findex __builtin_islessgreater
12645 @findex __builtin_isunordered
12646 @findex __builtin_object_size
12647 @findex __builtin_powi
12648 @findex __builtin_powif
12649 @findex __builtin_powil
12650 @findex __builtin_speculation_safe_value
12811 @findex fprintf_unlocked
12813 @findex fputs_unlocked
12922 @findex nexttowardf
12923 @findex nexttowardl
12931 @findex printf_unlocked
12962 @findex signbitd128
12963 @findex significand
12964 @findex significandf
12965 @findex significandl
12993 @findex strncasecmp
13037 GCC provides a large number of built-in functions other than the ones
13038 mentioned above. Some of these are for internal use in the processing
13039 of exceptions or variable-length argument lists and are not
13040 documented here because they may change from time to time; we do not
13041 recommend general use of these functions.
13043 The remaining functions are provided for optimization purposes.
13045 With the exception of built-ins that have library equivalents such as
13046 the standard C library functions discussed below, or that expand to
13047 library calls, GCC built-in functions are always expanded inline and
13048 thus do not have corresponding entry points and their address cannot
13049 be obtained. Attempting to use them in an expression other than
13050 a function call results in a compile-time error.
13052 @opindex fno-builtin
13053 GCC includes built-in versions of many of the functions in the standard
13054 C library. These functions come in two forms: one whose names start with
13055 the @code{__builtin_} prefix, and the other without. Both forms have the
13056 same type (including prototype), the same address (when their address is
13057 taken), and the same meaning as the C library functions even if you specify
13058 the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these
13059 functions are only optimized in certain cases; if they are not optimized in
13060 a particular case, a call to the library function is emitted.
13064 Outside strict ISO C mode (@option{-ansi}, @option{-std=c90},
13065 @option{-std=c99} or @option{-std=c11}), the functions
13066 @code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero},
13067 @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml},
13068 @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll},
13069 @code{ffsl}, @code{ffs}, @code{fprintf_unlocked},
13070 @code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma},
13071 @code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext},
13072 @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0},
13073 @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn},
13074 @code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy},
13075 @code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked},
13076 @code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roundevenl},
13077 @code{scalbf}, @code{scalbl}, @code{scalb},
13078 @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32},
13079 @code{signbitd64}, @code{signbitd128}, @code{significandf},
13080 @code{significandl}, @code{significand}, @code{sincosf},
13081 @code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy},
13082 @code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp},
13083 @code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l},
13084 @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and
13086 may be handled as built-in functions.
13087 All these functions have corresponding versions
13088 prefixed with @code{__builtin_}, which may be used even in strict C90
13091 The ISO C99 functions
13092 @code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf},
13093 @code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh},
13094 @code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf},
13095 @code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos},
13096 @code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf},
13097 @code{casinhl}, @code{casinh}, @code{casinl}, @code{casin},
13098 @code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh},
13099 @code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt},
13100 @code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl},
13101 @code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf},
13102 @code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog},
13103 @code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl},
13104 @code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf},
13105 @code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal},
13106 @code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl},
13107 @code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf},
13108 @code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan},
13109 @code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl},
13110 @code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f},
13111 @code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim},
13112 @code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax},
13113 @code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf},
13114 @code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb},
13115 @code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf},
13116 @code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl},
13117 @code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround},
13118 @code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l},
13119 @code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf},
13120 @code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl},
13121 @code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint},
13122 @code{nextafterf}, @code{nextafterl}, @code{nextafter},
13123 @code{nexttowardf}, @code{nexttowardl}, @code{nexttoward},
13124 @code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof},
13125 @code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint},
13126 @code{roundf}, @code{roundl}, @code{round}, @code{scalblnf},
13127 @code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl},
13128 @code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal},
13129 @code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc},
13130 @code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf}
13131 are handled as built-in functions
13132 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
13134 There are also built-in versions of the ISO C99 functions
13135 @code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f},
13136 @code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill},
13137 @code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf},
13138 @code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl},
13139 @code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf},
13140 @code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl},
13141 @code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf},
13142 @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl},
13143 @code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl}
13144 that are recognized in any mode since ISO C90 reserves these names for
13145 the purpose to which ISO C99 puts them. All these functions have
13146 corresponding versions prefixed with @code{__builtin_}.
13148 There are also built-in functions @code{__builtin_fabsf@var{n}},
13149 @code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and
13150 @code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3
13151 functions @code{fabsf@var{n}}, @code{fabsf@var{n}x},
13152 @code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported
13153 types @code{_Float@var{n}} and @code{_Float@var{n}x}.
13155 There are also GNU extension functions @code{clog10}, @code{clog10f} and
13156 @code{clog10l} which names are reserved by ISO C99 for future use.
13157 All these functions have versions prefixed with @code{__builtin_}.
13159 The ISO C94 functions
13160 @code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit},
13161 @code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct},
13162 @code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and
13164 are handled as built-in functions
13165 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
13167 The ISO C90 functions
13168 @code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2},
13169 @code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos},
13170 @code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod},
13171 @code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf},
13172 @code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit},
13173 @code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct},
13174 @code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower},
13175 @code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log},
13176 @code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy},
13177 @code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar},
13178 @code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin},
13179 @code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat},
13180 @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn},
13181 @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy},
13182 @code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr},
13183 @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf}
13184 are all recognized as built-in functions unless
13185 @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}}
13186 is specified for an individual function). All of these functions have
13187 corresponding versions prefixed with @code{__builtin_}.
13189 GCC provides built-in versions of the ISO C99 floating-point comparison
13190 macros that avoid raising exceptions for unordered operands. They have
13191 the same names as the standard macros ( @code{isgreater},
13192 @code{isgreaterequal}, @code{isless}, @code{islessequal},
13193 @code{islessgreater}, and @code{isunordered}) , with @code{__builtin_}
13194 prefixed. We intend for a library implementor to be able to simply
13195 @code{#define} each standard macro to its built-in equivalent.
13196 In the same fashion, GCC provides @code{fpclassify}, @code{isfinite},
13197 @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with
13198 @code{__builtin_} prefixed. The @code{isinf} and @code{isnan}
13199 built-in functions appear both with and without the @code{__builtin_} prefix.
13201 @deftypefn {Built-in Function} void *__builtin_alloca (size_t size)
13202 The @code{__builtin_alloca} function must be called at block scope.
13203 The function allocates an object @var{size} bytes large on the stack
13204 of the calling function. The object is aligned on the default stack
13205 alignment boundary for the target determined by the
13206 @code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca}
13207 function returns a pointer to the first byte of the allocated object.
13208 The lifetime of the allocated object ends just before the calling
13209 function returns to its caller. This is so even when
13210 @code{__builtin_alloca} is called within a nested block.
13212 For example, the following function allocates eight objects of @code{n}
13213 bytes each on the stack, storing a pointer to each in consecutive elements
13214 of the array @code{a}. It then passes the array to function @code{g}
13215 which can safely use the storage pointed to by each of the array elements.
13218 void f (unsigned n)
13221 for (int i = 0; i != 8; ++i)
13222 a [i] = __builtin_alloca (n);
13224 g (a, n); // @r{safe}
13228 Since the @code{__builtin_alloca} function doesn't validate its argument
13229 it is the responsibility of its caller to make sure the argument doesn't
13230 cause it to exceed the stack size limit.
13231 The @code{__builtin_alloca} function is provided to make it possible to
13232 allocate on the stack arrays of bytes with an upper bound that may be
13233 computed at run time. Since C99 Variable Length Arrays offer
13234 similar functionality under a portable, more convenient, and safer
13235 interface they are recommended instead, in both C99 and C++ programs
13236 where GCC provides them as an extension.
13237 @xref{Variable Length}, for details.
13241 @deftypefn {Built-in Function} void *__builtin_alloca_with_align (size_t size, size_t alignment)
13242 The @code{__builtin_alloca_with_align} function must be called at block
13243 scope. The function allocates an object @var{size} bytes large on
13244 the stack of the calling function. The allocated object is aligned on
13245 the boundary specified by the argument @var{alignment} whose unit is given
13246 in bits (not bytes). The @var{size} argument must be positive and not
13247 exceed the stack size limit. The @var{alignment} argument must be a constant
13248 integer expression that evaluates to a power of 2 greater than or equal to
13249 @code{CHAR_BIT} and less than some unspecified maximum. Invocations
13250 with other values are rejected with an error indicating the valid bounds.
13251 The function returns a pointer to the first byte of the allocated object.
13252 The lifetime of the allocated object ends at the end of the block in which
13253 the function was called. The allocated storage is released no later than
13254 just before the calling function returns to its caller, but may be released
13255 at the end of the block in which the function was called.
13257 For example, in the following function the call to @code{g} is unsafe
13258 because when @code{overalign} is non-zero, the space allocated by
13259 @code{__builtin_alloca_with_align} may have been released at the end
13260 of the @code{if} statement in which it was called.
13263 void f (unsigned n, bool overalign)
13267 p = __builtin_alloca_with_align (n, 64 /* bits */);
13269 p = __builtin_alloc (n);
13271 g (p, n); // @r{unsafe}
13275 Since the @code{__builtin_alloca_with_align} function doesn't validate its
13276 @var{size} argument it is the responsibility of its caller to make sure
13277 the argument doesn't cause it to exceed the stack size limit.
13278 The @code{__builtin_alloca_with_align} function is provided to make
13279 it possible to allocate on the stack overaligned arrays of bytes with
13280 an upper bound that may be computed at run time. Since C99
13281 Variable Length Arrays offer the same functionality under
13282 a portable, more convenient, and safer interface they are recommended
13283 instead, in both C99 and C++ programs where GCC provides them as
13284 an extension. @xref{Variable Length}, for details.
13288 @deftypefn {Built-in Function} void *__builtin_alloca_with_align_and_max (size_t size, size_t alignment, size_t max_size)
13289 Similar to @code{__builtin_alloca_with_align} but takes an extra argument
13290 specifying an upper bound for @var{size} in case its value cannot be computed
13291 at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage}
13292 and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer
13293 expression, it has no effect on code generation and no attempt is made to
13294 check its compatibility with @var{size}.
13298 @deftypefn {Built-in Function} bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})
13299 The @code{__builtin_has_attribute} function evaluates to an integer constant
13300 expression equal to @code{true} if the symbol or type referenced by
13301 the @var{type-or-expression} argument has been declared with
13302 the @var{attribute} referenced by the second argument. For
13303 an @var{type-or-expression} argument that does not reference a symbol,
13304 since attributes do not apply to expressions the built-in consider
13305 the type of the argument. Neither argument is evaluated.
13306 The @var{type-or-expression} argument is subject to the same
13307 restrictions as the argument to @code{typeof} (@pxref{Typeof}). The
13308 @var{attribute} argument is an attribute name optionally followed by
13309 a comma-separated list of arguments enclosed in parentheses. Both forms
13310 of attribute names---with and without double leading and trailing
13311 underscores---are recognized. @xref{Attribute Syntax}, for details.
13312 When no attribute arguments are specified for an attribute that expects
13313 one or more arguments the function returns @code{true} if
13314 @var{type-or-expression} has been declared with the attribute regardless
13315 of the attribute argument values. Arguments provided for an attribute
13316 that expects some are validated and matched up to the provided number.
13317 The function returns @code{true} if all provided arguments match. For
13318 example, the first call to the function below evaluates to @code{true}
13319 because @code{x} is declared with the @code{aligned} attribute but
13320 the second call evaluates to @code{false} because @code{x} is declared
13321 @code{aligned (8)} and not @code{aligned (4)}.
13324 __attribute__ ((aligned (8))) int x;
13325 _Static_assert (__builtin_has_attribute (x, aligned), "aligned");
13326 _Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)");
13329 Due to a limitation the @code{__builtin_has_attribute} function returns
13330 @code{false} for the @code{mode} attribute even if the type or variable
13331 referenced by the @var{type-or-expression} argument was declared with one.
13332 The function is also not supported with labels, and in C with enumerators.
13334 Note that unlike the @code{__has_attribute} preprocessor operator which
13335 is suitable for use in @code{#if} preprocessing directives
13336 @code{__builtin_has_attribute} is an intrinsic function that is not
13337 recognized in such contexts.
13341 @deftypefn {Built-in Function} @var{type} __builtin_speculation_safe_value (@var{type} val, @var{type} failval)
13343 This built-in function can be used to help mitigate against unsafe
13344 speculative execution. @var{type} may be any integral type or any
13349 If the CPU is not speculatively executing the code, then @var{val}
13352 If the CPU is executing speculatively then either:
13355 The function may cause execution to pause until it is known that the
13356 code is no-longer being executed speculatively (in which case
13357 @var{val} can be returned, as above); or
13359 The function may use target-dependent speculation tracking state to cause
13360 @var{failval} to be returned when it is known that speculative
13361 execution has incorrectly predicted a conditional branch operation.
13365 The second argument, @var{failval}, is optional and defaults to zero
13368 GCC defines the preprocessor macro
13369 @code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been
13370 updated to support this builtin.
13372 The built-in function can be used where a variable appears to be used in a
13373 safe way, but the CPU, due to speculative execution may temporarily ignore
13374 the bounds checks. Consider, for example, the following function:
13378 int f (unsigned untrusted_index)
13380 if (untrusted_index < 500)
13381 return array[untrusted_index];
13386 If the function is called repeatedly with @code{untrusted_index} less
13387 than the limit of 500, then a branch predictor will learn that the
13388 block of code that returns a value stored in @code{array} will be
13389 executed. If the function is subsequently called with an
13390 out-of-range value it will still try to execute that block of code
13391 first until the CPU determines that the prediction was incorrect
13392 (the CPU will unwind any incorrect operations at that point).
13393 However, depending on how the result of the function is used, it might be
13394 possible to leave traces in the cache that can reveal what was stored
13395 at the out-of-bounds location. The built-in function can be used to
13396 provide some protection against leaking data in this way by changing
13401 int f (unsigned untrusted_index)
13403 if (untrusted_index < 500)
13404 return array[__builtin_speculation_safe_value (untrusted_index)];
13409 The built-in function will either cause execution to stall until the
13410 conditional branch has been fully resolved, or it may permit
13411 speculative execution to continue, but using 0 instead of
13412 @code{untrusted_value} if that exceeds the limit.
13414 If accessing any memory location is potentially unsafe when speculative
13415 execution is incorrect, then the code can be rewritten as
13419 int f (unsigned untrusted_index)
13421 if (untrusted_index < 500)
13422 return *__builtin_speculation_safe_value (&array[untrusted_index], NULL);
13427 which will cause a @code{NULL} pointer to be used for the unsafe case.
13431 @deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2})
13433 You can use the built-in function @code{__builtin_types_compatible_p} to
13434 determine whether two types are the same.
13436 This built-in function returns 1 if the unqualified versions of the
13437 types @var{type1} and @var{type2} (which are types, not expressions) are
13438 compatible, 0 otherwise. The result of this built-in function can be
13439 used in integer constant expressions.
13441 This built-in function ignores top level qualifiers (e.g., @code{const},
13442 @code{volatile}). For example, @code{int} is equivalent to @code{const
13445 The type @code{int[]} and @code{int[5]} are compatible. On the other
13446 hand, @code{int} and @code{char *} are not compatible, even if the size
13447 of their types, on the particular architecture are the same. Also, the
13448 amount of pointer indirection is taken into account when determining
13449 similarity. Consequently, @code{short *} is not similar to
13450 @code{short **}. Furthermore, two types that are typedefed are
13451 considered compatible if their underlying types are compatible.
13453 An @code{enum} type is not considered to be compatible with another
13454 @code{enum} type even if both are compatible with the same integer
13455 type; this is what the C standard specifies.
13456 For example, @code{enum @{foo, bar@}} is not similar to
13457 @code{enum @{hot, dog@}}.
13459 You typically use this function in code whose execution varies
13460 depending on the arguments' types. For example:
13465 typeof (x) tmp = (x); \
13466 if (__builtin_types_compatible_p (typeof (x), long double)) \
13467 tmp = foo_long_double (tmp); \
13468 else if (__builtin_types_compatible_p (typeof (x), double)) \
13469 tmp = foo_double (tmp); \
13470 else if (__builtin_types_compatible_p (typeof (x), float)) \
13471 tmp = foo_float (tmp); \
13478 @emph{Note:} This construct is only available for C@.
13482 @deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})
13484 The @var{call_exp} expression must be a function call, and the
13485 @var{pointer_exp} expression must be a pointer. The @var{pointer_exp}
13486 is passed to the function call in the target's static chain location.
13487 The result of builtin is the result of the function call.
13489 @emph{Note:} This builtin is only available for C@.
13490 This builtin can be used to call Go closures from C.
13494 @deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})
13496 You can use the built-in function @code{__builtin_choose_expr} to
13497 evaluate code depending on the value of a constant expression. This
13498 built-in function returns @var{exp1} if @var{const_exp}, which is an
13499 integer constant expression, is nonzero. Otherwise it returns @var{exp2}.
13501 This built-in function is analogous to the @samp{? :} operator in C,
13502 except that the expression returned has its type unaltered by promotion
13503 rules. Also, the built-in function does not evaluate the expression
13504 that is not chosen. For example, if @var{const_exp} evaluates to @code{true},
13505 @var{exp2} is not evaluated even if it has side effects.
13507 This built-in function can return an lvalue if the chosen argument is an
13510 If @var{exp1} is returned, the return type is the same as @var{exp1}'s
13511 type. Similarly, if @var{exp2} is returned, its return type is the same
13518 __builtin_choose_expr ( \
13519 __builtin_types_compatible_p (typeof (x), double), \
13521 __builtin_choose_expr ( \
13522 __builtin_types_compatible_p (typeof (x), float), \
13524 /* @r{The void expression results in a compile-time error} \
13525 @r{when assigning the result to something.} */ \
13529 @emph{Note:} This construct is only available for C@. Furthermore, the
13530 unused expression (@var{exp1} or @var{exp2} depending on the value of
13531 @var{const_exp}) may still generate syntax errors. This may change in
13536 @deftypefn {Built-in Function} @var{type} __builtin_tgmath (@var{functions}, @var{arguments})
13538 The built-in function @code{__builtin_tgmath}, available only for C
13539 and Objective-C, calls a function determined according to the rules of
13540 @code{<tgmath.h>} macros. It is intended to be used in
13541 implementations of that header, so that expansions of macros from that
13542 header only expand each of their arguments once, to avoid problems
13543 when calls to such macros are nested inside the arguments of other
13544 calls to such macros; in addition, it results in better diagnostics
13545 for invalid calls to @code{<tgmath.h>} macros than implementations
13546 using other GNU C language features. For example, the @code{pow}
13547 type-generic macro might be defined as:
13550 #define pow(a, b) __builtin_tgmath (powf, pow, powl, \
13551 cpowf, cpow, cpowl, a, b)
13554 The arguments to @code{__builtin_tgmath} are at least two pointers to
13555 functions, followed by the arguments to the type-generic macro (which
13556 will be passed as arguments to the selected function). All the
13557 pointers to functions must be pointers to prototyped functions, none
13558 of which may have variable arguments, and all of which must have the
13559 same number of parameters; the number of parameters of the first
13560 function determines how many arguments to @code{__builtin_tgmath} are
13561 interpreted as function pointers, and how many as the arguments to the
13564 The types of the specified functions must all be different, but
13565 related to each other in the same way as a set of functions that may
13566 be selected between by a macro in @code{<tgmath.h>}. This means that
13567 the functions are parameterized by a floating-point type @var{t},
13568 different for each such function. The function return types may all
13569 be the same type, or they may be @var{t} for each function, or they
13570 may be the real type corresponding to @var{t} for each function (if
13571 some of the types @var{t} are complex). Likewise, for each parameter
13572 position, the type of the parameter in that position may always be the
13573 same type, or may be @var{t} for each function (this case must apply
13574 for at least one parameter position), or may be the real type
13575 corresponding to @var{t} for each function.
13577 The standard rules for @code{<tgmath.h>} macros are used to find a
13578 common type @var{u} from the types of the arguments for parameters
13579 whose types vary between the functions; complex integer types (a GNU
13580 extension) are treated like @code{_Complex double} for this purpose
13581 (or @code{_Complex _Float64} if all the function return types are the
13582 same @code{_Float@var{n}} or @code{_Float@var{n}x} type).
13583 If the function return types vary, or are all the same integer type,
13584 the function called is the one for which @var{t} is @var{u}, and it is
13585 an error if there is no such function. If the function return types
13586 are all the same floating-point type, the type-generic macro is taken
13587 to be one of those from TS 18661 that rounds the result to a narrower
13588 type; if there is a function for which @var{t} is @var{u}, it is
13589 called, and otherwise the first function, if any, for which @var{t}
13590 has at least the range and precision of @var{u} is called, and it is
13591 an error if there is no such function.
13595 @deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag})
13597 The built-in function @code{__builtin_complex} is provided for use in
13598 implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
13599 @code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
13600 real binary floating-point type, and the result has the corresponding
13601 complex type with real and imaginary parts @var{real} and @var{imag}.
13602 Unlike @samp{@var{real} + I * @var{imag}}, this works even when
13603 infinities, NaNs and negative zeros are involved.
13607 @deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
13608 You can use the built-in function @code{__builtin_constant_p} to
13609 determine if a value is known to be constant at compile time and hence
13610 that GCC can perform constant-folding on expressions involving that
13611 value. The argument of the function is the value to test. The function
13612 returns the integer 1 if the argument is known to be a compile-time
13613 constant and 0 if it is not known to be a compile-time constant. A
13614 return of 0 does not indicate that the value is @emph{not} a constant,
13615 but merely that GCC cannot prove it is a constant with the specified
13616 value of the @option{-O} option.
13618 You typically use this function in an embedded application where
13619 memory is a critical resource. If you have some complex calculation,
13620 you may want it to be folded if it involves constants, but need to call
13621 a function if it does not. For example:
13624 #define Scale_Value(X) \
13625 (__builtin_constant_p (X) \
13626 ? ((X) * SCALE + OFFSET) : Scale (X))
13629 You may use this built-in function in either a macro or an inline
13630 function. However, if you use it in an inlined function and pass an
13631 argument of the function as the argument to the built-in, GCC
13632 never returns 1 when you call the inline function with a string constant
13633 or compound literal (@pxref{Compound Literals}) and does not return 1
13634 when you pass a constant numeric value to the inline function unless you
13635 specify the @option{-O} option.
13637 You may also use @code{__builtin_constant_p} in initializers for static
13638 data. For instance, you can write
13641 static const int table[] = @{
13642 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
13648 This is an acceptable initializer even if @var{EXPRESSION} is not a
13649 constant expression, including the case where
13650 @code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be
13651 folded to a constant but @var{EXPRESSION} contains operands that are
13652 not otherwise permitted in a static initializer (for example,
13653 @code{0 && foo ()}). GCC must be more conservative about evaluating the
13654 built-in in this case, because it has no opportunity to perform
13658 @deftypefn {Built-in Function} bool __builtin_is_constant_evaluated (void)
13659 The @code{__builtin_is_constant_evaluated} function is available only
13660 in C++. The built-in is intended to be used by implementations of
13661 the @code{std::is_constant_evaluated} C++ function. Programs should make
13662 use of the latter function rather than invoking the built-in directly.
13664 The main use case of the built-in is to determine whether a @code{constexpr}
13665 function is being called in a @code{constexpr} context. A call to
13666 the function evaluates to a core constant expression with the value
13667 @code{true} if and only if it occurs within the evaluation of an expression
13668 or conversion that is manifestly constant-evaluated as defined in the C++
13669 standard. Manifestly constant-evaluated contexts include constant-expressions,
13670 the conditions of @code{constexpr if} statements, constraint-expressions, and
13671 initializers of variables usable in constant expressions. For more details
13672 refer to the latest revision of the C++ standard.
13675 @deftypefn {Built-in Function} void __builtin_clear_padding (@var{ptr})
13676 The built-in function @code{__builtin_clear_padding} function clears
13677 padding bits inside of the object representation of object pointed by
13678 @var{ptr}, which has to be a pointer. The value representation of the
13679 object is not affected. The type of the object is assumed to be the type
13680 the pointer points to. Inside of a union, the only cleared bits are
13681 bits that are padding bits for all the union members.
13683 This built-in-function is useful if the padding bits of an object might
13684 have intederminate values and the object representation needs to be
13685 bitwise compared to some other object, for example for atomic operations.
13688 @deftypefn {Built-in Function} @var{type} __builtin_bit_cast (@var{type}, @var{arg})
13689 The @code{__builtin_bit_cast} function is available only
13690 in C++. The built-in is intended to be used by implementations of
13691 the @code{std::bit_cast} C++ template function. Programs should make
13692 use of the latter function rather than invoking the built-in directly.
13694 This built-in function allows reinterpreting the bits of the @var{arg}
13695 argument as if it had type @var{type}. @var{type} and the type of the
13696 @var{arg} argument need to be trivially copyable types with the same size.
13697 When manifestly constant-evaluated, it performs extra diagnostics required
13698 for @code{std::bit_cast} and returns a constant expression if @var{arg}
13699 is a constant expression. For more details
13700 refer to the latest revision of the C++ standard.
13703 @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
13704 @opindex fprofile-arcs
13705 You may use @code{__builtin_expect} to provide the compiler with
13706 branch prediction information. In general, you should prefer to
13707 use actual profile feedback for this (@option{-fprofile-arcs}), as
13708 programmers are notoriously bad at predicting how their programs
13709 actually perform. However, there are applications in which this
13710 data is hard to collect.
13712 The return value is the value of @var{exp}, which should be an integral
13713 expression. The semantics of the built-in are that it is expected that
13714 @var{exp} == @var{c}. For example:
13717 if (__builtin_expect (x, 0))
13722 indicates that we do not expect to call @code{foo}, since
13723 we expect @code{x} to be zero. Since you are limited to integral
13724 expressions for @var{exp}, you should use constructions such as
13727 if (__builtin_expect (ptr != NULL, 1))
13732 when testing pointer or floating-point values.
13734 For the purposes of branch prediction optimizations, the probability that
13735 a @code{__builtin_expect} expression is @code{true} is controlled by GCC's
13736 @code{builtin-expect-probability} parameter, which defaults to 90%.
13738 You can also use @code{__builtin_expect_with_probability} to explicitly
13739 assign a probability value to individual expressions. If the built-in
13740 is used in a loop construct, the provided probability will influence
13741 the expected number of iterations made by loop optimizations.
13744 @deftypefn {Built-in Function} long __builtin_expect_with_probability
13745 (long @var{exp}, long @var{c}, double @var{probability})
13747 This function has the same semantics as @code{__builtin_expect},
13748 but the caller provides the expected probability that @var{exp} == @var{c}.
13749 The last argument, @var{probability}, is a floating-point value in the
13750 range 0.0 to 1.0, inclusive. The @var{probability} argument must be
13751 constant floating-point expression.
13754 @deftypefn {Built-in Function} void __builtin_trap (void)
13755 This function causes the program to exit abnormally. GCC implements
13756 this function by using a target-dependent mechanism (such as
13757 intentionally executing an illegal instruction) or by calling
13758 @code{abort}. The mechanism used may vary from release to release so
13759 you should not rely on any particular implementation.
13762 @deftypefn {Built-in Function} void __builtin_unreachable (void)
13763 If control flow reaches the point of the @code{__builtin_unreachable},
13764 the program is undefined. It is useful in situations where the
13765 compiler cannot deduce the unreachability of the code.
13767 One such case is immediately following an @code{asm} statement that
13768 either never terminates, or one that transfers control elsewhere
13769 and never returns. In this example, without the
13770 @code{__builtin_unreachable}, GCC issues a warning that control
13771 reaches the end of a non-void function. It also generates code
13772 to return after the @code{asm}.
13775 int f (int c, int v)
13783 asm("jmp error_handler");
13784 __builtin_unreachable ();
13790 Because the @code{asm} statement unconditionally transfers control out
13791 of the function, control never reaches the end of the function
13792 body. The @code{__builtin_unreachable} is in fact unreachable and
13793 communicates this fact to the compiler.
13795 Another use for @code{__builtin_unreachable} is following a call a
13796 function that never returns but that is not declared
13797 @code{__attribute__((noreturn))}, as in this example:
13800 void function_that_never_returns (void);
13810 function_that_never_returns ();
13811 __builtin_unreachable ();
13818 @deftypefn {Built-in Function} {void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)
13819 This function returns its first argument, and allows the compiler
13820 to assume that the returned pointer is at least @var{align} bytes
13821 aligned. This built-in can have either two or three arguments,
13822 if it has three, the third argument should have integer type, and
13823 if it is nonzero means misalignment offset. For example:
13826 void *x = __builtin_assume_aligned (arg, 16);
13830 means that the compiler can assume @code{x}, set to @code{arg}, is at least
13831 16-byte aligned, while:
13834 void *x = __builtin_assume_aligned (arg, 32, 8);
13838 means that the compiler can assume for @code{x}, set to @code{arg}, that
13839 @code{(char *) x - 8} is 32-byte aligned.
13842 @deftypefn {Built-in Function} int __builtin_LINE ()
13843 This function is the equivalent of the preprocessor @code{__LINE__}
13844 macro and returns a constant integer expression that evaluates to
13845 the line number of the invocation of the built-in. When used as a C++
13846 default argument for a function @var{F}, it returns the line number
13847 of the call to @var{F}.
13850 @deftypefn {Built-in Function} {const char *} __builtin_FUNCTION ()
13851 This function is the equivalent of the @code{__FUNCTION__} symbol
13852 and returns an address constant pointing to the name of the function
13853 from which the built-in was invoked, or the empty string if
13854 the invocation is not at function scope. When used as a C++ default
13855 argument for a function @var{F}, it returns the name of @var{F}'s
13856 caller or the empty string if the call was not made at function
13860 @deftypefn {Built-in Function} {const char *} __builtin_FILE ()
13861 This function is the equivalent of the preprocessor @code{__FILE__}
13862 macro and returns an address constant pointing to the file name
13863 containing the invocation of the built-in, or the empty string if
13864 the invocation is not at function scope. When used as a C++ default
13865 argument for a function @var{F}, it returns the file name of the call
13866 to @var{F} or the empty string if the call was not made at function
13869 For example, in the following, each call to function @code{foo} will
13870 print a line similar to @code{"file.c:123: foo: message"} with the name
13871 of the file and the line number of the @code{printf} call, the name of
13872 the function @code{foo}, followed by the word @code{message}.
13876 function (const char *func = __builtin_FUNCTION ())
13883 printf ("%s:%i: %s: message\n", file (), line (), function ());
13889 @deftypefn {Built-in Function} void __builtin___clear_cache (void *@var{begin}, void *@var{end})
13890 This function is used to flush the processor's instruction cache for
13891 the region of memory between @var{begin} inclusive and @var{end}
13892 exclusive. Some targets require that the instruction cache be
13893 flushed, after modifying memory containing code, in order to obtain
13894 deterministic behavior.
13896 If the target does not require instruction cache flushes,
13897 @code{__builtin___clear_cache} has no effect. Otherwise either
13898 instructions are emitted in-line to clear the instruction cache or a
13899 call to the @code{__clear_cache} function in libgcc is made.
13902 @deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...)
13903 This function is used to minimize cache-miss latency by moving data into
13904 a cache before it is accessed.
13905 You can insert calls to @code{__builtin_prefetch} into code for which
13906 you know addresses of data in memory that is likely to be accessed soon.
13907 If the target supports them, data prefetch instructions are generated.
13908 If the prefetch is done early enough before the access then the data will
13909 be in the cache by the time it is accessed.
13911 The value of @var{addr} is the address of the memory to prefetch.
13912 There are two optional arguments, @var{rw} and @var{locality}.
13913 The value of @var{rw} is a compile-time constant one or zero; one
13914 means that the prefetch is preparing for a write to the memory address
13915 and zero, the default, means that the prefetch is preparing for a read.
13916 The value @var{locality} must be a compile-time constant integer between
13917 zero and three. A value of zero means that the data has no temporal
13918 locality, so it need not be left in the cache after the access. A value
13919 of three means that the data has a high degree of temporal locality and
13920 should be left in all levels of cache possible. Values of one and two
13921 mean, respectively, a low or moderate degree of temporal locality. The
13925 for (i = 0; i < n; i++)
13927 a[i] = a[i] + b[i];
13928 __builtin_prefetch (&a[i+j], 1, 1);
13929 __builtin_prefetch (&b[i+j], 0, 1);
13934 Data prefetch does not generate faults if @var{addr} is invalid, but
13935 the address expression itself must be valid. For example, a prefetch
13936 of @code{p->next} does not fault if @code{p->next} is not a valid
13937 address, but evaluation faults if @code{p} is not a valid address.
13939 If the target does not support data prefetch, the address expression
13940 is evaluated if it includes side effects but no other code is generated
13941 and GCC does not issue a warning.
13944 @deftypefn {Built-in Function}{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
13945 Returns the size of an object pointed to by @var{ptr}. @xref{Object Size
13946 Checking}, for a detailed description of the function.
13949 @deftypefn {Built-in Function} double __builtin_huge_val (void)
13950 Returns a positive infinity, if supported by the floating-point format,
13951 else @code{DBL_MAX}. This function is suitable for implementing the
13952 ISO C macro @code{HUGE_VAL}.
13955 @deftypefn {Built-in Function} float __builtin_huge_valf (void)
13956 Similar to @code{__builtin_huge_val}, except the return type is @code{float}.
13959 @deftypefn {Built-in Function} {long double} __builtin_huge_vall (void)
13960 Similar to @code{__builtin_huge_val}, except the return
13961 type is @code{long double}.
13964 @deftypefn {Built-in Function} _Float@var{n} __builtin_huge_valf@var{n} (void)
13965 Similar to @code{__builtin_huge_val}, except the return type is
13966 @code{_Float@var{n}}.
13969 @deftypefn {Built-in Function} _Float@var{n}x __builtin_huge_valf@var{n}x (void)
13970 Similar to @code{__builtin_huge_val}, except the return type is
13971 @code{_Float@var{n}x}.
13974 @deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...)
13975 This built-in implements the C99 fpclassify functionality. The first
13976 five int arguments should be the target library's notion of the
13977 possible FP classes and are used for return values. They must be
13978 constant values and they must appear in this order: @code{FP_NAN},
13979 @code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and
13980 @code{FP_ZERO}. The ellipsis is for exactly one floating-point value
13981 to classify. GCC treats the last argument as type-generic, which
13982 means it does not do default promotion from float to double.
13985 @deftypefn {Built-in Function} double __builtin_inf (void)
13986 Similar to @code{__builtin_huge_val}, except a warning is generated
13987 if the target floating-point format does not support infinities.
13990 @deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void)
13991 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}.
13994 @deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void)
13995 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}.
13998 @deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void)
13999 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}.
14002 @deftypefn {Built-in Function} float __builtin_inff (void)
14003 Similar to @code{__builtin_inf}, except the return type is @code{float}.
14004 This function is suitable for implementing the ISO C99 macro @code{INFINITY}.
14007 @deftypefn {Built-in Function} {long double} __builtin_infl (void)
14008 Similar to @code{__builtin_inf}, except the return
14009 type is @code{long double}.
14012 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n} (void)
14013 Similar to @code{__builtin_inf}, except the return
14014 type is @code{_Float@var{n}}.
14017 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n}x (void)
14018 Similar to @code{__builtin_inf}, except the return
14019 type is @code{_Float@var{n}x}.
14022 @deftypefn {Built-in Function} int __builtin_isinf_sign (...)
14023 Similar to @code{isinf}, except the return value is -1 for
14024 an argument of @code{-Inf} and 1 for an argument of @code{+Inf}.
14025 Note while the parameter list is an
14026 ellipsis, this function only accepts exactly one floating-point
14027 argument. GCC treats this parameter as type-generic, which means it
14028 does not do default promotion from float to double.
14031 @deftypefn {Built-in Function} double __builtin_nan (const char *str)
14032 This is an implementation of the ISO C99 function @code{nan}.
14034 Since ISO C99 defines this function in terms of @code{strtod}, which we
14035 do not implement, a description of the parsing is in order. The string
14036 is parsed as by @code{strtol}; that is, the base is recognized by
14037 leading @samp{0} or @samp{0x} prefixes. The number parsed is placed
14038 in the significand such that the least significant bit of the number
14039 is at the least significant bit of the significand. The number is
14040 truncated to fit the significand field provided. The significand is
14041 forced to be a quiet NaN@.
14043 This function, if given a string literal all of which would have been
14044 consumed by @code{strtol}, is evaluated early enough that it is considered a
14045 compile-time constant.
14048 @deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str)
14049 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}.
14052 @deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str)
14053 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}.
14056 @deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str)
14057 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}.
14060 @deftypefn {Built-in Function} float __builtin_nanf (const char *str)
14061 Similar to @code{__builtin_nan}, except the return type is @code{float}.
14064 @deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str)
14065 Similar to @code{__builtin_nan}, except the return type is @code{long double}.
14068 @deftypefn {Built-in Function} _Float@var{n} __builtin_nanf@var{n} (const char *str)
14069 Similar to @code{__builtin_nan}, except the return type is
14070 @code{_Float@var{n}}.
14073 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nanf@var{n}x (const char *str)
14074 Similar to @code{__builtin_nan}, except the return type is
14075 @code{_Float@var{n}x}.
14078 @deftypefn {Built-in Function} double __builtin_nans (const char *str)
14079 Similar to @code{__builtin_nan}, except the significand is forced
14080 to be a signaling NaN@. The @code{nans} function is proposed by
14081 @uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}.
14084 @deftypefn {Built-in Function} _Decimal32 __builtin_nansd32 (const char *str)
14085 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal32}.
14088 @deftypefn {Built-in Function} _Decimal64 __builtin_nansd64 (const char *str)
14089 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal64}.
14092 @deftypefn {Built-in Function} _Decimal128 __builtin_nansd128 (const char *str)
14093 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal128}.
14096 @deftypefn {Built-in Function} float __builtin_nansf (const char *str)
14097 Similar to @code{__builtin_nans}, except the return type is @code{float}.
14100 @deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str)
14101 Similar to @code{__builtin_nans}, except the return type is @code{long double}.
14104 @deftypefn {Built-in Function} _Float@var{n} __builtin_nansf@var{n} (const char *str)
14105 Similar to @code{__builtin_nans}, except the return type is
14106 @code{_Float@var{n}}.
14109 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nansf@var{n}x (const char *str)
14110 Similar to @code{__builtin_nans}, except the return type is
14111 @code{_Float@var{n}x}.
14114 @deftypefn {Built-in Function} int __builtin_ffs (int x)
14115 Returns one plus the index of the least significant 1-bit of @var{x}, or
14116 if @var{x} is zero, returns zero.
14119 @deftypefn {Built-in Function} int __builtin_clz (unsigned int x)
14120 Returns the number of leading 0-bits in @var{x}, starting at the most
14121 significant bit position. If @var{x} is 0, the result is undefined.
14124 @deftypefn {Built-in Function} int __builtin_ctz (unsigned int x)
14125 Returns the number of trailing 0-bits in @var{x}, starting at the least
14126 significant bit position. If @var{x} is 0, the result is undefined.
14129 @deftypefn {Built-in Function} int __builtin_clrsb (int x)
14130 Returns the number of leading redundant sign bits in @var{x}, i.e.@: the
14131 number of bits following the most significant bit that are identical
14132 to it. There are no special cases for 0 or other values.
14135 @deftypefn {Built-in Function} int __builtin_popcount (unsigned int x)
14136 Returns the number of 1-bits in @var{x}.
14139 @deftypefn {Built-in Function} int __builtin_parity (unsigned int x)
14140 Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x}
14144 @deftypefn {Built-in Function} int __builtin_ffsl (long)
14145 Similar to @code{__builtin_ffs}, except the argument type is
14149 @deftypefn {Built-in Function} int __builtin_clzl (unsigned long)
14150 Similar to @code{__builtin_clz}, except the argument type is
14151 @code{unsigned long}.
14154 @deftypefn {Built-in Function} int __builtin_ctzl (unsigned long)
14155 Similar to @code{__builtin_ctz}, except the argument type is
14156 @code{unsigned long}.
14159 @deftypefn {Built-in Function} int __builtin_clrsbl (long)
14160 Similar to @code{__builtin_clrsb}, except the argument type is
14164 @deftypefn {Built-in Function} int __builtin_popcountl (unsigned long)
14165 Similar to @code{__builtin_popcount}, except the argument type is
14166 @code{unsigned long}.
14169 @deftypefn {Built-in Function} int __builtin_parityl (unsigned long)
14170 Similar to @code{__builtin_parity}, except the argument type is
14171 @code{unsigned long}.
14174 @deftypefn {Built-in Function} int __builtin_ffsll (long long)
14175 Similar to @code{__builtin_ffs}, except the argument type is
14179 @deftypefn {Built-in Function} int __builtin_clzll (unsigned long long)
14180 Similar to @code{__builtin_clz}, except the argument type is
14181 @code{unsigned long long}.
14184 @deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long)
14185 Similar to @code{__builtin_ctz}, except the argument type is
14186 @code{unsigned long long}.
14189 @deftypefn {Built-in Function} int __builtin_clrsbll (long long)
14190 Similar to @code{__builtin_clrsb}, except the argument type is
14194 @deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long)
14195 Similar to @code{__builtin_popcount}, except the argument type is
14196 @code{unsigned long long}.
14199 @deftypefn {Built-in Function} int __builtin_parityll (unsigned long long)
14200 Similar to @code{__builtin_parity}, except the argument type is
14201 @code{unsigned long long}.
14204 @deftypefn {Built-in Function} double __builtin_powi (double, int)
14205 Returns the first argument raised to the power of the second. Unlike the
14206 @code{pow} function no guarantees about precision and rounding are made.
14209 @deftypefn {Built-in Function} float __builtin_powif (float, int)
14210 Similar to @code{__builtin_powi}, except the argument and return types
14214 @deftypefn {Built-in Function} {long double} __builtin_powil (long double, int)
14215 Similar to @code{__builtin_powi}, except the argument and return types
14216 are @code{long double}.
14219 @deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x)
14220 Returns @var{x} with the order of the bytes reversed; for example,
14221 @code{0xaabb} becomes @code{0xbbaa}. Byte here always means
14225 @deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x)
14226 Similar to @code{__builtin_bswap16}, except the argument and return types
14230 @deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x)
14231 Similar to @code{__builtin_bswap32}, except the argument and return types
14235 @deftypefn {Built-in Function} uint128_t __builtin_bswap128 (uint128_t x)
14236 Similar to @code{__builtin_bswap64}, except the argument and return types
14237 are 128-bit. Only supported on targets when 128-bit types are supported.
14241 @deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x)
14242 On targets where the user visible pointer size is smaller than the size
14243 of an actual hardware address this function returns the extended user
14244 pointer. Targets where this is true included ILP32 mode on x86_64 or
14245 Aarch64. This function is mainly useful when writing inline assembly
14249 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_id (int x)
14250 Returns the openacc gang, worker or vector id depending on whether @var{x} is
14254 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_size (int x)
14255 Returns the openacc gang, worker or vector size depending on whether @var{x} is
14259 @node Target Builtins
14260 @section Built-in Functions Specific to Particular Target Machines
14262 On some target machines, GCC supports many built-in functions specific
14263 to those machines. Generally these generate calls to specific machine
14264 instructions, but allow the compiler to schedule those calls.
14267 * AArch64 Built-in Functions::
14268 * Alpha Built-in Functions::
14269 * Altera Nios II Built-in Functions::
14270 * ARC Built-in Functions::
14271 * ARC SIMD Built-in Functions::
14272 * ARM iWMMXt Built-in Functions::
14273 * ARM C Language Extensions (ACLE)::
14274 * ARM Floating Point Status and Control Intrinsics::
14275 * ARM ARMv8-M Security Extensions::
14276 * AVR Built-in Functions::
14277 * Blackfin Built-in Functions::
14278 * BPF Built-in Functions::
14279 * FR-V Built-in Functions::
14280 * MIPS DSP Built-in Functions::
14281 * MIPS Paired-Single Support::
14282 * MIPS Loongson Built-in Functions::
14283 * MIPS SIMD Architecture (MSA) Support::
14284 * Other MIPS Built-in Functions::
14285 * MSP430 Built-in Functions::
14286 * NDS32 Built-in Functions::
14287 * picoChip Built-in Functions::
14288 * Basic PowerPC Built-in Functions::
14289 * PowerPC AltiVec/VSX Built-in Functions::
14290 * PowerPC Hardware Transactional Memory Built-in Functions::
14291 * PowerPC Atomic Memory Operation Functions::
14292 * PowerPC Matrix-Multiply Assist Built-in Functions::
14293 * PRU Built-in Functions::
14294 * RISC-V Built-in Functions::
14295 * RX Built-in Functions::
14296 * S/390 System z Built-in Functions::
14297 * SH Built-in Functions::
14298 * SPARC VIS Built-in Functions::
14299 * TI C6X Built-in Functions::
14300 * TILE-Gx Built-in Functions::
14301 * TILEPro Built-in Functions::
14302 * x86 Built-in Functions::
14303 * x86 transactional memory intrinsics::
14304 * x86 control-flow protection intrinsics::
14307 @node AArch64 Built-in Functions
14308 @subsection AArch64 Built-in Functions
14310 These built-in functions are available for the AArch64 family of
14313 unsigned int __builtin_aarch64_get_fpcr ()
14314 void __builtin_aarch64_set_fpcr (unsigned int)
14315 unsigned int __builtin_aarch64_get_fpsr ()
14316 void __builtin_aarch64_set_fpsr (unsigned int)
14318 unsigned long long __builtin_aarch64_get_fpcr64 ()
14319 void __builtin_aarch64_set_fpcr64 (unsigned long long)
14320 unsigned long long __builtin_aarch64_get_fpsr64 ()
14321 void __builtin_aarch64_set_fpsr64 (unsigned long long)
14324 @node Alpha Built-in Functions
14325 @subsection Alpha Built-in Functions
14327 These built-in functions are available for the Alpha family of
14328 processors, depending on the command-line switches used.
14330 The following built-in functions are always available. They
14331 all generate the machine instruction that is part of the name.
14334 long __builtin_alpha_implver (void)
14335 long __builtin_alpha_rpcc (void)
14336 long __builtin_alpha_amask (long)
14337 long __builtin_alpha_cmpbge (long, long)
14338 long __builtin_alpha_extbl (long, long)
14339 long __builtin_alpha_extwl (long, long)
14340 long __builtin_alpha_extll (long, long)
14341 long __builtin_alpha_extql (long, long)
14342 long __builtin_alpha_extwh (long, long)
14343 long __builtin_alpha_extlh (long, long)
14344 long __builtin_alpha_extqh (long, long)
14345 long __builtin_alpha_insbl (long, long)
14346 long __builtin_alpha_inswl (long, long)
14347 long __builtin_alpha_insll (long, long)
14348 long __builtin_alpha_insql (long, long)
14349 long __builtin_alpha_inswh (long, long)
14350 long __builtin_alpha_inslh (long, long)
14351 long __builtin_alpha_insqh (long, long)
14352 long __builtin_alpha_mskbl (long, long)
14353 long __builtin_alpha_mskwl (long, long)
14354 long __builtin_alpha_mskll (long, long)
14355 long __builtin_alpha_mskql (long, long)
14356 long __builtin_alpha_mskwh (long, long)
14357 long __builtin_alpha_msklh (long, long)
14358 long __builtin_alpha_mskqh (long, long)
14359 long __builtin_alpha_umulh (long, long)
14360 long __builtin_alpha_zap (long, long)
14361 long __builtin_alpha_zapnot (long, long)
14364 The following built-in functions are always with @option{-mmax}
14365 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
14366 later. They all generate the machine instruction that is part
14370 long __builtin_alpha_pklb (long)
14371 long __builtin_alpha_pkwb (long)
14372 long __builtin_alpha_unpkbl (long)
14373 long __builtin_alpha_unpkbw (long)
14374 long __builtin_alpha_minub8 (long, long)
14375 long __builtin_alpha_minsb8 (long, long)
14376 long __builtin_alpha_minuw4 (long, long)
14377 long __builtin_alpha_minsw4 (long, long)
14378 long __builtin_alpha_maxub8 (long, long)
14379 long __builtin_alpha_maxsb8 (long, long)
14380 long __builtin_alpha_maxuw4 (long, long)
14381 long __builtin_alpha_maxsw4 (long, long)
14382 long __builtin_alpha_perr (long, long)
14385 The following built-in functions are always with @option{-mcix}
14386 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
14387 later. They all generate the machine instruction that is part
14391 long __builtin_alpha_cttz (long)
14392 long __builtin_alpha_ctlz (long)
14393 long __builtin_alpha_ctpop (long)
14396 The following built-in functions are available on systems that use the OSF/1
14397 PALcode. Normally they invoke the @code{rduniq} and @code{wruniq}
14398 PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
14399 @code{rdval} and @code{wrval}.
14402 void *__builtin_thread_pointer (void)
14403 void __builtin_set_thread_pointer (void *)
14406 @node Altera Nios II Built-in Functions
14407 @subsection Altera Nios II Built-in Functions
14409 These built-in functions are available for the Altera Nios II
14410 family of processors.
14412 The following built-in functions are always available. They
14413 all generate the machine instruction that is part of the name.
14416 int __builtin_ldbio (volatile const void *)
14417 int __builtin_ldbuio (volatile const void *)
14418 int __builtin_ldhio (volatile const void *)
14419 int __builtin_ldhuio (volatile const void *)
14420 int __builtin_ldwio (volatile const void *)
14421 void __builtin_stbio (volatile void *, int)
14422 void __builtin_sthio (volatile void *, int)
14423 void __builtin_stwio (volatile void *, int)
14424 void __builtin_sync (void)
14425 int __builtin_rdctl (int)
14426 int __builtin_rdprs (int, int)
14427 void __builtin_wrctl (int, int)
14428 void __builtin_flushd (volatile void *)
14429 void __builtin_flushda (volatile void *)
14430 int __builtin_wrpie (int);
14431 void __builtin_eni (int);
14432 int __builtin_ldex (volatile const void *)
14433 int __builtin_stex (volatile void *, int)
14434 int __builtin_ldsex (volatile const void *)
14435 int __builtin_stsex (volatile void *, int)
14438 The following built-in functions are always available. They
14439 all generate a Nios II Custom Instruction. The name of the
14440 function represents the types that the function takes and
14441 returns. The letter before the @code{n} is the return type
14442 or void if absent. The @code{n} represents the first parameter
14443 to all the custom instructions, the custom instruction number.
14444 The two letters after the @code{n} represent the up to two
14445 parameters to the function.
14447 The letters represent the following data types:
14450 @code{void} for return type and no parameter for parameter types.
14453 @code{int} for return type and parameter type
14456 @code{float} for return type and parameter type
14459 @code{void *} for return type and parameter type
14463 And the function names are:
14465 void __builtin_custom_n (void)
14466 void __builtin_custom_ni (int)
14467 void __builtin_custom_nf (float)
14468 void __builtin_custom_np (void *)
14469 void __builtin_custom_nii (int, int)
14470 void __builtin_custom_nif (int, float)
14471 void __builtin_custom_nip (int, void *)
14472 void __builtin_custom_nfi (float, int)
14473 void __builtin_custom_nff (float, float)
14474 void __builtin_custom_nfp (float, void *)
14475 void __builtin_custom_npi (void *, int)
14476 void __builtin_custom_npf (void *, float)
14477 void __builtin_custom_npp (void *, void *)
14478 int __builtin_custom_in (void)
14479 int __builtin_custom_ini (int)
14480 int __builtin_custom_inf (float)
14481 int __builtin_custom_inp (void *)
14482 int __builtin_custom_inii (int, int)
14483 int __builtin_custom_inif (int, float)
14484 int __builtin_custom_inip (int, void *)
14485 int __builtin_custom_infi (float, int)
14486 int __builtin_custom_inff (float, float)
14487 int __builtin_custom_infp (float, void *)
14488 int __builtin_custom_inpi (void *, int)
14489 int __builtin_custom_inpf (void *, float)
14490 int __builtin_custom_inpp (void *, void *)
14491 float __builtin_custom_fn (void)
14492 float __builtin_custom_fni (int)
14493 float __builtin_custom_fnf (float)
14494 float __builtin_custom_fnp (void *)
14495 float __builtin_custom_fnii (int, int)
14496 float __builtin_custom_fnif (int, float)
14497 float __builtin_custom_fnip (int, void *)
14498 float __builtin_custom_fnfi (float, int)
14499 float __builtin_custom_fnff (float, float)
14500 float __builtin_custom_fnfp (float, void *)
14501 float __builtin_custom_fnpi (void *, int)
14502 float __builtin_custom_fnpf (void *, float)
14503 float __builtin_custom_fnpp (void *, void *)
14504 void * __builtin_custom_pn (void)
14505 void * __builtin_custom_pni (int)
14506 void * __builtin_custom_pnf (float)
14507 void * __builtin_custom_pnp (void *)
14508 void * __builtin_custom_pnii (int, int)
14509 void * __builtin_custom_pnif (int, float)
14510 void * __builtin_custom_pnip (int, void *)
14511 void * __builtin_custom_pnfi (float, int)
14512 void * __builtin_custom_pnff (float, float)
14513 void * __builtin_custom_pnfp (float, void *)
14514 void * __builtin_custom_pnpi (void *, int)
14515 void * __builtin_custom_pnpf (void *, float)
14516 void * __builtin_custom_pnpp (void *, void *)
14519 @node ARC Built-in Functions
14520 @subsection ARC Built-in Functions
14522 The following built-in functions are provided for ARC targets. The
14523 built-ins generate the corresponding assembly instructions. In the
14524 examples given below, the generated code often requires an operand or
14525 result to be in a register. Where necessary further code will be
14526 generated to ensure this is true, but for brevity this is not
14527 described in each case.
14529 @emph{Note:} Using a built-in to generate an instruction not supported
14530 by a target may cause problems. At present the compiler is not
14531 guaranteed to detect such misuse, and as a result an internal compiler
14532 error may be generated.
14534 @deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval})
14535 Return 1 if @var{val} is known to have the byte alignment given
14536 by @var{alignval}, otherwise return 0.
14537 Note that this is different from
14539 __alignof__(*(char *)@var{val}) >= alignval
14541 because __alignof__ sees only the type of the dereference, whereas
14542 __builtin_arc_align uses alignment information from the pointer
14543 as well as from the pointed-to type.
14544 The information available will depend on optimization level.
14547 @deftypefn {Built-in Function} void __builtin_arc_brk (void)
14554 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno})
14555 The operand is the number of a register to be read. Generates:
14557 mov @var{dest}, r@var{regno}
14559 where the value in @var{dest} will be the result returned from the
14563 @deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val})
14564 The first operand is the number of a register to be written, the
14565 second operand is a compile time constant to write into that
14566 register. Generates:
14568 mov r@var{regno}, @var{val}
14572 @deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b})
14573 Only available if either @option{-mcpu=ARC700} or @option{-meA} is set.
14576 divaw @var{dest}, @var{a}, @var{b}
14578 where the value in @var{dest} will be the result returned from the
14582 @deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a})
14589 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr})
14590 The operand, @var{auxv}, is the address of an auxiliary register and
14591 must be a compile time constant. Generates:
14593 lr @var{dest}, [@var{auxr}]
14595 Where the value in @var{dest} will be the result returned from the
14599 @deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b})
14600 Only available with @option{-mmul64}. Generates:
14602 mul64 @var{a}, @var{b}
14606 @deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b})
14607 Only available with @option{-mmul64}. Generates:
14609 mulu64 @var{a}, @var{b}
14613 @deftypefn {Built-in Function} void __builtin_arc_nop (void)
14620 @deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src})
14621 Only valid if the @samp{norm} instruction is available through the
14622 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
14625 norm @var{dest}, @var{src}
14627 Where the value in @var{dest} will be the result returned from the
14631 @deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src})
14632 Only valid if the @samp{normw} instruction is available through the
14633 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
14636 normw @var{dest}, @var{src}
14638 Where the value in @var{dest} will be the result returned from the
14642 @deftypefn {Built-in Function} void __builtin_arc_rtie (void)
14649 @deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a}
14656 @deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{auxr}, unsigned int @var{val})
14657 The first argument, @var{auxv}, is the address of an auxiliary
14658 register, the second argument, @var{val}, is a compile time constant
14659 to be written to the register. Generates:
14661 sr @var{auxr}, [@var{val}]
14665 @deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src})
14666 Only valid with @option{-mswap}. Generates:
14668 swap @var{dest}, @var{src}
14670 Where the value in @var{dest} will be the result returned from the
14674 @deftypefn {Built-in Function} void __builtin_arc_swi (void)
14681 @deftypefn {Built-in Function} void __builtin_arc_sync (void)
14682 Only available with @option{-mcpu=ARC700}. Generates:
14688 @deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c})
14689 Only available with @option{-mcpu=ARC700}. Generates:
14695 @deftypefn {Built-in Function} void __builtin_arc_unimp_s (void)
14696 Only available with @option{-mcpu=ARC700}. Generates:
14702 The instructions generated by the following builtins are not
14703 considered as candidates for scheduling. They are not moved around by
14704 the compiler during scheduling, and thus can be expected to appear
14705 where they are put in the C code:
14707 __builtin_arc_brk()
14708 __builtin_arc_core_read()
14709 __builtin_arc_core_write()
14710 __builtin_arc_flag()
14712 __builtin_arc_sleep()
14714 __builtin_arc_swi()
14717 @node ARC SIMD Built-in Functions
14718 @subsection ARC SIMD Built-in Functions
14720 SIMD builtins provided by the compiler can be used to generate the
14721 vector instructions. This section describes the available builtins
14722 and their usage in programs. With the @option{-msimd} option, the
14723 compiler provides 128-bit vector types, which can be specified using
14724 the @code{vector_size} attribute. The header file @file{arc-simd.h}
14725 can be included to use the following predefined types:
14727 typedef int __v4si __attribute__((vector_size(16)));
14728 typedef short __v8hi __attribute__((vector_size(16)));
14731 These types can be used to define 128-bit variables. The built-in
14732 functions listed in the following section can be used on these
14733 variables to generate the vector operations.
14735 For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file
14736 @file{arc-simd.h} also provides equivalent macros called
14737 @code{_@var{someinsn}} that can be used for programming ease and
14738 improved readability. The following macros for DMA control are also
14741 #define _setup_dma_in_channel_reg _vdiwr
14742 #define _setup_dma_out_channel_reg _vdowr
14745 The following is a complete list of all the SIMD built-ins provided
14746 for ARC, grouped by calling signature.
14748 The following take two @code{__v8hi} arguments and return a
14749 @code{__v8hi} result:
14751 __v8hi __builtin_arc_vaddaw (__v8hi, __v8hi)
14752 __v8hi __builtin_arc_vaddw (__v8hi, __v8hi)
14753 __v8hi __builtin_arc_vand (__v8hi, __v8hi)
14754 __v8hi __builtin_arc_vandaw (__v8hi, __v8hi)
14755 __v8hi __builtin_arc_vavb (__v8hi, __v8hi)
14756 __v8hi __builtin_arc_vavrb (__v8hi, __v8hi)
14757 __v8hi __builtin_arc_vbic (__v8hi, __v8hi)
14758 __v8hi __builtin_arc_vbicaw (__v8hi, __v8hi)
14759 __v8hi __builtin_arc_vdifaw (__v8hi, __v8hi)
14760 __v8hi __builtin_arc_vdifw (__v8hi, __v8hi)
14761 __v8hi __builtin_arc_veqw (__v8hi, __v8hi)
14762 __v8hi __builtin_arc_vh264f (__v8hi, __v8hi)
14763 __v8hi __builtin_arc_vh264ft (__v8hi, __v8hi)
14764 __v8hi __builtin_arc_vh264fw (__v8hi, __v8hi)
14765 __v8hi __builtin_arc_vlew (__v8hi, __v8hi)
14766 __v8hi __builtin_arc_vltw (__v8hi, __v8hi)
14767 __v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi)
14768 __v8hi __builtin_arc_vmaxw (__v8hi, __v8hi)
14769 __v8hi __builtin_arc_vminaw (__v8hi, __v8hi)
14770 __v8hi __builtin_arc_vminw (__v8hi, __v8hi)
14771 __v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi)
14772 __v8hi __builtin_arc_vmr1w (__v8hi, __v8hi)
14773 __v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi)
14774 __v8hi __builtin_arc_vmr2w (__v8hi, __v8hi)
14775 __v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi)
14776 __v8hi __builtin_arc_vmr3w (__v8hi, __v8hi)
14777 __v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi)
14778 __v8hi __builtin_arc_vmr4w (__v8hi, __v8hi)
14779 __v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi)
14780 __v8hi __builtin_arc_vmr5w (__v8hi, __v8hi)
14781 __v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi)
14782 __v8hi __builtin_arc_vmr6w (__v8hi, __v8hi)
14783 __v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi)
14784 __v8hi __builtin_arc_vmr7w (__v8hi, __v8hi)
14785 __v8hi __builtin_arc_vmrb (__v8hi, __v8hi)
14786 __v8hi __builtin_arc_vmulaw (__v8hi, __v8hi)
14787 __v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi)
14788 __v8hi __builtin_arc_vmulfw (__v8hi, __v8hi)
14789 __v8hi __builtin_arc_vmulw (__v8hi, __v8hi)
14790 __v8hi __builtin_arc_vnew (__v8hi, __v8hi)
14791 __v8hi __builtin_arc_vor (__v8hi, __v8hi)
14792 __v8hi __builtin_arc_vsubaw (__v8hi, __v8hi)
14793 __v8hi __builtin_arc_vsubw (__v8hi, __v8hi)
14794 __v8hi __builtin_arc_vsummw (__v8hi, __v8hi)
14795 __v8hi __builtin_arc_vvc1f (__v8hi, __v8hi)
14796 __v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi)
14797 __v8hi __builtin_arc_vxor (__v8hi, __v8hi)
14798 __v8hi __builtin_arc_vxoraw (__v8hi, __v8hi)
14801 The following take one @code{__v8hi} and one @code{int} argument and return a
14802 @code{__v8hi} result:
14805 __v8hi __builtin_arc_vbaddw (__v8hi, int)
14806 __v8hi __builtin_arc_vbmaxw (__v8hi, int)
14807 __v8hi __builtin_arc_vbminw (__v8hi, int)
14808 __v8hi __builtin_arc_vbmulaw (__v8hi, int)
14809 __v8hi __builtin_arc_vbmulfw (__v8hi, int)
14810 __v8hi __builtin_arc_vbmulw (__v8hi, int)
14811 __v8hi __builtin_arc_vbrsubw (__v8hi, int)
14812 __v8hi __builtin_arc_vbsubw (__v8hi, int)
14815 The following take one @code{__v8hi} argument and one @code{int} argument which
14816 must be a 3-bit compile time constant indicating a register number
14817 I0-I7. They return a @code{__v8hi} result.
14819 __v8hi __builtin_arc_vasrw (__v8hi, const int)
14820 __v8hi __builtin_arc_vsr8 (__v8hi, const int)
14821 __v8hi __builtin_arc_vsr8aw (__v8hi, const int)
14824 The following take one @code{__v8hi} argument and one @code{int}
14825 argument which must be a 6-bit compile time constant. They return a
14826 @code{__v8hi} result.
14828 __v8hi __builtin_arc_vasrpwbi (__v8hi, const int)
14829 __v8hi __builtin_arc_vasrrpwbi (__v8hi, const int)
14830 __v8hi __builtin_arc_vasrrwi (__v8hi, const int)
14831 __v8hi __builtin_arc_vasrsrwi (__v8hi, const int)
14832 __v8hi __builtin_arc_vasrwi (__v8hi, const int)
14833 __v8hi __builtin_arc_vsr8awi (__v8hi, const int)
14834 __v8hi __builtin_arc_vsr8i (__v8hi, const int)
14837 The following take one @code{__v8hi} argument and one @code{int} argument which
14838 must be a 8-bit compile time constant. They return a @code{__v8hi}
14841 __v8hi __builtin_arc_vd6tapf (__v8hi, const int)
14842 __v8hi __builtin_arc_vmvaw (__v8hi, const int)
14843 __v8hi __builtin_arc_vmvw (__v8hi, const int)
14844 __v8hi __builtin_arc_vmvzw (__v8hi, const int)
14847 The following take two @code{int} arguments, the second of which which
14848 must be a 8-bit compile time constant. They return a @code{__v8hi}
14851 __v8hi __builtin_arc_vmovaw (int, const int)
14852 __v8hi __builtin_arc_vmovw (int, const int)
14853 __v8hi __builtin_arc_vmovzw (int, const int)
14856 The following take a single @code{__v8hi} argument and return a
14857 @code{__v8hi} result:
14859 __v8hi __builtin_arc_vabsaw (__v8hi)
14860 __v8hi __builtin_arc_vabsw (__v8hi)
14861 __v8hi __builtin_arc_vaddsuw (__v8hi)
14862 __v8hi __builtin_arc_vexch1 (__v8hi)
14863 __v8hi __builtin_arc_vexch2 (__v8hi)
14864 __v8hi __builtin_arc_vexch4 (__v8hi)
14865 __v8hi __builtin_arc_vsignw (__v8hi)
14866 __v8hi __builtin_arc_vupbaw (__v8hi)
14867 __v8hi __builtin_arc_vupbw (__v8hi)
14868 __v8hi __builtin_arc_vupsbaw (__v8hi)
14869 __v8hi __builtin_arc_vupsbw (__v8hi)
14872 The following take two @code{int} arguments and return no result:
14874 void __builtin_arc_vdirun (int, int)
14875 void __builtin_arc_vdorun (int, int)
14878 The following take two @code{int} arguments and return no result. The
14879 first argument must a 3-bit compile time constant indicating one of
14880 the DR0-DR7 DMA setup channels:
14882 void __builtin_arc_vdiwr (const int, int)
14883 void __builtin_arc_vdowr (const int, int)
14886 The following take an @code{int} argument and return no result:
14888 void __builtin_arc_vendrec (int)
14889 void __builtin_arc_vrec (int)
14890 void __builtin_arc_vrecrun (int)
14891 void __builtin_arc_vrun (int)
14894 The following take a @code{__v8hi} argument and two @code{int}
14895 arguments and return a @code{__v8hi} result. The second argument must
14896 be a 3-bit compile time constants, indicating one the registers I0-I7,
14897 and the third argument must be an 8-bit compile time constant.
14899 @emph{Note:} Although the equivalent hardware instructions do not take
14900 an SIMD register as an operand, these builtins overwrite the relevant
14901 bits of the @code{__v8hi} register provided as the first argument with
14902 the value loaded from the @code{[Ib, u8]} location in the SDM.
14905 __v8hi __builtin_arc_vld32 (__v8hi, const int, const int)
14906 __v8hi __builtin_arc_vld32wh (__v8hi, const int, const int)
14907 __v8hi __builtin_arc_vld32wl (__v8hi, const int, const int)
14908 __v8hi __builtin_arc_vld64 (__v8hi, const int, const int)
14911 The following take two @code{int} arguments and return a @code{__v8hi}
14912 result. The first argument must be a 3-bit compile time constants,
14913 indicating one the registers I0-I7, and the second argument must be an
14914 8-bit compile time constant.
14917 __v8hi __builtin_arc_vld128 (const int, const int)
14918 __v8hi __builtin_arc_vld64w (const int, const int)
14921 The following take a @code{__v8hi} argument and two @code{int}
14922 arguments and return no result. The second argument must be a 3-bit
14923 compile time constants, indicating one the registers I0-I7, and the
14924 third argument must be an 8-bit compile time constant.
14927 void __builtin_arc_vst128 (__v8hi, const int, const int)
14928 void __builtin_arc_vst64 (__v8hi, const int, const int)
14931 The following take a @code{__v8hi} argument and three @code{int}
14932 arguments and return no result. The second argument must be a 3-bit
14933 compile-time constant, identifying the 16-bit sub-register to be
14934 stored, the third argument must be a 3-bit compile time constants,
14935 indicating one the registers I0-I7, and the fourth argument must be an
14936 8-bit compile time constant.
14939 void __builtin_arc_vst16_n (__v8hi, const int, const int, const int)
14940 void __builtin_arc_vst32_n (__v8hi, const int, const int, const int)
14943 @node ARM iWMMXt Built-in Functions
14944 @subsection ARM iWMMXt Built-in Functions
14946 These built-in functions are available for the ARM family of
14947 processors when the @option{-mcpu=iwmmxt} switch is used:
14950 typedef int v2si __attribute__ ((vector_size (8)));
14951 typedef short v4hi __attribute__ ((vector_size (8)));
14952 typedef char v8qi __attribute__ ((vector_size (8)));
14954 int __builtin_arm_getwcgr0 (void)
14955 void __builtin_arm_setwcgr0 (int)
14956 int __builtin_arm_getwcgr1 (void)
14957 void __builtin_arm_setwcgr1 (int)
14958 int __builtin_arm_getwcgr2 (void)
14959 void __builtin_arm_setwcgr2 (int)
14960 int __builtin_arm_getwcgr3 (void)
14961 void __builtin_arm_setwcgr3 (int)
14962 int __builtin_arm_textrmsb (v8qi, int)
14963 int __builtin_arm_textrmsh (v4hi, int)
14964 int __builtin_arm_textrmsw (v2si, int)
14965 int __builtin_arm_textrmub (v8qi, int)
14966 int __builtin_arm_textrmuh (v4hi, int)
14967 int __builtin_arm_textrmuw (v2si, int)
14968 v8qi __builtin_arm_tinsrb (v8qi, int, int)
14969 v4hi __builtin_arm_tinsrh (v4hi, int, int)
14970 v2si __builtin_arm_tinsrw (v2si, int, int)
14971 long long __builtin_arm_tmia (long long, int, int)
14972 long long __builtin_arm_tmiabb (long long, int, int)
14973 long long __builtin_arm_tmiabt (long long, int, int)
14974 long long __builtin_arm_tmiaph (long long, int, int)
14975 long long __builtin_arm_tmiatb (long long, int, int)
14976 long long __builtin_arm_tmiatt (long long, int, int)
14977 int __builtin_arm_tmovmskb (v8qi)
14978 int __builtin_arm_tmovmskh (v4hi)
14979 int __builtin_arm_tmovmskw (v2si)
14980 long long __builtin_arm_waccb (v8qi)
14981 long long __builtin_arm_wacch (v4hi)
14982 long long __builtin_arm_waccw (v2si)
14983 v8qi __builtin_arm_waddb (v8qi, v8qi)
14984 v8qi __builtin_arm_waddbss (v8qi, v8qi)
14985 v8qi __builtin_arm_waddbus (v8qi, v8qi)
14986 v4hi __builtin_arm_waddh (v4hi, v4hi)
14987 v4hi __builtin_arm_waddhss (v4hi, v4hi)
14988 v4hi __builtin_arm_waddhus (v4hi, v4hi)
14989 v2si __builtin_arm_waddw (v2si, v2si)
14990 v2si __builtin_arm_waddwss (v2si, v2si)
14991 v2si __builtin_arm_waddwus (v2si, v2si)
14992 v8qi __builtin_arm_walign (v8qi, v8qi, int)
14993 long long __builtin_arm_wand(long long, long long)
14994 long long __builtin_arm_wandn (long long, long long)
14995 v8qi __builtin_arm_wavg2b (v8qi, v8qi)
14996 v8qi __builtin_arm_wavg2br (v8qi, v8qi)
14997 v4hi __builtin_arm_wavg2h (v4hi, v4hi)
14998 v4hi __builtin_arm_wavg2hr (v4hi, v4hi)
14999 v8qi __builtin_arm_wcmpeqb (v8qi, v8qi)
15000 v4hi __builtin_arm_wcmpeqh (v4hi, v4hi)
15001 v2si __builtin_arm_wcmpeqw (v2si, v2si)
15002 v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi)
15003 v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi)
15004 v2si __builtin_arm_wcmpgtsw (v2si, v2si)
15005 v8qi __builtin_arm_wcmpgtub (v8qi, v8qi)
15006 v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi)
15007 v2si __builtin_arm_wcmpgtuw (v2si, v2si)
15008 long long __builtin_arm_wmacs (long long, v4hi, v4hi)
15009 long long __builtin_arm_wmacsz (v4hi, v4hi)
15010 long long __builtin_arm_wmacu (long long, v4hi, v4hi)
15011 long long __builtin_arm_wmacuz (v4hi, v4hi)
15012 v4hi __builtin_arm_wmadds (v4hi, v4hi)
15013 v4hi __builtin_arm_wmaddu (v4hi, v4hi)
15014 v8qi __builtin_arm_wmaxsb (v8qi, v8qi)
15015 v4hi __builtin_arm_wmaxsh (v4hi, v4hi)
15016 v2si __builtin_arm_wmaxsw (v2si, v2si)
15017 v8qi __builtin_arm_wmaxub (v8qi, v8qi)
15018 v4hi __builtin_arm_wmaxuh (v4hi, v4hi)
15019 v2si __builtin_arm_wmaxuw (v2si, v2si)
15020 v8qi __builtin_arm_wminsb (v8qi, v8qi)
15021 v4hi __builtin_arm_wminsh (v4hi, v4hi)
15022 v2si __builtin_arm_wminsw (v2si, v2si)
15023 v8qi __builtin_arm_wminub (v8qi, v8qi)
15024 v4hi __builtin_arm_wminuh (v4hi, v4hi)
15025 v2si __builtin_arm_wminuw (v2si, v2si)
15026 v4hi __builtin_arm_wmulsm (v4hi, v4hi)
15027 v4hi __builtin_arm_wmulul (v4hi, v4hi)
15028 v4hi __builtin_arm_wmulum (v4hi, v4hi)
15029 long long __builtin_arm_wor (long long, long long)
15030 v2si __builtin_arm_wpackdss (long long, long long)
15031 v2si __builtin_arm_wpackdus (long long, long long)
15032 v8qi __builtin_arm_wpackhss (v4hi, v4hi)
15033 v8qi __builtin_arm_wpackhus (v4hi, v4hi)
15034 v4hi __builtin_arm_wpackwss (v2si, v2si)
15035 v4hi __builtin_arm_wpackwus (v2si, v2si)
15036 long long __builtin_arm_wrord (long long, long long)
15037 long long __builtin_arm_wrordi (long long, int)
15038 v4hi __builtin_arm_wrorh (v4hi, long long)
15039 v4hi __builtin_arm_wrorhi (v4hi, int)
15040 v2si __builtin_arm_wrorw (v2si, long long)
15041 v2si __builtin_arm_wrorwi (v2si, int)
15042 v2si __builtin_arm_wsadb (v2si, v8qi, v8qi)
15043 v2si __builtin_arm_wsadbz (v8qi, v8qi)
15044 v2si __builtin_arm_wsadh (v2si, v4hi, v4hi)
15045 v2si __builtin_arm_wsadhz (v4hi, v4hi)
15046 v4hi __builtin_arm_wshufh (v4hi, int)
15047 long long __builtin_arm_wslld (long long, long long)
15048 long long __builtin_arm_wslldi (long long, int)
15049 v4hi __builtin_arm_wsllh (v4hi, long long)
15050 v4hi __builtin_arm_wsllhi (v4hi, int)
15051 v2si __builtin_arm_wsllw (v2si, long long)
15052 v2si __builtin_arm_wsllwi (v2si, int)
15053 long long __builtin_arm_wsrad (long long, long long)
15054 long long __builtin_arm_wsradi (long long, int)
15055 v4hi __builtin_arm_wsrah (v4hi, long long)
15056 v4hi __builtin_arm_wsrahi (v4hi, int)
15057 v2si __builtin_arm_wsraw (v2si, long long)
15058 v2si __builtin_arm_wsrawi (v2si, int)
15059 long long __builtin_arm_wsrld (long long, long long)
15060 long long __builtin_arm_wsrldi (long long, int)
15061 v4hi __builtin_arm_wsrlh (v4hi, long long)
15062 v4hi __builtin_arm_wsrlhi (v4hi, int)
15063 v2si __builtin_arm_wsrlw (v2si, long long)
15064 v2si __builtin_arm_wsrlwi (v2si, int)
15065 v8qi __builtin_arm_wsubb (v8qi, v8qi)
15066 v8qi __builtin_arm_wsubbss (v8qi, v8qi)
15067 v8qi __builtin_arm_wsubbus (v8qi, v8qi)
15068 v4hi __builtin_arm_wsubh (v4hi, v4hi)
15069 v4hi __builtin_arm_wsubhss (v4hi, v4hi)
15070 v4hi __builtin_arm_wsubhus (v4hi, v4hi)
15071 v2si __builtin_arm_wsubw (v2si, v2si)
15072 v2si __builtin_arm_wsubwss (v2si, v2si)
15073 v2si __builtin_arm_wsubwus (v2si, v2si)
15074 v4hi __builtin_arm_wunpckehsb (v8qi)
15075 v2si __builtin_arm_wunpckehsh (v4hi)
15076 long long __builtin_arm_wunpckehsw (v2si)
15077 v4hi __builtin_arm_wunpckehub (v8qi)
15078 v2si __builtin_arm_wunpckehuh (v4hi)
15079 long long __builtin_arm_wunpckehuw (v2si)
15080 v4hi __builtin_arm_wunpckelsb (v8qi)
15081 v2si __builtin_arm_wunpckelsh (v4hi)
15082 long long __builtin_arm_wunpckelsw (v2si)
15083 v4hi __builtin_arm_wunpckelub (v8qi)
15084 v2si __builtin_arm_wunpckeluh (v4hi)
15085 long long __builtin_arm_wunpckeluw (v2si)
15086 v8qi __builtin_arm_wunpckihb (v8qi, v8qi)
15087 v4hi __builtin_arm_wunpckihh (v4hi, v4hi)
15088 v2si __builtin_arm_wunpckihw (v2si, v2si)
15089 v8qi __builtin_arm_wunpckilb (v8qi, v8qi)
15090 v4hi __builtin_arm_wunpckilh (v4hi, v4hi)
15091 v2si __builtin_arm_wunpckilw (v2si, v2si)
15092 long long __builtin_arm_wxor (long long, long long)
15093 long long __builtin_arm_wzero ()
15097 @node ARM C Language Extensions (ACLE)
15098 @subsection ARM C Language Extensions (ACLE)
15100 GCC implements extensions for C as described in the ARM C Language
15101 Extensions (ACLE) specification, which can be found at
15102 @uref{https://developer.arm.com/documentation/ihi0053/latest/}.
15104 As a part of ACLE, GCC implements extensions for Advanced SIMD as described in
15105 the ARM C Language Extensions Specification. The complete list of Advanced SIMD
15106 intrinsics can be found at
15107 @uref{https://developer.arm.com/documentation/ihi0073/latest/}.
15108 The built-in intrinsics for the Advanced SIMD extension are available when
15111 Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both
15112 back ends support CRC32 intrinsics and the ARM back end supports the
15113 Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit
15114 floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1.
15115 AArch64's back end does not have support for 16-bit floating point Advanced SIMD
15118 See @ref{ARM Options} and @ref{AArch64 Options} for more information on the
15119 availability of extensions.
15121 @node ARM Floating Point Status and Control Intrinsics
15122 @subsection ARM Floating Point Status and Control Intrinsics
15124 These built-in functions are available for the ARM family of
15125 processors with floating-point unit.
15128 unsigned int __builtin_arm_get_fpscr ()
15129 void __builtin_arm_set_fpscr (unsigned int)
15132 @node ARM ARMv8-M Security Extensions
15133 @subsection ARM ARMv8-M Security Extensions
15135 GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M
15136 Security Extensions: Requirements on Development Tools Engineering
15137 Specification, which can be found at
15138 @uref{https://developer.arm.com/documentation/ecm0359818/latest/}.
15140 As part of the Security Extensions GCC implements two new function attributes:
15141 @code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}.
15143 As part of the Security Extensions GCC implements the intrinsics below. FPTR
15144 is used here to mean any function pointer type.
15147 cmse_address_info_t cmse_TT (void *)
15148 cmse_address_info_t cmse_TT_fptr (FPTR)
15149 cmse_address_info_t cmse_TTT (void *)
15150 cmse_address_info_t cmse_TTT_fptr (FPTR)
15151 cmse_address_info_t cmse_TTA (void *)
15152 cmse_address_info_t cmse_TTA_fptr (FPTR)
15153 cmse_address_info_t cmse_TTAT (void *)
15154 cmse_address_info_t cmse_TTAT_fptr (FPTR)
15155 void * cmse_check_address_range (void *, size_t, int)
15156 typeof(p) cmse_nsfptr_create (FPTR p)
15157 intptr_t cmse_is_nsfptr (FPTR)
15158 int cmse_nonsecure_caller (void)
15161 @node AVR Built-in Functions
15162 @subsection AVR Built-in Functions
15164 For each built-in function for AVR, there is an equally named,
15165 uppercase built-in macro defined. That way users can easily query if
15166 or if not a specific built-in is implemented or not. For example, if
15167 @code{__builtin_avr_nop} is available the macro
15168 @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise.
15172 @item void __builtin_avr_nop (void)
15173 @itemx void __builtin_avr_sei (void)
15174 @itemx void __builtin_avr_cli (void)
15175 @itemx void __builtin_avr_sleep (void)
15176 @itemx void __builtin_avr_wdr (void)
15177 @itemx unsigned char __builtin_avr_swap (unsigned char)
15178 @itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char)
15179 @itemx int __builtin_avr_fmuls (char, char)
15180 @itemx int __builtin_avr_fmulsu (char, unsigned char)
15181 These built-in functions map to the respective machine
15182 instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep},
15183 @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls}
15184 resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented
15185 as library call if no hardware multiplier is available.
15187 @item void __builtin_avr_delay_cycles (unsigned long ticks)
15188 Delay execution for @var{ticks} cycles. Note that this
15189 built-in does not take into account the effect of interrupts that
15190 might increase delay time. @var{ticks} must be a compile-time
15191 integer constant; delays with a variable number of cycles are not supported.
15193 @item char __builtin_avr_flash_segment (const __memx void*)
15194 This built-in takes a byte address to the 24-bit
15195 @ref{AVR Named Address Spaces,address space} @code{__memx} and returns
15196 the number of the flash segment (the 64 KiB chunk) where the address
15197 points to. Counting starts at @code{0}.
15198 If the address does not point to flash memory, return @code{-1}.
15200 @item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val)
15201 Insert bits from @var{bits} into @var{val} and return the resulting
15202 value. The nibbles of @var{map} determine how the insertion is
15203 performed: Let @var{X} be the @var{n}-th nibble of @var{map}
15205 @item If @var{X} is @code{0xf},
15206 then the @var{n}-th bit of @var{val} is returned unaltered.
15208 @item If X is in the range 0@dots{}7,
15209 then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits}
15211 @item If X is in the range 8@dots{}@code{0xe},
15212 then the @var{n}-th result bit is undefined.
15216 One typical use case for this built-in is adjusting input and
15217 output values to non-contiguous port layouts. Some examples:
15220 // same as val, bits is unused
15221 __builtin_avr_insert_bits (0xffffffff, bits, val)
15225 // same as bits, val is unused
15226 __builtin_avr_insert_bits (0x76543210, bits, val)
15230 // same as rotating bits by 4
15231 __builtin_avr_insert_bits (0x32107654, bits, 0)
15235 // high nibble of result is the high nibble of val
15236 // low nibble of result is the low nibble of bits
15237 __builtin_avr_insert_bits (0xffff3210, bits, val)
15241 // reverse the bit order of bits
15242 __builtin_avr_insert_bits (0x01234567, bits, 0)
15245 @item void __builtin_avr_nops (unsigned count)
15246 Insert @var{count} @code{NOP} instructions.
15247 The number of instructions must be a compile-time integer constant.
15252 There are many more AVR-specific built-in functions that are used to
15253 implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of
15254 section 7.18a.6. You don't need to use these built-ins directly.
15255 Instead, use the declarations as supplied by the @code{stdfix.h} header
15259 #include <stdfix.h>
15261 // Re-interpret the bit representation of unsigned 16-bit
15262 // integer @var{uval} as Q-format 0.16 value.
15263 unsigned fract get_bits (uint_ur_t uval)
15265 return urbits (uval);
15269 @node Blackfin Built-in Functions
15270 @subsection Blackfin Built-in Functions
15272 Currently, there are two Blackfin-specific built-in functions. These are
15273 used for generating @code{CSYNC} and @code{SSYNC} machine insns without
15274 using inline assembly; by using these built-in functions the compiler can
15275 automatically add workarounds for hardware errata involving these
15276 instructions. These functions are named as follows:
15279 void __builtin_bfin_csync (void)
15280 void __builtin_bfin_ssync (void)
15283 @node BPF Built-in Functions
15284 @subsection BPF Built-in Functions
15286 The following built-in functions are available for eBPF targets.
15288 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_byte (unsigned long long @var{offset})
15289 Load a byte from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
15292 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_half (unsigned long long @var{offset})
15293 Load 16-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
15296 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_word (unsigned long long @var{offset})
15297 Load 32-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
15300 @node FR-V Built-in Functions
15301 @subsection FR-V Built-in Functions
15303 GCC provides many FR-V-specific built-in functions. In general,
15304 these functions are intended to be compatible with those described
15305 by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu
15306 Semiconductor}. The two exceptions are @code{__MDUNPACKH} and
15307 @code{__MBTOHE}, the GCC forms of which pass 128-bit values by
15308 pointer rather than by value.
15310 Most of the functions are named after specific FR-V instructions.
15311 Such functions are said to be ``directly mapped'' and are summarized
15312 here in tabular form.
15316 * Directly-mapped Integer Functions::
15317 * Directly-mapped Media Functions::
15318 * Raw read/write Functions::
15319 * Other Built-in Functions::
15322 @node Argument Types
15323 @subsubsection Argument Types
15325 The arguments to the built-in functions can be divided into three groups:
15326 register numbers, compile-time constants and run-time values. In order
15327 to make this classification clear at a glance, the arguments and return
15328 values are given the following pseudo types:
15330 @multitable @columnfractions .20 .30 .15 .35
15331 @item Pseudo type @tab Real C type @tab Constant? @tab Description
15332 @item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword
15333 @item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word
15334 @item @code{sw1} @tab @code{int} @tab No @tab a signed word
15335 @item @code{uw2} @tab @code{unsigned long long} @tab No
15336 @tab an unsigned doubleword
15337 @item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword
15338 @item @code{const} @tab @code{int} @tab Yes @tab an integer constant
15339 @item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number
15340 @item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number
15343 These pseudo types are not defined by GCC, they are simply a notational
15344 convenience used in this manual.
15346 Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2}
15347 and @code{sw2} are evaluated at run time. They correspond to
15348 register operands in the underlying FR-V instructions.
15350 @code{const} arguments represent immediate operands in the underlying
15351 FR-V instructions. They must be compile-time constants.
15353 @code{acc} arguments are evaluated at compile time and specify the number
15354 of an accumulator register. For example, an @code{acc} argument of 2
15355 selects the ACC2 register.
15357 @code{iacc} arguments are similar to @code{acc} arguments but specify the
15358 number of an IACC register. See @pxref{Other Built-in Functions}
15361 @node Directly-mapped Integer Functions
15362 @subsubsection Directly-Mapped Integer Functions
15364 The functions listed below map directly to FR-V I-type instructions.
15366 @multitable @columnfractions .45 .32 .23
15367 @item Function prototype @tab Example usage @tab Assembly output
15368 @item @code{sw1 __ADDSS (sw1, sw1)}
15369 @tab @code{@var{c} = __ADDSS (@var{a}, @var{b})}
15370 @tab @code{ADDSS @var{a},@var{b},@var{c}}
15371 @item @code{sw1 __SCAN (sw1, sw1)}
15372 @tab @code{@var{c} = __SCAN (@var{a}, @var{b})}
15373 @tab @code{SCAN @var{a},@var{b},@var{c}}
15374 @item @code{sw1 __SCUTSS (sw1)}
15375 @tab @code{@var{b} = __SCUTSS (@var{a})}
15376 @tab @code{SCUTSS @var{a},@var{b}}
15377 @item @code{sw1 __SLASS (sw1, sw1)}
15378 @tab @code{@var{c} = __SLASS (@var{a}, @var{b})}
15379 @tab @code{SLASS @var{a},@var{b},@var{c}}
15380 @item @code{void __SMASS (sw1, sw1)}
15381 @tab @code{__SMASS (@var{a}, @var{b})}
15382 @tab @code{SMASS @var{a},@var{b}}
15383 @item @code{void __SMSSS (sw1, sw1)}
15384 @tab @code{__SMSSS (@var{a}, @var{b})}
15385 @tab @code{SMSSS @var{a},@var{b}}
15386 @item @code{void __SMU (sw1, sw1)}
15387 @tab @code{__SMU (@var{a}, @var{b})}
15388 @tab @code{SMU @var{a},@var{b}}
15389 @item @code{sw2 __SMUL (sw1, sw1)}
15390 @tab @code{@var{c} = __SMUL (@var{a}, @var{b})}
15391 @tab @code{SMUL @var{a},@var{b},@var{c}}
15392 @item @code{sw1 __SUBSS (sw1, sw1)}
15393 @tab @code{@var{c} = __SUBSS (@var{a}, @var{b})}
15394 @tab @code{SUBSS @var{a},@var{b},@var{c}}
15395 @item @code{uw2 __UMUL (uw1, uw1)}
15396 @tab @code{@var{c} = __UMUL (@var{a}, @var{b})}
15397 @tab @code{UMUL @var{a},@var{b},@var{c}}
15400 @node Directly-mapped Media Functions
15401 @subsubsection Directly-Mapped Media Functions
15403 The functions listed below map directly to FR-V M-type instructions.
15405 @multitable @columnfractions .45 .32 .23
15406 @item Function prototype @tab Example usage @tab Assembly output
15407 @item @code{uw1 __MABSHS (sw1)}
15408 @tab @code{@var{b} = __MABSHS (@var{a})}
15409 @tab @code{MABSHS @var{a},@var{b}}
15410 @item @code{void __MADDACCS (acc, acc)}
15411 @tab @code{__MADDACCS (@var{b}, @var{a})}
15412 @tab @code{MADDACCS @var{a},@var{b}}
15413 @item @code{sw1 __MADDHSS (sw1, sw1)}
15414 @tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})}
15415 @tab @code{MADDHSS @var{a},@var{b},@var{c}}
15416 @item @code{uw1 __MADDHUS (uw1, uw1)}
15417 @tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})}
15418 @tab @code{MADDHUS @var{a},@var{b},@var{c}}
15419 @item @code{uw1 __MAND (uw1, uw1)}
15420 @tab @code{@var{c} = __MAND (@var{a}, @var{b})}
15421 @tab @code{MAND @var{a},@var{b},@var{c}}
15422 @item @code{void __MASACCS (acc, acc)}
15423 @tab @code{__MASACCS (@var{b}, @var{a})}
15424 @tab @code{MASACCS @var{a},@var{b}}
15425 @item @code{uw1 __MAVEH (uw1, uw1)}
15426 @tab @code{@var{c} = __MAVEH (@var{a}, @var{b})}
15427 @tab @code{MAVEH @var{a},@var{b},@var{c}}
15428 @item @code{uw2 __MBTOH (uw1)}
15429 @tab @code{@var{b} = __MBTOH (@var{a})}
15430 @tab @code{MBTOH @var{a},@var{b}}
15431 @item @code{void __MBTOHE (uw1 *, uw1)}
15432 @tab @code{__MBTOHE (&@var{b}, @var{a})}
15433 @tab @code{MBTOHE @var{a},@var{b}}
15434 @item @code{void __MCLRACC (acc)}
15435 @tab @code{__MCLRACC (@var{a})}
15436 @tab @code{MCLRACC @var{a}}
15437 @item @code{void __MCLRACCA (void)}
15438 @tab @code{__MCLRACCA ()}
15439 @tab @code{MCLRACCA}
15440 @item @code{uw1 __Mcop1 (uw1, uw1)}
15441 @tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})}
15442 @tab @code{Mcop1 @var{a},@var{b},@var{c}}
15443 @item @code{uw1 __Mcop2 (uw1, uw1)}
15444 @tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})}
15445 @tab @code{Mcop2 @var{a},@var{b},@var{c}}
15446 @item @code{uw1 __MCPLHI (uw2, const)}
15447 @tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})}
15448 @tab @code{MCPLHI @var{a},#@var{b},@var{c}}
15449 @item @code{uw1 __MCPLI (uw2, const)}
15450 @tab @code{@var{c} = __MCPLI (@var{a}, @var{b})}
15451 @tab @code{MCPLI @var{a},#@var{b},@var{c}}
15452 @item @code{void __MCPXIS (acc, sw1, sw1)}
15453 @tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})}
15454 @tab @code{MCPXIS @var{a},@var{b},@var{c}}
15455 @item @code{void __MCPXIU (acc, uw1, uw1)}
15456 @tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})}
15457 @tab @code{MCPXIU @var{a},@var{b},@var{c}}
15458 @item @code{void __MCPXRS (acc, sw1, sw1)}
15459 @tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})}
15460 @tab @code{MCPXRS @var{a},@var{b},@var{c}}
15461 @item @code{void __MCPXRU (acc, uw1, uw1)}
15462 @tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})}
15463 @tab @code{MCPXRU @var{a},@var{b},@var{c}}
15464 @item @code{uw1 __MCUT (acc, uw1)}
15465 @tab @code{@var{c} = __MCUT (@var{a}, @var{b})}
15466 @tab @code{MCUT @var{a},@var{b},@var{c}}
15467 @item @code{uw1 __MCUTSS (acc, sw1)}
15468 @tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})}
15469 @tab @code{MCUTSS @var{a},@var{b},@var{c}}
15470 @item @code{void __MDADDACCS (acc, acc)}
15471 @tab @code{__MDADDACCS (@var{b}, @var{a})}
15472 @tab @code{MDADDACCS @var{a},@var{b}}
15473 @item @code{void __MDASACCS (acc, acc)}
15474 @tab @code{__MDASACCS (@var{b}, @var{a})}
15475 @tab @code{MDASACCS @var{a},@var{b}}
15476 @item @code{uw2 __MDCUTSSI (acc, const)}
15477 @tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})}
15478 @tab @code{MDCUTSSI @var{a},#@var{b},@var{c}}
15479 @item @code{uw2 __MDPACKH (uw2, uw2)}
15480 @tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})}
15481 @tab @code{MDPACKH @var{a},@var{b},@var{c}}
15482 @item @code{uw2 __MDROTLI (uw2, const)}
15483 @tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})}
15484 @tab @code{MDROTLI @var{a},#@var{b},@var{c}}
15485 @item @code{void __MDSUBACCS (acc, acc)}
15486 @tab @code{__MDSUBACCS (@var{b}, @var{a})}
15487 @tab @code{MDSUBACCS @var{a},@var{b}}
15488 @item @code{void __MDUNPACKH (uw1 *, uw2)}
15489 @tab @code{__MDUNPACKH (&@var{b}, @var{a})}
15490 @tab @code{MDUNPACKH @var{a},@var{b}}
15491 @item @code{uw2 __MEXPDHD (uw1, const)}
15492 @tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})}
15493 @tab @code{MEXPDHD @var{a},#@var{b},@var{c}}
15494 @item @code{uw1 __MEXPDHW (uw1, const)}
15495 @tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})}
15496 @tab @code{MEXPDHW @var{a},#@var{b},@var{c}}
15497 @item @code{uw1 __MHDSETH (uw1, const)}
15498 @tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})}
15499 @tab @code{MHDSETH @var{a},#@var{b},@var{c}}
15500 @item @code{sw1 __MHDSETS (const)}
15501 @tab @code{@var{b} = __MHDSETS (@var{a})}
15502 @tab @code{MHDSETS #@var{a},@var{b}}
15503 @item @code{uw1 __MHSETHIH (uw1, const)}
15504 @tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})}
15505 @tab @code{MHSETHIH #@var{a},@var{b}}
15506 @item @code{sw1 __MHSETHIS (sw1, const)}
15507 @tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})}
15508 @tab @code{MHSETHIS #@var{a},@var{b}}
15509 @item @code{uw1 __MHSETLOH (uw1, const)}
15510 @tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})}
15511 @tab @code{MHSETLOH #@var{a},@var{b}}
15512 @item @code{sw1 __MHSETLOS (sw1, const)}
15513 @tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})}
15514 @tab @code{MHSETLOS #@var{a},@var{b}}
15515 @item @code{uw1 __MHTOB (uw2)}
15516 @tab @code{@var{b} = __MHTOB (@var{a})}
15517 @tab @code{MHTOB @var{a},@var{b}}
15518 @item @code{void __MMACHS (acc, sw1, sw1)}
15519 @tab @code{__MMACHS (@var{c}, @var{a}, @var{b})}
15520 @tab @code{MMACHS @var{a},@var{b},@var{c}}
15521 @item @code{void __MMACHU (acc, uw1, uw1)}
15522 @tab @code{__MMACHU (@var{c}, @var{a}, @var{b})}
15523 @tab @code{MMACHU @var{a},@var{b},@var{c}}
15524 @item @code{void __MMRDHS (acc, sw1, sw1)}
15525 @tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})}
15526 @tab @code{MMRDHS @var{a},@var{b},@var{c}}
15527 @item @code{void __MMRDHU (acc, uw1, uw1)}
15528 @tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})}
15529 @tab @code{MMRDHU @var{a},@var{b},@var{c}}
15530 @item @code{void __MMULHS (acc, sw1, sw1)}
15531 @tab @code{__MMULHS (@var{c}, @var{a}, @var{b})}
15532 @tab @code{MMULHS @var{a},@var{b},@var{c}}
15533 @item @code{void __MMULHU (acc, uw1, uw1)}
15534 @tab @code{__MMULHU (@var{c}, @var{a}, @var{b})}
15535 @tab @code{MMULHU @var{a},@var{b},@var{c}}
15536 @item @code{void __MMULXHS (acc, sw1, sw1)}
15537 @tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})}
15538 @tab @code{MMULXHS @var{a},@var{b},@var{c}}
15539 @item @code{void __MMULXHU (acc, uw1, uw1)}
15540 @tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})}
15541 @tab @code{MMULXHU @var{a},@var{b},@var{c}}
15542 @item @code{uw1 __MNOT (uw1)}
15543 @tab @code{@var{b} = __MNOT (@var{a})}
15544 @tab @code{MNOT @var{a},@var{b}}
15545 @item @code{uw1 __MOR (uw1, uw1)}
15546 @tab @code{@var{c} = __MOR (@var{a}, @var{b})}
15547 @tab @code{MOR @var{a},@var{b},@var{c}}
15548 @item @code{uw1 __MPACKH (uh, uh)}
15549 @tab @code{@var{c} = __MPACKH (@var{a}, @var{b})}
15550 @tab @code{MPACKH @var{a},@var{b},@var{c}}
15551 @item @code{sw2 __MQADDHSS (sw2, sw2)}
15552 @tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})}
15553 @tab @code{MQADDHSS @var{a},@var{b},@var{c}}
15554 @item @code{uw2 __MQADDHUS (uw2, uw2)}
15555 @tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})}
15556 @tab @code{MQADDHUS @var{a},@var{b},@var{c}}
15557 @item @code{void __MQCPXIS (acc, sw2, sw2)}
15558 @tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})}
15559 @tab @code{MQCPXIS @var{a},@var{b},@var{c}}
15560 @item @code{void __MQCPXIU (acc, uw2, uw2)}
15561 @tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})}
15562 @tab @code{MQCPXIU @var{a},@var{b},@var{c}}
15563 @item @code{void __MQCPXRS (acc, sw2, sw2)}
15564 @tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})}
15565 @tab @code{MQCPXRS @var{a},@var{b},@var{c}}
15566 @item @code{void __MQCPXRU (acc, uw2, uw2)}
15567 @tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})}
15568 @tab @code{MQCPXRU @var{a},@var{b},@var{c}}
15569 @item @code{sw2 __MQLCLRHS (sw2, sw2)}
15570 @tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})}
15571 @tab @code{MQLCLRHS @var{a},@var{b},@var{c}}
15572 @item @code{sw2 __MQLMTHS (sw2, sw2)}
15573 @tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})}
15574 @tab @code{MQLMTHS @var{a},@var{b},@var{c}}
15575 @item @code{void __MQMACHS (acc, sw2, sw2)}
15576 @tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})}
15577 @tab @code{MQMACHS @var{a},@var{b},@var{c}}
15578 @item @code{void __MQMACHU (acc, uw2, uw2)}
15579 @tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})}
15580 @tab @code{MQMACHU @var{a},@var{b},@var{c}}
15581 @item @code{void __MQMACXHS (acc, sw2, sw2)}
15582 @tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})}
15583 @tab @code{MQMACXHS @var{a},@var{b},@var{c}}
15584 @item @code{void __MQMULHS (acc, sw2, sw2)}
15585 @tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})}
15586 @tab @code{MQMULHS @var{a},@var{b},@var{c}}
15587 @item @code{void __MQMULHU (acc, uw2, uw2)}
15588 @tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})}
15589 @tab @code{MQMULHU @var{a},@var{b},@var{c}}
15590 @item @code{void __MQMULXHS (acc, sw2, sw2)}
15591 @tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})}
15592 @tab @code{MQMULXHS @var{a},@var{b},@var{c}}
15593 @item @code{void __MQMULXHU (acc, uw2, uw2)}
15594 @tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})}
15595 @tab @code{MQMULXHU @var{a},@var{b},@var{c}}
15596 @item @code{sw2 __MQSATHS (sw2, sw2)}
15597 @tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})}
15598 @tab @code{MQSATHS @var{a},@var{b},@var{c}}
15599 @item @code{uw2 __MQSLLHI (uw2, int)}
15600 @tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})}
15601 @tab @code{MQSLLHI @var{a},@var{b},@var{c}}
15602 @item @code{sw2 __MQSRAHI (sw2, int)}
15603 @tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})}
15604 @tab @code{MQSRAHI @var{a},@var{b},@var{c}}
15605 @item @code{sw2 __MQSUBHSS (sw2, sw2)}
15606 @tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})}
15607 @tab @code{MQSUBHSS @var{a},@var{b},@var{c}}
15608 @item @code{uw2 __MQSUBHUS (uw2, uw2)}
15609 @tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})}
15610 @tab @code{MQSUBHUS @var{a},@var{b},@var{c}}
15611 @item @code{void __MQXMACHS (acc, sw2, sw2)}
15612 @tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})}
15613 @tab @code{MQXMACHS @var{a},@var{b},@var{c}}
15614 @item @code{void __MQXMACXHS (acc, sw2, sw2)}
15615 @tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})}
15616 @tab @code{MQXMACXHS @var{a},@var{b},@var{c}}
15617 @item @code{uw1 __MRDACC (acc)}
15618 @tab @code{@var{b} = __MRDACC (@var{a})}
15619 @tab @code{MRDACC @var{a},@var{b}}
15620 @item @code{uw1 __MRDACCG (acc)}
15621 @tab @code{@var{b} = __MRDACCG (@var{a})}
15622 @tab @code{MRDACCG @var{a},@var{b}}
15623 @item @code{uw1 __MROTLI (uw1, const)}
15624 @tab @code{@var{c} = __MROTLI (@var{a}, @var{b})}
15625 @tab @code{MROTLI @var{a},#@var{b},@var{c}}
15626 @item @code{uw1 __MROTRI (uw1, const)}
15627 @tab @code{@var{c} = __MROTRI (@var{a}, @var{b})}
15628 @tab @code{MROTRI @var{a},#@var{b},@var{c}}
15629 @item @code{sw1 __MSATHS (sw1, sw1)}
15630 @tab @code{@var{c} = __MSATHS (@var{a}, @var{b})}
15631 @tab @code{MSATHS @var{a},@var{b},@var{c}}
15632 @item @code{uw1 __MSATHU (uw1, uw1)}
15633 @tab @code{@var{c} = __MSATHU (@var{a}, @var{b})}
15634 @tab @code{MSATHU @var{a},@var{b},@var{c}}
15635 @item @code{uw1 __MSLLHI (uw1, const)}
15636 @tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})}
15637 @tab @code{MSLLHI @var{a},#@var{b},@var{c}}
15638 @item @code{sw1 __MSRAHI (sw1, const)}
15639 @tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})}
15640 @tab @code{MSRAHI @var{a},#@var{b},@var{c}}
15641 @item @code{uw1 __MSRLHI (uw1, const)}
15642 @tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})}
15643 @tab @code{MSRLHI @var{a},#@var{b},@var{c}}
15644 @item @code{void __MSUBACCS (acc, acc)}
15645 @tab @code{__MSUBACCS (@var{b}, @var{a})}
15646 @tab @code{MSUBACCS @var{a},@var{b}}
15647 @item @code{sw1 __MSUBHSS (sw1, sw1)}
15648 @tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})}
15649 @tab @code{MSUBHSS @var{a},@var{b},@var{c}}
15650 @item @code{uw1 __MSUBHUS (uw1, uw1)}
15651 @tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})}
15652 @tab @code{MSUBHUS @var{a},@var{b},@var{c}}
15653 @item @code{void __MTRAP (void)}
15654 @tab @code{__MTRAP ()}
15656 @item @code{uw2 __MUNPACKH (uw1)}
15657 @tab @code{@var{b} = __MUNPACKH (@var{a})}
15658 @tab @code{MUNPACKH @var{a},@var{b}}
15659 @item @code{uw1 __MWCUT (uw2, uw1)}
15660 @tab @code{@var{c} = __MWCUT (@var{a}, @var{b})}
15661 @tab @code{MWCUT @var{a},@var{b},@var{c}}
15662 @item @code{void __MWTACC (acc, uw1)}
15663 @tab @code{__MWTACC (@var{b}, @var{a})}
15664 @tab @code{MWTACC @var{a},@var{b}}
15665 @item @code{void __MWTACCG (acc, uw1)}
15666 @tab @code{__MWTACCG (@var{b}, @var{a})}
15667 @tab @code{MWTACCG @var{a},@var{b}}
15668 @item @code{uw1 __MXOR (uw1, uw1)}
15669 @tab @code{@var{c} = __MXOR (@var{a}, @var{b})}
15670 @tab @code{MXOR @var{a},@var{b},@var{c}}
15673 @node Raw read/write Functions
15674 @subsubsection Raw Read/Write Functions
15676 This sections describes built-in functions related to read and write
15677 instructions to access memory. These functions generate
15678 @code{membar} instructions to flush the I/O load and stores where
15679 appropriate, as described in Fujitsu's manual described above.
15683 @item unsigned char __builtin_read8 (void *@var{data})
15684 @item unsigned short __builtin_read16 (void *@var{data})
15685 @item unsigned long __builtin_read32 (void *@var{data})
15686 @item unsigned long long __builtin_read64 (void *@var{data})
15688 @item void __builtin_write8 (void *@var{data}, unsigned char @var{datum})
15689 @item void __builtin_write16 (void *@var{data}, unsigned short @var{datum})
15690 @item void __builtin_write32 (void *@var{data}, unsigned long @var{datum})
15691 @item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum})
15694 @node Other Built-in Functions
15695 @subsubsection Other Built-in Functions
15697 This section describes built-in functions that are not named after
15698 a specific FR-V instruction.
15701 @item sw2 __IACCreadll (iacc @var{reg})
15702 Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved
15703 for future expansion and must be 0.
15705 @item sw1 __IACCreadl (iacc @var{reg})
15706 Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1.
15707 Other values of @var{reg} are rejected as invalid.
15709 @item void __IACCsetll (iacc @var{reg}, sw2 @var{x})
15710 Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument
15711 is reserved for future expansion and must be 0.
15713 @item void __IACCsetl (iacc @var{reg}, sw1 @var{x})
15714 Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg}
15715 is 1. Other values of @var{reg} are rejected as invalid.
15717 @item void __data_prefetch0 (const void *@var{x})
15718 Use the @code{dcpl} instruction to load the contents of address @var{x}
15719 into the data cache.
15721 @item void __data_prefetch (const void *@var{x})
15722 Use the @code{nldub} instruction to load the contents of address @var{x}
15723 into the data cache. The instruction is issued in slot I1@.
15726 @node MIPS DSP Built-in Functions
15727 @subsection MIPS DSP Built-in Functions
15729 The MIPS DSP Application-Specific Extension (ASE) includes new
15730 instructions that are designed to improve the performance of DSP and
15731 media applications. It provides instructions that operate on packed
15732 8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data.
15734 GCC supports MIPS DSP operations using both the generic
15735 vector extensions (@pxref{Vector Extensions}) and a collection of
15736 MIPS-specific built-in functions. Both kinds of support are
15737 enabled by the @option{-mdsp} command-line option.
15739 Revision 2 of the ASE was introduced in the second half of 2006.
15740 This revision adds extra instructions to the original ASE, but is
15741 otherwise backwards-compatible with it. You can select revision 2
15742 using the command-line option @option{-mdspr2}; this option implies
15745 The SCOUNT and POS bits of the DSP control register are global. The
15746 WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and
15747 POS bits. During optimization, the compiler does not delete these
15748 instructions and it does not delete calls to functions containing
15749 these instructions.
15751 At present, GCC only provides support for operations on 32-bit
15752 vectors. The vector type associated with 8-bit integer data is
15753 usually called @code{v4i8}, the vector type associated with Q7
15754 is usually called @code{v4q7}, the vector type associated with 16-bit
15755 integer data is usually called @code{v2i16}, and the vector type
15756 associated with Q15 is usually called @code{v2q15}. They can be
15757 defined in C as follows:
15760 typedef signed char v4i8 __attribute__ ((vector_size(4)));
15761 typedef signed char v4q7 __attribute__ ((vector_size(4)));
15762 typedef short v2i16 __attribute__ ((vector_size(4)));
15763 typedef short v2q15 __attribute__ ((vector_size(4)));
15766 @code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are
15767 initialized in the same way as aggregates. For example:
15770 v4i8 a = @{1, 2, 3, 4@};
15772 b = (v4i8) @{5, 6, 7, 8@};
15774 v2q15 c = @{0x0fcb, 0x3a75@};
15776 d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@};
15779 @emph{Note:} The CPU's endianness determines the order in which values
15780 are packed. On little-endian targets, the first value is the least
15781 significant and the last value is the most significant. The opposite
15782 order applies to big-endian targets. For example, the code above
15783 sets the lowest byte of @code{a} to @code{1} on little-endian targets
15784 and @code{4} on big-endian targets.
15786 @emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer
15787 representation. As shown in this example, the integer representation
15788 of a Q7 value can be obtained by multiplying the fractional value by
15789 @code{0x1.0p7}. The equivalent for Q15 values is to multiply by
15790 @code{0x1.0p15}. The equivalent for Q31 values is to multiply by
15793 The table below lists the @code{v4i8} and @code{v2q15} operations for which
15794 hardware support exists. @code{a} and @code{b} are @code{v4i8} values,
15795 and @code{c} and @code{d} are @code{v2q15} values.
15797 @multitable @columnfractions .50 .50
15798 @item C code @tab MIPS instruction
15799 @item @code{a + b} @tab @code{addu.qb}
15800 @item @code{c + d} @tab @code{addq.ph}
15801 @item @code{a - b} @tab @code{subu.qb}
15802 @item @code{c - d} @tab @code{subq.ph}
15805 The table below lists the @code{v2i16} operation for which
15806 hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are
15807 @code{v2i16} values.
15809 @multitable @columnfractions .50 .50
15810 @item C code @tab MIPS instruction
15811 @item @code{e * f} @tab @code{mul.ph}
15814 It is easier to describe the DSP built-in functions if we first define
15815 the following types:
15820 typedef unsigned int ui32;
15821 typedef long long a64;
15824 @code{q31} and @code{i32} are actually the same as @code{int}, but we
15825 use @code{q31} to indicate a Q31 fractional value and @code{i32} to
15826 indicate a 32-bit integer value. Similarly, @code{a64} is the same as
15827 @code{long long}, but we use @code{a64} to indicate values that are
15828 placed in one of the four DSP accumulators (@code{$ac0},
15829 @code{$ac1}, @code{$ac2} or @code{$ac3}).
15831 Also, some built-in functions prefer or require immediate numbers as
15832 parameters, because the corresponding DSP instructions accept both immediate
15833 numbers and register operands, or accept immediate numbers only. The
15834 immediate parameters are listed as follows.
15842 imm0_255: 0 to 255.
15843 imm_n32_31: -32 to 31.
15844 imm_n512_511: -512 to 511.
15847 The following built-in functions map directly to a particular MIPS DSP
15848 instruction. Please refer to the architecture specification
15849 for details on what each instruction does.
15852 v2q15 __builtin_mips_addq_ph (v2q15, v2q15)
15853 v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15)
15854 q31 __builtin_mips_addq_s_w (q31, q31)
15855 v4i8 __builtin_mips_addu_qb (v4i8, v4i8)
15856 v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8)
15857 v2q15 __builtin_mips_subq_ph (v2q15, v2q15)
15858 v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15)
15859 q31 __builtin_mips_subq_s_w (q31, q31)
15860 v4i8 __builtin_mips_subu_qb (v4i8, v4i8)
15861 v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8)
15862 i32 __builtin_mips_addsc (i32, i32)
15863 i32 __builtin_mips_addwc (i32, i32)
15864 i32 __builtin_mips_modsub (i32, i32)
15865 i32 __builtin_mips_raddu_w_qb (v4i8)
15866 v2q15 __builtin_mips_absq_s_ph (v2q15)
15867 q31 __builtin_mips_absq_s_w (q31)
15868 v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15)
15869 v2q15 __builtin_mips_precrq_ph_w (q31, q31)
15870 v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31)
15871 v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15)
15872 q31 __builtin_mips_preceq_w_phl (v2q15)
15873 q31 __builtin_mips_preceq_w_phr (v2q15)
15874 v2q15 __builtin_mips_precequ_ph_qbl (v4i8)
15875 v2q15 __builtin_mips_precequ_ph_qbr (v4i8)
15876 v2q15 __builtin_mips_precequ_ph_qbla (v4i8)
15877 v2q15 __builtin_mips_precequ_ph_qbra (v4i8)
15878 v2q15 __builtin_mips_preceu_ph_qbl (v4i8)
15879 v2q15 __builtin_mips_preceu_ph_qbr (v4i8)
15880 v2q15 __builtin_mips_preceu_ph_qbla (v4i8)
15881 v2q15 __builtin_mips_preceu_ph_qbra (v4i8)
15882 v4i8 __builtin_mips_shll_qb (v4i8, imm0_7)
15883 v4i8 __builtin_mips_shll_qb (v4i8, i32)
15884 v2q15 __builtin_mips_shll_ph (v2q15, imm0_15)
15885 v2q15 __builtin_mips_shll_ph (v2q15, i32)
15886 v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15)
15887 v2q15 __builtin_mips_shll_s_ph (v2q15, i32)
15888 q31 __builtin_mips_shll_s_w (q31, imm0_31)
15889 q31 __builtin_mips_shll_s_w (q31, i32)
15890 v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7)
15891 v4i8 __builtin_mips_shrl_qb (v4i8, i32)
15892 v2q15 __builtin_mips_shra_ph (v2q15, imm0_15)
15893 v2q15 __builtin_mips_shra_ph (v2q15, i32)
15894 v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15)
15895 v2q15 __builtin_mips_shra_r_ph (v2q15, i32)
15896 q31 __builtin_mips_shra_r_w (q31, imm0_31)
15897 q31 __builtin_mips_shra_r_w (q31, i32)
15898 v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15)
15899 v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15)
15900 v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15)
15901 q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15)
15902 q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15)
15903 a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8)
15904 a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8)
15905 a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8)
15906 a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8)
15907 a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15)
15908 a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31)
15909 a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15)
15910 a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31)
15911 a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15)
15912 a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15)
15913 a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15)
15914 a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15)
15915 a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15)
15916 i32 __builtin_mips_bitrev (i32)
15917 i32 __builtin_mips_insv (i32, i32)
15918 v4i8 __builtin_mips_repl_qb (imm0_255)
15919 v4i8 __builtin_mips_repl_qb (i32)
15920 v2q15 __builtin_mips_repl_ph (imm_n512_511)
15921 v2q15 __builtin_mips_repl_ph (i32)
15922 void __builtin_mips_cmpu_eq_qb (v4i8, v4i8)
15923 void __builtin_mips_cmpu_lt_qb (v4i8, v4i8)
15924 void __builtin_mips_cmpu_le_qb (v4i8, v4i8)
15925 i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8)
15926 i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8)
15927 i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8)
15928 void __builtin_mips_cmp_eq_ph (v2q15, v2q15)
15929 void __builtin_mips_cmp_lt_ph (v2q15, v2q15)
15930 void __builtin_mips_cmp_le_ph (v2q15, v2q15)
15931 v4i8 __builtin_mips_pick_qb (v4i8, v4i8)
15932 v2q15 __builtin_mips_pick_ph (v2q15, v2q15)
15933 v2q15 __builtin_mips_packrl_ph (v2q15, v2q15)
15934 i32 __builtin_mips_extr_w (a64, imm0_31)
15935 i32 __builtin_mips_extr_w (a64, i32)
15936 i32 __builtin_mips_extr_r_w (a64, imm0_31)
15937 i32 __builtin_mips_extr_s_h (a64, i32)
15938 i32 __builtin_mips_extr_rs_w (a64, imm0_31)
15939 i32 __builtin_mips_extr_rs_w (a64, i32)
15940 i32 __builtin_mips_extr_s_h (a64, imm0_31)
15941 i32 __builtin_mips_extr_r_w (a64, i32)
15942 i32 __builtin_mips_extp (a64, imm0_31)
15943 i32 __builtin_mips_extp (a64, i32)
15944 i32 __builtin_mips_extpdp (a64, imm0_31)
15945 i32 __builtin_mips_extpdp (a64, i32)
15946 a64 __builtin_mips_shilo (a64, imm_n32_31)
15947 a64 __builtin_mips_shilo (a64, i32)
15948 a64 __builtin_mips_mthlip (a64, i32)
15949 void __builtin_mips_wrdsp (i32, imm0_63)
15950 i32 __builtin_mips_rddsp (imm0_63)
15951 i32 __builtin_mips_lbux (void *, i32)
15952 i32 __builtin_mips_lhx (void *, i32)
15953 i32 __builtin_mips_lwx (void *, i32)
15954 a64 __builtin_mips_ldx (void *, i32) [MIPS64 only]
15955 i32 __builtin_mips_bposge32 (void)
15956 a64 __builtin_mips_madd (a64, i32, i32);
15957 a64 __builtin_mips_maddu (a64, ui32, ui32);
15958 a64 __builtin_mips_msub (a64, i32, i32);
15959 a64 __builtin_mips_msubu (a64, ui32, ui32);
15960 a64 __builtin_mips_mult (i32, i32);
15961 a64 __builtin_mips_multu (ui32, ui32);
15964 The following built-in functions map directly to a particular MIPS DSP REV 2
15965 instruction. Please refer to the architecture specification
15966 for details on what each instruction does.
15969 v4q7 __builtin_mips_absq_s_qb (v4q7);
15970 v2i16 __builtin_mips_addu_ph (v2i16, v2i16);
15971 v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16);
15972 v4i8 __builtin_mips_adduh_qb (v4i8, v4i8);
15973 v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8);
15974 i32 __builtin_mips_append (i32, i32, imm0_31);
15975 i32 __builtin_mips_balign (i32, i32, imm0_3);
15976 i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8);
15977 i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8);
15978 i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8);
15979 a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16);
15980 a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16);
15981 v2i16 __builtin_mips_mul_ph (v2i16, v2i16);
15982 v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16);
15983 q31 __builtin_mips_mulq_rs_w (q31, q31);
15984 v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15);
15985 q31 __builtin_mips_mulq_s_w (q31, q31);
15986 a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16);
15987 v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16);
15988 v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31);
15989 v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31);
15990 i32 __builtin_mips_prepend (i32, i32, imm0_31);
15991 v4i8 __builtin_mips_shra_qb (v4i8, imm0_7);
15992 v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7);
15993 v4i8 __builtin_mips_shra_qb (v4i8, i32);
15994 v4i8 __builtin_mips_shra_r_qb (v4i8, i32);
15995 v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15);
15996 v2i16 __builtin_mips_shrl_ph (v2i16, i32);
15997 v2i16 __builtin_mips_subu_ph (v2i16, v2i16);
15998 v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16);
15999 v4i8 __builtin_mips_subuh_qb (v4i8, v4i8);
16000 v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8);
16001 v2q15 __builtin_mips_addqh_ph (v2q15, v2q15);
16002 v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15);
16003 q31 __builtin_mips_addqh_w (q31, q31);
16004 q31 __builtin_mips_addqh_r_w (q31, q31);
16005 v2q15 __builtin_mips_subqh_ph (v2q15, v2q15);
16006 v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15);
16007 q31 __builtin_mips_subqh_w (q31, q31);
16008 q31 __builtin_mips_subqh_r_w (q31, q31);
16009 a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16);
16010 a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16);
16011 a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15);
16012 a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15);
16013 a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15);
16014 a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15);
16018 @node MIPS Paired-Single Support
16019 @subsection MIPS Paired-Single Support
16021 The MIPS64 architecture includes a number of instructions that
16022 operate on pairs of single-precision floating-point values.
16023 Each pair is packed into a 64-bit floating-point register,
16024 with one element being designated the ``upper half'' and
16025 the other being designated the ``lower half''.
16027 GCC supports paired-single operations using both the generic
16028 vector extensions (@pxref{Vector Extensions}) and a collection of
16029 MIPS-specific built-in functions. Both kinds of support are
16030 enabled by the @option{-mpaired-single} command-line option.
16032 The vector type associated with paired-single values is usually
16033 called @code{v2sf}. It can be defined in C as follows:
16036 typedef float v2sf __attribute__ ((vector_size (8)));
16039 @code{v2sf} values are initialized in the same way as aggregates.
16043 v2sf a = @{1.5, 9.1@};
16046 b = (v2sf) @{e, f@};
16049 @emph{Note:} The CPU's endianness determines which value is stored in
16050 the upper half of a register and which value is stored in the lower half.
16051 On little-endian targets, the first value is the lower one and the second
16052 value is the upper one. The opposite order applies to big-endian targets.
16053 For example, the code above sets the lower half of @code{a} to
16054 @code{1.5} on little-endian targets and @code{9.1} on big-endian targets.
16056 @node MIPS Loongson Built-in Functions
16057 @subsection MIPS Loongson Built-in Functions
16059 GCC provides intrinsics to access the SIMD instructions provided by the
16060 ST Microelectronics Loongson-2E and -2F processors. These intrinsics,
16061 available after inclusion of the @code{loongson.h} header file,
16062 operate on the following 64-bit vector types:
16065 @item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers;
16066 @item @code{uint16x4_t}, a vector of four unsigned 16-bit integers;
16067 @item @code{uint32x2_t}, a vector of two unsigned 32-bit integers;
16068 @item @code{int8x8_t}, a vector of eight signed 8-bit integers;
16069 @item @code{int16x4_t}, a vector of four signed 16-bit integers;
16070 @item @code{int32x2_t}, a vector of two signed 32-bit integers.
16073 The intrinsics provided are listed below; each is named after the
16074 machine instruction to which it corresponds, with suffixes added as
16075 appropriate to distinguish intrinsics that expand to the same machine
16076 instruction yet have different argument types. Refer to the architecture
16077 documentation for a description of the functionality of each
16081 int16x4_t packsswh (int32x2_t s, int32x2_t t);
16082 int8x8_t packsshb (int16x4_t s, int16x4_t t);
16083 uint8x8_t packushb (uint16x4_t s, uint16x4_t t);
16084 uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t);
16085 uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t);
16086 uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t);
16087 int32x2_t paddw_s (int32x2_t s, int32x2_t t);
16088 int16x4_t paddh_s (int16x4_t s, int16x4_t t);
16089 int8x8_t paddb_s (int8x8_t s, int8x8_t t);
16090 uint64_t paddd_u (uint64_t s, uint64_t t);
16091 int64_t paddd_s (int64_t s, int64_t t);
16092 int16x4_t paddsh (int16x4_t s, int16x4_t t);
16093 int8x8_t paddsb (int8x8_t s, int8x8_t t);
16094 uint16x4_t paddush (uint16x4_t s, uint16x4_t t);
16095 uint8x8_t paddusb (uint8x8_t s, uint8x8_t t);
16096 uint64_t pandn_ud (uint64_t s, uint64_t t);
16097 uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t);
16098 uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t);
16099 uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t);
16100 int64_t pandn_sd (int64_t s, int64_t t);
16101 int32x2_t pandn_sw (int32x2_t s, int32x2_t t);
16102 int16x4_t pandn_sh (int16x4_t s, int16x4_t t);
16103 int8x8_t pandn_sb (int8x8_t s, int8x8_t t);
16104 uint16x4_t pavgh (uint16x4_t s, uint16x4_t t);
16105 uint8x8_t pavgb (uint8x8_t s, uint8x8_t t);
16106 uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t);
16107 uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t);
16108 uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t);
16109 int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t);
16110 int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t);
16111 int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t);
16112 uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t);
16113 uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t);
16114 uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t);
16115 int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t);
16116 int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t);
16117 int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t);
16118 uint16x4_t pextrh_u (uint16x4_t s, int field);
16119 int16x4_t pextrh_s (int16x4_t s, int field);
16120 uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t);
16121 uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t);
16122 uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t);
16123 uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t);
16124 int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t);
16125 int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t);
16126 int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t);
16127 int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t);
16128 int32x2_t pmaddhw (int16x4_t s, int16x4_t t);
16129 int16x4_t pmaxsh (int16x4_t s, int16x4_t t);
16130 uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t);
16131 int16x4_t pminsh (int16x4_t s, int16x4_t t);
16132 uint8x8_t pminub (uint8x8_t s, uint8x8_t t);
16133 uint8x8_t pmovmskb_u (uint8x8_t s);
16134 int8x8_t pmovmskb_s (int8x8_t s);
16135 uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t);
16136 int16x4_t pmulhh (int16x4_t s, int16x4_t t);
16137 int16x4_t pmullh (int16x4_t s, int16x4_t t);
16138 int64_t pmuluw (uint32x2_t s, uint32x2_t t);
16139 uint8x8_t pasubub (uint8x8_t s, uint8x8_t t);
16140 uint16x4_t biadd (uint8x8_t s);
16141 uint16x4_t psadbh (uint8x8_t s, uint8x8_t t);
16142 uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order);
16143 int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order);
16144 uint16x4_t psllh_u (uint16x4_t s, uint8_t amount);
16145 int16x4_t psllh_s (int16x4_t s, uint8_t amount);
16146 uint32x2_t psllw_u (uint32x2_t s, uint8_t amount);
16147 int32x2_t psllw_s (int32x2_t s, uint8_t amount);
16148 uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount);
16149 int16x4_t psrlh_s (int16x4_t s, uint8_t amount);
16150 uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount);
16151 int32x2_t psrlw_s (int32x2_t s, uint8_t amount);
16152 uint16x4_t psrah_u (uint16x4_t s, uint8_t amount);
16153 int16x4_t psrah_s (int16x4_t s, uint8_t amount);
16154 uint32x2_t psraw_u (uint32x2_t s, uint8_t amount);
16155 int32x2_t psraw_s (int32x2_t s, uint8_t amount);
16156 uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t);
16157 uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t);
16158 uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t);
16159 int32x2_t psubw_s (int32x2_t s, int32x2_t t);
16160 int16x4_t psubh_s (int16x4_t s, int16x4_t t);
16161 int8x8_t psubb_s (int8x8_t s, int8x8_t t);
16162 uint64_t psubd_u (uint64_t s, uint64_t t);
16163 int64_t psubd_s (int64_t s, int64_t t);
16164 int16x4_t psubsh (int16x4_t s, int16x4_t t);
16165 int8x8_t psubsb (int8x8_t s, int8x8_t t);
16166 uint16x4_t psubush (uint16x4_t s, uint16x4_t t);
16167 uint8x8_t psubusb (uint8x8_t s, uint8x8_t t);
16168 uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t);
16169 uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t);
16170 uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t);
16171 int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t);
16172 int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t);
16173 int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t);
16174 uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t);
16175 uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t);
16176 uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t);
16177 int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t);
16178 int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t);
16179 int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t);
16183 * Paired-Single Arithmetic::
16184 * Paired-Single Built-in Functions::
16185 * MIPS-3D Built-in Functions::
16188 @node Paired-Single Arithmetic
16189 @subsubsection Paired-Single Arithmetic
16191 The table below lists the @code{v2sf} operations for which hardware
16192 support exists. @code{a}, @code{b} and @code{c} are @code{v2sf}
16193 values and @code{x} is an integral value.
16195 @multitable @columnfractions .50 .50
16196 @item C code @tab MIPS instruction
16197 @item @code{a + b} @tab @code{add.ps}
16198 @item @code{a - b} @tab @code{sub.ps}
16199 @item @code{-a} @tab @code{neg.ps}
16200 @item @code{a * b} @tab @code{mul.ps}
16201 @item @code{a * b + c} @tab @code{madd.ps}
16202 @item @code{a * b - c} @tab @code{msub.ps}
16203 @item @code{-(a * b + c)} @tab @code{nmadd.ps}
16204 @item @code{-(a * b - c)} @tab @code{nmsub.ps}
16205 @item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps}
16208 Note that the multiply-accumulate instructions can be disabled
16209 using the command-line option @code{-mno-fused-madd}.
16211 @node Paired-Single Built-in Functions
16212 @subsubsection Paired-Single Built-in Functions
16214 The following paired-single functions map directly to a particular
16215 MIPS instruction. Please refer to the architecture specification
16216 for details on what each instruction does.
16219 @item v2sf __builtin_mips_pll_ps (v2sf, v2sf)
16220 Pair lower lower (@code{pll.ps}).
16222 @item v2sf __builtin_mips_pul_ps (v2sf, v2sf)
16223 Pair upper lower (@code{pul.ps}).
16225 @item v2sf __builtin_mips_plu_ps (v2sf, v2sf)
16226 Pair lower upper (@code{plu.ps}).
16228 @item v2sf __builtin_mips_puu_ps (v2sf, v2sf)
16229 Pair upper upper (@code{puu.ps}).
16231 @item v2sf __builtin_mips_cvt_ps_s (float, float)
16232 Convert pair to paired single (@code{cvt.ps.s}).
16234 @item float __builtin_mips_cvt_s_pl (v2sf)
16235 Convert pair lower to single (@code{cvt.s.pl}).
16237 @item float __builtin_mips_cvt_s_pu (v2sf)
16238 Convert pair upper to single (@code{cvt.s.pu}).
16240 @item v2sf __builtin_mips_abs_ps (v2sf)
16241 Absolute value (@code{abs.ps}).
16243 @item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int)
16244 Align variable (@code{alnv.ps}).
16246 @emph{Note:} The value of the third parameter must be 0 or 4
16247 modulo 8, otherwise the result is unpredictable. Please read the
16248 instruction description for details.
16251 The following multi-instruction functions are also available.
16252 In each case, @var{cond} can be any of the 16 floating-point conditions:
16253 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
16254 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl},
16255 @code{lt}, @code{nge}, @code{le} or @code{ngt}.
16258 @item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16259 @itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16260 Conditional move based on floating-point comparison (@code{c.@var{cond}.ps},
16261 @code{movt.ps}/@code{movf.ps}).
16263 The @code{movt} functions return the value @var{x} computed by:
16266 c.@var{cond}.ps @var{cc},@var{a},@var{b}
16267 mov.ps @var{x},@var{c}
16268 movt.ps @var{x},@var{d},@var{cc}
16271 The @code{movf} functions are similar but use @code{movf.ps} instead
16274 @item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16275 @itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16276 Comparison of two paired-single values (@code{c.@var{cond}.ps},
16277 @code{bc1t}/@code{bc1f}).
16279 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
16280 and return either the upper or lower half of the result. For example:
16284 if (__builtin_mips_upper_c_eq_ps (a, b))
16285 upper_halves_are_equal ();
16287 upper_halves_are_unequal ();
16289 if (__builtin_mips_lower_c_eq_ps (a, b))
16290 lower_halves_are_equal ();
16292 lower_halves_are_unequal ();
16296 @node MIPS-3D Built-in Functions
16297 @subsubsection MIPS-3D Built-in Functions
16299 The MIPS-3D Application-Specific Extension (ASE) includes additional
16300 paired-single instructions that are designed to improve the performance
16301 of 3D graphics operations. Support for these instructions is controlled
16302 by the @option{-mips3d} command-line option.
16304 The functions listed below map directly to a particular MIPS-3D
16305 instruction. Please refer to the architecture specification for
16306 more details on what each instruction does.
16309 @item v2sf __builtin_mips_addr_ps (v2sf, v2sf)
16310 Reduction add (@code{addr.ps}).
16312 @item v2sf __builtin_mips_mulr_ps (v2sf, v2sf)
16313 Reduction multiply (@code{mulr.ps}).
16315 @item v2sf __builtin_mips_cvt_pw_ps (v2sf)
16316 Convert paired single to paired word (@code{cvt.pw.ps}).
16318 @item v2sf __builtin_mips_cvt_ps_pw (v2sf)
16319 Convert paired word to paired single (@code{cvt.ps.pw}).
16321 @item float __builtin_mips_recip1_s (float)
16322 @itemx double __builtin_mips_recip1_d (double)
16323 @itemx v2sf __builtin_mips_recip1_ps (v2sf)
16324 Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}).
16326 @item float __builtin_mips_recip2_s (float, float)
16327 @itemx double __builtin_mips_recip2_d (double, double)
16328 @itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf)
16329 Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}).
16331 @item float __builtin_mips_rsqrt1_s (float)
16332 @itemx double __builtin_mips_rsqrt1_d (double)
16333 @itemx v2sf __builtin_mips_rsqrt1_ps (v2sf)
16334 Reduced-precision reciprocal square root (sequence step 1)
16335 (@code{rsqrt1.@var{fmt}}).
16337 @item float __builtin_mips_rsqrt2_s (float, float)
16338 @itemx double __builtin_mips_rsqrt2_d (double, double)
16339 @itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf)
16340 Reduced-precision reciprocal square root (sequence step 2)
16341 (@code{rsqrt2.@var{fmt}}).
16344 The following multi-instruction functions are also available.
16345 In each case, @var{cond} can be any of the 16 floating-point conditions:
16346 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
16347 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq},
16348 @code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}.
16351 @item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b})
16352 @itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b})
16353 Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}},
16354 @code{bc1t}/@code{bc1f}).
16356 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s}
16357 or @code{cabs.@var{cond}.d} and return the result as a boolean value.
16362 if (__builtin_mips_cabs_eq_s (a, b))
16368 @item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16369 @itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16370 Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps},
16371 @code{bc1t}/@code{bc1f}).
16373 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps}
16374 and return either the upper or lower half of the result. For example:
16378 if (__builtin_mips_upper_cabs_eq_ps (a, b))
16379 upper_halves_are_equal ();
16381 upper_halves_are_unequal ();
16383 if (__builtin_mips_lower_cabs_eq_ps (a, b))
16384 lower_halves_are_equal ();
16386 lower_halves_are_unequal ();
16389 @item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16390 @itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16391 Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps},
16392 @code{movt.ps}/@code{movf.ps}).
16394 The @code{movt} functions return the value @var{x} computed by:
16397 cabs.@var{cond}.ps @var{cc},@var{a},@var{b}
16398 mov.ps @var{x},@var{c}
16399 movt.ps @var{x},@var{d},@var{cc}
16402 The @code{movf} functions are similar but use @code{movf.ps} instead
16405 @item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16406 @itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16407 @itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16408 @itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16409 Comparison of two paired-single values
16410 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
16411 @code{bc1any2t}/@code{bc1any2f}).
16413 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
16414 or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either
16415 result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}.
16420 if (__builtin_mips_any_c_eq_ps (a, b))
16425 if (__builtin_mips_all_c_eq_ps (a, b))
16431 @item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16432 @itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16433 @itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16434 @itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16435 Comparison of four paired-single values
16436 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
16437 @code{bc1any4t}/@code{bc1any4f}).
16439 These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps}
16440 to compare @var{a} with @var{b} and to compare @var{c} with @var{d}.
16441 The @code{any} forms return @code{true} if any of the four results are @code{true}
16442 and the @code{all} forms return @code{true} if all four results are @code{true}.
16447 if (__builtin_mips_any_c_eq_4s (a, b, c, d))
16452 if (__builtin_mips_all_c_eq_4s (a, b, c, d))
16459 @node MIPS SIMD Architecture (MSA) Support
16460 @subsection MIPS SIMD Architecture (MSA) Support
16463 * MIPS SIMD Architecture Built-in Functions::
16466 GCC provides intrinsics to access the SIMD instructions provided by the
16467 MSA MIPS SIMD Architecture. The interface is made available by including
16468 @code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}.
16469 For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic,
16472 MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and
16473 64-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point
16474 data elements. The following vectors typedefs are included in @code{msa.h}:
16476 @item @code{v16i8}, a vector of sixteen signed 8-bit integers;
16477 @item @code{v16u8}, a vector of sixteen unsigned 8-bit integers;
16478 @item @code{v8i16}, a vector of eight signed 16-bit integers;
16479 @item @code{v8u16}, a vector of eight unsigned 16-bit integers;
16480 @item @code{v4i32}, a vector of four signed 32-bit integers;
16481 @item @code{v4u32}, a vector of four unsigned 32-bit integers;
16482 @item @code{v2i64}, a vector of two signed 64-bit integers;
16483 @item @code{v2u64}, a vector of two unsigned 64-bit integers;
16484 @item @code{v4f32}, a vector of four 32-bit floats;
16485 @item @code{v2f64}, a vector of two 64-bit doubles.
16488 Instructions and corresponding built-ins may have additional restrictions and/or
16489 input/output values manipulated:
16491 @item @code{imm0_1}, an integer literal in range 0 to 1;
16492 @item @code{imm0_3}, an integer literal in range 0 to 3;
16493 @item @code{imm0_7}, an integer literal in range 0 to 7;
16494 @item @code{imm0_15}, an integer literal in range 0 to 15;
16495 @item @code{imm0_31}, an integer literal in range 0 to 31;
16496 @item @code{imm0_63}, an integer literal in range 0 to 63;
16497 @item @code{imm0_255}, an integer literal in range 0 to 255;
16498 @item @code{imm_n16_15}, an integer literal in range -16 to 15;
16499 @item @code{imm_n512_511}, an integer literal in range -512 to 511;
16500 @item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left
16501 shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022;
16502 @item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left
16503 shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044;
16504 @item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left
16505 shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088;
16506 @item @code{imm1_4}, an integer literal in range 1 to 4;
16507 @item @code{i32, i64, u32, u64, f32, f64}, defined as follows:
16513 #if __LONG_MAX__ == __LONG_LONG_MAX__
16516 typedef long long i64;
16519 typedef unsigned int u32;
16520 #if __LONG_MAX__ == __LONG_LONG_MAX__
16521 typedef unsigned long u64;
16523 typedef unsigned long long u64;
16526 typedef double f64;
16531 @node MIPS SIMD Architecture Built-in Functions
16532 @subsubsection MIPS SIMD Architecture Built-in Functions
16534 The intrinsics provided are listed below; each is named after the
16535 machine instruction.
16538 v16i8 __builtin_msa_add_a_b (v16i8, v16i8);
16539 v8i16 __builtin_msa_add_a_h (v8i16, v8i16);
16540 v4i32 __builtin_msa_add_a_w (v4i32, v4i32);
16541 v2i64 __builtin_msa_add_a_d (v2i64, v2i64);
16543 v16i8 __builtin_msa_adds_a_b (v16i8, v16i8);
16544 v8i16 __builtin_msa_adds_a_h (v8i16, v8i16);
16545 v4i32 __builtin_msa_adds_a_w (v4i32, v4i32);
16546 v2i64 __builtin_msa_adds_a_d (v2i64, v2i64);
16548 v16i8 __builtin_msa_adds_s_b (v16i8, v16i8);
16549 v8i16 __builtin_msa_adds_s_h (v8i16, v8i16);
16550 v4i32 __builtin_msa_adds_s_w (v4i32, v4i32);
16551 v2i64 __builtin_msa_adds_s_d (v2i64, v2i64);
16553 v16u8 __builtin_msa_adds_u_b (v16u8, v16u8);
16554 v8u16 __builtin_msa_adds_u_h (v8u16, v8u16);
16555 v4u32 __builtin_msa_adds_u_w (v4u32, v4u32);
16556 v2u64 __builtin_msa_adds_u_d (v2u64, v2u64);
16558 v16i8 __builtin_msa_addv_b (v16i8, v16i8);
16559 v8i16 __builtin_msa_addv_h (v8i16, v8i16);
16560 v4i32 __builtin_msa_addv_w (v4i32, v4i32);
16561 v2i64 __builtin_msa_addv_d (v2i64, v2i64);
16563 v16i8 __builtin_msa_addvi_b (v16i8, imm0_31);
16564 v8i16 __builtin_msa_addvi_h (v8i16, imm0_31);
16565 v4i32 __builtin_msa_addvi_w (v4i32, imm0_31);
16566 v2i64 __builtin_msa_addvi_d (v2i64, imm0_31);
16568 v16u8 __builtin_msa_and_v (v16u8, v16u8);
16570 v16u8 __builtin_msa_andi_b (v16u8, imm0_255);
16572 v16i8 __builtin_msa_asub_s_b (v16i8, v16i8);
16573 v8i16 __builtin_msa_asub_s_h (v8i16, v8i16);
16574 v4i32 __builtin_msa_asub_s_w (v4i32, v4i32);
16575 v2i64 __builtin_msa_asub_s_d (v2i64, v2i64);
16577 v16u8 __builtin_msa_asub_u_b (v16u8, v16u8);
16578 v8u16 __builtin_msa_asub_u_h (v8u16, v8u16);
16579 v4u32 __builtin_msa_asub_u_w (v4u32, v4u32);
16580 v2u64 __builtin_msa_asub_u_d (v2u64, v2u64);
16582 v16i8 __builtin_msa_ave_s_b (v16i8, v16i8);
16583 v8i16 __builtin_msa_ave_s_h (v8i16, v8i16);
16584 v4i32 __builtin_msa_ave_s_w (v4i32, v4i32);
16585 v2i64 __builtin_msa_ave_s_d (v2i64, v2i64);
16587 v16u8 __builtin_msa_ave_u_b (v16u8, v16u8);
16588 v8u16 __builtin_msa_ave_u_h (v8u16, v8u16);
16589 v4u32 __builtin_msa_ave_u_w (v4u32, v4u32);
16590 v2u64 __builtin_msa_ave_u_d (v2u64, v2u64);
16592 v16i8 __builtin_msa_aver_s_b (v16i8, v16i8);
16593 v8i16 __builtin_msa_aver_s_h (v8i16, v8i16);
16594 v4i32 __builtin_msa_aver_s_w (v4i32, v4i32);
16595 v2i64 __builtin_msa_aver_s_d (v2i64, v2i64);
16597 v16u8 __builtin_msa_aver_u_b (v16u8, v16u8);
16598 v8u16 __builtin_msa_aver_u_h (v8u16, v8u16);
16599 v4u32 __builtin_msa_aver_u_w (v4u32, v4u32);
16600 v2u64 __builtin_msa_aver_u_d (v2u64, v2u64);
16602 v16u8 __builtin_msa_bclr_b (v16u8, v16u8);
16603 v8u16 __builtin_msa_bclr_h (v8u16, v8u16);
16604 v4u32 __builtin_msa_bclr_w (v4u32, v4u32);
16605 v2u64 __builtin_msa_bclr_d (v2u64, v2u64);
16607 v16u8 __builtin_msa_bclri_b (v16u8, imm0_7);
16608 v8u16 __builtin_msa_bclri_h (v8u16, imm0_15);
16609 v4u32 __builtin_msa_bclri_w (v4u32, imm0_31);
16610 v2u64 __builtin_msa_bclri_d (v2u64, imm0_63);
16612 v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8);
16613 v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16);
16614 v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32);
16615 v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64);
16617 v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7);
16618 v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15);
16619 v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31);
16620 v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63);
16622 v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8);
16623 v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16);
16624 v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32);
16625 v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64);
16627 v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7);
16628 v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15);
16629 v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31);
16630 v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63);
16632 v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8);
16634 v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255);
16636 v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8);
16638 v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255);
16640 v16u8 __builtin_msa_bneg_b (v16u8, v16u8);
16641 v8u16 __builtin_msa_bneg_h (v8u16, v8u16);
16642 v4u32 __builtin_msa_bneg_w (v4u32, v4u32);
16643 v2u64 __builtin_msa_bneg_d (v2u64, v2u64);
16645 v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7);
16646 v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15);
16647 v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31);
16648 v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63);
16650 i32 __builtin_msa_bnz_b (v16u8);
16651 i32 __builtin_msa_bnz_h (v8u16);
16652 i32 __builtin_msa_bnz_w (v4u32);
16653 i32 __builtin_msa_bnz_d (v2u64);
16655 i32 __builtin_msa_bnz_v (v16u8);
16657 v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8);
16659 v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255);
16661 v16u8 __builtin_msa_bset_b (v16u8, v16u8);
16662 v8u16 __builtin_msa_bset_h (v8u16, v8u16);
16663 v4u32 __builtin_msa_bset_w (v4u32, v4u32);
16664 v2u64 __builtin_msa_bset_d (v2u64, v2u64);
16666 v16u8 __builtin_msa_bseti_b (v16u8, imm0_7);
16667 v8u16 __builtin_msa_bseti_h (v8u16, imm0_15);
16668 v4u32 __builtin_msa_bseti_w (v4u32, imm0_31);
16669 v2u64 __builtin_msa_bseti_d (v2u64, imm0_63);
16671 i32 __builtin_msa_bz_b (v16u8);
16672 i32 __builtin_msa_bz_h (v8u16);
16673 i32 __builtin_msa_bz_w (v4u32);
16674 i32 __builtin_msa_bz_d (v2u64);
16676 i32 __builtin_msa_bz_v (v16u8);
16678 v16i8 __builtin_msa_ceq_b (v16i8, v16i8);
16679 v8i16 __builtin_msa_ceq_h (v8i16, v8i16);
16680 v4i32 __builtin_msa_ceq_w (v4i32, v4i32);
16681 v2i64 __builtin_msa_ceq_d (v2i64, v2i64);
16683 v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15);
16684 v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15);
16685 v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15);
16686 v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15);
16688 i32 __builtin_msa_cfcmsa (imm0_31);
16690 v16i8 __builtin_msa_cle_s_b (v16i8, v16i8);
16691 v8i16 __builtin_msa_cle_s_h (v8i16, v8i16);
16692 v4i32 __builtin_msa_cle_s_w (v4i32, v4i32);
16693 v2i64 __builtin_msa_cle_s_d (v2i64, v2i64);
16695 v16i8 __builtin_msa_cle_u_b (v16u8, v16u8);
16696 v8i16 __builtin_msa_cle_u_h (v8u16, v8u16);
16697 v4i32 __builtin_msa_cle_u_w (v4u32, v4u32);
16698 v2i64 __builtin_msa_cle_u_d (v2u64, v2u64);
16700 v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15);
16701 v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15);
16702 v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15);
16703 v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15);
16705 v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31);
16706 v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31);
16707 v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31);
16708 v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31);
16710 v16i8 __builtin_msa_clt_s_b (v16i8, v16i8);
16711 v8i16 __builtin_msa_clt_s_h (v8i16, v8i16);
16712 v4i32 __builtin_msa_clt_s_w (v4i32, v4i32);
16713 v2i64 __builtin_msa_clt_s_d (v2i64, v2i64);
16715 v16i8 __builtin_msa_clt_u_b (v16u8, v16u8);
16716 v8i16 __builtin_msa_clt_u_h (v8u16, v8u16);
16717 v4i32 __builtin_msa_clt_u_w (v4u32, v4u32);
16718 v2i64 __builtin_msa_clt_u_d (v2u64, v2u64);
16720 v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15);
16721 v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15);
16722 v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15);
16723 v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15);
16725 v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31);
16726 v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31);
16727 v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31);
16728 v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31);
16730 i32 __builtin_msa_copy_s_b (v16i8, imm0_15);
16731 i32 __builtin_msa_copy_s_h (v8i16, imm0_7);
16732 i32 __builtin_msa_copy_s_w (v4i32, imm0_3);
16733 i64 __builtin_msa_copy_s_d (v2i64, imm0_1);
16735 u32 __builtin_msa_copy_u_b (v16i8, imm0_15);
16736 u32 __builtin_msa_copy_u_h (v8i16, imm0_7);
16737 u32 __builtin_msa_copy_u_w (v4i32, imm0_3);
16738 u64 __builtin_msa_copy_u_d (v2i64, imm0_1);
16740 void __builtin_msa_ctcmsa (imm0_31, i32);
16742 v16i8 __builtin_msa_div_s_b (v16i8, v16i8);
16743 v8i16 __builtin_msa_div_s_h (v8i16, v8i16);
16744 v4i32 __builtin_msa_div_s_w (v4i32, v4i32);
16745 v2i64 __builtin_msa_div_s_d (v2i64, v2i64);
16747 v16u8 __builtin_msa_div_u_b (v16u8, v16u8);
16748 v8u16 __builtin_msa_div_u_h (v8u16, v8u16);
16749 v4u32 __builtin_msa_div_u_w (v4u32, v4u32);
16750 v2u64 __builtin_msa_div_u_d (v2u64, v2u64);
16752 v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8);
16753 v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16);
16754 v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32);
16756 v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8);
16757 v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16);
16758 v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32);
16760 v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8);
16761 v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16);
16762 v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32);
16764 v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8);
16765 v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16);
16766 v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32);
16768 v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8);
16769 v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16);
16770 v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32);
16772 v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8);
16773 v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16);
16774 v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32);
16776 v4f32 __builtin_msa_fadd_w (v4f32, v4f32);
16777 v2f64 __builtin_msa_fadd_d (v2f64, v2f64);
16779 v4i32 __builtin_msa_fcaf_w (v4f32, v4f32);
16780 v2i64 __builtin_msa_fcaf_d (v2f64, v2f64);
16782 v4i32 __builtin_msa_fceq_w (v4f32, v4f32);
16783 v2i64 __builtin_msa_fceq_d (v2f64, v2f64);
16785 v4i32 __builtin_msa_fclass_w (v4f32);
16786 v2i64 __builtin_msa_fclass_d (v2f64);
16788 v4i32 __builtin_msa_fcle_w (v4f32, v4f32);
16789 v2i64 __builtin_msa_fcle_d (v2f64, v2f64);
16791 v4i32 __builtin_msa_fclt_w (v4f32, v4f32);
16792 v2i64 __builtin_msa_fclt_d (v2f64, v2f64);
16794 v4i32 __builtin_msa_fcne_w (v4f32, v4f32);
16795 v2i64 __builtin_msa_fcne_d (v2f64, v2f64);
16797 v4i32 __builtin_msa_fcor_w (v4f32, v4f32);
16798 v2i64 __builtin_msa_fcor_d (v2f64, v2f64);
16800 v4i32 __builtin_msa_fcueq_w (v4f32, v4f32);
16801 v2i64 __builtin_msa_fcueq_d (v2f64, v2f64);
16803 v4i32 __builtin_msa_fcule_w (v4f32, v4f32);
16804 v2i64 __builtin_msa_fcule_d (v2f64, v2f64);
16806 v4i32 __builtin_msa_fcult_w (v4f32, v4f32);
16807 v2i64 __builtin_msa_fcult_d (v2f64, v2f64);
16809 v4i32 __builtin_msa_fcun_w (v4f32, v4f32);
16810 v2i64 __builtin_msa_fcun_d (v2f64, v2f64);
16812 v4i32 __builtin_msa_fcune_w (v4f32, v4f32);
16813 v2i64 __builtin_msa_fcune_d (v2f64, v2f64);
16815 v4f32 __builtin_msa_fdiv_w (v4f32, v4f32);
16816 v2f64 __builtin_msa_fdiv_d (v2f64, v2f64);
16818 v8i16 __builtin_msa_fexdo_h (v4f32, v4f32);
16819 v4f32 __builtin_msa_fexdo_w (v2f64, v2f64);
16821 v4f32 __builtin_msa_fexp2_w (v4f32, v4i32);
16822 v2f64 __builtin_msa_fexp2_d (v2f64, v2i64);
16824 v4f32 __builtin_msa_fexupl_w (v8i16);
16825 v2f64 __builtin_msa_fexupl_d (v4f32);
16827 v4f32 __builtin_msa_fexupr_w (v8i16);
16828 v2f64 __builtin_msa_fexupr_d (v4f32);
16830 v4f32 __builtin_msa_ffint_s_w (v4i32);
16831 v2f64 __builtin_msa_ffint_s_d (v2i64);
16833 v4f32 __builtin_msa_ffint_u_w (v4u32);
16834 v2f64 __builtin_msa_ffint_u_d (v2u64);
16836 v4f32 __builtin_msa_ffql_w (v8i16);
16837 v2f64 __builtin_msa_ffql_d (v4i32);
16839 v4f32 __builtin_msa_ffqr_w (v8i16);
16840 v2f64 __builtin_msa_ffqr_d (v4i32);
16842 v16i8 __builtin_msa_fill_b (i32);
16843 v8i16 __builtin_msa_fill_h (i32);
16844 v4i32 __builtin_msa_fill_w (i32);
16845 v2i64 __builtin_msa_fill_d (i64);
16847 v4f32 __builtin_msa_flog2_w (v4f32);
16848 v2f64 __builtin_msa_flog2_d (v2f64);
16850 v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32);
16851 v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64);
16853 v4f32 __builtin_msa_fmax_w (v4f32, v4f32);
16854 v2f64 __builtin_msa_fmax_d (v2f64, v2f64);
16856 v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32);
16857 v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64);
16859 v4f32 __builtin_msa_fmin_w (v4f32, v4f32);
16860 v2f64 __builtin_msa_fmin_d (v2f64, v2f64);
16862 v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32);
16863 v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64);
16865 v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32);
16866 v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64);
16868 v4f32 __builtin_msa_fmul_w (v4f32, v4f32);
16869 v2f64 __builtin_msa_fmul_d (v2f64, v2f64);
16871 v4f32 __builtin_msa_frint_w (v4f32);
16872 v2f64 __builtin_msa_frint_d (v2f64);
16874 v4f32 __builtin_msa_frcp_w (v4f32);
16875 v2f64 __builtin_msa_frcp_d (v2f64);
16877 v4f32 __builtin_msa_frsqrt_w (v4f32);
16878 v2f64 __builtin_msa_frsqrt_d (v2f64);
16880 v4i32 __builtin_msa_fsaf_w (v4f32, v4f32);
16881 v2i64 __builtin_msa_fsaf_d (v2f64, v2f64);
16883 v4i32 __builtin_msa_fseq_w (v4f32, v4f32);
16884 v2i64 __builtin_msa_fseq_d (v2f64, v2f64);
16886 v4i32 __builtin_msa_fsle_w (v4f32, v4f32);
16887 v2i64 __builtin_msa_fsle_d (v2f64, v2f64);
16889 v4i32 __builtin_msa_fslt_w (v4f32, v4f32);
16890 v2i64 __builtin_msa_fslt_d (v2f64, v2f64);
16892 v4i32 __builtin_msa_fsne_w (v4f32, v4f32);
16893 v2i64 __builtin_msa_fsne_d (v2f64, v2f64);
16895 v4i32 __builtin_msa_fsor_w (v4f32, v4f32);
16896 v2i64 __builtin_msa_fsor_d (v2f64, v2f64);
16898 v4f32 __builtin_msa_fsqrt_w (v4f32);
16899 v2f64 __builtin_msa_fsqrt_d (v2f64);
16901 v4f32 __builtin_msa_fsub_w (v4f32, v4f32);
16902 v2f64 __builtin_msa_fsub_d (v2f64, v2f64);
16904 v4i32 __builtin_msa_fsueq_w (v4f32, v4f32);
16905 v2i64 __builtin_msa_fsueq_d (v2f64, v2f64);
16907 v4i32 __builtin_msa_fsule_w (v4f32, v4f32);
16908 v2i64 __builtin_msa_fsule_d (v2f64, v2f64);
16910 v4i32 __builtin_msa_fsult_w (v4f32, v4f32);
16911 v2i64 __builtin_msa_fsult_d (v2f64, v2f64);
16913 v4i32 __builtin_msa_fsun_w (v4f32, v4f32);
16914 v2i64 __builtin_msa_fsun_d (v2f64, v2f64);
16916 v4i32 __builtin_msa_fsune_w (v4f32, v4f32);
16917 v2i64 __builtin_msa_fsune_d (v2f64, v2f64);
16919 v4i32 __builtin_msa_ftint_s_w (v4f32);
16920 v2i64 __builtin_msa_ftint_s_d (v2f64);
16922 v4u32 __builtin_msa_ftint_u_w (v4f32);
16923 v2u64 __builtin_msa_ftint_u_d (v2f64);
16925 v8i16 __builtin_msa_ftq_h (v4f32, v4f32);
16926 v4i32 __builtin_msa_ftq_w (v2f64, v2f64);
16928 v4i32 __builtin_msa_ftrunc_s_w (v4f32);
16929 v2i64 __builtin_msa_ftrunc_s_d (v2f64);
16931 v4u32 __builtin_msa_ftrunc_u_w (v4f32);
16932 v2u64 __builtin_msa_ftrunc_u_d (v2f64);
16934 v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8);
16935 v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16);
16936 v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32);
16938 v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8);
16939 v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16);
16940 v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32);
16942 v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8);
16943 v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16);
16944 v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32);
16946 v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8);
16947 v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16);
16948 v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32);
16950 v16i8 __builtin_msa_ilvev_b (v16i8, v16i8);
16951 v8i16 __builtin_msa_ilvev_h (v8i16, v8i16);
16952 v4i32 __builtin_msa_ilvev_w (v4i32, v4i32);
16953 v2i64 __builtin_msa_ilvev_d (v2i64, v2i64);
16955 v16i8 __builtin_msa_ilvl_b (v16i8, v16i8);
16956 v8i16 __builtin_msa_ilvl_h (v8i16, v8i16);
16957 v4i32 __builtin_msa_ilvl_w (v4i32, v4i32);
16958 v2i64 __builtin_msa_ilvl_d (v2i64, v2i64);
16960 v16i8 __builtin_msa_ilvod_b (v16i8, v16i8);
16961 v8i16 __builtin_msa_ilvod_h (v8i16, v8i16);
16962 v4i32 __builtin_msa_ilvod_w (v4i32, v4i32);
16963 v2i64 __builtin_msa_ilvod_d (v2i64, v2i64);
16965 v16i8 __builtin_msa_ilvr_b (v16i8, v16i8);
16966 v8i16 __builtin_msa_ilvr_h (v8i16, v8i16);
16967 v4i32 __builtin_msa_ilvr_w (v4i32, v4i32);
16968 v2i64 __builtin_msa_ilvr_d (v2i64, v2i64);
16970 v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32);
16971 v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32);
16972 v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32);
16973 v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64);
16975 v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8);
16976 v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16);
16977 v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32);
16978 v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64);
16980 v16i8 __builtin_msa_ld_b (const void *, imm_n512_511);
16981 v8i16 __builtin_msa_ld_h (const void *, imm_n1024_1022);
16982 v4i32 __builtin_msa_ld_w (const void *, imm_n2048_2044);
16983 v2i64 __builtin_msa_ld_d (const void *, imm_n4096_4088);
16985 v16i8 __builtin_msa_ldi_b (imm_n512_511);
16986 v8i16 __builtin_msa_ldi_h (imm_n512_511);
16987 v4i32 __builtin_msa_ldi_w (imm_n512_511);
16988 v2i64 __builtin_msa_ldi_d (imm_n512_511);
16990 v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16);
16991 v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32);
16993 v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16);
16994 v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32);
16996 v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8);
16997 v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16);
16998 v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32);
16999 v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64);
17001 v16i8 __builtin_msa_max_a_b (v16i8, v16i8);
17002 v8i16 __builtin_msa_max_a_h (v8i16, v8i16);
17003 v4i32 __builtin_msa_max_a_w (v4i32, v4i32);
17004 v2i64 __builtin_msa_max_a_d (v2i64, v2i64);
17006 v16i8 __builtin_msa_max_s_b (v16i8, v16i8);
17007 v8i16 __builtin_msa_max_s_h (v8i16, v8i16);
17008 v4i32 __builtin_msa_max_s_w (v4i32, v4i32);
17009 v2i64 __builtin_msa_max_s_d (v2i64, v2i64);
17011 v16u8 __builtin_msa_max_u_b (v16u8, v16u8);
17012 v8u16 __builtin_msa_max_u_h (v8u16, v8u16);
17013 v4u32 __builtin_msa_max_u_w (v4u32, v4u32);
17014 v2u64 __builtin_msa_max_u_d (v2u64, v2u64);
17016 v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15);
17017 v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15);
17018 v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15);
17019 v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15);
17021 v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31);
17022 v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31);
17023 v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31);
17024 v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31);
17026 v16i8 __builtin_msa_min_a_b (v16i8, v16i8);
17027 v8i16 __builtin_msa_min_a_h (v8i16, v8i16);
17028 v4i32 __builtin_msa_min_a_w (v4i32, v4i32);
17029 v2i64 __builtin_msa_min_a_d (v2i64, v2i64);
17031 v16i8 __builtin_msa_min_s_b (v16i8, v16i8);
17032 v8i16 __builtin_msa_min_s_h (v8i16, v8i16);
17033 v4i32 __builtin_msa_min_s_w (v4i32, v4i32);
17034 v2i64 __builtin_msa_min_s_d (v2i64, v2i64);
17036 v16u8 __builtin_msa_min_u_b (v16u8, v16u8);
17037 v8u16 __builtin_msa_min_u_h (v8u16, v8u16);
17038 v4u32 __builtin_msa_min_u_w (v4u32, v4u32);
17039 v2u64 __builtin_msa_min_u_d (v2u64, v2u64);
17041 v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15);
17042 v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15);
17043 v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15);
17044 v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15);
17046 v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31);
17047 v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31);
17048 v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31);
17049 v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31);
17051 v16i8 __builtin_msa_mod_s_b (v16i8, v16i8);
17052 v8i16 __builtin_msa_mod_s_h (v8i16, v8i16);
17053 v4i32 __builtin_msa_mod_s_w (v4i32, v4i32);
17054 v2i64 __builtin_msa_mod_s_d (v2i64, v2i64);
17056 v16u8 __builtin_msa_mod_u_b (v16u8, v16u8);
17057 v8u16 __builtin_msa_mod_u_h (v8u16, v8u16);
17058 v4u32 __builtin_msa_mod_u_w (v4u32, v4u32);
17059 v2u64 __builtin_msa_mod_u_d (v2u64, v2u64);
17061 v16i8 __builtin_msa_move_v (v16i8);
17063 v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16);
17064 v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32);
17066 v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16);
17067 v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32);
17069 v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8);
17070 v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16);
17071 v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32);
17072 v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64);
17074 v8i16 __builtin_msa_mul_q_h (v8i16, v8i16);
17075 v4i32 __builtin_msa_mul_q_w (v4i32, v4i32);
17077 v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16);
17078 v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32);
17080 v16i8 __builtin_msa_mulv_b (v16i8, v16i8);
17081 v8i16 __builtin_msa_mulv_h (v8i16, v8i16);
17082 v4i32 __builtin_msa_mulv_w (v4i32, v4i32);
17083 v2i64 __builtin_msa_mulv_d (v2i64, v2i64);
17085 v16i8 __builtin_msa_nloc_b (v16i8);
17086 v8i16 __builtin_msa_nloc_h (v8i16);
17087 v4i32 __builtin_msa_nloc_w (v4i32);
17088 v2i64 __builtin_msa_nloc_d (v2i64);
17090 v16i8 __builtin_msa_nlzc_b (v16i8);
17091 v8i16 __builtin_msa_nlzc_h (v8i16);
17092 v4i32 __builtin_msa_nlzc_w (v4i32);
17093 v2i64 __builtin_msa_nlzc_d (v2i64);
17095 v16u8 __builtin_msa_nor_v (v16u8, v16u8);
17097 v16u8 __builtin_msa_nori_b (v16u8, imm0_255);
17099 v16u8 __builtin_msa_or_v (v16u8, v16u8);
17101 v16u8 __builtin_msa_ori_b (v16u8, imm0_255);
17103 v16i8 __builtin_msa_pckev_b (v16i8, v16i8);
17104 v8i16 __builtin_msa_pckev_h (v8i16, v8i16);
17105 v4i32 __builtin_msa_pckev_w (v4i32, v4i32);
17106 v2i64 __builtin_msa_pckev_d (v2i64, v2i64);
17108 v16i8 __builtin_msa_pckod_b (v16i8, v16i8);
17109 v8i16 __builtin_msa_pckod_h (v8i16, v8i16);
17110 v4i32 __builtin_msa_pckod_w (v4i32, v4i32);
17111 v2i64 __builtin_msa_pckod_d (v2i64, v2i64);
17113 v16i8 __builtin_msa_pcnt_b (v16i8);
17114 v8i16 __builtin_msa_pcnt_h (v8i16);
17115 v4i32 __builtin_msa_pcnt_w (v4i32);
17116 v2i64 __builtin_msa_pcnt_d (v2i64);
17118 v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7);
17119 v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15);
17120 v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31);
17121 v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63);
17123 v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7);
17124 v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15);
17125 v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31);
17126 v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63);
17128 v16i8 __builtin_msa_shf_b (v16i8, imm0_255);
17129 v8i16 __builtin_msa_shf_h (v8i16, imm0_255);
17130 v4i32 __builtin_msa_shf_w (v4i32, imm0_255);
17132 v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32);
17133 v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32);
17134 v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32);
17135 v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32);
17137 v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15);
17138 v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7);
17139 v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3);
17140 v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1);
17142 v16i8 __builtin_msa_sll_b (v16i8, v16i8);
17143 v8i16 __builtin_msa_sll_h (v8i16, v8i16);
17144 v4i32 __builtin_msa_sll_w (v4i32, v4i32);
17145 v2i64 __builtin_msa_sll_d (v2i64, v2i64);
17147 v16i8 __builtin_msa_slli_b (v16i8, imm0_7);
17148 v8i16 __builtin_msa_slli_h (v8i16, imm0_15);
17149 v4i32 __builtin_msa_slli_w (v4i32, imm0_31);
17150 v2i64 __builtin_msa_slli_d (v2i64, imm0_63);
17152 v16i8 __builtin_msa_splat_b (v16i8, i32);
17153 v8i16 __builtin_msa_splat_h (v8i16, i32);
17154 v4i32 __builtin_msa_splat_w (v4i32, i32);
17155 v2i64 __builtin_msa_splat_d (v2i64, i32);
17157 v16i8 __builtin_msa_splati_b (v16i8, imm0_15);
17158 v8i16 __builtin_msa_splati_h (v8i16, imm0_7);
17159 v4i32 __builtin_msa_splati_w (v4i32, imm0_3);
17160 v2i64 __builtin_msa_splati_d (v2i64, imm0_1);
17162 v16i8 __builtin_msa_sra_b (v16i8, v16i8);
17163 v8i16 __builtin_msa_sra_h (v8i16, v8i16);
17164 v4i32 __builtin_msa_sra_w (v4i32, v4i32);
17165 v2i64 __builtin_msa_sra_d (v2i64, v2i64);
17167 v16i8 __builtin_msa_srai_b (v16i8, imm0_7);
17168 v8i16 __builtin_msa_srai_h (v8i16, imm0_15);
17169 v4i32 __builtin_msa_srai_w (v4i32, imm0_31);
17170 v2i64 __builtin_msa_srai_d (v2i64, imm0_63);
17172 v16i8 __builtin_msa_srar_b (v16i8, v16i8);
17173 v8i16 __builtin_msa_srar_h (v8i16, v8i16);
17174 v4i32 __builtin_msa_srar_w (v4i32, v4i32);
17175 v2i64 __builtin_msa_srar_d (v2i64, v2i64);
17177 v16i8 __builtin_msa_srari_b (v16i8, imm0_7);
17178 v8i16 __builtin_msa_srari_h (v8i16, imm0_15);
17179 v4i32 __builtin_msa_srari_w (v4i32, imm0_31);
17180 v2i64 __builtin_msa_srari_d (v2i64, imm0_63);
17182 v16i8 __builtin_msa_srl_b (v16i8, v16i8);
17183 v8i16 __builtin_msa_srl_h (v8i16, v8i16);
17184 v4i32 __builtin_msa_srl_w (v4i32, v4i32);
17185 v2i64 __builtin_msa_srl_d (v2i64, v2i64);
17187 v16i8 __builtin_msa_srli_b (v16i8, imm0_7);
17188 v8i16 __builtin_msa_srli_h (v8i16, imm0_15);
17189 v4i32 __builtin_msa_srli_w (v4i32, imm0_31);
17190 v2i64 __builtin_msa_srli_d (v2i64, imm0_63);
17192 v16i8 __builtin_msa_srlr_b (v16i8, v16i8);
17193 v8i16 __builtin_msa_srlr_h (v8i16, v8i16);
17194 v4i32 __builtin_msa_srlr_w (v4i32, v4i32);
17195 v2i64 __builtin_msa_srlr_d (v2i64, v2i64);
17197 v16i8 __builtin_msa_srlri_b (v16i8, imm0_7);
17198 v8i16 __builtin_msa_srlri_h (v8i16, imm0_15);
17199 v4i32 __builtin_msa_srlri_w (v4i32, imm0_31);
17200 v2i64 __builtin_msa_srlri_d (v2i64, imm0_63);
17202 void __builtin_msa_st_b (v16i8, void *, imm_n512_511);
17203 void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022);
17204 void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044);
17205 void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088);
17207 v16i8 __builtin_msa_subs_s_b (v16i8, v16i8);
17208 v8i16 __builtin_msa_subs_s_h (v8i16, v8i16);
17209 v4i32 __builtin_msa_subs_s_w (v4i32, v4i32);
17210 v2i64 __builtin_msa_subs_s_d (v2i64, v2i64);
17212 v16u8 __builtin_msa_subs_u_b (v16u8, v16u8);
17213 v8u16 __builtin_msa_subs_u_h (v8u16, v8u16);
17214 v4u32 __builtin_msa_subs_u_w (v4u32, v4u32);
17215 v2u64 __builtin_msa_subs_u_d (v2u64, v2u64);
17217 v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8);
17218 v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16);
17219 v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32);
17220 v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64);
17222 v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8);
17223 v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16);
17224 v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32);
17225 v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64);
17227 v16i8 __builtin_msa_subv_b (v16i8, v16i8);
17228 v8i16 __builtin_msa_subv_h (v8i16, v8i16);
17229 v4i32 __builtin_msa_subv_w (v4i32, v4i32);
17230 v2i64 __builtin_msa_subv_d (v2i64, v2i64);
17232 v16i8 __builtin_msa_subvi_b (v16i8, imm0_31);
17233 v8i16 __builtin_msa_subvi_h (v8i16, imm0_31);
17234 v4i32 __builtin_msa_subvi_w (v4i32, imm0_31);
17235 v2i64 __builtin_msa_subvi_d (v2i64, imm0_31);
17237 v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8);
17238 v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16);
17239 v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32);
17240 v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64);
17242 v16u8 __builtin_msa_xor_v (v16u8, v16u8);
17244 v16u8 __builtin_msa_xori_b (v16u8, imm0_255);
17247 @node Other MIPS Built-in Functions
17248 @subsection Other MIPS Built-in Functions
17250 GCC provides other MIPS-specific built-in functions:
17253 @item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr})
17254 Insert a @samp{cache} instruction with operands @var{op} and @var{addr}.
17255 GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE}
17256 when this function is available.
17258 @item unsigned int __builtin_mips_get_fcsr (void)
17259 @itemx void __builtin_mips_set_fcsr (unsigned int @var{value})
17260 Get and set the contents of the floating-point control and status register
17261 (FPU control register 31). These functions are only available in hard-float
17262 code but can be called in both MIPS16 and non-MIPS16 contexts.
17264 @code{__builtin_mips_set_fcsr} can be used to change any bit of the
17265 register except the condition codes, which GCC assumes are preserved.
17268 @node MSP430 Built-in Functions
17269 @subsection MSP430 Built-in Functions
17271 GCC provides a couple of special builtin functions to aid in the
17272 writing of interrupt handlers in C.
17275 @item __bic_SR_register_on_exit (int @var{mask})
17276 This clears the indicated bits in the saved copy of the status register
17277 currently residing on the stack. This only works inside interrupt
17278 handlers and the changes to the status register will only take affect
17279 once the handler returns.
17281 @item __bis_SR_register_on_exit (int @var{mask})
17282 This sets the indicated bits in the saved copy of the status register
17283 currently residing on the stack. This only works inside interrupt
17284 handlers and the changes to the status register will only take affect
17285 once the handler returns.
17287 @item __delay_cycles (long long @var{cycles})
17288 This inserts an instruction sequence that takes exactly @var{cycles}
17289 cycles (between 0 and about 17E9) to complete. The inserted sequence
17290 may use jumps, loops, or no-ops, and does not interfere with any other
17291 instructions. Note that @var{cycles} must be a compile-time constant
17292 integer - that is, you must pass a number, not a variable that may be
17293 optimized to a constant later. The number of cycles delayed by this
17297 @node NDS32 Built-in Functions
17298 @subsection NDS32 Built-in Functions
17300 These built-in functions are available for the NDS32 target:
17302 @deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr})
17303 Insert an ISYNC instruction into the instruction stream where
17304 @var{addr} is an instruction address for serialization.
17307 @deftypefn {Built-in Function} void __builtin_nds32_isb (void)
17308 Insert an ISB instruction into the instruction stream.
17311 @deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr})
17312 Return the content of a system register which is mapped by @var{sr}.
17315 @deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr})
17316 Return the content of a user space register which is mapped by @var{usr}.
17319 @deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr})
17320 Move the @var{value} to a system register which is mapped by @var{sr}.
17323 @deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr})
17324 Move the @var{value} to a user space register which is mapped by @var{usr}.
17327 @deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void)
17328 Enable global interrupt.
17331 @deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void)
17332 Disable global interrupt.
17335 @node picoChip Built-in Functions
17336 @subsection picoChip Built-in Functions
17338 GCC provides an interface to selected machine instructions from the
17339 picoChip instruction set.
17342 @item int __builtin_sbc (int @var{value})
17343 Sign bit count. Return the number of consecutive bits in @var{value}
17344 that have the same value as the sign bit. The result is the number of
17345 leading sign bits minus one, giving the number of redundant sign bits in
17348 @item int __builtin_byteswap (int @var{value})
17349 Byte swap. Return the result of swapping the upper and lower bytes of
17352 @item int __builtin_brev (int @var{value})
17353 Bit reversal. Return the result of reversing the bits in
17354 @var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1,
17357 @item int __builtin_adds (int @var{x}, int @var{y})
17358 Saturating addition. Return the result of adding @var{x} and @var{y},
17359 storing the value 32767 if the result overflows.
17361 @item int __builtin_subs (int @var{x}, int @var{y})
17362 Saturating subtraction. Return the result of subtracting @var{y} from
17363 @var{x}, storing the value @minus{}32768 if the result overflows.
17365 @item void __builtin_halt (void)
17366 Halt. The processor stops execution. This built-in is useful for
17367 implementing assertions.
17371 @node Basic PowerPC Built-in Functions
17372 @subsection Basic PowerPC Built-in Functions
17375 * Basic PowerPC Built-in Functions Available on all Configurations::
17376 * Basic PowerPC Built-in Functions Available on ISA 2.05::
17377 * Basic PowerPC Built-in Functions Available on ISA 2.06::
17378 * Basic PowerPC Built-in Functions Available on ISA 2.07::
17379 * Basic PowerPC Built-in Functions Available on ISA 3.0::
17380 * Basic PowerPC Built-in Functions Available on ISA 3.1::
17383 This section describes PowerPC built-in functions that do not require
17384 the inclusion of any special header files to declare prototypes or
17385 provide macro definitions. The sections that follow describe
17386 additional PowerPC built-in functions.
17388 @node Basic PowerPC Built-in Functions Available on all Configurations
17389 @subsubsection Basic PowerPC Built-in Functions Available on all Configurations
17391 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
17392 This function is a @code{nop} on the PowerPC platform and is included solely
17393 to maintain API compatibility with the x86 builtins.
17396 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
17397 This function returns a value of @code{1} if the run-time CPU is of type
17398 @var{cpuname} and returns @code{0} otherwise
17400 The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer
17401 which exports the hardware capability bits. GCC defines the macro
17402 @code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports}
17403 built-in function is fully supported.
17405 If GCC was configured to use a GLIBC before 2.23, the built-in
17406 function @code{__builtin_cpu_is} always returns a 0 and the compiler
17409 The following CPU names can be detected:
17413 IBM POWER10 Server CPU.
17415 IBM POWER9 Server CPU.
17417 IBM POWER8 Server CPU.
17419 IBM POWER7 Server CPU.
17421 IBM POWER6 Server CPU (RAW mode).
17423 IBM POWER6 Server CPU (Architected mode).
17425 IBM POWER5+ Server CPU.
17427 IBM POWER5 Server CPU.
17429 IBM 970 Server CPU (ie, Apple G5).
17431 IBM POWER4 Server CPU.
17433 IBM A2 64-bit Embedded CPU
17435 IBM PowerPC 476FP 32-bit Embedded CPU.
17437 IBM PowerPC 464 32-bit Embedded CPU.
17439 PowerPC 440 32-bit Embedded CPU.
17441 PowerPC 405 32-bit Embedded CPU.
17443 IBM PowerPC Cell Broadband Engine Architecture CPU.
17446 Here is an example:
17448 #ifdef __BUILTIN_CPU_SUPPORTS__
17449 if (__builtin_cpu_is ("power8"))
17451 do_power8 (); // POWER8 specific implementation.
17456 do_generic (); // Generic implementation.
17461 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
17462 This function returns a value of @code{1} if the run-time CPU supports the HWCAP
17463 feature @var{feature} and returns @code{0} otherwise.
17465 The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or
17466 newer which exports the hardware capability bits. GCC defines the
17467 macro @code{__BUILTIN_CPU_SUPPORTS__} if the
17468 @code{__builtin_cpu_supports} built-in function is fully supported.
17470 If GCC was configured to use a GLIBC before 2.23, the built-in
17471 function @code{__builtin_cpu_suports} always returns a 0 and the
17472 compiler issues a warning.
17474 The following features can be
17479 4xx CPU has a Multiply Accumulator.
17481 CPU has a SIMD/Vector Unit.
17483 CPU supports ISA 2.05 (eg, POWER6)
17485 CPU supports ISA 2.06 (eg, POWER7)
17487 CPU supports ISA 2.07 (eg, POWER8)
17489 CPU supports ISA 3.0 (eg, POWER9)
17491 CPU supports ISA 3.1 (eg, POWER10)
17493 CPU supports the set of compatible performance monitoring events.
17495 CPU supports the Embedded ISA category.
17497 CPU has a CELL broadband engine.
17499 CPU supports the @code{darn} (deliver a random number) instruction.
17501 CPU has a decimal floating point unit.
17503 CPU supports the data stream control register.
17505 CPU supports event base branching.
17507 CPU has a SPE double precision floating point unit.
17509 CPU has a SPE single precision floating point unit.
17511 CPU has a floating point unit.
17513 CPU has hardware transaction memory instructions.
17515 Kernel aborts hardware transactions when a syscall is made.
17516 @item htm-no-suspend
17517 CPU supports hardware transaction memory but does not support the
17518 @code{tsuspend.} instruction.
17520 CPU supports icache snooping capabilities.
17522 CPU supports 128-bit IEEE binary floating point instructions.
17524 CPU supports the integer select instruction.
17526 CPU supports the matrix-multiply assist instructions.
17528 CPU has a memory management unit.
17530 CPU does not have a timebase (eg, 601 and 403gx).
17532 CPU supports the PA Semi 6T CORE ISA.
17534 CPU supports ISA 2.00 (eg, POWER4)
17536 CPU supports ISA 2.02 (eg, POWER5)
17538 CPU supports ISA 2.03 (eg, POWER5+)
17540 CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr.
17542 CPU supports 32-bit mode execution.
17544 CPU supports the old POWER ISA (eg, 601)
17546 CPU supports 64-bit mode execution.
17548 CPU supports a little-endian mode that uses address swizzling.
17550 Kernel supports system call vectored.
17552 CPU support simultaneous multi-threading.
17554 CPU has a signal processing extension unit.
17556 CPU supports the target address register.
17558 CPU supports true little-endian mode.
17560 CPU has unified I/D cache.
17562 CPU supports the vector cryptography instructions.
17564 CPU supports the vector-scalar extension.
17567 Here is an example:
17569 #ifdef __BUILTIN_CPU_SUPPORTS__
17570 if (__builtin_cpu_supports ("fpu"))
17572 asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2));
17577 dst = __fadd (src1, src2); // Software FP addition function.
17582 The following built-in functions are also available on all PowerPC
17585 uint64_t __builtin_ppc_get_timebase ();
17586 unsigned long __builtin_ppc_mftb ();
17587 double __builtin_unpack_ibm128 (__ibm128, int);
17588 __ibm128 __builtin_pack_ibm128 (double, double);
17589 double __builtin_mffs (void);
17590 void __builtin_mtfsf (const int, double);
17591 void __builtin_mtfsb0 (const int);
17592 void __builtin_mtfsb1 (const int);
17593 void __builtin_set_fpscr_rn (int);
17596 The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb}
17597 functions generate instructions to read the Time Base Register. The
17598 @code{__builtin_ppc_get_timebase} function may generate multiple
17599 instructions and always returns the 64 bits of the Time Base Register.
17600 The @code{__builtin_ppc_mftb} function always generates one instruction and
17601 returns the Time Base Register value as an unsigned long, throwing away
17602 the most significant word on 32-bit environments. The @code{__builtin_mffs}
17603 return the value of the FPSCR register. Note, ISA 3.0 supports the
17604 @code{__builtin_mffsl()} which permits software to read the control and
17605 non-sticky status bits in the FSPCR without the higher latency associated with
17606 accessing the sticky status bits. The @code{__builtin_mtfsf} takes a constant
17607 8-bit integer field mask and a double precision floating point argument
17608 and generates the @code{mtfsf} (extended mnemonic) instruction to write new
17609 values to selected fields of the FPSCR. The
17610 @code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change
17611 as an argument. The valid bit range is between 0 and 31. The builtins map to
17612 the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and
17613 add 32. Hence these instructions only modify the FPSCR[32:63] bits by
17614 changing the specified bit to a zero or one respectively. The
17615 @code{__builtin_set_fpscr_rn} builtin allows changing both of the floating
17616 point rounding mode bits. The argument is a 2-bit value. The argument can
17617 either be a @code{const int} or stored in a variable. The builtin uses
17619 instruction @code{mffscrn} if available, otherwise it reads the FPSCR, masks
17620 the current rounding mode bits out and OR's in the new value.
17622 @node Basic PowerPC Built-in Functions Available on ISA 2.05
17623 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05
17625 The basic built-in functions described in this section are
17626 available on the PowerPC family of processors starting with ISA 2.05
17627 or later. Unless specific options are explicitly disabled on the
17628 command line, specifying option @option{-mcpu=power6} has the effect of
17629 enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
17630 @option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb},
17631 @option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and
17632 @option{-mrecip-precision} options. Specify the
17633 @option{-maltivec} option explicitly in
17634 combination with the above options if desired.
17636 The following functions require option @option{-mcmpb}.
17638 unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int);
17639 unsigned int __builtin_cmpb (unsigned int, unsigned int);
17642 The @code{__builtin_cmpb} function
17643 performs a byte-wise compare on the contents of its two arguments,
17644 returning the result of the byte-wise comparison as the returned
17645 value. For each byte comparison, the corresponding byte of the return
17646 value holds 0xff if the input bytes are equal and 0 if the input bytes
17647 are not equal. If either of the arguments to this built-in function
17648 is wider than 32 bits, the function call expands into the form that
17649 expects @code{unsigned long long int} arguments
17650 which is only available on 64-bit targets.
17652 The following built-in functions are available
17653 when hardware decimal floating point
17654 (@option{-mhard-dfp}) is available:
17656 void __builtin_set_fpscr_drn(int);
17657 _Decimal64 __builtin_ddedpd (int, _Decimal64);
17658 _Decimal128 __builtin_ddedpdq (int, _Decimal128);
17659 _Decimal64 __builtin_denbcd (int, _Decimal64);
17660 _Decimal128 __builtin_denbcdq (int, _Decimal128);
17661 _Decimal64 __builtin_diex (long long, _Decimal64);
17662 _Decimal128 _builtin_diexq (long long, _Decimal128);
17663 _Decimal64 __builtin_dscli (_Decimal64, int);
17664 _Decimal128 __builtin_dscliq (_Decimal128, int);
17665 _Decimal64 __builtin_dscri (_Decimal64, int);
17666 _Decimal128 __builtin_dscriq (_Decimal128, int);
17667 long long __builtin_dxex (_Decimal64);
17668 long long __builtin_dxexq (_Decimal128);
17669 _Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long);
17670 unsigned long long __builtin_unpack_dec128 (_Decimal128, int);
17672 The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal
17673 floating point rounding mode bits. The argument is a 3-bit value. The
17674 argument can either be a @code{const int} or the value can be stored in
17676 The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available.
17677 Otherwise the builtin reads the FPSCR, masks the current decimal rounding
17678 mode bits out and OR's in the new value.
17682 The following functions require @option{-mhard-float},
17683 @option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options.
17686 double __builtin_recipdiv (double, double);
17687 float __builtin_recipdivf (float, float);
17688 double __builtin_rsqrt (double);
17689 float __builtin_rsqrtf (float);
17692 The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and
17693 @code{__builtin_rsqrtf} functions generate multiple instructions to
17694 implement the reciprocal sqrt functionality using reciprocal sqrt
17695 estimate instructions.
17697 The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf}
17698 functions generate multiple instructions to implement division using
17699 the reciprocal estimate instructions.
17701 The following functions require @option{-mhard-float} and
17702 @option{-mmultiple} options.
17704 The @code{__builtin_unpack_longdouble} function takes a
17705 @code{long double} argument and a compile time constant of 0 or 1. If
17706 the constant is 0, the first @code{double} within the
17707 @code{long double} is returned, otherwise the second @code{double}
17708 is returned. The @code{__builtin_unpack_longdouble} function is only
17709 available if @code{long double} uses the IBM extended double
17712 The @code{__builtin_pack_longdouble} function takes two @code{double}
17713 arguments and returns a @code{long double} value that combines the two
17714 arguments. The @code{__builtin_pack_longdouble} function is only
17715 available if @code{long double} uses the IBM extended double
17718 The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128}
17719 argument and a compile time constant of 0 or 1. If the constant is 0,
17720 the first @code{double} within the @code{__ibm128} is returned,
17721 otherwise the second @code{double} is returned.
17723 The @code{__builtin_pack_ibm128} function takes two @code{double}
17724 arguments and returns a @code{__ibm128} value that combines the two
17727 Additional built-in functions are available for the 64-bit PowerPC
17728 family of processors, for efficient use of 128-bit floating point
17729 (@code{__float128}) values.
17731 @node Basic PowerPC Built-in Functions Available on ISA 2.06
17732 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06
17734 The basic built-in functions described in this section are
17735 available on the PowerPC family of processors starting with ISA 2.05
17736 or later. Unless specific options are explicitly disabled on the
17737 command line, specifying option @option{-mcpu=power7} has the effect of
17738 enabling all the same options as for @option{-mcpu=power6} in
17739 addition to the @option{-maltivec}, @option{-mpopcntd}, and
17740 @option{-mvsx} options.
17742 The following basic built-in functions require @option{-mpopcntd}:
17744 unsigned int __builtin_addg6s (unsigned int, unsigned int);
17745 long long __builtin_bpermd (long long, long long);
17746 unsigned int __builtin_cbcdtd (unsigned int);
17747 unsigned int __builtin_cdtbcd (unsigned int);
17748 long long __builtin_divde (long long, long long);
17749 unsigned long long __builtin_divdeu (unsigned long long, unsigned long long);
17750 int __builtin_divwe (int, int);
17751 unsigned int __builtin_divweu (unsigned int, unsigned int);
17752 vector __int128 __builtin_pack_vector_int128 (long long, long long);
17753 void __builtin_rs6000_speculation_barrier (void);
17754 long long __builtin_unpack_vector_int128 (vector __int128, signed char);
17757 Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions
17758 require a 64-bit environment.
17760 The following basic built-in functions, which are also supported on
17761 x86 targets, require @option{-mfloat128}.
17763 __float128 __builtin_fabsq (__float128);
17764 __float128 __builtin_copysignq (__float128, __float128);
17765 __float128 __builtin_infq (void);
17766 __float128 __builtin_huge_valq (void);
17767 __float128 __builtin_nanq (void);
17768 __float128 __builtin_nansq (void);
17770 __float128 __builtin_sqrtf128 (__float128);
17771 __float128 __builtin_fmaf128 (__float128, __float128, __float128);
17774 @node Basic PowerPC Built-in Functions Available on ISA 2.07
17775 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07
17777 The basic built-in functions described in this section are
17778 available on the PowerPC family of processors starting with ISA 2.07
17779 or later. Unless specific options are explicitly disabled on the
17780 command line, specifying option @option{-mcpu=power8} has the effect of
17781 enabling all the same options as for @option{-mcpu=power7} in
17782 addition to the @option{-mpower8-fusion}, @option{-mpower8-vector},
17783 @option{-mcrypto}, @option{-mhtm}, @option{-mquad-memory}, and
17784 @option{-mquad-memory-atomic} options.
17786 This section intentionally empty.
17788 @node Basic PowerPC Built-in Functions Available on ISA 3.0
17789 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0
17791 The basic built-in functions described in this section are
17792 available on the PowerPC family of processors starting with ISA 3.0
17793 or later. Unless specific options are explicitly disabled on the
17794 command line, specifying option @option{-mcpu=power9} has the effect of
17795 enabling all the same options as for @option{-mcpu=power8} in
17796 addition to the @option{-misel} option.
17798 The following built-in functions are available on Linux 64-bit systems
17799 that use the ISA 3.0 instruction set (@option{-mcpu=power9}):
17802 @item __float128 __builtin_addf128_round_to_odd (__float128, __float128)
17803 Perform a 128-bit IEEE floating point add using round to odd as the
17805 @findex __builtin_addf128_round_to_odd
17807 @item __float128 __builtin_subf128_round_to_odd (__float128, __float128)
17808 Perform a 128-bit IEEE floating point subtract using round to odd as
17810 @findex __builtin_subf128_round_to_odd
17812 @item __float128 __builtin_mulf128_round_to_odd (__float128, __float128)
17813 Perform a 128-bit IEEE floating point multiply using round to odd as
17815 @findex __builtin_mulf128_round_to_odd
17817 @item __float128 __builtin_divf128_round_to_odd (__float128, __float128)
17818 Perform a 128-bit IEEE floating point divide using round to odd as
17820 @findex __builtin_divf128_round_to_odd
17822 @item __float128 __builtin_sqrtf128_round_to_odd (__float128)
17823 Perform a 128-bit IEEE floating point square root using round to odd
17824 as the rounding mode.
17825 @findex __builtin_sqrtf128_round_to_odd
17827 @item __float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128)
17828 Perform a 128-bit IEEE floating point fused multiply and add operation
17829 using round to odd as the rounding mode.
17830 @findex __builtin_fmaf128_round_to_odd
17832 @item double __builtin_truncf128_round_to_odd (__float128)
17833 Convert a 128-bit IEEE floating point value to @code{double} using
17834 round to odd as the rounding mode.
17835 @findex __builtin_truncf128_round_to_odd
17838 The following additional built-in functions are also available for the
17839 PowerPC family of processors, starting with ISA 3.0 or later:
17841 long long __builtin_darn (void);
17842 long long __builtin_darn_raw (void);
17843 int __builtin_darn_32 (void);
17846 The @code{__builtin_darn} and @code{__builtin_darn_raw}
17847 functions require a
17848 64-bit environment supporting ISA 3.0 or later.
17849 The @code{__builtin_darn} function provides a 64-bit conditioned
17850 random number. The @code{__builtin_darn_raw} function provides a
17851 64-bit raw random number. The @code{__builtin_darn_32} function
17852 provides a 32-bit conditioned random number.
17854 The following additional built-in functions are also available for the
17855 PowerPC family of processors, starting with ISA 3.0 or later:
17858 int __builtin_byte_in_set (unsigned char u, unsigned long long set);
17859 int __builtin_byte_in_range (unsigned char u, unsigned int range);
17860 int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges);
17862 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value);
17863 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value);
17864 int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value);
17865 int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value);
17867 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value);
17868 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value);
17869 int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value);
17870 int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value);
17872 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value);
17873 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value);
17874 int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value);
17875 int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value);
17877 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value);
17878 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value);
17879 int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value);
17880 int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value);
17882 double __builtin_mffsl(void);
17885 The @code{__builtin_byte_in_set} function requires a
17886 64-bit environment supporting ISA 3.0 or later. This function returns
17887 a non-zero value if and only if its @code{u} argument exactly equals one of
17888 the eight bytes contained within its 64-bit @code{set} argument.
17890 The @code{__builtin_byte_in_range} and
17891 @code{__builtin_byte_in_either_range} require an environment
17892 supporting ISA 3.0 or later. For these two functions, the
17893 @code{range} argument is encoded as 4 bytes, organized as
17894 @code{hi_1:lo_1:hi_2:lo_2}.
17895 The @code{__builtin_byte_in_range} function returns a
17896 non-zero value if and only if its @code{u} argument is within the
17897 range bounded between @code{lo_2} and @code{hi_2} inclusive.
17898 The @code{__builtin_byte_in_either_range} function returns non-zero if
17899 and only if its @code{u} argument is within either the range bounded
17900 between @code{lo_1} and @code{hi_1} inclusive or the range bounded
17901 between @code{lo_2} and @code{hi_2} inclusive.
17903 The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value
17904 if and only if the number of signficant digits of its @code{value} argument
17905 is less than its @code{comparison} argument. The
17906 @code{__builtin_dfp_dtstsfi_lt_dd} and
17907 @code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but
17908 require that the type of the @code{value} argument be
17909 @code{__Decimal64} and @code{__Decimal128} respectively.
17911 The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value
17912 if and only if the number of signficant digits of its @code{value} argument
17913 is greater than its @code{comparison} argument. The
17914 @code{__builtin_dfp_dtstsfi_gt_dd} and
17915 @code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but
17916 require that the type of the @code{value} argument be
17917 @code{__Decimal64} and @code{__Decimal128} respectively.
17919 The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value
17920 if and only if the number of signficant digits of its @code{value} argument
17921 equals its @code{comparison} argument. The
17922 @code{__builtin_dfp_dtstsfi_eq_dd} and
17923 @code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but
17924 require that the type of the @code{value} argument be
17925 @code{__Decimal64} and @code{__Decimal128} respectively.
17927 The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value
17928 if and only if its @code{value} argument has an undefined number of
17929 significant digits, such as when @code{value} is an encoding of @code{NaN}.
17930 The @code{__builtin_dfp_dtstsfi_ov_dd} and
17931 @code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but
17932 require that the type of the @code{value} argument be
17933 @code{__Decimal64} and @code{__Decimal128} respectively.
17935 The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read
17936 the FPSCR. The instruction is a lower latency version of the @code{mffs}
17937 instruction. If the @code{mffsl} instruction is not available, then the
17938 builtin uses the older @code{mffs} instruction to read the FPSCR.
17940 @node Basic PowerPC Built-in Functions Available on ISA 3.1
17941 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.1
17943 The basic built-in functions described in this section are
17944 available on the PowerPC family of processors starting with ISA 3.1.
17945 Unless specific options are explicitly disabled on the
17946 command line, specifying option @option{-mcpu=power10} has the effect of
17947 enabling all the same options as for @option{-mcpu=power9}.
17949 The following built-in functions are available on Linux 64-bit systems
17950 that use a future architecture instruction set (@option{-mcpu=power10}):
17953 @exdent unsigned long long int
17954 @exdent __builtin_cfuged (unsigned long long int, unsigned long long int)
17956 Perform a 64-bit centrifuge operation, as if implemented by the
17957 @code{cfuged} instruction.
17958 @findex __builtin_cfuged
17961 @exdent unsigned long long int
17962 @exdent __builtin_cntlzdm (unsigned long long int, unsigned long long int)
17964 Perform a 64-bit count leading zeros operation under mask, as if
17965 implemented by the @code{cntlzdm} instruction.
17966 @findex __builtin_cntlzdm
17969 @exdent unsigned long long int
17970 @exdent __builtin_cnttzdm (unsigned long long int, unsigned long long int)
17972 Perform a 64-bit count trailing zeros operation under mask, as if
17973 implemented by the @code{cnttzdm} instruction.
17974 @findex __builtin_cnttzdm
17977 @exdent unsigned long long int
17978 @exdent __builtin_pdepd (unsigned long long int, unsigned long long int)
17980 Perform a 64-bit parallel bits deposit operation, as if implemented by the
17981 @code{pdepd} instruction.
17982 @findex __builtin_pdepd
17985 @exdent unsigned long long int
17986 @exdent __builtin_pextd (unsigned long long int, unsigned long long int)
17988 Perform a 64-bit parallel bits extract operation, as if implemented by the
17989 @code{pextd} instruction.
17990 @findex __builtin_pextd
17993 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed char *);
17994 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed short *);
17995 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed int *);
17996 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed long long *);
17997 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned char *);
17998 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned short *);
17999 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned int *);
18000 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned long long *);
18003 Load (and sign extend) to an __int128 vector, as if implemented by the ISA 3.1
18004 @code{lxvrbx} @code{lxvrhx} @code{lxvrwx} @code{lxvrdx} instructions.
18005 @findex vsx_xl_sext
18006 @findex vsx_xl_zext
18009 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed char *);
18010 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed short *);
18011 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed int *);
18012 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed long long *);
18013 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned char *);
18014 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned short *);
18015 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned int *);
18016 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned long long *);
18019 Truncate and store the rightmost element of a vector, as if implemented by the
18020 ISA 3.1 @code{stxvrbx} @code{stxvrhx} @code{stxvrwx} @code{stxvrdx} instructions.
18021 @findex vec_xst_trunc
18023 @node PowerPC AltiVec/VSX Built-in Functions
18024 @subsection PowerPC AltiVec/VSX Built-in Functions
18026 GCC provides an interface for the PowerPC family of processors to access
18027 the AltiVec operations described in Motorola's AltiVec Programming
18028 Interface Manual. The interface is made available by including
18029 @code{<altivec.h>} and using @option{-maltivec} and
18030 @option{-mabi=altivec}. The interface supports the following vector
18034 vector unsigned char
18038 vector unsigned short
18039 vector signed short
18043 vector unsigned int
18049 GCC's implementation of the high-level language interface available from
18050 C and C++ code differs from Motorola's documentation in several ways.
18055 A vector constant is a list of constant expressions within curly braces.
18058 A vector initializer requires no cast if the vector constant is of the
18059 same type as the variable it is initializing.
18062 If @code{signed} or @code{unsigned} is omitted, the signedness of the
18063 vector type is the default signedness of the base type. The default
18064 varies depending on the operating system, so a portable program should
18065 always specify the signedness.
18068 Compiling with @option{-maltivec} adds keywords @code{__vector},
18069 @code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and
18070 @code{bool}. When compiling ISO C, the context-sensitive substitution
18071 of the keywords @code{vector}, @code{pixel} and @code{bool} is
18072 disabled. To use them, you must include @code{<altivec.h>} instead.
18075 GCC allows using a @code{typedef} name as the type specifier for a
18076 vector type, but only under the following circumstances:
18081 When using @code{__vector} instead of @code{vector}; for example,
18084 typedef signed short int16;
18085 __vector int16 data;
18089 When using @code{vector} in keyword-and-predefine mode; for example,
18092 typedef signed short int16;
18096 Note that keyword-and-predefine mode is enabled by disabling GNU
18097 extensions (e.g., by using @code{-std=c11}) and including
18098 @code{<altivec.h>}.
18102 For C, overloaded functions are implemented with macros so the following
18106 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo);
18110 Since @code{vec_add} is a macro, the vector constant in the example
18111 is treated as four separate arguments. Wrap the entire argument in
18112 parentheses for this to work.
18115 @emph{Note:} Only the @code{<altivec.h>} interface is supported.
18116 Internally, GCC uses built-in functions to achieve the functionality in
18117 the aforementioned header file, but they are not supported and are
18118 subject to change without notice.
18120 GCC complies with the OpenPOWER 64-Bit ELF V2 ABI Specification,
18121 which may be found at
18122 @uref{https://openpowerfoundation.org/?resource_lib=64-bit-elf-v2-abi-specification-power-architecture}.
18123 Appendix A of this document lists the vector API interfaces that must be
18124 provided by compliant compilers. Programmers should preferentially use
18125 the interfaces described therein. However, historically GCC has provided
18126 additional interfaces for access to vector instructions. These are
18127 briefly described below.
18130 * PowerPC AltiVec Built-in Functions on ISA 2.05::
18131 * PowerPC AltiVec Built-in Functions Available on ISA 2.06::
18132 * PowerPC AltiVec Built-in Functions Available on ISA 2.07::
18133 * PowerPC AltiVec Built-in Functions Available on ISA 3.0::
18134 * PowerPC AltiVec Built-in Functions Available on ISA 3.1::
18137 @node PowerPC AltiVec Built-in Functions on ISA 2.05
18138 @subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05
18140 The following interfaces are supported for the generic and specific
18141 AltiVec operations and the AltiVec predicates. In cases where there
18142 is a direct mapping between generic and specific operations, only the
18143 generic names are shown here, although the specific operations can also
18146 Arguments that are documented as @code{const int} require literal
18147 integral values within the range required for that operation.
18150 vector signed char vec_abs (vector signed char);
18151 vector signed short vec_abs (vector signed short);
18152 vector signed int vec_abs (vector signed int);
18153 vector float vec_abs (vector float);
18155 vector signed char vec_abss (vector signed char);
18156 vector signed short vec_abss (vector signed short);
18157 vector signed int vec_abss (vector signed int);
18159 vector signed char vec_add (vector bool char, vector signed char);
18160 vector signed char vec_add (vector signed char, vector bool char);
18161 vector signed char vec_add (vector signed char, vector signed char);
18162 vector unsigned char vec_add (vector bool char, vector unsigned char);
18163 vector unsigned char vec_add (vector unsigned char, vector bool char);
18164 vector unsigned char vec_add (vector unsigned char, vector unsigned char);
18165 vector signed short vec_add (vector bool short, vector signed short);
18166 vector signed short vec_add (vector signed short, vector bool short);
18167 vector signed short vec_add (vector signed short, vector signed short);
18168 vector unsigned short vec_add (vector bool short, vector unsigned short);
18169 vector unsigned short vec_add (vector unsigned short, vector bool short);
18170 vector unsigned short vec_add (vector unsigned short, vector unsigned short);
18171 vector signed int vec_add (vector bool int, vector signed int);
18172 vector signed int vec_add (vector signed int, vector bool int);
18173 vector signed int vec_add (vector signed int, vector signed int);
18174 vector unsigned int vec_add (vector bool int, vector unsigned int);
18175 vector unsigned int vec_add (vector unsigned int, vector bool int);
18176 vector unsigned int vec_add (vector unsigned int, vector unsigned int);
18177 vector float vec_add (vector float, vector float);
18179 vector unsigned int vec_addc (vector unsigned int, vector unsigned int);
18181 vector unsigned char vec_adds (vector bool char, vector unsigned char);
18182 vector unsigned char vec_adds (vector unsigned char, vector bool char);
18183 vector unsigned char vec_adds (vector unsigned char, vector unsigned char);
18184 vector signed char vec_adds (vector bool char, vector signed char);
18185 vector signed char vec_adds (vector signed char, vector bool char);
18186 vector signed char vec_adds (vector signed char, vector signed char);
18187 vector unsigned short vec_adds (vector bool short, vector unsigned short);
18188 vector unsigned short vec_adds (vector unsigned short, vector bool short);
18189 vector unsigned short vec_adds (vector unsigned short, vector unsigned short);
18190 vector signed short vec_adds (vector bool short, vector signed short);
18191 vector signed short vec_adds (vector signed short, vector bool short);
18192 vector signed short vec_adds (vector signed short, vector signed short);
18193 vector unsigned int vec_adds (vector bool int, vector unsigned int);
18194 vector unsigned int vec_adds (vector unsigned int, vector bool int);
18195 vector unsigned int vec_adds (vector unsigned int, vector unsigned int);
18196 vector signed int vec_adds (vector bool int, vector signed int);
18197 vector signed int vec_adds (vector signed int, vector bool int);
18198 vector signed int vec_adds (vector signed int, vector signed int);
18200 int vec_all_eq (vector signed char, vector bool char);
18201 int vec_all_eq (vector signed char, vector signed char);
18202 int vec_all_eq (vector unsigned char, vector bool char);
18203 int vec_all_eq (vector unsigned char, vector unsigned char);
18204 int vec_all_eq (vector bool char, vector bool char);
18205 int vec_all_eq (vector bool char, vector unsigned char);
18206 int vec_all_eq (vector bool char, vector signed char);
18207 int vec_all_eq (vector signed short, vector bool short);
18208 int vec_all_eq (vector signed short, vector signed short);
18209 int vec_all_eq (vector unsigned short, vector bool short);
18210 int vec_all_eq (vector unsigned short, vector unsigned short);
18211 int vec_all_eq (vector bool short, vector bool short);
18212 int vec_all_eq (vector bool short, vector unsigned short);
18213 int vec_all_eq (vector bool short, vector signed short);
18214 int vec_all_eq (vector pixel, vector pixel);
18215 int vec_all_eq (vector signed int, vector bool int);
18216 int vec_all_eq (vector signed int, vector signed int);
18217 int vec_all_eq (vector unsigned int, vector bool int);
18218 int vec_all_eq (vector unsigned int, vector unsigned int);
18219 int vec_all_eq (vector bool int, vector bool int);
18220 int vec_all_eq (vector bool int, vector unsigned int);
18221 int vec_all_eq (vector bool int, vector signed int);
18222 int vec_all_eq (vector float, vector float);
18224 int vec_all_ge (vector bool char, vector unsigned char);
18225 int vec_all_ge (vector unsigned char, vector bool char);
18226 int vec_all_ge (vector unsigned char, vector unsigned char);
18227 int vec_all_ge (vector bool char, vector signed char);
18228 int vec_all_ge (vector signed char, vector bool char);
18229 int vec_all_ge (vector signed char, vector signed char);
18230 int vec_all_ge (vector bool short, vector unsigned short);
18231 int vec_all_ge (vector unsigned short, vector bool short);
18232 int vec_all_ge (vector unsigned short, vector unsigned short);
18233 int vec_all_ge (vector signed short, vector signed short);
18234 int vec_all_ge (vector bool short, vector signed short);
18235 int vec_all_ge (vector signed short, vector bool short);
18236 int vec_all_ge (vector bool int, vector unsigned int);
18237 int vec_all_ge (vector unsigned int, vector bool int);
18238 int vec_all_ge (vector unsigned int, vector unsigned int);
18239 int vec_all_ge (vector bool int, vector signed int);
18240 int vec_all_ge (vector signed int, vector bool int);
18241 int vec_all_ge (vector signed int, vector signed int);
18242 int vec_all_ge (vector float, vector float);
18244 int vec_all_gt (vector bool char, vector unsigned char);
18245 int vec_all_gt (vector unsigned char, vector bool char);
18246 int vec_all_gt (vector unsigned char, vector unsigned char);
18247 int vec_all_gt (vector bool char, vector signed char);
18248 int vec_all_gt (vector signed char, vector bool char);
18249 int vec_all_gt (vector signed char, vector signed char);
18250 int vec_all_gt (vector bool short, vector unsigned short);
18251 int vec_all_gt (vector unsigned short, vector bool short);
18252 int vec_all_gt (vector unsigned short, vector unsigned short);
18253 int vec_all_gt (vector bool short, vector signed short);
18254 int vec_all_gt (vector signed short, vector bool short);
18255 int vec_all_gt (vector signed short, vector signed short);
18256 int vec_all_gt (vector bool int, vector unsigned int);
18257 int vec_all_gt (vector unsigned int, vector bool int);
18258 int vec_all_gt (vector unsigned int, vector unsigned int);
18259 int vec_all_gt (vector bool int, vector signed int);
18260 int vec_all_gt (vector signed int, vector bool int);
18261 int vec_all_gt (vector signed int, vector signed int);
18262 int vec_all_gt (vector float, vector float);
18264 int vec_all_in (vector float, vector float);
18266 int vec_all_le (vector bool char, vector unsigned char);
18267 int vec_all_le (vector unsigned char, vector bool char);
18268 int vec_all_le (vector unsigned char, vector unsigned char);
18269 int vec_all_le (vector bool char, vector signed char);
18270 int vec_all_le (vector signed char, vector bool char);
18271 int vec_all_le (vector signed char, vector signed char);
18272 int vec_all_le (vector bool short, vector unsigned short);
18273 int vec_all_le (vector unsigned short, vector bool short);
18274 int vec_all_le (vector unsigned short, vector unsigned short);
18275 int vec_all_le (vector bool short, vector signed short);
18276 int vec_all_le (vector signed short, vector bool short);
18277 int vec_all_le (vector signed short, vector signed short);
18278 int vec_all_le (vector bool int, vector unsigned int);
18279 int vec_all_le (vector unsigned int, vector bool int);
18280 int vec_all_le (vector unsigned int, vector unsigned int);
18281 int vec_all_le (vector bool int, vector signed int);
18282 int vec_all_le (vector signed int, vector bool int);
18283 int vec_all_le (vector signed int, vector signed int);
18284 int vec_all_le (vector float, vector float);
18286 int vec_all_lt (vector bool char, vector unsigned char);
18287 int vec_all_lt (vector unsigned char, vector bool char);
18288 int vec_all_lt (vector unsigned char, vector unsigned char);
18289 int vec_all_lt (vector bool char, vector signed char);
18290 int vec_all_lt (vector signed char, vector bool char);
18291 int vec_all_lt (vector signed char, vector signed char);
18292 int vec_all_lt (vector bool short, vector unsigned short);
18293 int vec_all_lt (vector unsigned short, vector bool short);
18294 int vec_all_lt (vector unsigned short, vector unsigned short);
18295 int vec_all_lt (vector bool short, vector signed short);
18296 int vec_all_lt (vector signed short, vector bool short);
18297 int vec_all_lt (vector signed short, vector signed short);
18298 int vec_all_lt (vector bool int, vector unsigned int);
18299 int vec_all_lt (vector unsigned int, vector bool int);
18300 int vec_all_lt (vector unsigned int, vector unsigned int);
18301 int vec_all_lt (vector bool int, vector signed int);
18302 int vec_all_lt (vector signed int, vector bool int);
18303 int vec_all_lt (vector signed int, vector signed int);
18304 int vec_all_lt (vector float, vector float);
18306 int vec_all_nan (vector float);
18308 int vec_all_ne (vector signed char, vector bool char);
18309 int vec_all_ne (vector signed char, vector signed char);
18310 int vec_all_ne (vector unsigned char, vector bool char);
18311 int vec_all_ne (vector unsigned char, vector unsigned char);
18312 int vec_all_ne (vector bool char, vector bool char);
18313 int vec_all_ne (vector bool char, vector unsigned char);
18314 int vec_all_ne (vector bool char, vector signed char);
18315 int vec_all_ne (vector signed short, vector bool short);
18316 int vec_all_ne (vector signed short, vector signed short);
18317 int vec_all_ne (vector unsigned short, vector bool short);
18318 int vec_all_ne (vector unsigned short, vector unsigned short);
18319 int vec_all_ne (vector bool short, vector bool short);
18320 int vec_all_ne (vector bool short, vector unsigned short);
18321 int vec_all_ne (vector bool short, vector signed short);
18322 int vec_all_ne (vector pixel, vector pixel);
18323 int vec_all_ne (vector signed int, vector bool int);
18324 int vec_all_ne (vector signed int, vector signed int);
18325 int vec_all_ne (vector unsigned int, vector bool int);
18326 int vec_all_ne (vector unsigned int, vector unsigned int);
18327 int vec_all_ne (vector bool int, vector bool int);
18328 int vec_all_ne (vector bool int, vector unsigned int);
18329 int vec_all_ne (vector bool int, vector signed int);
18330 int vec_all_ne (vector float, vector float);
18332 int vec_all_nge (vector float, vector float);
18334 int vec_all_ngt (vector float, vector float);
18336 int vec_all_nle (vector float, vector float);
18338 int vec_all_nlt (vector float, vector float);
18340 int vec_all_numeric (vector float);
18342 vector float vec_and (vector float, vector float);
18343 vector float vec_and (vector float, vector bool int);
18344 vector float vec_and (vector bool int, vector float);
18345 vector bool int vec_and (vector bool int, vector bool int);
18346 vector signed int vec_and (vector bool int, vector signed int);
18347 vector signed int vec_and (vector signed int, vector bool int);
18348 vector signed int vec_and (vector signed int, vector signed int);
18349 vector unsigned int vec_and (vector bool int, vector unsigned int);
18350 vector unsigned int vec_and (vector unsigned int, vector bool int);
18351 vector unsigned int vec_and (vector unsigned int, vector unsigned int);
18352 vector bool short vec_and (vector bool short, vector bool short);
18353 vector signed short vec_and (vector bool short, vector signed short);
18354 vector signed short vec_and (vector signed short, vector bool short);
18355 vector signed short vec_and (vector signed short, vector signed short);
18356 vector unsigned short vec_and (vector bool short, vector unsigned short);
18357 vector unsigned short vec_and (vector unsigned short, vector bool short);
18358 vector unsigned short vec_and (vector unsigned short, vector unsigned short);
18359 vector signed char vec_and (vector bool char, vector signed char);
18360 vector bool char vec_and (vector bool char, vector bool char);
18361 vector signed char vec_and (vector signed char, vector bool char);
18362 vector signed char vec_and (vector signed char, vector signed char);
18363 vector unsigned char vec_and (vector bool char, vector unsigned char);
18364 vector unsigned char vec_and (vector unsigned char, vector bool char);
18365 vector unsigned char vec_and (vector unsigned char, vector unsigned char);
18367 vector float vec_andc (vector float, vector float);
18368 vector float vec_andc (vector float, vector bool int);
18369 vector float vec_andc (vector bool int, vector float);
18370 vector bool int vec_andc (vector bool int, vector bool int);
18371 vector signed int vec_andc (vector bool int, vector signed int);
18372 vector signed int vec_andc (vector signed int, vector bool int);
18373 vector signed int vec_andc (vector signed int, vector signed int);
18374 vector unsigned int vec_andc (vector bool int, vector unsigned int);
18375 vector unsigned int vec_andc (vector unsigned int, vector bool int);
18376 vector unsigned int vec_andc (vector unsigned int, vector unsigned int);
18377 vector bool short vec_andc (vector bool short, vector bool short);
18378 vector signed short vec_andc (vector bool short, vector signed short);
18379 vector signed short vec_andc (vector signed short, vector bool short);
18380 vector signed short vec_andc (vector signed short, vector signed short);
18381 vector unsigned short vec_andc (vector bool short, vector unsigned short);
18382 vector unsigned short vec_andc (vector unsigned short, vector bool short);
18383 vector unsigned short vec_andc (vector unsigned short, vector unsigned short);
18384 vector signed char vec_andc (vector bool char, vector signed char);
18385 vector bool char vec_andc (vector bool char, vector bool char);
18386 vector signed char vec_andc (vector signed char, vector bool char);
18387 vector signed char vec_andc (vector signed char, vector signed char);
18388 vector unsigned char vec_andc (vector bool char, vector unsigned char);
18389 vector unsigned char vec_andc (vector unsigned char, vector bool char);
18390 vector unsigned char vec_andc (vector unsigned char, vector unsigned char);
18392 int vec_any_eq (vector signed char, vector bool char);
18393 int vec_any_eq (vector signed char, vector signed char);
18394 int vec_any_eq (vector unsigned char, vector bool char);
18395 int vec_any_eq (vector unsigned char, vector unsigned char);
18396 int vec_any_eq (vector bool char, vector bool char);
18397 int vec_any_eq (vector bool char, vector unsigned char);
18398 int vec_any_eq (vector bool char, vector signed char);
18399 int vec_any_eq (vector signed short, vector bool short);
18400 int vec_any_eq (vector signed short, vector signed short);
18401 int vec_any_eq (vector unsigned short, vector bool short);
18402 int vec_any_eq (vector unsigned short, vector unsigned short);
18403 int vec_any_eq (vector bool short, vector bool short);
18404 int vec_any_eq (vector bool short, vector unsigned short);
18405 int vec_any_eq (vector bool short, vector signed short);
18406 int vec_any_eq (vector pixel, vector pixel);
18407 int vec_any_eq (vector signed int, vector bool int);
18408 int vec_any_eq (vector signed int, vector signed int);
18409 int vec_any_eq (vector unsigned int, vector bool int);
18410 int vec_any_eq (vector unsigned int, vector unsigned int);
18411 int vec_any_eq (vector bool int, vector bool int);
18412 int vec_any_eq (vector bool int, vector unsigned int);
18413 int vec_any_eq (vector bool int, vector signed int);
18414 int vec_any_eq (vector float, vector float);
18416 int vec_any_ge (vector signed char, vector bool char);
18417 int vec_any_ge (vector unsigned char, vector bool char);
18418 int vec_any_ge (vector unsigned char, vector unsigned char);
18419 int vec_any_ge (vector signed char, vector signed char);
18420 int vec_any_ge (vector bool char, vector unsigned char);
18421 int vec_any_ge (vector bool char, vector signed char);
18422 int vec_any_ge (vector unsigned short, vector bool short);
18423 int vec_any_ge (vector unsigned short, vector unsigned short);
18424 int vec_any_ge (vector signed short, vector signed short);
18425 int vec_any_ge (vector signed short, vector bool short);
18426 int vec_any_ge (vector bool short, vector unsigned short);
18427 int vec_any_ge (vector bool short, vector signed short);
18428 int vec_any_ge (vector signed int, vector bool int);
18429 int vec_any_ge (vector unsigned int, vector bool int);
18430 int vec_any_ge (vector unsigned int, vector unsigned int);
18431 int vec_any_ge (vector signed int, vector signed int);
18432 int vec_any_ge (vector bool int, vector unsigned int);
18433 int vec_any_ge (vector bool int, vector signed int);
18434 int vec_any_ge (vector float, vector float);
18436 int vec_any_gt (vector bool char, vector unsigned char);
18437 int vec_any_gt (vector unsigned char, vector bool char);
18438 int vec_any_gt (vector unsigned char, vector unsigned char);
18439 int vec_any_gt (vector bool char, vector signed char);
18440 int vec_any_gt (vector signed char, vector bool char);
18441 int vec_any_gt (vector signed char, vector signed char);
18442 int vec_any_gt (vector bool short, vector unsigned short);
18443 int vec_any_gt (vector unsigned short, vector bool short);
18444 int vec_any_gt (vector unsigned short, vector unsigned short);
18445 int vec_any_gt (vector bool short, vector signed short);
18446 int vec_any_gt (vector signed short, vector bool short);
18447 int vec_any_gt (vector signed short, vector signed short);
18448 int vec_any_gt (vector bool int, vector unsigned int);
18449 int vec_any_gt (vector unsigned int, vector bool int);
18450 int vec_any_gt (vector unsigned int, vector unsigned int);
18451 int vec_any_gt (vector bool int, vector signed int);
18452 int vec_any_gt (vector signed int, vector bool int);
18453 int vec_any_gt (vector signed int, vector signed int);
18454 int vec_any_gt (vector float, vector float);
18456 int vec_any_le (vector bool char, vector unsigned char);
18457 int vec_any_le (vector unsigned char, vector bool char);
18458 int vec_any_le (vector unsigned char, vector unsigned char);
18459 int vec_any_le (vector bool char, vector signed char);
18460 int vec_any_le (vector signed char, vector bool char);
18461 int vec_any_le (vector signed char, vector signed char);
18462 int vec_any_le (vector bool short, vector unsigned short);
18463 int vec_any_le (vector unsigned short, vector bool short);
18464 int vec_any_le (vector unsigned short, vector unsigned short);
18465 int vec_any_le (vector bool short, vector signed short);
18466 int vec_any_le (vector signed short, vector bool short);
18467 int vec_any_le (vector signed short, vector signed short);
18468 int vec_any_le (vector bool int, vector unsigned int);
18469 int vec_any_le (vector unsigned int, vector bool int);
18470 int vec_any_le (vector unsigned int, vector unsigned int);
18471 int vec_any_le (vector bool int, vector signed int);
18472 int vec_any_le (vector signed int, vector bool int);
18473 int vec_any_le (vector signed int, vector signed int);
18474 int vec_any_le (vector float, vector float);
18476 int vec_any_lt (vector bool char, vector unsigned char);
18477 int vec_any_lt (vector unsigned char, vector bool char);
18478 int vec_any_lt (vector unsigned char, vector unsigned char);
18479 int vec_any_lt (vector bool char, vector signed char);
18480 int vec_any_lt (vector signed char, vector bool char);
18481 int vec_any_lt (vector signed char, vector signed char);
18482 int vec_any_lt (vector bool short, vector unsigned short);
18483 int vec_any_lt (vector unsigned short, vector bool short);
18484 int vec_any_lt (vector unsigned short, vector unsigned short);
18485 int vec_any_lt (vector bool short, vector signed short);
18486 int vec_any_lt (vector signed short, vector bool short);
18487 int vec_any_lt (vector signed short, vector signed short);
18488 int vec_any_lt (vector bool int, vector unsigned int);
18489 int vec_any_lt (vector unsigned int, vector bool int);
18490 int vec_any_lt (vector unsigned int, vector unsigned int);
18491 int vec_any_lt (vector bool int, vector signed int);
18492 int vec_any_lt (vector signed int, vector bool int);
18493 int vec_any_lt (vector signed int, vector signed int);
18494 int vec_any_lt (vector float, vector float);
18496 int vec_any_nan (vector float);
18498 int vec_any_ne (vector signed char, vector bool char);
18499 int vec_any_ne (vector signed char, vector signed char);
18500 int vec_any_ne (vector unsigned char, vector bool char);
18501 int vec_any_ne (vector unsigned char, vector unsigned char);
18502 int vec_any_ne (vector bool char, vector bool char);
18503 int vec_any_ne (vector bool char, vector unsigned char);
18504 int vec_any_ne (vector bool char, vector signed char);
18505 int vec_any_ne (vector signed short, vector bool short);
18506 int vec_any_ne (vector signed short, vector signed short);
18507 int vec_any_ne (vector unsigned short, vector bool short);
18508 int vec_any_ne (vector unsigned short, vector unsigned short);
18509 int vec_any_ne (vector bool short, vector bool short);
18510 int vec_any_ne (vector bool short, vector unsigned short);
18511 int vec_any_ne (vector bool short, vector signed short);
18512 int vec_any_ne (vector pixel, vector pixel);
18513 int vec_any_ne (vector signed int, vector bool int);
18514 int vec_any_ne (vector signed int, vector signed int);
18515 int vec_any_ne (vector unsigned int, vector bool int);
18516 int vec_any_ne (vector unsigned int, vector unsigned int);
18517 int vec_any_ne (vector bool int, vector bool int);
18518 int vec_any_ne (vector bool int, vector unsigned int);
18519 int vec_any_ne (vector bool int, vector signed int);
18520 int vec_any_ne (vector float, vector float);
18522 int vec_any_nge (vector float, vector float);
18524 int vec_any_ngt (vector float, vector float);
18526 int vec_any_nle (vector float, vector float);
18528 int vec_any_nlt (vector float, vector float);
18530 int vec_any_numeric (vector float);
18532 int vec_any_out (vector float, vector float);
18534 vector unsigned char vec_avg (vector unsigned char, vector unsigned char);
18535 vector signed char vec_avg (vector signed char, vector signed char);
18536 vector unsigned short vec_avg (vector unsigned short, vector unsigned short);
18537 vector signed short vec_avg (vector signed short, vector signed short);
18538 vector unsigned int vec_avg (vector unsigned int, vector unsigned int);
18539 vector signed int vec_avg (vector signed int, vector signed int);
18541 vector float vec_ceil (vector float);
18543 vector signed int vec_cmpb (vector float, vector float);
18545 vector bool char vec_cmpeq (vector bool char, vector bool char);
18546 vector bool short vec_cmpeq (vector bool short, vector bool short);
18547 vector bool int vec_cmpeq (vector bool int, vector bool int);
18548 vector bool char vec_cmpeq (vector signed char, vector signed char);
18549 vector bool char vec_cmpeq (vector unsigned char, vector unsigned char);
18550 vector bool short vec_cmpeq (vector signed short, vector signed short);
18551 vector bool short vec_cmpeq (vector unsigned short, vector unsigned short);
18552 vector bool int vec_cmpeq (vector signed int, vector signed int);
18553 vector bool int vec_cmpeq (vector unsigned int, vector unsigned int);
18554 vector bool int vec_cmpeq (vector float, vector float);
18556 vector bool int vec_cmpge (vector float, vector float);
18558 vector bool char vec_cmpgt (vector unsigned char, vector unsigned char);
18559 vector bool char vec_cmpgt (vector signed char, vector signed char);
18560 vector bool short vec_cmpgt (vector unsigned short, vector unsigned short);
18561 vector bool short vec_cmpgt (vector signed short, vector signed short);
18562 vector bool int vec_cmpgt (vector unsigned int, vector unsigned int);
18563 vector bool int vec_cmpgt (vector signed int, vector signed int);
18564 vector bool int vec_cmpgt (vector float, vector float);
18566 vector bool int vec_cmple (vector float, vector float);
18568 vector bool char vec_cmplt (vector unsigned char, vector unsigned char);
18569 vector bool char vec_cmplt (vector signed char, vector signed char);
18570 vector bool short vec_cmplt (vector unsigned short, vector unsigned short);
18571 vector bool short vec_cmplt (vector signed short, vector signed short);
18572 vector bool int vec_cmplt (vector unsigned int, vector unsigned int);
18573 vector bool int vec_cmplt (vector signed int, vector signed int);
18574 vector bool int vec_cmplt (vector float, vector float);
18576 vector float vec_cpsgn (vector float, vector float);
18578 vector float vec_ctf (vector unsigned int, const int);
18579 vector float vec_ctf (vector signed int, const int);
18581 vector signed int vec_cts (vector float, const int);
18583 vector unsigned int vec_ctu (vector float, const int);
18585 void vec_dss (const int);
18587 void vec_dssall (void);
18589 void vec_dst (const vector unsigned char *, int, const int);
18590 void vec_dst (const vector signed char *, int, const int);
18591 void vec_dst (const vector bool char *, int, const int);
18592 void vec_dst (const vector unsigned short *, int, const int);
18593 void vec_dst (const vector signed short *, int, const int);
18594 void vec_dst (const vector bool short *, int, const int);
18595 void vec_dst (const vector pixel *, int, const int);
18596 void vec_dst (const vector unsigned int *, int, const int);
18597 void vec_dst (const vector signed int *, int, const int);
18598 void vec_dst (const vector bool int *, int, const int);
18599 void vec_dst (const vector float *, int, const int);
18600 void vec_dst (const unsigned char *, int, const int);
18601 void vec_dst (const signed char *, int, const int);
18602 void vec_dst (const unsigned short *, int, const int);
18603 void vec_dst (const short *, int, const int);
18604 void vec_dst (const unsigned int *, int, const int);
18605 void vec_dst (const int *, int, const int);
18606 void vec_dst (const float *, int, const int);
18608 void vec_dstst (const vector unsigned char *, int, const int);
18609 void vec_dstst (const vector signed char *, int, const int);
18610 void vec_dstst (const vector bool char *, int, const int);
18611 void vec_dstst (const vector unsigned short *, int, const int);
18612 void vec_dstst (const vector signed short *, int, const int);
18613 void vec_dstst (const vector bool short *, int, const int);
18614 void vec_dstst (const vector pixel *, int, const int);
18615 void vec_dstst (const vector unsigned int *, int, const int);
18616 void vec_dstst (const vector signed int *, int, const int);
18617 void vec_dstst (const vector bool int *, int, const int);
18618 void vec_dstst (const vector float *, int, const int);
18619 void vec_dstst (const unsigned char *, int, const int);
18620 void vec_dstst (const signed char *, int, const int);
18621 void vec_dstst (const unsigned short *, int, const int);
18622 void vec_dstst (const short *, int, const int);
18623 void vec_dstst (const unsigned int *, int, const int);
18624 void vec_dstst (const int *, int, const int);
18625 void vec_dstst (const unsigned long *, int, const int);
18626 void vec_dstst (const long *, int, const int);
18627 void vec_dstst (const float *, int, const int);
18629 void vec_dststt (const vector unsigned char *, int, const int);
18630 void vec_dststt (const vector signed char *, int, const int);
18631 void vec_dststt (const vector bool char *, int, const int);
18632 void vec_dststt (const vector unsigned short *, int, const int);
18633 void vec_dststt (const vector signed short *, int, const int);
18634 void vec_dststt (const vector bool short *, int, const int);
18635 void vec_dststt (const vector pixel *, int, const int);
18636 void vec_dststt (const vector unsigned int *, int, const int);
18637 void vec_dststt (const vector signed int *, int, const int);
18638 void vec_dststt (const vector bool int *, int, const int);
18639 void vec_dststt (const vector float *, int, const int);
18640 void vec_dststt (const unsigned char *, int, const int);
18641 void vec_dststt (const signed char *, int, const int);
18642 void vec_dststt (const unsigned short *, int, const int);
18643 void vec_dststt (const short *, int, const int);
18644 void vec_dststt (const unsigned int *, int, const int);
18645 void vec_dststt (const int *, int, const int);
18646 void vec_dststt (const float *, int, const int);
18648 void vec_dstt (const vector unsigned char *, int, const int);
18649 void vec_dstt (const vector signed char *, int, const int);
18650 void vec_dstt (const vector bool char *, int, const int);
18651 void vec_dstt (const vector unsigned short *, int, const int);
18652 void vec_dstt (const vector signed short *, int, const int);
18653 void vec_dstt (const vector bool short *, int, const int);
18654 void vec_dstt (const vector pixel *, int, const int);
18655 void vec_dstt (const vector unsigned int *, int, const int);
18656 void vec_dstt (const vector signed int *, int, const int);
18657 void vec_dstt (const vector bool int *, int, const int);
18658 void vec_dstt (const vector float *, int, const int);
18659 void vec_dstt (const unsigned char *, int, const int);
18660 void vec_dstt (const signed char *, int, const int);
18661 void vec_dstt (const unsigned short *, int, const int);
18662 void vec_dstt (const short *, int, const int);
18663 void vec_dstt (const unsigned int *, int, const int);
18664 void vec_dstt (const int *, int, const int);
18665 void vec_dstt (const float *, int, const int);
18667 vector float vec_expte (vector float);
18669 vector float vec_floor (vector float);
18671 vector float vec_ld (int, const vector float *);
18672 vector float vec_ld (int, const float *);
18673 vector bool int vec_ld (int, const vector bool int *);
18674 vector signed int vec_ld (int, const vector signed int *);
18675 vector signed int vec_ld (int, const int *);
18676 vector unsigned int vec_ld (int, const vector unsigned int *);
18677 vector unsigned int vec_ld (int, const unsigned int *);
18678 vector bool short vec_ld (int, const vector bool short *);
18679 vector pixel vec_ld (int, const vector pixel *);
18680 vector signed short vec_ld (int, const vector signed short *);
18681 vector signed short vec_ld (int, const short *);
18682 vector unsigned short vec_ld (int, const vector unsigned short *);
18683 vector unsigned short vec_ld (int, const unsigned short *);
18684 vector bool char vec_ld (int, const vector bool char *);
18685 vector signed char vec_ld (int, const vector signed char *);
18686 vector signed char vec_ld (int, const signed char *);
18687 vector unsigned char vec_ld (int, const vector unsigned char *);
18688 vector unsigned char vec_ld (int, const unsigned char *);
18690 vector signed char vec_lde (int, const signed char *);
18691 vector unsigned char vec_lde (int, const unsigned char *);
18692 vector signed short vec_lde (int, const short *);
18693 vector unsigned short vec_lde (int, const unsigned short *);
18694 vector float vec_lde (int, const float *);
18695 vector signed int vec_lde (int, const int *);
18696 vector unsigned int vec_lde (int, const unsigned int *);
18698 vector float vec_ldl (int, const vector float *);
18699 vector float vec_ldl (int, const float *);
18700 vector bool int vec_ldl (int, const vector bool int *);
18701 vector signed int vec_ldl (int, const vector signed int *);
18702 vector signed int vec_ldl (int, const int *);
18703 vector unsigned int vec_ldl (int, const vector unsigned int *);
18704 vector unsigned int vec_ldl (int, const unsigned int *);
18705 vector bool short vec_ldl (int, const vector bool short *);
18706 vector pixel vec_ldl (int, const vector pixel *);
18707 vector signed short vec_ldl (int, const vector signed short *);
18708 vector signed short vec_ldl (int, const short *);
18709 vector unsigned short vec_ldl (int, const vector unsigned short *);
18710 vector unsigned short vec_ldl (int, const unsigned short *);
18711 vector bool char vec_ldl (int, const vector bool char *);
18712 vector signed char vec_ldl (int, const vector signed char *);
18713 vector signed char vec_ldl (int, const signed char *);
18714 vector unsigned char vec_ldl (int, const vector unsigned char *);
18715 vector unsigned char vec_ldl (int, const unsigned char *);
18717 vector float vec_loge (vector float);
18719 vector signed char vec_lvebx (int, char *);
18720 vector unsigned char vec_lvebx (int, unsigned char *);
18722 vector signed short vec_lvehx (int, short *);
18723 vector unsigned short vec_lvehx (int, unsigned short *);
18725 vector float vec_lvewx (int, float *);
18726 vector signed int vec_lvewx (int, int *);
18727 vector unsigned int vec_lvewx (int, unsigned int *);
18729 vector unsigned char vec_lvsl (int, const unsigned char *);
18730 vector unsigned char vec_lvsl (int, const signed char *);
18731 vector unsigned char vec_lvsl (int, const unsigned short *);
18732 vector unsigned char vec_lvsl (int, const short *);
18733 vector unsigned char vec_lvsl (int, const unsigned int *);
18734 vector unsigned char vec_lvsl (int, const int *);
18735 vector unsigned char vec_lvsl (int, const float *);
18737 vector unsigned char vec_lvsr (int, const unsigned char *);
18738 vector unsigned char vec_lvsr (int, const signed char *);
18739 vector unsigned char vec_lvsr (int, const unsigned short *);
18740 vector unsigned char vec_lvsr (int, const short *);
18741 vector unsigned char vec_lvsr (int, const unsigned int *);
18742 vector unsigned char vec_lvsr (int, const int *);
18743 vector unsigned char vec_lvsr (int, const float *);
18745 vector float vec_madd (vector float, vector float, vector float);
18747 vector signed short vec_madds (vector signed short, vector signed short,
18748 vector signed short);
18750 vector unsigned char vec_max (vector bool char, vector unsigned char);
18751 vector unsigned char vec_max (vector unsigned char, vector bool char);
18752 vector unsigned char vec_max (vector unsigned char, vector unsigned char);
18753 vector signed char vec_max (vector bool char, vector signed char);
18754 vector signed char vec_max (vector signed char, vector bool char);
18755 vector signed char vec_max (vector signed char, vector signed char);
18756 vector unsigned short vec_max (vector bool short, vector unsigned short);
18757 vector unsigned short vec_max (vector unsigned short, vector bool short);
18758 vector unsigned short vec_max (vector unsigned short, vector unsigned short);
18759 vector signed short vec_max (vector bool short, vector signed short);
18760 vector signed short vec_max (vector signed short, vector bool short);
18761 vector signed short vec_max (vector signed short, vector signed short);
18762 vector unsigned int vec_max (vector bool int, vector unsigned int);
18763 vector unsigned int vec_max (vector unsigned int, vector bool int);
18764 vector unsigned int vec_max (vector unsigned int, vector unsigned int);
18765 vector signed int vec_max (vector bool int, vector signed int);
18766 vector signed int vec_max (vector signed int, vector bool int);
18767 vector signed int vec_max (vector signed int, vector signed int);
18768 vector float vec_max (vector float, vector float);
18770 vector bool char vec_mergeh (vector bool char, vector bool char);
18771 vector signed char vec_mergeh (vector signed char, vector signed char);
18772 vector unsigned char vec_mergeh (vector unsigned char, vector unsigned char);
18773 vector bool short vec_mergeh (vector bool short, vector bool short);
18774 vector pixel vec_mergeh (vector pixel, vector pixel);
18775 vector signed short vec_mergeh (vector signed short, vector signed short);
18776 vector unsigned short vec_mergeh (vector unsigned short, vector unsigned short);
18777 vector float vec_mergeh (vector float, vector float);
18778 vector bool int vec_mergeh (vector bool int, vector bool int);
18779 vector signed int vec_mergeh (vector signed int, vector signed int);
18780 vector unsigned int vec_mergeh (vector unsigned int, vector unsigned int);
18782 vector bool char vec_mergel (vector bool char, vector bool char);
18783 vector signed char vec_mergel (vector signed char, vector signed char);
18784 vector unsigned char vec_mergel (vector unsigned char, vector unsigned char);
18785 vector bool short vec_mergel (vector bool short, vector bool short);
18786 vector pixel vec_mergel (vector pixel, vector pixel);
18787 vector signed short vec_mergel (vector signed short, vector signed short);
18788 vector unsigned short vec_mergel (vector unsigned short, vector unsigned short);
18789 vector float vec_mergel (vector float, vector float);
18790 vector bool int vec_mergel (vector bool int, vector bool int);
18791 vector signed int vec_mergel (vector signed int, vector signed int);
18792 vector unsigned int vec_mergel (vector unsigned int, vector unsigned int);
18794 vector unsigned short vec_mfvscr (void);
18796 vector unsigned char vec_min (vector bool char, vector unsigned char);
18797 vector unsigned char vec_min (vector unsigned char, vector bool char);
18798 vector unsigned char vec_min (vector unsigned char, vector unsigned char);
18799 vector signed char vec_min (vector bool char, vector signed char);
18800 vector signed char vec_min (vector signed char, vector bool char);
18801 vector signed char vec_min (vector signed char, vector signed char);
18802 vector unsigned short vec_min (vector bool short, vector unsigned short);
18803 vector unsigned short vec_min (vector unsigned short, vector bool short);
18804 vector unsigned short vec_min (vector unsigned short, vector unsigned short);
18805 vector signed short vec_min (vector bool short, vector signed short);
18806 vector signed short vec_min (vector signed short, vector bool short);
18807 vector signed short vec_min (vector signed short, vector signed short);
18808 vector unsigned int vec_min (vector bool int, vector unsigned int);
18809 vector unsigned int vec_min (vector unsigned int, vector bool int);
18810 vector unsigned int vec_min (vector unsigned int, vector unsigned int);
18811 vector signed int vec_min (vector bool int, vector signed int);
18812 vector signed int vec_min (vector signed int, vector bool int);
18813 vector signed int vec_min (vector signed int, vector signed int);
18814 vector float vec_min (vector float, vector float);
18816 vector signed short vec_mladd (vector signed short, vector signed short,
18817 vector signed short);
18818 vector signed short vec_mladd (vector signed short, vector unsigned short,
18819 vector unsigned short);
18820 vector signed short vec_mladd (vector unsigned short, vector signed short,
18821 vector signed short);
18822 vector unsigned short vec_mladd (vector unsigned short, vector unsigned short,
18823 vector unsigned short);
18825 vector signed short vec_mradds (vector signed short, vector signed short,
18826 vector signed short);
18828 vector unsigned int vec_msum (vector unsigned char, vector unsigned char,
18829 vector unsigned int);
18830 vector signed int vec_msum (vector signed char, vector unsigned char,
18831 vector signed int);
18832 vector unsigned int vec_msum (vector unsigned short, vector unsigned short,
18833 vector unsigned int);
18834 vector signed int vec_msum (vector signed short, vector signed short,
18835 vector signed int);
18837 vector unsigned int vec_msums (vector unsigned short, vector unsigned short,
18838 vector unsigned int);
18839 vector signed int vec_msums (vector signed short, vector signed short,
18840 vector signed int);
18842 void vec_mtvscr (vector signed int);
18843 void vec_mtvscr (vector unsigned int);
18844 void vec_mtvscr (vector bool int);
18845 void vec_mtvscr (vector signed short);
18846 void vec_mtvscr (vector unsigned short);
18847 void vec_mtvscr (vector bool short);
18848 void vec_mtvscr (vector pixel);
18849 void vec_mtvscr (vector signed char);
18850 void vec_mtvscr (vector unsigned char);
18851 void vec_mtvscr (vector bool char);
18853 vector float vec_mul (vector float, vector float);
18855 vector unsigned short vec_mule (vector unsigned char, vector unsigned char);
18856 vector signed short vec_mule (vector signed char, vector signed char);
18857 vector unsigned int vec_mule (vector unsigned short, vector unsigned short);
18858 vector signed int vec_mule (vector signed short, vector signed short);
18860 vector unsigned short vec_mulo (vector unsigned char, vector unsigned char);
18861 vector signed short vec_mulo (vector signed char, vector signed char);
18862 vector unsigned int vec_mulo (vector unsigned short, vector unsigned short);
18863 vector signed int vec_mulo (vector signed short, vector signed short);
18865 vector signed char vec_nabs (vector signed char);
18866 vector signed short vec_nabs (vector signed short);
18867 vector signed int vec_nabs (vector signed int);
18868 vector float vec_nabs (vector float);
18870 vector float vec_nmsub (vector float, vector float, vector float);
18872 vector float vec_nor (vector float, vector float);
18873 vector signed int vec_nor (vector signed int, vector signed int);
18874 vector unsigned int vec_nor (vector unsigned int, vector unsigned int);
18875 vector bool int vec_nor (vector bool int, vector bool int);
18876 vector signed short vec_nor (vector signed short, vector signed short);
18877 vector unsigned short vec_nor (vector unsigned short, vector unsigned short);
18878 vector bool short vec_nor (vector bool short, vector bool short);
18879 vector signed char vec_nor (vector signed char, vector signed char);
18880 vector unsigned char vec_nor (vector unsigned char, vector unsigned char);
18881 vector bool char vec_nor (vector bool char, vector bool char);
18883 vector float vec_or (vector float, vector float);
18884 vector float vec_or (vector float, vector bool int);
18885 vector float vec_or (vector bool int, vector float);
18886 vector bool int vec_or (vector bool int, vector bool int);
18887 vector signed int vec_or (vector bool int, vector signed int);
18888 vector signed int vec_or (vector signed int, vector bool int);
18889 vector signed int vec_or (vector signed int, vector signed int);
18890 vector unsigned int vec_or (vector bool int, vector unsigned int);
18891 vector unsigned int vec_or (vector unsigned int, vector bool int);
18892 vector unsigned int vec_or (vector unsigned int, vector unsigned int);
18893 vector bool short vec_or (vector bool short, vector bool short);
18894 vector signed short vec_or (vector bool short, vector signed short);
18895 vector signed short vec_or (vector signed short, vector bool short);
18896 vector signed short vec_or (vector signed short, vector signed short);
18897 vector unsigned short vec_or (vector bool short, vector unsigned short);
18898 vector unsigned short vec_or (vector unsigned short, vector bool short);
18899 vector unsigned short vec_or (vector unsigned short, vector unsigned short);
18900 vector signed char vec_or (vector bool char, vector signed char);
18901 vector bool char vec_or (vector bool char, vector bool char);
18902 vector signed char vec_or (vector signed char, vector bool char);
18903 vector signed char vec_or (vector signed char, vector signed char);
18904 vector unsigned char vec_or (vector bool char, vector unsigned char);
18905 vector unsigned char vec_or (vector unsigned char, vector bool char);
18906 vector unsigned char vec_or (vector unsigned char, vector unsigned char);
18908 vector signed char vec_pack (vector signed short, vector signed short);
18909 vector unsigned char vec_pack (vector unsigned short, vector unsigned short);
18910 vector bool char vec_pack (vector bool short, vector bool short);
18911 vector signed short vec_pack (vector signed int, vector signed int);
18912 vector unsigned short vec_pack (vector unsigned int, vector unsigned int);
18913 vector bool short vec_pack (vector bool int, vector bool int);
18915 vector pixel vec_packpx (vector unsigned int, vector unsigned int);
18917 vector unsigned char vec_packs (vector unsigned short, vector unsigned short);
18918 vector signed char vec_packs (vector signed short, vector signed short);
18919 vector unsigned short vec_packs (vector unsigned int, vector unsigned int);
18920 vector signed short vec_packs (vector signed int, vector signed int);
18922 vector unsigned char vec_packsu (vector unsigned short, vector unsigned short);
18923 vector unsigned char vec_packsu (vector signed short, vector signed short);
18924 vector unsigned short vec_packsu (vector unsigned int, vector unsigned int);
18925 vector unsigned short vec_packsu (vector signed int, vector signed int);
18927 vector float vec_perm (vector float, vector float, vector unsigned char);
18928 vector signed int vec_perm (vector signed int, vector signed int, vector unsigned char);
18929 vector unsigned int vec_perm (vector unsigned int, vector unsigned int,
18930 vector unsigned char);
18931 vector bool int vec_perm (vector bool int, vector bool int, vector unsigned char);
18932 vector signed short vec_perm (vector signed short, vector signed short,
18933 vector unsigned char);
18934 vector unsigned short vec_perm (vector unsigned short, vector unsigned short,
18935 vector unsigned char);
18936 vector bool short vec_perm (vector bool short, vector bool short, vector unsigned char);
18937 vector pixel vec_perm (vector pixel, vector pixel, vector unsigned char);
18938 vector signed char vec_perm (vector signed char, vector signed char,
18939 vector unsigned char);
18940 vector unsigned char vec_perm (vector unsigned char, vector unsigned char,
18941 vector unsigned char);
18942 vector bool char vec_perm (vector bool char, vector bool char, vector unsigned char);
18944 vector float vec_re (vector float);
18946 vector bool char vec_reve (vector bool char);
18947 vector signed char vec_reve (vector signed char);
18948 vector unsigned char vec_reve (vector unsigned char);
18949 vector bool int vec_reve (vector bool int);
18950 vector signed int vec_reve (vector signed int);
18951 vector unsigned int vec_reve (vector unsigned int);
18952 vector bool short vec_reve (vector bool short);
18953 vector signed short vec_reve (vector signed short);
18954 vector unsigned short vec_reve (vector unsigned short);
18956 vector signed char vec_rl (vector signed char, vector unsigned char);
18957 vector unsigned char vec_rl (vector unsigned char, vector unsigned char);
18958 vector signed short vec_rl (vector signed short, vector unsigned short);
18959 vector unsigned short vec_rl (vector unsigned short, vector unsigned short);
18960 vector signed int vec_rl (vector signed int, vector unsigned int);
18961 vector unsigned int vec_rl (vector unsigned int, vector unsigned int);
18963 vector float vec_round (vector float);
18965 vector float vec_rsqrt (vector float);
18967 vector float vec_rsqrte (vector float);
18969 vector float vec_sel (vector float, vector float, vector bool int);
18970 vector float vec_sel (vector float, vector float, vector unsigned int);
18971 vector signed int vec_sel (vector signed int, vector signed int, vector bool int);
18972 vector signed int vec_sel (vector signed int, vector signed int, vector unsigned int);
18973 vector unsigned int vec_sel (vector unsigned int, vector unsigned int, vector bool int);
18974 vector unsigned int vec_sel (vector unsigned int, vector unsigned int,
18975 vector unsigned int);
18976 vector bool int vec_sel (vector bool int, vector bool int, vector bool int);
18977 vector bool int vec_sel (vector bool int, vector bool int, vector unsigned int);
18978 vector signed short vec_sel (vector signed short, vector signed short,
18979 vector bool short);
18980 vector signed short vec_sel (vector signed short, vector signed short,
18981 vector unsigned short);
18982 vector unsigned short vec_sel (vector unsigned short, vector unsigned short,
18983 vector bool short);
18984 vector unsigned short vec_sel (vector unsigned short, vector unsigned short,
18985 vector unsigned short);
18986 vector bool short vec_sel (vector bool short, vector bool short, vector bool short);
18987 vector bool short vec_sel (vector bool short, vector bool short, vector unsigned short);
18988 vector signed char vec_sel (vector signed char, vector signed char, vector bool char);
18989 vector signed char vec_sel (vector signed char, vector signed char,
18990 vector unsigned char);
18991 vector unsigned char vec_sel (vector unsigned char, vector unsigned char,
18993 vector unsigned char vec_sel (vector unsigned char, vector unsigned char,
18994 vector unsigned char);
18995 vector bool char vec_sel (vector bool char, vector bool char, vector bool char);
18996 vector bool char vec_sel (vector bool char, vector bool char, vector unsigned char);
18998 vector signed char vec_sl (vector signed char, vector unsigned char);
18999 vector unsigned char vec_sl (vector unsigned char, vector unsigned char);
19000 vector signed short vec_sl (vector signed short, vector unsigned short);
19001 vector unsigned short vec_sl (vector unsigned short, vector unsigned short);
19002 vector signed int vec_sl (vector signed int, vector unsigned int);
19003 vector unsigned int vec_sl (vector unsigned int, vector unsigned int);
19005 vector float vec_sld (vector float, vector float, const int);
19006 vector signed int vec_sld (vector signed int, vector signed int, const int);
19007 vector unsigned int vec_sld (vector unsigned int, vector unsigned int, const int);
19008 vector bool int vec_sld (vector bool int, vector bool int, const int);
19009 vector signed short vec_sld (vector signed short, vector signed short, const int);
19010 vector unsigned short vec_sld (vector unsigned short, vector unsigned short, const int);
19011 vector bool short vec_sld (vector bool short, vector bool short, const int);
19012 vector pixel vec_sld (vector pixel, vector pixel, const int);
19013 vector signed char vec_sld (vector signed char, vector signed char, const int);
19014 vector unsigned char vec_sld (vector unsigned char, vector unsigned char, const int);
19015 vector bool char vec_sld (vector bool char, vector bool char, const int);
19017 vector signed int vec_sll (vector signed int, vector unsigned int);
19018 vector signed int vec_sll (vector signed int, vector unsigned short);
19019 vector signed int vec_sll (vector signed int, vector unsigned char);
19020 vector unsigned int vec_sll (vector unsigned int, vector unsigned int);
19021 vector unsigned int vec_sll (vector unsigned int, vector unsigned short);
19022 vector unsigned int vec_sll (vector unsigned int, vector unsigned char);
19023 vector bool int vec_sll (vector bool int, vector unsigned int);
19024 vector bool int vec_sll (vector bool int, vector unsigned short);
19025 vector bool int vec_sll (vector bool int, vector unsigned char);
19026 vector signed short vec_sll (vector signed short, vector unsigned int);
19027 vector signed short vec_sll (vector signed short, vector unsigned short);
19028 vector signed short vec_sll (vector signed short, vector unsigned char);
19029 vector unsigned short vec_sll (vector unsigned short, vector unsigned int);
19030 vector unsigned short vec_sll (vector unsigned short, vector unsigned short);
19031 vector unsigned short vec_sll (vector unsigned short, vector unsigned char);
19032 vector bool short vec_sll (vector bool short, vector unsigned int);
19033 vector bool short vec_sll (vector bool short, vector unsigned short);
19034 vector bool short vec_sll (vector bool short, vector unsigned char);
19035 vector pixel vec_sll (vector pixel, vector unsigned int);
19036 vector pixel vec_sll (vector pixel, vector unsigned short);
19037 vector pixel vec_sll (vector pixel, vector unsigned char);
19038 vector signed char vec_sll (vector signed char, vector unsigned int);
19039 vector signed char vec_sll (vector signed char, vector unsigned short);
19040 vector signed char vec_sll (vector signed char, vector unsigned char);
19041 vector unsigned char vec_sll (vector unsigned char, vector unsigned int);
19042 vector unsigned char vec_sll (vector unsigned char, vector unsigned short);
19043 vector unsigned char vec_sll (vector unsigned char, vector unsigned char);
19044 vector bool char vec_sll (vector bool char, vector unsigned int);
19045 vector bool char vec_sll (vector bool char, vector unsigned short);
19046 vector bool char vec_sll (vector bool char, vector unsigned char);
19048 vector float vec_slo (vector float, vector signed char);
19049 vector float vec_slo (vector float, vector unsigned char);
19050 vector signed int vec_slo (vector signed int, vector signed char);
19051 vector signed int vec_slo (vector signed int, vector unsigned char);
19052 vector unsigned int vec_slo (vector unsigned int, vector signed char);
19053 vector unsigned int vec_slo (vector unsigned int, vector unsigned char);
19054 vector signed short vec_slo (vector signed short, vector signed char);
19055 vector signed short vec_slo (vector signed short, vector unsigned char);
19056 vector unsigned short vec_slo (vector unsigned short, vector signed char);
19057 vector unsigned short vec_slo (vector unsigned short, vector unsigned char);
19058 vector pixel vec_slo (vector pixel, vector signed char);
19059 vector pixel vec_slo (vector pixel, vector unsigned char);
19060 vector signed char vec_slo (vector signed char, vector signed char);
19061 vector signed char vec_slo (vector signed char, vector unsigned char);
19062 vector unsigned char vec_slo (vector unsigned char, vector signed char);
19063 vector unsigned char vec_slo (vector unsigned char, vector unsigned char);
19065 vector signed char vec_splat (vector signed char, const int);
19066 vector unsigned char vec_splat (vector unsigned char, const int);
19067 vector bool char vec_splat (vector bool char, const int);
19068 vector signed short vec_splat (vector signed short, const int);
19069 vector unsigned short vec_splat (vector unsigned short, const int);
19070 vector bool short vec_splat (vector bool short, const int);
19071 vector pixel vec_splat (vector pixel, const int);
19072 vector float vec_splat (vector float, const int);
19073 vector signed int vec_splat (vector signed int, const int);
19074 vector unsigned int vec_splat (vector unsigned int, const int);
19075 vector bool int vec_splat (vector bool int, const int);
19077 vector signed short vec_splat_s16 (const int);
19079 vector signed int vec_splat_s32 (const int);
19081 vector signed char vec_splat_s8 (const int);
19083 vector unsigned short vec_splat_u16 (const int);
19085 vector unsigned int vec_splat_u32 (const int);
19087 vector unsigned char vec_splat_u8 (const int);
19089 vector signed char vec_splats (signed char);
19090 vector unsigned char vec_splats (unsigned char);
19091 vector signed short vec_splats (signed short);
19092 vector unsigned short vec_splats (unsigned short);
19093 vector signed int vec_splats (signed int);
19094 vector unsigned int vec_splats (unsigned int);
19095 vector float vec_splats (float);
19097 vector signed char vec_sr (vector signed char, vector unsigned char);
19098 vector unsigned char vec_sr (vector unsigned char, vector unsigned char);
19099 vector signed short vec_sr (vector signed short, vector unsigned short);
19100 vector unsigned short vec_sr (vector unsigned short, vector unsigned short);
19101 vector signed int vec_sr (vector signed int, vector unsigned int);
19102 vector unsigned int vec_sr (vector unsigned int, vector unsigned int);
19104 vector signed char vec_sra (vector signed char, vector unsigned char);
19105 vector unsigned char vec_sra (vector unsigned char, vector unsigned char);
19106 vector signed short vec_sra (vector signed short, vector unsigned short);
19107 vector unsigned short vec_sra (vector unsigned short, vector unsigned short);
19108 vector signed int vec_sra (vector signed int, vector unsigned int);
19109 vector unsigned int vec_sra (vector unsigned int, vector unsigned int);
19111 vector signed int vec_srl (vector signed int, vector unsigned int);
19112 vector signed int vec_srl (vector signed int, vector unsigned short);
19113 vector signed int vec_srl (vector signed int, vector unsigned char);
19114 vector unsigned int vec_srl (vector unsigned int, vector unsigned int);
19115 vector unsigned int vec_srl (vector unsigned int, vector unsigned short);
19116 vector unsigned int vec_srl (vector unsigned int, vector unsigned char);
19117 vector bool int vec_srl (vector bool int, vector unsigned int);
19118 vector bool int vec_srl (vector bool int, vector unsigned short);
19119 vector bool int vec_srl (vector bool int, vector unsigned char);
19120 vector signed short vec_srl (vector signed short, vector unsigned int);
19121 vector signed short vec_srl (vector signed short, vector unsigned short);
19122 vector signed short vec_srl (vector signed short, vector unsigned char);
19123 vector unsigned short vec_srl (vector unsigned short, vector unsigned int);
19124 vector unsigned short vec_srl (vector unsigned short, vector unsigned short);
19125 vector unsigned short vec_srl (vector unsigned short, vector unsigned char);
19126 vector bool short vec_srl (vector bool short, vector unsigned int);
19127 vector bool short vec_srl (vector bool short, vector unsigned short);
19128 vector bool short vec_srl (vector bool short, vector unsigned char);
19129 vector pixel vec_srl (vector pixel, vector unsigned int);
19130 vector pixel vec_srl (vector pixel, vector unsigned short);
19131 vector pixel vec_srl (vector pixel, vector unsigned char);
19132 vector signed char vec_srl (vector signed char, vector unsigned int);
19133 vector signed char vec_srl (vector signed char, vector unsigned short);
19134 vector signed char vec_srl (vector signed char, vector unsigned char);
19135 vector unsigned char vec_srl (vector unsigned char, vector unsigned int);
19136 vector unsigned char vec_srl (vector unsigned char, vector unsigned short);
19137 vector unsigned char vec_srl (vector unsigned char, vector unsigned char);
19138 vector bool char vec_srl (vector bool char, vector unsigned int);
19139 vector bool char vec_srl (vector bool char, vector unsigned short);
19140 vector bool char vec_srl (vector bool char, vector unsigned char);
19142 vector float vec_sro (vector float, vector signed char);
19143 vector float vec_sro (vector float, vector unsigned char);
19144 vector signed int vec_sro (vector signed int, vector signed char);
19145 vector signed int vec_sro (vector signed int, vector unsigned char);
19146 vector unsigned int vec_sro (vector unsigned int, vector signed char);
19147 vector unsigned int vec_sro (vector unsigned int, vector unsigned char);
19148 vector signed short vec_sro (vector signed short, vector signed char);
19149 vector signed short vec_sro (vector signed short, vector unsigned char);
19150 vector unsigned short vec_sro (vector unsigned short, vector signed char);
19151 vector unsigned short vec_sro (vector unsigned short, vector unsigned char);
19152 vector pixel vec_sro (vector pixel, vector signed char);
19153 vector pixel vec_sro (vector pixel, vector unsigned char);
19154 vector signed char vec_sro (vector signed char, vector signed char);
19155 vector signed char vec_sro (vector signed char, vector unsigned char);
19156 vector unsigned char vec_sro (vector unsigned char, vector signed char);
19157 vector unsigned char vec_sro (vector unsigned char, vector unsigned char);
19159 void vec_st (vector float, int, vector float *);
19160 void vec_st (vector float, int, float *);
19161 void vec_st (vector signed int, int, vector signed int *);
19162 void vec_st (vector signed int, int, int *);
19163 void vec_st (vector unsigned int, int, vector unsigned int *);
19164 void vec_st (vector unsigned int, int, unsigned int *);
19165 void vec_st (vector bool int, int, vector bool int *);
19166 void vec_st (vector bool int, int, unsigned int *);
19167 void vec_st (vector bool int, int, int *);
19168 void vec_st (vector signed short, int, vector signed short *);
19169 void vec_st (vector signed short, int, short *);
19170 void vec_st (vector unsigned short, int, vector unsigned short *);
19171 void vec_st (vector unsigned short, int, unsigned short *);
19172 void vec_st (vector bool short, int, vector bool short *);
19173 void vec_st (vector bool short, int, unsigned short *);
19174 void vec_st (vector pixel, int, vector pixel *);
19175 void vec_st (vector bool short, int, short *);
19176 void vec_st (vector signed char, int, vector signed char *);
19177 void vec_st (vector signed char, int, signed char *);
19178 void vec_st (vector unsigned char, int, vector unsigned char *);
19179 void vec_st (vector unsigned char, int, unsigned char *);
19180 void vec_st (vector bool char, int, vector bool char *);
19181 void vec_st (vector bool char, int, unsigned char *);
19182 void vec_st (vector bool char, int, signed char *);
19184 void vec_ste (vector signed char, int, signed char *);
19185 void vec_ste (vector unsigned char, int, unsigned char *);
19186 void vec_ste (vector bool char, int, signed char *);
19187 void vec_ste (vector bool char, int, unsigned char *);
19188 void vec_ste (vector signed short, int, short *);
19189 void vec_ste (vector unsigned short, int, unsigned short *);
19190 void vec_ste (vector bool short, int, short *);
19191 void vec_ste (vector bool short, int, unsigned short *);
19192 void vec_ste (vector pixel, int, short *);
19193 void vec_ste (vector pixel, int, unsigned short *);
19194 void vec_ste (vector float, int, float *);
19195 void vec_ste (vector signed int, int, int *);
19196 void vec_ste (vector unsigned int, int, unsigned int *);
19197 void vec_ste (vector bool int, int, int *);
19198 void vec_ste (vector bool int, int, unsigned int *);
19200 void vec_stl (vector float, int, vector float *);
19201 void vec_stl (vector float, int, float *);
19202 void vec_stl (vector signed int, int, vector signed int *);
19203 void vec_stl (vector signed int, int, int *);
19204 void vec_stl (vector unsigned int, int, vector unsigned int *);
19205 void vec_stl (vector unsigned int, int, unsigned int *);
19206 void vec_stl (vector bool int, int, vector bool int *);
19207 void vec_stl (vector bool int, int, unsigned int *);
19208 void vec_stl (vector bool int, int, int *);
19209 void vec_stl (vector signed short, int, vector signed short *);
19210 void vec_stl (vector signed short, int, short *);
19211 void vec_stl (vector unsigned short, int, vector unsigned short *);
19212 void vec_stl (vector unsigned short, int, unsigned short *);
19213 void vec_stl (vector bool short, int, vector bool short *);
19214 void vec_stl (vector bool short, int, unsigned short *);
19215 void vec_stl (vector bool short, int, short *);
19216 void vec_stl (vector pixel, int, vector pixel *);
19217 void vec_stl (vector signed char, int, vector signed char *);
19218 void vec_stl (vector signed char, int, signed char *);
19219 void vec_stl (vector unsigned char, int, vector unsigned char *);
19220 void vec_stl (vector unsigned char, int, unsigned char *);
19221 void vec_stl (vector bool char, int, vector bool char *);
19222 void vec_stl (vector bool char, int, unsigned char *);
19223 void vec_stl (vector bool char, int, signed char *);
19225 void vec_stvebx (vector signed char, int, signed char *);
19226 void vec_stvebx (vector unsigned char, int, unsigned char *);
19227 void vec_stvebx (vector bool char, int, signed char *);
19228 void vec_stvebx (vector bool char, int, unsigned char *);
19230 void vec_stvehx (vector signed short, int, short *);
19231 void vec_stvehx (vector unsigned short, int, unsigned short *);
19232 void vec_stvehx (vector bool short, int, short *);
19233 void vec_stvehx (vector bool short, int, unsigned short *);
19235 void vec_stvewx (vector float, int, float *);
19236 void vec_stvewx (vector signed int, int, int *);
19237 void vec_stvewx (vector unsigned int, int, unsigned int *);
19238 void vec_stvewx (vector bool int, int, int *);
19239 void vec_stvewx (vector bool int, int, unsigned int *);
19241 vector signed char vec_sub (vector bool char, vector signed char);
19242 vector signed char vec_sub (vector signed char, vector bool char);
19243 vector signed char vec_sub (vector signed char, vector signed char);
19244 vector unsigned char vec_sub (vector bool char, vector unsigned char);
19245 vector unsigned char vec_sub (vector unsigned char, vector bool char);
19246 vector unsigned char vec_sub (vector unsigned char, vector unsigned char);
19247 vector signed short vec_sub (vector bool short, vector signed short);
19248 vector signed short vec_sub (vector signed short, vector bool short);
19249 vector signed short vec_sub (vector signed short, vector signed short);
19250 vector unsigned short vec_sub (vector bool short, vector unsigned short);
19251 vector unsigned short vec_sub (vector unsigned short, vector bool short);
19252 vector unsigned short vec_sub (vector unsigned short, vector unsigned short);
19253 vector signed int vec_sub (vector bool int, vector signed int);
19254 vector signed int vec_sub (vector signed int, vector bool int);
19255 vector signed int vec_sub (vector signed int, vector signed int);
19256 vector unsigned int vec_sub (vector bool int, vector unsigned int);
19257 vector unsigned int vec_sub (vector unsigned int, vector bool int);
19258 vector unsigned int vec_sub (vector unsigned int, vector unsigned int);
19259 vector float vec_sub (vector float, vector float);
19261 vector signed int vec_subc (vector signed int, vector signed int);
19262 vector unsigned int vec_subc (vector unsigned int, vector unsigned int);
19264 vector signed int vec_sube (vector signed int, vector signed int,
19265 vector signed int);
19266 vector unsigned int vec_sube (vector unsigned int, vector unsigned int,
19267 vector unsigned int);
19269 vector signed int vec_subec (vector signed int, vector signed int,
19270 vector signed int);
19271 vector unsigned int vec_subec (vector unsigned int, vector unsigned int,
19272 vector unsigned int);
19274 vector unsigned char vec_subs (vector bool char, vector unsigned char);
19275 vector unsigned char vec_subs (vector unsigned char, vector bool char);
19276 vector unsigned char vec_subs (vector unsigned char, vector unsigned char);
19277 vector signed char vec_subs (vector bool char, vector signed char);
19278 vector signed char vec_subs (vector signed char, vector bool char);
19279 vector signed char vec_subs (vector signed char, vector signed char);
19280 vector unsigned short vec_subs (vector bool short, vector unsigned short);
19281 vector unsigned short vec_subs (vector unsigned short, vector bool short);
19282 vector unsigned short vec_subs (vector unsigned short, vector unsigned short);
19283 vector signed short vec_subs (vector bool short, vector signed short);
19284 vector signed short vec_subs (vector signed short, vector bool short);
19285 vector signed short vec_subs (vector signed short, vector signed short);
19286 vector unsigned int vec_subs (vector bool int, vector unsigned int);
19287 vector unsigned int vec_subs (vector unsigned int, vector bool int);
19288 vector unsigned int vec_subs (vector unsigned int, vector unsigned int);
19289 vector signed int vec_subs (vector bool int, vector signed int);
19290 vector signed int vec_subs (vector signed int, vector bool int);
19291 vector signed int vec_subs (vector signed int, vector signed int);
19293 vector signed int vec_sum2s (vector signed int, vector signed int);
19295 vector unsigned int vec_sum4s (vector unsigned char, vector unsigned int);
19296 vector signed int vec_sum4s (vector signed char, vector signed int);
19297 vector signed int vec_sum4s (vector signed short, vector signed int);
19299 vector signed int vec_sums (vector signed int, vector signed int);
19301 vector float vec_trunc (vector float);
19303 vector signed short vec_unpackh (vector signed char);
19304 vector bool short vec_unpackh (vector bool char);
19305 vector signed int vec_unpackh (vector signed short);
19306 vector bool int vec_unpackh (vector bool short);
19307 vector unsigned int vec_unpackh (vector pixel);
19309 vector signed short vec_unpackl (vector signed char);
19310 vector bool short vec_unpackl (vector bool char);
19311 vector unsigned int vec_unpackl (vector pixel);
19312 vector signed int vec_unpackl (vector signed short);
19313 vector bool int vec_unpackl (vector bool short);
19315 vector float vec_vaddfp (vector float, vector float);
19317 vector signed char vec_vaddsbs (vector bool char, vector signed char);
19318 vector signed char vec_vaddsbs (vector signed char, vector bool char);
19319 vector signed char vec_vaddsbs (vector signed char, vector signed char);
19321 vector signed short vec_vaddshs (vector bool short, vector signed short);
19322 vector signed short vec_vaddshs (vector signed short, vector bool short);
19323 vector signed short vec_vaddshs (vector signed short, vector signed short);
19325 vector signed int vec_vaddsws (vector bool int, vector signed int);
19326 vector signed int vec_vaddsws (vector signed int, vector bool int);
19327 vector signed int vec_vaddsws (vector signed int, vector signed int);
19329 vector signed char vec_vaddubm (vector bool char, vector signed char);
19330 vector signed char vec_vaddubm (vector signed char, vector bool char);
19331 vector signed char vec_vaddubm (vector signed char, vector signed char);
19332 vector unsigned char vec_vaddubm (vector bool char, vector unsigned char);
19333 vector unsigned char vec_vaddubm (vector unsigned char, vector bool char);
19334 vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char);
19336 vector unsigned char vec_vaddubs (vector bool char, vector unsigned char);
19337 vector unsigned char vec_vaddubs (vector unsigned char, vector bool char);
19338 vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char);
19340 vector signed short vec_vadduhm (vector bool short, vector signed short);
19341 vector signed short vec_vadduhm (vector signed short, vector bool short);
19342 vector signed short vec_vadduhm (vector signed short, vector signed short);
19343 vector unsigned short vec_vadduhm (vector bool short, vector unsigned short);
19344 vector unsigned short vec_vadduhm (vector unsigned short, vector bool short);
19345 vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short);
19347 vector unsigned short vec_vadduhs (vector bool short, vector unsigned short);
19348 vector unsigned short vec_vadduhs (vector unsigned short, vector bool short);
19349 vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short);
19351 vector signed int vec_vadduwm (vector bool int, vector signed int);
19352 vector signed int vec_vadduwm (vector signed int, vector bool int);
19353 vector signed int vec_vadduwm (vector signed int, vector signed int);
19354 vector unsigned int vec_vadduwm (vector bool int, vector unsigned int);
19355 vector unsigned int vec_vadduwm (vector unsigned int, vector bool int);
19356 vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int);
19358 vector unsigned int vec_vadduws (vector bool int, vector unsigned int);
19359 vector unsigned int vec_vadduws (vector unsigned int, vector bool int);
19360 vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int);
19362 vector signed char vec_vavgsb (vector signed char, vector signed char);
19364 vector signed short vec_vavgsh (vector signed short, vector signed short);
19366 vector signed int vec_vavgsw (vector signed int, vector signed int);
19368 vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char);
19370 vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short);
19372 vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int);
19374 vector float vec_vcfsx (vector signed int, const int);
19376 vector float vec_vcfux (vector unsigned int, const int);
19378 vector bool int vec_vcmpeqfp (vector float, vector float);
19380 vector bool char vec_vcmpequb (vector signed char, vector signed char);
19381 vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char);
19383 vector bool short vec_vcmpequh (vector signed short, vector signed short);
19384 vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short);
19386 vector bool int vec_vcmpequw (vector signed int, vector signed int);
19387 vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int);
19389 vector bool int vec_vcmpgtfp (vector float, vector float);
19391 vector bool char vec_vcmpgtsb (vector signed char, vector signed char);
19393 vector bool short vec_vcmpgtsh (vector signed short, vector signed short);
19395 vector bool int vec_vcmpgtsw (vector signed int, vector signed int);
19397 vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char);
19399 vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short);
19401 vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int);
19403 vector float vec_vmaxfp (vector float, vector float);
19405 vector signed char vec_vmaxsb (vector bool char, vector signed char);
19406 vector signed char vec_vmaxsb (vector signed char, vector bool char);
19407 vector signed char vec_vmaxsb (vector signed char, vector signed char);
19409 vector signed short vec_vmaxsh (vector bool short, vector signed short);
19410 vector signed short vec_vmaxsh (vector signed short, vector bool short);
19411 vector signed short vec_vmaxsh (vector signed short, vector signed short);
19413 vector signed int vec_vmaxsw (vector bool int, vector signed int);
19414 vector signed int vec_vmaxsw (vector signed int, vector bool int);
19415 vector signed int vec_vmaxsw (vector signed int, vector signed int);
19417 vector unsigned char vec_vmaxub (vector bool char, vector unsigned char);
19418 vector unsigned char vec_vmaxub (vector unsigned char, vector bool char);
19419 vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char);
19421 vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short);
19422 vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short);
19423 vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short);
19425 vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int);
19426 vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int);
19427 vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int);
19429 vector float vec_vminfp (vector float, vector float);
19431 vector signed char vec_vminsb (vector bool char, vector signed char);
19432 vector signed char vec_vminsb (vector signed char, vector bool char);
19433 vector signed char vec_vminsb (vector signed char, vector signed char);
19435 vector signed short vec_vminsh (vector bool short, vector signed short);
19436 vector signed short vec_vminsh (vector signed short, vector bool short);
19437 vector signed short vec_vminsh (vector signed short, vector signed short);
19439 vector signed int vec_vminsw (vector bool int, vector signed int);
19440 vector signed int vec_vminsw (vector signed int, vector bool int);
19441 vector signed int vec_vminsw (vector signed int, vector signed int);
19443 vector unsigned char vec_vminub (vector bool char, vector unsigned char);
19444 vector unsigned char vec_vminub (vector unsigned char, vector bool char);
19445 vector unsigned char vec_vminub (vector unsigned char, vector unsigned char);
19447 vector unsigned short vec_vminuh (vector bool short, vector unsigned short);
19448 vector unsigned short vec_vminuh (vector unsigned short, vector bool short);
19449 vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short);
19451 vector unsigned int vec_vminuw (vector bool int, vector unsigned int);
19452 vector unsigned int vec_vminuw (vector unsigned int, vector bool int);
19453 vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int);
19455 vector bool char vec_vmrghb (vector bool char, vector bool char);
19456 vector signed char vec_vmrghb (vector signed char, vector signed char);
19457 vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char);
19459 vector bool short vec_vmrghh (vector bool short, vector bool short);
19460 vector signed short vec_vmrghh (vector signed short, vector signed short);
19461 vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short);
19462 vector pixel vec_vmrghh (vector pixel, vector pixel);
19464 vector float vec_vmrghw (vector float, vector float);
19465 vector bool int vec_vmrghw (vector bool int, vector bool int);
19466 vector signed int vec_vmrghw (vector signed int, vector signed int);
19467 vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int);
19469 vector bool char vec_vmrglb (vector bool char, vector bool char);
19470 vector signed char vec_vmrglb (vector signed char, vector signed char);
19471 vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char);
19473 vector bool short vec_vmrglh (vector bool short, vector bool short);
19474 vector signed short vec_vmrglh (vector signed short, vector signed short);
19475 vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short);
19476 vector pixel vec_vmrglh (vector pixel, vector pixel);
19478 vector float vec_vmrglw (vector float, vector float);
19479 vector signed int vec_vmrglw (vector signed int, vector signed int);
19480 vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int);
19481 vector bool int vec_vmrglw (vector bool int, vector bool int);
19483 vector signed int vec_vmsummbm (vector signed char, vector unsigned char,
19484 vector signed int);
19486 vector signed int vec_vmsumshm (vector signed short, vector signed short,
19487 vector signed int);
19489 vector signed int vec_vmsumshs (vector signed short, vector signed short,
19490 vector signed int);
19492 vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char,
19493 vector unsigned int);
19495 vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short,
19496 vector unsigned int);
19498 vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short,
19499 vector unsigned int);
19501 vector signed short vec_vmulesb (vector signed char, vector signed char);
19503 vector signed int vec_vmulesh (vector signed short, vector signed short);
19505 vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char);
19507 vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short);
19509 vector signed short vec_vmulosb (vector signed char, vector signed char);
19511 vector signed int vec_vmulosh (vector signed short, vector signed short);
19513 vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char);
19515 vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short);
19517 vector signed char vec_vpkshss (vector signed short, vector signed short);
19519 vector unsigned char vec_vpkshus (vector signed short, vector signed short);
19521 vector signed short vec_vpkswss (vector signed int, vector signed int);
19523 vector unsigned short vec_vpkswus (vector signed int, vector signed int);
19525 vector bool char vec_vpkuhum (vector bool short, vector bool short);
19526 vector signed char vec_vpkuhum (vector signed short, vector signed short);
19527 vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short);
19529 vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short);
19531 vector bool short vec_vpkuwum (vector bool int, vector bool int);
19532 vector signed short vec_vpkuwum (vector signed int, vector signed int);
19533 vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int);
19535 vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int);
19537 vector signed char vec_vrlb (vector signed char, vector unsigned char);
19538 vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char);
19540 vector signed short vec_vrlh (vector signed short, vector unsigned short);
19541 vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short);
19543 vector signed int vec_vrlw (vector signed int, vector unsigned int);
19544 vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int);
19546 vector signed char vec_vslb (vector signed char, vector unsigned char);
19547 vector unsigned char vec_vslb (vector unsigned char, vector unsigned char);
19549 vector signed short vec_vslh (vector signed short, vector unsigned short);
19550 vector unsigned short vec_vslh (vector unsigned short, vector unsigned short);
19552 vector signed int vec_vslw (vector signed int, vector unsigned int);
19553 vector unsigned int vec_vslw (vector unsigned int, vector unsigned int);
19555 vector signed char vec_vspltb (vector signed char, const int);
19556 vector unsigned char vec_vspltb (vector unsigned char, const int);
19557 vector bool char vec_vspltb (vector bool char, const int);
19559 vector bool short vec_vsplth (vector bool short, const int);
19560 vector signed short vec_vsplth (vector signed short, const int);
19561 vector unsigned short vec_vsplth (vector unsigned short, const int);
19562 vector pixel vec_vsplth (vector pixel, const int);
19564 vector float vec_vspltw (vector float, const int);
19565 vector signed int vec_vspltw (vector signed int, const int);
19566 vector unsigned int vec_vspltw (vector unsigned int, const int);
19567 vector bool int vec_vspltw (vector bool int, const int);
19569 vector signed char vec_vsrab (vector signed char, vector unsigned char);
19570 vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char);
19572 vector signed short vec_vsrah (vector signed short, vector unsigned short);
19573 vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short);
19575 vector signed int vec_vsraw (vector signed int, vector unsigned int);
19576 vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int);
19578 vector signed char vec_vsrb (vector signed char, vector unsigned char);
19579 vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char);
19581 vector signed short vec_vsrh (vector signed short, vector unsigned short);
19582 vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short);
19584 vector signed int vec_vsrw (vector signed int, vector unsigned int);
19585 vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int);
19587 vector float vec_vsubfp (vector float, vector float);
19589 vector signed char vec_vsubsbs (vector bool char, vector signed char);
19590 vector signed char vec_vsubsbs (vector signed char, vector bool char);
19591 vector signed char vec_vsubsbs (vector signed char, vector signed char);
19593 vector signed short vec_vsubshs (vector bool short, vector signed short);
19594 vector signed short vec_vsubshs (vector signed short, vector bool short);
19595 vector signed short vec_vsubshs (vector signed short, vector signed short);
19597 vector signed int vec_vsubsws (vector bool int, vector signed int);
19598 vector signed int vec_vsubsws (vector signed int, vector bool int);
19599 vector signed int vec_vsubsws (vector signed int, vector signed int);
19601 vector signed char vec_vsububm (vector bool char, vector signed char);
19602 vector signed char vec_vsububm (vector signed char, vector bool char);
19603 vector signed char vec_vsububm (vector signed char, vector signed char);
19604 vector unsigned char vec_vsububm (vector bool char, vector unsigned char);
19605 vector unsigned char vec_vsububm (vector unsigned char, vector bool char);
19606 vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char);
19608 vector unsigned char vec_vsububs (vector bool char, vector unsigned char);
19609 vector unsigned char vec_vsububs (vector unsigned char, vector bool char);
19610 vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char);
19612 vector signed short vec_vsubuhm (vector bool short, vector signed short);
19613 vector signed short vec_vsubuhm (vector signed short, vector bool short);
19614 vector signed short vec_vsubuhm (vector signed short, vector signed short);
19615 vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short);
19616 vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short);
19617 vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short);
19619 vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short);
19620 vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short);
19621 vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short);
19623 vector signed int vec_vsubuwm (vector bool int, vector signed int);
19624 vector signed int vec_vsubuwm (vector signed int, vector bool int);
19625 vector signed int vec_vsubuwm (vector signed int, vector signed int);
19626 vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int);
19627 vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int);
19628 vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int);
19630 vector unsigned int vec_vsubuws (vector bool int, vector unsigned int);
19631 vector unsigned int vec_vsubuws (vector unsigned int, vector bool int);
19632 vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int);
19634 vector signed int vec_vsum4sbs (vector signed char, vector signed int);
19636 vector signed int vec_vsum4shs (vector signed short, vector signed int);
19638 vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int);
19640 vector unsigned int vec_vupkhpx (vector pixel);
19642 vector bool short vec_vupkhsb (vector bool char);
19643 vector signed short vec_vupkhsb (vector signed char);
19645 vector bool int vec_vupkhsh (vector bool short);
19646 vector signed int vec_vupkhsh (vector signed short);
19648 vector unsigned int vec_vupklpx (vector pixel);
19650 vector bool short vec_vupklsb (vector bool char);
19651 vector signed short vec_vupklsb (vector signed char);
19653 vector bool int vec_vupklsh (vector bool short);
19654 vector signed int vec_vupklsh (vector signed short);
19656 vector float vec_xor (vector float, vector float);
19657 vector float vec_xor (vector float, vector bool int);
19658 vector float vec_xor (vector bool int, vector float);
19659 vector bool int vec_xor (vector bool int, vector bool int);
19660 vector signed int vec_xor (vector bool int, vector signed int);
19661 vector signed int vec_xor (vector signed int, vector bool int);
19662 vector signed int vec_xor (vector signed int, vector signed int);
19663 vector unsigned int vec_xor (vector bool int, vector unsigned int);
19664 vector unsigned int vec_xor (vector unsigned int, vector bool int);
19665 vector unsigned int vec_xor (vector unsigned int, vector unsigned int);
19666 vector bool short vec_xor (vector bool short, vector bool short);
19667 vector signed short vec_xor (vector bool short, vector signed short);
19668 vector signed short vec_xor (vector signed short, vector bool short);
19669 vector signed short vec_xor (vector signed short, vector signed short);
19670 vector unsigned short vec_xor (vector bool short, vector unsigned short);
19671 vector unsigned short vec_xor (vector unsigned short, vector bool short);
19672 vector unsigned short vec_xor (vector unsigned short, vector unsigned short);
19673 vector signed char vec_xor (vector bool char, vector signed char);
19674 vector bool char vec_xor (vector bool char, vector bool char);
19675 vector signed char vec_xor (vector signed char, vector bool char);
19676 vector signed char vec_xor (vector signed char, vector signed char);
19677 vector unsigned char vec_xor (vector bool char, vector unsigned char);
19678 vector unsigned char vec_xor (vector unsigned char, vector bool char);
19679 vector unsigned char vec_xor (vector unsigned char, vector unsigned char);
19682 @node PowerPC AltiVec Built-in Functions Available on ISA 2.06
19683 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06
19685 The AltiVec built-in functions described in this section are
19686 available on the PowerPC family of processors starting with ISA 2.06
19687 or later. These are normally enabled by adding @option{-mvsx} to the
19690 When @option{-mvsx} is used, the following additional vector types are
19694 vector unsigned __int128
19695 vector signed __int128
19696 vector unsigned long long int
19697 vector signed long long int
19701 The long long types are only implemented for 64-bit code generation.
19705 vector bool long long vec_and (vector bool long long int, vector bool long long);
19707 vector double vec_ctf (vector unsigned long, const int);
19708 vector double vec_ctf (vector signed long, const int);
19710 vector signed long vec_cts (vector double, const int);
19712 vector unsigned long vec_ctu (vector double, const int);
19714 void vec_dst (const unsigned long *, int, const int);
19715 void vec_dst (const long *, int, const int);
19717 void vec_dststt (const unsigned long *, int, const int);
19718 void vec_dststt (const long *, int, const int);
19720 void vec_dstt (const unsigned long *, int, const int);
19721 void vec_dstt (const long *, int, const int);
19723 vector unsigned char vec_lvsl (int, const unsigned long *);
19724 vector unsigned char vec_lvsl (int, const long *);
19726 vector unsigned char vec_lvsr (int, const unsigned long *);
19727 vector unsigned char vec_lvsr (int, const long *);
19729 vector double vec_mul (vector double, vector double);
19730 vector long vec_mul (vector long, vector long);
19731 vector unsigned long vec_mul (vector unsigned long, vector unsigned long);
19733 vector unsigned long long vec_mule (vector unsigned int, vector unsigned int);
19734 vector signed long long vec_mule (vector signed int, vector signed int);
19736 vector unsigned long long vec_mulo (vector unsigned int, vector unsigned int);
19737 vector signed long long vec_mulo (vector signed int, vector signed int);
19739 vector double vec_nabs (vector double);
19741 vector bool long long vec_reve (vector bool long long);
19742 vector signed long long vec_reve (vector signed long long);
19743 vector unsigned long long vec_reve (vector unsigned long long);
19744 vector double vec_sld (vector double, vector double, const int);
19746 vector bool long long int vec_sld (vector bool long long int,
19747 vector bool long long int, const int);
19748 vector long long int vec_sld (vector long long int, vector long long int, const int);
19749 vector unsigned long long int vec_sld (vector unsigned long long int,
19750 vector unsigned long long int, const int);
19752 vector long long int vec_sll (vector long long int, vector unsigned char);
19753 vector unsigned long long int vec_sll (vector unsigned long long int,
19754 vector unsigned char);
19756 vector signed long long vec_slo (vector signed long long, vector signed char);
19757 vector signed long long vec_slo (vector signed long long, vector unsigned char);
19758 vector unsigned long long vec_slo (vector unsigned long long, vector signed char);
19759 vector unsigned long long vec_slo (vector unsigned long long, vector unsigned char);
19761 vector signed long vec_splat (vector signed long, const int);
19762 vector unsigned long vec_splat (vector unsigned long, const int);
19764 vector long long int vec_srl (vector long long int, vector unsigned char);
19765 vector unsigned long long int vec_srl (vector unsigned long long int,
19766 vector unsigned char);
19768 vector long long int vec_sro (vector long long int, vector char);
19769 vector long long int vec_sro (vector long long int, vector unsigned char);
19770 vector unsigned long long int vec_sro (vector unsigned long long int, vector char);
19771 vector unsigned long long int vec_sro (vector unsigned long long int,
19772 vector unsigned char);
19774 vector signed __int128 vec_subc (vector signed __int128, vector signed __int128);
19775 vector unsigned __int128 vec_subc (vector unsigned __int128, vector unsigned __int128);
19777 vector signed __int128 vec_sube (vector signed __int128, vector signed __int128,
19778 vector signed __int128);
19779 vector unsigned __int128 vec_sube (vector unsigned __int128, vector unsigned __int128,
19780 vector unsigned __int128);
19782 vector signed __int128 vec_subec (vector signed __int128, vector signed __int128,
19783 vector signed __int128);
19784 vector unsigned __int128 vec_subec (vector unsigned __int128, vector unsigned __int128,
19785 vector unsigned __int128);
19787 vector double vec_unpackh (vector float);
19789 vector double vec_unpackl (vector float);
19791 vector double vec_doublee (vector float);
19792 vector double vec_doublee (vector signed int);
19793 vector double vec_doublee (vector unsigned int);
19795 vector double vec_doubleo (vector float);
19796 vector double vec_doubleo (vector signed int);
19797 vector double vec_doubleo (vector unsigned int);
19799 vector double vec_doubleh (vector float);
19800 vector double vec_doubleh (vector signed int);
19801 vector double vec_doubleh (vector unsigned int);
19803 vector double vec_doublel (vector float);
19804 vector double vec_doublel (vector signed int);
19805 vector double vec_doublel (vector unsigned int);
19807 vector float vec_float (vector signed int);
19808 vector float vec_float (vector unsigned int);
19810 vector float vec_float2 (vector signed long long, vector signed long long);
19811 vector float vec_float2 (vector unsigned long long, vector signed long long);
19813 vector float vec_floate (vector double);
19814 vector float vec_floate (vector signed long long);
19815 vector float vec_floate (vector unsigned long long);
19817 vector float vec_floato (vector double);
19818 vector float vec_floato (vector signed long long);
19819 vector float vec_floato (vector unsigned long long);
19821 vector signed long long vec_signed (vector double);
19822 vector signed int vec_signed (vector float);
19824 vector signed int vec_signede (vector double);
19826 vector signed int vec_signedo (vector double);
19828 vector signed char vec_sldw (vector signed char, vector signed char, const int);
19829 vector unsigned char vec_sldw (vector unsigned char, vector unsigned char, const int);
19830 vector signed short vec_sldw (vector signed short, vector signed short, const int);
19831 vector unsigned short vec_sldw (vector unsigned short,
19832 vector unsigned short, const int);
19833 vector signed int vec_sldw (vector signed int, vector signed int, const int);
19834 vector unsigned int vec_sldw (vector unsigned int, vector unsigned int, const int);
19835 vector signed long long vec_sldw (vector signed long long,
19836 vector signed long long, const int);
19837 vector unsigned long long vec_sldw (vector unsigned long long,
19838 vector unsigned long long, const int);
19840 vector signed long long vec_unsigned (vector double);
19841 vector signed int vec_unsigned (vector float);
19843 vector signed int vec_unsignede (vector double);
19845 vector signed int vec_unsignedo (vector double);
19847 vector double vec_abs (vector double);
19848 vector double vec_add (vector double, vector double);
19849 vector double vec_and (vector double, vector double);
19850 vector double vec_and (vector double, vector bool long);
19851 vector double vec_and (vector bool long, vector double);
19852 vector long vec_and (vector long, vector long);
19853 vector long vec_and (vector long, vector bool long);
19854 vector long vec_and (vector bool long, vector long);
19855 vector unsigned long vec_and (vector unsigned long, vector unsigned long);
19856 vector unsigned long vec_and (vector unsigned long, vector bool long);
19857 vector unsigned long vec_and (vector bool long, vector unsigned long);
19858 vector double vec_andc (vector double, vector double);
19859 vector double vec_andc (vector double, vector bool long);
19860 vector double vec_andc (vector bool long, vector double);
19861 vector long vec_andc (vector long, vector long);
19862 vector long vec_andc (vector long, vector bool long);
19863 vector long vec_andc (vector bool long, vector long);
19864 vector unsigned long vec_andc (vector unsigned long, vector unsigned long);
19865 vector unsigned long vec_andc (vector unsigned long, vector bool long);
19866 vector unsigned long vec_andc (vector bool long, vector unsigned long);
19867 vector double vec_ceil (vector double);
19868 vector bool long vec_cmpeq (vector double, vector double);
19869 vector bool long vec_cmpge (vector double, vector double);
19870 vector bool long vec_cmpgt (vector double, vector double);
19871 vector bool long vec_cmple (vector double, vector double);
19872 vector bool long vec_cmplt (vector double, vector double);
19873 vector double vec_cpsgn (vector double, vector double);
19874 vector float vec_div (vector float, vector float);
19875 vector double vec_div (vector double, vector double);
19876 vector long vec_div (vector long, vector long);
19877 vector unsigned long vec_div (vector unsigned long, vector unsigned long);
19878 vector double vec_floor (vector double);
19879 vector signed long long vec_ld (int, const vector signed long long *);
19880 vector signed long long vec_ld (int, const signed long long *);
19881 vector unsigned long long vec_ld (int, const vector unsigned long long *);
19882 vector unsigned long long vec_ld (int, const unsigned long long *);
19883 vector __int128 vec_ld (int, const vector __int128 *);
19884 vector unsigned __int128 vec_ld (int, const vector unsigned __int128 *);
19885 vector __int128 vec_ld (int, const __int128 *);
19886 vector unsigned __int128 vec_ld (int, const unsigned __int128 *);
19887 vector double vec_ld (int, const vector double *);
19888 vector double vec_ld (int, const double *);
19889 vector double vec_ldl (int, const vector double *);
19890 vector double vec_ldl (int, const double *);
19891 vector unsigned char vec_lvsl (int, const double *);
19892 vector unsigned char vec_lvsr (int, const double *);
19893 vector double vec_madd (vector double, vector double, vector double);
19894 vector double vec_max (vector double, vector double);
19895 vector signed long vec_mergeh (vector signed long, vector signed long);
19896 vector signed long vec_mergeh (vector signed long, vector bool long);
19897 vector signed long vec_mergeh (vector bool long, vector signed long);
19898 vector unsigned long vec_mergeh (vector unsigned long, vector unsigned long);
19899 vector unsigned long vec_mergeh (vector unsigned long, vector bool long);
19900 vector unsigned long vec_mergeh (vector bool long, vector unsigned long);
19901 vector signed long vec_mergel (vector signed long, vector signed long);
19902 vector signed long vec_mergel (vector signed long, vector bool long);
19903 vector signed long vec_mergel (vector bool long, vector signed long);
19904 vector unsigned long vec_mergel (vector unsigned long, vector unsigned long);
19905 vector unsigned long vec_mergel (vector unsigned long, vector bool long);
19906 vector unsigned long vec_mergel (vector bool long, vector unsigned long);
19907 vector double vec_min (vector double, vector double);
19908 vector float vec_msub (vector float, vector float, vector float);
19909 vector double vec_msub (vector double, vector double, vector double);
19910 vector float vec_nearbyint (vector float);
19911 vector double vec_nearbyint (vector double);
19912 vector float vec_nmadd (vector float, vector float, vector float);
19913 vector double vec_nmadd (vector double, vector double, vector double);
19914 vector double vec_nmsub (vector double, vector double, vector double);
19915 vector double vec_nor (vector double, vector double);
19916 vector long vec_nor (vector long, vector long);
19917 vector long vec_nor (vector long, vector bool long);
19918 vector long vec_nor (vector bool long, vector long);
19919 vector unsigned long vec_nor (vector unsigned long, vector unsigned long);
19920 vector unsigned long vec_nor (vector unsigned long, vector bool long);
19921 vector unsigned long vec_nor (vector bool long, vector unsigned long);
19922 vector double vec_or (vector double, vector double);
19923 vector double vec_or (vector double, vector bool long);
19924 vector double vec_or (vector bool long, vector double);
19925 vector long vec_or (vector long, vector long);
19926 vector long vec_or (vector long, vector bool long);
19927 vector long vec_or (vector bool long, vector long);
19928 vector unsigned long vec_or (vector unsigned long, vector unsigned long);
19929 vector unsigned long vec_or (vector unsigned long, vector bool long);
19930 vector unsigned long vec_or (vector bool long, vector unsigned long);
19931 vector double vec_perm (vector double, vector double, vector unsigned char);
19932 vector long vec_perm (vector long, vector long, vector unsigned char);
19933 vector unsigned long vec_perm (vector unsigned long, vector unsigned long,
19934 vector unsigned char);
19935 vector bool char vec_permxor (vector bool char, vector bool char,
19937 vector unsigned char vec_permxor (vector signed char, vector signed char,
19938 vector signed char);
19939 vector unsigned char vec_permxor (vector unsigned char, vector unsigned char,
19940 vector unsigned char);
19941 vector double vec_rint (vector double);
19942 vector double vec_recip (vector double, vector double);
19943 vector double vec_rsqrt (vector double);
19944 vector double vec_rsqrte (vector double);
19945 vector double vec_sel (vector double, vector double, vector bool long);
19946 vector double vec_sel (vector double, vector double, vector unsigned long);
19947 vector long vec_sel (vector long, vector long, vector long);
19948 vector long vec_sel (vector long, vector long, vector unsigned long);
19949 vector long vec_sel (vector long, vector long, vector bool long);
19950 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19952 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19953 vector unsigned long);
19954 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19956 vector double vec_splats (double);
19957 vector signed long vec_splats (signed long);
19958 vector unsigned long vec_splats (unsigned long);
19959 vector float vec_sqrt (vector float);
19960 vector double vec_sqrt (vector double);
19961 void vec_st (vector signed long long, int, vector signed long long *);
19962 void vec_st (vector signed long long, int, signed long long *);
19963 void vec_st (vector unsigned long long, int, vector unsigned long long *);
19964 void vec_st (vector unsigned long long, int, unsigned long long *);
19965 void vec_st (vector bool long long, int, vector bool long long *);
19966 void vec_st (vector bool long long, int, signed long long *);
19967 void vec_st (vector bool long long, int, unsigned long long *);
19968 void vec_st (vector double, int, vector double *);
19969 void vec_st (vector double, int, double *);
19970 vector double vec_sub (vector double, vector double);
19971 vector double vec_trunc (vector double);
19972 vector double vec_xl (int, vector double *);
19973 vector double vec_xl (int, double *);
19974 vector long long vec_xl (int, vector long long *);
19975 vector long long vec_xl (int, long long *);
19976 vector unsigned long long vec_xl (int, vector unsigned long long *);
19977 vector unsigned long long vec_xl (int, unsigned long long *);
19978 vector float vec_xl (int, vector float *);
19979 vector float vec_xl (int, float *);
19980 vector int vec_xl (int, vector int *);
19981 vector int vec_xl (int, int *);
19982 vector unsigned int vec_xl (int, vector unsigned int *);
19983 vector unsigned int vec_xl (int, unsigned int *);
19984 vector double vec_xor (vector double, vector double);
19985 vector double vec_xor (vector double, vector bool long);
19986 vector double vec_xor (vector bool long, vector double);
19987 vector long vec_xor (vector long, vector long);
19988 vector long vec_xor (vector long, vector bool long);
19989 vector long vec_xor (vector bool long, vector long);
19990 vector unsigned long vec_xor (vector unsigned long, vector unsigned long);
19991 vector unsigned long vec_xor (vector unsigned long, vector bool long);
19992 vector unsigned long vec_xor (vector bool long, vector unsigned long);
19993 void vec_xst (vector double, int, vector double *);
19994 void vec_xst (vector double, int, double *);
19995 void vec_xst (vector long long, int, vector long long *);
19996 void vec_xst (vector long long, int, long long *);
19997 void vec_xst (vector unsigned long long, int, vector unsigned long long *);
19998 void vec_xst (vector unsigned long long, int, unsigned long long *);
19999 void vec_xst (vector float, int, vector float *);
20000 void vec_xst (vector float, int, float *);
20001 void vec_xst (vector int, int, vector int *);
20002 void vec_xst (vector int, int, int *);
20003 void vec_xst (vector unsigned int, int, vector unsigned int *);
20004 void vec_xst (vector unsigned int, int, unsigned int *);
20005 int vec_all_eq (vector double, vector double);
20006 int vec_all_ge (vector double, vector double);
20007 int vec_all_gt (vector double, vector double);
20008 int vec_all_le (vector double, vector double);
20009 int vec_all_lt (vector double, vector double);
20010 int vec_all_nan (vector double);
20011 int vec_all_ne (vector double, vector double);
20012 int vec_all_nge (vector double, vector double);
20013 int vec_all_ngt (vector double, vector double);
20014 int vec_all_nle (vector double, vector double);
20015 int vec_all_nlt (vector double, vector double);
20016 int vec_all_numeric (vector double);
20017 int vec_any_eq (vector double, vector double);
20018 int vec_any_ge (vector double, vector double);
20019 int vec_any_gt (vector double, vector double);
20020 int vec_any_le (vector double, vector double);
20021 int vec_any_lt (vector double, vector double);
20022 int vec_any_nan (vector double);
20023 int vec_any_ne (vector double, vector double);
20024 int vec_any_nge (vector double, vector double);
20025 int vec_any_ngt (vector double, vector double);
20026 int vec_any_nle (vector double, vector double);
20027 int vec_any_nlt (vector double, vector double);
20028 int vec_any_numeric (vector double);
20030 vector double vec_vsx_ld (int, const vector double *);
20031 vector double vec_vsx_ld (int, const double *);
20032 vector float vec_vsx_ld (int, const vector float *);
20033 vector float vec_vsx_ld (int, const float *);
20034 vector bool int vec_vsx_ld (int, const vector bool int *);
20035 vector signed int vec_vsx_ld (int, const vector signed int *);
20036 vector signed int vec_vsx_ld (int, const int *);
20037 vector signed int vec_vsx_ld (int, const long *);
20038 vector unsigned int vec_vsx_ld (int, const vector unsigned int *);
20039 vector unsigned int vec_vsx_ld (int, const unsigned int *);
20040 vector unsigned int vec_vsx_ld (int, const unsigned long *);
20041 vector bool short vec_vsx_ld (int, const vector bool short *);
20042 vector pixel vec_vsx_ld (int, const vector pixel *);
20043 vector signed short vec_vsx_ld (int, const vector signed short *);
20044 vector signed short vec_vsx_ld (int, const short *);
20045 vector unsigned short vec_vsx_ld (int, const vector unsigned short *);
20046 vector unsigned short vec_vsx_ld (int, const unsigned short *);
20047 vector bool char vec_vsx_ld (int, const vector bool char *);
20048 vector signed char vec_vsx_ld (int, const vector signed char *);
20049 vector signed char vec_vsx_ld (int, const signed char *);
20050 vector unsigned char vec_vsx_ld (int, const vector unsigned char *);
20051 vector unsigned char vec_vsx_ld (int, const unsigned char *);
20053 void vec_vsx_st (vector double, int, vector double *);
20054 void vec_vsx_st (vector double, int, double *);
20055 void vec_vsx_st (vector float, int, vector float *);
20056 void vec_vsx_st (vector float, int, float *);
20057 void vec_vsx_st (vector signed int, int, vector signed int *);
20058 void vec_vsx_st (vector signed int, int, int *);
20059 void vec_vsx_st (vector unsigned int, int, vector unsigned int *);
20060 void vec_vsx_st (vector unsigned int, int, unsigned int *);
20061 void vec_vsx_st (vector bool int, int, vector bool int *);
20062 void vec_vsx_st (vector bool int, int, unsigned int *);
20063 void vec_vsx_st (vector bool int, int, int *);
20064 void vec_vsx_st (vector signed short, int, vector signed short *);
20065 void vec_vsx_st (vector signed short, int, short *);
20066 void vec_vsx_st (vector unsigned short, int, vector unsigned short *);
20067 void vec_vsx_st (vector unsigned short, int, unsigned short *);
20068 void vec_vsx_st (vector bool short, int, vector bool short *);
20069 void vec_vsx_st (vector bool short, int, unsigned short *);
20070 void vec_vsx_st (vector pixel, int, vector pixel *);
20071 void vec_vsx_st (vector pixel, int, unsigned short *);
20072 void vec_vsx_st (vector pixel, int, short *);
20073 void vec_vsx_st (vector bool short, int, short *);
20074 void vec_vsx_st (vector signed char, int, vector signed char *);
20075 void vec_vsx_st (vector signed char, int, signed char *);
20076 void vec_vsx_st (vector unsigned char, int, vector unsigned char *);
20077 void vec_vsx_st (vector unsigned char, int, unsigned char *);
20078 void vec_vsx_st (vector bool char, int, vector bool char *);
20079 void vec_vsx_st (vector bool char, int, unsigned char *);
20080 void vec_vsx_st (vector bool char, int, signed char *);
20082 vector double vec_xxpermdi (vector double, vector double, const int);
20083 vector float vec_xxpermdi (vector float, vector float, const int);
20084 vector long long vec_xxpermdi (vector long long, vector long long, const int);
20085 vector unsigned long long vec_xxpermdi (vector unsigned long long,
20086 vector unsigned long long, const int);
20087 vector int vec_xxpermdi (vector int, vector int, const int);
20088 vector unsigned int vec_xxpermdi (vector unsigned int,
20089 vector unsigned int, const int);
20090 vector short vec_xxpermdi (vector short, vector short, const int);
20091 vector unsigned short vec_xxpermdi (vector unsigned short,
20092 vector unsigned short, const int);
20093 vector signed char vec_xxpermdi (vector signed char, vector signed char,
20095 vector unsigned char vec_xxpermdi (vector unsigned char,
20096 vector unsigned char, const int);
20098 vector double vec_xxsldi (vector double, vector double, int);
20099 vector float vec_xxsldi (vector float, vector float, int);
20100 vector long long vec_xxsldi (vector long long, vector long long, int);
20101 vector unsigned long long vec_xxsldi (vector unsigned long long,
20102 vector unsigned long long, int);
20103 vector int vec_xxsldi (vector int, vector int, int);
20104 vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int);
20105 vector short vec_xxsldi (vector short, vector short, int);
20106 vector unsigned short vec_xxsldi (vector unsigned short,
20107 vector unsigned short, int);
20108 vector signed char vec_xxsldi (vector signed char, vector signed char, int);
20109 vector unsigned char vec_xxsldi (vector unsigned char,
20110 vector unsigned char, int);
20113 Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always
20114 generate the AltiVec @samp{LVX} and @samp{STVX} instructions even
20115 if the VSX instruction set is available. The @samp{vec_vsx_ld} and
20116 @samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X},
20117 @samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions.
20119 @node PowerPC AltiVec Built-in Functions Available on ISA 2.07
20120 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07
20122 If the ISA 2.07 additions to the vector/scalar (power8-vector)
20123 instruction set are available, the following additional functions are
20124 available for both 32-bit and 64-bit targets. For 64-bit targets, you
20125 can use @var{vector long} instead of @var{vector long long},
20126 @var{vector bool long} instead of @var{vector bool long long}, and
20127 @var{vector unsigned long} instead of @var{vector unsigned long long}.
20130 vector signed char vec_neg (vector signed char);
20131 vector signed short vec_neg (vector signed short);
20132 vector signed int vec_neg (vector signed int);
20133 vector signed long long vec_neg (vector signed long long);
20134 vector float char vec_neg (vector float);
20135 vector double vec_neg (vector double);
20137 vector signed int vec_signed2 (vector double, vector double);
20139 vector signed int vec_unsigned2 (vector double, vector double);
20141 vector long long vec_abs (vector long long);
20143 vector long long vec_add (vector long long, vector long long);
20144 vector unsigned long long vec_add (vector unsigned long long,
20145 vector unsigned long long);
20147 int vec_all_eq (vector long long, vector long long);
20148 int vec_all_eq (vector unsigned long long, vector unsigned long long);
20149 int vec_all_ge (vector long long, vector long long);
20150 int vec_all_ge (vector unsigned long long, vector unsigned long long);
20151 int vec_all_gt (vector long long, vector long long);
20152 int vec_all_gt (vector unsigned long long, vector unsigned long long);
20153 int vec_all_le (vector long long, vector long long);
20154 int vec_all_le (vector unsigned long long, vector unsigned long long);
20155 int vec_all_lt (vector long long, vector long long);
20156 int vec_all_lt (vector unsigned long long, vector unsigned long long);
20157 int vec_all_ne (vector long long, vector long long);
20158 int vec_all_ne (vector unsigned long long, vector unsigned long long);
20160 int vec_any_eq (vector long long, vector long long);
20161 int vec_any_eq (vector unsigned long long, vector unsigned long long);
20162 int vec_any_ge (vector long long, vector long long);
20163 int vec_any_ge (vector unsigned long long, vector unsigned long long);
20164 int vec_any_gt (vector long long, vector long long);
20165 int vec_any_gt (vector unsigned long long, vector unsigned long long);
20166 int vec_any_le (vector long long, vector long long);
20167 int vec_any_le (vector unsigned long long, vector unsigned long long);
20168 int vec_any_lt (vector long long, vector long long);
20169 int vec_any_lt (vector unsigned long long, vector unsigned long long);
20170 int vec_any_ne (vector long long, vector long long);
20171 int vec_any_ne (vector unsigned long long, vector unsigned long long);
20173 vector bool long long vec_cmpeq (vector bool long long, vector bool long long);
20175 vector long long vec_eqv (vector long long, vector long long);
20176 vector long long vec_eqv (vector bool long long, vector long long);
20177 vector long long vec_eqv (vector long long, vector bool long long);
20178 vector unsigned long long vec_eqv (vector unsigned long long, vector unsigned long long);
20179 vector unsigned long long vec_eqv (vector bool long long, vector unsigned long long);
20180 vector unsigned long long vec_eqv (vector unsigned long long,
20181 vector bool long long);
20182 vector int vec_eqv (vector int, vector int);
20183 vector int vec_eqv (vector bool int, vector int);
20184 vector int vec_eqv (vector int, vector bool int);
20185 vector unsigned int vec_eqv (vector unsigned int, vector unsigned int);
20186 vector unsigned int vec_eqv (vector bool unsigned int, vector unsigned int);
20187 vector unsigned int vec_eqv (vector unsigned int, vector bool unsigned int);
20188 vector short vec_eqv (vector short, vector short);
20189 vector short vec_eqv (vector bool short, vector short);
20190 vector short vec_eqv (vector short, vector bool short);
20191 vector unsigned short vec_eqv (vector unsigned short, vector unsigned short);
20192 vector unsigned short vec_eqv (vector bool unsigned short, vector unsigned short);
20193 vector unsigned short vec_eqv (vector unsigned short, vector bool unsigned short);
20194 vector signed char vec_eqv (vector signed char, vector signed char);
20195 vector signed char vec_eqv (vector bool signed char, vector signed char);
20196 vector signed char vec_eqv (vector signed char, vector bool signed char);
20197 vector unsigned char vec_eqv (vector unsigned char, vector unsigned char);
20198 vector unsigned char vec_eqv (vector bool unsigned char, vector unsigned char);
20199 vector unsigned char vec_eqv (vector unsigned char, vector bool unsigned char);
20201 vector long long vec_max (vector long long, vector long long);
20202 vector unsigned long long vec_max (vector unsigned long long,
20203 vector unsigned long long);
20205 vector signed int vec_mergee (vector signed int, vector signed int);
20206 vector unsigned int vec_mergee (vector unsigned int, vector unsigned int);
20207 vector bool int vec_mergee (vector bool int, vector bool int);
20209 vector signed int vec_mergeo (vector signed int, vector signed int);
20210 vector unsigned int vec_mergeo (vector unsigned int, vector unsigned int);
20211 vector bool int vec_mergeo (vector bool int, vector bool int);
20213 vector long long vec_min (vector long long, vector long long);
20214 vector unsigned long long vec_min (vector unsigned long long,
20215 vector unsigned long long);
20217 vector signed long long vec_nabs (vector signed long long);
20219 vector long long vec_nand (vector long long, vector long long);
20220 vector long long vec_nand (vector bool long long, vector long long);
20221 vector long long vec_nand (vector long long, vector bool long long);
20222 vector unsigned long long vec_nand (vector unsigned long long,
20223 vector unsigned long long);
20224 vector unsigned long long vec_nand (vector bool long long, vector unsigned long long);
20225 vector unsigned long long vec_nand (vector unsigned long long, vector bool long long);
20226 vector int vec_nand (vector int, vector int);
20227 vector int vec_nand (vector bool int, vector int);
20228 vector int vec_nand (vector int, vector bool int);
20229 vector unsigned int vec_nand (vector unsigned int, vector unsigned int);
20230 vector unsigned int vec_nand (vector bool unsigned int, vector unsigned int);
20231 vector unsigned int vec_nand (vector unsigned int, vector bool unsigned int);
20232 vector short vec_nand (vector short, vector short);
20233 vector short vec_nand (vector bool short, vector short);
20234 vector short vec_nand (vector short, vector bool short);
20235 vector unsigned short vec_nand (vector unsigned short, vector unsigned short);
20236 vector unsigned short vec_nand (vector bool unsigned short, vector unsigned short);
20237 vector unsigned short vec_nand (vector unsigned short, vector bool unsigned short);
20238 vector signed char vec_nand (vector signed char, vector signed char);
20239 vector signed char vec_nand (vector bool signed char, vector signed char);
20240 vector signed char vec_nand (vector signed char, vector bool signed char);
20241 vector unsigned char vec_nand (vector unsigned char, vector unsigned char);
20242 vector unsigned char vec_nand (vector bool unsigned char, vector unsigned char);
20243 vector unsigned char vec_nand (vector unsigned char, vector bool unsigned char);
20245 vector long long vec_orc (vector long long, vector long long);
20246 vector long long vec_orc (vector bool long long, vector long long);
20247 vector long long vec_orc (vector long long, vector bool long long);
20248 vector unsigned long long vec_orc (vector unsigned long long,
20249 vector unsigned long long);
20250 vector unsigned long long vec_orc (vector bool long long, vector unsigned long long);
20251 vector unsigned long long vec_orc (vector unsigned long long, vector bool long long);
20252 vector int vec_orc (vector int, vector int);
20253 vector int vec_orc (vector bool int, vector int);
20254 vector int vec_orc (vector int, vector bool int);
20255 vector unsigned int vec_orc (vector unsigned int, vector unsigned int);
20256 vector unsigned int vec_orc (vector bool unsigned int, vector unsigned int);
20257 vector unsigned int vec_orc (vector unsigned int, vector bool unsigned int);
20258 vector short vec_orc (vector short, vector short);
20259 vector short vec_orc (vector bool short, vector short);
20260 vector short vec_orc (vector short, vector bool short);
20261 vector unsigned short vec_orc (vector unsigned short, vector unsigned short);
20262 vector unsigned short vec_orc (vector bool unsigned short, vector unsigned short);
20263 vector unsigned short vec_orc (vector unsigned short, vector bool unsigned short);
20264 vector signed char vec_orc (vector signed char, vector signed char);
20265 vector signed char vec_orc (vector bool signed char, vector signed char);
20266 vector signed char vec_orc (vector signed char, vector bool signed char);
20267 vector unsigned char vec_orc (vector unsigned char, vector unsigned char);
20268 vector unsigned char vec_orc (vector bool unsigned char, vector unsigned char);
20269 vector unsigned char vec_orc (vector unsigned char, vector bool unsigned char);
20271 vector int vec_pack (vector long long, vector long long);
20272 vector unsigned int vec_pack (vector unsigned long long, vector unsigned long long);
20273 vector bool int vec_pack (vector bool long long, vector bool long long);
20274 vector float vec_pack (vector double, vector double);
20276 vector int vec_packs (vector long long, vector long long);
20277 vector unsigned int vec_packs (vector unsigned long long, vector unsigned long long);
20279 vector unsigned char vec_packsu (vector signed short, vector signed short)
20280 vector unsigned char vec_packsu (vector unsigned short, vector unsigned short)
20281 vector unsigned short int vec_packsu (vector signed int, vector signed int);
20282 vector unsigned short int vec_packsu (vector unsigned int, vector unsigned int);
20283 vector unsigned int vec_packsu (vector long long, vector long long);
20284 vector unsigned int vec_packsu (vector unsigned long long, vector unsigned long long);
20285 vector unsigned int vec_packsu (vector signed long long, vector signed long long);
20287 vector unsigned char vec_popcnt (vector signed char);
20288 vector unsigned char vec_popcnt (vector unsigned char);
20289 vector unsigned short vec_popcnt (vector signed short);
20290 vector unsigned short vec_popcnt (vector unsigned short);
20291 vector unsigned int vec_popcnt (vector signed int);
20292 vector unsigned int vec_popcnt (vector unsigned int);
20293 vector unsigned long long vec_popcnt (vector signed long long);
20294 vector unsigned long long vec_popcnt (vector unsigned long long);
20296 vector long long vec_rl (vector long long, vector unsigned long long);
20297 vector long long vec_rl (vector unsigned long long, vector unsigned long long);
20299 vector long long vec_sl (vector long long, vector unsigned long long);
20300 vector long long vec_sl (vector unsigned long long, vector unsigned long long);
20302 vector long long vec_sr (vector long long, vector unsigned long long);
20303 vector unsigned long long char vec_sr (vector unsigned long long,
20304 vector unsigned long long);
20306 vector long long vec_sra (vector long long, vector unsigned long long);
20307 vector unsigned long long vec_sra (vector unsigned long long,
20308 vector unsigned long long);
20310 vector long long vec_sub (vector long long, vector long long);
20311 vector unsigned long long vec_sub (vector unsigned long long,
20312 vector unsigned long long);
20314 vector long long vec_unpackh (vector int);
20315 vector unsigned long long vec_unpackh (vector unsigned int);
20317 vector long long vec_unpackl (vector int);
20318 vector unsigned long long vec_unpackl (vector unsigned int);
20320 vector long long vec_vaddudm (vector long long, vector long long);
20321 vector long long vec_vaddudm (vector bool long long, vector long long);
20322 vector long long vec_vaddudm (vector long long, vector bool long long);
20323 vector unsigned long long vec_vaddudm (vector unsigned long long,
20324 vector unsigned long long);
20325 vector unsigned long long vec_vaddudm (vector bool unsigned long long,
20326 vector unsigned long long);
20327 vector unsigned long long vec_vaddudm (vector unsigned long long,
20328 vector bool unsigned long long);
20330 vector long long vec_vbpermq (vector signed char, vector signed char);
20331 vector long long vec_vbpermq (vector unsigned char, vector unsigned char);
20333 vector unsigned char vec_bperm (vector unsigned char, vector unsigned char);
20334 vector unsigned char vec_bperm (vector unsigned long long, vector unsigned char);
20335 vector unsigned long long vec_bperm (vector unsigned __int128, vector unsigned char);
20337 vector long long vec_cntlz (vector long long);
20338 vector unsigned long long vec_cntlz (vector unsigned long long);
20339 vector int vec_cntlz (vector int);
20340 vector unsigned int vec_cntlz (vector int);
20341 vector short vec_cntlz (vector short);
20342 vector unsigned short vec_cntlz (vector unsigned short);
20343 vector signed char vec_cntlz (vector signed char);
20344 vector unsigned char vec_cntlz (vector unsigned char);
20346 vector long long vec_vclz (vector long long);
20347 vector unsigned long long vec_vclz (vector unsigned long long);
20348 vector int vec_vclz (vector int);
20349 vector unsigned int vec_vclz (vector int);
20350 vector short vec_vclz (vector short);
20351 vector unsigned short vec_vclz (vector unsigned short);
20352 vector signed char vec_vclz (vector signed char);
20353 vector unsigned char vec_vclz (vector unsigned char);
20355 vector signed char vec_vclzb (vector signed char);
20356 vector unsigned char vec_vclzb (vector unsigned char);
20358 vector long long vec_vclzd (vector long long);
20359 vector unsigned long long vec_vclzd (vector unsigned long long);
20361 vector short vec_vclzh (vector short);
20362 vector unsigned short vec_vclzh (vector unsigned short);
20364 vector int vec_vclzw (vector int);
20365 vector unsigned int vec_vclzw (vector int);
20367 vector signed char vec_vgbbd (vector signed char);
20368 vector unsigned char vec_vgbbd (vector unsigned char);
20370 vector long long vec_vmaxsd (vector long long, vector long long);
20372 vector unsigned long long vec_vmaxud (vector unsigned long long,
20373 unsigned vector long long);
20375 vector long long vec_vminsd (vector long long, vector long long);
20377 vector unsigned long long vec_vminud (vector long long, vector long long);
20379 vector int vec_vpksdss (vector long long, vector long long);
20380 vector unsigned int vec_vpksdss (vector long long, vector long long);
20382 vector unsigned int vec_vpkudus (vector unsigned long long,
20383 vector unsigned long long);
20385 vector int vec_vpkudum (vector long long, vector long long);
20386 vector unsigned int vec_vpkudum (vector unsigned long long,
20387 vector unsigned long long);
20388 vector bool int vec_vpkudum (vector bool long long, vector bool long long);
20390 vector long long vec_vpopcnt (vector long long);
20391 vector unsigned long long vec_vpopcnt (vector unsigned long long);
20392 vector int vec_vpopcnt (vector int);
20393 vector unsigned int vec_vpopcnt (vector int);
20394 vector short vec_vpopcnt (vector short);
20395 vector unsigned short vec_vpopcnt (vector unsigned short);
20396 vector signed char vec_vpopcnt (vector signed char);
20397 vector unsigned char vec_vpopcnt (vector unsigned char);
20399 vector signed char vec_vpopcntb (vector signed char);
20400 vector unsigned char vec_vpopcntb (vector unsigned char);
20402 vector long long vec_vpopcntd (vector long long);
20403 vector unsigned long long vec_vpopcntd (vector unsigned long long);
20405 vector short vec_vpopcnth (vector short);
20406 vector unsigned short vec_vpopcnth (vector unsigned short);
20408 vector int vec_vpopcntw (vector int);
20409 vector unsigned int vec_vpopcntw (vector int);
20411 vector long long vec_vrld (vector long long, vector unsigned long long);
20412 vector unsigned long long vec_vrld (vector unsigned long long,
20413 vector unsigned long long);
20415 vector long long vec_vsld (vector long long, vector unsigned long long);
20416 vector long long vec_vsld (vector unsigned long long,
20417 vector unsigned long long);
20419 vector long long vec_vsrad (vector long long, vector unsigned long long);
20420 vector unsigned long long vec_vsrad (vector unsigned long long,
20421 vector unsigned long long);
20423 vector long long vec_vsrd (vector long long, vector unsigned long long);
20424 vector unsigned long long char vec_vsrd (vector unsigned long long,
20425 vector unsigned long long);
20427 vector long long vec_vsubudm (vector long long, vector long long);
20428 vector long long vec_vsubudm (vector bool long long, vector long long);
20429 vector long long vec_vsubudm (vector long long, vector bool long long);
20430 vector unsigned long long vec_vsubudm (vector unsigned long long,
20431 vector unsigned long long);
20432 vector unsigned long long vec_vsubudm (vector bool long long,
20433 vector unsigned long long);
20434 vector unsigned long long vec_vsubudm (vector unsigned long long,
20435 vector bool long long);
20437 vector long long vec_vupkhsw (vector int);
20438 vector unsigned long long vec_vupkhsw (vector unsigned int);
20440 vector long long vec_vupklsw (vector int);
20441 vector unsigned long long vec_vupklsw (vector int);
20444 If the ISA 2.07 additions to the vector/scalar (power8-vector)
20445 instruction set are available, the following additional functions are
20446 available for 64-bit targets. New vector types
20447 (@var{vector __int128} and @var{vector __uint128}) are available
20448 to hold the @var{__int128} and @var{__uint128} types to use these
20451 The normal vector extract, and set operations work on
20452 @var{vector __int128} and @var{vector __uint128} types,
20453 but the index value must be 0.
20456 vector __int128 vec_vaddcuq (vector __int128, vector __int128);
20457 vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128);
20459 vector __int128 vec_vadduqm (vector __int128, vector __int128);
20460 vector __uint128 vec_vadduqm (vector __uint128, vector __uint128);
20462 vector __int128 vec_vaddecuq (vector __int128, vector __int128,
20464 vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128,
20467 vector __int128 vec_vaddeuqm (vector __int128, vector __int128,
20469 vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128,
20472 vector __int128 vec_vsubecuq (vector __int128, vector __int128,
20474 vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128,
20477 vector __int128 vec_vsubeuqm (vector __int128, vector __int128,
20479 vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128,
20482 vector __int128 vec_vsubcuq (vector __int128, vector __int128);
20483 vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128);
20485 __int128 vec_vsubuqm (__int128, __int128);
20486 __uint128 vec_vsubuqm (__uint128, __uint128);
20488 vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int);
20489 vector unsigned char __builtin_bcdadd (vector unsigned char, vector unsigned char,
20491 int __builtin_bcdadd_lt (vector __int128, vector __int128, const int);
20492 int __builtin_bcdadd_lt (vector unsigned char, vector unsigned char, const int);
20493 int __builtin_bcdadd_eq (vector __int128, vector __int128, const int);
20494 int __builtin_bcdadd_eq (vector unsigned char, vector unsigned char, const int);
20495 int __builtin_bcdadd_gt (vector __int128, vector __int128, const int);
20496 int __builtin_bcdadd_gt (vector unsigned char, vector unsigned char, const int);
20497 int __builtin_bcdadd_ov (vector __int128, vector __int128, const int);
20498 int __builtin_bcdadd_ov (vector unsigned char, vector unsigned char, const int);
20500 vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int);
20501 vector unsigned char __builtin_bcdsub (vector unsigned char, vector unsigned char,
20503 int __builtin_bcdsub_lt (vector __int128, vector __int128, const int);
20504 int __builtin_bcdsub_lt (vector unsigned char, vector unsigned char, const int);
20505 int __builtin_bcdsub_eq (vector __int128, vector __int128, const int);
20506 int __builtin_bcdsub_eq (vector unsigned char, vector unsigned char, const int);
20507 int __builtin_bcdsub_gt (vector __int128, vector __int128, const int);
20508 int __builtin_bcdsub_gt (vector unsigned char, vector unsigned char, const int);
20509 int __builtin_bcdsub_ov (vector __int128, vector __int128, const int);
20510 int __builtin_bcdsub_ov (vector unsigned char, vector unsigned char, const int);
20513 @node PowerPC AltiVec Built-in Functions Available on ISA 3.0
20514 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0
20516 The following additional built-in functions are also available for the
20517 PowerPC family of processors, starting with ISA 3.0
20518 (@option{-mcpu=power9}) or later:
20520 unsigned int scalar_extract_exp (double source);
20521 unsigned long long int scalar_extract_exp (__ieee128 source);
20523 unsigned long long int scalar_extract_sig (double source);
20524 unsigned __int128 scalar_extract_sig (__ieee128 source);
20526 double scalar_insert_exp (unsigned long long int significand,
20527 unsigned long long int exponent);
20528 double scalar_insert_exp (double significand, unsigned long long int exponent);
20530 ieee_128 scalar_insert_exp (unsigned __int128 significand,
20531 unsigned long long int exponent);
20532 ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent);
20534 int scalar_cmp_exp_gt (double arg1, double arg2);
20535 int scalar_cmp_exp_lt (double arg1, double arg2);
20536 int scalar_cmp_exp_eq (double arg1, double arg2);
20537 int scalar_cmp_exp_unordered (double arg1, double arg2);
20539 bool scalar_test_data_class (float source, const int condition);
20540 bool scalar_test_data_class (double source, const int condition);
20541 bool scalar_test_data_class (__ieee128 source, const int condition);
20543 bool scalar_test_neg (float source);
20544 bool scalar_test_neg (double source);
20545 bool scalar_test_neg (__ieee128 source);
20547 vector _uint128_t vec_msum (vector unsigned long long,
20548 vector unsigned long long,
20549 vector _uint128_t);
20550 vector _int128_t vec_msum (vector signed long long,
20551 vector signed long long,
20555 The @code{scalar_extract_exp} and @code{scalar_extract_sig}
20556 functions require a 64-bit environment supporting ISA 3.0 or later.
20557 The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in
20558 functions return the significand and the biased exponent value
20559 respectively of their @code{source} arguments.
20560 When supplied with a 64-bit @code{source} argument, the
20561 result returned by @code{scalar_extract_sig} has
20562 the @code{0x0010000000000000} bit set if the
20563 function's @code{source} argument is in normalized form.
20564 Otherwise, this bit is set to 0.
20565 When supplied with a 128-bit @code{source} argument, the
20566 @code{0x00010000000000000000000000000000} bit of the result is
20568 Note that the sign of the significand is not represented in the result
20569 returned from the @code{scalar_extract_sig} function. Use the
20570 @code{scalar_test_neg} function to test the sign of its @code{double}
20572 The @code{vec_msum} functions perform a vector multiply-sum, returning
20573 the result of arg1*arg2+arg3. ISA 3.0 adds support for vec_msum returning
20574 a vector int128 result.
20576 The @code{scalar_insert_exp}
20577 functions require a 64-bit environment supporting ISA 3.0 or later.
20578 When supplied with a 64-bit first argument, the
20579 @code{scalar_insert_exp} built-in function returns a double-precision
20580 floating point value that is constructed by assembling the values of its
20581 @code{significand} and @code{exponent} arguments. The sign of the
20582 result is copied from the most significant bit of the
20583 @code{significand} argument. The significand and exponent components
20584 of the result are composed of the least significant 11 bits of the
20585 @code{exponent} argument and the least significant 52 bits of the
20586 @code{significand} argument respectively.
20588 When supplied with a 128-bit first argument, the
20589 @code{scalar_insert_exp} built-in function returns a quad-precision
20590 ieee floating point value. The sign bit of the result is copied from
20591 the most significant bit of the @code{significand} argument.
20592 The significand and exponent components of the result are composed of
20593 the least significant 15 bits of the @code{exponent} argument and the
20594 least significant 112 bits of the @code{significand} argument respectively.
20596 The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt},
20597 @code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in
20598 functions return a non-zero value if @code{arg1} is greater than, less
20599 than, equal to, or not comparable to @code{arg2} respectively. The
20600 arguments are not comparable if one or the other equals NaN (not a
20603 The @code{scalar_test_data_class} built-in function returns 1
20604 if any of the condition tests enabled by the value of the
20605 @code{condition} variable are true, and 0 otherwise. The
20606 @code{condition} argument must be a compile-time constant integer with
20607 value not exceeding 127. The
20608 @code{condition} argument is encoded as a bitmask with each bit
20609 enabling the testing of a different condition, as characterized by the
20613 0x20 Test for +Infinity
20614 0x10 Test for -Infinity
20615 0x08 Test for +Zero
20616 0x04 Test for -Zero
20617 0x02 Test for +Denormal
20618 0x01 Test for -Denormal
20621 The @code{scalar_test_neg} built-in function returns 1 if its
20622 @code{source} argument holds a negative value, 0 otherwise.
20624 The following built-in functions are also available for the PowerPC family
20625 of processors, starting with ISA 3.0 or later
20626 (@option{-mcpu=power9}). These string functions are described
20627 separately in order to group the descriptions closer to the function
20630 int vec_all_nez (vector signed char, vector signed char);
20631 int vec_all_nez (vector unsigned char, vector unsigned char);
20632 int vec_all_nez (vector signed short, vector signed short);
20633 int vec_all_nez (vector unsigned short, vector unsigned short);
20634 int vec_all_nez (vector signed int, vector signed int);
20635 int vec_all_nez (vector unsigned int, vector unsigned int);
20637 int vec_any_eqz (vector signed char, vector signed char);
20638 int vec_any_eqz (vector unsigned char, vector unsigned char);
20639 int vec_any_eqz (vector signed short, vector signed short);
20640 int vec_any_eqz (vector unsigned short, vector unsigned short);
20641 int vec_any_eqz (vector signed int, vector signed int);
20642 int vec_any_eqz (vector unsigned int, vector unsigned int);
20644 vector bool char vec_cmpnez (vector signed char arg1, vector signed char arg2);
20645 vector bool char vec_cmpnez (vector unsigned char arg1, vector unsigned char arg2);
20646 vector bool short vec_cmpnez (vector signed short arg1, vector signed short arg2);
20647 vector bool short vec_cmpnez (vector unsigned short arg1, vector unsigned short arg2);
20648 vector bool int vec_cmpnez (vector signed int arg1, vector signed int arg2);
20649 vector bool int vec_cmpnez (vector unsigned int, vector unsigned int);
20651 vector signed char vec_cnttz (vector signed char);
20652 vector unsigned char vec_cnttz (vector unsigned char);
20653 vector signed short vec_cnttz (vector signed short);
20654 vector unsigned short vec_cnttz (vector unsigned short);
20655 vector signed int vec_cnttz (vector signed int);
20656 vector unsigned int vec_cnttz (vector unsigned int);
20657 vector signed long long vec_cnttz (vector signed long long);
20658 vector unsigned long long vec_cnttz (vector unsigned long long);
20660 signed int vec_cntlz_lsbb (vector signed char);
20661 signed int vec_cntlz_lsbb (vector unsigned char);
20663 signed int vec_cnttz_lsbb (vector signed char);
20664 signed int vec_cnttz_lsbb (vector unsigned char);
20666 unsigned int vec_first_match_index (vector signed char, vector signed char);
20667 unsigned int vec_first_match_index (vector unsigned char, vector unsigned char);
20668 unsigned int vec_first_match_index (vector signed int, vector signed int);
20669 unsigned int vec_first_match_index (vector unsigned int, vector unsigned int);
20670 unsigned int vec_first_match_index (vector signed short, vector signed short);
20671 unsigned int vec_first_match_index (vector unsigned short, vector unsigned short);
20672 unsigned int vec_first_match_or_eos_index (vector signed char, vector signed char);
20673 unsigned int vec_first_match_or_eos_index (vector unsigned char, vector unsigned char);
20674 unsigned int vec_first_match_or_eos_index (vector signed int, vector signed int);
20675 unsigned int vec_first_match_or_eos_index (vector unsigned int, vector unsigned int);
20676 unsigned int vec_first_match_or_eos_index (vector signed short, vector signed short);
20677 unsigned int vec_first_match_or_eos_index (vector unsigned short,
20678 vector unsigned short);
20679 unsigned int vec_first_mismatch_index (vector signed char, vector signed char);
20680 unsigned int vec_first_mismatch_index (vector unsigned char, vector unsigned char);
20681 unsigned int vec_first_mismatch_index (vector signed int, vector signed int);
20682 unsigned int vec_first_mismatch_index (vector unsigned int, vector unsigned int);
20683 unsigned int vec_first_mismatch_index (vector signed short, vector signed short);
20684 unsigned int vec_first_mismatch_index (vector unsigned short, vector unsigned short);
20685 unsigned int vec_first_mismatch_or_eos_index (vector signed char, vector signed char);
20686 unsigned int vec_first_mismatch_or_eos_index (vector unsigned char,
20687 vector unsigned char);
20688 unsigned int vec_first_mismatch_or_eos_index (vector signed int, vector signed int);
20689 unsigned int vec_first_mismatch_or_eos_index (vector unsigned int, vector unsigned int);
20690 unsigned int vec_first_mismatch_or_eos_index (vector signed short, vector signed short);
20691 unsigned int vec_first_mismatch_or_eos_index (vector unsigned short,
20692 vector unsigned short);
20694 vector unsigned short vec_pack_to_short_fp32 (vector float, vector float);
20696 vector signed char vec_xl_be (signed long long, signed char *);
20697 vector unsigned char vec_xl_be (signed long long, unsigned char *);
20698 vector signed int vec_xl_be (signed long long, signed int *);
20699 vector unsigned int vec_xl_be (signed long long, unsigned int *);
20700 vector signed __int128 vec_xl_be (signed long long, signed __int128 *);
20701 vector unsigned __int128 vec_xl_be (signed long long, unsigned __int128 *);
20702 vector signed long long vec_xl_be (signed long long, signed long long *);
20703 vector unsigned long long vec_xl_be (signed long long, unsigned long long *);
20704 vector signed short vec_xl_be (signed long long, signed short *);
20705 vector unsigned short vec_xl_be (signed long long, unsigned short *);
20706 vector double vec_xl_be (signed long long, double *);
20707 vector float vec_xl_be (signed long long, float *);
20709 vector signed char vec_xl_len (signed char *addr, size_t len);
20710 vector unsigned char vec_xl_len (unsigned char *addr, size_t len);
20711 vector signed int vec_xl_len (signed int *addr, size_t len);
20712 vector unsigned int vec_xl_len (unsigned int *addr, size_t len);
20713 vector signed __int128 vec_xl_len (signed __int128 *addr, size_t len);
20714 vector unsigned __int128 vec_xl_len (unsigned __int128 *addr, size_t len);
20715 vector signed long long vec_xl_len (signed long long *addr, size_t len);
20716 vector unsigned long long vec_xl_len (unsigned long long *addr, size_t len);
20717 vector signed short vec_xl_len (signed short *addr, size_t len);
20718 vector unsigned short vec_xl_len (unsigned short *addr, size_t len);
20719 vector double vec_xl_len (double *addr, size_t len);
20720 vector float vec_xl_len (float *addr, size_t len);
20722 vector unsigned char vec_xl_len_r (unsigned char *addr, size_t len);
20724 void vec_xst_len (vector signed char data, signed char *addr, size_t len);
20725 void vec_xst_len (vector unsigned char data, unsigned char *addr, size_t len);
20726 void vec_xst_len (vector signed int data, signed int *addr, size_t len);
20727 void vec_xst_len (vector unsigned int data, unsigned int *addr, size_t len);
20728 void vec_xst_len (vector unsigned __int128 data, unsigned __int128 *addr, size_t len);
20729 void vec_xst_len (vector signed long long data, signed long long *addr, size_t len);
20730 void vec_xst_len (vector unsigned long long data, unsigned long long *addr, size_t len);
20731 void vec_xst_len (vector signed short data, signed short *addr, size_t len);
20732 void vec_xst_len (vector unsigned short data, unsigned short *addr, size_t len);
20733 void vec_xst_len (vector signed __int128 data, signed __int128 *addr, size_t len);
20734 void vec_xst_len (vector double data, double *addr, size_t len);
20735 void vec_xst_len (vector float data, float *addr, size_t len);
20737 void vec_xst_len_r (vector unsigned char data, unsigned char *addr, size_t len);
20739 signed char vec_xlx (unsigned int index, vector signed char data);
20740 unsigned char vec_xlx (unsigned int index, vector unsigned char data);
20741 signed short vec_xlx (unsigned int index, vector signed short data);
20742 unsigned short vec_xlx (unsigned int index, vector unsigned short data);
20743 signed int vec_xlx (unsigned int index, vector signed int data);
20744 unsigned int vec_xlx (unsigned int index, vector unsigned int data);
20745 float vec_xlx (unsigned int index, vector float data);
20747 signed char vec_xrx (unsigned int index, vector signed char data);
20748 unsigned char vec_xrx (unsigned int index, vector unsigned char data);
20749 signed short vec_xrx (unsigned int index, vector signed short data);
20750 unsigned short vec_xrx (unsigned int index, vector unsigned short data);
20751 signed int vec_xrx (unsigned int index, vector signed int data);
20752 unsigned int vec_xrx (unsigned int index, vector unsigned int data);
20753 float vec_xrx (unsigned int index, vector float data);
20756 The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez}
20757 perform pairwise comparisons between the elements at the same
20758 positions within their two vector arguments.
20759 The @code{vec_all_nez} function returns a
20760 non-zero value if and only if all pairwise comparisons are not
20761 equal and no element of either vector argument contains a zero.
20762 The @code{vec_any_eqz} function returns a
20763 non-zero value if and only if at least one pairwise comparison is equal
20764 or if at least one element of either vector argument contains a zero.
20765 The @code{vec_cmpnez} function returns a vector of the same type as
20766 its two arguments, within which each element consists of all ones to
20767 denote that either the corresponding elements of the incoming arguments are
20768 not equal or that at least one of the corresponding elements contains
20769 zero. Otherwise, the element of the returned vector contains all zeros.
20771 The @code{vec_cntlz_lsbb} function returns the count of the number of
20772 consecutive leading byte elements (starting from position 0 within the
20773 supplied vector argument) for which the least-significant bit
20774 equals zero. The @code{vec_cnttz_lsbb} function returns the count of
20775 the number of consecutive trailing byte elements (starting from
20776 position 15 and counting backwards within the supplied vector
20777 argument) for which the least-significant bit equals zero.
20779 The @code{vec_xl_len} and @code{vec_xst_len} functions require a
20780 64-bit environment supporting ISA 3.0 or later. The @code{vec_xl_len}
20781 function loads a variable length vector from memory. The
20782 @code{vec_xst_len} function stores a variable length vector to memory.
20783 With both the @code{vec_xl_len} and @code{vec_xst_len} functions, the
20784 @code{addr} argument represents the memory address to or from which
20785 data will be transferred, and the
20786 @code{len} argument represents the number of bytes to be
20787 transferred, as computed by the C expression @code{min((len & 0xff), 16)}.
20788 If this expression's value is not a multiple of the vector element's
20789 size, the behavior of this function is undefined.
20790 In the case that the underlying computer is configured to run in
20791 big-endian mode, the data transfer moves bytes 0 to @code{(len - 1)} of
20792 the corresponding vector. In little-endian mode, the data transfer
20793 moves bytes @code{(16 - len)} to @code{15} of the corresponding
20794 vector. For the load function, any bytes of the result vector that
20795 are not loaded from memory are set to zero.
20796 The value of the @code{addr} argument need not be aligned on a
20797 multiple of the vector's element size.
20799 The @code{vec_xlx} and @code{vec_xrx} functions extract the single
20800 element selected by the @code{index} argument from the vector
20801 represented by the @code{data} argument. The @code{index} argument
20802 always specifies a byte offset, regardless of the size of the vector
20803 element. With @code{vec_xlx}, @code{index} is the offset of the first
20804 byte of the element to be extracted. With @code{vec_xrx}, @code{index}
20805 represents the last byte of the element to be extracted, measured
20806 from the right end of the vector. In other words, the last byte of
20807 the element to be extracted is found at position @code{(15 - index)}.
20808 There is no requirement that @code{index} be a multiple of the vector
20809 element size. However, if the size of the vector element added to
20810 @code{index} is greater than 15, the content of the returned value is
20813 If the ISA 3.0 instruction set additions (@option{-mcpu=power9})
20817 vector unsigned long long vec_bperm (vector unsigned long long, vector unsigned char);
20819 vector bool char vec_cmpne (vector bool char, vector bool char);
20820 vector bool char vec_cmpne (vector signed char, vector signed char);
20821 vector bool char vec_cmpne (vector unsigned char, vector unsigned char);
20822 vector bool int vec_cmpne (vector bool int, vector bool int);
20823 vector bool int vec_cmpne (vector signed int, vector signed int);
20824 vector bool int vec_cmpne (vector unsigned int, vector unsigned int);
20825 vector bool long long vec_cmpne (vector bool long long, vector bool long long);
20826 vector bool long long vec_cmpne (vector signed long long, vector signed long long);
20827 vector bool long long vec_cmpne (vector unsigned long long, vector unsigned long long);
20828 vector bool short vec_cmpne (vector bool short, vector bool short);
20829 vector bool short vec_cmpne (vector signed short, vector signed short);
20830 vector bool short vec_cmpne (vector unsigned short, vector unsigned short);
20831 vector bool long long vec_cmpne (vector double, vector double);
20832 vector bool int vec_cmpne (vector float, vector float);
20834 vector float vec_extract_fp32_from_shorth (vector unsigned short);
20835 vector float vec_extract_fp32_from_shortl (vector unsigned short);
20837 vector long long vec_vctz (vector long long);
20838 vector unsigned long long vec_vctz (vector unsigned long long);
20839 vector int vec_vctz (vector int);
20840 vector unsigned int vec_vctz (vector int);
20841 vector short vec_vctz (vector short);
20842 vector unsigned short vec_vctz (vector unsigned short);
20843 vector signed char vec_vctz (vector signed char);
20844 vector unsigned char vec_vctz (vector unsigned char);
20846 vector signed char vec_vctzb (vector signed char);
20847 vector unsigned char vec_vctzb (vector unsigned char);
20849 vector long long vec_vctzd (vector long long);
20850 vector unsigned long long vec_vctzd (vector unsigned long long);
20852 vector short vec_vctzh (vector short);
20853 vector unsigned short vec_vctzh (vector unsigned short);
20855 vector int vec_vctzw (vector int);
20856 vector unsigned int vec_vctzw (vector int);
20858 vector unsigned long long vec_extract4b (vector unsigned char, const int);
20860 vector unsigned char vec_insert4b (vector signed int, vector unsigned char,
20862 vector unsigned char vec_insert4b (vector unsigned int, vector unsigned char,
20865 vector unsigned int vec_parity_lsbb (vector signed int);
20866 vector unsigned int vec_parity_lsbb (vector unsigned int);
20867 vector unsigned __int128 vec_parity_lsbb (vector signed __int128);
20868 vector unsigned __int128 vec_parity_lsbb (vector unsigned __int128);
20869 vector unsigned long long vec_parity_lsbb (vector signed long long);
20870 vector unsigned long long vec_parity_lsbb (vector unsigned long long);
20872 vector int vec_vprtyb (vector int);
20873 vector unsigned int vec_vprtyb (vector unsigned int);
20874 vector long long vec_vprtyb (vector long long);
20875 vector unsigned long long vec_vprtyb (vector unsigned long long);
20877 vector int vec_vprtybw (vector int);
20878 vector unsigned int vec_vprtybw (vector unsigned int);
20880 vector long long vec_vprtybd (vector long long);
20881 vector unsigned long long vec_vprtybd (vector unsigned long long);
20884 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
20888 vector long vec_vprtyb (vector long);
20889 vector unsigned long vec_vprtyb (vector unsigned long);
20890 vector __int128 vec_vprtyb (vector __int128);
20891 vector __uint128 vec_vprtyb (vector __uint128);
20893 vector long vec_vprtybd (vector long);
20894 vector unsigned long vec_vprtybd (vector unsigned long);
20896 vector __int128 vec_vprtybq (vector __int128);
20897 vector __uint128 vec_vprtybd (vector __uint128);
20900 The following built-in vector functions are available for the PowerPC family
20901 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20903 __vector unsigned char
20904 vec_slv (__vector unsigned char src, __vector unsigned char shift_distance);
20905 __vector unsigned char
20906 vec_srv (__vector unsigned char src, __vector unsigned char shift_distance);
20909 The @code{vec_slv} and @code{vec_srv} functions operate on
20910 all of the bytes of their @code{src} and @code{shift_distance}
20911 arguments in parallel. The behavior of the @code{vec_slv} is as if
20912 there existed a temporary array of 17 unsigned characters
20913 @code{slv_array} within which elements 0 through 15 are the same as
20914 the entries in the @code{src} array and element 16 equals 0. The
20915 result returned from the @code{vec_slv} function is a
20916 @code{__vector} of 16 unsigned characters within which element
20917 @code{i} is computed using the C expression
20918 @code{0xff & (*((unsigned short *)(slv_array + i)) << (0x07 &
20919 shift_distance[i]))},
20920 with this resulting value coerced to the @code{unsigned char} type.
20921 The behavior of the @code{vec_srv} is as if
20922 there existed a temporary array of 17 unsigned characters
20923 @code{srv_array} within which element 0 equals zero and
20924 elements 1 through 16 equal the elements 0 through 15 of
20925 the @code{src} array. The
20926 result returned from the @code{vec_srv} function is a
20927 @code{__vector} of 16 unsigned characters within which element
20928 @code{i} is computed using the C expression
20929 @code{0xff & (*((unsigned short *)(srv_array + i)) >>
20930 (0x07 & shift_distance[i]))},
20931 with this resulting value coerced to the @code{unsigned char} type.
20933 The following built-in functions are available for the PowerPC family
20934 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20936 __vector unsigned char
20937 vec_absd (__vector unsigned char arg1, __vector unsigned char arg2);
20938 __vector unsigned short
20939 vec_absd (__vector unsigned short arg1, __vector unsigned short arg2);
20940 __vector unsigned int
20941 vec_absd (__vector unsigned int arg1, __vector unsigned int arg2);
20943 __vector unsigned char
20944 vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2);
20945 __vector unsigned short
20946 vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2);
20947 __vector unsigned int
20948 vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2);
20951 The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and
20952 @code{vec_absdw} built-in functions each computes the absolute
20953 differences of the pairs of vector elements supplied in its two vector
20954 arguments, placing the absolute differences into the corresponding
20955 elements of the vector result.
20957 The following built-in functions are available for the PowerPC family
20958 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20960 __vector unsigned int vec_extract_exp (__vector float source);
20961 __vector unsigned long long int vec_extract_exp (__vector double source);
20963 __vector unsigned int vec_extract_sig (__vector float source);
20964 __vector unsigned long long int vec_extract_sig (__vector double source);
20966 __vector float vec_insert_exp (__vector unsigned int significands,
20967 __vector unsigned int exponents);
20968 __vector float vec_insert_exp (__vector unsigned float significands,
20969 __vector unsigned int exponents);
20970 __vector double vec_insert_exp (__vector unsigned long long int significands,
20971 __vector unsigned long long int exponents);
20972 __vector double vec_insert_exp (__vector unsigned double significands,
20973 __vector unsigned long long int exponents);
20975 __vector bool int vec_test_data_class (__vector float source, const int condition);
20976 __vector bool long long int vec_test_data_class (__vector double source,
20977 const int condition);
20980 The @code{vec_extract_sig} and @code{vec_extract_exp} built-in
20981 functions return vectors representing the significands and biased
20982 exponent values of their @code{source} arguments respectively.
20983 Within the result vector returned by @code{vec_extract_sig}, the
20984 @code{0x800000} bit of each vector element returned when the
20985 function's @code{source} argument is of type @code{float} is set to 1
20986 if the corresponding floating point value is in normalized form.
20987 Otherwise, this bit is set to 0. When the @code{source} argument is
20988 of type @code{double}, the @code{0x10000000000000} bit within each of
20989 the result vector's elements is set according to the same rules.
20990 Note that the sign of the significand is not represented in the result
20991 returned from the @code{vec_extract_sig} function. To extract the
20993 @code{vec_cpsgn} function, which returns a new vector within which all
20994 of the sign bits of its second argument vector are overwritten with the
20995 sign bits copied from the coresponding elements of its first argument
20996 vector, and all other (non-sign) bits of the second argument vector
20997 are copied unchanged into the result vector.
20999 The @code{vec_insert_exp} built-in functions return a vector of
21000 single- or double-precision floating
21001 point values constructed by assembling the values of their
21002 @code{significands} and @code{exponents} arguments into the
21003 corresponding elements of the returned vector.
21005 element of the result is copied from the most significant bit of the
21006 corresponding entry within the @code{significands} argument.
21007 Note that the relevant
21008 bits of the @code{significands} argument are the same, for both integer
21009 and floating point types.
21011 significand and exponent components of each element of the result are
21012 composed of the least significant bits of the corresponding
21013 @code{significands} element and the least significant bits of the
21014 corresponding @code{exponents} element.
21016 The @code{vec_test_data_class} built-in function returns a vector
21017 representing the results of testing the @code{source} vector for the
21018 condition selected by the @code{condition} argument. The
21019 @code{condition} argument must be a compile-time constant integer with
21020 value not exceeding 127. The
21021 @code{condition} argument is encoded as a bitmask with each bit
21022 enabling the testing of a different condition, as characterized by the
21026 0x20 Test for +Infinity
21027 0x10 Test for -Infinity
21028 0x08 Test for +Zero
21029 0x04 Test for -Zero
21030 0x02 Test for +Denormal
21031 0x01 Test for -Denormal
21034 If any of the enabled test conditions is true, the corresponding entry
21035 in the result vector is -1. Otherwise (all of the enabled test
21036 conditions are false), the corresponding entry of the result vector is 0.
21038 The following built-in functions are available for the PowerPC family
21039 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
21041 vector unsigned int vec_rlmi (vector unsigned int, vector unsigned int,
21042 vector unsigned int);
21043 vector unsigned long long vec_rlmi (vector unsigned long long,
21044 vector unsigned long long,
21045 vector unsigned long long);
21046 vector unsigned int vec_rlnm (vector unsigned int, vector unsigned int,
21047 vector unsigned int);
21048 vector unsigned long long vec_rlnm (vector unsigned long long,
21049 vector unsigned long long,
21050 vector unsigned long long);
21051 vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int);
21052 vector unsigned long long vec_vrlnm (vector unsigned long long,
21053 vector unsigned long long);
21056 The result of @code{vec_rlmi} is obtained by rotating each element of
21057 the first argument vector left and inserting it under mask into the
21058 second argument vector. The third argument vector contains the mask
21059 beginning in bits 11:15, the mask end in bits 19:23, and the shift
21060 count in bits 27:31, of each element.
21062 The result of @code{vec_rlnm} is obtained by rotating each element of
21063 the first argument vector left and ANDing it with a mask specified by
21064 the second and third argument vectors. The second argument vector
21065 contains the shift count for each element in the low-order byte. The
21066 third argument vector contains the mask end for each element in the
21067 low-order byte, with the mask begin in the next higher byte.
21069 The result of @code{vec_vrlnm} is obtained by rotating each element
21070 of the first argument vector left and ANDing it with a mask. The
21071 second argument vector contains the mask beginning in bits 11:15,
21072 the mask end in bits 19:23, and the shift count in bits 27:31,
21075 If the ISA 3.0 instruction set additions (@option{-mcpu=power9})
21078 vector signed bool char vec_revb (vector signed char);
21079 vector signed char vec_revb (vector signed char);
21080 vector unsigned char vec_revb (vector unsigned char);
21081 vector bool short vec_revb (vector bool short);
21082 vector short vec_revb (vector short);
21083 vector unsigned short vec_revb (vector unsigned short);
21084 vector bool int vec_revb (vector bool int);
21085 vector int vec_revb (vector int);
21086 vector unsigned int vec_revb (vector unsigned int);
21087 vector float vec_revb (vector float);
21088 vector bool long long vec_revb (vector bool long long);
21089 vector long long vec_revb (vector long long);
21090 vector unsigned long long vec_revb (vector unsigned long long);
21091 vector double vec_revb (vector double);
21094 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
21097 vector long vec_revb (vector long);
21098 vector unsigned long vec_revb (vector unsigned long);
21099 vector __int128 vec_revb (vector __int128);
21100 vector __uint128 vec_revb (vector __uint128);
21103 The @code{vec_revb} built-in function reverses the bytes on an element
21104 by element basis. A vector of @code{vector unsigned char} or
21105 @code{vector signed char} reverses the bytes in the whole word.
21107 If the cryptographic instructions are enabled (@option{-mcrypto} or
21108 @option{-mcpu=power8}), the following builtins are enabled.
21111 vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long);
21113 vector unsigned char vec_sbox_be (vector unsigned char);
21115 vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long,
21116 vector unsigned long long);
21118 vector unsigned char vec_cipher_be (vector unsigned char, vector unsigned char);
21120 vector unsigned long long __builtin_crypto_vcipherlast
21121 (vector unsigned long long,
21122 vector unsigned long long);
21124 vector unsigned char vec_cipherlast_be (vector unsigned char,
21125 vector unsigned char);
21127 vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long,
21128 vector unsigned long long);
21130 vector unsigned char vec_ncipher_be (vector unsigned char,
21131 vector unsigned char);
21133 vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long,
21134 vector unsigned long long);
21136 vector unsigned char vec_ncipherlast_be (vector unsigned char,
21137 vector unsigned char);
21139 vector unsigned char __builtin_crypto_vpermxor (vector unsigned char,
21140 vector unsigned char,
21141 vector unsigned char);
21143 vector unsigned short __builtin_crypto_vpermxor (vector unsigned short,
21144 vector unsigned short,
21145 vector unsigned short);
21147 vector unsigned int __builtin_crypto_vpermxor (vector unsigned int,
21148 vector unsigned int,
21149 vector unsigned int);
21151 vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long,
21152 vector unsigned long long,
21153 vector unsigned long long);
21155 vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char,
21156 vector unsigned char);
21158 vector unsigned short __builtin_crypto_vpmsumh (vector unsigned short,
21159 vector unsigned short);
21161 vector unsigned int __builtin_crypto_vpmsumw (vector unsigned int,
21162 vector unsigned int);
21164 vector unsigned long long __builtin_crypto_vpmsumd (vector unsigned long long,
21165 vector unsigned long long);
21167 vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long,
21170 vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int);
21173 The second argument to @var{__builtin_crypto_vshasigmad} and
21174 @var{__builtin_crypto_vshasigmaw} must be a constant
21175 integer that is 0 or 1. The third argument to these built-in functions
21176 must be a constant integer in the range of 0 to 15.
21178 If the ISA 3.0 instruction set additions
21179 are enabled (@option{-mcpu=power9}), the following additional
21180 functions are available for both 32-bit and 64-bit targets.
21182 vector short vec_xl (int, vector short *);
21183 vector short vec_xl (int, short *);
21184 vector unsigned short vec_xl (int, vector unsigned short *);
21185 vector unsigned short vec_xl (int, unsigned short *);
21186 vector char vec_xl (int, vector char *);
21187 vector char vec_xl (int, char *);
21188 vector unsigned char vec_xl (int, vector unsigned char *);
21189 vector unsigned char vec_xl (int, unsigned char *);
21191 void vec_xst (vector short, int, vector short *);
21192 void vec_xst (vector short, int, short *);
21193 void vec_xst (vector unsigned short, int, vector unsigned short *);
21194 void vec_xst (vector unsigned short, int, unsigned short *);
21195 void vec_xst (vector char, int, vector char *);
21196 void vec_xst (vector char, int, char *);
21197 void vec_xst (vector unsigned char, int, vector unsigned char *);
21198 void vec_xst (vector unsigned char, int, unsigned char *);
21201 @node PowerPC AltiVec Built-in Functions Available on ISA 3.1
21202 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.1
21204 The following additional built-in functions are also available for the
21205 PowerPC family of processors, starting with ISA 3.1 (@option{-mcpu=power10}):
21209 @exdent vector unsigned long long int
21210 @exdent vec_cfuge (vector unsigned long long int, vector unsigned long long int)
21212 Perform a vector centrifuge operation, as if implemented by the
21213 @code{vcfuged} instruction.
21217 @exdent vector unsigned long long int
21218 @exdent vec_cntlzm (vector unsigned long long int, vector unsigned long long int)
21220 Perform a vector count leading zeros under bit mask operation, as if
21221 implemented by the @code{vclzdm} instruction.
21225 @exdent vector unsigned long long int
21226 @exdent vec_cnttzm (vector unsigned long long int, vector unsigned long long int)
21228 Perform a vector count trailing zeros under bit mask operation, as if
21229 implemented by the @code{vctzdm} instruction.
21233 @exdent vector signed char
21234 @exdent vec_clrl (vector signed char a, unsigned int n)
21235 @exdent vector unsigned char
21236 @exdent vec_clrl (vector unsigned char a, unsigned int n)
21238 Clear the left-most @code{(16 - n)} bytes of vector argument @code{a}, as if
21239 implemented by the @code{vclrlb} instruction on a big-endian target
21240 and by the @code{vclrrb} instruction on a little-endian target. A
21241 value of @code{n} that is greater than 16 is treated as if it equaled 16.
21245 @exdent vector signed char
21246 @exdent vec_clrr (vector signed char a, unsigned int n)
21247 @exdent vector unsigned char
21248 @exdent vec_clrr (vector unsigned char a, unsigned int n)
21250 Clear the right-most @code{(16 - n)} bytes of vector argument @code{a}, as if
21251 implemented by the @code{vclrrb} instruction on a big-endian target
21252 and by the @code{vclrlb} instruction on a little-endian target. A
21253 value of @code{n} that is greater than 16 is treated as if it equaled 16.
21257 @exdent vector unsigned long long int
21258 @exdent vec_gnb (vector unsigned __int128, const unsigned char)
21260 Perform a 128-bit vector gather operation, as if implemented by the
21261 @code{vgnb} instruction. The second argument must be a literal
21262 integer value between 2 and 7 inclusive.
21269 @exdent vector unsigned long long int
21270 @exdent vec_extractl (vector unsigned char, vector unsigned char, unsigned int)
21271 @exdent vector unsigned long long int
21272 @exdent vec_extractl (vector unsigned short, vector unsigned short, unsigned int)
21273 @exdent vector unsigned long long int
21274 @exdent vec_extractl (vector unsigned int, vector unsigned int, unsigned int)
21275 @exdent vector unsigned long long int
21276 @exdent vec_extractl (vector unsigned long long, vector unsigned long long, unsigned int)
21278 Extract an element from two concatenated vectors starting at the given byte index
21279 in natural-endian order, and place it zero-extended in doubleword 1 of the result
21280 according to natural element order. If the byte index is out of range for the
21281 data type, the intrinsic will be rejected.
21282 For little-endian, this output will match the placement by the hardware
21283 instruction, i.e., dword[0] in RTL notation. For big-endian, an additional
21284 instruction is needed to move it from the "left" doubleword to the "right" one.
21285 For little-endian, semantics matching the @code{vextdubvrx},
21286 @code{vextduhvrx}, @code{vextduwvrx} instruction will be generated, while for
21287 big-endian, semantics matching the @code{vextdubvlx}, @code{vextduhvlx},
21288 @code{vextduwvlx} instructions
21289 will be generated. Note that some fairly anomalous results can be generated if
21290 the byte index is not aligned on an element boundary for the element being
21291 extracted. This is a limitation of the bi-endian vector programming model is
21292 consistent with the limitation on @code{vec_perm}.
21293 @findex vec_extractl
21296 @exdent vector unsigned long long int
21297 @exdent vec_extracth (vector unsigned char, vector unsigned char, unsigned int)
21298 @exdent vector unsigned long long int
21299 @exdent vec_extracth (vector unsigned short, vector unsigned short,
21301 @exdent vector unsigned long long int
21302 @exdent vec_extracth (vector unsigned int, vector unsigned int, unsigned int)
21303 @exdent vector unsigned long long int
21304 @exdent vec_extracth (vector unsigned long long, vector unsigned long long,
21307 Extract an element from two concatenated vectors starting at the given byte
21308 index. The index is based on big endian order for a little endian system.
21309 Similarly, the index is based on little endian order for a big endian system.
21310 The extraced elements are zero-extended and put in doubleword 1
21311 according to natural element order. If the byte index is out of range for the
21312 data type, the intrinsic will be rejected. For little-endian, this output
21313 will match the placement by the hardware instruction (vextdubvrx, vextduhvrx,
21314 vextduwvrx, vextddvrx) i.e., dword[0] in RTL
21315 notation. For big-endian, an additional instruction is needed to move it
21316 from the "left" doubleword to the "right" one. For little-endian, semantics
21317 matching the @code{vextdubvlx}, @code{vextduhvlx}, @code{vextduwvlx}
21318 instructions will be generated, while for big-endian, semantics matching the
21319 @code{vextdubvrx}, @code{vextduhvrx}, @code{vextduwvrx} instructions will
21320 be generated. Note that some fairly anomalous
21321 results can be generated if the byte index is not aligned on the
21322 element boundary for the element being extracted. This is a
21323 limitation of the bi-endian vector programming model consistent with the
21324 limitation on @code{vec_perm}.
21325 @findex vec_extracth
21327 @exdent vector unsigned long long int
21328 @exdent vec_pdep (vector unsigned long long int, vector unsigned long long int)
21330 Perform a vector parallel bits deposit operation, as if implemented by
21331 the @code{vpdepd} instruction.
21337 @exdent vector unsigned char
21338 @exdent vec_insertl (unsigned char, vector unsigned char, unsigned int);
21339 @exdent vector unsigned short
21340 @exdent vec_insertl (unsigned short, vector unsigned short, unsigned int);
21341 @exdent vector unsigned int
21342 @exdent vec_insertl (unsigned int, vector unsigned int, unsigned int);
21343 @exdent vector unsigned long long
21344 @exdent vec_insertl (unsigned long long, vector unsigned long long,
21346 @exdent vector unsigned char
21347 @exdent vec_insertl (vector unsigned char, vector unsigned char, unsigned int;
21348 @exdent vector unsigned short
21349 @exdent vec_insertl (vector unsigned short, vector unsigned short,
21351 @exdent vector unsigned int
21352 @exdent vec_insertl (vector unsigned int, vector unsigned int, unsigned int);
21355 Let src be the first argument, when the first argument is a scalar, or the
21356 rightmost element of the left doubleword of the first argument, when the first
21357 argument is a vector. Insert the source into the destination at the position
21358 given by the third argument, using natural element order in the second
21359 argument. The rest of the second argument is unchanged. If the byte
21360 index is greater than 14 for halfwords, greater than 12 for words, or
21361 greater than 8 for doublewords the result is undefined. For little-endian,
21362 the generated code will be semantically equivalent to @code{vins[bhwd]rx}
21363 instructions. Similarly for big-endian it will be semantically equivalent
21364 to @code{vins[bhwd]lx}. Note that some fairly anomalous results can be
21365 generated if the byte index is not aligned on an element boundary for the
21366 type of element being inserted.
21367 @findex vec_insertl
21370 @exdent vector unsigned char
21371 @exdent vec_inserth (unsigned char, vector unsigned char, unsigned int);
21372 @exdent vector unsigned short
21373 @exdent vec_inserth (unsigned short, vector unsigned short, unsigned int);
21374 @exdent vector unsigned int
21375 @exdent vec_inserth (unsigned int, vector unsigned int, unsigned int);
21376 @exdent vector unsigned long long
21377 @exdent vec_inserth (unsigned long long, vector unsigned long long,
21379 @exdent vector unsigned char
21380 @exdent vec_inserth (vector unsigned char, vector unsigned char, unsigned int);
21381 @exdent vector unsigned short
21382 @exdent vec_inserth (vector unsigned short, vector unsigned short,
21384 @exdent vector unsigned int
21385 @exdent vec_inserth (vector unsigned int, vector unsigned int, unsigned int);
21388 Let src be the first argument, when the first argument is a scalar, or the
21389 rightmost element of the first argument, when the first argument is a vector.
21390 Insert src into the second argument at the position identified by the third
21391 argument, using opposite element order in the second argument, and leaving the
21392 rest of the second argument unchanged. If the byte index is greater than 14
21393 for halfwords, 12 for words, or 8 for doublewords, the intrinsic will be
21394 rejected. Note that the underlying hardware instruction uses the same register
21395 for the second argument and the result.
21396 For little-endian, the code generation will be semantically equivalent to
21397 @code{vins[bhwd]lx}, while for big-endian it will be semantically equivalent to
21398 @code{vins[bhwd]rx}.
21399 Note that some fairly anomalous results can be generated if the byte index is
21400 not aligned on an element boundary for the sort of element being inserted.
21401 @findex vec_inserth
21403 Vector Replace Element
21405 @exdent vector signed int vec_replace_elt (vector signed int, signed int,
21407 @exdent vector unsigned int vec_replace_elt (vector unsigned int,
21408 unsigned int, const int);
21409 @exdent vector float vec_replace_elt (vector float, float, const int);
21410 @exdent vector signed long long vec_replace_elt (vector signed long long,
21411 signed long long, const int);
21412 @exdent vector unsigned long long vec_replace_elt (vector unsigned long long,
21413 unsigned long long, const int);
21414 @exdent vector double rec_replace_elt (vector double, double, const int);
21416 The third argument (constrained to [0,3]) identifies the natural-endian
21417 element number of the first argument that will be replaced by the second
21418 argument to produce the result. The other elements of the first argument will
21419 remain unchanged in the result.
21421 If it's desirable to insert a word at an unaligned position, use
21422 vec_replace_unaligned instead.
21424 @findex vec_replace_element
21426 Vector Replace Unaligned
21428 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
21429 signed int, const int);
21430 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
21431 unsigned int, const int);
21432 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
21434 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
21435 signed long long, const int);
21436 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
21437 unsigned long long, const int);
21438 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
21439 double, const int);
21442 The second argument replaces a portion of the first argument to produce the
21443 result, with the rest of the first argument unchanged in the result. The
21444 third argument identifies the byte index (using left-to-right, or big-endian
21445 order) where the high-order byte of the second argument will be placed, with
21446 the remaining bytes of the second argument placed naturally "to the right"
21447 of the high-order byte.
21449 The programmer is responsible for understanding the endianness issues involved
21450 with the first argument and the result.
21451 @findex vec_replace_unaligned
21453 Vector Shift Left Double Bit Immediate
21455 @exdent vector signed char vec_sldb (vector signed char, vector signed char,
21456 const unsigned int);
21457 @exdent vector unsigned char vec_sldb (vector unsigned char,
21458 vector unsigned char, const unsigned int);
21459 @exdent vector signed short vec_sldb (vector signed short, vector signed short,
21460 const unsigned int);
21461 @exdent vector unsigned short vec_sldb (vector unsigned short,
21462 vector unsigned short, const unsigned int);
21463 @exdent vector signed int vec_sldb (vector signed int, vector signed int,
21464 const unsigned int);
21465 @exdent vector unsigned int vec_sldb (vector unsigned int, vector unsigned int,
21466 const unsigned int);
21467 @exdent vector signed long long vec_sldb (vector signed long long,
21468 vector signed long long, const unsigned int);
21469 @exdent vector unsigned long long vec_sldb (vector unsigned long long,
21470 vector unsigned long long, const unsigned int);
21473 Shift the combined input vectors left by the amount specified by the low-order
21474 three bits of the third argument, and return the leftmost remaining 128 bits.
21475 Code using this instruction must be endian-aware.
21479 Vector Shift Right Double Bit Immediate
21482 @exdent vector signed char vec_srdb (vector signed char, vector signed char,
21483 const unsigned int);
21484 @exdent vector unsigned char vec_srdb (vector unsigned char, vector unsigned char,
21485 const unsigned int);
21486 @exdent vector signed short vec_srdb (vector signed short, vector signed short,
21487 const unsigned int);
21488 @exdent vector unsigned short vec_srdb (vector unsigned short, vector unsigned short,
21489 const unsigned int);
21490 @exdent vector signed int vec_srdb (vector signed int, vector signed int,
21491 const unsigned int);
21492 @exdent vector unsigned int vec_srdb (vector unsigned int, vector unsigned int,
21493 const unsigned int);
21494 @exdent vector signed long long vec_srdb (vector signed long long,
21495 vector signed long long, const unsigned int);
21496 @exdent vector unsigned long long vec_srdb (vector unsigned long long,
21497 vector unsigned long long, const unsigned int);
21500 Shift the combined input vectors right by the amount specified by the low-order
21501 three bits of the third argument, and return the remaining 128 bits. Code
21502 using this built-in must be endian-aware.
21509 @exdent vector signed int vec_splati (const signed int);
21510 @exdent vector float vec_splati (const float);
21513 Splat a 32-bit immediate into a vector of words.
21518 @exdent vector double vec_splatid (const float);
21521 Convert a single precision floating-point value to double-precision and splat
21522 the result to a vector of double-precision floats.
21524 @findex vec_splatid
21527 @exdent vector signed int vec_splati_ins (vector signed int,
21528 const unsigned int, const signed int);
21529 @exdent vector unsigned int vec_splati_ins (vector unsigned int,
21530 const unsigned int, const unsigned int);
21531 @exdent vector float vec_splati_ins (vector float, const unsigned int,
21535 Argument 2 must be either 0 or 1. Splat the value of argument 3 into the word
21536 identified by argument 2 of each doubleword of argument 1 and return the
21537 result. The other words of argument 1 are unchanged.
21539 @findex vec_splati_ins
21541 Vector Blend Variable
21544 @exdent vector signed char vec_blendv (vector signed char, vector signed char,
21545 vector unsigned char);
21546 @exdent vector unsigned char vec_blendv (vector unsigned char,
21547 vector unsigned char, vector unsigned char);
21548 @exdent vector signed short vec_blendv (vector signed short,
21549 vector signed short, vector unsigned short);
21550 @exdent vector unsigned short vec_blendv (vector unsigned short,
21551 vector unsigned short, vector unsigned short);
21552 @exdent vector signed int vec_blendv (vector signed int, vector signed int,
21553 vector unsigned int);
21554 @exdent vector unsigned int vec_blendv (vector unsigned int,
21555 vector unsigned int, vector unsigned int);
21556 @exdent vector signed long long vec_blendv (vector signed long long,
21557 vector signed long long, vector unsigned long long);
21558 @exdent vector unsigned long long vec_blendv (vector unsigned long long,
21559 vector unsigned long long, vector unsigned long long);
21560 @exdent vector float vec_blendv (vector float, vector float,
21561 vector unsigned int);
21562 @exdent vector double vec_blendv (vector double, vector double,
21563 vector unsigned long long);
21566 Blend the first and second argument vectors according to the sign bits of the
21567 corresponding elements of the third argument vector. This is similar to the
21568 @code{vsel} and @code{xxsel} instructions but for bigger elements.
21572 Vector Permute Extended
21575 @exdent vector signed char vec_permx (vector signed char, vector signed char,
21576 vector unsigned char, const int);
21577 @exdent vector unsigned char vec_permx (vector unsigned char,
21578 vector unsigned char, vector unsigned char, const int);
21579 @exdent vector signed short vec_permx (vector signed short,
21580 vector signed short, vector unsigned char, const int);
21581 @exdent vector unsigned short vec_permx (vector unsigned short,
21582 vector unsigned short, vector unsigned char, const int);
21583 @exdent vector signed int vec_permx (vector signed int, vector signed int,
21584 vector unsigned char, const int);
21585 @exdent vector unsigned int vec_permx (vector unsigned int,
21586 vector unsigned int, vector unsigned char, const int);
21587 @exdent vector signed long long vec_permx (vector signed long long,
21588 vector signed long long, vector unsigned char, const int);
21589 @exdent vector unsigned long long vec_permx (vector unsigned long long,
21590 vector unsigned long long, vector unsigned char, const int);
21591 @exdent vector float (vector float, vector float, vector unsigned char,
21593 @exdent vector double (vector double, vector double, vector unsigned char,
21597 Perform a partial permute of the first two arguments, which form a 32-byte
21598 section of an emulated vector up to 256 bytes wide, using the partial permute
21599 control vector in the third argument. The fourth argument (constrained to
21600 values of 0-7) identifies which 32-byte section of the emulated vector is
21601 contained in the first two arguments.
21605 @exdent vector unsigned long long int
21606 @exdent vec_pext (vector unsigned long long int, vector unsigned long long int)
21608 Perform a vector parallel bit extract operation, as if implemented by
21609 the @code{vpextd} instruction.
21613 @exdent vector unsigned char vec_stril (vector unsigned char)
21614 @exdent vector signed char vec_stril (vector signed char)
21615 @exdent vector unsigned short vec_stril (vector unsigned short)
21616 @exdent vector signed short vec_stril (vector signed short)
21618 Isolate the left-most non-zero elements of the incoming vector argument,
21619 replacing all elements to the right of the left-most zero element
21620 found within the argument with zero. The typical implementation uses
21621 the @code{vstribl} or @code{vstrihl} instruction on big-endian targets
21622 and uses the @code{vstribr} or @code{vstrihr} instruction on
21623 little-endian targets.
21627 @exdent int vec_stril_p (vector unsigned char)
21628 @exdent int vec_stril_p (vector signed char)
21629 @exdent int short vec_stril_p (vector unsigned short)
21630 @exdent int vec_stril_p (vector signed short)
21632 Return a non-zero value if and only if the argument contains a zero
21633 element. The typical implementation uses
21634 the @code{vstribl.} or @code{vstrihl.} instruction on big-endian targets
21635 and uses the @code{vstribr.} or @code{vstrihr.} instruction on
21636 little-endian targets. Choose this built-in to check for presence of
21637 zero element if the same argument is also passed to @code{vec_stril}.
21638 @findex vec_stril_p
21641 @exdent vector unsigned char vec_strir (vector unsigned char)
21642 @exdent vector signed char vec_strir (vector signed char)
21643 @exdent vector unsigned short vec_strir (vector unsigned short)
21644 @exdent vector signed short vec_strir (vector signed short)
21646 Isolate the right-most non-zero elements of the incoming vector argument,
21647 replacing all elements to the left of the right-most zero element
21648 found within the argument with zero. The typical implementation uses
21649 the @code{vstribr} or @code{vstrihr} instruction on big-endian targets
21650 and uses the @code{vstribl} or @code{vstrihl} instruction on
21651 little-endian targets.
21655 @exdent int vec_strir_p (vector unsigned char)
21656 @exdent int vec_strir_p (vector signed char)
21657 @exdent int short vec_strir_p (vector unsigned short)
21658 @exdent int vec_strir_p (vector signed short)
21660 Return a non-zero value if and only if the argument contains a zero
21661 element. The typical implementation uses
21662 the @code{vstribr.} or @code{vstrihr.} instruction on big-endian targets
21663 and uses the @code{vstribl.} or @code{vstrihl.} instruction on
21664 little-endian targets. Choose this built-in to check for presence of
21665 zero element if the same argument is also passed to @code{vec_strir}.
21666 @findex vec_strir_p
21669 @exdent vector unsigned char
21670 @exdent vec_ternarylogic (vector unsigned char, vector unsigned char,
21671 vector unsigned char, const unsigned int)
21672 @exdent vector unsigned short
21673 @exdent vec_ternarylogic (vector unsigned short, vector unsigned short,
21674 vector unsigned short, const unsigned int)
21675 @exdent vector unsigned int
21676 @exdent vec_ternarylogic (vector unsigned int, vector unsigned int,
21677 vector unsigned int, const unsigned int)
21678 @exdent vector unsigned long long int
21679 @exdent vec_ternarylogic (vector unsigned long long int, vector unsigned long long int,
21680 vector unsigned long long int, const unsigned int)
21681 @exdent vector unsigned __int128
21682 @exdent vec_ternarylogic (vector unsigned __int128, vector unsigned __int128,
21683 vector unsigned __int128, const unsigned int)
21685 Perform a 128-bit vector evaluate operation, as if implemented by the
21686 @code{xxeval} instruction. The fourth argument must be a literal
21687 integer value between 0 and 255 inclusive.
21688 @findex vec_ternarylogic
21691 @exdent vector unsigned char vec_genpcvm (vector unsigned char, const int)
21692 @exdent vector unsigned short vec_genpcvm (vector unsigned short, const int)
21693 @exdent vector unsigned int vec_genpcvm (vector unsigned int, const int)
21694 @exdent vector unsigned int vec_genpcvm (vector unsigned long long int,
21698 Vector Integer Multiply/Divide/Modulo
21701 @exdent vector signed int
21702 @exdent vec_mulh (vector signed int a, vector signed int b)
21703 @exdent vector unsigned int
21704 @exdent vec_mulh (vector unsigned int a, vector unsigned int b)
21707 For each integer value @code{i} from 0 to 3, do the following. The integer
21708 value in word element @code{i} of a is multiplied by the integer value in word
21709 element @code{i} of b. The high-order 32 bits of the 64-bit product are placed
21710 into word element @code{i} of the vector returned.
21713 @exdent vector signed long long
21714 @exdent vec_mulh (vector signed long long a, vector signed long long b)
21715 @exdent vector unsigned long long
21716 @exdent vec_mulh (vector unsigned long long a, vector unsigned long long b)
21719 For each integer value @code{i} from 0 to 1, do the following. The integer
21720 value in doubleword element @code{i} of a is multiplied by the integer value in
21721 doubleword element @code{i} of b. The high-order 64 bits of the 128-bit product
21722 are placed into doubleword element @code{i} of the vector returned.
21725 @exdent vector unsigned long long
21726 @exdent vec_mul (vector unsigned long long a, vector unsigned long long b)
21727 @exdent vector signed long long
21728 @exdent vec_mul (vector signed long long a, vector signed long long b)
21731 For each integer value @code{i} from 0 to 1, do the following. The integer
21732 value in doubleword element @code{i} of a is multiplied by the integer value in
21733 doubleword element @code{i} of b. The low-order 64 bits of the 128-bit product
21734 are placed into doubleword element @code{i} of the vector returned.
21737 @exdent vector signed int
21738 @exdent vec_div (vector signed int a, vector signed int b)
21739 @exdent vector unsigned int
21740 @exdent vec_div (vector unsigned int a, vector unsigned int b)
21743 For each integer value @code{i} from 0 to 3, do the following. The integer in
21744 word element @code{i} of a is divided by the integer in word element @code{i}
21745 of b. The unique integer quotient is placed into the word element @code{i} of
21746 the vector returned. If an attempt is made to perform any of the divisions
21747 <anything> ÷ 0 then the quotient is undefined.
21750 @exdent vector signed long long
21751 @exdent vec_div (vector signed long long a, vector signed long long b)
21752 @exdent vector unsigned long long
21753 @exdent vec_div (vector unsigned long long a, vector unsigned long long b)
21756 For each integer value @code{i} from 0 to 1, do the following. The integer in
21757 doubleword element @code{i} of a is divided by the integer in doubleword
21758 element @code{i} of b. The unique integer quotient is placed into the
21759 doubleword element @code{i} of the vector returned. If an attempt is made to
21760 perform any of the divisions 0x8000_0000_0000_0000 ÷ -1 or <anything> ÷ 0 then
21761 the quotient is undefined.
21764 @exdent vector signed int
21765 @exdent vec_dive (vector signed int a, vector signed int b)
21766 @exdent vector unsigned int
21767 @exdent vec_dive (vector unsigned int a, vector unsigned int b)
21770 For each integer value @code{i} from 0 to 3, do the following. The integer in
21771 word element @code{i} of a is shifted left by 32 bits, then divided by the
21772 integer in word element @code{i} of b. The unique integer quotient is placed
21773 into the word element @code{i} of the vector returned. If the quotient cannot
21774 be represented in 32 bits, or if an attempt is made to perform any of the
21775 divisions <anything> ÷ 0 then the quotient is undefined.
21778 @exdent vector signed long long
21779 @exdent vec_dive (vector signed long long a, vector signed long long b)
21780 @exdent vector unsigned long long
21781 @exdent vec_dive (vector unsigned long long a, vector unsigned long long b)
21784 For each integer value @code{i} from 0 to 1, do the following. The integer in
21785 doubleword element @code{i} of a is shifted left by 64 bits, then divided by
21786 the integer in doubleword element @code{i} of b. The unique integer quotient is
21787 placed into the doubleword element @code{i} of the vector returned. If the
21788 quotient cannot be represented in 64 bits, or if an attempt is made to perform
21789 <anything> ÷ 0 then the quotient is undefined.
21792 @exdent vector signed int
21793 @exdent vec_mod (vector signed int a, vector signed int b)
21794 @exdent vector unsigned int
21795 @exdent vec_mod (vector unsigned int a, vector unsigned int b)
21798 For each integer value @code{i} from 0 to 3, do the following. The integer in
21799 word element @code{i} of a is divided by the integer in word element @code{i}
21800 of b. The unique integer remainder is placed into the word element @code{i} of
21801 the vector returned. If an attempt is made to perform any of the divisions
21802 0x8000_0000 ÷ -1 or <anything> ÷ 0 then the remainder is undefined.
21805 @exdent vector signed long long
21806 @exdent vec_mod (vector signed long long a, vector signed long long b)
21807 @exdent vector unsigned long long
21808 @exdent vec_mod (vector unsigned long long a, vector unsigned long long b)
21811 For each integer value @code{i} from 0 to 1, do the following. The integer in
21812 doubleword element @code{i} of a is divided by the integer in doubleword
21813 element @code{i} of b. The unique integer remainder is placed into the
21814 doubleword element @code{i} of the vector returned. If an attempt is made to
21815 perform <anything> ÷ 0 then the remainder is undefined.
21817 Generate PCV from specified Mask size, as if implemented by the
21818 @code{xxgenpcvbm}, @code{xxgenpcvhm}, @code{xxgenpcvwm} instructions, where
21819 immediate value is either 0, 1, 2 or 3.
21820 @findex vec_genpcvm
21822 @node PowerPC Hardware Transactional Memory Built-in Functions
21823 @subsection PowerPC Hardware Transactional Memory Built-in Functions
21824 GCC provides two interfaces for accessing the Hardware Transactional
21825 Memory (HTM) instructions available on some of the PowerPC family
21826 of processors (eg, POWER8). The two interfaces come in a low level
21827 interface, consisting of built-in functions specific to PowerPC and a
21828 higher level interface consisting of inline functions that are common
21829 between PowerPC and S/390.
21831 @subsubsection PowerPC HTM Low Level Built-in Functions
21833 The following low level built-in functions are available with
21834 @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later.
21835 They all generate the machine instruction that is part of the name.
21837 The HTM builtins (with the exception of @code{__builtin_tbegin}) return
21838 the full 4-bit condition register value set by their associated hardware
21839 instruction. The header file @code{htmintrin.h} defines some macros that can
21840 be used to decipher the return value. The @code{__builtin_tbegin} builtin
21841 returns a simple @code{true} or @code{false} value depending on whether a transaction was
21842 successfully started or not. The arguments of the builtins match exactly the
21843 type and order of the associated hardware instruction's operands, except for
21844 the @code{__builtin_tcheck} builtin, which does not take any input arguments.
21845 Refer to the ISA manual for a description of each instruction's operands.
21848 unsigned int __builtin_tbegin (unsigned int)
21849 unsigned int __builtin_tend (unsigned int)
21851 unsigned int __builtin_tabort (unsigned int)
21852 unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int)
21853 unsigned int __builtin_tabortdci (unsigned int, unsigned int, int)
21854 unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int)
21855 unsigned int __builtin_tabortwci (unsigned int, unsigned int, int)
21857 unsigned int __builtin_tcheck (void)
21858 unsigned int __builtin_treclaim (unsigned int)
21859 unsigned int __builtin_trechkpt (void)
21860 unsigned int __builtin_tsr (unsigned int)
21863 In addition to the above HTM built-ins, we have added built-ins for
21864 some common extended mnemonics of the HTM instructions:
21867 unsigned int __builtin_tendall (void)
21868 unsigned int __builtin_tresume (void)
21869 unsigned int __builtin_tsuspend (void)
21872 Note that the semantics of the above HTM builtins are required to mimic
21873 the locking semantics used for critical sections. Builtins that are used
21874 to create a new transaction or restart a suspended transaction must have
21875 lock acquisition like semantics while those builtins that end or suspend a
21876 transaction must have lock release like semantics. Specifically, this must
21877 mimic lock semantics as specified by C++11, for example: Lock acquisition is
21878 as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE)
21879 that returns 0, and lock release is as-if an execution of
21880 __atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an
21881 implicit implementation-defined lock used for all transactions. The HTM
21882 instructions associated with with the builtins inherently provide the
21883 correct acquisition and release hardware barriers required. However,
21884 the compiler must also be prohibited from moving loads and stores across
21885 the builtins in a way that would violate their semantics. This has been
21886 accomplished by adding memory barriers to the associated HTM instructions
21887 (which is a conservative approach to provide acquire and release semantics).
21888 Earlier versions of the compiler did not treat the HTM instructions as
21889 memory barriers. A @code{__TM_FENCE__} macro has been added, which can
21890 be used to determine whether the current compiler treats HTM instructions
21891 as memory barriers or not. This allows the user to explicitly add memory
21892 barriers to their code when using an older version of the compiler.
21894 The following set of built-in functions are available to gain access
21895 to the HTM specific special purpose registers.
21898 unsigned long __builtin_get_texasr (void)
21899 unsigned long __builtin_get_texasru (void)
21900 unsigned long __builtin_get_tfhar (void)
21901 unsigned long __builtin_get_tfiar (void)
21903 void __builtin_set_texasr (unsigned long);
21904 void __builtin_set_texasru (unsigned long);
21905 void __builtin_set_tfhar (unsigned long);
21906 void __builtin_set_tfiar (unsigned long);
21909 Example usage of these low level built-in functions may look like:
21912 #include <htmintrin.h>
21914 int num_retries = 10;
21918 if (__builtin_tbegin (0))
21920 /* Transaction State Initiated. */
21921 if (is_locked (lock))
21922 __builtin_tabort (0);
21923 ... transaction code...
21924 __builtin_tend (0);
21929 /* Transaction State Failed. Use locks if the transaction
21930 failure is "persistent" or we've tried too many times. */
21931 if (num_retries-- <= 0
21932 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ()))
21934 acquire_lock (lock);
21935 ... non transactional fallback path...
21936 release_lock (lock);
21943 One final built-in function has been added that returns the value of
21944 the 2-bit Transaction State field of the Machine Status Register (MSR)
21945 as stored in @code{CR0}.
21948 unsigned long __builtin_ttest (void)
21951 This built-in can be used to determine the current transaction state
21952 using the following code example:
21955 #include <htmintrin.h>
21957 unsigned char tx_state = _HTM_STATE (__builtin_ttest ());
21959 if (tx_state == _HTM_TRANSACTIONAL)
21961 /* Code to use in transactional state. */
21963 else if (tx_state == _HTM_NONTRANSACTIONAL)
21965 /* Code to use in non-transactional state. */
21967 else if (tx_state == _HTM_SUSPENDED)
21969 /* Code to use in transaction suspended state. */
21973 @subsubsection PowerPC HTM High Level Inline Functions
21975 The following high level HTM interface is made available by including
21976 @code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU}
21977 where CPU is `power8' or later. This interface is common between PowerPC
21978 and S/390, allowing users to write one HTM source implementation that
21979 can be compiled and executed on either system.
21982 long __TM_simple_begin (void)
21983 long __TM_begin (void* const TM_buff)
21984 long __TM_end (void)
21985 void __TM_abort (void)
21986 void __TM_named_abort (unsigned char const code)
21987 void __TM_resume (void)
21988 void __TM_suspend (void)
21990 long __TM_is_user_abort (void* const TM_buff)
21991 long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code)
21992 long __TM_is_illegal (void* const TM_buff)
21993 long __TM_is_footprint_exceeded (void* const TM_buff)
21994 long __TM_nesting_depth (void* const TM_buff)
21995 long __TM_is_nested_too_deep(void* const TM_buff)
21996 long __TM_is_conflict(void* const TM_buff)
21997 long __TM_is_failure_persistent(void* const TM_buff)
21998 long __TM_failure_address(void* const TM_buff)
21999 long long __TM_failure_code(void* const TM_buff)
22002 Using these common set of HTM inline functions, we can create
22003 a more portable version of the HTM example in the previous
22004 section that will work on either PowerPC or S/390:
22007 #include <htmxlintrin.h>
22009 int num_retries = 10;
22010 TM_buff_type TM_buff;
22014 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED)
22016 /* Transaction State Initiated. */
22017 if (is_locked (lock))
22019 ... transaction code...
22025 /* Transaction State Failed. Use locks if the transaction
22026 failure is "persistent" or we've tried too many times. */
22027 if (num_retries-- <= 0
22028 || __TM_is_failure_persistent (TM_buff))
22030 acquire_lock (lock);
22031 ... non transactional fallback path...
22032 release_lock (lock);
22039 @node PowerPC Atomic Memory Operation Functions
22040 @subsection PowerPC Atomic Memory Operation Functions
22041 ISA 3.0 of the PowerPC added new atomic memory operation (amo)
22042 instructions. GCC provides support for these instructions in 64-bit
22043 environments. All of the functions are declared in the include file
22046 The functions supported are:
22051 uint32_t amo_lwat_add (uint32_t *, uint32_t);
22052 uint32_t amo_lwat_xor (uint32_t *, uint32_t);
22053 uint32_t amo_lwat_ior (uint32_t *, uint32_t);
22054 uint32_t amo_lwat_and (uint32_t *, uint32_t);
22055 uint32_t amo_lwat_umax (uint32_t *, uint32_t);
22056 uint32_t amo_lwat_umin (uint32_t *, uint32_t);
22057 uint32_t amo_lwat_swap (uint32_t *, uint32_t);
22059 int32_t amo_lwat_sadd (int32_t *, int32_t);
22060 int32_t amo_lwat_smax (int32_t *, int32_t);
22061 int32_t amo_lwat_smin (int32_t *, int32_t);
22062 int32_t amo_lwat_sswap (int32_t *, int32_t);
22064 uint64_t amo_ldat_add (uint64_t *, uint64_t);
22065 uint64_t amo_ldat_xor (uint64_t *, uint64_t);
22066 uint64_t amo_ldat_ior (uint64_t *, uint64_t);
22067 uint64_t amo_ldat_and (uint64_t *, uint64_t);
22068 uint64_t amo_ldat_umax (uint64_t *, uint64_t);
22069 uint64_t amo_ldat_umin (uint64_t *, uint64_t);
22070 uint64_t amo_ldat_swap (uint64_t *, uint64_t);
22072 int64_t amo_ldat_sadd (int64_t *, int64_t);
22073 int64_t amo_ldat_smax (int64_t *, int64_t);
22074 int64_t amo_ldat_smin (int64_t *, int64_t);
22075 int64_t amo_ldat_sswap (int64_t *, int64_t);
22077 void amo_stwat_add (uint32_t *, uint32_t);
22078 void amo_stwat_xor (uint32_t *, uint32_t);
22079 void amo_stwat_ior (uint32_t *, uint32_t);
22080 void amo_stwat_and (uint32_t *, uint32_t);
22081 void amo_stwat_umax (uint32_t *, uint32_t);
22082 void amo_stwat_umin (uint32_t *, uint32_t);
22084 void amo_stwat_sadd (int32_t *, int32_t);
22085 void amo_stwat_smax (int32_t *, int32_t);
22086 void amo_stwat_smin (int32_t *, int32_t);
22088 void amo_stdat_add (uint64_t *, uint64_t);
22089 void amo_stdat_xor (uint64_t *, uint64_t);
22090 void amo_stdat_ior (uint64_t *, uint64_t);
22091 void amo_stdat_and (uint64_t *, uint64_t);
22092 void amo_stdat_umax (uint64_t *, uint64_t);
22093 void amo_stdat_umin (uint64_t *, uint64_t);
22095 void amo_stdat_sadd (int64_t *, int64_t);
22096 void amo_stdat_smax (int64_t *, int64_t);
22097 void amo_stdat_smin (int64_t *, int64_t);
22100 @node PowerPC Matrix-Multiply Assist Built-in Functions
22101 @subsection PowerPC Matrix-Multiply Assist Built-in Functions
22102 ISA 3.1 of the PowerPC added new Matrix-Multiply Assist (MMA) instructions.
22103 GCC provides support for these instructions through the following built-in
22104 functions which are enabled with the @code{-mmma} option. The vec_t type
22105 below is defined to be a normal vector unsigned char type. The uint2, uint4
22106 and uint8 parameters are 2-bit, 4-bit and 8-bit unsigned integer constants
22107 respectively. The compiler will verify that they are constants and that
22108 their values are within range.
22110 The built-in functions supported are:
22113 void __builtin_mma_xvi4ger8 (__vector_quad *, vec_t, vec_t);
22114 void __builtin_mma_xvi8ger4 (__vector_quad *, vec_t, vec_t);
22115 void __builtin_mma_xvi16ger2 (__vector_quad *, vec_t, vec_t);
22116 void __builtin_mma_xvi16ger2s (__vector_quad *, vec_t, vec_t);
22117 void __builtin_mma_xvf16ger2 (__vector_quad *, vec_t, vec_t);
22118 void __builtin_mma_xvbf16ger2 (__vector_quad *, vec_t, vec_t);
22119 void __builtin_mma_xvf32ger (__vector_quad *, vec_t, vec_t);
22121 void __builtin_mma_xvi4ger8pp (__vector_quad *, vec_t, vec_t);
22122 void __builtin_mma_xvi8ger4pp (__vector_quad *, vec_t, vec_t);
22123 void __builtin_mma_xvi8ger4spp(__vector_quad *, vec_t, vec_t);
22124 void __builtin_mma_xvi16ger2pp (__vector_quad *, vec_t, vec_t);
22125 void __builtin_mma_xvi16ger2spp (__vector_quad *, vec_t, vec_t);
22126 void __builtin_mma_xvf16ger2pp (__vector_quad *, vec_t, vec_t);
22127 void __builtin_mma_xvf16ger2pn (__vector_quad *, vec_t, vec_t);
22128 void __builtin_mma_xvf16ger2np (__vector_quad *, vec_t, vec_t);
22129 void __builtin_mma_xvf16ger2nn (__vector_quad *, vec_t, vec_t);
22130 void __builtin_mma_xvbf16ger2pp (__vector_quad *, vec_t, vec_t);
22131 void __builtin_mma_xvbf16ger2pn (__vector_quad *, vec_t, vec_t);
22132 void __builtin_mma_xvbf16ger2np (__vector_quad *, vec_t, vec_t);
22133 void __builtin_mma_xvbf16ger2nn (__vector_quad *, vec_t, vec_t);
22134 void __builtin_mma_xvf32gerpp (__vector_quad *, vec_t, vec_t);
22135 void __builtin_mma_xvf32gerpn (__vector_quad *, vec_t, vec_t);
22136 void __builtin_mma_xvf32gernp (__vector_quad *, vec_t, vec_t);
22137 void __builtin_mma_xvf32gernn (__vector_quad *, vec_t, vec_t);
22139 void __builtin_mma_pmxvi4ger8 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8);
22140 void __builtin_mma_pmxvi4ger8pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8);
22142 void __builtin_mma_pmxvi8ger4 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
22143 void __builtin_mma_pmxvi8ger4pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
22144 void __builtin_mma_pmxvi8ger4spp(__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
22146 void __builtin_mma_pmxvi16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
22147 void __builtin_mma_pmxvi16ger2s (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
22148 void __builtin_mma_pmxvf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
22149 void __builtin_mma_pmxvbf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
22151 void __builtin_mma_pmxvi16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
22152 void __builtin_mma_pmxvi16ger2spp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
22153 void __builtin_mma_pmxvf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
22154 void __builtin_mma_pmxvf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
22155 void __builtin_mma_pmxvf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
22156 void __builtin_mma_pmxvf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
22157 void __builtin_mma_pmxvbf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
22158 void __builtin_mma_pmxvbf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
22159 void __builtin_mma_pmxvbf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
22160 void __builtin_mma_pmxvbf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
22162 void __builtin_mma_pmxvf32ger (__vector_quad *, vec_t, vec_t, uint4, uint4);
22163 void __builtin_mma_pmxvf32gerpp (__vector_quad *, vec_t, vec_t, uint4, uint4);
22164 void __builtin_mma_pmxvf32gerpn (__vector_quad *, vec_t, vec_t, uint4, uint4);
22165 void __builtin_mma_pmxvf32gernp (__vector_quad *, vec_t, vec_t, uint4, uint4);
22166 void __builtin_mma_pmxvf32gernn (__vector_quad *, vec_t, vec_t, uint4, uint4);
22168 void __builtin_mma_xvf64ger (__vector_quad *, __vector_pair, vec_t);
22169 void __builtin_mma_xvf64gerpp (__vector_quad *, __vector_pair, vec_t);
22170 void __builtin_mma_xvf64gerpn (__vector_quad *, __vector_pair, vec_t);
22171 void __builtin_mma_xvf64gernp (__vector_quad *, __vector_pair, vec_t);
22172 void __builtin_mma_xvf64gernn (__vector_quad *, __vector_pair, vec_t);
22174 void __builtin_mma_pmxvf64ger (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
22175 void __builtin_mma_pmxvf64gerpp (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
22176 void __builtin_mma_pmxvf64gerpn (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
22177 void __builtin_mma_pmxvf64gernp (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
22178 void __builtin_mma_pmxvf64gernn (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
22180 void __builtin_mma_xxmtacc (__vector_quad *);
22181 void __builtin_mma_xxmfacc (__vector_quad *);
22182 void __builtin_mma_xxsetaccz (__vector_quad *);
22184 void __builtin_mma_assemble_acc (__vector_quad *, vec_t, vec_t, vec_t, vec_t);
22185 void __builtin_mma_disassemble_acc (void *, __vector_quad *);
22187 void __builtin_mma_assemble_pair (__vector_pair *, vec_t, vec_t);
22188 void __builtin_mma_disassemble_pair (void *, __vector_pair *);
22190 vec_t __builtin_vsx_xvcvspbf16 (vec_t);
22191 vec_t __builtin_vsx_xvcvbf16spn (vec_t);
22194 @node PRU Built-in Functions
22195 @subsection PRU Built-in Functions
22197 GCC provides a couple of special builtin functions to aid in utilizing
22198 special PRU instructions.
22200 The built-in functions supported are:
22203 @item __delay_cycles (long long @var{cycles})
22204 This inserts an instruction sequence that takes exactly @var{cycles}
22205 cycles (between 0 and 0xffffffff) to complete. The inserted sequence
22206 may use jumps, loops, or no-ops, and does not interfere with any other
22207 instructions. Note that @var{cycles} must be a compile-time constant
22208 integer - that is, you must pass a number, not a variable that may be
22209 optimized to a constant later. The number of cycles delayed by this
22212 @item __halt (void)
22213 This inserts a HALT instruction to stop processor execution.
22215 @item unsigned int __lmbd (unsigned int @var{wordval}, unsigned int @var{bitval})
22216 This inserts LMBD instruction to calculate the left-most bit with value
22217 @var{bitval} in value @var{wordval}. Only the least significant bit
22218 of @var{bitval} is taken into account.
22221 @node RISC-V Built-in Functions
22222 @subsection RISC-V Built-in Functions
22224 These built-in functions are available for the RISC-V family of
22227 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
22228 Returns the value that is currently set in the @samp{tp} register.
22231 @node RX Built-in Functions
22232 @subsection RX Built-in Functions
22233 GCC supports some of the RX instructions which cannot be expressed in
22234 the C programming language via the use of built-in functions. The
22235 following functions are supported:
22237 @deftypefn {Built-in Function} void __builtin_rx_brk (void)
22238 Generates the @code{brk} machine instruction.
22241 @deftypefn {Built-in Function} void __builtin_rx_clrpsw (int)
22242 Generates the @code{clrpsw} machine instruction to clear the specified
22243 bit in the processor status word.
22246 @deftypefn {Built-in Function} void __builtin_rx_int (int)
22247 Generates the @code{int} machine instruction to generate an interrupt
22248 with the specified value.
22251 @deftypefn {Built-in Function} void __builtin_rx_machi (int, int)
22252 Generates the @code{machi} machine instruction to add the result of
22253 multiplying the top 16 bits of the two arguments into the
22257 @deftypefn {Built-in Function} void __builtin_rx_maclo (int, int)
22258 Generates the @code{maclo} machine instruction to add the result of
22259 multiplying the bottom 16 bits of the two arguments into the
22263 @deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int)
22264 Generates the @code{mulhi} machine instruction to place the result of
22265 multiplying the top 16 bits of the two arguments into the
22269 @deftypefn {Built-in Function} void __builtin_rx_mullo (int, int)
22270 Generates the @code{mullo} machine instruction to place the result of
22271 multiplying the bottom 16 bits of the two arguments into the
22275 @deftypefn {Built-in Function} int __builtin_rx_mvfachi (void)
22276 Generates the @code{mvfachi} machine instruction to read the top
22277 32 bits of the accumulator.
22280 @deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void)
22281 Generates the @code{mvfacmi} machine instruction to read the middle
22282 32 bits of the accumulator.
22285 @deftypefn {Built-in Function} int __builtin_rx_mvfc (int)
22286 Generates the @code{mvfc} machine instruction which reads the control
22287 register specified in its argument and returns its value.
22290 @deftypefn {Built-in Function} void __builtin_rx_mvtachi (int)
22291 Generates the @code{mvtachi} machine instruction to set the top
22292 32 bits of the accumulator.
22295 @deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int)
22296 Generates the @code{mvtaclo} machine instruction to set the bottom
22297 32 bits of the accumulator.
22300 @deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val)
22301 Generates the @code{mvtc} machine instruction which sets control
22302 register number @code{reg} to @code{val}.
22305 @deftypefn {Built-in Function} void __builtin_rx_mvtipl (int)
22306 Generates the @code{mvtipl} machine instruction set the interrupt
22310 @deftypefn {Built-in Function} void __builtin_rx_racw (int)
22311 Generates the @code{racw} machine instruction to round the accumulator
22312 according to the specified mode.
22315 @deftypefn {Built-in Function} int __builtin_rx_revw (int)
22316 Generates the @code{revw} machine instruction which swaps the bytes in
22317 the argument so that bits 0--7 now occupy bits 8--15 and vice versa,
22318 and also bits 16--23 occupy bits 24--31 and vice versa.
22321 @deftypefn {Built-in Function} void __builtin_rx_rmpa (void)
22322 Generates the @code{rmpa} machine instruction which initiates a
22323 repeated multiply and accumulate sequence.
22326 @deftypefn {Built-in Function} void __builtin_rx_round (float)
22327 Generates the @code{round} machine instruction which returns the
22328 floating-point argument rounded according to the current rounding mode
22329 set in the floating-point status word register.
22332 @deftypefn {Built-in Function} int __builtin_rx_sat (int)
22333 Generates the @code{sat} machine instruction which returns the
22334 saturated value of the argument.
22337 @deftypefn {Built-in Function} void __builtin_rx_setpsw (int)
22338 Generates the @code{setpsw} machine instruction to set the specified
22339 bit in the processor status word.
22342 @deftypefn {Built-in Function} void __builtin_rx_wait (void)
22343 Generates the @code{wait} machine instruction.
22346 @node S/390 System z Built-in Functions
22347 @subsection S/390 System z Built-in Functions
22348 @deftypefn {Built-in Function} int __builtin_tbegin (void*)
22349 Generates the @code{tbegin} machine instruction starting a
22350 non-constrained hardware transaction. If the parameter is non-NULL the
22351 memory area is used to store the transaction diagnostic buffer and
22352 will be passed as first operand to @code{tbegin}. This buffer can be
22353 defined using the @code{struct __htm_tdb} C struct defined in
22354 @code{htmintrin.h} and must reside on a double-word boundary. The
22355 second tbegin operand is set to @code{0xff0c}. This enables
22356 save/restore of all GPRs and disables aborts for FPR and AR
22357 manipulations inside the transaction body. The condition code set by
22358 the tbegin instruction is returned as integer value. The tbegin
22359 instruction by definition overwrites the content of all FPRs. The
22360 compiler will generate code which saves and restores the FPRs. For
22361 soft-float code it is recommended to used the @code{*_nofloat}
22362 variant. In order to prevent a TDB from being written it is required
22363 to pass a constant zero value as parameter. Passing a zero value
22364 through a variable is not sufficient. Although modifications of
22365 access registers inside the transaction will not trigger an
22366 transaction abort it is not supported to actually modify them. Access
22367 registers do not get saved when entering a transaction. They will have
22368 undefined state when reaching the abort code.
22371 Macros for the possible return codes of tbegin are defined in the
22372 @code{htmintrin.h} header file:
22375 @item _HTM_TBEGIN_STARTED
22376 @code{tbegin} has been executed as part of normal processing. The
22377 transaction body is supposed to be executed.
22378 @item _HTM_TBEGIN_INDETERMINATE
22379 The transaction was aborted due to an indeterminate condition which
22380 might be persistent.
22381 @item _HTM_TBEGIN_TRANSIENT
22382 The transaction aborted due to a transient failure. The transaction
22383 should be re-executed in that case.
22384 @item _HTM_TBEGIN_PERSISTENT
22385 The transaction aborted due to a persistent failure. Re-execution
22386 under same circumstances will not be productive.
22389 @defmac _HTM_FIRST_USER_ABORT_CODE
22390 The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h}
22391 specifies the first abort code which can be used for
22392 @code{__builtin_tabort}. Values below this threshold are reserved for
22396 @deftp {Data type} {struct __htm_tdb}
22397 The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes
22398 the structure of the transaction diagnostic block as specified in the
22399 Principles of Operation manual chapter 5-91.
22402 @deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*)
22403 Same as @code{__builtin_tbegin} but without FPR saves and restores.
22404 Using this variant in code making use of FPRs will leave the FPRs in
22405 undefined state when entering the transaction abort handler code.
22408 @deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int)
22409 In addition to @code{__builtin_tbegin} a loop for transient failures
22410 is generated. If tbegin returns a condition code of 2 the transaction
22411 will be retried as often as specified in the second argument. The
22412 perform processor assist instruction is used to tell the CPU about the
22413 number of fails so far.
22416 @deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int)
22417 Same as @code{__builtin_tbegin_retry} but without FPR saves and
22418 restores. Using this variant in code making use of FPRs will leave
22419 the FPRs in undefined state when entering the transaction abort
22423 @deftypefn {Built-in Function} void __builtin_tbeginc (void)
22424 Generates the @code{tbeginc} machine instruction starting a constrained
22425 hardware transaction. The second operand is set to @code{0xff08}.
22428 @deftypefn {Built-in Function} int __builtin_tend (void)
22429 Generates the @code{tend} machine instruction finishing a transaction
22430 and making the changes visible to other threads. The condition code
22431 generated by tend is returned as integer value.
22434 @deftypefn {Built-in Function} void __builtin_tabort (int)
22435 Generates the @code{tabort} machine instruction with the specified
22436 abort code. Abort codes from 0 through 255 are reserved and will
22437 result in an error message.
22440 @deftypefn {Built-in Function} void __builtin_tx_assist (int)
22441 Generates the @code{ppa rX,rY,1} machine instruction. Where the
22442 integer parameter is loaded into rX and a value of zero is loaded into
22443 rY. The integer parameter specifies the number of times the
22444 transaction repeatedly aborted.
22447 @deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void)
22448 Generates the @code{etnd} machine instruction. The current nesting
22449 depth is returned as integer value. For a nesting depth of 0 the code
22450 is not executed as part of an transaction.
22453 @deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t)
22455 Generates the @code{ntstg} machine instruction. The second argument
22456 is written to the first arguments location. The store operation will
22457 not be rolled-back in case of an transaction abort.
22460 @node SH Built-in Functions
22461 @subsection SH Built-in Functions
22462 The following built-in functions are supported on the SH1, SH2, SH3 and SH4
22463 families of processors:
22465 @deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr})
22466 Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually
22467 used by system code that manages threads and execution contexts. The compiler
22468 normally does not generate code that modifies the contents of @samp{GBR} and
22469 thus the value is preserved across function calls. Changing the @samp{GBR}
22470 value in user code must be done with caution, since the compiler might use
22471 @samp{GBR} in order to access thread local variables.
22475 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
22476 Returns the value that is currently set in the @samp{GBR} register.
22477 Memory loads and stores that use the thread pointer as a base address are
22478 turned into @samp{GBR} based displacement loads and stores, if possible.
22486 int get_tcb_value (void)
22488 // Generate @samp{mov.l @@(8,gbr),r0} instruction
22489 return ((my_tcb*)__builtin_thread_pointer ())->c;
22495 @deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void)
22496 Returns the value that is currently set in the @samp{FPSCR} register.
22499 @deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val})
22500 Sets the @samp{FPSCR} register to the specified value @var{val}, while
22501 preserving the current values of the FR, SZ and PR bits.
22504 @node SPARC VIS Built-in Functions
22505 @subsection SPARC VIS Built-in Functions
22507 GCC supports SIMD operations on the SPARC using both the generic vector
22508 extensions (@pxref{Vector Extensions}) as well as built-in functions for
22509 the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis}
22510 switch, the VIS extension is exposed as the following built-in functions:
22513 typedef int v1si __attribute__ ((vector_size (4)));
22514 typedef int v2si __attribute__ ((vector_size (8)));
22515 typedef short v4hi __attribute__ ((vector_size (8)));
22516 typedef short v2hi __attribute__ ((vector_size (4)));
22517 typedef unsigned char v8qi __attribute__ ((vector_size (8)));
22518 typedef unsigned char v4qi __attribute__ ((vector_size (4)));
22520 void __builtin_vis_write_gsr (int64_t);
22521 int64_t __builtin_vis_read_gsr (void);
22523 void * __builtin_vis_alignaddr (void *, long);
22524 void * __builtin_vis_alignaddrl (void *, long);
22525 int64_t __builtin_vis_faligndatadi (int64_t, int64_t);
22526 v2si __builtin_vis_faligndatav2si (v2si, v2si);
22527 v4hi __builtin_vis_faligndatav4hi (v4si, v4si);
22528 v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi);
22530 v4hi __builtin_vis_fexpand (v4qi);
22532 v4hi __builtin_vis_fmul8x16 (v4qi, v4hi);
22533 v4hi __builtin_vis_fmul8x16au (v4qi, v2hi);
22534 v4hi __builtin_vis_fmul8x16al (v4qi, v2hi);
22535 v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi);
22536 v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi);
22537 v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi);
22538 v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi);
22540 v4qi __builtin_vis_fpack16 (v4hi);
22541 v8qi __builtin_vis_fpack32 (v2si, v8qi);
22542 v2hi __builtin_vis_fpackfix (v2si);
22543 v8qi __builtin_vis_fpmerge (v4qi, v4qi);
22545 int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t);
22547 long __builtin_vis_edge8 (void *, void *);
22548 long __builtin_vis_edge8l (void *, void *);
22549 long __builtin_vis_edge16 (void *, void *);
22550 long __builtin_vis_edge16l (void *, void *);
22551 long __builtin_vis_edge32 (void *, void *);
22552 long __builtin_vis_edge32l (void *, void *);
22554 long __builtin_vis_fcmple16 (v4hi, v4hi);
22555 long __builtin_vis_fcmple32 (v2si, v2si);
22556 long __builtin_vis_fcmpne16 (v4hi, v4hi);
22557 long __builtin_vis_fcmpne32 (v2si, v2si);
22558 long __builtin_vis_fcmpgt16 (v4hi, v4hi);
22559 long __builtin_vis_fcmpgt32 (v2si, v2si);
22560 long __builtin_vis_fcmpeq16 (v4hi, v4hi);
22561 long __builtin_vis_fcmpeq32 (v2si, v2si);
22563 v4hi __builtin_vis_fpadd16 (v4hi, v4hi);
22564 v2hi __builtin_vis_fpadd16s (v2hi, v2hi);
22565 v2si __builtin_vis_fpadd32 (v2si, v2si);
22566 v1si __builtin_vis_fpadd32s (v1si, v1si);
22567 v4hi __builtin_vis_fpsub16 (v4hi, v4hi);
22568 v2hi __builtin_vis_fpsub16s (v2hi, v2hi);
22569 v2si __builtin_vis_fpsub32 (v2si, v2si);
22570 v1si __builtin_vis_fpsub32s (v1si, v1si);
22572 long __builtin_vis_array8 (long, long);
22573 long __builtin_vis_array16 (long, long);
22574 long __builtin_vis_array32 (long, long);
22577 When you use the @option{-mvis2} switch, the VIS version 2.0 built-in
22578 functions also become available:
22581 long __builtin_vis_bmask (long, long);
22582 int64_t __builtin_vis_bshuffledi (int64_t, int64_t);
22583 v2si __builtin_vis_bshufflev2si (v2si, v2si);
22584 v4hi __builtin_vis_bshufflev2si (v4hi, v4hi);
22585 v8qi __builtin_vis_bshufflev2si (v8qi, v8qi);
22587 long __builtin_vis_edge8n (void *, void *);
22588 long __builtin_vis_edge8ln (void *, void *);
22589 long __builtin_vis_edge16n (void *, void *);
22590 long __builtin_vis_edge16ln (void *, void *);
22591 long __builtin_vis_edge32n (void *, void *);
22592 long __builtin_vis_edge32ln (void *, void *);
22595 When you use the @option{-mvis3} switch, the VIS version 3.0 built-in
22596 functions also become available:
22599 void __builtin_vis_cmask8 (long);
22600 void __builtin_vis_cmask16 (long);
22601 void __builtin_vis_cmask32 (long);
22603 v4hi __builtin_vis_fchksm16 (v4hi, v4hi);
22605 v4hi __builtin_vis_fsll16 (v4hi, v4hi);
22606 v4hi __builtin_vis_fslas16 (v4hi, v4hi);
22607 v4hi __builtin_vis_fsrl16 (v4hi, v4hi);
22608 v4hi __builtin_vis_fsra16 (v4hi, v4hi);
22609 v2si __builtin_vis_fsll16 (v2si, v2si);
22610 v2si __builtin_vis_fslas16 (v2si, v2si);
22611 v2si __builtin_vis_fsrl16 (v2si, v2si);
22612 v2si __builtin_vis_fsra16 (v2si, v2si);
22614 long __builtin_vis_pdistn (v8qi, v8qi);
22616 v4hi __builtin_vis_fmean16 (v4hi, v4hi);
22618 int64_t __builtin_vis_fpadd64 (int64_t, int64_t);
22619 int64_t __builtin_vis_fpsub64 (int64_t, int64_t);
22621 v4hi __builtin_vis_fpadds16 (v4hi, v4hi);
22622 v2hi __builtin_vis_fpadds16s (v2hi, v2hi);
22623 v4hi __builtin_vis_fpsubs16 (v4hi, v4hi);
22624 v2hi __builtin_vis_fpsubs16s (v2hi, v2hi);
22625 v2si __builtin_vis_fpadds32 (v2si, v2si);
22626 v1si __builtin_vis_fpadds32s (v1si, v1si);
22627 v2si __builtin_vis_fpsubs32 (v2si, v2si);
22628 v1si __builtin_vis_fpsubs32s (v1si, v1si);
22630 long __builtin_vis_fucmple8 (v8qi, v8qi);
22631 long __builtin_vis_fucmpne8 (v8qi, v8qi);
22632 long __builtin_vis_fucmpgt8 (v8qi, v8qi);
22633 long __builtin_vis_fucmpeq8 (v8qi, v8qi);
22635 float __builtin_vis_fhadds (float, float);
22636 double __builtin_vis_fhaddd (double, double);
22637 float __builtin_vis_fhsubs (float, float);
22638 double __builtin_vis_fhsubd (double, double);
22639 float __builtin_vis_fnhadds (float, float);
22640 double __builtin_vis_fnhaddd (double, double);
22642 int64_t __builtin_vis_umulxhi (int64_t, int64_t);
22643 int64_t __builtin_vis_xmulx (int64_t, int64_t);
22644 int64_t __builtin_vis_xmulxhi (int64_t, int64_t);
22647 When you use the @option{-mvis4} switch, the VIS version 4.0 built-in
22648 functions also become available:
22651 v8qi __builtin_vis_fpadd8 (v8qi, v8qi);
22652 v8qi __builtin_vis_fpadds8 (v8qi, v8qi);
22653 v8qi __builtin_vis_fpaddus8 (v8qi, v8qi);
22654 v4hi __builtin_vis_fpaddus16 (v4hi, v4hi);
22656 v8qi __builtin_vis_fpsub8 (v8qi, v8qi);
22657 v8qi __builtin_vis_fpsubs8 (v8qi, v8qi);
22658 v8qi __builtin_vis_fpsubus8 (v8qi, v8qi);
22659 v4hi __builtin_vis_fpsubus16 (v4hi, v4hi);
22661 long __builtin_vis_fpcmple8 (v8qi, v8qi);
22662 long __builtin_vis_fpcmpgt8 (v8qi, v8qi);
22663 long __builtin_vis_fpcmpule16 (v4hi, v4hi);
22664 long __builtin_vis_fpcmpugt16 (v4hi, v4hi);
22665 long __builtin_vis_fpcmpule32 (v2si, v2si);
22666 long __builtin_vis_fpcmpugt32 (v2si, v2si);
22668 v8qi __builtin_vis_fpmax8 (v8qi, v8qi);
22669 v4hi __builtin_vis_fpmax16 (v4hi, v4hi);
22670 v2si __builtin_vis_fpmax32 (v2si, v2si);
22672 v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi);
22673 v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi);
22674 v2si __builtin_vis_fpmaxu32 (v2si, v2si);
22676 v8qi __builtin_vis_fpmin8 (v8qi, v8qi);
22677 v4hi __builtin_vis_fpmin16 (v4hi, v4hi);
22678 v2si __builtin_vis_fpmin32 (v2si, v2si);
22680 v8qi __builtin_vis_fpminu8 (v8qi, v8qi);
22681 v4hi __builtin_vis_fpminu16 (v4hi, v4hi);
22682 v2si __builtin_vis_fpminu32 (v2si, v2si);
22685 When you use the @option{-mvis4b} switch, the VIS version 4.0B
22686 built-in functions also become available:
22689 v8qi __builtin_vis_dictunpack8 (double, int);
22690 v4hi __builtin_vis_dictunpack16 (double, int);
22691 v2si __builtin_vis_dictunpack32 (double, int);
22693 long __builtin_vis_fpcmple8shl (v8qi, v8qi, int);
22694 long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int);
22695 long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int);
22696 long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int);
22698 long __builtin_vis_fpcmple16shl (v4hi, v4hi, int);
22699 long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int);
22700 long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int);
22701 long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int);
22703 long __builtin_vis_fpcmple32shl (v2si, v2si, int);
22704 long __builtin_vis_fpcmpgt32shl (v2si, v2si, int);
22705 long __builtin_vis_fpcmpeq32shl (v2si, v2si, int);
22706 long __builtin_vis_fpcmpne32shl (v2si, v2si, int);
22708 long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int);
22709 long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int);
22710 long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int);
22711 long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int);
22712 long __builtin_vis_fpcmpule32shl (v2si, v2si, int);
22713 long __builtin_vis_fpcmpugt32shl (v2si, v2si, int);
22715 long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int);
22716 long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int);
22717 long __builtin_vis_fpcmpde32shl (v2si, v2si, int);
22719 long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int);
22720 long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int);
22721 long __builtin_vis_fpcmpur32shl (v2si, v2si, int);
22724 @node TI C6X Built-in Functions
22725 @subsection TI C6X Built-in Functions
22727 GCC provides intrinsics to access certain instructions of the TI C6X
22728 processors. These intrinsics, listed below, are available after
22729 inclusion of the @code{c6x_intrinsics.h} header file. They map directly
22730 to C6X instructions.
22734 int _sadd (int, int)
22735 int _ssub (int, int)
22736 int _sadd2 (int, int)
22737 int _ssub2 (int, int)
22738 long long _mpy2 (int, int)
22739 long long _smpy2 (int, int)
22740 int _add4 (int, int)
22741 int _sub4 (int, int)
22742 int _saddu4 (int, int)
22744 int _smpy (int, int)
22745 int _smpyh (int, int)
22746 int _smpyhl (int, int)
22747 int _smpylh (int, int)
22749 int _sshl (int, int)
22750 int _subc (int, int)
22752 int _avg2 (int, int)
22753 int _avgu4 (int, int)
22755 int _clrr (int, int)
22756 int _extr (int, int)
22757 int _extru (int, int)
22763 @node TILE-Gx Built-in Functions
22764 @subsection TILE-Gx Built-in Functions
22766 GCC provides intrinsics to access every instruction of the TILE-Gx
22767 processor. The intrinsics are of the form:
22771 unsigned long long __insn_@var{op} (...)
22775 Where @var{op} is the name of the instruction. Refer to the ISA manual
22776 for the complete list of instructions.
22778 GCC also provides intrinsics to directly access the network registers.
22779 The intrinsics are:
22783 unsigned long long __tile_idn0_receive (void)
22784 unsigned long long __tile_idn1_receive (void)
22785 unsigned long long __tile_udn0_receive (void)
22786 unsigned long long __tile_udn1_receive (void)
22787 unsigned long long __tile_udn2_receive (void)
22788 unsigned long long __tile_udn3_receive (void)
22789 void __tile_idn_send (unsigned long long)
22790 void __tile_udn_send (unsigned long long)
22794 The intrinsic @code{void __tile_network_barrier (void)} is used to
22795 guarantee that no network operations before it are reordered with
22798 @node TILEPro Built-in Functions
22799 @subsection TILEPro Built-in Functions
22801 GCC provides intrinsics to access every instruction of the TILEPro
22802 processor. The intrinsics are of the form:
22806 unsigned __insn_@var{op} (...)
22811 where @var{op} is the name of the instruction. Refer to the ISA manual
22812 for the complete list of instructions.
22814 GCC also provides intrinsics to directly access the network registers.
22815 The intrinsics are:
22819 unsigned __tile_idn0_receive (void)
22820 unsigned __tile_idn1_receive (void)
22821 unsigned __tile_sn_receive (void)
22822 unsigned __tile_udn0_receive (void)
22823 unsigned __tile_udn1_receive (void)
22824 unsigned __tile_udn2_receive (void)
22825 unsigned __tile_udn3_receive (void)
22826 void __tile_idn_send (unsigned)
22827 void __tile_sn_send (unsigned)
22828 void __tile_udn_send (unsigned)
22832 The intrinsic @code{void __tile_network_barrier (void)} is used to
22833 guarantee that no network operations before it are reordered with
22836 @node x86 Built-in Functions
22837 @subsection x86 Built-in Functions
22839 These built-in functions are available for the x86-32 and x86-64 family
22840 of computers, depending on the command-line switches used.
22842 If you specify command-line switches such as @option{-msse},
22843 the compiler could use the extended instruction sets even if the built-ins
22844 are not used explicitly in the program. For this reason, applications
22845 that perform run-time CPU detection must compile separate files for each
22846 supported architecture, using the appropriate flags. In particular,
22847 the file containing the CPU detection code should be compiled without
22850 The following machine modes are available for use with MMX built-in functions
22851 (@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers,
22852 @code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a
22853 vector of eight 8-bit integers. Some of the built-in functions operate on
22854 MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode.
22856 If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector
22857 of two 32-bit floating-point values.
22859 If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit
22860 floating-point values. Some instructions use a vector of four 32-bit
22861 integers, these use @code{V4SI}. Finally, some instructions operate on an
22862 entire vector register, interpreting it as a 128-bit integer, these use mode
22865 The x86-32 and x86-64 family of processors use additional built-in
22866 functions for efficient use of @code{TF} (@code{__float128}) 128-bit
22867 floating point and @code{TC} 128-bit complex floating-point values.
22869 The following floating-point built-in functions are always available. All
22870 of them implement the function that is part of the name.
22873 __float128 __builtin_fabsq (__float128)
22874 __float128 __builtin_copysignq (__float128, __float128)
22877 The following built-in functions are always available.
22880 @item __float128 __builtin_infq (void)
22881 Similar to @code{__builtin_inf}, except the return type is @code{__float128}.
22882 @findex __builtin_infq
22884 @item __float128 __builtin_huge_valq (void)
22885 Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}.
22886 @findex __builtin_huge_valq
22888 @item __float128 __builtin_nanq (void)
22889 Similar to @code{__builtin_nan}, except the return type is @code{__float128}.
22890 @findex __builtin_nanq
22892 @item __float128 __builtin_nansq (void)
22893 Similar to @code{__builtin_nans}, except the return type is @code{__float128}.
22894 @findex __builtin_nansq
22897 The following built-in function is always available.
22900 @item void __builtin_ia32_pause (void)
22901 Generates the @code{pause} machine instruction with a compiler memory
22905 The following built-in functions are always available and can be used to
22906 check the target platform type.
22908 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
22909 This function runs the CPU detection code to check the type of CPU and the
22910 features supported. This built-in function needs to be invoked along with the built-in functions
22911 to check CPU type and features, @code{__builtin_cpu_is} and
22912 @code{__builtin_cpu_supports}, only when used in a function that is
22913 executed before any constructors are called. The CPU detection code is
22914 automatically executed in a very high priority constructor.
22916 For example, this function has to be used in @code{ifunc} resolvers that
22917 check for CPU type using the built-in functions @code{__builtin_cpu_is}
22918 and @code{__builtin_cpu_supports}, or in constructors on targets that
22919 don't support constructor priority.
22922 static void (*resolve_memcpy (void)) (void)
22924 // ifunc resolvers fire before constructors, explicitly call the init
22926 __builtin_cpu_init ();
22927 if (__builtin_cpu_supports ("ssse3"))
22928 return ssse3_memcpy; // super fast memcpy with ssse3 instructions.
22930 return default_memcpy;
22933 void *memcpy (void *, const void *, size_t)
22934 __attribute__ ((ifunc ("resolve_memcpy")));
22939 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
22940 This function returns a positive integer if the run-time CPU
22941 is of type @var{cpuname}
22942 and returns @code{0} otherwise. The following CPU names can be detected:
22955 Intel Silvermont CPU.
22964 Intel Core i7 Nehalem CPU.
22967 Intel Core i7 Westmere CPU.
22970 Intel Core i7 Sandy Bridge CPU.
22973 Intel Core i7 Ivy Bridge CPU.
22976 Intel Core i7 Haswell CPU.
22979 Intel Core i7 Broadwell CPU.
22982 Intel Core i7 Skylake CPU.
22984 @item skylake-avx512
22985 Intel Core i7 Skylake AVX512 CPU.
22988 Intel Core i7 Cannon Lake CPU.
22990 @item icelake-client
22991 Intel Core i7 Ice Lake Client CPU.
22993 @item icelake-server
22994 Intel Core i7 Ice Lake Server CPU.
22997 Intel Core i7 Cascadelake CPU.
23000 Intel Core i7 Tigerlake CPU.
23003 Intel Core i7 Cooperlake CPU.
23005 @item sapphirerapids
23006 Intel Core i7 sapphirerapids CPU.
23009 Intel Core i7 Alderlake CPU.
23012 Intel Atom Bonnell CPU.
23015 Intel Atom Silvermont CPU.
23018 Intel Atom Goldmont CPU.
23020 @item goldmont-plus
23021 Intel Atom Goldmont Plus CPU.
23024 Intel Atom Tremont CPU.
23027 Intel Knights Landing CPU.
23030 Intel Knights Mill CPU.
23033 AMD Family 10h CPU.
23036 AMD Family 10h Barcelona CPU.
23039 AMD Family 10h Shanghai CPU.
23042 AMD Family 10h Istanbul CPU.
23045 AMD Family 14h CPU.
23048 AMD Family 15h CPU.
23051 AMD Family 15h Bulldozer version 1.
23054 AMD Family 15h Bulldozer version 2.
23057 AMD Family 15h Bulldozer version 3.
23060 AMD Family 15h Bulldozer version 4.
23063 AMD Family 16h CPU.
23066 AMD Family 17h CPU.
23069 AMD Family 17h Zen version 1.
23072 AMD Family 17h Zen version 2.
23075 AMD Family 19h CPU.
23078 AMD Family 19h Zen version 3.
23081 Here is an example:
23083 if (__builtin_cpu_is ("corei7"))
23085 do_corei7 (); // Core i7 specific implementation.
23089 do_generic (); // Generic implementation.
23094 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
23095 This function returns a positive integer if the run-time CPU
23096 supports @var{feature}
23097 and returns @code{0} otherwise. The following features can be detected:
23105 POPCNT instruction.
23113 SSSE3 instructions.
23115 SSE4.1 instructions.
23117 SSE4.2 instructions.
23123 SSE4A instructions.
23131 AVX512F instructions.
23139 PCLMUL instructions.
23141 AVX512VL instructions.
23143 AVX512BW instructions.
23145 AVX512DQ instructions.
23147 AVX512CD instructions.
23149 AVX512ER instructions.
23151 AVX512PF instructions.
23153 AVX512VBMI instructions.
23155 AVX512IFMA instructions.
23157 AVX5124VNNIW instructions.
23159 AVX5124FMAPS instructions.
23160 @item avx512vpopcntdq
23161 AVX512VPOPCNTDQ instructions.
23163 AVX512VBMI2 instructions.
23167 VPCLMULQDQ instructions.
23169 AVX512VNNI instructions.
23171 AVX512BITALG instructions.
23174 Here is an example:
23176 if (__builtin_cpu_supports ("popcnt"))
23178 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc");
23182 count = generic_countbits (n); //generic implementation.
23187 The following built-in functions are made available by @option{-mmmx}.
23188 All of them generate the machine instruction that is part of the name.
23191 v8qi __builtin_ia32_paddb (v8qi, v8qi)
23192 v4hi __builtin_ia32_paddw (v4hi, v4hi)
23193 v2si __builtin_ia32_paddd (v2si, v2si)
23194 v8qi __builtin_ia32_psubb (v8qi, v8qi)
23195 v4hi __builtin_ia32_psubw (v4hi, v4hi)
23196 v2si __builtin_ia32_psubd (v2si, v2si)
23197 v8qi __builtin_ia32_paddsb (v8qi, v8qi)
23198 v4hi __builtin_ia32_paddsw (v4hi, v4hi)
23199 v8qi __builtin_ia32_psubsb (v8qi, v8qi)
23200 v4hi __builtin_ia32_psubsw (v4hi, v4hi)
23201 v8qi __builtin_ia32_paddusb (v8qi, v8qi)
23202 v4hi __builtin_ia32_paddusw (v4hi, v4hi)
23203 v8qi __builtin_ia32_psubusb (v8qi, v8qi)
23204 v4hi __builtin_ia32_psubusw (v4hi, v4hi)
23205 v4hi __builtin_ia32_pmullw (v4hi, v4hi)
23206 v4hi __builtin_ia32_pmulhw (v4hi, v4hi)
23207 di __builtin_ia32_pand (di, di)
23208 di __builtin_ia32_pandn (di,di)
23209 di __builtin_ia32_por (di, di)
23210 di __builtin_ia32_pxor (di, di)
23211 v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi)
23212 v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi)
23213 v2si __builtin_ia32_pcmpeqd (v2si, v2si)
23214 v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi)
23215 v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi)
23216 v2si __builtin_ia32_pcmpgtd (v2si, v2si)
23217 v8qi __builtin_ia32_punpckhbw (v8qi, v8qi)
23218 v4hi __builtin_ia32_punpckhwd (v4hi, v4hi)
23219 v2si __builtin_ia32_punpckhdq (v2si, v2si)
23220 v8qi __builtin_ia32_punpcklbw (v8qi, v8qi)
23221 v4hi __builtin_ia32_punpcklwd (v4hi, v4hi)
23222 v2si __builtin_ia32_punpckldq (v2si, v2si)
23223 v8qi __builtin_ia32_packsswb (v4hi, v4hi)
23224 v4hi __builtin_ia32_packssdw (v2si, v2si)
23225 v8qi __builtin_ia32_packuswb (v4hi, v4hi)
23227 v4hi __builtin_ia32_psllw (v4hi, v4hi)
23228 v2si __builtin_ia32_pslld (v2si, v2si)
23229 v1di __builtin_ia32_psllq (v1di, v1di)
23230 v4hi __builtin_ia32_psrlw (v4hi, v4hi)
23231 v2si __builtin_ia32_psrld (v2si, v2si)
23232 v1di __builtin_ia32_psrlq (v1di, v1di)
23233 v4hi __builtin_ia32_psraw (v4hi, v4hi)
23234 v2si __builtin_ia32_psrad (v2si, v2si)
23235 v4hi __builtin_ia32_psllwi (v4hi, int)
23236 v2si __builtin_ia32_pslldi (v2si, int)
23237 v1di __builtin_ia32_psllqi (v1di, int)
23238 v4hi __builtin_ia32_psrlwi (v4hi, int)
23239 v2si __builtin_ia32_psrldi (v2si, int)
23240 v1di __builtin_ia32_psrlqi (v1di, int)
23241 v4hi __builtin_ia32_psrawi (v4hi, int)
23242 v2si __builtin_ia32_psradi (v2si, int)
23246 The following built-in functions are made available either with
23247 @option{-msse}, or with @option{-m3dnowa}. All of them generate
23248 the machine instruction that is part of the name.
23251 v4hi __builtin_ia32_pmulhuw (v4hi, v4hi)
23252 v8qi __builtin_ia32_pavgb (v8qi, v8qi)
23253 v4hi __builtin_ia32_pavgw (v4hi, v4hi)
23254 v1di __builtin_ia32_psadbw (v8qi, v8qi)
23255 v8qi __builtin_ia32_pmaxub (v8qi, v8qi)
23256 v4hi __builtin_ia32_pmaxsw (v4hi, v4hi)
23257 v8qi __builtin_ia32_pminub (v8qi, v8qi)
23258 v4hi __builtin_ia32_pminsw (v4hi, v4hi)
23259 int __builtin_ia32_pmovmskb (v8qi)
23260 void __builtin_ia32_maskmovq (v8qi, v8qi, char *)
23261 void __builtin_ia32_movntq (di *, di)
23262 void __builtin_ia32_sfence (void)
23265 The following built-in functions are available when @option{-msse} is used.
23266 All of them generate the machine instruction that is part of the name.
23269 int __builtin_ia32_comieq (v4sf, v4sf)
23270 int __builtin_ia32_comineq (v4sf, v4sf)
23271 int __builtin_ia32_comilt (v4sf, v4sf)
23272 int __builtin_ia32_comile (v4sf, v4sf)
23273 int __builtin_ia32_comigt (v4sf, v4sf)
23274 int __builtin_ia32_comige (v4sf, v4sf)
23275 int __builtin_ia32_ucomieq (v4sf, v4sf)
23276 int __builtin_ia32_ucomineq (v4sf, v4sf)
23277 int __builtin_ia32_ucomilt (v4sf, v4sf)
23278 int __builtin_ia32_ucomile (v4sf, v4sf)
23279 int __builtin_ia32_ucomigt (v4sf, v4sf)
23280 int __builtin_ia32_ucomige (v4sf, v4sf)
23281 v4sf __builtin_ia32_addps (v4sf, v4sf)
23282 v4sf __builtin_ia32_subps (v4sf, v4sf)
23283 v4sf __builtin_ia32_mulps (v4sf, v4sf)
23284 v4sf __builtin_ia32_divps (v4sf, v4sf)
23285 v4sf __builtin_ia32_addss (v4sf, v4sf)
23286 v4sf __builtin_ia32_subss (v4sf, v4sf)
23287 v4sf __builtin_ia32_mulss (v4sf, v4sf)
23288 v4sf __builtin_ia32_divss (v4sf, v4sf)
23289 v4sf __builtin_ia32_cmpeqps (v4sf, v4sf)
23290 v4sf __builtin_ia32_cmpltps (v4sf, v4sf)
23291 v4sf __builtin_ia32_cmpleps (v4sf, v4sf)
23292 v4sf __builtin_ia32_cmpgtps (v4sf, v4sf)
23293 v4sf __builtin_ia32_cmpgeps (v4sf, v4sf)
23294 v4sf __builtin_ia32_cmpunordps (v4sf, v4sf)
23295 v4sf __builtin_ia32_cmpneqps (v4sf, v4sf)
23296 v4sf __builtin_ia32_cmpnltps (v4sf, v4sf)
23297 v4sf __builtin_ia32_cmpnleps (v4sf, v4sf)
23298 v4sf __builtin_ia32_cmpngtps (v4sf, v4sf)
23299 v4sf __builtin_ia32_cmpngeps (v4sf, v4sf)
23300 v4sf __builtin_ia32_cmpordps (v4sf, v4sf)
23301 v4sf __builtin_ia32_cmpeqss (v4sf, v4sf)
23302 v4sf __builtin_ia32_cmpltss (v4sf, v4sf)
23303 v4sf __builtin_ia32_cmpless (v4sf, v4sf)
23304 v4sf __builtin_ia32_cmpunordss (v4sf, v4sf)
23305 v4sf __builtin_ia32_cmpneqss (v4sf, v4sf)
23306 v4sf __builtin_ia32_cmpnltss (v4sf, v4sf)
23307 v4sf __builtin_ia32_cmpnless (v4sf, v4sf)
23308 v4sf __builtin_ia32_cmpordss (v4sf, v4sf)
23309 v4sf __builtin_ia32_maxps (v4sf, v4sf)
23310 v4sf __builtin_ia32_maxss (v4sf, v4sf)
23311 v4sf __builtin_ia32_minps (v4sf, v4sf)
23312 v4sf __builtin_ia32_minss (v4sf, v4sf)
23313 v4sf __builtin_ia32_andps (v4sf, v4sf)
23314 v4sf __builtin_ia32_andnps (v4sf, v4sf)
23315 v4sf __builtin_ia32_orps (v4sf, v4sf)
23316 v4sf __builtin_ia32_xorps (v4sf, v4sf)
23317 v4sf __builtin_ia32_movss (v4sf, v4sf)
23318 v4sf __builtin_ia32_movhlps (v4sf, v4sf)
23319 v4sf __builtin_ia32_movlhps (v4sf, v4sf)
23320 v4sf __builtin_ia32_unpckhps (v4sf, v4sf)
23321 v4sf __builtin_ia32_unpcklps (v4sf, v4sf)
23322 v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si)
23323 v4sf __builtin_ia32_cvtsi2ss (v4sf, int)
23324 v2si __builtin_ia32_cvtps2pi (v4sf)
23325 int __builtin_ia32_cvtss2si (v4sf)
23326 v2si __builtin_ia32_cvttps2pi (v4sf)
23327 int __builtin_ia32_cvttss2si (v4sf)
23328 v4sf __builtin_ia32_rcpps (v4sf)
23329 v4sf __builtin_ia32_rsqrtps (v4sf)
23330 v4sf __builtin_ia32_sqrtps (v4sf)
23331 v4sf __builtin_ia32_rcpss (v4sf)
23332 v4sf __builtin_ia32_rsqrtss (v4sf)
23333 v4sf __builtin_ia32_sqrtss (v4sf)
23334 v4sf __builtin_ia32_shufps (v4sf, v4sf, int)
23335 void __builtin_ia32_movntps (float *, v4sf)
23336 int __builtin_ia32_movmskps (v4sf)
23339 The following built-in functions are available when @option{-msse} is used.
23342 @item v4sf __builtin_ia32_loadups (float *)
23343 Generates the @code{movups} machine instruction as a load from memory.
23344 @item void __builtin_ia32_storeups (float *, v4sf)
23345 Generates the @code{movups} machine instruction as a store to memory.
23346 @item v4sf __builtin_ia32_loadss (float *)
23347 Generates the @code{movss} machine instruction as a load from memory.
23348 @item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)
23349 Generates the @code{movhps} machine instruction as a load from memory.
23350 @item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)
23351 Generates the @code{movlps} machine instruction as a load from memory
23352 @item void __builtin_ia32_storehps (v2sf *, v4sf)
23353 Generates the @code{movhps} machine instruction as a store to memory.
23354 @item void __builtin_ia32_storelps (v2sf *, v4sf)
23355 Generates the @code{movlps} machine instruction as a store to memory.
23358 The following built-in functions are available when @option{-msse2} is used.
23359 All of them generate the machine instruction that is part of the name.
23362 int __builtin_ia32_comisdeq (v2df, v2df)
23363 int __builtin_ia32_comisdlt (v2df, v2df)
23364 int __builtin_ia32_comisdle (v2df, v2df)
23365 int __builtin_ia32_comisdgt (v2df, v2df)
23366 int __builtin_ia32_comisdge (v2df, v2df)
23367 int __builtin_ia32_comisdneq (v2df, v2df)
23368 int __builtin_ia32_ucomisdeq (v2df, v2df)
23369 int __builtin_ia32_ucomisdlt (v2df, v2df)
23370 int __builtin_ia32_ucomisdle (v2df, v2df)
23371 int __builtin_ia32_ucomisdgt (v2df, v2df)
23372 int __builtin_ia32_ucomisdge (v2df, v2df)
23373 int __builtin_ia32_ucomisdneq (v2df, v2df)
23374 v2df __builtin_ia32_cmpeqpd (v2df, v2df)
23375 v2df __builtin_ia32_cmpltpd (v2df, v2df)
23376 v2df __builtin_ia32_cmplepd (v2df, v2df)
23377 v2df __builtin_ia32_cmpgtpd (v2df, v2df)
23378 v2df __builtin_ia32_cmpgepd (v2df, v2df)
23379 v2df __builtin_ia32_cmpunordpd (v2df, v2df)
23380 v2df __builtin_ia32_cmpneqpd (v2df, v2df)
23381 v2df __builtin_ia32_cmpnltpd (v2df, v2df)
23382 v2df __builtin_ia32_cmpnlepd (v2df, v2df)
23383 v2df __builtin_ia32_cmpngtpd (v2df, v2df)
23384 v2df __builtin_ia32_cmpngepd (v2df, v2df)
23385 v2df __builtin_ia32_cmpordpd (v2df, v2df)
23386 v2df __builtin_ia32_cmpeqsd (v2df, v2df)
23387 v2df __builtin_ia32_cmpltsd (v2df, v2df)
23388 v2df __builtin_ia32_cmplesd (v2df, v2df)
23389 v2df __builtin_ia32_cmpunordsd (v2df, v2df)
23390 v2df __builtin_ia32_cmpneqsd (v2df, v2df)
23391 v2df __builtin_ia32_cmpnltsd (v2df, v2df)
23392 v2df __builtin_ia32_cmpnlesd (v2df, v2df)
23393 v2df __builtin_ia32_cmpordsd (v2df, v2df)
23394 v2di __builtin_ia32_paddq (v2di, v2di)
23395 v2di __builtin_ia32_psubq (v2di, v2di)
23396 v2df __builtin_ia32_addpd (v2df, v2df)
23397 v2df __builtin_ia32_subpd (v2df, v2df)
23398 v2df __builtin_ia32_mulpd (v2df, v2df)
23399 v2df __builtin_ia32_divpd (v2df, v2df)
23400 v2df __builtin_ia32_addsd (v2df, v2df)
23401 v2df __builtin_ia32_subsd (v2df, v2df)
23402 v2df __builtin_ia32_mulsd (v2df, v2df)
23403 v2df __builtin_ia32_divsd (v2df, v2df)
23404 v2df __builtin_ia32_minpd (v2df, v2df)
23405 v2df __builtin_ia32_maxpd (v2df, v2df)
23406 v2df __builtin_ia32_minsd (v2df, v2df)
23407 v2df __builtin_ia32_maxsd (v2df, v2df)
23408 v2df __builtin_ia32_andpd (v2df, v2df)
23409 v2df __builtin_ia32_andnpd (v2df, v2df)
23410 v2df __builtin_ia32_orpd (v2df, v2df)
23411 v2df __builtin_ia32_xorpd (v2df, v2df)
23412 v2df __builtin_ia32_movsd (v2df, v2df)
23413 v2df __builtin_ia32_unpckhpd (v2df, v2df)
23414 v2df __builtin_ia32_unpcklpd (v2df, v2df)
23415 v16qi __builtin_ia32_paddb128 (v16qi, v16qi)
23416 v8hi __builtin_ia32_paddw128 (v8hi, v8hi)
23417 v4si __builtin_ia32_paddd128 (v4si, v4si)
23418 v2di __builtin_ia32_paddq128 (v2di, v2di)
23419 v16qi __builtin_ia32_psubb128 (v16qi, v16qi)
23420 v8hi __builtin_ia32_psubw128 (v8hi, v8hi)
23421 v4si __builtin_ia32_psubd128 (v4si, v4si)
23422 v2di __builtin_ia32_psubq128 (v2di, v2di)
23423 v8hi __builtin_ia32_pmullw128 (v8hi, v8hi)
23424 v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi)
23425 v2di __builtin_ia32_pand128 (v2di, v2di)
23426 v2di __builtin_ia32_pandn128 (v2di, v2di)
23427 v2di __builtin_ia32_por128 (v2di, v2di)
23428 v2di __builtin_ia32_pxor128 (v2di, v2di)
23429 v16qi __builtin_ia32_pavgb128 (v16qi, v16qi)
23430 v8hi __builtin_ia32_pavgw128 (v8hi, v8hi)
23431 v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi)
23432 v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi)
23433 v4si __builtin_ia32_pcmpeqd128 (v4si, v4si)
23434 v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi)
23435 v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi)
23436 v4si __builtin_ia32_pcmpgtd128 (v4si, v4si)
23437 v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi)
23438 v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi)
23439 v16qi __builtin_ia32_pminub128 (v16qi, v16qi)
23440 v8hi __builtin_ia32_pminsw128 (v8hi, v8hi)
23441 v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi)
23442 v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi)
23443 v4si __builtin_ia32_punpckhdq128 (v4si, v4si)
23444 v2di __builtin_ia32_punpckhqdq128 (v2di, v2di)
23445 v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi)
23446 v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi)
23447 v4si __builtin_ia32_punpckldq128 (v4si, v4si)
23448 v2di __builtin_ia32_punpcklqdq128 (v2di, v2di)
23449 v16qi __builtin_ia32_packsswb128 (v8hi, v8hi)
23450 v8hi __builtin_ia32_packssdw128 (v4si, v4si)
23451 v16qi __builtin_ia32_packuswb128 (v8hi, v8hi)
23452 v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi)
23453 void __builtin_ia32_maskmovdqu (v16qi, v16qi)
23454 v2df __builtin_ia32_loadupd (double *)
23455 void __builtin_ia32_storeupd (double *, v2df)
23456 v2df __builtin_ia32_loadhpd (v2df, double const *)
23457 v2df __builtin_ia32_loadlpd (v2df, double const *)
23458 int __builtin_ia32_movmskpd (v2df)
23459 int __builtin_ia32_pmovmskb128 (v16qi)
23460 void __builtin_ia32_movnti (int *, int)
23461 void __builtin_ia32_movnti64 (long long int *, long long int)
23462 void __builtin_ia32_movntpd (double *, v2df)
23463 void __builtin_ia32_movntdq (v2df *, v2df)
23464 v4si __builtin_ia32_pshufd (v4si, int)
23465 v8hi __builtin_ia32_pshuflw (v8hi, int)
23466 v8hi __builtin_ia32_pshufhw (v8hi, int)
23467 v2di __builtin_ia32_psadbw128 (v16qi, v16qi)
23468 v2df __builtin_ia32_sqrtpd (v2df)
23469 v2df __builtin_ia32_sqrtsd (v2df)
23470 v2df __builtin_ia32_shufpd (v2df, v2df, int)
23471 v2df __builtin_ia32_cvtdq2pd (v4si)
23472 v4sf __builtin_ia32_cvtdq2ps (v4si)
23473 v4si __builtin_ia32_cvtpd2dq (v2df)
23474 v2si __builtin_ia32_cvtpd2pi (v2df)
23475 v4sf __builtin_ia32_cvtpd2ps (v2df)
23476 v4si __builtin_ia32_cvttpd2dq (v2df)
23477 v2si __builtin_ia32_cvttpd2pi (v2df)
23478 v2df __builtin_ia32_cvtpi2pd (v2si)
23479 int __builtin_ia32_cvtsd2si (v2df)
23480 int __builtin_ia32_cvttsd2si (v2df)
23481 long long __builtin_ia32_cvtsd2si64 (v2df)
23482 long long __builtin_ia32_cvttsd2si64 (v2df)
23483 v4si __builtin_ia32_cvtps2dq (v4sf)
23484 v2df __builtin_ia32_cvtps2pd (v4sf)
23485 v4si __builtin_ia32_cvttps2dq (v4sf)
23486 v2df __builtin_ia32_cvtsi2sd (v2df, int)
23487 v2df __builtin_ia32_cvtsi642sd (v2df, long long)
23488 v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df)
23489 v2df __builtin_ia32_cvtss2sd (v2df, v4sf)
23490 void __builtin_ia32_clflush (const void *)
23491 void __builtin_ia32_lfence (void)
23492 void __builtin_ia32_mfence (void)
23493 v16qi __builtin_ia32_loaddqu (const char *)
23494 void __builtin_ia32_storedqu (char *, v16qi)
23495 v1di __builtin_ia32_pmuludq (v2si, v2si)
23496 v2di __builtin_ia32_pmuludq128 (v4si, v4si)
23497 v8hi __builtin_ia32_psllw128 (v8hi, v8hi)
23498 v4si __builtin_ia32_pslld128 (v4si, v4si)
23499 v2di __builtin_ia32_psllq128 (v2di, v2di)
23500 v8hi __builtin_ia32_psrlw128 (v8hi, v8hi)
23501 v4si __builtin_ia32_psrld128 (v4si, v4si)
23502 v2di __builtin_ia32_psrlq128 (v2di, v2di)
23503 v8hi __builtin_ia32_psraw128 (v8hi, v8hi)
23504 v4si __builtin_ia32_psrad128 (v4si, v4si)
23505 v2di __builtin_ia32_pslldqi128 (v2di, int)
23506 v8hi __builtin_ia32_psllwi128 (v8hi, int)
23507 v4si __builtin_ia32_pslldi128 (v4si, int)
23508 v2di __builtin_ia32_psllqi128 (v2di, int)
23509 v2di __builtin_ia32_psrldqi128 (v2di, int)
23510 v8hi __builtin_ia32_psrlwi128 (v8hi, int)
23511 v4si __builtin_ia32_psrldi128 (v4si, int)
23512 v2di __builtin_ia32_psrlqi128 (v2di, int)
23513 v8hi __builtin_ia32_psrawi128 (v8hi, int)
23514 v4si __builtin_ia32_psradi128 (v4si, int)
23515 v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi)
23516 v2di __builtin_ia32_movq128 (v2di)
23519 The following built-in functions are available when @option{-msse3} is used.
23520 All of them generate the machine instruction that is part of the name.
23523 v2df __builtin_ia32_addsubpd (v2df, v2df)
23524 v4sf __builtin_ia32_addsubps (v4sf, v4sf)
23525 v2df __builtin_ia32_haddpd (v2df, v2df)
23526 v4sf __builtin_ia32_haddps (v4sf, v4sf)
23527 v2df __builtin_ia32_hsubpd (v2df, v2df)
23528 v4sf __builtin_ia32_hsubps (v4sf, v4sf)
23529 v16qi __builtin_ia32_lddqu (char const *)
23530 void __builtin_ia32_monitor (void *, unsigned int, unsigned int)
23531 v4sf __builtin_ia32_movshdup (v4sf)
23532 v4sf __builtin_ia32_movsldup (v4sf)
23533 void __builtin_ia32_mwait (unsigned int, unsigned int)
23536 The following built-in functions are available when @option{-mssse3} is used.
23537 All of them generate the machine instruction that is part of the name.
23540 v2si __builtin_ia32_phaddd (v2si, v2si)
23541 v4hi __builtin_ia32_phaddw (v4hi, v4hi)
23542 v4hi __builtin_ia32_phaddsw (v4hi, v4hi)
23543 v2si __builtin_ia32_phsubd (v2si, v2si)
23544 v4hi __builtin_ia32_phsubw (v4hi, v4hi)
23545 v4hi __builtin_ia32_phsubsw (v4hi, v4hi)
23546 v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi)
23547 v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi)
23548 v8qi __builtin_ia32_pshufb (v8qi, v8qi)
23549 v8qi __builtin_ia32_psignb (v8qi, v8qi)
23550 v2si __builtin_ia32_psignd (v2si, v2si)
23551 v4hi __builtin_ia32_psignw (v4hi, v4hi)
23552 v1di __builtin_ia32_palignr (v1di, v1di, int)
23553 v8qi __builtin_ia32_pabsb (v8qi)
23554 v2si __builtin_ia32_pabsd (v2si)
23555 v4hi __builtin_ia32_pabsw (v4hi)
23558 The following built-in functions are available when @option{-mssse3} is used.
23559 All of them generate the machine instruction that is part of the name.
23562 v4si __builtin_ia32_phaddd128 (v4si, v4si)
23563 v8hi __builtin_ia32_phaddw128 (v8hi, v8hi)
23564 v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi)
23565 v4si __builtin_ia32_phsubd128 (v4si, v4si)
23566 v8hi __builtin_ia32_phsubw128 (v8hi, v8hi)
23567 v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi)
23568 v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi)
23569 v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi)
23570 v16qi __builtin_ia32_pshufb128 (v16qi, v16qi)
23571 v16qi __builtin_ia32_psignb128 (v16qi, v16qi)
23572 v4si __builtin_ia32_psignd128 (v4si, v4si)
23573 v8hi __builtin_ia32_psignw128 (v8hi, v8hi)
23574 v2di __builtin_ia32_palignr128 (v2di, v2di, int)
23575 v16qi __builtin_ia32_pabsb128 (v16qi)
23576 v4si __builtin_ia32_pabsd128 (v4si)
23577 v8hi __builtin_ia32_pabsw128 (v8hi)
23580 The following built-in functions are available when @option{-msse4.1} is
23581 used. All of them generate the machine instruction that is part of the
23585 v2df __builtin_ia32_blendpd (v2df, v2df, const int)
23586 v4sf __builtin_ia32_blendps (v4sf, v4sf, const int)
23587 v2df __builtin_ia32_blendvpd (v2df, v2df, v2df)
23588 v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf)
23589 v2df __builtin_ia32_dppd (v2df, v2df, const int)
23590 v4sf __builtin_ia32_dpps (v4sf, v4sf, const int)
23591 v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int)
23592 v2di __builtin_ia32_movntdqa (v2di *);
23593 v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int)
23594 v8hi __builtin_ia32_packusdw128 (v4si, v4si)
23595 v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi)
23596 v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int)
23597 v2di __builtin_ia32_pcmpeqq (v2di, v2di)
23598 v8hi __builtin_ia32_phminposuw128 (v8hi)
23599 v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi)
23600 v4si __builtin_ia32_pmaxsd128 (v4si, v4si)
23601 v4si __builtin_ia32_pmaxud128 (v4si, v4si)
23602 v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi)
23603 v16qi __builtin_ia32_pminsb128 (v16qi, v16qi)
23604 v4si __builtin_ia32_pminsd128 (v4si, v4si)
23605 v4si __builtin_ia32_pminud128 (v4si, v4si)
23606 v8hi __builtin_ia32_pminuw128 (v8hi, v8hi)
23607 v4si __builtin_ia32_pmovsxbd128 (v16qi)
23608 v2di __builtin_ia32_pmovsxbq128 (v16qi)
23609 v8hi __builtin_ia32_pmovsxbw128 (v16qi)
23610 v2di __builtin_ia32_pmovsxdq128 (v4si)
23611 v4si __builtin_ia32_pmovsxwd128 (v8hi)
23612 v2di __builtin_ia32_pmovsxwq128 (v8hi)
23613 v4si __builtin_ia32_pmovzxbd128 (v16qi)
23614 v2di __builtin_ia32_pmovzxbq128 (v16qi)
23615 v8hi __builtin_ia32_pmovzxbw128 (v16qi)
23616 v2di __builtin_ia32_pmovzxdq128 (v4si)
23617 v4si __builtin_ia32_pmovzxwd128 (v8hi)
23618 v2di __builtin_ia32_pmovzxwq128 (v8hi)
23619 v2di __builtin_ia32_pmuldq128 (v4si, v4si)
23620 v4si __builtin_ia32_pmulld128 (v4si, v4si)
23621 int __builtin_ia32_ptestc128 (v2di, v2di)
23622 int __builtin_ia32_ptestnzc128 (v2di, v2di)
23623 int __builtin_ia32_ptestz128 (v2di, v2di)
23624 v2df __builtin_ia32_roundpd (v2df, const int)
23625 v4sf __builtin_ia32_roundps (v4sf, const int)
23626 v2df __builtin_ia32_roundsd (v2df, v2df, const int)
23627 v4sf __builtin_ia32_roundss (v4sf, v4sf, const int)
23630 The following built-in functions are available when @option{-msse4.1} is
23634 @item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)
23635 Generates the @code{insertps} machine instruction.
23636 @item int __builtin_ia32_vec_ext_v16qi (v16qi, const int)
23637 Generates the @code{pextrb} machine instruction.
23638 @item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)
23639 Generates the @code{pinsrb} machine instruction.
23640 @item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)
23641 Generates the @code{pinsrd} machine instruction.
23642 @item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)
23643 Generates the @code{pinsrq} machine instruction in 64bit mode.
23646 The following built-in functions are changed to generate new SSE4.1
23647 instructions when @option{-msse4.1} is used.
23650 @item float __builtin_ia32_vec_ext_v4sf (v4sf, const int)
23651 Generates the @code{extractps} machine instruction.
23652 @item int __builtin_ia32_vec_ext_v4si (v4si, const int)
23653 Generates the @code{pextrd} machine instruction.
23654 @item long long __builtin_ia32_vec_ext_v2di (v2di, const int)
23655 Generates the @code{pextrq} machine instruction in 64bit mode.
23658 The following built-in functions are available when @option{-msse4.2} is
23659 used. All of them generate the machine instruction that is part of the
23663 v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int)
23664 int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int)
23665 int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int)
23666 int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int)
23667 int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int)
23668 int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int)
23669 int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int)
23670 v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int)
23671 int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int)
23672 int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int)
23673 int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int)
23674 int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int)
23675 int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int)
23676 int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int)
23677 v2di __builtin_ia32_pcmpgtq (v2di, v2di)
23680 The following built-in functions are available when @option{-msse4.2} is
23684 @item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char)
23685 Generates the @code{crc32b} machine instruction.
23686 @item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short)
23687 Generates the @code{crc32w} machine instruction.
23688 @item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int)
23689 Generates the @code{crc32l} machine instruction.
23690 @item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long)
23691 Generates the @code{crc32q} machine instruction.
23694 The following built-in functions are changed to generate new SSE4.2
23695 instructions when @option{-msse4.2} is used.
23698 @item int __builtin_popcount (unsigned int)
23699 Generates the @code{popcntl} machine instruction.
23700 @item int __builtin_popcountl (unsigned long)
23701 Generates the @code{popcntl} or @code{popcntq} machine instruction,
23702 depending on the size of @code{unsigned long}.
23703 @item int __builtin_popcountll (unsigned long long)
23704 Generates the @code{popcntq} machine instruction.
23707 The following built-in functions are available when @option{-mavx} is
23708 used. All of them generate the machine instruction that is part of the
23712 v4df __builtin_ia32_addpd256 (v4df,v4df)
23713 v8sf __builtin_ia32_addps256 (v8sf,v8sf)
23714 v4df __builtin_ia32_addsubpd256 (v4df,v4df)
23715 v8sf __builtin_ia32_addsubps256 (v8sf,v8sf)
23716 v4df __builtin_ia32_andnpd256 (v4df,v4df)
23717 v8sf __builtin_ia32_andnps256 (v8sf,v8sf)
23718 v4df __builtin_ia32_andpd256 (v4df,v4df)
23719 v8sf __builtin_ia32_andps256 (v8sf,v8sf)
23720 v4df __builtin_ia32_blendpd256 (v4df,v4df,int)
23721 v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int)
23722 v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df)
23723 v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf)
23724 v2df __builtin_ia32_cmppd (v2df,v2df,int)
23725 v4df __builtin_ia32_cmppd256 (v4df,v4df,int)
23726 v4sf __builtin_ia32_cmpps (v4sf,v4sf,int)
23727 v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int)
23728 v2df __builtin_ia32_cmpsd (v2df,v2df,int)
23729 v4sf __builtin_ia32_cmpss (v4sf,v4sf,int)
23730 v4df __builtin_ia32_cvtdq2pd256 (v4si)
23731 v8sf __builtin_ia32_cvtdq2ps256 (v8si)
23732 v4si __builtin_ia32_cvtpd2dq256 (v4df)
23733 v4sf __builtin_ia32_cvtpd2ps256 (v4df)
23734 v8si __builtin_ia32_cvtps2dq256 (v8sf)
23735 v4df __builtin_ia32_cvtps2pd256 (v4sf)
23736 v4si __builtin_ia32_cvttpd2dq256 (v4df)
23737 v8si __builtin_ia32_cvttps2dq256 (v8sf)
23738 v4df __builtin_ia32_divpd256 (v4df,v4df)
23739 v8sf __builtin_ia32_divps256 (v8sf,v8sf)
23740 v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int)
23741 v4df __builtin_ia32_haddpd256 (v4df,v4df)
23742 v8sf __builtin_ia32_haddps256 (v8sf,v8sf)
23743 v4df __builtin_ia32_hsubpd256 (v4df,v4df)
23744 v8sf __builtin_ia32_hsubps256 (v8sf,v8sf)
23745 v32qi __builtin_ia32_lddqu256 (pcchar)
23746 v32qi __builtin_ia32_loaddqu256 (pcchar)
23747 v4df __builtin_ia32_loadupd256 (pcdouble)
23748 v8sf __builtin_ia32_loadups256 (pcfloat)
23749 v2df __builtin_ia32_maskloadpd (pcv2df,v2df)
23750 v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df)
23751 v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf)
23752 v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf)
23753 void __builtin_ia32_maskstorepd (pv2df,v2df,v2df)
23754 void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df)
23755 void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf)
23756 void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf)
23757 v4df __builtin_ia32_maxpd256 (v4df,v4df)
23758 v8sf __builtin_ia32_maxps256 (v8sf,v8sf)
23759 v4df __builtin_ia32_minpd256 (v4df,v4df)
23760 v8sf __builtin_ia32_minps256 (v8sf,v8sf)
23761 v4df __builtin_ia32_movddup256 (v4df)
23762 int __builtin_ia32_movmskpd256 (v4df)
23763 int __builtin_ia32_movmskps256 (v8sf)
23764 v8sf __builtin_ia32_movshdup256 (v8sf)
23765 v8sf __builtin_ia32_movsldup256 (v8sf)
23766 v4df __builtin_ia32_mulpd256 (v4df,v4df)
23767 v8sf __builtin_ia32_mulps256 (v8sf,v8sf)
23768 v4df __builtin_ia32_orpd256 (v4df,v4df)
23769 v8sf __builtin_ia32_orps256 (v8sf,v8sf)
23770 v2df __builtin_ia32_pd_pd256 (v4df)
23771 v4df __builtin_ia32_pd256_pd (v2df)
23772 v4sf __builtin_ia32_ps_ps256 (v8sf)
23773 v8sf __builtin_ia32_ps256_ps (v4sf)
23774 int __builtin_ia32_ptestc256 (v4di,v4di,ptest)
23775 int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest)
23776 int __builtin_ia32_ptestz256 (v4di,v4di,ptest)
23777 v8sf __builtin_ia32_rcpps256 (v8sf)
23778 v4df __builtin_ia32_roundpd256 (v4df,int)
23779 v8sf __builtin_ia32_roundps256 (v8sf,int)
23780 v8sf __builtin_ia32_rsqrtps_nr256 (v8sf)
23781 v8sf __builtin_ia32_rsqrtps256 (v8sf)
23782 v4df __builtin_ia32_shufpd256 (v4df,v4df,int)
23783 v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int)
23784 v4si __builtin_ia32_si_si256 (v8si)
23785 v8si __builtin_ia32_si256_si (v4si)
23786 v4df __builtin_ia32_sqrtpd256 (v4df)
23787 v8sf __builtin_ia32_sqrtps_nr256 (v8sf)
23788 v8sf __builtin_ia32_sqrtps256 (v8sf)
23789 void __builtin_ia32_storedqu256 (pchar,v32qi)
23790 void __builtin_ia32_storeupd256 (pdouble,v4df)
23791 void __builtin_ia32_storeups256 (pfloat,v8sf)
23792 v4df __builtin_ia32_subpd256 (v4df,v4df)
23793 v8sf __builtin_ia32_subps256 (v8sf,v8sf)
23794 v4df __builtin_ia32_unpckhpd256 (v4df,v4df)
23795 v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf)
23796 v4df __builtin_ia32_unpcklpd256 (v4df,v4df)
23797 v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf)
23798 v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df)
23799 v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf)
23800 v4df __builtin_ia32_vbroadcastsd256 (pcdouble)
23801 v4sf __builtin_ia32_vbroadcastss (pcfloat)
23802 v8sf __builtin_ia32_vbroadcastss256 (pcfloat)
23803 v2df __builtin_ia32_vextractf128_pd256 (v4df,int)
23804 v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int)
23805 v4si __builtin_ia32_vextractf128_si256 (v8si,int)
23806 v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int)
23807 v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int)
23808 v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int)
23809 v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int)
23810 v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int)
23811 v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int)
23812 v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int)
23813 v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int)
23814 v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int)
23815 v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int)
23816 v2df __builtin_ia32_vpermilpd (v2df,int)
23817 v4df __builtin_ia32_vpermilpd256 (v4df,int)
23818 v4sf __builtin_ia32_vpermilps (v4sf,int)
23819 v8sf __builtin_ia32_vpermilps256 (v8sf,int)
23820 v2df __builtin_ia32_vpermilvarpd (v2df,v2di)
23821 v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di)
23822 v4sf __builtin_ia32_vpermilvarps (v4sf,v4si)
23823 v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si)
23824 int __builtin_ia32_vtestcpd (v2df,v2df,ptest)
23825 int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest)
23826 int __builtin_ia32_vtestcps (v4sf,v4sf,ptest)
23827 int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest)
23828 int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest)
23829 int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest)
23830 int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest)
23831 int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest)
23832 int __builtin_ia32_vtestzpd (v2df,v2df,ptest)
23833 int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest)
23834 int __builtin_ia32_vtestzps (v4sf,v4sf,ptest)
23835 int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest)
23836 void __builtin_ia32_vzeroall (void)
23837 void __builtin_ia32_vzeroupper (void)
23838 v4df __builtin_ia32_xorpd256 (v4df,v4df)
23839 v8sf __builtin_ia32_xorps256 (v8sf,v8sf)
23842 The following built-in functions are available when @option{-mavx2} is
23843 used. All of them generate the machine instruction that is part of the
23847 v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int)
23848 v32qi __builtin_ia32_pabsb256 (v32qi)
23849 v16hi __builtin_ia32_pabsw256 (v16hi)
23850 v8si __builtin_ia32_pabsd256 (v8si)
23851 v16hi __builtin_ia32_packssdw256 (v8si,v8si)
23852 v32qi __builtin_ia32_packsswb256 (v16hi,v16hi)
23853 v16hi __builtin_ia32_packusdw256 (v8si,v8si)
23854 v32qi __builtin_ia32_packuswb256 (v16hi,v16hi)
23855 v32qi __builtin_ia32_paddb256 (v32qi,v32qi)
23856 v16hi __builtin_ia32_paddw256 (v16hi,v16hi)
23857 v8si __builtin_ia32_paddd256 (v8si,v8si)
23858 v4di __builtin_ia32_paddq256 (v4di,v4di)
23859 v32qi __builtin_ia32_paddsb256 (v32qi,v32qi)
23860 v16hi __builtin_ia32_paddsw256 (v16hi,v16hi)
23861 v32qi __builtin_ia32_paddusb256 (v32qi,v32qi)
23862 v16hi __builtin_ia32_paddusw256 (v16hi,v16hi)
23863 v4di __builtin_ia32_palignr256 (v4di,v4di,int)
23864 v4di __builtin_ia32_andsi256 (v4di,v4di)
23865 v4di __builtin_ia32_andnotsi256 (v4di,v4di)
23866 v32qi __builtin_ia32_pavgb256 (v32qi,v32qi)
23867 v16hi __builtin_ia32_pavgw256 (v16hi,v16hi)
23868 v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi)
23869 v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int)
23870 v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi)
23871 v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi)
23872 v8si __builtin_ia32_pcmpeqd256 (c8si,v8si)
23873 v4di __builtin_ia32_pcmpeqq256 (v4di,v4di)
23874 v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi)
23875 v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi)
23876 v8si __builtin_ia32_pcmpgtd256 (v8si,v8si)
23877 v4di __builtin_ia32_pcmpgtq256 (v4di,v4di)
23878 v16hi __builtin_ia32_phaddw256 (v16hi,v16hi)
23879 v8si __builtin_ia32_phaddd256 (v8si,v8si)
23880 v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi)
23881 v16hi __builtin_ia32_phsubw256 (v16hi,v16hi)
23882 v8si __builtin_ia32_phsubd256 (v8si,v8si)
23883 v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi)
23884 v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi)
23885 v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi)
23886 v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi)
23887 v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi)
23888 v8si __builtin_ia32_pmaxsd256 (v8si,v8si)
23889 v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi)
23890 v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi)
23891 v8si __builtin_ia32_pmaxud256 (v8si,v8si)
23892 v32qi __builtin_ia32_pminsb256 (v32qi,v32qi)
23893 v16hi __builtin_ia32_pminsw256 (v16hi,v16hi)
23894 v8si __builtin_ia32_pminsd256 (v8si,v8si)
23895 v32qi __builtin_ia32_pminub256 (v32qi,v32qi)
23896 v16hi __builtin_ia32_pminuw256 (v16hi,v16hi)
23897 v8si __builtin_ia32_pminud256 (v8si,v8si)
23898 int __builtin_ia32_pmovmskb256 (v32qi)
23899 v16hi __builtin_ia32_pmovsxbw256 (v16qi)
23900 v8si __builtin_ia32_pmovsxbd256 (v16qi)
23901 v4di __builtin_ia32_pmovsxbq256 (v16qi)
23902 v8si __builtin_ia32_pmovsxwd256 (v8hi)
23903 v4di __builtin_ia32_pmovsxwq256 (v8hi)
23904 v4di __builtin_ia32_pmovsxdq256 (v4si)
23905 v16hi __builtin_ia32_pmovzxbw256 (v16qi)
23906 v8si __builtin_ia32_pmovzxbd256 (v16qi)
23907 v4di __builtin_ia32_pmovzxbq256 (v16qi)
23908 v8si __builtin_ia32_pmovzxwd256 (v8hi)
23909 v4di __builtin_ia32_pmovzxwq256 (v8hi)
23910 v4di __builtin_ia32_pmovzxdq256 (v4si)
23911 v4di __builtin_ia32_pmuldq256 (v8si,v8si)
23912 v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi)
23913 v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi)
23914 v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi)
23915 v16hi __builtin_ia32_pmullw256 (v16hi,v16hi)
23916 v8si __builtin_ia32_pmulld256 (v8si,v8si)
23917 v4di __builtin_ia32_pmuludq256 (v8si,v8si)
23918 v4di __builtin_ia32_por256 (v4di,v4di)
23919 v16hi __builtin_ia32_psadbw256 (v32qi,v32qi)
23920 v32qi __builtin_ia32_pshufb256 (v32qi,v32qi)
23921 v8si __builtin_ia32_pshufd256 (v8si,int)
23922 v16hi __builtin_ia32_pshufhw256 (v16hi,int)
23923 v16hi __builtin_ia32_pshuflw256 (v16hi,int)
23924 v32qi __builtin_ia32_psignb256 (v32qi,v32qi)
23925 v16hi __builtin_ia32_psignw256 (v16hi,v16hi)
23926 v8si __builtin_ia32_psignd256 (v8si,v8si)
23927 v4di __builtin_ia32_pslldqi256 (v4di,int)
23928 v16hi __builtin_ia32_psllwi256 (16hi,int)
23929 v16hi __builtin_ia32_psllw256(v16hi,v8hi)
23930 v8si __builtin_ia32_pslldi256 (v8si,int)
23931 v8si __builtin_ia32_pslld256(v8si,v4si)
23932 v4di __builtin_ia32_psllqi256 (v4di,int)
23933 v4di __builtin_ia32_psllq256(v4di,v2di)
23934 v16hi __builtin_ia32_psrawi256 (v16hi,int)
23935 v16hi __builtin_ia32_psraw256 (v16hi,v8hi)
23936 v8si __builtin_ia32_psradi256 (v8si,int)
23937 v8si __builtin_ia32_psrad256 (v8si,v4si)
23938 v4di __builtin_ia32_psrldqi256 (v4di, int)
23939 v16hi __builtin_ia32_psrlwi256 (v16hi,int)
23940 v16hi __builtin_ia32_psrlw256 (v16hi,v8hi)
23941 v8si __builtin_ia32_psrldi256 (v8si,int)
23942 v8si __builtin_ia32_psrld256 (v8si,v4si)
23943 v4di __builtin_ia32_psrlqi256 (v4di,int)
23944 v4di __builtin_ia32_psrlq256(v4di,v2di)
23945 v32qi __builtin_ia32_psubb256 (v32qi,v32qi)
23946 v32hi __builtin_ia32_psubw256 (v16hi,v16hi)
23947 v8si __builtin_ia32_psubd256 (v8si,v8si)
23948 v4di __builtin_ia32_psubq256 (v4di,v4di)
23949 v32qi __builtin_ia32_psubsb256 (v32qi,v32qi)
23950 v16hi __builtin_ia32_psubsw256 (v16hi,v16hi)
23951 v32qi __builtin_ia32_psubusb256 (v32qi,v32qi)
23952 v16hi __builtin_ia32_psubusw256 (v16hi,v16hi)
23953 v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi)
23954 v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi)
23955 v8si __builtin_ia32_punpckhdq256 (v8si,v8si)
23956 v4di __builtin_ia32_punpckhqdq256 (v4di,v4di)
23957 v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi)
23958 v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi)
23959 v8si __builtin_ia32_punpckldq256 (v8si,v8si)
23960 v4di __builtin_ia32_punpcklqdq256 (v4di,v4di)
23961 v4di __builtin_ia32_pxor256 (v4di,v4di)
23962 v4di __builtin_ia32_movntdqa256 (pv4di)
23963 v4sf __builtin_ia32_vbroadcastss_ps (v4sf)
23964 v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf)
23965 v4df __builtin_ia32_vbroadcastsd_pd256 (v2df)
23966 v4di __builtin_ia32_vbroadcastsi256 (v2di)
23967 v4si __builtin_ia32_pblendd128 (v4si,v4si)
23968 v8si __builtin_ia32_pblendd256 (v8si,v8si)
23969 v32qi __builtin_ia32_pbroadcastb256 (v16qi)
23970 v16hi __builtin_ia32_pbroadcastw256 (v8hi)
23971 v8si __builtin_ia32_pbroadcastd256 (v4si)
23972 v4di __builtin_ia32_pbroadcastq256 (v2di)
23973 v16qi __builtin_ia32_pbroadcastb128 (v16qi)
23974 v8hi __builtin_ia32_pbroadcastw128 (v8hi)
23975 v4si __builtin_ia32_pbroadcastd128 (v4si)
23976 v2di __builtin_ia32_pbroadcastq128 (v2di)
23977 v8si __builtin_ia32_permvarsi256 (v8si,v8si)
23978 v4df __builtin_ia32_permdf256 (v4df,int)
23979 v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf)
23980 v4di __builtin_ia32_permdi256 (v4di,int)
23981 v4di __builtin_ia32_permti256 (v4di,v4di,int)
23982 v4di __builtin_ia32_extract128i256 (v4di,int)
23983 v4di __builtin_ia32_insert128i256 (v4di,v2di,int)
23984 v8si __builtin_ia32_maskloadd256 (pcv8si,v8si)
23985 v4di __builtin_ia32_maskloadq256 (pcv4di,v4di)
23986 v4si __builtin_ia32_maskloadd (pcv4si,v4si)
23987 v2di __builtin_ia32_maskloadq (pcv2di,v2di)
23988 void __builtin_ia32_maskstored256 (pv8si,v8si,v8si)
23989 void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di)
23990 void __builtin_ia32_maskstored (pv4si,v4si,v4si)
23991 void __builtin_ia32_maskstoreq (pv2di,v2di,v2di)
23992 v8si __builtin_ia32_psllv8si (v8si,v8si)
23993 v4si __builtin_ia32_psllv4si (v4si,v4si)
23994 v4di __builtin_ia32_psllv4di (v4di,v4di)
23995 v2di __builtin_ia32_psllv2di (v2di,v2di)
23996 v8si __builtin_ia32_psrav8si (v8si,v8si)
23997 v4si __builtin_ia32_psrav4si (v4si,v4si)
23998 v8si __builtin_ia32_psrlv8si (v8si,v8si)
23999 v4si __builtin_ia32_psrlv4si (v4si,v4si)
24000 v4di __builtin_ia32_psrlv4di (v4di,v4di)
24001 v2di __builtin_ia32_psrlv2di (v2di,v2di)
24002 v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int)
24003 v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int)
24004 v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int)
24005 v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int)
24006 v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int)
24007 v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int)
24008 v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int)
24009 v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int)
24010 v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int)
24011 v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int)
24012 v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int)
24013 v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int)
24014 v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int)
24015 v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int)
24016 v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int)
24017 v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int)
24020 The following built-in functions are available when @option{-maes} is
24021 used. All of them generate the machine instruction that is part of the
24025 v2di __builtin_ia32_aesenc128 (v2di, v2di)
24026 v2di __builtin_ia32_aesenclast128 (v2di, v2di)
24027 v2di __builtin_ia32_aesdec128 (v2di, v2di)
24028 v2di __builtin_ia32_aesdeclast128 (v2di, v2di)
24029 v2di __builtin_ia32_aeskeygenassist128 (v2di, const int)
24030 v2di __builtin_ia32_aesimc128 (v2di)
24033 The following built-in function is available when @option{-mpclmul} is
24037 @item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)
24038 Generates the @code{pclmulqdq} machine instruction.
24041 The following built-in function is available when @option{-mfsgsbase} is
24042 used. All of them generate the machine instruction that is part of the
24046 unsigned int __builtin_ia32_rdfsbase32 (void)
24047 unsigned long long __builtin_ia32_rdfsbase64 (void)
24048 unsigned int __builtin_ia32_rdgsbase32 (void)
24049 unsigned long long __builtin_ia32_rdgsbase64 (void)
24050 void _writefsbase_u32 (unsigned int)
24051 void _writefsbase_u64 (unsigned long long)
24052 void _writegsbase_u32 (unsigned int)
24053 void _writegsbase_u64 (unsigned long long)
24056 The following built-in function is available when @option{-mrdrnd} is
24057 used. All of them generate the machine instruction that is part of the
24061 unsigned int __builtin_ia32_rdrand16_step (unsigned short *)
24062 unsigned int __builtin_ia32_rdrand32_step (unsigned int *)
24063 unsigned int __builtin_ia32_rdrand64_step (unsigned long long *)
24066 The following built-in function is available when @option{-mptwrite} is
24067 used. All of them generate the machine instruction that is part of the
24071 void __builtin_ia32_ptwrite32 (unsigned)
24072 void __builtin_ia32_ptwrite64 (unsigned long long)
24075 The following built-in functions are available when @option{-msse4a} is used.
24076 All of them generate the machine instruction that is part of the name.
24079 void __builtin_ia32_movntsd (double *, v2df)
24080 void __builtin_ia32_movntss (float *, v4sf)
24081 v2di __builtin_ia32_extrq (v2di, v16qi)
24082 v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int)
24083 v2di __builtin_ia32_insertq (v2di, v2di)
24084 v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int)
24087 The following built-in functions are available when @option{-mxop} is used.
24089 v2df __builtin_ia32_vfrczpd (v2df)
24090 v4sf __builtin_ia32_vfrczps (v4sf)
24091 v2df __builtin_ia32_vfrczsd (v2df)
24092 v4sf __builtin_ia32_vfrczss (v4sf)
24093 v4df __builtin_ia32_vfrczpd256 (v4df)
24094 v8sf __builtin_ia32_vfrczps256 (v8sf)
24095 v2di __builtin_ia32_vpcmov (v2di, v2di, v2di)
24096 v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di)
24097 v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si)
24098 v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi)
24099 v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi)
24100 v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df)
24101 v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf)
24102 v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di)
24103 v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si)
24104 v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi)
24105 v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi)
24106 v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df)
24107 v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf)
24108 v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi)
24109 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
24110 v4si __builtin_ia32_vpcomeqd (v4si, v4si)
24111 v2di __builtin_ia32_vpcomeqq (v2di, v2di)
24112 v16qi __builtin_ia32_vpcomequb (v16qi, v16qi)
24113 v4si __builtin_ia32_vpcomequd (v4si, v4si)
24114 v2di __builtin_ia32_vpcomequq (v2di, v2di)
24115 v8hi __builtin_ia32_vpcomequw (v8hi, v8hi)
24116 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
24117 v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi)
24118 v4si __builtin_ia32_vpcomfalsed (v4si, v4si)
24119 v2di __builtin_ia32_vpcomfalseq (v2di, v2di)
24120 v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi)
24121 v4si __builtin_ia32_vpcomfalseud (v4si, v4si)
24122 v2di __builtin_ia32_vpcomfalseuq (v2di, v2di)
24123 v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi)
24124 v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi)
24125 v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi)
24126 v4si __builtin_ia32_vpcomged (v4si, v4si)
24127 v2di __builtin_ia32_vpcomgeq (v2di, v2di)
24128 v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi)
24129 v4si __builtin_ia32_vpcomgeud (v4si, v4si)
24130 v2di __builtin_ia32_vpcomgeuq (v2di, v2di)
24131 v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi)
24132 v8hi __builtin_ia32_vpcomgew (v8hi, v8hi)
24133 v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi)
24134 v4si __builtin_ia32_vpcomgtd (v4si, v4si)
24135 v2di __builtin_ia32_vpcomgtq (v2di, v2di)
24136 v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi)
24137 v4si __builtin_ia32_vpcomgtud (v4si, v4si)
24138 v2di __builtin_ia32_vpcomgtuq (v2di, v2di)
24139 v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi)
24140 v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi)
24141 v16qi __builtin_ia32_vpcomleb (v16qi, v16qi)
24142 v4si __builtin_ia32_vpcomled (v4si, v4si)
24143 v2di __builtin_ia32_vpcomleq (v2di, v2di)
24144 v16qi __builtin_ia32_vpcomleub (v16qi, v16qi)
24145 v4si __builtin_ia32_vpcomleud (v4si, v4si)
24146 v2di __builtin_ia32_vpcomleuq (v2di, v2di)
24147 v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi)
24148 v8hi __builtin_ia32_vpcomlew (v8hi, v8hi)
24149 v16qi __builtin_ia32_vpcomltb (v16qi, v16qi)
24150 v4si __builtin_ia32_vpcomltd (v4si, v4si)
24151 v2di __builtin_ia32_vpcomltq (v2di, v2di)
24152 v16qi __builtin_ia32_vpcomltub (v16qi, v16qi)
24153 v4si __builtin_ia32_vpcomltud (v4si, v4si)
24154 v2di __builtin_ia32_vpcomltuq (v2di, v2di)
24155 v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi)
24156 v8hi __builtin_ia32_vpcomltw (v8hi, v8hi)
24157 v16qi __builtin_ia32_vpcomneb (v16qi, v16qi)
24158 v4si __builtin_ia32_vpcomned (v4si, v4si)
24159 v2di __builtin_ia32_vpcomneq (v2di, v2di)
24160 v16qi __builtin_ia32_vpcomneub (v16qi, v16qi)
24161 v4si __builtin_ia32_vpcomneud (v4si, v4si)
24162 v2di __builtin_ia32_vpcomneuq (v2di, v2di)
24163 v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi)
24164 v8hi __builtin_ia32_vpcomnew (v8hi, v8hi)
24165 v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi)
24166 v4si __builtin_ia32_vpcomtrued (v4si, v4si)
24167 v2di __builtin_ia32_vpcomtrueq (v2di, v2di)
24168 v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi)
24169 v4si __builtin_ia32_vpcomtrueud (v4si, v4si)
24170 v2di __builtin_ia32_vpcomtrueuq (v2di, v2di)
24171 v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi)
24172 v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi)
24173 v4si __builtin_ia32_vphaddbd (v16qi)
24174 v2di __builtin_ia32_vphaddbq (v16qi)
24175 v8hi __builtin_ia32_vphaddbw (v16qi)
24176 v2di __builtin_ia32_vphadddq (v4si)
24177 v4si __builtin_ia32_vphaddubd (v16qi)
24178 v2di __builtin_ia32_vphaddubq (v16qi)
24179 v8hi __builtin_ia32_vphaddubw (v16qi)
24180 v2di __builtin_ia32_vphaddudq (v4si)
24181 v4si __builtin_ia32_vphadduwd (v8hi)
24182 v2di __builtin_ia32_vphadduwq (v8hi)
24183 v4si __builtin_ia32_vphaddwd (v8hi)
24184 v2di __builtin_ia32_vphaddwq (v8hi)
24185 v8hi __builtin_ia32_vphsubbw (v16qi)
24186 v2di __builtin_ia32_vphsubdq (v4si)
24187 v4si __builtin_ia32_vphsubwd (v8hi)
24188 v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si)
24189 v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di)
24190 v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di)
24191 v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si)
24192 v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di)
24193 v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di)
24194 v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si)
24195 v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi)
24196 v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si)
24197 v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi)
24198 v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si)
24199 v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si)
24200 v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi)
24201 v16qi __builtin_ia32_vprotb (v16qi, v16qi)
24202 v4si __builtin_ia32_vprotd (v4si, v4si)
24203 v2di __builtin_ia32_vprotq (v2di, v2di)
24204 v8hi __builtin_ia32_vprotw (v8hi, v8hi)
24205 v16qi __builtin_ia32_vpshab (v16qi, v16qi)
24206 v4si __builtin_ia32_vpshad (v4si, v4si)
24207 v2di __builtin_ia32_vpshaq (v2di, v2di)
24208 v8hi __builtin_ia32_vpshaw (v8hi, v8hi)
24209 v16qi __builtin_ia32_vpshlb (v16qi, v16qi)
24210 v4si __builtin_ia32_vpshld (v4si, v4si)
24211 v2di __builtin_ia32_vpshlq (v2di, v2di)
24212 v8hi __builtin_ia32_vpshlw (v8hi, v8hi)
24215 The following built-in functions are available when @option{-mfma4} is used.
24216 All of them generate the machine instruction that is part of the name.
24219 v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df)
24220 v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf)
24221 v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df)
24222 v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf)
24223 v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df)
24224 v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf)
24225 v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df)
24226 v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf)
24227 v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df)
24228 v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf)
24229 v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df)
24230 v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf)
24231 v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df)
24232 v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf)
24233 v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df)
24234 v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf)
24235 v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df)
24236 v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf)
24237 v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df)
24238 v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf)
24239 v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df)
24240 v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf)
24241 v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df)
24242 v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf)
24243 v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df)
24244 v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf)
24245 v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df)
24246 v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf)
24247 v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df)
24248 v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf)
24249 v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df)
24250 v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf)
24254 The following built-in functions are available when @option{-mlwp} is used.
24257 void __builtin_ia32_llwpcb16 (void *);
24258 void __builtin_ia32_llwpcb32 (void *);
24259 void __builtin_ia32_llwpcb64 (void *);
24260 void * __builtin_ia32_llwpcb16 (void);
24261 void * __builtin_ia32_llwpcb32 (void);
24262 void * __builtin_ia32_llwpcb64 (void);
24263 void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short)
24264 void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int)
24265 void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int)
24266 unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short)
24267 unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int)
24268 unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int)
24271 The following built-in functions are available when @option{-mbmi} is used.
24272 All of them generate the machine instruction that is part of the name.
24274 unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int);
24275 unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long);
24278 The following built-in functions are available when @option{-mbmi2} is used.
24279 All of them generate the machine instruction that is part of the name.
24281 unsigned int _bzhi_u32 (unsigned int, unsigned int)
24282 unsigned int _pdep_u32 (unsigned int, unsigned int)
24283 unsigned int _pext_u32 (unsigned int, unsigned int)
24284 unsigned long long _bzhi_u64 (unsigned long long, unsigned long long)
24285 unsigned long long _pdep_u64 (unsigned long long, unsigned long long)
24286 unsigned long long _pext_u64 (unsigned long long, unsigned long long)
24289 The following built-in functions are available when @option{-mlzcnt} is used.
24290 All of them generate the machine instruction that is part of the name.
24292 unsigned short __builtin_ia32_lzcnt_u16(unsigned short);
24293 unsigned int __builtin_ia32_lzcnt_u32(unsigned int);
24294 unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long);
24297 The following built-in functions are available when @option{-mfxsr} is used.
24298 All of them generate the machine instruction that is part of the name.
24300 void __builtin_ia32_fxsave (void *)
24301 void __builtin_ia32_fxrstor (void *)
24302 void __builtin_ia32_fxsave64 (void *)
24303 void __builtin_ia32_fxrstor64 (void *)
24306 The following built-in functions are available when @option{-mxsave} is used.
24307 All of them generate the machine instruction that is part of the name.
24309 void __builtin_ia32_xsave (void *, long long)
24310 void __builtin_ia32_xrstor (void *, long long)
24311 void __builtin_ia32_xsave64 (void *, long long)
24312 void __builtin_ia32_xrstor64 (void *, long long)
24315 The following built-in functions are available when @option{-mxsaveopt} is used.
24316 All of them generate the machine instruction that is part of the name.
24318 void __builtin_ia32_xsaveopt (void *, long long)
24319 void __builtin_ia32_xsaveopt64 (void *, long long)
24322 The following built-in functions are available when @option{-mtbm} is used.
24323 Both of them generate the immediate form of the bextr machine instruction.
24325 unsigned int __builtin_ia32_bextri_u32 (unsigned int,
24326 const unsigned int);
24327 unsigned long long __builtin_ia32_bextri_u64 (unsigned long long,
24328 const unsigned long long);
24332 The following built-in functions are available when @option{-m3dnow} is used.
24333 All of them generate the machine instruction that is part of the name.
24336 void __builtin_ia32_femms (void)
24337 v8qi __builtin_ia32_pavgusb (v8qi, v8qi)
24338 v2si __builtin_ia32_pf2id (v2sf)
24339 v2sf __builtin_ia32_pfacc (v2sf, v2sf)
24340 v2sf __builtin_ia32_pfadd (v2sf, v2sf)
24341 v2si __builtin_ia32_pfcmpeq (v2sf, v2sf)
24342 v2si __builtin_ia32_pfcmpge (v2sf, v2sf)
24343 v2si __builtin_ia32_pfcmpgt (v2sf, v2sf)
24344 v2sf __builtin_ia32_pfmax (v2sf, v2sf)
24345 v2sf __builtin_ia32_pfmin (v2sf, v2sf)
24346 v2sf __builtin_ia32_pfmul (v2sf, v2sf)
24347 v2sf __builtin_ia32_pfrcp (v2sf)
24348 v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf)
24349 v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf)
24350 v2sf __builtin_ia32_pfrsqrt (v2sf)
24351 v2sf __builtin_ia32_pfsub (v2sf, v2sf)
24352 v2sf __builtin_ia32_pfsubr (v2sf, v2sf)
24353 v2sf __builtin_ia32_pi2fd (v2si)
24354 v4hi __builtin_ia32_pmulhrw (v4hi, v4hi)
24357 The following built-in functions are available when @option{-m3dnowa} is used.
24358 All of them generate the machine instruction that is part of the name.
24361 v2si __builtin_ia32_pf2iw (v2sf)
24362 v2sf __builtin_ia32_pfnacc (v2sf, v2sf)
24363 v2sf __builtin_ia32_pfpnacc (v2sf, v2sf)
24364 v2sf __builtin_ia32_pi2fw (v2si)
24365 v2sf __builtin_ia32_pswapdsf (v2sf)
24366 v2si __builtin_ia32_pswapdsi (v2si)
24369 The following built-in functions are available when @option{-mrtm} is used
24370 They are used for restricted transactional memory. These are the internal
24371 low level functions. Normally the functions in
24372 @ref{x86 transactional memory intrinsics} should be used instead.
24375 int __builtin_ia32_xbegin ()
24376 void __builtin_ia32_xend ()
24377 void __builtin_ia32_xabort (status)
24378 int __builtin_ia32_xtest ()
24381 The following built-in functions are available when @option{-mmwaitx} is used.
24382 All of them generate the machine instruction that is part of the name.
24384 void __builtin_ia32_monitorx (void *, unsigned int, unsigned int)
24385 void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int)
24388 The following built-in functions are available when @option{-mclzero} is used.
24389 All of them generate the machine instruction that is part of the name.
24391 void __builtin_i32_clzero (void *)
24394 The following built-in functions are available when @option{-mpku} is used.
24395 They generate reads and writes to PKRU.
24397 void __builtin_ia32_wrpkru (unsigned int)
24398 unsigned int __builtin_ia32_rdpkru ()
24401 The following built-in functions are available when
24402 @option{-mshstk} option is used. They support shadow stack
24403 machine instructions from Intel Control-flow Enforcement Technology (CET).
24404 Each built-in function generates the machine instruction that is part
24405 of the function's name. These are the internal low-level functions.
24406 Normally the functions in @ref{x86 control-flow protection intrinsics}
24407 should be used instead.
24410 unsigned int __builtin_ia32_rdsspd (void)
24411 unsigned long long __builtin_ia32_rdsspq (void)
24412 void __builtin_ia32_incsspd (unsigned int)
24413 void __builtin_ia32_incsspq (unsigned long long)
24414 void __builtin_ia32_saveprevssp(void);
24415 void __builtin_ia32_rstorssp(void *);
24416 void __builtin_ia32_wrssd(unsigned int, void *);
24417 void __builtin_ia32_wrssq(unsigned long long, void *);
24418 void __builtin_ia32_wrussd(unsigned int, void *);
24419 void __builtin_ia32_wrussq(unsigned long long, void *);
24420 void __builtin_ia32_setssbsy(void);
24421 void __builtin_ia32_clrssbsy(void *);
24424 @node x86 transactional memory intrinsics
24425 @subsection x86 Transactional Memory Intrinsics
24427 These hardware transactional memory intrinsics for x86 allow you to use
24428 memory transactions with RTM (Restricted Transactional Memory).
24429 This support is enabled with the @option{-mrtm} option.
24430 For using HLE (Hardware Lock Elision) see
24431 @ref{x86 specific memory model extensions for transactional memory} instead.
24433 A memory transaction commits all changes to memory in an atomic way,
24434 as visible to other threads. If the transaction fails it is rolled back
24435 and all side effects discarded.
24437 Generally there is no guarantee that a memory transaction ever succeeds
24438 and suitable fallback code always needs to be supplied.
24440 @deftypefn {RTM Function} {unsigned} _xbegin ()
24441 Start a RTM (Restricted Transactional Memory) transaction.
24442 Returns @code{_XBEGIN_STARTED} when the transaction
24443 started successfully (note this is not 0, so the constant has to be
24444 explicitly tested).
24446 If the transaction aborts, all side effects
24447 are undone and an abort code encoded as a bit mask is returned.
24448 The following macros are defined:
24451 @item _XABORT_EXPLICIT
24452 Transaction was explicitly aborted with @code{_xabort}. The parameter passed
24453 to @code{_xabort} is available with @code{_XABORT_CODE(status)}.
24454 @item _XABORT_RETRY
24455 Transaction retry is possible.
24456 @item _XABORT_CONFLICT
24457 Transaction abort due to a memory conflict with another thread.
24458 @item _XABORT_CAPACITY
24459 Transaction abort due to the transaction using too much memory.
24460 @item _XABORT_DEBUG
24461 Transaction abort due to a debug trap.
24462 @item _XABORT_NESTED
24463 Transaction abort in an inner nested transaction.
24466 There is no guarantee
24467 any transaction ever succeeds, so there always needs to be a valid
24471 @deftypefn {RTM Function} {void} _xend ()
24472 Commit the current transaction. When no transaction is active this faults.
24473 All memory side effects of the transaction become visible
24474 to other threads in an atomic manner.
24477 @deftypefn {RTM Function} {int} _xtest ()
24478 Return a nonzero value if a transaction is currently active, otherwise 0.
24481 @deftypefn {RTM Function} {void} _xabort (status)
24482 Abort the current transaction. When no transaction is active this is a no-op.
24483 The @var{status} is an 8-bit constant; its value is encoded in the return
24484 value from @code{_xbegin}.
24487 Here is an example showing handling for @code{_XABORT_RETRY}
24488 and a fallback path for other failures:
24491 #include <immintrin.h>
24493 int n_tries, max_tries;
24494 unsigned status = _XABORT_EXPLICIT;
24497 for (n_tries = 0; n_tries < max_tries; n_tries++)
24499 status = _xbegin ();
24500 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY))
24503 if (status == _XBEGIN_STARTED)
24505 ... transaction code...
24510 ... non-transactional fallback path...
24515 Note that, in most cases, the transactional and non-transactional code
24516 must synchronize together to ensure consistency.
24518 @node x86 control-flow protection intrinsics
24519 @subsection x86 Control-Flow Protection Intrinsics
24521 @deftypefn {CET Function} {ret_type} _get_ssp (void)
24522 Get the current value of shadow stack pointer if shadow stack support
24523 from Intel CET is enabled in the hardware or @code{0} otherwise.
24524 The @code{ret_type} is @code{unsigned long long} for 64-bit targets
24525 and @code{unsigned int} for 32-bit targets.
24528 @deftypefn {CET Function} void _inc_ssp (unsigned int)
24529 Increment the current shadow stack pointer by the size specified by the
24530 function argument. The argument is masked to a byte value for security
24531 reasons, so to increment by more than 255 bytes you must call the function
24535 The shadow stack unwind code looks like:
24538 #include <immintrin.h>
24540 /* Unwind the shadow stack for EH. */
24541 #define _Unwind_Frames_Extra(x) \
24544 _Unwind_Word ssp = _get_ssp (); \
24547 _Unwind_Word tmp = (x); \
24548 while (tmp > 255) \
24560 This code runs unconditionally on all 64-bit processors. For 32-bit
24561 processors the code runs on those that support multi-byte NOP instructions.
24563 @node Target Format Checks
24564 @section Format Checks Specific to Particular Target Machines
24566 For some target machines, GCC supports additional options to the
24568 (@pxref{Function Attributes,,Declaring Attributes of Functions}).
24571 * Solaris Format Checks::
24572 * Darwin Format Checks::
24575 @node Solaris Format Checks
24576 @subsection Solaris Format Checks
24578 Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format
24579 check. @code{cmn_err} accepts a subset of the standard @code{printf}
24580 conversions, and the two-argument @code{%b} conversion for displaying
24581 bit-fields. See the Solaris man page for @code{cmn_err} for more information.
24583 @node Darwin Format Checks
24584 @subsection Darwin Format Checks
24586 In addition to the full set of format archetypes (attribute format style
24587 arguments such as @code{printf}, @code{scanf}, @code{strftime}, and
24588 @code{strfmon}), Darwin targets also support the @code{CFString} (or
24589 @code{__CFString__}) archetype in the @code{format} attribute.
24590 Declarations with this archetype are parsed for correct syntax
24591 and argument types. However, parsing of the format string itself and
24592 validating arguments against it in calls to such functions is currently
24595 Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may
24596 also be used as format arguments. Note that the relevant headers are only likely to be
24597 available on Darwin (OSX) installations. On such installations, the XCode and system
24598 documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and
24599 associated functions.
24602 @section Pragmas Accepted by GCC
24604 @cindex @code{#pragma}
24606 GCC supports several types of pragmas, primarily in order to compile
24607 code originally written for other compilers. Note that in general
24608 we do not recommend the use of pragmas; @xref{Function Attributes},
24609 for further explanation.
24611 The GNU C preprocessor recognizes several pragmas in addition to the
24612 compiler pragmas documented here. Refer to the CPP manual for more
24616 * AArch64 Pragmas::
24621 * RS/6000 and PowerPC Pragmas::
24624 * Solaris Pragmas::
24625 * Symbol-Renaming Pragmas::
24626 * Structure-Layout Pragmas::
24628 * Diagnostic Pragmas::
24629 * Visibility Pragmas::
24630 * Push/Pop Macro Pragmas::
24631 * Function Specific Option Pragmas::
24632 * Loop-Specific Pragmas::
24635 @node AArch64 Pragmas
24636 @subsection AArch64 Pragmas
24638 The pragmas defined by the AArch64 target correspond to the AArch64
24639 target function attributes. They can be specified as below:
24641 #pragma GCC target("string")
24644 where @code{@var{string}} can be any string accepted as an AArch64 target
24645 attribute. @xref{AArch64 Function Attributes}, for more details
24646 on the permissible values of @code{string}.
24649 @subsection ARM Pragmas
24651 The ARM target defines pragmas for controlling the default addition of
24652 @code{long_call} and @code{short_call} attributes to functions.
24653 @xref{Function Attributes}, for information about the effects of these
24658 @cindex pragma, long_calls
24659 Set all subsequent functions to have the @code{long_call} attribute.
24661 @item no_long_calls
24662 @cindex pragma, no_long_calls
24663 Set all subsequent functions to have the @code{short_call} attribute.
24665 @item long_calls_off
24666 @cindex pragma, long_calls_off
24667 Do not affect the @code{long_call} or @code{short_call} attributes of
24668 subsequent functions.
24672 @subsection M32C Pragmas
24675 @item GCC memregs @var{number}
24676 @cindex pragma, memregs
24677 Overrides the command-line option @code{-memregs=} for the current
24678 file. Use with care! This pragma must be before any function in the
24679 file, and mixing different memregs values in different objects may
24680 make them incompatible. This pragma is useful when a
24681 performance-critical function uses a memreg for temporary values,
24682 as it may allow you to reduce the number of memregs used.
24684 @item ADDRESS @var{name} @var{address}
24685 @cindex pragma, address
24686 For any declared symbols matching @var{name}, this does three things
24687 to that symbol: it forces the symbol to be located at the given
24688 address (a number), it forces the symbol to be volatile, and it
24689 changes the symbol's scope to be static. This pragma exists for
24690 compatibility with other compilers, but note that the common
24691 @code{1234H} numeric syntax is not supported (use @code{0x1234}
24695 #pragma ADDRESS port3 0x103
24702 @subsection MeP Pragmas
24706 @item custom io_volatile (on|off)
24707 @cindex pragma, custom io_volatile
24708 Overrides the command-line option @code{-mio-volatile} for the current
24709 file. Note that for compatibility with future GCC releases, this
24710 option should only be used once before any @code{io} variables in each
24713 @item GCC coprocessor available @var{registers}
24714 @cindex pragma, coprocessor available
24715 Specifies which coprocessor registers are available to the register
24716 allocator. @var{registers} may be a single register, register range
24717 separated by ellipses, or comma-separated list of those. Example:
24720 #pragma GCC coprocessor available $c0...$c10, $c28
24723 @item GCC coprocessor call_saved @var{registers}
24724 @cindex pragma, coprocessor call_saved
24725 Specifies which coprocessor registers are to be saved and restored by
24726 any function using them. @var{registers} may be a single register,
24727 register range separated by ellipses, or comma-separated list of
24731 #pragma GCC coprocessor call_saved $c4...$c6, $c31
24734 @item GCC coprocessor subclass '(A|B|C|D)' = @var{registers}
24735 @cindex pragma, coprocessor subclass
24736 Creates and defines a register class. These register classes can be
24737 used by inline @code{asm} constructs. @var{registers} may be a single
24738 register, register range separated by ellipses, or comma-separated
24739 list of those. Example:
24742 #pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6
24744 asm ("cpfoo %0" : "=B" (x));
24747 @item GCC disinterrupt @var{name} , @var{name} @dots{}
24748 @cindex pragma, disinterrupt
24749 For the named functions, the compiler adds code to disable interrupts
24750 for the duration of those functions. If any functions so named
24751 are not encountered in the source, a warning is emitted that the pragma is
24752 not used. Examples:
24755 #pragma disinterrupt foo
24756 #pragma disinterrupt bar, grill
24757 int foo () @{ @dots{} @}
24760 @item GCC call @var{name} , @var{name} @dots{}
24761 @cindex pragma, call
24762 For the named functions, the compiler always uses a register-indirect
24763 call model when calling the named functions. Examples:
24773 @subsection PRU Pragmas
24777 @item ctable_entry @var{index} @var{constant_address}
24778 @cindex pragma, ctable_entry
24779 Specifies that the PRU CTABLE entry given by @var{index} has the value
24780 @var{constant_address}. This enables GCC to emit LBCO/SBCO instructions
24781 when the load/store address is known and can be addressed with some CTABLE
24782 entry. For example:
24785 /* will compile to "sbco Rx, 2, 0x10, 4" */
24786 #pragma ctable_entry 2 0x4802a000
24787 *(unsigned int *)0x4802a010 = val;
24792 @node RS/6000 and PowerPC Pragmas
24793 @subsection RS/6000 and PowerPC Pragmas
24795 The RS/6000 and PowerPC targets define one pragma for controlling
24796 whether or not the @code{longcall} attribute is added to function
24797 declarations by default. This pragma overrides the @option{-mlongcall}
24798 option, but not the @code{longcall} and @code{shortcall} attributes.
24799 @xref{RS/6000 and PowerPC Options}, for more information about when long
24800 calls are and are not necessary.
24804 @cindex pragma, longcall
24805 Apply the @code{longcall} attribute to all subsequent function
24809 Do not apply the @code{longcall} attribute to subsequent function
24813 @c Describe h8300 pragmas here.
24814 @c Describe sh pragmas here.
24815 @c Describe v850 pragmas here.
24817 @node S/390 Pragmas
24818 @subsection S/390 Pragmas
24820 The pragmas defined by the S/390 target correspond to the S/390
24821 target function attributes and some the additional options:
24828 Note that options of the pragma, unlike options of the target
24829 attribute, do change the value of preprocessor macros like
24830 @code{__VEC__}. They can be specified as below:
24833 #pragma GCC target("string[,string]...")
24834 #pragma GCC target("string"[,"string"]...)
24837 @node Darwin Pragmas
24838 @subsection Darwin Pragmas
24840 The following pragmas are available for all architectures running the
24841 Darwin operating system. These are useful for compatibility with other
24845 @item mark @var{tokens}@dots{}
24846 @cindex pragma, mark
24847 This pragma is accepted, but has no effect.
24849 @item options align=@var{alignment}
24850 @cindex pragma, options align
24851 This pragma sets the alignment of fields in structures. The values of
24852 @var{alignment} may be @code{mac68k}, to emulate m68k alignment, or
24853 @code{power}, to emulate PowerPC alignment. Uses of this pragma nest
24854 properly; to restore the previous setting, use @code{reset} for the
24857 @item segment @var{tokens}@dots{}
24858 @cindex pragma, segment
24859 This pragma is accepted, but has no effect.
24861 @item unused (@var{var} [, @var{var}]@dots{})
24862 @cindex pragma, unused
24863 This pragma declares variables to be possibly unused. GCC does not
24864 produce warnings for the listed variables. The effect is similar to
24865 that of the @code{unused} attribute, except that this pragma may appear
24866 anywhere within the variables' scopes.
24869 @node Solaris Pragmas
24870 @subsection Solaris Pragmas
24872 The Solaris target supports @code{#pragma redefine_extname}
24873 (@pxref{Symbol-Renaming Pragmas}). It also supports additional
24874 @code{#pragma} directives for compatibility with the system compiler.
24877 @item align @var{alignment} (@var{variable} [, @var{variable}]...)
24878 @cindex pragma, align
24880 Increase the minimum alignment of each @var{variable} to @var{alignment}.
24881 This is the same as GCC's @code{aligned} attribute @pxref{Variable
24882 Attributes}). Macro expansion occurs on the arguments to this pragma
24883 when compiling C and Objective-C@. It does not currently occur when
24884 compiling C++, but this is a bug which may be fixed in a future
24887 @item fini (@var{function} [, @var{function}]...)
24888 @cindex pragma, fini
24890 This pragma causes each listed @var{function} to be called after
24891 main, or during shared module unloading, by adding a call to the
24892 @code{.fini} section.
24894 @item init (@var{function} [, @var{function}]...)
24895 @cindex pragma, init
24897 This pragma causes each listed @var{function} to be called during
24898 initialization (before @code{main}) or during shared module loading, by
24899 adding a call to the @code{.init} section.
24903 @node Symbol-Renaming Pragmas
24904 @subsection Symbol-Renaming Pragmas
24906 GCC supports a @code{#pragma} directive that changes the name used in
24907 assembly for a given declaration. While this pragma is supported on all
24908 platforms, it is intended primarily to provide compatibility with the
24909 Solaris system headers. This effect can also be achieved using the asm
24910 labels extension (@pxref{Asm Labels}).
24913 @item redefine_extname @var{oldname} @var{newname}
24914 @cindex pragma, redefine_extname
24916 This pragma gives the C function @var{oldname} the assembly symbol
24917 @var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME}
24918 is defined if this pragma is available (currently on all platforms).
24921 This pragma and the @code{asm} labels extension interact in a complicated
24922 manner. Here are some corner cases you may want to be aware of:
24925 @item This pragma silently applies only to declarations with external
24926 linkage. The @code{asm} label feature does not have this restriction.
24928 @item In C++, this pragma silently applies only to declarations with
24929 ``C'' linkage. Again, @code{asm} labels do not have this restriction.
24931 @item If either of the ways of changing the assembly name of a
24932 declaration are applied to a declaration whose assembly name has
24933 already been determined (either by a previous use of one of these
24934 features, or because the compiler needed the assembly name in order to
24935 generate code), and the new name is different, a warning issues and
24936 the name does not change.
24938 @item The @var{oldname} used by @code{#pragma redefine_extname} is
24939 always the C-language name.
24942 @node Structure-Layout Pragmas
24943 @subsection Structure-Layout Pragmas
24945 For compatibility with Microsoft Windows compilers, GCC supports a
24946 set of @code{#pragma} directives that change the maximum alignment of
24947 members of structures (other than zero-width bit-fields), unions, and
24948 classes subsequently defined. The @var{n} value below always is required
24949 to be a small power of two and specifies the new alignment in bytes.
24952 @item @code{#pragma pack(@var{n})} simply sets the new alignment.
24953 @item @code{#pragma pack()} sets the alignment to the one that was in
24954 effect when compilation started (see also command-line option
24955 @option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}).
24956 @item @code{#pragma pack(push[,@var{n}])} pushes the current alignment
24957 setting on an internal stack and then optionally sets the new alignment.
24958 @item @code{#pragma pack(pop)} restores the alignment setting to the one
24959 saved at the top of the internal stack (and removes that stack entry).
24960 Note that @code{#pragma pack([@var{n}])} does not influence this internal
24961 stack; thus it is possible to have @code{#pragma pack(push)} followed by
24962 multiple @code{#pragma pack(@var{n})} instances and finalized by a single
24963 @code{#pragma pack(pop)}.
24966 Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct}
24967 directive which lays out structures and unions subsequently defined as the
24968 documented @code{__attribute__ ((ms_struct))}.
24971 @item @code{#pragma ms_struct on} turns on the Microsoft layout.
24972 @item @code{#pragma ms_struct off} turns off the Microsoft layout.
24973 @item @code{#pragma ms_struct reset} goes back to the default layout.
24976 Most targets also support the @code{#pragma scalar_storage_order} directive
24977 which lays out structures and unions subsequently defined as the documented
24978 @code{__attribute__ ((scalar_storage_order))}.
24981 @item @code{#pragma scalar_storage_order big-endian} sets the storage order
24982 of the scalar fields to big-endian.
24983 @item @code{#pragma scalar_storage_order little-endian} sets the storage order
24984 of the scalar fields to little-endian.
24985 @item @code{#pragma scalar_storage_order default} goes back to the endianness
24986 that was in effect when compilation started (see also command-line option
24987 @option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}).
24991 @subsection Weak Pragmas
24993 For compatibility with SVR4, GCC supports a set of @code{#pragma}
24994 directives for declaring symbols to be weak, and defining weak
24998 @item #pragma weak @var{symbol}
24999 @cindex pragma, weak
25000 This pragma declares @var{symbol} to be weak, as if the declaration
25001 had the attribute of the same name. The pragma may appear before
25002 or after the declaration of @var{symbol}. It is not an error for
25003 @var{symbol} to never be defined at all.
25005 @item #pragma weak @var{symbol1} = @var{symbol2}
25006 This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}.
25007 It is an error if @var{symbol2} is not defined in the current
25011 @node Diagnostic Pragmas
25012 @subsection Diagnostic Pragmas
25014 GCC allows the user to selectively enable or disable certain types of
25015 diagnostics, and change the kind of the diagnostic. For example, a
25016 project's policy might require that all sources compile with
25017 @option{-Werror} but certain files might have exceptions allowing
25018 specific types of warnings. Or, a project might selectively enable
25019 diagnostics and treat them as errors depending on which preprocessor
25020 macros are defined.
25023 @item #pragma GCC diagnostic @var{kind} @var{option}
25024 @cindex pragma, diagnostic
25026 Modifies the disposition of a diagnostic. Note that not all
25027 diagnostics are modifiable; at the moment only warnings (normally
25028 controlled by @samp{-W@dots{}}) can be controlled, and not all of them.
25029 Use @option{-fdiagnostics-show-option} to determine which diagnostics
25030 are controllable and which option controls them.
25032 @var{kind} is @samp{error} to treat this diagnostic as an error,
25033 @samp{warning} to treat it like a warning (even if @option{-Werror} is
25034 in effect), or @samp{ignored} if the diagnostic is to be ignored.
25035 @var{option} is a double quoted string that matches the command-line
25039 #pragma GCC diagnostic warning "-Wformat"
25040 #pragma GCC diagnostic error "-Wformat"
25041 #pragma GCC diagnostic ignored "-Wformat"
25044 Note that these pragmas override any command-line options. GCC keeps
25045 track of the location of each pragma, and issues diagnostics according
25046 to the state as of that point in the source file. Thus, pragmas occurring
25047 after a line do not affect diagnostics caused by that line.
25049 @item #pragma GCC diagnostic push
25050 @itemx #pragma GCC diagnostic pop
25052 Causes GCC to remember the state of the diagnostics as of each
25053 @code{push}, and restore to that point at each @code{pop}. If a
25054 @code{pop} has no matching @code{push}, the command-line options are
25058 #pragma GCC diagnostic error "-Wuninitialized"
25059 foo(a); /* error is given for this one */
25060 #pragma GCC diagnostic push
25061 #pragma GCC diagnostic ignored "-Wuninitialized"
25062 foo(b); /* no diagnostic for this one */
25063 #pragma GCC diagnostic pop
25064 foo(c); /* error is given for this one */
25065 #pragma GCC diagnostic pop
25066 foo(d); /* depends on command-line options */
25071 GCC also offers a simple mechanism for printing messages during
25075 @item #pragma message @var{string}
25076 @cindex pragma, diagnostic
25078 Prints @var{string} as a compiler message on compilation. The message
25079 is informational only, and is neither a compilation warning nor an
25080 error. Newlines can be included in the string by using the @samp{\n}
25084 #pragma message "Compiling " __FILE__ "..."
25087 @var{string} may be parenthesized, and is printed with location
25088 information. For example,
25091 #define DO_PRAGMA(x) _Pragma (#x)
25092 #define TODO(x) DO_PRAGMA(message ("TODO - " #x))
25094 TODO(Remember to fix this)
25098 prints @samp{/tmp/file.c:4: note: #pragma message:
25099 TODO - Remember to fix this}.
25101 @item #pragma GCC error @var{message}
25102 @cindex pragma, diagnostic
25103 Generates an error message. This pragma @emph{is} considered to
25104 indicate an error in the compilation, and it will be treated as such.
25106 Newlines can be included in the string by using the @samp{\n}
25107 escape sequence. They will be displayed as newlines even if the
25108 @option{-fmessage-length} option is set to zero.
25110 The error is only generated if the pragma is present in the code after
25111 pre-processing has been completed. It does not matter however if the
25112 code containing the pragma is unreachable:
25116 #pragma GCC error "this error is not seen"
25121 #pragma GCC error "this error is seen"
25125 @item #pragma GCC warning @var{message}
25126 @cindex pragma, diagnostic
25127 This is just like @samp{pragma GCC error} except that a warning
25128 message is issued instead of an error message. Unless
25129 @option{-Werror} is in effect, in which case this pragma will generate
25134 @node Visibility Pragmas
25135 @subsection Visibility Pragmas
25138 @item #pragma GCC visibility push(@var{visibility})
25139 @itemx #pragma GCC visibility pop
25140 @cindex pragma, visibility
25142 This pragma allows the user to set the visibility for multiple
25143 declarations without having to give each a visibility attribute
25144 (@pxref{Function Attributes}).
25146 In C++, @samp{#pragma GCC visibility} affects only namespace-scope
25147 declarations. Class members and template specializations are not
25148 affected; if you want to override the visibility for a particular
25149 member or instantiation, you must use an attribute.
25154 @node Push/Pop Macro Pragmas
25155 @subsection Push/Pop Macro Pragmas
25157 For compatibility with Microsoft Windows compilers, GCC supports
25158 @samp{#pragma push_macro(@var{"macro_name"})}
25159 and @samp{#pragma pop_macro(@var{"macro_name"})}.
25162 @item #pragma push_macro(@var{"macro_name"})
25163 @cindex pragma, push_macro
25164 This pragma saves the value of the macro named as @var{macro_name} to
25165 the top of the stack for this macro.
25167 @item #pragma pop_macro(@var{"macro_name"})
25168 @cindex pragma, pop_macro
25169 This pragma sets the value of the macro named as @var{macro_name} to
25170 the value on top of the stack for this macro. If the stack for
25171 @var{macro_name} is empty, the value of the macro remains unchanged.
25178 #pragma push_macro("X")
25181 #pragma pop_macro("X")
25186 In this example, the definition of X as 1 is saved by @code{#pragma
25187 push_macro} and restored by @code{#pragma pop_macro}.
25189 @node Function Specific Option Pragmas
25190 @subsection Function Specific Option Pragmas
25193 @item #pragma GCC target (@var{string}, @dots{})
25194 @cindex pragma GCC target
25196 This pragma allows you to set target-specific options for functions
25197 defined later in the source file. One or more strings can be
25198 specified. Each function that is defined after this point is treated
25199 as if it had been declared with one @code{target(}@var{string}@code{)}
25200 attribute for each @var{string} argument. The parentheses around
25201 the strings in the pragma are optional. @xref{Function Attributes},
25202 for more information about the @code{target} attribute and the attribute
25205 The @code{#pragma GCC target} pragma is presently implemented for
25206 x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only.
25208 @item #pragma GCC optimize (@var{string}, @dots{})
25209 @cindex pragma GCC optimize
25211 This pragma allows you to set global optimization options for functions
25212 defined later in the source file. One or more strings can be
25213 specified. Each function that is defined after this point is treated
25214 as if it had been declared with one @code{optimize(}@var{string}@code{)}
25215 attribute for each @var{string} argument. The parentheses around
25216 the strings in the pragma are optional. @xref{Function Attributes},
25217 for more information about the @code{optimize} attribute and the attribute
25220 @item #pragma GCC push_options
25221 @itemx #pragma GCC pop_options
25222 @cindex pragma GCC push_options
25223 @cindex pragma GCC pop_options
25225 These pragmas maintain a stack of the current target and optimization
25226 options. It is intended for include files where you temporarily want
25227 to switch to using a different @samp{#pragma GCC target} or
25228 @samp{#pragma GCC optimize} and then to pop back to the previous
25231 @item #pragma GCC reset_options
25232 @cindex pragma GCC reset_options
25234 This pragma clears the current @code{#pragma GCC target} and
25235 @code{#pragma GCC optimize} to use the default switches as specified
25236 on the command line.
25240 @node Loop-Specific Pragmas
25241 @subsection Loop-Specific Pragmas
25244 @item #pragma GCC ivdep
25245 @cindex pragma GCC ivdep
25247 With this pragma, the programmer asserts that there are no loop-carried
25248 dependencies which would prevent consecutive iterations of
25249 the following loop from executing concurrently with SIMD
25250 (single instruction multiple data) instructions.
25252 For example, the compiler can only unconditionally vectorize the following
25253 loop with the pragma:
25256 void foo (int n, int *a, int *b, int *c)
25260 for (i = 0; i < n; ++i)
25261 a[i] = b[i] + c[i];
25266 In this example, using the @code{restrict} qualifier had the same
25267 effect. In the following example, that would not be possible. Assume
25268 @math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows
25269 that it can unconditionally vectorize the following loop:
25272 void ignore_vec_dep (int *a, int k, int c, int m)
25275 for (int i = 0; i < m; i++)
25276 a[i] = a[i + k] * c;
25280 @item #pragma GCC unroll @var{n}
25281 @cindex pragma GCC unroll @var{n}
25283 You can use this pragma to control how many times a loop should be unrolled.
25284 It must be placed immediately before a @code{for}, @code{while} or @code{do}
25285 loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows.
25286 @var{n} is an integer constant expression specifying the unrolling factor.
25287 The values of @math{0} and @math{1} block any unrolling of the loop.
25291 @node Unnamed Fields
25292 @section Unnamed Structure and Union Fields
25293 @cindex @code{struct}
25294 @cindex @code{union}
25296 As permitted by ISO C11 and for compatibility with other compilers,
25297 GCC allows you to define
25298 a structure or union that contains, as fields, structures and unions
25299 without names. For example:
25313 In this example, you are able to access members of the unnamed
25314 union with code like @samp{foo.b}. Note that only unnamed structs and
25315 unions are allowed, you may not have, for example, an unnamed
25318 You must never create such structures that cause ambiguous field definitions.
25319 For example, in this structure:
25331 it is ambiguous which @code{a} is being referred to with @samp{foo.a}.
25332 The compiler gives errors for such constructs.
25334 @opindex fms-extensions
25335 Unless @option{-fms-extensions} is used, the unnamed field must be a
25336 structure or union definition without a tag (for example, @samp{struct
25337 @{ int a; @};}). If @option{-fms-extensions} is used, the field may
25338 also be a definition with a tag such as @samp{struct foo @{ int a;
25339 @};}, a reference to a previously defined structure or union such as
25340 @samp{struct foo;}, or a reference to a @code{typedef} name for a
25341 previously defined structure or union type.
25343 @opindex fplan9-extensions
25344 The option @option{-fplan9-extensions} enables
25345 @option{-fms-extensions} as well as two other extensions. First, a
25346 pointer to a structure is automatically converted to a pointer to an
25347 anonymous field for assignments and function calls. For example:
25350 struct s1 @{ int a; @};
25351 struct s2 @{ struct s1; @};
25352 extern void f1 (struct s1 *);
25353 void f2 (struct s2 *p) @{ f1 (p); @}
25357 In the call to @code{f1} inside @code{f2}, the pointer @code{p} is
25358 converted into a pointer to the anonymous field.
25360 Second, when the type of an anonymous field is a @code{typedef} for a
25361 @code{struct} or @code{union}, code may refer to the field using the
25362 name of the @code{typedef}.
25365 typedef struct @{ int a; @} s1;
25366 struct s2 @{ s1; @};
25367 s1 f1 (struct s2 *p) @{ return p->s1; @}
25370 These usages are only permitted when they are not ambiguous.
25373 @section Thread-Local Storage
25374 @cindex Thread-Local Storage
25375 @cindex @acronym{TLS}
25376 @cindex @code{__thread}
25378 Thread-local storage (@acronym{TLS}) is a mechanism by which variables
25379 are allocated such that there is one instance of the variable per extant
25380 thread. The runtime model GCC uses to implement this originates
25381 in the IA-64 processor-specific ABI, but has since been migrated
25382 to other processors as well. It requires significant support from
25383 the linker (@command{ld}), dynamic linker (@command{ld.so}), and
25384 system libraries (@file{libc.so} and @file{libpthread.so}), so it
25385 is not available everywhere.
25387 At the user level, the extension is visible with a new storage
25388 class keyword: @code{__thread}. For example:
25392 extern __thread struct state s;
25393 static __thread char *p;
25396 The @code{__thread} specifier may be used alone, with the @code{extern}
25397 or @code{static} specifiers, but with no other storage class specifier.
25398 When used with @code{extern} or @code{static}, @code{__thread} must appear
25399 immediately after the other storage class specifier.
25401 The @code{__thread} specifier may be applied to any global, file-scoped
25402 static, function-scoped static, or static data member of a class. It may
25403 not be applied to block-scoped automatic or non-static data member.
25405 When the address-of operator is applied to a thread-local variable, it is
25406 evaluated at run time and returns the address of the current thread's
25407 instance of that variable. An address so obtained may be used by any
25408 thread. When a thread terminates, any pointers to thread-local variables
25409 in that thread become invalid.
25411 No static initialization may refer to the address of a thread-local variable.
25413 In C++, if an initializer is present for a thread-local variable, it must
25414 be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++
25417 See @uref{https://www.akkadia.org/drepper/tls.pdf,
25418 ELF Handling For Thread-Local Storage} for a detailed explanation of
25419 the four thread-local storage addressing models, and how the runtime
25420 is expected to function.
25423 * C99 Thread-Local Edits::
25424 * C++98 Thread-Local Edits::
25427 @node C99 Thread-Local Edits
25428 @subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage
25430 The following are a set of changes to ISO/IEC 9899:1999 (aka C99)
25431 that document the exact semantics of the language extension.
25435 @cite{5.1.2 Execution environments}
25437 Add new text after paragraph 1
25440 Within either execution environment, a @dfn{thread} is a flow of
25441 control within a program. It is implementation defined whether
25442 or not there may be more than one thread associated with a program.
25443 It is implementation defined how threads beyond the first are
25444 created, the name and type of the function called at thread
25445 startup, and how threads may be terminated. However, objects
25446 with thread storage duration shall be initialized before thread
25451 @cite{6.2.4 Storage durations of objects}
25453 Add new text before paragraph 3
25456 An object whose identifier is declared with the storage-class
25457 specifier @w{@code{__thread}} has @dfn{thread storage duration}.
25458 Its lifetime is the entire execution of the thread, and its
25459 stored value is initialized only once, prior to thread startup.
25463 @cite{6.4.1 Keywords}
25465 Add @code{__thread}.
25468 @cite{6.7.1 Storage-class specifiers}
25470 Add @code{__thread} to the list of storage class specifiers in
25473 Change paragraph 2 to
25476 With the exception of @code{__thread}, at most one storage-class
25477 specifier may be given [@dots{}]. The @code{__thread} specifier may
25478 be used alone, or immediately following @code{extern} or
25482 Add new text after paragraph 6
25485 The declaration of an identifier for a variable that has
25486 block scope that specifies @code{__thread} shall also
25487 specify either @code{extern} or @code{static}.
25489 The @code{__thread} specifier shall be used only with
25494 @node C++98 Thread-Local Edits
25495 @subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage
25497 The following are a set of changes to ISO/IEC 14882:1998 (aka C++98)
25498 that document the exact semantics of the language extension.
25502 @b{[intro.execution]}
25504 New text after paragraph 4
25507 A @dfn{thread} is a flow of control within the abstract machine.
25508 It is implementation defined whether or not there may be more than
25512 New text after paragraph 7
25515 It is unspecified whether additional action must be taken to
25516 ensure when and whether side effects are visible to other threads.
25522 Add @code{__thread}.
25525 @b{[basic.start.main]}
25527 Add after paragraph 5
25530 The thread that begins execution at the @code{main} function is called
25531 the @dfn{main thread}. It is implementation defined how functions
25532 beginning threads other than the main thread are designated or typed.
25533 A function so designated, as well as the @code{main} function, is called
25534 a @dfn{thread startup function}. It is implementation defined what
25535 happens if a thread startup function returns. It is implementation
25536 defined what happens to other threads when any thread calls @code{exit}.
25540 @b{[basic.start.init]}
25542 Add after paragraph 4
25545 The storage for an object of thread storage duration shall be
25546 statically initialized before the first statement of the thread startup
25547 function. An object of thread storage duration shall not require
25548 dynamic initialization.
25552 @b{[basic.start.term]}
25554 Add after paragraph 3
25557 The type of an object with thread storage duration shall not have a
25558 non-trivial destructor, nor shall it be an array type whose elements
25559 (directly or indirectly) have non-trivial destructors.
25565 Add ``thread storage duration'' to the list in paragraph 1.
25570 Thread, static, and automatic storage durations are associated with
25571 objects introduced by declarations [@dots{}].
25574 Add @code{__thread} to the list of specifiers in paragraph 3.
25577 @b{[basic.stc.thread]}
25579 New section before @b{[basic.stc.static]}
25582 The keyword @code{__thread} applied to a non-local object gives the
25583 object thread storage duration.
25585 A local variable or class data member declared both @code{static}
25586 and @code{__thread} gives the variable or member thread storage
25591 @b{[basic.stc.static]}
25596 All objects that have neither thread storage duration, dynamic
25597 storage duration nor are local [@dots{}].
25603 Add @code{__thread} to the list in paragraph 1.
25608 With the exception of @code{__thread}, at most one
25609 @var{storage-class-specifier} shall appear in a given
25610 @var{decl-specifier-seq}. The @code{__thread} specifier may
25611 be used alone, or immediately following the @code{extern} or
25612 @code{static} specifiers. [@dots{}]
25615 Add after paragraph 5
25618 The @code{__thread} specifier can be applied only to the names of objects
25619 and to anonymous unions.
25625 Add after paragraph 6
25628 Non-@code{static} members shall not be @code{__thread}.
25632 @node Binary constants
25633 @section Binary Constants using the @samp{0b} Prefix
25634 @cindex Binary constants using the @samp{0b} prefix
25636 Integer constants can be written as binary constants, consisting of a
25637 sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
25638 @samp{0B}. This is particularly useful in environments that operate a
25639 lot on the bit level (like microcontrollers).
25641 The following statements are identical:
25650 The type of these constants follows the same rules as for octal or
25651 hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
25654 @node C++ Extensions
25655 @chapter Extensions to the C++ Language
25656 @cindex extensions, C++ language
25657 @cindex C++ language extensions
25659 The GNU compiler provides these extensions to the C++ language (and you
25660 can also use most of the C language extensions in your C++ programs). If you
25661 want to write code that checks whether these features are available, you can
25662 test for the GNU compiler the same way as for C programs: check for a
25663 predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to
25664 test specifically for GNU C++ (@pxref{Common Predefined Macros,,
25665 Predefined Macros,cpp,The GNU C Preprocessor}).
25668 * C++ Volatiles:: What constitutes an access to a volatile object.
25669 * Restricted Pointers:: C99 restricted pointers and references.
25670 * Vague Linkage:: Where G++ puts inlines, vtables and such.
25671 * C++ Interface:: You can use a single C++ header file for both
25672 declarations and definitions.
25673 * Template Instantiation:: Methods for ensuring that exactly one copy of
25674 each needed template instantiation is emitted.
25675 * Bound member functions:: You can extract a function pointer to the
25676 method denoted by a @samp{->*} or @samp{.*} expression.
25677 * C++ Attributes:: Variable, function, and type attributes for C++ only.
25678 * Function Multiversioning:: Declaring multiple function versions.
25679 * Type Traits:: Compiler support for type traits.
25680 * C++ Concepts:: Improved support for generic programming.
25681 * Deprecated Features:: Things will disappear from G++.
25682 * Backwards Compatibility:: Compatibilities with earlier definitions of C++.
25685 @node C++ Volatiles
25686 @section When is a Volatile C++ Object Accessed?
25687 @cindex accessing volatiles
25688 @cindex volatile read
25689 @cindex volatile write
25690 @cindex volatile access
25692 The C++ standard differs from the C standard in its treatment of
25693 volatile objects. It fails to specify what constitutes a volatile
25694 access, except to say that C++ should behave in a similar manner to C
25695 with respect to volatiles, where possible. However, the different
25696 lvalueness of expressions between C and C++ complicate the behavior.
25697 G++ behaves the same as GCC for volatile access, @xref{C
25698 Extensions,,Volatiles}, for a description of GCC's behavior.
25700 The C and C++ language specifications differ when an object is
25701 accessed in a void context:
25704 volatile int *src = @var{somevalue};
25708 The C++ standard specifies that such expressions do not undergo lvalue
25709 to rvalue conversion, and that the type of the dereferenced object may
25710 be incomplete. The C++ standard does not specify explicitly that it
25711 is lvalue to rvalue conversion that is responsible for causing an
25712 access. There is reason to believe that it is, because otherwise
25713 certain simple expressions become undefined. However, because it
25714 would surprise most programmers, G++ treats dereferencing a pointer to
25715 volatile object of complete type as GCC would do for an equivalent
25716 type in C@. When the object has incomplete type, G++ issues a
25717 warning; if you wish to force an error, you must force a conversion to
25718 rvalue with, for instance, a static cast.
25720 When using a reference to volatile, G++ does not treat equivalent
25721 expressions as accesses to volatiles, but instead issues a warning that
25722 no volatile is accessed. The rationale for this is that otherwise it
25723 becomes difficult to determine where volatile access occur, and not
25724 possible to ignore the return value from functions returning volatile
25725 references. Again, if you wish to force a read, cast the reference to
25728 G++ implements the same behavior as GCC does when assigning to a
25729 volatile object---there is no reread of the assigned-to object, the
25730 assigned rvalue is reused. Note that in C++ assignment expressions
25731 are lvalues, and if used as an lvalue, the volatile object is
25732 referred to. For instance, @var{vref} refers to @var{vobj}, as
25733 expected, in the following example:
25737 volatile int &vref = vobj = @var{something};
25740 @node Restricted Pointers
25741 @section Restricting Pointer Aliasing
25742 @cindex restricted pointers
25743 @cindex restricted references
25744 @cindex restricted this pointer
25746 As with the C front end, G++ understands the C99 feature of restricted pointers,
25747 specified with the @code{__restrict__}, or @code{__restrict} type
25748 qualifier. Because you cannot compile C++ by specifying the @option{-std=c99}
25749 language flag, @code{restrict} is not a keyword in C++.
25751 In addition to allowing restricted pointers, you can specify restricted
25752 references, which indicate that the reference is not aliased in the local
25756 void fn (int *__restrict__ rptr, int &__restrict__ rref)
25763 In the body of @code{fn}, @var{rptr} points to an unaliased integer and
25764 @var{rref} refers to a (different) unaliased integer.
25766 You may also specify whether a member function's @var{this} pointer is
25767 unaliased by using @code{__restrict__} as a member function qualifier.
25770 void T::fn () __restrict__
25777 Within the body of @code{T::fn}, @var{this} has the effective
25778 definition @code{T *__restrict__ const this}. Notice that the
25779 interpretation of a @code{__restrict__} member function qualifier is
25780 different to that of @code{const} or @code{volatile} qualifier, in that it
25781 is applied to the pointer rather than the object. This is consistent with
25782 other compilers that implement restricted pointers.
25784 As with all outermost parameter qualifiers, @code{__restrict__} is
25785 ignored in function definition matching. This means you only need to
25786 specify @code{__restrict__} in a function definition, rather than
25787 in a function prototype as well.
25789 @node Vague Linkage
25790 @section Vague Linkage
25791 @cindex vague linkage
25793 There are several constructs in C++ that require space in the object
25794 file but are not clearly tied to a single translation unit. We say that
25795 these constructs have ``vague linkage''. Typically such constructs are
25796 emitted wherever they are needed, though sometimes we can be more
25800 @item Inline Functions
25801 Inline functions are typically defined in a header file which can be
25802 included in many different compilations. Hopefully they can usually be
25803 inlined, but sometimes an out-of-line copy is necessary, if the address
25804 of the function is taken or if inlining fails. In general, we emit an
25805 out-of-line copy in all translation units where one is needed. As an
25806 exception, we only emit inline virtual functions with the vtable, since
25807 it always requires a copy.
25809 Local static variables and string constants used in an inline function
25810 are also considered to have vague linkage, since they must be shared
25811 between all inlined and out-of-line instances of the function.
25815 C++ virtual functions are implemented in most compilers using a lookup
25816 table, known as a vtable. The vtable contains pointers to the virtual
25817 functions provided by a class, and each object of the class contains a
25818 pointer to its vtable (or vtables, in some multiple-inheritance
25819 situations). If the class declares any non-inline, non-pure virtual
25820 functions, the first one is chosen as the ``key method'' for the class,
25821 and the vtable is only emitted in the translation unit where the key
25824 @emph{Note:} If the chosen key method is later defined as inline, the
25825 vtable is still emitted in every translation unit that defines it.
25826 Make sure that any inline virtuals are declared inline in the class
25827 body, even if they are not defined there.
25829 @item @code{type_info} objects
25830 @cindex @code{type_info}
25832 C++ requires information about types to be written out in order to
25833 implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
25834 For polymorphic classes (classes with virtual functions), the @samp{type_info}
25835 object is written out along with the vtable so that @samp{dynamic_cast}
25836 can determine the dynamic type of a class object at run time. For all
25837 other types, we write out the @samp{type_info} object when it is used: when
25838 applying @samp{typeid} to an expression, throwing an object, or
25839 referring to a type in a catch clause or exception specification.
25841 @item Template Instantiations
25842 Most everything in this section also applies to template instantiations,
25843 but there are other options as well.
25844 @xref{Template Instantiation,,Where's the Template?}.
25848 When used with GNU ld version 2.8 or later on an ELF system such as
25849 GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of
25850 these constructs will be discarded at link time. This is known as
25853 On targets that don't support COMDAT, but do support weak symbols, GCC
25854 uses them. This way one copy overrides all the others, but
25855 the unused copies still take up space in the executable.
25857 For targets that do not support either COMDAT or weak symbols,
25858 most entities with vague linkage are emitted as local symbols to
25859 avoid duplicate definition errors from the linker. This does not happen
25860 for local statics in inlines, however, as having multiple copies
25861 almost certainly breaks things.
25863 @xref{C++ Interface,,Declarations and Definitions in One Header}, for
25864 another way to control placement of these constructs.
25866 @node C++ Interface
25867 @section C++ Interface and Implementation Pragmas
25869 @cindex interface and implementation headers, C++
25870 @cindex C++ interface and implementation headers
25871 @cindex pragmas, interface and implementation
25873 @code{#pragma interface} and @code{#pragma implementation} provide the
25874 user with a way of explicitly directing the compiler to emit entities
25875 with vague linkage (and debugging information) in a particular
25878 @emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2
25879 by COMDAT support and the ``key method'' heuristic
25880 mentioned in @ref{Vague Linkage}. Using them can actually cause your
25881 program to grow due to unnecessary out-of-line copies of inline
25885 @item #pragma interface
25886 @itemx #pragma interface "@var{subdir}/@var{objects}.h"
25887 @kindex #pragma interface
25888 Use this directive in @emph{header files} that define object classes, to save
25889 space in most of the object files that use those classes. Normally,
25890 local copies of certain information (backup copies of inline member
25891 functions, debugging information, and the internal tables that implement
25892 virtual functions) must be kept in each object file that includes class
25893 definitions. You can use this pragma to avoid such duplication. When a
25894 header file containing @samp{#pragma interface} is included in a
25895 compilation, this auxiliary information is not generated (unless
25896 the main input source file itself uses @samp{#pragma implementation}).
25897 Instead, the object files contain references to be resolved at link
25900 The second form of this directive is useful for the case where you have
25901 multiple headers with the same name in different directories. If you
25902 use this form, you must specify the same string to @samp{#pragma
25905 @item #pragma implementation
25906 @itemx #pragma implementation "@var{objects}.h"
25907 @kindex #pragma implementation
25908 Use this pragma in a @emph{main input file}, when you want full output from
25909 included header files to be generated (and made globally visible). The
25910 included header file, in turn, should use @samp{#pragma interface}.
25911 Backup copies of inline member functions, debugging information, and the
25912 internal tables used to implement virtual functions are all generated in
25913 implementation files.
25915 @cindex implied @code{#pragma implementation}
25916 @cindex @code{#pragma implementation}, implied
25917 @cindex naming convention, implementation headers
25918 If you use @samp{#pragma implementation} with no argument, it applies to
25919 an include file with the same basename@footnote{A file's @dfn{basename}
25920 is the name stripped of all leading path information and of trailing
25921 suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source
25922 file. For example, in @file{allclass.cc}, giving just
25923 @samp{#pragma implementation}
25924 by itself is equivalent to @samp{#pragma implementation "allclass.h"}.
25926 Use the string argument if you want a single implementation file to
25927 include code from multiple header files. (You must also use
25928 @samp{#include} to include the header file; @samp{#pragma
25929 implementation} only specifies how to use the file---it doesn't actually
25932 There is no way to split up the contents of a single header file into
25933 multiple implementation files.
25936 @cindex inlining and C++ pragmas
25937 @cindex C++ pragmas, effect on inlining
25938 @cindex pragmas in C++, effect on inlining
25939 @samp{#pragma implementation} and @samp{#pragma interface} also have an
25940 effect on function inlining.
25942 If you define a class in a header file marked with @samp{#pragma
25943 interface}, the effect on an inline function defined in that class is
25944 similar to an explicit @code{extern} declaration---the compiler emits
25945 no code at all to define an independent version of the function. Its
25946 definition is used only for inlining with its callers.
25948 @opindex fno-implement-inlines
25949 Conversely, when you include the same header file in a main source file
25950 that declares it as @samp{#pragma implementation}, the compiler emits
25951 code for the function itself; this defines a version of the function
25952 that can be found via pointers (or by callers compiled without
25953 inlining). If all calls to the function can be inlined, you can avoid
25954 emitting the function by compiling with @option{-fno-implement-inlines}.
25955 If any calls are not inlined, you will get linker errors.
25957 @node Template Instantiation
25958 @section Where's the Template?
25959 @cindex template instantiation
25961 C++ templates were the first language feature to require more
25962 intelligence from the environment than was traditionally found on a UNIX
25963 system. Somehow the compiler and linker have to make sure that each
25964 template instance occurs exactly once in the executable if it is needed,
25965 and not at all otherwise. There are two basic approaches to this
25966 problem, which are referred to as the Borland model and the Cfront model.
25969 @item Borland model
25970 Borland C++ solved the template instantiation problem by adding the code
25971 equivalent of common blocks to their linker; the compiler emits template
25972 instances in each translation unit that uses them, and the linker
25973 collapses them together. The advantage of this model is that the linker
25974 only has to consider the object files themselves; there is no external
25975 complexity to worry about. The disadvantage is that compilation time
25976 is increased because the template code is being compiled repeatedly.
25977 Code written for this model tends to include definitions of all
25978 templates in the header file, since they must be seen to be
25982 The AT&T C++ translator, Cfront, solved the template instantiation
25983 problem by creating the notion of a template repository, an
25984 automatically maintained place where template instances are stored. A
25985 more modern version of the repository works as follows: As individual
25986 object files are built, the compiler places any template definitions and
25987 instantiations encountered in the repository. At link time, the link
25988 wrapper adds in the objects in the repository and compiles any needed
25989 instances that were not previously emitted. The advantages of this
25990 model are more optimal compilation speed and the ability to use the
25991 system linker; to implement the Borland model a compiler vendor also
25992 needs to replace the linker. The disadvantages are vastly increased
25993 complexity, and thus potential for error; for some code this can be
25994 just as transparent, but in practice it can been very difficult to build
25995 multiple programs in one directory and one program in multiple
25996 directories. Code written for this model tends to separate definitions
25997 of non-inline member templates into a separate file, which should be
25998 compiled separately.
26001 G++ implements the Borland model on targets where the linker supports it,
26002 including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows.
26003 Otherwise G++ implements neither automatic model.
26005 You have the following options for dealing with template instantiations:
26009 Do nothing. Code written for the Borland model works fine, but
26010 each translation unit contains instances of each of the templates it
26011 uses. The duplicate instances will be discarded by the linker, but in
26012 a large program, this can lead to an unacceptable amount of code
26013 duplication in object files or shared libraries.
26015 Duplicate instances of a template can be avoided by defining an explicit
26016 instantiation in one object file, and preventing the compiler from doing
26017 implicit instantiations in any other object files by using an explicit
26018 instantiation declaration, using the @code{extern template} syntax:
26021 extern template int max (int, int);
26024 This syntax is defined in the C++ 2011 standard, but has been supported by
26025 G++ and other compilers since well before 2011.
26027 Explicit instantiations can be used for the largest or most frequently
26028 duplicated instances, without having to know exactly which other instances
26029 are used in the rest of the program. You can scatter the explicit
26030 instantiations throughout your program, perhaps putting them in the
26031 translation units where the instances are used or the translation units
26032 that define the templates themselves; you can put all of the explicit
26033 instantiations you need into one big file; or you can create small files
26040 template class Foo<int>;
26041 template ostream& operator <<
26042 (ostream&, const Foo<int>&);
26046 for each of the instances you need, and create a template instantiation
26047 library from those.
26049 This is the simplest option, but also offers flexibility and
26050 fine-grained control when necessary. It is also the most portable
26051 alternative and programs using this approach will work with most modern
26055 @opindex fno-implicit-templates
26056 Compile your code with @option{-fno-implicit-templates} to disable the
26057 implicit generation of template instances, and explicitly instantiate
26058 all the ones you use. This approach requires more knowledge of exactly
26059 which instances you need than do the others, but it's less
26060 mysterious and allows greater control if you want to ensure that only
26061 the intended instances are used.
26063 If you are using Cfront-model code, you can probably get away with not
26064 using @option{-fno-implicit-templates} when compiling files that don't
26065 @samp{#include} the member template definitions.
26067 If you use one big file to do the instantiations, you may want to
26068 compile it without @option{-fno-implicit-templates} so you get all of the
26069 instances required by your explicit instantiations (but not by any
26070 other files) without having to specify them as well.
26072 In addition to forward declaration of explicit instantiations
26073 (with @code{extern}), G++ has extended the template instantiation
26074 syntax to support instantiation of the compiler support data for a
26075 template class (i.e.@: the vtable) without instantiating any of its
26076 members (with @code{inline}), and instantiation of only the static data
26077 members of a template class, without the support data or member
26078 functions (with @code{static}):
26081 inline template class Foo<int>;
26082 static template class Foo<int>;
26086 @node Bound member functions
26087 @section Extracting the Function Pointer from a Bound Pointer to Member Function
26089 @cindex pointer to member function
26090 @cindex bound pointer to member function
26092 In C++, pointer to member functions (PMFs) are implemented using a wide
26093 pointer of sorts to handle all the possible call mechanisms; the PMF
26094 needs to store information about how to adjust the @samp{this} pointer,
26095 and if the function pointed to is virtual, where to find the vtable, and
26096 where in the vtable to look for the member function. If you are using
26097 PMFs in an inner loop, you should really reconsider that decision. If
26098 that is not an option, you can extract the pointer to the function that
26099 would be called for a given object/PMF pair and call it directly inside
26100 the inner loop, to save a bit of time.
26102 Note that you still pay the penalty for the call through a
26103 function pointer; on most modern architectures, such a call defeats the
26104 branch prediction features of the CPU@. This is also true of normal
26105 virtual function calls.
26107 The syntax for this extension is
26111 extern int (A::*fp)();
26112 typedef int (*fptr)(A *);
26114 fptr p = (fptr)(a.*fp);
26117 For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}),
26118 no object is needed to obtain the address of the function. They can be
26119 converted to function pointers directly:
26122 fptr p1 = (fptr)(&A::foo);
26125 @opindex Wno-pmf-conversions
26126 You must specify @option{-Wno-pmf-conversions} to use this extension.
26128 @node C++ Attributes
26129 @section C++-Specific Variable, Function, and Type Attributes
26131 Some attributes only make sense for C++ programs.
26134 @item abi_tag ("@var{tag}", ...)
26135 @cindex @code{abi_tag} function attribute
26136 @cindex @code{abi_tag} variable attribute
26137 @cindex @code{abi_tag} type attribute
26138 The @code{abi_tag} attribute can be applied to a function, variable, or class
26139 declaration. It modifies the mangled name of the entity to
26140 incorporate the tag name, in order to distinguish the function or
26141 class from an earlier version with a different ABI; perhaps the class
26142 has changed size, or the function has a different return type that is
26143 not encoded in the mangled name.
26145 The attribute can also be applied to an inline namespace, but does not
26146 affect the mangled name of the namespace; in this case it is only used
26147 for @option{-Wabi-tag} warnings and automatic tagging of functions and
26148 variables. Tagging inline namespaces is generally preferable to
26149 tagging individual declarations, but the latter is sometimes
26150 necessary, such as when only certain members of a class need to be
26153 The argument can be a list of strings of arbitrary length. The
26154 strings are sorted on output, so the order of the list is
26157 A redeclaration of an entity must not add new ABI tags,
26158 since doing so would change the mangled name.
26160 The ABI tags apply to a name, so all instantiations and
26161 specializations of a template have the same tags. The attribute will
26162 be ignored if applied to an explicit specialization or instantiation.
26164 The @option{-Wabi-tag} flag enables a warning about a class which does
26165 not have all the ABI tags used by its subobjects and virtual functions; for users with code
26166 that needs to coexist with an earlier ABI, using this option can help
26167 to find all affected types that need to be tagged.
26169 When a type involving an ABI tag is used as the type of a variable or
26170 return type of a function where that tag is not already present in the
26171 signature of the function, the tag is automatically applied to the
26172 variable or function. @option{-Wabi-tag} also warns about this
26173 situation; this warning can be avoided by explicitly tagging the
26174 variable or function or moving it into a tagged inline namespace.
26176 @item init_priority (@var{priority})
26177 @cindex @code{init_priority} variable attribute
26179 In Standard C++, objects defined at namespace scope are guaranteed to be
26180 initialized in an order in strict accordance with that of their definitions
26181 @emph{in a given translation unit}. No guarantee is made for initializations
26182 across translation units. However, GNU C++ allows users to control the
26183 order of initialization of objects defined at namespace scope with the
26184 @code{init_priority} attribute by specifying a relative @var{priority},
26185 a constant integral expression currently bounded between 101 and 65535
26186 inclusive. Lower numbers indicate a higher priority.
26188 In the following example, @code{A} would normally be created before
26189 @code{B}, but the @code{init_priority} attribute reverses that order:
26192 Some_Class A __attribute__ ((init_priority (2000)));
26193 Some_Class B __attribute__ ((init_priority (543)));
26197 Note that the particular values of @var{priority} do not matter; only their
26201 @cindex @code{warn_unused} type attribute
26203 For C++ types with non-trivial constructors and/or destructors it is
26204 impossible for the compiler to determine whether a variable of this
26205 type is truly unused if it is not referenced. This type attribute
26206 informs the compiler that variables of this type should be warned
26207 about if they appear to be unused, just like variables of fundamental
26210 This attribute is appropriate for types which just represent a value,
26211 such as @code{std::string}; it is not appropriate for types which
26212 control a resource, such as @code{std::lock_guard}.
26214 This attribute is also accepted in C, but it is unnecessary because C
26215 does not have constructors or destructors.
26219 @node Function Multiversioning
26220 @section Function Multiversioning
26221 @cindex function versions
26223 With the GNU C++ front end, for x86 targets, you may specify multiple
26224 versions of a function, where each function is specialized for a
26225 specific target feature. At runtime, the appropriate version of the
26226 function is automatically executed depending on the characteristics of
26227 the execution platform. Here is an example.
26230 __attribute__ ((target ("default")))
26233 // The default version of foo.
26237 __attribute__ ((target ("sse4.2")))
26240 // foo version for SSE4.2
26244 __attribute__ ((target ("arch=atom")))
26247 // foo version for the Intel ATOM processor
26251 __attribute__ ((target ("arch=amdfam10")))
26254 // foo version for the AMD Family 0x10 processors.
26261 assert ((*p) () == foo ());
26266 In the above example, four versions of function foo are created. The
26267 first version of foo with the target attribute "default" is the default
26268 version. This version gets executed when no other target specific
26269 version qualifies for execution on a particular platform. A new version
26270 of foo is created by using the same function signature but with a
26271 different target string. Function foo is called or a pointer to it is
26272 taken just like a regular function. GCC takes care of doing the
26273 dispatching to call the right version at runtime. Refer to the
26274 @uref{http://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
26275 Function Multiversioning} for more details.
26278 @section Type Traits
26280 The C++ front end implements syntactic extensions that allow
26281 compile-time determination of
26282 various characteristics of a type (or of a
26286 @item __has_nothrow_assign (type)
26287 If @code{type} is @code{const}-qualified or is a reference type then
26288 the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)}
26289 is @code{true} then the trait is @code{true}, else if @code{type} is
26290 a cv-qualified class or union type with copy assignment operators that are
26291 known not to throw an exception then the trait is @code{true}, else it is
26293 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
26294 @code{void}, or an array of unknown bound.
26296 @item __has_nothrow_copy (type)
26297 If @code{__has_trivial_copy (type)} is @code{true} then the trait is
26298 @code{true}, else if @code{type} is a cv-qualified class or union type
26299 with copy constructors that are known not to throw an exception then
26300 the trait is @code{true}, else it is @code{false}.
26301 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
26302 @code{void}, or an array of unknown bound.
26304 @item __has_nothrow_constructor (type)
26305 If @code{__has_trivial_constructor (type)} is @code{true} then the trait
26306 is @code{true}, else if @code{type} is a cv class or union type (or array
26307 thereof) with a default constructor that is known not to throw an
26308 exception then the trait is @code{true}, else it is @code{false}.
26309 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
26310 @code{void}, or an array of unknown bound.
26312 @item __has_trivial_assign (type)
26313 If @code{type} is @code{const}- qualified or is a reference type then
26314 the trait is @code{false}. Otherwise if @code{__is_pod (type)} is
26315 @code{true} then the trait is @code{true}, else if @code{type} is
26316 a cv-qualified class or union type with a trivial copy assignment
26317 ([class.copy]) then the trait is @code{true}, else it is @code{false}.
26318 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
26319 @code{void}, or an array of unknown bound.
26321 @item __has_trivial_copy (type)
26322 If @code{__is_pod (type)} is @code{true} or @code{type} is a reference
26323 type then the trait is @code{true}, else if @code{type} is a cv class
26324 or union type with a trivial copy constructor ([class.copy]) then the trait
26325 is @code{true}, else it is @code{false}. Requires: @code{type} shall be
26326 a complete type, (possibly cv-qualified) @code{void}, or an array of unknown
26329 @item __has_trivial_constructor (type)
26330 If @code{__is_pod (type)} is @code{true} then the trait is @code{true},
26331 else if @code{type} is a cv-qualified class or union type (or array thereof)
26332 with a trivial default constructor ([class.ctor]) then the trait is @code{true},
26333 else it is @code{false}.
26334 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
26335 @code{void}, or an array of unknown bound.
26337 @item __has_trivial_destructor (type)
26338 If @code{__is_pod (type)} is @code{true} or @code{type} is a reference type
26339 then the trait is @code{true}, else if @code{type} is a cv class or union
26340 type (or array thereof) with a trivial destructor ([class.dtor]) then
26341 the trait is @code{true}, else it is @code{false}.
26342 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
26343 @code{void}, or an array of unknown bound.
26345 @item __has_virtual_destructor (type)
26346 If @code{type} is a class type with a virtual destructor
26347 ([class.dtor]) then the trait is @code{true}, else it is @code{false}.
26348 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
26349 @code{void}, or an array of unknown bound.
26351 @item __is_abstract (type)
26352 If @code{type} is an abstract class ([class.abstract]) then the trait
26353 is @code{true}, else it is @code{false}.
26354 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
26355 @code{void}, or an array of unknown bound.
26357 @item __is_base_of (base_type, derived_type)
26358 If @code{base_type} is a base class of @code{derived_type}
26359 ([class.derived]) then the trait is @code{true}, otherwise it is @code{false}.
26360 Top-level cv-qualifications of @code{base_type} and
26361 @code{derived_type} are ignored. For the purposes of this trait, a
26362 class type is considered is own base.
26363 Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)}
26364 are @code{true} and @code{base_type} and @code{derived_type} are not the same
26365 type (disregarding cv-qualifiers), @code{derived_type} shall be a complete
26366 type. A diagnostic is produced if this requirement is not met.
26368 @item __is_class (type)
26369 If @code{type} is a cv-qualified class type, and not a union type
26370 ([basic.compound]) the trait is @code{true}, else it is @code{false}.
26372 @item __is_empty (type)
26373 If @code{__is_class (type)} is @code{false} then the trait is @code{false}.
26374 Otherwise @code{type} is considered empty if and only if: @code{type}
26375 has no non-static data members, or all non-static data members, if
26376 any, are bit-fields of length 0, and @code{type} has no virtual
26377 members, and @code{type} has no virtual base classes, and @code{type}
26378 has no base classes @code{base_type} for which
26379 @code{__is_empty (base_type)} is @code{false}.
26380 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
26381 @code{void}, or an array of unknown bound.
26383 @item __is_enum (type)
26384 If @code{type} is a cv enumeration type ([basic.compound]) the trait is
26385 @code{true}, else it is @code{false}.
26387 @item __is_literal_type (type)
26388 If @code{type} is a literal type ([basic.types]) the trait is
26389 @code{true}, else it is @code{false}.
26390 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
26391 @code{void}, or an array of unknown bound.
26393 @item __is_pod (type)
26394 If @code{type} is a cv POD type ([basic.types]) then the trait is @code{true},
26395 else it is @code{false}.
26396 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
26397 @code{void}, or an array of unknown bound.
26399 @item __is_polymorphic (type)
26400 If @code{type} is a polymorphic class ([class.virtual]) then the trait
26401 is @code{true}, else it is @code{false}.
26402 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
26403 @code{void}, or an array of unknown bound.
26405 @item __is_standard_layout (type)
26406 If @code{type} is a standard-layout type ([basic.types]) the trait is
26407 @code{true}, else it is @code{false}.
26408 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
26409 @code{void}, or an array of unknown bound.
26411 @item __is_trivial (type)
26412 If @code{type} is a trivial type ([basic.types]) the trait is
26413 @code{true}, else it is @code{false}.
26414 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
26415 @code{void}, or an array of unknown bound.
26417 @item __is_union (type)
26418 If @code{type} is a cv union type ([basic.compound]) the trait is
26419 @code{true}, else it is @code{false}.
26421 @item __underlying_type (type)
26422 The underlying type of @code{type}.
26423 Requires: @code{type} shall be an enumeration type ([dcl.enum]).
26425 @item __integer_pack (length)
26426 When used as the pattern of a pack expansion within a template
26427 definition, expands to a template argument pack containing integers
26428 from @code{0} to @code{length-1}. This is provided for efficient
26429 implementation of @code{std::make_integer_sequence}.
26435 @section C++ Concepts
26437 C++ concepts provide much-improved support for generic programming. In
26438 particular, they allow the specification of constraints on template arguments.
26439 The constraints are used to extend the usual overloading and partial
26440 specialization capabilities of the language, allowing generic data structures
26441 and algorithms to be ``refined'' based on their properties rather than their
26444 The following keywords are reserved for concepts.
26448 States an expression as an assumption, and if possible, verifies that the
26449 assumption is valid. For example, @code{assume(n > 0)}.
26452 Introduces an axiom definition. Axioms introduce requirements on values.
26455 Introduces a universally quantified object in an axiom. For example,
26456 @code{forall (int n) n + 0 == n}).
26459 Introduces a concept definition. Concepts are sets of syntactic and semantic
26460 requirements on types and their values.
26463 Introduces constraints on template arguments or requirements for a member
26464 function of a class template.
26468 The front end also exposes a number of internal mechanism that can be used
26469 to simplify the writing of type traits. Note that some of these traits are
26470 likely to be removed in the future.
26473 @item __is_same (type1, type2)
26474 A binary type trait: @code{true} whenever the type arguments are the same.
26479 @node Deprecated Features
26480 @section Deprecated Features
26482 In the past, the GNU C++ compiler was extended to experiment with new
26483 features, at a time when the C++ language was still evolving. Now that
26484 the C++ standard is complete, some of those features are superseded by
26485 superior alternatives. Using the old features might cause a warning in
26486 some cases that the feature will be dropped in the future. In other
26487 cases, the feature might be gone already.
26489 G++ allows a virtual function returning @samp{void *} to be overridden
26490 by one returning a different pointer type. This extension to the
26491 covariant return type rules is now deprecated and will be removed from a
26494 The use of default arguments in function pointers, function typedefs
26495 and other places where they are not permitted by the standard is
26496 deprecated and will be removed from a future version of G++.
26498 G++ allows floating-point literals to appear in integral constant expressions,
26499 e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} }
26500 This extension is deprecated and will be removed from a future version.
26502 G++ allows static data members of const floating-point type to be declared
26503 with an initializer in a class definition. The standard only allows
26504 initializers for static members of const integral types and const
26505 enumeration types so this extension has been deprecated and will be removed
26506 from a future version.
26508 G++ allows attributes to follow a parenthesized direct initializer,
26509 e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension
26510 has been ignored since G++ 3.3 and is deprecated.
26512 G++ allows anonymous structs and unions to have members that are not
26513 public non-static data members (i.e.@: fields). These extensions are
26516 @node Backwards Compatibility
26517 @section Backwards Compatibility
26518 @cindex Backwards Compatibility
26519 @cindex ARM [Annotated C++ Reference Manual]
26521 Now that there is a definitive ISO standard C++, G++ has a specification
26522 to adhere to. The C++ language evolved over time, and features that
26523 used to be acceptable in previous drafts of the standard, such as the ARM
26524 [Annotated C++ Reference Manual], are no longer accepted. In order to allow
26525 compilation of C++ written to such drafts, G++ contains some backwards
26526 compatibilities. @emph{All such backwards compatibility features are
26527 liable to disappear in future versions of G++.} They should be considered
26528 deprecated. @xref{Deprecated Features}.
26532 @item Implicit C language
26533 Old C system header files did not contain an @code{extern "C" @{@dots{}@}}
26534 scope to set the language. On such systems, all system header files are
26535 implicitly scoped inside a C language scope. Such headers must
26536 correctly prototype function argument types, there is no leeway for
26537 @code{()} to indicate an unspecified set of arguments.
26541 @c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd
26542 @c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr