1 c Copyright (C) 1988-2020 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 Declarations:: Mixing declarations 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 Declarations
2357 @section Mixed Declarations 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. As an extension, GNU C also allows this in
2364 C90 mode. For example, you could do:
2373 Each identifier is visible from where it is declared until the end of
2374 the enclosing block.
2376 @node Function Attributes
2377 @section Declaring Attributes of Functions
2378 @cindex function attributes
2379 @cindex declaring attributes of functions
2380 @cindex @code{volatile} applied to function
2381 @cindex @code{const} applied to function
2383 In GNU C and C++, you can use function attributes to specify certain
2384 function properties that may help the compiler optimize calls or
2385 check code more carefully for correctness. For example, you
2386 can use attributes to specify that a function never returns
2387 (@code{noreturn}), returns a value depending only on the values of
2388 its arguments (@code{const}), or has @code{printf}-style arguments
2391 You can also use attributes to control memory placement, code
2392 generation options or call/return conventions within the function
2393 being annotated. Many of these attributes are target-specific. For
2394 example, many targets support attributes for defining interrupt
2395 handler functions, which typically must follow special register usage
2396 and return conventions. Such attributes are described in the subsection
2397 for each target. However, a considerable number of attributes are
2398 supported by most, if not all targets. Those are described in
2399 the @ref{Common Function Attributes} section.
2401 Function attributes are introduced by the @code{__attribute__} keyword
2402 in the declaration of a function, followed by an attribute specification
2403 enclosed in double parentheses. You can specify multiple attributes in
2404 a declaration by separating them by commas within the double parentheses
2405 or by immediately following one attribute specification with another.
2406 @xref{Attribute Syntax}, for the exact rules on attribute syntax and
2407 placement. Compatible attribute specifications on distinct declarations
2408 of the same function are merged. An attribute specification that is not
2409 compatible with attributes already applied to a declaration of the same
2410 function is ignored with a warning.
2412 Some function attributes take one or more arguments that refer to
2413 the function's parameters by their positions within the function parameter
2414 list. Such attribute arguments are referred to as @dfn{positional arguments}.
2415 Unless specified otherwise, positional arguments that specify properties
2416 of parameters with pointer types can also specify the same properties of
2417 the implicit C++ @code{this} argument in non-static member functions, and
2418 of parameters of reference to a pointer type. For ordinary functions,
2419 position one refers to the first parameter on the list. In C++ non-static
2420 member functions, position one refers to the implicit @code{this} pointer.
2421 The same restrictions and effects apply to function attributes used with
2422 ordinary functions or C++ member functions.
2424 GCC also supports attributes on
2425 variable declarations (@pxref{Variable Attributes}),
2426 labels (@pxref{Label Attributes}),
2427 enumerators (@pxref{Enumerator Attributes}),
2428 statements (@pxref{Statement Attributes}),
2429 and types (@pxref{Type Attributes}).
2431 There is some overlap between the purposes of attributes and pragmas
2432 (@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been
2433 found convenient to use @code{__attribute__} to achieve a natural
2434 attachment of attributes to their corresponding declarations, whereas
2435 @code{#pragma} is of use for compatibility with other compilers
2436 or constructs that do not naturally form part of the grammar.
2438 In addition to the attributes documented here,
2439 GCC plugins may provide their own attributes.
2442 * Common Function Attributes::
2443 * AArch64 Function Attributes::
2444 * AMD GCN Function Attributes::
2445 * ARC Function Attributes::
2446 * ARM Function Attributes::
2447 * AVR Function Attributes::
2448 * Blackfin Function Attributes::
2449 * CR16 Function Attributes::
2450 * C-SKY Function Attributes::
2451 * Epiphany Function Attributes::
2452 * H8/300 Function Attributes::
2453 * IA-64 Function Attributes::
2454 * M32C Function Attributes::
2455 * M32R/D Function Attributes::
2456 * m68k Function Attributes::
2457 * MCORE Function Attributes::
2458 * MeP Function Attributes::
2459 * MicroBlaze Function Attributes::
2460 * Microsoft Windows Function Attributes::
2461 * MIPS Function Attributes::
2462 * MSP430 Function Attributes::
2463 * NDS32 Function Attributes::
2464 * Nios II Function Attributes::
2465 * Nvidia PTX Function Attributes::
2466 * PowerPC Function Attributes::
2467 * RISC-V Function Attributes::
2468 * RL78 Function Attributes::
2469 * RX Function Attributes::
2470 * S/390 Function Attributes::
2471 * SH Function Attributes::
2472 * Symbian OS Function Attributes::
2473 * V850 Function Attributes::
2474 * Visium Function Attributes::
2475 * x86 Function Attributes::
2476 * Xstormy16 Function Attributes::
2479 @node Common Function Attributes
2480 @subsection Common Function Attributes
2482 The following attributes are supported on most targets.
2485 @c Keep this table alphabetized by attribute name. Treat _ as space.
2488 @itemx access (@var{access-mode}, @var{ref-index})
2489 @itemx access (@var{access-mode}, @var{ref-index}, @var{size-index})
2491 The @code{access} attribute enables the detection of invalid or unsafe
2492 accesses by functions to which they apply or their callers, as well as
2493 write-only accesses to objects that are never read from. Such accesses
2494 may be diagnosed by warnings such as @option{-Wstringop-overflow},
2495 @option{-Wuninitialized}, @option{-Wunused}, and others.
2497 The @code{access} attribute specifies that a function to whose by-reference
2498 arguments the attribute applies accesses the referenced object according to
2499 @var{access-mode}. The @var{access-mode} argument is required and must be
2500 one of three names: @code{read_only}, @code{read_write}, or @code{write_only}.
2501 The remaining two are positional arguments.
2503 The required @var{ref-index} positional argument denotes a function
2504 argument of pointer (or in C++, reference) type that is subject to
2505 the access. The same pointer argument can be referenced by at most one
2506 distinct @code{access} attribute.
2508 The optional @var{size-index} positional argument denotes a function
2509 argument of integer type that specifies the maximum size of the access.
2510 The size is the number of elements of the type referenced by @var{ref-index},
2511 or the number of bytes when the pointer type is @code{void*}. When no
2512 @var{size-index} argument is specified, the pointer argument must be either
2513 null or point to a space that is suitably aligned and large for at least one
2514 object of the referenced type (this implies that a past-the-end pointer is
2515 not a valid argument). The actual size of the access may be less but it
2518 The @code{read_only} access mode specifies that the pointer to which it
2519 applies is used to read the referenced object but not write to it. Unless
2520 the argument specifying the size of the access denoted by @var{size-index}
2521 is zero, the referenced object must be initialized. The mode implies
2522 a stronger guarantee than the @code{const} qualifier which, when cast away
2523 from a pointer, does not prevent the pointed-to object from being modified.
2524 Examples of the use of the @code{read_only} access mode is the argument to
2525 the @code{puts} function, or the second and third arguments to
2526 the @code{memcpy} function.
2529 __attribute__ ((access (read_only, 1))) int puts (const char*);
2530 __attribute__ ((access (read_only, 1, 2))) void* memcpy (void*, const void*, size_t);
2533 The @code{read_write} access mode applies to arguments of pointer types
2534 without the @code{const} qualifier. It specifies that the pointer to which
2535 it applies is used to both read and write the referenced object. Unless
2536 the argument specifying the size of the access denoted by @var{size-index}
2537 is zero, the object referenced by the pointer must be initialized. An example
2538 of the use of the @code{read_write} access mode is the first argument to
2539 the @code{strcat} function.
2542 __attribute__ ((access (read_write, 1), access (read_only, 2))) char* strcat (char*, const char*);
2545 The @code{write_only} access mode applies to arguments of pointer types
2546 without the @code{const} qualifier. It specifies that the pointer to which
2547 it applies is used to write to the referenced object but not read from it.
2548 The object referenced by the pointer need not be initialized. An example
2549 of the use of the @code{write_only} access mode is the first argument to
2550 the @code{strcpy} function, or the first two arguments to the @code{fgets}
2554 __attribute__ ((access (write_only, 1), access (read_only, 2))) char* strcpy (char*, const char*);
2555 __attribute__ ((access (write_only, 1, 2), access (read_write, 3))) int fgets (char*, int, FILE*);
2558 @item alias ("@var{target}")
2559 @cindex @code{alias} function attribute
2560 The @code{alias} attribute causes the declaration to be emitted as an alias
2561 for another symbol, which must have been previously declared with the same
2562 type, and for variables, also the same size and alignment. Declaring an alias
2563 with a different type than the target is undefined and may be diagnosed. As
2564 an example, the following declarations:
2567 void __f () @{ /* @r{Do something.} */; @}
2568 void f () __attribute__ ((weak, alias ("__f")));
2572 define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name
2573 for the target must be used. It is an error if @samp{__f} is not defined in
2574 the same translation unit.
2576 This attribute requires assembler and object file support,
2577 and may not be available on all targets.
2580 @itemx aligned (@var{alignment})
2581 @cindex @code{aligned} function attribute
2582 The @code{aligned} attribute specifies a minimum alignment for
2583 the first instruction of the function, measured in bytes. When specified,
2584 @var{alignment} must be an integer constant power of 2. Specifying no
2585 @var{alignment} argument implies the ideal alignment for the target.
2586 The @code{__alignof__} operator can be used to determine what that is
2587 (@pxref{Alignment}). The attribute has no effect when a definition for
2588 the function is not provided in the same translation unit.
2590 The attribute cannot be used to decrease the alignment of a function
2591 previously declared with a more restrictive alignment; only to increase
2592 it. Attempts to do otherwise are diagnosed. Some targets specify
2593 a minimum default alignment for functions that is greater than 1. On
2594 such targets, specifying a less restrictive alignment is silently ignored.
2595 Using the attribute overrides the effect of the @option{-falign-functions}
2596 (@pxref{Optimize Options}) option for this function.
2598 Note that the effectiveness of @code{aligned} attributes may be
2599 limited by inherent limitations in the system linker
2600 and/or object file format. On some systems, the
2601 linker is only able to arrange for functions to be aligned up to a
2602 certain maximum alignment. (For some linkers, the maximum supported
2603 alignment may be very very small.) See your linker documentation for
2604 further information.
2606 The @code{aligned} attribute can also be used for variables and fields
2607 (@pxref{Variable Attributes}.)
2609 @item alloc_align (@var{position})
2610 @cindex @code{alloc_align} function attribute
2611 The @code{alloc_align} attribute may be applied to a function that
2612 returns a pointer and takes at least one argument of an integer or
2614 It indicates that the returned pointer is aligned on a boundary given
2615 by the function argument at @var{position}. Meaningful alignments are
2616 powers of 2 greater than one. GCC uses this information to improve
2617 pointer alignment analysis.
2619 The function parameter denoting the allocated alignment is specified by
2620 one constant integer argument whose number is the argument of the attribute.
2621 Argument numbering starts at one.
2626 void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1)));
2630 declares that @code{my_memalign} returns memory with minimum alignment
2631 given by parameter 1.
2633 @item alloc_size (@var{position})
2634 @itemx alloc_size (@var{position-1}, @var{position-2})
2635 @cindex @code{alloc_size} function attribute
2636 The @code{alloc_size} attribute may be applied to a function that
2637 returns a pointer and takes at least one argument of an integer or
2639 It indicates that the returned pointer points to memory whose size is
2640 given by the function argument at @var{position-1}, or by the product
2641 of the arguments at @var{position-1} and @var{position-2}. Meaningful
2642 sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this
2643 information to improve the results of @code{__builtin_object_size}.
2645 The function parameter(s) denoting the allocated size are specified by
2646 one or two integer arguments supplied to the attribute. The allocated size
2647 is either the value of the single function argument specified or the product
2648 of the two function arguments specified. Argument numbering starts at
2649 one for ordinary functions, and at two for C++ non-static member functions.
2654 void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2)));
2655 void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2)));
2659 declares that @code{my_calloc} returns memory of the size given by
2660 the product of parameter 1 and 2 and that @code{my_realloc} returns memory
2661 of the size given by parameter 2.
2664 @cindex @code{always_inline} function attribute
2665 Generally, functions are not inlined unless optimization is specified.
2666 For functions declared inline, this attribute inlines the function
2667 independent of any restrictions that otherwise apply to inlining.
2668 Failure to inline such a function is diagnosed as an error.
2669 Note that if such a function is called indirectly the compiler may
2670 or may not inline it depending on optimization level and a failure
2671 to inline an indirect call may or may not be diagnosed.
2674 @cindex @code{artificial} function attribute
2675 This attribute is useful for small inline wrappers that if possible
2676 should appear during debugging as a unit. Depending on the debug
2677 info format it either means marking the function as artificial
2678 or using the caller location for all instructions within the inlined
2681 @item assume_aligned (@var{alignment})
2682 @itemx assume_aligned (@var{alignment}, @var{offset})
2683 @cindex @code{assume_aligned} function attribute
2684 The @code{assume_aligned} attribute may be applied to a function that
2685 returns a pointer. It indicates that the returned pointer is aligned
2686 on a boundary given by @var{alignment}. If the attribute has two
2687 arguments, the second argument is misalignment @var{offset}. Meaningful
2688 values of @var{alignment} are powers of 2 greater than one. Meaningful
2689 values of @var{offset} are greater than zero and less than @var{alignment}.
2694 void* my_alloc1 (size_t) __attribute__((assume_aligned (16)));
2695 void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8)));
2699 declares that @code{my_alloc1} returns 16-byte aligned pointers and
2700 that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
2704 @cindex @code{cold} function attribute
2705 The @code{cold} attribute on functions is used to inform the compiler that
2706 the function is unlikely to be executed. The function is optimized for
2707 size rather than speed and on many targets it is placed into a special
2708 subsection of the text section so all cold functions appear close together,
2709 improving code locality of non-cold parts of program. The paths leading
2710 to calls of cold functions within code are marked as unlikely by the branch
2711 prediction mechanism. It is thus useful to mark functions used to handle
2712 unlikely conditions, such as @code{perror}, as cold to improve optimization
2713 of hot functions that do call marked functions in rare occasions.
2715 When profile feedback is available, via @option{-fprofile-use}, cold functions
2716 are automatically detected and this attribute is ignored.
2719 @cindex @code{const} function attribute
2720 @cindex functions that have no side effects
2721 Calls to functions whose return value is not affected by changes to
2722 the observable state of the program and that have no observable effects
2723 on such state other than to return a value may lend themselves to
2724 optimizations such as common subexpression elimination. Declaring such
2725 functions with the @code{const} attribute allows GCC to avoid emitting
2726 some calls in repeated invocations of the function with the same argument
2732 int square (int) __attribute__ ((const));
2736 tells GCC that subsequent calls to function @code{square} with the same
2737 argument value can be replaced by the result of the first call regardless
2738 of the statements in between.
2740 The @code{const} attribute prohibits a function from reading objects
2741 that affect its return value between successive invocations. However,
2742 functions declared with the attribute can safely read objects that do
2743 not change their return value, such as non-volatile constants.
2745 The @code{const} attribute imposes greater restrictions on a function's
2746 definition than the similar @code{pure} attribute. Declaring the same
2747 function with both the @code{const} and the @code{pure} attribute is
2748 diagnosed. Because a const function cannot have any observable side
2749 effects it does not make sense for it to return @code{void}. Declaring
2750 such a function is diagnosed.
2752 @cindex pointer arguments
2753 Note that a function that has pointer arguments and examines the data
2754 pointed to must @emph{not} be declared @code{const} if the pointed-to
2755 data might change between successive invocations of the function. In
2756 general, since a function cannot distinguish data that might change
2757 from data that cannot, const functions should never take pointer or,
2758 in C++, reference arguments. Likewise, a function that calls a non-const
2759 function usually must not be const itself.
2763 @itemx constructor (@var{priority})
2764 @itemx destructor (@var{priority})
2765 @cindex @code{constructor} function attribute
2766 @cindex @code{destructor} function attribute
2767 The @code{constructor} attribute causes the function to be called
2768 automatically before execution enters @code{main ()}. Similarly, the
2769 @code{destructor} attribute causes the function to be called
2770 automatically after @code{main ()} completes or @code{exit ()} is
2771 called. Functions with these attributes are useful for
2772 initializing data that is used implicitly during the execution of
2775 On some targets the attributes also accept an integer argument to
2776 specify a priority to control the order in which constructor and
2777 destructor functions are run. A constructor
2778 with a smaller priority number runs before a constructor with a larger
2779 priority number; the opposite relationship holds for destructors. So,
2780 if you have a constructor that allocates a resource and a destructor
2781 that deallocates the same resource, both functions typically have the
2782 same priority. The priorities for constructor and destructor
2783 functions are the same as those specified for namespace-scope C++
2784 objects (@pxref{C++ Attributes}). However, at present, the order in which
2785 constructors for C++ objects with static storage duration and functions
2786 decorated with attribute @code{constructor} are invoked is unspecified.
2787 In mixed declarations, attribute @code{init_priority} can be used to
2788 impose a specific ordering.
2790 Using the argument forms of the @code{constructor} and @code{destructor}
2791 attributes on targets where the feature is not supported is rejected with
2795 @itemx copy (@var{function})
2796 @cindex @code{copy} function attribute
2797 The @code{copy} attribute applies the set of attributes with which
2798 @var{function} has been declared to the declaration of the function
2799 to which the attribute is applied. The attribute is designed for
2800 libraries that define aliases or function resolvers that are expected
2801 to specify the same set of attributes as their targets. The @code{copy}
2802 attribute can be used with functions, variables, or types. However,
2803 the kind of symbol to which the attribute is applied (either function
2804 or variable) must match the kind of symbol to which the argument refers.
2805 The @code{copy} attribute copies only syntactic and semantic attributes
2806 but not attributes that affect a symbol's linkage or visibility such as
2807 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
2808 and @code{target_clones} attribute are also not copied.
2809 @xref{Common Type Attributes}.
2810 @xref{Common Variable Attributes}.
2812 For example, the @var{StrongAlias} macro below makes use of the @code{alias}
2813 and @code{copy} attributes to define an alias named @var{alloc} for function
2814 @var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and
2815 @var{nothrow}. Thanks to the @code{__typeof__} operator the alias has
2816 the same type as the target function. As a result of the @code{copy}
2817 attribute the alias also shares the same attributes as the target.
2820 #define StrongAlias(TargetFunc, AliasDecl) \
2821 extern __typeof__ (TargetFunc) AliasDecl \
2822 __attribute__ ((alias (#TargetFunc), copy (TargetFunc)));
2824 extern __attribute__ ((alloc_size (1), malloc, nothrow))
2825 void* allocate (size_t);
2826 StrongAlias (allocate, alloc);
2830 @itemx deprecated (@var{msg})
2831 @cindex @code{deprecated} function attribute
2832 The @code{deprecated} attribute results in a warning if the function
2833 is used anywhere in the source file. This is useful when identifying
2834 functions that are expected to be removed in a future version of a
2835 program. The warning also includes the location of the declaration
2836 of the deprecated function, to enable users to easily find further
2837 information about why the function is deprecated, or what they should
2838 do instead. Note that the warnings only occurs for uses:
2841 int old_fn () __attribute__ ((deprecated));
2843 int (*fn_ptr)() = old_fn;
2847 results in a warning on line 3 but not line 2. The optional @var{msg}
2848 argument, which must be a string, is printed in the warning if
2851 The @code{deprecated} attribute can also be used for variables and
2852 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
2854 The message attached to the attribute is affected by the setting of
2855 the @option{-fmessage-length} option.
2857 @item error ("@var{message}")
2858 @itemx warning ("@var{message}")
2859 @cindex @code{error} function attribute
2860 @cindex @code{warning} function attribute
2861 If the @code{error} or @code{warning} attribute
2862 is used on a function declaration and a call to such a function
2863 is not eliminated through dead code elimination or other optimizations,
2864 an error or warning (respectively) that includes @var{message} is diagnosed.
2866 for compile-time checking, especially together with @code{__builtin_constant_p}
2867 and inline functions where checking the inline function arguments is not
2868 possible through @code{extern char [(condition) ? 1 : -1];} tricks.
2870 While it is possible to leave the function undefined and thus invoke
2871 a link failure (to define the function with
2872 a message in @code{.gnu.warning*} section),
2873 when using these attributes the problem is diagnosed
2874 earlier and with exact location of the call even in presence of inline
2875 functions or when not emitting debugging information.
2877 @item externally_visible
2878 @cindex @code{externally_visible} function attribute
2879 This attribute, attached to a global variable or function, nullifies
2880 the effect of the @option{-fwhole-program} command-line option, so the
2881 object remains visible outside the current compilation unit.
2883 If @option{-fwhole-program} is used together with @option{-flto} and
2884 @command{gold} is used as the linker plugin,
2885 @code{externally_visible} attributes are automatically added to functions
2886 (not variable yet due to a current @command{gold} issue)
2887 that are accessed outside of LTO objects according to resolution file
2888 produced by @command{gold}.
2889 For other linkers that cannot generate resolution file,
2890 explicit @code{externally_visible} attributes are still necessary.
2893 @cindex @code{flatten} function attribute
2894 Generally, inlining into a function is limited. For a function marked with
2895 this attribute, every call inside this function is inlined, if possible.
2896 Functions declared with attribute @code{noinline} and similar are not
2897 inlined. Whether the function itself is considered for inlining depends
2898 on its size and the current inlining parameters.
2900 @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
2901 @cindex @code{format} function attribute
2902 @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
2904 The @code{format} attribute specifies that a function takes @code{printf},
2905 @code{scanf}, @code{strftime} or @code{strfmon} style arguments that
2906 should be type-checked against a format string. For example, the
2911 my_printf (void *my_object, const char *my_format, ...)
2912 __attribute__ ((format (printf, 2, 3)));
2916 causes the compiler to check the arguments in calls to @code{my_printf}
2917 for consistency with the @code{printf} style format string argument
2920 The parameter @var{archetype} determines how the format string is
2921 interpreted, and should be @code{printf}, @code{scanf}, @code{strftime},
2922 @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or
2923 @code{strfmon}. (You can also use @code{__printf__},
2924 @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On
2925 MinGW targets, @code{ms_printf}, @code{ms_scanf}, and
2926 @code{ms_strftime} are also present.
2927 @var{archetype} values such as @code{printf} refer to the formats accepted
2928 by the system's C runtime library,
2929 while values prefixed with @samp{gnu_} always refer
2930 to the formats accepted by the GNU C Library. On Microsoft Windows
2931 targets, values prefixed with @samp{ms_} refer to the formats accepted by the
2932 @file{msvcrt.dll} library.
2933 The parameter @var{string-index}
2934 specifies which argument is the format string argument (starting
2935 from 1), while @var{first-to-check} is the number of the first
2936 argument to check against the format string. For functions
2937 where the arguments are not available to be checked (such as
2938 @code{vprintf}), specify the third parameter as zero. In this case the
2939 compiler only checks the format string for consistency. For
2940 @code{strftime} formats, the third parameter is required to be zero.
2941 Since non-static C++ methods have an implicit @code{this} argument, the
2942 arguments of such methods should be counted from two, not one, when
2943 giving values for @var{string-index} and @var{first-to-check}.
2945 In the example above, the format string (@code{my_format}) is the second
2946 argument of the function @code{my_print}, and the arguments to check
2947 start with the third argument, so the correct parameters for the format
2948 attribute are 2 and 3.
2950 @opindex ffreestanding
2951 @opindex fno-builtin
2952 The @code{format} attribute allows you to identify your own functions
2953 that take format strings as arguments, so that GCC can check the
2954 calls to these functions for errors. The compiler always (unless
2955 @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
2956 for the standard library functions @code{printf}, @code{fprintf},
2957 @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
2958 @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
2959 warnings are requested (using @option{-Wformat}), so there is no need to
2960 modify the header file @file{stdio.h}. In C99 mode, the functions
2961 @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
2962 @code{vsscanf} are also checked. Except in strictly conforming C
2963 standard modes, the X/Open function @code{strfmon} is also checked as
2964 are @code{printf_unlocked} and @code{fprintf_unlocked}.
2965 @xref{C Dialect Options,,Options Controlling C Dialect}.
2967 For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is
2968 recognized in the same context. Declarations including these format attributes
2969 are parsed for correct syntax, however the result of checking of such format
2970 strings is not yet defined, and is not carried out by this version of the
2973 The target may also provide additional types of format checks.
2974 @xref{Target Format Checks,,Format Checks Specific to Particular
2977 @item format_arg (@var{string-index})
2978 @cindex @code{format_arg} function attribute
2979 @opindex Wformat-nonliteral
2980 The @code{format_arg} attribute specifies that a function takes one or
2981 more format strings for a @code{printf}, @code{scanf}, @code{strftime} or
2982 @code{strfmon} style function and modifies it (for example, to translate
2983 it into another language), so the result can be passed to a
2984 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
2985 function (with the remaining arguments to the format function the same
2986 as they would have been for the unmodified string). Multiple
2987 @code{format_arg} attributes may be applied to the same function, each
2988 designating a distinct parameter as a format string. For example, the
2993 my_dgettext (char *my_domain, const char *my_format)
2994 __attribute__ ((format_arg (2)));
2998 causes the compiler to check the arguments in calls to a @code{printf},
2999 @code{scanf}, @code{strftime} or @code{strfmon} type function, whose
3000 format string argument is a call to the @code{my_dgettext} function, for
3001 consistency with the format string argument @code{my_format}. If the
3002 @code{format_arg} attribute had not been specified, all the compiler
3003 could tell in such calls to format functions would be that the format
3004 string argument is not constant; this would generate a warning when
3005 @option{-Wformat-nonliteral} is used, but the calls could not be checked
3006 without the attribute.
3008 In calls to a function declared with more than one @code{format_arg}
3009 attribute, each with a distinct argument value, the corresponding
3010 actual function arguments are checked against all format strings
3011 designated by the attributes. This capability is designed to support
3012 the GNU @code{ngettext} family of functions.
3014 The parameter @var{string-index} specifies which argument is the format
3015 string argument (starting from one). Since non-static C++ methods have
3016 an implicit @code{this} argument, the arguments of such methods should
3017 be counted from two.
3019 The @code{format_arg} attribute allows you to identify your own
3020 functions that modify format strings, so that GCC can check the
3021 calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
3022 type function whose operands are a call to one of your own function.
3023 The compiler always treats @code{gettext}, @code{dgettext}, and
3024 @code{dcgettext} in this manner except when strict ISO C support is
3025 requested by @option{-ansi} or an appropriate @option{-std} option, or
3026 @option{-ffreestanding} or @option{-fno-builtin}
3027 is used. @xref{C Dialect Options,,Options
3028 Controlling C Dialect}.
3030 For Objective-C dialects, the @code{format-arg} attribute may refer to an
3031 @code{NSString} reference for compatibility with the @code{format} attribute
3034 The target may also allow additional types in @code{format-arg} attributes.
3035 @xref{Target Format Checks,,Format Checks Specific to Particular
3039 @cindex @code{gnu_inline} function attribute
3040 This attribute should be used with a function that is also declared
3041 with the @code{inline} keyword. It directs GCC to treat the function
3042 as if it were defined in gnu90 mode even when compiling in C99 or
3045 If the function is declared @code{extern}, then this definition of the
3046 function is used only for inlining. In no case is the function
3047 compiled as a standalone function, not even if you take its address
3048 explicitly. Such an address becomes an external reference, as if you
3049 had only declared the function, and had not defined it. This has
3050 almost the effect of a macro. The way to use this is to put a
3051 function definition in a header file with this attribute, and put
3052 another copy of the function, without @code{extern}, in a library
3053 file. The definition in the header file causes most calls to the
3054 function to be inlined. If any uses of the function remain, they
3055 refer to the single copy in the library. Note that the two
3056 definitions of the functions need not be precisely the same, although
3057 if they do not have the same effect your program may behave oddly.
3059 In C, if the function is neither @code{extern} nor @code{static}, then
3060 the function is compiled as a standalone function, as well as being
3061 inlined where possible.
3063 This is how GCC traditionally handled functions declared
3064 @code{inline}. Since ISO C99 specifies a different semantics for
3065 @code{inline}, this function attribute is provided as a transition
3066 measure and as a useful feature in its own right. This attribute is
3067 available in GCC 4.1.3 and later. It is available if either of the
3068 preprocessor macros @code{__GNUC_GNU_INLINE__} or
3069 @code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
3070 Function is As Fast As a Macro}.
3072 In C++, this attribute does not depend on @code{extern} in any way,
3073 but it still requires the @code{inline} keyword to enable its special
3077 @cindex @code{hot} function attribute
3078 The @code{hot} attribute on a function is used to inform the compiler that
3079 the function is a hot spot of the compiled program. The function is
3080 optimized more aggressively and on many targets it is placed into a special
3081 subsection of the text section so all hot functions appear close together,
3084 When profile feedback is available, via @option{-fprofile-use}, hot functions
3085 are automatically detected and this attribute is ignored.
3087 @item ifunc ("@var{resolver}")
3088 @cindex @code{ifunc} function attribute
3089 @cindex indirect functions
3090 @cindex functions that are dynamically resolved
3091 The @code{ifunc} attribute is used to mark a function as an indirect
3092 function using the STT_GNU_IFUNC symbol type extension to the ELF
3093 standard. This allows the resolution of the symbol value to be
3094 determined dynamically at load time, and an optimized version of the
3095 routine to be selected for the particular processor or other system
3096 characteristics determined then. To use this attribute, first define
3097 the implementation functions available, and a resolver function that
3098 returns a pointer to the selected implementation function. The
3099 implementation functions' declarations must match the API of the
3100 function being implemented. The resolver should be declared to
3101 be a function taking no arguments and returning a pointer to
3102 a function of the same type as the implementation. For example:
3105 void *my_memcpy (void *dst, const void *src, size_t len)
3111 static void * (*resolve_memcpy (void))(void *, const void *, size_t)
3113 return my_memcpy; // we will just always select this routine
3118 The exported header file declaring the function the user calls would
3122 extern void *memcpy (void *, const void *, size_t);
3126 allowing the user to call @code{memcpy} as a regular function, unaware of
3127 the actual implementation. Finally, the indirect function needs to be
3128 defined in the same translation unit as the resolver function:
3131 void *memcpy (void *, const void *, size_t)
3132 __attribute__ ((ifunc ("resolve_memcpy")));
3135 In C++, the @code{ifunc} attribute takes a string that is the mangled name
3136 of the resolver function. A C++ resolver for a non-static member function
3137 of class @code{C} should be declared to return a pointer to a non-member
3138 function taking pointer to @code{C} as the first argument, followed by
3139 the same arguments as of the implementation function. G++ checks
3140 the signatures of the two functions and issues
3141 a @option{-Wattribute-alias} warning for mismatches. To suppress a warning
3142 for the necessary cast from a pointer to the implementation member function
3143 to the type of the corresponding non-member function use
3144 the @option{-Wno-pmf-conversions} option. For example:
3150 int debug_impl (int);
3151 int optimized_impl (int);
3153 typedef int Func (S*, int);
3155 static Func* resolver ();
3158 int interface (int);
3161 int S::debug_impl (int) @{ /* @r{@dots{}} */ @}
3162 int S::optimized_impl (int) @{ /* @r{@dots{}} */ @}
3164 S::Func* S::resolver ()
3166 int (S::*pimpl) (int)
3167 = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl;
3169 // Cast triggers -Wno-pmf-conversions.
3170 return reinterpret_cast<Func*>(pimpl);
3173 int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv")));
3176 Indirect functions cannot be weak. Binutils version 2.20.1 or higher
3177 and GNU C Library version 2.11.1 are required to use this feature.
3180 @itemx interrupt_handler
3181 Many GCC back ends support attributes to indicate that a function is
3182 an interrupt handler, which tells the compiler to generate function
3183 entry and exit sequences that differ from those from regular
3184 functions. The exact syntax and behavior are target-specific;
3185 refer to the following subsections for details.
3188 @cindex @code{leaf} function attribute
3189 Calls to external functions with this attribute must return to the
3190 current compilation unit only by return or by exception handling. In
3191 particular, a leaf function is not allowed to invoke callback functions
3192 passed to it from the current compilation unit, directly call functions
3193 exported by the unit, or @code{longjmp} into the unit. Leaf functions
3194 might still call functions from other compilation units and thus they
3195 are not necessarily leaf in the sense that they contain no function
3198 The attribute is intended for library functions to improve dataflow
3199 analysis. The compiler takes the hint that any data not escaping the
3200 current compilation unit cannot be used or modified by the leaf
3201 function. For example, the @code{sin} function is a leaf function, but
3202 @code{qsort} is not.
3204 Note that leaf functions might indirectly run a signal handler defined
3205 in the current compilation unit that uses static variables. Similarly,
3206 when lazy symbol resolution is in effect, leaf functions might invoke
3207 indirect functions whose resolver function or implementation function is
3208 defined in the current compilation unit and uses static variables. There
3209 is no standard-compliant way to write such a signal handler, resolver
3210 function, or implementation function, and the best that you can do is to
3211 remove the @code{leaf} attribute or mark all such static variables
3212 @code{volatile}. Lastly, for ELF-based systems that support symbol
3213 interposition, care should be taken that functions defined in the
3214 current compilation unit do not unexpectedly interpose other symbols
3215 based on the defined standards mode and defined feature test macros;
3216 otherwise an inadvertent callback would be added.
3218 The attribute has no effect on functions defined within the current
3219 compilation unit. This is to allow easy merging of multiple compilation
3220 units into one, for example, by using the link-time optimization. For
3221 this reason the attribute is not allowed on types to annotate indirect
3225 @cindex @code{malloc} function attribute
3226 @cindex functions that behave like malloc
3227 This tells the compiler that a function is @code{malloc}-like, i.e.,
3228 that the pointer @var{P} returned by the function cannot alias any
3229 other pointer valid when the function returns, and moreover no
3230 pointers to valid objects occur in any storage addressed by @var{P}.
3232 Using this attribute can improve optimization. Compiler predicts
3233 that a function with the attribute returns non-null in most cases.
3235 @code{malloc} and @code{calloc} have this property because they return
3236 a pointer to uninitialized or zeroed-out storage. However, functions
3237 like @code{realloc} do not have this property, as they can return a
3238 pointer to storage containing pointers.
3241 @cindex @code{no_icf} function attribute
3242 This function attribute prevents a functions from being merged with another
3243 semantically equivalent function.
3245 @item no_instrument_function
3246 @cindex @code{no_instrument_function} function attribute
3247 @opindex finstrument-functions
3250 If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are
3251 given, profiling function calls are
3252 generated at entry and exit of most user-compiled functions.
3253 Functions with this attribute are not so instrumented.
3255 @item no_profile_instrument_function
3256 @cindex @code{no_profile_instrument_function} function attribute
3257 The @code{no_profile_instrument_function} attribute on functions is used
3258 to inform the compiler that it should not process any profile feedback based
3259 optimization code instrumentation.
3262 @cindex @code{no_reorder} function attribute
3263 Do not reorder functions or variables marked @code{no_reorder}
3264 against each other or top level assembler statements the executable.
3265 The actual order in the program will depend on the linker command
3266 line. Static variables marked like this are also not removed.
3267 This has a similar effect
3268 as the @option{-fno-toplevel-reorder} option, but only applies to the
3271 @item no_sanitize ("@var{sanitize_option}")
3272 @cindex @code{no_sanitize} function attribute
3273 The @code{no_sanitize} attribute on functions is used
3274 to inform the compiler that it should not do sanitization of any option
3275 mentioned in @var{sanitize_option}. A list of values acceptable by
3276 the @option{-fsanitize} option can be provided.
3279 void __attribute__ ((no_sanitize ("alignment", "object-size")))
3280 f () @{ /* @r{Do something.} */; @}
3281 void __attribute__ ((no_sanitize ("alignment,object-size")))
3282 g () @{ /* @r{Do something.} */; @}
3285 @item no_sanitize_address
3286 @itemx no_address_safety_analysis
3287 @cindex @code{no_sanitize_address} function attribute
3288 The @code{no_sanitize_address} attribute on functions is used
3289 to inform the compiler that it should not instrument memory accesses
3290 in the function when compiling with the @option{-fsanitize=address} option.
3291 The @code{no_address_safety_analysis} is a deprecated alias of the
3292 @code{no_sanitize_address} attribute, new code should use
3293 @code{no_sanitize_address}.
3295 @item no_sanitize_thread
3296 @cindex @code{no_sanitize_thread} function attribute
3297 The @code{no_sanitize_thread} attribute on functions is used
3298 to inform the compiler that it should not instrument memory accesses
3299 in the function when compiling with the @option{-fsanitize=thread} option.
3301 @item no_sanitize_undefined
3302 @cindex @code{no_sanitize_undefined} function attribute
3303 The @code{no_sanitize_undefined} attribute on functions is used
3304 to inform the compiler that it should not check for undefined behavior
3305 in the function when compiling with the @option{-fsanitize=undefined} option.
3307 @item no_split_stack
3308 @cindex @code{no_split_stack} function attribute
3309 @opindex fsplit-stack
3310 If @option{-fsplit-stack} is given, functions have a small
3311 prologue which decides whether to split the stack. Functions with the
3312 @code{no_split_stack} attribute do not have that prologue, and thus
3313 may run with only a small amount of stack space available.
3315 @item no_stack_limit
3316 @cindex @code{no_stack_limit} function attribute
3317 This attribute locally overrides the @option{-fstack-limit-register}
3318 and @option{-fstack-limit-symbol} command-line options; it has the effect
3319 of disabling stack limit checking in the function it applies to.
3322 @cindex @code{noclone} function attribute
3323 This function attribute prevents a function from being considered for
3324 cloning---a mechanism that produces specialized copies of functions
3325 and which is (currently) performed by interprocedural constant
3329 @cindex @code{noinline} function attribute
3330 This function attribute prevents a function from being considered for
3332 @c Don't enumerate the optimizations by name here; we try to be
3333 @c future-compatible with this mechanism.
3334 If the function does not have side effects, there are optimizations
3335 other than inlining that cause function calls to be optimized away,
3336 although the function call is live. To keep such calls from being
3343 (@pxref{Extended Asm}) in the called function, to serve as a special
3347 @cindex @code{noipa} function attribute
3348 Disable interprocedural optimizations between the function with this
3349 attribute and its callers, as if the body of the function is not available
3350 when optimizing callers and the callers are unavailable when optimizing
3351 the body. This attribute implies @code{noinline}, @code{noclone} and
3352 @code{no_icf} attributes. However, this attribute is not equivalent
3353 to a combination of other attributes, because its purpose is to suppress
3354 existing and future optimizations employing interprocedural analysis,
3355 including those that do not have an attribute suitable for disabling
3356 them individually. This attribute is supported mainly for the purpose
3357 of testing the compiler.
3360 @itemx nonnull (@var{arg-index}, @dots{})
3361 @cindex @code{nonnull} function attribute
3362 @cindex functions with non-null pointer arguments
3363 The @code{nonnull} attribute may be applied to a function that takes at
3364 least one argument of a pointer type. It indicates that the referenced
3365 arguments must be non-null pointers. For instance, the declaration:
3369 my_memcpy (void *dest, const void *src, size_t len)
3370 __attribute__((nonnull (1, 2)));
3374 causes the compiler to check that, in calls to @code{my_memcpy},
3375 arguments @var{dest} and @var{src} are non-null. If the compiler
3376 determines that a null pointer is passed in an argument slot marked
3377 as non-null, and the @option{-Wnonnull} option is enabled, a warning
3378 is issued. @xref{Warning Options}. Unless disabled by
3379 the @option{-fno-delete-null-pointer-checks} option the compiler may
3380 also perform optimizations based on the knowledge that certain function
3381 arguments cannot be null. In addition,
3382 the @option{-fisolate-erroneous-paths-attribute} option can be specified
3383 to have GCC transform calls with null arguments to non-null functions
3384 into traps. @xref{Optimize Options}.
3386 If no @var{arg-index} is given to the @code{nonnull} attribute,
3387 all pointer arguments are marked as non-null. To illustrate, the
3388 following declaration is equivalent to the previous example:
3392 my_memcpy (void *dest, const void *src, size_t len)
3393 __attribute__((nonnull));
3397 @cindex @code{noplt} function attribute
3398 The @code{noplt} attribute is the counterpart to option @option{-fno-plt}.
3399 Calls to functions marked with this attribute in position-independent code
3404 /* Externally defined function foo. */
3405 int foo () __attribute__ ((noplt));
3408 main (/* @r{@dots{}} */)
3417 The @code{noplt} attribute on function @code{foo}
3418 tells the compiler to assume that
3419 the function @code{foo} is externally defined and that the call to
3420 @code{foo} must avoid the PLT
3421 in position-independent code.
3423 In position-dependent code, a few targets also convert calls to
3424 functions that are marked to not use the PLT to use the GOT instead.
3427 @cindex @code{noreturn} function attribute
3428 @cindex functions that never return
3429 A few standard library functions, such as @code{abort} and @code{exit},
3430 cannot return. GCC knows this automatically. Some programs define
3431 their own functions that never return. You can declare them
3432 @code{noreturn} to tell the compiler this fact. For example,
3436 void fatal () __attribute__ ((noreturn));
3439 fatal (/* @r{@dots{}} */)
3441 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
3447 The @code{noreturn} keyword tells the compiler to assume that
3448 @code{fatal} cannot return. It can then optimize without regard to what
3449 would happen if @code{fatal} ever did return. This makes slightly
3450 better code. More importantly, it helps avoid spurious warnings of
3451 uninitialized variables.
3453 The @code{noreturn} keyword does not affect the exceptional path when that
3454 applies: a @code{noreturn}-marked function may still return to the caller
3455 by throwing an exception or calling @code{longjmp}.
3457 In order to preserve backtraces, GCC will never turn calls to
3458 @code{noreturn} functions into tail calls.
3460 Do not assume that registers saved by the calling function are
3461 restored before calling the @code{noreturn} function.
3463 It does not make sense for a @code{noreturn} function to have a return
3464 type other than @code{void}.
3467 @cindex @code{nothrow} function attribute
3468 The @code{nothrow} attribute is used to inform the compiler that a
3469 function cannot throw an exception. For example, most functions in
3470 the standard C library can be guaranteed not to throw an exception
3471 with the notable exceptions of @code{qsort} and @code{bsearch} that
3472 take function pointer arguments.
3474 @item optimize (@var{level}, @dots{})
3475 @item optimize (@var{string}, @dots{})
3476 @cindex @code{optimize} function attribute
3477 The @code{optimize} attribute is used to specify that a function is to
3478 be compiled with different optimization options than specified on the
3479 command line. Valid arguments are constant non-negative integers and
3480 strings. Each numeric argument specifies an optimization @var{level}.
3481 Each @var{string} argument consists of one or more comma-separated
3482 substrings. Each substring that begins with the letter @code{O} refers
3483 to an optimization option such as @option{-O0} or @option{-Os}. Other
3484 substrings are taken as suffixes to the @code{-f} prefix jointly
3485 forming the name of an optimization option. @xref{Optimize Options}.
3487 @samp{#pragma GCC optimize} can be used to set optimization options
3488 for more than one function. @xref{Function Specific Option Pragmas},
3489 for details about the pragma.
3491 Providing multiple strings as arguments separated by commas to specify
3492 multiple options is equivalent to separating the option suffixes with
3493 a comma (@samp{,}) within a single string. Spaces are not permitted
3496 Not every optimization option that starts with the @var{-f} prefix
3497 specified by the attribute necessarily has an effect on the function.
3498 The @code{optimize} attribute should be used for debugging purposes only.
3499 It is not suitable in production code.
3501 @item patchable_function_entry
3502 @cindex @code{patchable_function_entry} function attribute
3503 @cindex extra NOP instructions at the function entry point
3504 In case the target's text segment can be made writable at run time by
3505 any means, padding the function entry with a number of NOPs can be
3506 used to provide a universal tool for instrumentation.
3508 The @code{patchable_function_entry} function attribute can be used to
3509 change the number of NOPs to any desired value. The two-value syntax
3510 is the same as for the command-line switch
3511 @option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with
3512 the function entry point before the @var{M}th NOP instruction.
3513 @var{M} defaults to 0 if omitted e.g.@: function entry point is before
3516 If patchable function entries are enabled globally using the command-line
3517 option @option{-fpatchable-function-entry=N,M}, then you must disable
3518 instrumentation on all functions that are part of the instrumentation
3519 framework with the attribute @code{patchable_function_entry (0)}
3520 to prevent recursion.
3523 @cindex @code{pure} function attribute
3524 @cindex functions that have no side effects
3526 Calls to functions that have no observable effects on the state of
3527 the program other than to return a value may lend themselves to optimizations
3528 such as common subexpression elimination. Declaring such functions with
3529 the @code{pure} attribute allows GCC to avoid emitting some calls in repeated
3530 invocations of the function with the same argument values.
3532 The @code{pure} attribute prohibits a function from modifying the state
3533 of the program that is observable by means other than inspecting
3534 the function's return value. However, functions declared with the @code{pure}
3535 attribute can safely read any non-volatile objects, and modify the value of
3536 objects in a way that does not affect their return value or the observable
3537 state of the program.
3542 int hash (char *) __attribute__ ((pure));
3546 tells GCC that subsequent calls to the function @code{hash} with the same
3547 string can be replaced by the result of the first call provided the state
3548 of the program observable by @code{hash}, including the contents of the array
3549 itself, does not change in between. Even though @code{hash} takes a non-const
3550 pointer argument it must not modify the array it points to, or any other object
3551 whose value the rest of the program may depend on. However, the caller may
3552 safely change the contents of the array between successive calls to
3553 the function (doing so disables the optimization). The restriction also
3554 applies to member objects referenced by the @code{this} pointer in C++
3555 non-static member functions.
3557 Some common examples of pure functions are @code{strlen} or @code{memcmp}.
3558 Interesting non-pure functions are functions with infinite loops or those
3559 depending on volatile memory or other system resource, that may change between
3560 consecutive calls (such as the standard C @code{feof} function in
3561 a multithreading environment).
3563 The @code{pure} attribute imposes similar but looser restrictions on
3564 a function's definition than the @code{const} attribute: @code{pure}
3565 allows the function to read any non-volatile memory, even if it changes
3566 in between successive invocations of the function. Declaring the same
3567 function with both the @code{pure} and the @code{const} attribute is
3568 diagnosed. Because a pure function cannot have any observable side
3569 effects it does not make sense for such a function to return @code{void}.
3570 Declaring such a function is diagnosed.
3572 @item returns_nonnull
3573 @cindex @code{returns_nonnull} function attribute
3574 The @code{returns_nonnull} attribute specifies that the function
3575 return value should be a non-null pointer. For instance, the declaration:
3579 mymalloc (size_t len) __attribute__((returns_nonnull));
3583 lets the compiler optimize callers based on the knowledge
3584 that the return value will never be null.
3587 @cindex @code{returns_twice} function attribute
3588 @cindex functions that return more than once
3589 The @code{returns_twice} attribute tells the compiler that a function may
3590 return more than one time. The compiler ensures that all registers
3591 are dead before calling such a function and emits a warning about
3592 the variables that may be clobbered after the second return from the
3593 function. Examples of such functions are @code{setjmp} and @code{vfork}.
3594 The @code{longjmp}-like counterpart of such function, if any, might need
3595 to be marked with the @code{noreturn} attribute.
3597 @item section ("@var{section-name}")
3598 @cindex @code{section} function attribute
3599 @cindex functions in arbitrary sections
3600 Normally, the compiler places the code it generates in the @code{text} section.
3601 Sometimes, however, you need additional sections, or you need certain
3602 particular functions to appear in special sections. The @code{section}
3603 attribute specifies that a function lives in a particular section.
3604 For example, the declaration:
3607 extern void foobar (void) __attribute__ ((section ("bar")));
3611 puts the function @code{foobar} in the @code{bar} section.
3613 Some file formats do not support arbitrary sections so the @code{section}
3614 attribute is not available on all platforms.
3615 If you need to map the entire contents of a module to a particular
3616 section, consider using the facilities of the linker instead.
3619 @itemx sentinel (@var{position})
3620 @cindex @code{sentinel} function attribute
3621 This function attribute indicates that an argument in a call to the function
3622 is expected to be an explicit @code{NULL}. The attribute is only valid on
3623 variadic functions. By default, the sentinel is expected to be the last
3624 argument of the function call. If the optional @var{position} argument
3625 is specified to the attribute, the sentinel must be located at
3626 @var{position} counting backwards from the end of the argument list.
3629 __attribute__ ((sentinel))
3631 __attribute__ ((sentinel(0)))
3634 The attribute is automatically set with a position of 0 for the built-in
3635 functions @code{execl} and @code{execlp}. The built-in function
3636 @code{execle} has the attribute set with a position of 1.
3638 A valid @code{NULL} in this context is defined as zero with any object
3639 pointer type. If your system defines the @code{NULL} macro with
3640 an integer type then you need to add an explicit cast. During
3641 installation GCC replaces the system @code{<stddef.h>} header with
3642 a copy that redefines NULL appropriately.
3644 The warnings for missing or incorrect sentinels are enabled with
3648 @itemx simd("@var{mask}")
3649 @cindex @code{simd} function attribute
3650 This attribute enables creation of one or more function versions that
3651 can process multiple arguments using SIMD instructions from a
3652 single invocation. Specifying this attribute allows compiler to
3653 assume that such versions are available at link time (provided
3654 in the same or another translation unit). Generated versions are
3655 target-dependent and described in the corresponding Vector ABI document. For
3656 x86_64 target this document can be found
3657 @w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}.
3659 The optional argument @var{mask} may have the value
3660 @code{notinbranch} or @code{inbranch},
3661 and instructs the compiler to generate non-masked or masked
3662 clones correspondingly. By default, all clones are generated.
3664 If the attribute is specified and @code{#pragma omp declare simd} is
3665 present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd}
3666 switch is specified, then the attribute is ignored.
3669 @cindex @code{stack_protect} function attribute
3670 This attribute adds stack protection code to the function if
3671 flags @option{-fstack-protector}, @option{-fstack-protector-strong}
3672 or @option{-fstack-protector-explicit} are set.
3674 @item target (@var{string}, @dots{})
3675 @cindex @code{target} function attribute
3676 Multiple target back ends implement the @code{target} attribute
3677 to specify that a function is to
3678 be compiled with different target options than specified on the
3679 command line. One or more strings can be provided as arguments.
3680 Each string consists of one or more comma-separated suffixes to
3681 the @code{-m} prefix jointly forming the name of a machine-dependent
3682 option. @xref{Submodel Options,,Machine-Dependent Options}.
3684 The @code{target} attribute can be used for instance to have a function
3685 compiled with a different ISA (instruction set architecture) than the
3686 default. @samp{#pragma GCC target} can be used to specify target-specific
3687 options for more than one function. @xref{Function Specific Option Pragmas},
3688 for details about the pragma.
3690 For instance, on an x86, you could declare one function with the
3691 @code{target("sse4.1,arch=core2")} attribute and another with
3692 @code{target("sse4a,arch=amdfam10")}. This is equivalent to
3693 compiling the first function with @option{-msse4.1} and
3694 @option{-march=core2} options, and the second function with
3695 @option{-msse4a} and @option{-march=amdfam10} options. It is up to you
3696 to make sure that a function is only invoked on a machine that
3697 supports the particular ISA it is compiled for (for example by using
3698 @code{cpuid} on x86 to determine what feature bits and architecture
3702 int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
3703 int sse3_func (void) __attribute__ ((__target__ ("sse3")));
3706 Providing multiple strings as arguments separated by commas to specify
3707 multiple options is equivalent to separating the option suffixes with
3708 a comma (@samp{,}) within a single string. Spaces are not permitted
3711 The options supported are specific to each target; refer to @ref{x86
3712 Function Attributes}, @ref{PowerPC Function Attributes},
3713 @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
3714 @ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
3717 @item symver ("@var{name2}@@@var{nodename}")
3718 On ELF targets this attribute creates a symbol version. The @var{name2} part
3719 of the parameter is the actual name of the symbol by which it will be
3720 externally referenced. The @code{nodename} portion should be the name of a
3721 node specified in the version script supplied to the linker when building a
3722 shared library. Versioned symbol must be defined and must be exported with
3726 __attribute__ ((__symver__ ("foo@@VERS_1"))) int
3732 Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
3735 It's an error to define multiple version of a given symbol. In such case
3736 an alias can be used.
3739 __attribute__ ((__symver__ ("foo@@VERS_2")))
3740 __attribute__ ((alias ("foo_v1")))
3741 int symver_foo_v1 (void);
3744 This example creates an alias of @code{foo_v1} with symbol name
3745 @code{symver_foo_v1} which will be version @code{VERS_2} of @code{foo}.
3747 Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
3748 addition to creating a symbol version (as if
3749 @code{"@var{name2}@@@var{nodename}"} was used) the version will be also used
3750 to resolve @var{name2} by the linker.
3752 @item target_clones (@var{options})
3753 @cindex @code{target_clones} function attribute
3754 The @code{target_clones} attribute is used to specify that a function
3755 be cloned into multiple versions compiled with different target options
3756 than specified on the command line. The supported options and restrictions
3757 are the same as for @code{target} attribute.
3759 For instance, on an x86, you could compile a function with
3760 @code{target_clones("sse4.1,avx")}. GCC creates two function clones,
3761 one compiled with @option{-msse4.1} and another with @option{-mavx}.
3763 On a PowerPC, you can compile a function with
3764 @code{target_clones("cpu=power9,default")}. GCC will create two
3765 function clones, one compiled with @option{-mcpu=power9} and another
3766 with the default options. GCC must be configured to use GLIBC 2.23 or
3767 newer in order to use the @code{target_clones} attribute.
3769 It also creates a resolver function (see
3770 the @code{ifunc} attribute above) that dynamically selects a clone
3771 suitable for current architecture. The resolver is created only if there
3772 is a usage of a function with @code{target_clones} attribute.
3774 Note that any subsequent call of a function without @code{target_clone}
3775 from a @code{target_clone} caller will not lead to copying
3776 (target clone) of the called function.
3777 If you want to enforce such behaviour,
3778 we recommend declaring the calling function with the @code{flatten} attribute?
3781 @cindex @code{unused} function attribute
3782 This attribute, attached to a function, means that the function is meant
3783 to be possibly unused. GCC does not produce a warning for this
3787 @cindex @code{used} function attribute
3788 This attribute, attached to a function, means that code must be emitted
3789 for the function even if it appears that the function is not referenced.
3790 This is useful, for example, when the function is referenced only in
3793 When applied to a member function of a C++ class template, the
3794 attribute also means that the function is instantiated if the
3795 class itself is instantiated.
3797 @item visibility ("@var{visibility_type}")
3798 @cindex @code{visibility} function attribute
3799 This attribute affects the linkage of the declaration to which it is attached.
3800 It can be applied to variables (@pxref{Common Variable Attributes}) and types
3801 (@pxref{Common Type Attributes}) as well as functions.
3803 There are four supported @var{visibility_type} values: default,
3804 hidden, protected or internal visibility.
3807 void __attribute__ ((visibility ("protected")))
3808 f () @{ /* @r{Do something.} */; @}
3809 int i __attribute__ ((visibility ("hidden")));
3812 The possible values of @var{visibility_type} correspond to the
3813 visibility settings in the ELF gABI.
3816 @c keep this list of visibilities in alphabetical order.
3819 Default visibility is the normal case for the object file format.
3820 This value is available for the visibility attribute to override other
3821 options that may change the assumed visibility of entities.
3823 On ELF, default visibility means that the declaration is visible to other
3824 modules and, in shared libraries, means that the declared entity may be
3827 On Darwin, default visibility means that the declaration is visible to
3830 Default visibility corresponds to ``external linkage'' in the language.
3833 Hidden visibility indicates that the entity declared has a new
3834 form of linkage, which we call ``hidden linkage''. Two
3835 declarations of an object with hidden linkage refer to the same object
3836 if they are in the same shared object.
3839 Internal visibility is like hidden visibility, but with additional
3840 processor specific semantics. Unless otherwise specified by the
3841 psABI, GCC defines internal visibility to mean that a function is
3842 @emph{never} called from another module. Compare this with hidden
3843 functions which, while they cannot be referenced directly by other
3844 modules, can be referenced indirectly via function pointers. By
3845 indicating that a function cannot be called from outside the module,
3846 GCC may for instance omit the load of a PIC register since it is known
3847 that the calling function loaded the correct value.
3850 Protected visibility is like default visibility except that it
3851 indicates that references within the defining module bind to the
3852 definition in that module. That is, the declared entity cannot be
3853 overridden by another module.
3857 All visibilities are supported on many, but not all, ELF targets
3858 (supported when the assembler supports the @samp{.visibility}
3859 pseudo-op). Default visibility is supported everywhere. Hidden
3860 visibility is supported on Darwin targets.
3862 The visibility attribute should be applied only to declarations that
3863 would otherwise have external linkage. The attribute should be applied
3864 consistently, so that the same entity should not be declared with
3865 different settings of the attribute.
3867 In C++, the visibility attribute applies to types as well as functions
3868 and objects, because in C++ types have linkage. A class must not have
3869 greater visibility than its non-static data member types and bases,
3870 and class members default to the visibility of their class. Also, a
3871 declaration without explicit visibility is limited to the visibility
3874 In C++, you can mark member functions and static member variables of a
3875 class with the visibility attribute. This is useful if you know a
3876 particular method or static member variable should only be used from
3877 one shared object; then you can mark it hidden while the rest of the
3878 class has default visibility. Care must be taken to avoid breaking
3879 the One Definition Rule; for example, it is usually not useful to mark
3880 an inline method as hidden without marking the whole class as hidden.
3882 A C++ namespace declaration can also have the visibility attribute.
3885 namespace nspace1 __attribute__ ((visibility ("protected")))
3886 @{ /* @r{Do something.} */; @}
3889 This attribute applies only to the particular namespace body, not to
3890 other definitions of the same namespace; it is equivalent to using
3891 @samp{#pragma GCC visibility} before and after the namespace
3892 definition (@pxref{Visibility Pragmas}).
3894 In C++, if a template argument has limited visibility, this
3895 restriction is implicitly propagated to the template instantiation.
3896 Otherwise, template instantiations and specializations default to the
3897 visibility of their template.
3899 If both the template and enclosing class have explicit visibility, the
3900 visibility from the template is used.
3902 @item warn_unused_result
3903 @cindex @code{warn_unused_result} function attribute
3904 The @code{warn_unused_result} attribute causes a warning to be emitted
3905 if a caller of the function with this attribute does not use its
3906 return value. This is useful for functions where not checking
3907 the result is either a security problem or always a bug, such as
3911 int fn () __attribute__ ((warn_unused_result));
3914 if (fn () < 0) return -1;
3921 results in warning on line 5.
3924 @cindex @code{weak} function attribute
3925 The @code{weak} attribute causes a declaration of an external symbol
3926 to be emitted as a weak symbol rather than a global. This is primarily
3927 useful in defining library functions that can be overridden in user code,
3928 though it can also be used with non-function declarations. The overriding
3929 symbol must have the same type as the weak symbol. In addition, if it
3930 designates a variable it must also have the same size and alignment as
3931 the weak symbol. Weak symbols are supported for ELF targets, and also
3932 for a.out targets when using the GNU assembler and linker.
3935 @itemx weakref ("@var{target}")
3936 @cindex @code{weakref} function attribute
3937 The @code{weakref} attribute marks a declaration as a weak reference.
3938 Without arguments, it should be accompanied by an @code{alias} attribute
3939 naming the target symbol. Alternatively, @var{target} may be given as
3940 an argument to @code{weakref} itself, naming the target definition of
3941 the alias. The @var{target} must have the same type as the declaration.
3942 In addition, if it designates a variable it must also have the same size
3943 and alignment as the declaration. In either form of the declaration
3944 @code{weakref} implicitly marks the declared symbol as @code{weak}. Without
3945 a @var{target} given as an argument to @code{weakref} or to @code{alias},
3946 @code{weakref} is equivalent to @code{weak} (in that case the declaration
3947 may be @code{extern}).
3950 /* Given the declaration: */
3951 extern int y (void);
3953 /* the following... */
3954 static int x (void) __attribute__ ((weakref ("y")));
3956 /* is equivalent to... */
3957 static int x (void) __attribute__ ((weakref, alias ("y")));
3959 /* or, alternatively, to... */
3960 static int x (void) __attribute__ ((weakref));
3961 static int x (void) __attribute__ ((alias ("y")));
3964 A weak reference is an alias that does not by itself require a
3965 definition to be given for the target symbol. If the target symbol is
3966 only referenced through weak references, then it becomes a @code{weak}
3967 undefined symbol. If it is directly referenced, however, then such
3968 strong references prevail, and a definition is required for the
3969 symbol, not necessarily in the same translation unit.
3971 The effect is equivalent to moving all references to the alias to a
3972 separate translation unit, renaming the alias to the aliased symbol,
3973 declaring it as weak, compiling the two separate translation units and
3974 performing a link with relocatable output (i.e.@: @code{ld -r}) on them.
3976 A declaration to which @code{weakref} is attached and that is associated
3977 with a named @code{target} must be @code{static}.
3981 @c This is the end of the target-independent attribute table
3983 @node AArch64 Function Attributes
3984 @subsection AArch64 Function Attributes
3986 The following target-specific function attributes are available for the
3987 AArch64 target. For the most part, these options mirror the behavior of
3988 similar command-line options (@pxref{AArch64 Options}), but on a
3992 @item general-regs-only
3993 @cindex @code{general-regs-only} function attribute, AArch64
3994 Indicates that no floating-point or Advanced SIMD registers should be
3995 used when generating code for this function. If the function explicitly
3996 uses floating-point code, then the compiler gives an error. This is
3997 the same behavior as that of the command-line option
3998 @option{-mgeneral-regs-only}.
4000 @item fix-cortex-a53-835769
4001 @cindex @code{fix-cortex-a53-835769} function attribute, AArch64
4002 Indicates that the workaround for the Cortex-A53 erratum 835769 should be
4003 applied to this function. To explicitly disable the workaround for this
4004 function specify the negated form: @code{no-fix-cortex-a53-835769}.
4005 This corresponds to the behavior of the command line options
4006 @option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
4009 @cindex @code{cmodel=} function attribute, AArch64
4010 Indicates that code should be generated for a particular code model for
4011 this function. The behavior and permissible arguments are the same as
4012 for the command line option @option{-mcmodel=}.
4015 @itemx no-strict-align
4016 @cindex @code{strict-align} function attribute, AArch64
4017 @code{strict-align} indicates that the compiler should not assume that unaligned
4018 memory references are handled by the system. To allow the compiler to assume
4019 that aligned memory references are handled by the system, the inverse attribute
4020 @code{no-strict-align} can be specified. The behavior is same as for the
4021 command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
4023 @item omit-leaf-frame-pointer
4024 @cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
4025 Indicates that the frame pointer should be omitted for a leaf function call.
4026 To keep the frame pointer, the inverse attribute
4027 @code{no-omit-leaf-frame-pointer} can be specified. These attributes have
4028 the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
4029 and @option{-mno-omit-leaf-frame-pointer}.
4032 @cindex @code{tls-dialect=} function attribute, AArch64
4033 Specifies the TLS dialect to use for this function. The behavior and
4034 permissible arguments are the same as for the command-line option
4035 @option{-mtls-dialect=}.
4038 @cindex @code{arch=} function attribute, AArch64
4039 Specifies the architecture version and architectural extensions to use
4040 for this function. The behavior and permissible arguments are the same as
4041 for the @option{-march=} command-line option.
4044 @cindex @code{tune=} function attribute, AArch64
4045 Specifies the core for which to tune the performance of this function.
4046 The behavior and permissible arguments are the same as for the @option{-mtune=}
4047 command-line option.
4050 @cindex @code{cpu=} function attribute, AArch64
4051 Specifies the core for which to tune the performance of this function and also
4052 whose architectural features to use. The behavior and valid arguments are the
4053 same as for the @option{-mcpu=} command-line option.
4055 @item sign-return-address
4056 @cindex @code{sign-return-address} function attribute, AArch64
4057 Select the function scope on which return address signing will be applied. The
4058 behavior and permissible arguments are the same as for the command-line option
4059 @option{-msign-return-address=}. The default value is @code{none}. This
4060 attribute is deprecated. The @code{branch-protection} attribute should
4063 @item branch-protection
4064 @cindex @code{branch-protection} function attribute, AArch64
4065 Select the function scope on which branch protection will be applied. The
4066 behavior and permissible arguments are the same as for the command-line option
4067 @option{-mbranch-protection=}. The default value is @code{none}.
4071 The above target attributes can be specified as follows:
4074 __attribute__((target("@var{attr-string}")))
4082 where @code{@var{attr-string}} is one of the attribute strings specified above.
4084 Additionally, the architectural extension string may be specified on its
4085 own. This can be used to turn on and off particular architectural extensions
4086 without having to specify a particular architecture version or core. Example:
4089 __attribute__((target("+crc+nocrypto")))
4097 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
4098 extension and disables the @code{crypto} extension for the function @code{foo}
4099 without modifying an existing @option{-march=} or @option{-mcpu} option.
4101 Multiple target function attributes can be specified by separating them with
4102 a comma. For example:
4104 __attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
4112 is valid and compiles function @code{foo} for ARMv8-A with @code{crc}
4113 and @code{crypto} extensions and tunes it for @code{cortex-a53}.
4115 @subsubsection Inlining rules
4116 Specifying target attributes on individual functions or performing link-time
4117 optimization across translation units compiled with different target options
4118 can affect function inlining rules:
4120 In particular, a caller function can inline a callee function only if the
4121 architectural features available to the callee are a subset of the features
4122 available to the caller.
4123 For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
4124 or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
4125 can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
4126 because the all the architectural features that function @code{bar} requires
4127 are available to function @code{foo}. Conversely, function @code{bar} cannot
4128 inline function @code{foo}.
4130 Additionally inlining a function compiled with @option{-mstrict-align} into a
4131 function compiled without @code{-mstrict-align} is not allowed.
4132 However, inlining a function compiled without @option{-mstrict-align} into a
4133 function compiled with @option{-mstrict-align} is allowed.
4135 Note that CPU tuning options and attributes such as the @option{-mcpu=},
4136 @option{-mtune=} do not inhibit inlining unless the CPU specified by the
4137 @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
4138 architectural feature rules specified above.
4140 @node AMD GCN Function Attributes
4141 @subsection AMD GCN Function Attributes
4143 These function attributes are supported by the AMD GCN back end:
4146 @item amdgpu_hsa_kernel
4147 @cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN
4148 This attribute indicates that the corresponding function should be compiled as
4149 a kernel function, that is an entry point that can be invoked from the host
4150 via the HSA runtime library. By default functions are only callable only from
4151 other GCN functions.
4153 This attribute is implicitly applied to any function named @code{main}, using
4156 Kernel functions may return an integer value, which will be written to a
4157 conventional place within the HSA "kernargs" region.
4159 The attribute parameters configure what values are passed into the kernel
4160 function by the GPU drivers, via the initial register state. Some values are
4161 used by the compiler, and therefore forced on. Enabling other options may
4162 break assumptions in the compiler and/or run-time libraries.
4165 @item private_segment_buffer
4166 Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to
4170 Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the
4174 Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address
4177 @item kernarg_segment_ptr
4178 Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to
4179 locate the kernel arguments, "kernargs").
4182 Set @code{enable_sgpr_dispatch_id} flag.
4184 @item flat_scratch_init
4185 Set @code{enable_sgpr_flat_scratch_init} flag.
4187 @item private_segment_size
4188 Set @code{enable_sgpr_private_segment_size} flag.
4190 @item grid_workgroup_count_X
4191 Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to
4192 use OpenACC/OpenMP).
4194 @item grid_workgroup_count_Y
4195 Set @code{enable_sgpr_grid_workgroup_count_y} flag.
4197 @item grid_workgroup_count_Z
4198 Set @code{enable_sgpr_grid_workgroup_count_z} flag.
4200 @item workgroup_id_X
4201 Set @code{enable_sgpr_workgroup_id_x} flag.
4203 @item workgroup_id_Y
4204 Set @code{enable_sgpr_workgroup_id_y} flag.
4206 @item workgroup_id_Z
4207 Set @code{enable_sgpr_workgroup_id_z} flag.
4209 @item workgroup_info
4210 Set @code{enable_sgpr_workgroup_info} flag.
4212 @item private_segment_wave_offset
4213 Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on
4214 (required to locate the stack).
4216 @item work_item_id_X
4217 Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled).
4219 @item work_item_id_Y
4220 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable
4223 @item work_item_id_Z
4224 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use
4230 @node ARC Function Attributes
4231 @subsection ARC Function Attributes
4233 These function attributes are supported by the ARC back end:
4237 @cindex @code{interrupt} function attribute, ARC
4238 Use this attribute to indicate
4239 that the specified function is an interrupt handler. The compiler generates
4240 function entry and exit sequences suitable for use in an interrupt handler
4241 when this attribute is present.
4243 On the ARC, you must specify the kind of interrupt to be handled
4244 in a parameter to the interrupt attribute like this:
4247 void f () __attribute__ ((interrupt ("ilink1")));
4250 Permissible values for this parameter are: @w{@code{ilink1}} and
4251 @w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and
4252 @w{@code{firq}} for ARCv2 architecture.
4257 @cindex @code{long_call} function attribute, ARC
4258 @cindex @code{medium_call} function attribute, ARC
4259 @cindex @code{short_call} function attribute, ARC
4260 @cindex indirect calls, ARC
4261 These attributes specify how a particular function is called.
4262 These attributes override the
4263 @option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
4264 command-line switches and @code{#pragma long_calls} settings.
4266 For ARC, a function marked with the @code{long_call} attribute is
4267 always called using register-indirect jump-and-link instructions,
4268 thereby enabling the called function to be placed anywhere within the
4269 32-bit address space. A function marked with the @code{medium_call}
4270 attribute will always be close enough to be called with an unconditional
4271 branch-and-link instruction, which has a 25-bit offset from
4272 the call site. A function marked with the @code{short_call}
4273 attribute will always be close enough to be called with a conditional
4274 branch-and-link instruction, which has a 21-bit offset from
4278 @cindex @code{jli_always} function attribute, ARC
4279 Forces a particular function to be called using @code{jli}
4280 instruction. The @code{jli} instruction makes use of a table stored
4281 into @code{.jlitab} section, which holds the location of the functions
4282 which are addressed using this instruction.
4285 @cindex @code{jli_fixed} function attribute, ARC
4286 Identical like the above one, but the location of the function in the
4287 @code{jli} table is known and given as an attribute parameter.
4290 @cindex @code{secure_call} function attribute, ARC
4291 This attribute allows one to mark secure-code functions that are
4292 callable from normal mode. The location of the secure call function
4293 into the @code{sjli} table needs to be passed as argument.
4296 @cindex @code{naked} function attribute, ARC
4297 This attribute allows the compiler to construct the requisite function
4298 declaration, while allowing the body of the function to be assembly
4299 code. The specified function will not have prologue/epilogue
4300 sequences generated by the compiler. Only basic @code{asm} statements
4301 can safely be included in naked functions (@pxref{Basic Asm}). While
4302 using extended @code{asm} or a mixture of basic @code{asm} and C code
4303 may appear to work, they cannot be depended upon to work reliably and
4308 @node ARM Function Attributes
4309 @subsection ARM Function Attributes
4311 These function attributes are supported for ARM targets:
4315 @item general-regs-only
4316 @cindex @code{general-regs-only} function attribute, ARM
4317 Indicates that no floating-point or Advanced SIMD registers should be
4318 used when generating code for this function. If the function explicitly
4319 uses floating-point code, then the compiler gives an error. This is
4320 the same behavior as that of the command-line option
4321 @option{-mgeneral-regs-only}.
4324 @cindex @code{interrupt} function attribute, ARM
4325 Use this attribute to indicate
4326 that the specified function is an interrupt handler. The compiler generates
4327 function entry and exit sequences suitable for use in an interrupt handler
4328 when this attribute is present.
4330 You can specify the kind of interrupt to be handled by
4331 adding an optional parameter to the interrupt attribute like this:
4334 void f () __attribute__ ((interrupt ("IRQ")));
4338 Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
4339 @code{SWI}, @code{ABORT} and @code{UNDEF}.
4341 On ARMv7-M the interrupt type is ignored, and the attribute means the function
4342 may be called with a word-aligned stack pointer.
4345 @cindex @code{isr} function attribute, ARM
4346 Use this attribute on ARM to write Interrupt Service Routines. This is an
4347 alias to the @code{interrupt} attribute above.
4351 @cindex @code{long_call} function attribute, ARM
4352 @cindex @code{short_call} function attribute, ARM
4353 @cindex indirect calls, ARM
4354 These attributes specify how a particular function is called.
4355 These attributes override the
4356 @option{-mlong-calls} (@pxref{ARM Options})
4357 command-line switch and @code{#pragma long_calls} settings. For ARM, the
4358 @code{long_call} attribute indicates that the function might be far
4359 away from the call site and require a different (more expensive)
4360 calling sequence. The @code{short_call} attribute always places
4361 the offset to the function from the call site into the @samp{BL}
4362 instruction directly.
4365 @cindex @code{naked} function attribute, ARM
4366 This attribute allows the compiler to construct the
4367 requisite function declaration, while allowing the body of the
4368 function to be assembly code. The specified function will not have
4369 prologue/epilogue sequences generated by the compiler. Only basic
4370 @code{asm} statements can safely be included in naked functions
4371 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4372 basic @code{asm} and C code may appear to work, they cannot be
4373 depended upon to work reliably and are not supported.
4376 @cindex @code{pcs} function attribute, ARM
4378 The @code{pcs} attribute can be used to control the calling convention
4379 used for a function on ARM. The attribute takes an argument that specifies
4380 the calling convention to use.
4382 When compiling using the AAPCS ABI (or a variant of it) then valid
4383 values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
4384 order to use a variant other than @code{"aapcs"} then the compiler must
4385 be permitted to use the appropriate co-processor registers (i.e., the
4386 VFP registers must be available in order to use @code{"aapcs-vfp"}).
4390 /* Argument passed in r0, and result returned in r0+r1. */
4391 double f2d (float) __attribute__((pcs("aapcs")));
4394 Variadic functions always use the @code{"aapcs"} calling convention and
4395 the compiler rejects attempts to specify an alternative.
4397 @item target (@var{options})
4398 @cindex @code{target} function attribute
4399 As discussed in @ref{Common Function Attributes}, this attribute
4400 allows specification of target-specific compilation options.
4402 On ARM, the following options are allowed:
4406 @cindex @code{target("thumb")} function attribute, ARM
4407 Force code generation in the Thumb (T16/T32) ISA, depending on the
4411 @cindex @code{target("arm")} function attribute, ARM
4412 Force code generation in the ARM (A32) ISA.
4414 Functions from different modes can be inlined in the caller's mode.
4417 @cindex @code{target("fpu=")} function attribute, ARM
4418 Specifies the fpu for which to tune the performance of this function.
4419 The behavior and permissible arguments are the same as for the @option{-mfpu=}
4420 command-line option.
4423 @cindex @code{arch=} function attribute, ARM
4424 Specifies the architecture version and architectural extensions to use
4425 for this function. The behavior and permissible arguments are the same as
4426 for the @option{-march=} command-line option.
4428 The above target attributes can be specified as follows:
4431 __attribute__((target("arch=armv8-a+crc")))
4439 Additionally, the architectural extension string may be specified on its
4440 own. This can be used to turn on and off particular architectural extensions
4441 without having to specify a particular architecture version or core. Example:
4444 __attribute__((target("+crc+nocrypto")))
4452 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
4453 extension and disables the @code{crypto} extension for the function @code{foo}
4454 without modifying an existing @option{-march=} or @option{-mcpu} option.
4460 @node AVR Function Attributes
4461 @subsection AVR Function Attributes
4463 These function attributes are supported by the AVR back end:
4467 @cindex @code{interrupt} function attribute, AVR
4468 Use this attribute to indicate
4469 that the specified function is an interrupt handler. The compiler generates
4470 function entry and exit sequences suitable for use in an interrupt handler
4471 when this attribute is present.
4473 On the AVR, the hardware globally disables interrupts when an
4474 interrupt is executed. The first instruction of an interrupt handler
4475 declared with this attribute is a @code{SEI} instruction to
4476 re-enable interrupts. See also the @code{signal} function attribute
4477 that does not insert a @code{SEI} instruction. If both @code{signal} and
4478 @code{interrupt} are specified for the same function, @code{signal}
4479 is silently ignored.
4482 @cindex @code{naked} function attribute, AVR
4483 This attribute allows the compiler to construct the
4484 requisite function declaration, while allowing the body of the
4485 function to be assembly code. The specified function will not have
4486 prologue/epilogue sequences generated by the compiler. Only basic
4487 @code{asm} statements can safely be included in naked functions
4488 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4489 basic @code{asm} and C code may appear to work, they cannot be
4490 depended upon to work reliably and are not supported.
4493 @cindex @code{no_gccisr} function attribute, AVR
4494 Do not use @code{__gcc_isr} pseudo instructions in a function with
4495 the @code{interrupt} or @code{signal} attribute aka. interrupt
4496 service routine (ISR).
4497 Use this attribute if the preamble of the ISR prologue should always read
4501 in __tmp_reg__, __SREG__
4505 and accordingly for the postamble of the epilogue --- no matter whether
4506 the mentioned registers are actually used in the ISR or not.
4507 Situations where you might want to use this attribute include:
4510 Code that (effectively) clobbers bits of @code{SREG} other than the
4511 @code{I}-flag by writing to the memory location of @code{SREG}.
4513 Code that uses inline assembler to jump to a different function which
4514 expects (parts of) the prologue code as outlined above to be present.
4516 To disable @code{__gcc_isr} generation for the whole compilation unit,
4517 there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}.
4521 @cindex @code{OS_main} function attribute, AVR
4522 @cindex @code{OS_task} function attribute, AVR
4523 On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
4524 do not save/restore any call-saved register in their prologue/epilogue.
4526 The @code{OS_main} attribute can be used when there @emph{is
4527 guarantee} that interrupts are disabled at the time when the function
4528 is entered. This saves resources when the stack pointer has to be
4529 changed to set up a frame for local variables.
4531 The @code{OS_task} attribute can be used when there is @emph{no
4532 guarantee} that interrupts are disabled at that time when the function
4533 is entered like for, e@.g@. task functions in a multi-threading operating
4534 system. In that case, changing the stack pointer register is
4535 guarded by save/clear/restore of the global interrupt enable flag.
4537 The differences to the @code{naked} function attribute are:
4539 @item @code{naked} functions do not have a return instruction whereas
4540 @code{OS_main} and @code{OS_task} functions have a @code{RET} or
4541 @code{RETI} return instruction.
4542 @item @code{naked} functions do not set up a frame for local variables
4543 or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
4548 @cindex @code{signal} function attribute, AVR
4549 Use this attribute on the AVR to indicate that the specified
4550 function is an interrupt handler. The compiler generates function
4551 entry and exit sequences suitable for use in an interrupt handler when this
4552 attribute is present.
4554 See also the @code{interrupt} function attribute.
4556 The AVR hardware globally disables interrupts when an interrupt is executed.
4557 Interrupt handler functions defined with the @code{signal} attribute
4558 do not re-enable interrupts. It is save to enable interrupts in a
4559 @code{signal} handler. This ``save'' only applies to the code
4560 generated by the compiler and not to the IRQ layout of the
4561 application which is responsibility of the application.
4563 If both @code{signal} and @code{interrupt} are specified for the same
4564 function, @code{signal} is silently ignored.
4567 @node Blackfin Function Attributes
4568 @subsection Blackfin Function Attributes
4570 These function attributes are supported by the Blackfin back end:
4574 @item exception_handler
4575 @cindex @code{exception_handler} function attribute
4576 @cindex exception handler functions, Blackfin
4577 Use this attribute on the Blackfin to indicate that the specified function
4578 is an exception handler. The compiler generates function entry and
4579 exit sequences suitable for use in an exception handler when this
4580 attribute is present.
4582 @item interrupt_handler
4583 @cindex @code{interrupt_handler} function attribute, Blackfin
4584 Use this attribute to
4585 indicate that the specified function is an interrupt handler. The compiler
4586 generates function entry and exit sequences suitable for use in an
4587 interrupt handler when this attribute is present.
4590 @cindex @code{kspisusp} function attribute, Blackfin
4591 @cindex User stack pointer in interrupts on the Blackfin
4592 When used together with @code{interrupt_handler}, @code{exception_handler}
4593 or @code{nmi_handler}, code is generated to load the stack pointer
4594 from the USP register in the function prologue.
4597 @cindex @code{l1_text} function attribute, Blackfin
4598 This attribute specifies a function to be placed into L1 Instruction
4599 SRAM@. The function is put into a specific section named @code{.l1.text}.
4600 With @option{-mfdpic}, function calls with a such function as the callee
4601 or caller uses inlined PLT.
4604 @cindex @code{l2} function attribute, Blackfin
4605 This attribute specifies a function to be placed into L2
4606 SRAM. The function is put into a specific section named
4607 @code{.l2.text}. With @option{-mfdpic}, callers of such functions use
4612 @cindex indirect calls, Blackfin
4613 @cindex @code{longcall} function attribute, Blackfin
4614 @cindex @code{shortcall} function attribute, Blackfin
4615 The @code{longcall} attribute
4616 indicates that the function might be far away from the call site and
4617 require a different (more expensive) calling sequence. The
4618 @code{shortcall} attribute indicates that the function is always close
4619 enough for the shorter calling sequence to be used. These attributes
4620 override the @option{-mlongcall} switch.
4623 @cindex @code{nesting} function attribute, Blackfin
4624 @cindex Allow nesting in an interrupt handler on the Blackfin processor
4625 Use this attribute together with @code{interrupt_handler},
4626 @code{exception_handler} or @code{nmi_handler} to indicate that the function
4627 entry code should enable nested interrupts or exceptions.
4630 @cindex @code{nmi_handler} function attribute, Blackfin
4631 @cindex NMI handler functions on the Blackfin processor
4632 Use this attribute on the Blackfin to indicate that the specified function
4633 is an NMI handler. The compiler generates function entry and
4634 exit sequences suitable for use in an NMI handler when this
4635 attribute is present.
4638 @cindex @code{saveall} function attribute, Blackfin
4639 @cindex save all registers on the Blackfin
4640 Use this attribute to indicate that
4641 all registers except the stack pointer should be saved in the prologue
4642 regardless of whether they are used or not.
4645 @node CR16 Function Attributes
4646 @subsection CR16 Function Attributes
4648 These function attributes are supported by the CR16 back end:
4652 @cindex @code{interrupt} function attribute, CR16
4653 Use this attribute to indicate
4654 that the specified function is an interrupt handler. The compiler generates
4655 function entry and exit sequences suitable for use in an interrupt handler
4656 when this attribute is present.
4659 @node C-SKY Function Attributes
4660 @subsection C-SKY Function Attributes
4662 These function attributes are supported by the C-SKY back end:
4667 @cindex @code{interrupt} function attribute, C-SKY
4668 @cindex @code{isr} function attribute, C-SKY
4669 Use these attributes to indicate that the specified function
4670 is an interrupt handler.
4671 The compiler generates function entry and exit sequences suitable for
4672 use in an interrupt handler when either of these attributes are present.
4674 Use of these options requires the @option{-mistack} command-line option
4675 to enable support for the necessary interrupt stack instructions. They
4676 are ignored with a warning otherwise. @xref{C-SKY Options}.
4679 @cindex @code{naked} function attribute, C-SKY
4680 This attribute allows the compiler to construct the
4681 requisite function declaration, while allowing the body of the
4682 function to be assembly code. The specified function will not have
4683 prologue/epilogue sequences generated by the compiler. Only basic
4684 @code{asm} statements can safely be included in naked functions
4685 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4686 basic @code{asm} and C code may appear to work, they cannot be
4687 depended upon to work reliably and are not supported.
4691 @node Epiphany Function Attributes
4692 @subsection Epiphany Function Attributes
4694 These function attributes are supported by the Epiphany back end:
4698 @cindex @code{disinterrupt} function attribute, Epiphany
4699 This attribute causes the compiler to emit
4700 instructions to disable interrupts for the duration of the given
4703 @item forwarder_section
4704 @cindex @code{forwarder_section} function attribute, Epiphany
4705 This attribute modifies the behavior of an interrupt handler.
4706 The interrupt handler may be in external memory which cannot be
4707 reached by a branch instruction, so generate a local memory trampoline
4708 to transfer control. The single parameter identifies the section where
4709 the trampoline is placed.
4712 @cindex @code{interrupt} function attribute, Epiphany
4713 Use this attribute to indicate
4714 that the specified function is an interrupt handler. The compiler generates
4715 function entry and exit sequences suitable for use in an interrupt handler
4716 when this attribute is present. It may also generate
4717 a special section with code to initialize the interrupt vector table.
4719 On Epiphany targets one or more optional parameters can be added like this:
4722 void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
4725 Permissible values for these parameters are: @w{@code{reset}},
4726 @w{@code{software_exception}}, @w{@code{page_miss}},
4727 @w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
4728 @w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
4729 Multiple parameters indicate that multiple entries in the interrupt
4730 vector table should be initialized for this function, i.e.@: for each
4731 parameter @w{@var{name}}, a jump to the function is emitted in
4732 the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
4733 entirely, in which case no interrupt vector table entry is provided.
4735 Note that interrupts are enabled inside the function
4736 unless the @code{disinterrupt} attribute is also specified.
4738 The following examples are all valid uses of these attributes on
4741 void __attribute__ ((interrupt)) universal_handler ();
4742 void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
4743 void __attribute__ ((interrupt ("dma0, dma1")))
4744 universal_dma_handler ();
4745 void __attribute__ ((interrupt ("timer0"), disinterrupt))
4746 fast_timer_handler ();
4747 void __attribute__ ((interrupt ("dma0, dma1"),
4748 forwarder_section ("tramp")))
4749 external_dma_handler ();
4754 @cindex @code{long_call} function attribute, Epiphany
4755 @cindex @code{short_call} function attribute, Epiphany
4756 @cindex indirect calls, Epiphany
4757 These attributes specify how a particular function is called.
4758 These attributes override the
4759 @option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
4760 command-line switch and @code{#pragma long_calls} settings.
4764 @node H8/300 Function Attributes
4765 @subsection H8/300 Function Attributes
4767 These function attributes are available for H8/300 targets:
4770 @item function_vector
4771 @cindex @code{function_vector} function attribute, H8/300
4772 Use this attribute on the H8/300, H8/300H, and H8S to indicate
4773 that the specified function should be called through the function vector.
4774 Calling a function through the function vector reduces code size; however,
4775 the function vector has a limited size (maximum 128 entries on the H8/300
4776 and 64 entries on the H8/300H and H8S)
4777 and shares space with the interrupt vector.
4779 @item interrupt_handler
4780 @cindex @code{interrupt_handler} function attribute, H8/300
4781 Use this attribute on the H8/300, H8/300H, and H8S to
4782 indicate that the specified function is an interrupt handler. The compiler
4783 generates function entry and exit sequences suitable for use in an
4784 interrupt handler when this attribute is present.
4787 @cindex @code{saveall} function attribute, H8/300
4788 @cindex save all registers on the H8/300, H8/300H, and H8S
4789 Use this attribute on the H8/300, H8/300H, and H8S to indicate that
4790 all registers except the stack pointer should be saved in the prologue
4791 regardless of whether they are used or not.
4794 @node IA-64 Function Attributes
4795 @subsection IA-64 Function Attributes
4797 These function attributes are supported on IA-64 targets:
4800 @item syscall_linkage
4801 @cindex @code{syscall_linkage} function attribute, IA-64
4802 This attribute is used to modify the IA-64 calling convention by marking
4803 all input registers as live at all function exits. This makes it possible
4804 to restart a system call after an interrupt without having to save/restore
4805 the input registers. This also prevents kernel data from leaking into
4809 @cindex @code{version_id} function attribute, IA-64
4810 This IA-64 HP-UX attribute, attached to a global variable or function, renames a
4811 symbol to contain a version string, thus allowing for function level
4812 versioning. HP-UX system header files may use function level versioning
4813 for some system calls.
4816 extern int foo () __attribute__((version_id ("20040821")));
4820 Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
4823 @node M32C Function Attributes
4824 @subsection M32C Function Attributes
4826 These function attributes are supported by the M32C back end:
4830 @cindex @code{bank_switch} function attribute, M32C
4831 When added to an interrupt handler with the M32C port, causes the
4832 prologue and epilogue to use bank switching to preserve the registers
4833 rather than saving them on the stack.
4835 @item fast_interrupt
4836 @cindex @code{fast_interrupt} function attribute, M32C
4837 Use this attribute on the M32C port to indicate that the specified
4838 function is a fast interrupt handler. This is just like the
4839 @code{interrupt} attribute, except that @code{freit} is used to return
4840 instead of @code{reit}.
4842 @item function_vector
4843 @cindex @code{function_vector} function attribute, M16C/M32C
4844 On M16C/M32C targets, the @code{function_vector} attribute declares a
4845 special page subroutine call function. Use of this attribute reduces
4846 the code size by 2 bytes for each call generated to the
4847 subroutine. The argument to the attribute is the vector number entry
4848 from the special page vector table which contains the 16 low-order
4849 bits of the subroutine's entry address. Each vector table has special
4850 page number (18 to 255) that is used in @code{jsrs} instructions.
4851 Jump addresses of the routines are generated by adding 0x0F0000 (in
4852 case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
4853 2-byte addresses set in the vector table. Therefore you need to ensure
4854 that all the special page vector routines should get mapped within the
4855 address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
4858 In the following example 2 bytes are saved for each call to
4859 function @code{foo}.
4862 void foo (void) __attribute__((function_vector(0x18)));
4873 If functions are defined in one file and are called in another file,
4874 then be sure to write this declaration in both files.
4876 This attribute is ignored for R8C target.
4879 @cindex @code{interrupt} function attribute, M32C
4880 Use this attribute to indicate
4881 that the specified function is an interrupt handler. The compiler generates
4882 function entry and exit sequences suitable for use in an interrupt handler
4883 when this attribute is present.
4886 @node M32R/D Function Attributes
4887 @subsection M32R/D Function Attributes
4889 These function attributes are supported by the M32R/D back end:
4893 @cindex @code{interrupt} function attribute, M32R/D
4894 Use this attribute to indicate
4895 that the specified function is an interrupt handler. The compiler generates
4896 function entry and exit sequences suitable for use in an interrupt handler
4897 when this attribute is present.
4899 @item model (@var{model-name})
4900 @cindex @code{model} function attribute, M32R/D
4901 @cindex function addressability on the M32R/D
4903 On the M32R/D, use this attribute to set the addressability of an
4904 object, and of the code generated for a function. The identifier
4905 @var{model-name} is one of @code{small}, @code{medium}, or
4906 @code{large}, representing each of the code models.
4908 Small model objects live in the lower 16MB of memory (so that their
4909 addresses can be loaded with the @code{ld24} instruction), and are
4910 callable with the @code{bl} instruction.
4912 Medium model objects may live anywhere in the 32-bit address space (the
4913 compiler generates @code{seth/add3} instructions to load their addresses),
4914 and are callable with the @code{bl} instruction.
4916 Large model objects may live anywhere in the 32-bit address space (the
4917 compiler generates @code{seth/add3} instructions to load their addresses),
4918 and may not be reachable with the @code{bl} instruction (the compiler
4919 generates the much slower @code{seth/add3/jl} instruction sequence).
4922 @node m68k Function Attributes
4923 @subsection m68k Function Attributes
4925 These function attributes are supported by the m68k back end:
4929 @itemx interrupt_handler
4930 @cindex @code{interrupt} function attribute, m68k
4931 @cindex @code{interrupt_handler} function attribute, m68k
4932 Use this attribute to
4933 indicate that the specified function is an interrupt handler. The compiler
4934 generates function entry and exit sequences suitable for use in an
4935 interrupt handler when this attribute is present. Either name may be used.
4937 @item interrupt_thread
4938 @cindex @code{interrupt_thread} function attribute, fido
4939 Use this attribute on fido, a subarchitecture of the m68k, to indicate
4940 that the specified function is an interrupt handler that is designed
4941 to run as a thread. The compiler omits generate prologue/epilogue
4942 sequences and replaces the return instruction with a @code{sleep}
4943 instruction. This attribute is available only on fido.
4946 @node MCORE Function Attributes
4947 @subsection MCORE Function Attributes
4949 These function attributes are supported by the MCORE back end:
4953 @cindex @code{naked} function attribute, MCORE
4954 This attribute allows the compiler to construct the
4955 requisite function declaration, while allowing the body of the
4956 function to be assembly code. The specified function will not have
4957 prologue/epilogue sequences generated by the compiler. Only basic
4958 @code{asm} statements can safely be included in naked functions
4959 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4960 basic @code{asm} and C code may appear to work, they cannot be
4961 depended upon to work reliably and are not supported.
4964 @node MeP Function Attributes
4965 @subsection MeP Function Attributes
4967 These function attributes are supported by the MeP back end:
4971 @cindex @code{disinterrupt} function attribute, MeP
4972 On MeP targets, this attribute causes the compiler to emit
4973 instructions to disable interrupts for the duration of the given
4977 @cindex @code{interrupt} function attribute, MeP
4978 Use this attribute to indicate
4979 that the specified function is an interrupt handler. The compiler generates
4980 function entry and exit sequences suitable for use in an interrupt handler
4981 when this attribute is present.
4984 @cindex @code{near} function attribute, MeP
4985 This attribute causes the compiler to assume the called
4986 function is close enough to use the normal calling convention,
4987 overriding the @option{-mtf} command-line option.
4990 @cindex @code{far} function attribute, MeP
4991 On MeP targets this causes the compiler to use a calling convention
4992 that assumes the called function is too far away for the built-in
4996 @cindex @code{vliw} function attribute, MeP
4997 The @code{vliw} attribute tells the compiler to emit
4998 instructions in VLIW mode instead of core mode. Note that this
4999 attribute is not allowed unless a VLIW coprocessor has been configured
5000 and enabled through command-line options.
5003 @node MicroBlaze Function Attributes
5004 @subsection MicroBlaze Function Attributes
5006 These function attributes are supported on MicroBlaze targets:
5009 @item save_volatiles
5010 @cindex @code{save_volatiles} function attribute, MicroBlaze
5011 Use this attribute to indicate that the function is
5012 an interrupt handler. All volatile registers (in addition to non-volatile
5013 registers) are saved in the function prologue. If the function is a leaf
5014 function, only volatiles used by the function are saved. A normal function
5015 return is generated instead of a return from interrupt.
5018 @cindex @code{break_handler} function attribute, MicroBlaze
5019 @cindex break handler functions
5020 Use this attribute to indicate that
5021 the specified function is a break handler. The compiler generates function
5022 entry and exit sequences suitable for use in an break handler when this
5023 attribute is present. The return from @code{break_handler} is done through
5024 the @code{rtbd} instead of @code{rtsd}.
5027 void f () __attribute__ ((break_handler));
5030 @item interrupt_handler
5031 @itemx fast_interrupt
5032 @cindex @code{interrupt_handler} function attribute, MicroBlaze
5033 @cindex @code{fast_interrupt} function attribute, MicroBlaze
5034 These attributes indicate that the specified function is an interrupt
5035 handler. Use the @code{fast_interrupt} attribute to indicate handlers
5036 used in low-latency interrupt mode, and @code{interrupt_handler} for
5037 interrupts that do not use low-latency handlers. In both cases, GCC
5038 emits appropriate prologue code and generates a return from the handler
5039 using @code{rtid} instead of @code{rtsd}.
5042 @node Microsoft Windows Function Attributes
5043 @subsection Microsoft Windows Function Attributes
5045 The following attributes are available on Microsoft Windows and Symbian OS
5050 @cindex @code{dllexport} function attribute
5051 @cindex @code{__declspec(dllexport)}
5052 On Microsoft Windows targets and Symbian OS targets the
5053 @code{dllexport} attribute causes the compiler to provide a global
5054 pointer to a pointer in a DLL, so that it can be referenced with the
5055 @code{dllimport} attribute. On Microsoft Windows targets, the pointer
5056 name is formed by combining @code{_imp__} and the function or variable
5059 You can use @code{__declspec(dllexport)} as a synonym for
5060 @code{__attribute__ ((dllexport))} for compatibility with other
5063 On systems that support the @code{visibility} attribute, this
5064 attribute also implies ``default'' visibility. It is an error to
5065 explicitly specify any other visibility.
5067 GCC's default behavior is to emit all inline functions with the
5068 @code{dllexport} attribute. Since this can cause object file-size bloat,
5069 you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
5070 ignore the attribute for inlined functions unless the
5071 @option{-fkeep-inline-functions} flag is used instead.
5073 The attribute is ignored for undefined symbols.
5075 When applied to C++ classes, the attribute marks defined non-inlined
5076 member functions and static data members as exports. Static consts
5077 initialized in-class are not marked unless they are also defined
5080 For Microsoft Windows targets there are alternative methods for
5081 including the symbol in the DLL's export table such as using a
5082 @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
5083 the @option{--export-all} linker flag.
5086 @cindex @code{dllimport} function attribute
5087 @cindex @code{__declspec(dllimport)}
5088 On Microsoft Windows and Symbian OS targets, the @code{dllimport}
5089 attribute causes the compiler to reference a function or variable via
5090 a global pointer to a pointer that is set up by the DLL exporting the
5091 symbol. The attribute implies @code{extern}. On Microsoft Windows
5092 targets, the pointer name is formed by combining @code{_imp__} and the
5093 function or variable name.
5095 You can use @code{__declspec(dllimport)} as a synonym for
5096 @code{__attribute__ ((dllimport))} for compatibility with other
5099 On systems that support the @code{visibility} attribute, this
5100 attribute also implies ``default'' visibility. It is an error to
5101 explicitly specify any other visibility.
5103 Currently, the attribute is ignored for inlined functions. If the
5104 attribute is applied to a symbol @emph{definition}, an error is reported.
5105 If a symbol previously declared @code{dllimport} is later defined, the
5106 attribute is ignored in subsequent references, and a warning is emitted.
5107 The attribute is also overridden by a subsequent declaration as
5110 When applied to C++ classes, the attribute marks non-inlined
5111 member functions and static data members as imports. However, the
5112 attribute is ignored for virtual methods to allow creation of vtables
5115 On the SH Symbian OS target the @code{dllimport} attribute also has
5116 another affect---it can cause the vtable and run-time type information
5117 for a class to be exported. This happens when the class has a
5118 dllimported constructor or a non-inline, non-pure virtual function
5119 and, for either of those two conditions, the class also has an inline
5120 constructor or destructor and has a key function that is defined in
5121 the current translation unit.
5123 For Microsoft Windows targets the use of the @code{dllimport}
5124 attribute on functions is not necessary, but provides a small
5125 performance benefit by eliminating a thunk in the DLL@. The use of the
5126 @code{dllimport} attribute on imported variables can be avoided by passing the
5127 @option{--enable-auto-import} switch to the GNU linker. As with
5128 functions, using the attribute for a variable eliminates a thunk in
5131 One drawback to using this attribute is that a pointer to a
5132 @emph{variable} marked as @code{dllimport} cannot be used as a constant
5133 address. However, a pointer to a @emph{function} with the
5134 @code{dllimport} attribute can be used as a constant initializer; in
5135 this case, the address of a stub function in the import lib is
5136 referenced. On Microsoft Windows targets, the attribute can be disabled
5137 for functions by setting the @option{-mnop-fun-dllimport} flag.
5140 @node MIPS Function Attributes
5141 @subsection MIPS Function Attributes
5143 These function attributes are supported by the MIPS back end:
5147 @cindex @code{interrupt} function attribute, MIPS
5148 Use this attribute to indicate that the specified function is an interrupt
5149 handler. The compiler generates function entry and exit sequences suitable
5150 for use in an interrupt handler when this attribute is present.
5151 An optional argument is supported for the interrupt attribute which allows
5152 the interrupt mode to be described. By default GCC assumes the external
5153 interrupt controller (EIC) mode is in use, this can be explicitly set using
5154 @code{eic}. When interrupts are non-masked then the requested Interrupt
5155 Priority Level (IPL) is copied to the current IPL which has the effect of only
5156 enabling higher priority interrupts. To use vectored interrupt mode use
5157 the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
5158 the behavior of the non-masked interrupt support and GCC will arrange to mask
5159 all interrupts from sw0 up to and including the specified interrupt vector.
5161 You can use the following attributes to modify the behavior
5162 of an interrupt handler:
5164 @item use_shadow_register_set
5165 @cindex @code{use_shadow_register_set} function attribute, MIPS
5166 Assume that the handler uses a shadow register set, instead of
5167 the main general-purpose registers. An optional argument @code{intstack} is
5168 supported to indicate that the shadow register set contains a valid stack
5171 @item keep_interrupts_masked
5172 @cindex @code{keep_interrupts_masked} function attribute, MIPS
5173 Keep interrupts masked for the whole function. Without this attribute,
5174 GCC tries to reenable interrupts for as much of the function as it can.
5176 @item use_debug_exception_return
5177 @cindex @code{use_debug_exception_return} function attribute, MIPS
5178 Return using the @code{deret} instruction. Interrupt handlers that don't
5179 have this attribute return using @code{eret} instead.
5182 You can use any combination of these attributes, as shown below:
5184 void __attribute__ ((interrupt)) v0 ();
5185 void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
5186 void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
5187 void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
5188 void __attribute__ ((interrupt, use_shadow_register_set,
5189 keep_interrupts_masked)) v4 ();
5190 void __attribute__ ((interrupt, use_shadow_register_set,
5191 use_debug_exception_return)) v5 ();
5192 void __attribute__ ((interrupt, keep_interrupts_masked,
5193 use_debug_exception_return)) v6 ();
5194 void __attribute__ ((interrupt, use_shadow_register_set,
5195 keep_interrupts_masked,
5196 use_debug_exception_return)) v7 ();
5197 void __attribute__ ((interrupt("eic"))) v8 ();
5198 void __attribute__ ((interrupt("vector=hw3"))) v9 ();
5205 @cindex indirect calls, MIPS
5206 @cindex @code{long_call} function attribute, MIPS
5207 @cindex @code{short_call} function attribute, MIPS
5208 @cindex @code{near} function attribute, MIPS
5209 @cindex @code{far} function attribute, MIPS
5210 These attributes specify how a particular function is called on MIPS@.
5211 The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
5212 command-line switch. The @code{long_call} and @code{far} attributes are
5213 synonyms, and cause the compiler to always call
5214 the function by first loading its address into a register, and then using
5215 the contents of that register. The @code{short_call} and @code{near}
5216 attributes are synonyms, and have the opposite
5217 effect; they specify that non-PIC calls should be made using the more
5218 efficient @code{jal} instruction.
5222 @cindex @code{mips16} function attribute, MIPS
5223 @cindex @code{nomips16} function attribute, MIPS
5225 On MIPS targets, you can use the @code{mips16} and @code{nomips16}
5226 function attributes to locally select or turn off MIPS16 code generation.
5227 A function with the @code{mips16} attribute is emitted as MIPS16 code,
5228 while MIPS16 code generation is disabled for functions with the
5229 @code{nomips16} attribute. These attributes override the
5230 @option{-mips16} and @option{-mno-mips16} options on the command line
5231 (@pxref{MIPS Options}).
5233 When compiling files containing mixed MIPS16 and non-MIPS16 code, the
5234 preprocessor symbol @code{__mips16} reflects the setting on the command line,
5235 not that within individual functions. Mixed MIPS16 and non-MIPS16 code
5236 may interact badly with some GCC extensions such as @code{__builtin_apply}
5237 (@pxref{Constructing Calls}).
5239 @item micromips, MIPS
5240 @itemx nomicromips, MIPS
5241 @cindex @code{micromips} function attribute
5242 @cindex @code{nomicromips} function attribute
5244 On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
5245 function attributes to locally select or turn off microMIPS code generation.
5246 A function with the @code{micromips} attribute is emitted as microMIPS code,
5247 while microMIPS code generation is disabled for functions with the
5248 @code{nomicromips} attribute. These attributes override the
5249 @option{-mmicromips} and @option{-mno-micromips} options on the command line
5250 (@pxref{MIPS Options}).
5252 When compiling files containing mixed microMIPS and non-microMIPS code, the
5253 preprocessor symbol @code{__mips_micromips} reflects the setting on the
5255 not that within individual functions. Mixed microMIPS and non-microMIPS code
5256 may interact badly with some GCC extensions such as @code{__builtin_apply}
5257 (@pxref{Constructing Calls}).
5260 @cindex @code{nocompression} function attribute, MIPS
5261 On MIPS targets, you can use the @code{nocompression} function attribute
5262 to locally turn off MIPS16 and microMIPS code generation. This attribute
5263 overrides the @option{-mips16} and @option{-mmicromips} options on the
5264 command line (@pxref{MIPS Options}).
5267 @node MSP430 Function Attributes
5268 @subsection MSP430 Function Attributes
5270 These function attributes are supported by the MSP430 back end:
5274 @cindex @code{critical} function attribute, MSP430
5275 Critical functions disable interrupts upon entry and restore the
5276 previous interrupt state upon exit. Critical functions cannot also
5277 have the @code{naked}, @code{reentrant} or @code{interrupt} attributes.
5279 The MSP430 hardware ensures that interrupts are disabled on entry to
5280 @code{interrupt} functions, and restores the previous interrupt state
5281 on exit. The @code{critical} attribute is therefore redundant on
5282 @code{interrupt} functions.
5285 @cindex @code{interrupt} function attribute, MSP430
5286 Use this attribute to indicate
5287 that the specified function is an interrupt handler. The compiler generates
5288 function entry and exit sequences suitable for use in an interrupt handler
5289 when this attribute is present.
5291 You can provide an argument to the interrupt
5292 attribute which specifies a name or number. If the argument is a
5293 number it indicates the slot in the interrupt vector table (0 - 31) to
5294 which this handler should be assigned. If the argument is a name it
5295 is treated as a symbolic name for the vector slot. These names should
5296 match up with appropriate entries in the linker script. By default
5297 the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
5298 @code{reset} for vector 31 are recognized.
5301 @cindex @code{naked} function attribute, MSP430
5302 This attribute allows the compiler to construct the
5303 requisite function declaration, while allowing the body of the
5304 function to be assembly code. The specified function will not have
5305 prologue/epilogue sequences generated by the compiler. Only basic
5306 @code{asm} statements can safely be included in naked functions
5307 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5308 basic @code{asm} and C code may appear to work, they cannot be
5309 depended upon to work reliably and are not supported.
5312 @cindex @code{reentrant} function attribute, MSP430
5313 Reentrant functions disable interrupts upon entry and enable them
5314 upon exit. Reentrant functions cannot also have the @code{naked}
5315 or @code{critical} attributes. They can have the @code{interrupt}
5319 @cindex @code{wakeup} function attribute, MSP430
5320 This attribute only applies to interrupt functions. It is silently
5321 ignored if applied to a non-interrupt function. A wakeup interrupt
5322 function will rouse the processor from any low-power state that it
5323 might be in when the function exits.
5328 @cindex @code{lower} function attribute, MSP430
5329 @cindex @code{upper} function attribute, MSP430
5330 @cindex @code{either} function attribute, MSP430
5331 On the MSP430 target these attributes can be used to specify whether
5332 the function or variable should be placed into low memory, high
5333 memory, or the placement should be left to the linker to decide. The
5334 attributes are only significant if compiling for the MSP430X
5335 architecture in the large memory model.
5337 The attributes work in conjunction with a linker script that has been
5338 augmented to specify where to place sections with a @code{.lower} and
5339 a @code{.upper} prefix. So, for example, as well as placing the
5340 @code{.data} section, the script also specifies the placement of a
5341 @code{.lower.data} and a @code{.upper.data} section. The intention
5342 is that @code{lower} sections are placed into a small but easier to
5343 access memory region and the upper sections are placed into a larger, but
5344 slower to access, region.
5346 The @code{either} attribute is special. It tells the linker to place
5347 the object into the corresponding @code{lower} section if there is
5348 room for it. If there is insufficient room then the object is placed
5349 into the corresponding @code{upper} section instead. Note that the
5350 placement algorithm is not very sophisticated. It does not attempt to
5351 find an optimal packing of the @code{lower} sections. It just makes
5352 one pass over the objects and does the best that it can. Using the
5353 @option{-ffunction-sections} and @option{-fdata-sections} command-line
5354 options can help the packing, however, since they produce smaller,
5355 easier to pack regions.
5358 @node NDS32 Function Attributes
5359 @subsection NDS32 Function Attributes
5361 These function attributes are supported by the NDS32 back end:
5365 @cindex @code{exception} function attribute
5366 @cindex exception handler functions, NDS32
5367 Use this attribute on the NDS32 target to indicate that the specified function
5368 is an exception handler. The compiler will generate corresponding sections
5369 for use in an exception handler.
5372 @cindex @code{interrupt} function attribute, NDS32
5373 On NDS32 target, this attribute indicates that the specified function
5374 is an interrupt handler. The compiler generates corresponding sections
5375 for use in an interrupt handler. You can use the following attributes
5376 to modify the behavior:
5379 @cindex @code{nested} function attribute, NDS32
5380 This interrupt service routine is interruptible.
5382 @cindex @code{not_nested} function attribute, NDS32
5383 This interrupt service routine is not interruptible.
5385 @cindex @code{nested_ready} function attribute, NDS32
5386 This interrupt service routine is interruptible after @code{PSW.GIE}
5387 (global interrupt enable) is set. This allows interrupt service routine to
5388 finish some short critical code before enabling interrupts.
5390 @cindex @code{save_all} function attribute, NDS32
5391 The system will help save all registers into stack before entering
5394 @cindex @code{partial_save} function attribute, NDS32
5395 The system will help save caller registers into stack before entering
5400 @cindex @code{naked} function attribute, NDS32
5401 This attribute allows the compiler to construct the
5402 requisite function declaration, while allowing the body of the
5403 function to be assembly code. The specified function will not have
5404 prologue/epilogue sequences generated by the compiler. Only basic
5405 @code{asm} statements can safely be included in naked functions
5406 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5407 basic @code{asm} and C code may appear to work, they cannot be
5408 depended upon to work reliably and are not supported.
5411 @cindex @code{reset} function attribute, NDS32
5412 @cindex reset handler functions
5413 Use this attribute on the NDS32 target to indicate that the specified function
5414 is a reset handler. The compiler will generate corresponding sections
5415 for use in a reset handler. You can use the following attributes
5416 to provide extra exception handling:
5419 @cindex @code{nmi} function attribute, NDS32
5420 Provide a user-defined function to handle NMI exception.
5422 @cindex @code{warm} function attribute, NDS32
5423 Provide a user-defined function to handle warm reset exception.
5427 @node Nios II Function Attributes
5428 @subsection Nios II Function Attributes
5430 These function attributes are supported by the Nios II back end:
5433 @item target (@var{options})
5434 @cindex @code{target} function attribute
5435 As discussed in @ref{Common Function Attributes}, this attribute
5436 allows specification of target-specific compilation options.
5438 When compiling for Nios II, the following options are allowed:
5441 @item custom-@var{insn}=@var{N}
5442 @itemx no-custom-@var{insn}
5443 @cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II
5444 @cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II
5445 Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a
5446 custom instruction with encoding @var{N} when generating code that uses
5447 @var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of
5448 the custom instruction @var{insn}.
5449 These target attributes correspond to the
5450 @option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}}
5451 command-line options, and support the same set of @var{insn} keywords.
5452 @xref{Nios II Options}, for more information.
5454 @item custom-fpu-cfg=@var{name}
5455 @cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II
5456 This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}}
5457 command-line option, to select a predefined set of custom instructions
5459 @xref{Nios II Options}, for more information.
5463 @node Nvidia PTX Function Attributes
5464 @subsection Nvidia PTX Function Attributes
5466 These function attributes are supported by the Nvidia PTX back end:
5470 @cindex @code{kernel} attribute, Nvidia PTX
5471 This attribute indicates that the corresponding function should be compiled
5472 as a kernel function, which can be invoked from the host via the CUDA RT
5474 By default functions are only callable only from other PTX functions.
5476 Kernel functions must have @code{void} return type.
5479 @node PowerPC Function Attributes
5480 @subsection PowerPC Function Attributes
5482 These function attributes are supported by the PowerPC back end:
5487 @cindex indirect calls, PowerPC
5488 @cindex @code{longcall} function attribute, PowerPC
5489 @cindex @code{shortcall} function attribute, PowerPC
5490 The @code{longcall} attribute
5491 indicates that the function might be far away from the call site and
5492 require a different (more expensive) calling sequence. The
5493 @code{shortcall} attribute indicates that the function is always close
5494 enough for the shorter calling sequence to be used. These attributes
5495 override both the @option{-mlongcall} switch and
5496 the @code{#pragma longcall} setting.
5498 @xref{RS/6000 and PowerPC Options}, for more information on whether long
5499 calls are necessary.
5501 @item target (@var{options})
5502 @cindex @code{target} function attribute
5503 As discussed in @ref{Common Function Attributes}, this attribute
5504 allows specification of target-specific compilation options.
5506 On the PowerPC, the following options are allowed:
5511 @cindex @code{target("altivec")} function attribute, PowerPC
5512 Generate code that uses (does not use) AltiVec instructions. In
5513 32-bit code, you cannot enable AltiVec instructions unless
5514 @option{-mabi=altivec} is used on the command line.
5518 @cindex @code{target("cmpb")} function attribute, PowerPC
5519 Generate code that uses (does not use) the compare bytes instruction
5520 implemented on the POWER6 processor and other processors that support
5521 the PowerPC V2.05 architecture.
5525 @cindex @code{target("dlmzb")} function attribute, PowerPC
5526 Generate code that uses (does not use) the string-search @samp{dlmzb}
5527 instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
5528 generated by default when targeting those processors.
5532 @cindex @code{target("fprnd")} function attribute, PowerPC
5533 Generate code that uses (does not use) the FP round to integer
5534 instructions implemented on the POWER5+ processor and other processors
5535 that support the PowerPC V2.03 architecture.
5539 @cindex @code{target("hard-dfp")} function attribute, PowerPC
5540 Generate code that uses (does not use) the decimal floating-point
5541 instructions implemented on some POWER processors.
5545 @cindex @code{target("isel")} function attribute, PowerPC
5546 Generate code that uses (does not use) ISEL instruction.
5550 @cindex @code{target("mfcrf")} function attribute, PowerPC
5551 Generate code that uses (does not use) the move from condition
5552 register field instruction implemented on the POWER4 processor and
5553 other processors that support the PowerPC V2.01 architecture.
5557 @cindex @code{target("mulhw")} function attribute, PowerPC
5558 Generate code that uses (does not use) the half-word multiply and
5559 multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
5560 These instructions are generated by default when targeting those
5565 @cindex @code{target("multiple")} function attribute, PowerPC
5566 Generate code that uses (does not use) the load multiple word
5567 instructions and the store multiple word instructions.
5571 @cindex @code{target("update")} function attribute, PowerPC
5572 Generate code that uses (does not use) the load or store instructions
5573 that update the base register to the address of the calculated memory
5578 @cindex @code{target("popcntb")} function attribute, PowerPC
5579 Generate code that uses (does not use) the popcount and double-precision
5580 FP reciprocal estimate instruction implemented on the POWER5
5581 processor and other processors that support the PowerPC V2.02
5586 @cindex @code{target("popcntd")} function attribute, PowerPC
5587 Generate code that uses (does not use) the popcount instruction
5588 implemented on the POWER7 processor and other processors that support
5589 the PowerPC V2.06 architecture.
5591 @item powerpc-gfxopt
5592 @itemx no-powerpc-gfxopt
5593 @cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
5594 Generate code that uses (does not use) the optional PowerPC
5595 architecture instructions in the Graphics group, including
5596 floating-point select.
5599 @itemx no-powerpc-gpopt
5600 @cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
5601 Generate code that uses (does not use) the optional PowerPC
5602 architecture instructions in the General Purpose group, including
5603 floating-point square root.
5605 @item recip-precision
5606 @itemx no-recip-precision
5607 @cindex @code{target("recip-precision")} function attribute, PowerPC
5608 Assume (do not assume) that the reciprocal estimate instructions
5609 provide higher-precision estimates than is mandated by the PowerPC
5614 @cindex @code{target("string")} function attribute, PowerPC
5615 Generate code that uses (does not use) the load string instructions
5616 and the store string word instructions to save multiple registers and
5617 do small block moves.
5621 @cindex @code{target("vsx")} function attribute, PowerPC
5622 Generate code that uses (does not use) vector/scalar (VSX)
5623 instructions, and also enable the use of built-in functions that allow
5624 more direct access to the VSX instruction set. In 32-bit code, you
5625 cannot enable VSX or AltiVec instructions unless
5626 @option{-mabi=altivec} is used on the command line.
5630 @cindex @code{target("friz")} function attribute, PowerPC
5631 Generate (do not generate) the @code{friz} instruction when the
5632 @option{-funsafe-math-optimizations} option is used to optimize
5633 rounding a floating-point value to 64-bit integer and back to floating
5634 point. The @code{friz} instruction does not return the same value if
5635 the floating-point number is too large to fit in an integer.
5637 @item avoid-indexed-addresses
5638 @itemx no-avoid-indexed-addresses
5639 @cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
5640 Generate code that tries to avoid (not avoid) the use of indexed load
5641 or store instructions.
5645 @cindex @code{target("paired")} function attribute, PowerPC
5646 Generate code that uses (does not use) the generation of PAIRED simd
5651 @cindex @code{target("longcall")} function attribute, PowerPC
5652 Generate code that assumes (does not assume) that all calls are far
5653 away so that a longer more expensive calling sequence is required.
5656 @cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
5657 Specify the architecture to generate code for when compiling the
5658 function. If you select the @code{target("cpu=power7")} attribute when
5659 generating 32-bit code, VSX and AltiVec instructions are not generated
5660 unless you use the @option{-mabi=altivec} option on the command line.
5662 @item tune=@var{TUNE}
5663 @cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
5664 Specify the architecture to tune for when compiling the function. If
5665 you do not specify the @code{target("tune=@var{TUNE}")} attribute and
5666 you do specify the @code{target("cpu=@var{CPU}")} attribute,
5667 compilation tunes for the @var{CPU} architecture, and not the
5668 default tuning specified on the command line.
5671 On the PowerPC, the inliner does not inline a
5672 function that has different target options than the caller, unless the
5673 callee has a subset of the target options of the caller.
5676 @node RISC-V Function Attributes
5677 @subsection RISC-V Function Attributes
5679 These function attributes are supported by the RISC-V back end:
5683 @cindex @code{naked} function attribute, RISC-V
5684 This attribute allows the compiler to construct the
5685 requisite function declaration, while allowing the body of the
5686 function to be assembly code. The specified function will not have
5687 prologue/epilogue sequences generated by the compiler. Only basic
5688 @code{asm} statements can safely be included in naked functions
5689 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5690 basic @code{asm} and C code may appear to work, they cannot be
5691 depended upon to work reliably and are not supported.
5694 @cindex @code{interrupt} function attribute, RISC-V
5695 Use this attribute to indicate that the specified function is an interrupt
5696 handler. The compiler generates function entry and exit sequences suitable
5697 for use in an interrupt handler when this attribute is present.
5699 You can specify the kind of interrupt to be handled by adding an optional
5700 parameter to the interrupt attribute like this:
5703 void f (void) __attribute__ ((interrupt ("user")));
5706 Permissible values for this parameter are @code{user}, @code{supervisor},
5707 and @code{machine}. If there is no parameter, then it defaults to
5711 @node RL78 Function Attributes
5712 @subsection RL78 Function Attributes
5714 These function attributes are supported by the RL78 back end:
5718 @itemx brk_interrupt
5719 @cindex @code{interrupt} function attribute, RL78
5720 @cindex @code{brk_interrupt} function attribute, RL78
5721 These attributes indicate
5722 that the specified function is an interrupt handler. The compiler generates
5723 function entry and exit sequences suitable for use in an interrupt handler
5724 when this attribute is present.
5726 Use @code{brk_interrupt} instead of @code{interrupt} for
5727 handlers intended to be used with the @code{BRK} opcode (i.e.@: those
5728 that must end with @code{RETB} instead of @code{RETI}).
5731 @cindex @code{naked} function attribute, RL78
5732 This attribute allows the compiler to construct the
5733 requisite function declaration, while allowing the body of the
5734 function to be assembly code. The specified function will not have
5735 prologue/epilogue sequences generated by the compiler. Only basic
5736 @code{asm} statements can safely be included in naked functions
5737 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5738 basic @code{asm} and C code may appear to work, they cannot be
5739 depended upon to work reliably and are not supported.
5742 @node RX Function Attributes
5743 @subsection RX Function Attributes
5745 These function attributes are supported by the RX back end:
5748 @item fast_interrupt
5749 @cindex @code{fast_interrupt} function attribute, RX
5750 Use this attribute on the RX port to indicate that the specified
5751 function is a fast interrupt handler. This is just like the
5752 @code{interrupt} attribute, except that @code{freit} is used to return
5753 instead of @code{reit}.
5756 @cindex @code{interrupt} function attribute, RX
5757 Use this attribute to indicate
5758 that the specified function is an interrupt handler. The compiler generates
5759 function entry and exit sequences suitable for use in an interrupt handler
5760 when this attribute is present.
5762 On RX and RL78 targets, you may specify one or more vector numbers as arguments
5763 to the attribute, as well as naming an alternate table name.
5764 Parameters are handled sequentially, so one handler can be assigned to
5765 multiple entries in multiple tables. One may also pass the magic
5766 string @code{"$default"} which causes the function to be used for any
5767 unfilled slots in the current table.
5769 This example shows a simple assignment of a function to one vector in
5770 the default table (note that preprocessor macros may be used for
5771 chip-specific symbolic vector names):
5773 void __attribute__ ((interrupt (5))) txd1_handler ();
5776 This example assigns a function to two slots in the default table
5777 (using preprocessor macros defined elsewhere) and makes it the default
5778 for the @code{dct} table:
5780 void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
5785 @cindex @code{naked} function attribute, RX
5786 This attribute allows the compiler to construct the
5787 requisite function declaration, while allowing the body of the
5788 function to be assembly code. The specified function will not have
5789 prologue/epilogue sequences generated by the compiler. Only basic
5790 @code{asm} statements can safely be included in naked functions
5791 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5792 basic @code{asm} and C code may appear to work, they cannot be
5793 depended upon to work reliably and are not supported.
5796 @cindex @code{vector} function attribute, RX
5797 This RX attribute is similar to the @code{interrupt} attribute, including its
5798 parameters, but does not make the function an interrupt-handler type
5799 function (i.e.@: it retains the normal C function calling ABI). See the
5800 @code{interrupt} attribute for a description of its arguments.
5803 @node S/390 Function Attributes
5804 @subsection S/390 Function Attributes
5806 These function attributes are supported on the S/390:
5809 @item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
5810 @cindex @code{hotpatch} function attribute, S/390
5812 On S/390 System z targets, you can use this function attribute to
5813 make GCC generate a ``hot-patching'' function prologue. If the
5814 @option{-mhotpatch=} command-line option is used at the same time,
5815 the @code{hotpatch} attribute takes precedence. The first of the
5816 two arguments specifies the number of halfwords to be added before
5817 the function label. A second argument can be used to specify the
5818 number of halfwords to be added after the function label. For
5819 both arguments the maximum allowed value is 1000000.
5821 If both arguments are zero, hotpatching is disabled.
5823 @item target (@var{options})
5824 @cindex @code{target} function attribute
5825 As discussed in @ref{Common Function Attributes}, this attribute
5826 allows specification of target-specific compilation options.
5828 On S/390, the following options are supported:
5836 @item warn-framesize=
5848 @itemx no-packed-stack
5850 @itemx no-small-exec
5853 @item warn-dynamicstack
5854 @itemx no-warn-dynamicstack
5857 The options work exactly like the S/390 specific command line
5858 options (without the prefix @option{-m}) except that they do not
5859 change any feature macros. For example,
5862 @code{target("no-vx")}
5865 does not undefine the @code{__VEC__} macro.
5868 @node SH Function Attributes
5869 @subsection SH Function Attributes
5871 These function attributes are supported on the SH family of processors:
5874 @item function_vector
5875 @cindex @code{function_vector} function attribute, SH
5876 @cindex calling functions through the function vector on SH2A
5877 On SH2A targets, this attribute declares a function to be called using the
5878 TBR relative addressing mode. The argument to this attribute is the entry
5879 number of the same function in a vector table containing all the TBR
5880 relative addressable functions. For correct operation the TBR must be setup
5881 accordingly to point to the start of the vector table before any functions with
5882 this attribute are invoked. Usually a good place to do the initialization is
5883 the startup routine. The TBR relative vector table can have at max 256 function
5884 entries. The jumps to these functions are generated using a SH2A specific,
5885 non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD
5886 from GNU binutils version 2.7 or later for this attribute to work correctly.
5888 In an application, for a function being called once, this attribute
5889 saves at least 8 bytes of code; and if other successive calls are being
5890 made to the same function, it saves 2 bytes of code per each of these
5893 @item interrupt_handler
5894 @cindex @code{interrupt_handler} function attribute, SH
5895 Use this attribute to
5896 indicate that the specified function is an interrupt handler. The compiler
5897 generates function entry and exit sequences suitable for use in an
5898 interrupt handler when this attribute is present.
5900 @item nosave_low_regs
5901 @cindex @code{nosave_low_regs} function attribute, SH
5902 Use this attribute on SH targets to indicate that an @code{interrupt_handler}
5903 function should not save and restore registers R0..R7. This can be used on SH3*
5904 and SH4* targets that have a second R0..R7 register bank for non-reentrant
5908 @cindex @code{renesas} function attribute, SH
5909 On SH targets this attribute specifies that the function or struct follows the
5913 @cindex @code{resbank} function attribute, SH
5914 On the SH2A target, this attribute enables the high-speed register
5915 saving and restoration using a register bank for @code{interrupt_handler}
5916 routines. Saving to the bank is performed automatically after the CPU
5917 accepts an interrupt that uses a register bank.
5919 The nineteen 32-bit registers comprising general register R0 to R14,
5920 control register GBR, and system registers MACH, MACL, and PR and the
5921 vector table address offset are saved into a register bank. Register
5922 banks are stacked in first-in last-out (FILO) sequence. Restoration
5923 from the bank is executed by issuing a RESBANK instruction.
5926 @cindex @code{sp_switch} function attribute, SH
5927 Use this attribute on the SH to indicate an @code{interrupt_handler}
5928 function should switch to an alternate stack. It expects a string
5929 argument that names a global variable holding the address of the
5934 void f () __attribute__ ((interrupt_handler,
5935 sp_switch ("alt_stack")));
5939 @cindex @code{trap_exit} function attribute, SH
5940 Use this attribute on the SH for an @code{interrupt_handler} to return using
5941 @code{trapa} instead of @code{rte}. This attribute expects an integer
5942 argument specifying the trap number to be used.
5945 @cindex @code{trapa_handler} function attribute, SH
5946 On SH targets this function attribute is similar to @code{interrupt_handler}
5947 but it does not save and restore all registers.
5950 @node Symbian OS Function Attributes
5951 @subsection Symbian OS Function Attributes
5953 @xref{Microsoft Windows Function Attributes}, for discussion of the
5954 @code{dllexport} and @code{dllimport} attributes.
5956 @node V850 Function Attributes
5957 @subsection V850 Function Attributes
5959 The V850 back end supports these function attributes:
5963 @itemx interrupt_handler
5964 @cindex @code{interrupt} function attribute, V850
5965 @cindex @code{interrupt_handler} function attribute, V850
5966 Use these attributes to indicate
5967 that the specified function is an interrupt handler. The compiler generates
5968 function entry and exit sequences suitable for use in an interrupt handler
5969 when either attribute is present.
5972 @node Visium Function Attributes
5973 @subsection Visium Function Attributes
5975 These function attributes are supported by the Visium back end:
5979 @cindex @code{interrupt} function attribute, Visium
5980 Use this attribute to indicate
5981 that the specified function is an interrupt handler. The compiler generates
5982 function entry and exit sequences suitable for use in an interrupt handler
5983 when this attribute is present.
5986 @node x86 Function Attributes
5987 @subsection x86 Function Attributes
5989 These function attributes are supported by the x86 back end:
5993 @cindex @code{cdecl} function attribute, x86-32
5994 @cindex functions that pop the argument stack on x86-32
5996 On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
5997 assume that the calling function pops off the stack space used to
5998 pass arguments. This is
5999 useful to override the effects of the @option{-mrtd} switch.
6002 @cindex @code{fastcall} function attribute, x86-32
6003 @cindex functions that pop the argument stack on x86-32
6004 On x86-32 targets, the @code{fastcall} attribute causes the compiler to
6005 pass the first argument (if of integral type) in the register ECX and
6006 the second argument (if of integral type) in the register EDX@. Subsequent
6007 and other typed arguments are passed on the stack. The called function
6008 pops the arguments off the stack. If the number of arguments is variable all
6009 arguments are pushed on the stack.
6012 @cindex @code{thiscall} function attribute, x86-32
6013 @cindex functions that pop the argument stack on x86-32
6014 On x86-32 targets, the @code{thiscall} attribute causes the compiler to
6015 pass the first argument (if of integral type) in the register ECX.
6016 Subsequent and other typed arguments are passed on the stack. The called
6017 function pops the arguments off the stack.
6018 If the number of arguments is variable all arguments are pushed on the
6020 The @code{thiscall} attribute is intended for C++ non-static member functions.
6021 As a GCC extension, this calling convention can be used for C functions
6022 and for static member methods.
6026 @cindex @code{ms_abi} function attribute, x86
6027 @cindex @code{sysv_abi} function attribute, x86
6029 On 32-bit and 64-bit x86 targets, you can use an ABI attribute
6030 to indicate which calling convention should be used for a function. The
6031 @code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
6032 while the @code{sysv_abi} attribute tells the compiler to use the ABI
6033 used on GNU/Linux and other systems. The default is to use the Microsoft ABI
6034 when targeting Windows. On all other systems, the default is the x86/AMD ABI.
6036 Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
6037 requires the @option{-maccumulate-outgoing-args} option.
6039 @item callee_pop_aggregate_return (@var{number})
6040 @cindex @code{callee_pop_aggregate_return} function attribute, x86
6042 On x86-32 targets, you can use this attribute to control how
6043 aggregates are returned in memory. If the caller is responsible for
6044 popping the hidden pointer together with the rest of the arguments, specify
6045 @var{number} equal to zero. If callee is responsible for popping the
6046 hidden pointer, specify @var{number} equal to one.
6048 The default x86-32 ABI assumes that the callee pops the
6049 stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
6050 the compiler assumes that the
6051 caller pops the stack for hidden pointer.
6053 @item ms_hook_prologue
6054 @cindex @code{ms_hook_prologue} function attribute, x86
6056 On 32-bit and 64-bit x86 targets, you can use
6057 this function attribute to make GCC generate the ``hot-patching'' function
6058 prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
6062 @cindex @code{naked} function attribute, x86
6063 This attribute allows the compiler to construct the
6064 requisite function declaration, while allowing the body of the
6065 function to be assembly code. The specified function will not have
6066 prologue/epilogue sequences generated by the compiler. Only basic
6067 @code{asm} statements can safely be included in naked functions
6068 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6069 basic @code{asm} and C code may appear to work, they cannot be
6070 depended upon to work reliably and are not supported.
6072 @item regparm (@var{number})
6073 @cindex @code{regparm} function attribute, x86
6074 @cindex functions that are passed arguments in registers on x86-32
6075 On x86-32 targets, the @code{regparm} attribute causes the compiler to
6076 pass arguments number one to @var{number} if they are of integral type
6077 in registers EAX, EDX, and ECX instead of on the stack. Functions that
6078 take a variable number of arguments continue to be passed all of their
6079 arguments on the stack.
6081 Beware that on some ELF systems this attribute is unsuitable for
6082 global functions in shared libraries with lazy binding (which is the
6083 default). Lazy binding sends the first call via resolving code in
6084 the loader, which might assume EAX, EDX and ECX can be clobbered, as
6085 per the standard calling conventions. Solaris 8 is affected by this.
6086 Systems with the GNU C Library version 2.1 or higher
6087 and FreeBSD are believed to be
6088 safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
6089 disabled with the linker or the loader if desired, to avoid the
6093 @cindex @code{sseregparm} function attribute, x86
6094 On x86-32 targets with SSE support, the @code{sseregparm} attribute
6095 causes the compiler to pass up to 3 floating-point arguments in
6096 SSE registers instead of on the stack. Functions that take a
6097 variable number of arguments continue to pass all of their
6098 floating-point arguments on the stack.
6100 @item force_align_arg_pointer
6101 @cindex @code{force_align_arg_pointer} function attribute, x86
6102 On x86 targets, the @code{force_align_arg_pointer} attribute may be
6103 applied to individual function definitions, generating an alternate
6104 prologue and epilogue that realigns the run-time stack if necessary.
6105 This supports mixing legacy codes that run with a 4-byte aligned stack
6106 with modern codes that keep a 16-byte stack for SSE compatibility.
6109 @cindex @code{stdcall} function attribute, x86-32
6110 @cindex functions that pop the argument stack on x86-32
6111 On x86-32 targets, the @code{stdcall} attribute causes the compiler to
6112 assume that the called function pops off the stack space used to
6113 pass arguments, unless it takes a variable number of arguments.
6115 @item no_caller_saved_registers
6116 @cindex @code{no_caller_saved_registers} function attribute, x86
6117 Use this attribute to indicate that the specified function has no
6118 caller-saved registers. That is, all registers are callee-saved. For
6119 example, this attribute can be used for a function called from an
6120 interrupt handler. The compiler generates proper function entry and
6121 exit sequences to save and restore any modified registers, except for
6122 the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87
6123 states, the GCC option @option{-mgeneral-regs-only} should be used to
6124 compile functions with @code{no_caller_saved_registers} attribute.
6127 @cindex @code{interrupt} function attribute, x86
6128 Use this attribute to indicate that the specified function is an
6129 interrupt handler or an exception handler (depending on parameters passed
6130 to the function, explained further). The compiler generates function
6131 entry and exit sequences suitable for use in an interrupt handler when
6132 this attribute is present. The @code{IRET} instruction, instead of the
6133 @code{RET} instruction, is used to return from interrupt handlers. All
6134 registers, except for the EFLAGS register which is restored by the
6135 @code{IRET} instruction, are preserved by the compiler. Since GCC
6136 doesn't preserve SSE, MMX nor x87 states, the GCC option
6137 @option{-mgeneral-regs-only} should be used to compile interrupt and
6140 Any interruptible-without-stack-switch code must be compiled with
6141 @option{-mno-red-zone} since interrupt handlers can and will, because
6142 of the hardware design, touch the red zone.
6144 An interrupt handler must be declared with a mandatory pointer
6148 struct interrupt_frame;
6150 __attribute__ ((interrupt))
6152 f (struct interrupt_frame *frame)
6158 and you must define @code{struct interrupt_frame} as described in the
6161 Exception handlers differ from interrupt handlers because the system
6162 pushes an error code on the stack. An exception handler declaration is
6163 similar to that for an interrupt handler, but with a different mandatory
6164 function signature. The compiler arranges to pop the error code off the
6165 stack before the @code{IRET} instruction.
6169 typedef unsigned long long int uword_t;
6171 typedef unsigned int uword_t;
6174 struct interrupt_frame;
6176 __attribute__ ((interrupt))
6178 f (struct interrupt_frame *frame, uword_t error_code)
6184 Exception handlers should only be used for exceptions that push an error
6185 code; you should use an interrupt handler in other cases. The system
6186 will crash if the wrong kind of handler is used.
6188 @item target (@var{options})
6189 @cindex @code{target} function attribute
6190 As discussed in @ref{Common Function Attributes}, this attribute
6191 allows specification of target-specific compilation options.
6193 On the x86, the following options are allowed:
6197 @cindex @code{target("3dnow")} function attribute, x86
6198 Enable/disable the generation of the 3DNow!@: instructions.
6202 @cindex @code{target("3dnowa")} function attribute, x86
6203 Enable/disable the generation of the enhanced 3DNow!@: instructions.
6207 @cindex @code{target("abm")} function attribute, x86
6208 Enable/disable the generation of the advanced bit instructions.
6212 @cindex @code{target("adx")} function attribute, x86
6213 Enable/disable the generation of the ADX instructions.
6217 @cindex @code{target("aes")} function attribute, x86
6218 Enable/disable the generation of the AES instructions.
6222 @cindex @code{target("avx")} function attribute, x86
6223 Enable/disable the generation of the AVX instructions.
6227 @cindex @code{target("avx2")} function attribute, x86
6228 Enable/disable the generation of the AVX2 instructions.
6231 @itemx no-avx5124fmaps
6232 @cindex @code{target("avx5124fmaps")} function attribute, x86
6233 Enable/disable the generation of the AVX5124FMAPS instructions.
6236 @itemx no-avx5124vnniw
6237 @cindex @code{target("avx5124vnniw")} function attribute, x86
6238 Enable/disable the generation of the AVX5124VNNIW instructions.
6241 @itemx no-avx512bitalg
6242 @cindex @code{target("avx512bitalg")} function attribute, x86
6243 Enable/disable the generation of the AVX512BITALG instructions.
6247 @cindex @code{target("avx512bw")} function attribute, x86
6248 Enable/disable the generation of the AVX512BW instructions.
6252 @cindex @code{target("avx512cd")} function attribute, x86
6253 Enable/disable the generation of the AVX512CD instructions.
6257 @cindex @code{target("avx512dq")} function attribute, x86
6258 Enable/disable the generation of the AVX512DQ instructions.
6262 @cindex @code{target("avx512er")} function attribute, x86
6263 Enable/disable the generation of the AVX512ER instructions.
6267 @cindex @code{target("avx512f")} function attribute, x86
6268 Enable/disable the generation of the AVX512F instructions.
6271 @itemx no-avx512ifma
6272 @cindex @code{target("avx512ifma")} function attribute, x86
6273 Enable/disable the generation of the AVX512IFMA instructions.
6277 @cindex @code{target("avx512pf")} function attribute, x86
6278 Enable/disable the generation of the AVX512PF instructions.
6281 @itemx no-avx512vbmi
6282 @cindex @code{target("avx512vbmi")} function attribute, x86
6283 Enable/disable the generation of the AVX512VBMI instructions.
6286 @itemx no-avx512vbmi2
6287 @cindex @code{target("avx512vbmi2")} function attribute, x86
6288 Enable/disable the generation of the AVX512VBMI2 instructions.
6292 @cindex @code{target("avx512vl")} function attribute, x86
6293 Enable/disable the generation of the AVX512VL instructions.
6296 @itemx no-avx512vnni
6297 @cindex @code{target("avx512vnni")} function attribute, x86
6298 Enable/disable the generation of the AVX512VNNI instructions.
6300 @item avx512vpopcntdq
6301 @itemx no-avx512vpopcntdq
6302 @cindex @code{target("avx512vpopcntdq")} function attribute, x86
6303 Enable/disable the generation of the AVX512VPOPCNTDQ instructions.
6307 @cindex @code{target("bmi")} function attribute, x86
6308 Enable/disable the generation of the BMI instructions.
6312 @cindex @code{target("bmi2")} function attribute, x86
6313 Enable/disable the generation of the BMI2 instructions.
6317 @cindex @code{target("cldemote")} function attribute, x86
6318 Enable/disable the generation of the CLDEMOTE instructions.
6321 @itemx no-clflushopt
6322 @cindex @code{target("clflushopt")} function attribute, x86
6323 Enable/disable the generation of the CLFLUSHOPT instructions.
6327 @cindex @code{target("clwb")} function attribute, x86
6328 Enable/disable the generation of the CLWB instructions.
6332 @cindex @code{target("clzero")} function attribute, x86
6333 Enable/disable the generation of the CLZERO instructions.
6337 @cindex @code{target("crc32")} function attribute, x86
6338 Enable/disable the generation of the CRC32 instructions.
6342 @cindex @code{target("cx16")} function attribute, x86
6343 Enable/disable the generation of the CMPXCHG16B instructions.
6346 @cindex @code{target("default")} function attribute, x86
6347 @xref{Function Multiversioning}, where it is used to specify the
6348 default function version.
6352 @cindex @code{target("f16c")} function attribute, x86
6353 Enable/disable the generation of the F16C instructions.
6357 @cindex @code{target("fma")} function attribute, x86
6358 Enable/disable the generation of the FMA instructions.
6362 @cindex @code{target("fma4")} function attribute, x86
6363 Enable/disable the generation of the FMA4 instructions.
6367 @cindex @code{target("fsgsbase")} function attribute, x86
6368 Enable/disable the generation of the FSGSBASE instructions.
6372 @cindex @code{target("fxsr")} function attribute, x86
6373 Enable/disable the generation of the FXSR instructions.
6377 @cindex @code{target("gfni")} function attribute, x86
6378 Enable/disable the generation of the GFNI instructions.
6382 @cindex @code{target("hle")} function attribute, x86
6383 Enable/disable the generation of the HLE instruction prefixes.
6387 @cindex @code{target("lwp")} function attribute, x86
6388 Enable/disable the generation of the LWP instructions.
6392 @cindex @code{target("lzcnt")} function attribute, x86
6393 Enable/disable the generation of the LZCNT instructions.
6397 @cindex @code{target("mmx")} function attribute, x86
6398 Enable/disable the generation of the MMX instructions.
6402 @cindex @code{target("movbe")} function attribute, x86
6403 Enable/disable the generation of the MOVBE instructions.
6407 @cindex @code{target("movdir64b")} function attribute, x86
6408 Enable/disable the generation of the MOVDIR64B instructions.
6412 @cindex @code{target("movdiri")} function attribute, x86
6413 Enable/disable the generation of the MOVDIRI instructions.
6417 @cindex @code{target("mwaitx")} function attribute, x86
6418 Enable/disable the generation of the MWAITX instructions.
6422 @cindex @code{target("pclmul")} function attribute, x86
6423 Enable/disable the generation of the PCLMUL instructions.
6427 @cindex @code{target("pconfig")} function attribute, x86
6428 Enable/disable the generation of the PCONFIG instructions.
6432 @cindex @code{target("pku")} function attribute, x86
6433 Enable/disable the generation of the PKU instructions.
6437 @cindex @code{target("popcnt")} function attribute, x86
6438 Enable/disable the generation of the POPCNT instruction.
6441 @itemx no-prefetchwt1
6442 @cindex @code{target("prefetchwt1")} function attribute, x86
6443 Enable/disable the generation of the PREFETCHWT1 instructions.
6447 @cindex @code{target("prfchw")} function attribute, x86
6448 Enable/disable the generation of the PREFETCHW instruction.
6452 @cindex @code{target("ptwrite")} function attribute, x86
6453 Enable/disable the generation of the PTWRITE instructions.
6457 @cindex @code{target("rdpid")} function attribute, x86
6458 Enable/disable the generation of the RDPID instructions.
6462 @cindex @code{target("rdrnd")} function attribute, x86
6463 Enable/disable the generation of the RDRND instructions.
6467 @cindex @code{target("rdseed")} function attribute, x86
6468 Enable/disable the generation of the RDSEED instructions.
6472 @cindex @code{target("rtm")} function attribute, x86
6473 Enable/disable the generation of the RTM instructions.
6477 @cindex @code{target("sahf")} function attribute, x86
6478 Enable/disable the generation of the SAHF instructions.
6482 @cindex @code{target("sgx")} function attribute, x86
6483 Enable/disable the generation of the SGX instructions.
6487 @cindex @code{target("sha")} function attribute, x86
6488 Enable/disable the generation of the SHA instructions.
6492 @cindex @code{target("shstk")} function attribute, x86
6493 Enable/disable the shadow stack built-in functions from CET.
6497 @cindex @code{target("sse")} function attribute, x86
6498 Enable/disable the generation of the SSE instructions.
6502 @cindex @code{target("sse2")} function attribute, x86
6503 Enable/disable the generation of the SSE2 instructions.
6507 @cindex @code{target("sse3")} function attribute, x86
6508 Enable/disable the generation of the SSE3 instructions.
6512 @cindex @code{target("sse4")} function attribute, x86
6513 Enable/disable the generation of the SSE4 instructions (both SSE4.1
6518 @cindex @code{target("sse4.1")} function attribute, x86
6519 Enable/disable the generation of the sse4.1 instructions.
6523 @cindex @code{target("sse4.2")} function attribute, x86
6524 Enable/disable the generation of the sse4.2 instructions.
6528 @cindex @code{target("sse4a")} function attribute, x86
6529 Enable/disable the generation of the SSE4A instructions.
6533 @cindex @code{target("ssse3")} function attribute, x86
6534 Enable/disable the generation of the SSSE3 instructions.
6538 @cindex @code{target("tbm")} function attribute, x86
6539 Enable/disable the generation of the TBM instructions.
6543 @cindex @code{target("vaes")} function attribute, x86
6544 Enable/disable the generation of the VAES instructions.
6547 @itemx no-vpclmulqdq
6548 @cindex @code{target("vpclmulqdq")} function attribute, x86
6549 Enable/disable the generation of the VPCLMULQDQ instructions.
6553 @cindex @code{target("waitpkg")} function attribute, x86
6554 Enable/disable the generation of the WAITPKG instructions.
6558 @cindex @code{target("wbnoinvd")} function attribute, x86
6559 Enable/disable the generation of the WBNOINVD instructions.
6563 @cindex @code{target("xop")} function attribute, x86
6564 Enable/disable the generation of the XOP instructions.
6568 @cindex @code{target("xsave")} function attribute, x86
6569 Enable/disable the generation of the XSAVE instructions.
6573 @cindex @code{target("xsavec")} function attribute, x86
6574 Enable/disable the generation of the XSAVEC instructions.
6578 @cindex @code{target("xsaveopt")} function attribute, x86
6579 Enable/disable the generation of the XSAVEOPT instructions.
6583 @cindex @code{target("xsaves")} function attribute, x86
6584 Enable/disable the generation of the XSAVES instructions.
6588 @cindex @code{target("cld")} function attribute, x86
6589 Enable/disable the generation of the CLD before string moves.
6591 @item fancy-math-387
6592 @itemx no-fancy-math-387
6593 @cindex @code{target("fancy-math-387")} function attribute, x86
6594 Enable/disable the generation of the @code{sin}, @code{cos}, and
6595 @code{sqrt} instructions on the 387 floating-point unit.
6599 @cindex @code{target("ieee-fp")} function attribute, x86
6600 Enable/disable the generation of floating point that depends on IEEE arithmetic.
6602 @item inline-all-stringops
6603 @itemx no-inline-all-stringops
6604 @cindex @code{target("inline-all-stringops")} function attribute, x86
6605 Enable/disable inlining of string operations.
6607 @item inline-stringops-dynamically
6608 @itemx no-inline-stringops-dynamically
6609 @cindex @code{target("inline-stringops-dynamically")} function attribute, x86
6610 Enable/disable the generation of the inline code to do small string
6611 operations and calling the library routines for large operations.
6613 @item align-stringops
6614 @itemx no-align-stringops
6615 @cindex @code{target("align-stringops")} function attribute, x86
6616 Do/do not align destination of inlined string operations.
6620 @cindex @code{target("recip")} function attribute, x86
6621 Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
6622 instructions followed an additional Newton-Raphson step instead of
6623 doing a floating-point division.
6625 @item arch=@var{ARCH}
6626 @cindex @code{target("arch=@var{ARCH}")} function attribute, x86
6627 Specify the architecture to generate code for in compiling the function.
6629 @item tune=@var{TUNE}
6630 @cindex @code{target("tune=@var{TUNE}")} function attribute, x86
6631 Specify the architecture to tune for in compiling the function.
6633 @item fpmath=@var{FPMATH}
6634 @cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
6635 Specify which floating-point unit to use. You must specify the
6636 @code{target("fpmath=sse,387")} option as
6637 @code{target("fpmath=sse+387")} because the comma would separate
6640 @item indirect_branch("@var{choice}")
6641 @cindex @code{indirect_branch} function attribute, x86
6642 On x86 targets, the @code{indirect_branch} attribute causes the compiler
6643 to convert indirect call and jump with @var{choice}. @samp{keep}
6644 keeps indirect call and jump unmodified. @samp{thunk} converts indirect
6645 call and jump to call and return thunk. @samp{thunk-inline} converts
6646 indirect call and jump to inlined call and return thunk.
6647 @samp{thunk-extern} converts indirect call and jump to external call
6648 and return thunk provided in a separate object file.
6650 @item function_return("@var{choice}")
6651 @cindex @code{function_return} function attribute, x86
6652 On x86 targets, the @code{function_return} attribute causes the compiler
6653 to convert function return with @var{choice}. @samp{keep} keeps function
6654 return unmodified. @samp{thunk} converts function return to call and
6655 return thunk. @samp{thunk-inline} converts function return to inlined
6656 call and return thunk. @samp{thunk-extern} converts function return to
6657 external call and return thunk provided in a separate object file.
6660 @cindex @code{nocf_check} function attribute
6661 The @code{nocf_check} attribute on a function is used to inform the
6662 compiler that the function's prologue should not be instrumented when
6663 compiled with the @option{-fcf-protection=branch} option. The
6664 compiler assumes that the function's address is a valid target for a
6665 control-flow transfer.
6667 The @code{nocf_check} attribute on a type of pointer to function is
6668 used to inform the compiler that a call through the pointer should
6669 not be instrumented when compiled with the
6670 @option{-fcf-protection=branch} option. The compiler assumes
6671 that the function's address from the pointer is a valid target for
6672 a control-flow transfer. A direct function call through a function
6673 name is assumed to be a safe call thus direct calls are not
6674 instrumented by the compiler.
6676 The @code{nocf_check} attribute is applied to an object's type.
6677 In case of assignment of a function address or a function pointer to
6678 another pointer, the attribute is not carried over from the right-hand
6679 object's type; the type of left-hand object stays unchanged. The
6680 compiler checks for @code{nocf_check} attribute mismatch and reports
6681 a warning in case of mismatch.
6685 int foo (void) __attribute__(nocf_check);
6686 void (*foo1)(void) __attribute__(nocf_check);
6689 /* foo's address is assumed to be valid. */
6693 /* This call site is not checked for control-flow
6697 /* A warning is issued about attribute mismatch. */
6700 /* This call site is still not checked. */
6703 /* This call site is checked. */
6706 /* A warning is issued about attribute mismatch. */
6709 /* This call site is still checked. */
6717 @cindex @code{cf_check} function attribute, x86
6719 The @code{cf_check} attribute on a function is used to inform the
6720 compiler that ENDBR instruction should be placed at the function
6721 entry when @option{-fcf-protection=branch} is enabled.
6723 @item indirect_return
6724 @cindex @code{indirect_return} function attribute, x86
6726 The @code{indirect_return} attribute can be applied to a function,
6727 as well as variable or type of function pointer to inform the
6728 compiler that the function may return via indirect branch.
6730 @item fentry_name("@var{name}")
6731 @cindex @code{fentry_name} function attribute, x86
6732 On x86 targets, the @code{fentry_name} attribute sets the function to
6733 call on function entry when function instrumentation is enabled
6734 with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte
6735 nop sequence is generated.
6737 @item fentry_section("@var{name}")
6738 @cindex @code{fentry_section} function attribute, x86
6739 On x86 targets, the @code{fentry_section} attribute sets the name
6740 of the section to record function entry instrumentation calls in when
6741 enabled with @option{-pg -mrecord-mcount}
6745 On the x86, the inliner does not inline a
6746 function that has different target options than the caller, unless the
6747 callee has a subset of the target options of the caller. For example
6748 a function declared with @code{target("sse3")} can inline a function
6749 with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
6752 @node Xstormy16 Function Attributes
6753 @subsection Xstormy16 Function Attributes
6755 These function attributes are supported by the Xstormy16 back end:
6759 @cindex @code{interrupt} function attribute, Xstormy16
6760 Use this attribute to indicate
6761 that the specified function is an interrupt handler. The compiler generates
6762 function entry and exit sequences suitable for use in an interrupt handler
6763 when this attribute is present.
6766 @node Variable Attributes
6767 @section Specifying Attributes of Variables
6768 @cindex attribute of variables
6769 @cindex variable attributes
6771 The keyword @code{__attribute__} allows you to specify special properties
6772 of variables, function parameters, or structure, union, and, in C++, class
6773 members. This @code{__attribute__} keyword is followed by an attribute
6774 specification enclosed in double parentheses. Some attributes are currently
6775 defined generically for variables. Other attributes are defined for
6776 variables on particular target systems. Other attributes are available
6777 for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
6778 enumerators (@pxref{Enumerator Attributes}), statements
6779 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
6780 Other front ends might define more attributes
6781 (@pxref{C++ Extensions,,Extensions to the C++ Language}).
6783 @xref{Attribute Syntax}, for details of the exact syntax for using
6787 * Common Variable Attributes::
6788 * ARC Variable Attributes::
6789 * AVR Variable Attributes::
6790 * Blackfin Variable Attributes::
6791 * H8/300 Variable Attributes::
6792 * IA-64 Variable Attributes::
6793 * M32R/D Variable Attributes::
6794 * MeP Variable Attributes::
6795 * Microsoft Windows Variable Attributes::
6796 * MSP430 Variable Attributes::
6797 * Nvidia PTX Variable Attributes::
6798 * PowerPC Variable Attributes::
6799 * RL78 Variable Attributes::
6800 * V850 Variable Attributes::
6801 * x86 Variable Attributes::
6802 * Xstormy16 Variable Attributes::
6805 @node Common Variable Attributes
6806 @subsection Common Variable Attributes
6808 The following attributes are supported on most targets.
6812 @item alias ("@var{target}")
6813 @cindex @code{alias} variable attribute
6814 The @code{alias} variable attribute causes the declaration to be emitted
6815 as an alias for another symbol known as an @dfn{alias target}. Except
6816 for top-level qualifiers the alias target must have the same type as
6817 the alias. For instance, the following
6821 extern int __attribute__ ((alias ("var_target"))) var_alias;
6825 defines @code{var_alias} to be an alias for the @code{var_target} variable.
6827 It is an error if the alias target is not defined in the same translation
6830 Note that in the absence of the attribute GCC assumes that distinct
6831 declarations with external linkage denote distinct objects. Using both
6832 the alias and the alias target to access the same object is undefined
6833 in a translation unit without a declaration of the alias with the attribute.
6835 This attribute requires assembler and object file support, and may not be
6836 available on all targets.
6838 @cindex @code{aligned} variable attribute
6840 @itemx aligned (@var{alignment})
6841 The @code{aligned} attribute specifies a minimum alignment for the variable
6842 or structure field, measured in bytes. When specified, @var{alignment} must
6843 be an integer constant power of 2. Specifying no @var{alignment} argument
6844 implies the maximum alignment for the target, which is often, but by no
6845 means always, 8 or 16 bytes.
6847 For example, the declaration:
6850 int x __attribute__ ((aligned (16))) = 0;
6854 causes the compiler to allocate the global variable @code{x} on a
6855 16-byte boundary. On a 68040, this could be used in conjunction with
6856 an @code{asm} expression to access the @code{move16} instruction which
6857 requires 16-byte aligned operands.
6859 You can also specify the alignment of structure fields. For example, to
6860 create a double-word aligned @code{int} pair, you could write:
6863 struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
6867 This is an alternative to creating a union with a @code{double} member,
6868 which forces the union to be double-word aligned.
6870 As in the preceding examples, you can explicitly specify the alignment
6871 (in bytes) that you wish the compiler to use for a given variable or
6872 structure field. Alternatively, you can leave out the alignment factor
6873 and just ask the compiler to align a variable or field to the
6874 default alignment for the target architecture you are compiling for.
6875 The default alignment is sufficient for all scalar types, but may not be
6876 enough for all vector types on a target that supports vector operations.
6877 The default alignment is fixed for a particular target ABI.
6879 GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
6880 which is the largest alignment ever used for any data type on the
6881 target machine you are compiling for. For example, you could write:
6884 short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
6887 The compiler automatically sets the alignment for the declared
6888 variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
6889 often make copy operations more efficient, because the compiler can
6890 use whatever instructions copy the biggest chunks of memory when
6891 performing copies to or from the variables or fields that you have
6892 aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
6893 may change depending on command-line options.
6895 When used on a struct, or struct member, the @code{aligned} attribute can
6896 only increase the alignment; in order to decrease it, the @code{packed}
6897 attribute must be specified as well. When used as part of a typedef, the
6898 @code{aligned} attribute can both increase and decrease alignment, and
6899 specifying the @code{packed} attribute generates a warning.
6901 Note that the effectiveness of @code{aligned} attributes for static
6902 variables may be limited by inherent limitations in the system linker
6903 and/or object file format. On some systems, the linker is
6904 only able to arrange for variables to be aligned up to a certain maximum
6905 alignment. (For some linkers, the maximum supported alignment may
6906 be very very small.) If your linker is only able to align variables
6907 up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
6908 in an @code{__attribute__} still only provides you with 8-byte
6909 alignment. See your linker documentation for further information.
6911 Stack variables are not affected by linker restrictions; GCC can properly
6912 align them on any target.
6914 The @code{aligned} attribute can also be used for functions
6915 (@pxref{Common Function Attributes}.)
6917 @cindex @code{warn_if_not_aligned} variable attribute
6918 @item warn_if_not_aligned (@var{alignment})
6919 This attribute specifies a threshold for the structure field, measured
6920 in bytes. If the structure field is aligned below the threshold, a
6921 warning will be issued. For example, the declaration:
6928 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
6933 causes the compiler to issue an warning on @code{struct foo}, like
6934 @samp{warning: alignment 8 of 'struct foo' is less than 16}.
6935 The compiler also issues a warning, like @samp{warning: 'x' offset
6936 8 in 'struct foo' isn't aligned to 16}, when the structure field has
6937 the misaligned offset:
6940 struct __attribute__ ((aligned (16))) foo
6944 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
6948 This warning can be disabled by @option{-Wno-if-not-aligned}.
6949 The @code{warn_if_not_aligned} attribute can also be used for types
6950 (@pxref{Common Type Attributes}.)
6952 @item alloc_size (@var{position})
6953 @itemx alloc_size (@var{position-1}, @var{position-2})
6954 @cindex @code{alloc_size} variable attribute
6955 The @code{alloc_size} variable attribute may be applied to the declaration
6956 of a pointer to a function that returns a pointer and takes at least one
6957 argument of an integer type. It indicates that the returned pointer points
6958 to an object whose size is given by the function argument at @var{position-1},
6959 or by the product of the arguments at @var{position-1} and @var{position-2}.
6960 Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other
6961 sizes are disagnosed when detected. GCC uses this information to improve
6962 the results of @code{__builtin_object_size}.
6964 For instance, the following declarations
6967 typedef __attribute__ ((alloc_size (1, 2))) void*
6968 (*calloc_ptr) (size_t, size_t);
6969 typedef __attribute__ ((alloc_size (1))) void*
6970 (*malloc_ptr) (size_t);
6974 specify that @code{calloc_ptr} is a pointer of a function that, like
6975 the standard C function @code{calloc}, returns an object whose size
6976 is given by the product of arguments 1 and 2, and similarly, that
6977 @code{malloc_ptr}, like the standard C function @code{malloc},
6978 returns an object whose size is given by argument 1 to the function.
6980 @item cleanup (@var{cleanup_function})
6981 @cindex @code{cleanup} variable attribute
6982 The @code{cleanup} attribute runs a function when the variable goes
6983 out of scope. This attribute can only be applied to auto function
6984 scope variables; it may not be applied to parameters or variables
6985 with static storage duration. The function must take one parameter,
6986 a pointer to a type compatible with the variable. The return value
6987 of the function (if any) is ignored.
6989 If @option{-fexceptions} is enabled, then @var{cleanup_function}
6990 is run during the stack unwinding that happens during the
6991 processing of the exception. Note that the @code{cleanup} attribute
6992 does not allow the exception to be caught, only to perform an action.
6993 It is undefined what happens if @var{cleanup_function} does not
6998 @cindex @code{common} variable attribute
6999 @cindex @code{nocommon} variable attribute
7002 The @code{common} attribute requests GCC to place a variable in
7003 ``common'' storage. The @code{nocommon} attribute requests the
7004 opposite---to allocate space for it directly.
7006 These attributes override the default chosen by the
7007 @option{-fno-common} and @option{-fcommon} flags respectively.
7010 @itemx copy (@var{variable})
7011 @cindex @code{copy} variable attribute
7012 The @code{copy} attribute applies the set of attributes with which
7013 @var{variable} has been declared to the declaration of the variable
7014 to which the attribute is applied. The attribute is designed for
7015 libraries that define aliases that are expected to specify the same
7016 set of attributes as the aliased symbols. The @code{copy} attribute
7017 can be used with variables, functions or types. However, the kind
7018 of symbol to which the attribute is applied (either varible or
7019 function) must match the kind of symbol to which the argument refers.
7020 The @code{copy} attribute copies only syntactic and semantic attributes
7021 but not attributes that affect a symbol's linkage or visibility such as
7022 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
7023 attribute is also not copied. @xref{Common Function Attributes}.
7024 @xref{Common Type Attributes}.
7027 @itemx deprecated (@var{msg})
7028 @cindex @code{deprecated} variable attribute
7029 The @code{deprecated} attribute results in a warning if the variable
7030 is used anywhere in the source file. This is useful when identifying
7031 variables that are expected to be removed in a future version of a
7032 program. The warning also includes the location of the declaration
7033 of the deprecated variable, to enable users to easily find further
7034 information about why the variable is deprecated, or what they should
7035 do instead. Note that the warning only occurs for uses:
7038 extern int old_var __attribute__ ((deprecated));
7040 int new_fn () @{ return old_var; @}
7044 results in a warning on line 3 but not line 2. The optional @var{msg}
7045 argument, which must be a string, is printed in the warning if
7048 The @code{deprecated} attribute can also be used for functions and
7049 types (@pxref{Common Function Attributes},
7050 @pxref{Common Type Attributes}).
7052 The message attached to the attribute is affected by the setting of
7053 the @option{-fmessage-length} option.
7055 @item mode (@var{mode})
7056 @cindex @code{mode} variable attribute
7057 This attribute specifies the data type for the declaration---whichever
7058 type corresponds to the mode @var{mode}. This in effect lets you
7059 request an integer or floating-point type according to its width.
7061 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
7062 for a list of the possible keywords for @var{mode}.
7063 You may also specify a mode of @code{byte} or @code{__byte__} to
7064 indicate the mode corresponding to a one-byte integer, @code{word} or
7065 @code{__word__} for the mode of a one-word integer, and @code{pointer}
7066 or @code{__pointer__} for the mode used to represent pointers.
7069 @cindex @code{nonstring} variable attribute
7070 The @code{nonstring} variable attribute specifies that an object or member
7071 declaration with type array of @code{char}, @code{signed char}, or
7072 @code{unsigned char}, or pointer to such a type is intended to store
7073 character arrays that do not necessarily contain a terminating @code{NUL}.
7074 This is useful in detecting uses of such arrays or pointers with functions
7075 that expect @code{NUL}-terminated strings, and to avoid warnings when such
7076 an array or pointer is used as an argument to a bounded string manipulation
7077 function such as @code{strncpy}. For example, without the attribute, GCC
7078 will issue a warning for the @code{strncpy} call below because it may
7079 truncate the copy without appending the terminating @code{NUL} character.
7080 Using the attribute makes it possible to suppress the warning. However,
7081 when the array is declared with the attribute the call to @code{strlen} is
7082 diagnosed because when the array doesn't contain a @code{NUL}-terminated
7083 string the call is undefined. To copy, compare, of search non-string
7084 character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr},
7085 and other functions that operate on arrays of bytes. In addition,
7086 calling @code{strnlen} and @code{strndup} with such arrays is safe
7087 provided a suitable bound is specified, and not diagnosed.
7092 char name [32] __attribute__ ((nonstring));
7095 int f (struct Data *pd, const char *s)
7097 strncpy (pd->name, s, sizeof pd->name);
7099 return strlen (pd->name); // unsafe, gets a warning
7104 @cindex @code{packed} variable attribute
7105 The @code{packed} attribute specifies that a structure member should have
7106 the smallest possible alignment---one bit for a bit-field and one byte
7107 otherwise, unless a larger value is specified with the @code{aligned}
7108 attribute. The attribute does not apply to non-member objects.
7110 For example in the structure below, the member array @code{x} is packed
7111 so that it immediately follows @code{a} with no intervening padding:
7117 int x[2] __attribute__ ((packed));
7121 @emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
7122 @code{packed} attribute on bit-fields of type @code{char}. This has
7123 been fixed in GCC 4.4 but the change can lead to differences in the
7124 structure layout. See the documentation of
7125 @option{-Wpacked-bitfield-compat} for more information.
7127 @item section ("@var{section-name}")
7128 @cindex @code{section} variable attribute
7129 Normally, the compiler places the objects it generates in sections like
7130 @code{data} and @code{bss}. Sometimes, however, you need additional sections,
7131 or you need certain particular variables to appear in special sections,
7132 for example to map to special hardware. The @code{section}
7133 attribute specifies that a variable (or function) lives in a particular
7134 section. For example, this small program uses several specific section names:
7137 struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
7138 struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
7139 char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
7140 int init_data __attribute__ ((section ("INITDATA")));
7144 /* @r{Initialize stack pointer} */
7145 init_sp (stack + sizeof (stack));
7147 /* @r{Initialize initialized data} */
7148 memcpy (&init_data, &data, &edata - &data);
7150 /* @r{Turn on the serial ports} */
7157 Use the @code{section} attribute with
7158 @emph{global} variables and not @emph{local} variables,
7159 as shown in the example.
7161 You may use the @code{section} attribute with initialized or
7162 uninitialized global variables but the linker requires
7163 each object be defined once, with the exception that uninitialized
7164 variables tentatively go in the @code{common} (or @code{bss}) section
7165 and can be multiply ``defined''. Using the @code{section} attribute
7166 changes what section the variable goes into and may cause the
7167 linker to issue an error if an uninitialized variable has multiple
7168 definitions. You can force a variable to be initialized with the
7169 @option{-fno-common} flag or the @code{nocommon} attribute.
7171 Some file formats do not support arbitrary sections so the @code{section}
7172 attribute is not available on all platforms.
7173 If you need to map the entire contents of a module to a particular
7174 section, consider using the facilities of the linker instead.
7176 @item tls_model ("@var{tls_model}")
7177 @cindex @code{tls_model} variable attribute
7178 The @code{tls_model} attribute sets thread-local storage model
7179 (@pxref{Thread-Local}) of a particular @code{__thread} variable,
7180 overriding @option{-ftls-model=} command-line switch on a per-variable
7182 The @var{tls_model} argument should be one of @code{global-dynamic},
7183 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
7185 Not all targets support this attribute.
7188 @cindex @code{unused} variable attribute
7189 This attribute, attached to a variable, means that the variable is meant
7190 to be possibly unused. GCC does not produce a warning for this
7194 @cindex @code{used} variable attribute
7195 This attribute, attached to a variable with static storage, means that
7196 the variable must be emitted even if it appears that the variable is not
7199 When applied to a static data member of a C++ class template, the
7200 attribute also means that the member is instantiated if the
7201 class itself is instantiated.
7203 @item vector_size (@var{bytes})
7204 @cindex @code{vector_size} variable attribute
7205 This attribute specifies the vector size for the type of the declared
7206 variable, measured in bytes. The type to which it applies is known as
7207 the @dfn{base type}. The @var{bytes} argument must be a positive
7208 power-of-two multiple of the base type size. For example, the declaration:
7211 int foo __attribute__ ((vector_size (16)));
7215 causes the compiler to set the mode for @code{foo}, to be 16 bytes,
7216 divided into @code{int} sized units. Assuming a 32-bit @code{int},
7217 @code{foo}'s type is a vector of four units of four bytes each, and
7218 the corresponding mode of @code{foo} is @code{V4SI}.
7219 @xref{Vector Extensions}, for details of manipulating vector variables.
7221 This attribute is only applicable to integral and floating scalars,
7222 although arrays, pointers, and function return values are allowed in
7223 conjunction with this construct.
7225 Aggregates with this attribute are invalid, even if they are of the same
7226 size as a corresponding scalar. For example, the declaration:
7229 struct S @{ int a; @};
7230 struct S __attribute__ ((vector_size (16))) foo;
7234 is invalid even if the size of the structure is the same as the size of
7237 @item visibility ("@var{visibility_type}")
7238 @cindex @code{visibility} variable attribute
7239 This attribute affects the linkage of the declaration to which it is attached.
7240 The @code{visibility} attribute is described in
7241 @ref{Common Function Attributes}.
7244 @cindex @code{weak} variable attribute
7245 The @code{weak} attribute is described in
7246 @ref{Common Function Attributes}.
7249 @cindex @code{noinit} variable attribute
7250 Any data with the @code{noinit} attribute will not be initialized by
7251 the C runtime startup code, or the program loader. Not initializing
7252 data in this way can reduce program startup times. This attribute is
7253 specific to ELF targets and relies on the linker to place such data in
7258 @node ARC Variable Attributes
7259 @subsection ARC Variable Attributes
7263 @cindex @code{aux} variable attribute, ARC
7264 The @code{aux} attribute is used to directly access the ARC's
7265 auxiliary register space from C. The auxilirary register number is
7266 given via attribute argument.
7270 @node AVR Variable Attributes
7271 @subsection AVR Variable Attributes
7275 @cindex @code{progmem} variable attribute, AVR
7276 The @code{progmem} attribute is used on the AVR to place read-only
7277 data in the non-volatile program memory (flash). The @code{progmem}
7278 attribute accomplishes this by putting respective variables into a
7279 section whose name starts with @code{.progmem}.
7281 This attribute works similar to the @code{section} attribute
7282 but adds additional checking.
7285 @item @bullet{}@tie{} Ordinary AVR cores with 32 general purpose registers:
7286 @code{progmem} affects the location
7287 of the data but not how this data is accessed.
7288 In order to read data located with the @code{progmem} attribute
7289 (inline) assembler must be used.
7291 /* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */
7292 #include <avr/pgmspace.h>
7294 /* Locate var in flash memory */
7295 const int var[2] PROGMEM = @{ 1, 2 @};
7297 int read_var (int i)
7299 /* Access var[] by accessor macro from avr/pgmspace.h */
7300 return (int) pgm_read_word (& var[i]);
7304 AVR is a Harvard architecture processor and data and read-only data
7305 normally resides in the data memory (RAM).
7307 See also the @ref{AVR Named Address Spaces} section for
7308 an alternate way to locate and access data in flash memory.
7310 @item @bullet{}@tie{} AVR cores with flash memory visible in the RAM address range:
7311 On such devices, there is no need for attribute @code{progmem} or
7312 @ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all.
7313 Just use standard C / C++. The compiler will generate @code{LD*}
7314 instructions. As flash memory is visible in the RAM address range,
7315 and the default linker script does @emph{not} locate @code{.rodata} in
7316 RAM, no special features are needed in order not to waste RAM for
7317 read-only data or to read from flash. You might even get slightly better
7319 avoiding @code{progmem} and @code{__flash}. This applies to devices from
7320 families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for
7323 @item @bullet{}@tie{}Reduced AVR Tiny cores like ATtiny40:
7324 The compiler adds @code{0x4000}
7325 to the addresses of objects and declarations in @code{progmem} and locates
7326 the objects in flash memory, namely in section @code{.progmem.data}.
7327 The offset is needed because the flash memory is visible in the RAM
7328 address space starting at address @code{0x4000}.
7330 Data in @code{progmem} can be accessed by means of ordinary C@tie{}code,
7331 no special functions or macros are needed.
7334 /* var is located in flash memory */
7335 extern const int var[2] __attribute__((progmem));
7337 int read_var (int i)
7343 Please notice that on these devices, there is no need for @code{progmem}
7349 @itemx io (@var{addr})
7350 @cindex @code{io} variable attribute, AVR
7351 Variables with the @code{io} attribute are used to address
7352 memory-mapped peripherals in the io address range.
7353 If an address is specified, the variable
7354 is assigned that address, and the value is interpreted as an
7355 address in the data address space.
7359 volatile int porta __attribute__((io (0x22)));
7362 The address specified in the address in the data address range.
7364 Otherwise, the variable it is not assigned an address, but the
7365 compiler will still use in/out instructions where applicable,
7366 assuming some other module assigns an address in the io address range.
7370 extern volatile int porta __attribute__((io));
7374 @itemx io_low (@var{addr})
7375 @cindex @code{io_low} variable attribute, AVR
7376 This is like the @code{io} attribute, but additionally it informs the
7377 compiler that the object lies in the lower half of the I/O area,
7378 allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis}
7382 @itemx address (@var{addr})
7383 @cindex @code{address} variable attribute, AVR
7384 Variables with the @code{address} attribute are used to address
7385 memory-mapped peripherals that may lie outside the io address range.
7388 volatile int porta __attribute__((address (0x600)));
7392 @cindex @code{absdata} variable attribute, AVR
7393 Variables in static storage and with the @code{absdata} attribute can
7394 be accessed by the @code{LDS} and @code{STS} instructions which take
7399 This attribute is only supported for the reduced AVR Tiny core
7403 You must make sure that respective data is located in the
7404 address range @code{0x40}@dots{}@code{0xbf} accessible by
7405 @code{LDS} and @code{STS}. One way to achieve this as an
7406 appropriate linker description file.
7409 If the location does not fit the address range of @code{LDS}
7410 and @code{STS}, there is currently (Binutils 2.26) just an unspecific
7413 @code{module.c:(.text+0x1c): warning: internal error: out of range error}
7418 See also the @option{-mabsdata} @ref{AVR Options,command-line option}.
7422 @node Blackfin Variable Attributes
7423 @subsection Blackfin Variable Attributes
7425 Three attributes are currently defined for the Blackfin.
7431 @cindex @code{l1_data} variable attribute, Blackfin
7432 @cindex @code{l1_data_A} variable attribute, Blackfin
7433 @cindex @code{l1_data_B} variable attribute, Blackfin
7434 Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
7435 Variables with @code{l1_data} attribute are put into the specific section
7436 named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into
7437 the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
7438 attribute are put into the specific section named @code{.l1.data.B}.
7441 @cindex @code{l2} variable attribute, Blackfin
7442 Use this attribute on the Blackfin to place the variable into L2 SRAM.
7443 Variables with @code{l2} attribute are put into the specific section
7444 named @code{.l2.data}.
7447 @node H8/300 Variable Attributes
7448 @subsection H8/300 Variable Attributes
7450 These variable attributes are available for H8/300 targets:
7454 @cindex @code{eightbit_data} variable attribute, H8/300
7455 @cindex eight-bit data on the H8/300, H8/300H, and H8S
7456 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
7457 variable should be placed into the eight-bit data section.
7458 The compiler generates more efficient code for certain operations
7459 on data in the eight-bit data area. Note the eight-bit data area is limited to
7462 You must use GAS and GLD from GNU binutils version 2.7 or later for
7463 this attribute to work correctly.
7466 @cindex @code{tiny_data} variable attribute, H8/300
7467 @cindex tiny data section on the H8/300H and H8S
7468 Use this attribute on the H8/300H and H8S to indicate that the specified
7469 variable should be placed into the tiny data section.
7470 The compiler generates more efficient code for loads and stores
7471 on data in the tiny data section. Note the tiny data area is limited to
7472 slightly under 32KB of data.
7476 @node IA-64 Variable Attributes
7477 @subsection IA-64 Variable Attributes
7479 The IA-64 back end supports the following variable attribute:
7482 @item model (@var{model-name})
7483 @cindex @code{model} variable attribute, IA-64
7485 On IA-64, use this attribute to set the addressability of an object.
7486 At present, the only supported identifier for @var{model-name} is
7487 @code{small}, indicating addressability via ``small'' (22-bit)
7488 addresses (so that their addresses can be loaded with the @code{addl}
7489 instruction). Caveat: such addressing is by definition not position
7490 independent and hence this attribute must not be used for objects
7491 defined by shared libraries.
7495 @node M32R/D Variable Attributes
7496 @subsection M32R/D Variable Attributes
7498 One attribute is currently defined for the M32R/D@.
7501 @item model (@var{model-name})
7502 @cindex @code{model-name} variable attribute, M32R/D
7503 @cindex variable addressability on the M32R/D
7504 Use this attribute on the M32R/D to set the addressability of an object.
7505 The identifier @var{model-name} is one of @code{small}, @code{medium},
7506 or @code{large}, representing each of the code models.
7508 Small model objects live in the lower 16MB of memory (so that their
7509 addresses can be loaded with the @code{ld24} instruction).
7511 Medium and large model objects may live anywhere in the 32-bit address space
7512 (the compiler generates @code{seth/add3} instructions to load their
7516 @node MeP Variable Attributes
7517 @subsection MeP Variable Attributes
7519 The MeP target has a number of addressing modes and busses. The
7520 @code{near} space spans the standard memory space's first 16 megabytes
7521 (24 bits). The @code{far} space spans the entire 32-bit memory space.
7522 The @code{based} space is a 128-byte region in the memory space that
7523 is addressed relative to the @code{$tp} register. The @code{tiny}
7524 space is a 65536-byte region relative to the @code{$gp} register. In
7525 addition to these memory regions, the MeP target has a separate 16-bit
7526 control bus which is specified with @code{cb} attributes.
7531 @cindex @code{based} variable attribute, MeP
7532 Any variable with the @code{based} attribute is assigned to the
7533 @code{.based} section, and is accessed with relative to the
7534 @code{$tp} register.
7537 @cindex @code{tiny} variable attribute, MeP
7538 Likewise, the @code{tiny} attribute assigned variables to the
7539 @code{.tiny} section, relative to the @code{$gp} register.
7542 @cindex @code{near} variable attribute, MeP
7543 Variables with the @code{near} attribute are assumed to have addresses
7544 that fit in a 24-bit addressing mode. This is the default for large
7545 variables (@code{-mtiny=4} is the default) but this attribute can
7546 override @code{-mtiny=} for small variables, or override @code{-ml}.
7549 @cindex @code{far} variable attribute, MeP
7550 Variables with the @code{far} attribute are addressed using a full
7551 32-bit address. Since this covers the entire memory space, this
7552 allows modules to make no assumptions about where variables might be
7556 @cindex @code{io} variable attribute, MeP
7557 @itemx io (@var{addr})
7558 Variables with the @code{io} attribute are used to address
7559 memory-mapped peripherals. If an address is specified, the variable
7560 is assigned that address, else it is not assigned an address (it is
7561 assumed some other module assigns an address). Example:
7564 int timer_count __attribute__((io(0x123)));
7568 @itemx cb (@var{addr})
7569 @cindex @code{cb} variable attribute, MeP
7570 Variables with the @code{cb} attribute are used to access the control
7571 bus, using special instructions. @code{addr} indicates the control bus
7575 int cpu_clock __attribute__((cb(0x123)));
7580 @node Microsoft Windows Variable Attributes
7581 @subsection Microsoft Windows Variable Attributes
7583 You can use these attributes on Microsoft Windows targets.
7584 @ref{x86 Variable Attributes} for additional Windows compatibility
7585 attributes available on all x86 targets.
7590 @cindex @code{dllimport} variable attribute
7591 @cindex @code{dllexport} variable attribute
7592 The @code{dllimport} and @code{dllexport} attributes are described in
7593 @ref{Microsoft Windows Function Attributes}.
7596 @cindex @code{selectany} variable attribute
7597 The @code{selectany} attribute causes an initialized global variable to
7598 have link-once semantics. When multiple definitions of the variable are
7599 encountered by the linker, the first is selected and the remainder are
7600 discarded. Following usage by the Microsoft compiler, the linker is told
7601 @emph{not} to warn about size or content differences of the multiple
7604 Although the primary usage of this attribute is for POD types, the
7605 attribute can also be applied to global C++ objects that are initialized
7606 by a constructor. In this case, the static initialization and destruction
7607 code for the object is emitted in each translation defining the object,
7608 but the calls to the constructor and destructor are protected by a
7609 link-once guard variable.
7611 The @code{selectany} attribute is only available on Microsoft Windows
7612 targets. You can use @code{__declspec (selectany)} as a synonym for
7613 @code{__attribute__ ((selectany))} for compatibility with other
7617 @cindex @code{shared} variable attribute
7618 On Microsoft Windows, in addition to putting variable definitions in a named
7619 section, the section can also be shared among all running copies of an
7620 executable or DLL@. For example, this small program defines shared data
7621 by putting it in a named section @code{shared} and marking the section
7625 int foo __attribute__((section ("shared"), shared)) = 0;
7630 /* @r{Read and write foo. All running
7631 copies see the same value.} */
7637 You may only use the @code{shared} attribute along with @code{section}
7638 attribute with a fully-initialized global definition because of the way
7639 linkers work. See @code{section} attribute for more information.
7641 The @code{shared} attribute is only available on Microsoft Windows@.
7645 @node MSP430 Variable Attributes
7646 @subsection MSP430 Variable Attributes
7650 @cindex @code{noinit} variable attribute, MSP430
7651 Any data with the @code{noinit} attribute will not be initialised by
7652 the C runtime startup code, or the program loader. Not initialising
7653 data in this way can reduce program startup times.
7656 @cindex @code{persistent} variable attribute, MSP430
7657 Any variable with the @code{persistent} attribute will not be
7658 initialised by the C runtime startup code. Instead its value will be
7659 set once, when the application is loaded, and then never initialised
7660 again, even if the processor is reset or the program restarts.
7661 Persistent data is intended to be placed into FLASH RAM, where its
7662 value will be retained across resets. The linker script being used to
7663 create the application should ensure that persistent data is correctly
7668 @cindex @code{upper} variable attribute, MSP430
7669 @cindex @code{either} variable attribute, MSP430
7670 These attributes are the same as the MSP430 function attributes of the
7671 same name (@pxref{MSP430 Function Attributes}).
7674 @cindex @code{lower} variable attribute, MSP430
7675 This option behaves mostly the same as the MSP430 function attribute of the
7676 same name (@pxref{MSP430 Function Attributes}), but it has some additional
7679 If @option{-mdata-region=}@{@code{upper,either,none}@} has been passed, or
7680 the @code{section} attribute is applied to a variable, the compiler will
7681 generate 430X instructions to handle it. This is because the compiler has
7682 to assume that the variable could get placed in the upper memory region
7683 (above address 0xFFFF). Marking the variable with the @code{lower} attribute
7684 informs the compiler that the variable will be placed in lower memory so it
7685 is safe to use 430 instructions to handle it.
7687 In the case of the @code{section} attribute, the section name given
7688 will be used, and the @code{.lower} prefix will not be added.
7692 @node Nvidia PTX Variable Attributes
7693 @subsection Nvidia PTX Variable Attributes
7695 These variable attributes are supported by the Nvidia PTX back end:
7699 @cindex @code{shared} attribute, Nvidia PTX
7700 Use this attribute to place a variable in the @code{.shared} memory space.
7701 This memory space is private to each cooperative thread array; only threads
7702 within one thread block refer to the same instance of the variable.
7703 The runtime does not initialize variables in this memory space.
7706 @node PowerPC Variable Attributes
7707 @subsection PowerPC Variable Attributes
7709 Three attributes currently are defined for PowerPC configurations:
7710 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
7712 @cindex @code{ms_struct} variable attribute, PowerPC
7713 @cindex @code{gcc_struct} variable attribute, PowerPC
7714 For full documentation of the struct attributes please see the
7715 documentation in @ref{x86 Variable Attributes}.
7717 @cindex @code{altivec} variable attribute, PowerPC
7718 For documentation of @code{altivec} attribute please see the
7719 documentation in @ref{PowerPC Type Attributes}.
7721 @node RL78 Variable Attributes
7722 @subsection RL78 Variable Attributes
7724 @cindex @code{saddr} variable attribute, RL78
7725 The RL78 back end supports the @code{saddr} variable attribute. This
7726 specifies placement of the corresponding variable in the SADDR area,
7727 which can be accessed more efficiently than the default memory region.
7729 @node V850 Variable Attributes
7730 @subsection V850 Variable Attributes
7732 These variable attributes are supported by the V850 back end:
7737 @cindex @code{sda} variable attribute, V850
7738 Use this attribute to explicitly place a variable in the small data area,
7739 which can hold up to 64 kilobytes.
7742 @cindex @code{tda} variable attribute, V850
7743 Use this attribute to explicitly place a variable in the tiny data area,
7744 which can hold up to 256 bytes in total.
7747 @cindex @code{zda} variable attribute, V850
7748 Use this attribute to explicitly place a variable in the first 32 kilobytes
7752 @node x86 Variable Attributes
7753 @subsection x86 Variable Attributes
7755 Two attributes are currently defined for x86 configurations:
7756 @code{ms_struct} and @code{gcc_struct}.
7761 @cindex @code{ms_struct} variable attribute, x86
7762 @cindex @code{gcc_struct} variable attribute, x86
7764 If @code{packed} is used on a structure, or if bit-fields are used,
7765 it may be that the Microsoft ABI lays out the structure differently
7766 than the way GCC normally does. Particularly when moving packed
7767 data between functions compiled with GCC and the native Microsoft compiler
7768 (either via function call or as data in a file), it may be necessary to access
7771 The @code{ms_struct} and @code{gcc_struct} attributes correspond
7772 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
7773 command-line options, respectively;
7774 see @ref{x86 Options}, for details of how structure layout is affected.
7775 @xref{x86 Type Attributes}, for information about the corresponding
7776 attributes on types.
7780 @node Xstormy16 Variable Attributes
7781 @subsection Xstormy16 Variable Attributes
7783 One attribute is currently defined for xstormy16 configurations:
7788 @cindex @code{below100} variable attribute, Xstormy16
7790 If a variable has the @code{below100} attribute (@code{BELOW100} is
7791 allowed also), GCC places the variable in the first 0x100 bytes of
7792 memory and use special opcodes to access it. Such variables are
7793 placed in either the @code{.bss_below100} section or the
7794 @code{.data_below100} section.
7798 @node Type Attributes
7799 @section Specifying Attributes of Types
7800 @cindex attribute of types
7801 @cindex type attributes
7803 The keyword @code{__attribute__} allows you to specify various special
7804 properties of types. Some type attributes apply only to structure and
7805 union types, and in C++, also class types, while others can apply to
7806 any type defined via a @code{typedef} declaration. Unless otherwise
7807 specified, the same restrictions and effects apply to attributes regardless
7808 of whether a type is a trivial structure or a C++ class with user-defined
7809 constructors, destructors, or a copy assignment.
7811 Other attributes are defined for functions (@pxref{Function Attributes}),
7812 labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator
7813 Attributes}), statements (@pxref{Statement Attributes}), and for variables
7814 (@pxref{Variable Attributes}).
7816 The @code{__attribute__} keyword is followed by an attribute specification
7817 enclosed in double parentheses.
7819 You may specify type attributes in an enum, struct or union type
7820 declaration or definition by placing them immediately after the
7821 @code{struct}, @code{union} or @code{enum} keyword. You can also place
7822 them just past the closing curly brace of the definition, but this is less
7823 preferred because logically the type should be fully defined at
7826 You can also include type attributes in a @code{typedef} declaration.
7827 @xref{Attribute Syntax}, for details of the exact syntax for using
7831 * Common Type Attributes::
7832 * ARC Type Attributes::
7833 * ARM Type Attributes::
7834 * MeP Type Attributes::
7835 * PowerPC Type Attributes::
7836 * x86 Type Attributes::
7839 @node Common Type Attributes
7840 @subsection Common Type Attributes
7842 The following type attributes are supported on most targets.
7845 @cindex @code{aligned} type attribute
7847 @itemx aligned (@var{alignment})
7848 The @code{aligned} attribute specifies a minimum alignment (in bytes) for
7849 variables of the specified type. When specified, @var{alignment} must be
7850 a power of 2. Specifying no @var{alignment} argument implies the maximum
7851 alignment for the target, which is often, but by no means always, 8 or 16
7852 bytes. For example, the declarations:
7855 struct __attribute__ ((aligned (8))) S @{ short f[3]; @};
7856 typedef int more_aligned_int __attribute__ ((aligned (8)));
7860 force the compiler to ensure (as far as it can) that each variable whose
7861 type is @code{struct S} or @code{more_aligned_int} is allocated and
7862 aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all
7863 variables of type @code{struct S} aligned to 8-byte boundaries allows
7864 the compiler to use the @code{ldd} and @code{std} (doubleword load and
7865 store) instructions when copying one variable of type @code{struct S} to
7866 another, thus improving run-time efficiency.
7868 Note that the alignment of any given @code{struct} or @code{union} type
7869 is required by the ISO C standard to be at least a perfect multiple of
7870 the lowest common multiple of the alignments of all of the members of
7871 the @code{struct} or @code{union} in question. This means that you @emph{can}
7872 effectively adjust the alignment of a @code{struct} or @code{union}
7873 type by attaching an @code{aligned} attribute to any one of the members
7874 of such a type, but the notation illustrated in the example above is a
7875 more obvious, intuitive, and readable way to request the compiler to
7876 adjust the alignment of an entire @code{struct} or @code{union} type.
7878 As in the preceding example, you can explicitly specify the alignment
7879 (in bytes) that you wish the compiler to use for a given @code{struct}
7880 or @code{union} type. Alternatively, you can leave out the alignment factor
7881 and just ask the compiler to align a type to the maximum
7882 useful alignment for the target machine you are compiling for. For
7883 example, you could write:
7886 struct __attribute__ ((aligned)) S @{ short f[3]; @};
7889 Whenever you leave out the alignment factor in an @code{aligned}
7890 attribute specification, the compiler automatically sets the alignment
7891 for the type to the largest alignment that is ever used for any data
7892 type on the target machine you are compiling for. Doing this can often
7893 make copy operations more efficient, because the compiler can use
7894 whatever instructions copy the biggest chunks of memory when performing
7895 copies to or from the variables that have types that you have aligned
7898 In the example above, if the size of each @code{short} is 2 bytes, then
7899 the size of the entire @code{struct S} type is 6 bytes. The smallest
7900 power of two that is greater than or equal to that is 8, so the
7901 compiler sets the alignment for the entire @code{struct S} type to 8
7904 Note that although you can ask the compiler to select a time-efficient
7905 alignment for a given type and then declare only individual stand-alone
7906 objects of that type, the compiler's ability to select a time-efficient
7907 alignment is primarily useful only when you plan to create arrays of
7908 variables having the relevant (efficiently aligned) type. If you
7909 declare or use arrays of variables of an efficiently-aligned type, then
7910 it is likely that your program also does pointer arithmetic (or
7911 subscripting, which amounts to the same thing) on pointers to the
7912 relevant type, and the code that the compiler generates for these
7913 pointer arithmetic operations is often more efficient for
7914 efficiently-aligned types than for other types.
7916 Note that the effectiveness of @code{aligned} attributes may be limited
7917 by inherent limitations in your linker. On many systems, the linker is
7918 only able to arrange for variables to be aligned up to a certain maximum
7919 alignment. (For some linkers, the maximum supported alignment may
7920 be very very small.) If your linker is only able to align variables
7921 up to a maximum of 8-byte alignment, then specifying @code{aligned (16)}
7922 in an @code{__attribute__} still only provides you with 8-byte
7923 alignment. See your linker documentation for further information.
7925 When used on a struct, or struct member, the @code{aligned} attribute can
7926 only increase the alignment; in order to decrease it, the @code{packed}
7927 attribute must be specified as well. When used as part of a typedef, the
7928 @code{aligned} attribute can both increase and decrease alignment, and
7929 specifying the @code{packed} attribute generates a warning.
7931 @cindex @code{warn_if_not_aligned} type attribute
7932 @item warn_if_not_aligned (@var{alignment})
7933 This attribute specifies a threshold for the structure field, measured
7934 in bytes. If the structure field is aligned below the threshold, a
7935 warning will be issued. For example, the declaration:
7938 typedef unsigned long long __u64
7939 __attribute__((aligned (4), warn_if_not_aligned (8)));
7950 causes the compiler to issue an warning on @code{struct foo}, like
7951 @samp{warning: alignment 4 of 'struct foo' is less than 8}.
7952 It is used to define @code{struct foo} in such a way that
7953 @code{struct foo} has the same layout and the structure field @code{x}
7954 has the same alignment when @code{__u64} is aligned at either 4 or
7955 8 bytes. Align @code{struct foo} to 8 bytes:
7958 struct __attribute__ ((aligned (8))) foo
7967 silences the warning. The compiler also issues a warning, like
7968 @samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8},
7969 when the structure field has the misaligned offset:
7972 struct __attribute__ ((aligned (8))) foo
7981 This warning can be disabled by @option{-Wno-if-not-aligned}.
7983 @item alloc_size (@var{position})
7984 @itemx alloc_size (@var{position-1}, @var{position-2})
7985 @cindex @code{alloc_size} type attribute
7986 The @code{alloc_size} type attribute may be applied to the definition
7987 of a type of a function that returns a pointer and takes at least one
7988 argument of an integer type. It indicates that the returned pointer
7989 points to an object whose size is given by the function argument at
7990 @var{position-1}, or by the product of the arguments at @var{position-1}
7991 and @var{position-2}. Meaningful sizes are positive values less than
7992 @code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses
7993 this information to improve the results of @code{__builtin_object_size}.
7995 For instance, the following declarations
7998 typedef __attribute__ ((alloc_size (1, 2))) void*
7999 calloc_type (size_t, size_t);
8000 typedef __attribute__ ((alloc_size (1))) void*
8001 malloc_type (size_t);
8005 specify that @code{calloc_type} is a type of a function that, like
8006 the standard C function @code{calloc}, returns an object whose size
8007 is given by the product of arguments 1 and 2, and that
8008 @code{malloc_type}, like the standard C function @code{malloc},
8009 returns an object whose size is given by argument 1 to the function.
8012 @itemx copy (@var{expression})
8013 @cindex @code{copy} type attribute
8014 The @code{copy} attribute applies the set of attributes with which
8015 the type of the @var{expression} has been declared to the declaration
8016 of the type to which the attribute is applied. The attribute is
8017 designed for libraries that define aliases that are expected to
8018 specify the same set of attributes as the aliased symbols.
8019 The @code{copy} attribute can be used with types, variables, or
8020 functions. However, the kind of symbol to which the attribute is
8021 applied (either varible or function) must match the kind of symbol
8022 to which the argument refers.
8023 The @code{copy} attribute copies only syntactic and semantic attributes
8024 but not attributes that affect a symbol's linkage or visibility such as
8025 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
8026 attribute is also not copied. @xref{Common Function Attributes}.
8027 @xref{Common Variable Attributes}.
8029 For example, suppose @code{struct A} below is defined in some third
8030 party library header to have the alignment requirement @code{N} and
8031 to force a warning whenever a variable of the type is not so aligned
8032 due to attribute @code{packed}. Specifying the @code{copy} attribute
8033 on the definition on the unrelated @code{struct B} has the effect of
8034 copying all relevant attributes from the type referenced by the pointer
8035 expression to @code{struct B}.
8038 struct __attribute__ ((aligned (N), warn_if_not_aligned (N)))
8039 A @{ /* @r{@dots{}} */ @};
8040 struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @};
8044 @itemx deprecated (@var{msg})
8045 @cindex @code{deprecated} type attribute
8046 The @code{deprecated} attribute results in a warning if the type
8047 is used anywhere in the source file. This is useful when identifying
8048 types that are expected to be removed in a future version of a program.
8049 If possible, the warning also includes the location of the declaration
8050 of the deprecated type, to enable users to easily find further
8051 information about why the type is deprecated, or what they should do
8052 instead. Note that the warnings only occur for uses and then only
8053 if the type is being applied to an identifier that itself is not being
8054 declared as deprecated.
8057 typedef int T1 __attribute__ ((deprecated));
8061 typedef T1 T3 __attribute__ ((deprecated));
8062 T3 z __attribute__ ((deprecated));
8066 results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
8067 warning is issued for line 4 because T2 is not explicitly
8068 deprecated. Line 5 has no warning because T3 is explicitly
8069 deprecated. Similarly for line 6. The optional @var{msg}
8070 argument, which must be a string, is printed in the warning if
8071 present. Control characters in the string will be replaced with
8072 escape sequences, and if the @option{-fmessage-length} option is set
8073 to 0 (its default value) then any newline characters will be ignored.
8075 The @code{deprecated} attribute can also be used for functions and
8076 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
8078 The message attached to the attribute is affected by the setting of
8079 the @option{-fmessage-length} option.
8081 @item designated_init
8082 @cindex @code{designated_init} type attribute
8083 This attribute may only be applied to structure types. It indicates
8084 that any initialization of an object of this type must use designated
8085 initializers rather than positional initializers. The intent of this
8086 attribute is to allow the programmer to indicate that a structure's
8087 layout may change, and that therefore relying on positional
8088 initialization will result in future breakage.
8090 GCC emits warnings based on this attribute by default; use
8091 @option{-Wno-designated-init} to suppress them.
8094 @cindex @code{may_alias} type attribute
8095 Accesses through pointers to types with this attribute are not subject
8096 to type-based alias analysis, but are instead assumed to be able to alias
8097 any other type of objects.
8098 In the context of section 6.5 paragraph 7 of the C99 standard,
8099 an lvalue expression
8100 dereferencing such a pointer is treated like having a character type.
8101 See @option{-fstrict-aliasing} for more information on aliasing issues.
8102 This extension exists to support some vector APIs, in which pointers to
8103 one vector type are permitted to alias pointers to a different vector type.
8105 Note that an object of a type with this attribute does not have any
8111 typedef short __attribute__ ((__may_alias__)) short_a;
8117 short_a *b = (short_a *) &a;
8121 if (a == 0x12345678)
8129 If you replaced @code{short_a} with @code{short} in the variable
8130 declaration, the above program would abort when compiled with
8131 @option{-fstrict-aliasing}, which is on by default at @option{-O2} or
8134 @item mode (@var{mode})
8135 @cindex @code{mode} type attribute
8136 This attribute specifies the data type for the declaration---whichever
8137 type corresponds to the mode @var{mode}. This in effect lets you
8138 request an integer or floating-point type according to its width.
8140 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
8141 for a list of the possible keywords for @var{mode}.
8142 You may also specify a mode of @code{byte} or @code{__byte__} to
8143 indicate the mode corresponding to a one-byte integer, @code{word} or
8144 @code{__word__} for the mode of a one-word integer, and @code{pointer}
8145 or @code{__pointer__} for the mode used to represent pointers.
8148 @cindex @code{packed} type attribute
8149 This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class}
8150 type definition, specifies that each of its members (other than zero-width
8151 bit-fields) is placed to minimize the memory required. This is equivalent
8152 to specifying the @code{packed} attribute on each of the members.
8154 @opindex fshort-enums
8155 When attached to an @code{enum} definition, the @code{packed} attribute
8156 indicates that the smallest integral type should be used.
8157 Specifying the @option{-fshort-enums} flag on the command line
8158 is equivalent to specifying the @code{packed}
8159 attribute on all @code{enum} definitions.
8161 In the following example @code{struct my_packed_struct}'s members are
8162 packed closely together, but the internal layout of its @code{s} member
8163 is not packed---to do that, @code{struct my_unpacked_struct} needs to
8167 struct my_unpacked_struct
8173 struct __attribute__ ((__packed__)) my_packed_struct
8177 struct my_unpacked_struct s;
8181 You may only specify the @code{packed} attribute on the definition
8182 of an @code{enum}, @code{struct}, @code{union}, or @code{class},
8183 not on a @code{typedef} that does not also define the enumerated type,
8184 structure, union, or class.
8186 @item scalar_storage_order ("@var{endianness}")
8187 @cindex @code{scalar_storage_order} type attribute
8188 When attached to a @code{union} or a @code{struct}, this attribute sets
8189 the storage order, aka endianness, of the scalar fields of the type, as
8190 well as the array fields whose component is scalar. The supported
8191 endiannesses are @code{big-endian} and @code{little-endian}. The attribute
8192 has no effects on fields which are themselves a @code{union}, a @code{struct}
8193 or an array whose component is a @code{union} or a @code{struct}, and it is
8194 possible for these fields to have a different scalar storage order than the
8197 This attribute is supported only for targets that use a uniform default
8198 scalar storage order (fortunately, most of them), i.e.@: targets that store
8199 the scalars either all in big-endian or all in little-endian.
8201 Additional restrictions are enforced for types with the reverse scalar
8202 storage order with regard to the scalar storage order of the target:
8205 @item Taking the address of a scalar field of a @code{union} or a
8206 @code{struct} with reverse scalar storage order is not permitted and yields
8208 @item Taking the address of an array field, whose component is scalar, of
8209 a @code{union} or a @code{struct} with reverse scalar storage order is
8210 permitted but yields a warning, unless @option{-Wno-scalar-storage-order}
8212 @item Taking the address of a @code{union} or a @code{struct} with reverse
8213 scalar storage order is permitted.
8216 These restrictions exist because the storage order attribute is lost when
8217 the address of a scalar or the address of an array with scalar component is
8218 taken, so storing indirectly through this address generally does not work.
8219 The second case is nevertheless allowed to be able to perform a block copy
8220 from or to the array.
8222 Moreover, the use of type punning or aliasing to toggle the storage order
8223 is not supported; that is to say, a given scalar object cannot be accessed
8224 through distinct types that assign a different storage order to it.
8226 @item transparent_union
8227 @cindex @code{transparent_union} type attribute
8229 This attribute, attached to a @code{union} type definition, indicates
8230 that any function parameter having that union type causes calls to that
8231 function to be treated in a special way.
8233 First, the argument corresponding to a transparent union type can be of
8234 any type in the union; no cast is required. Also, if the union contains
8235 a pointer type, the corresponding argument can be a null pointer
8236 constant or a void pointer expression; and if the union contains a void
8237 pointer type, the corresponding argument can be any pointer expression.
8238 If the union member type is a pointer, qualifiers like @code{const} on
8239 the referenced type must be respected, just as with normal pointer
8242 Second, the argument is passed to the function using the calling
8243 conventions of the first member of the transparent union, not the calling
8244 conventions of the union itself. All members of the union must have the
8245 same machine representation; this is necessary for this argument passing
8248 Transparent unions are designed for library functions that have multiple
8249 interfaces for compatibility reasons. For example, suppose the
8250 @code{wait} function must accept either a value of type @code{int *} to
8251 comply with POSIX, or a value of type @code{union wait *} to comply with
8252 the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
8253 @code{wait} would accept both kinds of arguments, but it would also
8254 accept any other pointer type and this would make argument type checking
8255 less useful. Instead, @code{<sys/wait.h>} might define the interface
8259 typedef union __attribute__ ((__transparent_union__))
8263 @} wait_status_ptr_t;
8265 pid_t wait (wait_status_ptr_t);
8269 This interface allows either @code{int *} or @code{union wait *}
8270 arguments to be passed, using the @code{int *} calling convention.
8271 The program can call @code{wait} with arguments of either type:
8274 int w1 () @{ int w; return wait (&w); @}
8275 int w2 () @{ union wait w; return wait (&w); @}
8279 With this interface, @code{wait}'s implementation might look like this:
8282 pid_t wait (wait_status_ptr_t p)
8284 return waitpid (-1, p.__ip, 0);
8289 @cindex @code{unused} type attribute
8290 When attached to a type (including a @code{union} or a @code{struct}),
8291 this attribute means that variables of that type are meant to appear
8292 possibly unused. GCC does not produce a warning for any variables of
8293 that type, even if the variable appears to do nothing. This is often
8294 the case with lock or thread classes, which are usually defined and then
8295 not referenced, but contain constructors and destructors that have
8296 nontrivial bookkeeping functions.
8298 @item vector_size (@var{bytes})
8299 @cindex @code{vector_size} type attribute
8300 This attribute specifies the vector size for the type, measured in bytes.
8301 The type to which it applies is known as the @dfn{base type}. The @var{bytes}
8302 argument must be a positive power-of-two multiple of the base type size. For
8303 example, the following declarations:
8306 typedef __attribute__ ((vector_size (32))) int int_vec32_t ;
8307 typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t;
8308 typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3];
8312 define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int}
8313 sized units. With @code{int} having a size of 4 bytes, the type defines
8314 a vector of eight units, four bytes each. The mode of variables of type
8315 @code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined
8316 to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be
8317 an array of three such vectors. @xref{Vector Extensions}, for details of
8318 manipulating objects of vector types.
8320 This attribute is only applicable to integral and floating scalar types.
8321 In function declarations the attribute applies to the function return
8324 For example, the following:
8326 __attribute__ ((vector_size (16))) float get_flt_vec16 (void);
8328 declares @code{get_flt_vec16} to be a function returning a 16-byte vector
8329 with the base type @code{float}.
8332 @cindex @code{visibility} type attribute
8333 In C++, attribute visibility (@pxref{Function Attributes}) can also be
8334 applied to class, struct, union and enum types. Unlike other type
8335 attributes, the attribute must appear between the initial keyword and
8336 the name of the type; it cannot appear after the body of the type.
8338 Note that the type visibility is applied to vague linkage entities
8339 associated with the class (vtable, typeinfo node, etc.). In
8340 particular, if a class is thrown as an exception in one shared object
8341 and caught in another, the class must have default visibility.
8342 Otherwise the two shared objects are unable to use the same
8343 typeinfo node and exception handling will break.
8347 To specify multiple attributes, separate them by commas within the
8348 double parentheses: for example, @samp{__attribute__ ((aligned (16),
8351 @node ARC Type Attributes
8352 @subsection ARC Type Attributes
8354 @cindex @code{uncached} type attribute, ARC
8355 Declaring objects with @code{uncached} allows you to exclude
8356 data-cache participation in load and store operations on those objects
8357 without involving the additional semantic implications of
8358 @code{volatile}. The @code{.di} instruction suffix is used for all
8359 loads and stores of data declared @code{uncached}.
8361 @node ARM Type Attributes
8362 @subsection ARM Type Attributes
8364 @cindex @code{notshared} type attribute, ARM
8365 On those ARM targets that support @code{dllimport} (such as Symbian
8366 OS), you can use the @code{notshared} attribute to indicate that the
8367 virtual table and other similar data for a class should not be
8368 exported from a DLL@. For example:
8371 class __declspec(notshared) C @{
8373 __declspec(dllimport) C();
8377 __declspec(dllexport)
8382 In this code, @code{C::C} is exported from the current DLL, but the
8383 virtual table for @code{C} is not exported. (You can use
8384 @code{__attribute__} instead of @code{__declspec} if you prefer, but
8385 most Symbian OS code uses @code{__declspec}.)
8387 @node MeP Type Attributes
8388 @subsection MeP Type Attributes
8390 @cindex @code{based} type attribute, MeP
8391 @cindex @code{tiny} type attribute, MeP
8392 @cindex @code{near} type attribute, MeP
8393 @cindex @code{far} type attribute, MeP
8394 Many of the MeP variable attributes may be applied to types as well.
8395 Specifically, the @code{based}, @code{tiny}, @code{near}, and
8396 @code{far} attributes may be applied to either. The @code{io} and
8397 @code{cb} attributes may not be applied to types.
8399 @node PowerPC Type Attributes
8400 @subsection PowerPC Type Attributes
8402 Three attributes currently are defined for PowerPC configurations:
8403 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
8405 @cindex @code{ms_struct} type attribute, PowerPC
8406 @cindex @code{gcc_struct} type attribute, PowerPC
8407 For full documentation of the @code{ms_struct} and @code{gcc_struct}
8408 attributes please see the documentation in @ref{x86 Type Attributes}.
8410 @cindex @code{altivec} type attribute, PowerPC
8411 The @code{altivec} attribute allows one to declare AltiVec vector data
8412 types supported by the AltiVec Programming Interface Manual. The
8413 attribute requires an argument to specify one of three vector types:
8414 @code{vector__}, @code{pixel__} (always followed by unsigned short),
8415 and @code{bool__} (always followed by unsigned).
8418 __attribute__((altivec(vector__)))
8419 __attribute__((altivec(pixel__))) unsigned short
8420 __attribute__((altivec(bool__))) unsigned
8423 These attributes mainly are intended to support the @code{__vector},
8424 @code{__pixel}, and @code{__bool} AltiVec keywords.
8426 @node x86 Type Attributes
8427 @subsection x86 Type Attributes
8429 Two attributes are currently defined for x86 configurations:
8430 @code{ms_struct} and @code{gcc_struct}.
8436 @cindex @code{ms_struct} type attribute, x86
8437 @cindex @code{gcc_struct} type attribute, x86
8439 If @code{packed} is used on a structure, or if bit-fields are used
8440 it may be that the Microsoft ABI packs them differently
8441 than GCC normally packs them. Particularly when moving packed
8442 data between functions compiled with GCC and the native Microsoft compiler
8443 (either via function call or as data in a file), it may be necessary to access
8446 The @code{ms_struct} and @code{gcc_struct} attributes correspond
8447 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
8448 command-line options, respectively;
8449 see @ref{x86 Options}, for details of how structure layout is affected.
8450 @xref{x86 Variable Attributes}, for information about the corresponding
8451 attributes on variables.
8455 @node Label Attributes
8456 @section Label Attributes
8457 @cindex Label Attributes
8459 GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for
8460 details of the exact syntax for using attributes. Other attributes are
8461 available for functions (@pxref{Function Attributes}), variables
8462 (@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}),
8463 statements (@pxref{Statement Attributes}), and for types
8464 (@pxref{Type Attributes}).
8466 This example uses the @code{cold} label attribute to indicate the
8467 @code{ErrorHandling} branch is unlikely to be taken and that the
8468 @code{ErrorHandling} label is unused:
8472 asm goto ("some asm" : : : : NoError);
8474 /* This branch (the fall-through from the asm) is less commonly used */
8476 __attribute__((cold, unused)); /* Semi-colon is required here */
8481 printf("no error\n");
8487 @cindex @code{unused} label attribute
8488 This feature is intended for program-generated code that may contain
8489 unused labels, but which is compiled with @option{-Wall}. It is
8490 not normally appropriate to use in it human-written code, though it
8491 could be useful in cases where the code that jumps to the label is
8492 contained within an @code{#ifdef} conditional.
8495 @cindex @code{hot} label attribute
8496 The @code{hot} attribute on a label is used to inform the compiler that
8497 the path following the label is more likely than paths that are not so
8498 annotated. This attribute is used in cases where @code{__builtin_expect}
8499 cannot be used, for instance with computed goto or @code{asm goto}.
8502 @cindex @code{cold} label attribute
8503 The @code{cold} attribute on labels is used to inform the compiler that
8504 the path following the label is unlikely to be executed. This attribute
8505 is used in cases where @code{__builtin_expect} cannot be used, for instance
8506 with computed goto or @code{asm goto}.
8510 @node Enumerator Attributes
8511 @section Enumerator Attributes
8512 @cindex Enumerator Attributes
8514 GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for
8515 details of the exact syntax for using attributes. Other attributes are
8516 available for functions (@pxref{Function Attributes}), variables
8517 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements
8518 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
8520 This example uses the @code{deprecated} enumerator attribute to indicate the
8521 @code{oldval} enumerator is deprecated:
8525 oldval __attribute__((deprecated)),
8538 @cindex @code{deprecated} enumerator attribute
8539 The @code{deprecated} attribute results in a warning if the enumerator
8540 is used anywhere in the source file. This is useful when identifying
8541 enumerators that are expected to be removed in a future version of a
8542 program. The warning also includes the location of the declaration
8543 of the deprecated enumerator, to enable users to easily find further
8544 information about why the enumerator is deprecated, or what they should
8545 do instead. Note that the warnings only occurs for uses.
8549 @node Statement Attributes
8550 @section Statement Attributes
8551 @cindex Statement Attributes
8553 GCC allows attributes to be set on null statements. @xref{Attribute Syntax},
8554 for details of the exact syntax for using attributes. Other attributes are
8555 available for functions (@pxref{Function Attributes}), variables
8556 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators
8557 (@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}).
8559 This example uses the @code{fallthrough} statement attribute to indicate that
8560 the @option{-Wimplicit-fallthrough} warning should not be emitted:
8567 __attribute__((fallthrough));
8575 @cindex @code{fallthrough} statement attribute
8576 The @code{fallthrough} attribute with a null statement serves as a
8577 fallthrough statement. It hints to the compiler that a statement
8578 that falls through to another case label, or user-defined label
8579 in a switch statement is intentional and thus the
8580 @option{-Wimplicit-fallthrough} warning must not trigger. The
8581 fallthrough attribute may appear at most once in each attribute
8582 list, and may not be mixed with other attributes. It can only
8583 be used in a switch statement (the compiler will issue an error
8584 otherwise), after a preceding statement and before a logically
8585 succeeding case label, or user-defined label.
8589 @node Attribute Syntax
8590 @section Attribute Syntax
8591 @cindex attribute syntax
8593 This section describes the syntax with which @code{__attribute__} may be
8594 used, and the constructs to which attribute specifiers bind, for the C
8595 language. Some details may vary for C++ and Objective-C@. Because of
8596 infelicities in the grammar for attributes, some forms described here
8597 may not be successfully parsed in all cases.
8599 There are some problems with the semantics of attributes in C++. For
8600 example, there are no manglings for attributes, although they may affect
8601 code generation, so problems may arise when attributed types are used in
8602 conjunction with templates or overloading. Similarly, @code{typeid}
8603 does not distinguish between types with different attributes. Support
8604 for attributes in C++ may be restricted in future to attributes on
8605 declarations only, but not on nested declarators.
8607 @xref{Function Attributes}, for details of the semantics of attributes
8608 applying to functions. @xref{Variable Attributes}, for details of the
8609 semantics of attributes applying to variables. @xref{Type Attributes},
8610 for details of the semantics of attributes applying to structure, union
8611 and enumerated types.
8612 @xref{Label Attributes}, for details of the semantics of attributes
8614 @xref{Enumerator Attributes}, for details of the semantics of attributes
8615 applying to enumerators.
8616 @xref{Statement Attributes}, for details of the semantics of attributes
8617 applying to statements.
8619 An @dfn{attribute specifier} is of the form
8620 @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
8621 is a possibly empty comma-separated sequence of @dfn{attributes}, where
8622 each attribute is one of the following:
8626 Empty. Empty attributes are ignored.
8630 (which may be an identifier such as @code{unused}, or a reserved
8631 word such as @code{const}).
8634 An attribute name followed by a parenthesized list of
8635 parameters for the attribute.
8636 These parameters take one of the following forms:
8640 An identifier. For example, @code{mode} attributes use this form.
8643 An identifier followed by a comma and a non-empty comma-separated list
8644 of expressions. For example, @code{format} attributes use this form.
8647 A possibly empty comma-separated list of expressions. For example,
8648 @code{format_arg} attributes use this form with the list being a single
8649 integer constant expression, and @code{alias} attributes use this form
8650 with the list being a single string constant.
8654 An @dfn{attribute specifier list} is a sequence of one or more attribute
8655 specifiers, not separated by any other tokens.
8657 You may optionally specify attribute names with @samp{__}
8658 preceding and following the name.
8659 This allows you to use them in header files without
8660 being concerned about a possible macro of the same name. For example,
8661 you may use the attribute name @code{__noreturn__} instead of @code{noreturn}.
8664 @subsubheading Label Attributes
8666 In GNU C, an attribute specifier list may appear after the colon following a
8667 label, other than a @code{case} or @code{default} label. GNU C++ only permits
8668 attributes on labels if the attribute specifier is immediately
8669 followed by a semicolon (i.e., the label applies to an empty
8670 statement). If the semicolon is missing, C++ label attributes are
8671 ambiguous, as it is permissible for a declaration, which could begin
8672 with an attribute list, to be labelled in C++. Declarations cannot be
8673 labelled in C90 or C99, so the ambiguity does not arise there.
8675 @subsubheading Enumerator Attributes
8677 In GNU C, an attribute specifier list may appear as part of an enumerator.
8678 The attribute goes after the enumeration constant, before @code{=}, if
8679 present. The optional attribute in the enumerator appertains to the
8680 enumeration constant. It is not possible to place the attribute after
8681 the constant expression, if present.
8683 @subsubheading Statement Attributes
8684 In GNU C, an attribute specifier list may appear as part of a null
8685 statement. The attribute goes before the semicolon.
8687 @subsubheading Type Attributes
8689 An attribute specifier list may appear as part of a @code{struct},
8690 @code{union} or @code{enum} specifier. It may go either immediately
8691 after the @code{struct}, @code{union} or @code{enum} keyword, or after
8692 the closing brace. The former syntax is preferred.
8693 Where attribute specifiers follow the closing brace, they are considered
8694 to relate to the structure, union or enumerated type defined, not to any
8695 enclosing declaration the type specifier appears in, and the type
8696 defined is not complete until after the attribute specifiers.
8697 @c Otherwise, there would be the following problems: a shift/reduce
8698 @c conflict between attributes binding the struct/union/enum and
8699 @c binding to the list of specifiers/qualifiers; and "aligned"
8700 @c attributes could use sizeof for the structure, but the size could be
8701 @c changed later by "packed" attributes.
8704 @subsubheading All other attributes
8706 Otherwise, an attribute specifier appears as part of a declaration,
8707 counting declarations of unnamed parameters and type names, and relates
8708 to that declaration (which may be nested in another declaration, for
8709 example in the case of a parameter declaration), or to a particular declarator
8710 within a declaration. Where an
8711 attribute specifier is applied to a parameter declared as a function or
8712 an array, it should apply to the function or array rather than the
8713 pointer to which the parameter is implicitly converted, but this is not
8714 yet correctly implemented.
8716 Any list of specifiers and qualifiers at the start of a declaration may
8717 contain attribute specifiers, whether or not such a list may in that
8718 context contain storage class specifiers. (Some attributes, however,
8719 are essentially in the nature of storage class specifiers, and only make
8720 sense where storage class specifiers may be used; for example,
8721 @code{section}.) There is one necessary limitation to this syntax: the
8722 first old-style parameter declaration in a function definition cannot
8723 begin with an attribute specifier, because such an attribute applies to
8724 the function instead by syntax described below (which, however, is not
8725 yet implemented in this case). In some other cases, attribute
8726 specifiers are permitted by this grammar but not yet supported by the
8727 compiler. All attribute specifiers in this place relate to the
8728 declaration as a whole. In the obsolescent usage where a type of
8729 @code{int} is implied by the absence of type specifiers, such a list of
8730 specifiers and qualifiers may be an attribute specifier list with no
8731 other specifiers or qualifiers.
8733 At present, the first parameter in a function prototype must have some
8734 type specifier that is not an attribute specifier; this resolves an
8735 ambiguity in the interpretation of @code{void f(int
8736 (__attribute__((foo)) x))}, but is subject to change. At present, if
8737 the parentheses of a function declarator contain only attributes then
8738 those attributes are ignored, rather than yielding an error or warning
8739 or implying a single parameter of type int, but this is subject to
8742 An attribute specifier list may appear immediately before a declarator
8743 (other than the first) in a comma-separated list of declarators in a
8744 declaration of more than one identifier using a single list of
8745 specifiers and qualifiers. Such attribute specifiers apply
8746 only to the identifier before whose declarator they appear. For
8750 __attribute__((noreturn)) void d0 (void),
8751 __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
8756 the @code{noreturn} attribute applies to all the functions
8757 declared; the @code{format} attribute only applies to @code{d1}.
8759 An attribute specifier list may appear immediately before the comma,
8760 @code{=} or semicolon terminating the declaration of an identifier other
8761 than a function definition. Such attribute specifiers apply
8762 to the declared object or function. Where an
8763 assembler name for an object or function is specified (@pxref{Asm
8764 Labels}), the attribute must follow the @code{asm}
8767 An attribute specifier list may, in future, be permitted to appear after
8768 the declarator in a function definition (before any old-style parameter
8769 declarations or the function body).
8771 Attribute specifiers may be mixed with type qualifiers appearing inside
8772 the @code{[]} of a parameter array declarator, in the C99 construct by
8773 which such qualifiers are applied to the pointer to which the array is
8774 implicitly converted. Such attribute specifiers apply to the pointer,
8775 not to the array, but at present this is not implemented and they are
8778 An attribute specifier list may appear at the start of a nested
8779 declarator. At present, there are some limitations in this usage: the
8780 attributes correctly apply to the declarator, but for most individual
8781 attributes the semantics this implies are not implemented.
8782 When attribute specifiers follow the @code{*} of a pointer
8783 declarator, they may be mixed with any type qualifiers present.
8784 The following describes the formal semantics of this syntax. It makes the
8785 most sense if you are familiar with the formal specification of
8786 declarators in the ISO C standard.
8788 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
8789 D1}, where @code{T} contains declaration specifiers that specify a type
8790 @var{Type} (such as @code{int}) and @code{D1} is a declarator that
8791 contains an identifier @var{ident}. The type specified for @var{ident}
8792 for derived declarators whose type does not include an attribute
8793 specifier is as in the ISO C standard.
8795 If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
8796 and the declaration @code{T D} specifies the type
8797 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
8798 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
8799 @var{attribute-specifier-list} @var{Type}'' for @var{ident}.
8801 If @code{D1} has the form @code{*
8802 @var{type-qualifier-and-attribute-specifier-list} D}, and the
8803 declaration @code{T D} specifies the type
8804 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
8805 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
8806 @var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for
8812 void (__attribute__((noreturn)) ****f) (void);
8816 specifies the type ``pointer to pointer to pointer to pointer to
8817 non-returning function returning @code{void}''. As another example,
8820 char *__attribute__((aligned(8))) *f;
8824 specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
8825 Note again that this does not work with most attributes; for example,
8826 the usage of @samp{aligned} and @samp{noreturn} attributes given above
8827 is not yet supported.
8829 For compatibility with existing code written for compiler versions that
8830 did not implement attributes on nested declarators, some laxity is
8831 allowed in the placing of attributes. If an attribute that only applies
8832 to types is applied to a declaration, it is treated as applying to
8833 the type of that declaration. If an attribute that only applies to
8834 declarations is applied to the type of a declaration, it is treated
8835 as applying to that declaration; and, for compatibility with code
8836 placing the attributes immediately before the identifier declared, such
8837 an attribute applied to a function return type is treated as
8838 applying to the function type, and such an attribute applied to an array
8839 element type is treated as applying to the array type. If an
8840 attribute that only applies to function types is applied to a
8841 pointer-to-function type, it is treated as applying to the pointer
8842 target type; if such an attribute is applied to a function return type
8843 that is not a pointer-to-function type, it is treated as applying
8844 to the function type.
8846 @node Function Prototypes
8847 @section Prototypes and Old-Style Function Definitions
8848 @cindex function prototype declarations
8849 @cindex old-style function definitions
8850 @cindex promotion of formal parameters
8852 GNU C extends ISO C to allow a function prototype to override a later
8853 old-style non-prototype definition. Consider the following example:
8856 /* @r{Use prototypes unless the compiler is old-fashioned.} */
8863 /* @r{Prototype function declaration.} */
8864 int isroot P((uid_t));
8866 /* @r{Old-style function definition.} */
8868 isroot (x) /* @r{??? lossage here ???} */
8875 Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
8876 not allow this example, because subword arguments in old-style
8877 non-prototype definitions are promoted. Therefore in this example the
8878 function definition's argument is really an @code{int}, which does not
8879 match the prototype argument type of @code{short}.
8881 This restriction of ISO C makes it hard to write code that is portable
8882 to traditional C compilers, because the programmer does not know
8883 whether the @code{uid_t} type is @code{short}, @code{int}, or
8884 @code{long}. Therefore, in cases like these GNU C allows a prototype
8885 to override a later old-style definition. More precisely, in GNU C, a
8886 function prototype argument type overrides the argument type specified
8887 by a later old-style definition if the former type is the same as the
8888 latter type before promotion. Thus in GNU C the above example is
8889 equivalent to the following:
8902 GNU C++ does not support old-style function definitions, so this
8903 extension is irrelevant.
8906 @section C++ Style Comments
8908 @cindex C++ comments
8909 @cindex comments, C++ style
8911 In GNU C, you may use C++ style comments, which start with @samp{//} and
8912 continue until the end of the line. Many other C implementations allow
8913 such comments, and they are included in the 1999 C standard. However,
8914 C++ style comments are not recognized if you specify an @option{-std}
8915 option specifying a version of ISO C before C99, or @option{-ansi}
8916 (equivalent to @option{-std=c90}).
8919 @section Dollar Signs in Identifier Names
8921 @cindex dollar signs in identifier names
8922 @cindex identifier names, dollar signs in
8924 In GNU C, you may normally use dollar signs in identifier names.
8925 This is because many traditional C implementations allow such identifiers.
8926 However, dollar signs in identifiers are not supported on a few target
8927 machines, typically because the target assembler does not allow them.
8929 @node Character Escapes
8930 @section The Character @key{ESC} in Constants
8932 You can use the sequence @samp{\e} in a string or character constant to
8933 stand for the ASCII character @key{ESC}.
8936 @section Determining the Alignment of Functions, Types or Variables
8938 @cindex type alignment
8939 @cindex variable alignment
8941 The keyword @code{__alignof__} determines the alignment requirement of
8942 a function, object, or a type, or the minimum alignment usually required
8943 by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}.
8945 For example, if the target machine requires a @code{double} value to be
8946 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
8947 This is true on many RISC machines. On more traditional machine
8948 designs, @code{__alignof__ (double)} is 4 or even 2.
8950 Some machines never actually require alignment; they allow references to any
8951 data type even at an odd address. For these machines, @code{__alignof__}
8952 reports the smallest alignment that GCC gives the data type, usually as
8953 mandated by the target ABI.
8955 If the operand of @code{__alignof__} is an lvalue rather than a type,
8956 its value is the required alignment for its type, taking into account
8957 any minimum alignment specified by attribute @code{aligned}
8958 (@pxref{Common Variable Attributes}). For example, after this
8962 struct foo @{ int x; char y; @} foo1;
8966 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
8967 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
8968 It is an error to ask for the alignment of an incomplete type other
8971 If the operand of the @code{__alignof__} expression is a function,
8972 the expression evaluates to the alignment of the function which may
8973 be specified by attribute @code{aligned} (@pxref{Common Function Attributes}).
8976 @section An Inline Function is As Fast As a Macro
8977 @cindex inline functions
8978 @cindex integrating function code
8980 @cindex macros, inline alternative
8982 By declaring a function inline, you can direct GCC to make
8983 calls to that function faster. One way GCC can achieve this is to
8984 integrate that function's code into the code for its callers. This
8985 makes execution faster by eliminating the function-call overhead; in
8986 addition, if any of the actual argument values are constant, their
8987 known values may permit simplifications at compile time so that not
8988 all of the inline function's code needs to be included. The effect on
8989 code size is less predictable; object code may be larger or smaller
8990 with function inlining, depending on the particular case. You can
8991 also direct GCC to try to integrate all ``simple enough'' functions
8992 into their callers with the option @option{-finline-functions}.
8994 GCC implements three different semantics of declaring a function
8995 inline. One is available with @option{-std=gnu89} or
8996 @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
8997 on all inline declarations, another when
8999 @option{-std=gnu99} or an option for a later C version is used
9000 (without @option{-fgnu89-inline}), and the third
9001 is used when compiling C++.
9003 To declare a function inline, use the @code{inline} keyword in its
9004 declaration, like this:
9014 If you are writing a header file to be included in ISO C90 programs, write
9015 @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
9017 The three types of inlining behave similarly in two important cases:
9018 when the @code{inline} keyword is used on a @code{static} function,
9019 like the example above, and when a function is first declared without
9020 using the @code{inline} keyword and then is defined with
9021 @code{inline}, like this:
9024 extern int inc (int *a);
9032 In both of these common cases, the program behaves the same as if you
9033 had not used the @code{inline} keyword, except for its speed.
9035 @cindex inline functions, omission of
9036 @opindex fkeep-inline-functions
9037 When a function is both inline and @code{static}, if all calls to the
9038 function are integrated into the caller, and the function's address is
9039 never used, then the function's own assembler code is never referenced.
9040 In this case, GCC does not actually output assembler code for the
9041 function, unless you specify the option @option{-fkeep-inline-functions}.
9042 If there is a nonintegrated call, then the function is compiled to
9043 assembler code as usual. The function must also be compiled as usual if
9044 the program refers to its address, because that cannot be inlined.
9047 Note that certain usages in a function definition can make it unsuitable
9048 for inline substitution. Among these usages are: variadic functions,
9049 use of @code{alloca}, use of computed goto (@pxref{Labels as Values}),
9050 use of nonlocal goto, use of nested functions, use of @code{setjmp}, use
9051 of @code{__builtin_longjmp} and use of @code{__builtin_return} or
9052 @code{__builtin_apply_args}. Using @option{-Winline} warns when a
9053 function marked @code{inline} could not be substituted, and gives the
9054 reason for the failure.
9056 @cindex automatic @code{inline} for C++ member fns
9057 @cindex @code{inline} automatic for C++ member fns
9058 @cindex member fns, automatically @code{inline}
9059 @cindex C++ member fns, automatically @code{inline}
9060 @opindex fno-default-inline
9061 As required by ISO C++, GCC considers member functions defined within
9062 the body of a class to be marked inline even if they are
9063 not explicitly declared with the @code{inline} keyword. You can
9064 override this with @option{-fno-default-inline}; @pxref{C++ Dialect
9065 Options,,Options Controlling C++ Dialect}.
9067 GCC does not inline any functions when not optimizing unless you specify
9068 the @samp{always_inline} attribute for the function, like this:
9071 /* @r{Prototype.} */
9072 inline void foo (const char) __attribute__((always_inline));
9075 The remainder of this section is specific to GNU C90 inlining.
9077 @cindex non-static inline function
9078 When an inline function is not @code{static}, then the compiler must assume
9079 that there may be calls from other source files; since a global symbol can
9080 be defined only once in any program, the function must not be defined in
9081 the other source files, so the calls therein cannot be integrated.
9082 Therefore, a non-@code{static} inline function is always compiled on its
9083 own in the usual fashion.
9085 If you specify both @code{inline} and @code{extern} in the function
9086 definition, then the definition is used only for inlining. In no case
9087 is the function compiled on its own, not even if you refer to its
9088 address explicitly. Such an address becomes an external reference, as
9089 if you had only declared the function, and had not defined it.
9091 This combination of @code{inline} and @code{extern} has almost the
9092 effect of a macro. The way to use it is to put a function definition in
9093 a header file with these keywords, and put another copy of the
9094 definition (lacking @code{inline} and @code{extern}) in a library file.
9095 The definition in the header file causes most calls to the function
9096 to be inlined. If any uses of the function remain, they refer to
9097 the single copy in the library.
9100 @section When is a Volatile Object Accessed?
9101 @cindex accessing volatiles
9102 @cindex volatile read
9103 @cindex volatile write
9104 @cindex volatile access
9106 C has the concept of volatile objects. These are normally accessed by
9107 pointers and used for accessing hardware or inter-thread
9108 communication. The standard encourages compilers to refrain from
9109 optimizations concerning accesses to volatile objects, but leaves it
9110 implementation defined as to what constitutes a volatile access. The
9111 minimum requirement is that at a sequence point all previous accesses
9112 to volatile objects have stabilized and no subsequent accesses have
9113 occurred. Thus an implementation is free to reorder and combine
9114 volatile accesses that occur between sequence points, but cannot do
9115 so for accesses across a sequence point. The use of volatile does
9116 not allow you to violate the restriction on updating objects multiple
9117 times between two sequence points.
9119 Accesses to non-volatile objects are not ordered with respect to
9120 volatile accesses. You cannot use a volatile object as a memory
9121 barrier to order a sequence of writes to non-volatile memory. For
9125 int *ptr = @var{something};
9127 *ptr = @var{something};
9132 Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed
9133 that the write to @var{*ptr} occurs by the time the update
9134 of @var{vobj} happens. If you need this guarantee, you must use
9135 a stronger memory barrier such as:
9138 int *ptr = @var{something};
9140 *ptr = @var{something};
9141 asm volatile ("" : : : "memory");
9145 A scalar volatile object is read when it is accessed in a void context:
9148 volatile int *src = @var{somevalue};
9152 Such expressions are rvalues, and GCC implements this as a
9153 read of the volatile object being pointed to.
9155 Assignments are also expressions and have an rvalue. However when
9156 assigning to a scalar volatile, the volatile object is not reread,
9157 regardless of whether the assignment expression's rvalue is used or
9158 not. If the assignment's rvalue is used, the value is that assigned
9159 to the volatile object. For instance, there is no read of @var{vobj}
9160 in all the following cases:
9165 vobj = @var{something};
9166 obj = vobj = @var{something};
9167 obj ? vobj = @var{onething} : vobj = @var{anotherthing};
9168 obj = (@var{something}, vobj = @var{anotherthing});
9171 If you need to read the volatile object after an assignment has
9172 occurred, you must use a separate expression with an intervening
9175 As bit-fields are not individually addressable, volatile bit-fields may
9176 be implicitly read when written to, or when adjacent bit-fields are
9177 accessed. Bit-field operations may be optimized such that adjacent
9178 bit-fields are only partially accessed, if they straddle a storage unit
9179 boundary. For these reasons it is unwise to use volatile bit-fields to
9182 @node Using Assembly Language with C
9183 @section How to Use Inline Assembly Language in C Code
9184 @cindex @code{asm} keyword
9185 @cindex assembly language in C
9186 @cindex inline assembly language
9187 @cindex mixing assembly language and C
9189 The @code{asm} keyword allows you to embed assembler instructions
9190 within C code. GCC provides two forms of inline @code{asm}
9191 statements. A @dfn{basic @code{asm}} statement is one with no
9192 operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}}
9193 statement (@pxref{Extended Asm}) includes one or more operands.
9194 The extended form is preferred for mixing C and assembly language
9195 within a function, but to include assembly language at
9196 top level you must use basic @code{asm}.
9198 You can also use the @code{asm} keyword to override the assembler name
9199 for a C symbol, or to place a C variable in a specific register.
9202 * Basic Asm:: Inline assembler without operands.
9203 * Extended Asm:: Inline assembler with operands.
9204 * Constraints:: Constraints for @code{asm} operands
9205 * Asm Labels:: Specifying the assembler name to use for a C symbol.
9206 * Explicit Register Variables:: Defining variables residing in specified
9208 * Size of an asm:: How GCC calculates the size of an @code{asm} block.
9212 @subsection Basic Asm --- Assembler Instructions Without Operands
9213 @cindex basic @code{asm}
9214 @cindex assembly language in C, basic
9216 A basic @code{asm} statement has the following syntax:
9219 asm @var{asm-qualifiers} ( @var{AssemblerInstructions} )
9222 The @code{asm} keyword is a GNU extension.
9223 When writing code that can be compiled with @option{-ansi} and the
9224 various @option{-std} options, use @code{__asm__} instead of
9225 @code{asm} (@pxref{Alternate Keywords}).
9227 @subsubheading Qualifiers
9230 The optional @code{volatile} qualifier has no effect.
9231 All basic @code{asm} blocks are implicitly volatile.
9234 If you use the @code{inline} qualifier, then for inlining purposes the size
9235 of the @code{asm} statement is taken as the smallest size possible (@pxref{Size
9239 @subsubheading Parameters
9242 @item AssemblerInstructions
9243 This is a literal string that specifies the assembler code. The string can
9244 contain any instructions recognized by the assembler, including directives.
9245 GCC does not parse the assembler instructions themselves and
9246 does not know what they mean or even whether they are valid assembler input.
9248 You may place multiple assembler instructions together in a single @code{asm}
9249 string, separated by the characters normally used in assembly code for the
9250 system. A combination that works in most places is a newline to break the
9251 line, plus a tab character (written as @samp{\n\t}).
9252 Some assemblers allow semicolons as a line separator. However,
9253 note that some assembler dialects use semicolons to start a comment.
9256 @subsubheading Remarks
9257 Using extended @code{asm} (@pxref{Extended Asm}) typically produces
9258 smaller, safer, and more efficient code, and in most cases it is a
9259 better solution than basic @code{asm}. However, there are two
9260 situations where only basic @code{asm} can be used:
9264 Extended @code{asm} statements have to be inside a C
9265 function, so to write inline assembly language at file scope (``top-level''),
9266 outside of C functions, you must use basic @code{asm}.
9267 You can use this technique to emit assembler directives,
9268 define assembly language macros that can be invoked elsewhere in the file,
9269 or write entire functions in assembly language.
9270 Basic @code{asm} statements outside of functions may not use any
9275 with the @code{naked} attribute also require basic @code{asm}
9276 (@pxref{Function Attributes}).
9279 Safely accessing C data and calling functions from basic @code{asm} is more
9280 complex than it may appear. To access C data, it is better to use extended
9283 Do not expect a sequence of @code{asm} statements to remain perfectly
9284 consecutive after compilation. If certain instructions need to remain
9285 consecutive in the output, put them in a single multi-instruction @code{asm}
9286 statement. Note that GCC's optimizers can move @code{asm} statements
9287 relative to other code, including across jumps.
9289 @code{asm} statements may not perform jumps into other @code{asm} statements.
9290 GCC does not know about these jumps, and therefore cannot take
9291 account of them when deciding how to optimize. Jumps from @code{asm} to C
9292 labels are only supported in extended @code{asm}.
9294 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
9295 assembly code when optimizing. This can lead to unexpected duplicate
9296 symbol errors during compilation if your assembly code defines symbols or
9299 @strong{Warning:} The C standards do not specify semantics for @code{asm},
9300 making it a potential source of incompatibilities between compilers. These
9301 incompatibilities may not produce compiler warnings/errors.
9303 GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which
9304 means there is no way to communicate to the compiler what is happening
9305 inside them. GCC has no visibility of symbols in the @code{asm} and may
9306 discard them as unreferenced. It also does not know about side effects of
9307 the assembler code, such as modifications to memory or registers. Unlike
9308 some compilers, GCC assumes that no changes to general purpose registers
9309 occur. This assumption may change in a future release.
9311 To avoid complications from future changes to the semantics and the
9312 compatibility issues between compilers, consider replacing basic @code{asm}
9313 with extended @code{asm}. See
9314 @uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert
9315 from basic asm to extended asm} for information about how to perform this
9318 The compiler copies the assembler instructions in a basic @code{asm}
9319 verbatim to the assembly language output file, without
9320 processing dialects or any of the @samp{%} operators that are available with
9321 extended @code{asm}. This results in minor differences between basic
9322 @code{asm} strings and extended @code{asm} templates. For example, to refer to
9323 registers you might use @samp{%eax} in basic @code{asm} and
9324 @samp{%%eax} in extended @code{asm}.
9326 On targets such as x86 that support multiple assembler dialects,
9327 all basic @code{asm} blocks use the assembler dialect specified by the
9328 @option{-masm} command-line option (@pxref{x86 Options}).
9329 Basic @code{asm} provides no
9330 mechanism to provide different assembler strings for different dialects.
9332 For basic @code{asm} with non-empty assembler string GCC assumes
9333 the assembler block does not change any general purpose registers,
9334 but it may read or write any globally accessible variable.
9336 Here is an example of basic @code{asm} for i386:
9339 /* Note that this code will not compile with -masm=intel */
9340 #define DebugBreak() asm("int $3")
9344 @subsection Extended Asm - Assembler Instructions with C Expression Operands
9345 @cindex extended @code{asm}
9346 @cindex assembly language in C, extended
9348 With extended @code{asm} you can read and write C variables from
9349 assembler and perform jumps from assembler code to C labels.
9350 Extended @code{asm} syntax uses colons (@samp{:}) to delimit
9351 the operand parameters after the assembler template:
9354 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9355 : @var{OutputOperands}
9356 @r{[} : @var{InputOperands}
9357 @r{[} : @var{Clobbers} @r{]} @r{]})
9359 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9361 : @var{InputOperands}
9365 where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the
9368 The @code{asm} keyword is a GNU extension.
9369 When writing code that can be compiled with @option{-ansi} and the
9370 various @option{-std} options, use @code{__asm__} instead of
9371 @code{asm} (@pxref{Alternate Keywords}).
9373 @subsubheading Qualifiers
9377 The typical use of extended @code{asm} statements is to manipulate input
9378 values to produce output values. However, your @code{asm} statements may
9379 also produce side effects. If so, you may need to use the @code{volatile}
9380 qualifier to disable certain optimizations. @xref{Volatile}.
9383 If you use the @code{inline} qualifier, then for inlining purposes the size
9384 of the @code{asm} statement is taken as the smallest size possible
9385 (@pxref{Size of an asm}).
9388 This qualifier informs the compiler that the @code{asm} statement may
9389 perform a jump to one of the labels listed in the @var{GotoLabels}.
9393 @subsubheading Parameters
9395 @item AssemblerTemplate
9396 This is a literal string that is the template for the assembler code. It is a
9397 combination of fixed text and tokens that refer to the input, output,
9398 and goto parameters. @xref{AssemblerTemplate}.
9400 @item OutputOperands
9401 A comma-separated list of the C variables modified by the instructions in the
9402 @var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}.
9405 A comma-separated list of C expressions read by the instructions in the
9406 @var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}.
9409 A comma-separated list of registers or other values changed by the
9410 @var{AssemblerTemplate}, beyond those listed as outputs.
9411 An empty list is permitted. @xref{Clobbers and Scratch Registers}.
9414 When you are using the @code{goto} form of @code{asm}, this section contains
9415 the list of all C labels to which the code in the
9416 @var{AssemblerTemplate} may jump.
9419 @code{asm} statements may not perform jumps into other @code{asm} statements,
9420 only to the listed @var{GotoLabels}.
9421 GCC's optimizers do not know about other jumps; therefore they cannot take
9422 account of them when deciding how to optimize.
9425 The total number of input + output + goto operands is limited to 30.
9427 @subsubheading Remarks
9428 The @code{asm} statement allows you to include assembly instructions directly
9429 within C code. This may help you to maximize performance in time-sensitive
9430 code or to access assembly instructions that are not readily available to C
9433 Note that extended @code{asm} statements must be inside a function. Only
9434 basic @code{asm} may be outside functions (@pxref{Basic Asm}).
9435 Functions declared with the @code{naked} attribute also require basic
9436 @code{asm} (@pxref{Function Attributes}).
9438 While the uses of @code{asm} are many and varied, it may help to think of an
9439 @code{asm} statement as a series of low-level instructions that convert input
9440 parameters to output parameters. So a simple (if not particularly useful)
9441 example for i386 using @code{asm} might look like this:
9447 asm ("mov %1, %0\n\t"
9452 printf("%d\n", dst);
9455 This code copies @code{src} to @code{dst} and add 1 to @code{dst}.
9458 @subsubsection Volatile
9459 @cindex volatile @code{asm}
9460 @cindex @code{asm} volatile
9462 GCC's optimizers sometimes discard @code{asm} statements if they determine
9463 there is no need for the output variables. Also, the optimizers may move
9464 code out of loops if they believe that the code will always return the same
9465 result (i.e.@: none of its input values change between calls). Using the
9466 @code{volatile} qualifier disables these optimizations. @code{asm} statements
9467 that have no output operands, including @code{asm goto} statements,
9468 are implicitly volatile.
9470 This i386 code demonstrates a case that does not use (or require) the
9471 @code{volatile} qualifier. If it is performing assertion checking, this code
9472 uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is
9473 unreferenced by any code. As a result, the optimizers can discard the
9474 @code{asm} statement, which in turn removes the need for the entire
9475 @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
9476 isn't needed you allow the optimizers to produce the most efficient code
9480 void DoCheck(uint32_t dwSomeValue)
9484 // Assumes dwSomeValue is not zero.
9494 The next example shows a case where the optimizers can recognize that the input
9495 (@code{dwSomeValue}) never changes during the execution of the function and can
9496 therefore move the @code{asm} outside the loop to produce more efficient code.
9497 Again, using the @code{volatile} qualifier disables this type of optimization.
9500 void do_print(uint32_t dwSomeValue)
9504 for (uint32_t x=0; x < 5; x++)
9506 // Assumes dwSomeValue is not zero.
9512 printf("%u: %u %u\n", x, dwSomeValue, dwRes);
9517 The following example demonstrates a case where you need to use the
9518 @code{volatile} qualifier.
9519 It uses the x86 @code{rdtsc} instruction, which reads
9520 the computer's time-stamp counter. Without the @code{volatile} qualifier,
9521 the optimizers might assume that the @code{asm} block will always return the
9522 same value and therefore optimize away the second call.
9527 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
9528 "shl $32, %%rdx\n\t" // Shift the upper bits left.
9529 "or %%rdx, %0" // 'Or' in the lower bits.
9534 printf("msr: %llx\n", msr);
9538 // Reprint the timestamp
9539 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
9540 "shl $32, %%rdx\n\t" // Shift the upper bits left.
9541 "or %%rdx, %0" // 'Or' in the lower bits.
9546 printf("msr: %llx\n", msr);
9549 GCC's optimizers do not treat this code like the non-volatile code in the
9550 earlier examples. They do not move it out of loops or omit it on the
9551 assumption that the result from a previous call is still valid.
9553 Note that the compiler can move even @code{volatile asm} instructions relative
9554 to other code, including across jump instructions. For example, on many
9555 targets there is a system register that controls the rounding mode of
9556 floating-point operations. Setting it with a @code{volatile asm} statement,
9557 as in the following PowerPC example, does not work reliably.
9560 asm volatile("mtfsf 255, %0" : : "f" (fpenv));
9564 The compiler may move the addition back before the @code{volatile asm}
9565 statement. To make it work as expected, add an artificial dependency to
9566 the @code{asm} by referencing a variable in the subsequent code, for
9570 asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
9574 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
9575 assembly code when optimizing. This can lead to unexpected duplicate symbol
9576 errors during compilation if your @code{asm} code defines symbols or labels.
9578 (@pxref{AssemblerTemplate}) may help resolve this problem.
9580 @anchor{AssemblerTemplate}
9581 @subsubsection Assembler Template
9582 @cindex @code{asm} assembler template
9584 An assembler template is a literal string containing assembler instructions.
9585 The compiler replaces tokens in the template that refer
9586 to inputs, outputs, and goto labels,
9587 and then outputs the resulting string to the assembler. The
9588 string can contain any instructions recognized by the assembler, including
9589 directives. GCC does not parse the assembler instructions
9590 themselves and does not know what they mean or even whether they are valid
9591 assembler input. However, it does count the statements
9592 (@pxref{Size of an asm}).
9594 You may place multiple assembler instructions together in a single @code{asm}
9595 string, separated by the characters normally used in assembly code for the
9596 system. A combination that works in most places is a newline to break the
9597 line, plus a tab character to move to the instruction field (written as
9599 Some assemblers allow semicolons as a line separator. However, note
9600 that some assembler dialects use semicolons to start a comment.
9602 Do not expect a sequence of @code{asm} statements to remain perfectly
9603 consecutive after compilation, even when you are using the @code{volatile}
9604 qualifier. If certain instructions need to remain consecutive in the output,
9605 put them in a single multi-instruction @code{asm} statement.
9607 Accessing data from C programs without using input/output operands (such as
9608 by using global symbols directly from the assembler template) may not work as
9609 expected. Similarly, calling functions directly from an assembler template
9610 requires a detailed understanding of the target assembler and ABI.
9612 Since GCC does not parse the assembler template,
9613 it has no visibility of any
9614 symbols it references. This may result in GCC discarding those symbols as
9615 unreferenced unless they are also listed as input, output, or goto operands.
9617 @subsubheading Special format strings
9619 In addition to the tokens described by the input, output, and goto operands,
9620 these tokens have special meanings in the assembler template:
9624 Outputs a single @samp{%} into the assembler code.
9627 Outputs a number that is unique to each instance of the @code{asm}
9628 statement in the entire compilation. This option is useful when creating local
9629 labels and referring to them multiple times in a single template that
9630 generates multiple assembler instructions.
9635 Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively)
9636 into the assembler code. When unescaped, these characters have special
9637 meaning to indicate multiple assembler dialects, as described below.
9640 @subsubheading Multiple assembler dialects in @code{asm} templates
9642 On targets such as x86, GCC supports multiple assembler dialects.
9643 The @option{-masm} option controls which dialect GCC uses as its
9644 default for inline assembler. The target-specific documentation for the
9645 @option{-masm} option contains the list of supported dialects, as well as the
9646 default dialect if the option is not specified. This information may be
9647 important to understand, since assembler code that works correctly when
9648 compiled using one dialect will likely fail if compiled using another.
9651 If your code needs to support multiple assembler dialects (for example, if
9652 you are writing public headers that need to support a variety of compilation
9653 options), use constructs of this form:
9656 @{ dialect0 | dialect1 | dialect2... @}
9659 This construct outputs @code{dialect0}
9660 when using dialect #0 to compile the code,
9661 @code{dialect1} for dialect #1, etc. If there are fewer alternatives within the
9662 braces than the number of dialects the compiler supports, the construct
9665 For example, if an x86 compiler supports two dialects
9666 (@samp{att}, @samp{intel}), an
9667 assembler template such as this:
9670 "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
9674 is equivalent to one of
9677 "btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */}
9678 "bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */}
9681 Using that same compiler, this code:
9684 "xchg@{l@}\t@{%%@}ebx, %1"
9688 corresponds to either
9691 "xchgl\t%%ebx, %1" @r{/* att dialect */}
9692 "xchg\tebx, %1" @r{/* intel dialect */}
9695 There is no support for nesting dialect alternatives.
9697 @anchor{OutputOperands}
9698 @subsubsection Output Operands
9699 @cindex @code{asm} output operands
9701 An @code{asm} statement has zero or more output operands indicating the names
9702 of C variables modified by the assembler code.
9704 In this i386 example, @code{old} (referred to in the template string as
9705 @code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset}
9706 (@code{%2}) is an input:
9711 __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
9712 "sbb %0,%0" // Use the CF to calculate old.
9713 : "=r" (old), "+rm" (*Base)
9720 Operands are separated by commas. Each operand has this format:
9723 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename})
9727 @item asmSymbolicName
9728 Specifies a symbolic name for the operand.
9729 Reference the name in the assembler template
9730 by enclosing it in square brackets
9731 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
9732 that contains the definition. Any valid C variable name is acceptable,
9733 including names already defined in the surrounding code. No two operands
9734 within the same @code{asm} statement can use the same symbolic name.
9736 When not using an @var{asmSymbolicName}, use the (zero-based) position
9738 in the list of operands in the assembler template. For example if there are
9739 three output operands, use @samp{%0} in the template to refer to the first,
9740 @samp{%1} for the second, and @samp{%2} for the third.
9743 A string constant specifying constraints on the placement of the operand;
9744 @xref{Constraints}, for details.
9746 Output constraints must begin with either @samp{=} (a variable overwriting an
9747 existing value) or @samp{+} (when reading and writing). When using
9748 @samp{=}, do not assume the location contains the existing value
9749 on entry to the @code{asm}, except
9750 when the operand is tied to an input; @pxref{InputOperands,,Input Operands}.
9752 After the prefix, there must be one or more additional constraints
9753 (@pxref{Constraints}) that describe where the value resides. Common
9754 constraints include @samp{r} for register and @samp{m} for memory.
9755 When you list more than one possible location (for example, @code{"=rm"}),
9756 the compiler chooses the most efficient one based on the current context.
9757 If you list as many alternates as the @code{asm} statement allows, you permit
9758 the optimizers to produce the best possible code.
9759 If you must use a specific register, but your Machine Constraints do not
9760 provide sufficient control to select the specific register you want,
9761 local register variables may provide a solution (@pxref{Local Register
9765 Specifies a C lvalue expression to hold the output, typically a variable name.
9766 The enclosing parentheses are a required part of the syntax.
9770 When the compiler selects the registers to use to
9771 represent the output operands, it does not use any of the clobbered registers
9772 (@pxref{Clobbers and Scratch Registers}).
9774 Output operand expressions must be lvalues. The compiler cannot check whether
9775 the operands have data types that are reasonable for the instruction being
9776 executed. For output expressions that are not directly addressable (for
9777 example a bit-field), the constraint must allow a register. In that case, GCC
9778 uses the register as the output of the @code{asm}, and then stores that
9779 register into the output.
9781 Operands using the @samp{+} constraint modifier count as two operands
9782 (that is, both as input and output) towards the total maximum of 30 operands
9783 per @code{asm} statement.
9785 Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output
9786 operands that must not overlap an input. Otherwise,
9787 GCC may allocate the output operand in the same register as an unrelated
9788 input operand, on the assumption that the assembler code consumes its
9789 inputs before producing outputs. This assumption may be false if the assembler
9790 code actually consists of more than one instruction.
9792 The same problem can occur if one output parameter (@var{a}) allows a register
9793 constraint and another output parameter (@var{b}) allows a memory constraint.
9794 The code generated by GCC to access the memory address in @var{b} can contain
9795 registers which @emph{might} be shared by @var{a}, and GCC considers those
9796 registers to be inputs to the asm. As above, GCC assumes that such input
9797 registers are consumed before any outputs are written. This assumption may
9798 result in incorrect behavior if the @code{asm} statement writes to @var{a}
9800 @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a}
9801 ensures that modifying @var{a} does not affect the address referenced by
9802 @var{b}. Otherwise, the location of @var{b}
9803 is undefined if @var{a} is modified before using @var{b}.
9805 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
9806 instead of simply @samp{%2}). Typically these qualifiers are hardware
9807 dependent. The list of supported modifiers for x86 is found at
9808 @ref{x86Operandmodifiers,x86 Operand modifiers}.
9810 If the C code that follows the @code{asm} makes no use of any of the output
9811 operands, use @code{volatile} for the @code{asm} statement to prevent the
9812 optimizers from discarding the @code{asm} statement as unneeded
9813 (see @ref{Volatile}).
9815 This code makes no use of the optional @var{asmSymbolicName}. Therefore it
9816 references the first output operand as @code{%0} (were there a second, it
9817 would be @code{%1}, etc). The number of the first input operand is one greater
9818 than that of the last output operand. In this i386 example, that makes
9819 @code{Mask} referenced as @code{%1}:
9822 uint32_t Mask = 1234;
9831 That code overwrites the variable @code{Index} (@samp{=}),
9832 placing the value in a register (@samp{r}).
9833 Using the generic @samp{r} constraint instead of a constraint for a specific
9834 register allows the compiler to pick the register to use, which can result
9835 in more efficient code. This may not be possible if an assembler instruction
9836 requires a specific register.
9838 The following i386 example uses the @var{asmSymbolicName} syntax.
9840 same result as the code above, but some may consider it more readable or more
9841 maintainable since reordering index numbers is not necessary when adding or
9842 removing operands. The names @code{aIndex} and @code{aMask}
9843 are only used in this example to emphasize which
9844 names get used where.
9845 It is acceptable to reuse the names @code{Index} and @code{Mask}.
9848 uint32_t Mask = 1234;
9851 asm ("bsfl %[aMask], %[aIndex]"
9852 : [aIndex] "=r" (Index)
9853 : [aMask] "r" (Mask)
9857 Here are some more examples of output operands.
9864 asm ("mov %[e], %[d]"
9869 Here, @code{d} may either be in a register or in memory. Since the compiler
9870 might already have the current value of the @code{uint32_t} location
9871 pointed to by @code{e}
9872 in a register, you can enable it to choose the best location
9873 for @code{d} by specifying both constraints.
9875 @anchor{FlagOutputOperands}
9876 @subsubsection Flag Output Operands
9877 @cindex @code{asm} flag output operands
9879 Some targets have a special register that holds the ``flags'' for the
9880 result of an operation or comparison. Normally, the contents of that
9881 register are either unmodifed by the asm, or the @code{asm} statement is
9882 considered to clobber the contents.
9884 On some targets, a special form of output operand exists by which
9885 conditions in the flags register may be outputs of the asm. The set of
9886 conditions supported are target specific, but the general rule is that
9887 the output variable must be a scalar integer, and the value is boolean.
9888 When supported, the target defines the preprocessor symbol
9889 @code{__GCC_ASM_FLAG_OUTPUTS__}.
9891 Because of the special nature of the flag output operands, the constraint
9892 may not include alternatives.
9894 Most often, the target has only one flags register, and thus is an implied
9895 operand of many instructions. In this case, the operand should not be
9896 referenced within the assembler template via @code{%0} etc, as there's
9897 no corresponding text in the assembly language.
9902 The flag output constraints for the ARM family are of the form
9903 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
9904 conditions defined in the ARM ARM for @code{ConditionHolds}.
9908 Z flag set, or equal
9910 Z flag clear or not equal
9913 C flag set or unsigned greater than equal
9916 C flag clear or unsigned less than
9918 N flag set or ``minus''
9920 N flag clear or ``plus''
9922 V flag set or signed overflow
9926 unsigned greater than
9928 unsigned less than equal
9930 signed greater than equal
9936 signed less than equal
9939 The flag output constraints are not supported in thumb1 mode.
9942 The flag output constraints for the x86 family are of the form
9943 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
9944 conditions defined in the ISA manual for @code{j@var{cc}} or
9949 ``above'' or unsigned greater than
9951 ``above or equal'' or unsigned greater than or equal
9953 ``below'' or unsigned less than
9955 ``below or equal'' or unsigned less than or equal
9960 ``equal'' or zero flag set
9964 signed greater than or equal
9968 signed less than or equal
9989 ``not'' @var{flag}, or inverted versions of those above
9994 @anchor{InputOperands}
9995 @subsubsection Input Operands
9996 @cindex @code{asm} input operands
9997 @cindex @code{asm} expressions
9999 Input operands make values from C variables and expressions available to the
10002 Operands are separated by commas. Each operand has this format:
10005 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression})
10009 @item asmSymbolicName
10010 Specifies a symbolic name for the operand.
10011 Reference the name in the assembler template
10012 by enclosing it in square brackets
10013 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
10014 that contains the definition. Any valid C variable name is acceptable,
10015 including names already defined in the surrounding code. No two operands
10016 within the same @code{asm} statement can use the same symbolic name.
10018 When not using an @var{asmSymbolicName}, use the (zero-based) position
10020 in the list of operands in the assembler template. For example if there are
10021 two output operands and three inputs,
10022 use @samp{%2} in the template to refer to the first input operand,
10023 @samp{%3} for the second, and @samp{%4} for the third.
10026 A string constant specifying constraints on the placement of the operand;
10027 @xref{Constraints}, for details.
10029 Input constraint strings may not begin with either @samp{=} or @samp{+}.
10030 When you list more than one possible location (for example, @samp{"irm"}),
10031 the compiler chooses the most efficient one based on the current context.
10032 If you must use a specific register, but your Machine Constraints do not
10033 provide sufficient control to select the specific register you want,
10034 local register variables may provide a solution (@pxref{Local Register
10037 Input constraints can also be digits (for example, @code{"0"}). This indicates
10038 that the specified input must be in the same place as the output constraint
10039 at the (zero-based) index in the output constraint list.
10040 When using @var{asmSymbolicName} syntax for the output operands,
10041 you may use these names (enclosed in brackets @samp{[]}) instead of digits.
10044 This is the C variable or expression being passed to the @code{asm} statement
10045 as input. The enclosing parentheses are a required part of the syntax.
10049 When the compiler selects the registers to use to represent the input
10050 operands, it does not use any of the clobbered registers
10051 (@pxref{Clobbers and Scratch Registers}).
10053 If there are no output operands but there are input operands, place two
10054 consecutive colons where the output operands would go:
10057 __asm__ ("some instructions"
10058 : /* No outputs. */
10059 : "r" (Offset / 8));
10062 @strong{Warning:} Do @emph{not} modify the contents of input-only operands
10063 (except for inputs tied to outputs). The compiler assumes that on exit from
10064 the @code{asm} statement these operands contain the same values as they
10065 had before executing the statement.
10066 It is @emph{not} possible to use clobbers
10067 to inform the compiler that the values in these inputs are changing. One
10068 common work-around is to tie the changing input variable to an output variable
10069 that never gets used. Note, however, that if the code that follows the
10070 @code{asm} statement makes no use of any of the output operands, the GCC
10071 optimizers may discard the @code{asm} statement as unneeded
10072 (see @ref{Volatile}).
10074 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
10075 instead of simply @samp{%2}). Typically these qualifiers are hardware
10076 dependent. The list of supported modifiers for x86 is found at
10077 @ref{x86Operandmodifiers,x86 Operand modifiers}.
10079 In this example using the fictitious @code{combine} instruction, the
10080 constraint @code{"0"} for input operand 1 says that it must occupy the same
10081 location as output operand 0. Only input operands may use numbers in
10082 constraints, and they must each refer to an output operand. Only a number (or
10083 the symbolic assembler name) in the constraint can guarantee that one operand
10084 is in the same place as another. The mere fact that @code{foo} is the value of
10085 both operands is not enough to guarantee that they are in the same place in
10086 the generated assembler code.
10089 asm ("combine %2, %0"
10091 : "0" (foo), "g" (bar));
10094 Here is an example using symbolic names.
10097 asm ("cmoveq %1, %2, %[result]"
10098 : [result] "=r"(result)
10099 : "r" (test), "r" (new), "[result]" (old));
10102 @anchor{Clobbers and Scratch Registers}
10103 @subsubsection Clobbers and Scratch Registers
10104 @cindex @code{asm} clobbers
10105 @cindex @code{asm} scratch registers
10107 While the compiler is aware of changes to entries listed in the output
10108 operands, the inline @code{asm} code may modify more than just the outputs. For
10109 example, calculations may require additional registers, or the processor may
10110 overwrite a register as a side effect of a particular assembler instruction.
10111 In order to inform the compiler of these changes, list them in the clobber
10112 list. Clobber list items are either register names or the special clobbers
10113 (listed below). Each clobber list item is a string constant
10114 enclosed in double quotes and separated by commas.
10116 Clobber descriptions may not in any way overlap with an input or output
10117 operand. For example, you may not have an operand describing a register class
10118 with one member when listing that register in the clobber list. Variables
10119 declared to live in specific registers (@pxref{Explicit Register
10120 Variables}) and used
10121 as @code{asm} input or output operands must have no part mentioned in the
10122 clobber description. In particular, there is no way to specify that input
10123 operands get modified without also specifying them as output operands.
10125 When the compiler selects which registers to use to represent input and output
10126 operands, it does not use any of the clobbered registers. As a result,
10127 clobbered registers are available for any use in the assembler code.
10129 Another restriction is that the clobber list should not contain the
10130 stack pointer register. This is because the compiler requires the
10131 value of the stack pointer to be the same after an @code{asm}
10132 statement as it was on entry to the statement. However, previous
10133 versions of GCC did not enforce this rule and allowed the stack
10134 pointer to appear in the list, with unclear semantics. This behavior
10135 is deprecated and listing the stack pointer may become an error in
10136 future versions of GCC@.
10138 Here is a realistic example for the VAX showing the use of clobbered
10142 asm volatile ("movc3 %0, %1, %2"
10143 : /* No outputs. */
10144 : "g" (from), "g" (to), "g" (count)
10145 : "r0", "r1", "r2", "r3", "r4", "r5", "memory");
10148 Also, there are two special clobber arguments:
10152 The @code{"cc"} clobber indicates that the assembler code modifies the flags
10153 register. On some machines, GCC represents the condition codes as a specific
10154 hardware register; @code{"cc"} serves to name this register.
10155 On other machines, condition code handling is different,
10156 and specifying @code{"cc"} has no effect. But
10157 it is valid no matter what the target.
10160 The @code{"memory"} clobber tells the compiler that the assembly code
10162 reads or writes to items other than those listed in the input and output
10163 operands (for example, accessing the memory pointed to by one of the input
10164 parameters). To ensure memory contains correct values, GCC may need to flush
10165 specific register values to memory before executing the @code{asm}. Further,
10166 the compiler does not assume that any values read from memory before an
10167 @code{asm} remain unchanged after that @code{asm}; it reloads them as
10169 Using the @code{"memory"} clobber effectively forms a read/write
10170 memory barrier for the compiler.
10172 Note that this clobber does not prevent the @emph{processor} from doing
10173 speculative reads past the @code{asm} statement. To prevent that, you need
10174 processor-specific fence instructions.
10178 Flushing registers to memory has performance implications and may be
10179 an issue for time-sensitive code. You can provide better information
10180 to GCC to avoid this, as shown in the following examples. At a
10181 minimum, aliasing rules allow GCC to know what memory @emph{doesn't}
10182 need to be flushed.
10184 Here is a fictitious sum of squares instruction, that takes two
10185 pointers to floating point values in memory and produces a floating
10186 point register output.
10187 Notice that @code{x}, and @code{y} both appear twice in the @code{asm}
10188 parameters, once to specify memory accessed, and once to specify a
10189 base register used by the @code{asm}. You won't normally be wasting a
10190 register by doing this as GCC can use the same register for both
10191 purposes. However, it would be foolish to use both @code{%1} and
10192 @code{%3} for @code{x} in this @code{asm} and expect them to be the
10193 same. In fact, @code{%3} may well not be a register. It might be a
10194 symbolic memory reference to the object pointed to by @code{x}.
10197 asm ("sumsq %0, %1, %2"
10199 : "r" (x), "r" (y), "m" (*x), "m" (*y));
10202 Here is a fictitious @code{*z++ = *x++ * *y++} instruction.
10203 Notice that the @code{x}, @code{y} and @code{z} pointer registers
10204 must be specified as input/output because the @code{asm} modifies
10208 asm ("vecmul %0, %1, %2"
10209 : "+r" (z), "+r" (x), "+r" (y), "=m" (*z)
10210 : "m" (*x), "m" (*y));
10213 An x86 example where the string memory argument is of unknown length.
10217 : "=c" (count), "+D" (p)
10218 : "m" (*(const char (*)[]) p), "0" (-1), "a" (0));
10221 If you know the above will only be reading a ten byte array then you
10222 could instead use a memory input like:
10223 @code{"m" (*(const char (*)[10]) p)}.
10225 Here is an example of a PowerPC vector scale implemented in assembly,
10226 complete with vector and condition code clobbers, and some initialized
10227 offset registers that are unchanged by the @code{asm}.
10231 dscal (size_t n, double *x, double alpha)
10233 asm ("/* lots of asm here */"
10234 : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x)
10235 : "d" (alpha), "b" (32), "b" (48), "b" (64),
10236 "b" (80), "b" (96), "b" (112)
10238 "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39",
10239 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47");
10243 Rather than allocating fixed registers via clobbers to provide scratch
10244 registers for an @code{asm} statement, an alternative is to define a
10245 variable and make it an early-clobber output as with @code{a2} and
10246 @code{a3} in the example below. This gives the compiler register
10247 allocator more freedom. You can also define a variable and make it an
10248 output tied to an input as with @code{a0} and @code{a1}, tied
10249 respectively to @code{ap} and @code{lda}. Of course, with tied
10250 outputs your @code{asm} can't use the input value after modifying the
10251 output register since they are one and the same register. What's
10252 more, if you omit the early-clobber on the output, it is possible that
10253 GCC might allocate the same register to another of the inputs if GCC
10254 could prove they had the same value on entry to the @code{asm}. This
10255 is why @code{a1} has an early-clobber. Its tied input, @code{lda}
10256 might conceivably be known to have the value 16 and without an
10257 early-clobber share the same register as @code{%11}. On the other
10258 hand, @code{ap} can't be the same as any of the other inputs, so an
10259 early-clobber on @code{a0} is not needed. It is also not desirable in
10260 this case. An early-clobber on @code{a0} would cause GCC to allocate
10261 a separate register for the @code{"m" (*(const double (*)[]) ap)}
10262 input. Note that tying an input to an output is the way to set up an
10263 initialized temporary register modified by an @code{asm} statement.
10264 An input not tied to an output is assumed by GCC to be unchanged, for
10265 example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might
10266 use that register in following code if the value 16 happened to be
10267 needed. You can even use a normal @code{asm} output for a scratch if
10268 all inputs that might share the same register are consumed before the
10269 scratch is used. The VSX registers clobbered by the @code{asm}
10270 statement could have used this technique except for GCC's limit on the
10271 number of @code{asm} parameters.
10275 dgemv_kernel_4x4 (long n, const double *ap, long lda,
10276 const double *x, double *y, double alpha)
10285 /* lots of asm here */
10286 "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n"
10287 "#a0=%3 a1=%4 a2=%5 a3=%6"
10289 "+m" (*(double (*)[n]) y),
10297 "m" (*(const double (*)[n]) x),
10298 "m" (*(const double (*)[]) ap),
10306 "vs32","vs33","vs34","vs35","vs36","vs37",
10307 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"
10312 @anchor{GotoLabels}
10313 @subsubsection Goto Labels
10314 @cindex @code{asm} goto labels
10316 @code{asm goto} allows assembly code to jump to one or more C labels. The
10317 @var{GotoLabels} section in an @code{asm goto} statement contains
10319 list of all C labels to which the assembler code may jump. GCC assumes that
10320 @code{asm} execution falls through to the next statement (if this is not the
10321 case, consider using the @code{__builtin_unreachable} intrinsic after the
10322 @code{asm} statement). Optimization of @code{asm goto} may be improved by
10323 using the @code{hot} and @code{cold} label attributes (@pxref{Label
10326 An @code{asm goto} statement cannot have outputs.
10327 This is due to an internal restriction of
10328 the compiler: control transfer instructions cannot have outputs.
10329 If the assembler code does modify anything, use the @code{"memory"} clobber
10331 optimizers to flush all register values to memory and reload them if
10332 necessary after the @code{asm} statement.
10334 Also note that an @code{asm goto} statement is always implicitly
10335 considered volatile.
10337 To reference a label in the assembler template,
10338 prefix it with @samp{%l} (lowercase @samp{L}) followed
10339 by its (zero-based) position in @var{GotoLabels} plus the number of input
10340 operands. For example, if the @code{asm} has three inputs and references two
10341 labels, refer to the first label as @samp{%l3} and the second as @samp{%l4}).
10343 Alternately, you can reference labels using the actual C label name enclosed
10344 in brackets. For example, to reference a label named @code{carry}, you can
10345 use @samp{%l[carry]}. The label must still be listed in the @var{GotoLabels}
10346 section when using this approach.
10348 Here is an example of @code{asm goto} for i386:
10354 : /* No outputs. */
10355 : "r" (p1), "r" (p2)
10365 The following example shows an @code{asm goto} that uses a memory clobber.
10371 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
10372 : /* No outputs. */
10382 @anchor{x86Operandmodifiers}
10383 @subsubsection x86 Operand Modifiers
10385 References to input, output, and goto operands in the assembler template
10386 of extended @code{asm} statements can use
10387 modifiers to affect the way the operands are formatted in
10388 the code output to the assembler. For example, the
10389 following code uses the @samp{h} and @samp{b} modifiers for x86:
10393 asm volatile ("xchg %h0, %b0" : "+a" (num) );
10397 These modifiers generate this assembler code:
10403 The rest of this discussion uses the following code for illustrative purposes.
10412 asm volatile goto ("some assembler instructions here"
10413 : /* No outputs. */
10414 : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42)
10415 : /* No clobbers. */
10420 With no modifiers, this is what the output from the operands would be
10421 for the @samp{att} and @samp{intel} dialects of assembler:
10423 @multitable {Operand} {$.L2} {OFFSET FLAT:.L2}
10424 @headitem Operand @tab @samp{att} @tab @samp{intel}
10433 @tab @code{OFFSET FLAT:.L3}
10445 The table below shows the list of supported modifiers and their effects.
10447 @multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}}
10448 @headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel}
10450 @tab Print an absolute memory reference.
10455 @tab Print the QImode name of the register.
10460 @tab print the opcode suffix of b.
10465 @tab Require a constant operand and print the constant expression with no punctuation.
10470 @tab print duplicated register operand for AVX instruction.
10472 @tab @code{%xmm0, %xmm0}
10473 @tab @code{xmm0, xmm0}
10475 @tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit.
10476 Otherwise mode is unspecified (VOIDmode).
10481 @tab Print the V16SFmode name of the register.
10486 @tab Print the QImode name for a ``high'' register.
10491 @tab Add 8 bytes to an offsettable memory reference. Useful when accessing the
10492 high 8 bytes of SSE values. For a memref in (%rax), it generates
10494 @tab @code{8(%rax)}
10497 @tab Print the SImode name of the register.
10502 @tab Print the label name with no punctuation.
10507 @tab print the opcode suffix of l.
10517 @tab Print raw symbol name (without syntax-specific prefixes).
10522 @tab If used for a function, print the PLT suffix and generate PIC code.
10523 For example, emit @code{foo@@PLT} instead of 'foo' for the function
10524 foo(). If used for a constant, drop all syntax-specific prefixes and
10525 issue the bare constant. See @code{p} above.
10527 @tab Print the DImode name of the register.
10532 @tab print the opcode suffix of q.
10537 @tab print embedded rounding and sae.
10539 @tab @code{@{rn-sae@}, }
10540 @tab @code{, @{rn-sae@}}
10542 @tab print only sae.
10544 @tab @code{@{sae@}, }
10545 @tab @code{, @{sae@}}
10547 @tab print a shift double count, followed by the assemblers argument
10548 delimiterprint the opcode suffix of s.
10553 @tab print the opcode suffix of s.
10558 @tab print the V8SFmode name of the register.
10563 @tab print the opcode suffix of t.
10568 @tab print naked full integer register name without %.
10573 @tab Print the HImode name of the register.
10578 @tab print the opcode suffix of w.
10583 @tab print the V4SFmode name of the register.
10588 @tab print "st(0)" instead of "st" as a register.
10593 @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}).
10598 @tab Like @code{z}, with special suffixes for x87 instructions.
10602 @anchor{x86floatingpointasmoperands}
10603 @subsubsection x86 Floating-Point @code{asm} Operands
10605 On x86 targets, there are several rules on the usage of stack-like registers
10606 in the operands of an @code{asm}. These rules apply only to the operands
10607 that are stack-like registers:
10611 Given a set of input registers that die in an @code{asm}, it is
10612 necessary to know which are implicitly popped by the @code{asm}, and
10613 which must be explicitly popped by GCC@.
10615 An input register that is implicitly popped by the @code{asm} must be
10616 explicitly clobbered, unless it is constrained to match an
10620 For any input register that is implicitly popped by an @code{asm}, it is
10621 necessary to know how to adjust the stack to compensate for the pop.
10622 If any non-popped input is closer to the top of the reg-stack than
10623 the implicitly popped register, it would not be possible to know what the
10624 stack looked like---it's not clear how the rest of the stack ``slides
10627 All implicitly popped input registers must be closer to the top of
10628 the reg-stack than any input that is not implicitly popped.
10630 It is possible that if an input dies in an @code{asm}, the compiler might
10631 use the input register for an output reload. Consider this example:
10634 asm ("foo" : "=t" (a) : "f" (b));
10638 This code says that input @code{b} is not popped by the @code{asm}, and that
10639 the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one
10640 deeper after the @code{asm} than it was before. But, it is possible that
10641 reload may think that it can use the same register for both the input and
10644 To prevent this from happening,
10645 if any input operand uses the @samp{f} constraint, all output register
10646 constraints must use the @samp{&} early-clobber modifier.
10648 The example above is correctly written as:
10651 asm ("foo" : "=&t" (a) : "f" (b));
10655 Some operands need to be in particular places on the stack. All
10656 output operands fall in this category---GCC has no other way to
10657 know which registers the outputs appear in unless you indicate
10658 this in the constraints.
10660 Output operands must specifically indicate which register an output
10661 appears in after an @code{asm}. @samp{=f} is not allowed: the operand
10662 constraints must select a class with a single register.
10665 Output operands may not be ``inserted'' between existing stack registers.
10666 Since no 387 opcode uses a read/write operand, all output operands
10667 are dead before the @code{asm}, and are pushed by the @code{asm}.
10668 It makes no sense to push anywhere but the top of the reg-stack.
10670 Output operands must start at the top of the reg-stack: output
10671 operands may not ``skip'' a register.
10674 Some @code{asm} statements may need extra stack space for internal
10675 calculations. This can be guaranteed by clobbering stack registers
10676 unrelated to the inputs and outputs.
10681 takes one input, which is internally popped, and produces two outputs.
10684 asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
10688 This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode,
10689 and replaces them with one output. The @code{st(1)} clobber is necessary
10690 for the compiler to know that @code{fyl2xp1} pops both inputs.
10693 asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
10701 @subsection Controlling Names Used in Assembler Code
10702 @cindex assembler names for identifiers
10703 @cindex names used in assembler code
10704 @cindex identifiers, names in assembler code
10706 You can specify the name to be used in the assembler code for a C
10707 function or variable by writing the @code{asm} (or @code{__asm__})
10708 keyword after the declarator.
10709 It is up to you to make sure that the assembler names you choose do not
10710 conflict with any other assembler symbols, or reference registers.
10712 @subsubheading Assembler names for data:
10714 This sample shows how to specify the assembler name for data:
10717 int foo asm ("myfoo") = 2;
10721 This specifies that the name to be used for the variable @code{foo} in
10722 the assembler code should be @samp{myfoo} rather than the usual
10725 On systems where an underscore is normally prepended to the name of a C
10726 variable, this feature allows you to define names for the
10727 linker that do not start with an underscore.
10729 GCC does not support using this feature with a non-static local variable
10730 since such variables do not have assembler names. If you are
10731 trying to put the variable in a particular register, see
10732 @ref{Explicit Register Variables}.
10734 @subsubheading Assembler names for functions:
10736 To specify the assembler name for functions, write a declaration for the
10737 function before its definition and put @code{asm} there, like this:
10740 int func (int x, int y) asm ("MYFUNC");
10742 int func (int x, int y)
10748 This specifies that the name to be used for the function @code{func} in
10749 the assembler code should be @code{MYFUNC}.
10751 @node Explicit Register Variables
10752 @subsection Variables in Specified Registers
10753 @anchor{Explicit Reg Vars}
10754 @cindex explicit register variables
10755 @cindex variables in specified registers
10756 @cindex specified registers
10758 GNU C allows you to associate specific hardware registers with C
10759 variables. In almost all cases, allowing the compiler to assign
10760 registers produces the best code. However under certain unusual
10761 circumstances, more precise control over the variable storage is
10764 Both global and local variables can be associated with a register. The
10765 consequences of performing this association are very different between
10766 the two, as explained in the sections below.
10769 * Global Register Variables:: Variables declared at global scope.
10770 * Local Register Variables:: Variables declared within a function.
10773 @node Global Register Variables
10774 @subsubsection Defining Global Register Variables
10775 @anchor{Global Reg Vars}
10776 @cindex global register variables
10777 @cindex registers, global variables in
10778 @cindex registers, global allocation
10780 You can define a global register variable and associate it with a specified
10781 register like this:
10784 register int *foo asm ("r12");
10788 Here @code{r12} is the name of the register that should be used. Note that
10789 this is the same syntax used for defining local register variables, but for
10790 a global variable the declaration appears outside a function. The
10791 @code{register} keyword is required, and cannot be combined with
10792 @code{static}. The register name must be a valid register name for the
10795 Do not use type qualifiers such as @code{const} and @code{volatile}, as
10796 the outcome may be contrary to expectations. In particular, using the
10797 @code{volatile} qualifier does not fully prevent the compiler from
10798 optimizing accesses to the register.
10800 Registers are a scarce resource on most systems and allowing the
10801 compiler to manage their usage usually results in the best code. However,
10802 under special circumstances it can make sense to reserve some globally.
10803 For example this may be useful in programs such as programming language
10804 interpreters that have a couple of global variables that are accessed
10807 After defining a global register variable, for the current compilation
10811 @item If the register is a call-saved register, call ABI is affected:
10812 the register will not be restored in function epilogue sequences after
10813 the variable has been assigned. Therefore, functions cannot safely
10814 return to callers that assume standard ABI.
10815 @item Conversely, if the register is a call-clobbered register, making
10816 calls to functions that use standard ABI may lose contents of the variable.
10817 Such calls may be created by the compiler even if none are evident in
10818 the original program, for example when libgcc functions are used to
10819 make up for unavailable instructions.
10820 @item Accesses to the variable may be optimized as usual and the register
10821 remains available for allocation and use in any computations, provided that
10822 observable values of the variable are not affected.
10823 @item If the variable is referenced in inline assembly, the type of access
10824 must be provided to the compiler via constraints (@pxref{Constraints}).
10825 Accesses from basic asms are not supported.
10828 Note that these points @emph{only} apply to code that is compiled with the
10829 definition. The behavior of code that is merely linked in (for example
10830 code from libraries) is not affected.
10832 If you want to recompile source files that do not actually use your global
10833 register variable so they do not use the specified register for any other
10834 purpose, you need not actually add the global register declaration to
10835 their source code. It suffices to specify the compiler option
10836 @option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the
10839 @subsubheading Declaring the variable
10841 Global register variables cannot have initial values, because an
10842 executable file has no means to supply initial contents for a register.
10844 When selecting a register, choose one that is normally saved and
10845 restored by function calls on your machine. This ensures that code
10846 which is unaware of this reservation (such as library routines) will
10847 restore it before returning.
10849 On machines with register windows, be sure to choose a global
10850 register that is not affected magically by the function call mechanism.
10852 @subsubheading Using the variable
10854 @cindex @code{qsort}, and global register variables
10855 When calling routines that are not aware of the reservation, be
10856 cautious if those routines call back into code which uses them. As an
10857 example, if you call the system library version of @code{qsort}, it may
10858 clobber your registers during execution, but (if you have selected
10859 appropriate registers) it will restore them before returning. However
10860 it will @emph{not} restore them before calling @code{qsort}'s comparison
10861 function. As a result, global values will not reliably be available to
10862 the comparison function unless the @code{qsort} function itself is rebuilt.
10864 Similarly, it is not safe to access the global register variables from signal
10865 handlers or from more than one thread of control. Unless you recompile
10866 them specially for the task at hand, the system library routines may
10867 temporarily use the register for other things. Furthermore, since the register
10868 is not reserved exclusively for the variable, accessing it from handlers of
10869 asynchronous signals may observe unrelated temporary values residing in the
10872 @cindex register variable after @code{longjmp}
10873 @cindex global register after @code{longjmp}
10874 @cindex value after @code{longjmp}
10877 On most machines, @code{longjmp} restores to each global register
10878 variable the value it had at the time of the @code{setjmp}. On some
10879 machines, however, @code{longjmp} does not change the value of global
10880 register variables. To be portable, the function that called @code{setjmp}
10881 should make other arrangements to save the values of the global register
10882 variables, and to restore them in a @code{longjmp}. This way, the same
10883 thing happens regardless of what @code{longjmp} does.
10885 @node Local Register Variables
10886 @subsubsection Specifying Registers for Local Variables
10887 @anchor{Local Reg Vars}
10888 @cindex local variables, specifying registers
10889 @cindex specifying registers for local variables
10890 @cindex registers for local variables
10892 You can define a local register variable and associate it with a specified
10893 register like this:
10896 register int *foo asm ("r12");
10900 Here @code{r12} is the name of the register that should be used. Note
10901 that this is the same syntax used for defining global register variables,
10902 but for a local variable the declaration appears within a function. The
10903 @code{register} keyword is required, and cannot be combined with
10904 @code{static}. The register name must be a valid register name for the
10907 Do not use type qualifiers such as @code{const} and @code{volatile}, as
10908 the outcome may be contrary to expectations. In particular, when the
10909 @code{const} qualifier is used, the compiler may substitute the
10910 variable with its initializer in @code{asm} statements, which may cause
10911 the corresponding operand to appear in a different register.
10913 As with global register variables, it is recommended that you choose
10914 a register that is normally saved and restored by function calls on your
10915 machine, so that calls to library routines will not clobber it.
10917 The only supported use for this feature is to specify registers
10918 for input and output operands when calling Extended @code{asm}
10919 (@pxref{Extended Asm}). This may be necessary if the constraints for a
10920 particular machine don't provide sufficient control to select the desired
10921 register. To force an operand into a register, create a local variable
10922 and specify the register name after the variable's declaration. Then use
10923 the local variable for the @code{asm} operand and specify any constraint
10924 letter that matches the register:
10927 register int *p1 asm ("r0") = @dots{};
10928 register int *p2 asm ("r1") = @dots{};
10929 register int *result asm ("r0");
10930 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
10933 @emph{Warning:} In the above example, be aware that a register (for example
10934 @code{r0}) can be call-clobbered by subsequent code, including function
10935 calls and library calls for arithmetic operators on other variables (for
10936 example the initialization of @code{p2}). In this case, use temporary
10937 variables for expressions between the register assignments:
10941 register int *p1 asm ("r0") = @dots{};
10942 register int *p2 asm ("r1") = t1;
10943 register int *result asm ("r0");
10944 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
10947 Defining a register variable does not reserve the register. Other than
10948 when invoking the Extended @code{asm}, the contents of the specified
10949 register are not guaranteed. For this reason, the following uses
10950 are explicitly @emph{not} supported. If they appear to work, it is only
10951 happenstance, and may stop working as intended due to (seemingly)
10952 unrelated changes in surrounding code, or even minor changes in the
10953 optimization of a future version of gcc:
10956 @item Passing parameters to or from Basic @code{asm}
10957 @item Passing parameters to or from Extended @code{asm} without using input
10958 or output operands.
10959 @item Passing parameters to or from routines written in assembler (or
10960 other languages) using non-standard calling conventions.
10963 Some developers use Local Register Variables in an attempt to improve
10964 gcc's allocation of registers, especially in large functions. In this
10965 case the register name is essentially a hint to the register allocator.
10966 While in some instances this can generate better code, improvements are
10967 subject to the whims of the allocator/optimizers. Since there are no
10968 guarantees that your improvements won't be lost, this usage of Local
10969 Register Variables is discouraged.
10971 On the MIPS platform, there is related use for local register variables
10972 with slightly different characteristics (@pxref{MIPS Coprocessors,,
10973 Defining coprocessor specifics for MIPS targets, gccint,
10974 GNU Compiler Collection (GCC) Internals}).
10976 @node Size of an asm
10977 @subsection Size of an @code{asm}
10979 Some targets require that GCC track the size of each instruction used
10980 in order to generate correct code. Because the final length of the
10981 code produced by an @code{asm} statement is only known by the
10982 assembler, GCC must make an estimate as to how big it will be. It
10983 does this by counting the number of instructions in the pattern of the
10984 @code{asm} and multiplying that by the length of the longest
10985 instruction supported by that processor. (When working out the number
10986 of instructions, it assumes that any occurrence of a newline or of
10987 whatever statement separator character is supported by the assembler ---
10988 typically @samp{;} --- indicates the end of an instruction.)
10990 Normally, GCC's estimate is adequate to ensure that correct
10991 code is generated, but it is possible to confuse the compiler if you use
10992 pseudo instructions or assembler macros that expand into multiple real
10993 instructions, or if you use assembler directives that expand to more
10994 space in the object file than is needed for a single instruction.
10995 If this happens then the assembler may produce a diagnostic saying that
10996 a label is unreachable.
10998 @cindex @code{asm inline}
10999 This size is also used for inlining decisions. If you use @code{asm inline}
11000 instead of just @code{asm}, then for inlining purposes the size of the asm
11001 is taken as the minimum size, ignoring how many instructions GCC thinks it is.
11003 @node Alternate Keywords
11004 @section Alternate Keywords
11005 @cindex alternate keywords
11006 @cindex keywords, alternate
11008 @option{-ansi} and the various @option{-std} options disable certain
11009 keywords. This causes trouble when you want to use GNU C extensions, or
11010 a general-purpose header file that should be usable by all programs,
11011 including ISO C programs. The keywords @code{asm}, @code{typeof} and
11012 @code{inline} are not available in programs compiled with
11013 @option{-ansi} or @option{-std} (although @code{inline} can be used in a
11014 program compiled with @option{-std=c99} or a later standard). The
11016 @code{restrict} is only available when @option{-std=gnu99} (which will
11017 eventually be the default) or @option{-std=c99} (or the equivalent
11018 @option{-std=iso9899:1999}), or an option for a later standard
11021 The way to solve these problems is to put @samp{__} at the beginning and
11022 end of each problematical keyword. For example, use @code{__asm__}
11023 instead of @code{asm}, and @code{__inline__} instead of @code{inline}.
11025 Other C compilers won't accept these alternative keywords; if you want to
11026 compile with another compiler, you can define the alternate keywords as
11027 macros to replace them with the customary keywords. It looks like this:
11031 #define __asm__ asm
11035 @findex __extension__
11037 @option{-pedantic} and other options cause warnings for many GNU C extensions.
11039 prevent such warnings within one expression by writing
11040 @code{__extension__} before the expression. @code{__extension__} has no
11041 effect aside from this.
11043 @node Incomplete Enums
11044 @section Incomplete @code{enum} Types
11046 You can define an @code{enum} tag without specifying its possible values.
11047 This results in an incomplete type, much like what you get if you write
11048 @code{struct foo} without describing the elements. A later declaration
11049 that does specify the possible values completes the type.
11051 You cannot allocate variables or storage using the type while it is
11052 incomplete. However, you can work with pointers to that type.
11054 This extension may not be very useful, but it makes the handling of
11055 @code{enum} more consistent with the way @code{struct} and @code{union}
11058 This extension is not supported by GNU C++.
11060 @node Function Names
11061 @section Function Names as Strings
11062 @cindex @code{__func__} identifier
11063 @cindex @code{__FUNCTION__} identifier
11064 @cindex @code{__PRETTY_FUNCTION__} identifier
11066 GCC provides three magic constants that hold the name of the current
11067 function as a string. In C++11 and later modes, all three are treated
11068 as constant expressions and can be used in @code{constexpr} constexts.
11069 The first of these constants is @code{__func__}, which is part of
11072 The identifier @code{__func__} is implicitly declared by the translator
11073 as if, immediately following the opening brace of each function
11074 definition, the declaration
11077 static const char __func__[] = "function-name";
11081 appeared, where function-name is the name of the lexically-enclosing
11082 function. This name is the unadorned name of the function. As an
11083 extension, at file (or, in C++, namespace scope), @code{__func__}
11084 evaluates to the empty string.
11086 @code{__FUNCTION__} is another name for @code{__func__}, provided for
11087 backward compatibility with old versions of GCC.
11089 In C, @code{__PRETTY_FUNCTION__} is yet another name for
11090 @code{__func__}, except that at file scope (or, in C++, namespace scope),
11091 it evaluates to the string @code{"top level"}. In addition, in C++,
11092 @code{__PRETTY_FUNCTION__} contains the signature of the function as
11093 well as its bare name. For example, this program:
11096 extern "C" int printf (const char *, ...);
11102 printf ("__FUNCTION__ = %s\n", __FUNCTION__);
11103 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
11121 __PRETTY_FUNCTION__ = void a::sub(int)
11124 These identifiers are variables, not preprocessor macros, and may not
11125 be used to initialize @code{char} arrays or be concatenated with string
11128 @node Return Address
11129 @section Getting the Return or Frame Address of a Function
11131 These functions may be used to get information about the callers of a
11134 @deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level})
11135 This function returns the return address of the current function, or of
11136 one of its callers. The @var{level} argument is number of frames to
11137 scan up the call stack. A value of @code{0} yields the return address
11138 of the current function, a value of @code{1} yields the return address
11139 of the caller of the current function, and so forth. When inlining
11140 the expected behavior is that the function returns the address of
11141 the function that is returned to. To work around this behavior use
11142 the @code{noinline} function attribute.
11144 The @var{level} argument must be a constant integer.
11146 On some machines it may be impossible to determine the return address of
11147 any function other than the current one; in such cases, or when the top
11148 of the stack has been reached, this function returns @code{0} or a
11149 random value. In addition, @code{__builtin_frame_address} may be used
11150 to determine if the top of the stack has been reached.
11152 Additional post-processing of the returned value may be needed, see
11153 @code{__builtin_extract_return_addr}.
11155 Calling this function with a nonzero argument can have unpredictable
11156 effects, including crashing the calling program. As a result, calls
11157 that are considered unsafe are diagnosed when the @option{-Wframe-address}
11158 option is in effect. Such calls should only be made in debugging
11162 @deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr})
11163 The address as returned by @code{__builtin_return_address} may have to be fed
11164 through this function to get the actual encoded address. For example, on the
11165 31-bit S/390 platform the highest bit has to be masked out, or on SPARC
11166 platforms an offset has to be added for the true next instruction to be
11169 If no fixup is needed, this function simply passes through @var{addr}.
11172 @deftypefn {Built-in Function} {void *} __builtin_frob_return_addr (void *@var{addr})
11173 This function does the reverse of @code{__builtin_extract_return_addr}.
11176 @deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level})
11177 This function is similar to @code{__builtin_return_address}, but it
11178 returns the address of the function frame rather than the return address
11179 of the function. Calling @code{__builtin_frame_address} with a value of
11180 @code{0} yields the frame address of the current function, a value of
11181 @code{1} yields the frame address of the caller of the current function,
11184 The frame is the area on the stack that holds local variables and saved
11185 registers. The frame address is normally the address of the first word
11186 pushed on to the stack by the function. However, the exact definition
11187 depends upon the processor and the calling convention. If the processor
11188 has a dedicated frame pointer register, and the function has a frame,
11189 then @code{__builtin_frame_address} returns the value of the frame
11192 On some machines it may be impossible to determine the frame address of
11193 any function other than the current one; in such cases, or when the top
11194 of the stack has been reached, this function returns @code{0} if
11195 the first frame pointer is properly initialized by the startup code.
11197 Calling this function with a nonzero argument can have unpredictable
11198 effects, including crashing the calling program. As a result, calls
11199 that are considered unsafe are diagnosed when the @option{-Wframe-address}
11200 option is in effect. Such calls should only be made in debugging
11204 @node Vector Extensions
11205 @section Using Vector Instructions through Built-in Functions
11207 On some targets, the instruction set contains SIMD vector instructions which
11208 operate on multiple values contained in one large register at the same time.
11209 For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used
11212 The first step in using these extensions is to provide the necessary data
11213 types. This should be done using an appropriate @code{typedef}:
11216 typedef int v4si __attribute__ ((vector_size (16)));
11220 The @code{int} type specifies the @dfn{base type}, while the attribute specifies
11221 the vector size for the variable, measured in bytes. For example, the
11222 declaration above causes the compiler to set the mode for the @code{v4si}
11223 type to be 16 bytes wide and divided into @code{int} sized units. For
11224 a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the
11225 corresponding mode of @code{foo} is @acronym{V4SI}.
11227 The @code{vector_size} attribute is only applicable to integral and
11228 floating scalars, although arrays, pointers, and function return values
11229 are allowed in conjunction with this construct. Only sizes that are
11230 positive power-of-two multiples of the base type size are currently allowed.
11232 All the basic integer types can be used as base types, both as signed
11233 and as unsigned: @code{char}, @code{short}, @code{int}, @code{long},
11234 @code{long long}. In addition, @code{float} and @code{double} can be
11235 used to build floating-point vector types.
11237 Specifying a combination that is not valid for the current architecture
11238 causes GCC to synthesize the instructions using a narrower mode.
11239 For example, if you specify a variable of type @code{V4SI} and your
11240 architecture does not allow for this specific SIMD type, GCC
11241 produces code that uses 4 @code{SIs}.
11243 The types defined in this manner can be used with a subset of normal C
11244 operations. Currently, GCC allows using the following operators
11245 on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@.
11247 The operations behave like C++ @code{valarrays}. Addition is defined as
11248 the addition of the corresponding elements of the operands. For
11249 example, in the code below, each of the 4 elements in @var{a} is
11250 added to the corresponding 4 elements in @var{b} and the resulting
11251 vector is stored in @var{c}.
11254 typedef int v4si __attribute__ ((vector_size (16)));
11261 Subtraction, multiplication, division, and the logical operations
11262 operate in a similar manner. Likewise, the result of using the unary
11263 minus or complement operators on a vector type is a vector whose
11264 elements are the negative or complemented values of the corresponding
11265 elements in the operand.
11267 It is possible to use shifting operators @code{<<}, @code{>>} on
11268 integer-type vectors. The operation is defined as following: @code{@{a0,
11269 a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1,
11270 @dots{}, an >> bn@}}@. Vector operands must have the same number of
11273 For convenience, it is allowed to use a binary vector operation
11274 where one operand is a scalar. In that case the compiler transforms
11275 the scalar operand into a vector where each element is the scalar from
11276 the operation. The transformation happens only if the scalar could be
11277 safely converted to the vector-element type.
11278 Consider the following code.
11281 typedef int v4si __attribute__ ((vector_size (16)));
11286 a = b + 1; /* a = b + @{1,1,1,1@}; */
11287 a = 2 * b; /* a = @{2,2,2,2@} * b; */
11289 a = l + a; /* Error, cannot convert long to int. */
11292 Vectors can be subscripted as if the vector were an array with
11293 the same number of elements and base type. Out of bound accesses
11294 invoke undefined behavior at run time. Warnings for out of bound
11295 accesses for vector subscription can be enabled with
11296 @option{-Warray-bounds}.
11298 Vector comparison is supported with standard comparison
11299 operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be
11300 vector expressions of integer-type or real-type. Comparison between
11301 integer-type vectors and real-type vectors are not supported. The
11302 result of the comparison is a vector of the same width and number of
11303 elements as the comparison operands with a signed integral element
11306 Vectors are compared element-wise producing 0 when comparison is false
11307 and -1 (constant of the appropriate type where all bits are set)
11308 otherwise. Consider the following example.
11311 typedef int v4si __attribute__ ((vector_size (16)));
11313 v4si a = @{1,2,3,4@};
11314 v4si b = @{3,2,1,4@};
11317 c = a > b; /* The result would be @{0, 0,-1, 0@} */
11318 c = a == b; /* The result would be @{0,-1, 0,-1@} */
11321 In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where
11322 @code{b} and @code{c} are vectors of the same type and @code{a} is an
11323 integer vector with the same number of elements of the same size as @code{b}
11324 and @code{c}, computes all three arguments and creates a vector
11325 @code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in
11326 OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}.
11327 As in the case of binary operations, this syntax is also accepted when
11328 one of @code{b} or @code{c} is a scalar that is then transformed into a
11329 vector. If both @code{b} and @code{c} are scalars and the type of
11330 @code{true?b:c} has the same size as the element type of @code{a}, then
11331 @code{b} and @code{c} are converted to a vector type whose elements have
11332 this type and with the same number of elements as @code{a}.
11334 In C++, the logic operators @code{!, &&, ||} are available for vectors.
11335 @code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to
11336 @code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}.
11337 For mixed operations between a scalar @code{s} and a vector @code{v},
11338 @code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is
11339 short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}.
11341 @findex __builtin_shuffle
11342 Vector shuffling is available using functions
11343 @code{__builtin_shuffle (vec, mask)} and
11344 @code{__builtin_shuffle (vec0, vec1, mask)}.
11345 Both functions construct a permutation of elements from one or two
11346 vectors and return a vector of the same type as the input vector(s).
11347 The @var{mask} is an integral vector with the same width (@var{W})
11348 and element count (@var{N}) as the output vector.
11350 The elements of the input vectors are numbered in memory ordering of
11351 @var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The
11352 elements of @var{mask} are considered modulo @var{N} in the single-operand
11353 case and modulo @math{2*@var{N}} in the two-operand case.
11355 Consider the following example,
11358 typedef int v4si __attribute__ ((vector_size (16)));
11360 v4si a = @{1,2,3,4@};
11361 v4si b = @{5,6,7,8@};
11362 v4si mask1 = @{0,1,1,3@};
11363 v4si mask2 = @{0,4,2,5@};
11366 res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */
11367 res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */
11370 Note that @code{__builtin_shuffle} is intentionally semantically
11371 compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions.
11373 You can declare variables and use them in function calls and returns, as
11374 well as in assignments and some casts. You can specify a vector type as
11375 a return type for a function. Vector types can also be used as function
11376 arguments. It is possible to cast from one vector type to another,
11377 provided they are of the same size (in fact, you can also cast vectors
11378 to and from other datatypes of the same size).
11380 You cannot operate between vectors of different lengths or different
11381 signedness without a cast.
11383 @findex __builtin_convertvector
11384 Vector conversion is available using the
11385 @code{__builtin_convertvector (vec, vectype)}
11386 function. @var{vec} must be an expression with integral or floating
11387 vector type and @var{vectype} an integral or floating vector type with the
11388 same number of elements. The result has @var{vectype} type and value of
11389 a C cast of every element of @var{vec} to the element type of @var{vectype}.
11391 Consider the following example,
11393 typedef int v4si __attribute__ ((vector_size (16)));
11394 typedef float v4sf __attribute__ ((vector_size (16)));
11395 typedef double v4df __attribute__ ((vector_size (32)));
11396 typedef unsigned long long v4di __attribute__ ((vector_size (32)));
11398 v4si a = @{1,-2,3,-4@};
11399 v4sf b = @{1.5f,-2.5f,3.f,7.f@};
11400 v4di c = @{1ULL,5ULL,0ULL,10ULL@};
11401 v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */
11403 v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */
11404 v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */
11405 v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */
11406 v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */
11407 v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */
11410 @cindex vector types, using with x86 intrinsics
11411 Sometimes it is desirable to write code using a mix of generic vector
11412 operations (for clarity) and machine-specific vector intrinsics (to
11413 access vector instructions that are not exposed via generic built-ins).
11414 On x86, intrinsic functions for integer vectors typically use the same
11415 vector type @code{__m128i} irrespective of how they interpret the vector,
11416 making it necessary to cast their arguments and return values from/to
11417 other vector types. In C, you can make use of a @code{union} type:
11418 @c In C++ such type punning via a union is not allowed by the language
11420 #include <immintrin.h>
11422 typedef unsigned char u8x16 __attribute__ ((vector_size (16)));
11423 typedef unsigned int u32x4 __attribute__ ((vector_size (16)));
11433 for variables that can be used with both built-in operators and x86
11437 v128 x, y = @{ 0 @};
11438 memcpy (&x, ptr, sizeof x);
11440 x.mm = _mm_adds_epu8 (x.mm, y.mm);
11443 /* Instead of a variable, a compound literal may be used to pass the
11444 return value of an intrinsic call to a function expecting the union: */
11446 x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@});
11447 @c This could be done implicitly with __attribute__((transparent_union)),
11448 @c but GCC does not accept it for unions of vector types (PR 88955).
11452 @section Support for @code{offsetof}
11453 @findex __builtin_offsetof
11455 GCC implements for both C and C++ a syntactic extension to implement
11456 the @code{offsetof} macro.
11460 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
11462 offsetof_member_designator:
11464 | offsetof_member_designator "." @code{identifier}
11465 | offsetof_member_designator "[" @code{expr} "]"
11468 This extension is sufficient such that
11471 #define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member})
11475 is a suitable definition of the @code{offsetof} macro. In C++, @var{type}
11476 may be dependent. In either case, @var{member} may consist of a single
11477 identifier, or a sequence of member accesses and array references.
11479 @node __sync Builtins
11480 @section Legacy @code{__sync} Built-in Functions for Atomic Memory Access
11482 The following built-in functions
11483 are intended to be compatible with those described
11484 in the @cite{Intel Itanium Processor-specific Application Binary Interface},
11485 section 7.4. As such, they depart from normal GCC practice by not using
11486 the @samp{__builtin_} prefix and also by being overloaded so that they
11487 work on multiple types.
11489 The definition given in the Intel documentation allows only for the use of
11490 the types @code{int}, @code{long}, @code{long long} or their unsigned
11491 counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in
11492 size other than the C type @code{_Bool} or the C++ type @code{bool}.
11493 Operations on pointer arguments are performed as if the operands were
11494 of the @code{uintptr_t} type. That is, they are not scaled by the size
11495 of the type to which the pointer points.
11497 These functions are implemented in terms of the @samp{__atomic}
11498 builtins (@pxref{__atomic Builtins}). They should not be used for new
11499 code which should use the @samp{__atomic} builtins instead.
11501 Not all operations are supported by all target processors. If a particular
11502 operation cannot be implemented on the target processor, a warning is
11503 generated and a call to an external function is generated. The external
11504 function carries the same name as the built-in version,
11505 with an additional suffix
11506 @samp{_@var{n}} where @var{n} is the size of the data type.
11508 @c ??? Should we have a mechanism to suppress this warning? This is almost
11509 @c useful for implementing the operation under the control of an external
11512 In most cases, these built-in functions are considered a @dfn{full barrier}.
11514 no memory operand is moved across the operation, either forward or
11515 backward. Further, instructions are issued as necessary to prevent the
11516 processor from speculating loads across the operation and from queuing stores
11517 after the operation.
11519 All of the routines are described in the Intel documentation to take
11520 ``an optional list of variables protected by the memory barrier''. It's
11521 not clear what is meant by that; it could mean that @emph{only} the
11522 listed variables are protected, or it could mean a list of additional
11523 variables to be protected. The list is ignored by GCC which treats it as
11524 empty. GCC interprets an empty list as meaning that all globally
11525 accessible variables should be protected.
11528 @item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...)
11529 @itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...)
11530 @itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...)
11531 @itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...)
11532 @itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...)
11533 @itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...)
11534 @findex __sync_fetch_and_add
11535 @findex __sync_fetch_and_sub
11536 @findex __sync_fetch_and_or
11537 @findex __sync_fetch_and_and
11538 @findex __sync_fetch_and_xor
11539 @findex __sync_fetch_and_nand
11540 These built-in functions perform the operation suggested by the name, and
11541 returns the value that had previously been in memory. That is, operations
11542 on integer operands have the following semantics. Operations on pointer
11543 arguments are performed as if the operands were of the @code{uintptr_t}
11544 type. That is, they are not scaled by the size of the type to which
11545 the pointer points.
11548 @{ tmp = *ptr; *ptr @var{op}= value; return tmp; @}
11549 @{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand
11552 The object pointed to by the first argument must be of integer or pointer
11553 type. It must not be a boolean type.
11555 @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand}
11556 as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}.
11558 @item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...)
11559 @itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...)
11560 @itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...)
11561 @itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...)
11562 @itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...)
11563 @itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...)
11564 @findex __sync_add_and_fetch
11565 @findex __sync_sub_and_fetch
11566 @findex __sync_or_and_fetch
11567 @findex __sync_and_and_fetch
11568 @findex __sync_xor_and_fetch
11569 @findex __sync_nand_and_fetch
11570 These built-in functions perform the operation suggested by the name, and
11571 return the new value. That is, operations on integer operands have
11572 the following semantics. Operations on pointer operands are performed as
11573 if the operand's type were @code{uintptr_t}.
11576 @{ *ptr @var{op}= value; return *ptr; @}
11577 @{ *ptr = ~(*ptr & value); return *ptr; @} // nand
11580 The same constraints on arguments apply as for the corresponding
11581 @code{__sync_op_and_fetch} built-in functions.
11583 @emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch}
11584 as @code{*ptr = ~(*ptr & value)} instead of
11585 @code{*ptr = ~*ptr & value}.
11587 @item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
11588 @itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
11589 @findex __sync_bool_compare_and_swap
11590 @findex __sync_val_compare_and_swap
11591 These built-in functions perform an atomic compare and swap.
11592 That is, if the current
11593 value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into
11596 The ``bool'' version returns @code{true} if the comparison is successful and
11597 @var{newval} is written. The ``val'' version returns the contents
11598 of @code{*@var{ptr}} before the operation.
11600 @item __sync_synchronize (...)
11601 @findex __sync_synchronize
11602 This built-in function issues a full memory barrier.
11604 @item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...)
11605 @findex __sync_lock_test_and_set
11606 This built-in function, as described by Intel, is not a traditional test-and-set
11607 operation, but rather an atomic exchange operation. It writes @var{value}
11608 into @code{*@var{ptr}}, and returns the previous contents of
11611 Many targets have only minimal support for such locks, and do not support
11612 a full exchange operation. In this case, a target may support reduced
11613 functionality here by which the @emph{only} valid value to store is the
11614 immediate constant 1. The exact value actually stored in @code{*@var{ptr}}
11615 is implementation defined.
11617 This built-in function is not a full barrier,
11618 but rather an @dfn{acquire barrier}.
11619 This means that references after the operation cannot move to (or be
11620 speculated to) before the operation, but previous memory stores may not
11621 be globally visible yet, and previous memory loads may not yet be
11624 @item void __sync_lock_release (@var{type} *ptr, ...)
11625 @findex __sync_lock_release
11626 This built-in function releases the lock acquired by
11627 @code{__sync_lock_test_and_set}.
11628 Normally this means writing the constant 0 to @code{*@var{ptr}}.
11630 This built-in function is not a full barrier,
11631 but rather a @dfn{release barrier}.
11632 This means that all previous memory stores are globally visible, and all
11633 previous memory loads have been satisfied, but following memory reads
11634 are not prevented from being speculated to before the barrier.
11637 @node __atomic Builtins
11638 @section Built-in Functions for Memory Model Aware Atomic Operations
11640 The following built-in functions approximately match the requirements
11641 for the C++11 memory model. They are all
11642 identified by being prefixed with @samp{__atomic} and most are
11643 overloaded so that they work with multiple types.
11645 These functions are intended to replace the legacy @samp{__sync}
11646 builtins. The main difference is that the memory order that is requested
11647 is a parameter to the functions. New code should always use the
11648 @samp{__atomic} builtins rather than the @samp{__sync} builtins.
11650 Note that the @samp{__atomic} builtins assume that programs will
11651 conform to the C++11 memory model. In particular, they assume
11652 that programs are free of data races. See the C++11 standard for
11653 detailed requirements.
11655 The @samp{__atomic} builtins can be used with any integral scalar or
11656 pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral
11657 types are also allowed if @samp{__int128} (@pxref{__int128}) is
11658 supported by the architecture.
11660 The four non-arithmetic functions (load, store, exchange, and
11661 compare_exchange) all have a generic version as well. This generic
11662 version works on any data type. It uses the lock-free built-in function
11663 if the specific data type size makes that possible; otherwise, an
11664 external call is left to be resolved at run time. This external call is
11665 the same format with the addition of a @samp{size_t} parameter inserted
11666 as the first parameter indicating the size of the object being pointed to.
11667 All objects must be the same size.
11669 There are 6 different memory orders that can be specified. These map
11670 to the C++11 memory orders with the same names, see the C++11 standard
11671 or the @uref{http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki
11672 on atomic synchronization} for detailed definitions. Individual
11673 targets may also support additional memory orders for use on specific
11674 architectures. Refer to the target documentation for details of
11677 An atomic operation can both constrain code motion and
11678 be mapped to hardware instructions for synchronization between threads
11679 (e.g., a fence). To which extent this happens is controlled by the
11680 memory orders, which are listed here in approximately ascending order of
11681 strength. The description of each memory order is only meant to roughly
11682 illustrate the effects and is not a specification; see the C++11
11683 memory model for precise semantics.
11686 @item __ATOMIC_RELAXED
11687 Implies no inter-thread ordering constraints.
11688 @item __ATOMIC_CONSUME
11689 This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE}
11690 memory order because of a deficiency in C++11's semantics for
11691 @code{memory_order_consume}.
11692 @item __ATOMIC_ACQUIRE
11693 Creates an inter-thread happens-before constraint from the release (or
11694 stronger) semantic store to this acquire load. Can prevent hoisting
11695 of code to before the operation.
11696 @item __ATOMIC_RELEASE
11697 Creates an inter-thread happens-before constraint to acquire (or stronger)
11698 semantic loads that read from this release store. Can prevent sinking
11699 of code to after the operation.
11700 @item __ATOMIC_ACQ_REL
11701 Combines the effects of both @code{__ATOMIC_ACQUIRE} and
11702 @code{__ATOMIC_RELEASE}.
11703 @item __ATOMIC_SEQ_CST
11704 Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations.
11707 Note that in the C++11 memory model, @emph{fences} (e.g.,
11708 @samp{__atomic_thread_fence}) take effect in combination with other
11709 atomic operations on specific memory locations (e.g., atomic loads);
11710 operations on specific memory locations do not necessarily affect other
11711 operations in the same way.
11713 Target architectures are encouraged to provide their own patterns for
11714 each of the atomic built-in functions. If no target is provided, the original
11715 non-memory model set of @samp{__sync} atomic built-in functions are
11716 used, along with any required synchronization fences surrounding it in
11717 order to achieve the proper behavior. Execution in this case is subject
11718 to the same restrictions as those built-in functions.
11720 If there is no pattern or mechanism to provide a lock-free instruction
11721 sequence, a call is made to an external routine with the same parameters
11722 to be resolved at run time.
11724 When implementing patterns for these built-in functions, the memory order
11725 parameter can be ignored as long as the pattern implements the most
11726 restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory
11727 orders execute correctly with this memory order but they may not execute as
11728 efficiently as they could with a more appropriate implementation of the
11729 relaxed requirements.
11731 Note that the C++11 standard allows for the memory order parameter to be
11732 determined at run time rather than at compile time. These built-in
11733 functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather
11734 than invoke a runtime library call or inline a switch statement. This is
11735 standard compliant, safe, and the simplest approach for now.
11737 The memory order parameter is a signed int, but only the lower 16 bits are
11738 reserved for the memory order. The remainder of the signed int is reserved
11739 for target use and should be 0. Use of the predefined atomic values
11740 ensures proper usage.
11742 @deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memorder)
11743 This built-in function implements an atomic load operation. It returns the
11744 contents of @code{*@var{ptr}}.
11746 The valid memory order variants are
11747 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
11748 and @code{__ATOMIC_CONSUME}.
11752 @deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder)
11753 This is the generic version of an atomic load. It returns the
11754 contents of @code{*@var{ptr}} in @code{*@var{ret}}.
11758 @deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder)
11759 This built-in function implements an atomic store operation. It writes
11760 @code{@var{val}} into @code{*@var{ptr}}.
11762 The valid memory order variants are
11763 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}.
11767 @deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder)
11768 This is the generic version of an atomic store. It stores the value
11769 of @code{*@var{val}} into @code{*@var{ptr}}.
11773 @deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder)
11774 This built-in function implements an atomic exchange operation. It writes
11775 @var{val} into @code{*@var{ptr}}, and returns the previous contents of
11778 The valid memory order variants are
11779 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
11780 @code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}.
11784 @deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder)
11785 This is the generic version of an atomic exchange. It stores the
11786 contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value
11787 of @code{*@var{ptr}} is copied into @code{*@var{ret}}.
11791 @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)
11792 This built-in function implements an atomic compare and exchange operation.
11793 This compares the contents of @code{*@var{ptr}} with the contents of
11794 @code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write}
11795 operation that writes @var{desired} into @code{*@var{ptr}}. If they are not
11796 equal, the operation is a @emph{read} and the current contents of
11797 @code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true}
11798 for weak compare_exchange, which may fail spuriously, and @code{false} for
11799 the strong variation, which never fails spuriously. Many targets
11800 only offer the strong variation and ignore the parameter. When in doubt, use
11801 the strong variation.
11803 If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned
11804 and memory is affected according to the
11805 memory order specified by @var{success_memorder}. There are no
11806 restrictions on what memory order can be used here.
11808 Otherwise, @code{false} is returned and memory is affected according
11809 to @var{failure_memorder}. This memory order cannot be
11810 @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a
11811 stronger order than that specified by @var{success_memorder}.
11815 @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)
11816 This built-in function implements the generic version of
11817 @code{__atomic_compare_exchange}. The function is virtually identical to
11818 @code{__atomic_compare_exchange_n}, except the desired value is also a
11823 @deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder)
11824 @deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder)
11825 @deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder)
11826 @deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder)
11827 @deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder)
11828 @deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder)
11829 These built-in functions perform the operation suggested by the name, and
11830 return the result of the operation. Operations on pointer arguments are
11831 performed as if the operands were of the @code{uintptr_t} type. That is,
11832 they are not scaled by the size of the type to which the pointer points.
11835 @{ *ptr @var{op}= val; return *ptr; @}
11836 @{ *ptr = ~(*ptr & val); return *ptr; @} // nand
11839 The object pointed to by the first argument must be of integer or pointer
11840 type. It must not be a boolean type. All memory orders are valid.
11844 @deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder)
11845 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder)
11846 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder)
11847 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder)
11848 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder)
11849 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder)
11850 These built-in functions perform the operation suggested by the name, and
11851 return the value that had previously been in @code{*@var{ptr}}. Operations
11852 on pointer arguments are performed as if the operands were of
11853 the @code{uintptr_t} type. That is, they are not scaled by the size of
11854 the type to which the pointer points.
11857 @{ tmp = *ptr; *ptr @var{op}= val; return tmp; @}
11858 @{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand
11861 The same constraints on arguments apply as for the corresponding
11862 @code{__atomic_op_fetch} built-in functions. All memory orders are valid.
11866 @deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memorder)
11868 This built-in function performs an atomic test-and-set operation on
11869 the byte at @code{*@var{ptr}}. The byte is set to some implementation
11870 defined nonzero ``set'' value and the return value is @code{true} if and only
11871 if the previous contents were ``set''.
11872 It should be only used for operands of type @code{bool} or @code{char}. For
11873 other types only part of the value may be set.
11875 All memory orders are valid.
11879 @deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memorder)
11881 This built-in function performs an atomic clear operation on
11882 @code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0.
11883 It should be only used for operands of type @code{bool} or @code{char} and
11884 in conjunction with @code{__atomic_test_and_set}.
11885 For other types it may only clear partially. If the type is not @code{bool}
11886 prefer using @code{__atomic_store}.
11888 The valid memory order variants are
11889 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and
11890 @code{__ATOMIC_RELEASE}.
11894 @deftypefn {Built-in Function} void __atomic_thread_fence (int memorder)
11896 This built-in function acts as a synchronization fence between threads
11897 based on the specified memory order.
11899 All memory orders are valid.
11903 @deftypefn {Built-in Function} void __atomic_signal_fence (int memorder)
11905 This built-in function acts as a synchronization fence between a thread
11906 and signal handlers based in the same thread.
11908 All memory orders are valid.
11912 @deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr)
11914 This built-in function returns @code{true} if objects of @var{size} bytes always
11915 generate lock-free atomic instructions for the target architecture.
11916 @var{size} must resolve to a compile-time constant and the result also
11917 resolves to a compile-time constant.
11919 @var{ptr} is an optional pointer to the object that may be used to determine
11920 alignment. A value of 0 indicates typical alignment should be used. The
11921 compiler may also ignore this parameter.
11924 if (__atomic_always_lock_free (sizeof (long long), 0))
11929 @deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr)
11931 This built-in function returns @code{true} if objects of @var{size} bytes always
11932 generate lock-free atomic instructions for the target architecture. If
11933 the built-in function is not known to be lock-free, a call is made to a
11934 runtime routine named @code{__atomic_is_lock_free}.
11936 @var{ptr} is an optional pointer to the object that may be used to determine
11937 alignment. A value of 0 indicates typical alignment should be used. The
11938 compiler may also ignore this parameter.
11941 @node Integer Overflow Builtins
11942 @section Built-in Functions to Perform Arithmetic with Overflow Checking
11944 The following built-in functions allow performing simple arithmetic operations
11945 together with checking whether the operations overflowed.
11947 @deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
11948 @deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res)
11949 @deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res)
11950 @deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res)
11951 @deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res)
11952 @deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
11953 @deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
11955 These built-in functions promote the first two operands into infinite precision signed
11956 type and perform addition on those promoted operands. The result is then
11957 cast to the type the third pointer argument points to and stored there.
11958 If the stored result is equal to the infinite precision result, the built-in
11959 functions return @code{false}, otherwise they return @code{true}. As the addition is
11960 performed in infinite signed precision, these built-in functions have fully defined
11961 behavior for all argument values.
11963 The first built-in function allows arbitrary integral types for operands and
11964 the result type must be pointer to some integral type other than enumerated or
11965 boolean type, the rest of the built-in functions have explicit integer types.
11967 The compiler will attempt to use hardware instructions to implement
11968 these built-in functions where possible, like conditional jump on overflow
11969 after addition, conditional jump on carry etc.
11973 @deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
11974 @deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res)
11975 @deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res)
11976 @deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res)
11977 @deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res)
11978 @deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
11979 @deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
11981 These built-in functions are similar to the add overflow checking built-in
11982 functions above, except they perform subtraction, subtract the second argument
11983 from the first one, instead of addition.
11987 @deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
11988 @deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res)
11989 @deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res)
11990 @deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res)
11991 @deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res)
11992 @deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
11993 @deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
11995 These built-in functions are similar to the add overflow checking built-in
11996 functions above, except they perform multiplication, instead of addition.
12000 The following built-in functions allow checking if simple arithmetic operation
12003 @deftypefn {Built-in Function} bool __builtin_add_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12004 @deftypefnx {Built-in Function} bool __builtin_sub_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12005 @deftypefnx {Built-in Function} bool __builtin_mul_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
12007 These built-in functions are similar to @code{__builtin_add_overflow},
12008 @code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that
12009 they don't store the result of the arithmetic operation anywhere and the
12010 last argument is not a pointer, but some expression with integral type other
12011 than enumerated or boolean type.
12013 The built-in functions promote the first two operands into infinite precision signed type
12014 and perform addition on those promoted operands. The result is then
12015 cast to the type of the third argument. If the cast result is equal to the infinite
12016 precision result, the built-in functions return @code{false}, otherwise they return @code{true}.
12017 The value of the third argument is ignored, just the side effects in the third argument
12018 are evaluated, and no integral argument promotions are performed on the last argument.
12019 If the third argument is a bit-field, the type used for the result cast has the
12020 precision and signedness of the given bit-field, rather than precision and signedness
12021 of the underlying type.
12023 For example, the following macro can be used to portably check, at
12024 compile-time, whether or not adding two constant integers will overflow,
12025 and perform the addition only when it is known to be safe and not to trigger
12026 a @option{-Woverflow} warning.
12029 #define INT_ADD_OVERFLOW_P(a, b) \
12030 __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0)
12033 A = INT_MAX, B = 3,
12034 C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B,
12035 D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0)
12039 The compiler will attempt to use hardware instructions to implement
12040 these built-in functions where possible, like conditional jump on overflow
12041 after addition, conditional jump on carry etc.
12045 @node x86 specific memory model extensions for transactional memory
12046 @section x86-Specific Memory Model Extensions for Transactional Memory
12048 The x86 architecture supports additional memory ordering flags
12049 to mark critical sections for hardware lock elision.
12050 These must be specified in addition to an existing memory order to
12054 @item __ATOMIC_HLE_ACQUIRE
12055 Start lock elision on a lock variable.
12056 Memory order must be @code{__ATOMIC_ACQUIRE} or stronger.
12057 @item __ATOMIC_HLE_RELEASE
12058 End lock elision on a lock variable.
12059 Memory order must be @code{__ATOMIC_RELEASE} or stronger.
12062 When a lock acquire fails, it is required for good performance to abort
12063 the transaction quickly. This can be done with a @code{_mm_pause}.
12066 #include <immintrin.h> // For _mm_pause
12070 /* Acquire lock with lock elision */
12071 while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE))
12072 _mm_pause(); /* Abort failed transaction */
12074 /* Free lock with lock elision */
12075 __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE);
12078 @node Object Size Checking
12079 @section Object Size Checking Built-in Functions
12080 @findex __builtin_object_size
12081 @findex __builtin___memcpy_chk
12082 @findex __builtin___mempcpy_chk
12083 @findex __builtin___memmove_chk
12084 @findex __builtin___memset_chk
12085 @findex __builtin___strcpy_chk
12086 @findex __builtin___stpcpy_chk
12087 @findex __builtin___strncpy_chk
12088 @findex __builtin___strcat_chk
12089 @findex __builtin___strncat_chk
12090 @findex __builtin___sprintf_chk
12091 @findex __builtin___snprintf_chk
12092 @findex __builtin___vsprintf_chk
12093 @findex __builtin___vsnprintf_chk
12094 @findex __builtin___printf_chk
12095 @findex __builtin___vprintf_chk
12096 @findex __builtin___fprintf_chk
12097 @findex __builtin___vfprintf_chk
12099 GCC implements a limited buffer overflow protection mechanism that can
12100 prevent some buffer overflow attacks by determining the sizes of objects
12101 into which data is about to be written and preventing the writes when
12102 the size isn't sufficient. The built-in functions described below yield
12103 the best results when used together and when optimization is enabled.
12104 For example, to detect object sizes across function boundaries or to
12105 follow pointer assignments through non-trivial control flow they rely
12106 on various optimization passes enabled with @option{-O2}. However, to
12107 a limited extent, they can be used without optimization as well.
12109 @deftypefn {Built-in Function} {size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
12110 is a built-in construct that returns a constant number of bytes from
12111 @var{ptr} to the end of the object @var{ptr} pointer points to
12112 (if known at compile time). To determine the sizes of dynamically allocated
12113 objects the function relies on the allocation functions called to obtain
12114 the storage to be declared with the @code{alloc_size} attribute (@pxref{Common
12115 Function Attributes}). @code{__builtin_object_size} never evaluates
12116 its arguments for side effects. If there are any side effects in them, it
12117 returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
12118 for @var{type} 2 or 3. If there are multiple objects @var{ptr} can
12119 point to and all of them are known at compile time, the returned number
12120 is the maximum of remaining byte counts in those objects if @var{type} & 2 is
12121 0 and minimum if nonzero. If it is not possible to determine which objects
12122 @var{ptr} points to at compile time, @code{__builtin_object_size} should
12123 return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
12124 for @var{type} 2 or 3.
12126 @var{type} is an integer constant from 0 to 3. If the least significant
12127 bit is clear, objects are whole variables, if it is set, a closest
12128 surrounding subobject is considered the object a pointer points to.
12129 The second bit determines if maximum or minimum of remaining bytes
12133 struct V @{ char buf1[10]; int b; char buf2[10]; @} var;
12134 char *p = &var.buf1[1], *q = &var.b;
12136 /* Here the object p points to is var. */
12137 assert (__builtin_object_size (p, 0) == sizeof (var) - 1);
12138 /* The subobject p points to is var.buf1. */
12139 assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1);
12140 /* The object q points to is var. */
12141 assert (__builtin_object_size (q, 0)
12142 == (char *) (&var + 1) - (char *) &var.b);
12143 /* The subobject q points to is var.b. */
12144 assert (__builtin_object_size (q, 1) == sizeof (var.b));
12148 There are built-in functions added for many common string operation
12149 functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk}
12150 built-in is provided. This built-in has an additional last argument,
12151 which is the number of bytes remaining in the object the @var{dest}
12152 argument points to or @code{(size_t) -1} if the size is not known.
12154 The built-in functions are optimized into the normal string functions
12155 like @code{memcpy} if the last argument is @code{(size_t) -1} or if
12156 it is known at compile time that the destination object will not
12157 be overflowed. If the compiler can determine at compile time that the
12158 object will always be overflowed, it issues a warning.
12160 The intended use can be e.g.@:
12164 #define bos0(dest) __builtin_object_size (dest, 0)
12165 #define memcpy(dest, src, n) \
12166 __builtin___memcpy_chk (dest, src, n, bos0 (dest))
12170 /* It is unknown what object p points to, so this is optimized
12171 into plain memcpy - no checking is possible. */
12172 memcpy (p, "abcde", n);
12173 /* Destination is known and length too. It is known at compile
12174 time there will be no overflow. */
12175 memcpy (&buf[5], "abcde", 5);
12176 /* Destination is known, but the length is not known at compile time.
12177 This will result in __memcpy_chk call that can check for overflow
12179 memcpy (&buf[5], "abcde", n);
12180 /* Destination is known and it is known at compile time there will
12181 be overflow. There will be a warning and __memcpy_chk call that
12182 will abort the program at run time. */
12183 memcpy (&buf[6], "abcde", 5);
12186 Such built-in functions are provided for @code{memcpy}, @code{mempcpy},
12187 @code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy},
12188 @code{strcat} and @code{strncat}.
12190 There are also checking built-in functions for formatted output functions.
12192 int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...);
12193 int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os,
12194 const char *fmt, ...);
12195 int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt,
12197 int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os,
12198 const char *fmt, va_list ap);
12201 The added @var{flag} argument is passed unchanged to @code{__sprintf_chk}
12202 etc.@: functions and can contain implementation specific flags on what
12203 additional security measures the checking function might take, such as
12204 handling @code{%n} differently.
12206 The @var{os} argument is the object size @var{s} points to, like in the
12207 other built-in functions. There is a small difference in the behavior
12208 though, if @var{os} is @code{(size_t) -1}, the built-in functions are
12209 optimized into the non-checking functions only if @var{flag} is 0, otherwise
12210 the checking function is called with @var{os} argument set to
12211 @code{(size_t) -1}.
12213 In addition to this, there are checking built-in functions
12214 @code{__builtin___printf_chk}, @code{__builtin___vprintf_chk},
12215 @code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}.
12216 These have just one additional argument, @var{flag}, right before
12217 format string @var{fmt}. If the compiler is able to optimize them to
12218 @code{fputc} etc.@: functions, it does, otherwise the checking function
12219 is called and the @var{flag} argument passed to it.
12221 @node Other Builtins
12222 @section Other Built-in Functions Provided by GCC
12223 @cindex built-in functions
12224 @findex __builtin_alloca
12225 @findex __builtin_alloca_with_align
12226 @findex __builtin_alloca_with_align_and_max
12227 @findex __builtin_call_with_static_chain
12228 @findex __builtin_extend_pointer
12229 @findex __builtin_fpclassify
12230 @findex __builtin_has_attribute
12231 @findex __builtin_isfinite
12232 @findex __builtin_isnormal
12233 @findex __builtin_isgreater
12234 @findex __builtin_isgreaterequal
12235 @findex __builtin_isinf_sign
12236 @findex __builtin_isless
12237 @findex __builtin_islessequal
12238 @findex __builtin_islessgreater
12239 @findex __builtin_isunordered
12240 @findex __builtin_object_size
12241 @findex __builtin_powi
12242 @findex __builtin_powif
12243 @findex __builtin_powil
12244 @findex __builtin_speculation_safe_value
12405 @findex fprintf_unlocked
12407 @findex fputs_unlocked
12516 @findex nexttowardf
12517 @findex nexttowardl
12525 @findex printf_unlocked
12556 @findex signbitd128
12557 @findex significand
12558 @findex significandf
12559 @findex significandl
12587 @findex strncasecmp
12631 GCC provides a large number of built-in functions other than the ones
12632 mentioned above. Some of these are for internal use in the processing
12633 of exceptions or variable-length argument lists and are not
12634 documented here because they may change from time to time; we do not
12635 recommend general use of these functions.
12637 The remaining functions are provided for optimization purposes.
12639 With the exception of built-ins that have library equivalents such as
12640 the standard C library functions discussed below, or that expand to
12641 library calls, GCC built-in functions are always expanded inline and
12642 thus do not have corresponding entry points and their address cannot
12643 be obtained. Attempting to use them in an expression other than
12644 a function call results in a compile-time error.
12646 @opindex fno-builtin
12647 GCC includes built-in versions of many of the functions in the standard
12648 C library. These functions come in two forms: one whose names start with
12649 the @code{__builtin_} prefix, and the other without. Both forms have the
12650 same type (including prototype), the same address (when their address is
12651 taken), and the same meaning as the C library functions even if you specify
12652 the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these
12653 functions are only optimized in certain cases; if they are not optimized in
12654 a particular case, a call to the library function is emitted.
12658 Outside strict ISO C mode (@option{-ansi}, @option{-std=c90},
12659 @option{-std=c99} or @option{-std=c11}), the functions
12660 @code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero},
12661 @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml},
12662 @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll},
12663 @code{ffsl}, @code{ffs}, @code{fprintf_unlocked},
12664 @code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma},
12665 @code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext},
12666 @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0},
12667 @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn},
12668 @code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy},
12669 @code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked},
12670 @code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roudnevenl},
12671 @code{scalbf}, @code{scalbl}, @code{scalb},
12672 @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32},
12673 @code{signbitd64}, @code{signbitd128}, @code{significandf},
12674 @code{significandl}, @code{significand}, @code{sincosf},
12675 @code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy},
12676 @code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp},
12677 @code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l},
12678 @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and
12680 may be handled as built-in functions.
12681 All these functions have corresponding versions
12682 prefixed with @code{__builtin_}, which may be used even in strict C90
12685 The ISO C99 functions
12686 @code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf},
12687 @code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh},
12688 @code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf},
12689 @code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos},
12690 @code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf},
12691 @code{casinhl}, @code{casinh}, @code{casinl}, @code{casin},
12692 @code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh},
12693 @code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt},
12694 @code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl},
12695 @code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf},
12696 @code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog},
12697 @code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl},
12698 @code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf},
12699 @code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal},
12700 @code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl},
12701 @code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf},
12702 @code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan},
12703 @code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl},
12704 @code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f},
12705 @code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim},
12706 @code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax},
12707 @code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf},
12708 @code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb},
12709 @code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf},
12710 @code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl},
12711 @code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround},
12712 @code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l},
12713 @code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf},
12714 @code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl},
12715 @code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint},
12716 @code{nextafterf}, @code{nextafterl}, @code{nextafter},
12717 @code{nexttowardf}, @code{nexttowardl}, @code{nexttoward},
12718 @code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof},
12719 @code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint},
12720 @code{roundf}, @code{roundl}, @code{round}, @code{scalblnf},
12721 @code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl},
12722 @code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal},
12723 @code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc},
12724 @code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf}
12725 are handled as built-in functions
12726 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
12728 There are also built-in versions of the ISO C99 functions
12729 @code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f},
12730 @code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill},
12731 @code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf},
12732 @code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl},
12733 @code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf},
12734 @code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl},
12735 @code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf},
12736 @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl},
12737 @code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl}
12738 that are recognized in any mode since ISO C90 reserves these names for
12739 the purpose to which ISO C99 puts them. All these functions have
12740 corresponding versions prefixed with @code{__builtin_}.
12742 There are also built-in functions @code{__builtin_fabsf@var{n}},
12743 @code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and
12744 @code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3
12745 functions @code{fabsf@var{n}}, @code{fabsf@var{n}x},
12746 @code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported
12747 types @code{_Float@var{n}} and @code{_Float@var{n}x}.
12749 There are also GNU extension functions @code{clog10}, @code{clog10f} and
12750 @code{clog10l} which names are reserved by ISO C99 for future use.
12751 All these functions have versions prefixed with @code{__builtin_}.
12753 The ISO C94 functions
12754 @code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit},
12755 @code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct},
12756 @code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and
12758 are handled as built-in functions
12759 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
12761 The ISO C90 functions
12762 @code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2},
12763 @code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos},
12764 @code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod},
12765 @code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf},
12766 @code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit},
12767 @code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct},
12768 @code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower},
12769 @code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log},
12770 @code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy},
12771 @code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar},
12772 @code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin},
12773 @code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat},
12774 @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn},
12775 @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy},
12776 @code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr},
12777 @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf}
12778 are all recognized as built-in functions unless
12779 @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}}
12780 is specified for an individual function). All of these functions have
12781 corresponding versions prefixed with @code{__builtin_}.
12783 GCC provides built-in versions of the ISO C99 floating-point comparison
12784 macros that avoid raising exceptions for unordered operands. They have
12785 the same names as the standard macros ( @code{isgreater},
12786 @code{isgreaterequal}, @code{isless}, @code{islessequal},
12787 @code{islessgreater}, and @code{isunordered}) , with @code{__builtin_}
12788 prefixed. We intend for a library implementor to be able to simply
12789 @code{#define} each standard macro to its built-in equivalent.
12790 In the same fashion, GCC provides @code{fpclassify}, @code{isfinite},
12791 @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with
12792 @code{__builtin_} prefixed. The @code{isinf} and @code{isnan}
12793 built-in functions appear both with and without the @code{__builtin_} prefix.
12795 @deftypefn {Built-in Function} void *__builtin_alloca (size_t size)
12796 The @code{__builtin_alloca} function must be called at block scope.
12797 The function allocates an object @var{size} bytes large on the stack
12798 of the calling function. The object is aligned on the default stack
12799 alignment boundary for the target determined by the
12800 @code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca}
12801 function returns a pointer to the first byte of the allocated object.
12802 The lifetime of the allocated object ends just before the calling
12803 function returns to its caller. This is so even when
12804 @code{__builtin_alloca} is called within a nested block.
12806 For example, the following function allocates eight objects of @code{n}
12807 bytes each on the stack, storing a pointer to each in consecutive elements
12808 of the array @code{a}. It then passes the array to function @code{g}
12809 which can safely use the storage pointed to by each of the array elements.
12812 void f (unsigned n)
12815 for (int i = 0; i != 8; ++i)
12816 a [i] = __builtin_alloca (n);
12818 g (a, n); // @r{safe}
12822 Since the @code{__builtin_alloca} function doesn't validate its argument
12823 it is the responsibility of its caller to make sure the argument doesn't
12824 cause it to exceed the stack size limit.
12825 The @code{__builtin_alloca} function is provided to make it possible to
12826 allocate on the stack arrays of bytes with an upper bound that may be
12827 computed at run time. Since C99 Variable Length Arrays offer
12828 similar functionality under a portable, more convenient, and safer
12829 interface they are recommended instead, in both C99 and C++ programs
12830 where GCC provides them as an extension.
12831 @xref{Variable Length}, for details.
12835 @deftypefn {Built-in Function} void *__builtin_alloca_with_align (size_t size, size_t alignment)
12836 The @code{__builtin_alloca_with_align} function must be called at block
12837 scope. The function allocates an object @var{size} bytes large on
12838 the stack of the calling function. The allocated object is aligned on
12839 the boundary specified by the argument @var{alignment} whose unit is given
12840 in bits (not bytes). The @var{size} argument must be positive and not
12841 exceed the stack size limit. The @var{alignment} argument must be a constant
12842 integer expression that evaluates to a power of 2 greater than or equal to
12843 @code{CHAR_BIT} and less than some unspecified maximum. Invocations
12844 with other values are rejected with an error indicating the valid bounds.
12845 The function returns a pointer to the first byte of the allocated object.
12846 The lifetime of the allocated object ends at the end of the block in which
12847 the function was called. The allocated storage is released no later than
12848 just before the calling function returns to its caller, but may be released
12849 at the end of the block in which the function was called.
12851 For example, in the following function the call to @code{g} is unsafe
12852 because when @code{overalign} is non-zero, the space allocated by
12853 @code{__builtin_alloca_with_align} may have been released at the end
12854 of the @code{if} statement in which it was called.
12857 void f (unsigned n, bool overalign)
12861 p = __builtin_alloca_with_align (n, 64 /* bits */);
12863 p = __builtin_alloc (n);
12865 g (p, n); // @r{unsafe}
12869 Since the @code{__builtin_alloca_with_align} function doesn't validate its
12870 @var{size} argument it is the responsibility of its caller to make sure
12871 the argument doesn't cause it to exceed the stack size limit.
12872 The @code{__builtin_alloca_with_align} function is provided to make
12873 it possible to allocate on the stack overaligned arrays of bytes with
12874 an upper bound that may be computed at run time. Since C99
12875 Variable Length Arrays offer the same functionality under
12876 a portable, more convenient, and safer interface they are recommended
12877 instead, in both C99 and C++ programs where GCC provides them as
12878 an extension. @xref{Variable Length}, for details.
12882 @deftypefn {Built-in Function} void *__builtin_alloca_with_align_and_max (size_t size, size_t alignment, size_t max_size)
12883 Similar to @code{__builtin_alloca_with_align} but takes an extra argument
12884 specifying an upper bound for @var{size} in case its value cannot be computed
12885 at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage}
12886 and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer
12887 expression, it has no effect on code generation and no attempt is made to
12888 check its compatibility with @var{size}.
12892 @deftypefn {Built-in Function} bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})
12893 The @code{__builtin_has_attribute} function evaluates to an integer constant
12894 expression equal to @code{true} if the symbol or type referenced by
12895 the @var{type-or-expression} argument has been declared with
12896 the @var{attribute} referenced by the second argument. For
12897 an @var{type-or-expression} argument that does not reference a symbol,
12898 since attributes do not apply to expressions the built-in consider
12899 the type of the argument. Neither argument is evaluated.
12900 The @var{type-or-expression} argument is subject to the same
12901 restrictions as the argument to @code{typeof} (@pxref{Typeof}). The
12902 @var{attribute} argument is an attribute name optionally followed by
12903 a comma-separated list of arguments enclosed in parentheses. Both forms
12904 of attribute names---with and without double leading and trailing
12905 underscores---are recognized. @xref{Attribute Syntax}, for details.
12906 When no attribute arguments are specified for an attribute that expects
12907 one or more arguments the function returns @code{true} if
12908 @var{type-or-expression} has been declared with the attribute regardless
12909 of the attribute argument values. Arguments provided for an attribute
12910 that expects some are validated and matched up to the provided number.
12911 The function returns @code{true} if all provided arguments match. For
12912 example, the first call to the function below evaluates to @code{true}
12913 because @code{x} is declared with the @code{aligned} attribute but
12914 the second call evaluates to @code{false} because @code{x} is declared
12915 @code{aligned (8)} and not @code{aligned (4)}.
12918 __attribute__ ((aligned (8))) int x;
12919 _Static_assert (__builtin_has_attribute (x, aligned), "aligned");
12920 _Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)");
12923 Due to a limitation the @code{__builtin_has_attribute} function returns
12924 @code{false} for the @code{mode} attribute even if the type or variable
12925 referenced by the @var{type-or-expression} argument was declared with one.
12926 The function is also not supported with labels, and in C with enumerators.
12928 Note that unlike the @code{__has_attribute} preprocessor operator which
12929 is suitable for use in @code{#if} preprocessing directives
12930 @code{__builtin_has_attribute} is an intrinsic function that is not
12931 recognized in such contexts.
12935 @deftypefn {Built-in Function} @var{type} __builtin_speculation_safe_value (@var{type} val, @var{type} failval)
12937 This built-in function can be used to help mitigate against unsafe
12938 speculative execution. @var{type} may be any integral type or any
12943 If the CPU is not speculatively executing the code, then @var{val}
12946 If the CPU is executing speculatively then either:
12949 The function may cause execution to pause until it is known that the
12950 code is no-longer being executed speculatively (in which case
12951 @var{val} can be returned, as above); or
12953 The function may use target-dependent speculation tracking state to cause
12954 @var{failval} to be returned when it is known that speculative
12955 execution has incorrectly predicted a conditional branch operation.
12959 The second argument, @var{failval}, is optional and defaults to zero
12962 GCC defines the preprocessor macro
12963 @code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been
12964 updated to support this builtin.
12966 The built-in function can be used where a variable appears to be used in a
12967 safe way, but the CPU, due to speculative execution may temporarily ignore
12968 the bounds checks. Consider, for example, the following function:
12972 int f (unsigned untrusted_index)
12974 if (untrusted_index < 500)
12975 return array[untrusted_index];
12980 If the function is called repeatedly with @code{untrusted_index} less
12981 than the limit of 500, then a branch predictor will learn that the
12982 block of code that returns a value stored in @code{array} will be
12983 executed. If the function is subsequently called with an
12984 out-of-range value it will still try to execute that block of code
12985 first until the CPU determines that the prediction was incorrect
12986 (the CPU will unwind any incorrect operations at that point).
12987 However, depending on how the result of the function is used, it might be
12988 possible to leave traces in the cache that can reveal what was stored
12989 at the out-of-bounds location. The built-in function can be used to
12990 provide some protection against leaking data in this way by changing
12995 int f (unsigned untrusted_index)
12997 if (untrusted_index < 500)
12998 return array[__builtin_speculation_safe_value (untrusted_index)];
13003 The built-in function will either cause execution to stall until the
13004 conditional branch has been fully resolved, or it may permit
13005 speculative execution to continue, but using 0 instead of
13006 @code{untrusted_value} if that exceeds the limit.
13008 If accessing any memory location is potentially unsafe when speculative
13009 execution is incorrect, then the code can be rewritten as
13013 int f (unsigned untrusted_index)
13015 if (untrusted_index < 500)
13016 return *__builtin_speculation_safe_value (&array[untrusted_index], NULL);
13021 which will cause a @code{NULL} pointer to be used for the unsafe case.
13025 @deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2})
13027 You can use the built-in function @code{__builtin_types_compatible_p} to
13028 determine whether two types are the same.
13030 This built-in function returns 1 if the unqualified versions of the
13031 types @var{type1} and @var{type2} (which are types, not expressions) are
13032 compatible, 0 otherwise. The result of this built-in function can be
13033 used in integer constant expressions.
13035 This built-in function ignores top level qualifiers (e.g., @code{const},
13036 @code{volatile}). For example, @code{int} is equivalent to @code{const
13039 The type @code{int[]} and @code{int[5]} are compatible. On the other
13040 hand, @code{int} and @code{char *} are not compatible, even if the size
13041 of their types, on the particular architecture are the same. Also, the
13042 amount of pointer indirection is taken into account when determining
13043 similarity. Consequently, @code{short *} is not similar to
13044 @code{short **}. Furthermore, two types that are typedefed are
13045 considered compatible if their underlying types are compatible.
13047 An @code{enum} type is not considered to be compatible with another
13048 @code{enum} type even if both are compatible with the same integer
13049 type; this is what the C standard specifies.
13050 For example, @code{enum @{foo, bar@}} is not similar to
13051 @code{enum @{hot, dog@}}.
13053 You typically use this function in code whose execution varies
13054 depending on the arguments' types. For example:
13059 typeof (x) tmp = (x); \
13060 if (__builtin_types_compatible_p (typeof (x), long double)) \
13061 tmp = foo_long_double (tmp); \
13062 else if (__builtin_types_compatible_p (typeof (x), double)) \
13063 tmp = foo_double (tmp); \
13064 else if (__builtin_types_compatible_p (typeof (x), float)) \
13065 tmp = foo_float (tmp); \
13072 @emph{Note:} This construct is only available for C@.
13076 @deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})
13078 The @var{call_exp} expression must be a function call, and the
13079 @var{pointer_exp} expression must be a pointer. The @var{pointer_exp}
13080 is passed to the function call in the target's static chain location.
13081 The result of builtin is the result of the function call.
13083 @emph{Note:} This builtin is only available for C@.
13084 This builtin can be used to call Go closures from C.
13088 @deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})
13090 You can use the built-in function @code{__builtin_choose_expr} to
13091 evaluate code depending on the value of a constant expression. This
13092 built-in function returns @var{exp1} if @var{const_exp}, which is an
13093 integer constant expression, is nonzero. Otherwise it returns @var{exp2}.
13095 This built-in function is analogous to the @samp{? :} operator in C,
13096 except that the expression returned has its type unaltered by promotion
13097 rules. Also, the built-in function does not evaluate the expression
13098 that is not chosen. For example, if @var{const_exp} evaluates to @code{true},
13099 @var{exp2} is not evaluated even if it has side effects.
13101 This built-in function can return an lvalue if the chosen argument is an
13104 If @var{exp1} is returned, the return type is the same as @var{exp1}'s
13105 type. Similarly, if @var{exp2} is returned, its return type is the same
13112 __builtin_choose_expr ( \
13113 __builtin_types_compatible_p (typeof (x), double), \
13115 __builtin_choose_expr ( \
13116 __builtin_types_compatible_p (typeof (x), float), \
13118 /* @r{The void expression results in a compile-time error} \
13119 @r{when assigning the result to something.} */ \
13123 @emph{Note:} This construct is only available for C@. Furthermore, the
13124 unused expression (@var{exp1} or @var{exp2} depending on the value of
13125 @var{const_exp}) may still generate syntax errors. This may change in
13130 @deftypefn {Built-in Function} @var{type} __builtin_tgmath (@var{functions}, @var{arguments})
13132 The built-in function @code{__builtin_tgmath}, available only for C
13133 and Objective-C, calls a function determined according to the rules of
13134 @code{<tgmath.h>} macros. It is intended to be used in
13135 implementations of that header, so that expansions of macros from that
13136 header only expand each of their arguments once, to avoid problems
13137 when calls to such macros are nested inside the arguments of other
13138 calls to such macros; in addition, it results in better diagnostics
13139 for invalid calls to @code{<tgmath.h>} macros than implementations
13140 using other GNU C language features. For example, the @code{pow}
13141 type-generic macro might be defined as:
13144 #define pow(a, b) __builtin_tgmath (powf, pow, powl, \
13145 cpowf, cpow, cpowl, a, b)
13148 The arguments to @code{__builtin_tgmath} are at least two pointers to
13149 functions, followed by the arguments to the type-generic macro (which
13150 will be passed as arguments to the selected function). All the
13151 pointers to functions must be pointers to prototyped functions, none
13152 of which may have variable arguments, and all of which must have the
13153 same number of parameters; the number of parameters of the first
13154 function determines how many arguments to @code{__builtin_tgmath} are
13155 interpreted as function pointers, and how many as the arguments to the
13158 The types of the specified functions must all be different, but
13159 related to each other in the same way as a set of functions that may
13160 be selected between by a macro in @code{<tgmath.h>}. This means that
13161 the functions are parameterized by a floating-point type @var{t},
13162 different for each such function. The function return types may all
13163 be the same type, or they may be @var{t} for each function, or they
13164 may be the real type corresponding to @var{t} for each function (if
13165 some of the types @var{t} are complex). Likewise, for each parameter
13166 position, the type of the parameter in that position may always be the
13167 same type, or may be @var{t} for each function (this case must apply
13168 for at least one parameter position), or may be the real type
13169 corresponding to @var{t} for each function.
13171 The standard rules for @code{<tgmath.h>} macros are used to find a
13172 common type @var{u} from the types of the arguments for parameters
13173 whose types vary between the functions; complex integer types (a GNU
13174 extension) are treated like @code{_Complex double} for this purpose
13175 (or @code{_Complex _Float64} if all the function return types are the
13176 same @code{_Float@var{n}} or @code{_Float@var{n}x} type).
13177 If the function return types vary, or are all the same integer type,
13178 the function called is the one for which @var{t} is @var{u}, and it is
13179 an error if there is no such function. If the function return types
13180 are all the same floating-point type, the type-generic macro is taken
13181 to be one of those from TS 18661 that rounds the result to a narrower
13182 type; if there is a function for which @var{t} is @var{u}, it is
13183 called, and otherwise the first function, if any, for which @var{t}
13184 has at least the range and precision of @var{u} is called, and it is
13185 an error if there is no such function.
13189 @deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag})
13191 The built-in function @code{__builtin_complex} is provided for use in
13192 implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
13193 @code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
13194 real binary floating-point type, and the result has the corresponding
13195 complex type with real and imaginary parts @var{real} and @var{imag}.
13196 Unlike @samp{@var{real} + I * @var{imag}}, this works even when
13197 infinities, NaNs and negative zeros are involved.
13201 @deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
13202 You can use the built-in function @code{__builtin_constant_p} to
13203 determine if a value is known to be constant at compile time and hence
13204 that GCC can perform constant-folding on expressions involving that
13205 value. The argument of the function is the value to test. The function
13206 returns the integer 1 if the argument is known to be a compile-time
13207 constant and 0 if it is not known to be a compile-time constant. A
13208 return of 0 does not indicate that the value is @emph{not} a constant,
13209 but merely that GCC cannot prove it is a constant with the specified
13210 value of the @option{-O} option.
13212 You typically use this function in an embedded application where
13213 memory is a critical resource. If you have some complex calculation,
13214 you may want it to be folded if it involves constants, but need to call
13215 a function if it does not. For example:
13218 #define Scale_Value(X) \
13219 (__builtin_constant_p (X) \
13220 ? ((X) * SCALE + OFFSET) : Scale (X))
13223 You may use this built-in function in either a macro or an inline
13224 function. However, if you use it in an inlined function and pass an
13225 argument of the function as the argument to the built-in, GCC
13226 never returns 1 when you call the inline function with a string constant
13227 or compound literal (@pxref{Compound Literals}) and does not return 1
13228 when you pass a constant numeric value to the inline function unless you
13229 specify the @option{-O} option.
13231 You may also use @code{__builtin_constant_p} in initializers for static
13232 data. For instance, you can write
13235 static const int table[] = @{
13236 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
13242 This is an acceptable initializer even if @var{EXPRESSION} is not a
13243 constant expression, including the case where
13244 @code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be
13245 folded to a constant but @var{EXPRESSION} contains operands that are
13246 not otherwise permitted in a static initializer (for example,
13247 @code{0 && foo ()}). GCC must be more conservative about evaluating the
13248 built-in in this case, because it has no opportunity to perform
13252 @deftypefn {Built-in Function} bool __builtin_is_constant_evaluated (void)
13253 The @code{__builtin_is_constant_evaluated} function is available only
13254 in C++. The built-in is intended to be used by implementations of
13255 the @code{std::is_constant_evaluated} C++ function. Programs should make
13256 use of the latter function rather than invoking the built-in directly.
13258 The main use case of the built-in is to determine whether a @code{constexpr}
13259 function is being called in a @code{constexpr} context. A call to
13260 the function evaluates to a core constant expression with the value
13261 @code{true} if and only if it occurs within the evaluation of an expression
13262 or conversion that is manifestly constant-evaluated as defined in the C++
13263 standard. Manifestly constant-evaluated contexts include constant-expressions,
13264 the conditions of @code{constexpr if} statements, constraint-expressions, and
13265 initializers of variables usable in constant expressions. For more details
13266 refer to the latest revision of the C++ standard.
13269 @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
13270 @opindex fprofile-arcs
13271 You may use @code{__builtin_expect} to provide the compiler with
13272 branch prediction information. In general, you should prefer to
13273 use actual profile feedback for this (@option{-fprofile-arcs}), as
13274 programmers are notoriously bad at predicting how their programs
13275 actually perform. However, there are applications in which this
13276 data is hard to collect.
13278 The return value is the value of @var{exp}, which should be an integral
13279 expression. The semantics of the built-in are that it is expected that
13280 @var{exp} == @var{c}. For example:
13283 if (__builtin_expect (x, 0))
13288 indicates that we do not expect to call @code{foo}, since
13289 we expect @code{x} to be zero. Since you are limited to integral
13290 expressions for @var{exp}, you should use constructions such as
13293 if (__builtin_expect (ptr != NULL, 1))
13298 when testing pointer or floating-point values.
13300 For the purposes of branch prediction optimizations, the probability that
13301 a @code{__builtin_expect} expression is @code{true} is controlled by GCC's
13302 @code{builtin-expect-probability} parameter, which defaults to 90%.
13304 You can also use @code{__builtin_expect_with_probability} to explicitly
13305 assign a probability value to individual expressions. If the built-in
13306 is used in a loop construct, the provided probability will influence
13307 the expected number of iterations made by loop optimizations.
13310 @deftypefn {Built-in Function} long __builtin_expect_with_probability
13311 (long @var{exp}, long @var{c}, double @var{probability})
13313 This function has the same semantics as @code{__builtin_expect},
13314 but the caller provides the expected probability that @var{exp} == @var{c}.
13315 The last argument, @var{probability}, is a floating-point value in the
13316 range 0.0 to 1.0, inclusive. The @var{probability} argument must be
13317 constant floating-point expression.
13320 @deftypefn {Built-in Function} void __builtin_trap (void)
13321 This function causes the program to exit abnormally. GCC implements
13322 this function by using a target-dependent mechanism (such as
13323 intentionally executing an illegal instruction) or by calling
13324 @code{abort}. The mechanism used may vary from release to release so
13325 you should not rely on any particular implementation.
13328 @deftypefn {Built-in Function} void __builtin_unreachable (void)
13329 If control flow reaches the point of the @code{__builtin_unreachable},
13330 the program is undefined. It is useful in situations where the
13331 compiler cannot deduce the unreachability of the code.
13333 One such case is immediately following an @code{asm} statement that
13334 either never terminates, or one that transfers control elsewhere
13335 and never returns. In this example, without the
13336 @code{__builtin_unreachable}, GCC issues a warning that control
13337 reaches the end of a non-void function. It also generates code
13338 to return after the @code{asm}.
13341 int f (int c, int v)
13349 asm("jmp error_handler");
13350 __builtin_unreachable ();
13356 Because the @code{asm} statement unconditionally transfers control out
13357 of the function, control never reaches the end of the function
13358 body. The @code{__builtin_unreachable} is in fact unreachable and
13359 communicates this fact to the compiler.
13361 Another use for @code{__builtin_unreachable} is following a call a
13362 function that never returns but that is not declared
13363 @code{__attribute__((noreturn))}, as in this example:
13366 void function_that_never_returns (void);
13376 function_that_never_returns ();
13377 __builtin_unreachable ();
13384 @deftypefn {Built-in Function} {void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)
13385 This function returns its first argument, and allows the compiler
13386 to assume that the returned pointer is at least @var{align} bytes
13387 aligned. This built-in can have either two or three arguments,
13388 if it has three, the third argument should have integer type, and
13389 if it is nonzero means misalignment offset. For example:
13392 void *x = __builtin_assume_aligned (arg, 16);
13396 means that the compiler can assume @code{x}, set to @code{arg}, is at least
13397 16-byte aligned, while:
13400 void *x = __builtin_assume_aligned (arg, 32, 8);
13404 means that the compiler can assume for @code{x}, set to @code{arg}, that
13405 @code{(char *) x - 8} is 32-byte aligned.
13408 @deftypefn {Built-in Function} int __builtin_LINE ()
13409 This function is the equivalent of the preprocessor @code{__LINE__}
13410 macro and returns a constant integer expression that evaluates to
13411 the line number of the invocation of the built-in. When used as a C++
13412 default argument for a function @var{F}, it returns the line number
13413 of the call to @var{F}.
13416 @deftypefn {Built-in Function} {const char *} __builtin_FUNCTION ()
13417 This function is the equivalent of the @code{__FUNCTION__} symbol
13418 and returns an address constant pointing to the name of the function
13419 from which the built-in was invoked, or the empty string if
13420 the invocation is not at function scope. When used as a C++ default
13421 argument for a function @var{F}, it returns the name of @var{F}'s
13422 caller or the empty string if the call was not made at function
13426 @deftypefn {Built-in Function} {const char *} __builtin_FILE ()
13427 This function is the equivalent of the preprocessor @code{__FILE__}
13428 macro and returns an address constant pointing to the file name
13429 containing the invocation of the built-in, or the empty string if
13430 the invocation is not at function scope. When used as a C++ default
13431 argument for a function @var{F}, it returns the file name of the call
13432 to @var{F} or the empty string if the call was not made at function
13435 For example, in the following, each call to function @code{foo} will
13436 print a line similar to @code{"file.c:123: foo: message"} with the name
13437 of the file and the line number of the @code{printf} call, the name of
13438 the function @code{foo}, followed by the word @code{message}.
13442 function (const char *func = __builtin_FUNCTION ())
13449 printf ("%s:%i: %s: message\n", file (), line (), function ());
13455 @deftypefn {Built-in Function} void __builtin___clear_cache (void *@var{begin}, void *@var{end})
13456 This function is used to flush the processor's instruction cache for
13457 the region of memory between @var{begin} inclusive and @var{end}
13458 exclusive. Some targets require that the instruction cache be
13459 flushed, after modifying memory containing code, in order to obtain
13460 deterministic behavior.
13462 If the target does not require instruction cache flushes,
13463 @code{__builtin___clear_cache} has no effect. Otherwise either
13464 instructions are emitted in-line to clear the instruction cache or a
13465 call to the @code{__clear_cache} function in libgcc is made.
13468 @deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...)
13469 This function is used to minimize cache-miss latency by moving data into
13470 a cache before it is accessed.
13471 You can insert calls to @code{__builtin_prefetch} into code for which
13472 you know addresses of data in memory that is likely to be accessed soon.
13473 If the target supports them, data prefetch instructions are generated.
13474 If the prefetch is done early enough before the access then the data will
13475 be in the cache by the time it is accessed.
13477 The value of @var{addr} is the address of the memory to prefetch.
13478 There are two optional arguments, @var{rw} and @var{locality}.
13479 The value of @var{rw} is a compile-time constant one or zero; one
13480 means that the prefetch is preparing for a write to the memory address
13481 and zero, the default, means that the prefetch is preparing for a read.
13482 The value @var{locality} must be a compile-time constant integer between
13483 zero and three. A value of zero means that the data has no temporal
13484 locality, so it need not be left in the cache after the access. A value
13485 of three means that the data has a high degree of temporal locality and
13486 should be left in all levels of cache possible. Values of one and two
13487 mean, respectively, a low or moderate degree of temporal locality. The
13491 for (i = 0; i < n; i++)
13493 a[i] = a[i] + b[i];
13494 __builtin_prefetch (&a[i+j], 1, 1);
13495 __builtin_prefetch (&b[i+j], 0, 1);
13500 Data prefetch does not generate faults if @var{addr} is invalid, but
13501 the address expression itself must be valid. For example, a prefetch
13502 of @code{p->next} does not fault if @code{p->next} is not a valid
13503 address, but evaluation faults if @code{p} is not a valid address.
13505 If the target does not support data prefetch, the address expression
13506 is evaluated if it includes side effects but no other code is generated
13507 and GCC does not issue a warning.
13510 @deftypefn {Built-in Function}{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
13511 Returns the size of an object pointed to by @var{ptr}. @xref{Object Size
13512 Checking}, for a detailed description of the function.
13515 @deftypefn {Built-in Function} double __builtin_huge_val (void)
13516 Returns a positive infinity, if supported by the floating-point format,
13517 else @code{DBL_MAX}. This function is suitable for implementing the
13518 ISO C macro @code{HUGE_VAL}.
13521 @deftypefn {Built-in Function} float __builtin_huge_valf (void)
13522 Similar to @code{__builtin_huge_val}, except the return type is @code{float}.
13525 @deftypefn {Built-in Function} {long double} __builtin_huge_vall (void)
13526 Similar to @code{__builtin_huge_val}, except the return
13527 type is @code{long double}.
13530 @deftypefn {Built-in Function} _Float@var{n} __builtin_huge_valf@var{n} (void)
13531 Similar to @code{__builtin_huge_val}, except the return type is
13532 @code{_Float@var{n}}.
13535 @deftypefn {Built-in Function} _Float@var{n}x __builtin_huge_valf@var{n}x (void)
13536 Similar to @code{__builtin_huge_val}, except the return type is
13537 @code{_Float@var{n}x}.
13540 @deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...)
13541 This built-in implements the C99 fpclassify functionality. The first
13542 five int arguments should be the target library's notion of the
13543 possible FP classes and are used for return values. They must be
13544 constant values and they must appear in this order: @code{FP_NAN},
13545 @code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and
13546 @code{FP_ZERO}. The ellipsis is for exactly one floating-point value
13547 to classify. GCC treats the last argument as type-generic, which
13548 means it does not do default promotion from float to double.
13551 @deftypefn {Built-in Function} double __builtin_inf (void)
13552 Similar to @code{__builtin_huge_val}, except a warning is generated
13553 if the target floating-point format does not support infinities.
13556 @deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void)
13557 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}.
13560 @deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void)
13561 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}.
13564 @deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void)
13565 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}.
13568 @deftypefn {Built-in Function} float __builtin_inff (void)
13569 Similar to @code{__builtin_inf}, except the return type is @code{float}.
13570 This function is suitable for implementing the ISO C99 macro @code{INFINITY}.
13573 @deftypefn {Built-in Function} {long double} __builtin_infl (void)
13574 Similar to @code{__builtin_inf}, except the return
13575 type is @code{long double}.
13578 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n} (void)
13579 Similar to @code{__builtin_inf}, except the return
13580 type is @code{_Float@var{n}}.
13583 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n}x (void)
13584 Similar to @code{__builtin_inf}, except the return
13585 type is @code{_Float@var{n}x}.
13588 @deftypefn {Built-in Function} int __builtin_isinf_sign (...)
13589 Similar to @code{isinf}, except the return value is -1 for
13590 an argument of @code{-Inf} and 1 for an argument of @code{+Inf}.
13591 Note while the parameter list is an
13592 ellipsis, this function only accepts exactly one floating-point
13593 argument. GCC treats this parameter as type-generic, which means it
13594 does not do default promotion from float to double.
13597 @deftypefn {Built-in Function} double __builtin_nan (const char *str)
13598 This is an implementation of the ISO C99 function @code{nan}.
13600 Since ISO C99 defines this function in terms of @code{strtod}, which we
13601 do not implement, a description of the parsing is in order. The string
13602 is parsed as by @code{strtol}; that is, the base is recognized by
13603 leading @samp{0} or @samp{0x} prefixes. The number parsed is placed
13604 in the significand such that the least significant bit of the number
13605 is at the least significant bit of the significand. The number is
13606 truncated to fit the significand field provided. The significand is
13607 forced to be a quiet NaN@.
13609 This function, if given a string literal all of which would have been
13610 consumed by @code{strtol}, is evaluated early enough that it is considered a
13611 compile-time constant.
13614 @deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str)
13615 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}.
13618 @deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str)
13619 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}.
13622 @deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str)
13623 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}.
13626 @deftypefn {Built-in Function} float __builtin_nanf (const char *str)
13627 Similar to @code{__builtin_nan}, except the return type is @code{float}.
13630 @deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str)
13631 Similar to @code{__builtin_nan}, except the return type is @code{long double}.
13634 @deftypefn {Built-in Function} _Float@var{n} __builtin_nanf@var{n} (const char *str)
13635 Similar to @code{__builtin_nan}, except the return type is
13636 @code{_Float@var{n}}.
13639 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nanf@var{n}x (const char *str)
13640 Similar to @code{__builtin_nan}, except the return type is
13641 @code{_Float@var{n}x}.
13644 @deftypefn {Built-in Function} double __builtin_nans (const char *str)
13645 Similar to @code{__builtin_nan}, except the significand is forced
13646 to be a signaling NaN@. The @code{nans} function is proposed by
13647 @uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}.
13650 @deftypefn {Built-in Function} float __builtin_nansf (const char *str)
13651 Similar to @code{__builtin_nans}, except the return type is @code{float}.
13654 @deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str)
13655 Similar to @code{__builtin_nans}, except the return type is @code{long double}.
13658 @deftypefn {Built-in Function} _Float@var{n} __builtin_nansf@var{n} (const char *str)
13659 Similar to @code{__builtin_nans}, except the return type is
13660 @code{_Float@var{n}}.
13663 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nansf@var{n}x (const char *str)
13664 Similar to @code{__builtin_nans}, except the return type is
13665 @code{_Float@var{n}x}.
13668 @deftypefn {Built-in Function} int __builtin_ffs (int x)
13669 Returns one plus the index of the least significant 1-bit of @var{x}, or
13670 if @var{x} is zero, returns zero.
13673 @deftypefn {Built-in Function} int __builtin_clz (unsigned int x)
13674 Returns the number of leading 0-bits in @var{x}, starting at the most
13675 significant bit position. If @var{x} is 0, the result is undefined.
13678 @deftypefn {Built-in Function} int __builtin_ctz (unsigned int x)
13679 Returns the number of trailing 0-bits in @var{x}, starting at the least
13680 significant bit position. If @var{x} is 0, the result is undefined.
13683 @deftypefn {Built-in Function} int __builtin_clrsb (int x)
13684 Returns the number of leading redundant sign bits in @var{x}, i.e.@: the
13685 number of bits following the most significant bit that are identical
13686 to it. There are no special cases for 0 or other values.
13689 @deftypefn {Built-in Function} int __builtin_popcount (unsigned int x)
13690 Returns the number of 1-bits in @var{x}.
13693 @deftypefn {Built-in Function} int __builtin_parity (unsigned int x)
13694 Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x}
13698 @deftypefn {Built-in Function} int __builtin_ffsl (long)
13699 Similar to @code{__builtin_ffs}, except the argument type is
13703 @deftypefn {Built-in Function} int __builtin_clzl (unsigned long)
13704 Similar to @code{__builtin_clz}, except the argument type is
13705 @code{unsigned long}.
13708 @deftypefn {Built-in Function} int __builtin_ctzl (unsigned long)
13709 Similar to @code{__builtin_ctz}, except the argument type is
13710 @code{unsigned long}.
13713 @deftypefn {Built-in Function} int __builtin_clrsbl (long)
13714 Similar to @code{__builtin_clrsb}, except the argument type is
13718 @deftypefn {Built-in Function} int __builtin_popcountl (unsigned long)
13719 Similar to @code{__builtin_popcount}, except the argument type is
13720 @code{unsigned long}.
13723 @deftypefn {Built-in Function} int __builtin_parityl (unsigned long)
13724 Similar to @code{__builtin_parity}, except the argument type is
13725 @code{unsigned long}.
13728 @deftypefn {Built-in Function} int __builtin_ffsll (long long)
13729 Similar to @code{__builtin_ffs}, except the argument type is
13733 @deftypefn {Built-in Function} int __builtin_clzll (unsigned long long)
13734 Similar to @code{__builtin_clz}, except the argument type is
13735 @code{unsigned long long}.
13738 @deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long)
13739 Similar to @code{__builtin_ctz}, except the argument type is
13740 @code{unsigned long long}.
13743 @deftypefn {Built-in Function} int __builtin_clrsbll (long long)
13744 Similar to @code{__builtin_clrsb}, except the argument type is
13748 @deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long)
13749 Similar to @code{__builtin_popcount}, except the argument type is
13750 @code{unsigned long long}.
13753 @deftypefn {Built-in Function} int __builtin_parityll (unsigned long long)
13754 Similar to @code{__builtin_parity}, except the argument type is
13755 @code{unsigned long long}.
13758 @deftypefn {Built-in Function} double __builtin_powi (double, int)
13759 Returns the first argument raised to the power of the second. Unlike the
13760 @code{pow} function no guarantees about precision and rounding are made.
13763 @deftypefn {Built-in Function} float __builtin_powif (float, int)
13764 Similar to @code{__builtin_powi}, except the argument and return types
13768 @deftypefn {Built-in Function} {long double} __builtin_powil (long double, int)
13769 Similar to @code{__builtin_powi}, except the argument and return types
13770 are @code{long double}.
13773 @deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x)
13774 Returns @var{x} with the order of the bytes reversed; for example,
13775 @code{0xaabb} becomes @code{0xbbaa}. Byte here always means
13779 @deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x)
13780 Similar to @code{__builtin_bswap16}, except the argument and return types
13784 @deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x)
13785 Similar to @code{__builtin_bswap32}, except the argument and return types
13789 @deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x)
13790 On targets where the user visible pointer size is smaller than the size
13791 of an actual hardware address this function returns the extended user
13792 pointer. Targets where this is true included ILP32 mode on x86_64 or
13793 Aarch64. This function is mainly useful when writing inline assembly
13797 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_id (int x)
13798 Returns the openacc gang, worker or vector id depending on whether @var{x} is
13802 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_size (int x)
13803 Returns the openacc gang, worker or vector size depending on whether @var{x} is
13807 @node Target Builtins
13808 @section Built-in Functions Specific to Particular Target Machines
13810 On some target machines, GCC supports many built-in functions specific
13811 to those machines. Generally these generate calls to specific machine
13812 instructions, but allow the compiler to schedule those calls.
13815 * AArch64 Built-in Functions::
13816 * Alpha Built-in Functions::
13817 * Altera Nios II Built-in Functions::
13818 * ARC Built-in Functions::
13819 * ARC SIMD Built-in Functions::
13820 * ARM iWMMXt Built-in Functions::
13821 * ARM C Language Extensions (ACLE)::
13822 * ARM Floating Point Status and Control Intrinsics::
13823 * ARM ARMv8-M Security Extensions::
13824 * AVR Built-in Functions::
13825 * Blackfin Built-in Functions::
13826 * BPF Built-in Functions::
13827 * BPF Kernel Helpers::
13828 * FR-V Built-in Functions::
13829 * MIPS DSP Built-in Functions::
13830 * MIPS Paired-Single Support::
13831 * MIPS Loongson Built-in Functions::
13832 * MIPS SIMD Architecture (MSA) Support::
13833 * Other MIPS Built-in Functions::
13834 * MSP430 Built-in Functions::
13835 * NDS32 Built-in Functions::
13836 * picoChip Built-in Functions::
13837 * Basic PowerPC Built-in Functions::
13838 * PowerPC AltiVec/VSX Built-in Functions::
13839 * PowerPC Hardware Transactional Memory Built-in Functions::
13840 * PowerPC Atomic Memory Operation Functions::
13841 * RX Built-in Functions::
13842 * S/390 System z Built-in Functions::
13843 * SH Built-in Functions::
13844 * SPARC VIS Built-in Functions::
13845 * TI C6X Built-in Functions::
13846 * TILE-Gx Built-in Functions::
13847 * TILEPro Built-in Functions::
13848 * x86 Built-in Functions::
13849 * x86 transactional memory intrinsics::
13850 * x86 control-flow protection intrinsics::
13853 @node AArch64 Built-in Functions
13854 @subsection AArch64 Built-in Functions
13856 These built-in functions are available for the AArch64 family of
13859 unsigned int __builtin_aarch64_get_fpcr ()
13860 void __builtin_aarch64_set_fpcr (unsigned int)
13861 unsigned int __builtin_aarch64_get_fpsr ()
13862 void __builtin_aarch64_set_fpsr (unsigned int)
13865 @node Alpha Built-in Functions
13866 @subsection Alpha Built-in Functions
13868 These built-in functions are available for the Alpha family of
13869 processors, depending on the command-line switches used.
13871 The following built-in functions are always available. They
13872 all generate the machine instruction that is part of the name.
13875 long __builtin_alpha_implver (void)
13876 long __builtin_alpha_rpcc (void)
13877 long __builtin_alpha_amask (long)
13878 long __builtin_alpha_cmpbge (long, long)
13879 long __builtin_alpha_extbl (long, long)
13880 long __builtin_alpha_extwl (long, long)
13881 long __builtin_alpha_extll (long, long)
13882 long __builtin_alpha_extql (long, long)
13883 long __builtin_alpha_extwh (long, long)
13884 long __builtin_alpha_extlh (long, long)
13885 long __builtin_alpha_extqh (long, long)
13886 long __builtin_alpha_insbl (long, long)
13887 long __builtin_alpha_inswl (long, long)
13888 long __builtin_alpha_insll (long, long)
13889 long __builtin_alpha_insql (long, long)
13890 long __builtin_alpha_inswh (long, long)
13891 long __builtin_alpha_inslh (long, long)
13892 long __builtin_alpha_insqh (long, long)
13893 long __builtin_alpha_mskbl (long, long)
13894 long __builtin_alpha_mskwl (long, long)
13895 long __builtin_alpha_mskll (long, long)
13896 long __builtin_alpha_mskql (long, long)
13897 long __builtin_alpha_mskwh (long, long)
13898 long __builtin_alpha_msklh (long, long)
13899 long __builtin_alpha_mskqh (long, long)
13900 long __builtin_alpha_umulh (long, long)
13901 long __builtin_alpha_zap (long, long)
13902 long __builtin_alpha_zapnot (long, long)
13905 The following built-in functions are always with @option{-mmax}
13906 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
13907 later. They all generate the machine instruction that is part
13911 long __builtin_alpha_pklb (long)
13912 long __builtin_alpha_pkwb (long)
13913 long __builtin_alpha_unpkbl (long)
13914 long __builtin_alpha_unpkbw (long)
13915 long __builtin_alpha_minub8 (long, long)
13916 long __builtin_alpha_minsb8 (long, long)
13917 long __builtin_alpha_minuw4 (long, long)
13918 long __builtin_alpha_minsw4 (long, long)
13919 long __builtin_alpha_maxub8 (long, long)
13920 long __builtin_alpha_maxsb8 (long, long)
13921 long __builtin_alpha_maxuw4 (long, long)
13922 long __builtin_alpha_maxsw4 (long, long)
13923 long __builtin_alpha_perr (long, long)
13926 The following built-in functions are always with @option{-mcix}
13927 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
13928 later. They all generate the machine instruction that is part
13932 long __builtin_alpha_cttz (long)
13933 long __builtin_alpha_ctlz (long)
13934 long __builtin_alpha_ctpop (long)
13937 The following built-in functions are available on systems that use the OSF/1
13938 PALcode. Normally they invoke the @code{rduniq} and @code{wruniq}
13939 PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
13940 @code{rdval} and @code{wrval}.
13943 void *__builtin_thread_pointer (void)
13944 void __builtin_set_thread_pointer (void *)
13947 @node Altera Nios II Built-in Functions
13948 @subsection Altera Nios II Built-in Functions
13950 These built-in functions are available for the Altera Nios II
13951 family of processors.
13953 The following built-in functions are always available. They
13954 all generate the machine instruction that is part of the name.
13957 int __builtin_ldbio (volatile const void *)
13958 int __builtin_ldbuio (volatile const void *)
13959 int __builtin_ldhio (volatile const void *)
13960 int __builtin_ldhuio (volatile const void *)
13961 int __builtin_ldwio (volatile const void *)
13962 void __builtin_stbio (volatile void *, int)
13963 void __builtin_sthio (volatile void *, int)
13964 void __builtin_stwio (volatile void *, int)
13965 void __builtin_sync (void)
13966 int __builtin_rdctl (int)
13967 int __builtin_rdprs (int, int)
13968 void __builtin_wrctl (int, int)
13969 void __builtin_flushd (volatile void *)
13970 void __builtin_flushda (volatile void *)
13971 int __builtin_wrpie (int);
13972 void __builtin_eni (int);
13973 int __builtin_ldex (volatile const void *)
13974 int __builtin_stex (volatile void *, int)
13975 int __builtin_ldsex (volatile const void *)
13976 int __builtin_stsex (volatile void *, int)
13979 The following built-in functions are always available. They
13980 all generate a Nios II Custom Instruction. The name of the
13981 function represents the types that the function takes and
13982 returns. The letter before the @code{n} is the return type
13983 or void if absent. The @code{n} represents the first parameter
13984 to all the custom instructions, the custom instruction number.
13985 The two letters after the @code{n} represent the up to two
13986 parameters to the function.
13988 The letters represent the following data types:
13991 @code{void} for return type and no parameter for parameter types.
13994 @code{int} for return type and parameter type
13997 @code{float} for return type and parameter type
14000 @code{void *} for return type and parameter type
14004 And the function names are:
14006 void __builtin_custom_n (void)
14007 void __builtin_custom_ni (int)
14008 void __builtin_custom_nf (float)
14009 void __builtin_custom_np (void *)
14010 void __builtin_custom_nii (int, int)
14011 void __builtin_custom_nif (int, float)
14012 void __builtin_custom_nip (int, void *)
14013 void __builtin_custom_nfi (float, int)
14014 void __builtin_custom_nff (float, float)
14015 void __builtin_custom_nfp (float, void *)
14016 void __builtin_custom_npi (void *, int)
14017 void __builtin_custom_npf (void *, float)
14018 void __builtin_custom_npp (void *, void *)
14019 int __builtin_custom_in (void)
14020 int __builtin_custom_ini (int)
14021 int __builtin_custom_inf (float)
14022 int __builtin_custom_inp (void *)
14023 int __builtin_custom_inii (int, int)
14024 int __builtin_custom_inif (int, float)
14025 int __builtin_custom_inip (int, void *)
14026 int __builtin_custom_infi (float, int)
14027 int __builtin_custom_inff (float, float)
14028 int __builtin_custom_infp (float, void *)
14029 int __builtin_custom_inpi (void *, int)
14030 int __builtin_custom_inpf (void *, float)
14031 int __builtin_custom_inpp (void *, void *)
14032 float __builtin_custom_fn (void)
14033 float __builtin_custom_fni (int)
14034 float __builtin_custom_fnf (float)
14035 float __builtin_custom_fnp (void *)
14036 float __builtin_custom_fnii (int, int)
14037 float __builtin_custom_fnif (int, float)
14038 float __builtin_custom_fnip (int, void *)
14039 float __builtin_custom_fnfi (float, int)
14040 float __builtin_custom_fnff (float, float)
14041 float __builtin_custom_fnfp (float, void *)
14042 float __builtin_custom_fnpi (void *, int)
14043 float __builtin_custom_fnpf (void *, float)
14044 float __builtin_custom_fnpp (void *, void *)
14045 void * __builtin_custom_pn (void)
14046 void * __builtin_custom_pni (int)
14047 void * __builtin_custom_pnf (float)
14048 void * __builtin_custom_pnp (void *)
14049 void * __builtin_custom_pnii (int, int)
14050 void * __builtin_custom_pnif (int, float)
14051 void * __builtin_custom_pnip (int, void *)
14052 void * __builtin_custom_pnfi (float, int)
14053 void * __builtin_custom_pnff (float, float)
14054 void * __builtin_custom_pnfp (float, void *)
14055 void * __builtin_custom_pnpi (void *, int)
14056 void * __builtin_custom_pnpf (void *, float)
14057 void * __builtin_custom_pnpp (void *, void *)
14060 @node ARC Built-in Functions
14061 @subsection ARC Built-in Functions
14063 The following built-in functions are provided for ARC targets. The
14064 built-ins generate the corresponding assembly instructions. In the
14065 examples given below, the generated code often requires an operand or
14066 result to be in a register. Where necessary further code will be
14067 generated to ensure this is true, but for brevity this is not
14068 described in each case.
14070 @emph{Note:} Using a built-in to generate an instruction not supported
14071 by a target may cause problems. At present the compiler is not
14072 guaranteed to detect such misuse, and as a result an internal compiler
14073 error may be generated.
14075 @deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval})
14076 Return 1 if @var{val} is known to have the byte alignment given
14077 by @var{alignval}, otherwise return 0.
14078 Note that this is different from
14080 __alignof__(*(char *)@var{val}) >= alignval
14082 because __alignof__ sees only the type of the dereference, whereas
14083 __builtin_arc_align uses alignment information from the pointer
14084 as well as from the pointed-to type.
14085 The information available will depend on optimization level.
14088 @deftypefn {Built-in Function} void __builtin_arc_brk (void)
14095 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno})
14096 The operand is the number of a register to be read. Generates:
14098 mov @var{dest}, r@var{regno}
14100 where the value in @var{dest} will be the result returned from the
14104 @deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val})
14105 The first operand is the number of a register to be written, the
14106 second operand is a compile time constant to write into that
14107 register. Generates:
14109 mov r@var{regno}, @var{val}
14113 @deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b})
14114 Only available if either @option{-mcpu=ARC700} or @option{-meA} is set.
14117 divaw @var{dest}, @var{a}, @var{b}
14119 where the value in @var{dest} will be the result returned from the
14123 @deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a})
14130 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr})
14131 The operand, @var{auxv}, is the address of an auxiliary register and
14132 must be a compile time constant. Generates:
14134 lr @var{dest}, [@var{auxr}]
14136 Where the value in @var{dest} will be the result returned from the
14140 @deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b})
14141 Only available with @option{-mmul64}. Generates:
14143 mul64 @var{a}, @var{b}
14147 @deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b})
14148 Only available with @option{-mmul64}. Generates:
14150 mulu64 @var{a}, @var{b}
14154 @deftypefn {Built-in Function} void __builtin_arc_nop (void)
14161 @deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src})
14162 Only valid if the @samp{norm} instruction is available through the
14163 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
14166 norm @var{dest}, @var{src}
14168 Where the value in @var{dest} will be the result returned from the
14172 @deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src})
14173 Only valid if the @samp{normw} instruction is available through the
14174 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
14177 normw @var{dest}, @var{src}
14179 Where the value in @var{dest} will be the result returned from the
14183 @deftypefn {Built-in Function} void __builtin_arc_rtie (void)
14190 @deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a}
14197 @deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{auxr}, unsigned int @var{val})
14198 The first argument, @var{auxv}, is the address of an auxiliary
14199 register, the second argument, @var{val}, is a compile time constant
14200 to be written to the register. Generates:
14202 sr @var{auxr}, [@var{val}]
14206 @deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src})
14207 Only valid with @option{-mswap}. Generates:
14209 swap @var{dest}, @var{src}
14211 Where the value in @var{dest} will be the result returned from the
14215 @deftypefn {Built-in Function} void __builtin_arc_swi (void)
14222 @deftypefn {Built-in Function} void __builtin_arc_sync (void)
14223 Only available with @option{-mcpu=ARC700}. Generates:
14229 @deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c})
14230 Only available with @option{-mcpu=ARC700}. Generates:
14236 @deftypefn {Built-in Function} void __builtin_arc_unimp_s (void)
14237 Only available with @option{-mcpu=ARC700}. Generates:
14243 The instructions generated by the following builtins are not
14244 considered as candidates for scheduling. They are not moved around by
14245 the compiler during scheduling, and thus can be expected to appear
14246 where they are put in the C code:
14248 __builtin_arc_brk()
14249 __builtin_arc_core_read()
14250 __builtin_arc_core_write()
14251 __builtin_arc_flag()
14253 __builtin_arc_sleep()
14255 __builtin_arc_swi()
14258 @node ARC SIMD Built-in Functions
14259 @subsection ARC SIMD Built-in Functions
14261 SIMD builtins provided by the compiler can be used to generate the
14262 vector instructions. This section describes the available builtins
14263 and their usage in programs. With the @option{-msimd} option, the
14264 compiler provides 128-bit vector types, which can be specified using
14265 the @code{vector_size} attribute. The header file @file{arc-simd.h}
14266 can be included to use the following predefined types:
14268 typedef int __v4si __attribute__((vector_size(16)));
14269 typedef short __v8hi __attribute__((vector_size(16)));
14272 These types can be used to define 128-bit variables. The built-in
14273 functions listed in the following section can be used on these
14274 variables to generate the vector operations.
14276 For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file
14277 @file{arc-simd.h} also provides equivalent macros called
14278 @code{_@var{someinsn}} that can be used for programming ease and
14279 improved readability. The following macros for DMA control are also
14282 #define _setup_dma_in_channel_reg _vdiwr
14283 #define _setup_dma_out_channel_reg _vdowr
14286 The following is a complete list of all the SIMD built-ins provided
14287 for ARC, grouped by calling signature.
14289 The following take two @code{__v8hi} arguments and return a
14290 @code{__v8hi} result:
14292 __v8hi __builtin_arc_vaddaw (__v8hi, __v8hi)
14293 __v8hi __builtin_arc_vaddw (__v8hi, __v8hi)
14294 __v8hi __builtin_arc_vand (__v8hi, __v8hi)
14295 __v8hi __builtin_arc_vandaw (__v8hi, __v8hi)
14296 __v8hi __builtin_arc_vavb (__v8hi, __v8hi)
14297 __v8hi __builtin_arc_vavrb (__v8hi, __v8hi)
14298 __v8hi __builtin_arc_vbic (__v8hi, __v8hi)
14299 __v8hi __builtin_arc_vbicaw (__v8hi, __v8hi)
14300 __v8hi __builtin_arc_vdifaw (__v8hi, __v8hi)
14301 __v8hi __builtin_arc_vdifw (__v8hi, __v8hi)
14302 __v8hi __builtin_arc_veqw (__v8hi, __v8hi)
14303 __v8hi __builtin_arc_vh264f (__v8hi, __v8hi)
14304 __v8hi __builtin_arc_vh264ft (__v8hi, __v8hi)
14305 __v8hi __builtin_arc_vh264fw (__v8hi, __v8hi)
14306 __v8hi __builtin_arc_vlew (__v8hi, __v8hi)
14307 __v8hi __builtin_arc_vltw (__v8hi, __v8hi)
14308 __v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi)
14309 __v8hi __builtin_arc_vmaxw (__v8hi, __v8hi)
14310 __v8hi __builtin_arc_vminaw (__v8hi, __v8hi)
14311 __v8hi __builtin_arc_vminw (__v8hi, __v8hi)
14312 __v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi)
14313 __v8hi __builtin_arc_vmr1w (__v8hi, __v8hi)
14314 __v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi)
14315 __v8hi __builtin_arc_vmr2w (__v8hi, __v8hi)
14316 __v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi)
14317 __v8hi __builtin_arc_vmr3w (__v8hi, __v8hi)
14318 __v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi)
14319 __v8hi __builtin_arc_vmr4w (__v8hi, __v8hi)
14320 __v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi)
14321 __v8hi __builtin_arc_vmr5w (__v8hi, __v8hi)
14322 __v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi)
14323 __v8hi __builtin_arc_vmr6w (__v8hi, __v8hi)
14324 __v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi)
14325 __v8hi __builtin_arc_vmr7w (__v8hi, __v8hi)
14326 __v8hi __builtin_arc_vmrb (__v8hi, __v8hi)
14327 __v8hi __builtin_arc_vmulaw (__v8hi, __v8hi)
14328 __v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi)
14329 __v8hi __builtin_arc_vmulfw (__v8hi, __v8hi)
14330 __v8hi __builtin_arc_vmulw (__v8hi, __v8hi)
14331 __v8hi __builtin_arc_vnew (__v8hi, __v8hi)
14332 __v8hi __builtin_arc_vor (__v8hi, __v8hi)
14333 __v8hi __builtin_arc_vsubaw (__v8hi, __v8hi)
14334 __v8hi __builtin_arc_vsubw (__v8hi, __v8hi)
14335 __v8hi __builtin_arc_vsummw (__v8hi, __v8hi)
14336 __v8hi __builtin_arc_vvc1f (__v8hi, __v8hi)
14337 __v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi)
14338 __v8hi __builtin_arc_vxor (__v8hi, __v8hi)
14339 __v8hi __builtin_arc_vxoraw (__v8hi, __v8hi)
14342 The following take one @code{__v8hi} and one @code{int} argument and return a
14343 @code{__v8hi} result:
14346 __v8hi __builtin_arc_vbaddw (__v8hi, int)
14347 __v8hi __builtin_arc_vbmaxw (__v8hi, int)
14348 __v8hi __builtin_arc_vbminw (__v8hi, int)
14349 __v8hi __builtin_arc_vbmulaw (__v8hi, int)
14350 __v8hi __builtin_arc_vbmulfw (__v8hi, int)
14351 __v8hi __builtin_arc_vbmulw (__v8hi, int)
14352 __v8hi __builtin_arc_vbrsubw (__v8hi, int)
14353 __v8hi __builtin_arc_vbsubw (__v8hi, int)
14356 The following take one @code{__v8hi} argument and one @code{int} argument which
14357 must be a 3-bit compile time constant indicating a register number
14358 I0-I7. They return a @code{__v8hi} result.
14360 __v8hi __builtin_arc_vasrw (__v8hi, const int)
14361 __v8hi __builtin_arc_vsr8 (__v8hi, const int)
14362 __v8hi __builtin_arc_vsr8aw (__v8hi, const int)
14365 The following take one @code{__v8hi} argument and one @code{int}
14366 argument which must be a 6-bit compile time constant. They return a
14367 @code{__v8hi} result.
14369 __v8hi __builtin_arc_vasrpwbi (__v8hi, const int)
14370 __v8hi __builtin_arc_vasrrpwbi (__v8hi, const int)
14371 __v8hi __builtin_arc_vasrrwi (__v8hi, const int)
14372 __v8hi __builtin_arc_vasrsrwi (__v8hi, const int)
14373 __v8hi __builtin_arc_vasrwi (__v8hi, const int)
14374 __v8hi __builtin_arc_vsr8awi (__v8hi, const int)
14375 __v8hi __builtin_arc_vsr8i (__v8hi, const int)
14378 The following take one @code{__v8hi} argument and one @code{int} argument which
14379 must be a 8-bit compile time constant. They return a @code{__v8hi}
14382 __v8hi __builtin_arc_vd6tapf (__v8hi, const int)
14383 __v8hi __builtin_arc_vmvaw (__v8hi, const int)
14384 __v8hi __builtin_arc_vmvw (__v8hi, const int)
14385 __v8hi __builtin_arc_vmvzw (__v8hi, const int)
14388 The following take two @code{int} arguments, the second of which which
14389 must be a 8-bit compile time constant. They return a @code{__v8hi}
14392 __v8hi __builtin_arc_vmovaw (int, const int)
14393 __v8hi __builtin_arc_vmovw (int, const int)
14394 __v8hi __builtin_arc_vmovzw (int, const int)
14397 The following take a single @code{__v8hi} argument and return a
14398 @code{__v8hi} result:
14400 __v8hi __builtin_arc_vabsaw (__v8hi)
14401 __v8hi __builtin_arc_vabsw (__v8hi)
14402 __v8hi __builtin_arc_vaddsuw (__v8hi)
14403 __v8hi __builtin_arc_vexch1 (__v8hi)
14404 __v8hi __builtin_arc_vexch2 (__v8hi)
14405 __v8hi __builtin_arc_vexch4 (__v8hi)
14406 __v8hi __builtin_arc_vsignw (__v8hi)
14407 __v8hi __builtin_arc_vupbaw (__v8hi)
14408 __v8hi __builtin_arc_vupbw (__v8hi)
14409 __v8hi __builtin_arc_vupsbaw (__v8hi)
14410 __v8hi __builtin_arc_vupsbw (__v8hi)
14413 The following take two @code{int} arguments and return no result:
14415 void __builtin_arc_vdirun (int, int)
14416 void __builtin_arc_vdorun (int, int)
14419 The following take two @code{int} arguments and return no result. The
14420 first argument must a 3-bit compile time constant indicating one of
14421 the DR0-DR7 DMA setup channels:
14423 void __builtin_arc_vdiwr (const int, int)
14424 void __builtin_arc_vdowr (const int, int)
14427 The following take an @code{int} argument and return no result:
14429 void __builtin_arc_vendrec (int)
14430 void __builtin_arc_vrec (int)
14431 void __builtin_arc_vrecrun (int)
14432 void __builtin_arc_vrun (int)
14435 The following take a @code{__v8hi} argument and two @code{int}
14436 arguments and return a @code{__v8hi} result. The second argument must
14437 be a 3-bit compile time constants, indicating one the registers I0-I7,
14438 and the third argument must be an 8-bit compile time constant.
14440 @emph{Note:} Although the equivalent hardware instructions do not take
14441 an SIMD register as an operand, these builtins overwrite the relevant
14442 bits of the @code{__v8hi} register provided as the first argument with
14443 the value loaded from the @code{[Ib, u8]} location in the SDM.
14446 __v8hi __builtin_arc_vld32 (__v8hi, const int, const int)
14447 __v8hi __builtin_arc_vld32wh (__v8hi, const int, const int)
14448 __v8hi __builtin_arc_vld32wl (__v8hi, const int, const int)
14449 __v8hi __builtin_arc_vld64 (__v8hi, const int, const int)
14452 The following take two @code{int} arguments and return a @code{__v8hi}
14453 result. The first argument must be a 3-bit compile time constants,
14454 indicating one the registers I0-I7, and the second argument must be an
14455 8-bit compile time constant.
14458 __v8hi __builtin_arc_vld128 (const int, const int)
14459 __v8hi __builtin_arc_vld64w (const int, const int)
14462 The following take a @code{__v8hi} argument and two @code{int}
14463 arguments and return no result. The second argument must be a 3-bit
14464 compile time constants, indicating one the registers I0-I7, and the
14465 third argument must be an 8-bit compile time constant.
14468 void __builtin_arc_vst128 (__v8hi, const int, const int)
14469 void __builtin_arc_vst64 (__v8hi, const int, const int)
14472 The following take a @code{__v8hi} argument and three @code{int}
14473 arguments and return no result. The second argument must be a 3-bit
14474 compile-time constant, identifying the 16-bit sub-register to be
14475 stored, the third argument must be a 3-bit compile time constants,
14476 indicating one the registers I0-I7, and the fourth argument must be an
14477 8-bit compile time constant.
14480 void __builtin_arc_vst16_n (__v8hi, const int, const int, const int)
14481 void __builtin_arc_vst32_n (__v8hi, const int, const int, const int)
14484 @node ARM iWMMXt Built-in Functions
14485 @subsection ARM iWMMXt Built-in Functions
14487 These built-in functions are available for the ARM family of
14488 processors when the @option{-mcpu=iwmmxt} switch is used:
14491 typedef int v2si __attribute__ ((vector_size (8)));
14492 typedef short v4hi __attribute__ ((vector_size (8)));
14493 typedef char v8qi __attribute__ ((vector_size (8)));
14495 int __builtin_arm_getwcgr0 (void)
14496 void __builtin_arm_setwcgr0 (int)
14497 int __builtin_arm_getwcgr1 (void)
14498 void __builtin_arm_setwcgr1 (int)
14499 int __builtin_arm_getwcgr2 (void)
14500 void __builtin_arm_setwcgr2 (int)
14501 int __builtin_arm_getwcgr3 (void)
14502 void __builtin_arm_setwcgr3 (int)
14503 int __builtin_arm_textrmsb (v8qi, int)
14504 int __builtin_arm_textrmsh (v4hi, int)
14505 int __builtin_arm_textrmsw (v2si, int)
14506 int __builtin_arm_textrmub (v8qi, int)
14507 int __builtin_arm_textrmuh (v4hi, int)
14508 int __builtin_arm_textrmuw (v2si, int)
14509 v8qi __builtin_arm_tinsrb (v8qi, int, int)
14510 v4hi __builtin_arm_tinsrh (v4hi, int, int)
14511 v2si __builtin_arm_tinsrw (v2si, int, int)
14512 long long __builtin_arm_tmia (long long, int, int)
14513 long long __builtin_arm_tmiabb (long long, int, int)
14514 long long __builtin_arm_tmiabt (long long, int, int)
14515 long long __builtin_arm_tmiaph (long long, int, int)
14516 long long __builtin_arm_tmiatb (long long, int, int)
14517 long long __builtin_arm_tmiatt (long long, int, int)
14518 int __builtin_arm_tmovmskb (v8qi)
14519 int __builtin_arm_tmovmskh (v4hi)
14520 int __builtin_arm_tmovmskw (v2si)
14521 long long __builtin_arm_waccb (v8qi)
14522 long long __builtin_arm_wacch (v4hi)
14523 long long __builtin_arm_waccw (v2si)
14524 v8qi __builtin_arm_waddb (v8qi, v8qi)
14525 v8qi __builtin_arm_waddbss (v8qi, v8qi)
14526 v8qi __builtin_arm_waddbus (v8qi, v8qi)
14527 v4hi __builtin_arm_waddh (v4hi, v4hi)
14528 v4hi __builtin_arm_waddhss (v4hi, v4hi)
14529 v4hi __builtin_arm_waddhus (v4hi, v4hi)
14530 v2si __builtin_arm_waddw (v2si, v2si)
14531 v2si __builtin_arm_waddwss (v2si, v2si)
14532 v2si __builtin_arm_waddwus (v2si, v2si)
14533 v8qi __builtin_arm_walign (v8qi, v8qi, int)
14534 long long __builtin_arm_wand(long long, long long)
14535 long long __builtin_arm_wandn (long long, long long)
14536 v8qi __builtin_arm_wavg2b (v8qi, v8qi)
14537 v8qi __builtin_arm_wavg2br (v8qi, v8qi)
14538 v4hi __builtin_arm_wavg2h (v4hi, v4hi)
14539 v4hi __builtin_arm_wavg2hr (v4hi, v4hi)
14540 v8qi __builtin_arm_wcmpeqb (v8qi, v8qi)
14541 v4hi __builtin_arm_wcmpeqh (v4hi, v4hi)
14542 v2si __builtin_arm_wcmpeqw (v2si, v2si)
14543 v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi)
14544 v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi)
14545 v2si __builtin_arm_wcmpgtsw (v2si, v2si)
14546 v8qi __builtin_arm_wcmpgtub (v8qi, v8qi)
14547 v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi)
14548 v2si __builtin_arm_wcmpgtuw (v2si, v2si)
14549 long long __builtin_arm_wmacs (long long, v4hi, v4hi)
14550 long long __builtin_arm_wmacsz (v4hi, v4hi)
14551 long long __builtin_arm_wmacu (long long, v4hi, v4hi)
14552 long long __builtin_arm_wmacuz (v4hi, v4hi)
14553 v4hi __builtin_arm_wmadds (v4hi, v4hi)
14554 v4hi __builtin_arm_wmaddu (v4hi, v4hi)
14555 v8qi __builtin_arm_wmaxsb (v8qi, v8qi)
14556 v4hi __builtin_arm_wmaxsh (v4hi, v4hi)
14557 v2si __builtin_arm_wmaxsw (v2si, v2si)
14558 v8qi __builtin_arm_wmaxub (v8qi, v8qi)
14559 v4hi __builtin_arm_wmaxuh (v4hi, v4hi)
14560 v2si __builtin_arm_wmaxuw (v2si, v2si)
14561 v8qi __builtin_arm_wminsb (v8qi, v8qi)
14562 v4hi __builtin_arm_wminsh (v4hi, v4hi)
14563 v2si __builtin_arm_wminsw (v2si, v2si)
14564 v8qi __builtin_arm_wminub (v8qi, v8qi)
14565 v4hi __builtin_arm_wminuh (v4hi, v4hi)
14566 v2si __builtin_arm_wminuw (v2si, v2si)
14567 v4hi __builtin_arm_wmulsm (v4hi, v4hi)
14568 v4hi __builtin_arm_wmulul (v4hi, v4hi)
14569 v4hi __builtin_arm_wmulum (v4hi, v4hi)
14570 long long __builtin_arm_wor (long long, long long)
14571 v2si __builtin_arm_wpackdss (long long, long long)
14572 v2si __builtin_arm_wpackdus (long long, long long)
14573 v8qi __builtin_arm_wpackhss (v4hi, v4hi)
14574 v8qi __builtin_arm_wpackhus (v4hi, v4hi)
14575 v4hi __builtin_arm_wpackwss (v2si, v2si)
14576 v4hi __builtin_arm_wpackwus (v2si, v2si)
14577 long long __builtin_arm_wrord (long long, long long)
14578 long long __builtin_arm_wrordi (long long, int)
14579 v4hi __builtin_arm_wrorh (v4hi, long long)
14580 v4hi __builtin_arm_wrorhi (v4hi, int)
14581 v2si __builtin_arm_wrorw (v2si, long long)
14582 v2si __builtin_arm_wrorwi (v2si, int)
14583 v2si __builtin_arm_wsadb (v2si, v8qi, v8qi)
14584 v2si __builtin_arm_wsadbz (v8qi, v8qi)
14585 v2si __builtin_arm_wsadh (v2si, v4hi, v4hi)
14586 v2si __builtin_arm_wsadhz (v4hi, v4hi)
14587 v4hi __builtin_arm_wshufh (v4hi, int)
14588 long long __builtin_arm_wslld (long long, long long)
14589 long long __builtin_arm_wslldi (long long, int)
14590 v4hi __builtin_arm_wsllh (v4hi, long long)
14591 v4hi __builtin_arm_wsllhi (v4hi, int)
14592 v2si __builtin_arm_wsllw (v2si, long long)
14593 v2si __builtin_arm_wsllwi (v2si, int)
14594 long long __builtin_arm_wsrad (long long, long long)
14595 long long __builtin_arm_wsradi (long long, int)
14596 v4hi __builtin_arm_wsrah (v4hi, long long)
14597 v4hi __builtin_arm_wsrahi (v4hi, int)
14598 v2si __builtin_arm_wsraw (v2si, long long)
14599 v2si __builtin_arm_wsrawi (v2si, int)
14600 long long __builtin_arm_wsrld (long long, long long)
14601 long long __builtin_arm_wsrldi (long long, int)
14602 v4hi __builtin_arm_wsrlh (v4hi, long long)
14603 v4hi __builtin_arm_wsrlhi (v4hi, int)
14604 v2si __builtin_arm_wsrlw (v2si, long long)
14605 v2si __builtin_arm_wsrlwi (v2si, int)
14606 v8qi __builtin_arm_wsubb (v8qi, v8qi)
14607 v8qi __builtin_arm_wsubbss (v8qi, v8qi)
14608 v8qi __builtin_arm_wsubbus (v8qi, v8qi)
14609 v4hi __builtin_arm_wsubh (v4hi, v4hi)
14610 v4hi __builtin_arm_wsubhss (v4hi, v4hi)
14611 v4hi __builtin_arm_wsubhus (v4hi, v4hi)
14612 v2si __builtin_arm_wsubw (v2si, v2si)
14613 v2si __builtin_arm_wsubwss (v2si, v2si)
14614 v2si __builtin_arm_wsubwus (v2si, v2si)
14615 v4hi __builtin_arm_wunpckehsb (v8qi)
14616 v2si __builtin_arm_wunpckehsh (v4hi)
14617 long long __builtin_arm_wunpckehsw (v2si)
14618 v4hi __builtin_arm_wunpckehub (v8qi)
14619 v2si __builtin_arm_wunpckehuh (v4hi)
14620 long long __builtin_arm_wunpckehuw (v2si)
14621 v4hi __builtin_arm_wunpckelsb (v8qi)
14622 v2si __builtin_arm_wunpckelsh (v4hi)
14623 long long __builtin_arm_wunpckelsw (v2si)
14624 v4hi __builtin_arm_wunpckelub (v8qi)
14625 v2si __builtin_arm_wunpckeluh (v4hi)
14626 long long __builtin_arm_wunpckeluw (v2si)
14627 v8qi __builtin_arm_wunpckihb (v8qi, v8qi)
14628 v4hi __builtin_arm_wunpckihh (v4hi, v4hi)
14629 v2si __builtin_arm_wunpckihw (v2si, v2si)
14630 v8qi __builtin_arm_wunpckilb (v8qi, v8qi)
14631 v4hi __builtin_arm_wunpckilh (v4hi, v4hi)
14632 v2si __builtin_arm_wunpckilw (v2si, v2si)
14633 long long __builtin_arm_wxor (long long, long long)
14634 long long __builtin_arm_wzero ()
14638 @node ARM C Language Extensions (ACLE)
14639 @subsection ARM C Language Extensions (ACLE)
14641 GCC implements extensions for C as described in the ARM C Language
14642 Extensions (ACLE) specification, which can be found at
14643 @uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf}.
14645 As a part of ACLE, GCC implements extensions for Advanced SIMD as described in
14646 the ARM C Language Extensions Specification. The complete list of Advanced SIMD
14647 intrinsics can be found at
14648 @uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0073a/IHI0073A_arm_neon_intrinsics_ref.pdf}.
14649 The built-in intrinsics for the Advanced SIMD extension are available when
14652 Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both
14653 back ends support CRC32 intrinsics and the ARM back end supports the
14654 Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit
14655 floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1.
14656 AArch64's back end does not have support for 16-bit floating point Advanced SIMD
14659 See @ref{ARM Options} and @ref{AArch64 Options} for more information on the
14660 availability of extensions.
14662 @node ARM Floating Point Status and Control Intrinsics
14663 @subsection ARM Floating Point Status and Control Intrinsics
14665 These built-in functions are available for the ARM family of
14666 processors with floating-point unit.
14669 unsigned int __builtin_arm_get_fpscr ()
14670 void __builtin_arm_set_fpscr (unsigned int)
14673 @node ARM ARMv8-M Security Extensions
14674 @subsection ARM ARMv8-M Security Extensions
14676 GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M
14677 Security Extensions: Requirements on Development Tools Engineering
14678 Specification, which can be found at
14679 @uref{http://infocenter.arm.com/help/topic/com.arm.doc.ecm0359818/ECM0359818_armv8m_security_extensions_reqs_on_dev_tools_1_0.pdf}.
14681 As part of the Security Extensions GCC implements two new function attributes:
14682 @code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}.
14684 As part of the Security Extensions GCC implements the intrinsics below. FPTR
14685 is used here to mean any function pointer type.
14688 cmse_address_info_t cmse_TT (void *)
14689 cmse_address_info_t cmse_TT_fptr (FPTR)
14690 cmse_address_info_t cmse_TTT (void *)
14691 cmse_address_info_t cmse_TTT_fptr (FPTR)
14692 cmse_address_info_t cmse_TTA (void *)
14693 cmse_address_info_t cmse_TTA_fptr (FPTR)
14694 cmse_address_info_t cmse_TTAT (void *)
14695 cmse_address_info_t cmse_TTAT_fptr (FPTR)
14696 void * cmse_check_address_range (void *, size_t, int)
14697 typeof(p) cmse_nsfptr_create (FPTR p)
14698 intptr_t cmse_is_nsfptr (FPTR)
14699 int cmse_nonsecure_caller (void)
14702 @node AVR Built-in Functions
14703 @subsection AVR Built-in Functions
14705 For each built-in function for AVR, there is an equally named,
14706 uppercase built-in macro defined. That way users can easily query if
14707 or if not a specific built-in is implemented or not. For example, if
14708 @code{__builtin_avr_nop} is available the macro
14709 @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise.
14713 @item void __builtin_avr_nop (void)
14714 @itemx void __builtin_avr_sei (void)
14715 @itemx void __builtin_avr_cli (void)
14716 @itemx void __builtin_avr_sleep (void)
14717 @itemx void __builtin_avr_wdr (void)
14718 @itemx unsigned char __builtin_avr_swap (unsigned char)
14719 @itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char)
14720 @itemx int __builtin_avr_fmuls (char, char)
14721 @itemx int __builtin_avr_fmulsu (char, unsigned char)
14722 These built-in functions map to the respective machine
14723 instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep},
14724 @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls}
14725 resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented
14726 as library call if no hardware multiplier is available.
14728 @item void __builtin_avr_delay_cycles (unsigned long ticks)
14729 Delay execution for @var{ticks} cycles. Note that this
14730 built-in does not take into account the effect of interrupts that
14731 might increase delay time. @var{ticks} must be a compile-time
14732 integer constant; delays with a variable number of cycles are not supported.
14734 @item char __builtin_avr_flash_segment (const __memx void*)
14735 This built-in takes a byte address to the 24-bit
14736 @ref{AVR Named Address Spaces,address space} @code{__memx} and returns
14737 the number of the flash segment (the 64 KiB chunk) where the address
14738 points to. Counting starts at @code{0}.
14739 If the address does not point to flash memory, return @code{-1}.
14741 @item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val)
14742 Insert bits from @var{bits} into @var{val} and return the resulting
14743 value. The nibbles of @var{map} determine how the insertion is
14744 performed: Let @var{X} be the @var{n}-th nibble of @var{map}
14746 @item If @var{X} is @code{0xf},
14747 then the @var{n}-th bit of @var{val} is returned unaltered.
14749 @item If X is in the range 0@dots{}7,
14750 then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits}
14752 @item If X is in the range 8@dots{}@code{0xe},
14753 then the @var{n}-th result bit is undefined.
14757 One typical use case for this built-in is adjusting input and
14758 output values to non-contiguous port layouts. Some examples:
14761 // same as val, bits is unused
14762 __builtin_avr_insert_bits (0xffffffff, bits, val)
14766 // same as bits, val is unused
14767 __builtin_avr_insert_bits (0x76543210, bits, val)
14771 // same as rotating bits by 4
14772 __builtin_avr_insert_bits (0x32107654, bits, 0)
14776 // high nibble of result is the high nibble of val
14777 // low nibble of result is the low nibble of bits
14778 __builtin_avr_insert_bits (0xffff3210, bits, val)
14782 // reverse the bit order of bits
14783 __builtin_avr_insert_bits (0x01234567, bits, 0)
14786 @item void __builtin_avr_nops (unsigned count)
14787 Insert @var{count} @code{NOP} instructions.
14788 The number of instructions must be a compile-time integer constant.
14793 There are many more AVR-specific built-in functions that are used to
14794 implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of
14795 section 7.18a.6. You don't need to use these built-ins directly.
14796 Instead, use the declarations as supplied by the @code{stdfix.h} header
14800 #include <stdfix.h>
14802 // Re-interpret the bit representation of unsigned 16-bit
14803 // integer @var{uval} as Q-format 0.16 value.
14804 unsigned fract get_bits (uint_ur_t uval)
14806 return urbits (uval);
14810 @node Blackfin Built-in Functions
14811 @subsection Blackfin Built-in Functions
14813 Currently, there are two Blackfin-specific built-in functions. These are
14814 used for generating @code{CSYNC} and @code{SSYNC} machine insns without
14815 using inline assembly; by using these built-in functions the compiler can
14816 automatically add workarounds for hardware errata involving these
14817 instructions. These functions are named as follows:
14820 void __builtin_bfin_csync (void)
14821 void __builtin_bfin_ssync (void)
14824 @node BPF Built-in Functions
14825 @subsection BPF Built-in Functions
14827 The following built-in functions are available for eBPF targets.
14829 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_byte (unsigned long long @var{offset})
14830 Load a byte from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
14833 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_half (unsigned long long @var{offset})
14834 Load 16-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
14837 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_word (unsigned long long @var{offset})
14838 Load 32-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
14841 @node BPF Kernel Helpers
14842 @subsection BPF Kernel Helpers
14844 These built-in functions are available for calling kernel helpers, and
14845 they are available depending on the kernel version selected as the
14848 Rather than using the built-ins directly, it is preferred for programs
14849 to include @file{bpf-helpers.h} and use the wrappers defined there.
14851 For a full description of what the helpers do, the arguments they
14852 take, and the returned value, see the
14853 @file{linux/include/uapi/linux/bpf.h} in a Linux source tree.
14856 void *__builtin_bpf_helper_map_lookup_elem (void *map, void *key)
14857 int __builtin_bpf_helper_map_update_elem (void *map, void *key,
14859 unsigned long long flags)
14860 int __builtin_bpf_helper_map_delete_elem (void *map, const void *key)
14861 int __builtin_bpf_helper_map_push_elem (void *map, const void *value,
14862 unsigned long long flags)
14863 int __builtin_bpf_helper_map_pop_elem (void *map, void *value)
14864 int __builtin_bpf_helper_map_peek_elem (void *map, void *value)
14865 int __builtin_bpf_helper_clone_redirect (void *skb,
14866 unsigned int ifindex,
14867 unsigned long long flags)
14868 int __builtin_bpf_helper_skb_get_tunnel_key (void *ctx, void *key, int size, int flags)
14869 int __builtin_bpf_helper_skb_set_tunnel_key (void *ctx, void *key, int size, int flags)
14870 int __builtin_bpf_helper_skb_get_tunnel_opt (void *ctx, void *md, int size)
14871 int __builtin_bpf_helper_skb_set_tunnel_opt (void *ctx, void *md, int size)
14872 int __builtin_bpf_helper_skb_get_xfrm_state (void *ctx, int index, void *state,
14873 int size, int flags)
14874 static unsigned long long __builtin_bpf_helper_skb_cgroup_id (void *ctx)
14875 static unsigned long long __builtin_bpf_helper_skb_ancestor_cgroup_id
14876 (void *ctx, int level)
14877 int __builtin_bpf_helper_skb_vlan_push (void *ctx, __be16 vlan_proto, __u16 vlan_tci)
14878 int __builtin_bpf_helper_skb_vlan_pop (void *ctx)
14879 int __builtin_bpf_helper_skb_ecn_set_ce (void *ctx)
14881 int __builtin_bpf_helper_skb_load_bytes (void *ctx, int off, void *to, int len)
14882 int __builtin_bpf_helper_skb_load_bytes_relative (void *ctx, int off, void *to, int len, __u32 start_header)
14883 int __builtin_bpf_helper_skb_store_bytes (void *ctx, int off, void *from, int len, int flags)
14884 int __builtin_bpf_helper_skb_under_cgroup (void *ctx, void *map, int index)
14885 int __builtin_bpf_helper_skb_change_head (void *, int len, int flags)
14886 int __builtin_bpf_helper_skb_pull_data (void *, int len)
14887 int __builtin_bpf_helper_skb_change_proto (void *ctx, __be16 proto, __u64 flags)
14888 int __builtin_bpf_helper_skb_change_type (void *ctx, __u32 type)
14889 int __builtin_bpf_helper_skb_change_tail (void *ctx, __u32 len, __u64 flags)
14890 int __builtin_bpf_helper_skb_adjust_room (void *ctx, __s32 len_diff, __u32 mode,
14891 unsigned long long flags)
14897 int __builtin_bpf_helper_probe_read (void *dst, unsigned int size, void *src)
14898 unsigned long long __builtin_bpf_helper_ktime_get_ns (void)
14899 int __builtin_bpf_helper_trace_printk (const char *fmt, unsigned int fmt_size, ...)
14900 void __builtin_bpf_helper_tail_call (void *ctx, void *prog_array_map, unsigned int index)
14901 unsigned int __builtin_bpf_helper_get_smp_processor_id (void)
14902 unsigned long long __builtin_bpf_helper_get_current_pid_tgid (void)
14903 unsigned long long __builtin_bpf_helper_get_current_uid_gid (void)
14904 int __builtin_bpf_helper_get_current_comm (void *buf, unsigned int size_of_buf)
14905 unsigned long long __builtin_bpf_helper_perf_event_read (void *map, unsigned long long flags)
14907 int __builtin_bpf_helper_redirect (unsigned int ifindex, unsigned long long flags)
14908 int __builtin_bpf_helper_redirect_map (void *map, unsigned int key, unsigned long long flags)
14909 int __builtin_bpf_helper_perf_event_output (void *ctx,void *map, unsigned long long flags, void *data, unsigned long long size)
14910 int __builtin_bpf_helper_get_stackid (void *ctx, void *map, unsigned long long flags)
14911 int __builtin_bpf_helper_probe_write_user (void *dst, const void *src, unsigned int len)
14912 int __builtin_bpf_helper_current_task_under_cgroup (void *map, unsigned int index)
14914 static unsigned long long __builtin_bpf_helper_get_prandom_u32 (void)
14915 int __builtin_bpf_helper_xdp_adjust_head (void *ctx, int offset)
14916 int __builtin_bpf_helper_xdp_adjust_meta (void *ctx, int offset)
14917 int __builtin_bpf_helper_get_socket_cookie (void *ctx)
14918 int __builtin_bpf_helper_setsockopt (void *ctx, int level, int optname, void *optval,
14920 int __builtin_bpf_helper_getsockopt (void *ctx, int level, int optname, void *optval,
14922 int __builtin_bpf_helper_sock_ops_cb_flags_set (void *ctx, int flags)
14923 int __builtin_bpf_helper_sk_redirect_map (void *ctx, void *map, int key, int flags)
14924 int __builtin_bpf_helper_sk_redirect_hash (void *ctx, void *map, void *key, int flags)
14925 int __builtin_bpf_helper_sock_map_update (void *map, void *key, void *value,
14926 unsigned long long flags)
14927 int __builtin_bpf_helper_sock_hash_update (void *map, void *key, void *value,
14928 unsigned long long flags)
14929 int __builtin_bpf_helper_perf_event_read_value (void *map, unsigned long long flags,
14930 void *buf, unsigned int buf_size)
14931 int __builtin_bpf_helper_perf_prog_read_value (void *ctx, void *buf,
14932 unsigned int buf_size)
14934 int __builtin_bpf_helper_override_return (void *ctx, unsigned long rc)
14935 int __builtin_bpf_helper_msg_redirect_map (void *ctx, void *map, int key, int flags)
14936 int __builtin_bpf_helper_msg_redirect_hash (void *ctx,
14937 void *map, void *key, int flags)
14938 int __builtin_bpf_helper_msg_apply_bytes (void *ctx, int len)
14939 int __builtin_bpf_helper_msg_cork_bytes (void *ctx, int len)
14940 int __builtin_bpf_helper_msg_pull_data (void *ctx, int start, int end, int flags)
14941 int __builtin_bpf_helper_msg_push_data (void *ctx, int start, int end, int flags)
14942 int __builtin_bpf_helper_msg_pop_data (void *ctx, int start, int cut, int flags)
14943 int __builtin_bpf_helper_bind (void *ctx, void *addr, int addr_len)
14944 int __builtin_bpf_helper_xdp_adjust_tail (void *ctx, int offset)
14945 int __builtin_bpf_helper_sk_select_reuseport (void *ctx, void *map, void *key, __u32 flags)
14946 int __builtin_bpf_helper_get_stack (void *ctx, void *buf, int size, int flags)
14947 int __builtin_bpf_helper_fib_lookup (void *ctx, struct bpf_fib_lookup *params,
14948 int plen, __u32 flags)
14950 int __builtin_bpf_helper_lwt_push_encap (void *ctx, unsigned int type, void *hdr,
14952 int __builtin_bpf_helper_lwt_seg6_store_bytes (void *ctx, unsigned int offset,
14953 void *from, unsigned int len)
14954 int __builtin_bpf_helper_lwt_seg6_action (void *ctx, unsigned int action, void *param,
14955 unsigned int param_len)
14956 int __builtin_bpf_helper_lwt_seg6_adjust_srh (void *ctx, unsigned int offset,
14958 int __builtin_bpf_helper_rc_repeat (void *ctx)
14959 int __builtin_bpf_helper_rc_keydown (void *ctx, unsigned int protocol,
14960 unsigned long long scancode, unsigned int toggle)
14961 static unsigned long long __builtin_bpf_helper_get_current_cgroup_id (void)
14962 static void *__builtin_bpf_helper_get_local_storage (void *map, unsigned long long flags)
14963 static struct bpf_sock *__builtin_bpf_helper_sk_lookup_tcp (void *ctx, void *tuple, int size, unsigned long long netns_id, unsigned long long flags)
14964 static struct bpf_sock *__builtin_bpf_helper_sk_lookup_udp (void *ctx, void *tuple, int size, unsigned long long netns_id, unsigned long long flags)
14965 int __builtin_bpf_helper_sk_release (struct bpf_sock *sk)
14966 int __builtin_bpf_helper_rc_pointer_rel (void *ctx, int rel_x, int rel_y)
14967 static void __builtin_bpf_helper_spin_lock (struct bpf_spin_lock *lock)
14968 static void __builtin_bpf_helper_spin_unlock (struct bpf_spin_lock *lock)
14970 static struct bpf_sock *__builtin_bpf_helper_sk_fullsock (struct bpf_sock *sk)
14971 static struct bpf_tcp_sock *__builtin_bpf_helper_tcp_sock (struct bpf_sock *sk)
14972 static struct bpf_sock *__builtin_bpf_helper_get_listener_sock (struct bpf_sock *sk)
14974 int __builtin_bpf_helper_l3_csum_replace (void *ctx, int off, int from, int to, int flags)
14975 int __builtin_bpf_helper_l4_csum_replace (void *ctx, int off, int from, int to, int flags)
14976 int __builtin_bpf_helper_csum_diff (void *from, int from_size, void *to, int to_size, int seed)
14978 static unsigned int __builtin_bpf_helper_get_cgroup_classid (void *ctx)
14979 static unsigned int __builtin_bpf_helper_get_route_realm (void *ctx)
14980 static unsigned int __builtin_bpf_helper_get_hash_recalc (void *ctx)
14981 static unsigned long long __builtin_bpf_helper_get_current_task (void *ctx)
14983 static long long __builtin_bpf_helper_csum_update (void *ctx, __u32 csum)
14984 static void __builtin_bpf_helper_set_hash_invalid (void *ctx)
14985 int __builtin_bpf_helper_get_numa_node_id (void)
14986 int __builtin_bpf_helper_probe_read_str (void *ctx, __u32 size,
14987 const void *unsafe_ptr)
14988 static unsigned int __builtin_bpf_helper_get_socket_uid (void *ctx)
14989 static unsigned int __builtin_bpf_helper_set_hash (void *ctx, __u32 hash)
14993 @node FR-V Built-in Functions
14994 @subsection FR-V Built-in Functions
14996 GCC provides many FR-V-specific built-in functions. In general,
14997 these functions are intended to be compatible with those described
14998 by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu
14999 Semiconductor}. The two exceptions are @code{__MDUNPACKH} and
15000 @code{__MBTOHE}, the GCC forms of which pass 128-bit values by
15001 pointer rather than by value.
15003 Most of the functions are named after specific FR-V instructions.
15004 Such functions are said to be ``directly mapped'' and are summarized
15005 here in tabular form.
15009 * Directly-mapped Integer Functions::
15010 * Directly-mapped Media Functions::
15011 * Raw read/write Functions::
15012 * Other Built-in Functions::
15015 @node Argument Types
15016 @subsubsection Argument Types
15018 The arguments to the built-in functions can be divided into three groups:
15019 register numbers, compile-time constants and run-time values. In order
15020 to make this classification clear at a glance, the arguments and return
15021 values are given the following pseudo types:
15023 @multitable @columnfractions .20 .30 .15 .35
15024 @item Pseudo type @tab Real C type @tab Constant? @tab Description
15025 @item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword
15026 @item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word
15027 @item @code{sw1} @tab @code{int} @tab No @tab a signed word
15028 @item @code{uw2} @tab @code{unsigned long long} @tab No
15029 @tab an unsigned doubleword
15030 @item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword
15031 @item @code{const} @tab @code{int} @tab Yes @tab an integer constant
15032 @item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number
15033 @item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number
15036 These pseudo types are not defined by GCC, they are simply a notational
15037 convenience used in this manual.
15039 Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2}
15040 and @code{sw2} are evaluated at run time. They correspond to
15041 register operands in the underlying FR-V instructions.
15043 @code{const} arguments represent immediate operands in the underlying
15044 FR-V instructions. They must be compile-time constants.
15046 @code{acc} arguments are evaluated at compile time and specify the number
15047 of an accumulator register. For example, an @code{acc} argument of 2
15048 selects the ACC2 register.
15050 @code{iacc} arguments are similar to @code{acc} arguments but specify the
15051 number of an IACC register. See @pxref{Other Built-in Functions}
15054 @node Directly-mapped Integer Functions
15055 @subsubsection Directly-Mapped Integer Functions
15057 The functions listed below map directly to FR-V I-type instructions.
15059 @multitable @columnfractions .45 .32 .23
15060 @item Function prototype @tab Example usage @tab Assembly output
15061 @item @code{sw1 __ADDSS (sw1, sw1)}
15062 @tab @code{@var{c} = __ADDSS (@var{a}, @var{b})}
15063 @tab @code{ADDSS @var{a},@var{b},@var{c}}
15064 @item @code{sw1 __SCAN (sw1, sw1)}
15065 @tab @code{@var{c} = __SCAN (@var{a}, @var{b})}
15066 @tab @code{SCAN @var{a},@var{b},@var{c}}
15067 @item @code{sw1 __SCUTSS (sw1)}
15068 @tab @code{@var{b} = __SCUTSS (@var{a})}
15069 @tab @code{SCUTSS @var{a},@var{b}}
15070 @item @code{sw1 __SLASS (sw1, sw1)}
15071 @tab @code{@var{c} = __SLASS (@var{a}, @var{b})}
15072 @tab @code{SLASS @var{a},@var{b},@var{c}}
15073 @item @code{void __SMASS (sw1, sw1)}
15074 @tab @code{__SMASS (@var{a}, @var{b})}
15075 @tab @code{SMASS @var{a},@var{b}}
15076 @item @code{void __SMSSS (sw1, sw1)}
15077 @tab @code{__SMSSS (@var{a}, @var{b})}
15078 @tab @code{SMSSS @var{a},@var{b}}
15079 @item @code{void __SMU (sw1, sw1)}
15080 @tab @code{__SMU (@var{a}, @var{b})}
15081 @tab @code{SMU @var{a},@var{b}}
15082 @item @code{sw2 __SMUL (sw1, sw1)}
15083 @tab @code{@var{c} = __SMUL (@var{a}, @var{b})}
15084 @tab @code{SMUL @var{a},@var{b},@var{c}}
15085 @item @code{sw1 __SUBSS (sw1, sw1)}
15086 @tab @code{@var{c} = __SUBSS (@var{a}, @var{b})}
15087 @tab @code{SUBSS @var{a},@var{b},@var{c}}
15088 @item @code{uw2 __UMUL (uw1, uw1)}
15089 @tab @code{@var{c} = __UMUL (@var{a}, @var{b})}
15090 @tab @code{UMUL @var{a},@var{b},@var{c}}
15093 @node Directly-mapped Media Functions
15094 @subsubsection Directly-Mapped Media Functions
15096 The functions listed below map directly to FR-V M-type instructions.
15098 @multitable @columnfractions .45 .32 .23
15099 @item Function prototype @tab Example usage @tab Assembly output
15100 @item @code{uw1 __MABSHS (sw1)}
15101 @tab @code{@var{b} = __MABSHS (@var{a})}
15102 @tab @code{MABSHS @var{a},@var{b}}
15103 @item @code{void __MADDACCS (acc, acc)}
15104 @tab @code{__MADDACCS (@var{b}, @var{a})}
15105 @tab @code{MADDACCS @var{a},@var{b}}
15106 @item @code{sw1 __MADDHSS (sw1, sw1)}
15107 @tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})}
15108 @tab @code{MADDHSS @var{a},@var{b},@var{c}}
15109 @item @code{uw1 __MADDHUS (uw1, uw1)}
15110 @tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})}
15111 @tab @code{MADDHUS @var{a},@var{b},@var{c}}
15112 @item @code{uw1 __MAND (uw1, uw1)}
15113 @tab @code{@var{c} = __MAND (@var{a}, @var{b})}
15114 @tab @code{MAND @var{a},@var{b},@var{c}}
15115 @item @code{void __MASACCS (acc, acc)}
15116 @tab @code{__MASACCS (@var{b}, @var{a})}
15117 @tab @code{MASACCS @var{a},@var{b}}
15118 @item @code{uw1 __MAVEH (uw1, uw1)}
15119 @tab @code{@var{c} = __MAVEH (@var{a}, @var{b})}
15120 @tab @code{MAVEH @var{a},@var{b},@var{c}}
15121 @item @code{uw2 __MBTOH (uw1)}
15122 @tab @code{@var{b} = __MBTOH (@var{a})}
15123 @tab @code{MBTOH @var{a},@var{b}}
15124 @item @code{void __MBTOHE (uw1 *, uw1)}
15125 @tab @code{__MBTOHE (&@var{b}, @var{a})}
15126 @tab @code{MBTOHE @var{a},@var{b}}
15127 @item @code{void __MCLRACC (acc)}
15128 @tab @code{__MCLRACC (@var{a})}
15129 @tab @code{MCLRACC @var{a}}
15130 @item @code{void __MCLRACCA (void)}
15131 @tab @code{__MCLRACCA ()}
15132 @tab @code{MCLRACCA}
15133 @item @code{uw1 __Mcop1 (uw1, uw1)}
15134 @tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})}
15135 @tab @code{Mcop1 @var{a},@var{b},@var{c}}
15136 @item @code{uw1 __Mcop2 (uw1, uw1)}
15137 @tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})}
15138 @tab @code{Mcop2 @var{a},@var{b},@var{c}}
15139 @item @code{uw1 __MCPLHI (uw2, const)}
15140 @tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})}
15141 @tab @code{MCPLHI @var{a},#@var{b},@var{c}}
15142 @item @code{uw1 __MCPLI (uw2, const)}
15143 @tab @code{@var{c} = __MCPLI (@var{a}, @var{b})}
15144 @tab @code{MCPLI @var{a},#@var{b},@var{c}}
15145 @item @code{void __MCPXIS (acc, sw1, sw1)}
15146 @tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})}
15147 @tab @code{MCPXIS @var{a},@var{b},@var{c}}
15148 @item @code{void __MCPXIU (acc, uw1, uw1)}
15149 @tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})}
15150 @tab @code{MCPXIU @var{a},@var{b},@var{c}}
15151 @item @code{void __MCPXRS (acc, sw1, sw1)}
15152 @tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})}
15153 @tab @code{MCPXRS @var{a},@var{b},@var{c}}
15154 @item @code{void __MCPXRU (acc, uw1, uw1)}
15155 @tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})}
15156 @tab @code{MCPXRU @var{a},@var{b},@var{c}}
15157 @item @code{uw1 __MCUT (acc, uw1)}
15158 @tab @code{@var{c} = __MCUT (@var{a}, @var{b})}
15159 @tab @code{MCUT @var{a},@var{b},@var{c}}
15160 @item @code{uw1 __MCUTSS (acc, sw1)}
15161 @tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})}
15162 @tab @code{MCUTSS @var{a},@var{b},@var{c}}
15163 @item @code{void __MDADDACCS (acc, acc)}
15164 @tab @code{__MDADDACCS (@var{b}, @var{a})}
15165 @tab @code{MDADDACCS @var{a},@var{b}}
15166 @item @code{void __MDASACCS (acc, acc)}
15167 @tab @code{__MDASACCS (@var{b}, @var{a})}
15168 @tab @code{MDASACCS @var{a},@var{b}}
15169 @item @code{uw2 __MDCUTSSI (acc, const)}
15170 @tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})}
15171 @tab @code{MDCUTSSI @var{a},#@var{b},@var{c}}
15172 @item @code{uw2 __MDPACKH (uw2, uw2)}
15173 @tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})}
15174 @tab @code{MDPACKH @var{a},@var{b},@var{c}}
15175 @item @code{uw2 __MDROTLI (uw2, const)}
15176 @tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})}
15177 @tab @code{MDROTLI @var{a},#@var{b},@var{c}}
15178 @item @code{void __MDSUBACCS (acc, acc)}
15179 @tab @code{__MDSUBACCS (@var{b}, @var{a})}
15180 @tab @code{MDSUBACCS @var{a},@var{b}}
15181 @item @code{void __MDUNPACKH (uw1 *, uw2)}
15182 @tab @code{__MDUNPACKH (&@var{b}, @var{a})}
15183 @tab @code{MDUNPACKH @var{a},@var{b}}
15184 @item @code{uw2 __MEXPDHD (uw1, const)}
15185 @tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})}
15186 @tab @code{MEXPDHD @var{a},#@var{b},@var{c}}
15187 @item @code{uw1 __MEXPDHW (uw1, const)}
15188 @tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})}
15189 @tab @code{MEXPDHW @var{a},#@var{b},@var{c}}
15190 @item @code{uw1 __MHDSETH (uw1, const)}
15191 @tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})}
15192 @tab @code{MHDSETH @var{a},#@var{b},@var{c}}
15193 @item @code{sw1 __MHDSETS (const)}
15194 @tab @code{@var{b} = __MHDSETS (@var{a})}
15195 @tab @code{MHDSETS #@var{a},@var{b}}
15196 @item @code{uw1 __MHSETHIH (uw1, const)}
15197 @tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})}
15198 @tab @code{MHSETHIH #@var{a},@var{b}}
15199 @item @code{sw1 __MHSETHIS (sw1, const)}
15200 @tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})}
15201 @tab @code{MHSETHIS #@var{a},@var{b}}
15202 @item @code{uw1 __MHSETLOH (uw1, const)}
15203 @tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})}
15204 @tab @code{MHSETLOH #@var{a},@var{b}}
15205 @item @code{sw1 __MHSETLOS (sw1, const)}
15206 @tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})}
15207 @tab @code{MHSETLOS #@var{a},@var{b}}
15208 @item @code{uw1 __MHTOB (uw2)}
15209 @tab @code{@var{b} = __MHTOB (@var{a})}
15210 @tab @code{MHTOB @var{a},@var{b}}
15211 @item @code{void __MMACHS (acc, sw1, sw1)}
15212 @tab @code{__MMACHS (@var{c}, @var{a}, @var{b})}
15213 @tab @code{MMACHS @var{a},@var{b},@var{c}}
15214 @item @code{void __MMACHU (acc, uw1, uw1)}
15215 @tab @code{__MMACHU (@var{c}, @var{a}, @var{b})}
15216 @tab @code{MMACHU @var{a},@var{b},@var{c}}
15217 @item @code{void __MMRDHS (acc, sw1, sw1)}
15218 @tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})}
15219 @tab @code{MMRDHS @var{a},@var{b},@var{c}}
15220 @item @code{void __MMRDHU (acc, uw1, uw1)}
15221 @tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})}
15222 @tab @code{MMRDHU @var{a},@var{b},@var{c}}
15223 @item @code{void __MMULHS (acc, sw1, sw1)}
15224 @tab @code{__MMULHS (@var{c}, @var{a}, @var{b})}
15225 @tab @code{MMULHS @var{a},@var{b},@var{c}}
15226 @item @code{void __MMULHU (acc, uw1, uw1)}
15227 @tab @code{__MMULHU (@var{c}, @var{a}, @var{b})}
15228 @tab @code{MMULHU @var{a},@var{b},@var{c}}
15229 @item @code{void __MMULXHS (acc, sw1, sw1)}
15230 @tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})}
15231 @tab @code{MMULXHS @var{a},@var{b},@var{c}}
15232 @item @code{void __MMULXHU (acc, uw1, uw1)}
15233 @tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})}
15234 @tab @code{MMULXHU @var{a},@var{b},@var{c}}
15235 @item @code{uw1 __MNOT (uw1)}
15236 @tab @code{@var{b} = __MNOT (@var{a})}
15237 @tab @code{MNOT @var{a},@var{b}}
15238 @item @code{uw1 __MOR (uw1, uw1)}
15239 @tab @code{@var{c} = __MOR (@var{a}, @var{b})}
15240 @tab @code{MOR @var{a},@var{b},@var{c}}
15241 @item @code{uw1 __MPACKH (uh, uh)}
15242 @tab @code{@var{c} = __MPACKH (@var{a}, @var{b})}
15243 @tab @code{MPACKH @var{a},@var{b},@var{c}}
15244 @item @code{sw2 __MQADDHSS (sw2, sw2)}
15245 @tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})}
15246 @tab @code{MQADDHSS @var{a},@var{b},@var{c}}
15247 @item @code{uw2 __MQADDHUS (uw2, uw2)}
15248 @tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})}
15249 @tab @code{MQADDHUS @var{a},@var{b},@var{c}}
15250 @item @code{void __MQCPXIS (acc, sw2, sw2)}
15251 @tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})}
15252 @tab @code{MQCPXIS @var{a},@var{b},@var{c}}
15253 @item @code{void __MQCPXIU (acc, uw2, uw2)}
15254 @tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})}
15255 @tab @code{MQCPXIU @var{a},@var{b},@var{c}}
15256 @item @code{void __MQCPXRS (acc, sw2, sw2)}
15257 @tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})}
15258 @tab @code{MQCPXRS @var{a},@var{b},@var{c}}
15259 @item @code{void __MQCPXRU (acc, uw2, uw2)}
15260 @tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})}
15261 @tab @code{MQCPXRU @var{a},@var{b},@var{c}}
15262 @item @code{sw2 __MQLCLRHS (sw2, sw2)}
15263 @tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})}
15264 @tab @code{MQLCLRHS @var{a},@var{b},@var{c}}
15265 @item @code{sw2 __MQLMTHS (sw2, sw2)}
15266 @tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})}
15267 @tab @code{MQLMTHS @var{a},@var{b},@var{c}}
15268 @item @code{void __MQMACHS (acc, sw2, sw2)}
15269 @tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})}
15270 @tab @code{MQMACHS @var{a},@var{b},@var{c}}
15271 @item @code{void __MQMACHU (acc, uw2, uw2)}
15272 @tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})}
15273 @tab @code{MQMACHU @var{a},@var{b},@var{c}}
15274 @item @code{void __MQMACXHS (acc, sw2, sw2)}
15275 @tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})}
15276 @tab @code{MQMACXHS @var{a},@var{b},@var{c}}
15277 @item @code{void __MQMULHS (acc, sw2, sw2)}
15278 @tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})}
15279 @tab @code{MQMULHS @var{a},@var{b},@var{c}}
15280 @item @code{void __MQMULHU (acc, uw2, uw2)}
15281 @tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})}
15282 @tab @code{MQMULHU @var{a},@var{b},@var{c}}
15283 @item @code{void __MQMULXHS (acc, sw2, sw2)}
15284 @tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})}
15285 @tab @code{MQMULXHS @var{a},@var{b},@var{c}}
15286 @item @code{void __MQMULXHU (acc, uw2, uw2)}
15287 @tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})}
15288 @tab @code{MQMULXHU @var{a},@var{b},@var{c}}
15289 @item @code{sw2 __MQSATHS (sw2, sw2)}
15290 @tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})}
15291 @tab @code{MQSATHS @var{a},@var{b},@var{c}}
15292 @item @code{uw2 __MQSLLHI (uw2, int)}
15293 @tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})}
15294 @tab @code{MQSLLHI @var{a},@var{b},@var{c}}
15295 @item @code{sw2 __MQSRAHI (sw2, int)}
15296 @tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})}
15297 @tab @code{MQSRAHI @var{a},@var{b},@var{c}}
15298 @item @code{sw2 __MQSUBHSS (sw2, sw2)}
15299 @tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})}
15300 @tab @code{MQSUBHSS @var{a},@var{b},@var{c}}
15301 @item @code{uw2 __MQSUBHUS (uw2, uw2)}
15302 @tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})}
15303 @tab @code{MQSUBHUS @var{a},@var{b},@var{c}}
15304 @item @code{void __MQXMACHS (acc, sw2, sw2)}
15305 @tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})}
15306 @tab @code{MQXMACHS @var{a},@var{b},@var{c}}
15307 @item @code{void __MQXMACXHS (acc, sw2, sw2)}
15308 @tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})}
15309 @tab @code{MQXMACXHS @var{a},@var{b},@var{c}}
15310 @item @code{uw1 __MRDACC (acc)}
15311 @tab @code{@var{b} = __MRDACC (@var{a})}
15312 @tab @code{MRDACC @var{a},@var{b}}
15313 @item @code{uw1 __MRDACCG (acc)}
15314 @tab @code{@var{b} = __MRDACCG (@var{a})}
15315 @tab @code{MRDACCG @var{a},@var{b}}
15316 @item @code{uw1 __MROTLI (uw1, const)}
15317 @tab @code{@var{c} = __MROTLI (@var{a}, @var{b})}
15318 @tab @code{MROTLI @var{a},#@var{b},@var{c}}
15319 @item @code{uw1 __MROTRI (uw1, const)}
15320 @tab @code{@var{c} = __MROTRI (@var{a}, @var{b})}
15321 @tab @code{MROTRI @var{a},#@var{b},@var{c}}
15322 @item @code{sw1 __MSATHS (sw1, sw1)}
15323 @tab @code{@var{c} = __MSATHS (@var{a}, @var{b})}
15324 @tab @code{MSATHS @var{a},@var{b},@var{c}}
15325 @item @code{uw1 __MSATHU (uw1, uw1)}
15326 @tab @code{@var{c} = __MSATHU (@var{a}, @var{b})}
15327 @tab @code{MSATHU @var{a},@var{b},@var{c}}
15328 @item @code{uw1 __MSLLHI (uw1, const)}
15329 @tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})}
15330 @tab @code{MSLLHI @var{a},#@var{b},@var{c}}
15331 @item @code{sw1 __MSRAHI (sw1, const)}
15332 @tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})}
15333 @tab @code{MSRAHI @var{a},#@var{b},@var{c}}
15334 @item @code{uw1 __MSRLHI (uw1, const)}
15335 @tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})}
15336 @tab @code{MSRLHI @var{a},#@var{b},@var{c}}
15337 @item @code{void __MSUBACCS (acc, acc)}
15338 @tab @code{__MSUBACCS (@var{b}, @var{a})}
15339 @tab @code{MSUBACCS @var{a},@var{b}}
15340 @item @code{sw1 __MSUBHSS (sw1, sw1)}
15341 @tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})}
15342 @tab @code{MSUBHSS @var{a},@var{b},@var{c}}
15343 @item @code{uw1 __MSUBHUS (uw1, uw1)}
15344 @tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})}
15345 @tab @code{MSUBHUS @var{a},@var{b},@var{c}}
15346 @item @code{void __MTRAP (void)}
15347 @tab @code{__MTRAP ()}
15349 @item @code{uw2 __MUNPACKH (uw1)}
15350 @tab @code{@var{b} = __MUNPACKH (@var{a})}
15351 @tab @code{MUNPACKH @var{a},@var{b}}
15352 @item @code{uw1 __MWCUT (uw2, uw1)}
15353 @tab @code{@var{c} = __MWCUT (@var{a}, @var{b})}
15354 @tab @code{MWCUT @var{a},@var{b},@var{c}}
15355 @item @code{void __MWTACC (acc, uw1)}
15356 @tab @code{__MWTACC (@var{b}, @var{a})}
15357 @tab @code{MWTACC @var{a},@var{b}}
15358 @item @code{void __MWTACCG (acc, uw1)}
15359 @tab @code{__MWTACCG (@var{b}, @var{a})}
15360 @tab @code{MWTACCG @var{a},@var{b}}
15361 @item @code{uw1 __MXOR (uw1, uw1)}
15362 @tab @code{@var{c} = __MXOR (@var{a}, @var{b})}
15363 @tab @code{MXOR @var{a},@var{b},@var{c}}
15366 @node Raw read/write Functions
15367 @subsubsection Raw Read/Write Functions
15369 This sections describes built-in functions related to read and write
15370 instructions to access memory. These functions generate
15371 @code{membar} instructions to flush the I/O load and stores where
15372 appropriate, as described in Fujitsu's manual described above.
15376 @item unsigned char __builtin_read8 (void *@var{data})
15377 @item unsigned short __builtin_read16 (void *@var{data})
15378 @item unsigned long __builtin_read32 (void *@var{data})
15379 @item unsigned long long __builtin_read64 (void *@var{data})
15381 @item void __builtin_write8 (void *@var{data}, unsigned char @var{datum})
15382 @item void __builtin_write16 (void *@var{data}, unsigned short @var{datum})
15383 @item void __builtin_write32 (void *@var{data}, unsigned long @var{datum})
15384 @item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum})
15387 @node Other Built-in Functions
15388 @subsubsection Other Built-in Functions
15390 This section describes built-in functions that are not named after
15391 a specific FR-V instruction.
15394 @item sw2 __IACCreadll (iacc @var{reg})
15395 Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved
15396 for future expansion and must be 0.
15398 @item sw1 __IACCreadl (iacc @var{reg})
15399 Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1.
15400 Other values of @var{reg} are rejected as invalid.
15402 @item void __IACCsetll (iacc @var{reg}, sw2 @var{x})
15403 Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument
15404 is reserved for future expansion and must be 0.
15406 @item void __IACCsetl (iacc @var{reg}, sw1 @var{x})
15407 Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg}
15408 is 1. Other values of @var{reg} are rejected as invalid.
15410 @item void __data_prefetch0 (const void *@var{x})
15411 Use the @code{dcpl} instruction to load the contents of address @var{x}
15412 into the data cache.
15414 @item void __data_prefetch (const void *@var{x})
15415 Use the @code{nldub} instruction to load the contents of address @var{x}
15416 into the data cache. The instruction is issued in slot I1@.
15419 @node MIPS DSP Built-in Functions
15420 @subsection MIPS DSP Built-in Functions
15422 The MIPS DSP Application-Specific Extension (ASE) includes new
15423 instructions that are designed to improve the performance of DSP and
15424 media applications. It provides instructions that operate on packed
15425 8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data.
15427 GCC supports MIPS DSP operations using both the generic
15428 vector extensions (@pxref{Vector Extensions}) and a collection of
15429 MIPS-specific built-in functions. Both kinds of support are
15430 enabled by the @option{-mdsp} command-line option.
15432 Revision 2 of the ASE was introduced in the second half of 2006.
15433 This revision adds extra instructions to the original ASE, but is
15434 otherwise backwards-compatible with it. You can select revision 2
15435 using the command-line option @option{-mdspr2}; this option implies
15438 The SCOUNT and POS bits of the DSP control register are global. The
15439 WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and
15440 POS bits. During optimization, the compiler does not delete these
15441 instructions and it does not delete calls to functions containing
15442 these instructions.
15444 At present, GCC only provides support for operations on 32-bit
15445 vectors. The vector type associated with 8-bit integer data is
15446 usually called @code{v4i8}, the vector type associated with Q7
15447 is usually called @code{v4q7}, the vector type associated with 16-bit
15448 integer data is usually called @code{v2i16}, and the vector type
15449 associated with Q15 is usually called @code{v2q15}. They can be
15450 defined in C as follows:
15453 typedef signed char v4i8 __attribute__ ((vector_size(4)));
15454 typedef signed char v4q7 __attribute__ ((vector_size(4)));
15455 typedef short v2i16 __attribute__ ((vector_size(4)));
15456 typedef short v2q15 __attribute__ ((vector_size(4)));
15459 @code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are
15460 initialized in the same way as aggregates. For example:
15463 v4i8 a = @{1, 2, 3, 4@};
15465 b = (v4i8) @{5, 6, 7, 8@};
15467 v2q15 c = @{0x0fcb, 0x3a75@};
15469 d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@};
15472 @emph{Note:} The CPU's endianness determines the order in which values
15473 are packed. On little-endian targets, the first value is the least
15474 significant and the last value is the most significant. The opposite
15475 order applies to big-endian targets. For example, the code above
15476 sets the lowest byte of @code{a} to @code{1} on little-endian targets
15477 and @code{4} on big-endian targets.
15479 @emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer
15480 representation. As shown in this example, the integer representation
15481 of a Q7 value can be obtained by multiplying the fractional value by
15482 @code{0x1.0p7}. The equivalent for Q15 values is to multiply by
15483 @code{0x1.0p15}. The equivalent for Q31 values is to multiply by
15486 The table below lists the @code{v4i8} and @code{v2q15} operations for which
15487 hardware support exists. @code{a} and @code{b} are @code{v4i8} values,
15488 and @code{c} and @code{d} are @code{v2q15} values.
15490 @multitable @columnfractions .50 .50
15491 @item C code @tab MIPS instruction
15492 @item @code{a + b} @tab @code{addu.qb}
15493 @item @code{c + d} @tab @code{addq.ph}
15494 @item @code{a - b} @tab @code{subu.qb}
15495 @item @code{c - d} @tab @code{subq.ph}
15498 The table below lists the @code{v2i16} operation for which
15499 hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are
15500 @code{v2i16} values.
15502 @multitable @columnfractions .50 .50
15503 @item C code @tab MIPS instruction
15504 @item @code{e * f} @tab @code{mul.ph}
15507 It is easier to describe the DSP built-in functions if we first define
15508 the following types:
15513 typedef unsigned int ui32;
15514 typedef long long a64;
15517 @code{q31} and @code{i32} are actually the same as @code{int}, but we
15518 use @code{q31} to indicate a Q31 fractional value and @code{i32} to
15519 indicate a 32-bit integer value. Similarly, @code{a64} is the same as
15520 @code{long long}, but we use @code{a64} to indicate values that are
15521 placed in one of the four DSP accumulators (@code{$ac0},
15522 @code{$ac1}, @code{$ac2} or @code{$ac3}).
15524 Also, some built-in functions prefer or require immediate numbers as
15525 parameters, because the corresponding DSP instructions accept both immediate
15526 numbers and register operands, or accept immediate numbers only. The
15527 immediate parameters are listed as follows.
15535 imm0_255: 0 to 255.
15536 imm_n32_31: -32 to 31.
15537 imm_n512_511: -512 to 511.
15540 The following built-in functions map directly to a particular MIPS DSP
15541 instruction. Please refer to the architecture specification
15542 for details on what each instruction does.
15545 v2q15 __builtin_mips_addq_ph (v2q15, v2q15)
15546 v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15)
15547 q31 __builtin_mips_addq_s_w (q31, q31)
15548 v4i8 __builtin_mips_addu_qb (v4i8, v4i8)
15549 v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8)
15550 v2q15 __builtin_mips_subq_ph (v2q15, v2q15)
15551 v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15)
15552 q31 __builtin_mips_subq_s_w (q31, q31)
15553 v4i8 __builtin_mips_subu_qb (v4i8, v4i8)
15554 v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8)
15555 i32 __builtin_mips_addsc (i32, i32)
15556 i32 __builtin_mips_addwc (i32, i32)
15557 i32 __builtin_mips_modsub (i32, i32)
15558 i32 __builtin_mips_raddu_w_qb (v4i8)
15559 v2q15 __builtin_mips_absq_s_ph (v2q15)
15560 q31 __builtin_mips_absq_s_w (q31)
15561 v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15)
15562 v2q15 __builtin_mips_precrq_ph_w (q31, q31)
15563 v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31)
15564 v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15)
15565 q31 __builtin_mips_preceq_w_phl (v2q15)
15566 q31 __builtin_mips_preceq_w_phr (v2q15)
15567 v2q15 __builtin_mips_precequ_ph_qbl (v4i8)
15568 v2q15 __builtin_mips_precequ_ph_qbr (v4i8)
15569 v2q15 __builtin_mips_precequ_ph_qbla (v4i8)
15570 v2q15 __builtin_mips_precequ_ph_qbra (v4i8)
15571 v2q15 __builtin_mips_preceu_ph_qbl (v4i8)
15572 v2q15 __builtin_mips_preceu_ph_qbr (v4i8)
15573 v2q15 __builtin_mips_preceu_ph_qbla (v4i8)
15574 v2q15 __builtin_mips_preceu_ph_qbra (v4i8)
15575 v4i8 __builtin_mips_shll_qb (v4i8, imm0_7)
15576 v4i8 __builtin_mips_shll_qb (v4i8, i32)
15577 v2q15 __builtin_mips_shll_ph (v2q15, imm0_15)
15578 v2q15 __builtin_mips_shll_ph (v2q15, i32)
15579 v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15)
15580 v2q15 __builtin_mips_shll_s_ph (v2q15, i32)
15581 q31 __builtin_mips_shll_s_w (q31, imm0_31)
15582 q31 __builtin_mips_shll_s_w (q31, i32)
15583 v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7)
15584 v4i8 __builtin_mips_shrl_qb (v4i8, i32)
15585 v2q15 __builtin_mips_shra_ph (v2q15, imm0_15)
15586 v2q15 __builtin_mips_shra_ph (v2q15, i32)
15587 v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15)
15588 v2q15 __builtin_mips_shra_r_ph (v2q15, i32)
15589 q31 __builtin_mips_shra_r_w (q31, imm0_31)
15590 q31 __builtin_mips_shra_r_w (q31, i32)
15591 v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15)
15592 v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15)
15593 v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15)
15594 q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15)
15595 q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15)
15596 a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8)
15597 a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8)
15598 a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8)
15599 a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8)
15600 a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15)
15601 a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31)
15602 a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15)
15603 a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31)
15604 a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15)
15605 a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15)
15606 a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15)
15607 a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15)
15608 a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15)
15609 i32 __builtin_mips_bitrev (i32)
15610 i32 __builtin_mips_insv (i32, i32)
15611 v4i8 __builtin_mips_repl_qb (imm0_255)
15612 v4i8 __builtin_mips_repl_qb (i32)
15613 v2q15 __builtin_mips_repl_ph (imm_n512_511)
15614 v2q15 __builtin_mips_repl_ph (i32)
15615 void __builtin_mips_cmpu_eq_qb (v4i8, v4i8)
15616 void __builtin_mips_cmpu_lt_qb (v4i8, v4i8)
15617 void __builtin_mips_cmpu_le_qb (v4i8, v4i8)
15618 i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8)
15619 i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8)
15620 i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8)
15621 void __builtin_mips_cmp_eq_ph (v2q15, v2q15)
15622 void __builtin_mips_cmp_lt_ph (v2q15, v2q15)
15623 void __builtin_mips_cmp_le_ph (v2q15, v2q15)
15624 v4i8 __builtin_mips_pick_qb (v4i8, v4i8)
15625 v2q15 __builtin_mips_pick_ph (v2q15, v2q15)
15626 v2q15 __builtin_mips_packrl_ph (v2q15, v2q15)
15627 i32 __builtin_mips_extr_w (a64, imm0_31)
15628 i32 __builtin_mips_extr_w (a64, i32)
15629 i32 __builtin_mips_extr_r_w (a64, imm0_31)
15630 i32 __builtin_mips_extr_s_h (a64, i32)
15631 i32 __builtin_mips_extr_rs_w (a64, imm0_31)
15632 i32 __builtin_mips_extr_rs_w (a64, i32)
15633 i32 __builtin_mips_extr_s_h (a64, imm0_31)
15634 i32 __builtin_mips_extr_r_w (a64, i32)
15635 i32 __builtin_mips_extp (a64, imm0_31)
15636 i32 __builtin_mips_extp (a64, i32)
15637 i32 __builtin_mips_extpdp (a64, imm0_31)
15638 i32 __builtin_mips_extpdp (a64, i32)
15639 a64 __builtin_mips_shilo (a64, imm_n32_31)
15640 a64 __builtin_mips_shilo (a64, i32)
15641 a64 __builtin_mips_mthlip (a64, i32)
15642 void __builtin_mips_wrdsp (i32, imm0_63)
15643 i32 __builtin_mips_rddsp (imm0_63)
15644 i32 __builtin_mips_lbux (void *, i32)
15645 i32 __builtin_mips_lhx (void *, i32)
15646 i32 __builtin_mips_lwx (void *, i32)
15647 a64 __builtin_mips_ldx (void *, i32) [MIPS64 only]
15648 i32 __builtin_mips_bposge32 (void)
15649 a64 __builtin_mips_madd (a64, i32, i32);
15650 a64 __builtin_mips_maddu (a64, ui32, ui32);
15651 a64 __builtin_mips_msub (a64, i32, i32);
15652 a64 __builtin_mips_msubu (a64, ui32, ui32);
15653 a64 __builtin_mips_mult (i32, i32);
15654 a64 __builtin_mips_multu (ui32, ui32);
15657 The following built-in functions map directly to a particular MIPS DSP REV 2
15658 instruction. Please refer to the architecture specification
15659 for details on what each instruction does.
15662 v4q7 __builtin_mips_absq_s_qb (v4q7);
15663 v2i16 __builtin_mips_addu_ph (v2i16, v2i16);
15664 v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16);
15665 v4i8 __builtin_mips_adduh_qb (v4i8, v4i8);
15666 v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8);
15667 i32 __builtin_mips_append (i32, i32, imm0_31);
15668 i32 __builtin_mips_balign (i32, i32, imm0_3);
15669 i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8);
15670 i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8);
15671 i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8);
15672 a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16);
15673 a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16);
15674 v2i16 __builtin_mips_mul_ph (v2i16, v2i16);
15675 v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16);
15676 q31 __builtin_mips_mulq_rs_w (q31, q31);
15677 v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15);
15678 q31 __builtin_mips_mulq_s_w (q31, q31);
15679 a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16);
15680 v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16);
15681 v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31);
15682 v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31);
15683 i32 __builtin_mips_prepend (i32, i32, imm0_31);
15684 v4i8 __builtin_mips_shra_qb (v4i8, imm0_7);
15685 v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7);
15686 v4i8 __builtin_mips_shra_qb (v4i8, i32);
15687 v4i8 __builtin_mips_shra_r_qb (v4i8, i32);
15688 v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15);
15689 v2i16 __builtin_mips_shrl_ph (v2i16, i32);
15690 v2i16 __builtin_mips_subu_ph (v2i16, v2i16);
15691 v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16);
15692 v4i8 __builtin_mips_subuh_qb (v4i8, v4i8);
15693 v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8);
15694 v2q15 __builtin_mips_addqh_ph (v2q15, v2q15);
15695 v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15);
15696 q31 __builtin_mips_addqh_w (q31, q31);
15697 q31 __builtin_mips_addqh_r_w (q31, q31);
15698 v2q15 __builtin_mips_subqh_ph (v2q15, v2q15);
15699 v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15);
15700 q31 __builtin_mips_subqh_w (q31, q31);
15701 q31 __builtin_mips_subqh_r_w (q31, q31);
15702 a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16);
15703 a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16);
15704 a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15);
15705 a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15);
15706 a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15);
15707 a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15);
15711 @node MIPS Paired-Single Support
15712 @subsection MIPS Paired-Single Support
15714 The MIPS64 architecture includes a number of instructions that
15715 operate on pairs of single-precision floating-point values.
15716 Each pair is packed into a 64-bit floating-point register,
15717 with one element being designated the ``upper half'' and
15718 the other being designated the ``lower half''.
15720 GCC supports paired-single operations using both the generic
15721 vector extensions (@pxref{Vector Extensions}) and a collection of
15722 MIPS-specific built-in functions. Both kinds of support are
15723 enabled by the @option{-mpaired-single} command-line option.
15725 The vector type associated with paired-single values is usually
15726 called @code{v2sf}. It can be defined in C as follows:
15729 typedef float v2sf __attribute__ ((vector_size (8)));
15732 @code{v2sf} values are initialized in the same way as aggregates.
15736 v2sf a = @{1.5, 9.1@};
15739 b = (v2sf) @{e, f@};
15742 @emph{Note:} The CPU's endianness determines which value is stored in
15743 the upper half of a register and which value is stored in the lower half.
15744 On little-endian targets, the first value is the lower one and the second
15745 value is the upper one. The opposite order applies to big-endian targets.
15746 For example, the code above sets the lower half of @code{a} to
15747 @code{1.5} on little-endian targets and @code{9.1} on big-endian targets.
15749 @node MIPS Loongson Built-in Functions
15750 @subsection MIPS Loongson Built-in Functions
15752 GCC provides intrinsics to access the SIMD instructions provided by the
15753 ST Microelectronics Loongson-2E and -2F processors. These intrinsics,
15754 available after inclusion of the @code{loongson.h} header file,
15755 operate on the following 64-bit vector types:
15758 @item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers;
15759 @item @code{uint16x4_t}, a vector of four unsigned 16-bit integers;
15760 @item @code{uint32x2_t}, a vector of two unsigned 32-bit integers;
15761 @item @code{int8x8_t}, a vector of eight signed 8-bit integers;
15762 @item @code{int16x4_t}, a vector of four signed 16-bit integers;
15763 @item @code{int32x2_t}, a vector of two signed 32-bit integers.
15766 The intrinsics provided are listed below; each is named after the
15767 machine instruction to which it corresponds, with suffixes added as
15768 appropriate to distinguish intrinsics that expand to the same machine
15769 instruction yet have different argument types. Refer to the architecture
15770 documentation for a description of the functionality of each
15774 int16x4_t packsswh (int32x2_t s, int32x2_t t);
15775 int8x8_t packsshb (int16x4_t s, int16x4_t t);
15776 uint8x8_t packushb (uint16x4_t s, uint16x4_t t);
15777 uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t);
15778 uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t);
15779 uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t);
15780 int32x2_t paddw_s (int32x2_t s, int32x2_t t);
15781 int16x4_t paddh_s (int16x4_t s, int16x4_t t);
15782 int8x8_t paddb_s (int8x8_t s, int8x8_t t);
15783 uint64_t paddd_u (uint64_t s, uint64_t t);
15784 int64_t paddd_s (int64_t s, int64_t t);
15785 int16x4_t paddsh (int16x4_t s, int16x4_t t);
15786 int8x8_t paddsb (int8x8_t s, int8x8_t t);
15787 uint16x4_t paddush (uint16x4_t s, uint16x4_t t);
15788 uint8x8_t paddusb (uint8x8_t s, uint8x8_t t);
15789 uint64_t pandn_ud (uint64_t s, uint64_t t);
15790 uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t);
15791 uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t);
15792 uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t);
15793 int64_t pandn_sd (int64_t s, int64_t t);
15794 int32x2_t pandn_sw (int32x2_t s, int32x2_t t);
15795 int16x4_t pandn_sh (int16x4_t s, int16x4_t t);
15796 int8x8_t pandn_sb (int8x8_t s, int8x8_t t);
15797 uint16x4_t pavgh (uint16x4_t s, uint16x4_t t);
15798 uint8x8_t pavgb (uint8x8_t s, uint8x8_t t);
15799 uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t);
15800 uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t);
15801 uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t);
15802 int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t);
15803 int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t);
15804 int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t);
15805 uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t);
15806 uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t);
15807 uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t);
15808 int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t);
15809 int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t);
15810 int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t);
15811 uint16x4_t pextrh_u (uint16x4_t s, int field);
15812 int16x4_t pextrh_s (int16x4_t s, int field);
15813 uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t);
15814 uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t);
15815 uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t);
15816 uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t);
15817 int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t);
15818 int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t);
15819 int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t);
15820 int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t);
15821 int32x2_t pmaddhw (int16x4_t s, int16x4_t t);
15822 int16x4_t pmaxsh (int16x4_t s, int16x4_t t);
15823 uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t);
15824 int16x4_t pminsh (int16x4_t s, int16x4_t t);
15825 uint8x8_t pminub (uint8x8_t s, uint8x8_t t);
15826 uint8x8_t pmovmskb_u (uint8x8_t s);
15827 int8x8_t pmovmskb_s (int8x8_t s);
15828 uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t);
15829 int16x4_t pmulhh (int16x4_t s, int16x4_t t);
15830 int16x4_t pmullh (int16x4_t s, int16x4_t t);
15831 int64_t pmuluw (uint32x2_t s, uint32x2_t t);
15832 uint8x8_t pasubub (uint8x8_t s, uint8x8_t t);
15833 uint16x4_t biadd (uint8x8_t s);
15834 uint16x4_t psadbh (uint8x8_t s, uint8x8_t t);
15835 uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order);
15836 int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order);
15837 uint16x4_t psllh_u (uint16x4_t s, uint8_t amount);
15838 int16x4_t psllh_s (int16x4_t s, uint8_t amount);
15839 uint32x2_t psllw_u (uint32x2_t s, uint8_t amount);
15840 int32x2_t psllw_s (int32x2_t s, uint8_t amount);
15841 uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount);
15842 int16x4_t psrlh_s (int16x4_t s, uint8_t amount);
15843 uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount);
15844 int32x2_t psrlw_s (int32x2_t s, uint8_t amount);
15845 uint16x4_t psrah_u (uint16x4_t s, uint8_t amount);
15846 int16x4_t psrah_s (int16x4_t s, uint8_t amount);
15847 uint32x2_t psraw_u (uint32x2_t s, uint8_t amount);
15848 int32x2_t psraw_s (int32x2_t s, uint8_t amount);
15849 uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t);
15850 uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t);
15851 uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t);
15852 int32x2_t psubw_s (int32x2_t s, int32x2_t t);
15853 int16x4_t psubh_s (int16x4_t s, int16x4_t t);
15854 int8x8_t psubb_s (int8x8_t s, int8x8_t t);
15855 uint64_t psubd_u (uint64_t s, uint64_t t);
15856 int64_t psubd_s (int64_t s, int64_t t);
15857 int16x4_t psubsh (int16x4_t s, int16x4_t t);
15858 int8x8_t psubsb (int8x8_t s, int8x8_t t);
15859 uint16x4_t psubush (uint16x4_t s, uint16x4_t t);
15860 uint8x8_t psubusb (uint8x8_t s, uint8x8_t t);
15861 uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t);
15862 uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t);
15863 uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t);
15864 int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t);
15865 int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t);
15866 int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t);
15867 uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t);
15868 uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t);
15869 uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t);
15870 int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t);
15871 int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t);
15872 int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t);
15876 * Paired-Single Arithmetic::
15877 * Paired-Single Built-in Functions::
15878 * MIPS-3D Built-in Functions::
15881 @node Paired-Single Arithmetic
15882 @subsubsection Paired-Single Arithmetic
15884 The table below lists the @code{v2sf} operations for which hardware
15885 support exists. @code{a}, @code{b} and @code{c} are @code{v2sf}
15886 values and @code{x} is an integral value.
15888 @multitable @columnfractions .50 .50
15889 @item C code @tab MIPS instruction
15890 @item @code{a + b} @tab @code{add.ps}
15891 @item @code{a - b} @tab @code{sub.ps}
15892 @item @code{-a} @tab @code{neg.ps}
15893 @item @code{a * b} @tab @code{mul.ps}
15894 @item @code{a * b + c} @tab @code{madd.ps}
15895 @item @code{a * b - c} @tab @code{msub.ps}
15896 @item @code{-(a * b + c)} @tab @code{nmadd.ps}
15897 @item @code{-(a * b - c)} @tab @code{nmsub.ps}
15898 @item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps}
15901 Note that the multiply-accumulate instructions can be disabled
15902 using the command-line option @code{-mno-fused-madd}.
15904 @node Paired-Single Built-in Functions
15905 @subsubsection Paired-Single Built-in Functions
15907 The following paired-single functions map directly to a particular
15908 MIPS instruction. Please refer to the architecture specification
15909 for details on what each instruction does.
15912 @item v2sf __builtin_mips_pll_ps (v2sf, v2sf)
15913 Pair lower lower (@code{pll.ps}).
15915 @item v2sf __builtin_mips_pul_ps (v2sf, v2sf)
15916 Pair upper lower (@code{pul.ps}).
15918 @item v2sf __builtin_mips_plu_ps (v2sf, v2sf)
15919 Pair lower upper (@code{plu.ps}).
15921 @item v2sf __builtin_mips_puu_ps (v2sf, v2sf)
15922 Pair upper upper (@code{puu.ps}).
15924 @item v2sf __builtin_mips_cvt_ps_s (float, float)
15925 Convert pair to paired single (@code{cvt.ps.s}).
15927 @item float __builtin_mips_cvt_s_pl (v2sf)
15928 Convert pair lower to single (@code{cvt.s.pl}).
15930 @item float __builtin_mips_cvt_s_pu (v2sf)
15931 Convert pair upper to single (@code{cvt.s.pu}).
15933 @item v2sf __builtin_mips_abs_ps (v2sf)
15934 Absolute value (@code{abs.ps}).
15936 @item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int)
15937 Align variable (@code{alnv.ps}).
15939 @emph{Note:} The value of the third parameter must be 0 or 4
15940 modulo 8, otherwise the result is unpredictable. Please read the
15941 instruction description for details.
15944 The following multi-instruction functions are also available.
15945 In each case, @var{cond} can be any of the 16 floating-point conditions:
15946 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
15947 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl},
15948 @code{lt}, @code{nge}, @code{le} or @code{ngt}.
15951 @item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15952 @itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15953 Conditional move based on floating-point comparison (@code{c.@var{cond}.ps},
15954 @code{movt.ps}/@code{movf.ps}).
15956 The @code{movt} functions return the value @var{x} computed by:
15959 c.@var{cond}.ps @var{cc},@var{a},@var{b}
15960 mov.ps @var{x},@var{c}
15961 movt.ps @var{x},@var{d},@var{cc}
15964 The @code{movf} functions are similar but use @code{movf.ps} instead
15967 @item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15968 @itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15969 Comparison of two paired-single values (@code{c.@var{cond}.ps},
15970 @code{bc1t}/@code{bc1f}).
15972 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
15973 and return either the upper or lower half of the result. For example:
15977 if (__builtin_mips_upper_c_eq_ps (a, b))
15978 upper_halves_are_equal ();
15980 upper_halves_are_unequal ();
15982 if (__builtin_mips_lower_c_eq_ps (a, b))
15983 lower_halves_are_equal ();
15985 lower_halves_are_unequal ();
15989 @node MIPS-3D Built-in Functions
15990 @subsubsection MIPS-3D Built-in Functions
15992 The MIPS-3D Application-Specific Extension (ASE) includes additional
15993 paired-single instructions that are designed to improve the performance
15994 of 3D graphics operations. Support for these instructions is controlled
15995 by the @option{-mips3d} command-line option.
15997 The functions listed below map directly to a particular MIPS-3D
15998 instruction. Please refer to the architecture specification for
15999 more details on what each instruction does.
16002 @item v2sf __builtin_mips_addr_ps (v2sf, v2sf)
16003 Reduction add (@code{addr.ps}).
16005 @item v2sf __builtin_mips_mulr_ps (v2sf, v2sf)
16006 Reduction multiply (@code{mulr.ps}).
16008 @item v2sf __builtin_mips_cvt_pw_ps (v2sf)
16009 Convert paired single to paired word (@code{cvt.pw.ps}).
16011 @item v2sf __builtin_mips_cvt_ps_pw (v2sf)
16012 Convert paired word to paired single (@code{cvt.ps.pw}).
16014 @item float __builtin_mips_recip1_s (float)
16015 @itemx double __builtin_mips_recip1_d (double)
16016 @itemx v2sf __builtin_mips_recip1_ps (v2sf)
16017 Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}).
16019 @item float __builtin_mips_recip2_s (float, float)
16020 @itemx double __builtin_mips_recip2_d (double, double)
16021 @itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf)
16022 Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}).
16024 @item float __builtin_mips_rsqrt1_s (float)
16025 @itemx double __builtin_mips_rsqrt1_d (double)
16026 @itemx v2sf __builtin_mips_rsqrt1_ps (v2sf)
16027 Reduced-precision reciprocal square root (sequence step 1)
16028 (@code{rsqrt1.@var{fmt}}).
16030 @item float __builtin_mips_rsqrt2_s (float, float)
16031 @itemx double __builtin_mips_rsqrt2_d (double, double)
16032 @itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf)
16033 Reduced-precision reciprocal square root (sequence step 2)
16034 (@code{rsqrt2.@var{fmt}}).
16037 The following multi-instruction functions are also available.
16038 In each case, @var{cond} can be any of the 16 floating-point conditions:
16039 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
16040 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq},
16041 @code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}.
16044 @item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b})
16045 @itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b})
16046 Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}},
16047 @code{bc1t}/@code{bc1f}).
16049 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s}
16050 or @code{cabs.@var{cond}.d} and return the result as a boolean value.
16055 if (__builtin_mips_cabs_eq_s (a, b))
16061 @item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16062 @itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16063 Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps},
16064 @code{bc1t}/@code{bc1f}).
16066 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps}
16067 and return either the upper or lower half of the result. For example:
16071 if (__builtin_mips_upper_cabs_eq_ps (a, b))
16072 upper_halves_are_equal ();
16074 upper_halves_are_unequal ();
16076 if (__builtin_mips_lower_cabs_eq_ps (a, b))
16077 lower_halves_are_equal ();
16079 lower_halves_are_unequal ();
16082 @item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16083 @itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16084 Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps},
16085 @code{movt.ps}/@code{movf.ps}).
16087 The @code{movt} functions return the value @var{x} computed by:
16090 cabs.@var{cond}.ps @var{cc},@var{a},@var{b}
16091 mov.ps @var{x},@var{c}
16092 movt.ps @var{x},@var{d},@var{cc}
16095 The @code{movf} functions are similar but use @code{movf.ps} instead
16098 @item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16099 @itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16100 @itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16101 @itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
16102 Comparison of two paired-single values
16103 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
16104 @code{bc1any2t}/@code{bc1any2f}).
16106 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
16107 or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either
16108 result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}.
16113 if (__builtin_mips_any_c_eq_ps (a, b))
16118 if (__builtin_mips_all_c_eq_ps (a, b))
16124 @item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16125 @itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16126 @itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16127 @itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
16128 Comparison of four paired-single values
16129 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
16130 @code{bc1any4t}/@code{bc1any4f}).
16132 These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps}
16133 to compare @var{a} with @var{b} and to compare @var{c} with @var{d}.
16134 The @code{any} forms return @code{true} if any of the four results are @code{true}
16135 and the @code{all} forms return @code{true} if all four results are @code{true}.
16140 if (__builtin_mips_any_c_eq_4s (a, b, c, d))
16145 if (__builtin_mips_all_c_eq_4s (a, b, c, d))
16152 @node MIPS SIMD Architecture (MSA) Support
16153 @subsection MIPS SIMD Architecture (MSA) Support
16156 * MIPS SIMD Architecture Built-in Functions::
16159 GCC provides intrinsics to access the SIMD instructions provided by the
16160 MSA MIPS SIMD Architecture. The interface is made available by including
16161 @code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}.
16162 For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic,
16165 MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and
16166 64-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point
16167 data elements. The following vectors typedefs are included in @code{msa.h}:
16169 @item @code{v16i8}, a vector of sixteen signed 8-bit integers;
16170 @item @code{v16u8}, a vector of sixteen unsigned 8-bit integers;
16171 @item @code{v8i16}, a vector of eight signed 16-bit integers;
16172 @item @code{v8u16}, a vector of eight unsigned 16-bit integers;
16173 @item @code{v4i32}, a vector of four signed 32-bit integers;
16174 @item @code{v4u32}, a vector of four unsigned 32-bit integers;
16175 @item @code{v2i64}, a vector of two signed 64-bit integers;
16176 @item @code{v2u64}, a vector of two unsigned 64-bit integers;
16177 @item @code{v4f32}, a vector of four 32-bit floats;
16178 @item @code{v2f64}, a vector of two 64-bit doubles.
16181 Instructions and corresponding built-ins may have additional restrictions and/or
16182 input/output values manipulated:
16184 @item @code{imm0_1}, an integer literal in range 0 to 1;
16185 @item @code{imm0_3}, an integer literal in range 0 to 3;
16186 @item @code{imm0_7}, an integer literal in range 0 to 7;
16187 @item @code{imm0_15}, an integer literal in range 0 to 15;
16188 @item @code{imm0_31}, an integer literal in range 0 to 31;
16189 @item @code{imm0_63}, an integer literal in range 0 to 63;
16190 @item @code{imm0_255}, an integer literal in range 0 to 255;
16191 @item @code{imm_n16_15}, an integer literal in range -16 to 15;
16192 @item @code{imm_n512_511}, an integer literal in range -512 to 511;
16193 @item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left
16194 shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022;
16195 @item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left
16196 shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044;
16197 @item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left
16198 shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088;
16199 @item @code{imm1_4}, an integer literal in range 1 to 4;
16200 @item @code{i32, i64, u32, u64, f32, f64}, defined as follows:
16206 #if __LONG_MAX__ == __LONG_LONG_MAX__
16209 typedef long long i64;
16212 typedef unsigned int u32;
16213 #if __LONG_MAX__ == __LONG_LONG_MAX__
16214 typedef unsigned long u64;
16216 typedef unsigned long long u64;
16219 typedef double f64;
16224 @node MIPS SIMD Architecture Built-in Functions
16225 @subsubsection MIPS SIMD Architecture Built-in Functions
16227 The intrinsics provided are listed below; each is named after the
16228 machine instruction.
16231 v16i8 __builtin_msa_add_a_b (v16i8, v16i8);
16232 v8i16 __builtin_msa_add_a_h (v8i16, v8i16);
16233 v4i32 __builtin_msa_add_a_w (v4i32, v4i32);
16234 v2i64 __builtin_msa_add_a_d (v2i64, v2i64);
16236 v16i8 __builtin_msa_adds_a_b (v16i8, v16i8);
16237 v8i16 __builtin_msa_adds_a_h (v8i16, v8i16);
16238 v4i32 __builtin_msa_adds_a_w (v4i32, v4i32);
16239 v2i64 __builtin_msa_adds_a_d (v2i64, v2i64);
16241 v16i8 __builtin_msa_adds_s_b (v16i8, v16i8);
16242 v8i16 __builtin_msa_adds_s_h (v8i16, v8i16);
16243 v4i32 __builtin_msa_adds_s_w (v4i32, v4i32);
16244 v2i64 __builtin_msa_adds_s_d (v2i64, v2i64);
16246 v16u8 __builtin_msa_adds_u_b (v16u8, v16u8);
16247 v8u16 __builtin_msa_adds_u_h (v8u16, v8u16);
16248 v4u32 __builtin_msa_adds_u_w (v4u32, v4u32);
16249 v2u64 __builtin_msa_adds_u_d (v2u64, v2u64);
16251 v16i8 __builtin_msa_addv_b (v16i8, v16i8);
16252 v8i16 __builtin_msa_addv_h (v8i16, v8i16);
16253 v4i32 __builtin_msa_addv_w (v4i32, v4i32);
16254 v2i64 __builtin_msa_addv_d (v2i64, v2i64);
16256 v16i8 __builtin_msa_addvi_b (v16i8, imm0_31);
16257 v8i16 __builtin_msa_addvi_h (v8i16, imm0_31);
16258 v4i32 __builtin_msa_addvi_w (v4i32, imm0_31);
16259 v2i64 __builtin_msa_addvi_d (v2i64, imm0_31);
16261 v16u8 __builtin_msa_and_v (v16u8, v16u8);
16263 v16u8 __builtin_msa_andi_b (v16u8, imm0_255);
16265 v16i8 __builtin_msa_asub_s_b (v16i8, v16i8);
16266 v8i16 __builtin_msa_asub_s_h (v8i16, v8i16);
16267 v4i32 __builtin_msa_asub_s_w (v4i32, v4i32);
16268 v2i64 __builtin_msa_asub_s_d (v2i64, v2i64);
16270 v16u8 __builtin_msa_asub_u_b (v16u8, v16u8);
16271 v8u16 __builtin_msa_asub_u_h (v8u16, v8u16);
16272 v4u32 __builtin_msa_asub_u_w (v4u32, v4u32);
16273 v2u64 __builtin_msa_asub_u_d (v2u64, v2u64);
16275 v16i8 __builtin_msa_ave_s_b (v16i8, v16i8);
16276 v8i16 __builtin_msa_ave_s_h (v8i16, v8i16);
16277 v4i32 __builtin_msa_ave_s_w (v4i32, v4i32);
16278 v2i64 __builtin_msa_ave_s_d (v2i64, v2i64);
16280 v16u8 __builtin_msa_ave_u_b (v16u8, v16u8);
16281 v8u16 __builtin_msa_ave_u_h (v8u16, v8u16);
16282 v4u32 __builtin_msa_ave_u_w (v4u32, v4u32);
16283 v2u64 __builtin_msa_ave_u_d (v2u64, v2u64);
16285 v16i8 __builtin_msa_aver_s_b (v16i8, v16i8);
16286 v8i16 __builtin_msa_aver_s_h (v8i16, v8i16);
16287 v4i32 __builtin_msa_aver_s_w (v4i32, v4i32);
16288 v2i64 __builtin_msa_aver_s_d (v2i64, v2i64);
16290 v16u8 __builtin_msa_aver_u_b (v16u8, v16u8);
16291 v8u16 __builtin_msa_aver_u_h (v8u16, v8u16);
16292 v4u32 __builtin_msa_aver_u_w (v4u32, v4u32);
16293 v2u64 __builtin_msa_aver_u_d (v2u64, v2u64);
16295 v16u8 __builtin_msa_bclr_b (v16u8, v16u8);
16296 v8u16 __builtin_msa_bclr_h (v8u16, v8u16);
16297 v4u32 __builtin_msa_bclr_w (v4u32, v4u32);
16298 v2u64 __builtin_msa_bclr_d (v2u64, v2u64);
16300 v16u8 __builtin_msa_bclri_b (v16u8, imm0_7);
16301 v8u16 __builtin_msa_bclri_h (v8u16, imm0_15);
16302 v4u32 __builtin_msa_bclri_w (v4u32, imm0_31);
16303 v2u64 __builtin_msa_bclri_d (v2u64, imm0_63);
16305 v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8);
16306 v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16);
16307 v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32);
16308 v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64);
16310 v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7);
16311 v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15);
16312 v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31);
16313 v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63);
16315 v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8);
16316 v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16);
16317 v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32);
16318 v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64);
16320 v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7);
16321 v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15);
16322 v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31);
16323 v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63);
16325 v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8);
16327 v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255);
16329 v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8);
16331 v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255);
16333 v16u8 __builtin_msa_bneg_b (v16u8, v16u8);
16334 v8u16 __builtin_msa_bneg_h (v8u16, v8u16);
16335 v4u32 __builtin_msa_bneg_w (v4u32, v4u32);
16336 v2u64 __builtin_msa_bneg_d (v2u64, v2u64);
16338 v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7);
16339 v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15);
16340 v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31);
16341 v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63);
16343 i32 __builtin_msa_bnz_b (v16u8);
16344 i32 __builtin_msa_bnz_h (v8u16);
16345 i32 __builtin_msa_bnz_w (v4u32);
16346 i32 __builtin_msa_bnz_d (v2u64);
16348 i32 __builtin_msa_bnz_v (v16u8);
16350 v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8);
16352 v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255);
16354 v16u8 __builtin_msa_bset_b (v16u8, v16u8);
16355 v8u16 __builtin_msa_bset_h (v8u16, v8u16);
16356 v4u32 __builtin_msa_bset_w (v4u32, v4u32);
16357 v2u64 __builtin_msa_bset_d (v2u64, v2u64);
16359 v16u8 __builtin_msa_bseti_b (v16u8, imm0_7);
16360 v8u16 __builtin_msa_bseti_h (v8u16, imm0_15);
16361 v4u32 __builtin_msa_bseti_w (v4u32, imm0_31);
16362 v2u64 __builtin_msa_bseti_d (v2u64, imm0_63);
16364 i32 __builtin_msa_bz_b (v16u8);
16365 i32 __builtin_msa_bz_h (v8u16);
16366 i32 __builtin_msa_bz_w (v4u32);
16367 i32 __builtin_msa_bz_d (v2u64);
16369 i32 __builtin_msa_bz_v (v16u8);
16371 v16i8 __builtin_msa_ceq_b (v16i8, v16i8);
16372 v8i16 __builtin_msa_ceq_h (v8i16, v8i16);
16373 v4i32 __builtin_msa_ceq_w (v4i32, v4i32);
16374 v2i64 __builtin_msa_ceq_d (v2i64, v2i64);
16376 v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15);
16377 v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15);
16378 v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15);
16379 v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15);
16381 i32 __builtin_msa_cfcmsa (imm0_31);
16383 v16i8 __builtin_msa_cle_s_b (v16i8, v16i8);
16384 v8i16 __builtin_msa_cle_s_h (v8i16, v8i16);
16385 v4i32 __builtin_msa_cle_s_w (v4i32, v4i32);
16386 v2i64 __builtin_msa_cle_s_d (v2i64, v2i64);
16388 v16i8 __builtin_msa_cle_u_b (v16u8, v16u8);
16389 v8i16 __builtin_msa_cle_u_h (v8u16, v8u16);
16390 v4i32 __builtin_msa_cle_u_w (v4u32, v4u32);
16391 v2i64 __builtin_msa_cle_u_d (v2u64, v2u64);
16393 v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15);
16394 v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15);
16395 v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15);
16396 v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15);
16398 v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31);
16399 v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31);
16400 v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31);
16401 v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31);
16403 v16i8 __builtin_msa_clt_s_b (v16i8, v16i8);
16404 v8i16 __builtin_msa_clt_s_h (v8i16, v8i16);
16405 v4i32 __builtin_msa_clt_s_w (v4i32, v4i32);
16406 v2i64 __builtin_msa_clt_s_d (v2i64, v2i64);
16408 v16i8 __builtin_msa_clt_u_b (v16u8, v16u8);
16409 v8i16 __builtin_msa_clt_u_h (v8u16, v8u16);
16410 v4i32 __builtin_msa_clt_u_w (v4u32, v4u32);
16411 v2i64 __builtin_msa_clt_u_d (v2u64, v2u64);
16413 v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15);
16414 v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15);
16415 v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15);
16416 v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15);
16418 v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31);
16419 v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31);
16420 v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31);
16421 v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31);
16423 i32 __builtin_msa_copy_s_b (v16i8, imm0_15);
16424 i32 __builtin_msa_copy_s_h (v8i16, imm0_7);
16425 i32 __builtin_msa_copy_s_w (v4i32, imm0_3);
16426 i64 __builtin_msa_copy_s_d (v2i64, imm0_1);
16428 u32 __builtin_msa_copy_u_b (v16i8, imm0_15);
16429 u32 __builtin_msa_copy_u_h (v8i16, imm0_7);
16430 u32 __builtin_msa_copy_u_w (v4i32, imm0_3);
16431 u64 __builtin_msa_copy_u_d (v2i64, imm0_1);
16433 void __builtin_msa_ctcmsa (imm0_31, i32);
16435 v16i8 __builtin_msa_div_s_b (v16i8, v16i8);
16436 v8i16 __builtin_msa_div_s_h (v8i16, v8i16);
16437 v4i32 __builtin_msa_div_s_w (v4i32, v4i32);
16438 v2i64 __builtin_msa_div_s_d (v2i64, v2i64);
16440 v16u8 __builtin_msa_div_u_b (v16u8, v16u8);
16441 v8u16 __builtin_msa_div_u_h (v8u16, v8u16);
16442 v4u32 __builtin_msa_div_u_w (v4u32, v4u32);
16443 v2u64 __builtin_msa_div_u_d (v2u64, v2u64);
16445 v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8);
16446 v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16);
16447 v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32);
16449 v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8);
16450 v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16);
16451 v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32);
16453 v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8);
16454 v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16);
16455 v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32);
16457 v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8);
16458 v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16);
16459 v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32);
16461 v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8);
16462 v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16);
16463 v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32);
16465 v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8);
16466 v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16);
16467 v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32);
16469 v4f32 __builtin_msa_fadd_w (v4f32, v4f32);
16470 v2f64 __builtin_msa_fadd_d (v2f64, v2f64);
16472 v4i32 __builtin_msa_fcaf_w (v4f32, v4f32);
16473 v2i64 __builtin_msa_fcaf_d (v2f64, v2f64);
16475 v4i32 __builtin_msa_fceq_w (v4f32, v4f32);
16476 v2i64 __builtin_msa_fceq_d (v2f64, v2f64);
16478 v4i32 __builtin_msa_fclass_w (v4f32);
16479 v2i64 __builtin_msa_fclass_d (v2f64);
16481 v4i32 __builtin_msa_fcle_w (v4f32, v4f32);
16482 v2i64 __builtin_msa_fcle_d (v2f64, v2f64);
16484 v4i32 __builtin_msa_fclt_w (v4f32, v4f32);
16485 v2i64 __builtin_msa_fclt_d (v2f64, v2f64);
16487 v4i32 __builtin_msa_fcne_w (v4f32, v4f32);
16488 v2i64 __builtin_msa_fcne_d (v2f64, v2f64);
16490 v4i32 __builtin_msa_fcor_w (v4f32, v4f32);
16491 v2i64 __builtin_msa_fcor_d (v2f64, v2f64);
16493 v4i32 __builtin_msa_fcueq_w (v4f32, v4f32);
16494 v2i64 __builtin_msa_fcueq_d (v2f64, v2f64);
16496 v4i32 __builtin_msa_fcule_w (v4f32, v4f32);
16497 v2i64 __builtin_msa_fcule_d (v2f64, v2f64);
16499 v4i32 __builtin_msa_fcult_w (v4f32, v4f32);
16500 v2i64 __builtin_msa_fcult_d (v2f64, v2f64);
16502 v4i32 __builtin_msa_fcun_w (v4f32, v4f32);
16503 v2i64 __builtin_msa_fcun_d (v2f64, v2f64);
16505 v4i32 __builtin_msa_fcune_w (v4f32, v4f32);
16506 v2i64 __builtin_msa_fcune_d (v2f64, v2f64);
16508 v4f32 __builtin_msa_fdiv_w (v4f32, v4f32);
16509 v2f64 __builtin_msa_fdiv_d (v2f64, v2f64);
16511 v8i16 __builtin_msa_fexdo_h (v4f32, v4f32);
16512 v4f32 __builtin_msa_fexdo_w (v2f64, v2f64);
16514 v4f32 __builtin_msa_fexp2_w (v4f32, v4i32);
16515 v2f64 __builtin_msa_fexp2_d (v2f64, v2i64);
16517 v4f32 __builtin_msa_fexupl_w (v8i16);
16518 v2f64 __builtin_msa_fexupl_d (v4f32);
16520 v4f32 __builtin_msa_fexupr_w (v8i16);
16521 v2f64 __builtin_msa_fexupr_d (v4f32);
16523 v4f32 __builtin_msa_ffint_s_w (v4i32);
16524 v2f64 __builtin_msa_ffint_s_d (v2i64);
16526 v4f32 __builtin_msa_ffint_u_w (v4u32);
16527 v2f64 __builtin_msa_ffint_u_d (v2u64);
16529 v4f32 __builtin_msa_ffql_w (v8i16);
16530 v2f64 __builtin_msa_ffql_d (v4i32);
16532 v4f32 __builtin_msa_ffqr_w (v8i16);
16533 v2f64 __builtin_msa_ffqr_d (v4i32);
16535 v16i8 __builtin_msa_fill_b (i32);
16536 v8i16 __builtin_msa_fill_h (i32);
16537 v4i32 __builtin_msa_fill_w (i32);
16538 v2i64 __builtin_msa_fill_d (i64);
16540 v4f32 __builtin_msa_flog2_w (v4f32);
16541 v2f64 __builtin_msa_flog2_d (v2f64);
16543 v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32);
16544 v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64);
16546 v4f32 __builtin_msa_fmax_w (v4f32, v4f32);
16547 v2f64 __builtin_msa_fmax_d (v2f64, v2f64);
16549 v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32);
16550 v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64);
16552 v4f32 __builtin_msa_fmin_w (v4f32, v4f32);
16553 v2f64 __builtin_msa_fmin_d (v2f64, v2f64);
16555 v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32);
16556 v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64);
16558 v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32);
16559 v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64);
16561 v4f32 __builtin_msa_fmul_w (v4f32, v4f32);
16562 v2f64 __builtin_msa_fmul_d (v2f64, v2f64);
16564 v4f32 __builtin_msa_frint_w (v4f32);
16565 v2f64 __builtin_msa_frint_d (v2f64);
16567 v4f32 __builtin_msa_frcp_w (v4f32);
16568 v2f64 __builtin_msa_frcp_d (v2f64);
16570 v4f32 __builtin_msa_frsqrt_w (v4f32);
16571 v2f64 __builtin_msa_frsqrt_d (v2f64);
16573 v4i32 __builtin_msa_fsaf_w (v4f32, v4f32);
16574 v2i64 __builtin_msa_fsaf_d (v2f64, v2f64);
16576 v4i32 __builtin_msa_fseq_w (v4f32, v4f32);
16577 v2i64 __builtin_msa_fseq_d (v2f64, v2f64);
16579 v4i32 __builtin_msa_fsle_w (v4f32, v4f32);
16580 v2i64 __builtin_msa_fsle_d (v2f64, v2f64);
16582 v4i32 __builtin_msa_fslt_w (v4f32, v4f32);
16583 v2i64 __builtin_msa_fslt_d (v2f64, v2f64);
16585 v4i32 __builtin_msa_fsne_w (v4f32, v4f32);
16586 v2i64 __builtin_msa_fsne_d (v2f64, v2f64);
16588 v4i32 __builtin_msa_fsor_w (v4f32, v4f32);
16589 v2i64 __builtin_msa_fsor_d (v2f64, v2f64);
16591 v4f32 __builtin_msa_fsqrt_w (v4f32);
16592 v2f64 __builtin_msa_fsqrt_d (v2f64);
16594 v4f32 __builtin_msa_fsub_w (v4f32, v4f32);
16595 v2f64 __builtin_msa_fsub_d (v2f64, v2f64);
16597 v4i32 __builtin_msa_fsueq_w (v4f32, v4f32);
16598 v2i64 __builtin_msa_fsueq_d (v2f64, v2f64);
16600 v4i32 __builtin_msa_fsule_w (v4f32, v4f32);
16601 v2i64 __builtin_msa_fsule_d (v2f64, v2f64);
16603 v4i32 __builtin_msa_fsult_w (v4f32, v4f32);
16604 v2i64 __builtin_msa_fsult_d (v2f64, v2f64);
16606 v4i32 __builtin_msa_fsun_w (v4f32, v4f32);
16607 v2i64 __builtin_msa_fsun_d (v2f64, v2f64);
16609 v4i32 __builtin_msa_fsune_w (v4f32, v4f32);
16610 v2i64 __builtin_msa_fsune_d (v2f64, v2f64);
16612 v4i32 __builtin_msa_ftint_s_w (v4f32);
16613 v2i64 __builtin_msa_ftint_s_d (v2f64);
16615 v4u32 __builtin_msa_ftint_u_w (v4f32);
16616 v2u64 __builtin_msa_ftint_u_d (v2f64);
16618 v8i16 __builtin_msa_ftq_h (v4f32, v4f32);
16619 v4i32 __builtin_msa_ftq_w (v2f64, v2f64);
16621 v4i32 __builtin_msa_ftrunc_s_w (v4f32);
16622 v2i64 __builtin_msa_ftrunc_s_d (v2f64);
16624 v4u32 __builtin_msa_ftrunc_u_w (v4f32);
16625 v2u64 __builtin_msa_ftrunc_u_d (v2f64);
16627 v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8);
16628 v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16);
16629 v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32);
16631 v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8);
16632 v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16);
16633 v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32);
16635 v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8);
16636 v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16);
16637 v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32);
16639 v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8);
16640 v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16);
16641 v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32);
16643 v16i8 __builtin_msa_ilvev_b (v16i8, v16i8);
16644 v8i16 __builtin_msa_ilvev_h (v8i16, v8i16);
16645 v4i32 __builtin_msa_ilvev_w (v4i32, v4i32);
16646 v2i64 __builtin_msa_ilvev_d (v2i64, v2i64);
16648 v16i8 __builtin_msa_ilvl_b (v16i8, v16i8);
16649 v8i16 __builtin_msa_ilvl_h (v8i16, v8i16);
16650 v4i32 __builtin_msa_ilvl_w (v4i32, v4i32);
16651 v2i64 __builtin_msa_ilvl_d (v2i64, v2i64);
16653 v16i8 __builtin_msa_ilvod_b (v16i8, v16i8);
16654 v8i16 __builtin_msa_ilvod_h (v8i16, v8i16);
16655 v4i32 __builtin_msa_ilvod_w (v4i32, v4i32);
16656 v2i64 __builtin_msa_ilvod_d (v2i64, v2i64);
16658 v16i8 __builtin_msa_ilvr_b (v16i8, v16i8);
16659 v8i16 __builtin_msa_ilvr_h (v8i16, v8i16);
16660 v4i32 __builtin_msa_ilvr_w (v4i32, v4i32);
16661 v2i64 __builtin_msa_ilvr_d (v2i64, v2i64);
16663 v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32);
16664 v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32);
16665 v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32);
16666 v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64);
16668 v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8);
16669 v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16);
16670 v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32);
16671 v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64);
16673 v16i8 __builtin_msa_ld_b (const void *, imm_n512_511);
16674 v8i16 __builtin_msa_ld_h (const void *, imm_n1024_1022);
16675 v4i32 __builtin_msa_ld_w (const void *, imm_n2048_2044);
16676 v2i64 __builtin_msa_ld_d (const void *, imm_n4096_4088);
16678 v16i8 __builtin_msa_ldi_b (imm_n512_511);
16679 v8i16 __builtin_msa_ldi_h (imm_n512_511);
16680 v4i32 __builtin_msa_ldi_w (imm_n512_511);
16681 v2i64 __builtin_msa_ldi_d (imm_n512_511);
16683 v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16);
16684 v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32);
16686 v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16);
16687 v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32);
16689 v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8);
16690 v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16);
16691 v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32);
16692 v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64);
16694 v16i8 __builtin_msa_max_a_b (v16i8, v16i8);
16695 v8i16 __builtin_msa_max_a_h (v8i16, v8i16);
16696 v4i32 __builtin_msa_max_a_w (v4i32, v4i32);
16697 v2i64 __builtin_msa_max_a_d (v2i64, v2i64);
16699 v16i8 __builtin_msa_max_s_b (v16i8, v16i8);
16700 v8i16 __builtin_msa_max_s_h (v8i16, v8i16);
16701 v4i32 __builtin_msa_max_s_w (v4i32, v4i32);
16702 v2i64 __builtin_msa_max_s_d (v2i64, v2i64);
16704 v16u8 __builtin_msa_max_u_b (v16u8, v16u8);
16705 v8u16 __builtin_msa_max_u_h (v8u16, v8u16);
16706 v4u32 __builtin_msa_max_u_w (v4u32, v4u32);
16707 v2u64 __builtin_msa_max_u_d (v2u64, v2u64);
16709 v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15);
16710 v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15);
16711 v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15);
16712 v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15);
16714 v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31);
16715 v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31);
16716 v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31);
16717 v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31);
16719 v16i8 __builtin_msa_min_a_b (v16i8, v16i8);
16720 v8i16 __builtin_msa_min_a_h (v8i16, v8i16);
16721 v4i32 __builtin_msa_min_a_w (v4i32, v4i32);
16722 v2i64 __builtin_msa_min_a_d (v2i64, v2i64);
16724 v16i8 __builtin_msa_min_s_b (v16i8, v16i8);
16725 v8i16 __builtin_msa_min_s_h (v8i16, v8i16);
16726 v4i32 __builtin_msa_min_s_w (v4i32, v4i32);
16727 v2i64 __builtin_msa_min_s_d (v2i64, v2i64);
16729 v16u8 __builtin_msa_min_u_b (v16u8, v16u8);
16730 v8u16 __builtin_msa_min_u_h (v8u16, v8u16);
16731 v4u32 __builtin_msa_min_u_w (v4u32, v4u32);
16732 v2u64 __builtin_msa_min_u_d (v2u64, v2u64);
16734 v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15);
16735 v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15);
16736 v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15);
16737 v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15);
16739 v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31);
16740 v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31);
16741 v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31);
16742 v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31);
16744 v16i8 __builtin_msa_mod_s_b (v16i8, v16i8);
16745 v8i16 __builtin_msa_mod_s_h (v8i16, v8i16);
16746 v4i32 __builtin_msa_mod_s_w (v4i32, v4i32);
16747 v2i64 __builtin_msa_mod_s_d (v2i64, v2i64);
16749 v16u8 __builtin_msa_mod_u_b (v16u8, v16u8);
16750 v8u16 __builtin_msa_mod_u_h (v8u16, v8u16);
16751 v4u32 __builtin_msa_mod_u_w (v4u32, v4u32);
16752 v2u64 __builtin_msa_mod_u_d (v2u64, v2u64);
16754 v16i8 __builtin_msa_move_v (v16i8);
16756 v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16);
16757 v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32);
16759 v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16);
16760 v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32);
16762 v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8);
16763 v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16);
16764 v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32);
16765 v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64);
16767 v8i16 __builtin_msa_mul_q_h (v8i16, v8i16);
16768 v4i32 __builtin_msa_mul_q_w (v4i32, v4i32);
16770 v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16);
16771 v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32);
16773 v16i8 __builtin_msa_mulv_b (v16i8, v16i8);
16774 v8i16 __builtin_msa_mulv_h (v8i16, v8i16);
16775 v4i32 __builtin_msa_mulv_w (v4i32, v4i32);
16776 v2i64 __builtin_msa_mulv_d (v2i64, v2i64);
16778 v16i8 __builtin_msa_nloc_b (v16i8);
16779 v8i16 __builtin_msa_nloc_h (v8i16);
16780 v4i32 __builtin_msa_nloc_w (v4i32);
16781 v2i64 __builtin_msa_nloc_d (v2i64);
16783 v16i8 __builtin_msa_nlzc_b (v16i8);
16784 v8i16 __builtin_msa_nlzc_h (v8i16);
16785 v4i32 __builtin_msa_nlzc_w (v4i32);
16786 v2i64 __builtin_msa_nlzc_d (v2i64);
16788 v16u8 __builtin_msa_nor_v (v16u8, v16u8);
16790 v16u8 __builtin_msa_nori_b (v16u8, imm0_255);
16792 v16u8 __builtin_msa_or_v (v16u8, v16u8);
16794 v16u8 __builtin_msa_ori_b (v16u8, imm0_255);
16796 v16i8 __builtin_msa_pckev_b (v16i8, v16i8);
16797 v8i16 __builtin_msa_pckev_h (v8i16, v8i16);
16798 v4i32 __builtin_msa_pckev_w (v4i32, v4i32);
16799 v2i64 __builtin_msa_pckev_d (v2i64, v2i64);
16801 v16i8 __builtin_msa_pckod_b (v16i8, v16i8);
16802 v8i16 __builtin_msa_pckod_h (v8i16, v8i16);
16803 v4i32 __builtin_msa_pckod_w (v4i32, v4i32);
16804 v2i64 __builtin_msa_pckod_d (v2i64, v2i64);
16806 v16i8 __builtin_msa_pcnt_b (v16i8);
16807 v8i16 __builtin_msa_pcnt_h (v8i16);
16808 v4i32 __builtin_msa_pcnt_w (v4i32);
16809 v2i64 __builtin_msa_pcnt_d (v2i64);
16811 v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7);
16812 v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15);
16813 v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31);
16814 v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63);
16816 v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7);
16817 v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15);
16818 v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31);
16819 v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63);
16821 v16i8 __builtin_msa_shf_b (v16i8, imm0_255);
16822 v8i16 __builtin_msa_shf_h (v8i16, imm0_255);
16823 v4i32 __builtin_msa_shf_w (v4i32, imm0_255);
16825 v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32);
16826 v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32);
16827 v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32);
16828 v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32);
16830 v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15);
16831 v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7);
16832 v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3);
16833 v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1);
16835 v16i8 __builtin_msa_sll_b (v16i8, v16i8);
16836 v8i16 __builtin_msa_sll_h (v8i16, v8i16);
16837 v4i32 __builtin_msa_sll_w (v4i32, v4i32);
16838 v2i64 __builtin_msa_sll_d (v2i64, v2i64);
16840 v16i8 __builtin_msa_slli_b (v16i8, imm0_7);
16841 v8i16 __builtin_msa_slli_h (v8i16, imm0_15);
16842 v4i32 __builtin_msa_slli_w (v4i32, imm0_31);
16843 v2i64 __builtin_msa_slli_d (v2i64, imm0_63);
16845 v16i8 __builtin_msa_splat_b (v16i8, i32);
16846 v8i16 __builtin_msa_splat_h (v8i16, i32);
16847 v4i32 __builtin_msa_splat_w (v4i32, i32);
16848 v2i64 __builtin_msa_splat_d (v2i64, i32);
16850 v16i8 __builtin_msa_splati_b (v16i8, imm0_15);
16851 v8i16 __builtin_msa_splati_h (v8i16, imm0_7);
16852 v4i32 __builtin_msa_splati_w (v4i32, imm0_3);
16853 v2i64 __builtin_msa_splati_d (v2i64, imm0_1);
16855 v16i8 __builtin_msa_sra_b (v16i8, v16i8);
16856 v8i16 __builtin_msa_sra_h (v8i16, v8i16);
16857 v4i32 __builtin_msa_sra_w (v4i32, v4i32);
16858 v2i64 __builtin_msa_sra_d (v2i64, v2i64);
16860 v16i8 __builtin_msa_srai_b (v16i8, imm0_7);
16861 v8i16 __builtin_msa_srai_h (v8i16, imm0_15);
16862 v4i32 __builtin_msa_srai_w (v4i32, imm0_31);
16863 v2i64 __builtin_msa_srai_d (v2i64, imm0_63);
16865 v16i8 __builtin_msa_srar_b (v16i8, v16i8);
16866 v8i16 __builtin_msa_srar_h (v8i16, v8i16);
16867 v4i32 __builtin_msa_srar_w (v4i32, v4i32);
16868 v2i64 __builtin_msa_srar_d (v2i64, v2i64);
16870 v16i8 __builtin_msa_srari_b (v16i8, imm0_7);
16871 v8i16 __builtin_msa_srari_h (v8i16, imm0_15);
16872 v4i32 __builtin_msa_srari_w (v4i32, imm0_31);
16873 v2i64 __builtin_msa_srari_d (v2i64, imm0_63);
16875 v16i8 __builtin_msa_srl_b (v16i8, v16i8);
16876 v8i16 __builtin_msa_srl_h (v8i16, v8i16);
16877 v4i32 __builtin_msa_srl_w (v4i32, v4i32);
16878 v2i64 __builtin_msa_srl_d (v2i64, v2i64);
16880 v16i8 __builtin_msa_srli_b (v16i8, imm0_7);
16881 v8i16 __builtin_msa_srli_h (v8i16, imm0_15);
16882 v4i32 __builtin_msa_srli_w (v4i32, imm0_31);
16883 v2i64 __builtin_msa_srli_d (v2i64, imm0_63);
16885 v16i8 __builtin_msa_srlr_b (v16i8, v16i8);
16886 v8i16 __builtin_msa_srlr_h (v8i16, v8i16);
16887 v4i32 __builtin_msa_srlr_w (v4i32, v4i32);
16888 v2i64 __builtin_msa_srlr_d (v2i64, v2i64);
16890 v16i8 __builtin_msa_srlri_b (v16i8, imm0_7);
16891 v8i16 __builtin_msa_srlri_h (v8i16, imm0_15);
16892 v4i32 __builtin_msa_srlri_w (v4i32, imm0_31);
16893 v2i64 __builtin_msa_srlri_d (v2i64, imm0_63);
16895 void __builtin_msa_st_b (v16i8, void *, imm_n512_511);
16896 void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022);
16897 void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044);
16898 void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088);
16900 v16i8 __builtin_msa_subs_s_b (v16i8, v16i8);
16901 v8i16 __builtin_msa_subs_s_h (v8i16, v8i16);
16902 v4i32 __builtin_msa_subs_s_w (v4i32, v4i32);
16903 v2i64 __builtin_msa_subs_s_d (v2i64, v2i64);
16905 v16u8 __builtin_msa_subs_u_b (v16u8, v16u8);
16906 v8u16 __builtin_msa_subs_u_h (v8u16, v8u16);
16907 v4u32 __builtin_msa_subs_u_w (v4u32, v4u32);
16908 v2u64 __builtin_msa_subs_u_d (v2u64, v2u64);
16910 v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8);
16911 v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16);
16912 v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32);
16913 v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64);
16915 v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8);
16916 v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16);
16917 v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32);
16918 v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64);
16920 v16i8 __builtin_msa_subv_b (v16i8, v16i8);
16921 v8i16 __builtin_msa_subv_h (v8i16, v8i16);
16922 v4i32 __builtin_msa_subv_w (v4i32, v4i32);
16923 v2i64 __builtin_msa_subv_d (v2i64, v2i64);
16925 v16i8 __builtin_msa_subvi_b (v16i8, imm0_31);
16926 v8i16 __builtin_msa_subvi_h (v8i16, imm0_31);
16927 v4i32 __builtin_msa_subvi_w (v4i32, imm0_31);
16928 v2i64 __builtin_msa_subvi_d (v2i64, imm0_31);
16930 v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8);
16931 v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16);
16932 v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32);
16933 v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64);
16935 v16u8 __builtin_msa_xor_v (v16u8, v16u8);
16937 v16u8 __builtin_msa_xori_b (v16u8, imm0_255);
16940 @node Other MIPS Built-in Functions
16941 @subsection Other MIPS Built-in Functions
16943 GCC provides other MIPS-specific built-in functions:
16946 @item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr})
16947 Insert a @samp{cache} instruction with operands @var{op} and @var{addr}.
16948 GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE}
16949 when this function is available.
16951 @item unsigned int __builtin_mips_get_fcsr (void)
16952 @itemx void __builtin_mips_set_fcsr (unsigned int @var{value})
16953 Get and set the contents of the floating-point control and status register
16954 (FPU control register 31). These functions are only available in hard-float
16955 code but can be called in both MIPS16 and non-MIPS16 contexts.
16957 @code{__builtin_mips_set_fcsr} can be used to change any bit of the
16958 register except the condition codes, which GCC assumes are preserved.
16961 @node MSP430 Built-in Functions
16962 @subsection MSP430 Built-in Functions
16964 GCC provides a couple of special builtin functions to aid in the
16965 writing of interrupt handlers in C.
16968 @item __bic_SR_register_on_exit (int @var{mask})
16969 This clears the indicated bits in the saved copy of the status register
16970 currently residing on the stack. This only works inside interrupt
16971 handlers and the changes to the status register will only take affect
16972 once the handler returns.
16974 @item __bis_SR_register_on_exit (int @var{mask})
16975 This sets the indicated bits in the saved copy of the status register
16976 currently residing on the stack. This only works inside interrupt
16977 handlers and the changes to the status register will only take affect
16978 once the handler returns.
16980 @item __delay_cycles (long long @var{cycles})
16981 This inserts an instruction sequence that takes exactly @var{cycles}
16982 cycles (between 0 and about 17E9) to complete. The inserted sequence
16983 may use jumps, loops, or no-ops, and does not interfere with any other
16984 instructions. Note that @var{cycles} must be a compile-time constant
16985 integer - that is, you must pass a number, not a variable that may be
16986 optimized to a constant later. The number of cycles delayed by this
16990 @node NDS32 Built-in Functions
16991 @subsection NDS32 Built-in Functions
16993 These built-in functions are available for the NDS32 target:
16995 @deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr})
16996 Insert an ISYNC instruction into the instruction stream where
16997 @var{addr} is an instruction address for serialization.
17000 @deftypefn {Built-in Function} void __builtin_nds32_isb (void)
17001 Insert an ISB instruction into the instruction stream.
17004 @deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr})
17005 Return the content of a system register which is mapped by @var{sr}.
17008 @deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr})
17009 Return the content of a user space register which is mapped by @var{usr}.
17012 @deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr})
17013 Move the @var{value} to a system register which is mapped by @var{sr}.
17016 @deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr})
17017 Move the @var{value} to a user space register which is mapped by @var{usr}.
17020 @deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void)
17021 Enable global interrupt.
17024 @deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void)
17025 Disable global interrupt.
17028 @node picoChip Built-in Functions
17029 @subsection picoChip Built-in Functions
17031 GCC provides an interface to selected machine instructions from the
17032 picoChip instruction set.
17035 @item int __builtin_sbc (int @var{value})
17036 Sign bit count. Return the number of consecutive bits in @var{value}
17037 that have the same value as the sign bit. The result is the number of
17038 leading sign bits minus one, giving the number of redundant sign bits in
17041 @item int __builtin_byteswap (int @var{value})
17042 Byte swap. Return the result of swapping the upper and lower bytes of
17045 @item int __builtin_brev (int @var{value})
17046 Bit reversal. Return the result of reversing the bits in
17047 @var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1,
17050 @item int __builtin_adds (int @var{x}, int @var{y})
17051 Saturating addition. Return the result of adding @var{x} and @var{y},
17052 storing the value 32767 if the result overflows.
17054 @item int __builtin_subs (int @var{x}, int @var{y})
17055 Saturating subtraction. Return the result of subtracting @var{y} from
17056 @var{x}, storing the value @minus{}32768 if the result overflows.
17058 @item void __builtin_halt (void)
17059 Halt. The processor stops execution. This built-in is useful for
17060 implementing assertions.
17064 @node Basic PowerPC Built-in Functions
17065 @subsection Basic PowerPC Built-in Functions
17068 * Basic PowerPC Built-in Functions Available on all Configurations::
17069 * Basic PowerPC Built-in Functions Available on ISA 2.05::
17070 * Basic PowerPC Built-in Functions Available on ISA 2.06::
17071 * Basic PowerPC Built-in Functions Available on ISA 2.07::
17072 * Basic PowerPC Built-in Functions Available on ISA 3.0::
17073 * Basic PowerPC Built-in Functions Available for a Future Architecture::
17076 This section describes PowerPC built-in functions that do not require
17077 the inclusion of any special header files to declare prototypes or
17078 provide macro definitions. The sections that follow describe
17079 additional PowerPC built-in functions.
17081 @node Basic PowerPC Built-in Functions Available on all Configurations
17082 @subsubsection Basic PowerPC Built-in Functions Available on all Configurations
17084 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
17085 This function is a @code{nop} on the PowerPC platform and is included solely
17086 to maintain API compatibility with the x86 builtins.
17089 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
17090 This function returns a value of @code{1} if the run-time CPU is of type
17091 @var{cpuname} and returns @code{0} otherwise
17093 The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer
17094 which exports the hardware capability bits. GCC defines the macro
17095 @code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports}
17096 built-in function is fully supported.
17098 If GCC was configured to use a GLIBC before 2.23, the built-in
17099 function @code{__builtin_cpu_is} always returns a 0 and the compiler
17102 The following CPU names can be detected:
17106 IBM POWER9 Server CPU.
17108 IBM POWER8 Server CPU.
17110 IBM POWER7 Server CPU.
17112 IBM POWER6 Server CPU (RAW mode).
17114 IBM POWER6 Server CPU (Architected mode).
17116 IBM POWER5+ Server CPU.
17118 IBM POWER5 Server CPU.
17120 IBM 970 Server CPU (ie, Apple G5).
17122 IBM POWER4 Server CPU.
17124 IBM A2 64-bit Embedded CPU
17126 IBM PowerPC 476FP 32-bit Embedded CPU.
17128 IBM PowerPC 464 32-bit Embedded CPU.
17130 PowerPC 440 32-bit Embedded CPU.
17132 PowerPC 405 32-bit Embedded CPU.
17134 IBM PowerPC Cell Broadband Engine Architecture CPU.
17137 Here is an example:
17139 #ifdef __BUILTIN_CPU_SUPPORTS__
17140 if (__builtin_cpu_is ("power8"))
17142 do_power8 (); // POWER8 specific implementation.
17147 do_generic (); // Generic implementation.
17152 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
17153 This function returns a value of @code{1} if the run-time CPU supports the HWCAP
17154 feature @var{feature} and returns @code{0} otherwise.
17156 The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or
17157 newer which exports the hardware capability bits. GCC defines the
17158 macro @code{__BUILTIN_CPU_SUPPORTS__} if the
17159 @code{__builtin_cpu_supports} built-in function is fully supported.
17161 If GCC was configured to use a GLIBC before 2.23, the built-in
17162 function @code{__builtin_cpu_suports} always returns a 0 and the
17163 compiler issues a warning.
17165 The following features can be
17170 4xx CPU has a Multiply Accumulator.
17172 CPU has a SIMD/Vector Unit.
17174 CPU supports ISA 2.05 (eg, POWER6)
17176 CPU supports ISA 2.06 (eg, POWER7)
17178 CPU supports ISA 2.07 (eg, POWER8)
17180 CPU supports ISA 3.0 (eg, POWER9)
17182 CPU supports the set of compatible performance monitoring events.
17184 CPU supports the Embedded ISA category.
17186 CPU has a CELL broadband engine.
17188 CPU supports the @code{darn} (deliver a random number) instruction.
17190 CPU has a decimal floating point unit.
17192 CPU supports the data stream control register.
17194 CPU supports event base branching.
17196 CPU has a SPE double precision floating point unit.
17198 CPU has a SPE single precision floating point unit.
17200 CPU has a floating point unit.
17202 CPU has hardware transaction memory instructions.
17204 Kernel aborts hardware transactions when a syscall is made.
17205 @item htm-no-suspend
17206 CPU supports hardware transaction memory but does not support the
17207 @code{tsuspend.} instruction.
17209 CPU supports icache snooping capabilities.
17211 CPU supports 128-bit IEEE binary floating point instructions.
17213 CPU supports the integer select instruction.
17215 CPU has a memory management unit.
17217 CPU does not have a timebase (eg, 601 and 403gx).
17219 CPU supports the PA Semi 6T CORE ISA.
17221 CPU supports ISA 2.00 (eg, POWER4)
17223 CPU supports ISA 2.02 (eg, POWER5)
17225 CPU supports ISA 2.03 (eg, POWER5+)
17227 CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr.
17229 CPU supports 32-bit mode execution.
17231 CPU supports the old POWER ISA (eg, 601)
17233 CPU supports 64-bit mode execution.
17235 CPU supports a little-endian mode that uses address swizzling.
17237 Kernel supports system call vectored.
17239 CPU support simultaneous multi-threading.
17241 CPU has a signal processing extension unit.
17243 CPU supports the target address register.
17245 CPU supports true little-endian mode.
17247 CPU has unified I/D cache.
17249 CPU supports the vector cryptography instructions.
17251 CPU supports the vector-scalar extension.
17254 Here is an example:
17256 #ifdef __BUILTIN_CPU_SUPPORTS__
17257 if (__builtin_cpu_supports ("fpu"))
17259 asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2));
17264 dst = __fadd (src1, src2); // Software FP addition function.
17269 The following built-in functions are also available on all PowerPC
17272 uint64_t __builtin_ppc_get_timebase ();
17273 unsigned long __builtin_ppc_mftb ();
17274 double __builtin_unpack_ibm128 (__ibm128, int);
17275 __ibm128 __builtin_pack_ibm128 (double, double);
17276 double __builtin_mffs (void);
17277 void __builtin_mtfsf (const int, double);
17278 void __builtin_mtfsb0 (const int);
17279 void __builtin_mtfsb1 (const int);
17280 void __builtin_set_fpscr_rn (int);
17283 The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb}
17284 functions generate instructions to read the Time Base Register. The
17285 @code{__builtin_ppc_get_timebase} function may generate multiple
17286 instructions and always returns the 64 bits of the Time Base Register.
17287 The @code{__builtin_ppc_mftb} function always generates one instruction and
17288 returns the Time Base Register value as an unsigned long, throwing away
17289 the most significant word on 32-bit environments. The @code{__builtin_mffs}
17290 return the value of the FPSCR register. Note, ISA 3.0 supports the
17291 @code{__builtin_mffsl()} which permits software to read the control and
17292 non-sticky status bits in the FSPCR without the higher latency associated with
17293 accessing the sticky status bits. The @code{__builtin_mtfsf} takes a constant
17294 8-bit integer field mask and a double precision floating point argument
17295 and generates the @code{mtfsf} (extended mnemonic) instruction to write new
17296 values to selected fields of the FPSCR. The
17297 @code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change
17298 as an argument. The valid bit range is between 0 and 31. The builtins map to
17299 the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and
17300 add 32. Hence these instructions only modify the FPSCR[32:63] bits by
17301 changing the specified bit to a zero or one respectively. The
17302 @code{__builtin_set_fpscr_rn} builtin allows changing both of the floating
17303 point rounding mode bits. The argument is a 2-bit value. The argument can
17304 either be a @code{const int} or stored in a variable. The builtin uses
17306 instruction @code{mffscrn} if available, otherwise it reads the FPSCR, masks
17307 the current rounding mode bits out and OR's in the new value.
17309 @node Basic PowerPC Built-in Functions Available on ISA 2.05
17310 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05
17312 The basic built-in functions described in this section are
17313 available on the PowerPC family of processors starting with ISA 2.05
17314 or later. Unless specific options are explicitly disabled on the
17315 command line, specifying option @option{-mcpu=power6} has the effect of
17316 enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
17317 @option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb},
17318 @option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and
17319 @option{-mrecip-precision} options. Specify the
17320 @option{-maltivec} option explicitly in
17321 combination with the above options if desired.
17323 The following functions require option @option{-mcmpb}.
17325 unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int);
17326 unsigned int __builtin_cmpb (unsigned int, unsigned int);
17329 The @code{__builtin_cmpb} function
17330 performs a byte-wise compare on the contents of its two arguments,
17331 returning the result of the byte-wise comparison as the returned
17332 value. For each byte comparison, the corresponding byte of the return
17333 value holds 0xff if the input bytes are equal and 0 if the input bytes
17334 are not equal. If either of the arguments to this built-in function
17335 is wider than 32 bits, the function call expands into the form that
17336 expects @code{unsigned long long int} arguments
17337 which is only available on 64-bit targets.
17339 The following built-in functions are available
17340 when hardware decimal floating point
17341 (@option{-mhard-dfp}) is available:
17343 void __builtin_set_fpscr_drn(int);
17344 _Decimal64 __builtin_ddedpd (int, _Decimal64);
17345 _Decimal128 __builtin_ddedpdq (int, _Decimal128);
17346 _Decimal64 __builtin_denbcd (int, _Decimal64);
17347 _Decimal128 __builtin_denbcdq (int, _Decimal128);
17348 _Decimal64 __builtin_diex (long long, _Decimal64);
17349 _Decimal128 _builtin_diexq (long long, _Decimal128);
17350 _Decimal64 __builtin_dscli (_Decimal64, int);
17351 _Decimal128 __builtin_dscliq (_Decimal128, int);
17352 _Decimal64 __builtin_dscri (_Decimal64, int);
17353 _Decimal128 __builtin_dscriq (_Decimal128, int);
17354 long long __builtin_dxex (_Decimal64);
17355 long long __builtin_dxexq (_Decimal128);
17356 _Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long);
17357 unsigned long long __builtin_unpack_dec128 (_Decimal128, int);
17359 The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal
17360 floating point rounding mode bits. The argument is a 3-bit value. The
17361 argument can either be a @code{const int} or the value can be stored in
17363 The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available.
17364 Otherwise the builtin reads the FPSCR, masks the current decimal rounding
17365 mode bits out and OR's in the new value.
17369 The following functions require @option{-mhard-float},
17370 @option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options.
17373 double __builtin_recipdiv (double, double);
17374 float __builtin_recipdivf (float, float);
17375 double __builtin_rsqrt (double);
17376 float __builtin_rsqrtf (float);
17379 The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and
17380 @code{__builtin_rsqrtf} functions generate multiple instructions to
17381 implement the reciprocal sqrt functionality using reciprocal sqrt
17382 estimate instructions.
17384 The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf}
17385 functions generate multiple instructions to implement division using
17386 the reciprocal estimate instructions.
17388 The following functions require @option{-mhard-float} and
17389 @option{-mmultiple} options.
17391 The @code{__builtin_unpack_longdouble} function takes a
17392 @code{long double} argument and a compile time constant of 0 or 1. If
17393 the constant is 0, the first @code{double} within the
17394 @code{long double} is returned, otherwise the second @code{double}
17395 is returned. The @code{__builtin_unpack_longdouble} function is only
17396 available if @code{long double} uses the IBM extended double
17399 The @code{__builtin_pack_longdouble} function takes two @code{double}
17400 arguments and returns a @code{long double} value that combines the two
17401 arguments. The @code{__builtin_pack_longdouble} function is only
17402 available if @code{long double} uses the IBM extended double
17405 The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128}
17406 argument and a compile time constant of 0 or 1. If the constant is 0,
17407 the first @code{double} within the @code{__ibm128} is returned,
17408 otherwise the second @code{double} is returned.
17410 The @code{__builtin_pack_ibm128} function takes two @code{double}
17411 arguments and returns a @code{__ibm128} value that combines the two
17414 Additional built-in functions are available for the 64-bit PowerPC
17415 family of processors, for efficient use of 128-bit floating point
17416 (@code{__float128}) values.
17418 @node Basic PowerPC Built-in Functions Available on ISA 2.06
17419 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06
17421 The basic built-in functions described in this section are
17422 available on the PowerPC family of processors starting with ISA 2.05
17423 or later. Unless specific options are explicitly disabled on the
17424 command line, specifying option @option{-mcpu=power7} has the effect of
17425 enabling all the same options as for @option{-mcpu=power6} in
17426 addition to the @option{-maltivec}, @option{-mpopcntd}, and
17427 @option{-mvsx} options.
17429 The following basic built-in functions require @option{-mpopcntd}:
17431 unsigned int __builtin_addg6s (unsigned int, unsigned int);
17432 long long __builtin_bpermd (long long, long long);
17433 unsigned int __builtin_cbcdtd (unsigned int);
17434 unsigned int __builtin_cdtbcd (unsigned int);
17435 long long __builtin_divde (long long, long long);
17436 unsigned long long __builtin_divdeu (unsigned long long, unsigned long long);
17437 int __builtin_divwe (int, int);
17438 unsigned int __builtin_divweu (unsigned int, unsigned int);
17439 vector __int128 __builtin_pack_vector_int128 (long long, long long);
17440 void __builtin_rs6000_speculation_barrier (void);
17441 long long __builtin_unpack_vector_int128 (vector __int128, signed char);
17444 Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions
17445 require a 64-bit environment.
17447 The following basic built-in functions, which are also supported on
17448 x86 targets, require @option{-mfloat128}.
17450 __float128 __builtin_fabsq (__float128);
17451 __float128 __builtin_copysignq (__float128, __float128);
17452 __float128 __builtin_infq (void);
17453 __float128 __builtin_huge_valq (void);
17454 __float128 __builtin_nanq (void);
17455 __float128 __builtin_nansq (void);
17457 __float128 __builtin_sqrtf128 (__float128);
17458 __float128 __builtin_fmaf128 (__float128, __float128, __float128);
17461 @node Basic PowerPC Built-in Functions Available on ISA 2.07
17462 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07
17464 The basic built-in functions described in this section are
17465 available on the PowerPC family of processors starting with ISA 2.07
17466 or later. Unless specific options are explicitly disabled on the
17467 command line, specifying option @option{-mcpu=power8} has the effect of
17468 enabling all the same options as for @option{-mcpu=power7} in
17469 addition to the @option{-mpower8-fusion}, @option{-mpower8-vector},
17470 @option{-mcrypto}, @option{-mhtm}, @option{-mquad-memory}, and
17471 @option{-mquad-memory-atomic} options.
17473 This section intentionally empty.
17475 @node Basic PowerPC Built-in Functions Available on ISA 3.0
17476 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0
17478 The basic built-in functions described in this section are
17479 available on the PowerPC family of processors starting with ISA 3.0
17480 or later. Unless specific options are explicitly disabled on the
17481 command line, specifying option @option{-mcpu=power9} has the effect of
17482 enabling all the same options as for @option{-mcpu=power8} in
17483 addition to the @option{-misel} option.
17485 The following built-in functions are available on Linux 64-bit systems
17486 that use the ISA 3.0 instruction set (@option{-mcpu=power9}):
17489 @item __float128 __builtin_addf128_round_to_odd (__float128, __float128)
17490 Perform a 128-bit IEEE floating point add using round to odd as the
17492 @findex __builtin_addf128_round_to_odd
17494 @item __float128 __builtin_subf128_round_to_odd (__float128, __float128)
17495 Perform a 128-bit IEEE floating point subtract using round to odd as
17497 @findex __builtin_subf128_round_to_odd
17499 @item __float128 __builtin_mulf128_round_to_odd (__float128, __float128)
17500 Perform a 128-bit IEEE floating point multiply using round to odd as
17502 @findex __builtin_mulf128_round_to_odd
17504 @item __float128 __builtin_divf128_round_to_odd (__float128, __float128)
17505 Perform a 128-bit IEEE floating point divide using round to odd as
17507 @findex __builtin_divf128_round_to_odd
17509 @item __float128 __builtin_sqrtf128_round_to_odd (__float128)
17510 Perform a 128-bit IEEE floating point square root using round to odd
17511 as the rounding mode.
17512 @findex __builtin_sqrtf128_round_to_odd
17514 @item __float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128)
17515 Perform a 128-bit IEEE floating point fused multiply and add operation
17516 using round to odd as the rounding mode.
17517 @findex __builtin_fmaf128_round_to_odd
17519 @item double __builtin_truncf128_round_to_odd (__float128)
17520 Convert a 128-bit IEEE floating point value to @code{double} using
17521 round to odd as the rounding mode.
17522 @findex __builtin_truncf128_round_to_odd
17525 The following additional built-in functions are also available for the
17526 PowerPC family of processors, starting with ISA 3.0 or later:
17528 long long __builtin_darn (void);
17529 long long __builtin_darn_raw (void);
17530 int __builtin_darn_32 (void);
17533 The @code{__builtin_darn} and @code{__builtin_darn_raw}
17534 functions require a
17535 64-bit environment supporting ISA 3.0 or later.
17536 The @code{__builtin_darn} function provides a 64-bit conditioned
17537 random number. The @code{__builtin_darn_raw} function provides a
17538 64-bit raw random number. The @code{__builtin_darn_32} function
17539 provides a 32-bit conditioned random number.
17541 The following additional built-in functions are also available for the
17542 PowerPC family of processors, starting with ISA 3.0 or later:
17545 int __builtin_byte_in_set (unsigned char u, unsigned long long set);
17546 int __builtin_byte_in_range (unsigned char u, unsigned int range);
17547 int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges);
17549 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value);
17550 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value);
17551 int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value);
17552 int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value);
17554 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value);
17555 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value);
17556 int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value);
17557 int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value);
17559 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value);
17560 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value);
17561 int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value);
17562 int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value);
17564 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value);
17565 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value);
17566 int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value);
17567 int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value);
17569 double __builtin_mffsl(void);
17572 The @code{__builtin_byte_in_set} function requires a
17573 64-bit environment supporting ISA 3.0 or later. This function returns
17574 a non-zero value if and only if its @code{u} argument exactly equals one of
17575 the eight bytes contained within its 64-bit @code{set} argument.
17577 The @code{__builtin_byte_in_range} and
17578 @code{__builtin_byte_in_either_range} require an environment
17579 supporting ISA 3.0 or later. For these two functions, the
17580 @code{range} argument is encoded as 4 bytes, organized as
17581 @code{hi_1:lo_1:hi_2:lo_2}.
17582 The @code{__builtin_byte_in_range} function returns a
17583 non-zero value if and only if its @code{u} argument is within the
17584 range bounded between @code{lo_2} and @code{hi_2} inclusive.
17585 The @code{__builtin_byte_in_either_range} function returns non-zero if
17586 and only if its @code{u} argument is within either the range bounded
17587 between @code{lo_1} and @code{hi_1} inclusive or the range bounded
17588 between @code{lo_2} and @code{hi_2} inclusive.
17590 The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value
17591 if and only if the number of signficant digits of its @code{value} argument
17592 is less than its @code{comparison} argument. The
17593 @code{__builtin_dfp_dtstsfi_lt_dd} and
17594 @code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but
17595 require that the type of the @code{value} argument be
17596 @code{__Decimal64} and @code{__Decimal128} respectively.
17598 The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value
17599 if and only if the number of signficant digits of its @code{value} argument
17600 is greater than its @code{comparison} argument. The
17601 @code{__builtin_dfp_dtstsfi_gt_dd} and
17602 @code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but
17603 require that the type of the @code{value} argument be
17604 @code{__Decimal64} and @code{__Decimal128} respectively.
17606 The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value
17607 if and only if the number of signficant digits of its @code{value} argument
17608 equals its @code{comparison} argument. The
17609 @code{__builtin_dfp_dtstsfi_eq_dd} and
17610 @code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but
17611 require that the type of the @code{value} argument be
17612 @code{__Decimal64} and @code{__Decimal128} respectively.
17614 The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value
17615 if and only if its @code{value} argument has an undefined number of
17616 significant digits, such as when @code{value} is an encoding of @code{NaN}.
17617 The @code{__builtin_dfp_dtstsfi_ov_dd} and
17618 @code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but
17619 require that the type of the @code{value} argument be
17620 @code{__Decimal64} and @code{__Decimal128} respectively.
17622 The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read
17623 the FPSCR. The instruction is a lower latency version of the @code{mffs}
17624 instruction. If the @code{mffsl} instruction is not available, then the
17625 builtin uses the older @code{mffs} instruction to read the FPSCR.
17627 @node Basic PowerPC Built-in Functions Available for a Future Architecture
17628 @subsubsection Basic PowerPC Built-in Functions Available for a Future Architecture
17630 The basic built-in functions described in this section are
17631 available on the PowerPC family of processors starting with a
17632 hypothetical CPU which may or may not be available in the future, as
17633 requested by specifying @option{-mcpu=future} on the command line.
17634 Unless explicitly disabled on the command line,
17635 specifying @option{-mcpu=future} has the effect of enabling all the
17636 same options as for @option{-mcpu=power9}.
17638 The following built-in functions are available on Linux 64-bit systems
17639 that use a future architecture instruction set (@option{-mcpu=future}):
17642 @exdent unsigned long long int
17643 @exdent __builtin_cfuged (unsigned long long int, unsigned long long int)
17645 Perform a 64-bit centrifuge operation, as if implemented by the Future
17646 @code{cfuged} instruction.
17647 @findex __builtin_cfuged
17650 @exdent unsigned long long int
17651 @exdent __builtin_cntlzdm (unsigned long long int, unsigned long long int)
17653 Perform a 64-bit count leading zeros operation under mask, as if
17654 implemented by the future @code{cntlzdm} instruction.
17655 @findex __builtin_cntlzdm
17658 @exdent unsigned long long int
17659 @exdent __builtin_cnttzdm (unsigned long long int, unsigned long long int)
17661 Perform a 64-bit count trailing zeros operation under mask, as if
17662 implemented by the future @code{cnttzdm} instruction.
17663 @findex __builtin_cnttzdm
17666 @exdent unsigned long long int
17667 @exdent __builtin_pdepd (unsigned long long int, unsigned long long int)
17669 Perform a 64-bit parallel bits deposit operation, as if implemented by the
17670 Future @code{pdepd} instruction.
17671 @findex __builtin_pdepd
17674 @exdent unsigned long long int
17675 @exdent __builtin_pextd (unsigned long long int, unsigned long long int)
17677 Perform a 64-bit parallel bits extract operation, as if implemented by the
17678 Future @code{pextd} instruction.
17679 @findex __builtin_pextd
17681 @node PowerPC AltiVec/VSX Built-in Functions
17682 @subsection PowerPC AltiVec/VSX Built-in Functions
17684 GCC provides an interface for the PowerPC family of processors to access
17685 the AltiVec operations described in Motorola's AltiVec Programming
17686 Interface Manual. The interface is made available by including
17687 @code{<altivec.h>} and using @option{-maltivec} and
17688 @option{-mabi=altivec}. The interface supports the following vector
17692 vector unsigned char
17696 vector unsigned short
17697 vector signed short
17701 vector unsigned int
17707 GCC's implementation of the high-level language interface available from
17708 C and C++ code differs from Motorola's documentation in several ways.
17713 A vector constant is a list of constant expressions within curly braces.
17716 A vector initializer requires no cast if the vector constant is of the
17717 same type as the variable it is initializing.
17720 If @code{signed} or @code{unsigned} is omitted, the signedness of the
17721 vector type is the default signedness of the base type. The default
17722 varies depending on the operating system, so a portable program should
17723 always specify the signedness.
17726 Compiling with @option{-maltivec} adds keywords @code{__vector},
17727 @code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and
17728 @code{bool}. When compiling ISO C, the context-sensitive substitution
17729 of the keywords @code{vector}, @code{pixel} and @code{bool} is
17730 disabled. To use them, you must include @code{<altivec.h>} instead.
17733 GCC allows using a @code{typedef} name as the type specifier for a
17734 vector type, but only under the following circumstances:
17739 When using @code{__vector} instead of @code{vector}; for example,
17742 typedef signed short int16;
17743 __vector int16 data;
17747 When using @code{vector} in keyword-and-predefine mode; for example,
17750 typedef signed short int16;
17754 Note that keyword-and-predefine mode is enabled by disabling GNU
17755 extensions (e.g., by using @code{-std=c11}) and including
17756 @code{<altivec.h>}.
17760 For C, overloaded functions are implemented with macros so the following
17764 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo);
17768 Since @code{vec_add} is a macro, the vector constant in the example
17769 is treated as four separate arguments. Wrap the entire argument in
17770 parentheses for this to work.
17773 @emph{Note:} Only the @code{<altivec.h>} interface is supported.
17774 Internally, GCC uses built-in functions to achieve the functionality in
17775 the aforementioned header file, but they are not supported and are
17776 subject to change without notice.
17778 GCC complies with the OpenPOWER 64-Bit ELF V2 ABI Specification,
17779 which may be found at
17780 @uref{https://openpowerfoundation.org/?resource_lib=64-bit-elf-v2-abi-specification-power-architecture}.
17781 Appendix A of this document lists the vector API interfaces that must be
17782 provided by compliant compilers. Programmers should preferentially use
17783 the interfaces described therein. However, historically GCC has provided
17784 additional interfaces for access to vector instructions. These are
17785 briefly described below.
17788 * PowerPC AltiVec Built-in Functions on ISA 2.05::
17789 * PowerPC AltiVec Built-in Functions Available on ISA 2.06::
17790 * PowerPC AltiVec Built-in Functions Available on ISA 2.07::
17791 * PowerPC AltiVec Built-in Functions Available on ISA 3.0::
17792 * PowerPC AltiVec Built-in Functions Available for a Future Architecture::
17795 @node PowerPC AltiVec Built-in Functions on ISA 2.05
17796 @subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05
17798 The following interfaces are supported for the generic and specific
17799 AltiVec operations and the AltiVec predicates. In cases where there
17800 is a direct mapping between generic and specific operations, only the
17801 generic names are shown here, although the specific operations can also
17804 Arguments that are documented as @code{const int} require literal
17805 integral values within the range required for that operation.
17808 vector signed char vec_abs (vector signed char);
17809 vector signed short vec_abs (vector signed short);
17810 vector signed int vec_abs (vector signed int);
17811 vector float vec_abs (vector float);
17813 vector signed char vec_abss (vector signed char);
17814 vector signed short vec_abss (vector signed short);
17815 vector signed int vec_abss (vector signed int);
17817 vector signed char vec_add (vector bool char, vector signed char);
17818 vector signed char vec_add (vector signed char, vector bool char);
17819 vector signed char vec_add (vector signed char, vector signed char);
17820 vector unsigned char vec_add (vector bool char, vector unsigned char);
17821 vector unsigned char vec_add (vector unsigned char, vector bool char);
17822 vector unsigned char vec_add (vector unsigned char, vector unsigned char);
17823 vector signed short vec_add (vector bool short, vector signed short);
17824 vector signed short vec_add (vector signed short, vector bool short);
17825 vector signed short vec_add (vector signed short, vector signed short);
17826 vector unsigned short vec_add (vector bool short, vector unsigned short);
17827 vector unsigned short vec_add (vector unsigned short, vector bool short);
17828 vector unsigned short vec_add (vector unsigned short, vector unsigned short);
17829 vector signed int vec_add (vector bool int, vector signed int);
17830 vector signed int vec_add (vector signed int, vector bool int);
17831 vector signed int vec_add (vector signed int, vector signed int);
17832 vector unsigned int vec_add (vector bool int, vector unsigned int);
17833 vector unsigned int vec_add (vector unsigned int, vector bool int);
17834 vector unsigned int vec_add (vector unsigned int, vector unsigned int);
17835 vector float vec_add (vector float, vector float);
17837 vector unsigned int vec_addc (vector unsigned int, vector unsigned int);
17839 vector unsigned char vec_adds (vector bool char, vector unsigned char);
17840 vector unsigned char vec_adds (vector unsigned char, vector bool char);
17841 vector unsigned char vec_adds (vector unsigned char, vector unsigned char);
17842 vector signed char vec_adds (vector bool char, vector signed char);
17843 vector signed char vec_adds (vector signed char, vector bool char);
17844 vector signed char vec_adds (vector signed char, vector signed char);
17845 vector unsigned short vec_adds (vector bool short, vector unsigned short);
17846 vector unsigned short vec_adds (vector unsigned short, vector bool short);
17847 vector unsigned short vec_adds (vector unsigned short, vector unsigned short);
17848 vector signed short vec_adds (vector bool short, vector signed short);
17849 vector signed short vec_adds (vector signed short, vector bool short);
17850 vector signed short vec_adds (vector signed short, vector signed short);
17851 vector unsigned int vec_adds (vector bool int, vector unsigned int);
17852 vector unsigned int vec_adds (vector unsigned int, vector bool int);
17853 vector unsigned int vec_adds (vector unsigned int, vector unsigned int);
17854 vector signed int vec_adds (vector bool int, vector signed int);
17855 vector signed int vec_adds (vector signed int, vector bool int);
17856 vector signed int vec_adds (vector signed int, vector signed int);
17858 int vec_all_eq (vector signed char, vector bool char);
17859 int vec_all_eq (vector signed char, vector signed char);
17860 int vec_all_eq (vector unsigned char, vector bool char);
17861 int vec_all_eq (vector unsigned char, vector unsigned char);
17862 int vec_all_eq (vector bool char, vector bool char);
17863 int vec_all_eq (vector bool char, vector unsigned char);
17864 int vec_all_eq (vector bool char, vector signed char);
17865 int vec_all_eq (vector signed short, vector bool short);
17866 int vec_all_eq (vector signed short, vector signed short);
17867 int vec_all_eq (vector unsigned short, vector bool short);
17868 int vec_all_eq (vector unsigned short, vector unsigned short);
17869 int vec_all_eq (vector bool short, vector bool short);
17870 int vec_all_eq (vector bool short, vector unsigned short);
17871 int vec_all_eq (vector bool short, vector signed short);
17872 int vec_all_eq (vector pixel, vector pixel);
17873 int vec_all_eq (vector signed int, vector bool int);
17874 int vec_all_eq (vector signed int, vector signed int);
17875 int vec_all_eq (vector unsigned int, vector bool int);
17876 int vec_all_eq (vector unsigned int, vector unsigned int);
17877 int vec_all_eq (vector bool int, vector bool int);
17878 int vec_all_eq (vector bool int, vector unsigned int);
17879 int vec_all_eq (vector bool int, vector signed int);
17880 int vec_all_eq (vector float, vector float);
17882 int vec_all_ge (vector bool char, vector unsigned char);
17883 int vec_all_ge (vector unsigned char, vector bool char);
17884 int vec_all_ge (vector unsigned char, vector unsigned char);
17885 int vec_all_ge (vector bool char, vector signed char);
17886 int vec_all_ge (vector signed char, vector bool char);
17887 int vec_all_ge (vector signed char, vector signed char);
17888 int vec_all_ge (vector bool short, vector unsigned short);
17889 int vec_all_ge (vector unsigned short, vector bool short);
17890 int vec_all_ge (vector unsigned short, vector unsigned short);
17891 int vec_all_ge (vector signed short, vector signed short);
17892 int vec_all_ge (vector bool short, vector signed short);
17893 int vec_all_ge (vector signed short, vector bool short);
17894 int vec_all_ge (vector bool int, vector unsigned int);
17895 int vec_all_ge (vector unsigned int, vector bool int);
17896 int vec_all_ge (vector unsigned int, vector unsigned int);
17897 int vec_all_ge (vector bool int, vector signed int);
17898 int vec_all_ge (vector signed int, vector bool int);
17899 int vec_all_ge (vector signed int, vector signed int);
17900 int vec_all_ge (vector float, vector float);
17902 int vec_all_gt (vector bool char, vector unsigned char);
17903 int vec_all_gt (vector unsigned char, vector bool char);
17904 int vec_all_gt (vector unsigned char, vector unsigned char);
17905 int vec_all_gt (vector bool char, vector signed char);
17906 int vec_all_gt (vector signed char, vector bool char);
17907 int vec_all_gt (vector signed char, vector signed char);
17908 int vec_all_gt (vector bool short, vector unsigned short);
17909 int vec_all_gt (vector unsigned short, vector bool short);
17910 int vec_all_gt (vector unsigned short, vector unsigned short);
17911 int vec_all_gt (vector bool short, vector signed short);
17912 int vec_all_gt (vector signed short, vector bool short);
17913 int vec_all_gt (vector signed short, vector signed short);
17914 int vec_all_gt (vector bool int, vector unsigned int);
17915 int vec_all_gt (vector unsigned int, vector bool int);
17916 int vec_all_gt (vector unsigned int, vector unsigned int);
17917 int vec_all_gt (vector bool int, vector signed int);
17918 int vec_all_gt (vector signed int, vector bool int);
17919 int vec_all_gt (vector signed int, vector signed int);
17920 int vec_all_gt (vector float, vector float);
17922 int vec_all_in (vector float, vector float);
17924 int vec_all_le (vector bool char, vector unsigned char);
17925 int vec_all_le (vector unsigned char, vector bool char);
17926 int vec_all_le (vector unsigned char, vector unsigned char);
17927 int vec_all_le (vector bool char, vector signed char);
17928 int vec_all_le (vector signed char, vector bool char);
17929 int vec_all_le (vector signed char, vector signed char);
17930 int vec_all_le (vector bool short, vector unsigned short);
17931 int vec_all_le (vector unsigned short, vector bool short);
17932 int vec_all_le (vector unsigned short, vector unsigned short);
17933 int vec_all_le (vector bool short, vector signed short);
17934 int vec_all_le (vector signed short, vector bool short);
17935 int vec_all_le (vector signed short, vector signed short);
17936 int vec_all_le (vector bool int, vector unsigned int);
17937 int vec_all_le (vector unsigned int, vector bool int);
17938 int vec_all_le (vector unsigned int, vector unsigned int);
17939 int vec_all_le (vector bool int, vector signed int);
17940 int vec_all_le (vector signed int, vector bool int);
17941 int vec_all_le (vector signed int, vector signed int);
17942 int vec_all_le (vector float, vector float);
17944 int vec_all_lt (vector bool char, vector unsigned char);
17945 int vec_all_lt (vector unsigned char, vector bool char);
17946 int vec_all_lt (vector unsigned char, vector unsigned char);
17947 int vec_all_lt (vector bool char, vector signed char);
17948 int vec_all_lt (vector signed char, vector bool char);
17949 int vec_all_lt (vector signed char, vector signed char);
17950 int vec_all_lt (vector bool short, vector unsigned short);
17951 int vec_all_lt (vector unsigned short, vector bool short);
17952 int vec_all_lt (vector unsigned short, vector unsigned short);
17953 int vec_all_lt (vector bool short, vector signed short);
17954 int vec_all_lt (vector signed short, vector bool short);
17955 int vec_all_lt (vector signed short, vector signed short);
17956 int vec_all_lt (vector bool int, vector unsigned int);
17957 int vec_all_lt (vector unsigned int, vector bool int);
17958 int vec_all_lt (vector unsigned int, vector unsigned int);
17959 int vec_all_lt (vector bool int, vector signed int);
17960 int vec_all_lt (vector signed int, vector bool int);
17961 int vec_all_lt (vector signed int, vector signed int);
17962 int vec_all_lt (vector float, vector float);
17964 int vec_all_nan (vector float);
17966 int vec_all_ne (vector signed char, vector bool char);
17967 int vec_all_ne (vector signed char, vector signed char);
17968 int vec_all_ne (vector unsigned char, vector bool char);
17969 int vec_all_ne (vector unsigned char, vector unsigned char);
17970 int vec_all_ne (vector bool char, vector bool char);
17971 int vec_all_ne (vector bool char, vector unsigned char);
17972 int vec_all_ne (vector bool char, vector signed char);
17973 int vec_all_ne (vector signed short, vector bool short);
17974 int vec_all_ne (vector signed short, vector signed short);
17975 int vec_all_ne (vector unsigned short, vector bool short);
17976 int vec_all_ne (vector unsigned short, vector unsigned short);
17977 int vec_all_ne (vector bool short, vector bool short);
17978 int vec_all_ne (vector bool short, vector unsigned short);
17979 int vec_all_ne (vector bool short, vector signed short);
17980 int vec_all_ne (vector pixel, vector pixel);
17981 int vec_all_ne (vector signed int, vector bool int);
17982 int vec_all_ne (vector signed int, vector signed int);
17983 int vec_all_ne (vector unsigned int, vector bool int);
17984 int vec_all_ne (vector unsigned int, vector unsigned int);
17985 int vec_all_ne (vector bool int, vector bool int);
17986 int vec_all_ne (vector bool int, vector unsigned int);
17987 int vec_all_ne (vector bool int, vector signed int);
17988 int vec_all_ne (vector float, vector float);
17990 int vec_all_nge (vector float, vector float);
17992 int vec_all_ngt (vector float, vector float);
17994 int vec_all_nle (vector float, vector float);
17996 int vec_all_nlt (vector float, vector float);
17998 int vec_all_numeric (vector float);
18000 vector float vec_and (vector float, vector float);
18001 vector float vec_and (vector float, vector bool int);
18002 vector float vec_and (vector bool int, vector float);
18003 vector bool int vec_and (vector bool int, vector bool int);
18004 vector signed int vec_and (vector bool int, vector signed int);
18005 vector signed int vec_and (vector signed int, vector bool int);
18006 vector signed int vec_and (vector signed int, vector signed int);
18007 vector unsigned int vec_and (vector bool int, vector unsigned int);
18008 vector unsigned int vec_and (vector unsigned int, vector bool int);
18009 vector unsigned int vec_and (vector unsigned int, vector unsigned int);
18010 vector bool short vec_and (vector bool short, vector bool short);
18011 vector signed short vec_and (vector bool short, vector signed short);
18012 vector signed short vec_and (vector signed short, vector bool short);
18013 vector signed short vec_and (vector signed short, vector signed short);
18014 vector unsigned short vec_and (vector bool short, vector unsigned short);
18015 vector unsigned short vec_and (vector unsigned short, vector bool short);
18016 vector unsigned short vec_and (vector unsigned short, vector unsigned short);
18017 vector signed char vec_and (vector bool char, vector signed char);
18018 vector bool char vec_and (vector bool char, vector bool char);
18019 vector signed char vec_and (vector signed char, vector bool char);
18020 vector signed char vec_and (vector signed char, vector signed char);
18021 vector unsigned char vec_and (vector bool char, vector unsigned char);
18022 vector unsigned char vec_and (vector unsigned char, vector bool char);
18023 vector unsigned char vec_and (vector unsigned char, vector unsigned char);
18025 vector float vec_andc (vector float, vector float);
18026 vector float vec_andc (vector float, vector bool int);
18027 vector float vec_andc (vector bool int, vector float);
18028 vector bool int vec_andc (vector bool int, vector bool int);
18029 vector signed int vec_andc (vector bool int, vector signed int);
18030 vector signed int vec_andc (vector signed int, vector bool int);
18031 vector signed int vec_andc (vector signed int, vector signed int);
18032 vector unsigned int vec_andc (vector bool int, vector unsigned int);
18033 vector unsigned int vec_andc (vector unsigned int, vector bool int);
18034 vector unsigned int vec_andc (vector unsigned int, vector unsigned int);
18035 vector bool short vec_andc (vector bool short, vector bool short);
18036 vector signed short vec_andc (vector bool short, vector signed short);
18037 vector signed short vec_andc (vector signed short, vector bool short);
18038 vector signed short vec_andc (vector signed short, vector signed short);
18039 vector unsigned short vec_andc (vector bool short, vector unsigned short);
18040 vector unsigned short vec_andc (vector unsigned short, vector bool short);
18041 vector unsigned short vec_andc (vector unsigned short, vector unsigned short);
18042 vector signed char vec_andc (vector bool char, vector signed char);
18043 vector bool char vec_andc (vector bool char, vector bool char);
18044 vector signed char vec_andc (vector signed char, vector bool char);
18045 vector signed char vec_andc (vector signed char, vector signed char);
18046 vector unsigned char vec_andc (vector bool char, vector unsigned char);
18047 vector unsigned char vec_andc (vector unsigned char, vector bool char);
18048 vector unsigned char vec_andc (vector unsigned char, vector unsigned char);
18050 int vec_any_eq (vector signed char, vector bool char);
18051 int vec_any_eq (vector signed char, vector signed char);
18052 int vec_any_eq (vector unsigned char, vector bool char);
18053 int vec_any_eq (vector unsigned char, vector unsigned char);
18054 int vec_any_eq (vector bool char, vector bool char);
18055 int vec_any_eq (vector bool char, vector unsigned char);
18056 int vec_any_eq (vector bool char, vector signed char);
18057 int vec_any_eq (vector signed short, vector bool short);
18058 int vec_any_eq (vector signed short, vector signed short);
18059 int vec_any_eq (vector unsigned short, vector bool short);
18060 int vec_any_eq (vector unsigned short, vector unsigned short);
18061 int vec_any_eq (vector bool short, vector bool short);
18062 int vec_any_eq (vector bool short, vector unsigned short);
18063 int vec_any_eq (vector bool short, vector signed short);
18064 int vec_any_eq (vector pixel, vector pixel);
18065 int vec_any_eq (vector signed int, vector bool int);
18066 int vec_any_eq (vector signed int, vector signed int);
18067 int vec_any_eq (vector unsigned int, vector bool int);
18068 int vec_any_eq (vector unsigned int, vector unsigned int);
18069 int vec_any_eq (vector bool int, vector bool int);
18070 int vec_any_eq (vector bool int, vector unsigned int);
18071 int vec_any_eq (vector bool int, vector signed int);
18072 int vec_any_eq (vector float, vector float);
18074 int vec_any_ge (vector signed char, vector bool char);
18075 int vec_any_ge (vector unsigned char, vector bool char);
18076 int vec_any_ge (vector unsigned char, vector unsigned char);
18077 int vec_any_ge (vector signed char, vector signed char);
18078 int vec_any_ge (vector bool char, vector unsigned char);
18079 int vec_any_ge (vector bool char, vector signed char);
18080 int vec_any_ge (vector unsigned short, vector bool short);
18081 int vec_any_ge (vector unsigned short, vector unsigned short);
18082 int vec_any_ge (vector signed short, vector signed short);
18083 int vec_any_ge (vector signed short, vector bool short);
18084 int vec_any_ge (vector bool short, vector unsigned short);
18085 int vec_any_ge (vector bool short, vector signed short);
18086 int vec_any_ge (vector signed int, vector bool int);
18087 int vec_any_ge (vector unsigned int, vector bool int);
18088 int vec_any_ge (vector unsigned int, vector unsigned int);
18089 int vec_any_ge (vector signed int, vector signed int);
18090 int vec_any_ge (vector bool int, vector unsigned int);
18091 int vec_any_ge (vector bool int, vector signed int);
18092 int vec_any_ge (vector float, vector float);
18094 int vec_any_gt (vector bool char, vector unsigned char);
18095 int vec_any_gt (vector unsigned char, vector bool char);
18096 int vec_any_gt (vector unsigned char, vector unsigned char);
18097 int vec_any_gt (vector bool char, vector signed char);
18098 int vec_any_gt (vector signed char, vector bool char);
18099 int vec_any_gt (vector signed char, vector signed char);
18100 int vec_any_gt (vector bool short, vector unsigned short);
18101 int vec_any_gt (vector unsigned short, vector bool short);
18102 int vec_any_gt (vector unsigned short, vector unsigned short);
18103 int vec_any_gt (vector bool short, vector signed short);
18104 int vec_any_gt (vector signed short, vector bool short);
18105 int vec_any_gt (vector signed short, vector signed short);
18106 int vec_any_gt (vector bool int, vector unsigned int);
18107 int vec_any_gt (vector unsigned int, vector bool int);
18108 int vec_any_gt (vector unsigned int, vector unsigned int);
18109 int vec_any_gt (vector bool int, vector signed int);
18110 int vec_any_gt (vector signed int, vector bool int);
18111 int vec_any_gt (vector signed int, vector signed int);
18112 int vec_any_gt (vector float, vector float);
18114 int vec_any_le (vector bool char, vector unsigned char);
18115 int vec_any_le (vector unsigned char, vector bool char);
18116 int vec_any_le (vector unsigned char, vector unsigned char);
18117 int vec_any_le (vector bool char, vector signed char);
18118 int vec_any_le (vector signed char, vector bool char);
18119 int vec_any_le (vector signed char, vector signed char);
18120 int vec_any_le (vector bool short, vector unsigned short);
18121 int vec_any_le (vector unsigned short, vector bool short);
18122 int vec_any_le (vector unsigned short, vector unsigned short);
18123 int vec_any_le (vector bool short, vector signed short);
18124 int vec_any_le (vector signed short, vector bool short);
18125 int vec_any_le (vector signed short, vector signed short);
18126 int vec_any_le (vector bool int, vector unsigned int);
18127 int vec_any_le (vector unsigned int, vector bool int);
18128 int vec_any_le (vector unsigned int, vector unsigned int);
18129 int vec_any_le (vector bool int, vector signed int);
18130 int vec_any_le (vector signed int, vector bool int);
18131 int vec_any_le (vector signed int, vector signed int);
18132 int vec_any_le (vector float, vector float);
18134 int vec_any_lt (vector bool char, vector unsigned char);
18135 int vec_any_lt (vector unsigned char, vector bool char);
18136 int vec_any_lt (vector unsigned char, vector unsigned char);
18137 int vec_any_lt (vector bool char, vector signed char);
18138 int vec_any_lt (vector signed char, vector bool char);
18139 int vec_any_lt (vector signed char, vector signed char);
18140 int vec_any_lt (vector bool short, vector unsigned short);
18141 int vec_any_lt (vector unsigned short, vector bool short);
18142 int vec_any_lt (vector unsigned short, vector unsigned short);
18143 int vec_any_lt (vector bool short, vector signed short);
18144 int vec_any_lt (vector signed short, vector bool short);
18145 int vec_any_lt (vector signed short, vector signed short);
18146 int vec_any_lt (vector bool int, vector unsigned int);
18147 int vec_any_lt (vector unsigned int, vector bool int);
18148 int vec_any_lt (vector unsigned int, vector unsigned int);
18149 int vec_any_lt (vector bool int, vector signed int);
18150 int vec_any_lt (vector signed int, vector bool int);
18151 int vec_any_lt (vector signed int, vector signed int);
18152 int vec_any_lt (vector float, vector float);
18154 int vec_any_nan (vector float);
18156 int vec_any_ne (vector signed char, vector bool char);
18157 int vec_any_ne (vector signed char, vector signed char);
18158 int vec_any_ne (vector unsigned char, vector bool char);
18159 int vec_any_ne (vector unsigned char, vector unsigned char);
18160 int vec_any_ne (vector bool char, vector bool char);
18161 int vec_any_ne (vector bool char, vector unsigned char);
18162 int vec_any_ne (vector bool char, vector signed char);
18163 int vec_any_ne (vector signed short, vector bool short);
18164 int vec_any_ne (vector signed short, vector signed short);
18165 int vec_any_ne (vector unsigned short, vector bool short);
18166 int vec_any_ne (vector unsigned short, vector unsigned short);
18167 int vec_any_ne (vector bool short, vector bool short);
18168 int vec_any_ne (vector bool short, vector unsigned short);
18169 int vec_any_ne (vector bool short, vector signed short);
18170 int vec_any_ne (vector pixel, vector pixel);
18171 int vec_any_ne (vector signed int, vector bool int);
18172 int vec_any_ne (vector signed int, vector signed int);
18173 int vec_any_ne (vector unsigned int, vector bool int);
18174 int vec_any_ne (vector unsigned int, vector unsigned int);
18175 int vec_any_ne (vector bool int, vector bool int);
18176 int vec_any_ne (vector bool int, vector unsigned int);
18177 int vec_any_ne (vector bool int, vector signed int);
18178 int vec_any_ne (vector float, vector float);
18180 int vec_any_nge (vector float, vector float);
18182 int vec_any_ngt (vector float, vector float);
18184 int vec_any_nle (vector float, vector float);
18186 int vec_any_nlt (vector float, vector float);
18188 int vec_any_numeric (vector float);
18190 int vec_any_out (vector float, vector float);
18192 vector unsigned char vec_avg (vector unsigned char, vector unsigned char);
18193 vector signed char vec_avg (vector signed char, vector signed char);
18194 vector unsigned short vec_avg (vector unsigned short, vector unsigned short);
18195 vector signed short vec_avg (vector signed short, vector signed short);
18196 vector unsigned int vec_avg (vector unsigned int, vector unsigned int);
18197 vector signed int vec_avg (vector signed int, vector signed int);
18199 vector float vec_ceil (vector float);
18201 vector signed int vec_cmpb (vector float, vector float);
18203 vector bool char vec_cmpeq (vector bool char, vector bool char);
18204 vector bool short vec_cmpeq (vector bool short, vector bool short);
18205 vector bool int vec_cmpeq (vector bool int, vector bool int);
18206 vector bool char vec_cmpeq (vector signed char, vector signed char);
18207 vector bool char vec_cmpeq (vector unsigned char, vector unsigned char);
18208 vector bool short vec_cmpeq (vector signed short, vector signed short);
18209 vector bool short vec_cmpeq (vector unsigned short, vector unsigned short);
18210 vector bool int vec_cmpeq (vector signed int, vector signed int);
18211 vector bool int vec_cmpeq (vector unsigned int, vector unsigned int);
18212 vector bool int vec_cmpeq (vector float, vector float);
18214 vector bool int vec_cmpge (vector float, vector float);
18216 vector bool char vec_cmpgt (vector unsigned char, vector unsigned char);
18217 vector bool char vec_cmpgt (vector signed char, vector signed char);
18218 vector bool short vec_cmpgt (vector unsigned short, vector unsigned short);
18219 vector bool short vec_cmpgt (vector signed short, vector signed short);
18220 vector bool int vec_cmpgt (vector unsigned int, vector unsigned int);
18221 vector bool int vec_cmpgt (vector signed int, vector signed int);
18222 vector bool int vec_cmpgt (vector float, vector float);
18224 vector bool int vec_cmple (vector float, vector float);
18226 vector bool char vec_cmplt (vector unsigned char, vector unsigned char);
18227 vector bool char vec_cmplt (vector signed char, vector signed char);
18228 vector bool short vec_cmplt (vector unsigned short, vector unsigned short);
18229 vector bool short vec_cmplt (vector signed short, vector signed short);
18230 vector bool int vec_cmplt (vector unsigned int, vector unsigned int);
18231 vector bool int vec_cmplt (vector signed int, vector signed int);
18232 vector bool int vec_cmplt (vector float, vector float);
18234 vector float vec_cpsgn (vector float, vector float);
18236 vector float vec_ctf (vector unsigned int, const int);
18237 vector float vec_ctf (vector signed int, const int);
18239 vector signed int vec_cts (vector float, const int);
18241 vector unsigned int vec_ctu (vector float, const int);
18243 void vec_dss (const int);
18245 void vec_dssall (void);
18247 void vec_dst (const vector unsigned char *, int, const int);
18248 void vec_dst (const vector signed char *, int, const int);
18249 void vec_dst (const vector bool char *, int, const int);
18250 void vec_dst (const vector unsigned short *, int, const int);
18251 void vec_dst (const vector signed short *, int, const int);
18252 void vec_dst (const vector bool short *, int, const int);
18253 void vec_dst (const vector pixel *, int, const int);
18254 void vec_dst (const vector unsigned int *, int, const int);
18255 void vec_dst (const vector signed int *, int, const int);
18256 void vec_dst (const vector bool int *, int, const int);
18257 void vec_dst (const vector float *, int, const int);
18258 void vec_dst (const unsigned char *, int, const int);
18259 void vec_dst (const signed char *, int, const int);
18260 void vec_dst (const unsigned short *, int, const int);
18261 void vec_dst (const short *, int, const int);
18262 void vec_dst (const unsigned int *, int, const int);
18263 void vec_dst (const int *, int, const int);
18264 void vec_dst (const float *, int, const int);
18266 void vec_dstst (const vector unsigned char *, int, const int);
18267 void vec_dstst (const vector signed char *, int, const int);
18268 void vec_dstst (const vector bool char *, int, const int);
18269 void vec_dstst (const vector unsigned short *, int, const int);
18270 void vec_dstst (const vector signed short *, int, const int);
18271 void vec_dstst (const vector bool short *, int, const int);
18272 void vec_dstst (const vector pixel *, int, const int);
18273 void vec_dstst (const vector unsigned int *, int, const int);
18274 void vec_dstst (const vector signed int *, int, const int);
18275 void vec_dstst (const vector bool int *, int, const int);
18276 void vec_dstst (const vector float *, int, const int);
18277 void vec_dstst (const unsigned char *, int, const int);
18278 void vec_dstst (const signed char *, int, const int);
18279 void vec_dstst (const unsigned short *, int, const int);
18280 void vec_dstst (const short *, int, const int);
18281 void vec_dstst (const unsigned int *, int, const int);
18282 void vec_dstst (const int *, int, const int);
18283 void vec_dstst (const unsigned long *, int, const int);
18284 void vec_dstst (const long *, int, const int);
18285 void vec_dstst (const float *, int, const int);
18287 void vec_dststt (const vector unsigned char *, int, const int);
18288 void vec_dststt (const vector signed char *, int, const int);
18289 void vec_dststt (const vector bool char *, int, const int);
18290 void vec_dststt (const vector unsigned short *, int, const int);
18291 void vec_dststt (const vector signed short *, int, const int);
18292 void vec_dststt (const vector bool short *, int, const int);
18293 void vec_dststt (const vector pixel *, int, const int);
18294 void vec_dststt (const vector unsigned int *, int, const int);
18295 void vec_dststt (const vector signed int *, int, const int);
18296 void vec_dststt (const vector bool int *, int, const int);
18297 void vec_dststt (const vector float *, int, const int);
18298 void vec_dststt (const unsigned char *, int, const int);
18299 void vec_dststt (const signed char *, int, const int);
18300 void vec_dststt (const unsigned short *, int, const int);
18301 void vec_dststt (const short *, int, const int);
18302 void vec_dststt (const unsigned int *, int, const int);
18303 void vec_dststt (const int *, int, const int);
18304 void vec_dststt (const float *, int, const int);
18306 void vec_dstt (const vector unsigned char *, int, const int);
18307 void vec_dstt (const vector signed char *, int, const int);
18308 void vec_dstt (const vector bool char *, int, const int);
18309 void vec_dstt (const vector unsigned short *, int, const int);
18310 void vec_dstt (const vector signed short *, int, const int);
18311 void vec_dstt (const vector bool short *, int, const int);
18312 void vec_dstt (const vector pixel *, int, const int);
18313 void vec_dstt (const vector unsigned int *, int, const int);
18314 void vec_dstt (const vector signed int *, int, const int);
18315 void vec_dstt (const vector bool int *, int, const int);
18316 void vec_dstt (const vector float *, int, const int);
18317 void vec_dstt (const unsigned char *, int, const int);
18318 void vec_dstt (const signed char *, int, const int);
18319 void vec_dstt (const unsigned short *, int, const int);
18320 void vec_dstt (const short *, int, const int);
18321 void vec_dstt (const unsigned int *, int, const int);
18322 void vec_dstt (const int *, int, const int);
18323 void vec_dstt (const float *, int, const int);
18325 vector float vec_expte (vector float);
18327 vector float vec_floor (vector float);
18329 vector float vec_ld (int, const vector float *);
18330 vector float vec_ld (int, const float *);
18331 vector bool int vec_ld (int, const vector bool int *);
18332 vector signed int vec_ld (int, const vector signed int *);
18333 vector signed int vec_ld (int, const int *);
18334 vector unsigned int vec_ld (int, const vector unsigned int *);
18335 vector unsigned int vec_ld (int, const unsigned int *);
18336 vector bool short vec_ld (int, const vector bool short *);
18337 vector pixel vec_ld (int, const vector pixel *);
18338 vector signed short vec_ld (int, const vector signed short *);
18339 vector signed short vec_ld (int, const short *);
18340 vector unsigned short vec_ld (int, const vector unsigned short *);
18341 vector unsigned short vec_ld (int, const unsigned short *);
18342 vector bool char vec_ld (int, const vector bool char *);
18343 vector signed char vec_ld (int, const vector signed char *);
18344 vector signed char vec_ld (int, const signed char *);
18345 vector unsigned char vec_ld (int, const vector unsigned char *);
18346 vector unsigned char vec_ld (int, const unsigned char *);
18348 vector signed char vec_lde (int, const signed char *);
18349 vector unsigned char vec_lde (int, const unsigned char *);
18350 vector signed short vec_lde (int, const short *);
18351 vector unsigned short vec_lde (int, const unsigned short *);
18352 vector float vec_lde (int, const float *);
18353 vector signed int vec_lde (int, const int *);
18354 vector unsigned int vec_lde (int, const unsigned int *);
18356 vector float vec_ldl (int, const vector float *);
18357 vector float vec_ldl (int, const float *);
18358 vector bool int vec_ldl (int, const vector bool int *);
18359 vector signed int vec_ldl (int, const vector signed int *);
18360 vector signed int vec_ldl (int, const int *);
18361 vector unsigned int vec_ldl (int, const vector unsigned int *);
18362 vector unsigned int vec_ldl (int, const unsigned int *);
18363 vector bool short vec_ldl (int, const vector bool short *);
18364 vector pixel vec_ldl (int, const vector pixel *);
18365 vector signed short vec_ldl (int, const vector signed short *);
18366 vector signed short vec_ldl (int, const short *);
18367 vector unsigned short vec_ldl (int, const vector unsigned short *);
18368 vector unsigned short vec_ldl (int, const unsigned short *);
18369 vector bool char vec_ldl (int, const vector bool char *);
18370 vector signed char vec_ldl (int, const vector signed char *);
18371 vector signed char vec_ldl (int, const signed char *);
18372 vector unsigned char vec_ldl (int, const vector unsigned char *);
18373 vector unsigned char vec_ldl (int, const unsigned char *);
18375 vector float vec_loge (vector float);
18377 vector signed char vec_lvebx (int, char *);
18378 vector unsigned char vec_lvebx (int, unsigned char *);
18380 vector signed short vec_lvehx (int, short *);
18381 vector unsigned short vec_lvehx (int, unsigned short *);
18383 vector float vec_lvewx (int, float *);
18384 vector signed int vec_lvewx (int, int *);
18385 vector unsigned int vec_lvewx (int, unsigned int *);
18387 vector unsigned char vec_lvsl (int, const unsigned char *);
18388 vector unsigned char vec_lvsl (int, const signed char *);
18389 vector unsigned char vec_lvsl (int, const unsigned short *);
18390 vector unsigned char vec_lvsl (int, const short *);
18391 vector unsigned char vec_lvsl (int, const unsigned int *);
18392 vector unsigned char vec_lvsl (int, const int *);
18393 vector unsigned char vec_lvsl (int, const float *);
18395 vector unsigned char vec_lvsr (int, const unsigned char *);
18396 vector unsigned char vec_lvsr (int, const signed char *);
18397 vector unsigned char vec_lvsr (int, const unsigned short *);
18398 vector unsigned char vec_lvsr (int, const short *);
18399 vector unsigned char vec_lvsr (int, const unsigned int *);
18400 vector unsigned char vec_lvsr (int, const int *);
18401 vector unsigned char vec_lvsr (int, const float *);
18403 vector float vec_madd (vector float, vector float, vector float);
18405 vector signed short vec_madds (vector signed short, vector signed short,
18406 vector signed short);
18408 vector unsigned char vec_max (vector bool char, vector unsigned char);
18409 vector unsigned char vec_max (vector unsigned char, vector bool char);
18410 vector unsigned char vec_max (vector unsigned char, vector unsigned char);
18411 vector signed char vec_max (vector bool char, vector signed char);
18412 vector signed char vec_max (vector signed char, vector bool char);
18413 vector signed char vec_max (vector signed char, vector signed char);
18414 vector unsigned short vec_max (vector bool short, vector unsigned short);
18415 vector unsigned short vec_max (vector unsigned short, vector bool short);
18416 vector unsigned short vec_max (vector unsigned short, vector unsigned short);
18417 vector signed short vec_max (vector bool short, vector signed short);
18418 vector signed short vec_max (vector signed short, vector bool short);
18419 vector signed short vec_max (vector signed short, vector signed short);
18420 vector unsigned int vec_max (vector bool int, vector unsigned int);
18421 vector unsigned int vec_max (vector unsigned int, vector bool int);
18422 vector unsigned int vec_max (vector unsigned int, vector unsigned int);
18423 vector signed int vec_max (vector bool int, vector signed int);
18424 vector signed int vec_max (vector signed int, vector bool int);
18425 vector signed int vec_max (vector signed int, vector signed int);
18426 vector float vec_max (vector float, vector float);
18428 vector bool char vec_mergeh (vector bool char, vector bool char);
18429 vector signed char vec_mergeh (vector signed char, vector signed char);
18430 vector unsigned char vec_mergeh (vector unsigned char, vector unsigned char);
18431 vector bool short vec_mergeh (vector bool short, vector bool short);
18432 vector pixel vec_mergeh (vector pixel, vector pixel);
18433 vector signed short vec_mergeh (vector signed short, vector signed short);
18434 vector unsigned short vec_mergeh (vector unsigned short, vector unsigned short);
18435 vector float vec_mergeh (vector float, vector float);
18436 vector bool int vec_mergeh (vector bool int, vector bool int);
18437 vector signed int vec_mergeh (vector signed int, vector signed int);
18438 vector unsigned int vec_mergeh (vector unsigned int, vector unsigned int);
18440 vector bool char vec_mergel (vector bool char, vector bool char);
18441 vector signed char vec_mergel (vector signed char, vector signed char);
18442 vector unsigned char vec_mergel (vector unsigned char, vector unsigned char);
18443 vector bool short vec_mergel (vector bool short, vector bool short);
18444 vector pixel vec_mergel (vector pixel, vector pixel);
18445 vector signed short vec_mergel (vector signed short, vector signed short);
18446 vector unsigned short vec_mergel (vector unsigned short, vector unsigned short);
18447 vector float vec_mergel (vector float, vector float);
18448 vector bool int vec_mergel (vector bool int, vector bool int);
18449 vector signed int vec_mergel (vector signed int, vector signed int);
18450 vector unsigned int vec_mergel (vector unsigned int, vector unsigned int);
18452 vector unsigned short vec_mfvscr (void);
18454 vector unsigned char vec_min (vector bool char, vector unsigned char);
18455 vector unsigned char vec_min (vector unsigned char, vector bool char);
18456 vector unsigned char vec_min (vector unsigned char, vector unsigned char);
18457 vector signed char vec_min (vector bool char, vector signed char);
18458 vector signed char vec_min (vector signed char, vector bool char);
18459 vector signed char vec_min (vector signed char, vector signed char);
18460 vector unsigned short vec_min (vector bool short, vector unsigned short);
18461 vector unsigned short vec_min (vector unsigned short, vector bool short);
18462 vector unsigned short vec_min (vector unsigned short, vector unsigned short);
18463 vector signed short vec_min (vector bool short, vector signed short);
18464 vector signed short vec_min (vector signed short, vector bool short);
18465 vector signed short vec_min (vector signed short, vector signed short);
18466 vector unsigned int vec_min (vector bool int, vector unsigned int);
18467 vector unsigned int vec_min (vector unsigned int, vector bool int);
18468 vector unsigned int vec_min (vector unsigned int, vector unsigned int);
18469 vector signed int vec_min (vector bool int, vector signed int);
18470 vector signed int vec_min (vector signed int, vector bool int);
18471 vector signed int vec_min (vector signed int, vector signed int);
18472 vector float vec_min (vector float, vector float);
18474 vector signed short vec_mladd (vector signed short, vector signed short,
18475 vector signed short);
18476 vector signed short vec_mladd (vector signed short, vector unsigned short,
18477 vector unsigned short);
18478 vector signed short vec_mladd (vector unsigned short, vector signed short,
18479 vector signed short);
18480 vector unsigned short vec_mladd (vector unsigned short, vector unsigned short,
18481 vector unsigned short);
18483 vector signed short vec_mradds (vector signed short, vector signed short,
18484 vector signed short);
18486 vector unsigned int vec_msum (vector unsigned char, vector unsigned char,
18487 vector unsigned int);
18488 vector signed int vec_msum (vector signed char, vector unsigned char,
18489 vector signed int);
18490 vector unsigned int vec_msum (vector unsigned short, vector unsigned short,
18491 vector unsigned int);
18492 vector signed int vec_msum (vector signed short, vector signed short,
18493 vector signed int);
18495 vector unsigned int vec_msums (vector unsigned short, vector unsigned short,
18496 vector unsigned int);
18497 vector signed int vec_msums (vector signed short, vector signed short,
18498 vector signed int);
18500 void vec_mtvscr (vector signed int);
18501 void vec_mtvscr (vector unsigned int);
18502 void vec_mtvscr (vector bool int);
18503 void vec_mtvscr (vector signed short);
18504 void vec_mtvscr (vector unsigned short);
18505 void vec_mtvscr (vector bool short);
18506 void vec_mtvscr (vector pixel);
18507 void vec_mtvscr (vector signed char);
18508 void vec_mtvscr (vector unsigned char);
18509 void vec_mtvscr (vector bool char);
18511 vector float vec_mul (vector float, vector float);
18513 vector unsigned short vec_mule (vector unsigned char, vector unsigned char);
18514 vector signed short vec_mule (vector signed char, vector signed char);
18515 vector unsigned int vec_mule (vector unsigned short, vector unsigned short);
18516 vector signed int vec_mule (vector signed short, vector signed short);
18518 vector unsigned short vec_mulo (vector unsigned char, vector unsigned char);
18519 vector signed short vec_mulo (vector signed char, vector signed char);
18520 vector unsigned int vec_mulo (vector unsigned short, vector unsigned short);
18521 vector signed int vec_mulo (vector signed short, vector signed short);
18523 vector signed char vec_nabs (vector signed char);
18524 vector signed short vec_nabs (vector signed short);
18525 vector signed int vec_nabs (vector signed int);
18526 vector float vec_nabs (vector float);
18528 vector float vec_nmsub (vector float, vector float, vector float);
18530 vector float vec_nor (vector float, vector float);
18531 vector signed int vec_nor (vector signed int, vector signed int);
18532 vector unsigned int vec_nor (vector unsigned int, vector unsigned int);
18533 vector bool int vec_nor (vector bool int, vector bool int);
18534 vector signed short vec_nor (vector signed short, vector signed short);
18535 vector unsigned short vec_nor (vector unsigned short, vector unsigned short);
18536 vector bool short vec_nor (vector bool short, vector bool short);
18537 vector signed char vec_nor (vector signed char, vector signed char);
18538 vector unsigned char vec_nor (vector unsigned char, vector unsigned char);
18539 vector bool char vec_nor (vector bool char, vector bool char);
18541 vector float vec_or (vector float, vector float);
18542 vector float vec_or (vector float, vector bool int);
18543 vector float vec_or (vector bool int, vector float);
18544 vector bool int vec_or (vector bool int, vector bool int);
18545 vector signed int vec_or (vector bool int, vector signed int);
18546 vector signed int vec_or (vector signed int, vector bool int);
18547 vector signed int vec_or (vector signed int, vector signed int);
18548 vector unsigned int vec_or (vector bool int, vector unsigned int);
18549 vector unsigned int vec_or (vector unsigned int, vector bool int);
18550 vector unsigned int vec_or (vector unsigned int, vector unsigned int);
18551 vector bool short vec_or (vector bool short, vector bool short);
18552 vector signed short vec_or (vector bool short, vector signed short);
18553 vector signed short vec_or (vector signed short, vector bool short);
18554 vector signed short vec_or (vector signed short, vector signed short);
18555 vector unsigned short vec_or (vector bool short, vector unsigned short);
18556 vector unsigned short vec_or (vector unsigned short, vector bool short);
18557 vector unsigned short vec_or (vector unsigned short, vector unsigned short);
18558 vector signed char vec_or (vector bool char, vector signed char);
18559 vector bool char vec_or (vector bool char, vector bool char);
18560 vector signed char vec_or (vector signed char, vector bool char);
18561 vector signed char vec_or (vector signed char, vector signed char);
18562 vector unsigned char vec_or (vector bool char, vector unsigned char);
18563 vector unsigned char vec_or (vector unsigned char, vector bool char);
18564 vector unsigned char vec_or (vector unsigned char, vector unsigned char);
18566 vector signed char vec_pack (vector signed short, vector signed short);
18567 vector unsigned char vec_pack (vector unsigned short, vector unsigned short);
18568 vector bool char vec_pack (vector bool short, vector bool short);
18569 vector signed short vec_pack (vector signed int, vector signed int);
18570 vector unsigned short vec_pack (vector unsigned int, vector unsigned int);
18571 vector bool short vec_pack (vector bool int, vector bool int);
18573 vector pixel vec_packpx (vector unsigned int, vector unsigned int);
18575 vector unsigned char vec_packs (vector unsigned short, vector unsigned short);
18576 vector signed char vec_packs (vector signed short, vector signed short);
18577 vector unsigned short vec_packs (vector unsigned int, vector unsigned int);
18578 vector signed short vec_packs (vector signed int, vector signed int);
18580 vector unsigned char vec_packsu (vector unsigned short, vector unsigned short);
18581 vector unsigned char vec_packsu (vector signed short, vector signed short);
18582 vector unsigned short vec_packsu (vector unsigned int, vector unsigned int);
18583 vector unsigned short vec_packsu (vector signed int, vector signed int);
18585 vector float vec_perm (vector float, vector float, vector unsigned char);
18586 vector signed int vec_perm (vector signed int, vector signed int, vector unsigned char);
18587 vector unsigned int vec_perm (vector unsigned int, vector unsigned int,
18588 vector unsigned char);
18589 vector bool int vec_perm (vector bool int, vector bool int, vector unsigned char);
18590 vector signed short vec_perm (vector signed short, vector signed short,
18591 vector unsigned char);
18592 vector unsigned short vec_perm (vector unsigned short, vector unsigned short,
18593 vector unsigned char);
18594 vector bool short vec_perm (vector bool short, vector bool short, vector unsigned char);
18595 vector pixel vec_perm (vector pixel, vector pixel, vector unsigned char);
18596 vector signed char vec_perm (vector signed char, vector signed char,
18597 vector unsigned char);
18598 vector unsigned char vec_perm (vector unsigned char, vector unsigned char,
18599 vector unsigned char);
18600 vector bool char vec_perm (vector bool char, vector bool char, vector unsigned char);
18602 vector float vec_re (vector float);
18604 vector bool char vec_reve (vector bool char);
18605 vector signed char vec_reve (vector signed char);
18606 vector unsigned char vec_reve (vector unsigned char);
18607 vector bool int vec_reve (vector bool int);
18608 vector signed int vec_reve (vector signed int);
18609 vector unsigned int vec_reve (vector unsigned int);
18610 vector bool short vec_reve (vector bool short);
18611 vector signed short vec_reve (vector signed short);
18612 vector unsigned short vec_reve (vector unsigned short);
18614 vector signed char vec_rl (vector signed char, vector unsigned char);
18615 vector unsigned char vec_rl (vector unsigned char, vector unsigned char);
18616 vector signed short vec_rl (vector signed short, vector unsigned short);
18617 vector unsigned short vec_rl (vector unsigned short, vector unsigned short);
18618 vector signed int vec_rl (vector signed int, vector unsigned int);
18619 vector unsigned int vec_rl (vector unsigned int, vector unsigned int);
18621 vector float vec_round (vector float);
18623 vector float vec_rsqrt (vector float);
18625 vector float vec_rsqrte (vector float);
18627 vector float vec_sel (vector float, vector float, vector bool int);
18628 vector float vec_sel (vector float, vector float, vector unsigned int);
18629 vector signed int vec_sel (vector signed int, vector signed int, vector bool int);
18630 vector signed int vec_sel (vector signed int, vector signed int, vector unsigned int);
18631 vector unsigned int vec_sel (vector unsigned int, vector unsigned int, vector bool int);
18632 vector unsigned int vec_sel (vector unsigned int, vector unsigned int,
18633 vector unsigned int);
18634 vector bool int vec_sel (vector bool int, vector bool int, vector bool int);
18635 vector bool int vec_sel (vector bool int, vector bool int, vector unsigned int);
18636 vector signed short vec_sel (vector signed short, vector signed short,
18637 vector bool short);
18638 vector signed short vec_sel (vector signed short, vector signed short,
18639 vector unsigned short);
18640 vector unsigned short vec_sel (vector unsigned short, vector unsigned short,
18641 vector bool short);
18642 vector unsigned short vec_sel (vector unsigned short, vector unsigned short,
18643 vector unsigned short);
18644 vector bool short vec_sel (vector bool short, vector bool short, vector bool short);
18645 vector bool short vec_sel (vector bool short, vector bool short, vector unsigned short);
18646 vector signed char vec_sel (vector signed char, vector signed char, vector bool char);
18647 vector signed char vec_sel (vector signed char, vector signed char,
18648 vector unsigned char);
18649 vector unsigned char vec_sel (vector unsigned char, vector unsigned char,
18651 vector unsigned char vec_sel (vector unsigned char, vector unsigned char,
18652 vector unsigned char);
18653 vector bool char vec_sel (vector bool char, vector bool char, vector bool char);
18654 vector bool char vec_sel (vector bool char, vector bool char, vector unsigned char);
18656 vector signed char vec_sl (vector signed char, vector unsigned char);
18657 vector unsigned char vec_sl (vector unsigned char, vector unsigned char);
18658 vector signed short vec_sl (vector signed short, vector unsigned short);
18659 vector unsigned short vec_sl (vector unsigned short, vector unsigned short);
18660 vector signed int vec_sl (vector signed int, vector unsigned int);
18661 vector unsigned int vec_sl (vector unsigned int, vector unsigned int);
18663 vector float vec_sld (vector float, vector float, const int);
18664 vector signed int vec_sld (vector signed int, vector signed int, const int);
18665 vector unsigned int vec_sld (vector unsigned int, vector unsigned int, const int);
18666 vector bool int vec_sld (vector bool int, vector bool int, const int);
18667 vector signed short vec_sld (vector signed short, vector signed short, const int);
18668 vector unsigned short vec_sld (vector unsigned short, vector unsigned short, const int);
18669 vector bool short vec_sld (vector bool short, vector bool short, const int);
18670 vector pixel vec_sld (vector pixel, vector pixel, const int);
18671 vector signed char vec_sld (vector signed char, vector signed char, const int);
18672 vector unsigned char vec_sld (vector unsigned char, vector unsigned char, const int);
18673 vector bool char vec_sld (vector bool char, vector bool char, const int);
18675 vector signed int vec_sll (vector signed int, vector unsigned int);
18676 vector signed int vec_sll (vector signed int, vector unsigned short);
18677 vector signed int vec_sll (vector signed int, vector unsigned char);
18678 vector unsigned int vec_sll (vector unsigned int, vector unsigned int);
18679 vector unsigned int vec_sll (vector unsigned int, vector unsigned short);
18680 vector unsigned int vec_sll (vector unsigned int, vector unsigned char);
18681 vector bool int vec_sll (vector bool int, vector unsigned int);
18682 vector bool int vec_sll (vector bool int, vector unsigned short);
18683 vector bool int vec_sll (vector bool int, vector unsigned char);
18684 vector signed short vec_sll (vector signed short, vector unsigned int);
18685 vector signed short vec_sll (vector signed short, vector unsigned short);
18686 vector signed short vec_sll (vector signed short, vector unsigned char);
18687 vector unsigned short vec_sll (vector unsigned short, vector unsigned int);
18688 vector unsigned short vec_sll (vector unsigned short, vector unsigned short);
18689 vector unsigned short vec_sll (vector unsigned short, vector unsigned char);
18690 vector bool short vec_sll (vector bool short, vector unsigned int);
18691 vector bool short vec_sll (vector bool short, vector unsigned short);
18692 vector bool short vec_sll (vector bool short, vector unsigned char);
18693 vector pixel vec_sll (vector pixel, vector unsigned int);
18694 vector pixel vec_sll (vector pixel, vector unsigned short);
18695 vector pixel vec_sll (vector pixel, vector unsigned char);
18696 vector signed char vec_sll (vector signed char, vector unsigned int);
18697 vector signed char vec_sll (vector signed char, vector unsigned short);
18698 vector signed char vec_sll (vector signed char, vector unsigned char);
18699 vector unsigned char vec_sll (vector unsigned char, vector unsigned int);
18700 vector unsigned char vec_sll (vector unsigned char, vector unsigned short);
18701 vector unsigned char vec_sll (vector unsigned char, vector unsigned char);
18702 vector bool char vec_sll (vector bool char, vector unsigned int);
18703 vector bool char vec_sll (vector bool char, vector unsigned short);
18704 vector bool char vec_sll (vector bool char, vector unsigned char);
18706 vector float vec_slo (vector float, vector signed char);
18707 vector float vec_slo (vector float, vector unsigned char);
18708 vector signed int vec_slo (vector signed int, vector signed char);
18709 vector signed int vec_slo (vector signed int, vector unsigned char);
18710 vector unsigned int vec_slo (vector unsigned int, vector signed char);
18711 vector unsigned int vec_slo (vector unsigned int, vector unsigned char);
18712 vector signed short vec_slo (vector signed short, vector signed char);
18713 vector signed short vec_slo (vector signed short, vector unsigned char);
18714 vector unsigned short vec_slo (vector unsigned short, vector signed char);
18715 vector unsigned short vec_slo (vector unsigned short, vector unsigned char);
18716 vector pixel vec_slo (vector pixel, vector signed char);
18717 vector pixel vec_slo (vector pixel, vector unsigned char);
18718 vector signed char vec_slo (vector signed char, vector signed char);
18719 vector signed char vec_slo (vector signed char, vector unsigned char);
18720 vector unsigned char vec_slo (vector unsigned char, vector signed char);
18721 vector unsigned char vec_slo (vector unsigned char, vector unsigned char);
18723 vector signed char vec_splat (vector signed char, const int);
18724 vector unsigned char vec_splat (vector unsigned char, const int);
18725 vector bool char vec_splat (vector bool char, const int);
18726 vector signed short vec_splat (vector signed short, const int);
18727 vector unsigned short vec_splat (vector unsigned short, const int);
18728 vector bool short vec_splat (vector bool short, const int);
18729 vector pixel vec_splat (vector pixel, const int);
18730 vector float vec_splat (vector float, const int);
18731 vector signed int vec_splat (vector signed int, const int);
18732 vector unsigned int vec_splat (vector unsigned int, const int);
18733 vector bool int vec_splat (vector bool int, const int);
18735 vector signed short vec_splat_s16 (const int);
18737 vector signed int vec_splat_s32 (const int);
18739 vector signed char vec_splat_s8 (const int);
18741 vector unsigned short vec_splat_u16 (const int);
18743 vector unsigned int vec_splat_u32 (const int);
18745 vector unsigned char vec_splat_u8 (const int);
18747 vector signed char vec_splats (signed char);
18748 vector unsigned char vec_splats (unsigned char);
18749 vector signed short vec_splats (signed short);
18750 vector unsigned short vec_splats (unsigned short);
18751 vector signed int vec_splats (signed int);
18752 vector unsigned int vec_splats (unsigned int);
18753 vector float vec_splats (float);
18755 vector signed char vec_sr (vector signed char, vector unsigned char);
18756 vector unsigned char vec_sr (vector unsigned char, vector unsigned char);
18757 vector signed short vec_sr (vector signed short, vector unsigned short);
18758 vector unsigned short vec_sr (vector unsigned short, vector unsigned short);
18759 vector signed int vec_sr (vector signed int, vector unsigned int);
18760 vector unsigned int vec_sr (vector unsigned int, vector unsigned int);
18762 vector signed char vec_sra (vector signed char, vector unsigned char);
18763 vector unsigned char vec_sra (vector unsigned char, vector unsigned char);
18764 vector signed short vec_sra (vector signed short, vector unsigned short);
18765 vector unsigned short vec_sra (vector unsigned short, vector unsigned short);
18766 vector signed int vec_sra (vector signed int, vector unsigned int);
18767 vector unsigned int vec_sra (vector unsigned int, vector unsigned int);
18769 vector signed int vec_srl (vector signed int, vector unsigned int);
18770 vector signed int vec_srl (vector signed int, vector unsigned short);
18771 vector signed int vec_srl (vector signed int, vector unsigned char);
18772 vector unsigned int vec_srl (vector unsigned int, vector unsigned int);
18773 vector unsigned int vec_srl (vector unsigned int, vector unsigned short);
18774 vector unsigned int vec_srl (vector unsigned int, vector unsigned char);
18775 vector bool int vec_srl (vector bool int, vector unsigned int);
18776 vector bool int vec_srl (vector bool int, vector unsigned short);
18777 vector bool int vec_srl (vector bool int, vector unsigned char);
18778 vector signed short vec_srl (vector signed short, vector unsigned int);
18779 vector signed short vec_srl (vector signed short, vector unsigned short);
18780 vector signed short vec_srl (vector signed short, vector unsigned char);
18781 vector unsigned short vec_srl (vector unsigned short, vector unsigned int);
18782 vector unsigned short vec_srl (vector unsigned short, vector unsigned short);
18783 vector unsigned short vec_srl (vector unsigned short, vector unsigned char);
18784 vector bool short vec_srl (vector bool short, vector unsigned int);
18785 vector bool short vec_srl (vector bool short, vector unsigned short);
18786 vector bool short vec_srl (vector bool short, vector unsigned char);
18787 vector pixel vec_srl (vector pixel, vector unsigned int);
18788 vector pixel vec_srl (vector pixel, vector unsigned short);
18789 vector pixel vec_srl (vector pixel, vector unsigned char);
18790 vector signed char vec_srl (vector signed char, vector unsigned int);
18791 vector signed char vec_srl (vector signed char, vector unsigned short);
18792 vector signed char vec_srl (vector signed char, vector unsigned char);
18793 vector unsigned char vec_srl (vector unsigned char, vector unsigned int);
18794 vector unsigned char vec_srl (vector unsigned char, vector unsigned short);
18795 vector unsigned char vec_srl (vector unsigned char, vector unsigned char);
18796 vector bool char vec_srl (vector bool char, vector unsigned int);
18797 vector bool char vec_srl (vector bool char, vector unsigned short);
18798 vector bool char vec_srl (vector bool char, vector unsigned char);
18800 vector float vec_sro (vector float, vector signed char);
18801 vector float vec_sro (vector float, vector unsigned char);
18802 vector signed int vec_sro (vector signed int, vector signed char);
18803 vector signed int vec_sro (vector signed int, vector unsigned char);
18804 vector unsigned int vec_sro (vector unsigned int, vector signed char);
18805 vector unsigned int vec_sro (vector unsigned int, vector unsigned char);
18806 vector signed short vec_sro (vector signed short, vector signed char);
18807 vector signed short vec_sro (vector signed short, vector unsigned char);
18808 vector unsigned short vec_sro (vector unsigned short, vector signed char);
18809 vector unsigned short vec_sro (vector unsigned short, vector unsigned char);
18810 vector pixel vec_sro (vector pixel, vector signed char);
18811 vector pixel vec_sro (vector pixel, vector unsigned char);
18812 vector signed char vec_sro (vector signed char, vector signed char);
18813 vector signed char vec_sro (vector signed char, vector unsigned char);
18814 vector unsigned char vec_sro (vector unsigned char, vector signed char);
18815 vector unsigned char vec_sro (vector unsigned char, vector unsigned char);
18817 void vec_st (vector float, int, vector float *);
18818 void vec_st (vector float, int, float *);
18819 void vec_st (vector signed int, int, vector signed int *);
18820 void vec_st (vector signed int, int, int *);
18821 void vec_st (vector unsigned int, int, vector unsigned int *);
18822 void vec_st (vector unsigned int, int, unsigned int *);
18823 void vec_st (vector bool int, int, vector bool int *);
18824 void vec_st (vector bool int, int, unsigned int *);
18825 void vec_st (vector bool int, int, int *);
18826 void vec_st (vector signed short, int, vector signed short *);
18827 void vec_st (vector signed short, int, short *);
18828 void vec_st (vector unsigned short, int, vector unsigned short *);
18829 void vec_st (vector unsigned short, int, unsigned short *);
18830 void vec_st (vector bool short, int, vector bool short *);
18831 void vec_st (vector bool short, int, unsigned short *);
18832 void vec_st (vector pixel, int, vector pixel *);
18833 void vec_st (vector bool short, int, short *);
18834 void vec_st (vector signed char, int, vector signed char *);
18835 void vec_st (vector signed char, int, signed char *);
18836 void vec_st (vector unsigned char, int, vector unsigned char *);
18837 void vec_st (vector unsigned char, int, unsigned char *);
18838 void vec_st (vector bool char, int, vector bool char *);
18839 void vec_st (vector bool char, int, unsigned char *);
18840 void vec_st (vector bool char, int, signed char *);
18842 void vec_ste (vector signed char, int, signed char *);
18843 void vec_ste (vector unsigned char, int, unsigned char *);
18844 void vec_ste (vector bool char, int, signed char *);
18845 void vec_ste (vector bool char, int, unsigned char *);
18846 void vec_ste (vector signed short, int, short *);
18847 void vec_ste (vector unsigned short, int, unsigned short *);
18848 void vec_ste (vector bool short, int, short *);
18849 void vec_ste (vector bool short, int, unsigned short *);
18850 void vec_ste (vector pixel, int, short *);
18851 void vec_ste (vector pixel, int, unsigned short *);
18852 void vec_ste (vector float, int, float *);
18853 void vec_ste (vector signed int, int, int *);
18854 void vec_ste (vector unsigned int, int, unsigned int *);
18855 void vec_ste (vector bool int, int, int *);
18856 void vec_ste (vector bool int, int, unsigned int *);
18858 void vec_stl (vector float, int, vector float *);
18859 void vec_stl (vector float, int, float *);
18860 void vec_stl (vector signed int, int, vector signed int *);
18861 void vec_stl (vector signed int, int, int *);
18862 void vec_stl (vector unsigned int, int, vector unsigned int *);
18863 void vec_stl (vector unsigned int, int, unsigned int *);
18864 void vec_stl (vector bool int, int, vector bool int *);
18865 void vec_stl (vector bool int, int, unsigned int *);
18866 void vec_stl (vector bool int, int, int *);
18867 void vec_stl (vector signed short, int, vector signed short *);
18868 void vec_stl (vector signed short, int, short *);
18869 void vec_stl (vector unsigned short, int, vector unsigned short *);
18870 void vec_stl (vector unsigned short, int, unsigned short *);
18871 void vec_stl (vector bool short, int, vector bool short *);
18872 void vec_stl (vector bool short, int, unsigned short *);
18873 void vec_stl (vector bool short, int, short *);
18874 void vec_stl (vector pixel, int, vector pixel *);
18875 void vec_stl (vector signed char, int, vector signed char *);
18876 void vec_stl (vector signed char, int, signed char *);
18877 void vec_stl (vector unsigned char, int, vector unsigned char *);
18878 void vec_stl (vector unsigned char, int, unsigned char *);
18879 void vec_stl (vector bool char, int, vector bool char *);
18880 void vec_stl (vector bool char, int, unsigned char *);
18881 void vec_stl (vector bool char, int, signed char *);
18883 void vec_stvebx (vector signed char, int, signed char *);
18884 void vec_stvebx (vector unsigned char, int, unsigned char *);
18885 void vec_stvebx (vector bool char, int, signed char *);
18886 void vec_stvebx (vector bool char, int, unsigned char *);
18888 void vec_stvehx (vector signed short, int, short *);
18889 void vec_stvehx (vector unsigned short, int, unsigned short *);
18890 void vec_stvehx (vector bool short, int, short *);
18891 void vec_stvehx (vector bool short, int, unsigned short *);
18893 void vec_stvewx (vector float, int, float *);
18894 void vec_stvewx (vector signed int, int, int *);
18895 void vec_stvewx (vector unsigned int, int, unsigned int *);
18896 void vec_stvewx (vector bool int, int, int *);
18897 void vec_stvewx (vector bool int, int, unsigned int *);
18899 vector signed char vec_sub (vector bool char, vector signed char);
18900 vector signed char vec_sub (vector signed char, vector bool char);
18901 vector signed char vec_sub (vector signed char, vector signed char);
18902 vector unsigned char vec_sub (vector bool char, vector unsigned char);
18903 vector unsigned char vec_sub (vector unsigned char, vector bool char);
18904 vector unsigned char vec_sub (vector unsigned char, vector unsigned char);
18905 vector signed short vec_sub (vector bool short, vector signed short);
18906 vector signed short vec_sub (vector signed short, vector bool short);
18907 vector signed short vec_sub (vector signed short, vector signed short);
18908 vector unsigned short vec_sub (vector bool short, vector unsigned short);
18909 vector unsigned short vec_sub (vector unsigned short, vector bool short);
18910 vector unsigned short vec_sub (vector unsigned short, vector unsigned short);
18911 vector signed int vec_sub (vector bool int, vector signed int);
18912 vector signed int vec_sub (vector signed int, vector bool int);
18913 vector signed int vec_sub (vector signed int, vector signed int);
18914 vector unsigned int vec_sub (vector bool int, vector unsigned int);
18915 vector unsigned int vec_sub (vector unsigned int, vector bool int);
18916 vector unsigned int vec_sub (vector unsigned int, vector unsigned int);
18917 vector float vec_sub (vector float, vector float);
18919 vector signed int vec_subc (vector signed int, vector signed int);
18920 vector unsigned int vec_subc (vector unsigned int, vector unsigned int);
18922 vector signed int vec_sube (vector signed int, vector signed int,
18923 vector signed int);
18924 vector unsigned int vec_sube (vector unsigned int, vector unsigned int,
18925 vector unsigned int);
18927 vector signed int vec_subec (vector signed int, vector signed int,
18928 vector signed int);
18929 vector unsigned int vec_subec (vector unsigned int, vector unsigned int,
18930 vector unsigned int);
18932 vector unsigned char vec_subs (vector bool char, vector unsigned char);
18933 vector unsigned char vec_subs (vector unsigned char, vector bool char);
18934 vector unsigned char vec_subs (vector unsigned char, vector unsigned char);
18935 vector signed char vec_subs (vector bool char, vector signed char);
18936 vector signed char vec_subs (vector signed char, vector bool char);
18937 vector signed char vec_subs (vector signed char, vector signed char);
18938 vector unsigned short vec_subs (vector bool short, vector unsigned short);
18939 vector unsigned short vec_subs (vector unsigned short, vector bool short);
18940 vector unsigned short vec_subs (vector unsigned short, vector unsigned short);
18941 vector signed short vec_subs (vector bool short, vector signed short);
18942 vector signed short vec_subs (vector signed short, vector bool short);
18943 vector signed short vec_subs (vector signed short, vector signed short);
18944 vector unsigned int vec_subs (vector bool int, vector unsigned int);
18945 vector unsigned int vec_subs (vector unsigned int, vector bool int);
18946 vector unsigned int vec_subs (vector unsigned int, vector unsigned int);
18947 vector signed int vec_subs (vector bool int, vector signed int);
18948 vector signed int vec_subs (vector signed int, vector bool int);
18949 vector signed int vec_subs (vector signed int, vector signed int);
18951 vector signed int vec_sum2s (vector signed int, vector signed int);
18953 vector unsigned int vec_sum4s (vector unsigned char, vector unsigned int);
18954 vector signed int vec_sum4s (vector signed char, vector signed int);
18955 vector signed int vec_sum4s (vector signed short, vector signed int);
18957 vector signed int vec_sums (vector signed int, vector signed int);
18959 vector float vec_trunc (vector float);
18961 vector signed short vec_unpackh (vector signed char);
18962 vector bool short vec_unpackh (vector bool char);
18963 vector signed int vec_unpackh (vector signed short);
18964 vector bool int vec_unpackh (vector bool short);
18965 vector unsigned int vec_unpackh (vector pixel);
18967 vector signed short vec_unpackl (vector signed char);
18968 vector bool short vec_unpackl (vector bool char);
18969 vector unsigned int vec_unpackl (vector pixel);
18970 vector signed int vec_unpackl (vector signed short);
18971 vector bool int vec_unpackl (vector bool short);
18973 vector float vec_vaddfp (vector float, vector float);
18975 vector signed char vec_vaddsbs (vector bool char, vector signed char);
18976 vector signed char vec_vaddsbs (vector signed char, vector bool char);
18977 vector signed char vec_vaddsbs (vector signed char, vector signed char);
18979 vector signed short vec_vaddshs (vector bool short, vector signed short);
18980 vector signed short vec_vaddshs (vector signed short, vector bool short);
18981 vector signed short vec_vaddshs (vector signed short, vector signed short);
18983 vector signed int vec_vaddsws (vector bool int, vector signed int);
18984 vector signed int vec_vaddsws (vector signed int, vector bool int);
18985 vector signed int vec_vaddsws (vector signed int, vector signed int);
18987 vector signed char vec_vaddubm (vector bool char, vector signed char);
18988 vector signed char vec_vaddubm (vector signed char, vector bool char);
18989 vector signed char vec_vaddubm (vector signed char, vector signed char);
18990 vector unsigned char vec_vaddubm (vector bool char, vector unsigned char);
18991 vector unsigned char vec_vaddubm (vector unsigned char, vector bool char);
18992 vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char);
18994 vector unsigned char vec_vaddubs (vector bool char, vector unsigned char);
18995 vector unsigned char vec_vaddubs (vector unsigned char, vector bool char);
18996 vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char);
18998 vector signed short vec_vadduhm (vector bool short, vector signed short);
18999 vector signed short vec_vadduhm (vector signed short, vector bool short);
19000 vector signed short vec_vadduhm (vector signed short, vector signed short);
19001 vector unsigned short vec_vadduhm (vector bool short, vector unsigned short);
19002 vector unsigned short vec_vadduhm (vector unsigned short, vector bool short);
19003 vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short);
19005 vector unsigned short vec_vadduhs (vector bool short, vector unsigned short);
19006 vector unsigned short vec_vadduhs (vector unsigned short, vector bool short);
19007 vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short);
19009 vector signed int vec_vadduwm (vector bool int, vector signed int);
19010 vector signed int vec_vadduwm (vector signed int, vector bool int);
19011 vector signed int vec_vadduwm (vector signed int, vector signed int);
19012 vector unsigned int vec_vadduwm (vector bool int, vector unsigned int);
19013 vector unsigned int vec_vadduwm (vector unsigned int, vector bool int);
19014 vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int);
19016 vector unsigned int vec_vadduws (vector bool int, vector unsigned int);
19017 vector unsigned int vec_vadduws (vector unsigned int, vector bool int);
19018 vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int);
19020 vector signed char vec_vavgsb (vector signed char, vector signed char);
19022 vector signed short vec_vavgsh (vector signed short, vector signed short);
19024 vector signed int vec_vavgsw (vector signed int, vector signed int);
19026 vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char);
19028 vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short);
19030 vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int);
19032 vector float vec_vcfsx (vector signed int, const int);
19034 vector float vec_vcfux (vector unsigned int, const int);
19036 vector bool int vec_vcmpeqfp (vector float, vector float);
19038 vector bool char vec_vcmpequb (vector signed char, vector signed char);
19039 vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char);
19041 vector bool short vec_vcmpequh (vector signed short, vector signed short);
19042 vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short);
19044 vector bool int vec_vcmpequw (vector signed int, vector signed int);
19045 vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int);
19047 vector bool int vec_vcmpgtfp (vector float, vector float);
19049 vector bool char vec_vcmpgtsb (vector signed char, vector signed char);
19051 vector bool short vec_vcmpgtsh (vector signed short, vector signed short);
19053 vector bool int vec_vcmpgtsw (vector signed int, vector signed int);
19055 vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char);
19057 vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short);
19059 vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int);
19061 vector float vec_vmaxfp (vector float, vector float);
19063 vector signed char vec_vmaxsb (vector bool char, vector signed char);
19064 vector signed char vec_vmaxsb (vector signed char, vector bool char);
19065 vector signed char vec_vmaxsb (vector signed char, vector signed char);
19067 vector signed short vec_vmaxsh (vector bool short, vector signed short);
19068 vector signed short vec_vmaxsh (vector signed short, vector bool short);
19069 vector signed short vec_vmaxsh (vector signed short, vector signed short);
19071 vector signed int vec_vmaxsw (vector bool int, vector signed int);
19072 vector signed int vec_vmaxsw (vector signed int, vector bool int);
19073 vector signed int vec_vmaxsw (vector signed int, vector signed int);
19075 vector unsigned char vec_vmaxub (vector bool char, vector unsigned char);
19076 vector unsigned char vec_vmaxub (vector unsigned char, vector bool char);
19077 vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char);
19079 vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short);
19080 vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short);
19081 vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short);
19083 vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int);
19084 vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int);
19085 vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int);
19087 vector float vec_vminfp (vector float, vector float);
19089 vector signed char vec_vminsb (vector bool char, vector signed char);
19090 vector signed char vec_vminsb (vector signed char, vector bool char);
19091 vector signed char vec_vminsb (vector signed char, vector signed char);
19093 vector signed short vec_vminsh (vector bool short, vector signed short);
19094 vector signed short vec_vminsh (vector signed short, vector bool short);
19095 vector signed short vec_vminsh (vector signed short, vector signed short);
19097 vector signed int vec_vminsw (vector bool int, vector signed int);
19098 vector signed int vec_vminsw (vector signed int, vector bool int);
19099 vector signed int vec_vminsw (vector signed int, vector signed int);
19101 vector unsigned char vec_vminub (vector bool char, vector unsigned char);
19102 vector unsigned char vec_vminub (vector unsigned char, vector bool char);
19103 vector unsigned char vec_vminub (vector unsigned char, vector unsigned char);
19105 vector unsigned short vec_vminuh (vector bool short, vector unsigned short);
19106 vector unsigned short vec_vminuh (vector unsigned short, vector bool short);
19107 vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short);
19109 vector unsigned int vec_vminuw (vector bool int, vector unsigned int);
19110 vector unsigned int vec_vminuw (vector unsigned int, vector bool int);
19111 vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int);
19113 vector bool char vec_vmrghb (vector bool char, vector bool char);
19114 vector signed char vec_vmrghb (vector signed char, vector signed char);
19115 vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char);
19117 vector bool short vec_vmrghh (vector bool short, vector bool short);
19118 vector signed short vec_vmrghh (vector signed short, vector signed short);
19119 vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short);
19120 vector pixel vec_vmrghh (vector pixel, vector pixel);
19122 vector float vec_vmrghw (vector float, vector float);
19123 vector bool int vec_vmrghw (vector bool int, vector bool int);
19124 vector signed int vec_vmrghw (vector signed int, vector signed int);
19125 vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int);
19127 vector bool char vec_vmrglb (vector bool char, vector bool char);
19128 vector signed char vec_vmrglb (vector signed char, vector signed char);
19129 vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char);
19131 vector bool short vec_vmrglh (vector bool short, vector bool short);
19132 vector signed short vec_vmrglh (vector signed short, vector signed short);
19133 vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short);
19134 vector pixel vec_vmrglh (vector pixel, vector pixel);
19136 vector float vec_vmrglw (vector float, vector float);
19137 vector signed int vec_vmrglw (vector signed int, vector signed int);
19138 vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int);
19139 vector bool int vec_vmrglw (vector bool int, vector bool int);
19141 vector signed int vec_vmsummbm (vector signed char, vector unsigned char,
19142 vector signed int);
19144 vector signed int vec_vmsumshm (vector signed short, vector signed short,
19145 vector signed int);
19147 vector signed int vec_vmsumshs (vector signed short, vector signed short,
19148 vector signed int);
19150 vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char,
19151 vector unsigned int);
19153 vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short,
19154 vector unsigned int);
19156 vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short,
19157 vector unsigned int);
19159 vector signed short vec_vmulesb (vector signed char, vector signed char);
19161 vector signed int vec_vmulesh (vector signed short, vector signed short);
19163 vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char);
19165 vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short);
19167 vector signed short vec_vmulosb (vector signed char, vector signed char);
19169 vector signed int vec_vmulosh (vector signed short, vector signed short);
19171 vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char);
19173 vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short);
19175 vector signed char vec_vpkshss (vector signed short, vector signed short);
19177 vector unsigned char vec_vpkshus (vector signed short, vector signed short);
19179 vector signed short vec_vpkswss (vector signed int, vector signed int);
19181 vector unsigned short vec_vpkswus (vector signed int, vector signed int);
19183 vector bool char vec_vpkuhum (vector bool short, vector bool short);
19184 vector signed char vec_vpkuhum (vector signed short, vector signed short);
19185 vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short);
19187 vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short);
19189 vector bool short vec_vpkuwum (vector bool int, vector bool int);
19190 vector signed short vec_vpkuwum (vector signed int, vector signed int);
19191 vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int);
19193 vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int);
19195 vector signed char vec_vrlb (vector signed char, vector unsigned char);
19196 vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char);
19198 vector signed short vec_vrlh (vector signed short, vector unsigned short);
19199 vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short);
19201 vector signed int vec_vrlw (vector signed int, vector unsigned int);
19202 vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int);
19204 vector signed char vec_vslb (vector signed char, vector unsigned char);
19205 vector unsigned char vec_vslb (vector unsigned char, vector unsigned char);
19207 vector signed short vec_vslh (vector signed short, vector unsigned short);
19208 vector unsigned short vec_vslh (vector unsigned short, vector unsigned short);
19210 vector signed int vec_vslw (vector signed int, vector unsigned int);
19211 vector unsigned int vec_vslw (vector unsigned int, vector unsigned int);
19213 vector signed char vec_vspltb (vector signed char, const int);
19214 vector unsigned char vec_vspltb (vector unsigned char, const int);
19215 vector bool char vec_vspltb (vector bool char, const int);
19217 vector bool short vec_vsplth (vector bool short, const int);
19218 vector signed short vec_vsplth (vector signed short, const int);
19219 vector unsigned short vec_vsplth (vector unsigned short, const int);
19220 vector pixel vec_vsplth (vector pixel, const int);
19222 vector float vec_vspltw (vector float, const int);
19223 vector signed int vec_vspltw (vector signed int, const int);
19224 vector unsigned int vec_vspltw (vector unsigned int, const int);
19225 vector bool int vec_vspltw (vector bool int, const int);
19227 vector signed char vec_vsrab (vector signed char, vector unsigned char);
19228 vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char);
19230 vector signed short vec_vsrah (vector signed short, vector unsigned short);
19231 vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short);
19233 vector signed int vec_vsraw (vector signed int, vector unsigned int);
19234 vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int);
19236 vector signed char vec_vsrb (vector signed char, vector unsigned char);
19237 vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char);
19239 vector signed short vec_vsrh (vector signed short, vector unsigned short);
19240 vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short);
19242 vector signed int vec_vsrw (vector signed int, vector unsigned int);
19243 vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int);
19245 vector float vec_vsubfp (vector float, vector float);
19247 vector signed char vec_vsubsbs (vector bool char, vector signed char);
19248 vector signed char vec_vsubsbs (vector signed char, vector bool char);
19249 vector signed char vec_vsubsbs (vector signed char, vector signed char);
19251 vector signed short vec_vsubshs (vector bool short, vector signed short);
19252 vector signed short vec_vsubshs (vector signed short, vector bool short);
19253 vector signed short vec_vsubshs (vector signed short, vector signed short);
19255 vector signed int vec_vsubsws (vector bool int, vector signed int);
19256 vector signed int vec_vsubsws (vector signed int, vector bool int);
19257 vector signed int vec_vsubsws (vector signed int, vector signed int);
19259 vector signed char vec_vsububm (vector bool char, vector signed char);
19260 vector signed char vec_vsububm (vector signed char, vector bool char);
19261 vector signed char vec_vsububm (vector signed char, vector signed char);
19262 vector unsigned char vec_vsububm (vector bool char, vector unsigned char);
19263 vector unsigned char vec_vsububm (vector unsigned char, vector bool char);
19264 vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char);
19266 vector unsigned char vec_vsububs (vector bool char, vector unsigned char);
19267 vector unsigned char vec_vsububs (vector unsigned char, vector bool char);
19268 vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char);
19270 vector signed short vec_vsubuhm (vector bool short, vector signed short);
19271 vector signed short vec_vsubuhm (vector signed short, vector bool short);
19272 vector signed short vec_vsubuhm (vector signed short, vector signed short);
19273 vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short);
19274 vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short);
19275 vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short);
19277 vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short);
19278 vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short);
19279 vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short);
19281 vector signed int vec_vsubuwm (vector bool int, vector signed int);
19282 vector signed int vec_vsubuwm (vector signed int, vector bool int);
19283 vector signed int vec_vsubuwm (vector signed int, vector signed int);
19284 vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int);
19285 vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int);
19286 vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int);
19288 vector unsigned int vec_vsubuws (vector bool int, vector unsigned int);
19289 vector unsigned int vec_vsubuws (vector unsigned int, vector bool int);
19290 vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int);
19292 vector signed int vec_vsum4sbs (vector signed char, vector signed int);
19294 vector signed int vec_vsum4shs (vector signed short, vector signed int);
19296 vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int);
19298 vector unsigned int vec_vupkhpx (vector pixel);
19300 vector bool short vec_vupkhsb (vector bool char);
19301 vector signed short vec_vupkhsb (vector signed char);
19303 vector bool int vec_vupkhsh (vector bool short);
19304 vector signed int vec_vupkhsh (vector signed short);
19306 vector unsigned int vec_vupklpx (vector pixel);
19308 vector bool short vec_vupklsb (vector bool char);
19309 vector signed short vec_vupklsb (vector signed char);
19311 vector bool int vec_vupklsh (vector bool short);
19312 vector signed int vec_vupklsh (vector signed short);
19314 vector float vec_xor (vector float, vector float);
19315 vector float vec_xor (vector float, vector bool int);
19316 vector float vec_xor (vector bool int, vector float);
19317 vector bool int vec_xor (vector bool int, vector bool int);
19318 vector signed int vec_xor (vector bool int, vector signed int);
19319 vector signed int vec_xor (vector signed int, vector bool int);
19320 vector signed int vec_xor (vector signed int, vector signed int);
19321 vector unsigned int vec_xor (vector bool int, vector unsigned int);
19322 vector unsigned int vec_xor (vector unsigned int, vector bool int);
19323 vector unsigned int vec_xor (vector unsigned int, vector unsigned int);
19324 vector bool short vec_xor (vector bool short, vector bool short);
19325 vector signed short vec_xor (vector bool short, vector signed short);
19326 vector signed short vec_xor (vector signed short, vector bool short);
19327 vector signed short vec_xor (vector signed short, vector signed short);
19328 vector unsigned short vec_xor (vector bool short, vector unsigned short);
19329 vector unsigned short vec_xor (vector unsigned short, vector bool short);
19330 vector unsigned short vec_xor (vector unsigned short, vector unsigned short);
19331 vector signed char vec_xor (vector bool char, vector signed char);
19332 vector bool char vec_xor (vector bool char, vector bool char);
19333 vector signed char vec_xor (vector signed char, vector bool char);
19334 vector signed char vec_xor (vector signed char, vector signed char);
19335 vector unsigned char vec_xor (vector bool char, vector unsigned char);
19336 vector unsigned char vec_xor (vector unsigned char, vector bool char);
19337 vector unsigned char vec_xor (vector unsigned char, vector unsigned char);
19340 @node PowerPC AltiVec Built-in Functions Available on ISA 2.06
19341 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06
19343 The AltiVec built-in functions described in this section are
19344 available on the PowerPC family of processors starting with ISA 2.06
19345 or later. These are normally enabled by adding @option{-mvsx} to the
19348 When @option{-mvsx} is used, the following additional vector types are
19352 vector unsigned __int128
19353 vector signed __int128
19354 vector unsigned long long int
19355 vector signed long long int
19359 The long long types are only implemented for 64-bit code generation.
19363 vector bool long long vec_and (vector bool long long int, vector bool long long);
19365 vector double vec_ctf (vector unsigned long, const int);
19366 vector double vec_ctf (vector signed long, const int);
19368 vector signed long vec_cts (vector double, const int);
19370 vector unsigned long vec_ctu (vector double, const int);
19372 void vec_dst (const unsigned long *, int, const int);
19373 void vec_dst (const long *, int, const int);
19375 void vec_dststt (const unsigned long *, int, const int);
19376 void vec_dststt (const long *, int, const int);
19378 void vec_dstt (const unsigned long *, int, const int);
19379 void vec_dstt (const long *, int, const int);
19381 vector unsigned char vec_lvsl (int, const unsigned long *);
19382 vector unsigned char vec_lvsl (int, const long *);
19384 vector unsigned char vec_lvsr (int, const unsigned long *);
19385 vector unsigned char vec_lvsr (int, const long *);
19387 vector double vec_mul (vector double, vector double);
19388 vector long vec_mul (vector long, vector long);
19389 vector unsigned long vec_mul (vector unsigned long, vector unsigned long);
19391 vector unsigned long long vec_mule (vector unsigned int, vector unsigned int);
19392 vector signed long long vec_mule (vector signed int, vector signed int);
19394 vector unsigned long long vec_mulo (vector unsigned int, vector unsigned int);
19395 vector signed long long vec_mulo (vector signed int, vector signed int);
19397 vector double vec_nabs (vector double);
19399 vector bool long long vec_reve (vector bool long long);
19400 vector signed long long vec_reve (vector signed long long);
19401 vector unsigned long long vec_reve (vector unsigned long long);
19402 vector double vec_sld (vector double, vector double, const int);
19404 vector bool long long int vec_sld (vector bool long long int,
19405 vector bool long long int, const int);
19406 vector long long int vec_sld (vector long long int, vector long long int, const int);
19407 vector unsigned long long int vec_sld (vector unsigned long long int,
19408 vector unsigned long long int, const int);
19410 vector long long int vec_sll (vector long long int, vector unsigned char);
19411 vector unsigned long long int vec_sll (vector unsigned long long int,
19412 vector unsigned char);
19414 vector signed long long vec_slo (vector signed long long, vector signed char);
19415 vector signed long long vec_slo (vector signed long long, vector unsigned char);
19416 vector unsigned long long vec_slo (vector unsigned long long, vector signed char);
19417 vector unsigned long long vec_slo (vector unsigned long long, vector unsigned char);
19419 vector signed long vec_splat (vector signed long, const int);
19420 vector unsigned long vec_splat (vector unsigned long, const int);
19422 vector long long int vec_srl (vector long long int, vector unsigned char);
19423 vector unsigned long long int vec_srl (vector unsigned long long int,
19424 vector unsigned char);
19426 vector long long int vec_sro (vector long long int, vector char);
19427 vector long long int vec_sro (vector long long int, vector unsigned char);
19428 vector unsigned long long int vec_sro (vector unsigned long long int, vector char);
19429 vector unsigned long long int vec_sro (vector unsigned long long int,
19430 vector unsigned char);
19432 vector signed __int128 vec_subc (vector signed __int128, vector signed __int128);
19433 vector unsigned __int128 vec_subc (vector unsigned __int128, vector unsigned __int128);
19435 vector signed __int128 vec_sube (vector signed __int128, vector signed __int128,
19436 vector signed __int128);
19437 vector unsigned __int128 vec_sube (vector unsigned __int128, vector unsigned __int128,
19438 vector unsigned __int128);
19440 vector signed __int128 vec_subec (vector signed __int128, vector signed __int128,
19441 vector signed __int128);
19442 vector unsigned __int128 vec_subec (vector unsigned __int128, vector unsigned __int128,
19443 vector unsigned __int128);
19445 vector double vec_unpackh (vector float);
19447 vector double vec_unpackl (vector float);
19449 vector double vec_doublee (vector float);
19450 vector double vec_doublee (vector signed int);
19451 vector double vec_doublee (vector unsigned int);
19453 vector double vec_doubleo (vector float);
19454 vector double vec_doubleo (vector signed int);
19455 vector double vec_doubleo (vector unsigned int);
19457 vector double vec_doubleh (vector float);
19458 vector double vec_doubleh (vector signed int);
19459 vector double vec_doubleh (vector unsigned int);
19461 vector double vec_doublel (vector float);
19462 vector double vec_doublel (vector signed int);
19463 vector double vec_doublel (vector unsigned int);
19465 vector float vec_float (vector signed int);
19466 vector float vec_float (vector unsigned int);
19468 vector float vec_float2 (vector signed long long, vector signed long long);
19469 vector float vec_float2 (vector unsigned long long, vector signed long long);
19471 vector float vec_floate (vector double);
19472 vector float vec_floate (vector signed long long);
19473 vector float vec_floate (vector unsigned long long);
19475 vector float vec_floato (vector double);
19476 vector float vec_floato (vector signed long long);
19477 vector float vec_floato (vector unsigned long long);
19479 vector signed long long vec_signed (vector double);
19480 vector signed int vec_signed (vector float);
19482 vector signed int vec_signede (vector double);
19484 vector signed int vec_signedo (vector double);
19486 vector signed char vec_sldw (vector signed char, vector signed char, const int);
19487 vector unsigned char vec_sldw (vector unsigned char, vector unsigned char, const int);
19488 vector signed short vec_sldw (vector signed short, vector signed short, const int);
19489 vector unsigned short vec_sldw (vector unsigned short,
19490 vector unsigned short, const int);
19491 vector signed int vec_sldw (vector signed int, vector signed int, const int);
19492 vector unsigned int vec_sldw (vector unsigned int, vector unsigned int, const int);
19493 vector signed long long vec_sldw (vector signed long long,
19494 vector signed long long, const int);
19495 vector unsigned long long vec_sldw (vector unsigned long long,
19496 vector unsigned long long, const int);
19498 vector signed long long vec_unsigned (vector double);
19499 vector signed int vec_unsigned (vector float);
19501 vector signed int vec_unsignede (vector double);
19503 vector signed int vec_unsignedo (vector double);
19505 vector double vec_abs (vector double);
19506 vector double vec_add (vector double, vector double);
19507 vector double vec_and (vector double, vector double);
19508 vector double vec_and (vector double, vector bool long);
19509 vector double vec_and (vector bool long, vector double);
19510 vector long vec_and (vector long, vector long);
19511 vector long vec_and (vector long, vector bool long);
19512 vector long vec_and (vector bool long, vector long);
19513 vector unsigned long vec_and (vector unsigned long, vector unsigned long);
19514 vector unsigned long vec_and (vector unsigned long, vector bool long);
19515 vector unsigned long vec_and (vector bool long, vector unsigned long);
19516 vector double vec_andc (vector double, vector double);
19517 vector double vec_andc (vector double, vector bool long);
19518 vector double vec_andc (vector bool long, vector double);
19519 vector long vec_andc (vector long, vector long);
19520 vector long vec_andc (vector long, vector bool long);
19521 vector long vec_andc (vector bool long, vector long);
19522 vector unsigned long vec_andc (vector unsigned long, vector unsigned long);
19523 vector unsigned long vec_andc (vector unsigned long, vector bool long);
19524 vector unsigned long vec_andc (vector bool long, vector unsigned long);
19525 vector double vec_ceil (vector double);
19526 vector bool long vec_cmpeq (vector double, vector double);
19527 vector bool long vec_cmpge (vector double, vector double);
19528 vector bool long vec_cmpgt (vector double, vector double);
19529 vector bool long vec_cmple (vector double, vector double);
19530 vector bool long vec_cmplt (vector double, vector double);
19531 vector double vec_cpsgn (vector double, vector double);
19532 vector float vec_div (vector float, vector float);
19533 vector double vec_div (vector double, vector double);
19534 vector long vec_div (vector long, vector long);
19535 vector unsigned long vec_div (vector unsigned long, vector unsigned long);
19536 vector double vec_floor (vector double);
19537 vector signed long long vec_ld (int, const vector signed long long *);
19538 vector signed long long vec_ld (int, const signed long long *);
19539 vector unsigned long long vec_ld (int, const vector unsigned long long *);
19540 vector unsigned long long vec_ld (int, const unsigned long long *);
19541 vector __int128 vec_ld (int, const vector __int128 *);
19542 vector unsigned __int128 vec_ld (int, const vector unsigned __int128 *);
19543 vector __int128 vec_ld (int, const __int128 *);
19544 vector unsigned __int128 vec_ld (int, const unsigned __int128 *);
19545 vector double vec_ld (int, const vector double *);
19546 vector double vec_ld (int, const double *);
19547 vector double vec_ldl (int, const vector double *);
19548 vector double vec_ldl (int, const double *);
19549 vector unsigned char vec_lvsl (int, const double *);
19550 vector unsigned char vec_lvsr (int, const double *);
19551 vector double vec_madd (vector double, vector double, vector double);
19552 vector double vec_max (vector double, vector double);
19553 vector signed long vec_mergeh (vector signed long, vector signed long);
19554 vector signed long vec_mergeh (vector signed long, vector bool long);
19555 vector signed long vec_mergeh (vector bool long, vector signed long);
19556 vector unsigned long vec_mergeh (vector unsigned long, vector unsigned long);
19557 vector unsigned long vec_mergeh (vector unsigned long, vector bool long);
19558 vector unsigned long vec_mergeh (vector bool long, vector unsigned long);
19559 vector signed long vec_mergel (vector signed long, vector signed long);
19560 vector signed long vec_mergel (vector signed long, vector bool long);
19561 vector signed long vec_mergel (vector bool long, vector signed long);
19562 vector unsigned long vec_mergel (vector unsigned long, vector unsigned long);
19563 vector unsigned long vec_mergel (vector unsigned long, vector bool long);
19564 vector unsigned long vec_mergel (vector bool long, vector unsigned long);
19565 vector double vec_min (vector double, vector double);
19566 vector float vec_msub (vector float, vector float, vector float);
19567 vector double vec_msub (vector double, vector double, vector double);
19568 vector float vec_nearbyint (vector float);
19569 vector double vec_nearbyint (vector double);
19570 vector float vec_nmadd (vector float, vector float, vector float);
19571 vector double vec_nmadd (vector double, vector double, vector double);
19572 vector double vec_nmsub (vector double, vector double, vector double);
19573 vector double vec_nor (vector double, vector double);
19574 vector long vec_nor (vector long, vector long);
19575 vector long vec_nor (vector long, vector bool long);
19576 vector long vec_nor (vector bool long, vector long);
19577 vector unsigned long vec_nor (vector unsigned long, vector unsigned long);
19578 vector unsigned long vec_nor (vector unsigned long, vector bool long);
19579 vector unsigned long vec_nor (vector bool long, vector unsigned long);
19580 vector double vec_or (vector double, vector double);
19581 vector double vec_or (vector double, vector bool long);
19582 vector double vec_or (vector bool long, vector double);
19583 vector long vec_or (vector long, vector long);
19584 vector long vec_or (vector long, vector bool long);
19585 vector long vec_or (vector bool long, vector long);
19586 vector unsigned long vec_or (vector unsigned long, vector unsigned long);
19587 vector unsigned long vec_or (vector unsigned long, vector bool long);
19588 vector unsigned long vec_or (vector bool long, vector unsigned long);
19589 vector double vec_perm (vector double, vector double, vector unsigned char);
19590 vector long vec_perm (vector long, vector long, vector unsigned char);
19591 vector unsigned long vec_perm (vector unsigned long, vector unsigned long,
19592 vector unsigned char);
19593 vector bool char vec_permxor (vector bool char, vector bool char,
19595 vector unsigned char vec_permxor (vector signed char, vector signed char,
19596 vector signed char);
19597 vector unsigned char vec_permxor (vector unsigned char, vector unsigned char,
19598 vector unsigned char);
19599 vector double vec_rint (vector double);
19600 vector double vec_recip (vector double, vector double);
19601 vector double vec_rsqrt (vector double);
19602 vector double vec_rsqrte (vector double);
19603 vector double vec_sel (vector double, vector double, vector bool long);
19604 vector double vec_sel (vector double, vector double, vector unsigned long);
19605 vector long vec_sel (vector long, vector long, vector long);
19606 vector long vec_sel (vector long, vector long, vector unsigned long);
19607 vector long vec_sel (vector long, vector long, vector bool long);
19608 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19610 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19611 vector unsigned long);
19612 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19614 vector double vec_splats (double);
19615 vector signed long vec_splats (signed long);
19616 vector unsigned long vec_splats (unsigned long);
19617 vector float vec_sqrt (vector float);
19618 vector double vec_sqrt (vector double);
19619 void vec_st (vector signed long long, int, vector signed long long *);
19620 void vec_st (vector signed long long, int, signed long long *);
19621 void vec_st (vector unsigned long long, int, vector unsigned long long *);
19622 void vec_st (vector unsigned long long, int, unsigned long long *);
19623 void vec_st (vector bool long long, int, vector bool long long *);
19624 void vec_st (vector bool long long, int, signed long long *);
19625 void vec_st (vector bool long long, int, unsigned long long *);
19626 void vec_st (vector double, int, vector double *);
19627 void vec_st (vector double, int, double *);
19628 vector double vec_sub (vector double, vector double);
19629 vector double vec_trunc (vector double);
19630 vector double vec_xl (int, vector double *);
19631 vector double vec_xl (int, double *);
19632 vector long long vec_xl (int, vector long long *);
19633 vector long long vec_xl (int, long long *);
19634 vector unsigned long long vec_xl (int, vector unsigned long long *);
19635 vector unsigned long long vec_xl (int, unsigned long long *);
19636 vector float vec_xl (int, vector float *);
19637 vector float vec_xl (int, float *);
19638 vector int vec_xl (int, vector int *);
19639 vector int vec_xl (int, int *);
19640 vector unsigned int vec_xl (int, vector unsigned int *);
19641 vector unsigned int vec_xl (int, unsigned int *);
19642 vector double vec_xor (vector double, vector double);
19643 vector double vec_xor (vector double, vector bool long);
19644 vector double vec_xor (vector bool long, vector double);
19645 vector long vec_xor (vector long, vector long);
19646 vector long vec_xor (vector long, vector bool long);
19647 vector long vec_xor (vector bool long, vector long);
19648 vector unsigned long vec_xor (vector unsigned long, vector unsigned long);
19649 vector unsigned long vec_xor (vector unsigned long, vector bool long);
19650 vector unsigned long vec_xor (vector bool long, vector unsigned long);
19651 void vec_xst (vector double, int, vector double *);
19652 void vec_xst (vector double, int, double *);
19653 void vec_xst (vector long long, int, vector long long *);
19654 void vec_xst (vector long long, int, long long *);
19655 void vec_xst (vector unsigned long long, int, vector unsigned long long *);
19656 void vec_xst (vector unsigned long long, int, unsigned long long *);
19657 void vec_xst (vector float, int, vector float *);
19658 void vec_xst (vector float, int, float *);
19659 void vec_xst (vector int, int, vector int *);
19660 void vec_xst (vector int, int, int *);
19661 void vec_xst (vector unsigned int, int, vector unsigned int *);
19662 void vec_xst (vector unsigned int, int, unsigned int *);
19663 int vec_all_eq (vector double, vector double);
19664 int vec_all_ge (vector double, vector double);
19665 int vec_all_gt (vector double, vector double);
19666 int vec_all_le (vector double, vector double);
19667 int vec_all_lt (vector double, vector double);
19668 int vec_all_nan (vector double);
19669 int vec_all_ne (vector double, vector double);
19670 int vec_all_nge (vector double, vector double);
19671 int vec_all_ngt (vector double, vector double);
19672 int vec_all_nle (vector double, vector double);
19673 int vec_all_nlt (vector double, vector double);
19674 int vec_all_numeric (vector double);
19675 int vec_any_eq (vector double, vector double);
19676 int vec_any_ge (vector double, vector double);
19677 int vec_any_gt (vector double, vector double);
19678 int vec_any_le (vector double, vector double);
19679 int vec_any_lt (vector double, vector double);
19680 int vec_any_nan (vector double);
19681 int vec_any_ne (vector double, vector double);
19682 int vec_any_nge (vector double, vector double);
19683 int vec_any_ngt (vector double, vector double);
19684 int vec_any_nle (vector double, vector double);
19685 int vec_any_nlt (vector double, vector double);
19686 int vec_any_numeric (vector double);
19688 vector double vec_vsx_ld (int, const vector double *);
19689 vector double vec_vsx_ld (int, const double *);
19690 vector float vec_vsx_ld (int, const vector float *);
19691 vector float vec_vsx_ld (int, const float *);
19692 vector bool int vec_vsx_ld (int, const vector bool int *);
19693 vector signed int vec_vsx_ld (int, const vector signed int *);
19694 vector signed int vec_vsx_ld (int, const int *);
19695 vector signed int vec_vsx_ld (int, const long *);
19696 vector unsigned int vec_vsx_ld (int, const vector unsigned int *);
19697 vector unsigned int vec_vsx_ld (int, const unsigned int *);
19698 vector unsigned int vec_vsx_ld (int, const unsigned long *);
19699 vector bool short vec_vsx_ld (int, const vector bool short *);
19700 vector pixel vec_vsx_ld (int, const vector pixel *);
19701 vector signed short vec_vsx_ld (int, const vector signed short *);
19702 vector signed short vec_vsx_ld (int, const short *);
19703 vector unsigned short vec_vsx_ld (int, const vector unsigned short *);
19704 vector unsigned short vec_vsx_ld (int, const unsigned short *);
19705 vector bool char vec_vsx_ld (int, const vector bool char *);
19706 vector signed char vec_vsx_ld (int, const vector signed char *);
19707 vector signed char vec_vsx_ld (int, const signed char *);
19708 vector unsigned char vec_vsx_ld (int, const vector unsigned char *);
19709 vector unsigned char vec_vsx_ld (int, const unsigned char *);
19711 void vec_vsx_st (vector double, int, vector double *);
19712 void vec_vsx_st (vector double, int, double *);
19713 void vec_vsx_st (vector float, int, vector float *);
19714 void vec_vsx_st (vector float, int, float *);
19715 void vec_vsx_st (vector signed int, int, vector signed int *);
19716 void vec_vsx_st (vector signed int, int, int *);
19717 void vec_vsx_st (vector unsigned int, int, vector unsigned int *);
19718 void vec_vsx_st (vector unsigned int, int, unsigned int *);
19719 void vec_vsx_st (vector bool int, int, vector bool int *);
19720 void vec_vsx_st (vector bool int, int, unsigned int *);
19721 void vec_vsx_st (vector bool int, int, int *);
19722 void vec_vsx_st (vector signed short, int, vector signed short *);
19723 void vec_vsx_st (vector signed short, int, short *);
19724 void vec_vsx_st (vector unsigned short, int, vector unsigned short *);
19725 void vec_vsx_st (vector unsigned short, int, unsigned short *);
19726 void vec_vsx_st (vector bool short, int, vector bool short *);
19727 void vec_vsx_st (vector bool short, int, unsigned short *);
19728 void vec_vsx_st (vector pixel, int, vector pixel *);
19729 void vec_vsx_st (vector pixel, int, unsigned short *);
19730 void vec_vsx_st (vector pixel, int, short *);
19731 void vec_vsx_st (vector bool short, int, short *);
19732 void vec_vsx_st (vector signed char, int, vector signed char *);
19733 void vec_vsx_st (vector signed char, int, signed char *);
19734 void vec_vsx_st (vector unsigned char, int, vector unsigned char *);
19735 void vec_vsx_st (vector unsigned char, int, unsigned char *);
19736 void vec_vsx_st (vector bool char, int, vector bool char *);
19737 void vec_vsx_st (vector bool char, int, unsigned char *);
19738 void vec_vsx_st (vector bool char, int, signed char *);
19740 vector double vec_xxpermdi (vector double, vector double, const int);
19741 vector float vec_xxpermdi (vector float, vector float, const int);
19742 vector long long vec_xxpermdi (vector long long, vector long long, const int);
19743 vector unsigned long long vec_xxpermdi (vector unsigned long long,
19744 vector unsigned long long, const int);
19745 vector int vec_xxpermdi (vector int, vector int, const int);
19746 vector unsigned int vec_xxpermdi (vector unsigned int,
19747 vector unsigned int, const int);
19748 vector short vec_xxpermdi (vector short, vector short, const int);
19749 vector unsigned short vec_xxpermdi (vector unsigned short,
19750 vector unsigned short, const int);
19751 vector signed char vec_xxpermdi (vector signed char, vector signed char,
19753 vector unsigned char vec_xxpermdi (vector unsigned char,
19754 vector unsigned char, const int);
19756 vector double vec_xxsldi (vector double, vector double, int);
19757 vector float vec_xxsldi (vector float, vector float, int);
19758 vector long long vec_xxsldi (vector long long, vector long long, int);
19759 vector unsigned long long vec_xxsldi (vector unsigned long long,
19760 vector unsigned long long, int);
19761 vector int vec_xxsldi (vector int, vector int, int);
19762 vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int);
19763 vector short vec_xxsldi (vector short, vector short, int);
19764 vector unsigned short vec_xxsldi (vector unsigned short,
19765 vector unsigned short, int);
19766 vector signed char vec_xxsldi (vector signed char, vector signed char, int);
19767 vector unsigned char vec_xxsldi (vector unsigned char,
19768 vector unsigned char, int);
19771 Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always
19772 generate the AltiVec @samp{LVX} and @samp{STVX} instructions even
19773 if the VSX instruction set is available. The @samp{vec_vsx_ld} and
19774 @samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X},
19775 @samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions.
19777 @node PowerPC AltiVec Built-in Functions Available on ISA 2.07
19778 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07
19780 If the ISA 2.07 additions to the vector/scalar (power8-vector)
19781 instruction set are available, the following additional functions are
19782 available for both 32-bit and 64-bit targets. For 64-bit targets, you
19783 can use @var{vector long} instead of @var{vector long long},
19784 @var{vector bool long} instead of @var{vector bool long long}, and
19785 @var{vector unsigned long} instead of @var{vector unsigned long long}.
19788 vector signed char vec_neg (vector signed char);
19789 vector signed short vec_neg (vector signed short);
19790 vector signed int vec_neg (vector signed int);
19791 vector signed long long vec_neg (vector signed long long);
19792 vector float char vec_neg (vector float);
19793 vector double vec_neg (vector double);
19795 vector signed int vec_signed2 (vector double, vector double);
19797 vector signed int vec_unsigned2 (vector double, vector double);
19799 vector long long vec_abs (vector long long);
19801 vector long long vec_add (vector long long, vector long long);
19802 vector unsigned long long vec_add (vector unsigned long long,
19803 vector unsigned long long);
19805 int vec_all_eq (vector long long, vector long long);
19806 int vec_all_eq (vector unsigned long long, vector unsigned long long);
19807 int vec_all_ge (vector long long, vector long long);
19808 int vec_all_ge (vector unsigned long long, vector unsigned long long);
19809 int vec_all_gt (vector long long, vector long long);
19810 int vec_all_gt (vector unsigned long long, vector unsigned long long);
19811 int vec_all_le (vector long long, vector long long);
19812 int vec_all_le (vector unsigned long long, vector unsigned long long);
19813 int vec_all_lt (vector long long, vector long long);
19814 int vec_all_lt (vector unsigned long long, vector unsigned long long);
19815 int vec_all_ne (vector long long, vector long long);
19816 int vec_all_ne (vector unsigned long long, vector unsigned long long);
19818 int vec_any_eq (vector long long, vector long long);
19819 int vec_any_eq (vector unsigned long long, vector unsigned long long);
19820 int vec_any_ge (vector long long, vector long long);
19821 int vec_any_ge (vector unsigned long long, vector unsigned long long);
19822 int vec_any_gt (vector long long, vector long long);
19823 int vec_any_gt (vector unsigned long long, vector unsigned long long);
19824 int vec_any_le (vector long long, vector long long);
19825 int vec_any_le (vector unsigned long long, vector unsigned long long);
19826 int vec_any_lt (vector long long, vector long long);
19827 int vec_any_lt (vector unsigned long long, vector unsigned long long);
19828 int vec_any_ne (vector long long, vector long long);
19829 int vec_any_ne (vector unsigned long long, vector unsigned long long);
19831 vector bool long long vec_cmpeq (vector bool long long, vector bool long long);
19833 vector long long vec_eqv (vector long long, vector long long);
19834 vector long long vec_eqv (vector bool long long, vector long long);
19835 vector long long vec_eqv (vector long long, vector bool long long);
19836 vector unsigned long long vec_eqv (vector unsigned long long, vector unsigned long long);
19837 vector unsigned long long vec_eqv (vector bool long long, vector unsigned long long);
19838 vector unsigned long long vec_eqv (vector unsigned long long,
19839 vector bool long long);
19840 vector int vec_eqv (vector int, vector int);
19841 vector int vec_eqv (vector bool int, vector int);
19842 vector int vec_eqv (vector int, vector bool int);
19843 vector unsigned int vec_eqv (vector unsigned int, vector unsigned int);
19844 vector unsigned int vec_eqv (vector bool unsigned int, vector unsigned int);
19845 vector unsigned int vec_eqv (vector unsigned int, vector bool unsigned int);
19846 vector short vec_eqv (vector short, vector short);
19847 vector short vec_eqv (vector bool short, vector short);
19848 vector short vec_eqv (vector short, vector bool short);
19849 vector unsigned short vec_eqv (vector unsigned short, vector unsigned short);
19850 vector unsigned short vec_eqv (vector bool unsigned short, vector unsigned short);
19851 vector unsigned short vec_eqv (vector unsigned short, vector bool unsigned short);
19852 vector signed char vec_eqv (vector signed char, vector signed char);
19853 vector signed char vec_eqv (vector bool signed char, vector signed char);
19854 vector signed char vec_eqv (vector signed char, vector bool signed char);
19855 vector unsigned char vec_eqv (vector unsigned char, vector unsigned char);
19856 vector unsigned char vec_eqv (vector bool unsigned char, vector unsigned char);
19857 vector unsigned char vec_eqv (vector unsigned char, vector bool unsigned char);
19859 vector long long vec_max (vector long long, vector long long);
19860 vector unsigned long long vec_max (vector unsigned long long,
19861 vector unsigned long long);
19863 vector signed int vec_mergee (vector signed int, vector signed int);
19864 vector unsigned int vec_mergee (vector unsigned int, vector unsigned int);
19865 vector bool int vec_mergee (vector bool int, vector bool int);
19867 vector signed int vec_mergeo (vector signed int, vector signed int);
19868 vector unsigned int vec_mergeo (vector unsigned int, vector unsigned int);
19869 vector bool int vec_mergeo (vector bool int, vector bool int);
19871 vector long long vec_min (vector long long, vector long long);
19872 vector unsigned long long vec_min (vector unsigned long long,
19873 vector unsigned long long);
19875 vector signed long long vec_nabs (vector signed long long);
19877 vector long long vec_nand (vector long long, vector long long);
19878 vector long long vec_nand (vector bool long long, vector long long);
19879 vector long long vec_nand (vector long long, vector bool long long);
19880 vector unsigned long long vec_nand (vector unsigned long long,
19881 vector unsigned long long);
19882 vector unsigned long long vec_nand (vector bool long long, vector unsigned long long);
19883 vector unsigned long long vec_nand (vector unsigned long long, vector bool long long);
19884 vector int vec_nand (vector int, vector int);
19885 vector int vec_nand (vector bool int, vector int);
19886 vector int vec_nand (vector int, vector bool int);
19887 vector unsigned int vec_nand (vector unsigned int, vector unsigned int);
19888 vector unsigned int vec_nand (vector bool unsigned int, vector unsigned int);
19889 vector unsigned int vec_nand (vector unsigned int, vector bool unsigned int);
19890 vector short vec_nand (vector short, vector short);
19891 vector short vec_nand (vector bool short, vector short);
19892 vector short vec_nand (vector short, vector bool short);
19893 vector unsigned short vec_nand (vector unsigned short, vector unsigned short);
19894 vector unsigned short vec_nand (vector bool unsigned short, vector unsigned short);
19895 vector unsigned short vec_nand (vector unsigned short, vector bool unsigned short);
19896 vector signed char vec_nand (vector signed char, vector signed char);
19897 vector signed char vec_nand (vector bool signed char, vector signed char);
19898 vector signed char vec_nand (vector signed char, vector bool signed char);
19899 vector unsigned char vec_nand (vector unsigned char, vector unsigned char);
19900 vector unsigned char vec_nand (vector bool unsigned char, vector unsigned char);
19901 vector unsigned char vec_nand (vector unsigned char, vector bool unsigned char);
19903 vector long long vec_orc (vector long long, vector long long);
19904 vector long long vec_orc (vector bool long long, vector long long);
19905 vector long long vec_orc (vector long long, vector bool long long);
19906 vector unsigned long long vec_orc (vector unsigned long long,
19907 vector unsigned long long);
19908 vector unsigned long long vec_orc (vector bool long long, vector unsigned long long);
19909 vector unsigned long long vec_orc (vector unsigned long long, vector bool long long);
19910 vector int vec_orc (vector int, vector int);
19911 vector int vec_orc (vector bool int, vector int);
19912 vector int vec_orc (vector int, vector bool int);
19913 vector unsigned int vec_orc (vector unsigned int, vector unsigned int);
19914 vector unsigned int vec_orc (vector bool unsigned int, vector unsigned int);
19915 vector unsigned int vec_orc (vector unsigned int, vector bool unsigned int);
19916 vector short vec_orc (vector short, vector short);
19917 vector short vec_orc (vector bool short, vector short);
19918 vector short vec_orc (vector short, vector bool short);
19919 vector unsigned short vec_orc (vector unsigned short, vector unsigned short);
19920 vector unsigned short vec_orc (vector bool unsigned short, vector unsigned short);
19921 vector unsigned short vec_orc (vector unsigned short, vector bool unsigned short);
19922 vector signed char vec_orc (vector signed char, vector signed char);
19923 vector signed char vec_orc (vector bool signed char, vector signed char);
19924 vector signed char vec_orc (vector signed char, vector bool signed char);
19925 vector unsigned char vec_orc (vector unsigned char, vector unsigned char);
19926 vector unsigned char vec_orc (vector bool unsigned char, vector unsigned char);
19927 vector unsigned char vec_orc (vector unsigned char, vector bool unsigned char);
19929 vector int vec_pack (vector long long, vector long long);
19930 vector unsigned int vec_pack (vector unsigned long long, vector unsigned long long);
19931 vector bool int vec_pack (vector bool long long, vector bool long long);
19932 vector float vec_pack (vector double, vector double);
19934 vector int vec_packs (vector long long, vector long long);
19935 vector unsigned int vec_packs (vector unsigned long long, vector unsigned long long);
19937 vector unsigned char vec_packsu (vector signed short, vector signed short)
19938 vector unsigned char vec_packsu (vector unsigned short, vector unsigned short)
19939 vector unsigned short int vec_packsu (vector signed int, vector signed int);
19940 vector unsigned short int vec_packsu (vector unsigned int, vector unsigned int);
19941 vector unsigned int vec_packsu (vector long long, vector long long);
19942 vector unsigned int vec_packsu (vector unsigned long long, vector unsigned long long);
19943 vector unsigned int vec_packsu (vector signed long long, vector signed long long);
19945 vector unsigned char vec_popcnt (vector signed char);
19946 vector unsigned char vec_popcnt (vector unsigned char);
19947 vector unsigned short vec_popcnt (vector signed short);
19948 vector unsigned short vec_popcnt (vector unsigned short);
19949 vector unsigned int vec_popcnt (vector signed int);
19950 vector unsigned int vec_popcnt (vector unsigned int);
19951 vector unsigned long long vec_popcnt (vector signed long long);
19952 vector unsigned long long vec_popcnt (vector unsigned long long);
19954 vector long long vec_rl (vector long long, vector unsigned long long);
19955 vector long long vec_rl (vector unsigned long long, vector unsigned long long);
19957 vector long long vec_sl (vector long long, vector unsigned long long);
19958 vector long long vec_sl (vector unsigned long long, vector unsigned long long);
19960 vector long long vec_sr (vector long long, vector unsigned long long);
19961 vector unsigned long long char vec_sr (vector unsigned long long,
19962 vector unsigned long long);
19964 vector long long vec_sra (vector long long, vector unsigned long long);
19965 vector unsigned long long vec_sra (vector unsigned long long,
19966 vector unsigned long long);
19968 vector long long vec_sub (vector long long, vector long long);
19969 vector unsigned long long vec_sub (vector unsigned long long,
19970 vector unsigned long long);
19972 vector long long vec_unpackh (vector int);
19973 vector unsigned long long vec_unpackh (vector unsigned int);
19975 vector long long vec_unpackl (vector int);
19976 vector unsigned long long vec_unpackl (vector unsigned int);
19978 vector long long vec_vaddudm (vector long long, vector long long);
19979 vector long long vec_vaddudm (vector bool long long, vector long long);
19980 vector long long vec_vaddudm (vector long long, vector bool long long);
19981 vector unsigned long long vec_vaddudm (vector unsigned long long,
19982 vector unsigned long long);
19983 vector unsigned long long vec_vaddudm (vector bool unsigned long long,
19984 vector unsigned long long);
19985 vector unsigned long long vec_vaddudm (vector unsigned long long,
19986 vector bool unsigned long long);
19988 vector long long vec_vbpermq (vector signed char, vector signed char);
19989 vector long long vec_vbpermq (vector unsigned char, vector unsigned char);
19991 vector unsigned char vec_bperm (vector unsigned char, vector unsigned char);
19992 vector unsigned char vec_bperm (vector unsigned long long, vector unsigned char);
19993 vector unsigned long long vec_bperm (vector unsigned __int128, vector unsigned char);
19995 vector long long vec_cntlz (vector long long);
19996 vector unsigned long long vec_cntlz (vector unsigned long long);
19997 vector int vec_cntlz (vector int);
19998 vector unsigned int vec_cntlz (vector int);
19999 vector short vec_cntlz (vector short);
20000 vector unsigned short vec_cntlz (vector unsigned short);
20001 vector signed char vec_cntlz (vector signed char);
20002 vector unsigned char vec_cntlz (vector unsigned char);
20004 vector long long vec_vclz (vector long long);
20005 vector unsigned long long vec_vclz (vector unsigned long long);
20006 vector int vec_vclz (vector int);
20007 vector unsigned int vec_vclz (vector int);
20008 vector short vec_vclz (vector short);
20009 vector unsigned short vec_vclz (vector unsigned short);
20010 vector signed char vec_vclz (vector signed char);
20011 vector unsigned char vec_vclz (vector unsigned char);
20013 vector signed char vec_vclzb (vector signed char);
20014 vector unsigned char vec_vclzb (vector unsigned char);
20016 vector long long vec_vclzd (vector long long);
20017 vector unsigned long long vec_vclzd (vector unsigned long long);
20019 vector short vec_vclzh (vector short);
20020 vector unsigned short vec_vclzh (vector unsigned short);
20022 vector int vec_vclzw (vector int);
20023 vector unsigned int vec_vclzw (vector int);
20025 vector signed char vec_vgbbd (vector signed char);
20026 vector unsigned char vec_vgbbd (vector unsigned char);
20028 vector long long vec_vmaxsd (vector long long, vector long long);
20030 vector unsigned long long vec_vmaxud (vector unsigned long long,
20031 unsigned vector long long);
20033 vector long long vec_vminsd (vector long long, vector long long);
20035 vector unsigned long long vec_vminud (vector long long, vector long long);
20037 vector int vec_vpksdss (vector long long, vector long long);
20038 vector unsigned int vec_vpksdss (vector long long, vector long long);
20040 vector unsigned int vec_vpkudus (vector unsigned long long,
20041 vector unsigned long long);
20043 vector int vec_vpkudum (vector long long, vector long long);
20044 vector unsigned int vec_vpkudum (vector unsigned long long,
20045 vector unsigned long long);
20046 vector bool int vec_vpkudum (vector bool long long, vector bool long long);
20048 vector long long vec_vpopcnt (vector long long);
20049 vector unsigned long long vec_vpopcnt (vector unsigned long long);
20050 vector int vec_vpopcnt (vector int);
20051 vector unsigned int vec_vpopcnt (vector int);
20052 vector short vec_vpopcnt (vector short);
20053 vector unsigned short vec_vpopcnt (vector unsigned short);
20054 vector signed char vec_vpopcnt (vector signed char);
20055 vector unsigned char vec_vpopcnt (vector unsigned char);
20057 vector signed char vec_vpopcntb (vector signed char);
20058 vector unsigned char vec_vpopcntb (vector unsigned char);
20060 vector long long vec_vpopcntd (vector long long);
20061 vector unsigned long long vec_vpopcntd (vector unsigned long long);
20063 vector short vec_vpopcnth (vector short);
20064 vector unsigned short vec_vpopcnth (vector unsigned short);
20066 vector int vec_vpopcntw (vector int);
20067 vector unsigned int vec_vpopcntw (vector int);
20069 vector long long vec_vrld (vector long long, vector unsigned long long);
20070 vector unsigned long long vec_vrld (vector unsigned long long,
20071 vector unsigned long long);
20073 vector long long vec_vsld (vector long long, vector unsigned long long);
20074 vector long long vec_vsld (vector unsigned long long,
20075 vector unsigned long long);
20077 vector long long vec_vsrad (vector long long, vector unsigned long long);
20078 vector unsigned long long vec_vsrad (vector unsigned long long,
20079 vector unsigned long long);
20081 vector long long vec_vsrd (vector long long, vector unsigned long long);
20082 vector unsigned long long char vec_vsrd (vector unsigned long long,
20083 vector unsigned long long);
20085 vector long long vec_vsubudm (vector long long, vector long long);
20086 vector long long vec_vsubudm (vector bool long long, vector long long);
20087 vector long long vec_vsubudm (vector long long, vector bool long long);
20088 vector unsigned long long vec_vsubudm (vector unsigned long long,
20089 vector unsigned long long);
20090 vector unsigned long long vec_vsubudm (vector bool long long,
20091 vector unsigned long long);
20092 vector unsigned long long vec_vsubudm (vector unsigned long long,
20093 vector bool long long);
20095 vector long long vec_vupkhsw (vector int);
20096 vector unsigned long long vec_vupkhsw (vector unsigned int);
20098 vector long long vec_vupklsw (vector int);
20099 vector unsigned long long vec_vupklsw (vector int);
20102 If the ISA 2.07 additions to the vector/scalar (power8-vector)
20103 instruction set are available, the following additional functions are
20104 available for 64-bit targets. New vector types
20105 (@var{vector __int128} and @var{vector __uint128}) are available
20106 to hold the @var{__int128} and @var{__uint128} types to use these
20109 The normal vector extract, and set operations work on
20110 @var{vector __int128} and @var{vector __uint128} types,
20111 but the index value must be 0.
20114 vector __int128 vec_vaddcuq (vector __int128, vector __int128);
20115 vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128);
20117 vector __int128 vec_vadduqm (vector __int128, vector __int128);
20118 vector __uint128 vec_vadduqm (vector __uint128, vector __uint128);
20120 vector __int128 vec_vaddecuq (vector __int128, vector __int128,
20122 vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128,
20125 vector __int128 vec_vaddeuqm (vector __int128, vector __int128,
20127 vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128,
20130 vector __int128 vec_vsubecuq (vector __int128, vector __int128,
20132 vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128,
20135 vector __int128 vec_vsubeuqm (vector __int128, vector __int128,
20137 vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128,
20140 vector __int128 vec_vsubcuq (vector __int128, vector __int128);
20141 vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128);
20143 __int128 vec_vsubuqm (__int128, __int128);
20144 __uint128 vec_vsubuqm (__uint128, __uint128);
20146 vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int);
20147 int __builtin_bcdadd_lt (vector __int128, vector __int128, const int);
20148 int __builtin_bcdadd_eq (vector __int128, vector __int128, const int);
20149 int __builtin_bcdadd_gt (vector __int128, vector __int128, const int);
20150 int __builtin_bcdadd_ov (vector __int128, vector __int128, const int);
20151 vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int);
20152 int __builtin_bcdsub_lt (vector __int128, vector __int128, const int);
20153 int __builtin_bcdsub_eq (vector __int128, vector __int128, const int);
20154 int __builtin_bcdsub_gt (vector __int128, vector __int128, const int);
20155 int __builtin_bcdsub_ov (vector __int128, vector __int128, const int);
20158 @node PowerPC AltiVec Built-in Functions Available on ISA 3.0
20159 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0
20161 The following additional built-in functions are also available for the
20162 PowerPC family of processors, starting with ISA 3.0
20163 (@option{-mcpu=power9}) or later:
20165 unsigned int scalar_extract_exp (double source);
20166 unsigned long long int scalar_extract_exp (__ieee128 source);
20168 unsigned long long int scalar_extract_sig (double source);
20169 unsigned __int128 scalar_extract_sig (__ieee128 source);
20171 double scalar_insert_exp (unsigned long long int significand,
20172 unsigned long long int exponent);
20173 double scalar_insert_exp (double significand, unsigned long long int exponent);
20175 ieee_128 scalar_insert_exp (unsigned __int128 significand,
20176 unsigned long long int exponent);
20177 ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent);
20179 int scalar_cmp_exp_gt (double arg1, double arg2);
20180 int scalar_cmp_exp_lt (double arg1, double arg2);
20181 int scalar_cmp_exp_eq (double arg1, double arg2);
20182 int scalar_cmp_exp_unordered (double arg1, double arg2);
20184 bool scalar_test_data_class (float source, const int condition);
20185 bool scalar_test_data_class (double source, const int condition);
20186 bool scalar_test_data_class (__ieee128 source, const int condition);
20188 bool scalar_test_neg (float source);
20189 bool scalar_test_neg (double source);
20190 bool scalar_test_neg (__ieee128 source);
20193 The @code{scalar_extract_exp} and @code{scalar_extract_sig}
20194 functions require a 64-bit environment supporting ISA 3.0 or later.
20195 The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in
20196 functions return the significand and the biased exponent value
20197 respectively of their @code{source} arguments.
20198 When supplied with a 64-bit @code{source} argument, the
20199 result returned by @code{scalar_extract_sig} has
20200 the @code{0x0010000000000000} bit set if the
20201 function's @code{source} argument is in normalized form.
20202 Otherwise, this bit is set to 0.
20203 When supplied with a 128-bit @code{source} argument, the
20204 @code{0x00010000000000000000000000000000} bit of the result is
20206 Note that the sign of the significand is not represented in the result
20207 returned from the @code{scalar_extract_sig} function. Use the
20208 @code{scalar_test_neg} function to test the sign of its @code{double}
20211 The @code{scalar_insert_exp}
20212 functions require a 64-bit environment supporting ISA 3.0 or later.
20213 When supplied with a 64-bit first argument, the
20214 @code{scalar_insert_exp} built-in function returns a double-precision
20215 floating point value that is constructed by assembling the values of its
20216 @code{significand} and @code{exponent} arguments. The sign of the
20217 result is copied from the most significant bit of the
20218 @code{significand} argument. The significand and exponent components
20219 of the result are composed of the least significant 11 bits of the
20220 @code{exponent} argument and the least significant 52 bits of the
20221 @code{significand} argument respectively.
20223 When supplied with a 128-bit first argument, the
20224 @code{scalar_insert_exp} built-in function returns a quad-precision
20225 ieee floating point value. The sign bit of the result is copied from
20226 the most significant bit of the @code{significand} argument.
20227 The significand and exponent components of the result are composed of
20228 the least significant 15 bits of the @code{exponent} argument and the
20229 least significant 112 bits of the @code{significand} argument respectively.
20231 The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt},
20232 @code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in
20233 functions return a non-zero value if @code{arg1} is greater than, less
20234 than, equal to, or not comparable to @code{arg2} respectively. The
20235 arguments are not comparable if one or the other equals NaN (not a
20238 The @code{scalar_test_data_class} built-in function returns 1
20239 if any of the condition tests enabled by the value of the
20240 @code{condition} variable are true, and 0 otherwise. The
20241 @code{condition} argument must be a compile-time constant integer with
20242 value not exceeding 127. The
20243 @code{condition} argument is encoded as a bitmask with each bit
20244 enabling the testing of a different condition, as characterized by the
20248 0x20 Test for +Infinity
20249 0x10 Test for -Infinity
20250 0x08 Test for +Zero
20251 0x04 Test for -Zero
20252 0x02 Test for +Denormal
20253 0x01 Test for -Denormal
20256 The @code{scalar_test_neg} built-in function returns 1 if its
20257 @code{source} argument holds a negative value, 0 otherwise.
20259 The following built-in functions are also available for the PowerPC family
20260 of processors, starting with ISA 3.0 or later
20261 (@option{-mcpu=power9}). These string functions are described
20262 separately in order to group the descriptions closer to the function
20265 int vec_all_nez (vector signed char, vector signed char);
20266 int vec_all_nez (vector unsigned char, vector unsigned char);
20267 int vec_all_nez (vector signed short, vector signed short);
20268 int vec_all_nez (vector unsigned short, vector unsigned short);
20269 int vec_all_nez (vector signed int, vector signed int);
20270 int vec_all_nez (vector unsigned int, vector unsigned int);
20272 int vec_any_eqz (vector signed char, vector signed char);
20273 int vec_any_eqz (vector unsigned char, vector unsigned char);
20274 int vec_any_eqz (vector signed short, vector signed short);
20275 int vec_any_eqz (vector unsigned short, vector unsigned short);
20276 int vec_any_eqz (vector signed int, vector signed int);
20277 int vec_any_eqz (vector unsigned int, vector unsigned int);
20279 vector bool char vec_cmpnez (vector signed char arg1, vector signed char arg2);
20280 vector bool char vec_cmpnez (vector unsigned char arg1, vector unsigned char arg2);
20281 vector bool short vec_cmpnez (vector signed short arg1, vector signed short arg2);
20282 vector bool short vec_cmpnez (vector unsigned short arg1, vector unsigned short arg2);
20283 vector bool int vec_cmpnez (vector signed int arg1, vector signed int arg2);
20284 vector bool int vec_cmpnez (vector unsigned int, vector unsigned int);
20286 vector signed char vec_cnttz (vector signed char);
20287 vector unsigned char vec_cnttz (vector unsigned char);
20288 vector signed short vec_cnttz (vector signed short);
20289 vector unsigned short vec_cnttz (vector unsigned short);
20290 vector signed int vec_cnttz (vector signed int);
20291 vector unsigned int vec_cnttz (vector unsigned int);
20292 vector signed long long vec_cnttz (vector signed long long);
20293 vector unsigned long long vec_cnttz (vector unsigned long long);
20295 signed int vec_cntlz_lsbb (vector signed char);
20296 signed int vec_cntlz_lsbb (vector unsigned char);
20298 signed int vec_cnttz_lsbb (vector signed char);
20299 signed int vec_cnttz_lsbb (vector unsigned char);
20301 unsigned int vec_first_match_index (vector signed char, vector signed char);
20302 unsigned int vec_first_match_index (vector unsigned char, vector unsigned char);
20303 unsigned int vec_first_match_index (vector signed int, vector signed int);
20304 unsigned int vec_first_match_index (vector unsigned int, vector unsigned int);
20305 unsigned int vec_first_match_index (vector signed short, vector signed short);
20306 unsigned int vec_first_match_index (vector unsigned short, vector unsigned short);
20307 unsigned int vec_first_match_or_eos_index (vector signed char, vector signed char);
20308 unsigned int vec_first_match_or_eos_index (vector unsigned char, vector unsigned char);
20309 unsigned int vec_first_match_or_eos_index (vector signed int, vector signed int);
20310 unsigned int vec_first_match_or_eos_index (vector unsigned int, vector unsigned int);
20311 unsigned int vec_first_match_or_eos_index (vector signed short, vector signed short);
20312 unsigned int vec_first_match_or_eos_index (vector unsigned short,
20313 vector unsigned short);
20314 unsigned int vec_first_mismatch_index (vector signed char, vector signed char);
20315 unsigned int vec_first_mismatch_index (vector unsigned char, vector unsigned char);
20316 unsigned int vec_first_mismatch_index (vector signed int, vector signed int);
20317 unsigned int vec_first_mismatch_index (vector unsigned int, vector unsigned int);
20318 unsigned int vec_first_mismatch_index (vector signed short, vector signed short);
20319 unsigned int vec_first_mismatch_index (vector unsigned short, vector unsigned short);
20320 unsigned int vec_first_mismatch_or_eos_index (vector signed char, vector signed char);
20321 unsigned int vec_first_mismatch_or_eos_index (vector unsigned char,
20322 vector unsigned char);
20323 unsigned int vec_first_mismatch_or_eos_index (vector signed int, vector signed int);
20324 unsigned int vec_first_mismatch_or_eos_index (vector unsigned int, vector unsigned int);
20325 unsigned int vec_first_mismatch_or_eos_index (vector signed short, vector signed short);
20326 unsigned int vec_first_mismatch_or_eos_index (vector unsigned short,
20327 vector unsigned short);
20329 vector unsigned short vec_pack_to_short_fp32 (vector float, vector float);
20331 vector signed char vec_xl_be (signed long long, signed char *);
20332 vector unsigned char vec_xl_be (signed long long, unsigned char *);
20333 vector signed int vec_xl_be (signed long long, signed int *);
20334 vector unsigned int vec_xl_be (signed long long, unsigned int *);
20335 vector signed __int128 vec_xl_be (signed long long, signed __int128 *);
20336 vector unsigned __int128 vec_xl_be (signed long long, unsigned __int128 *);
20337 vector signed long long vec_xl_be (signed long long, signed long long *);
20338 vector unsigned long long vec_xl_be (signed long long, unsigned long long *);
20339 vector signed short vec_xl_be (signed long long, signed short *);
20340 vector unsigned short vec_xl_be (signed long long, unsigned short *);
20341 vector double vec_xl_be (signed long long, double *);
20342 vector float vec_xl_be (signed long long, float *);
20344 vector signed char vec_xl_len (signed char *addr, size_t len);
20345 vector unsigned char vec_xl_len (unsigned char *addr, size_t len);
20346 vector signed int vec_xl_len (signed int *addr, size_t len);
20347 vector unsigned int vec_xl_len (unsigned int *addr, size_t len);
20348 vector signed __int128 vec_xl_len (signed __int128 *addr, size_t len);
20349 vector unsigned __int128 vec_xl_len (unsigned __int128 *addr, size_t len);
20350 vector signed long long vec_xl_len (signed long long *addr, size_t len);
20351 vector unsigned long long vec_xl_len (unsigned long long *addr, size_t len);
20352 vector signed short vec_xl_len (signed short *addr, size_t len);
20353 vector unsigned short vec_xl_len (unsigned short *addr, size_t len);
20354 vector double vec_xl_len (double *addr, size_t len);
20355 vector float vec_xl_len (float *addr, size_t len);
20357 vector unsigned char vec_xl_len_r (unsigned char *addr, size_t len);
20359 void vec_xst_len (vector signed char data, signed char *addr, size_t len);
20360 void vec_xst_len (vector unsigned char data, unsigned char *addr, size_t len);
20361 void vec_xst_len (vector signed int data, signed int *addr, size_t len);
20362 void vec_xst_len (vector unsigned int data, unsigned int *addr, size_t len);
20363 void vec_xst_len (vector unsigned __int128 data, unsigned __int128 *addr, size_t len);
20364 void vec_xst_len (vector signed long long data, signed long long *addr, size_t len);
20365 void vec_xst_len (vector unsigned long long data, unsigned long long *addr, size_t len);
20366 void vec_xst_len (vector signed short data, signed short *addr, size_t len);
20367 void vec_xst_len (vector unsigned short data, unsigned short *addr, size_t len);
20368 void vec_xst_len (vector signed __int128 data, signed __int128 *addr, size_t len);
20369 void vec_xst_len (vector double data, double *addr, size_t len);
20370 void vec_xst_len (vector float data, float *addr, size_t len);
20372 void vec_xst_len_r (vector unsigned char data, unsigned char *addr, size_t len);
20374 signed char vec_xlx (unsigned int index, vector signed char data);
20375 unsigned char vec_xlx (unsigned int index, vector unsigned char data);
20376 signed short vec_xlx (unsigned int index, vector signed short data);
20377 unsigned short vec_xlx (unsigned int index, vector unsigned short data);
20378 signed int vec_xlx (unsigned int index, vector signed int data);
20379 unsigned int vec_xlx (unsigned int index, vector unsigned int data);
20380 float vec_xlx (unsigned int index, vector float data);
20382 signed char vec_xrx (unsigned int index, vector signed char data);
20383 unsigned char vec_xrx (unsigned int index, vector unsigned char data);
20384 signed short vec_xrx (unsigned int index, vector signed short data);
20385 unsigned short vec_xrx (unsigned int index, vector unsigned short data);
20386 signed int vec_xrx (unsigned int index, vector signed int data);
20387 unsigned int vec_xrx (unsigned int index, vector unsigned int data);
20388 float vec_xrx (unsigned int index, vector float data);
20391 The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez}
20392 perform pairwise comparisons between the elements at the same
20393 positions within their two vector arguments.
20394 The @code{vec_all_nez} function returns a
20395 non-zero value if and only if all pairwise comparisons are not
20396 equal and no element of either vector argument contains a zero.
20397 The @code{vec_any_eqz} function returns a
20398 non-zero value if and only if at least one pairwise comparison is equal
20399 or if at least one element of either vector argument contains a zero.
20400 The @code{vec_cmpnez} function returns a vector of the same type as
20401 its two arguments, within which each element consists of all ones to
20402 denote that either the corresponding elements of the incoming arguments are
20403 not equal or that at least one of the corresponding elements contains
20404 zero. Otherwise, the element of the returned vector contains all zeros.
20406 The @code{vec_cntlz_lsbb} function returns the count of the number of
20407 consecutive leading byte elements (starting from position 0 within the
20408 supplied vector argument) for which the least-significant bit
20409 equals zero. The @code{vec_cnttz_lsbb} function returns the count of
20410 the number of consecutive trailing byte elements (starting from
20411 position 15 and counting backwards within the supplied vector
20412 argument) for which the least-significant bit equals zero.
20414 The @code{vec_xl_len} and @code{vec_xst_len} functions require a
20415 64-bit environment supporting ISA 3.0 or later. The @code{vec_xl_len}
20416 function loads a variable length vector from memory. The
20417 @code{vec_xst_len} function stores a variable length vector to memory.
20418 With both the @code{vec_xl_len} and @code{vec_xst_len} functions, the
20419 @code{addr} argument represents the memory address to or from which
20420 data will be transferred, and the
20421 @code{len} argument represents the number of bytes to be
20422 transferred, as computed by the C expression @code{min((len & 0xff), 16)}.
20423 If this expression's value is not a multiple of the vector element's
20424 size, the behavior of this function is undefined.
20425 In the case that the underlying computer is configured to run in
20426 big-endian mode, the data transfer moves bytes 0 to @code{(len - 1)} of
20427 the corresponding vector. In little-endian mode, the data transfer
20428 moves bytes @code{(16 - len)} to @code{15} of the corresponding
20429 vector. For the load function, any bytes of the result vector that
20430 are not loaded from memory are set to zero.
20431 The value of the @code{addr} argument need not be aligned on a
20432 multiple of the vector's element size.
20434 The @code{vec_xlx} and @code{vec_xrx} functions extract the single
20435 element selected by the @code{index} argument from the vector
20436 represented by the @code{data} argument. The @code{index} argument
20437 always specifies a byte offset, regardless of the size of the vector
20438 element. With @code{vec_xlx}, @code{index} is the offset of the first
20439 byte of the element to be extracted. With @code{vec_xrx}, @code{index}
20440 represents the last byte of the element to be extracted, measured
20441 from the right end of the vector. In other words, the last byte of
20442 the element to be extracted is found at position @code{(15 - index)}.
20443 There is no requirement that @code{index} be a multiple of the vector
20444 element size. However, if the size of the vector element added to
20445 @code{index} is greater than 15, the content of the returned value is
20448 If the ISA 3.0 instruction set additions (@option{-mcpu=power9})
20452 vector unsigned long long vec_bperm (vector unsigned long long, vector unsigned char);
20454 vector bool char vec_cmpne (vector bool char, vector bool char);
20455 vector bool char vec_cmpne (vector signed char, vector signed char);
20456 vector bool char vec_cmpne (vector unsigned char, vector unsigned char);
20457 vector bool int vec_cmpne (vector bool int, vector bool int);
20458 vector bool int vec_cmpne (vector signed int, vector signed int);
20459 vector bool int vec_cmpne (vector unsigned int, vector unsigned int);
20460 vector bool long long vec_cmpne (vector bool long long, vector bool long long);
20461 vector bool long long vec_cmpne (vector signed long long, vector signed long long);
20462 vector bool long long vec_cmpne (vector unsigned long long, vector unsigned long long);
20463 vector bool short vec_cmpne (vector bool short, vector bool short);
20464 vector bool short vec_cmpne (vector signed short, vector signed short);
20465 vector bool short vec_cmpne (vector unsigned short, vector unsigned short);
20466 vector bool long long vec_cmpne (vector double, vector double);
20467 vector bool int vec_cmpne (vector float, vector float);
20469 vector float vec_extract_fp32_from_shorth (vector unsigned short);
20470 vector float vec_extract_fp32_from_shortl (vector unsigned short);
20472 vector long long vec_vctz (vector long long);
20473 vector unsigned long long vec_vctz (vector unsigned long long);
20474 vector int vec_vctz (vector int);
20475 vector unsigned int vec_vctz (vector int);
20476 vector short vec_vctz (vector short);
20477 vector unsigned short vec_vctz (vector unsigned short);
20478 vector signed char vec_vctz (vector signed char);
20479 vector unsigned char vec_vctz (vector unsigned char);
20481 vector signed char vec_vctzb (vector signed char);
20482 vector unsigned char vec_vctzb (vector unsigned char);
20484 vector long long vec_vctzd (vector long long);
20485 vector unsigned long long vec_vctzd (vector unsigned long long);
20487 vector short vec_vctzh (vector short);
20488 vector unsigned short vec_vctzh (vector unsigned short);
20490 vector int vec_vctzw (vector int);
20491 vector unsigned int vec_vctzw (vector int);
20493 vector unsigned long long vec_extract4b (vector unsigned char, const int);
20495 vector unsigned char vec_insert4b (vector signed int, vector unsigned char,
20497 vector unsigned char vec_insert4b (vector unsigned int, vector unsigned char,
20500 vector unsigned int vec_parity_lsbb (vector signed int);
20501 vector unsigned int vec_parity_lsbb (vector unsigned int);
20502 vector unsigned __int128 vec_parity_lsbb (vector signed __int128);
20503 vector unsigned __int128 vec_parity_lsbb (vector unsigned __int128);
20504 vector unsigned long long vec_parity_lsbb (vector signed long long);
20505 vector unsigned long long vec_parity_lsbb (vector unsigned long long);
20507 vector int vec_vprtyb (vector int);
20508 vector unsigned int vec_vprtyb (vector unsigned int);
20509 vector long long vec_vprtyb (vector long long);
20510 vector unsigned long long vec_vprtyb (vector unsigned long long);
20512 vector int vec_vprtybw (vector int);
20513 vector unsigned int vec_vprtybw (vector unsigned int);
20515 vector long long vec_vprtybd (vector long long);
20516 vector unsigned long long vec_vprtybd (vector unsigned long long);
20519 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
20523 vector long vec_vprtyb (vector long);
20524 vector unsigned long vec_vprtyb (vector unsigned long);
20525 vector __int128 vec_vprtyb (vector __int128);
20526 vector __uint128 vec_vprtyb (vector __uint128);
20528 vector long vec_vprtybd (vector long);
20529 vector unsigned long vec_vprtybd (vector unsigned long);
20531 vector __int128 vec_vprtybq (vector __int128);
20532 vector __uint128 vec_vprtybd (vector __uint128);
20535 The following built-in vector functions are available for the PowerPC family
20536 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20538 __vector unsigned char
20539 vec_slv (__vector unsigned char src, __vector unsigned char shift_distance);
20540 __vector unsigned char
20541 vec_srv (__vector unsigned char src, __vector unsigned char shift_distance);
20544 The @code{vec_slv} and @code{vec_srv} functions operate on
20545 all of the bytes of their @code{src} and @code{shift_distance}
20546 arguments in parallel. The behavior of the @code{vec_slv} is as if
20547 there existed a temporary array of 17 unsigned characters
20548 @code{slv_array} within which elements 0 through 15 are the same as
20549 the entries in the @code{src} array and element 16 equals 0. The
20550 result returned from the @code{vec_slv} function is a
20551 @code{__vector} of 16 unsigned characters within which element
20552 @code{i} is computed using the C expression
20553 @code{0xff & (*((unsigned short *)(slv_array + i)) << (0x07 &
20554 shift_distance[i]))},
20555 with this resulting value coerced to the @code{unsigned char} type.
20556 The behavior of the @code{vec_srv} is as if
20557 there existed a temporary array of 17 unsigned characters
20558 @code{srv_array} within which element 0 equals zero and
20559 elements 1 through 16 equal the elements 0 through 15 of
20560 the @code{src} array. The
20561 result returned from the @code{vec_srv} function is a
20562 @code{__vector} of 16 unsigned characters within which element
20563 @code{i} is computed using the C expression
20564 @code{0xff & (*((unsigned short *)(srv_array + i)) >>
20565 (0x07 & shift_distance[i]))},
20566 with this resulting value coerced to the @code{unsigned char} type.
20568 The following built-in functions are available for the PowerPC family
20569 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20571 __vector unsigned char
20572 vec_absd (__vector unsigned char arg1, __vector unsigned char arg2);
20573 __vector unsigned short
20574 vec_absd (__vector unsigned short arg1, __vector unsigned short arg2);
20575 __vector unsigned int
20576 vec_absd (__vector unsigned int arg1, __vector unsigned int arg2);
20578 __vector unsigned char
20579 vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2);
20580 __vector unsigned short
20581 vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2);
20582 __vector unsigned int
20583 vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2);
20586 The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and
20587 @code{vec_absdw} built-in functions each computes the absolute
20588 differences of the pairs of vector elements supplied in its two vector
20589 arguments, placing the absolute differences into the corresponding
20590 elements of the vector result.
20592 The following built-in functions are available for the PowerPC family
20593 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20595 __vector unsigned int vec_extract_exp (__vector float source);
20596 __vector unsigned long long int vec_extract_exp (__vector double source);
20598 __vector unsigned int vec_extract_sig (__vector float source);
20599 __vector unsigned long long int vec_extract_sig (__vector double source);
20601 __vector float vec_insert_exp (__vector unsigned int significands,
20602 __vector unsigned int exponents);
20603 __vector float vec_insert_exp (__vector unsigned float significands,
20604 __vector unsigned int exponents);
20605 __vector double vec_insert_exp (__vector unsigned long long int significands,
20606 __vector unsigned long long int exponents);
20607 __vector double vec_insert_exp (__vector unsigned double significands,
20608 __vector unsigned long long int exponents);
20610 __vector bool int vec_test_data_class (__vector float source, const int condition);
20611 __vector bool long long int vec_test_data_class (__vector double source,
20612 const int condition);
20615 The @code{vec_extract_sig} and @code{vec_extract_exp} built-in
20616 functions return vectors representing the significands and biased
20617 exponent values of their @code{source} arguments respectively.
20618 Within the result vector returned by @code{vec_extract_sig}, the
20619 @code{0x800000} bit of each vector element returned when the
20620 function's @code{source} argument is of type @code{float} is set to 1
20621 if the corresponding floating point value is in normalized form.
20622 Otherwise, this bit is set to 0. When the @code{source} argument is
20623 of type @code{double}, the @code{0x10000000000000} bit within each of
20624 the result vector's elements is set according to the same rules.
20625 Note that the sign of the significand is not represented in the result
20626 returned from the @code{vec_extract_sig} function. To extract the
20628 @code{vec_cpsgn} function, which returns a new vector within which all
20629 of the sign bits of its second argument vector are overwritten with the
20630 sign bits copied from the coresponding elements of its first argument
20631 vector, and all other (non-sign) bits of the second argument vector
20632 are copied unchanged into the result vector.
20634 The @code{vec_insert_exp} built-in functions return a vector of
20635 single- or double-precision floating
20636 point values constructed by assembling the values of their
20637 @code{significands} and @code{exponents} arguments into the
20638 corresponding elements of the returned vector.
20640 element of the result is copied from the most significant bit of the
20641 corresponding entry within the @code{significands} argument.
20642 Note that the relevant
20643 bits of the @code{significands} argument are the same, for both integer
20644 and floating point types.
20646 significand and exponent components of each element of the result are
20647 composed of the least significant bits of the corresponding
20648 @code{significands} element and the least significant bits of the
20649 corresponding @code{exponents} element.
20651 The @code{vec_test_data_class} built-in function returns a vector
20652 representing the results of testing the @code{source} vector for the
20653 condition selected by the @code{condition} argument. The
20654 @code{condition} argument must be a compile-time constant integer with
20655 value not exceeding 127. The
20656 @code{condition} argument is encoded as a bitmask with each bit
20657 enabling the testing of a different condition, as characterized by the
20661 0x20 Test for +Infinity
20662 0x10 Test for -Infinity
20663 0x08 Test for +Zero
20664 0x04 Test for -Zero
20665 0x02 Test for +Denormal
20666 0x01 Test for -Denormal
20669 If any of the enabled test conditions is true, the corresponding entry
20670 in the result vector is -1. Otherwise (all of the enabled test
20671 conditions are false), the corresponding entry of the result vector is 0.
20673 The following built-in functions are available for the PowerPC family
20674 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20676 vector unsigned int vec_rlmi (vector unsigned int, vector unsigned int,
20677 vector unsigned int);
20678 vector unsigned long long vec_rlmi (vector unsigned long long,
20679 vector unsigned long long,
20680 vector unsigned long long);
20681 vector unsigned int vec_rlnm (vector unsigned int, vector unsigned int,
20682 vector unsigned int);
20683 vector unsigned long long vec_rlnm (vector unsigned long long,
20684 vector unsigned long long,
20685 vector unsigned long long);
20686 vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int);
20687 vector unsigned long long vec_vrlnm (vector unsigned long long,
20688 vector unsigned long long);
20691 The result of @code{vec_rlmi} is obtained by rotating each element of
20692 the first argument vector left and inserting it under mask into the
20693 second argument vector. The third argument vector contains the mask
20694 beginning in bits 11:15, the mask end in bits 19:23, and the shift
20695 count in bits 27:31, of each element.
20697 The result of @code{vec_rlnm} is obtained by rotating each element of
20698 the first argument vector left and ANDing it with a mask specified by
20699 the second and third argument vectors. The second argument vector
20700 contains the shift count for each element in the low-order byte. The
20701 third argument vector contains the mask end for each element in the
20702 low-order byte, with the mask begin in the next higher byte.
20704 The result of @code{vec_vrlnm} is obtained by rotating each element
20705 of the first argument vector left and ANDing it with a mask. The
20706 second argument vector contains the mask beginning in bits 11:15,
20707 the mask end in bits 19:23, and the shift count in bits 27:31,
20710 If the ISA 3.0 instruction set additions (@option{-mcpu=power9})
20713 vector signed bool char vec_revb (vector signed char);
20714 vector signed char vec_revb (vector signed char);
20715 vector unsigned char vec_revb (vector unsigned char);
20716 vector bool short vec_revb (vector bool short);
20717 vector short vec_revb (vector short);
20718 vector unsigned short vec_revb (vector unsigned short);
20719 vector bool int vec_revb (vector bool int);
20720 vector int vec_revb (vector int);
20721 vector unsigned int vec_revb (vector unsigned int);
20722 vector float vec_revb (vector float);
20723 vector bool long long vec_revb (vector bool long long);
20724 vector long long vec_revb (vector long long);
20725 vector unsigned long long vec_revb (vector unsigned long long);
20726 vector double vec_revb (vector double);
20729 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
20732 vector long vec_revb (vector long);
20733 vector unsigned long vec_revb (vector unsigned long);
20734 vector __int128 vec_revb (vector __int128);
20735 vector __uint128 vec_revb (vector __uint128);
20738 The @code{vec_revb} built-in function reverses the bytes on an element
20739 by element basis. A vector of @code{vector unsigned char} or
20740 @code{vector signed char} reverses the bytes in the whole word.
20742 If the cryptographic instructions are enabled (@option{-mcrypto} or
20743 @option{-mcpu=power8}), the following builtins are enabled.
20746 vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long);
20748 vector unsigned char vec_sbox_be (vector unsigned char);
20750 vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long,
20751 vector unsigned long long);
20753 vector unsigned char vec_cipher_be (vector unsigned char, vector unsigned char);
20755 vector unsigned long long __builtin_crypto_vcipherlast
20756 (vector unsigned long long,
20757 vector unsigned long long);
20759 vector unsigned char vec_cipherlast_be (vector unsigned char,
20760 vector unsigned char);
20762 vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long,
20763 vector unsigned long long);
20765 vector unsigned char vec_ncipher_be (vector unsigned char,
20766 vector unsigned char);
20768 vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long,
20769 vector unsigned long long);
20771 vector unsigned char vec_ncipherlast_be (vector unsigned char,
20772 vector unsigned char);
20774 vector unsigned char __builtin_crypto_vpermxor (vector unsigned char,
20775 vector unsigned char,
20776 vector unsigned char);
20778 vector unsigned short __builtin_crypto_vpermxor (vector unsigned short,
20779 vector unsigned short,
20780 vector unsigned short);
20782 vector unsigned int __builtin_crypto_vpermxor (vector unsigned int,
20783 vector unsigned int,
20784 vector unsigned int);
20786 vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long,
20787 vector unsigned long long,
20788 vector unsigned long long);
20790 vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char,
20791 vector unsigned char);
20793 vector unsigned short __builtin_crypto_vpmsumh (vector unsigned short,
20794 vector unsigned short);
20796 vector unsigned int __builtin_crypto_vpmsumw (vector unsigned int,
20797 vector unsigned int);
20799 vector unsigned long long __builtin_crypto_vpmsumd (vector unsigned long long,
20800 vector unsigned long long);
20802 vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long,
20805 vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int);
20808 The second argument to @var{__builtin_crypto_vshasigmad} and
20809 @var{__builtin_crypto_vshasigmaw} must be a constant
20810 integer that is 0 or 1. The third argument to these built-in functions
20811 must be a constant integer in the range of 0 to 15.
20813 If the ISA 3.0 instruction set additions
20814 are enabled (@option{-mcpu=power9}), the following additional
20815 functions are available for both 32-bit and 64-bit targets.
20817 vector short vec_xl (int, vector short *);
20818 vector short vec_xl (int, short *);
20819 vector unsigned short vec_xl (int, vector unsigned short *);
20820 vector unsigned short vec_xl (int, unsigned short *);
20821 vector char vec_xl (int, vector char *);
20822 vector char vec_xl (int, char *);
20823 vector unsigned char vec_xl (int, vector unsigned char *);
20824 vector unsigned char vec_xl (int, unsigned char *);
20826 void vec_xst (vector short, int, vector short *);
20827 void vec_xst (vector short, int, short *);
20828 void vec_xst (vector unsigned short, int, vector unsigned short *);
20829 void vec_xst (vector unsigned short, int, unsigned short *);
20830 void vec_xst (vector char, int, vector char *);
20831 void vec_xst (vector char, int, char *);
20832 void vec_xst (vector unsigned char, int, vector unsigned char *);
20833 void vec_xst (vector unsigned char, int, unsigned char *);
20836 @node PowerPC AltiVec Built-in Functions Available for a Future Architecture
20837 @subsubsection PowerPC AltiVec Built-in Functions Available for a Future Architecture
20839 The following additional built-in functions are also available for the
20840 PowerPC family of processors, starting with a hypothetical CPU
20841 which may or may not be available in the future
20842 (@option{-mcpu=future}) or later:
20846 @exdent vector unsigned long long int
20847 @exdent vec_cfuge (vector unsigned long long int, vector unsigned long long int)
20849 Perform a vector centrifuge operation, as if implemented by the Future
20850 @code{vcfuged} instruction.
20854 @exdent vector unsigned long long int
20855 @exdent vec_cntlzm (vector unsigned long long int, vector unsigned long long int)
20857 Perform a vector count leading zeros under bit mask operation, as if
20858 implemented by the Future @code{vclzdm} instruction.
20862 @exdent vector unsigned long long int
20863 @exdent vec_cnttzm (vector unsigned long long int, vector unsigned long long int)
20865 Perform a vector count trailing zeros under bit mask operation, as if
20866 implemented by the Future @code{vctzdm} instruction.
20870 @exdent vector signed char
20871 @exdent vec_clrl (vector signed char a, unsigned int n)
20872 @exdent vector unsigned char
20873 @exdent vec_clrl (vector unsigned char a, unsigned int n)
20875 Clear the left-most @code{(16 - n)} bytes of vector argument @code{a}, as if
20876 implemented by the @code{vclrlb} instruction on a big-endian target
20877 and by the @code{vclrrb} instruction on a little-endian target. A
20878 value of @code{n} that is greater than 16 is treated as if it equaled 16.
20882 @exdent vector signed char
20883 @exdent vec_clrr (vector signed char a, unsigned int n)
20884 @exdent vector unsigned char
20885 @exdent vec_clrr (vector unsigned char a, unsigned int n)
20887 Clear the right-most @code{(16 - n)} bytes of vector argument @code{a}, as if
20888 implemented by the @code{vclrrb} instruction on a big-endian target
20889 and by the @code{vclrlb} instruction on a little-endian target. A
20890 value of @code{n} that is greater than 16 is treated as if it equaled 16.
20894 @exdent vector unsigned long long int
20895 @exdent vec_gnb (vector unsigned __int128, const unsigned char)
20897 Perform a 128-bit vector gather operation, as if implemented by the Future
20898 @code{vgnb} instruction. The second argument must be a literal
20899 integer value between 2 and 7 inclusive.
20903 @exdent vector unsigned long long int
20904 @exdent vec_extractl (vector unsigned char, vector unsigned char, unsigned int)
20905 @exdent vector unsigned long long int
20906 @exdent vec_extractl (vector unsigned short, vector unsigned short, unsigned int)
20907 @exdent vector unsigned long long int
20908 @exdent vec_extractl (vector unsigned int, vector unsigned int, unsigned int)
20909 @exdent vector unsigned long long int
20910 @exdent vec_extractl (vector unsigned long long, vector unsigned long long, unsigned int)
20912 Extract a single element from the vector formed by catenating this function's
20913 first two arguments at the byte offset specified by this function's
20914 third argument. On big-endian targets, this function behaves as if
20915 implemented by the Future @code{vextdubvlx}, @code{vextduhvlx},
20916 @code{vextduwvlx}, or @code{vextddvlx} instructions, depending on the
20917 types of the function's first two arguments. On little-endian
20918 targets, this function behaves as if implemented by the Future
20919 @code{vextdubvrx}, @code{vextduhvrx},
20920 @code{vextduwvrx}, or @code{vextddvrx} instructions.
20921 The byte offset of the element to be extracted is calculated
20922 by computing the remainder of dividing the third argument by 32.
20923 If this reminader value is not a multiple of the vector element size,
20924 or if its value added to the vector element size exceeds 32, the
20925 result is undefined.
20926 @findex vec_extractl
20929 @exdent vector unsigned long long int
20930 @exdent vec_extractr (vector unsigned char, vector unsigned char, unsigned int)
20931 @exdent vector unsigned long long int
20932 @exdent vec_extractr (vector unsigned short, vector unsigned short, unsigned int)
20933 @exdent vector unsigned long long int
20934 @exdent vec_extractr (vector unsigned int, vector unsigned int, unsigned int)
20935 @exdent vector unsigned long long int
20936 @exdent vec_extractr (vector unsigned long long, vector unsigned long long, unsigned int)
20938 Extract a single element from the vector formed by catenating this function's
20939 first two arguments at the byte offset calculated by subtracting this
20940 function's third argument from 31. On big-endian targets, this
20941 function behaves as if
20942 implemented by the Future
20943 @code{vextdubvrx}, @code{vextduhvrx},
20944 @code{vextduwvrx}, or @code{vextddvrx} instructions, depending on the
20945 types of the function's first two arguments.
20947 targets, this function behaves as if implemented by the Future
20948 @code{vextdubvlx}, @code{vextduhvlx},
20949 @code{vextduwvlx}, or @code{vextddvlx} instructions.
20950 The byte offset of the element to be extracted, measured from the
20951 right end of the catenation of the two vector arguments, is calculated
20952 by computing the remainder of dividing the third argument by 32.
20953 If this reminader value is not a multiple of the vector element size,
20954 or if its value added to the vector element size exceeds 32, the
20955 result is undefined.
20956 @findex vec_extractr
20959 @exdent vector unsigned long long int
20960 @exdent vec_pdep (vector unsigned long long int, vector unsigned long long int)
20962 Perform a vector parallel bits deposit operation, as if implemented by
20963 the Future @code{vpdepd} instruction.
20967 @exdent vector unsigned long long int
20968 @exdent vec_pext (vector unsigned long long int, vector unsigned long long int)
20970 Perform a vector parallel bit extract operation, as if implemented by
20971 the Future @code{vpextd} instruction.
20975 @exdent vector unsigned char vec_stril (vector unsigned char)
20976 @exdent vector signed char vec_stril (vector signed char)
20977 @exdent vector unsigned short vec_stril (vector unsigned short)
20978 @exdent vector signed short vec_stril (vector signed short)
20980 Isolate the left-most non-zero elements of the incoming vector argument,
20981 replacing all elements to the right of the left-most zero element
20982 found within the argument with zero. The typical implementation uses
20983 the @code{vstribl} or @code{vstrihl} instruction on big-endian targets
20984 and uses the @code{vstribr} or @code{vstrihr} instruction on
20985 little-endian targets.
20989 @exdent int vec_stril_p (vector unsigned char)
20990 @exdent int vec_stril_p (vector signed char)
20991 @exdent int short vec_stril_p (vector unsigned short)
20992 @exdent int vec_stril_p (vector signed short)
20994 Return a non-zero value if and only if the argument contains a zero
20995 element. The typical implementation uses
20996 the @code{vstribl.} or @code{vstrihl.} instruction on big-endian targets
20997 and uses the @code{vstribr.} or @code{vstrihr.} instruction on
20998 little-endian targets. Choose this built-in to check for presence of
20999 zero element if the same argument is also passed to @code{vec_stril}.
21000 @findex vec_stril_p
21003 @exdent vector unsigned char vec_strir (vector unsigned char)
21004 @exdent vector signed char vec_strir (vector signed char)
21005 @exdent vector unsigned short vec_strir (vector unsigned short)
21006 @exdent vector signed short vec_strir (vector signed short)
21008 Isolate the right-most non-zero elements of the incoming vector argument,
21009 replacing all elements to the left of the right-most zero element
21010 found within the argument with zero. The typical implementation uses
21011 the @code{vstribr} or @code{vstrihr} instruction on big-endian targets
21012 and uses the @code{vstribl} or @code{vstrihl} instruction on
21013 little-endian targets.
21017 @exdent int vec_strir_p (vector unsigned char)
21018 @exdent int vec_strir_p (vector signed char)
21019 @exdent int short vec_strir_p (vector unsigned short)
21020 @exdent int vec_strir_p (vector signed short)
21022 Return a non-zero value if and only if the argument contains a zero
21023 element. The typical implementation uses
21024 the @code{vstribr.} or @code{vstrihr.} instruction on big-endian targets
21025 and uses the @code{vstribl.} or @code{vstrihl.} instruction on
21026 little-endian targets. Choose this built-in to check for presence of
21027 zero element if the same argument is also passed to @code{vec_strir}.
21028 @findex vec_strir_p
21031 @exdent vector unsigned char
21032 @exdent vec_ternarylogic (vector unsigned char, vector unsigned char,
21033 vector unsigned char, const unsigned int)
21034 @exdent vector unsigned short
21035 @exdent vec_ternarylogic (vector unsigned short, vector unsigned short,
21036 vector unsigned short, const unsigned int)
21037 @exdent vector unsigned int
21038 @exdent vec_ternarylogic (vector unsigned int, vector unsigned int,
21039 vector unsigned int, const unsigned int)
21040 @exdent vector unsigned long long int
21041 @exdent vec_ternarylogic (vector unsigned long long int, vector unsigned long long int,
21042 vector unsigned long long int, const unsigned int)
21043 @exdent vector unsigned __int128
21044 @exdent vec_ternarylogic (vector unsigned __int128, vector unsigned __int128,
21045 vector unsigned __int128, const unsigned int)
21047 Perform a 128-bit vector evaluate operation, as if implemented by the
21048 Future @code{xxeval} instruction. The fourth argument must be a literal
21049 integer value between 0 and 255 inclusive.
21050 @findex vec_ternarylogic
21053 @exdent vector unsigned char vec_genpcvm (vector unsigned char, const int)
21054 @exdent vector unsigned short vec_genpcvm (vector unsigned short, const int)
21055 @exdent vector unsigned int vec_genpcvm (vector unsigned int, const int)
21056 @exdent vector unsigned int vec_genpcvm (vector unsigned long long int,
21059 Generate PCV from specified Mask size, as if implemented by the Future
21060 @code{xxgenpcvbm}, @code{xxgenpcvhm}, @code{xxgenpcvwm} instructions, where
21061 immediate value is either 0, 1, 2 or 3.
21062 @findex vec_genpcvm
21064 @node PowerPC Hardware Transactional Memory Built-in Functions
21065 @subsection PowerPC Hardware Transactional Memory Built-in Functions
21066 GCC provides two interfaces for accessing the Hardware Transactional
21067 Memory (HTM) instructions available on some of the PowerPC family
21068 of processors (eg, POWER8). The two interfaces come in a low level
21069 interface, consisting of built-in functions specific to PowerPC and a
21070 higher level interface consisting of inline functions that are common
21071 between PowerPC and S/390.
21073 @subsubsection PowerPC HTM Low Level Built-in Functions
21075 The following low level built-in functions are available with
21076 @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later.
21077 They all generate the machine instruction that is part of the name.
21079 The HTM builtins (with the exception of @code{__builtin_tbegin}) return
21080 the full 4-bit condition register value set by their associated hardware
21081 instruction. The header file @code{htmintrin.h} defines some macros that can
21082 be used to decipher the return value. The @code{__builtin_tbegin} builtin
21083 returns a simple @code{true} or @code{false} value depending on whether a transaction was
21084 successfully started or not. The arguments of the builtins match exactly the
21085 type and order of the associated hardware instruction's operands, except for
21086 the @code{__builtin_tcheck} builtin, which does not take any input arguments.
21087 Refer to the ISA manual for a description of each instruction's operands.
21090 unsigned int __builtin_tbegin (unsigned int)
21091 unsigned int __builtin_tend (unsigned int)
21093 unsigned int __builtin_tabort (unsigned int)
21094 unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int)
21095 unsigned int __builtin_tabortdci (unsigned int, unsigned int, int)
21096 unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int)
21097 unsigned int __builtin_tabortwci (unsigned int, unsigned int, int)
21099 unsigned int __builtin_tcheck (void)
21100 unsigned int __builtin_treclaim (unsigned int)
21101 unsigned int __builtin_trechkpt (void)
21102 unsigned int __builtin_tsr (unsigned int)
21105 In addition to the above HTM built-ins, we have added built-ins for
21106 some common extended mnemonics of the HTM instructions:
21109 unsigned int __builtin_tendall (void)
21110 unsigned int __builtin_tresume (void)
21111 unsigned int __builtin_tsuspend (void)
21114 Note that the semantics of the above HTM builtins are required to mimic
21115 the locking semantics used for critical sections. Builtins that are used
21116 to create a new transaction or restart a suspended transaction must have
21117 lock acquisition like semantics while those builtins that end or suspend a
21118 transaction must have lock release like semantics. Specifically, this must
21119 mimic lock semantics as specified by C++11, for example: Lock acquisition is
21120 as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE)
21121 that returns 0, and lock release is as-if an execution of
21122 __atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an
21123 implicit implementation-defined lock used for all transactions. The HTM
21124 instructions associated with with the builtins inherently provide the
21125 correct acquisition and release hardware barriers required. However,
21126 the compiler must also be prohibited from moving loads and stores across
21127 the builtins in a way that would violate their semantics. This has been
21128 accomplished by adding memory barriers to the associated HTM instructions
21129 (which is a conservative approach to provide acquire and release semantics).
21130 Earlier versions of the compiler did not treat the HTM instructions as
21131 memory barriers. A @code{__TM_FENCE__} macro has been added, which can
21132 be used to determine whether the current compiler treats HTM instructions
21133 as memory barriers or not. This allows the user to explicitly add memory
21134 barriers to their code when using an older version of the compiler.
21136 The following set of built-in functions are available to gain access
21137 to the HTM specific special purpose registers.
21140 unsigned long __builtin_get_texasr (void)
21141 unsigned long __builtin_get_texasru (void)
21142 unsigned long __builtin_get_tfhar (void)
21143 unsigned long __builtin_get_tfiar (void)
21145 void __builtin_set_texasr (unsigned long);
21146 void __builtin_set_texasru (unsigned long);
21147 void __builtin_set_tfhar (unsigned long);
21148 void __builtin_set_tfiar (unsigned long);
21151 Example usage of these low level built-in functions may look like:
21154 #include <htmintrin.h>
21156 int num_retries = 10;
21160 if (__builtin_tbegin (0))
21162 /* Transaction State Initiated. */
21163 if (is_locked (lock))
21164 __builtin_tabort (0);
21165 ... transaction code...
21166 __builtin_tend (0);
21171 /* Transaction State Failed. Use locks if the transaction
21172 failure is "persistent" or we've tried too many times. */
21173 if (num_retries-- <= 0
21174 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ()))
21176 acquire_lock (lock);
21177 ... non transactional fallback path...
21178 release_lock (lock);
21185 One final built-in function has been added that returns the value of
21186 the 2-bit Transaction State field of the Machine Status Register (MSR)
21187 as stored in @code{CR0}.
21190 unsigned long __builtin_ttest (void)
21193 This built-in can be used to determine the current transaction state
21194 using the following code example:
21197 #include <htmintrin.h>
21199 unsigned char tx_state = _HTM_STATE (__builtin_ttest ());
21201 if (tx_state == _HTM_TRANSACTIONAL)
21203 /* Code to use in transactional state. */
21205 else if (tx_state == _HTM_NONTRANSACTIONAL)
21207 /* Code to use in non-transactional state. */
21209 else if (tx_state == _HTM_SUSPENDED)
21211 /* Code to use in transaction suspended state. */
21215 @subsubsection PowerPC HTM High Level Inline Functions
21217 The following high level HTM interface is made available by including
21218 @code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU}
21219 where CPU is `power8' or later. This interface is common between PowerPC
21220 and S/390, allowing users to write one HTM source implementation that
21221 can be compiled and executed on either system.
21224 long __TM_simple_begin (void)
21225 long __TM_begin (void* const TM_buff)
21226 long __TM_end (void)
21227 void __TM_abort (void)
21228 void __TM_named_abort (unsigned char const code)
21229 void __TM_resume (void)
21230 void __TM_suspend (void)
21232 long __TM_is_user_abort (void* const TM_buff)
21233 long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code)
21234 long __TM_is_illegal (void* const TM_buff)
21235 long __TM_is_footprint_exceeded (void* const TM_buff)
21236 long __TM_nesting_depth (void* const TM_buff)
21237 long __TM_is_nested_too_deep(void* const TM_buff)
21238 long __TM_is_conflict(void* const TM_buff)
21239 long __TM_is_failure_persistent(void* const TM_buff)
21240 long __TM_failure_address(void* const TM_buff)
21241 long long __TM_failure_code(void* const TM_buff)
21244 Using these common set of HTM inline functions, we can create
21245 a more portable version of the HTM example in the previous
21246 section that will work on either PowerPC or S/390:
21249 #include <htmxlintrin.h>
21251 int num_retries = 10;
21252 TM_buff_type TM_buff;
21256 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED)
21258 /* Transaction State Initiated. */
21259 if (is_locked (lock))
21261 ... transaction code...
21267 /* Transaction State Failed. Use locks if the transaction
21268 failure is "persistent" or we've tried too many times. */
21269 if (num_retries-- <= 0
21270 || __TM_is_failure_persistent (TM_buff))
21272 acquire_lock (lock);
21273 ... non transactional fallback path...
21274 release_lock (lock);
21281 @node PowerPC Atomic Memory Operation Functions
21282 @subsection PowerPC Atomic Memory Operation Functions
21283 ISA 3.0 of the PowerPC added new atomic memory operation (amo)
21284 instructions. GCC provides support for these instructions in 64-bit
21285 environments. All of the functions are declared in the include file
21288 The functions supported are:
21293 uint32_t amo_lwat_add (uint32_t *, uint32_t);
21294 uint32_t amo_lwat_xor (uint32_t *, uint32_t);
21295 uint32_t amo_lwat_ior (uint32_t *, uint32_t);
21296 uint32_t amo_lwat_and (uint32_t *, uint32_t);
21297 uint32_t amo_lwat_umax (uint32_t *, uint32_t);
21298 uint32_t amo_lwat_umin (uint32_t *, uint32_t);
21299 uint32_t amo_lwat_swap (uint32_t *, uint32_t);
21301 int32_t amo_lwat_sadd (int32_t *, int32_t);
21302 int32_t amo_lwat_smax (int32_t *, int32_t);
21303 int32_t amo_lwat_smin (int32_t *, int32_t);
21304 int32_t amo_lwat_sswap (int32_t *, int32_t);
21306 uint64_t amo_ldat_add (uint64_t *, uint64_t);
21307 uint64_t amo_ldat_xor (uint64_t *, uint64_t);
21308 uint64_t amo_ldat_ior (uint64_t *, uint64_t);
21309 uint64_t amo_ldat_and (uint64_t *, uint64_t);
21310 uint64_t amo_ldat_umax (uint64_t *, uint64_t);
21311 uint64_t amo_ldat_umin (uint64_t *, uint64_t);
21312 uint64_t amo_ldat_swap (uint64_t *, uint64_t);
21314 int64_t amo_ldat_sadd (int64_t *, int64_t);
21315 int64_t amo_ldat_smax (int64_t *, int64_t);
21316 int64_t amo_ldat_smin (int64_t *, int64_t);
21317 int64_t amo_ldat_sswap (int64_t *, int64_t);
21319 void amo_stwat_add (uint32_t *, uint32_t);
21320 void amo_stwat_xor (uint32_t *, uint32_t);
21321 void amo_stwat_ior (uint32_t *, uint32_t);
21322 void amo_stwat_and (uint32_t *, uint32_t);
21323 void amo_stwat_umax (uint32_t *, uint32_t);
21324 void amo_stwat_umin (uint32_t *, uint32_t);
21326 void amo_stwat_sadd (int32_t *, int32_t);
21327 void amo_stwat_smax (int32_t *, int32_t);
21328 void amo_stwat_smin (int32_t *, int32_t);
21330 void amo_stdat_add (uint64_t *, uint64_t);
21331 void amo_stdat_xor (uint64_t *, uint64_t);
21332 void amo_stdat_ior (uint64_t *, uint64_t);
21333 void amo_stdat_and (uint64_t *, uint64_t);
21334 void amo_stdat_umax (uint64_t *, uint64_t);
21335 void amo_stdat_umin (uint64_t *, uint64_t);
21337 void amo_stdat_sadd (int64_t *, int64_t);
21338 void amo_stdat_smax (int64_t *, int64_t);
21339 void amo_stdat_smin (int64_t *, int64_t);
21342 @node RX Built-in Functions
21343 @subsection RX Built-in Functions
21344 GCC supports some of the RX instructions which cannot be expressed in
21345 the C programming language via the use of built-in functions. The
21346 following functions are supported:
21348 @deftypefn {Built-in Function} void __builtin_rx_brk (void)
21349 Generates the @code{brk} machine instruction.
21352 @deftypefn {Built-in Function} void __builtin_rx_clrpsw (int)
21353 Generates the @code{clrpsw} machine instruction to clear the specified
21354 bit in the processor status word.
21357 @deftypefn {Built-in Function} void __builtin_rx_int (int)
21358 Generates the @code{int} machine instruction to generate an interrupt
21359 with the specified value.
21362 @deftypefn {Built-in Function} void __builtin_rx_machi (int, int)
21363 Generates the @code{machi} machine instruction to add the result of
21364 multiplying the top 16 bits of the two arguments into the
21368 @deftypefn {Built-in Function} void __builtin_rx_maclo (int, int)
21369 Generates the @code{maclo} machine instruction to add the result of
21370 multiplying the bottom 16 bits of the two arguments into the
21374 @deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int)
21375 Generates the @code{mulhi} machine instruction to place the result of
21376 multiplying the top 16 bits of the two arguments into the
21380 @deftypefn {Built-in Function} void __builtin_rx_mullo (int, int)
21381 Generates the @code{mullo} machine instruction to place the result of
21382 multiplying the bottom 16 bits of the two arguments into the
21386 @deftypefn {Built-in Function} int __builtin_rx_mvfachi (void)
21387 Generates the @code{mvfachi} machine instruction to read the top
21388 32 bits of the accumulator.
21391 @deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void)
21392 Generates the @code{mvfacmi} machine instruction to read the middle
21393 32 bits of the accumulator.
21396 @deftypefn {Built-in Function} int __builtin_rx_mvfc (int)
21397 Generates the @code{mvfc} machine instruction which reads the control
21398 register specified in its argument and returns its value.
21401 @deftypefn {Built-in Function} void __builtin_rx_mvtachi (int)
21402 Generates the @code{mvtachi} machine instruction to set the top
21403 32 bits of the accumulator.
21406 @deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int)
21407 Generates the @code{mvtaclo} machine instruction to set the bottom
21408 32 bits of the accumulator.
21411 @deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val)
21412 Generates the @code{mvtc} machine instruction which sets control
21413 register number @code{reg} to @code{val}.
21416 @deftypefn {Built-in Function} void __builtin_rx_mvtipl (int)
21417 Generates the @code{mvtipl} machine instruction set the interrupt
21421 @deftypefn {Built-in Function} void __builtin_rx_racw (int)
21422 Generates the @code{racw} machine instruction to round the accumulator
21423 according to the specified mode.
21426 @deftypefn {Built-in Function} int __builtin_rx_revw (int)
21427 Generates the @code{revw} machine instruction which swaps the bytes in
21428 the argument so that bits 0--7 now occupy bits 8--15 and vice versa,
21429 and also bits 16--23 occupy bits 24--31 and vice versa.
21432 @deftypefn {Built-in Function} void __builtin_rx_rmpa (void)
21433 Generates the @code{rmpa} machine instruction which initiates a
21434 repeated multiply and accumulate sequence.
21437 @deftypefn {Built-in Function} void __builtin_rx_round (float)
21438 Generates the @code{round} machine instruction which returns the
21439 floating-point argument rounded according to the current rounding mode
21440 set in the floating-point status word register.
21443 @deftypefn {Built-in Function} int __builtin_rx_sat (int)
21444 Generates the @code{sat} machine instruction which returns the
21445 saturated value of the argument.
21448 @deftypefn {Built-in Function} void __builtin_rx_setpsw (int)
21449 Generates the @code{setpsw} machine instruction to set the specified
21450 bit in the processor status word.
21453 @deftypefn {Built-in Function} void __builtin_rx_wait (void)
21454 Generates the @code{wait} machine instruction.
21457 @node S/390 System z Built-in Functions
21458 @subsection S/390 System z Built-in Functions
21459 @deftypefn {Built-in Function} int __builtin_tbegin (void*)
21460 Generates the @code{tbegin} machine instruction starting a
21461 non-constrained hardware transaction. If the parameter is non-NULL the
21462 memory area is used to store the transaction diagnostic buffer and
21463 will be passed as first operand to @code{tbegin}. This buffer can be
21464 defined using the @code{struct __htm_tdb} C struct defined in
21465 @code{htmintrin.h} and must reside on a double-word boundary. The
21466 second tbegin operand is set to @code{0xff0c}. This enables
21467 save/restore of all GPRs and disables aborts for FPR and AR
21468 manipulations inside the transaction body. The condition code set by
21469 the tbegin instruction is returned as integer value. The tbegin
21470 instruction by definition overwrites the content of all FPRs. The
21471 compiler will generate code which saves and restores the FPRs. For
21472 soft-float code it is recommended to used the @code{*_nofloat}
21473 variant. In order to prevent a TDB from being written it is required
21474 to pass a constant zero value as parameter. Passing a zero value
21475 through a variable is not sufficient. Although modifications of
21476 access registers inside the transaction will not trigger an
21477 transaction abort it is not supported to actually modify them. Access
21478 registers do not get saved when entering a transaction. They will have
21479 undefined state when reaching the abort code.
21482 Macros for the possible return codes of tbegin are defined in the
21483 @code{htmintrin.h} header file:
21486 @item _HTM_TBEGIN_STARTED
21487 @code{tbegin} has been executed as part of normal processing. The
21488 transaction body is supposed to be executed.
21489 @item _HTM_TBEGIN_INDETERMINATE
21490 The transaction was aborted due to an indeterminate condition which
21491 might be persistent.
21492 @item _HTM_TBEGIN_TRANSIENT
21493 The transaction aborted due to a transient failure. The transaction
21494 should be re-executed in that case.
21495 @item _HTM_TBEGIN_PERSISTENT
21496 The transaction aborted due to a persistent failure. Re-execution
21497 under same circumstances will not be productive.
21500 @defmac _HTM_FIRST_USER_ABORT_CODE
21501 The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h}
21502 specifies the first abort code which can be used for
21503 @code{__builtin_tabort}. Values below this threshold are reserved for
21507 @deftp {Data type} {struct __htm_tdb}
21508 The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes
21509 the structure of the transaction diagnostic block as specified in the
21510 Principles of Operation manual chapter 5-91.
21513 @deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*)
21514 Same as @code{__builtin_tbegin} but without FPR saves and restores.
21515 Using this variant in code making use of FPRs will leave the FPRs in
21516 undefined state when entering the transaction abort handler code.
21519 @deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int)
21520 In addition to @code{__builtin_tbegin} a loop for transient failures
21521 is generated. If tbegin returns a condition code of 2 the transaction
21522 will be retried as often as specified in the second argument. The
21523 perform processor assist instruction is used to tell the CPU about the
21524 number of fails so far.
21527 @deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int)
21528 Same as @code{__builtin_tbegin_retry} but without FPR saves and
21529 restores. Using this variant in code making use of FPRs will leave
21530 the FPRs in undefined state when entering the transaction abort
21534 @deftypefn {Built-in Function} void __builtin_tbeginc (void)
21535 Generates the @code{tbeginc} machine instruction starting a constrained
21536 hardware transaction. The second operand is set to @code{0xff08}.
21539 @deftypefn {Built-in Function} int __builtin_tend (void)
21540 Generates the @code{tend} machine instruction finishing a transaction
21541 and making the changes visible to other threads. The condition code
21542 generated by tend is returned as integer value.
21545 @deftypefn {Built-in Function} void __builtin_tabort (int)
21546 Generates the @code{tabort} machine instruction with the specified
21547 abort code. Abort codes from 0 through 255 are reserved and will
21548 result in an error message.
21551 @deftypefn {Built-in Function} void __builtin_tx_assist (int)
21552 Generates the @code{ppa rX,rY,1} machine instruction. Where the
21553 integer parameter is loaded into rX and a value of zero is loaded into
21554 rY. The integer parameter specifies the number of times the
21555 transaction repeatedly aborted.
21558 @deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void)
21559 Generates the @code{etnd} machine instruction. The current nesting
21560 depth is returned as integer value. For a nesting depth of 0 the code
21561 is not executed as part of an transaction.
21564 @deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t)
21566 Generates the @code{ntstg} machine instruction. The second argument
21567 is written to the first arguments location. The store operation will
21568 not be rolled-back in case of an transaction abort.
21571 @node SH Built-in Functions
21572 @subsection SH Built-in Functions
21573 The following built-in functions are supported on the SH1, SH2, SH3 and SH4
21574 families of processors:
21576 @deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr})
21577 Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually
21578 used by system code that manages threads and execution contexts. The compiler
21579 normally does not generate code that modifies the contents of @samp{GBR} and
21580 thus the value is preserved across function calls. Changing the @samp{GBR}
21581 value in user code must be done with caution, since the compiler might use
21582 @samp{GBR} in order to access thread local variables.
21586 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
21587 Returns the value that is currently set in the @samp{GBR} register.
21588 Memory loads and stores that use the thread pointer as a base address are
21589 turned into @samp{GBR} based displacement loads and stores, if possible.
21597 int get_tcb_value (void)
21599 // Generate @samp{mov.l @@(8,gbr),r0} instruction
21600 return ((my_tcb*)__builtin_thread_pointer ())->c;
21606 @deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void)
21607 Returns the value that is currently set in the @samp{FPSCR} register.
21610 @deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val})
21611 Sets the @samp{FPSCR} register to the specified value @var{val}, while
21612 preserving the current values of the FR, SZ and PR bits.
21615 @node SPARC VIS Built-in Functions
21616 @subsection SPARC VIS Built-in Functions
21618 GCC supports SIMD operations on the SPARC using both the generic vector
21619 extensions (@pxref{Vector Extensions}) as well as built-in functions for
21620 the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis}
21621 switch, the VIS extension is exposed as the following built-in functions:
21624 typedef int v1si __attribute__ ((vector_size (4)));
21625 typedef int v2si __attribute__ ((vector_size (8)));
21626 typedef short v4hi __attribute__ ((vector_size (8)));
21627 typedef short v2hi __attribute__ ((vector_size (4)));
21628 typedef unsigned char v8qi __attribute__ ((vector_size (8)));
21629 typedef unsigned char v4qi __attribute__ ((vector_size (4)));
21631 void __builtin_vis_write_gsr (int64_t);
21632 int64_t __builtin_vis_read_gsr (void);
21634 void * __builtin_vis_alignaddr (void *, long);
21635 void * __builtin_vis_alignaddrl (void *, long);
21636 int64_t __builtin_vis_faligndatadi (int64_t, int64_t);
21637 v2si __builtin_vis_faligndatav2si (v2si, v2si);
21638 v4hi __builtin_vis_faligndatav4hi (v4si, v4si);
21639 v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi);
21641 v4hi __builtin_vis_fexpand (v4qi);
21643 v4hi __builtin_vis_fmul8x16 (v4qi, v4hi);
21644 v4hi __builtin_vis_fmul8x16au (v4qi, v2hi);
21645 v4hi __builtin_vis_fmul8x16al (v4qi, v2hi);
21646 v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi);
21647 v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi);
21648 v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi);
21649 v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi);
21651 v4qi __builtin_vis_fpack16 (v4hi);
21652 v8qi __builtin_vis_fpack32 (v2si, v8qi);
21653 v2hi __builtin_vis_fpackfix (v2si);
21654 v8qi __builtin_vis_fpmerge (v4qi, v4qi);
21656 int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t);
21658 long __builtin_vis_edge8 (void *, void *);
21659 long __builtin_vis_edge8l (void *, void *);
21660 long __builtin_vis_edge16 (void *, void *);
21661 long __builtin_vis_edge16l (void *, void *);
21662 long __builtin_vis_edge32 (void *, void *);
21663 long __builtin_vis_edge32l (void *, void *);
21665 long __builtin_vis_fcmple16 (v4hi, v4hi);
21666 long __builtin_vis_fcmple32 (v2si, v2si);
21667 long __builtin_vis_fcmpne16 (v4hi, v4hi);
21668 long __builtin_vis_fcmpne32 (v2si, v2si);
21669 long __builtin_vis_fcmpgt16 (v4hi, v4hi);
21670 long __builtin_vis_fcmpgt32 (v2si, v2si);
21671 long __builtin_vis_fcmpeq16 (v4hi, v4hi);
21672 long __builtin_vis_fcmpeq32 (v2si, v2si);
21674 v4hi __builtin_vis_fpadd16 (v4hi, v4hi);
21675 v2hi __builtin_vis_fpadd16s (v2hi, v2hi);
21676 v2si __builtin_vis_fpadd32 (v2si, v2si);
21677 v1si __builtin_vis_fpadd32s (v1si, v1si);
21678 v4hi __builtin_vis_fpsub16 (v4hi, v4hi);
21679 v2hi __builtin_vis_fpsub16s (v2hi, v2hi);
21680 v2si __builtin_vis_fpsub32 (v2si, v2si);
21681 v1si __builtin_vis_fpsub32s (v1si, v1si);
21683 long __builtin_vis_array8 (long, long);
21684 long __builtin_vis_array16 (long, long);
21685 long __builtin_vis_array32 (long, long);
21688 When you use the @option{-mvis2} switch, the VIS version 2.0 built-in
21689 functions also become available:
21692 long __builtin_vis_bmask (long, long);
21693 int64_t __builtin_vis_bshuffledi (int64_t, int64_t);
21694 v2si __builtin_vis_bshufflev2si (v2si, v2si);
21695 v4hi __builtin_vis_bshufflev2si (v4hi, v4hi);
21696 v8qi __builtin_vis_bshufflev2si (v8qi, v8qi);
21698 long __builtin_vis_edge8n (void *, void *);
21699 long __builtin_vis_edge8ln (void *, void *);
21700 long __builtin_vis_edge16n (void *, void *);
21701 long __builtin_vis_edge16ln (void *, void *);
21702 long __builtin_vis_edge32n (void *, void *);
21703 long __builtin_vis_edge32ln (void *, void *);
21706 When you use the @option{-mvis3} switch, the VIS version 3.0 built-in
21707 functions also become available:
21710 void __builtin_vis_cmask8 (long);
21711 void __builtin_vis_cmask16 (long);
21712 void __builtin_vis_cmask32 (long);
21714 v4hi __builtin_vis_fchksm16 (v4hi, v4hi);
21716 v4hi __builtin_vis_fsll16 (v4hi, v4hi);
21717 v4hi __builtin_vis_fslas16 (v4hi, v4hi);
21718 v4hi __builtin_vis_fsrl16 (v4hi, v4hi);
21719 v4hi __builtin_vis_fsra16 (v4hi, v4hi);
21720 v2si __builtin_vis_fsll16 (v2si, v2si);
21721 v2si __builtin_vis_fslas16 (v2si, v2si);
21722 v2si __builtin_vis_fsrl16 (v2si, v2si);
21723 v2si __builtin_vis_fsra16 (v2si, v2si);
21725 long __builtin_vis_pdistn (v8qi, v8qi);
21727 v4hi __builtin_vis_fmean16 (v4hi, v4hi);
21729 int64_t __builtin_vis_fpadd64 (int64_t, int64_t);
21730 int64_t __builtin_vis_fpsub64 (int64_t, int64_t);
21732 v4hi __builtin_vis_fpadds16 (v4hi, v4hi);
21733 v2hi __builtin_vis_fpadds16s (v2hi, v2hi);
21734 v4hi __builtin_vis_fpsubs16 (v4hi, v4hi);
21735 v2hi __builtin_vis_fpsubs16s (v2hi, v2hi);
21736 v2si __builtin_vis_fpadds32 (v2si, v2si);
21737 v1si __builtin_vis_fpadds32s (v1si, v1si);
21738 v2si __builtin_vis_fpsubs32 (v2si, v2si);
21739 v1si __builtin_vis_fpsubs32s (v1si, v1si);
21741 long __builtin_vis_fucmple8 (v8qi, v8qi);
21742 long __builtin_vis_fucmpne8 (v8qi, v8qi);
21743 long __builtin_vis_fucmpgt8 (v8qi, v8qi);
21744 long __builtin_vis_fucmpeq8 (v8qi, v8qi);
21746 float __builtin_vis_fhadds (float, float);
21747 double __builtin_vis_fhaddd (double, double);
21748 float __builtin_vis_fhsubs (float, float);
21749 double __builtin_vis_fhsubd (double, double);
21750 float __builtin_vis_fnhadds (float, float);
21751 double __builtin_vis_fnhaddd (double, double);
21753 int64_t __builtin_vis_umulxhi (int64_t, int64_t);
21754 int64_t __builtin_vis_xmulx (int64_t, int64_t);
21755 int64_t __builtin_vis_xmulxhi (int64_t, int64_t);
21758 When you use the @option{-mvis4} switch, the VIS version 4.0 built-in
21759 functions also become available:
21762 v8qi __builtin_vis_fpadd8 (v8qi, v8qi);
21763 v8qi __builtin_vis_fpadds8 (v8qi, v8qi);
21764 v8qi __builtin_vis_fpaddus8 (v8qi, v8qi);
21765 v4hi __builtin_vis_fpaddus16 (v4hi, v4hi);
21767 v8qi __builtin_vis_fpsub8 (v8qi, v8qi);
21768 v8qi __builtin_vis_fpsubs8 (v8qi, v8qi);
21769 v8qi __builtin_vis_fpsubus8 (v8qi, v8qi);
21770 v4hi __builtin_vis_fpsubus16 (v4hi, v4hi);
21772 long __builtin_vis_fpcmple8 (v8qi, v8qi);
21773 long __builtin_vis_fpcmpgt8 (v8qi, v8qi);
21774 long __builtin_vis_fpcmpule16 (v4hi, v4hi);
21775 long __builtin_vis_fpcmpugt16 (v4hi, v4hi);
21776 long __builtin_vis_fpcmpule32 (v2si, v2si);
21777 long __builtin_vis_fpcmpugt32 (v2si, v2si);
21779 v8qi __builtin_vis_fpmax8 (v8qi, v8qi);
21780 v4hi __builtin_vis_fpmax16 (v4hi, v4hi);
21781 v2si __builtin_vis_fpmax32 (v2si, v2si);
21783 v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi);
21784 v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi);
21785 v2si __builtin_vis_fpmaxu32 (v2si, v2si);
21787 v8qi __builtin_vis_fpmin8 (v8qi, v8qi);
21788 v4hi __builtin_vis_fpmin16 (v4hi, v4hi);
21789 v2si __builtin_vis_fpmin32 (v2si, v2si);
21791 v8qi __builtin_vis_fpminu8 (v8qi, v8qi);
21792 v4hi __builtin_vis_fpminu16 (v4hi, v4hi);
21793 v2si __builtin_vis_fpminu32 (v2si, v2si);
21796 When you use the @option{-mvis4b} switch, the VIS version 4.0B
21797 built-in functions also become available:
21800 v8qi __builtin_vis_dictunpack8 (double, int);
21801 v4hi __builtin_vis_dictunpack16 (double, int);
21802 v2si __builtin_vis_dictunpack32 (double, int);
21804 long __builtin_vis_fpcmple8shl (v8qi, v8qi, int);
21805 long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int);
21806 long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int);
21807 long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int);
21809 long __builtin_vis_fpcmple16shl (v4hi, v4hi, int);
21810 long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int);
21811 long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int);
21812 long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int);
21814 long __builtin_vis_fpcmple32shl (v2si, v2si, int);
21815 long __builtin_vis_fpcmpgt32shl (v2si, v2si, int);
21816 long __builtin_vis_fpcmpeq32shl (v2si, v2si, int);
21817 long __builtin_vis_fpcmpne32shl (v2si, v2si, int);
21819 long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int);
21820 long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int);
21821 long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int);
21822 long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int);
21823 long __builtin_vis_fpcmpule32shl (v2si, v2si, int);
21824 long __builtin_vis_fpcmpugt32shl (v2si, v2si, int);
21826 long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int);
21827 long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int);
21828 long __builtin_vis_fpcmpde32shl (v2si, v2si, int);
21830 long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int);
21831 long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int);
21832 long __builtin_vis_fpcmpur32shl (v2si, v2si, int);
21835 @node TI C6X Built-in Functions
21836 @subsection TI C6X Built-in Functions
21838 GCC provides intrinsics to access certain instructions of the TI C6X
21839 processors. These intrinsics, listed below, are available after
21840 inclusion of the @code{c6x_intrinsics.h} header file. They map directly
21841 to C6X instructions.
21845 int _sadd (int, int)
21846 int _ssub (int, int)
21847 int _sadd2 (int, int)
21848 int _ssub2 (int, int)
21849 long long _mpy2 (int, int)
21850 long long _smpy2 (int, int)
21851 int _add4 (int, int)
21852 int _sub4 (int, int)
21853 int _saddu4 (int, int)
21855 int _smpy (int, int)
21856 int _smpyh (int, int)
21857 int _smpyhl (int, int)
21858 int _smpylh (int, int)
21860 int _sshl (int, int)
21861 int _subc (int, int)
21863 int _avg2 (int, int)
21864 int _avgu4 (int, int)
21866 int _clrr (int, int)
21867 int _extr (int, int)
21868 int _extru (int, int)
21874 @node TILE-Gx Built-in Functions
21875 @subsection TILE-Gx Built-in Functions
21877 GCC provides intrinsics to access every instruction of the TILE-Gx
21878 processor. The intrinsics are of the form:
21882 unsigned long long __insn_@var{op} (...)
21886 Where @var{op} is the name of the instruction. Refer to the ISA manual
21887 for the complete list of instructions.
21889 GCC also provides intrinsics to directly access the network registers.
21890 The intrinsics are:
21894 unsigned long long __tile_idn0_receive (void)
21895 unsigned long long __tile_idn1_receive (void)
21896 unsigned long long __tile_udn0_receive (void)
21897 unsigned long long __tile_udn1_receive (void)
21898 unsigned long long __tile_udn2_receive (void)
21899 unsigned long long __tile_udn3_receive (void)
21900 void __tile_idn_send (unsigned long long)
21901 void __tile_udn_send (unsigned long long)
21905 The intrinsic @code{void __tile_network_barrier (void)} is used to
21906 guarantee that no network operations before it are reordered with
21909 @node TILEPro Built-in Functions
21910 @subsection TILEPro Built-in Functions
21912 GCC provides intrinsics to access every instruction of the TILEPro
21913 processor. The intrinsics are of the form:
21917 unsigned __insn_@var{op} (...)
21922 where @var{op} is the name of the instruction. Refer to the ISA manual
21923 for the complete list of instructions.
21925 GCC also provides intrinsics to directly access the network registers.
21926 The intrinsics are:
21930 unsigned __tile_idn0_receive (void)
21931 unsigned __tile_idn1_receive (void)
21932 unsigned __tile_sn_receive (void)
21933 unsigned __tile_udn0_receive (void)
21934 unsigned __tile_udn1_receive (void)
21935 unsigned __tile_udn2_receive (void)
21936 unsigned __tile_udn3_receive (void)
21937 void __tile_idn_send (unsigned)
21938 void __tile_sn_send (unsigned)
21939 void __tile_udn_send (unsigned)
21943 The intrinsic @code{void __tile_network_barrier (void)} is used to
21944 guarantee that no network operations before it are reordered with
21947 @node x86 Built-in Functions
21948 @subsection x86 Built-in Functions
21950 These built-in functions are available for the x86-32 and x86-64 family
21951 of computers, depending on the command-line switches used.
21953 If you specify command-line switches such as @option{-msse},
21954 the compiler could use the extended instruction sets even if the built-ins
21955 are not used explicitly in the program. For this reason, applications
21956 that perform run-time CPU detection must compile separate files for each
21957 supported architecture, using the appropriate flags. In particular,
21958 the file containing the CPU detection code should be compiled without
21961 The following machine modes are available for use with MMX built-in functions
21962 (@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers,
21963 @code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a
21964 vector of eight 8-bit integers. Some of the built-in functions operate on
21965 MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode.
21967 If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector
21968 of two 32-bit floating-point values.
21970 If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit
21971 floating-point values. Some instructions use a vector of four 32-bit
21972 integers, these use @code{V4SI}. Finally, some instructions operate on an
21973 entire vector register, interpreting it as a 128-bit integer, these use mode
21976 The x86-32 and x86-64 family of processors use additional built-in
21977 functions for efficient use of @code{TF} (@code{__float128}) 128-bit
21978 floating point and @code{TC} 128-bit complex floating-point values.
21980 The following floating-point built-in functions are always available. All
21981 of them implement the function that is part of the name.
21984 __float128 __builtin_fabsq (__float128)
21985 __float128 __builtin_copysignq (__float128, __float128)
21988 The following built-in functions are always available.
21991 @item __float128 __builtin_infq (void)
21992 Similar to @code{__builtin_inf}, except the return type is @code{__float128}.
21993 @findex __builtin_infq
21995 @item __float128 __builtin_huge_valq (void)
21996 Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}.
21997 @findex __builtin_huge_valq
21999 @item __float128 __builtin_nanq (void)
22000 Similar to @code{__builtin_nan}, except the return type is @code{__float128}.
22001 @findex __builtin_nanq
22003 @item __float128 __builtin_nansq (void)
22004 Similar to @code{__builtin_nans}, except the return type is @code{__float128}.
22005 @findex __builtin_nansq
22008 The following built-in function is always available.
22011 @item void __builtin_ia32_pause (void)
22012 Generates the @code{pause} machine instruction with a compiler memory
22016 The following built-in functions are always available and can be used to
22017 check the target platform type.
22019 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
22020 This function runs the CPU detection code to check the type of CPU and the
22021 features supported. This built-in function needs to be invoked along with the built-in functions
22022 to check CPU type and features, @code{__builtin_cpu_is} and
22023 @code{__builtin_cpu_supports}, only when used in a function that is
22024 executed before any constructors are called. The CPU detection code is
22025 automatically executed in a very high priority constructor.
22027 For example, this function has to be used in @code{ifunc} resolvers that
22028 check for CPU type using the built-in functions @code{__builtin_cpu_is}
22029 and @code{__builtin_cpu_supports}, or in constructors on targets that
22030 don't support constructor priority.
22033 static void (*resolve_memcpy (void)) (void)
22035 // ifunc resolvers fire before constructors, explicitly call the init
22037 __builtin_cpu_init ();
22038 if (__builtin_cpu_supports ("ssse3"))
22039 return ssse3_memcpy; // super fast memcpy with ssse3 instructions.
22041 return default_memcpy;
22044 void *memcpy (void *, const void *, size_t)
22045 __attribute__ ((ifunc ("resolve_memcpy")));
22050 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
22051 This function returns a positive integer if the run-time CPU
22052 is of type @var{cpuname}
22053 and returns @code{0} otherwise. The following CPU names can be detected:
22066 Intel Silvermont CPU.
22075 Intel Core i7 Nehalem CPU.
22078 Intel Core i7 Westmere CPU.
22081 Intel Core i7 Sandy Bridge CPU.
22084 Intel Core i7 Ivy Bridge CPU.
22087 Intel Core i7 Haswell CPU.
22090 Intel Core i7 Broadwell CPU.
22093 Intel Core i7 Skylake CPU.
22095 @item skylake-avx512
22096 Intel Core i7 Skylake AVX512 CPU.
22099 Intel Core i7 Cannon Lake CPU.
22101 @item icelake-client
22102 Intel Core i7 Ice Lake Client CPU.
22104 @item icelake-server
22105 Intel Core i7 Ice Lake Server CPU.
22108 Intel Core i7 Cascadelake CPU.
22111 Intel Core i7 Tigerlake CPU.
22114 Intel Core i7 Cooperlake CPU.
22117 Intel Atom Bonnell CPU.
22120 Intel Atom Silvermont CPU.
22123 Intel Atom Goldmont CPU.
22125 @item goldmont-plus
22126 Intel Atom Goldmont Plus CPU.
22129 Intel Atom Tremont CPU.
22132 Intel Knights Landing CPU.
22135 Intel Knights Mill CPU.
22138 AMD Family 10h CPU.
22141 AMD Family 10h Barcelona CPU.
22144 AMD Family 10h Shanghai CPU.
22147 AMD Family 10h Istanbul CPU.
22150 AMD Family 14h CPU.
22153 AMD Family 15h CPU.
22156 AMD Family 15h Bulldozer version 1.
22159 AMD Family 15h Bulldozer version 2.
22162 AMD Family 15h Bulldozer version 3.
22165 AMD Family 15h Bulldozer version 4.
22168 AMD Family 16h CPU.
22171 AMD Family 17h CPU.
22174 AMD Family 17h Zen version 1.
22177 AMD Family 17h Zen version 2.
22180 Here is an example:
22182 if (__builtin_cpu_is ("corei7"))
22184 do_corei7 (); // Core i7 specific implementation.
22188 do_generic (); // Generic implementation.
22193 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
22194 This function returns a positive integer if the run-time CPU
22195 supports @var{feature}
22196 and returns @code{0} otherwise. The following features can be detected:
22204 POPCNT instruction.
22212 SSSE3 instructions.
22214 SSE4.1 instructions.
22216 SSE4.2 instructions.
22222 SSE4A instructions.
22230 AVX512F instructions.
22238 PCLMUL instructions.
22240 AVX512VL instructions.
22242 AVX512BW instructions.
22244 AVX512DQ instructions.
22246 AVX512CD instructions.
22248 AVX512ER instructions.
22250 AVX512PF instructions.
22252 AVX512VBMI instructions.
22254 AVX512IFMA instructions.
22256 AVX5124VNNIW instructions.
22258 AVX5124FMAPS instructions.
22259 @item avx512vpopcntdq
22260 AVX512VPOPCNTDQ instructions.
22262 AVX512VBMI2 instructions.
22266 VPCLMULQDQ instructions.
22268 AVX512VNNI instructions.
22270 AVX512BITALG instructions.
22273 Here is an example:
22275 if (__builtin_cpu_supports ("popcnt"))
22277 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc");
22281 count = generic_countbits (n); //generic implementation.
22286 The following built-in functions are made available by @option{-mmmx}.
22287 All of them generate the machine instruction that is part of the name.
22290 v8qi __builtin_ia32_paddb (v8qi, v8qi)
22291 v4hi __builtin_ia32_paddw (v4hi, v4hi)
22292 v2si __builtin_ia32_paddd (v2si, v2si)
22293 v8qi __builtin_ia32_psubb (v8qi, v8qi)
22294 v4hi __builtin_ia32_psubw (v4hi, v4hi)
22295 v2si __builtin_ia32_psubd (v2si, v2si)
22296 v8qi __builtin_ia32_paddsb (v8qi, v8qi)
22297 v4hi __builtin_ia32_paddsw (v4hi, v4hi)
22298 v8qi __builtin_ia32_psubsb (v8qi, v8qi)
22299 v4hi __builtin_ia32_psubsw (v4hi, v4hi)
22300 v8qi __builtin_ia32_paddusb (v8qi, v8qi)
22301 v4hi __builtin_ia32_paddusw (v4hi, v4hi)
22302 v8qi __builtin_ia32_psubusb (v8qi, v8qi)
22303 v4hi __builtin_ia32_psubusw (v4hi, v4hi)
22304 v4hi __builtin_ia32_pmullw (v4hi, v4hi)
22305 v4hi __builtin_ia32_pmulhw (v4hi, v4hi)
22306 di __builtin_ia32_pand (di, di)
22307 di __builtin_ia32_pandn (di,di)
22308 di __builtin_ia32_por (di, di)
22309 di __builtin_ia32_pxor (di, di)
22310 v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi)
22311 v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi)
22312 v2si __builtin_ia32_pcmpeqd (v2si, v2si)
22313 v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi)
22314 v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi)
22315 v2si __builtin_ia32_pcmpgtd (v2si, v2si)
22316 v8qi __builtin_ia32_punpckhbw (v8qi, v8qi)
22317 v4hi __builtin_ia32_punpckhwd (v4hi, v4hi)
22318 v2si __builtin_ia32_punpckhdq (v2si, v2si)
22319 v8qi __builtin_ia32_punpcklbw (v8qi, v8qi)
22320 v4hi __builtin_ia32_punpcklwd (v4hi, v4hi)
22321 v2si __builtin_ia32_punpckldq (v2si, v2si)
22322 v8qi __builtin_ia32_packsswb (v4hi, v4hi)
22323 v4hi __builtin_ia32_packssdw (v2si, v2si)
22324 v8qi __builtin_ia32_packuswb (v4hi, v4hi)
22326 v4hi __builtin_ia32_psllw (v4hi, v4hi)
22327 v2si __builtin_ia32_pslld (v2si, v2si)
22328 v1di __builtin_ia32_psllq (v1di, v1di)
22329 v4hi __builtin_ia32_psrlw (v4hi, v4hi)
22330 v2si __builtin_ia32_psrld (v2si, v2si)
22331 v1di __builtin_ia32_psrlq (v1di, v1di)
22332 v4hi __builtin_ia32_psraw (v4hi, v4hi)
22333 v2si __builtin_ia32_psrad (v2si, v2si)
22334 v4hi __builtin_ia32_psllwi (v4hi, int)
22335 v2si __builtin_ia32_pslldi (v2si, int)
22336 v1di __builtin_ia32_psllqi (v1di, int)
22337 v4hi __builtin_ia32_psrlwi (v4hi, int)
22338 v2si __builtin_ia32_psrldi (v2si, int)
22339 v1di __builtin_ia32_psrlqi (v1di, int)
22340 v4hi __builtin_ia32_psrawi (v4hi, int)
22341 v2si __builtin_ia32_psradi (v2si, int)
22345 The following built-in functions are made available either with
22346 @option{-msse}, or with @option{-m3dnowa}. All of them generate
22347 the machine instruction that is part of the name.
22350 v4hi __builtin_ia32_pmulhuw (v4hi, v4hi)
22351 v8qi __builtin_ia32_pavgb (v8qi, v8qi)
22352 v4hi __builtin_ia32_pavgw (v4hi, v4hi)
22353 v1di __builtin_ia32_psadbw (v8qi, v8qi)
22354 v8qi __builtin_ia32_pmaxub (v8qi, v8qi)
22355 v4hi __builtin_ia32_pmaxsw (v4hi, v4hi)
22356 v8qi __builtin_ia32_pminub (v8qi, v8qi)
22357 v4hi __builtin_ia32_pminsw (v4hi, v4hi)
22358 int __builtin_ia32_pmovmskb (v8qi)
22359 void __builtin_ia32_maskmovq (v8qi, v8qi, char *)
22360 void __builtin_ia32_movntq (di *, di)
22361 void __builtin_ia32_sfence (void)
22364 The following built-in functions are available when @option{-msse} is used.
22365 All of them generate the machine instruction that is part of the name.
22368 int __builtin_ia32_comieq (v4sf, v4sf)
22369 int __builtin_ia32_comineq (v4sf, v4sf)
22370 int __builtin_ia32_comilt (v4sf, v4sf)
22371 int __builtin_ia32_comile (v4sf, v4sf)
22372 int __builtin_ia32_comigt (v4sf, v4sf)
22373 int __builtin_ia32_comige (v4sf, v4sf)
22374 int __builtin_ia32_ucomieq (v4sf, v4sf)
22375 int __builtin_ia32_ucomineq (v4sf, v4sf)
22376 int __builtin_ia32_ucomilt (v4sf, v4sf)
22377 int __builtin_ia32_ucomile (v4sf, v4sf)
22378 int __builtin_ia32_ucomigt (v4sf, v4sf)
22379 int __builtin_ia32_ucomige (v4sf, v4sf)
22380 v4sf __builtin_ia32_addps (v4sf, v4sf)
22381 v4sf __builtin_ia32_subps (v4sf, v4sf)
22382 v4sf __builtin_ia32_mulps (v4sf, v4sf)
22383 v4sf __builtin_ia32_divps (v4sf, v4sf)
22384 v4sf __builtin_ia32_addss (v4sf, v4sf)
22385 v4sf __builtin_ia32_subss (v4sf, v4sf)
22386 v4sf __builtin_ia32_mulss (v4sf, v4sf)
22387 v4sf __builtin_ia32_divss (v4sf, v4sf)
22388 v4sf __builtin_ia32_cmpeqps (v4sf, v4sf)
22389 v4sf __builtin_ia32_cmpltps (v4sf, v4sf)
22390 v4sf __builtin_ia32_cmpleps (v4sf, v4sf)
22391 v4sf __builtin_ia32_cmpgtps (v4sf, v4sf)
22392 v4sf __builtin_ia32_cmpgeps (v4sf, v4sf)
22393 v4sf __builtin_ia32_cmpunordps (v4sf, v4sf)
22394 v4sf __builtin_ia32_cmpneqps (v4sf, v4sf)
22395 v4sf __builtin_ia32_cmpnltps (v4sf, v4sf)
22396 v4sf __builtin_ia32_cmpnleps (v4sf, v4sf)
22397 v4sf __builtin_ia32_cmpngtps (v4sf, v4sf)
22398 v4sf __builtin_ia32_cmpngeps (v4sf, v4sf)
22399 v4sf __builtin_ia32_cmpordps (v4sf, v4sf)
22400 v4sf __builtin_ia32_cmpeqss (v4sf, v4sf)
22401 v4sf __builtin_ia32_cmpltss (v4sf, v4sf)
22402 v4sf __builtin_ia32_cmpless (v4sf, v4sf)
22403 v4sf __builtin_ia32_cmpunordss (v4sf, v4sf)
22404 v4sf __builtin_ia32_cmpneqss (v4sf, v4sf)
22405 v4sf __builtin_ia32_cmpnltss (v4sf, v4sf)
22406 v4sf __builtin_ia32_cmpnless (v4sf, v4sf)
22407 v4sf __builtin_ia32_cmpordss (v4sf, v4sf)
22408 v4sf __builtin_ia32_maxps (v4sf, v4sf)
22409 v4sf __builtin_ia32_maxss (v4sf, v4sf)
22410 v4sf __builtin_ia32_minps (v4sf, v4sf)
22411 v4sf __builtin_ia32_minss (v4sf, v4sf)
22412 v4sf __builtin_ia32_andps (v4sf, v4sf)
22413 v4sf __builtin_ia32_andnps (v4sf, v4sf)
22414 v4sf __builtin_ia32_orps (v4sf, v4sf)
22415 v4sf __builtin_ia32_xorps (v4sf, v4sf)
22416 v4sf __builtin_ia32_movss (v4sf, v4sf)
22417 v4sf __builtin_ia32_movhlps (v4sf, v4sf)
22418 v4sf __builtin_ia32_movlhps (v4sf, v4sf)
22419 v4sf __builtin_ia32_unpckhps (v4sf, v4sf)
22420 v4sf __builtin_ia32_unpcklps (v4sf, v4sf)
22421 v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si)
22422 v4sf __builtin_ia32_cvtsi2ss (v4sf, int)
22423 v2si __builtin_ia32_cvtps2pi (v4sf)
22424 int __builtin_ia32_cvtss2si (v4sf)
22425 v2si __builtin_ia32_cvttps2pi (v4sf)
22426 int __builtin_ia32_cvttss2si (v4sf)
22427 v4sf __builtin_ia32_rcpps (v4sf)
22428 v4sf __builtin_ia32_rsqrtps (v4sf)
22429 v4sf __builtin_ia32_sqrtps (v4sf)
22430 v4sf __builtin_ia32_rcpss (v4sf)
22431 v4sf __builtin_ia32_rsqrtss (v4sf)
22432 v4sf __builtin_ia32_sqrtss (v4sf)
22433 v4sf __builtin_ia32_shufps (v4sf, v4sf, int)
22434 void __builtin_ia32_movntps (float *, v4sf)
22435 int __builtin_ia32_movmskps (v4sf)
22438 The following built-in functions are available when @option{-msse} is used.
22441 @item v4sf __builtin_ia32_loadups (float *)
22442 Generates the @code{movups} machine instruction as a load from memory.
22443 @item void __builtin_ia32_storeups (float *, v4sf)
22444 Generates the @code{movups} machine instruction as a store to memory.
22445 @item v4sf __builtin_ia32_loadss (float *)
22446 Generates the @code{movss} machine instruction as a load from memory.
22447 @item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)
22448 Generates the @code{movhps} machine instruction as a load from memory.
22449 @item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)
22450 Generates the @code{movlps} machine instruction as a load from memory
22451 @item void __builtin_ia32_storehps (v2sf *, v4sf)
22452 Generates the @code{movhps} machine instruction as a store to memory.
22453 @item void __builtin_ia32_storelps (v2sf *, v4sf)
22454 Generates the @code{movlps} machine instruction as a store to memory.
22457 The following built-in functions are available when @option{-msse2} is used.
22458 All of them generate the machine instruction that is part of the name.
22461 int __builtin_ia32_comisdeq (v2df, v2df)
22462 int __builtin_ia32_comisdlt (v2df, v2df)
22463 int __builtin_ia32_comisdle (v2df, v2df)
22464 int __builtin_ia32_comisdgt (v2df, v2df)
22465 int __builtin_ia32_comisdge (v2df, v2df)
22466 int __builtin_ia32_comisdneq (v2df, v2df)
22467 int __builtin_ia32_ucomisdeq (v2df, v2df)
22468 int __builtin_ia32_ucomisdlt (v2df, v2df)
22469 int __builtin_ia32_ucomisdle (v2df, v2df)
22470 int __builtin_ia32_ucomisdgt (v2df, v2df)
22471 int __builtin_ia32_ucomisdge (v2df, v2df)
22472 int __builtin_ia32_ucomisdneq (v2df, v2df)
22473 v2df __builtin_ia32_cmpeqpd (v2df, v2df)
22474 v2df __builtin_ia32_cmpltpd (v2df, v2df)
22475 v2df __builtin_ia32_cmplepd (v2df, v2df)
22476 v2df __builtin_ia32_cmpgtpd (v2df, v2df)
22477 v2df __builtin_ia32_cmpgepd (v2df, v2df)
22478 v2df __builtin_ia32_cmpunordpd (v2df, v2df)
22479 v2df __builtin_ia32_cmpneqpd (v2df, v2df)
22480 v2df __builtin_ia32_cmpnltpd (v2df, v2df)
22481 v2df __builtin_ia32_cmpnlepd (v2df, v2df)
22482 v2df __builtin_ia32_cmpngtpd (v2df, v2df)
22483 v2df __builtin_ia32_cmpngepd (v2df, v2df)
22484 v2df __builtin_ia32_cmpordpd (v2df, v2df)
22485 v2df __builtin_ia32_cmpeqsd (v2df, v2df)
22486 v2df __builtin_ia32_cmpltsd (v2df, v2df)
22487 v2df __builtin_ia32_cmplesd (v2df, v2df)
22488 v2df __builtin_ia32_cmpunordsd (v2df, v2df)
22489 v2df __builtin_ia32_cmpneqsd (v2df, v2df)
22490 v2df __builtin_ia32_cmpnltsd (v2df, v2df)
22491 v2df __builtin_ia32_cmpnlesd (v2df, v2df)
22492 v2df __builtin_ia32_cmpordsd (v2df, v2df)
22493 v2di __builtin_ia32_paddq (v2di, v2di)
22494 v2di __builtin_ia32_psubq (v2di, v2di)
22495 v2df __builtin_ia32_addpd (v2df, v2df)
22496 v2df __builtin_ia32_subpd (v2df, v2df)
22497 v2df __builtin_ia32_mulpd (v2df, v2df)
22498 v2df __builtin_ia32_divpd (v2df, v2df)
22499 v2df __builtin_ia32_addsd (v2df, v2df)
22500 v2df __builtin_ia32_subsd (v2df, v2df)
22501 v2df __builtin_ia32_mulsd (v2df, v2df)
22502 v2df __builtin_ia32_divsd (v2df, v2df)
22503 v2df __builtin_ia32_minpd (v2df, v2df)
22504 v2df __builtin_ia32_maxpd (v2df, v2df)
22505 v2df __builtin_ia32_minsd (v2df, v2df)
22506 v2df __builtin_ia32_maxsd (v2df, v2df)
22507 v2df __builtin_ia32_andpd (v2df, v2df)
22508 v2df __builtin_ia32_andnpd (v2df, v2df)
22509 v2df __builtin_ia32_orpd (v2df, v2df)
22510 v2df __builtin_ia32_xorpd (v2df, v2df)
22511 v2df __builtin_ia32_movsd (v2df, v2df)
22512 v2df __builtin_ia32_unpckhpd (v2df, v2df)
22513 v2df __builtin_ia32_unpcklpd (v2df, v2df)
22514 v16qi __builtin_ia32_paddb128 (v16qi, v16qi)
22515 v8hi __builtin_ia32_paddw128 (v8hi, v8hi)
22516 v4si __builtin_ia32_paddd128 (v4si, v4si)
22517 v2di __builtin_ia32_paddq128 (v2di, v2di)
22518 v16qi __builtin_ia32_psubb128 (v16qi, v16qi)
22519 v8hi __builtin_ia32_psubw128 (v8hi, v8hi)
22520 v4si __builtin_ia32_psubd128 (v4si, v4si)
22521 v2di __builtin_ia32_psubq128 (v2di, v2di)
22522 v8hi __builtin_ia32_pmullw128 (v8hi, v8hi)
22523 v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi)
22524 v2di __builtin_ia32_pand128 (v2di, v2di)
22525 v2di __builtin_ia32_pandn128 (v2di, v2di)
22526 v2di __builtin_ia32_por128 (v2di, v2di)
22527 v2di __builtin_ia32_pxor128 (v2di, v2di)
22528 v16qi __builtin_ia32_pavgb128 (v16qi, v16qi)
22529 v8hi __builtin_ia32_pavgw128 (v8hi, v8hi)
22530 v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi)
22531 v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi)
22532 v4si __builtin_ia32_pcmpeqd128 (v4si, v4si)
22533 v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi)
22534 v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi)
22535 v4si __builtin_ia32_pcmpgtd128 (v4si, v4si)
22536 v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi)
22537 v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi)
22538 v16qi __builtin_ia32_pminub128 (v16qi, v16qi)
22539 v8hi __builtin_ia32_pminsw128 (v8hi, v8hi)
22540 v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi)
22541 v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi)
22542 v4si __builtin_ia32_punpckhdq128 (v4si, v4si)
22543 v2di __builtin_ia32_punpckhqdq128 (v2di, v2di)
22544 v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi)
22545 v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi)
22546 v4si __builtin_ia32_punpckldq128 (v4si, v4si)
22547 v2di __builtin_ia32_punpcklqdq128 (v2di, v2di)
22548 v16qi __builtin_ia32_packsswb128 (v8hi, v8hi)
22549 v8hi __builtin_ia32_packssdw128 (v4si, v4si)
22550 v16qi __builtin_ia32_packuswb128 (v8hi, v8hi)
22551 v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi)
22552 void __builtin_ia32_maskmovdqu (v16qi, v16qi)
22553 v2df __builtin_ia32_loadupd (double *)
22554 void __builtin_ia32_storeupd (double *, v2df)
22555 v2df __builtin_ia32_loadhpd (v2df, double const *)
22556 v2df __builtin_ia32_loadlpd (v2df, double const *)
22557 int __builtin_ia32_movmskpd (v2df)
22558 int __builtin_ia32_pmovmskb128 (v16qi)
22559 void __builtin_ia32_movnti (int *, int)
22560 void __builtin_ia32_movnti64 (long long int *, long long int)
22561 void __builtin_ia32_movntpd (double *, v2df)
22562 void __builtin_ia32_movntdq (v2df *, v2df)
22563 v4si __builtin_ia32_pshufd (v4si, int)
22564 v8hi __builtin_ia32_pshuflw (v8hi, int)
22565 v8hi __builtin_ia32_pshufhw (v8hi, int)
22566 v2di __builtin_ia32_psadbw128 (v16qi, v16qi)
22567 v2df __builtin_ia32_sqrtpd (v2df)
22568 v2df __builtin_ia32_sqrtsd (v2df)
22569 v2df __builtin_ia32_shufpd (v2df, v2df, int)
22570 v2df __builtin_ia32_cvtdq2pd (v4si)
22571 v4sf __builtin_ia32_cvtdq2ps (v4si)
22572 v4si __builtin_ia32_cvtpd2dq (v2df)
22573 v2si __builtin_ia32_cvtpd2pi (v2df)
22574 v4sf __builtin_ia32_cvtpd2ps (v2df)
22575 v4si __builtin_ia32_cvttpd2dq (v2df)
22576 v2si __builtin_ia32_cvttpd2pi (v2df)
22577 v2df __builtin_ia32_cvtpi2pd (v2si)
22578 int __builtin_ia32_cvtsd2si (v2df)
22579 int __builtin_ia32_cvttsd2si (v2df)
22580 long long __builtin_ia32_cvtsd2si64 (v2df)
22581 long long __builtin_ia32_cvttsd2si64 (v2df)
22582 v4si __builtin_ia32_cvtps2dq (v4sf)
22583 v2df __builtin_ia32_cvtps2pd (v4sf)
22584 v4si __builtin_ia32_cvttps2dq (v4sf)
22585 v2df __builtin_ia32_cvtsi2sd (v2df, int)
22586 v2df __builtin_ia32_cvtsi642sd (v2df, long long)
22587 v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df)
22588 v2df __builtin_ia32_cvtss2sd (v2df, v4sf)
22589 void __builtin_ia32_clflush (const void *)
22590 void __builtin_ia32_lfence (void)
22591 void __builtin_ia32_mfence (void)
22592 v16qi __builtin_ia32_loaddqu (const char *)
22593 void __builtin_ia32_storedqu (char *, v16qi)
22594 v1di __builtin_ia32_pmuludq (v2si, v2si)
22595 v2di __builtin_ia32_pmuludq128 (v4si, v4si)
22596 v8hi __builtin_ia32_psllw128 (v8hi, v8hi)
22597 v4si __builtin_ia32_pslld128 (v4si, v4si)
22598 v2di __builtin_ia32_psllq128 (v2di, v2di)
22599 v8hi __builtin_ia32_psrlw128 (v8hi, v8hi)
22600 v4si __builtin_ia32_psrld128 (v4si, v4si)
22601 v2di __builtin_ia32_psrlq128 (v2di, v2di)
22602 v8hi __builtin_ia32_psraw128 (v8hi, v8hi)
22603 v4si __builtin_ia32_psrad128 (v4si, v4si)
22604 v2di __builtin_ia32_pslldqi128 (v2di, int)
22605 v8hi __builtin_ia32_psllwi128 (v8hi, int)
22606 v4si __builtin_ia32_pslldi128 (v4si, int)
22607 v2di __builtin_ia32_psllqi128 (v2di, int)
22608 v2di __builtin_ia32_psrldqi128 (v2di, int)
22609 v8hi __builtin_ia32_psrlwi128 (v8hi, int)
22610 v4si __builtin_ia32_psrldi128 (v4si, int)
22611 v2di __builtin_ia32_psrlqi128 (v2di, int)
22612 v8hi __builtin_ia32_psrawi128 (v8hi, int)
22613 v4si __builtin_ia32_psradi128 (v4si, int)
22614 v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi)
22615 v2di __builtin_ia32_movq128 (v2di)
22618 The following built-in functions are available when @option{-msse3} is used.
22619 All of them generate the machine instruction that is part of the name.
22622 v2df __builtin_ia32_addsubpd (v2df, v2df)
22623 v4sf __builtin_ia32_addsubps (v4sf, v4sf)
22624 v2df __builtin_ia32_haddpd (v2df, v2df)
22625 v4sf __builtin_ia32_haddps (v4sf, v4sf)
22626 v2df __builtin_ia32_hsubpd (v2df, v2df)
22627 v4sf __builtin_ia32_hsubps (v4sf, v4sf)
22628 v16qi __builtin_ia32_lddqu (char const *)
22629 void __builtin_ia32_monitor (void *, unsigned int, unsigned int)
22630 v4sf __builtin_ia32_movshdup (v4sf)
22631 v4sf __builtin_ia32_movsldup (v4sf)
22632 void __builtin_ia32_mwait (unsigned int, unsigned int)
22635 The following built-in functions are available when @option{-mssse3} is used.
22636 All of them generate the machine instruction that is part of the name.
22639 v2si __builtin_ia32_phaddd (v2si, v2si)
22640 v4hi __builtin_ia32_phaddw (v4hi, v4hi)
22641 v4hi __builtin_ia32_phaddsw (v4hi, v4hi)
22642 v2si __builtin_ia32_phsubd (v2si, v2si)
22643 v4hi __builtin_ia32_phsubw (v4hi, v4hi)
22644 v4hi __builtin_ia32_phsubsw (v4hi, v4hi)
22645 v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi)
22646 v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi)
22647 v8qi __builtin_ia32_pshufb (v8qi, v8qi)
22648 v8qi __builtin_ia32_psignb (v8qi, v8qi)
22649 v2si __builtin_ia32_psignd (v2si, v2si)
22650 v4hi __builtin_ia32_psignw (v4hi, v4hi)
22651 v1di __builtin_ia32_palignr (v1di, v1di, int)
22652 v8qi __builtin_ia32_pabsb (v8qi)
22653 v2si __builtin_ia32_pabsd (v2si)
22654 v4hi __builtin_ia32_pabsw (v4hi)
22657 The following built-in functions are available when @option{-mssse3} is used.
22658 All of them generate the machine instruction that is part of the name.
22661 v4si __builtin_ia32_phaddd128 (v4si, v4si)
22662 v8hi __builtin_ia32_phaddw128 (v8hi, v8hi)
22663 v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi)
22664 v4si __builtin_ia32_phsubd128 (v4si, v4si)
22665 v8hi __builtin_ia32_phsubw128 (v8hi, v8hi)
22666 v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi)
22667 v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi)
22668 v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi)
22669 v16qi __builtin_ia32_pshufb128 (v16qi, v16qi)
22670 v16qi __builtin_ia32_psignb128 (v16qi, v16qi)
22671 v4si __builtin_ia32_psignd128 (v4si, v4si)
22672 v8hi __builtin_ia32_psignw128 (v8hi, v8hi)
22673 v2di __builtin_ia32_palignr128 (v2di, v2di, int)
22674 v16qi __builtin_ia32_pabsb128 (v16qi)
22675 v4si __builtin_ia32_pabsd128 (v4si)
22676 v8hi __builtin_ia32_pabsw128 (v8hi)
22679 The following built-in functions are available when @option{-msse4.1} is
22680 used. All of them generate the machine instruction that is part of the
22684 v2df __builtin_ia32_blendpd (v2df, v2df, const int)
22685 v4sf __builtin_ia32_blendps (v4sf, v4sf, const int)
22686 v2df __builtin_ia32_blendvpd (v2df, v2df, v2df)
22687 v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf)
22688 v2df __builtin_ia32_dppd (v2df, v2df, const int)
22689 v4sf __builtin_ia32_dpps (v4sf, v4sf, const int)
22690 v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int)
22691 v2di __builtin_ia32_movntdqa (v2di *);
22692 v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int)
22693 v8hi __builtin_ia32_packusdw128 (v4si, v4si)
22694 v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi)
22695 v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int)
22696 v2di __builtin_ia32_pcmpeqq (v2di, v2di)
22697 v8hi __builtin_ia32_phminposuw128 (v8hi)
22698 v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi)
22699 v4si __builtin_ia32_pmaxsd128 (v4si, v4si)
22700 v4si __builtin_ia32_pmaxud128 (v4si, v4si)
22701 v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi)
22702 v16qi __builtin_ia32_pminsb128 (v16qi, v16qi)
22703 v4si __builtin_ia32_pminsd128 (v4si, v4si)
22704 v4si __builtin_ia32_pminud128 (v4si, v4si)
22705 v8hi __builtin_ia32_pminuw128 (v8hi, v8hi)
22706 v4si __builtin_ia32_pmovsxbd128 (v16qi)
22707 v2di __builtin_ia32_pmovsxbq128 (v16qi)
22708 v8hi __builtin_ia32_pmovsxbw128 (v16qi)
22709 v2di __builtin_ia32_pmovsxdq128 (v4si)
22710 v4si __builtin_ia32_pmovsxwd128 (v8hi)
22711 v2di __builtin_ia32_pmovsxwq128 (v8hi)
22712 v4si __builtin_ia32_pmovzxbd128 (v16qi)
22713 v2di __builtin_ia32_pmovzxbq128 (v16qi)
22714 v8hi __builtin_ia32_pmovzxbw128 (v16qi)
22715 v2di __builtin_ia32_pmovzxdq128 (v4si)
22716 v4si __builtin_ia32_pmovzxwd128 (v8hi)
22717 v2di __builtin_ia32_pmovzxwq128 (v8hi)
22718 v2di __builtin_ia32_pmuldq128 (v4si, v4si)
22719 v4si __builtin_ia32_pmulld128 (v4si, v4si)
22720 int __builtin_ia32_ptestc128 (v2di, v2di)
22721 int __builtin_ia32_ptestnzc128 (v2di, v2di)
22722 int __builtin_ia32_ptestz128 (v2di, v2di)
22723 v2df __builtin_ia32_roundpd (v2df, const int)
22724 v4sf __builtin_ia32_roundps (v4sf, const int)
22725 v2df __builtin_ia32_roundsd (v2df, v2df, const int)
22726 v4sf __builtin_ia32_roundss (v4sf, v4sf, const int)
22729 The following built-in functions are available when @option{-msse4.1} is
22733 @item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)
22734 Generates the @code{insertps} machine instruction.
22735 @item int __builtin_ia32_vec_ext_v16qi (v16qi, const int)
22736 Generates the @code{pextrb} machine instruction.
22737 @item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)
22738 Generates the @code{pinsrb} machine instruction.
22739 @item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)
22740 Generates the @code{pinsrd} machine instruction.
22741 @item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)
22742 Generates the @code{pinsrq} machine instruction in 64bit mode.
22745 The following built-in functions are changed to generate new SSE4.1
22746 instructions when @option{-msse4.1} is used.
22749 @item float __builtin_ia32_vec_ext_v4sf (v4sf, const int)
22750 Generates the @code{extractps} machine instruction.
22751 @item int __builtin_ia32_vec_ext_v4si (v4si, const int)
22752 Generates the @code{pextrd} machine instruction.
22753 @item long long __builtin_ia32_vec_ext_v2di (v2di, const int)
22754 Generates the @code{pextrq} machine instruction in 64bit mode.
22757 The following built-in functions are available when @option{-msse4.2} is
22758 used. All of them generate the machine instruction that is part of the
22762 v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int)
22763 int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int)
22764 int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int)
22765 int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int)
22766 int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int)
22767 int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int)
22768 int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int)
22769 v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int)
22770 int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int)
22771 int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int)
22772 int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int)
22773 int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int)
22774 int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int)
22775 int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int)
22776 v2di __builtin_ia32_pcmpgtq (v2di, v2di)
22779 The following built-in functions are available when @option{-msse4.2} is
22783 @item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char)
22784 Generates the @code{crc32b} machine instruction.
22785 @item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short)
22786 Generates the @code{crc32w} machine instruction.
22787 @item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int)
22788 Generates the @code{crc32l} machine instruction.
22789 @item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long)
22790 Generates the @code{crc32q} machine instruction.
22793 The following built-in functions are changed to generate new SSE4.2
22794 instructions when @option{-msse4.2} is used.
22797 @item int __builtin_popcount (unsigned int)
22798 Generates the @code{popcntl} machine instruction.
22799 @item int __builtin_popcountl (unsigned long)
22800 Generates the @code{popcntl} or @code{popcntq} machine instruction,
22801 depending on the size of @code{unsigned long}.
22802 @item int __builtin_popcountll (unsigned long long)
22803 Generates the @code{popcntq} machine instruction.
22806 The following built-in functions are available when @option{-mavx} is
22807 used. All of them generate the machine instruction that is part of the
22811 v4df __builtin_ia32_addpd256 (v4df,v4df)
22812 v8sf __builtin_ia32_addps256 (v8sf,v8sf)
22813 v4df __builtin_ia32_addsubpd256 (v4df,v4df)
22814 v8sf __builtin_ia32_addsubps256 (v8sf,v8sf)
22815 v4df __builtin_ia32_andnpd256 (v4df,v4df)
22816 v8sf __builtin_ia32_andnps256 (v8sf,v8sf)
22817 v4df __builtin_ia32_andpd256 (v4df,v4df)
22818 v8sf __builtin_ia32_andps256 (v8sf,v8sf)
22819 v4df __builtin_ia32_blendpd256 (v4df,v4df,int)
22820 v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int)
22821 v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df)
22822 v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf)
22823 v2df __builtin_ia32_cmppd (v2df,v2df,int)
22824 v4df __builtin_ia32_cmppd256 (v4df,v4df,int)
22825 v4sf __builtin_ia32_cmpps (v4sf,v4sf,int)
22826 v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int)
22827 v2df __builtin_ia32_cmpsd (v2df,v2df,int)
22828 v4sf __builtin_ia32_cmpss (v4sf,v4sf,int)
22829 v4df __builtin_ia32_cvtdq2pd256 (v4si)
22830 v8sf __builtin_ia32_cvtdq2ps256 (v8si)
22831 v4si __builtin_ia32_cvtpd2dq256 (v4df)
22832 v4sf __builtin_ia32_cvtpd2ps256 (v4df)
22833 v8si __builtin_ia32_cvtps2dq256 (v8sf)
22834 v4df __builtin_ia32_cvtps2pd256 (v4sf)
22835 v4si __builtin_ia32_cvttpd2dq256 (v4df)
22836 v8si __builtin_ia32_cvttps2dq256 (v8sf)
22837 v4df __builtin_ia32_divpd256 (v4df,v4df)
22838 v8sf __builtin_ia32_divps256 (v8sf,v8sf)
22839 v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int)
22840 v4df __builtin_ia32_haddpd256 (v4df,v4df)
22841 v8sf __builtin_ia32_haddps256 (v8sf,v8sf)
22842 v4df __builtin_ia32_hsubpd256 (v4df,v4df)
22843 v8sf __builtin_ia32_hsubps256 (v8sf,v8sf)
22844 v32qi __builtin_ia32_lddqu256 (pcchar)
22845 v32qi __builtin_ia32_loaddqu256 (pcchar)
22846 v4df __builtin_ia32_loadupd256 (pcdouble)
22847 v8sf __builtin_ia32_loadups256 (pcfloat)
22848 v2df __builtin_ia32_maskloadpd (pcv2df,v2df)
22849 v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df)
22850 v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf)
22851 v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf)
22852 void __builtin_ia32_maskstorepd (pv2df,v2df,v2df)
22853 void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df)
22854 void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf)
22855 void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf)
22856 v4df __builtin_ia32_maxpd256 (v4df,v4df)
22857 v8sf __builtin_ia32_maxps256 (v8sf,v8sf)
22858 v4df __builtin_ia32_minpd256 (v4df,v4df)
22859 v8sf __builtin_ia32_minps256 (v8sf,v8sf)
22860 v4df __builtin_ia32_movddup256 (v4df)
22861 int __builtin_ia32_movmskpd256 (v4df)
22862 int __builtin_ia32_movmskps256 (v8sf)
22863 v8sf __builtin_ia32_movshdup256 (v8sf)
22864 v8sf __builtin_ia32_movsldup256 (v8sf)
22865 v4df __builtin_ia32_mulpd256 (v4df,v4df)
22866 v8sf __builtin_ia32_mulps256 (v8sf,v8sf)
22867 v4df __builtin_ia32_orpd256 (v4df,v4df)
22868 v8sf __builtin_ia32_orps256 (v8sf,v8sf)
22869 v2df __builtin_ia32_pd_pd256 (v4df)
22870 v4df __builtin_ia32_pd256_pd (v2df)
22871 v4sf __builtin_ia32_ps_ps256 (v8sf)
22872 v8sf __builtin_ia32_ps256_ps (v4sf)
22873 int __builtin_ia32_ptestc256 (v4di,v4di,ptest)
22874 int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest)
22875 int __builtin_ia32_ptestz256 (v4di,v4di,ptest)
22876 v8sf __builtin_ia32_rcpps256 (v8sf)
22877 v4df __builtin_ia32_roundpd256 (v4df,int)
22878 v8sf __builtin_ia32_roundps256 (v8sf,int)
22879 v8sf __builtin_ia32_rsqrtps_nr256 (v8sf)
22880 v8sf __builtin_ia32_rsqrtps256 (v8sf)
22881 v4df __builtin_ia32_shufpd256 (v4df,v4df,int)
22882 v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int)
22883 v4si __builtin_ia32_si_si256 (v8si)
22884 v8si __builtin_ia32_si256_si (v4si)
22885 v4df __builtin_ia32_sqrtpd256 (v4df)
22886 v8sf __builtin_ia32_sqrtps_nr256 (v8sf)
22887 v8sf __builtin_ia32_sqrtps256 (v8sf)
22888 void __builtin_ia32_storedqu256 (pchar,v32qi)
22889 void __builtin_ia32_storeupd256 (pdouble,v4df)
22890 void __builtin_ia32_storeups256 (pfloat,v8sf)
22891 v4df __builtin_ia32_subpd256 (v4df,v4df)
22892 v8sf __builtin_ia32_subps256 (v8sf,v8sf)
22893 v4df __builtin_ia32_unpckhpd256 (v4df,v4df)
22894 v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf)
22895 v4df __builtin_ia32_unpcklpd256 (v4df,v4df)
22896 v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf)
22897 v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df)
22898 v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf)
22899 v4df __builtin_ia32_vbroadcastsd256 (pcdouble)
22900 v4sf __builtin_ia32_vbroadcastss (pcfloat)
22901 v8sf __builtin_ia32_vbroadcastss256 (pcfloat)
22902 v2df __builtin_ia32_vextractf128_pd256 (v4df,int)
22903 v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int)
22904 v4si __builtin_ia32_vextractf128_si256 (v8si,int)
22905 v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int)
22906 v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int)
22907 v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int)
22908 v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int)
22909 v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int)
22910 v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int)
22911 v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int)
22912 v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int)
22913 v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int)
22914 v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int)
22915 v2df __builtin_ia32_vpermilpd (v2df,int)
22916 v4df __builtin_ia32_vpermilpd256 (v4df,int)
22917 v4sf __builtin_ia32_vpermilps (v4sf,int)
22918 v8sf __builtin_ia32_vpermilps256 (v8sf,int)
22919 v2df __builtin_ia32_vpermilvarpd (v2df,v2di)
22920 v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di)
22921 v4sf __builtin_ia32_vpermilvarps (v4sf,v4si)
22922 v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si)
22923 int __builtin_ia32_vtestcpd (v2df,v2df,ptest)
22924 int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest)
22925 int __builtin_ia32_vtestcps (v4sf,v4sf,ptest)
22926 int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest)
22927 int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest)
22928 int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest)
22929 int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest)
22930 int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest)
22931 int __builtin_ia32_vtestzpd (v2df,v2df,ptest)
22932 int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest)
22933 int __builtin_ia32_vtestzps (v4sf,v4sf,ptest)
22934 int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest)
22935 void __builtin_ia32_vzeroall (void)
22936 void __builtin_ia32_vzeroupper (void)
22937 v4df __builtin_ia32_xorpd256 (v4df,v4df)
22938 v8sf __builtin_ia32_xorps256 (v8sf,v8sf)
22941 The following built-in functions are available when @option{-mavx2} is
22942 used. All of them generate the machine instruction that is part of the
22946 v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int)
22947 v32qi __builtin_ia32_pabsb256 (v32qi)
22948 v16hi __builtin_ia32_pabsw256 (v16hi)
22949 v8si __builtin_ia32_pabsd256 (v8si)
22950 v16hi __builtin_ia32_packssdw256 (v8si,v8si)
22951 v32qi __builtin_ia32_packsswb256 (v16hi,v16hi)
22952 v16hi __builtin_ia32_packusdw256 (v8si,v8si)
22953 v32qi __builtin_ia32_packuswb256 (v16hi,v16hi)
22954 v32qi __builtin_ia32_paddb256 (v32qi,v32qi)
22955 v16hi __builtin_ia32_paddw256 (v16hi,v16hi)
22956 v8si __builtin_ia32_paddd256 (v8si,v8si)
22957 v4di __builtin_ia32_paddq256 (v4di,v4di)
22958 v32qi __builtin_ia32_paddsb256 (v32qi,v32qi)
22959 v16hi __builtin_ia32_paddsw256 (v16hi,v16hi)
22960 v32qi __builtin_ia32_paddusb256 (v32qi,v32qi)
22961 v16hi __builtin_ia32_paddusw256 (v16hi,v16hi)
22962 v4di __builtin_ia32_palignr256 (v4di,v4di,int)
22963 v4di __builtin_ia32_andsi256 (v4di,v4di)
22964 v4di __builtin_ia32_andnotsi256 (v4di,v4di)
22965 v32qi __builtin_ia32_pavgb256 (v32qi,v32qi)
22966 v16hi __builtin_ia32_pavgw256 (v16hi,v16hi)
22967 v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi)
22968 v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int)
22969 v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi)
22970 v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi)
22971 v8si __builtin_ia32_pcmpeqd256 (c8si,v8si)
22972 v4di __builtin_ia32_pcmpeqq256 (v4di,v4di)
22973 v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi)
22974 v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi)
22975 v8si __builtin_ia32_pcmpgtd256 (v8si,v8si)
22976 v4di __builtin_ia32_pcmpgtq256 (v4di,v4di)
22977 v16hi __builtin_ia32_phaddw256 (v16hi,v16hi)
22978 v8si __builtin_ia32_phaddd256 (v8si,v8si)
22979 v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi)
22980 v16hi __builtin_ia32_phsubw256 (v16hi,v16hi)
22981 v8si __builtin_ia32_phsubd256 (v8si,v8si)
22982 v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi)
22983 v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi)
22984 v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi)
22985 v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi)
22986 v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi)
22987 v8si __builtin_ia32_pmaxsd256 (v8si,v8si)
22988 v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi)
22989 v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi)
22990 v8si __builtin_ia32_pmaxud256 (v8si,v8si)
22991 v32qi __builtin_ia32_pminsb256 (v32qi,v32qi)
22992 v16hi __builtin_ia32_pminsw256 (v16hi,v16hi)
22993 v8si __builtin_ia32_pminsd256 (v8si,v8si)
22994 v32qi __builtin_ia32_pminub256 (v32qi,v32qi)
22995 v16hi __builtin_ia32_pminuw256 (v16hi,v16hi)
22996 v8si __builtin_ia32_pminud256 (v8si,v8si)
22997 int __builtin_ia32_pmovmskb256 (v32qi)
22998 v16hi __builtin_ia32_pmovsxbw256 (v16qi)
22999 v8si __builtin_ia32_pmovsxbd256 (v16qi)
23000 v4di __builtin_ia32_pmovsxbq256 (v16qi)
23001 v8si __builtin_ia32_pmovsxwd256 (v8hi)
23002 v4di __builtin_ia32_pmovsxwq256 (v8hi)
23003 v4di __builtin_ia32_pmovsxdq256 (v4si)
23004 v16hi __builtin_ia32_pmovzxbw256 (v16qi)
23005 v8si __builtin_ia32_pmovzxbd256 (v16qi)
23006 v4di __builtin_ia32_pmovzxbq256 (v16qi)
23007 v8si __builtin_ia32_pmovzxwd256 (v8hi)
23008 v4di __builtin_ia32_pmovzxwq256 (v8hi)
23009 v4di __builtin_ia32_pmovzxdq256 (v4si)
23010 v4di __builtin_ia32_pmuldq256 (v8si,v8si)
23011 v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi)
23012 v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi)
23013 v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi)
23014 v16hi __builtin_ia32_pmullw256 (v16hi,v16hi)
23015 v8si __builtin_ia32_pmulld256 (v8si,v8si)
23016 v4di __builtin_ia32_pmuludq256 (v8si,v8si)
23017 v4di __builtin_ia32_por256 (v4di,v4di)
23018 v16hi __builtin_ia32_psadbw256 (v32qi,v32qi)
23019 v32qi __builtin_ia32_pshufb256 (v32qi,v32qi)
23020 v8si __builtin_ia32_pshufd256 (v8si,int)
23021 v16hi __builtin_ia32_pshufhw256 (v16hi,int)
23022 v16hi __builtin_ia32_pshuflw256 (v16hi,int)
23023 v32qi __builtin_ia32_psignb256 (v32qi,v32qi)
23024 v16hi __builtin_ia32_psignw256 (v16hi,v16hi)
23025 v8si __builtin_ia32_psignd256 (v8si,v8si)
23026 v4di __builtin_ia32_pslldqi256 (v4di,int)
23027 v16hi __builtin_ia32_psllwi256 (16hi,int)
23028 v16hi __builtin_ia32_psllw256(v16hi,v8hi)
23029 v8si __builtin_ia32_pslldi256 (v8si,int)
23030 v8si __builtin_ia32_pslld256(v8si,v4si)
23031 v4di __builtin_ia32_psllqi256 (v4di,int)
23032 v4di __builtin_ia32_psllq256(v4di,v2di)
23033 v16hi __builtin_ia32_psrawi256 (v16hi,int)
23034 v16hi __builtin_ia32_psraw256 (v16hi,v8hi)
23035 v8si __builtin_ia32_psradi256 (v8si,int)
23036 v8si __builtin_ia32_psrad256 (v8si,v4si)
23037 v4di __builtin_ia32_psrldqi256 (v4di, int)
23038 v16hi __builtin_ia32_psrlwi256 (v16hi,int)
23039 v16hi __builtin_ia32_psrlw256 (v16hi,v8hi)
23040 v8si __builtin_ia32_psrldi256 (v8si,int)
23041 v8si __builtin_ia32_psrld256 (v8si,v4si)
23042 v4di __builtin_ia32_psrlqi256 (v4di,int)
23043 v4di __builtin_ia32_psrlq256(v4di,v2di)
23044 v32qi __builtin_ia32_psubb256 (v32qi,v32qi)
23045 v32hi __builtin_ia32_psubw256 (v16hi,v16hi)
23046 v8si __builtin_ia32_psubd256 (v8si,v8si)
23047 v4di __builtin_ia32_psubq256 (v4di,v4di)
23048 v32qi __builtin_ia32_psubsb256 (v32qi,v32qi)
23049 v16hi __builtin_ia32_psubsw256 (v16hi,v16hi)
23050 v32qi __builtin_ia32_psubusb256 (v32qi,v32qi)
23051 v16hi __builtin_ia32_psubusw256 (v16hi,v16hi)
23052 v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi)
23053 v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi)
23054 v8si __builtin_ia32_punpckhdq256 (v8si,v8si)
23055 v4di __builtin_ia32_punpckhqdq256 (v4di,v4di)
23056 v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi)
23057 v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi)
23058 v8si __builtin_ia32_punpckldq256 (v8si,v8si)
23059 v4di __builtin_ia32_punpcklqdq256 (v4di,v4di)
23060 v4di __builtin_ia32_pxor256 (v4di,v4di)
23061 v4di __builtin_ia32_movntdqa256 (pv4di)
23062 v4sf __builtin_ia32_vbroadcastss_ps (v4sf)
23063 v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf)
23064 v4df __builtin_ia32_vbroadcastsd_pd256 (v2df)
23065 v4di __builtin_ia32_vbroadcastsi256 (v2di)
23066 v4si __builtin_ia32_pblendd128 (v4si,v4si)
23067 v8si __builtin_ia32_pblendd256 (v8si,v8si)
23068 v32qi __builtin_ia32_pbroadcastb256 (v16qi)
23069 v16hi __builtin_ia32_pbroadcastw256 (v8hi)
23070 v8si __builtin_ia32_pbroadcastd256 (v4si)
23071 v4di __builtin_ia32_pbroadcastq256 (v2di)
23072 v16qi __builtin_ia32_pbroadcastb128 (v16qi)
23073 v8hi __builtin_ia32_pbroadcastw128 (v8hi)
23074 v4si __builtin_ia32_pbroadcastd128 (v4si)
23075 v2di __builtin_ia32_pbroadcastq128 (v2di)
23076 v8si __builtin_ia32_permvarsi256 (v8si,v8si)
23077 v4df __builtin_ia32_permdf256 (v4df,int)
23078 v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf)
23079 v4di __builtin_ia32_permdi256 (v4di,int)
23080 v4di __builtin_ia32_permti256 (v4di,v4di,int)
23081 v4di __builtin_ia32_extract128i256 (v4di,int)
23082 v4di __builtin_ia32_insert128i256 (v4di,v2di,int)
23083 v8si __builtin_ia32_maskloadd256 (pcv8si,v8si)
23084 v4di __builtin_ia32_maskloadq256 (pcv4di,v4di)
23085 v4si __builtin_ia32_maskloadd (pcv4si,v4si)
23086 v2di __builtin_ia32_maskloadq (pcv2di,v2di)
23087 void __builtin_ia32_maskstored256 (pv8si,v8si,v8si)
23088 void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di)
23089 void __builtin_ia32_maskstored (pv4si,v4si,v4si)
23090 void __builtin_ia32_maskstoreq (pv2di,v2di,v2di)
23091 v8si __builtin_ia32_psllv8si (v8si,v8si)
23092 v4si __builtin_ia32_psllv4si (v4si,v4si)
23093 v4di __builtin_ia32_psllv4di (v4di,v4di)
23094 v2di __builtin_ia32_psllv2di (v2di,v2di)
23095 v8si __builtin_ia32_psrav8si (v8si,v8si)
23096 v4si __builtin_ia32_psrav4si (v4si,v4si)
23097 v8si __builtin_ia32_psrlv8si (v8si,v8si)
23098 v4si __builtin_ia32_psrlv4si (v4si,v4si)
23099 v4di __builtin_ia32_psrlv4di (v4di,v4di)
23100 v2di __builtin_ia32_psrlv2di (v2di,v2di)
23101 v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int)
23102 v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int)
23103 v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int)
23104 v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int)
23105 v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int)
23106 v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int)
23107 v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int)
23108 v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int)
23109 v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int)
23110 v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int)
23111 v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int)
23112 v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int)
23113 v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int)
23114 v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int)
23115 v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int)
23116 v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int)
23119 The following built-in functions are available when @option{-maes} is
23120 used. All of them generate the machine instruction that is part of the
23124 v2di __builtin_ia32_aesenc128 (v2di, v2di)
23125 v2di __builtin_ia32_aesenclast128 (v2di, v2di)
23126 v2di __builtin_ia32_aesdec128 (v2di, v2di)
23127 v2di __builtin_ia32_aesdeclast128 (v2di, v2di)
23128 v2di __builtin_ia32_aeskeygenassist128 (v2di, const int)
23129 v2di __builtin_ia32_aesimc128 (v2di)
23132 The following built-in function is available when @option{-mpclmul} is
23136 @item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)
23137 Generates the @code{pclmulqdq} machine instruction.
23140 The following built-in function is available when @option{-mfsgsbase} is
23141 used. All of them generate the machine instruction that is part of the
23145 unsigned int __builtin_ia32_rdfsbase32 (void)
23146 unsigned long long __builtin_ia32_rdfsbase64 (void)
23147 unsigned int __builtin_ia32_rdgsbase32 (void)
23148 unsigned long long __builtin_ia32_rdgsbase64 (void)
23149 void _writefsbase_u32 (unsigned int)
23150 void _writefsbase_u64 (unsigned long long)
23151 void _writegsbase_u32 (unsigned int)
23152 void _writegsbase_u64 (unsigned long long)
23155 The following built-in function is available when @option{-mrdrnd} is
23156 used. All of them generate the machine instruction that is part of the
23160 unsigned int __builtin_ia32_rdrand16_step (unsigned short *)
23161 unsigned int __builtin_ia32_rdrand32_step (unsigned int *)
23162 unsigned int __builtin_ia32_rdrand64_step (unsigned long long *)
23165 The following built-in function is available when @option{-mptwrite} is
23166 used. All of them generate the machine instruction that is part of the
23170 void __builtin_ia32_ptwrite32 (unsigned)
23171 void __builtin_ia32_ptwrite64 (unsigned long long)
23174 The following built-in functions are available when @option{-msse4a} is used.
23175 All of them generate the machine instruction that is part of the name.
23178 void __builtin_ia32_movntsd (double *, v2df)
23179 void __builtin_ia32_movntss (float *, v4sf)
23180 v2di __builtin_ia32_extrq (v2di, v16qi)
23181 v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int)
23182 v2di __builtin_ia32_insertq (v2di, v2di)
23183 v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int)
23186 The following built-in functions are available when @option{-mxop} is used.
23188 v2df __builtin_ia32_vfrczpd (v2df)
23189 v4sf __builtin_ia32_vfrczps (v4sf)
23190 v2df __builtin_ia32_vfrczsd (v2df)
23191 v4sf __builtin_ia32_vfrczss (v4sf)
23192 v4df __builtin_ia32_vfrczpd256 (v4df)
23193 v8sf __builtin_ia32_vfrczps256 (v8sf)
23194 v2di __builtin_ia32_vpcmov (v2di, v2di, v2di)
23195 v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di)
23196 v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si)
23197 v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi)
23198 v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi)
23199 v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df)
23200 v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf)
23201 v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di)
23202 v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si)
23203 v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi)
23204 v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi)
23205 v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df)
23206 v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf)
23207 v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi)
23208 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
23209 v4si __builtin_ia32_vpcomeqd (v4si, v4si)
23210 v2di __builtin_ia32_vpcomeqq (v2di, v2di)
23211 v16qi __builtin_ia32_vpcomequb (v16qi, v16qi)
23212 v4si __builtin_ia32_vpcomequd (v4si, v4si)
23213 v2di __builtin_ia32_vpcomequq (v2di, v2di)
23214 v8hi __builtin_ia32_vpcomequw (v8hi, v8hi)
23215 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
23216 v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi)
23217 v4si __builtin_ia32_vpcomfalsed (v4si, v4si)
23218 v2di __builtin_ia32_vpcomfalseq (v2di, v2di)
23219 v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi)
23220 v4si __builtin_ia32_vpcomfalseud (v4si, v4si)
23221 v2di __builtin_ia32_vpcomfalseuq (v2di, v2di)
23222 v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi)
23223 v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi)
23224 v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi)
23225 v4si __builtin_ia32_vpcomged (v4si, v4si)
23226 v2di __builtin_ia32_vpcomgeq (v2di, v2di)
23227 v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi)
23228 v4si __builtin_ia32_vpcomgeud (v4si, v4si)
23229 v2di __builtin_ia32_vpcomgeuq (v2di, v2di)
23230 v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi)
23231 v8hi __builtin_ia32_vpcomgew (v8hi, v8hi)
23232 v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi)
23233 v4si __builtin_ia32_vpcomgtd (v4si, v4si)
23234 v2di __builtin_ia32_vpcomgtq (v2di, v2di)
23235 v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi)
23236 v4si __builtin_ia32_vpcomgtud (v4si, v4si)
23237 v2di __builtin_ia32_vpcomgtuq (v2di, v2di)
23238 v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi)
23239 v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi)
23240 v16qi __builtin_ia32_vpcomleb (v16qi, v16qi)
23241 v4si __builtin_ia32_vpcomled (v4si, v4si)
23242 v2di __builtin_ia32_vpcomleq (v2di, v2di)
23243 v16qi __builtin_ia32_vpcomleub (v16qi, v16qi)
23244 v4si __builtin_ia32_vpcomleud (v4si, v4si)
23245 v2di __builtin_ia32_vpcomleuq (v2di, v2di)
23246 v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi)
23247 v8hi __builtin_ia32_vpcomlew (v8hi, v8hi)
23248 v16qi __builtin_ia32_vpcomltb (v16qi, v16qi)
23249 v4si __builtin_ia32_vpcomltd (v4si, v4si)
23250 v2di __builtin_ia32_vpcomltq (v2di, v2di)
23251 v16qi __builtin_ia32_vpcomltub (v16qi, v16qi)
23252 v4si __builtin_ia32_vpcomltud (v4si, v4si)
23253 v2di __builtin_ia32_vpcomltuq (v2di, v2di)
23254 v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi)
23255 v8hi __builtin_ia32_vpcomltw (v8hi, v8hi)
23256 v16qi __builtin_ia32_vpcomneb (v16qi, v16qi)
23257 v4si __builtin_ia32_vpcomned (v4si, v4si)
23258 v2di __builtin_ia32_vpcomneq (v2di, v2di)
23259 v16qi __builtin_ia32_vpcomneub (v16qi, v16qi)
23260 v4si __builtin_ia32_vpcomneud (v4si, v4si)
23261 v2di __builtin_ia32_vpcomneuq (v2di, v2di)
23262 v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi)
23263 v8hi __builtin_ia32_vpcomnew (v8hi, v8hi)
23264 v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi)
23265 v4si __builtin_ia32_vpcomtrued (v4si, v4si)
23266 v2di __builtin_ia32_vpcomtrueq (v2di, v2di)
23267 v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi)
23268 v4si __builtin_ia32_vpcomtrueud (v4si, v4si)
23269 v2di __builtin_ia32_vpcomtrueuq (v2di, v2di)
23270 v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi)
23271 v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi)
23272 v4si __builtin_ia32_vphaddbd (v16qi)
23273 v2di __builtin_ia32_vphaddbq (v16qi)
23274 v8hi __builtin_ia32_vphaddbw (v16qi)
23275 v2di __builtin_ia32_vphadddq (v4si)
23276 v4si __builtin_ia32_vphaddubd (v16qi)
23277 v2di __builtin_ia32_vphaddubq (v16qi)
23278 v8hi __builtin_ia32_vphaddubw (v16qi)
23279 v2di __builtin_ia32_vphaddudq (v4si)
23280 v4si __builtin_ia32_vphadduwd (v8hi)
23281 v2di __builtin_ia32_vphadduwq (v8hi)
23282 v4si __builtin_ia32_vphaddwd (v8hi)
23283 v2di __builtin_ia32_vphaddwq (v8hi)
23284 v8hi __builtin_ia32_vphsubbw (v16qi)
23285 v2di __builtin_ia32_vphsubdq (v4si)
23286 v4si __builtin_ia32_vphsubwd (v8hi)
23287 v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si)
23288 v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di)
23289 v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di)
23290 v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si)
23291 v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di)
23292 v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di)
23293 v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si)
23294 v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi)
23295 v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si)
23296 v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi)
23297 v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si)
23298 v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si)
23299 v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi)
23300 v16qi __builtin_ia32_vprotb (v16qi, v16qi)
23301 v4si __builtin_ia32_vprotd (v4si, v4si)
23302 v2di __builtin_ia32_vprotq (v2di, v2di)
23303 v8hi __builtin_ia32_vprotw (v8hi, v8hi)
23304 v16qi __builtin_ia32_vpshab (v16qi, v16qi)
23305 v4si __builtin_ia32_vpshad (v4si, v4si)
23306 v2di __builtin_ia32_vpshaq (v2di, v2di)
23307 v8hi __builtin_ia32_vpshaw (v8hi, v8hi)
23308 v16qi __builtin_ia32_vpshlb (v16qi, v16qi)
23309 v4si __builtin_ia32_vpshld (v4si, v4si)
23310 v2di __builtin_ia32_vpshlq (v2di, v2di)
23311 v8hi __builtin_ia32_vpshlw (v8hi, v8hi)
23314 The following built-in functions are available when @option{-mfma4} is used.
23315 All of them generate the machine instruction that is part of the name.
23318 v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df)
23319 v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf)
23320 v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df)
23321 v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf)
23322 v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df)
23323 v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf)
23324 v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df)
23325 v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf)
23326 v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df)
23327 v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf)
23328 v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df)
23329 v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf)
23330 v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df)
23331 v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf)
23332 v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df)
23333 v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf)
23334 v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df)
23335 v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf)
23336 v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df)
23337 v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf)
23338 v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df)
23339 v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf)
23340 v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df)
23341 v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf)
23342 v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df)
23343 v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf)
23344 v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df)
23345 v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf)
23346 v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df)
23347 v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf)
23348 v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df)
23349 v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf)
23353 The following built-in functions are available when @option{-mlwp} is used.
23356 void __builtin_ia32_llwpcb16 (void *);
23357 void __builtin_ia32_llwpcb32 (void *);
23358 void __builtin_ia32_llwpcb64 (void *);
23359 void * __builtin_ia32_llwpcb16 (void);
23360 void * __builtin_ia32_llwpcb32 (void);
23361 void * __builtin_ia32_llwpcb64 (void);
23362 void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short)
23363 void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int)
23364 void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int)
23365 unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short)
23366 unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int)
23367 unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int)
23370 The following built-in functions are available when @option{-mbmi} is used.
23371 All of them generate the machine instruction that is part of the name.
23373 unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int);
23374 unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long);
23377 The following built-in functions are available when @option{-mbmi2} is used.
23378 All of them generate the machine instruction that is part of the name.
23380 unsigned int _bzhi_u32 (unsigned int, unsigned int)
23381 unsigned int _pdep_u32 (unsigned int, unsigned int)
23382 unsigned int _pext_u32 (unsigned int, unsigned int)
23383 unsigned long long _bzhi_u64 (unsigned long long, unsigned long long)
23384 unsigned long long _pdep_u64 (unsigned long long, unsigned long long)
23385 unsigned long long _pext_u64 (unsigned long long, unsigned long long)
23388 The following built-in functions are available when @option{-mlzcnt} is used.
23389 All of them generate the machine instruction that is part of the name.
23391 unsigned short __builtin_ia32_lzcnt_u16(unsigned short);
23392 unsigned int __builtin_ia32_lzcnt_u32(unsigned int);
23393 unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long);
23396 The following built-in functions are available when @option{-mfxsr} is used.
23397 All of them generate the machine instruction that is part of the name.
23399 void __builtin_ia32_fxsave (void *)
23400 void __builtin_ia32_fxrstor (void *)
23401 void __builtin_ia32_fxsave64 (void *)
23402 void __builtin_ia32_fxrstor64 (void *)
23405 The following built-in functions are available when @option{-mxsave} is used.
23406 All of them generate the machine instruction that is part of the name.
23408 void __builtin_ia32_xsave (void *, long long)
23409 void __builtin_ia32_xrstor (void *, long long)
23410 void __builtin_ia32_xsave64 (void *, long long)
23411 void __builtin_ia32_xrstor64 (void *, long long)
23414 The following built-in functions are available when @option{-mxsaveopt} is used.
23415 All of them generate the machine instruction that is part of the name.
23417 void __builtin_ia32_xsaveopt (void *, long long)
23418 void __builtin_ia32_xsaveopt64 (void *, long long)
23421 The following built-in functions are available when @option{-mtbm} is used.
23422 Both of them generate the immediate form of the bextr machine instruction.
23424 unsigned int __builtin_ia32_bextri_u32 (unsigned int,
23425 const unsigned int);
23426 unsigned long long __builtin_ia32_bextri_u64 (unsigned long long,
23427 const unsigned long long);
23431 The following built-in functions are available when @option{-m3dnow} is used.
23432 All of them generate the machine instruction that is part of the name.
23435 void __builtin_ia32_femms (void)
23436 v8qi __builtin_ia32_pavgusb (v8qi, v8qi)
23437 v2si __builtin_ia32_pf2id (v2sf)
23438 v2sf __builtin_ia32_pfacc (v2sf, v2sf)
23439 v2sf __builtin_ia32_pfadd (v2sf, v2sf)
23440 v2si __builtin_ia32_pfcmpeq (v2sf, v2sf)
23441 v2si __builtin_ia32_pfcmpge (v2sf, v2sf)
23442 v2si __builtin_ia32_pfcmpgt (v2sf, v2sf)
23443 v2sf __builtin_ia32_pfmax (v2sf, v2sf)
23444 v2sf __builtin_ia32_pfmin (v2sf, v2sf)
23445 v2sf __builtin_ia32_pfmul (v2sf, v2sf)
23446 v2sf __builtin_ia32_pfrcp (v2sf)
23447 v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf)
23448 v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf)
23449 v2sf __builtin_ia32_pfrsqrt (v2sf)
23450 v2sf __builtin_ia32_pfsub (v2sf, v2sf)
23451 v2sf __builtin_ia32_pfsubr (v2sf, v2sf)
23452 v2sf __builtin_ia32_pi2fd (v2si)
23453 v4hi __builtin_ia32_pmulhrw (v4hi, v4hi)
23456 The following built-in functions are available when @option{-m3dnowa} is used.
23457 All of them generate the machine instruction that is part of the name.
23460 v2si __builtin_ia32_pf2iw (v2sf)
23461 v2sf __builtin_ia32_pfnacc (v2sf, v2sf)
23462 v2sf __builtin_ia32_pfpnacc (v2sf, v2sf)
23463 v2sf __builtin_ia32_pi2fw (v2si)
23464 v2sf __builtin_ia32_pswapdsf (v2sf)
23465 v2si __builtin_ia32_pswapdsi (v2si)
23468 The following built-in functions are available when @option{-mrtm} is used
23469 They are used for restricted transactional memory. These are the internal
23470 low level functions. Normally the functions in
23471 @ref{x86 transactional memory intrinsics} should be used instead.
23474 int __builtin_ia32_xbegin ()
23475 void __builtin_ia32_xend ()
23476 void __builtin_ia32_xabort (status)
23477 int __builtin_ia32_xtest ()
23480 The following built-in functions are available when @option{-mmwaitx} is used.
23481 All of them generate the machine instruction that is part of the name.
23483 void __builtin_ia32_monitorx (void *, unsigned int, unsigned int)
23484 void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int)
23487 The following built-in functions are available when @option{-mclzero} is used.
23488 All of them generate the machine instruction that is part of the name.
23490 void __builtin_i32_clzero (void *)
23493 The following built-in functions are available when @option{-mpku} is used.
23494 They generate reads and writes to PKRU.
23496 void __builtin_ia32_wrpkru (unsigned int)
23497 unsigned int __builtin_ia32_rdpkru ()
23500 The following built-in functions are available when @option{-mcet} or
23501 @option{-mshstk} option is used. They support shadow stack
23502 machine instructions from Intel Control-flow Enforcement Technology (CET).
23503 Each built-in function generates the machine instruction that is part
23504 of the function's name. These are the internal low-level functions.
23505 Normally the functions in @ref{x86 control-flow protection intrinsics}
23506 should be used instead.
23509 unsigned int __builtin_ia32_rdsspd (void)
23510 unsigned long long __builtin_ia32_rdsspq (void)
23511 void __builtin_ia32_incsspd (unsigned int)
23512 void __builtin_ia32_incsspq (unsigned long long)
23513 void __builtin_ia32_saveprevssp(void);
23514 void __builtin_ia32_rstorssp(void *);
23515 void __builtin_ia32_wrssd(unsigned int, void *);
23516 void __builtin_ia32_wrssq(unsigned long long, void *);
23517 void __builtin_ia32_wrussd(unsigned int, void *);
23518 void __builtin_ia32_wrussq(unsigned long long, void *);
23519 void __builtin_ia32_setssbsy(void);
23520 void __builtin_ia32_clrssbsy(void *);
23523 @node x86 transactional memory intrinsics
23524 @subsection x86 Transactional Memory Intrinsics
23526 These hardware transactional memory intrinsics for x86 allow you to use
23527 memory transactions with RTM (Restricted Transactional Memory).
23528 This support is enabled with the @option{-mrtm} option.
23529 For using HLE (Hardware Lock Elision) see
23530 @ref{x86 specific memory model extensions for transactional memory} instead.
23532 A memory transaction commits all changes to memory in an atomic way,
23533 as visible to other threads. If the transaction fails it is rolled back
23534 and all side effects discarded.
23536 Generally there is no guarantee that a memory transaction ever succeeds
23537 and suitable fallback code always needs to be supplied.
23539 @deftypefn {RTM Function} {unsigned} _xbegin ()
23540 Start a RTM (Restricted Transactional Memory) transaction.
23541 Returns @code{_XBEGIN_STARTED} when the transaction
23542 started successfully (note this is not 0, so the constant has to be
23543 explicitly tested).
23545 If the transaction aborts, all side effects
23546 are undone and an abort code encoded as a bit mask is returned.
23547 The following macros are defined:
23550 @item _XABORT_EXPLICIT
23551 Transaction was explicitly aborted with @code{_xabort}. The parameter passed
23552 to @code{_xabort} is available with @code{_XABORT_CODE(status)}.
23553 @item _XABORT_RETRY
23554 Transaction retry is possible.
23555 @item _XABORT_CONFLICT
23556 Transaction abort due to a memory conflict with another thread.
23557 @item _XABORT_CAPACITY
23558 Transaction abort due to the transaction using too much memory.
23559 @item _XABORT_DEBUG
23560 Transaction abort due to a debug trap.
23561 @item _XABORT_NESTED
23562 Transaction abort in an inner nested transaction.
23565 There is no guarantee
23566 any transaction ever succeeds, so there always needs to be a valid
23570 @deftypefn {RTM Function} {void} _xend ()
23571 Commit the current transaction. When no transaction is active this faults.
23572 All memory side effects of the transaction become visible
23573 to other threads in an atomic manner.
23576 @deftypefn {RTM Function} {int} _xtest ()
23577 Return a nonzero value if a transaction is currently active, otherwise 0.
23580 @deftypefn {RTM Function} {void} _xabort (status)
23581 Abort the current transaction. When no transaction is active this is a no-op.
23582 The @var{status} is an 8-bit constant; its value is encoded in the return
23583 value from @code{_xbegin}.
23586 Here is an example showing handling for @code{_XABORT_RETRY}
23587 and a fallback path for other failures:
23590 #include <immintrin.h>
23592 int n_tries, max_tries;
23593 unsigned status = _XABORT_EXPLICIT;
23596 for (n_tries = 0; n_tries < max_tries; n_tries++)
23598 status = _xbegin ();
23599 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY))
23602 if (status == _XBEGIN_STARTED)
23604 ... transaction code...
23609 ... non-transactional fallback path...
23614 Note that, in most cases, the transactional and non-transactional code
23615 must synchronize together to ensure consistency.
23617 @node x86 control-flow protection intrinsics
23618 @subsection x86 Control-Flow Protection Intrinsics
23620 @deftypefn {CET Function} {ret_type} _get_ssp (void)
23621 Get the current value of shadow stack pointer if shadow stack support
23622 from Intel CET is enabled in the hardware or @code{0} otherwise.
23623 The @code{ret_type} is @code{unsigned long long} for 64-bit targets
23624 and @code{unsigned int} for 32-bit targets.
23627 @deftypefn {CET Function} void _inc_ssp (unsigned int)
23628 Increment the current shadow stack pointer by the size specified by the
23629 function argument. The argument is masked to a byte value for security
23630 reasons, so to increment by more than 255 bytes you must call the function
23634 The shadow stack unwind code looks like:
23637 #include <immintrin.h>
23639 /* Unwind the shadow stack for EH. */
23640 #define _Unwind_Frames_Extra(x) \
23643 _Unwind_Word ssp = _get_ssp (); \
23646 _Unwind_Word tmp = (x); \
23647 while (tmp > 255) \
23659 This code runs unconditionally on all 64-bit processors. For 32-bit
23660 processors the code runs on those that support multi-byte NOP instructions.
23662 @node Target Format Checks
23663 @section Format Checks Specific to Particular Target Machines
23665 For some target machines, GCC supports additional options to the
23667 (@pxref{Function Attributes,,Declaring Attributes of Functions}).
23670 * Solaris Format Checks::
23671 * Darwin Format Checks::
23674 @node Solaris Format Checks
23675 @subsection Solaris Format Checks
23677 Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format
23678 check. @code{cmn_err} accepts a subset of the standard @code{printf}
23679 conversions, and the two-argument @code{%b} conversion for displaying
23680 bit-fields. See the Solaris man page for @code{cmn_err} for more information.
23682 @node Darwin Format Checks
23683 @subsection Darwin Format Checks
23685 In addition to the full set of format archetypes (attribute format style
23686 arguments such as @code{printf}, @code{scanf}, @code{strftime}, and
23687 @code{strfmon}), Darwin targets also support the @code{CFString} (or
23688 @code{__CFString__}) archetype in the @code{format} attribute.
23689 Declarations with this archetype are parsed for correct syntax
23690 and argument types. However, parsing of the format string itself and
23691 validating arguments against it in calls to such functions is currently
23694 Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may
23695 also be used as format arguments. Note that the relevant headers are only likely to be
23696 available on Darwin (OSX) installations. On such installations, the XCode and system
23697 documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and
23698 associated functions.
23701 @section Pragmas Accepted by GCC
23703 @cindex @code{#pragma}
23705 GCC supports several types of pragmas, primarily in order to compile
23706 code originally written for other compilers. Note that in general
23707 we do not recommend the use of pragmas; @xref{Function Attributes},
23708 for further explanation.
23710 The GNU C preprocessor recognizes several pragmas in addition to the
23711 compiler pragmas documented here. Refer to the CPP manual for more
23715 * AArch64 Pragmas::
23720 * RS/6000 and PowerPC Pragmas::
23723 * Solaris Pragmas::
23724 * Symbol-Renaming Pragmas::
23725 * Structure-Layout Pragmas::
23727 * Diagnostic Pragmas::
23728 * Visibility Pragmas::
23729 * Push/Pop Macro Pragmas::
23730 * Function Specific Option Pragmas::
23731 * Loop-Specific Pragmas::
23734 @node AArch64 Pragmas
23735 @subsection AArch64 Pragmas
23737 The pragmas defined by the AArch64 target correspond to the AArch64
23738 target function attributes. They can be specified as below:
23740 #pragma GCC target("string")
23743 where @code{@var{string}} can be any string accepted as an AArch64 target
23744 attribute. @xref{AArch64 Function Attributes}, for more details
23745 on the permissible values of @code{string}.
23748 @subsection ARM Pragmas
23750 The ARM target defines pragmas for controlling the default addition of
23751 @code{long_call} and @code{short_call} attributes to functions.
23752 @xref{Function Attributes}, for information about the effects of these
23757 @cindex pragma, long_calls
23758 Set all subsequent functions to have the @code{long_call} attribute.
23760 @item no_long_calls
23761 @cindex pragma, no_long_calls
23762 Set all subsequent functions to have the @code{short_call} attribute.
23764 @item long_calls_off
23765 @cindex pragma, long_calls_off
23766 Do not affect the @code{long_call} or @code{short_call} attributes of
23767 subsequent functions.
23771 @subsection M32C Pragmas
23774 @item GCC memregs @var{number}
23775 @cindex pragma, memregs
23776 Overrides the command-line option @code{-memregs=} for the current
23777 file. Use with care! This pragma must be before any function in the
23778 file, and mixing different memregs values in different objects may
23779 make them incompatible. This pragma is useful when a
23780 performance-critical function uses a memreg for temporary values,
23781 as it may allow you to reduce the number of memregs used.
23783 @item ADDRESS @var{name} @var{address}
23784 @cindex pragma, address
23785 For any declared symbols matching @var{name}, this does three things
23786 to that symbol: it forces the symbol to be located at the given
23787 address (a number), it forces the symbol to be volatile, and it
23788 changes the symbol's scope to be static. This pragma exists for
23789 compatibility with other compilers, but note that the common
23790 @code{1234H} numeric syntax is not supported (use @code{0x1234}
23794 #pragma ADDRESS port3 0x103
23801 @subsection MeP Pragmas
23805 @item custom io_volatile (on|off)
23806 @cindex pragma, custom io_volatile
23807 Overrides the command-line option @code{-mio-volatile} for the current
23808 file. Note that for compatibility with future GCC releases, this
23809 option should only be used once before any @code{io} variables in each
23812 @item GCC coprocessor available @var{registers}
23813 @cindex pragma, coprocessor available
23814 Specifies which coprocessor registers are available to the register
23815 allocator. @var{registers} may be a single register, register range
23816 separated by ellipses, or comma-separated list of those. Example:
23819 #pragma GCC coprocessor available $c0...$c10, $c28
23822 @item GCC coprocessor call_saved @var{registers}
23823 @cindex pragma, coprocessor call_saved
23824 Specifies which coprocessor registers are to be saved and restored by
23825 any function using them. @var{registers} may be a single register,
23826 register range separated by ellipses, or comma-separated list of
23830 #pragma GCC coprocessor call_saved $c4...$c6, $c31
23833 @item GCC coprocessor subclass '(A|B|C|D)' = @var{registers}
23834 @cindex pragma, coprocessor subclass
23835 Creates and defines a register class. These register classes can be
23836 used by inline @code{asm} constructs. @var{registers} may be a single
23837 register, register range separated by ellipses, or comma-separated
23838 list of those. Example:
23841 #pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6
23843 asm ("cpfoo %0" : "=B" (x));
23846 @item GCC disinterrupt @var{name} , @var{name} @dots{}
23847 @cindex pragma, disinterrupt
23848 For the named functions, the compiler adds code to disable interrupts
23849 for the duration of those functions. If any functions so named
23850 are not encountered in the source, a warning is emitted that the pragma is
23851 not used. Examples:
23854 #pragma disinterrupt foo
23855 #pragma disinterrupt bar, grill
23856 int foo () @{ @dots{} @}
23859 @item GCC call @var{name} , @var{name} @dots{}
23860 @cindex pragma, call
23861 For the named functions, the compiler always uses a register-indirect
23862 call model when calling the named functions. Examples:
23872 @subsection PRU Pragmas
23876 @item ctable_entry @var{index} @var{constant_address}
23877 @cindex pragma, ctable_entry
23878 Specifies that the PRU CTABLE entry given by @var{index} has the value
23879 @var{constant_address}. This enables GCC to emit LBCO/SBCO instructions
23880 when the load/store address is known and can be addressed with some CTABLE
23881 entry. For example:
23884 /* will compile to "sbco Rx, 2, 0x10, 4" */
23885 #pragma ctable_entry 2 0x4802a000
23886 *(unsigned int *)0x4802a010 = val;
23891 @node RS/6000 and PowerPC Pragmas
23892 @subsection RS/6000 and PowerPC Pragmas
23894 The RS/6000 and PowerPC targets define one pragma for controlling
23895 whether or not the @code{longcall} attribute is added to function
23896 declarations by default. This pragma overrides the @option{-mlongcall}
23897 option, but not the @code{longcall} and @code{shortcall} attributes.
23898 @xref{RS/6000 and PowerPC Options}, for more information about when long
23899 calls are and are not necessary.
23903 @cindex pragma, longcall
23904 Apply the @code{longcall} attribute to all subsequent function
23908 Do not apply the @code{longcall} attribute to subsequent function
23912 @c Describe h8300 pragmas here.
23913 @c Describe sh pragmas here.
23914 @c Describe v850 pragmas here.
23916 @node S/390 Pragmas
23917 @subsection S/390 Pragmas
23919 The pragmas defined by the S/390 target correspond to the S/390
23920 target function attributes and some the additional options:
23927 Note that options of the pragma, unlike options of the target
23928 attribute, do change the value of preprocessor macros like
23929 @code{__VEC__}. They can be specified as below:
23932 #pragma GCC target("string[,string]...")
23933 #pragma GCC target("string"[,"string"]...)
23936 @node Darwin Pragmas
23937 @subsection Darwin Pragmas
23939 The following pragmas are available for all architectures running the
23940 Darwin operating system. These are useful for compatibility with other
23944 @item mark @var{tokens}@dots{}
23945 @cindex pragma, mark
23946 This pragma is accepted, but has no effect.
23948 @item options align=@var{alignment}
23949 @cindex pragma, options align
23950 This pragma sets the alignment of fields in structures. The values of
23951 @var{alignment} may be @code{mac68k}, to emulate m68k alignment, or
23952 @code{power}, to emulate PowerPC alignment. Uses of this pragma nest
23953 properly; to restore the previous setting, use @code{reset} for the
23956 @item segment @var{tokens}@dots{}
23957 @cindex pragma, segment
23958 This pragma is accepted, but has no effect.
23960 @item unused (@var{var} [, @var{var}]@dots{})
23961 @cindex pragma, unused
23962 This pragma declares variables to be possibly unused. GCC does not
23963 produce warnings for the listed variables. The effect is similar to
23964 that of the @code{unused} attribute, except that this pragma may appear
23965 anywhere within the variables' scopes.
23968 @node Solaris Pragmas
23969 @subsection Solaris Pragmas
23971 The Solaris target supports @code{#pragma redefine_extname}
23972 (@pxref{Symbol-Renaming Pragmas}). It also supports additional
23973 @code{#pragma} directives for compatibility with the system compiler.
23976 @item align @var{alignment} (@var{variable} [, @var{variable}]...)
23977 @cindex pragma, align
23979 Increase the minimum alignment of each @var{variable} to @var{alignment}.
23980 This is the same as GCC's @code{aligned} attribute @pxref{Variable
23981 Attributes}). Macro expansion occurs on the arguments to this pragma
23982 when compiling C and Objective-C@. It does not currently occur when
23983 compiling C++, but this is a bug which may be fixed in a future
23986 @item fini (@var{function} [, @var{function}]...)
23987 @cindex pragma, fini
23989 This pragma causes each listed @var{function} to be called after
23990 main, or during shared module unloading, by adding a call to the
23991 @code{.fini} section.
23993 @item init (@var{function} [, @var{function}]...)
23994 @cindex pragma, init
23996 This pragma causes each listed @var{function} to be called during
23997 initialization (before @code{main}) or during shared module loading, by
23998 adding a call to the @code{.init} section.
24002 @node Symbol-Renaming Pragmas
24003 @subsection Symbol-Renaming Pragmas
24005 GCC supports a @code{#pragma} directive that changes the name used in
24006 assembly for a given declaration. While this pragma is supported on all
24007 platforms, it is intended primarily to provide compatibility with the
24008 Solaris system headers. This effect can also be achieved using the asm
24009 labels extension (@pxref{Asm Labels}).
24012 @item redefine_extname @var{oldname} @var{newname}
24013 @cindex pragma, redefine_extname
24015 This pragma gives the C function @var{oldname} the assembly symbol
24016 @var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME}
24017 is defined if this pragma is available (currently on all platforms).
24020 This pragma and the @code{asm} labels extension interact in a complicated
24021 manner. Here are some corner cases you may want to be aware of:
24024 @item This pragma silently applies only to declarations with external
24025 linkage. The @code{asm} label feature does not have this restriction.
24027 @item In C++, this pragma silently applies only to declarations with
24028 ``C'' linkage. Again, @code{asm} labels do not have this restriction.
24030 @item If either of the ways of changing the assembly name of a
24031 declaration are applied to a declaration whose assembly name has
24032 already been determined (either by a previous use of one of these
24033 features, or because the compiler needed the assembly name in order to
24034 generate code), and the new name is different, a warning issues and
24035 the name does not change.
24037 @item The @var{oldname} used by @code{#pragma redefine_extname} is
24038 always the C-language name.
24041 @node Structure-Layout Pragmas
24042 @subsection Structure-Layout Pragmas
24044 For compatibility with Microsoft Windows compilers, GCC supports a
24045 set of @code{#pragma} directives that change the maximum alignment of
24046 members of structures (other than zero-width bit-fields), unions, and
24047 classes subsequently defined. The @var{n} value below always is required
24048 to be a small power of two and specifies the new alignment in bytes.
24051 @item @code{#pragma pack(@var{n})} simply sets the new alignment.
24052 @item @code{#pragma pack()} sets the alignment to the one that was in
24053 effect when compilation started (see also command-line option
24054 @option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}).
24055 @item @code{#pragma pack(push[,@var{n}])} pushes the current alignment
24056 setting on an internal stack and then optionally sets the new alignment.
24057 @item @code{#pragma pack(pop)} restores the alignment setting to the one
24058 saved at the top of the internal stack (and removes that stack entry).
24059 Note that @code{#pragma pack([@var{n}])} does not influence this internal
24060 stack; thus it is possible to have @code{#pragma pack(push)} followed by
24061 multiple @code{#pragma pack(@var{n})} instances and finalized by a single
24062 @code{#pragma pack(pop)}.
24065 Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct}
24066 directive which lays out structures and unions subsequently defined as the
24067 documented @code{__attribute__ ((ms_struct))}.
24070 @item @code{#pragma ms_struct on} turns on the Microsoft layout.
24071 @item @code{#pragma ms_struct off} turns off the Microsoft layout.
24072 @item @code{#pragma ms_struct reset} goes back to the default layout.
24075 Most targets also support the @code{#pragma scalar_storage_order} directive
24076 which lays out structures and unions subsequently defined as the documented
24077 @code{__attribute__ ((scalar_storage_order))}.
24080 @item @code{#pragma scalar_storage_order big-endian} sets the storage order
24081 of the scalar fields to big-endian.
24082 @item @code{#pragma scalar_storage_order little-endian} sets the storage order
24083 of the scalar fields to little-endian.
24084 @item @code{#pragma scalar_storage_order default} goes back to the endianness
24085 that was in effect when compilation started (see also command-line option
24086 @option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}).
24090 @subsection Weak Pragmas
24092 For compatibility with SVR4, GCC supports a set of @code{#pragma}
24093 directives for declaring symbols to be weak, and defining weak
24097 @item #pragma weak @var{symbol}
24098 @cindex pragma, weak
24099 This pragma declares @var{symbol} to be weak, as if the declaration
24100 had the attribute of the same name. The pragma may appear before
24101 or after the declaration of @var{symbol}. It is not an error for
24102 @var{symbol} to never be defined at all.
24104 @item #pragma weak @var{symbol1} = @var{symbol2}
24105 This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}.
24106 It is an error if @var{symbol2} is not defined in the current
24110 @node Diagnostic Pragmas
24111 @subsection Diagnostic Pragmas
24113 GCC allows the user to selectively enable or disable certain types of
24114 diagnostics, and change the kind of the diagnostic. For example, a
24115 project's policy might require that all sources compile with
24116 @option{-Werror} but certain files might have exceptions allowing
24117 specific types of warnings. Or, a project might selectively enable
24118 diagnostics and treat them as errors depending on which preprocessor
24119 macros are defined.
24122 @item #pragma GCC diagnostic @var{kind} @var{option}
24123 @cindex pragma, diagnostic
24125 Modifies the disposition of a diagnostic. Note that not all
24126 diagnostics are modifiable; at the moment only warnings (normally
24127 controlled by @samp{-W@dots{}}) can be controlled, and not all of them.
24128 Use @option{-fdiagnostics-show-option} to determine which diagnostics
24129 are controllable and which option controls them.
24131 @var{kind} is @samp{error} to treat this diagnostic as an error,
24132 @samp{warning} to treat it like a warning (even if @option{-Werror} is
24133 in effect), or @samp{ignored} if the diagnostic is to be ignored.
24134 @var{option} is a double quoted string that matches the command-line
24138 #pragma GCC diagnostic warning "-Wformat"
24139 #pragma GCC diagnostic error "-Wformat"
24140 #pragma GCC diagnostic ignored "-Wformat"
24143 Note that these pragmas override any command-line options. GCC keeps
24144 track of the location of each pragma, and issues diagnostics according
24145 to the state as of that point in the source file. Thus, pragmas occurring
24146 after a line do not affect diagnostics caused by that line.
24148 @item #pragma GCC diagnostic push
24149 @itemx #pragma GCC diagnostic pop
24151 Causes GCC to remember the state of the diagnostics as of each
24152 @code{push}, and restore to that point at each @code{pop}. If a
24153 @code{pop} has no matching @code{push}, the command-line options are
24157 #pragma GCC diagnostic error "-Wuninitialized"
24158 foo(a); /* error is given for this one */
24159 #pragma GCC diagnostic push
24160 #pragma GCC diagnostic ignored "-Wuninitialized"
24161 foo(b); /* no diagnostic for this one */
24162 #pragma GCC diagnostic pop
24163 foo(c); /* error is given for this one */
24164 #pragma GCC diagnostic pop
24165 foo(d); /* depends on command-line options */
24170 GCC also offers a simple mechanism for printing messages during
24174 @item #pragma message @var{string}
24175 @cindex pragma, diagnostic
24177 Prints @var{string} as a compiler message on compilation. The message
24178 is informational only, and is neither a compilation warning nor an
24179 error. Newlines can be included in the string by using the @samp{\n}
24183 #pragma message "Compiling " __FILE__ "..."
24186 @var{string} may be parenthesized, and is printed with location
24187 information. For example,
24190 #define DO_PRAGMA(x) _Pragma (#x)
24191 #define TODO(x) DO_PRAGMA(message ("TODO - " #x))
24193 TODO(Remember to fix this)
24197 prints @samp{/tmp/file.c:4: note: #pragma message:
24198 TODO - Remember to fix this}.
24200 @item #pragma GCC error @var{message}
24201 @cindex pragma, diagnostic
24202 Generates an error message. This pragma @emph{is} considered to
24203 indicate an error in the compilation, and it will be treated as such.
24205 Newlines can be included in the string by using the @samp{\n}
24206 escape sequence. They will be displayed as newlines even if the
24207 @option{-fmessage-length} option is set to zero.
24209 The error is only generated if the pragma is present in the code after
24210 pre-processing has been completed. It does not matter however if the
24211 code containing the pragma is unreachable:
24215 #pragma GCC error "this error is not seen"
24220 #pragma GCC error "this error is seen"
24224 @item #pragma GCC warning @var{message}
24225 @cindex pragma, diagnostic
24226 This is just like @samp{pragma GCC error} except that a warning
24227 message is issued instead of an error message. Unless
24228 @option{-Werror} is in effect, in which case this pragma will generate
24233 @node Visibility Pragmas
24234 @subsection Visibility Pragmas
24237 @item #pragma GCC visibility push(@var{visibility})
24238 @itemx #pragma GCC visibility pop
24239 @cindex pragma, visibility
24241 This pragma allows the user to set the visibility for multiple
24242 declarations without having to give each a visibility attribute
24243 (@pxref{Function Attributes}).
24245 In C++, @samp{#pragma GCC visibility} affects only namespace-scope
24246 declarations. Class members and template specializations are not
24247 affected; if you want to override the visibility for a particular
24248 member or instantiation, you must use an attribute.
24253 @node Push/Pop Macro Pragmas
24254 @subsection Push/Pop Macro Pragmas
24256 For compatibility with Microsoft Windows compilers, GCC supports
24257 @samp{#pragma push_macro(@var{"macro_name"})}
24258 and @samp{#pragma pop_macro(@var{"macro_name"})}.
24261 @item #pragma push_macro(@var{"macro_name"})
24262 @cindex pragma, push_macro
24263 This pragma saves the value of the macro named as @var{macro_name} to
24264 the top of the stack for this macro.
24266 @item #pragma pop_macro(@var{"macro_name"})
24267 @cindex pragma, pop_macro
24268 This pragma sets the value of the macro named as @var{macro_name} to
24269 the value on top of the stack for this macro. If the stack for
24270 @var{macro_name} is empty, the value of the macro remains unchanged.
24277 #pragma push_macro("X")
24280 #pragma pop_macro("X")
24285 In this example, the definition of X as 1 is saved by @code{#pragma
24286 push_macro} and restored by @code{#pragma pop_macro}.
24288 @node Function Specific Option Pragmas
24289 @subsection Function Specific Option Pragmas
24292 @item #pragma GCC target (@var{string}, @dots{})
24293 @cindex pragma GCC target
24295 This pragma allows you to set target-specific options for functions
24296 defined later in the source file. One or more strings can be
24297 specified. Each function that is defined after this point is treated
24298 as if it had been declared with one @code{target(}@var{string}@code{)}
24299 attribute for each @var{string} argument. The parentheses around
24300 the strings in the pragma are optional. @xref{Function Attributes},
24301 for more information about the @code{target} attribute and the attribute
24304 The @code{#pragma GCC target} pragma is presently implemented for
24305 x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only.
24307 @item #pragma GCC optimize (@var{string}, @dots{})
24308 @cindex pragma GCC optimize
24310 This pragma allows you to set global optimization options for functions
24311 defined later in the source file. One or more strings can be
24312 specified. Each function that is defined after this point is treated
24313 as if it had been declared with one @code{optimize(}@var{string}@code{)}
24314 attribute for each @var{string} argument. The parentheses around
24315 the strings in the pragma are optional. @xref{Function Attributes},
24316 for more information about the @code{optimize} attribute and the attribute
24319 @item #pragma GCC push_options
24320 @itemx #pragma GCC pop_options
24321 @cindex pragma GCC push_options
24322 @cindex pragma GCC pop_options
24324 These pragmas maintain a stack of the current target and optimization
24325 options. It is intended for include files where you temporarily want
24326 to switch to using a different @samp{#pragma GCC target} or
24327 @samp{#pragma GCC optimize} and then to pop back to the previous
24330 @item #pragma GCC reset_options
24331 @cindex pragma GCC reset_options
24333 This pragma clears the current @code{#pragma GCC target} and
24334 @code{#pragma GCC optimize} to use the default switches as specified
24335 on the command line.
24339 @node Loop-Specific Pragmas
24340 @subsection Loop-Specific Pragmas
24343 @item #pragma GCC ivdep
24344 @cindex pragma GCC ivdep
24346 With this pragma, the programmer asserts that there are no loop-carried
24347 dependencies which would prevent consecutive iterations of
24348 the following loop from executing concurrently with SIMD
24349 (single instruction multiple data) instructions.
24351 For example, the compiler can only unconditionally vectorize the following
24352 loop with the pragma:
24355 void foo (int n, int *a, int *b, int *c)
24359 for (i = 0; i < n; ++i)
24360 a[i] = b[i] + c[i];
24365 In this example, using the @code{restrict} qualifier had the same
24366 effect. In the following example, that would not be possible. Assume
24367 @math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows
24368 that it can unconditionally vectorize the following loop:
24371 void ignore_vec_dep (int *a, int k, int c, int m)
24374 for (int i = 0; i < m; i++)
24375 a[i] = a[i + k] * c;
24379 @item #pragma GCC unroll @var{n}
24380 @cindex pragma GCC unroll @var{n}
24382 You can use this pragma to control how many times a loop should be unrolled.
24383 It must be placed immediately before a @code{for}, @code{while} or @code{do}
24384 loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows.
24385 @var{n} is an integer constant expression specifying the unrolling factor.
24386 The values of @math{0} and @math{1} block any unrolling of the loop.
24390 @node Unnamed Fields
24391 @section Unnamed Structure and Union Fields
24392 @cindex @code{struct}
24393 @cindex @code{union}
24395 As permitted by ISO C11 and for compatibility with other compilers,
24396 GCC allows you to define
24397 a structure or union that contains, as fields, structures and unions
24398 without names. For example:
24412 In this example, you are able to access members of the unnamed
24413 union with code like @samp{foo.b}. Note that only unnamed structs and
24414 unions are allowed, you may not have, for example, an unnamed
24417 You must never create such structures that cause ambiguous field definitions.
24418 For example, in this structure:
24430 it is ambiguous which @code{a} is being referred to with @samp{foo.a}.
24431 The compiler gives errors for such constructs.
24433 @opindex fms-extensions
24434 Unless @option{-fms-extensions} is used, the unnamed field must be a
24435 structure or union definition without a tag (for example, @samp{struct
24436 @{ int a; @};}). If @option{-fms-extensions} is used, the field may
24437 also be a definition with a tag such as @samp{struct foo @{ int a;
24438 @};}, a reference to a previously defined structure or union such as
24439 @samp{struct foo;}, or a reference to a @code{typedef} name for a
24440 previously defined structure or union type.
24442 @opindex fplan9-extensions
24443 The option @option{-fplan9-extensions} enables
24444 @option{-fms-extensions} as well as two other extensions. First, a
24445 pointer to a structure is automatically converted to a pointer to an
24446 anonymous field for assignments and function calls. For example:
24449 struct s1 @{ int a; @};
24450 struct s2 @{ struct s1; @};
24451 extern void f1 (struct s1 *);
24452 void f2 (struct s2 *p) @{ f1 (p); @}
24456 In the call to @code{f1} inside @code{f2}, the pointer @code{p} is
24457 converted into a pointer to the anonymous field.
24459 Second, when the type of an anonymous field is a @code{typedef} for a
24460 @code{struct} or @code{union}, code may refer to the field using the
24461 name of the @code{typedef}.
24464 typedef struct @{ int a; @} s1;
24465 struct s2 @{ s1; @};
24466 s1 f1 (struct s2 *p) @{ return p->s1; @}
24469 These usages are only permitted when they are not ambiguous.
24472 @section Thread-Local Storage
24473 @cindex Thread-Local Storage
24474 @cindex @acronym{TLS}
24475 @cindex @code{__thread}
24477 Thread-local storage (@acronym{TLS}) is a mechanism by which variables
24478 are allocated such that there is one instance of the variable per extant
24479 thread. The runtime model GCC uses to implement this originates
24480 in the IA-64 processor-specific ABI, but has since been migrated
24481 to other processors as well. It requires significant support from
24482 the linker (@command{ld}), dynamic linker (@command{ld.so}), and
24483 system libraries (@file{libc.so} and @file{libpthread.so}), so it
24484 is not available everywhere.
24486 At the user level, the extension is visible with a new storage
24487 class keyword: @code{__thread}. For example:
24491 extern __thread struct state s;
24492 static __thread char *p;
24495 The @code{__thread} specifier may be used alone, with the @code{extern}
24496 or @code{static} specifiers, but with no other storage class specifier.
24497 When used with @code{extern} or @code{static}, @code{__thread} must appear
24498 immediately after the other storage class specifier.
24500 The @code{__thread} specifier may be applied to any global, file-scoped
24501 static, function-scoped static, or static data member of a class. It may
24502 not be applied to block-scoped automatic or non-static data member.
24504 When the address-of operator is applied to a thread-local variable, it is
24505 evaluated at run time and returns the address of the current thread's
24506 instance of that variable. An address so obtained may be used by any
24507 thread. When a thread terminates, any pointers to thread-local variables
24508 in that thread become invalid.
24510 No static initialization may refer to the address of a thread-local variable.
24512 In C++, if an initializer is present for a thread-local variable, it must
24513 be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++
24516 See @uref{https://www.akkadia.org/drepper/tls.pdf,
24517 ELF Handling For Thread-Local Storage} for a detailed explanation of
24518 the four thread-local storage addressing models, and how the runtime
24519 is expected to function.
24522 * C99 Thread-Local Edits::
24523 * C++98 Thread-Local Edits::
24526 @node C99 Thread-Local Edits
24527 @subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage
24529 The following are a set of changes to ISO/IEC 9899:1999 (aka C99)
24530 that document the exact semantics of the language extension.
24534 @cite{5.1.2 Execution environments}
24536 Add new text after paragraph 1
24539 Within either execution environment, a @dfn{thread} is a flow of
24540 control within a program. It is implementation defined whether
24541 or not there may be more than one thread associated with a program.
24542 It is implementation defined how threads beyond the first are
24543 created, the name and type of the function called at thread
24544 startup, and how threads may be terminated. However, objects
24545 with thread storage duration shall be initialized before thread
24550 @cite{6.2.4 Storage durations of objects}
24552 Add new text before paragraph 3
24555 An object whose identifier is declared with the storage-class
24556 specifier @w{@code{__thread}} has @dfn{thread storage duration}.
24557 Its lifetime is the entire execution of the thread, and its
24558 stored value is initialized only once, prior to thread startup.
24562 @cite{6.4.1 Keywords}
24564 Add @code{__thread}.
24567 @cite{6.7.1 Storage-class specifiers}
24569 Add @code{__thread} to the list of storage class specifiers in
24572 Change paragraph 2 to
24575 With the exception of @code{__thread}, at most one storage-class
24576 specifier may be given [@dots{}]. The @code{__thread} specifier may
24577 be used alone, or immediately following @code{extern} or
24581 Add new text after paragraph 6
24584 The declaration of an identifier for a variable that has
24585 block scope that specifies @code{__thread} shall also
24586 specify either @code{extern} or @code{static}.
24588 The @code{__thread} specifier shall be used only with
24593 @node C++98 Thread-Local Edits
24594 @subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage
24596 The following are a set of changes to ISO/IEC 14882:1998 (aka C++98)
24597 that document the exact semantics of the language extension.
24601 @b{[intro.execution]}
24603 New text after paragraph 4
24606 A @dfn{thread} is a flow of control within the abstract machine.
24607 It is implementation defined whether or not there may be more than
24611 New text after paragraph 7
24614 It is unspecified whether additional action must be taken to
24615 ensure when and whether side effects are visible to other threads.
24621 Add @code{__thread}.
24624 @b{[basic.start.main]}
24626 Add after paragraph 5
24629 The thread that begins execution at the @code{main} function is called
24630 the @dfn{main thread}. It is implementation defined how functions
24631 beginning threads other than the main thread are designated or typed.
24632 A function so designated, as well as the @code{main} function, is called
24633 a @dfn{thread startup function}. It is implementation defined what
24634 happens if a thread startup function returns. It is implementation
24635 defined what happens to other threads when any thread calls @code{exit}.
24639 @b{[basic.start.init]}
24641 Add after paragraph 4
24644 The storage for an object of thread storage duration shall be
24645 statically initialized before the first statement of the thread startup
24646 function. An object of thread storage duration shall not require
24647 dynamic initialization.
24651 @b{[basic.start.term]}
24653 Add after paragraph 3
24656 The type of an object with thread storage duration shall not have a
24657 non-trivial destructor, nor shall it be an array type whose elements
24658 (directly or indirectly) have non-trivial destructors.
24664 Add ``thread storage duration'' to the list in paragraph 1.
24669 Thread, static, and automatic storage durations are associated with
24670 objects introduced by declarations [@dots{}].
24673 Add @code{__thread} to the list of specifiers in paragraph 3.
24676 @b{[basic.stc.thread]}
24678 New section before @b{[basic.stc.static]}
24681 The keyword @code{__thread} applied to a non-local object gives the
24682 object thread storage duration.
24684 A local variable or class data member declared both @code{static}
24685 and @code{__thread} gives the variable or member thread storage
24690 @b{[basic.stc.static]}
24695 All objects that have neither thread storage duration, dynamic
24696 storage duration nor are local [@dots{}].
24702 Add @code{__thread} to the list in paragraph 1.
24707 With the exception of @code{__thread}, at most one
24708 @var{storage-class-specifier} shall appear in a given
24709 @var{decl-specifier-seq}. The @code{__thread} specifier may
24710 be used alone, or immediately following the @code{extern} or
24711 @code{static} specifiers. [@dots{}]
24714 Add after paragraph 5
24717 The @code{__thread} specifier can be applied only to the names of objects
24718 and to anonymous unions.
24724 Add after paragraph 6
24727 Non-@code{static} members shall not be @code{__thread}.
24731 @node Binary constants
24732 @section Binary Constants using the @samp{0b} Prefix
24733 @cindex Binary constants using the @samp{0b} prefix
24735 Integer constants can be written as binary constants, consisting of a
24736 sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
24737 @samp{0B}. This is particularly useful in environments that operate a
24738 lot on the bit level (like microcontrollers).
24740 The following statements are identical:
24749 The type of these constants follows the same rules as for octal or
24750 hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
24753 @node C++ Extensions
24754 @chapter Extensions to the C++ Language
24755 @cindex extensions, C++ language
24756 @cindex C++ language extensions
24758 The GNU compiler provides these extensions to the C++ language (and you
24759 can also use most of the C language extensions in your C++ programs). If you
24760 want to write code that checks whether these features are available, you can
24761 test for the GNU compiler the same way as for C programs: check for a
24762 predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to
24763 test specifically for GNU C++ (@pxref{Common Predefined Macros,,
24764 Predefined Macros,cpp,The GNU C Preprocessor}).
24767 * C++ Volatiles:: What constitutes an access to a volatile object.
24768 * Restricted Pointers:: C99 restricted pointers and references.
24769 * Vague Linkage:: Where G++ puts inlines, vtables and such.
24770 * C++ Interface:: You can use a single C++ header file for both
24771 declarations and definitions.
24772 * Template Instantiation:: Methods for ensuring that exactly one copy of
24773 each needed template instantiation is emitted.
24774 * Bound member functions:: You can extract a function pointer to the
24775 method denoted by a @samp{->*} or @samp{.*} expression.
24776 * C++ Attributes:: Variable, function, and type attributes for C++ only.
24777 * Function Multiversioning:: Declaring multiple function versions.
24778 * Type Traits:: Compiler support for type traits.
24779 * C++ Concepts:: Improved support for generic programming.
24780 * Deprecated Features:: Things will disappear from G++.
24781 * Backwards Compatibility:: Compatibilities with earlier definitions of C++.
24784 @node C++ Volatiles
24785 @section When is a Volatile C++ Object Accessed?
24786 @cindex accessing volatiles
24787 @cindex volatile read
24788 @cindex volatile write
24789 @cindex volatile access
24791 The C++ standard differs from the C standard in its treatment of
24792 volatile objects. It fails to specify what constitutes a volatile
24793 access, except to say that C++ should behave in a similar manner to C
24794 with respect to volatiles, where possible. However, the different
24795 lvalueness of expressions between C and C++ complicate the behavior.
24796 G++ behaves the same as GCC for volatile access, @xref{C
24797 Extensions,,Volatiles}, for a description of GCC's behavior.
24799 The C and C++ language specifications differ when an object is
24800 accessed in a void context:
24803 volatile int *src = @var{somevalue};
24807 The C++ standard specifies that such expressions do not undergo lvalue
24808 to rvalue conversion, and that the type of the dereferenced object may
24809 be incomplete. The C++ standard does not specify explicitly that it
24810 is lvalue to rvalue conversion that is responsible for causing an
24811 access. There is reason to believe that it is, because otherwise
24812 certain simple expressions become undefined. However, because it
24813 would surprise most programmers, G++ treats dereferencing a pointer to
24814 volatile object of complete type as GCC would do for an equivalent
24815 type in C@. When the object has incomplete type, G++ issues a
24816 warning; if you wish to force an error, you must force a conversion to
24817 rvalue with, for instance, a static cast.
24819 When using a reference to volatile, G++ does not treat equivalent
24820 expressions as accesses to volatiles, but instead issues a warning that
24821 no volatile is accessed. The rationale for this is that otherwise it
24822 becomes difficult to determine where volatile access occur, and not
24823 possible to ignore the return value from functions returning volatile
24824 references. Again, if you wish to force a read, cast the reference to
24827 G++ implements the same behavior as GCC does when assigning to a
24828 volatile object---there is no reread of the assigned-to object, the
24829 assigned rvalue is reused. Note that in C++ assignment expressions
24830 are lvalues, and if used as an lvalue, the volatile object is
24831 referred to. For instance, @var{vref} refers to @var{vobj}, as
24832 expected, in the following example:
24836 volatile int &vref = vobj = @var{something};
24839 @node Restricted Pointers
24840 @section Restricting Pointer Aliasing
24841 @cindex restricted pointers
24842 @cindex restricted references
24843 @cindex restricted this pointer
24845 As with the C front end, G++ understands the C99 feature of restricted pointers,
24846 specified with the @code{__restrict__}, or @code{__restrict} type
24847 qualifier. Because you cannot compile C++ by specifying the @option{-std=c99}
24848 language flag, @code{restrict} is not a keyword in C++.
24850 In addition to allowing restricted pointers, you can specify restricted
24851 references, which indicate that the reference is not aliased in the local
24855 void fn (int *__restrict__ rptr, int &__restrict__ rref)
24862 In the body of @code{fn}, @var{rptr} points to an unaliased integer and
24863 @var{rref} refers to a (different) unaliased integer.
24865 You may also specify whether a member function's @var{this} pointer is
24866 unaliased by using @code{__restrict__} as a member function qualifier.
24869 void T::fn () __restrict__
24876 Within the body of @code{T::fn}, @var{this} has the effective
24877 definition @code{T *__restrict__ const this}. Notice that the
24878 interpretation of a @code{__restrict__} member function qualifier is
24879 different to that of @code{const} or @code{volatile} qualifier, in that it
24880 is applied to the pointer rather than the object. This is consistent with
24881 other compilers that implement restricted pointers.
24883 As with all outermost parameter qualifiers, @code{__restrict__} is
24884 ignored in function definition matching. This means you only need to
24885 specify @code{__restrict__} in a function definition, rather than
24886 in a function prototype as well.
24888 @node Vague Linkage
24889 @section Vague Linkage
24890 @cindex vague linkage
24892 There are several constructs in C++ that require space in the object
24893 file but are not clearly tied to a single translation unit. We say that
24894 these constructs have ``vague linkage''. Typically such constructs are
24895 emitted wherever they are needed, though sometimes we can be more
24899 @item Inline Functions
24900 Inline functions are typically defined in a header file which can be
24901 included in many different compilations. Hopefully they can usually be
24902 inlined, but sometimes an out-of-line copy is necessary, if the address
24903 of the function is taken or if inlining fails. In general, we emit an
24904 out-of-line copy in all translation units where one is needed. As an
24905 exception, we only emit inline virtual functions with the vtable, since
24906 it always requires a copy.
24908 Local static variables and string constants used in an inline function
24909 are also considered to have vague linkage, since they must be shared
24910 between all inlined and out-of-line instances of the function.
24914 C++ virtual functions are implemented in most compilers using a lookup
24915 table, known as a vtable. The vtable contains pointers to the virtual
24916 functions provided by a class, and each object of the class contains a
24917 pointer to its vtable (or vtables, in some multiple-inheritance
24918 situations). If the class declares any non-inline, non-pure virtual
24919 functions, the first one is chosen as the ``key method'' for the class,
24920 and the vtable is only emitted in the translation unit where the key
24923 @emph{Note:} If the chosen key method is later defined as inline, the
24924 vtable is still emitted in every translation unit that defines it.
24925 Make sure that any inline virtuals are declared inline in the class
24926 body, even if they are not defined there.
24928 @item @code{type_info} objects
24929 @cindex @code{type_info}
24931 C++ requires information about types to be written out in order to
24932 implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
24933 For polymorphic classes (classes with virtual functions), the @samp{type_info}
24934 object is written out along with the vtable so that @samp{dynamic_cast}
24935 can determine the dynamic type of a class object at run time. For all
24936 other types, we write out the @samp{type_info} object when it is used: when
24937 applying @samp{typeid} to an expression, throwing an object, or
24938 referring to a type in a catch clause or exception specification.
24940 @item Template Instantiations
24941 Most everything in this section also applies to template instantiations,
24942 but there are other options as well.
24943 @xref{Template Instantiation,,Where's the Template?}.
24947 When used with GNU ld version 2.8 or later on an ELF system such as
24948 GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of
24949 these constructs will be discarded at link time. This is known as
24952 On targets that don't support COMDAT, but do support weak symbols, GCC
24953 uses them. This way one copy overrides all the others, but
24954 the unused copies still take up space in the executable.
24956 For targets that do not support either COMDAT or weak symbols,
24957 most entities with vague linkage are emitted as local symbols to
24958 avoid duplicate definition errors from the linker. This does not happen
24959 for local statics in inlines, however, as having multiple copies
24960 almost certainly breaks things.
24962 @xref{C++ Interface,,Declarations and Definitions in One Header}, for
24963 another way to control placement of these constructs.
24965 @node C++ Interface
24966 @section C++ Interface and Implementation Pragmas
24968 @cindex interface and implementation headers, C++
24969 @cindex C++ interface and implementation headers
24970 @cindex pragmas, interface and implementation
24972 @code{#pragma interface} and @code{#pragma implementation} provide the
24973 user with a way of explicitly directing the compiler to emit entities
24974 with vague linkage (and debugging information) in a particular
24977 @emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2
24978 by COMDAT support and the ``key method'' heuristic
24979 mentioned in @ref{Vague Linkage}. Using them can actually cause your
24980 program to grow due to unnecessary out-of-line copies of inline
24984 @item #pragma interface
24985 @itemx #pragma interface "@var{subdir}/@var{objects}.h"
24986 @kindex #pragma interface
24987 Use this directive in @emph{header files} that define object classes, to save
24988 space in most of the object files that use those classes. Normally,
24989 local copies of certain information (backup copies of inline member
24990 functions, debugging information, and the internal tables that implement
24991 virtual functions) must be kept in each object file that includes class
24992 definitions. You can use this pragma to avoid such duplication. When a
24993 header file containing @samp{#pragma interface} is included in a
24994 compilation, this auxiliary information is not generated (unless
24995 the main input source file itself uses @samp{#pragma implementation}).
24996 Instead, the object files contain references to be resolved at link
24999 The second form of this directive is useful for the case where you have
25000 multiple headers with the same name in different directories. If you
25001 use this form, you must specify the same string to @samp{#pragma
25004 @item #pragma implementation
25005 @itemx #pragma implementation "@var{objects}.h"
25006 @kindex #pragma implementation
25007 Use this pragma in a @emph{main input file}, when you want full output from
25008 included header files to be generated (and made globally visible). The
25009 included header file, in turn, should use @samp{#pragma interface}.
25010 Backup copies of inline member functions, debugging information, and the
25011 internal tables used to implement virtual functions are all generated in
25012 implementation files.
25014 @cindex implied @code{#pragma implementation}
25015 @cindex @code{#pragma implementation}, implied
25016 @cindex naming convention, implementation headers
25017 If you use @samp{#pragma implementation} with no argument, it applies to
25018 an include file with the same basename@footnote{A file's @dfn{basename}
25019 is the name stripped of all leading path information and of trailing
25020 suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source
25021 file. For example, in @file{allclass.cc}, giving just
25022 @samp{#pragma implementation}
25023 by itself is equivalent to @samp{#pragma implementation "allclass.h"}.
25025 Use the string argument if you want a single implementation file to
25026 include code from multiple header files. (You must also use
25027 @samp{#include} to include the header file; @samp{#pragma
25028 implementation} only specifies how to use the file---it doesn't actually
25031 There is no way to split up the contents of a single header file into
25032 multiple implementation files.
25035 @cindex inlining and C++ pragmas
25036 @cindex C++ pragmas, effect on inlining
25037 @cindex pragmas in C++, effect on inlining
25038 @samp{#pragma implementation} and @samp{#pragma interface} also have an
25039 effect on function inlining.
25041 If you define a class in a header file marked with @samp{#pragma
25042 interface}, the effect on an inline function defined in that class is
25043 similar to an explicit @code{extern} declaration---the compiler emits
25044 no code at all to define an independent version of the function. Its
25045 definition is used only for inlining with its callers.
25047 @opindex fno-implement-inlines
25048 Conversely, when you include the same header file in a main source file
25049 that declares it as @samp{#pragma implementation}, the compiler emits
25050 code for the function itself; this defines a version of the function
25051 that can be found via pointers (or by callers compiled without
25052 inlining). If all calls to the function can be inlined, you can avoid
25053 emitting the function by compiling with @option{-fno-implement-inlines}.
25054 If any calls are not inlined, you will get linker errors.
25056 @node Template Instantiation
25057 @section Where's the Template?
25058 @cindex template instantiation
25060 C++ templates were the first language feature to require more
25061 intelligence from the environment than was traditionally found on a UNIX
25062 system. Somehow the compiler and linker have to make sure that each
25063 template instance occurs exactly once in the executable if it is needed,
25064 and not at all otherwise. There are two basic approaches to this
25065 problem, which are referred to as the Borland model and the Cfront model.
25068 @item Borland model
25069 Borland C++ solved the template instantiation problem by adding the code
25070 equivalent of common blocks to their linker; the compiler emits template
25071 instances in each translation unit that uses them, and the linker
25072 collapses them together. The advantage of this model is that the linker
25073 only has to consider the object files themselves; there is no external
25074 complexity to worry about. The disadvantage is that compilation time
25075 is increased because the template code is being compiled repeatedly.
25076 Code written for this model tends to include definitions of all
25077 templates in the header file, since they must be seen to be
25081 The AT&T C++ translator, Cfront, solved the template instantiation
25082 problem by creating the notion of a template repository, an
25083 automatically maintained place where template instances are stored. A
25084 more modern version of the repository works as follows: As individual
25085 object files are built, the compiler places any template definitions and
25086 instantiations encountered in the repository. At link time, the link
25087 wrapper adds in the objects in the repository and compiles any needed
25088 instances that were not previously emitted. The advantages of this
25089 model are more optimal compilation speed and the ability to use the
25090 system linker; to implement the Borland model a compiler vendor also
25091 needs to replace the linker. The disadvantages are vastly increased
25092 complexity, and thus potential for error; for some code this can be
25093 just as transparent, but in practice it can been very difficult to build
25094 multiple programs in one directory and one program in multiple
25095 directories. Code written for this model tends to separate definitions
25096 of non-inline member templates into a separate file, which should be
25097 compiled separately.
25100 G++ implements the Borland model on targets where the linker supports it,
25101 including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows.
25102 Otherwise G++ implements neither automatic model.
25104 You have the following options for dealing with template instantiations:
25108 Do nothing. Code written for the Borland model works fine, but
25109 each translation unit contains instances of each of the templates it
25110 uses. The duplicate instances will be discarded by the linker, but in
25111 a large program, this can lead to an unacceptable amount of code
25112 duplication in object files or shared libraries.
25114 Duplicate instances of a template can be avoided by defining an explicit
25115 instantiation in one object file, and preventing the compiler from doing
25116 implicit instantiations in any other object files by using an explicit
25117 instantiation declaration, using the @code{extern template} syntax:
25120 extern template int max (int, int);
25123 This syntax is defined in the C++ 2011 standard, but has been supported by
25124 G++ and other compilers since well before 2011.
25126 Explicit instantiations can be used for the largest or most frequently
25127 duplicated instances, without having to know exactly which other instances
25128 are used in the rest of the program. You can scatter the explicit
25129 instantiations throughout your program, perhaps putting them in the
25130 translation units where the instances are used or the translation units
25131 that define the templates themselves; you can put all of the explicit
25132 instantiations you need into one big file; or you can create small files
25139 template class Foo<int>;
25140 template ostream& operator <<
25141 (ostream&, const Foo<int>&);
25145 for each of the instances you need, and create a template instantiation
25146 library from those.
25148 This is the simplest option, but also offers flexibility and
25149 fine-grained control when necessary. It is also the most portable
25150 alternative and programs using this approach will work with most modern
25154 @opindex fno-implicit-templates
25155 Compile your code with @option{-fno-implicit-templates} to disable the
25156 implicit generation of template instances, and explicitly instantiate
25157 all the ones you use. This approach requires more knowledge of exactly
25158 which instances you need than do the others, but it's less
25159 mysterious and allows greater control if you want to ensure that only
25160 the intended instances are used.
25162 If you are using Cfront-model code, you can probably get away with not
25163 using @option{-fno-implicit-templates} when compiling files that don't
25164 @samp{#include} the member template definitions.
25166 If you use one big file to do the instantiations, you may want to
25167 compile it without @option{-fno-implicit-templates} so you get all of the
25168 instances required by your explicit instantiations (but not by any
25169 other files) without having to specify them as well.
25171 In addition to forward declaration of explicit instantiations
25172 (with @code{extern}), G++ has extended the template instantiation
25173 syntax to support instantiation of the compiler support data for a
25174 template class (i.e.@: the vtable) without instantiating any of its
25175 members (with @code{inline}), and instantiation of only the static data
25176 members of a template class, without the support data or member
25177 functions (with @code{static}):
25180 inline template class Foo<int>;
25181 static template class Foo<int>;
25185 @node Bound member functions
25186 @section Extracting the Function Pointer from a Bound Pointer to Member Function
25188 @cindex pointer to member function
25189 @cindex bound pointer to member function
25191 In C++, pointer to member functions (PMFs) are implemented using a wide
25192 pointer of sorts to handle all the possible call mechanisms; the PMF
25193 needs to store information about how to adjust the @samp{this} pointer,
25194 and if the function pointed to is virtual, where to find the vtable, and
25195 where in the vtable to look for the member function. If you are using
25196 PMFs in an inner loop, you should really reconsider that decision. If
25197 that is not an option, you can extract the pointer to the function that
25198 would be called for a given object/PMF pair and call it directly inside
25199 the inner loop, to save a bit of time.
25201 Note that you still pay the penalty for the call through a
25202 function pointer; on most modern architectures, such a call defeats the
25203 branch prediction features of the CPU@. This is also true of normal
25204 virtual function calls.
25206 The syntax for this extension is
25210 extern int (A::*fp)();
25211 typedef int (*fptr)(A *);
25213 fptr p = (fptr)(a.*fp);
25216 For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}),
25217 no object is needed to obtain the address of the function. They can be
25218 converted to function pointers directly:
25221 fptr p1 = (fptr)(&A::foo);
25224 @opindex Wno-pmf-conversions
25225 You must specify @option{-Wno-pmf-conversions} to use this extension.
25227 @node C++ Attributes
25228 @section C++-Specific Variable, Function, and Type Attributes
25230 Some attributes only make sense for C++ programs.
25233 @item abi_tag ("@var{tag}", ...)
25234 @cindex @code{abi_tag} function attribute
25235 @cindex @code{abi_tag} variable attribute
25236 @cindex @code{abi_tag} type attribute
25237 The @code{abi_tag} attribute can be applied to a function, variable, or class
25238 declaration. It modifies the mangled name of the entity to
25239 incorporate the tag name, in order to distinguish the function or
25240 class from an earlier version with a different ABI; perhaps the class
25241 has changed size, or the function has a different return type that is
25242 not encoded in the mangled name.
25244 The attribute can also be applied to an inline namespace, but does not
25245 affect the mangled name of the namespace; in this case it is only used
25246 for @option{-Wabi-tag} warnings and automatic tagging of functions and
25247 variables. Tagging inline namespaces is generally preferable to
25248 tagging individual declarations, but the latter is sometimes
25249 necessary, such as when only certain members of a class need to be
25252 The argument can be a list of strings of arbitrary length. The
25253 strings are sorted on output, so the order of the list is
25256 A redeclaration of an entity must not add new ABI tags,
25257 since doing so would change the mangled name.
25259 The ABI tags apply to a name, so all instantiations and
25260 specializations of a template have the same tags. The attribute will
25261 be ignored if applied to an explicit specialization or instantiation.
25263 The @option{-Wabi-tag} flag enables a warning about a class which does
25264 not have all the ABI tags used by its subobjects and virtual functions; for users with code
25265 that needs to coexist with an earlier ABI, using this option can help
25266 to find all affected types that need to be tagged.
25268 When a type involving an ABI tag is used as the type of a variable or
25269 return type of a function where that tag is not already present in the
25270 signature of the function, the tag is automatically applied to the
25271 variable or function. @option{-Wabi-tag} also warns about this
25272 situation; this warning can be avoided by explicitly tagging the
25273 variable or function or moving it into a tagged inline namespace.
25275 @item init_priority (@var{priority})
25276 @cindex @code{init_priority} variable attribute
25278 In Standard C++, objects defined at namespace scope are guaranteed to be
25279 initialized in an order in strict accordance with that of their definitions
25280 @emph{in a given translation unit}. No guarantee is made for initializations
25281 across translation units. However, GNU C++ allows users to control the
25282 order of initialization of objects defined at namespace scope with the
25283 @code{init_priority} attribute by specifying a relative @var{priority},
25284 a constant integral expression currently bounded between 101 and 65535
25285 inclusive. Lower numbers indicate a higher priority.
25287 In the following example, @code{A} would normally be created before
25288 @code{B}, but the @code{init_priority} attribute reverses that order:
25291 Some_Class A __attribute__ ((init_priority (2000)));
25292 Some_Class B __attribute__ ((init_priority (543)));
25296 Note that the particular values of @var{priority} do not matter; only their
25300 @cindex @code{warn_unused} type attribute
25302 For C++ types with non-trivial constructors and/or destructors it is
25303 impossible for the compiler to determine whether a variable of this
25304 type is truly unused if it is not referenced. This type attribute
25305 informs the compiler that variables of this type should be warned
25306 about if they appear to be unused, just like variables of fundamental
25309 This attribute is appropriate for types which just represent a value,
25310 such as @code{std::string}; it is not appropriate for types which
25311 control a resource, such as @code{std::lock_guard}.
25313 This attribute is also accepted in C, but it is unnecessary because C
25314 does not have constructors or destructors.
25318 @node Function Multiversioning
25319 @section Function Multiversioning
25320 @cindex function versions
25322 With the GNU C++ front end, for x86 targets, you may specify multiple
25323 versions of a function, where each function is specialized for a
25324 specific target feature. At runtime, the appropriate version of the
25325 function is automatically executed depending on the characteristics of
25326 the execution platform. Here is an example.
25329 __attribute__ ((target ("default")))
25332 // The default version of foo.
25336 __attribute__ ((target ("sse4.2")))
25339 // foo version for SSE4.2
25343 __attribute__ ((target ("arch=atom")))
25346 // foo version for the Intel ATOM processor
25350 __attribute__ ((target ("arch=amdfam10")))
25353 // foo version for the AMD Family 0x10 processors.
25360 assert ((*p) () == foo ());
25365 In the above example, four versions of function foo are created. The
25366 first version of foo with the target attribute "default" is the default
25367 version. This version gets executed when no other target specific
25368 version qualifies for execution on a particular platform. A new version
25369 of foo is created by using the same function signature but with a
25370 different target string. Function foo is called or a pointer to it is
25371 taken just like a regular function. GCC takes care of doing the
25372 dispatching to call the right version at runtime. Refer to the
25373 @uref{http://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
25374 Function Multiversioning} for more details.
25377 @section Type Traits
25379 The C++ front end implements syntactic extensions that allow
25380 compile-time determination of
25381 various characteristics of a type (or of a
25385 @item __has_nothrow_assign (type)
25386 If @code{type} is @code{const}-qualified or is a reference type then
25387 the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)}
25388 is @code{true} then the trait is @code{true}, else if @code{type} is
25389 a cv-qualified class or union type with copy assignment operators that are
25390 known not to throw an exception then the trait is @code{true}, else it is
25392 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25393 @code{void}, or an array of unknown bound.
25395 @item __has_nothrow_copy (type)
25396 If @code{__has_trivial_copy (type)} is @code{true} then the trait is
25397 @code{true}, else if @code{type} is a cv-qualified class or union type
25398 with copy constructors that are known not to throw an exception then
25399 the trait is @code{true}, else it is @code{false}.
25400 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25401 @code{void}, or an array of unknown bound.
25403 @item __has_nothrow_constructor (type)
25404 If @code{__has_trivial_constructor (type)} is @code{true} then the trait
25405 is @code{true}, else if @code{type} is a cv class or union type (or array
25406 thereof) with a default constructor that is known not to throw an
25407 exception then the trait is @code{true}, else it is @code{false}.
25408 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25409 @code{void}, or an array of unknown bound.
25411 @item __has_trivial_assign (type)
25412 If @code{type} is @code{const}- qualified or is a reference type then
25413 the trait is @code{false}. Otherwise if @code{__is_pod (type)} is
25414 @code{true} then the trait is @code{true}, else if @code{type} is
25415 a cv-qualified class or union type with a trivial copy assignment
25416 ([class.copy]) then the trait is @code{true}, else it is @code{false}.
25417 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25418 @code{void}, or an array of unknown bound.
25420 @item __has_trivial_copy (type)
25421 If @code{__is_pod (type)} is @code{true} or @code{type} is a reference
25422 type then the trait is @code{true}, else if @code{type} is a cv class
25423 or union type with a trivial copy constructor ([class.copy]) then the trait
25424 is @code{true}, else it is @code{false}. Requires: @code{type} shall be
25425 a complete type, (possibly cv-qualified) @code{void}, or an array of unknown
25428 @item __has_trivial_constructor (type)
25429 If @code{__is_pod (type)} is @code{true} then the trait is @code{true},
25430 else if @code{type} is a cv-qualified class or union type (or array thereof)
25431 with a trivial default constructor ([class.ctor]) then the trait is @code{true},
25432 else it is @code{false}.
25433 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25434 @code{void}, or an array of unknown bound.
25436 @item __has_trivial_destructor (type)
25437 If @code{__is_pod (type)} is @code{true} or @code{type} is a reference type
25438 then the trait is @code{true}, else if @code{type} is a cv class or union
25439 type (or array thereof) with a trivial destructor ([class.dtor]) then
25440 the trait is @code{true}, else it is @code{false}.
25441 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25442 @code{void}, or an array of unknown bound.
25444 @item __has_virtual_destructor (type)
25445 If @code{type} is a class type with a virtual destructor
25446 ([class.dtor]) then the trait is @code{true}, else it is @code{false}.
25447 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25448 @code{void}, or an array of unknown bound.
25450 @item __is_abstract (type)
25451 If @code{type} is an abstract class ([class.abstract]) then the trait
25452 is @code{true}, else it is @code{false}.
25453 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25454 @code{void}, or an array of unknown bound.
25456 @item __is_base_of (base_type, derived_type)
25457 If @code{base_type} is a base class of @code{derived_type}
25458 ([class.derived]) then the trait is @code{true}, otherwise it is @code{false}.
25459 Top-level cv-qualifications of @code{base_type} and
25460 @code{derived_type} are ignored. For the purposes of this trait, a
25461 class type is considered is own base.
25462 Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)}
25463 are @code{true} and @code{base_type} and @code{derived_type} are not the same
25464 type (disregarding cv-qualifiers), @code{derived_type} shall be a complete
25465 type. A diagnostic is produced if this requirement is not met.
25467 @item __is_class (type)
25468 If @code{type} is a cv-qualified class type, and not a union type
25469 ([basic.compound]) the trait is @code{true}, else it is @code{false}.
25471 @item __is_empty (type)
25472 If @code{__is_class (type)} is @code{false} then the trait is @code{false}.
25473 Otherwise @code{type} is considered empty if and only if: @code{type}
25474 has no non-static data members, or all non-static data members, if
25475 any, are bit-fields of length 0, and @code{type} has no virtual
25476 members, and @code{type} has no virtual base classes, and @code{type}
25477 has no base classes @code{base_type} for which
25478 @code{__is_empty (base_type)} is @code{false}.
25479 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25480 @code{void}, or an array of unknown bound.
25482 @item __is_enum (type)
25483 If @code{type} is a cv enumeration type ([basic.compound]) the trait is
25484 @code{true}, else it is @code{false}.
25486 @item __is_literal_type (type)
25487 If @code{type} is a literal type ([basic.types]) the trait is
25488 @code{true}, else it is @code{false}.
25489 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25490 @code{void}, or an array of unknown bound.
25492 @item __is_pod (type)
25493 If @code{type} is a cv POD type ([basic.types]) then the trait is @code{true},
25494 else it is @code{false}.
25495 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25496 @code{void}, or an array of unknown bound.
25498 @item __is_polymorphic (type)
25499 If @code{type} is a polymorphic class ([class.virtual]) then the trait
25500 is @code{true}, else it is @code{false}.
25501 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25502 @code{void}, or an array of unknown bound.
25504 @item __is_standard_layout (type)
25505 If @code{type} is a standard-layout type ([basic.types]) the trait is
25506 @code{true}, else it is @code{false}.
25507 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25508 @code{void}, or an array of unknown bound.
25510 @item __is_trivial (type)
25511 If @code{type} is a trivial type ([basic.types]) the trait is
25512 @code{true}, else it is @code{false}.
25513 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
25514 @code{void}, or an array of unknown bound.
25516 @item __is_union (type)
25517 If @code{type} is a cv union type ([basic.compound]) the trait is
25518 @code{true}, else it is @code{false}.
25520 @item __underlying_type (type)
25521 The underlying type of @code{type}.
25522 Requires: @code{type} shall be an enumeration type ([dcl.enum]).
25524 @item __integer_pack (length)
25525 When used as the pattern of a pack expansion within a template
25526 definition, expands to a template argument pack containing integers
25527 from @code{0} to @code{length-1}. This is provided for efficient
25528 implementation of @code{std::make_integer_sequence}.
25534 @section C++ Concepts
25536 C++ concepts provide much-improved support for generic programming. In
25537 particular, they allow the specification of constraints on template arguments.
25538 The constraints are used to extend the usual overloading and partial
25539 specialization capabilities of the language, allowing generic data structures
25540 and algorithms to be ``refined'' based on their properties rather than their
25543 The following keywords are reserved for concepts.
25547 States an expression as an assumption, and if possible, verifies that the
25548 assumption is valid. For example, @code{assume(n > 0)}.
25551 Introduces an axiom definition. Axioms introduce requirements on values.
25554 Introduces a universally quantified object in an axiom. For example,
25555 @code{forall (int n) n + 0 == n}).
25558 Introduces a concept definition. Concepts are sets of syntactic and semantic
25559 requirements on types and their values.
25562 Introduces constraints on template arguments or requirements for a member
25563 function of a class template.
25567 The front end also exposes a number of internal mechanism that can be used
25568 to simplify the writing of type traits. Note that some of these traits are
25569 likely to be removed in the future.
25572 @item __is_same (type1, type2)
25573 A binary type trait: @code{true} whenever the type arguments are the same.
25578 @node Deprecated Features
25579 @section Deprecated Features
25581 In the past, the GNU C++ compiler was extended to experiment with new
25582 features, at a time when the C++ language was still evolving. Now that
25583 the C++ standard is complete, some of those features are superseded by
25584 superior alternatives. Using the old features might cause a warning in
25585 some cases that the feature will be dropped in the future. In other
25586 cases, the feature might be gone already.
25588 G++ allows a virtual function returning @samp{void *} to be overridden
25589 by one returning a different pointer type. This extension to the
25590 covariant return type rules is now deprecated and will be removed from a
25593 The use of default arguments in function pointers, function typedefs
25594 and other places where they are not permitted by the standard is
25595 deprecated and will be removed from a future version of G++.
25597 G++ allows floating-point literals to appear in integral constant expressions,
25598 e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} }
25599 This extension is deprecated and will be removed from a future version.
25601 G++ allows static data members of const floating-point type to be declared
25602 with an initializer in a class definition. The standard only allows
25603 initializers for static members of const integral types and const
25604 enumeration types so this extension has been deprecated and will be removed
25605 from a future version.
25607 G++ allows attributes to follow a parenthesized direct initializer,
25608 e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension
25609 has been ignored since G++ 3.3 and is deprecated.
25611 G++ allows anonymous structs and unions to have members that are not
25612 public non-static data members (i.e.@: fields). These extensions are
25615 @node Backwards Compatibility
25616 @section Backwards Compatibility
25617 @cindex Backwards Compatibility
25618 @cindex ARM [Annotated C++ Reference Manual]
25620 Now that there is a definitive ISO standard C++, G++ has a specification
25621 to adhere to. The C++ language evolved over time, and features that
25622 used to be acceptable in previous drafts of the standard, such as the ARM
25623 [Annotated C++ Reference Manual], are no longer accepted. In order to allow
25624 compilation of C++ written to such drafts, G++ contains some backwards
25625 compatibilities. @emph{All such backwards compatibility features are
25626 liable to disappear in future versions of G++.} They should be considered
25627 deprecated. @xref{Deprecated Features}.
25631 @item Implicit C language
25632 Old C system header files did not contain an @code{extern "C" @{@dots{}@}}
25633 scope to set the language. On such systems, all system header files are
25634 implicitly scoped inside a C language scope. Such headers must
25635 correctly prototype function argument types, there is no leeway for
25636 @code{()} to indicate an unspecified set of arguments.
25640 @c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd
25641 @c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr