1 c Copyright (C) 1988-2019 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, SPU, 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 SPU Named Address Spaces
1577 @cindex @code{__ea} SPU Named Address Spaces
1579 On the SPU target variables may be declared as
1580 belonging to another address space by qualifying the type with the
1581 @code{__ea} address space identifier:
1588 The compiler generates special code to access the variable @code{i}.
1589 It may use runtime library
1590 support, or generate special machine instructions to access that address
1593 @subsection x86 Named Address Spaces
1594 @cindex x86 named address spaces
1596 On the x86 target, variables may be declared as being relative
1597 to the @code{%fs} or @code{%gs} segments.
1602 @cindex @code{__seg_fs} x86 named address space
1603 @cindex @code{__seg_gs} x86 named address space
1604 The object is accessed with the respective segment override prefix.
1606 The respective segment base must be set via some method specific to
1607 the operating system. Rather than require an expensive system call
1608 to retrieve the segment base, these address spaces are not considered
1609 to be subspaces of the generic (flat) address space. This means that
1610 explicit casts are required to convert pointers between these address
1611 spaces and the generic address space. In practice the application
1612 should cast to @code{uintptr_t} and apply the segment base offset
1613 that it installed previously.
1615 The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are
1616 defined when these address spaces are supported.
1620 @section Arrays of Length Zero
1621 @cindex arrays of length zero
1622 @cindex zero-length arrays
1623 @cindex length-zero arrays
1624 @cindex flexible array members
1626 Declaring zero-length arrays is allowed in GNU C as an extension.
1627 A zero-length array can be useful as the last element of a structure
1628 that is really a header for a variable-length object:
1636 struct line *thisline = (struct line *)
1637 malloc (sizeof (struct line) + this_length);
1638 thisline->length = this_length;
1641 Although the size of a zero-length array is zero, an array member of
1642 this kind may increase the size of the enclosing type as a result of tail
1643 padding. The offset of a zero-length array member from the beginning
1644 of the enclosing structure is the same as the offset of an array with
1645 one or more elements of the same type. The alignment of a zero-length
1646 array is the same as the alignment of its elements.
1648 Declaring zero-length arrays in other contexts, including as interior
1649 members of structure objects or as non-member objects, is discouraged.
1650 Accessing elements of zero-length arrays declared in such contexts is
1651 undefined and may be diagnosed.
1653 In the absence of the zero-length array extension, in ISO C90
1654 the @code{contents} array in the example above would typically be declared
1655 to have a single element. Unlike a zero-length array which only contributes
1656 to the size of the enclosing structure for the purposes of alignment,
1657 a one-element array always occupies at least as much space as a single
1658 object of the type. Although using one-element arrays this way is
1659 discouraged, GCC handles accesses to trailing one-element array members
1660 analogously to zero-length arrays.
1662 The preferred mechanism to declare variable-length types like
1663 @code{struct line} above is the ISO C99 @dfn{flexible array member},
1664 with slightly different syntax and semantics:
1668 Flexible array members are written as @code{contents[]} without
1672 Flexible array members have incomplete type, and so the @code{sizeof}
1673 operator may not be applied. As a quirk of the original implementation
1674 of zero-length arrays, @code{sizeof} evaluates to zero.
1677 Flexible array members may only appear as the last member of a
1678 @code{struct} that is otherwise non-empty.
1681 A structure containing a flexible array member, or a union containing
1682 such a structure (possibly recursively), may not be a member of a
1683 structure or an element of an array. (However, these uses are
1684 permitted by GCC as extensions.)
1687 Non-empty initialization of zero-length
1688 arrays is treated like any case where there are more initializer
1689 elements than the array holds, in that a suitable warning about ``excess
1690 elements in array'' is given, and the excess elements (all of them, in
1691 this case) are ignored.
1693 GCC allows static initialization of flexible array members.
1694 This is equivalent to defining a new structure containing the original
1695 structure followed by an array of sufficient size to contain the data.
1696 E.g.@: in the following, @code{f1} is constructed as if it were declared
1702 @} f1 = @{ 1, @{ 2, 3, 4 @} @};
1705 struct f1 f1; int data[3];
1706 @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
1710 The convenience of this extension is that @code{f1} has the desired
1711 type, eliminating the need to consistently refer to @code{f2.f1}.
1713 This has symmetry with normal static arrays, in that an array of
1714 unknown size is also written with @code{[]}.
1716 Of course, this extension only makes sense if the extra data comes at
1717 the end of a top-level object, as otherwise we would be overwriting
1718 data at subsequent offsets. To avoid undue complication and confusion
1719 with initialization of deeply nested arrays, we simply disallow any
1720 non-empty initialization except when the structure is the top-level
1721 object. For example:
1724 struct foo @{ int x; int y[]; @};
1725 struct bar @{ struct foo z; @};
1727 struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
1728 struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1729 struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
1730 struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1733 @node Empty Structures
1734 @section Structures with No Members
1735 @cindex empty structures
1736 @cindex zero-size structures
1738 GCC permits a C structure to have no members:
1745 The structure has size zero. In C++, empty structures are part
1746 of the language. G++ treats empty structures as if they had a single
1747 member of type @code{char}.
1749 @node Variable Length
1750 @section Arrays of Variable Length
1751 @cindex variable-length arrays
1752 @cindex arrays of variable length
1755 Variable-length automatic arrays are allowed in ISO C99, and as an
1756 extension GCC accepts them in C90 mode and in C++. These arrays are
1757 declared like any other automatic arrays, but with a length that is not
1758 a constant expression. The storage is allocated at the point of
1759 declaration and deallocated when the block scope containing the declaration
1765 concat_fopen (char *s1, char *s2, char *mode)
1767 char str[strlen (s1) + strlen (s2) + 1];
1770 return fopen (str, mode);
1774 @cindex scope of a variable length array
1775 @cindex variable-length array scope
1776 @cindex deallocating variable length arrays
1777 Jumping or breaking out of the scope of the array name deallocates the
1778 storage. Jumping into the scope is not allowed; you get an error
1781 @cindex variable-length array in a structure
1782 As an extension, GCC accepts variable-length arrays as a member of
1783 a structure or a union. For example:
1789 struct S @{ int x[n]; @};
1793 @cindex @code{alloca} vs variable-length arrays
1794 You can use the function @code{alloca} to get an effect much like
1795 variable-length arrays. The function @code{alloca} is available in
1796 many other C implementations (but not in all). On the other hand,
1797 variable-length arrays are more elegant.
1799 There are other differences between these two methods. Space allocated
1800 with @code{alloca} exists until the containing @emph{function} returns.
1801 The space for a variable-length array is deallocated as soon as the array
1802 name's scope ends, unless you also use @code{alloca} in this scope.
1804 You can also use variable-length arrays as arguments to functions:
1808 tester (int len, char data[len][len])
1814 The length of an array is computed once when the storage is allocated
1815 and is remembered for the scope of the array in case you access it with
1818 If you want to pass the array first and the length afterward, you can
1819 use a forward declaration in the parameter list---another GNU extension.
1823 tester (int len; char data[len][len], int len)
1829 @cindex parameter forward declaration
1830 The @samp{int len} before the semicolon is a @dfn{parameter forward
1831 declaration}, and it serves the purpose of making the name @code{len}
1832 known when the declaration of @code{data} is parsed.
1834 You can write any number of such parameter forward declarations in the
1835 parameter list. They can be separated by commas or semicolons, but the
1836 last one must end with a semicolon, which is followed by the ``real''
1837 parameter declarations. Each forward declaration must match a ``real''
1838 declaration in parameter name and data type. ISO C99 does not support
1839 parameter forward declarations.
1841 @node Variadic Macros
1842 @section Macros with a Variable Number of Arguments.
1843 @cindex variable number of arguments
1844 @cindex macro with variable arguments
1845 @cindex rest argument (in macro)
1846 @cindex variadic macros
1848 In the ISO C standard of 1999, a macro can be declared to accept a
1849 variable number of arguments much as a function can. The syntax for
1850 defining the macro is similar to that of a function. Here is an
1854 #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
1858 Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
1859 such a macro, it represents the zero or more tokens until the closing
1860 parenthesis that ends the invocation, including any commas. This set of
1861 tokens replaces the identifier @code{__VA_ARGS__} in the macro body
1862 wherever it appears. See the CPP manual for more information.
1864 GCC has long supported variadic macros, and used a different syntax that
1865 allowed you to give a name to the variable arguments just like any other
1866 argument. Here is an example:
1869 #define debug(format, args...) fprintf (stderr, format, args)
1873 This is in all ways equivalent to the ISO C example above, but arguably
1874 more readable and descriptive.
1876 GNU CPP has two further variadic macro extensions, and permits them to
1877 be used with either of the above forms of macro definition.
1879 In standard C, you are not allowed to leave the variable argument out
1880 entirely; but you are allowed to pass an empty argument. For example,
1881 this invocation is invalid in ISO C, because there is no comma after
1888 GNU CPP permits you to completely omit the variable arguments in this
1889 way. In the above examples, the compiler would complain, though since
1890 the expansion of the macro still has the extra comma after the format
1893 To help solve this problem, CPP behaves specially for variable arguments
1894 used with the token paste operator, @samp{##}. If instead you write
1897 #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
1901 and if the variable arguments are omitted or empty, the @samp{##}
1902 operator causes the preprocessor to remove the comma before it. If you
1903 do provide some variable arguments in your macro invocation, GNU CPP
1904 does not complain about the paste operation and instead places the
1905 variable arguments after the comma. Just like any other pasted macro
1906 argument, these arguments are not macro expanded.
1908 @node Escaped Newlines
1909 @section Slightly Looser Rules for Escaped Newlines
1910 @cindex escaped newlines
1911 @cindex newlines (escaped)
1913 The preprocessor treatment of escaped newlines is more relaxed
1914 than that specified by the C90 standard, which requires the newline
1915 to immediately follow a backslash.
1916 GCC's implementation allows whitespace in the form
1917 of spaces, horizontal and vertical tabs, and form feeds between the
1918 backslash and the subsequent newline. The preprocessor issues a
1919 warning, but treats it as a valid escaped newline and combines the two
1920 lines to form a single logical line. This works within comments and
1921 tokens, as well as between tokens. Comments are @emph{not} treated as
1922 whitespace for the purposes of this relaxation, since they have not
1923 yet been replaced with spaces.
1926 @section Non-Lvalue Arrays May Have Subscripts
1927 @cindex subscripting
1928 @cindex arrays, non-lvalue
1930 @cindex subscripting and function values
1931 In ISO C99, arrays that are not lvalues still decay to pointers, and
1932 may be subscripted, although they may not be modified or used after
1933 the next sequence point and the unary @samp{&} operator may not be
1934 applied to them. As an extension, GNU C allows such arrays to be
1935 subscripted in C90 mode, though otherwise they do not decay to
1936 pointers outside C99 mode. For example,
1937 this is valid in GNU C though not valid in C90:
1941 struct foo @{int a[4];@};
1947 return f().a[index];
1953 @section Arithmetic on @code{void}- and Function-Pointers
1954 @cindex void pointers, arithmetic
1955 @cindex void, size of pointer to
1956 @cindex function pointers, arithmetic
1957 @cindex function, size of pointer to
1959 In GNU C, addition and subtraction operations are supported on pointers to
1960 @code{void} and on pointers to functions. This is done by treating the
1961 size of a @code{void} or of a function as 1.
1963 A consequence of this is that @code{sizeof} is also allowed on @code{void}
1964 and on function types, and returns 1.
1966 @opindex Wpointer-arith
1967 The option @option{-Wpointer-arith} requests a warning if these extensions
1970 @node Variadic Pointer Args
1971 @section Pointer Arguments in Variadic Functions
1972 @cindex pointer arguments in variadic functions
1973 @cindex variadic functions, pointer arguments
1975 Standard C requires that pointer types used with @code{va_arg} in
1976 functions with variable argument lists either must be compatible with
1977 that of the actual argument, or that one type must be a pointer to
1978 @code{void} and the other a pointer to a character type. GNU C
1979 implements the POSIX XSI extension that additionally permits the use
1980 of @code{va_arg} with a pointer type to receive arguments of any other
1983 In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used
1984 to consume an argument of any pointer type.
1986 @node Pointers to Arrays
1987 @section Pointers to Arrays with Qualifiers Work as Expected
1988 @cindex pointers to arrays
1989 @cindex const qualifier
1991 In GNU C, pointers to arrays with qualifiers work similar to pointers
1992 to other qualified types. For example, a value of type @code{int (*)[5]}
1993 can be used to initialize a variable of type @code{const int (*)[5]}.
1994 These types are incompatible in ISO C because the @code{const} qualifier
1995 is formally attached to the element type of the array and not the
2000 transpose (int N, int M, double out[M][N], const double in[N][M]);
2004 transpose(3, 2, y, x);
2008 @section Non-Constant Initializers
2009 @cindex initializers, non-constant
2010 @cindex non-constant initializers
2012 As in standard C++ and ISO C99, the elements of an aggregate initializer for an
2013 automatic variable are not required to be constant expressions in GNU C@.
2014 Here is an example of an initializer with run-time varying elements:
2017 foo (float f, float g)
2019 float beat_freqs[2] = @{ f-g, f+g @};
2024 @node Compound Literals
2025 @section Compound Literals
2026 @cindex constructor expressions
2027 @cindex initializations in expressions
2028 @cindex structures, constructor expression
2029 @cindex expressions, constructor
2030 @cindex compound literals
2031 @c The GNU C name for what C99 calls compound literals was "constructor expressions".
2033 A compound literal looks like a cast of a brace-enclosed aggregate
2034 initializer list. Its value is an object of the type specified in
2035 the cast, containing the elements specified in the initializer.
2036 Unlike the result of a cast, a compound literal is an lvalue. ISO
2037 C99 and later support compound literals. As an extension, GCC
2038 supports compound literals also in C90 mode and in C++, although
2039 as explained below, the C++ semantics are somewhat different.
2041 Usually, the specified type of a compound literal is a structure. Assume
2042 that @code{struct foo} and @code{structure} are declared as shown:
2045 struct foo @{int a; char b[2];@} structure;
2049 Here is an example of constructing a @code{struct foo} with a compound literal:
2052 structure = ((struct foo) @{x + y, 'a', 0@});
2056 This is equivalent to writing the following:
2060 struct foo temp = @{x + y, 'a', 0@};
2065 You can also construct an array, though this is dangerous in C++, as
2066 explained below. If all the elements of the compound literal are
2067 (made up of) simple constant expressions suitable for use in
2068 initializers of objects of static storage duration, then the compound
2069 literal can be coerced to a pointer to its first element and used in
2070 such an initializer, as shown here:
2073 char **foo = (char *[]) @{ "x", "y", "z" @};
2076 Compound literals for scalar types and union types are also allowed. In
2077 the following example the variable @code{i} is initialized to the value
2078 @code{2}, the result of incrementing the unnamed object created by
2079 the compound literal.
2082 int i = ++(int) @{ 1 @};
2085 As a GNU extension, GCC allows initialization of objects with static storage
2086 duration by compound literals (which is not possible in ISO C99 because
2087 the initializer is not a constant).
2088 It is handled as if the object were initialized only with the brace-enclosed
2089 list if the types of the compound literal and the object match.
2090 The elements of the compound literal must be constant.
2091 If the object being initialized has array type of unknown size, the size is
2092 determined by the size of the compound literal.
2095 static struct foo x = (struct foo) @{1, 'a', 'b'@};
2096 static int y[] = (int []) @{1, 2, 3@};
2097 static int z[] = (int [3]) @{1@};
2101 The above lines are equivalent to the following:
2103 static struct foo x = @{1, 'a', 'b'@};
2104 static int y[] = @{1, 2, 3@};
2105 static int z[] = @{1, 0, 0@};
2108 In C, a compound literal designates an unnamed object with static or
2109 automatic storage duration. In C++, a compound literal designates a
2110 temporary object that only lives until the end of its full-expression.
2111 As a result, well-defined C code that takes the address of a subobject
2112 of a compound literal can be undefined in C++, so G++ rejects
2113 the conversion of a temporary array to a pointer. For instance, if
2114 the array compound literal example above appeared inside a function,
2115 any subsequent use of @code{foo} in C++ would have undefined behavior
2116 because the lifetime of the array ends after the declaration of @code{foo}.
2118 As an optimization, G++ sometimes gives array compound literals longer
2119 lifetimes: when the array either appears outside a function or has
2120 a @code{const}-qualified type. If @code{foo} and its initializer had
2121 elements of type @code{char *const} rather than @code{char *}, or if
2122 @code{foo} were a global variable, the array would have static storage
2123 duration. But it is probably safest just to avoid the use of array
2124 compound literals in C++ code.
2126 @node Designated Inits
2127 @section Designated Initializers
2128 @cindex initializers with labeled elements
2129 @cindex labeled elements in initializers
2130 @cindex case labels in initializers
2131 @cindex designated initializers
2133 Standard C90 requires the elements of an initializer to appear in a fixed
2134 order, the same as the order of the elements in the array or structure
2137 In ISO C99 you can give the elements in any order, specifying the array
2138 indices or structure field names they apply to, and GNU C allows this as
2139 an extension in C90 mode as well. This extension is not
2140 implemented in GNU C++.
2142 To specify an array index, write
2143 @samp{[@var{index}] =} before the element value. For example,
2146 int a[6] = @{ [4] = 29, [2] = 15 @};
2153 int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
2157 The index values must be constant expressions, even if the array being
2158 initialized is automatic.
2160 An alternative syntax for this that has been obsolete since GCC 2.5 but
2161 GCC still accepts is to write @samp{[@var{index}]} before the element
2162 value, with no @samp{=}.
2164 To initialize a range of elements to the same value, write
2165 @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
2166 extension. For example,
2169 int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
2173 If the value in it has side effects, the side effects happen only once,
2174 not for each initialized field by the range initializer.
2177 Note that the length of the array is the highest value specified
2180 In a structure initializer, specify the name of a field to initialize
2181 with @samp{.@var{fieldname} =} before the element value. For example,
2182 given the following structure,
2185 struct point @{ int x, y; @};
2189 the following initialization
2192 struct point p = @{ .y = yvalue, .x = xvalue @};
2199 struct point p = @{ xvalue, yvalue @};
2202 Another syntax that has the same meaning, obsolete since GCC 2.5, is
2203 @samp{@var{fieldname}:}, as shown here:
2206 struct point p = @{ y: yvalue, x: xvalue @};
2209 Omitted fields are implicitly initialized the same as for objects
2210 that have static storage duration.
2213 The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
2214 @dfn{designator}. You can also use a designator (or the obsolete colon
2215 syntax) when initializing a union, to specify which element of the union
2216 should be used. For example,
2219 union foo @{ int i; double d; @};
2221 union foo f = @{ .d = 4 @};
2225 converts 4 to a @code{double} to store it in the union using
2226 the second element. By contrast, casting 4 to type @code{union foo}
2227 stores it into the union as the integer @code{i}, since it is
2228 an integer. @xref{Cast to Union}.
2230 You can combine this technique of naming elements with ordinary C
2231 initialization of successive elements. Each initializer element that
2232 does not have a designator applies to the next consecutive element of the
2233 array or structure. For example,
2236 int a[6] = @{ [1] = v1, v2, [4] = v4 @};
2243 int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
2246 Labeling the elements of an array initializer is especially useful
2247 when the indices are characters or belong to an @code{enum} type.
2252 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
2253 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
2256 @cindex designator lists
2257 You can also write a series of @samp{.@var{fieldname}} and
2258 @samp{[@var{index}]} designators before an @samp{=} to specify a
2259 nested subobject to initialize; the list is taken relative to the
2260 subobject corresponding to the closest surrounding brace pair. For
2261 example, with the @samp{struct point} declaration above:
2264 struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
2267 If the same field is initialized multiple times, or overlapping
2268 fields of a union are initialized, the value from the last
2269 initialization is used. When a field of a union is itself a structure,
2270 the entire structure from the last field initialized is used. If any previous
2271 initializer has side effect, it is unspecified whether the side effect
2272 happens or not. Currently, GCC discards the side-effecting
2273 initializer expressions and issues a warning.
2276 @section Case Ranges
2278 @cindex ranges in case statements
2280 You can specify a range of consecutive values in a single @code{case} label,
2284 case @var{low} ... @var{high}:
2288 This has the same effect as the proper number of individual @code{case}
2289 labels, one for each integer value from @var{low} to @var{high}, inclusive.
2291 This feature is especially useful for ranges of ASCII character codes:
2297 @strong{Be careful:} Write spaces around the @code{...}, for otherwise
2298 it may be parsed wrong when you use it with integer values. For example,
2313 @section Cast to a Union Type
2314 @cindex cast to a union
2315 @cindex union, casting to a
2317 A cast to a union type is a C extension not available in C++. It looks
2318 just like ordinary casts with the constraint that the type specified is
2319 a union type. You can specify the type either with the @code{union}
2320 keyword or with a @code{typedef} name that refers to a union. The result
2321 of a cast to a union is a temporary rvalue of the union type with a member
2322 whose type matches that of the operand initialized to the value of
2323 the operand. The effect of a cast to a union is similar to a compound
2324 literal except that it yields an rvalue like standard casts do.
2325 @xref{Compound Literals}.
2327 Expressions that may be cast to the union type are those whose type matches
2328 at least one of the members of the union. Thus, given the following union
2332 union foo @{ int i; double d; @};
2339 both @code{x} and @code{y} can be cast to type @code{union foo} and
2340 the following assignments
2345 are shorthand equivalents of these
2347 z = (union foo) @{ .i = x @};
2348 z = (union foo) @{ .d = y @};
2351 However, @code{(union foo) FLT_MAX;} is not a valid cast because the union
2352 has no member of type @code{float}.
2354 Using the cast as the right-hand side of an assignment to a variable of
2355 union type is equivalent to storing in a member of the union with
2361 u = (union foo) x @equiv{} u.i = x
2362 u = (union foo) y @equiv{} u.d = y
2365 You can also use the union cast as a function argument:
2368 void hack (union foo);
2370 hack ((union foo) x);
2373 @node Mixed Declarations
2374 @section Mixed Declarations and Code
2375 @cindex mixed declarations and code
2376 @cindex declarations, mixed with code
2377 @cindex code, mixed with declarations
2379 ISO C99 and ISO C++ allow declarations and code to be freely mixed
2380 within compound statements. As an extension, GNU C also allows this in
2381 C90 mode. For example, you could do:
2390 Each identifier is visible from where it is declared until the end of
2391 the enclosing block.
2393 @node Function Attributes
2394 @section Declaring Attributes of Functions
2395 @cindex function attributes
2396 @cindex declaring attributes of functions
2397 @cindex @code{volatile} applied to function
2398 @cindex @code{const} applied to function
2400 In GNU C and C++, you can use function attributes to specify certain
2401 function properties that may help the compiler optimize calls or
2402 check code more carefully for correctness. For example, you
2403 can use attributes to specify that a function never returns
2404 (@code{noreturn}), returns a value depending only on the values of
2405 its arguments (@code{const}), or has @code{printf}-style arguments
2408 You can also use attributes to control memory placement, code
2409 generation options or call/return conventions within the function
2410 being annotated. Many of these attributes are target-specific. For
2411 example, many targets support attributes for defining interrupt
2412 handler functions, which typically must follow special register usage
2413 and return conventions. Such attributes are described in the subsection
2414 for each target. However, a considerable number of attributes are
2415 supported by most, if not all targets. Those are described in
2416 the @ref{Common Function Attributes} section.
2418 Function attributes are introduced by the @code{__attribute__} keyword
2419 in the declaration of a function, followed by an attribute specification
2420 enclosed in double parentheses. You can specify multiple attributes in
2421 a declaration by separating them by commas within the double parentheses
2422 or by immediately following one attribute specification with another.
2423 @xref{Attribute Syntax}, for the exact rules on attribute syntax and
2424 placement. Compatible attribute specifications on distinct declarations
2425 of the same function are merged. An attribute specification that is not
2426 compatible with attributes already applied to a declaration of the same
2427 function is ignored with a warning.
2429 Some function attributes take one or more arguments that refer to
2430 the function's parameters by their positions within the function parameter
2431 list. Such attribute arguments are referred to as @dfn{positional arguments}.
2432 Unless specified otherwise, positional arguments that specify properties
2433 of parameters with pointer types can also specify the same properties of
2434 the implicit C++ @code{this} argument in non-static member functions, and
2435 of parameters of reference to a pointer type. For ordinary functions,
2436 position one refers to the first parameter on the list. In C++ non-static
2437 member functions, position one refers to the implicit @code{this} pointer.
2438 The same restrictions and effects apply to function attributes used with
2439 ordinary functions or C++ member functions.
2441 GCC also supports attributes on
2442 variable declarations (@pxref{Variable Attributes}),
2443 labels (@pxref{Label Attributes}),
2444 enumerators (@pxref{Enumerator Attributes}),
2445 statements (@pxref{Statement Attributes}),
2446 and types (@pxref{Type Attributes}).
2448 There is some overlap between the purposes of attributes and pragmas
2449 (@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been
2450 found convenient to use @code{__attribute__} to achieve a natural
2451 attachment of attributes to their corresponding declarations, whereas
2452 @code{#pragma} is of use for compatibility with other compilers
2453 or constructs that do not naturally form part of the grammar.
2455 In addition to the attributes documented here,
2456 GCC plugins may provide their own attributes.
2459 * Common Function Attributes::
2460 * AArch64 Function Attributes::
2461 * AMD GCN Function Attributes::
2462 * ARC Function Attributes::
2463 * ARM Function Attributes::
2464 * AVR Function Attributes::
2465 * Blackfin Function Attributes::
2466 * CR16 Function Attributes::
2467 * C-SKY Function Attributes::
2468 * Epiphany Function Attributes::
2469 * H8/300 Function Attributes::
2470 * IA-64 Function Attributes::
2471 * M32C Function Attributes::
2472 * M32R/D Function Attributes::
2473 * m68k Function Attributes::
2474 * MCORE Function Attributes::
2475 * MeP Function Attributes::
2476 * MicroBlaze Function Attributes::
2477 * Microsoft Windows Function Attributes::
2478 * MIPS Function Attributes::
2479 * MSP430 Function Attributes::
2480 * NDS32 Function Attributes::
2481 * Nios II Function Attributes::
2482 * Nvidia PTX Function Attributes::
2483 * PowerPC Function Attributes::
2484 * RISC-V Function Attributes::
2485 * RL78 Function Attributes::
2486 * RX Function Attributes::
2487 * S/390 Function Attributes::
2488 * SH Function Attributes::
2489 * SPU Function Attributes::
2490 * Symbian OS Function Attributes::
2491 * V850 Function Attributes::
2492 * Visium Function Attributes::
2493 * x86 Function Attributes::
2494 * Xstormy16 Function Attributes::
2497 @node Common Function Attributes
2498 @subsection Common Function Attributes
2500 The following attributes are supported on most targets.
2503 @c Keep this table alphabetized by attribute name. Treat _ as space.
2505 @item alias ("@var{target}")
2506 @cindex @code{alias} function attribute
2507 The @code{alias} attribute causes the declaration to be emitted as an
2508 alias for another symbol, which must be specified. For instance,
2511 void __f () @{ /* @r{Do something.} */; @}
2512 void f () __attribute__ ((weak, alias ("__f")));
2516 defines @samp{f} to be a weak alias for @samp{__f}. In C++, the
2517 mangled name for the target must be used. It is an error if @samp{__f}
2518 is not defined in the same translation unit.
2520 This attribute requires assembler and object file support,
2521 and may not be available on all targets.
2524 @itemx aligned (@var{alignment})
2525 @cindex @code{aligned} function attribute
2526 The @code{aligned} attribute specifies a minimum alignment for
2527 the first instruction of the function, measured in bytes. When specified,
2528 @var{alignment} must be an integer constant power of 2. Specifying no
2529 @var{alignment} argument implies the ideal alignment for the target.
2530 The @code{__alignof__} operator can be used to determine what that is
2531 (@pxref{Alignment}). The attribute has no effect when a definition for
2532 the function is not provided in the same translation unit.
2534 The attribute cannot be used to decrease the alignment of a function
2535 previously declared with a more restrictive alignment; only to increase
2536 it. Attempts to do otherwise are diagnosed. Some targets specify
2537 a minimum default alignment for functions that is greater than 1. On
2538 such targets, specifying a less restrictive alignment is silently ignored.
2539 Using the attribute overrides the effect of the @option{-falign-functions}
2540 (@pxref{Optimize Options}) option for this function.
2542 Note that the effectiveness of @code{aligned} attributes may be
2543 limited by inherent limitations in the system linker
2544 and/or object file format. On some systems, the
2545 linker is only able to arrange for functions to be aligned up to a
2546 certain maximum alignment. (For some linkers, the maximum supported
2547 alignment may be very very small.) See your linker documentation for
2548 further information.
2550 The @code{aligned} attribute can also be used for variables and fields
2551 (@pxref{Variable Attributes}.)
2553 @item alloc_align (@var{position})
2554 @cindex @code{alloc_align} function attribute
2555 The @code{alloc_align} attribute may be applied to a function that
2556 returns a pointer and takes at least one argument of an integer or
2558 It indicates that the returned pointer is aligned on a boundary given
2559 by the function argument at @var{position}. Meaningful alignments are
2560 powers of 2 greater than one. GCC uses this information to improve
2561 pointer alignment analysis.
2563 The function parameter denoting the allocated alignment is specified by
2564 one constant integer argument whose number is the argument of the attribute.
2565 Argument numbering starts at one.
2570 void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1)));
2574 declares that @code{my_memalign} returns memory with minimum alignment
2575 given by parameter 1.
2577 @item alloc_size (@var{position})
2578 @itemx alloc_size (@var{position-1}, @var{position-2})
2579 @cindex @code{alloc_size} function attribute
2580 The @code{alloc_size} attribute may be applied to a function that
2581 returns a pointer and takes at least one argument of an integer or
2583 It indicates that the returned pointer points to memory whose size is
2584 given by the function argument at @var{position-1}, or by the product
2585 of the arguments at @var{position-1} and @var{position-2}. Meaningful
2586 sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this
2587 information to improve the results of @code{__builtin_object_size}.
2589 The function parameter(s) denoting the allocated size are specified by
2590 one or two integer arguments supplied to the attribute. The allocated size
2591 is either the value of the single function argument specified or the product
2592 of the two function arguments specified. Argument numbering starts at
2593 one for ordinary functions, and at two for C++ non-static member functions.
2598 void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2)));
2599 void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2)));
2603 declares that @code{my_calloc} returns memory of the size given by
2604 the product of parameter 1 and 2 and that @code{my_realloc} returns memory
2605 of the size given by parameter 2.
2608 @cindex @code{always_inline} function attribute
2609 Generally, functions are not inlined unless optimization is specified.
2610 For functions declared inline, this attribute inlines the function
2611 independent of any restrictions that otherwise apply to inlining.
2612 Failure to inline such a function is diagnosed as an error.
2613 Note that if such a function is called indirectly the compiler may
2614 or may not inline it depending on optimization level and a failure
2615 to inline an indirect call may or may not be diagnosed.
2618 @cindex @code{artificial} function attribute
2619 This attribute is useful for small inline wrappers that if possible
2620 should appear during debugging as a unit. Depending on the debug
2621 info format it either means marking the function as artificial
2622 or using the caller location for all instructions within the inlined
2625 @item assume_aligned (@var{alignment})
2626 @itemx assume_aligned (@var{alignment}, @var{offset})
2627 @cindex @code{assume_aligned} function attribute
2628 The @code{assume_aligned} attribute may be applied to a function that
2629 returns a pointer. It indicates that the returned pointer is aligned
2630 on a boundary given by @var{alignment}. If the attribute has two
2631 arguments, the second argument is misalignment @var{offset}. Meaningful
2632 values of @var{alignment} are powers of 2 greater than one. Meaningful
2633 values of @var{offset} are greater than zero and less than @var{alignment}.
2638 void* my_alloc1 (size_t) __attribute__((assume_aligned (16)));
2639 void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8)));
2643 declares that @code{my_alloc1} returns 16-byte aligned pointers and
2644 that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
2648 @cindex @code{cold} function attribute
2649 The @code{cold} attribute on functions is used to inform the compiler that
2650 the function is unlikely to be executed. The function is optimized for
2651 size rather than speed and on many targets it is placed into a special
2652 subsection of the text section so all cold functions appear close together,
2653 improving code locality of non-cold parts of program. The paths leading
2654 to calls of cold functions within code are marked as unlikely by the branch
2655 prediction mechanism. It is thus useful to mark functions used to handle
2656 unlikely conditions, such as @code{perror}, as cold to improve optimization
2657 of hot functions that do call marked functions in rare occasions.
2659 When profile feedback is available, via @option{-fprofile-use}, cold functions
2660 are automatically detected and this attribute is ignored.
2663 @cindex @code{const} function attribute
2664 @cindex functions that have no side effects
2665 Calls to functions whose return value is not affected by changes to
2666 the observable state of the program and that have no observable effects
2667 on such state other than to return a value may lend themselves to
2668 optimizations such as common subexpression elimination. Declaring such
2669 functions with the @code{const} attribute allows GCC to avoid emitting
2670 some calls in repeated invocations of the function with the same argument
2676 int square (int) __attribute__ ((const));
2680 tells GCC that subsequent calls to function @code{square} with the same
2681 argument value can be replaced by the result of the first call regardless
2682 of the statements in between.
2684 The @code{const} attribute prohibits a function from reading objects
2685 that affect its return value between successive invocations. However,
2686 functions declared with the attribute can safely read objects that do
2687 not change their return value, such as non-volatile constants.
2689 The @code{const} attribute imposes greater restrictions on a function's
2690 definition than the similar @code{pure} attribute. Declaring the same
2691 function with both the @code{const} and the @code{pure} attribute is
2692 diagnosed. Because a const function cannot have any observable side
2693 effects it does not make sense for it to return @code{void}. Declaring
2694 such a function is diagnosed.
2696 @cindex pointer arguments
2697 Note that a function that has pointer arguments and examines the data
2698 pointed to must @emph{not} be declared @code{const} if the pointed-to
2699 data might change between successive invocations of the function. In
2700 general, since a function cannot distinguish data that might change
2701 from data that cannot, const functions should never take pointer or,
2702 in C++, reference arguments. Likewise, a function that calls a non-const
2703 function usually must not be const itself.
2707 @itemx constructor (@var{priority})
2708 @itemx destructor (@var{priority})
2709 @cindex @code{constructor} function attribute
2710 @cindex @code{destructor} function attribute
2711 The @code{constructor} attribute causes the function to be called
2712 automatically before execution enters @code{main ()}. Similarly, the
2713 @code{destructor} attribute causes the function to be called
2714 automatically after @code{main ()} completes or @code{exit ()} is
2715 called. Functions with these attributes are useful for
2716 initializing data that is used implicitly during the execution of
2719 On some targets the attributes also accept an integer argument to
2720 specify a priority to control the order in which constructor and
2721 destructor functions are run. A constructor
2722 with a smaller priority number runs before a constructor with a larger
2723 priority number; the opposite relationship holds for destructors. So,
2724 if you have a constructor that allocates a resource and a destructor
2725 that deallocates the same resource, both functions typically have the
2726 same priority. The priorities for constructor and destructor
2727 functions are the same as those specified for namespace-scope C++
2728 objects (@pxref{C++ Attributes}). However, at present, the order in which
2729 constructors for C++ objects with static storage duration and functions
2730 decorated with attribute @code{constructor} are invoked is unspecified.
2731 In mixed declarations, attribute @code{init_priority} can be used to
2732 impose a specific ordering.
2734 Using the argument forms of the @code{constructor} and @code{destructor}
2735 attributes on targets where the feature is not supported is rejected with
2739 @itemx copy (@var{function})
2740 @cindex @code{copy} function attribute
2741 The @code{copy} attribute applies the set of attributes with which
2742 @var{function} has been declared to the declaration of the function
2743 to which the attribute is applied. The attribute is designed for
2744 libraries that define aliases or function resolvers that are expected
2745 to specify the same set of attributes as their targets. The @code{copy}
2746 attribute can be used with functions, variables, or types. However,
2747 the kind of symbol to which the attribute is applied (either function
2748 or variable) must match the kind of symbol to which the argument refers.
2749 The @code{copy} attribute copies only syntactic and semantic attributes
2750 but not attributes that affect a symbol's linkage or visibility such as
2751 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
2752 and @code{target_clones} attribute are also not copied.
2753 @xref{Common Type Attributes}.
2754 @xref{Common Variable Attributes}.
2756 For example, the @var{StrongAlias} macro below makes use of the @code{alias}
2757 and @code{copy} attributes to define an alias named @var{alloc} for function
2758 @var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and
2759 @var{nothrow}. Thanks to the @code{__typeof__} operator the alias has
2760 the same type as the target function. As a result of the @code{copy}
2761 attribute the alias also shares the same attributes as the target.
2764 #define StrongAlias(TagetFunc, AliasDecl) \
2765 extern __typeof__ (TargetFunc) AliasDecl \
2766 __attribute__ ((alias (#TargetFunc), copy (TargetFunc)));
2768 extern __attribute__ ((alloc_size (1), malloc, nothrow))
2769 void* allocate (size_t);
2770 StrongAlias (allocate, alloc);
2774 @itemx deprecated (@var{msg})
2775 @cindex @code{deprecated} function attribute
2776 The @code{deprecated} attribute results in a warning if the function
2777 is used anywhere in the source file. This is useful when identifying
2778 functions that are expected to be removed in a future version of a
2779 program. The warning also includes the location of the declaration
2780 of the deprecated function, to enable users to easily find further
2781 information about why the function is deprecated, or what they should
2782 do instead. Note that the warnings only occurs for uses:
2785 int old_fn () __attribute__ ((deprecated));
2787 int (*fn_ptr)() = old_fn;
2791 results in a warning on line 3 but not line 2. The optional @var{msg}
2792 argument, which must be a string, is printed in the warning if
2795 The @code{deprecated} attribute can also be used for variables and
2796 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
2798 The message attached to the attribute is affected by the setting of
2799 the @option{-fmessage-length} option.
2801 @item error ("@var{message}")
2802 @itemx warning ("@var{message}")
2803 @cindex @code{error} function attribute
2804 @cindex @code{warning} function attribute
2805 If the @code{error} or @code{warning} attribute
2806 is used on a function declaration and a call to such a function
2807 is not eliminated through dead code elimination or other optimizations,
2808 an error or warning (respectively) that includes @var{message} is diagnosed.
2810 for compile-time checking, especially together with @code{__builtin_constant_p}
2811 and inline functions where checking the inline function arguments is not
2812 possible through @code{extern char [(condition) ? 1 : -1];} tricks.
2814 While it is possible to leave the function undefined and thus invoke
2815 a link failure (to define the function with
2816 a message in @code{.gnu.warning*} section),
2817 when using these attributes the problem is diagnosed
2818 earlier and with exact location of the call even in presence of inline
2819 functions or when not emitting debugging information.
2821 @item externally_visible
2822 @cindex @code{externally_visible} function attribute
2823 This attribute, attached to a global variable or function, nullifies
2824 the effect of the @option{-fwhole-program} command-line option, so the
2825 object remains visible outside the current compilation unit.
2827 If @option{-fwhole-program} is used together with @option{-flto} and
2828 @command{gold} is used as the linker plugin,
2829 @code{externally_visible} attributes are automatically added to functions
2830 (not variable yet due to a current @command{gold} issue)
2831 that are accessed outside of LTO objects according to resolution file
2832 produced by @command{gold}.
2833 For other linkers that cannot generate resolution file,
2834 explicit @code{externally_visible} attributes are still necessary.
2837 @cindex @code{flatten} function attribute
2838 Generally, inlining into a function is limited. For a function marked with
2839 this attribute, every call inside this function is inlined, if possible.
2840 Functions declared with attribute @code{noinline} and similar are not
2841 inlined. Whether the function itself is considered for inlining depends
2842 on its size and the current inlining parameters.
2844 @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
2845 @cindex @code{format} function attribute
2846 @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
2848 The @code{format} attribute specifies that a function takes @code{printf},
2849 @code{scanf}, @code{strftime} or @code{strfmon} style arguments that
2850 should be type-checked against a format string. For example, the
2855 my_printf (void *my_object, const char *my_format, ...)
2856 __attribute__ ((format (printf, 2, 3)));
2860 causes the compiler to check the arguments in calls to @code{my_printf}
2861 for consistency with the @code{printf} style format string argument
2864 The parameter @var{archetype} determines how the format string is
2865 interpreted, and should be @code{printf}, @code{scanf}, @code{strftime},
2866 @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or
2867 @code{strfmon}. (You can also use @code{__printf__},
2868 @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On
2869 MinGW targets, @code{ms_printf}, @code{ms_scanf}, and
2870 @code{ms_strftime} are also present.
2871 @var{archetype} values such as @code{printf} refer to the formats accepted
2872 by the system's C runtime library,
2873 while values prefixed with @samp{gnu_} always refer
2874 to the formats accepted by the GNU C Library. On Microsoft Windows
2875 targets, values prefixed with @samp{ms_} refer to the formats accepted by the
2876 @file{msvcrt.dll} library.
2877 The parameter @var{string-index}
2878 specifies which argument is the format string argument (starting
2879 from 1), while @var{first-to-check} is the number of the first
2880 argument to check against the format string. For functions
2881 where the arguments are not available to be checked (such as
2882 @code{vprintf}), specify the third parameter as zero. In this case the
2883 compiler only checks the format string for consistency. For
2884 @code{strftime} formats, the third parameter is required to be zero.
2885 Since non-static C++ methods have an implicit @code{this} argument, the
2886 arguments of such methods should be counted from two, not one, when
2887 giving values for @var{string-index} and @var{first-to-check}.
2889 In the example above, the format string (@code{my_format}) is the second
2890 argument of the function @code{my_print}, and the arguments to check
2891 start with the third argument, so the correct parameters for the format
2892 attribute are 2 and 3.
2894 @opindex ffreestanding
2895 @opindex fno-builtin
2896 The @code{format} attribute allows you to identify your own functions
2897 that take format strings as arguments, so that GCC can check the
2898 calls to these functions for errors. The compiler always (unless
2899 @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
2900 for the standard library functions @code{printf}, @code{fprintf},
2901 @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
2902 @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
2903 warnings are requested (using @option{-Wformat}), so there is no need to
2904 modify the header file @file{stdio.h}. In C99 mode, the functions
2905 @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
2906 @code{vsscanf} are also checked. Except in strictly conforming C
2907 standard modes, the X/Open function @code{strfmon} is also checked as
2908 are @code{printf_unlocked} and @code{fprintf_unlocked}.
2909 @xref{C Dialect Options,,Options Controlling C Dialect}.
2911 For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is
2912 recognized in the same context. Declarations including these format attributes
2913 are parsed for correct syntax, however the result of checking of such format
2914 strings is not yet defined, and is not carried out by this version of the
2917 The target may also provide additional types of format checks.
2918 @xref{Target Format Checks,,Format Checks Specific to Particular
2921 @item format_arg (@var{string-index})
2922 @cindex @code{format_arg} function attribute
2923 @opindex Wformat-nonliteral
2924 The @code{format_arg} attribute specifies that a function takes one or
2925 more format strings for a @code{printf}, @code{scanf}, @code{strftime} or
2926 @code{strfmon} style function and modifies it (for example, to translate
2927 it into another language), so the result can be passed to a
2928 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
2929 function (with the remaining arguments to the format function the same
2930 as they would have been for the unmodified string). Multiple
2931 @code{format_arg} attributes may be applied to the same function, each
2932 designating a distinct parameter as a format string. For example, the
2937 my_dgettext (char *my_domain, const char *my_format)
2938 __attribute__ ((format_arg (2)));
2942 causes the compiler to check the arguments in calls to a @code{printf},
2943 @code{scanf}, @code{strftime} or @code{strfmon} type function, whose
2944 format string argument is a call to the @code{my_dgettext} function, for
2945 consistency with the format string argument @code{my_format}. If the
2946 @code{format_arg} attribute had not been specified, all the compiler
2947 could tell in such calls to format functions would be that the format
2948 string argument is not constant; this would generate a warning when
2949 @option{-Wformat-nonliteral} is used, but the calls could not be checked
2950 without the attribute.
2952 In calls to a function declared with more than one @code{format_arg}
2953 attribute, each with a distinct argument value, the corresponding
2954 actual function arguments are checked against all format strings
2955 designated by the attributes. This capability is designed to support
2956 the GNU @code{ngettext} family of functions.
2958 The parameter @var{string-index} specifies which argument is the format
2959 string argument (starting from one). Since non-static C++ methods have
2960 an implicit @code{this} argument, the arguments of such methods should
2961 be counted from two.
2963 The @code{format_arg} attribute allows you to identify your own
2964 functions that modify format strings, so that GCC can check the
2965 calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
2966 type function whose operands are a call to one of your own function.
2967 The compiler always treats @code{gettext}, @code{dgettext}, and
2968 @code{dcgettext} in this manner except when strict ISO C support is
2969 requested by @option{-ansi} or an appropriate @option{-std} option, or
2970 @option{-ffreestanding} or @option{-fno-builtin}
2971 is used. @xref{C Dialect Options,,Options
2972 Controlling C Dialect}.
2974 For Objective-C dialects, the @code{format-arg} attribute may refer to an
2975 @code{NSString} reference for compatibility with the @code{format} attribute
2978 The target may also allow additional types in @code{format-arg} attributes.
2979 @xref{Target Format Checks,,Format Checks Specific to Particular
2983 @cindex @code{gnu_inline} function attribute
2984 This attribute should be used with a function that is also declared
2985 with the @code{inline} keyword. It directs GCC to treat the function
2986 as if it were defined in gnu90 mode even when compiling in C99 or
2989 If the function is declared @code{extern}, then this definition of the
2990 function is used only for inlining. In no case is the function
2991 compiled as a standalone function, not even if you take its address
2992 explicitly. Such an address becomes an external reference, as if you
2993 had only declared the function, and had not defined it. This has
2994 almost the effect of a macro. The way to use this is to put a
2995 function definition in a header file with this attribute, and put
2996 another copy of the function, without @code{extern}, in a library
2997 file. The definition in the header file causes most calls to the
2998 function to be inlined. If any uses of the function remain, they
2999 refer to the single copy in the library. Note that the two
3000 definitions of the functions need not be precisely the same, although
3001 if they do not have the same effect your program may behave oddly.
3003 In C, if the function is neither @code{extern} nor @code{static}, then
3004 the function is compiled as a standalone function, as well as being
3005 inlined where possible.
3007 This is how GCC traditionally handled functions declared
3008 @code{inline}. Since ISO C99 specifies a different semantics for
3009 @code{inline}, this function attribute is provided as a transition
3010 measure and as a useful feature in its own right. This attribute is
3011 available in GCC 4.1.3 and later. It is available if either of the
3012 preprocessor macros @code{__GNUC_GNU_INLINE__} or
3013 @code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
3014 Function is As Fast As a Macro}.
3016 In C++, this attribute does not depend on @code{extern} in any way,
3017 but it still requires the @code{inline} keyword to enable its special
3021 @cindex @code{hot} function attribute
3022 The @code{hot} attribute on a function is used to inform the compiler that
3023 the function is a hot spot of the compiled program. The function is
3024 optimized more aggressively and on many targets it is placed into a special
3025 subsection of the text section so all hot functions appear close together,
3028 When profile feedback is available, via @option{-fprofile-use}, hot functions
3029 are automatically detected and this attribute is ignored.
3031 @item ifunc ("@var{resolver}")
3032 @cindex @code{ifunc} function attribute
3033 @cindex indirect functions
3034 @cindex functions that are dynamically resolved
3035 The @code{ifunc} attribute is used to mark a function as an indirect
3036 function using the STT_GNU_IFUNC symbol type extension to the ELF
3037 standard. This allows the resolution of the symbol value to be
3038 determined dynamically at load time, and an optimized version of the
3039 routine to be selected for the particular processor or other system
3040 characteristics determined then. To use this attribute, first define
3041 the implementation functions available, and a resolver function that
3042 returns a pointer to the selected implementation function. The
3043 implementation functions' declarations must match the API of the
3044 function being implemented. The resolver should be declared to
3045 be a function taking no arguments and returning a pointer to
3046 a function of the same type as the implementation. For example:
3049 void *my_memcpy (void *dst, const void *src, size_t len)
3055 static void * (*resolve_memcpy (void))(void *, const void *, size_t)
3057 return my_memcpy; // we will just always select this routine
3062 The exported header file declaring the function the user calls would
3066 extern void *memcpy (void *, const void *, size_t);
3070 allowing the user to call @code{memcpy} as a regular function, unaware of
3071 the actual implementation. Finally, the indirect function needs to be
3072 defined in the same translation unit as the resolver function:
3075 void *memcpy (void *, const void *, size_t)
3076 __attribute__ ((ifunc ("resolve_memcpy")));
3079 In C++, the @code{ifunc} attribute takes a string that is the mangled name
3080 of the resolver function. A C++ resolver for a non-static member function
3081 of class @code{C} should be declared to return a pointer to a non-member
3082 function taking pointer to @code{C} as the first argument, followed by
3083 the same arguments as of the implementation function. G++ checks
3084 the signatures of the two functions and issues
3085 a @option{-Wattribute-alias} warning for mismatches. To suppress a warning
3086 for the necessary cast from a pointer to the implementation member function
3087 to the type of the corresponding non-member function use
3088 the @option{-Wno-pmf-conversions} option. For example:
3094 int debug_impl (int);
3095 int optimized_impl (int);
3097 typedef int Func (S*, int);
3099 static Func* resolver ();
3102 int interface (int);
3105 int S::debug_impl (int) @{ /* @r{@dots{}} */ @}
3106 int S::optimized_impl (int) @{ /* @r{@dots{}} */ @}
3108 S::Func* S::resolver ()
3110 int (S::*pimpl) (int)
3111 = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl;
3113 // Cast triggers -Wno-pmf-conversions.
3114 return reinterpret_cast<Func*>(pimpl);
3117 int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv")));
3120 Indirect functions cannot be weak. Binutils version 2.20.1 or higher
3121 and GNU C Library version 2.11.1 are required to use this feature.
3124 @itemx interrupt_handler
3125 Many GCC back ends support attributes to indicate that a function is
3126 an interrupt handler, which tells the compiler to generate function
3127 entry and exit sequences that differ from those from regular
3128 functions. The exact syntax and behavior are target-specific;
3129 refer to the following subsections for details.
3132 @cindex @code{leaf} function attribute
3133 Calls to external functions with this attribute must return to the
3134 current compilation unit only by return or by exception handling. In
3135 particular, a leaf function is not allowed to invoke callback functions
3136 passed to it from the current compilation unit, directly call functions
3137 exported by the unit, or @code{longjmp} into the unit. Leaf functions
3138 might still call functions from other compilation units and thus they
3139 are not necessarily leaf in the sense that they contain no function
3142 The attribute is intended for library functions to improve dataflow
3143 analysis. The compiler takes the hint that any data not escaping the
3144 current compilation unit cannot be used or modified by the leaf
3145 function. For example, the @code{sin} function is a leaf function, but
3146 @code{qsort} is not.
3148 Note that leaf functions might indirectly run a signal handler defined
3149 in the current compilation unit that uses static variables. Similarly,
3150 when lazy symbol resolution is in effect, leaf functions might invoke
3151 indirect functions whose resolver function or implementation function is
3152 defined in the current compilation unit and uses static variables. There
3153 is no standard-compliant way to write such a signal handler, resolver
3154 function, or implementation function, and the best that you can do is to
3155 remove the @code{leaf} attribute or mark all such static variables
3156 @code{volatile}. Lastly, for ELF-based systems that support symbol
3157 interposition, care should be taken that functions defined in the
3158 current compilation unit do not unexpectedly interpose other symbols
3159 based on the defined standards mode and defined feature test macros;
3160 otherwise an inadvertent callback would be added.
3162 The attribute has no effect on functions defined within the current
3163 compilation unit. This is to allow easy merging of multiple compilation
3164 units into one, for example, by using the link-time optimization. For
3165 this reason the attribute is not allowed on types to annotate indirect
3169 @cindex @code{malloc} function attribute
3170 @cindex functions that behave like malloc
3171 This tells the compiler that a function is @code{malloc}-like, i.e.,
3172 that the pointer @var{P} returned by the function cannot alias any
3173 other pointer valid when the function returns, and moreover no
3174 pointers to valid objects occur in any storage addressed by @var{P}.
3176 Using this attribute can improve optimization. Compiler predicts
3177 that a function with the attribute returns non-null in most cases.
3179 @code{malloc} and @code{calloc} have this property because they return
3180 a pointer to uninitialized or zeroed-out storage. However, functions
3181 like @code{realloc} do not have this property, as they can return a
3182 pointer to storage containing pointers.
3185 @cindex @code{no_icf} function attribute
3186 This function attribute prevents a functions from being merged with another
3187 semantically equivalent function.
3189 @item no_instrument_function
3190 @cindex @code{no_instrument_function} function attribute
3191 @opindex finstrument-functions
3194 If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are
3195 given, profiling function calls are
3196 generated at entry and exit of most user-compiled functions.
3197 Functions with this attribute are not so instrumented.
3199 @item no_profile_instrument_function
3200 @cindex @code{no_profile_instrument_function} function attribute
3201 The @code{no_profile_instrument_function} attribute on functions is used
3202 to inform the compiler that it should not process any profile feedback based
3203 optimization code instrumentation.
3206 @cindex @code{no_reorder} function attribute
3207 Do not reorder functions or variables marked @code{no_reorder}
3208 against each other or top level assembler statements the executable.
3209 The actual order in the program will depend on the linker command
3210 line. Static variables marked like this are also not removed.
3211 This has a similar effect
3212 as the @option{-fno-toplevel-reorder} option, but only applies to the
3215 @item no_sanitize ("@var{sanitize_option}")
3216 @cindex @code{no_sanitize} function attribute
3217 The @code{no_sanitize} attribute on functions is used
3218 to inform the compiler that it should not do sanitization of any option
3219 mentioned in @var{sanitize_option}. A list of values acceptable by
3220 the @option{-fsanitize} option can be provided.
3223 void __attribute__ ((no_sanitize ("alignment", "object-size")))
3224 f () @{ /* @r{Do something.} */; @}
3225 void __attribute__ ((no_sanitize ("alignment,object-size")))
3226 g () @{ /* @r{Do something.} */; @}
3229 @item no_sanitize_address
3230 @itemx no_address_safety_analysis
3231 @cindex @code{no_sanitize_address} function attribute
3232 The @code{no_sanitize_address} attribute on functions is used
3233 to inform the compiler that it should not instrument memory accesses
3234 in the function when compiling with the @option{-fsanitize=address} option.
3235 The @code{no_address_safety_analysis} is a deprecated alias of the
3236 @code{no_sanitize_address} attribute, new code should use
3237 @code{no_sanitize_address}.
3239 @item no_sanitize_thread
3240 @cindex @code{no_sanitize_thread} function attribute
3241 The @code{no_sanitize_thread} attribute on functions is used
3242 to inform the compiler that it should not instrument memory accesses
3243 in the function when compiling with the @option{-fsanitize=thread} option.
3245 @item no_sanitize_undefined
3246 @cindex @code{no_sanitize_undefined} function attribute
3247 The @code{no_sanitize_undefined} attribute on functions is used
3248 to inform the compiler that it should not check for undefined behavior
3249 in the function when compiling with the @option{-fsanitize=undefined} option.
3251 @item no_split_stack
3252 @cindex @code{no_split_stack} function attribute
3253 @opindex fsplit-stack
3254 If @option{-fsplit-stack} is given, functions have a small
3255 prologue which decides whether to split the stack. Functions with the
3256 @code{no_split_stack} attribute do not have that prologue, and thus
3257 may run with only a small amount of stack space available.
3259 @item no_stack_limit
3260 @cindex @code{no_stack_limit} function attribute
3261 This attribute locally overrides the @option{-fstack-limit-register}
3262 and @option{-fstack-limit-symbol} command-line options; it has the effect
3263 of disabling stack limit checking in the function it applies to.
3266 @cindex @code{noclone} function attribute
3267 This function attribute prevents a function from being considered for
3268 cloning---a mechanism that produces specialized copies of functions
3269 and which is (currently) performed by interprocedural constant
3273 @cindex @code{noinline} function attribute
3274 This function attribute prevents a function from being considered for
3276 @c Don't enumerate the optimizations by name here; we try to be
3277 @c future-compatible with this mechanism.
3278 If the function does not have side effects, there are optimizations
3279 other than inlining that cause function calls to be optimized away,
3280 although the function call is live. To keep such calls from being
3287 (@pxref{Extended Asm}) in the called function, to serve as a special
3291 @cindex @code{noipa} function attribute
3292 Disable interprocedural optimizations between the function with this
3293 attribute and its callers, as if the body of the function is not available
3294 when optimizing callers and the callers are unavailable when optimizing
3295 the body. This attribute implies @code{noinline}, @code{noclone} and
3296 @code{no_icf} attributes. However, this attribute is not equivalent
3297 to a combination of other attributes, because its purpose is to suppress
3298 existing and future optimizations employing interprocedural analysis,
3299 including those that do not have an attribute suitable for disabling
3300 them individually. This attribute is supported mainly for the purpose
3301 of testing the compiler.
3304 @itemx nonnull (@var{arg-index}, @dots{})
3305 @cindex @code{nonnull} function attribute
3306 @cindex functions with non-null pointer arguments
3307 The @code{nonnull} attribute may be applied to a function that takes at
3308 least one argument of a pointer type. It indicates that the referenced
3309 arguments must be non-null pointers. For instance, the declaration:
3313 my_memcpy (void *dest, const void *src, size_t len)
3314 __attribute__((nonnull (1, 2)));
3318 causes the compiler to check that, in calls to @code{my_memcpy},
3319 arguments @var{dest} and @var{src} are non-null. If the compiler
3320 determines that a null pointer is passed in an argument slot marked
3321 as non-null, and the @option{-Wnonnull} option is enabled, a warning
3322 is issued. @xref{Warning Options}. Unless disabled by
3323 the @option{-fno-delete-null-pointer-checks} option the compiler may
3324 also perform optimizations based on the knowledge that certain function
3325 arguments cannot be null. In addition,
3326 the @option{-fisolate-erroneous-paths-attribute} option can be specified
3327 to have GCC transform calls with null arguments to non-null functions
3328 into traps. @xref{Optimize Options}.
3330 If no @var{arg-index} is given to the @code{nonnull} attribute,
3331 all pointer arguments are marked as non-null. To illustrate, the
3332 following declaration is equivalent to the previous example:
3336 my_memcpy (void *dest, const void *src, size_t len)
3337 __attribute__((nonnull));
3341 @cindex @code{noplt} function attribute
3342 The @code{noplt} attribute is the counterpart to option @option{-fno-plt}.
3343 Calls to functions marked with this attribute in position-independent code
3348 /* Externally defined function foo. */
3349 int foo () __attribute__ ((noplt));
3352 main (/* @r{@dots{}} */)
3361 The @code{noplt} attribute on function @code{foo}
3362 tells the compiler to assume that
3363 the function @code{foo} is externally defined and that the call to
3364 @code{foo} must avoid the PLT
3365 in position-independent code.
3367 In position-dependent code, a few targets also convert calls to
3368 functions that are marked to not use the PLT to use the GOT instead.
3371 @cindex @code{noreturn} function attribute
3372 @cindex functions that never return
3373 A few standard library functions, such as @code{abort} and @code{exit},
3374 cannot return. GCC knows this automatically. Some programs define
3375 their own functions that never return. You can declare them
3376 @code{noreturn} to tell the compiler this fact. For example,
3380 void fatal () __attribute__ ((noreturn));
3383 fatal (/* @r{@dots{}} */)
3385 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
3391 The @code{noreturn} keyword tells the compiler to assume that
3392 @code{fatal} cannot return. It can then optimize without regard to what
3393 would happen if @code{fatal} ever did return. This makes slightly
3394 better code. More importantly, it helps avoid spurious warnings of
3395 uninitialized variables.
3397 The @code{noreturn} keyword does not affect the exceptional path when that
3398 applies: a @code{noreturn}-marked function may still return to the caller
3399 by throwing an exception or calling @code{longjmp}.
3401 In order to preserve backtraces, GCC will never turn calls to
3402 @code{noreturn} functions into tail calls.
3404 Do not assume that registers saved by the calling function are
3405 restored before calling the @code{noreturn} function.
3407 It does not make sense for a @code{noreturn} function to have a return
3408 type other than @code{void}.
3411 @cindex @code{nothrow} function attribute
3412 The @code{nothrow} attribute is used to inform the compiler that a
3413 function cannot throw an exception. For example, most functions in
3414 the standard C library can be guaranteed not to throw an exception
3415 with the notable exceptions of @code{qsort} and @code{bsearch} that
3416 take function pointer arguments.
3418 @item optimize (@var{level}, @dots{})
3419 @item optimize (@var{string}, @dots{})
3420 @cindex @code{optimize} function attribute
3421 The @code{optimize} attribute is used to specify that a function is to
3422 be compiled with different optimization options than specified on the
3423 command line. Valid arguments are constant non-negative integers and
3424 strings. Each numeric argument specifies an optimization @var{level}.
3425 Each @var{string} argument consists of one or more comma-separated
3426 substrings. Each substring that begins with the letter @code{O} refers
3427 to an optimization option such as @option{-O0} or @option{-Os}. Other
3428 substrings are taken as suffixes to the @code{-f} prefix jointly
3429 forming the name of an optimization option. @xref{Optimize Options}.
3431 @samp{#pragma GCC optimize} can be used to set optimization options
3432 for more than one function. @xref{Function Specific Option Pragmas},
3433 for details about the pragma.
3435 Providing multiple strings as arguments separated by commas to specify
3436 multiple options is equivalent to separating the option suffixes with
3437 a comma (@samp{,}) within a single string. Spaces are not permitted
3440 Not every optimization option that starts with the @var{-f} prefix
3441 specified by the attribute necessarily has an effect on the function.
3442 The @code{optimize} attribute should be used for debugging purposes only.
3443 It is not suitable in production code.
3445 @item patchable_function_entry
3446 @cindex @code{patchable_function_entry} function attribute
3447 @cindex extra NOP instructions at the function entry point
3448 In case the target's text segment can be made writable at run time by
3449 any means, padding the function entry with a number of NOPs can be
3450 used to provide a universal tool for instrumentation.
3452 The @code{patchable_function_entry} function attribute can be used to
3453 change the number of NOPs to any desired value. The two-value syntax
3454 is the same as for the command-line switch
3455 @option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with
3456 the function entry point before the @var{M}th NOP instruction.
3457 @var{M} defaults to 0 if omitted e.g.@: function entry point is before
3460 If patchable function entries are enabled globally using the command-line
3461 option @option{-fpatchable-function-entry=N,M}, then you must disable
3462 instrumentation on all functions that are part of the instrumentation
3463 framework with the attribute @code{patchable_function_entry (0)}
3464 to prevent recursion.
3467 @cindex @code{pure} function attribute
3468 @cindex functions that have no side effects
3470 Calls to functions that have no observable effects on the state of
3471 the program other than to return a value may lend themselves to optimizations
3472 such as common subexpression elimination. Declaring such functions with
3473 the @code{pure} attribute allows GCC to avoid emitting some calls in repeated
3474 invocations of the function with the same argument values.
3476 The @code{pure} attribute prohibits a function from modifying the state
3477 of the program that is observable by means other than inspecting
3478 the function's return value. However, functions declared with the @code{pure}
3479 attribute can safely read any non-volatile objects, and modify the value of
3480 objects in a way that does not affect their return value or the observable
3481 state of the program.
3486 int hash (char *) __attribute__ ((pure));
3490 tells GCC that subsequent calls to the function @code{hash} with the same
3491 string can be replaced by the result of the first call provided the state
3492 of the program observable by @code{hash}, including the contents of the array
3493 itself, does not change in between. Even though @code{hash} takes a non-const
3494 pointer argument it must not modify the array it points to, or any other object
3495 whose value the rest of the program may depend on. However, the caller may
3496 safely change the contents of the array between successive calls to
3497 the function (doing so disables the optimization). The restriction also
3498 applies to member objects referenced by the @code{this} pointer in C++
3499 non-static member functions.
3501 Some common examples of pure functions are @code{strlen} or @code{memcmp}.
3502 Interesting non-pure functions are functions with infinite loops or those
3503 depending on volatile memory or other system resource, that may change between
3504 consecutive calls (such as the standard C @code{feof} function in
3505 a multithreading environment).
3507 The @code{pure} attribute imposes similar but looser restrictions on
3508 a function's definition than the @code{const} attribute: @code{pure}
3509 allows the function to read any non-volatile memory, even if it changes
3510 in between successive invocations of the function. Declaring the same
3511 function with both the @code{pure} and the @code{const} attribute is
3512 diagnosed. Because a pure function cannot have any observable side
3513 effects it does not make sense for such a function to return @code{void}.
3514 Declaring such a function is diagnosed.
3516 @item returns_nonnull
3517 @cindex @code{returns_nonnull} function attribute
3518 The @code{returns_nonnull} attribute specifies that the function
3519 return value should be a non-null pointer. For instance, the declaration:
3523 mymalloc (size_t len) __attribute__((returns_nonnull));
3527 lets the compiler optimize callers based on the knowledge
3528 that the return value will never be null.
3531 @cindex @code{returns_twice} function attribute
3532 @cindex functions that return more than once
3533 The @code{returns_twice} attribute tells the compiler that a function may
3534 return more than one time. The compiler ensures that all registers
3535 are dead before calling such a function and emits a warning about
3536 the variables that may be clobbered after the second return from the
3537 function. Examples of such functions are @code{setjmp} and @code{vfork}.
3538 The @code{longjmp}-like counterpart of such function, if any, might need
3539 to be marked with the @code{noreturn} attribute.
3541 @item section ("@var{section-name}")
3542 @cindex @code{section} function attribute
3543 @cindex functions in arbitrary sections
3544 Normally, the compiler places the code it generates in the @code{text} section.
3545 Sometimes, however, you need additional sections, or you need certain
3546 particular functions to appear in special sections. The @code{section}
3547 attribute specifies that a function lives in a particular section.
3548 For example, the declaration:
3551 extern void foobar (void) __attribute__ ((section ("bar")));
3555 puts the function @code{foobar} in the @code{bar} section.
3557 Some file formats do not support arbitrary sections so the @code{section}
3558 attribute is not available on all platforms.
3559 If you need to map the entire contents of a module to a particular
3560 section, consider using the facilities of the linker instead.
3563 @itemx sentinel (@var{position})
3564 @cindex @code{sentinel} function attribute
3565 This function attribute indicates that an argument in a call to the function
3566 is expected to be an explicit @code{NULL}. The attribute is only valid on
3567 variadic functions. By default, the sentinel is expected to be the last
3568 argument of the function call. If the optional @var{position} argument
3569 is specified to the attribute, the sentinel must be located at
3570 @var{position} counting backwards from the end of the argument list.
3573 __attribute__ ((sentinel))
3575 __attribute__ ((sentinel(0)))
3578 The attribute is automatically set with a position of 0 for the built-in
3579 functions @code{execl} and @code{execlp}. The built-in function
3580 @code{execle} has the attribute set with a position of 1.
3582 A valid @code{NULL} in this context is defined as zero with any object
3583 pointer type. If your system defines the @code{NULL} macro with
3584 an integer type then you need to add an explicit cast. During
3585 installation GCC replaces the system @code{<stddef.h>} header with
3586 a copy that redefines NULL appropriately.
3588 The warnings for missing or incorrect sentinels are enabled with
3592 @itemx simd("@var{mask}")
3593 @cindex @code{simd} function attribute
3594 This attribute enables creation of one or more function versions that
3595 can process multiple arguments using SIMD instructions from a
3596 single invocation. Specifying this attribute allows compiler to
3597 assume that such versions are available at link time (provided
3598 in the same or another translation unit). Generated versions are
3599 target-dependent and described in the corresponding Vector ABI document. For
3600 x86_64 target this document can be found
3601 @w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}.
3603 The optional argument @var{mask} may have the value
3604 @code{notinbranch} or @code{inbranch},
3605 and instructs the compiler to generate non-masked or masked
3606 clones correspondingly. By default, all clones are generated.
3608 If the attribute is specified and @code{#pragma omp declare simd} is
3609 present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd}
3610 switch is specified, then the attribute is ignored.
3613 @cindex @code{stack_protect} function attribute
3614 This attribute adds stack protection code to the function if
3615 flags @option{-fstack-protector}, @option{-fstack-protector-strong}
3616 or @option{-fstack-protector-explicit} are set.
3618 @item target (@var{string}, @dots{})
3619 @cindex @code{target} function attribute
3620 Multiple target back ends implement the @code{target} attribute
3621 to specify that a function is to
3622 be compiled with different target options than specified on the
3623 command line. One or more strings can be provided as arguments.
3624 Each string consists of one or more comma-separated suffixes to
3625 the @code{-m} prefix jointly forming the name of a machine-dependent
3626 option. @xref{Submodel Options,,Machine-Dependent Options}.
3628 The @code{target} attribute can be used for instance to have a function
3629 compiled with a different ISA (instruction set architecture) than the
3630 default. @samp{#pragma GCC target} can be used to specify target-specific
3631 options for more than one function. @xref{Function Specific Option Pragmas},
3632 for details about the pragma.
3634 For instance, on an x86, you could declare one function with the
3635 @code{target("sse4.1,arch=core2")} attribute and another with
3636 @code{target("sse4a,arch=amdfam10")}. This is equivalent to
3637 compiling the first function with @option{-msse4.1} and
3638 @option{-march=core2} options, and the second function with
3639 @option{-msse4a} and @option{-march=amdfam10} options. It is up to you
3640 to make sure that a function is only invoked on a machine that
3641 supports the particular ISA it is compiled for (for example by using
3642 @code{cpuid} on x86 to determine what feature bits and architecture
3646 int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
3647 int sse3_func (void) __attribute__ ((__target__ ("sse3")));
3650 Providing multiple strings as arguments separated by commas to specify
3651 multiple options is equivalent to separating the option suffixes with
3652 a comma (@samp{,}) within a single string. Spaces are not permitted
3655 The options supported are specific to each target; refer to @ref{x86
3656 Function Attributes}, @ref{PowerPC Function Attributes},
3657 @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
3658 @ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
3661 @item target_clones (@var{options})
3662 @cindex @code{target_clones} function attribute
3663 The @code{target_clones} attribute is used to specify that a function
3664 be cloned into multiple versions compiled with different target options
3665 than specified on the command line. The supported options and restrictions
3666 are the same as for @code{target} attribute.
3668 For instance, on an x86, you could compile a function with
3669 @code{target_clones("sse4.1,avx")}. GCC creates two function clones,
3670 one compiled with @option{-msse4.1} and another with @option{-mavx}.
3672 On a PowerPC, you can compile a function with
3673 @code{target_clones("cpu=power9,default")}. GCC will create two
3674 function clones, one compiled with @option{-mcpu=power9} and another
3675 with the default options. GCC must be configured to use GLIBC 2.23 or
3676 newer in order to use the @code{target_clones} attribute.
3678 It also creates a resolver function (see
3679 the @code{ifunc} attribute above) that dynamically selects a clone
3680 suitable for current architecture. The resolver is created only if there
3681 is a usage of a function with @code{target_clones} attribute.
3684 @cindex @code{unused} function attribute
3685 This attribute, attached to a function, means that the function is meant
3686 to be possibly unused. GCC does not produce a warning for this
3690 @cindex @code{used} function attribute
3691 This attribute, attached to a function, means that code must be emitted
3692 for the function even if it appears that the function is not referenced.
3693 This is useful, for example, when the function is referenced only in
3696 When applied to a member function of a C++ class template, the
3697 attribute also means that the function is instantiated if the
3698 class itself is instantiated.
3700 @item visibility ("@var{visibility_type}")
3701 @cindex @code{visibility} function attribute
3702 This attribute affects the linkage of the declaration to which it is attached.
3703 It can be applied to variables (@pxref{Common Variable Attributes}) and types
3704 (@pxref{Common Type Attributes}) as well as functions.
3706 There are four supported @var{visibility_type} values: default,
3707 hidden, protected or internal visibility.
3710 void __attribute__ ((visibility ("protected")))
3711 f () @{ /* @r{Do something.} */; @}
3712 int i __attribute__ ((visibility ("hidden")));
3715 The possible values of @var{visibility_type} correspond to the
3716 visibility settings in the ELF gABI.
3719 @c keep this list of visibilities in alphabetical order.
3722 Default visibility is the normal case for the object file format.
3723 This value is available for the visibility attribute to override other
3724 options that may change the assumed visibility of entities.
3726 On ELF, default visibility means that the declaration is visible to other
3727 modules and, in shared libraries, means that the declared entity may be
3730 On Darwin, default visibility means that the declaration is visible to
3733 Default visibility corresponds to ``external linkage'' in the language.
3736 Hidden visibility indicates that the entity declared has a new
3737 form of linkage, which we call ``hidden linkage''. Two
3738 declarations of an object with hidden linkage refer to the same object
3739 if they are in the same shared object.
3742 Internal visibility is like hidden visibility, but with additional
3743 processor specific semantics. Unless otherwise specified by the
3744 psABI, GCC defines internal visibility to mean that a function is
3745 @emph{never} called from another module. Compare this with hidden
3746 functions which, while they cannot be referenced directly by other
3747 modules, can be referenced indirectly via function pointers. By
3748 indicating that a function cannot be called from outside the module,
3749 GCC may for instance omit the load of a PIC register since it is known
3750 that the calling function loaded the correct value.
3753 Protected visibility is like default visibility except that it
3754 indicates that references within the defining module bind to the
3755 definition in that module. That is, the declared entity cannot be
3756 overridden by another module.
3760 All visibilities are supported on many, but not all, ELF targets
3761 (supported when the assembler supports the @samp{.visibility}
3762 pseudo-op). Default visibility is supported everywhere. Hidden
3763 visibility is supported on Darwin targets.
3765 The visibility attribute should be applied only to declarations that
3766 would otherwise have external linkage. The attribute should be applied
3767 consistently, so that the same entity should not be declared with
3768 different settings of the attribute.
3770 In C++, the visibility attribute applies to types as well as functions
3771 and objects, because in C++ types have linkage. A class must not have
3772 greater visibility than its non-static data member types and bases,
3773 and class members default to the visibility of their class. Also, a
3774 declaration without explicit visibility is limited to the visibility
3777 In C++, you can mark member functions and static member variables of a
3778 class with the visibility attribute. This is useful if you know a
3779 particular method or static member variable should only be used from
3780 one shared object; then you can mark it hidden while the rest of the
3781 class has default visibility. Care must be taken to avoid breaking
3782 the One Definition Rule; for example, it is usually not useful to mark
3783 an inline method as hidden without marking the whole class as hidden.
3785 A C++ namespace declaration can also have the visibility attribute.
3788 namespace nspace1 __attribute__ ((visibility ("protected")))
3789 @{ /* @r{Do something.} */; @}
3792 This attribute applies only to the particular namespace body, not to
3793 other definitions of the same namespace; it is equivalent to using
3794 @samp{#pragma GCC visibility} before and after the namespace
3795 definition (@pxref{Visibility Pragmas}).
3797 In C++, if a template argument has limited visibility, this
3798 restriction is implicitly propagated to the template instantiation.
3799 Otherwise, template instantiations and specializations default to the
3800 visibility of their template.
3802 If both the template and enclosing class have explicit visibility, the
3803 visibility from the template is used.
3805 @item warn_unused_result
3806 @cindex @code{warn_unused_result} function attribute
3807 The @code{warn_unused_result} attribute causes a warning to be emitted
3808 if a caller of the function with this attribute does not use its
3809 return value. This is useful for functions where not checking
3810 the result is either a security problem or always a bug, such as
3814 int fn () __attribute__ ((warn_unused_result));
3817 if (fn () < 0) return -1;
3824 results in warning on line 5.
3827 @cindex @code{weak} function attribute
3828 The @code{weak} attribute causes the declaration to be emitted as a weak
3829 symbol rather than a global. This is primarily useful in defining
3830 library functions that can be overridden in user code, though it can
3831 also be used with non-function declarations. Weak symbols are supported
3832 for ELF targets, and also for a.out targets when using the GNU assembler
3836 @itemx weakref ("@var{target}")
3837 @cindex @code{weakref} function attribute
3838 The @code{weakref} attribute marks a declaration as a weak reference.
3839 Without arguments, it should be accompanied by an @code{alias} attribute
3840 naming the target symbol. Optionally, the @var{target} may be given as
3841 an argument to @code{weakref} itself. In either case, @code{weakref}
3842 implicitly marks the declaration as @code{weak}. Without a
3843 @var{target}, given as an argument to @code{weakref} or to @code{alias},
3844 @code{weakref} is equivalent to @code{weak}.
3847 static int x() __attribute__ ((weakref ("y")));
3848 /* is equivalent to... */
3849 static int x() __attribute__ ((weak, weakref, alias ("y")));
3851 static int x() __attribute__ ((weakref));
3852 static int x() __attribute__ ((alias ("y")));
3855 A weak reference is an alias that does not by itself require a
3856 definition to be given for the target symbol. If the target symbol is
3857 only referenced through weak references, then it becomes a @code{weak}
3858 undefined symbol. If it is directly referenced, however, then such
3859 strong references prevail, and a definition is required for the
3860 symbol, not necessarily in the same translation unit.
3862 The effect is equivalent to moving all references to the alias to a
3863 separate translation unit, renaming the alias to the aliased symbol,
3864 declaring it as weak, compiling the two separate translation units and
3865 performing a link with relocatable output (ie: @code{ld -r}) on them.
3867 At present, a declaration to which @code{weakref} is attached can
3868 only be @code{static}.
3873 @c This is the end of the target-independent attribute table
3875 @node AArch64 Function Attributes
3876 @subsection AArch64 Function Attributes
3878 The following target-specific function attributes are available for the
3879 AArch64 target. For the most part, these options mirror the behavior of
3880 similar command-line options (@pxref{AArch64 Options}), but on a
3884 @item general-regs-only
3885 @cindex @code{general-regs-only} function attribute, AArch64
3886 Indicates that no floating-point or Advanced SIMD registers should be
3887 used when generating code for this function. If the function explicitly
3888 uses floating-point code, then the compiler gives an error. This is
3889 the same behavior as that of the command-line option
3890 @option{-mgeneral-regs-only}.
3892 @item fix-cortex-a53-835769
3893 @cindex @code{fix-cortex-a53-835769} function attribute, AArch64
3894 Indicates that the workaround for the Cortex-A53 erratum 835769 should be
3895 applied to this function. To explicitly disable the workaround for this
3896 function specify the negated form: @code{no-fix-cortex-a53-835769}.
3897 This corresponds to the behavior of the command line options
3898 @option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
3901 @cindex @code{cmodel=} function attribute, AArch64
3902 Indicates that code should be generated for a particular code model for
3903 this function. The behavior and permissible arguments are the same as
3904 for the command line option @option{-mcmodel=}.
3907 @itemx no-strict-align
3908 @cindex @code{strict-align} function attribute, AArch64
3909 @code{strict-align} indicates that the compiler should not assume that unaligned
3910 memory references are handled by the system. To allow the compiler to assume
3911 that aligned memory references are handled by the system, the inverse attribute
3912 @code{no-strict-align} can be specified. The behavior is same as for the
3913 command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
3915 @item omit-leaf-frame-pointer
3916 @cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
3917 Indicates that the frame pointer should be omitted for a leaf function call.
3918 To keep the frame pointer, the inverse attribute
3919 @code{no-omit-leaf-frame-pointer} can be specified. These attributes have
3920 the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
3921 and @option{-mno-omit-leaf-frame-pointer}.
3924 @cindex @code{tls-dialect=} function attribute, AArch64
3925 Specifies the TLS dialect to use for this function. The behavior and
3926 permissible arguments are the same as for the command-line option
3927 @option{-mtls-dialect=}.
3930 @cindex @code{arch=} function attribute, AArch64
3931 Specifies the architecture version and architectural extensions to use
3932 for this function. The behavior and permissible arguments are the same as
3933 for the @option{-march=} command-line option.
3936 @cindex @code{tune=} function attribute, AArch64
3937 Specifies the core for which to tune the performance of this function.
3938 The behavior and permissible arguments are the same as for the @option{-mtune=}
3939 command-line option.
3942 @cindex @code{cpu=} function attribute, AArch64
3943 Specifies the core for which to tune the performance of this function and also
3944 whose architectural features to use. The behavior and valid arguments are the
3945 same as for the @option{-mcpu=} command-line option.
3947 @item sign-return-address
3948 @cindex @code{sign-return-address} function attribute, AArch64
3949 Select the function scope on which return address signing will be applied. The
3950 behavior and permissible arguments are the same as for the command-line option
3951 @option{-msign-return-address=}. The default value is @code{none}. This
3952 attribute is deprecated. The @code{branch-protection} attribute should
3955 @item branch-protection
3956 @cindex @code{branch-protection} function attribute, AArch64
3957 Select the function scope on which branch protection will be applied. The
3958 behavior and permissible arguments are the same as for the command-line option
3959 @option{-mbranch-protection=}. The default value is @code{none}.
3963 The above target attributes can be specified as follows:
3966 __attribute__((target("@var{attr-string}")))
3974 where @code{@var{attr-string}} is one of the attribute strings specified above.
3976 Additionally, the architectural extension string may be specified on its
3977 own. This can be used to turn on and off particular architectural extensions
3978 without having to specify a particular architecture version or core. Example:
3981 __attribute__((target("+crc+nocrypto")))
3989 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
3990 extension and disables the @code{crypto} extension for the function @code{foo}
3991 without modifying an existing @option{-march=} or @option{-mcpu} option.
3993 Multiple target function attributes can be specified by separating them with
3994 a comma. For example:
3996 __attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
4004 is valid and compiles function @code{foo} for ARMv8-A with @code{crc}
4005 and @code{crypto} extensions and tunes it for @code{cortex-a53}.
4007 @subsubsection Inlining rules
4008 Specifying target attributes on individual functions or performing link-time
4009 optimization across translation units compiled with different target options
4010 can affect function inlining rules:
4012 In particular, a caller function can inline a callee function only if the
4013 architectural features available to the callee are a subset of the features
4014 available to the caller.
4015 For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
4016 or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
4017 can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
4018 because the all the architectural features that function @code{bar} requires
4019 are available to function @code{foo}. Conversely, function @code{bar} cannot
4020 inline function @code{foo}.
4022 Additionally inlining a function compiled with @option{-mstrict-align} into a
4023 function compiled without @code{-mstrict-align} is not allowed.
4024 However, inlining a function compiled without @option{-mstrict-align} into a
4025 function compiled with @option{-mstrict-align} is allowed.
4027 Note that CPU tuning options and attributes such as the @option{-mcpu=},
4028 @option{-mtune=} do not inhibit inlining unless the CPU specified by the
4029 @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
4030 architectural feature rules specified above.
4032 @node AMD GCN Function Attributes
4033 @subsection AMD GCN Function Attributes
4035 These function attributes are supported by the AMD GCN back end:
4038 @item amdgpu_hsa_kernel
4039 @cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN
4040 This attribute indicates that the corresponding function should be compiled as
4041 a kernel function, that is an entry point that can be invoked from the host
4042 via the HSA runtime library. By default functions are only callable only from
4043 other GCN functions.
4045 This attribute is implicitly applied to any function named @code{main}, using
4048 Kernel functions may return an integer value, which will be written to a
4049 conventional place within the HSA "kernargs" region.
4051 The attribute parameters configure what values are passed into the kernel
4052 function by the GPU drivers, via the initial register state. Some values are
4053 used by the compiler, and therefore forced on. Enabling other options may
4054 break assumptions in the compiler and/or run-time libraries.
4057 @item private_segment_buffer
4058 Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to
4062 Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the
4066 Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address
4069 @item kernarg_segment_ptr
4070 Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to
4071 locate the kernel arguments, "kernargs").
4074 Set @code{enable_sgpr_dispatch_id} flag.
4076 @item flat_scratch_init
4077 Set @code{enable_sgpr_flat_scratch_init} flag.
4079 @item private_segment_size
4080 Set @code{enable_sgpr_private_segment_size} flag.
4082 @item grid_workgroup_count_X
4083 Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to
4084 use OpenACC/OpenMP).
4086 @item grid_workgroup_count_Y
4087 Set @code{enable_sgpr_grid_workgroup_count_y} flag.
4089 @item grid_workgroup_count_Z
4090 Set @code{enable_sgpr_grid_workgroup_count_z} flag.
4092 @item workgroup_id_X
4093 Set @code{enable_sgpr_workgroup_id_x} flag.
4095 @item workgroup_id_Y
4096 Set @code{enable_sgpr_workgroup_id_y} flag.
4098 @item workgroup_id_Z
4099 Set @code{enable_sgpr_workgroup_id_z} flag.
4101 @item workgroup_info
4102 Set @code{enable_sgpr_workgroup_info} flag.
4104 @item private_segment_wave_offset
4105 Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on
4106 (required to locate the stack).
4108 @item work_item_id_X
4109 Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled).
4111 @item work_item_id_Y
4112 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable
4115 @item work_item_id_Z
4116 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use
4122 @node ARC Function Attributes
4123 @subsection ARC Function Attributes
4125 These function attributes are supported by the ARC back end:
4129 @cindex @code{interrupt} function attribute, ARC
4130 Use this attribute to indicate
4131 that the specified function is an interrupt handler. The compiler generates
4132 function entry and exit sequences suitable for use in an interrupt handler
4133 when this attribute is present.
4135 On the ARC, you must specify the kind of interrupt to be handled
4136 in a parameter to the interrupt attribute like this:
4139 void f () __attribute__ ((interrupt ("ilink1")));
4142 Permissible values for this parameter are: @w{@code{ilink1}} and
4143 @w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and
4144 @w{@code{firq}} for ARCv2 architecture.
4149 @cindex @code{long_call} function attribute, ARC
4150 @cindex @code{medium_call} function attribute, ARC
4151 @cindex @code{short_call} function attribute, ARC
4152 @cindex indirect calls, ARC
4153 These attributes specify how a particular function is called.
4154 These attributes override the
4155 @option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
4156 command-line switches and @code{#pragma long_calls} settings.
4158 For ARC, a function marked with the @code{long_call} attribute is
4159 always called using register-indirect jump-and-link instructions,
4160 thereby enabling the called function to be placed anywhere within the
4161 32-bit address space. A function marked with the @code{medium_call}
4162 attribute will always be close enough to be called with an unconditional
4163 branch-and-link instruction, which has a 25-bit offset from
4164 the call site. A function marked with the @code{short_call}
4165 attribute will always be close enough to be called with a conditional
4166 branch-and-link instruction, which has a 21-bit offset from
4170 @cindex @code{jli_always} function attribute, ARC
4171 Forces a particular function to be called using @code{jli}
4172 instruction. The @code{jli} instruction makes use of a table stored
4173 into @code{.jlitab} section, which holds the location of the functions
4174 which are addressed using this instruction.
4177 @cindex @code{jli_fixed} function attribute, ARC
4178 Identical like the above one, but the location of the function in the
4179 @code{jli} table is known and given as an attribute parameter.
4182 @cindex @code{secure_call} function attribute, ARC
4183 This attribute allows one to mark secure-code functions that are
4184 callable from normal mode. The location of the secure call function
4185 into the @code{sjli} table needs to be passed as argument.
4188 @cindex @code{naked} function attribute, ARC
4189 This attribute allows the compiler to construct the requisite function
4190 declaration, while allowing the body of the function to be assembly
4191 code. The specified function will not have prologue/epilogue
4192 sequences generated by the compiler. Only basic @code{asm} statements
4193 can safely be included in naked functions (@pxref{Basic Asm}). While
4194 using extended @code{asm} or a mixture of basic @code{asm} and C code
4195 may appear to work, they cannot be depended upon to work reliably and
4200 @node ARM Function Attributes
4201 @subsection ARM Function Attributes
4203 These function attributes are supported for ARM targets:
4207 @item general-regs-only
4208 @cindex @code{general-regs-only} function attribute, ARM
4209 Indicates that no floating-point or Advanced SIMD registers should be
4210 used when generating code for this function. If the function explicitly
4211 uses floating-point code, then the compiler gives an error. This is
4212 the same behavior as that of the command-line option
4213 @option{-mgeneral-regs-only}.
4216 @cindex @code{interrupt} function attribute, ARM
4217 Use this attribute to indicate
4218 that the specified function is an interrupt handler. The compiler generates
4219 function entry and exit sequences suitable for use in an interrupt handler
4220 when this attribute is present.
4222 You can specify the kind of interrupt to be handled by
4223 adding an optional parameter to the interrupt attribute like this:
4226 void f () __attribute__ ((interrupt ("IRQ")));
4230 Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
4231 @code{SWI}, @code{ABORT} and @code{UNDEF}.
4233 On ARMv7-M the interrupt type is ignored, and the attribute means the function
4234 may be called with a word-aligned stack pointer.
4237 @cindex @code{isr} function attribute, ARM
4238 Use this attribute on ARM to write Interrupt Service Routines. This is an
4239 alias to the @code{interrupt} attribute above.
4243 @cindex @code{long_call} function attribute, ARM
4244 @cindex @code{short_call} function attribute, ARM
4245 @cindex indirect calls, ARM
4246 These attributes specify how a particular function is called.
4247 These attributes override the
4248 @option{-mlong-calls} (@pxref{ARM Options})
4249 command-line switch and @code{#pragma long_calls} settings. For ARM, the
4250 @code{long_call} attribute indicates that the function might be far
4251 away from the call site and require a different (more expensive)
4252 calling sequence. The @code{short_call} attribute always places
4253 the offset to the function from the call site into the @samp{BL}
4254 instruction directly.
4257 @cindex @code{naked} function attribute, ARM
4258 This attribute allows the compiler to construct the
4259 requisite function declaration, while allowing the body of the
4260 function to be assembly code. The specified function will not have
4261 prologue/epilogue sequences generated by the compiler. Only basic
4262 @code{asm} statements can safely be included in naked functions
4263 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4264 basic @code{asm} and C code may appear to work, they cannot be
4265 depended upon to work reliably and are not supported.
4268 @cindex @code{pcs} function attribute, ARM
4270 The @code{pcs} attribute can be used to control the calling convention
4271 used for a function on ARM. The attribute takes an argument that specifies
4272 the calling convention to use.
4274 When compiling using the AAPCS ABI (or a variant of it) then valid
4275 values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
4276 order to use a variant other than @code{"aapcs"} then the compiler must
4277 be permitted to use the appropriate co-processor registers (i.e., the
4278 VFP registers must be available in order to use @code{"aapcs-vfp"}).
4282 /* Argument passed in r0, and result returned in r0+r1. */
4283 double f2d (float) __attribute__((pcs("aapcs")));
4286 Variadic functions always use the @code{"aapcs"} calling convention and
4287 the compiler rejects attempts to specify an alternative.
4289 @item target (@var{options})
4290 @cindex @code{target} function attribute
4291 As discussed in @ref{Common Function Attributes}, this attribute
4292 allows specification of target-specific compilation options.
4294 On ARM, the following options are allowed:
4298 @cindex @code{target("thumb")} function attribute, ARM
4299 Force code generation in the Thumb (T16/T32) ISA, depending on the
4303 @cindex @code{target("arm")} function attribute, ARM
4304 Force code generation in the ARM (A32) ISA.
4306 Functions from different modes can be inlined in the caller's mode.
4309 @cindex @code{target("fpu=")} function attribute, ARM
4310 Specifies the fpu for which to tune the performance of this function.
4311 The behavior and permissible arguments are the same as for the @option{-mfpu=}
4312 command-line option.
4315 @cindex @code{arch=} function attribute, ARM
4316 Specifies the architecture version and architectural extensions to use
4317 for this function. The behavior and permissible arguments are the same as
4318 for the @option{-march=} command-line option.
4320 The above target attributes can be specified as follows:
4323 __attribute__((target("arch=armv8-a+crc")))
4331 Additionally, the architectural extension string may be specified on its
4332 own. This can be used to turn on and off particular architectural extensions
4333 without having to specify a particular architecture version or core. Example:
4336 __attribute__((target("+crc+nocrypto")))
4344 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
4345 extension and disables the @code{crypto} extension for the function @code{foo}
4346 without modifying an existing @option{-march=} or @option{-mcpu} option.
4352 @node AVR Function Attributes
4353 @subsection AVR Function Attributes
4355 These function attributes are supported by the AVR back end:
4359 @cindex @code{interrupt} function attribute, AVR
4360 Use this attribute to indicate
4361 that the specified function is an interrupt handler. The compiler generates
4362 function entry and exit sequences suitable for use in an interrupt handler
4363 when this attribute is present.
4365 On the AVR, the hardware globally disables interrupts when an
4366 interrupt is executed. The first instruction of an interrupt handler
4367 declared with this attribute is a @code{SEI} instruction to
4368 re-enable interrupts. See also the @code{signal} function attribute
4369 that does not insert a @code{SEI} instruction. If both @code{signal} and
4370 @code{interrupt} are specified for the same function, @code{signal}
4371 is silently ignored.
4374 @cindex @code{naked} function attribute, AVR
4375 This attribute allows the compiler to construct the
4376 requisite function declaration, while allowing the body of the
4377 function to be assembly code. The specified function will not have
4378 prologue/epilogue sequences generated by the compiler. Only basic
4379 @code{asm} statements can safely be included in naked functions
4380 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4381 basic @code{asm} and C code may appear to work, they cannot be
4382 depended upon to work reliably and are not supported.
4385 @cindex @code{no_gccisr} function attribute, AVR
4386 Do not use @code{__gcc_isr} pseudo instructions in a function with
4387 the @code{interrupt} or @code{signal} attribute aka. interrupt
4388 service routine (ISR).
4389 Use this attribute if the preamble of the ISR prologue should always read
4393 in __tmp_reg__, __SREG__
4397 and accordingly for the postamble of the epilogue --- no matter whether
4398 the mentioned registers are actually used in the ISR or not.
4399 Situations where you might want to use this attribute include:
4402 Code that (effectively) clobbers bits of @code{SREG} other than the
4403 @code{I}-flag by writing to the memory location of @code{SREG}.
4405 Code that uses inline assembler to jump to a different function which
4406 expects (parts of) the prologue code as outlined above to be present.
4408 To disable @code{__gcc_isr} generation for the whole compilation unit,
4409 there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}.
4413 @cindex @code{OS_main} function attribute, AVR
4414 @cindex @code{OS_task} function attribute, AVR
4415 On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
4416 do not save/restore any call-saved register in their prologue/epilogue.
4418 The @code{OS_main} attribute can be used when there @emph{is
4419 guarantee} that interrupts are disabled at the time when the function
4420 is entered. This saves resources when the stack pointer has to be
4421 changed to set up a frame for local variables.
4423 The @code{OS_task} attribute can be used when there is @emph{no
4424 guarantee} that interrupts are disabled at that time when the function
4425 is entered like for, e@.g@. task functions in a multi-threading operating
4426 system. In that case, changing the stack pointer register is
4427 guarded by save/clear/restore of the global interrupt enable flag.
4429 The differences to the @code{naked} function attribute are:
4431 @item @code{naked} functions do not have a return instruction whereas
4432 @code{OS_main} and @code{OS_task} functions have a @code{RET} or
4433 @code{RETI} return instruction.
4434 @item @code{naked} functions do not set up a frame for local variables
4435 or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
4440 @cindex @code{signal} function attribute, AVR
4441 Use this attribute on the AVR to indicate that the specified
4442 function is an interrupt handler. The compiler generates function
4443 entry and exit sequences suitable for use in an interrupt handler when this
4444 attribute is present.
4446 See also the @code{interrupt} function attribute.
4448 The AVR hardware globally disables interrupts when an interrupt is executed.
4449 Interrupt handler functions defined with the @code{signal} attribute
4450 do not re-enable interrupts. It is save to enable interrupts in a
4451 @code{signal} handler. This ``save'' only applies to the code
4452 generated by the compiler and not to the IRQ layout of the
4453 application which is responsibility of the application.
4455 If both @code{signal} and @code{interrupt} are specified for the same
4456 function, @code{signal} is silently ignored.
4459 @node Blackfin Function Attributes
4460 @subsection Blackfin Function Attributes
4462 These function attributes are supported by the Blackfin back end:
4466 @item exception_handler
4467 @cindex @code{exception_handler} function attribute
4468 @cindex exception handler functions, Blackfin
4469 Use this attribute on the Blackfin to indicate that the specified function
4470 is an exception handler. The compiler generates function entry and
4471 exit sequences suitable for use in an exception handler when this
4472 attribute is present.
4474 @item interrupt_handler
4475 @cindex @code{interrupt_handler} function attribute, Blackfin
4476 Use this attribute to
4477 indicate that the specified function is an interrupt handler. The compiler
4478 generates function entry and exit sequences suitable for use in an
4479 interrupt handler when this attribute is present.
4482 @cindex @code{kspisusp} function attribute, Blackfin
4483 @cindex User stack pointer in interrupts on the Blackfin
4484 When used together with @code{interrupt_handler}, @code{exception_handler}
4485 or @code{nmi_handler}, code is generated to load the stack pointer
4486 from the USP register in the function prologue.
4489 @cindex @code{l1_text} function attribute, Blackfin
4490 This attribute specifies a function to be placed into L1 Instruction
4491 SRAM@. The function is put into a specific section named @code{.l1.text}.
4492 With @option{-mfdpic}, function calls with a such function as the callee
4493 or caller uses inlined PLT.
4496 @cindex @code{l2} function attribute, Blackfin
4497 This attribute specifies a function to be placed into L2
4498 SRAM. The function is put into a specific section named
4499 @code{.l2.text}. With @option{-mfdpic}, callers of such functions use
4504 @cindex indirect calls, Blackfin
4505 @cindex @code{longcall} function attribute, Blackfin
4506 @cindex @code{shortcall} function attribute, Blackfin
4507 The @code{longcall} attribute
4508 indicates that the function might be far away from the call site and
4509 require a different (more expensive) calling sequence. The
4510 @code{shortcall} attribute indicates that the function is always close
4511 enough for the shorter calling sequence to be used. These attributes
4512 override the @option{-mlongcall} switch.
4515 @cindex @code{nesting} function attribute, Blackfin
4516 @cindex Allow nesting in an interrupt handler on the Blackfin processor
4517 Use this attribute together with @code{interrupt_handler},
4518 @code{exception_handler} or @code{nmi_handler} to indicate that the function
4519 entry code should enable nested interrupts or exceptions.
4522 @cindex @code{nmi_handler} function attribute, Blackfin
4523 @cindex NMI handler functions on the Blackfin processor
4524 Use this attribute on the Blackfin to indicate that the specified function
4525 is an NMI handler. The compiler generates function entry and
4526 exit sequences suitable for use in an NMI handler when this
4527 attribute is present.
4530 @cindex @code{saveall} function attribute, Blackfin
4531 @cindex save all registers on the Blackfin
4532 Use this attribute to indicate that
4533 all registers except the stack pointer should be saved in the prologue
4534 regardless of whether they are used or not.
4537 @node CR16 Function Attributes
4538 @subsection CR16 Function Attributes
4540 These function attributes are supported by the CR16 back end:
4544 @cindex @code{interrupt} function attribute, CR16
4545 Use this attribute to indicate
4546 that the specified function is an interrupt handler. The compiler generates
4547 function entry and exit sequences suitable for use in an interrupt handler
4548 when this attribute is present.
4551 @node C-SKY Function Attributes
4552 @subsection C-SKY Function Attributes
4554 These function attributes are supported by the C-SKY back end:
4559 @cindex @code{interrupt} function attribute, C-SKY
4560 @cindex @code{isr} function attribute, C-SKY
4561 Use these attributes to indicate that the specified function
4562 is an interrupt handler.
4563 The compiler generates function entry and exit sequences suitable for
4564 use in an interrupt handler when either of these attributes are present.
4566 Use of these options requires the @option{-mistack} command-line option
4567 to enable support for the necessary interrupt stack instructions. They
4568 are ignored with a warning otherwise. @xref{C-SKY Options}.
4571 @cindex @code{naked} function attribute, C-SKY
4572 This attribute allows the compiler to construct the
4573 requisite function declaration, while allowing the body of the
4574 function to be assembly code. The specified function will not have
4575 prologue/epilogue sequences generated by the compiler. Only basic
4576 @code{asm} statements can safely be included in naked functions
4577 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4578 basic @code{asm} and C code may appear to work, they cannot be
4579 depended upon to work reliably and are not supported.
4583 @node Epiphany Function Attributes
4584 @subsection Epiphany Function Attributes
4586 These function attributes are supported by the Epiphany back end:
4590 @cindex @code{disinterrupt} function attribute, Epiphany
4591 This attribute causes the compiler to emit
4592 instructions to disable interrupts for the duration of the given
4595 @item forwarder_section
4596 @cindex @code{forwarder_section} function attribute, Epiphany
4597 This attribute modifies the behavior of an interrupt handler.
4598 The interrupt handler may be in external memory which cannot be
4599 reached by a branch instruction, so generate a local memory trampoline
4600 to transfer control. The single parameter identifies the section where
4601 the trampoline is placed.
4604 @cindex @code{interrupt} function attribute, Epiphany
4605 Use this attribute to indicate
4606 that the specified function is an interrupt handler. The compiler generates
4607 function entry and exit sequences suitable for use in an interrupt handler
4608 when this attribute is present. It may also generate
4609 a special section with code to initialize the interrupt vector table.
4611 On Epiphany targets one or more optional parameters can be added like this:
4614 void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
4617 Permissible values for these parameters are: @w{@code{reset}},
4618 @w{@code{software_exception}}, @w{@code{page_miss}},
4619 @w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
4620 @w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
4621 Multiple parameters indicate that multiple entries in the interrupt
4622 vector table should be initialized for this function, i.e.@: for each
4623 parameter @w{@var{name}}, a jump to the function is emitted in
4624 the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
4625 entirely, in which case no interrupt vector table entry is provided.
4627 Note that interrupts are enabled inside the function
4628 unless the @code{disinterrupt} attribute is also specified.
4630 The following examples are all valid uses of these attributes on
4633 void __attribute__ ((interrupt)) universal_handler ();
4634 void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
4635 void __attribute__ ((interrupt ("dma0, dma1")))
4636 universal_dma_handler ();
4637 void __attribute__ ((interrupt ("timer0"), disinterrupt))
4638 fast_timer_handler ();
4639 void __attribute__ ((interrupt ("dma0, dma1"),
4640 forwarder_section ("tramp")))
4641 external_dma_handler ();
4646 @cindex @code{long_call} function attribute, Epiphany
4647 @cindex @code{short_call} function attribute, Epiphany
4648 @cindex indirect calls, Epiphany
4649 These attributes specify how a particular function is called.
4650 These attributes override the
4651 @option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
4652 command-line switch and @code{#pragma long_calls} settings.
4656 @node H8/300 Function Attributes
4657 @subsection H8/300 Function Attributes
4659 These function attributes are available for H8/300 targets:
4662 @item function_vector
4663 @cindex @code{function_vector} function attribute, H8/300
4664 Use this attribute on the H8/300, H8/300H, and H8S to indicate
4665 that the specified function should be called through the function vector.
4666 Calling a function through the function vector reduces code size; however,
4667 the function vector has a limited size (maximum 128 entries on the H8/300
4668 and 64 entries on the H8/300H and H8S)
4669 and shares space with the interrupt vector.
4671 @item interrupt_handler
4672 @cindex @code{interrupt_handler} function attribute, H8/300
4673 Use this attribute on the H8/300, H8/300H, and H8S to
4674 indicate that the specified function is an interrupt handler. The compiler
4675 generates function entry and exit sequences suitable for use in an
4676 interrupt handler when this attribute is present.
4679 @cindex @code{saveall} function attribute, H8/300
4680 @cindex save all registers on the H8/300, H8/300H, and H8S
4681 Use this attribute on the H8/300, H8/300H, and H8S to indicate that
4682 all registers except the stack pointer should be saved in the prologue
4683 regardless of whether they are used or not.
4686 @node IA-64 Function Attributes
4687 @subsection IA-64 Function Attributes
4689 These function attributes are supported on IA-64 targets:
4692 @item syscall_linkage
4693 @cindex @code{syscall_linkage} function attribute, IA-64
4694 This attribute is used to modify the IA-64 calling convention by marking
4695 all input registers as live at all function exits. This makes it possible
4696 to restart a system call after an interrupt without having to save/restore
4697 the input registers. This also prevents kernel data from leaking into
4701 @cindex @code{version_id} function attribute, IA-64
4702 This IA-64 HP-UX attribute, attached to a global variable or function, renames a
4703 symbol to contain a version string, thus allowing for function level
4704 versioning. HP-UX system header files may use function level versioning
4705 for some system calls.
4708 extern int foo () __attribute__((version_id ("20040821")));
4712 Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
4715 @node M32C Function Attributes
4716 @subsection M32C Function Attributes
4718 These function attributes are supported by the M32C back end:
4722 @cindex @code{bank_switch} function attribute, M32C
4723 When added to an interrupt handler with the M32C port, causes the
4724 prologue and epilogue to use bank switching to preserve the registers
4725 rather than saving them on the stack.
4727 @item fast_interrupt
4728 @cindex @code{fast_interrupt} function attribute, M32C
4729 Use this attribute on the M32C port to indicate that the specified
4730 function is a fast interrupt handler. This is just like the
4731 @code{interrupt} attribute, except that @code{freit} is used to return
4732 instead of @code{reit}.
4734 @item function_vector
4735 @cindex @code{function_vector} function attribute, M16C/M32C
4736 On M16C/M32C targets, the @code{function_vector} attribute declares a
4737 special page subroutine call function. Use of this attribute reduces
4738 the code size by 2 bytes for each call generated to the
4739 subroutine. The argument to the attribute is the vector number entry
4740 from the special page vector table which contains the 16 low-order
4741 bits of the subroutine's entry address. Each vector table has special
4742 page number (18 to 255) that is used in @code{jsrs} instructions.
4743 Jump addresses of the routines are generated by adding 0x0F0000 (in
4744 case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
4745 2-byte addresses set in the vector table. Therefore you need to ensure
4746 that all the special page vector routines should get mapped within the
4747 address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
4750 In the following example 2 bytes are saved for each call to
4751 function @code{foo}.
4754 void foo (void) __attribute__((function_vector(0x18)));
4765 If functions are defined in one file and are called in another file,
4766 then be sure to write this declaration in both files.
4768 This attribute is ignored for R8C target.
4771 @cindex @code{interrupt} function attribute, M32C
4772 Use this attribute to indicate
4773 that the specified function is an interrupt handler. The compiler generates
4774 function entry and exit sequences suitable for use in an interrupt handler
4775 when this attribute is present.
4778 @node M32R/D Function Attributes
4779 @subsection M32R/D Function Attributes
4781 These function attributes are supported by the M32R/D back end:
4785 @cindex @code{interrupt} function attribute, M32R/D
4786 Use this attribute to indicate
4787 that the specified function is an interrupt handler. The compiler generates
4788 function entry and exit sequences suitable for use in an interrupt handler
4789 when this attribute is present.
4791 @item model (@var{model-name})
4792 @cindex @code{model} function attribute, M32R/D
4793 @cindex function addressability on the M32R/D
4795 On the M32R/D, use this attribute to set the addressability of an
4796 object, and of the code generated for a function. The identifier
4797 @var{model-name} is one of @code{small}, @code{medium}, or
4798 @code{large}, representing each of the code models.
4800 Small model objects live in the lower 16MB of memory (so that their
4801 addresses can be loaded with the @code{ld24} instruction), and are
4802 callable with the @code{bl} instruction.
4804 Medium model objects may live anywhere in the 32-bit address space (the
4805 compiler generates @code{seth/add3} instructions to load their addresses),
4806 and are callable with the @code{bl} instruction.
4808 Large model objects may live anywhere in the 32-bit address space (the
4809 compiler generates @code{seth/add3} instructions to load their addresses),
4810 and may not be reachable with the @code{bl} instruction (the compiler
4811 generates the much slower @code{seth/add3/jl} instruction sequence).
4814 @node m68k Function Attributes
4815 @subsection m68k Function Attributes
4817 These function attributes are supported by the m68k back end:
4821 @itemx interrupt_handler
4822 @cindex @code{interrupt} function attribute, m68k
4823 @cindex @code{interrupt_handler} function attribute, m68k
4824 Use this attribute to
4825 indicate that the specified function is an interrupt handler. The compiler
4826 generates function entry and exit sequences suitable for use in an
4827 interrupt handler when this attribute is present. Either name may be used.
4829 @item interrupt_thread
4830 @cindex @code{interrupt_thread} function attribute, fido
4831 Use this attribute on fido, a subarchitecture of the m68k, to indicate
4832 that the specified function is an interrupt handler that is designed
4833 to run as a thread. The compiler omits generate prologue/epilogue
4834 sequences and replaces the return instruction with a @code{sleep}
4835 instruction. This attribute is available only on fido.
4838 @node MCORE Function Attributes
4839 @subsection MCORE Function Attributes
4841 These function attributes are supported by the MCORE back end:
4845 @cindex @code{naked} function attribute, MCORE
4846 This attribute allows the compiler to construct the
4847 requisite function declaration, while allowing the body of the
4848 function to be assembly code. The specified function will not have
4849 prologue/epilogue sequences generated by the compiler. Only basic
4850 @code{asm} statements can safely be included in naked functions
4851 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4852 basic @code{asm} and C code may appear to work, they cannot be
4853 depended upon to work reliably and are not supported.
4856 @node MeP Function Attributes
4857 @subsection MeP Function Attributes
4859 These function attributes are supported by the MeP back end:
4863 @cindex @code{disinterrupt} function attribute, MeP
4864 On MeP targets, this attribute causes the compiler to emit
4865 instructions to disable interrupts for the duration of the given
4869 @cindex @code{interrupt} function attribute, MeP
4870 Use this attribute to indicate
4871 that the specified function is an interrupt handler. The compiler generates
4872 function entry and exit sequences suitable for use in an interrupt handler
4873 when this attribute is present.
4876 @cindex @code{near} function attribute, MeP
4877 This attribute causes the compiler to assume the called
4878 function is close enough to use the normal calling convention,
4879 overriding the @option{-mtf} command-line option.
4882 @cindex @code{far} function attribute, MeP
4883 On MeP targets this causes the compiler to use a calling convention
4884 that assumes the called function is too far away for the built-in
4888 @cindex @code{vliw} function attribute, MeP
4889 The @code{vliw} attribute tells the compiler to emit
4890 instructions in VLIW mode instead of core mode. Note that this
4891 attribute is not allowed unless a VLIW coprocessor has been configured
4892 and enabled through command-line options.
4895 @node MicroBlaze Function Attributes
4896 @subsection MicroBlaze Function Attributes
4898 These function attributes are supported on MicroBlaze targets:
4901 @item save_volatiles
4902 @cindex @code{save_volatiles} function attribute, MicroBlaze
4903 Use this attribute to indicate that the function is
4904 an interrupt handler. All volatile registers (in addition to non-volatile
4905 registers) are saved in the function prologue. If the function is a leaf
4906 function, only volatiles used by the function are saved. A normal function
4907 return is generated instead of a return from interrupt.
4910 @cindex @code{break_handler} function attribute, MicroBlaze
4911 @cindex break handler functions
4912 Use this attribute to indicate that
4913 the specified function is a break handler. The compiler generates function
4914 entry and exit sequences suitable for use in an break handler when this
4915 attribute is present. The return from @code{break_handler} is done through
4916 the @code{rtbd} instead of @code{rtsd}.
4919 void f () __attribute__ ((break_handler));
4922 @item interrupt_handler
4923 @itemx fast_interrupt
4924 @cindex @code{interrupt_handler} function attribute, MicroBlaze
4925 @cindex @code{fast_interrupt} function attribute, MicroBlaze
4926 These attributes indicate that the specified function is an interrupt
4927 handler. Use the @code{fast_interrupt} attribute to indicate handlers
4928 used in low-latency interrupt mode, and @code{interrupt_handler} for
4929 interrupts that do not use low-latency handlers. In both cases, GCC
4930 emits appropriate prologue code and generates a return from the handler
4931 using @code{rtid} instead of @code{rtsd}.
4934 @node Microsoft Windows Function Attributes
4935 @subsection Microsoft Windows Function Attributes
4937 The following attributes are available on Microsoft Windows and Symbian OS
4942 @cindex @code{dllexport} function attribute
4943 @cindex @code{__declspec(dllexport)}
4944 On Microsoft Windows targets and Symbian OS targets the
4945 @code{dllexport} attribute causes the compiler to provide a global
4946 pointer to a pointer in a DLL, so that it can be referenced with the
4947 @code{dllimport} attribute. On Microsoft Windows targets, the pointer
4948 name is formed by combining @code{_imp__} and the function or variable
4951 You can use @code{__declspec(dllexport)} as a synonym for
4952 @code{__attribute__ ((dllexport))} for compatibility with other
4955 On systems that support the @code{visibility} attribute, this
4956 attribute also implies ``default'' visibility. It is an error to
4957 explicitly specify any other visibility.
4959 GCC's default behavior is to emit all inline functions with the
4960 @code{dllexport} attribute. Since this can cause object file-size bloat,
4961 you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
4962 ignore the attribute for inlined functions unless the
4963 @option{-fkeep-inline-functions} flag is used instead.
4965 The attribute is ignored for undefined symbols.
4967 When applied to C++ classes, the attribute marks defined non-inlined
4968 member functions and static data members as exports. Static consts
4969 initialized in-class are not marked unless they are also defined
4972 For Microsoft Windows targets there are alternative methods for
4973 including the symbol in the DLL's export table such as using a
4974 @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
4975 the @option{--export-all} linker flag.
4978 @cindex @code{dllimport} function attribute
4979 @cindex @code{__declspec(dllimport)}
4980 On Microsoft Windows and Symbian OS targets, the @code{dllimport}
4981 attribute causes the compiler to reference a function or variable via
4982 a global pointer to a pointer that is set up by the DLL exporting the
4983 symbol. The attribute implies @code{extern}. On Microsoft Windows
4984 targets, the pointer name is formed by combining @code{_imp__} and the
4985 function or variable name.
4987 You can use @code{__declspec(dllimport)} as a synonym for
4988 @code{__attribute__ ((dllimport))} for compatibility with other
4991 On systems that support the @code{visibility} attribute, this
4992 attribute also implies ``default'' visibility. It is an error to
4993 explicitly specify any other visibility.
4995 Currently, the attribute is ignored for inlined functions. If the
4996 attribute is applied to a symbol @emph{definition}, an error is reported.
4997 If a symbol previously declared @code{dllimport} is later defined, the
4998 attribute is ignored in subsequent references, and a warning is emitted.
4999 The attribute is also overridden by a subsequent declaration as
5002 When applied to C++ classes, the attribute marks non-inlined
5003 member functions and static data members as imports. However, the
5004 attribute is ignored for virtual methods to allow creation of vtables
5007 On the SH Symbian OS target the @code{dllimport} attribute also has
5008 another affect---it can cause the vtable and run-time type information
5009 for a class to be exported. This happens when the class has a
5010 dllimported constructor or a non-inline, non-pure virtual function
5011 and, for either of those two conditions, the class also has an inline
5012 constructor or destructor and has a key function that is defined in
5013 the current translation unit.
5015 For Microsoft Windows targets the use of the @code{dllimport}
5016 attribute on functions is not necessary, but provides a small
5017 performance benefit by eliminating a thunk in the DLL@. The use of the
5018 @code{dllimport} attribute on imported variables can be avoided by passing the
5019 @option{--enable-auto-import} switch to the GNU linker. As with
5020 functions, using the attribute for a variable eliminates a thunk in
5023 One drawback to using this attribute is that a pointer to a
5024 @emph{variable} marked as @code{dllimport} cannot be used as a constant
5025 address. However, a pointer to a @emph{function} with the
5026 @code{dllimport} attribute can be used as a constant initializer; in
5027 this case, the address of a stub function in the import lib is
5028 referenced. On Microsoft Windows targets, the attribute can be disabled
5029 for functions by setting the @option{-mnop-fun-dllimport} flag.
5032 @node MIPS Function Attributes
5033 @subsection MIPS Function Attributes
5035 These function attributes are supported by the MIPS back end:
5039 @cindex @code{interrupt} function attribute, MIPS
5040 Use this attribute to indicate that the specified function is an interrupt
5041 handler. The compiler generates function entry and exit sequences suitable
5042 for use in an interrupt handler when this attribute is present.
5043 An optional argument is supported for the interrupt attribute which allows
5044 the interrupt mode to be described. By default GCC assumes the external
5045 interrupt controller (EIC) mode is in use, this can be explicitly set using
5046 @code{eic}. When interrupts are non-masked then the requested Interrupt
5047 Priority Level (IPL) is copied to the current IPL which has the effect of only
5048 enabling higher priority interrupts. To use vectored interrupt mode use
5049 the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
5050 the behavior of the non-masked interrupt support and GCC will arrange to mask
5051 all interrupts from sw0 up to and including the specified interrupt vector.
5053 You can use the following attributes to modify the behavior
5054 of an interrupt handler:
5056 @item use_shadow_register_set
5057 @cindex @code{use_shadow_register_set} function attribute, MIPS
5058 Assume that the handler uses a shadow register set, instead of
5059 the main general-purpose registers. An optional argument @code{intstack} is
5060 supported to indicate that the shadow register set contains a valid stack
5063 @item keep_interrupts_masked
5064 @cindex @code{keep_interrupts_masked} function attribute, MIPS
5065 Keep interrupts masked for the whole function. Without this attribute,
5066 GCC tries to reenable interrupts for as much of the function as it can.
5068 @item use_debug_exception_return
5069 @cindex @code{use_debug_exception_return} function attribute, MIPS
5070 Return using the @code{deret} instruction. Interrupt handlers that don't
5071 have this attribute return using @code{eret} instead.
5074 You can use any combination of these attributes, as shown below:
5076 void __attribute__ ((interrupt)) v0 ();
5077 void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
5078 void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
5079 void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
5080 void __attribute__ ((interrupt, use_shadow_register_set,
5081 keep_interrupts_masked)) v4 ();
5082 void __attribute__ ((interrupt, use_shadow_register_set,
5083 use_debug_exception_return)) v5 ();
5084 void __attribute__ ((interrupt, keep_interrupts_masked,
5085 use_debug_exception_return)) v6 ();
5086 void __attribute__ ((interrupt, use_shadow_register_set,
5087 keep_interrupts_masked,
5088 use_debug_exception_return)) v7 ();
5089 void __attribute__ ((interrupt("eic"))) v8 ();
5090 void __attribute__ ((interrupt("vector=hw3"))) v9 ();
5097 @cindex indirect calls, MIPS
5098 @cindex @code{long_call} function attribute, MIPS
5099 @cindex @code{short_call} function attribute, MIPS
5100 @cindex @code{near} function attribute, MIPS
5101 @cindex @code{far} function attribute, MIPS
5102 These attributes specify how a particular function is called on MIPS@.
5103 The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
5104 command-line switch. The @code{long_call} and @code{far} attributes are
5105 synonyms, and cause the compiler to always call
5106 the function by first loading its address into a register, and then using
5107 the contents of that register. The @code{short_call} and @code{near}
5108 attributes are synonyms, and have the opposite
5109 effect; they specify that non-PIC calls should be made using the more
5110 efficient @code{jal} instruction.
5114 @cindex @code{mips16} function attribute, MIPS
5115 @cindex @code{nomips16} function attribute, MIPS
5117 On MIPS targets, you can use the @code{mips16} and @code{nomips16}
5118 function attributes to locally select or turn off MIPS16 code generation.
5119 A function with the @code{mips16} attribute is emitted as MIPS16 code,
5120 while MIPS16 code generation is disabled for functions with the
5121 @code{nomips16} attribute. These attributes override the
5122 @option{-mips16} and @option{-mno-mips16} options on the command line
5123 (@pxref{MIPS Options}).
5125 When compiling files containing mixed MIPS16 and non-MIPS16 code, the
5126 preprocessor symbol @code{__mips16} reflects the setting on the command line,
5127 not that within individual functions. Mixed MIPS16 and non-MIPS16 code
5128 may interact badly with some GCC extensions such as @code{__builtin_apply}
5129 (@pxref{Constructing Calls}).
5131 @item micromips, MIPS
5132 @itemx nomicromips, MIPS
5133 @cindex @code{micromips} function attribute
5134 @cindex @code{nomicromips} function attribute
5136 On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
5137 function attributes to locally select or turn off microMIPS code generation.
5138 A function with the @code{micromips} attribute is emitted as microMIPS code,
5139 while microMIPS code generation is disabled for functions with the
5140 @code{nomicromips} attribute. These attributes override the
5141 @option{-mmicromips} and @option{-mno-micromips} options on the command line
5142 (@pxref{MIPS Options}).
5144 When compiling files containing mixed microMIPS and non-microMIPS code, the
5145 preprocessor symbol @code{__mips_micromips} reflects the setting on the
5147 not that within individual functions. Mixed microMIPS and non-microMIPS code
5148 may interact badly with some GCC extensions such as @code{__builtin_apply}
5149 (@pxref{Constructing Calls}).
5152 @cindex @code{nocompression} function attribute, MIPS
5153 On MIPS targets, you can use the @code{nocompression} function attribute
5154 to locally turn off MIPS16 and microMIPS code generation. This attribute
5155 overrides the @option{-mips16} and @option{-mmicromips} options on the
5156 command line (@pxref{MIPS Options}).
5159 @node MSP430 Function Attributes
5160 @subsection MSP430 Function Attributes
5162 These function attributes are supported by the MSP430 back end:
5166 @cindex @code{critical} function attribute, MSP430
5167 Critical functions disable interrupts upon entry and restore the
5168 previous interrupt state upon exit. Critical functions cannot also
5169 have the @code{naked}, @code{reentrant} or @code{interrupt} attributes.
5171 The MSP430 hardware ensures that interrupts are disabled on entry to
5172 @code{interrupt} functions, and restores the previous interrupt state
5173 on exit. The @code{critical} attribute is therefore redundant on
5174 @code{interrupt} functions.
5177 @cindex @code{interrupt} function attribute, MSP430
5178 Use this attribute to indicate
5179 that the specified function is an interrupt handler. The compiler generates
5180 function entry and exit sequences suitable for use in an interrupt handler
5181 when this attribute is present.
5183 You can provide an argument to the interrupt
5184 attribute which specifies a name or number. If the argument is a
5185 number it indicates the slot in the interrupt vector table (0 - 31) to
5186 which this handler should be assigned. If the argument is a name it
5187 is treated as a symbolic name for the vector slot. These names should
5188 match up with appropriate entries in the linker script. By default
5189 the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
5190 @code{reset} for vector 31 are recognized.
5193 @cindex @code{naked} function attribute, MSP430
5194 This attribute allows the compiler to construct the
5195 requisite function declaration, while allowing the body of the
5196 function to be assembly code. The specified function will not have
5197 prologue/epilogue sequences generated by the compiler. Only basic
5198 @code{asm} statements can safely be included in naked functions
5199 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5200 basic @code{asm} and C code may appear to work, they cannot be
5201 depended upon to work reliably and are not supported.
5204 @cindex @code{reentrant} function attribute, MSP430
5205 Reentrant functions disable interrupts upon entry and enable them
5206 upon exit. Reentrant functions cannot also have the @code{naked}
5207 or @code{critical} attributes. They can have the @code{interrupt}
5211 @cindex @code{wakeup} function attribute, MSP430
5212 This attribute only applies to interrupt functions. It is silently
5213 ignored if applied to a non-interrupt function. A wakeup interrupt
5214 function will rouse the processor from any low-power state that it
5215 might be in when the function exits.
5220 @cindex @code{lower} function attribute, MSP430
5221 @cindex @code{upper} function attribute, MSP430
5222 @cindex @code{either} function attribute, MSP430
5223 On the MSP430 target these attributes can be used to specify whether
5224 the function or variable should be placed into low memory, high
5225 memory, or the placement should be left to the linker to decide. The
5226 attributes are only significant if compiling for the MSP430X
5229 The attributes work in conjunction with a linker script that has been
5230 augmented to specify where to place sections with a @code{.lower} and
5231 a @code{.upper} prefix. So, for example, as well as placing the
5232 @code{.data} section, the script also specifies the placement of a
5233 @code{.lower.data} and a @code{.upper.data} section. The intention
5234 is that @code{lower} sections are placed into a small but easier to
5235 access memory region and the upper sections are placed into a larger, but
5236 slower to access, region.
5238 The @code{either} attribute is special. It tells the linker to place
5239 the object into the corresponding @code{lower} section if there is
5240 room for it. If there is insufficient room then the object is placed
5241 into the corresponding @code{upper} section instead. Note that the
5242 placement algorithm is not very sophisticated. It does not attempt to
5243 find an optimal packing of the @code{lower} sections. It just makes
5244 one pass over the objects and does the best that it can. Using the
5245 @option{-ffunction-sections} and @option{-fdata-sections} command-line
5246 options can help the packing, however, since they produce smaller,
5247 easier to pack regions.
5250 @node NDS32 Function Attributes
5251 @subsection NDS32 Function Attributes
5253 These function attributes are supported by the NDS32 back end:
5257 @cindex @code{exception} function attribute
5258 @cindex exception handler functions, NDS32
5259 Use this attribute on the NDS32 target to indicate that the specified function
5260 is an exception handler. The compiler will generate corresponding sections
5261 for use in an exception handler.
5264 @cindex @code{interrupt} function attribute, NDS32
5265 On NDS32 target, this attribute indicates that the specified function
5266 is an interrupt handler. The compiler generates corresponding sections
5267 for use in an interrupt handler. You can use the following attributes
5268 to modify the behavior:
5271 @cindex @code{nested} function attribute, NDS32
5272 This interrupt service routine is interruptible.
5274 @cindex @code{not_nested} function attribute, NDS32
5275 This interrupt service routine is not interruptible.
5277 @cindex @code{nested_ready} function attribute, NDS32
5278 This interrupt service routine is interruptible after @code{PSW.GIE}
5279 (global interrupt enable) is set. This allows interrupt service routine to
5280 finish some short critical code before enabling interrupts.
5282 @cindex @code{save_all} function attribute, NDS32
5283 The system will help save all registers into stack before entering
5286 @cindex @code{partial_save} function attribute, NDS32
5287 The system will help save caller registers into stack before entering
5292 @cindex @code{naked} function attribute, NDS32
5293 This attribute allows the compiler to construct the
5294 requisite function declaration, while allowing the body of the
5295 function to be assembly code. The specified function will not have
5296 prologue/epilogue sequences generated by the compiler. Only basic
5297 @code{asm} statements can safely be included in naked functions
5298 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5299 basic @code{asm} and C code may appear to work, they cannot be
5300 depended upon to work reliably and are not supported.
5303 @cindex @code{reset} function attribute, NDS32
5304 @cindex reset handler functions
5305 Use this attribute on the NDS32 target to indicate that the specified function
5306 is a reset handler. The compiler will generate corresponding sections
5307 for use in a reset handler. You can use the following attributes
5308 to provide extra exception handling:
5311 @cindex @code{nmi} function attribute, NDS32
5312 Provide a user-defined function to handle NMI exception.
5314 @cindex @code{warm} function attribute, NDS32
5315 Provide a user-defined function to handle warm reset exception.
5319 @node Nios II Function Attributes
5320 @subsection Nios II Function Attributes
5322 These function attributes are supported by the Nios II back end:
5325 @item target (@var{options})
5326 @cindex @code{target} function attribute
5327 As discussed in @ref{Common Function Attributes}, this attribute
5328 allows specification of target-specific compilation options.
5330 When compiling for Nios II, the following options are allowed:
5333 @item custom-@var{insn}=@var{N}
5334 @itemx no-custom-@var{insn}
5335 @cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II
5336 @cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II
5337 Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a
5338 custom instruction with encoding @var{N} when generating code that uses
5339 @var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of
5340 the custom instruction @var{insn}.
5341 These target attributes correspond to the
5342 @option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}}
5343 command-line options, and support the same set of @var{insn} keywords.
5344 @xref{Nios II Options}, for more information.
5346 @item custom-fpu-cfg=@var{name}
5347 @cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II
5348 This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}}
5349 command-line option, to select a predefined set of custom instructions
5351 @xref{Nios II Options}, for more information.
5355 @node Nvidia PTX Function Attributes
5356 @subsection Nvidia PTX Function Attributes
5358 These function attributes are supported by the Nvidia PTX back end:
5362 @cindex @code{kernel} attribute, Nvidia PTX
5363 This attribute indicates that the corresponding function should be compiled
5364 as a kernel function, which can be invoked from the host via the CUDA RT
5366 By default functions are only callable only from other PTX functions.
5368 Kernel functions must have @code{void} return type.
5371 @node PowerPC Function Attributes
5372 @subsection PowerPC Function Attributes
5374 These function attributes are supported by the PowerPC back end:
5379 @cindex indirect calls, PowerPC
5380 @cindex @code{longcall} function attribute, PowerPC
5381 @cindex @code{shortcall} function attribute, PowerPC
5382 The @code{longcall} attribute
5383 indicates that the function might be far away from the call site and
5384 require a different (more expensive) calling sequence. The
5385 @code{shortcall} attribute indicates that the function is always close
5386 enough for the shorter calling sequence to be used. These attributes
5387 override both the @option{-mlongcall} switch and
5388 the @code{#pragma longcall} setting.
5390 @xref{RS/6000 and PowerPC Options}, for more information on whether long
5391 calls are necessary.
5393 @item target (@var{options})
5394 @cindex @code{target} function attribute
5395 As discussed in @ref{Common Function Attributes}, this attribute
5396 allows specification of target-specific compilation options.
5398 On the PowerPC, the following options are allowed:
5403 @cindex @code{target("altivec")} function attribute, PowerPC
5404 Generate code that uses (does not use) AltiVec instructions. In
5405 32-bit code, you cannot enable AltiVec instructions unless
5406 @option{-mabi=altivec} is used on the command line.
5410 @cindex @code{target("cmpb")} function attribute, PowerPC
5411 Generate code that uses (does not use) the compare bytes instruction
5412 implemented on the POWER6 processor and other processors that support
5413 the PowerPC V2.05 architecture.
5417 @cindex @code{target("dlmzb")} function attribute, PowerPC
5418 Generate code that uses (does not use) the string-search @samp{dlmzb}
5419 instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
5420 generated by default when targeting those processors.
5424 @cindex @code{target("fprnd")} function attribute, PowerPC
5425 Generate code that uses (does not use) the FP round to integer
5426 instructions implemented on the POWER5+ processor and other processors
5427 that support the PowerPC V2.03 architecture.
5431 @cindex @code{target("hard-dfp")} function attribute, PowerPC
5432 Generate code that uses (does not use) the decimal floating-point
5433 instructions implemented on some POWER processors.
5437 @cindex @code{target("isel")} function attribute, PowerPC
5438 Generate code that uses (does not use) ISEL instruction.
5442 @cindex @code{target("mfcrf")} function attribute, PowerPC
5443 Generate code that uses (does not use) the move from condition
5444 register field instruction implemented on the POWER4 processor and
5445 other processors that support the PowerPC V2.01 architecture.
5449 @cindex @code{target("mulhw")} function attribute, PowerPC
5450 Generate code that uses (does not use) the half-word multiply and
5451 multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
5452 These instructions are generated by default when targeting those
5457 @cindex @code{target("multiple")} function attribute, PowerPC
5458 Generate code that uses (does not use) the load multiple word
5459 instructions and the store multiple word instructions.
5463 @cindex @code{target("update")} function attribute, PowerPC
5464 Generate code that uses (does not use) the load or store instructions
5465 that update the base register to the address of the calculated memory
5470 @cindex @code{target("popcntb")} function attribute, PowerPC
5471 Generate code that uses (does not use) the popcount and double-precision
5472 FP reciprocal estimate instruction implemented on the POWER5
5473 processor and other processors that support the PowerPC V2.02
5478 @cindex @code{target("popcntd")} function attribute, PowerPC
5479 Generate code that uses (does not use) the popcount instruction
5480 implemented on the POWER7 processor and other processors that support
5481 the PowerPC V2.06 architecture.
5483 @item powerpc-gfxopt
5484 @itemx no-powerpc-gfxopt
5485 @cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
5486 Generate code that uses (does not use) the optional PowerPC
5487 architecture instructions in the Graphics group, including
5488 floating-point select.
5491 @itemx no-powerpc-gpopt
5492 @cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
5493 Generate code that uses (does not use) the optional PowerPC
5494 architecture instructions in the General Purpose group, including
5495 floating-point square root.
5497 @item recip-precision
5498 @itemx no-recip-precision
5499 @cindex @code{target("recip-precision")} function attribute, PowerPC
5500 Assume (do not assume) that the reciprocal estimate instructions
5501 provide higher-precision estimates than is mandated by the PowerPC
5506 @cindex @code{target("string")} function attribute, PowerPC
5507 Generate code that uses (does not use) the load string instructions
5508 and the store string word instructions to save multiple registers and
5509 do small block moves.
5513 @cindex @code{target("vsx")} function attribute, PowerPC
5514 Generate code that uses (does not use) vector/scalar (VSX)
5515 instructions, and also enable the use of built-in functions that allow
5516 more direct access to the VSX instruction set. In 32-bit code, you
5517 cannot enable VSX or AltiVec instructions unless
5518 @option{-mabi=altivec} is used on the command line.
5522 @cindex @code{target("friz")} function attribute, PowerPC
5523 Generate (do not generate) the @code{friz} instruction when the
5524 @option{-funsafe-math-optimizations} option is used to optimize
5525 rounding a floating-point value to 64-bit integer and back to floating
5526 point. The @code{friz} instruction does not return the same value if
5527 the floating-point number is too large to fit in an integer.
5529 @item avoid-indexed-addresses
5530 @itemx no-avoid-indexed-addresses
5531 @cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
5532 Generate code that tries to avoid (not avoid) the use of indexed load
5533 or store instructions.
5537 @cindex @code{target("paired")} function attribute, PowerPC
5538 Generate code that uses (does not use) the generation of PAIRED simd
5543 @cindex @code{target("longcall")} function attribute, PowerPC
5544 Generate code that assumes (does not assume) that all calls are far
5545 away so that a longer more expensive calling sequence is required.
5548 @cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
5549 Specify the architecture to generate code for when compiling the
5550 function. If you select the @code{target("cpu=power7")} attribute when
5551 generating 32-bit code, VSX and AltiVec instructions are not generated
5552 unless you use the @option{-mabi=altivec} option on the command line.
5554 @item tune=@var{TUNE}
5555 @cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
5556 Specify the architecture to tune for when compiling the function. If
5557 you do not specify the @code{target("tune=@var{TUNE}")} attribute and
5558 you do specify the @code{target("cpu=@var{CPU}")} attribute,
5559 compilation tunes for the @var{CPU} architecture, and not the
5560 default tuning specified on the command line.
5563 On the PowerPC, the inliner does not inline a
5564 function that has different target options than the caller, unless the
5565 callee has a subset of the target options of the caller.
5568 @node RISC-V Function Attributes
5569 @subsection RISC-V Function Attributes
5571 These function attributes are supported by the RISC-V back end:
5575 @cindex @code{naked} function attribute, RISC-V
5576 This attribute allows the compiler to construct the
5577 requisite function declaration, while allowing the body of the
5578 function to be assembly code. The specified function will not have
5579 prologue/epilogue sequences generated by the compiler. Only basic
5580 @code{asm} statements can safely be included in naked functions
5581 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5582 basic @code{asm} and C code may appear to work, they cannot be
5583 depended upon to work reliably and are not supported.
5586 @cindex @code{interrupt} function attribute, RISC-V
5587 Use this attribute to indicate that the specified function is an interrupt
5588 handler. The compiler generates function entry and exit sequences suitable
5589 for use in an interrupt handler when this attribute is present.
5591 You can specify the kind of interrupt to be handled by adding an optional
5592 parameter to the interrupt attribute like this:
5595 void f (void) __attribute__ ((interrupt ("user")));
5598 Permissible values for this parameter are @code{user}, @code{supervisor},
5599 and @code{machine}. If there is no parameter, then it defaults to
5603 @node RL78 Function Attributes
5604 @subsection RL78 Function Attributes
5606 These function attributes are supported by the RL78 back end:
5610 @itemx brk_interrupt
5611 @cindex @code{interrupt} function attribute, RL78
5612 @cindex @code{brk_interrupt} function attribute, RL78
5613 These attributes indicate
5614 that the specified function is an interrupt handler. The compiler generates
5615 function entry and exit sequences suitable for use in an interrupt handler
5616 when this attribute is present.
5618 Use @code{brk_interrupt} instead of @code{interrupt} for
5619 handlers intended to be used with the @code{BRK} opcode (i.e.@: those
5620 that must end with @code{RETB} instead of @code{RETI}).
5623 @cindex @code{naked} function attribute, RL78
5624 This attribute allows the compiler to construct the
5625 requisite function declaration, while allowing the body of the
5626 function to be assembly code. The specified function will not have
5627 prologue/epilogue sequences generated by the compiler. Only basic
5628 @code{asm} statements can safely be included in naked functions
5629 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5630 basic @code{asm} and C code may appear to work, they cannot be
5631 depended upon to work reliably and are not supported.
5634 @node RX Function Attributes
5635 @subsection RX Function Attributes
5637 These function attributes are supported by the RX back end:
5640 @item fast_interrupt
5641 @cindex @code{fast_interrupt} function attribute, RX
5642 Use this attribute on the RX port to indicate that the specified
5643 function is a fast interrupt handler. This is just like the
5644 @code{interrupt} attribute, except that @code{freit} is used to return
5645 instead of @code{reit}.
5648 @cindex @code{interrupt} function attribute, RX
5649 Use this attribute to indicate
5650 that the specified function is an interrupt handler. The compiler generates
5651 function entry and exit sequences suitable for use in an interrupt handler
5652 when this attribute is present.
5654 On RX and RL78 targets, you may specify one or more vector numbers as arguments
5655 to the attribute, as well as naming an alternate table name.
5656 Parameters are handled sequentially, so one handler can be assigned to
5657 multiple entries in multiple tables. One may also pass the magic
5658 string @code{"$default"} which causes the function to be used for any
5659 unfilled slots in the current table.
5661 This example shows a simple assignment of a function to one vector in
5662 the default table (note that preprocessor macros may be used for
5663 chip-specific symbolic vector names):
5665 void __attribute__ ((interrupt (5))) txd1_handler ();
5668 This example assigns a function to two slots in the default table
5669 (using preprocessor macros defined elsewhere) and makes it the default
5670 for the @code{dct} table:
5672 void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
5677 @cindex @code{naked} function attribute, RX
5678 This attribute allows the compiler to construct the
5679 requisite function declaration, while allowing the body of the
5680 function to be assembly code. The specified function will not have
5681 prologue/epilogue sequences generated by the compiler. Only basic
5682 @code{asm} statements can safely be included in naked functions
5683 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5684 basic @code{asm} and C code may appear to work, they cannot be
5685 depended upon to work reliably and are not supported.
5688 @cindex @code{vector} function attribute, RX
5689 This RX attribute is similar to the @code{interrupt} attribute, including its
5690 parameters, but does not make the function an interrupt-handler type
5691 function (i.e.@: it retains the normal C function calling ABI). See the
5692 @code{interrupt} attribute for a description of its arguments.
5695 @node S/390 Function Attributes
5696 @subsection S/390 Function Attributes
5698 These function attributes are supported on the S/390:
5701 @item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
5702 @cindex @code{hotpatch} function attribute, S/390
5704 On S/390 System z targets, you can use this function attribute to
5705 make GCC generate a ``hot-patching'' function prologue. If the
5706 @option{-mhotpatch=} command-line option is used at the same time,
5707 the @code{hotpatch} attribute takes precedence. The first of the
5708 two arguments specifies the number of halfwords to be added before
5709 the function label. A second argument can be used to specify the
5710 number of halfwords to be added after the function label. For
5711 both arguments the maximum allowed value is 1000000.
5713 If both arguments are zero, hotpatching is disabled.
5715 @item target (@var{options})
5716 @cindex @code{target} function attribute
5717 As discussed in @ref{Common Function Attributes}, this attribute
5718 allows specification of target-specific compilation options.
5720 On S/390, the following options are supported:
5728 @item warn-framesize=
5740 @itemx no-packed-stack
5742 @itemx no-small-exec
5745 @item warn-dynamicstack
5746 @itemx no-warn-dynamicstack
5749 The options work exactly like the S/390 specific command line
5750 options (without the prefix @option{-m}) except that they do not
5751 change any feature macros. For example,
5754 @code{target("no-vx")}
5757 does not undefine the @code{__VEC__} macro.
5760 @node SH Function Attributes
5761 @subsection SH Function Attributes
5763 These function attributes are supported on the SH family of processors:
5766 @item function_vector
5767 @cindex @code{function_vector} function attribute, SH
5768 @cindex calling functions through the function vector on SH2A
5769 On SH2A targets, this attribute declares a function to be called using the
5770 TBR relative addressing mode. The argument to this attribute is the entry
5771 number of the same function in a vector table containing all the TBR
5772 relative addressable functions. For correct operation the TBR must be setup
5773 accordingly to point to the start of the vector table before any functions with
5774 this attribute are invoked. Usually a good place to do the initialization is
5775 the startup routine. The TBR relative vector table can have at max 256 function
5776 entries. The jumps to these functions are generated using a SH2A specific,
5777 non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD
5778 from GNU binutils version 2.7 or later for this attribute to work correctly.
5780 In an application, for a function being called once, this attribute
5781 saves at least 8 bytes of code; and if other successive calls are being
5782 made to the same function, it saves 2 bytes of code per each of these
5785 @item interrupt_handler
5786 @cindex @code{interrupt_handler} function attribute, SH
5787 Use this attribute to
5788 indicate that the specified function is an interrupt handler. The compiler
5789 generates function entry and exit sequences suitable for use in an
5790 interrupt handler when this attribute is present.
5792 @item nosave_low_regs
5793 @cindex @code{nosave_low_regs} function attribute, SH
5794 Use this attribute on SH targets to indicate that an @code{interrupt_handler}
5795 function should not save and restore registers R0..R7. This can be used on SH3*
5796 and SH4* targets that have a second R0..R7 register bank for non-reentrant
5800 @cindex @code{renesas} function attribute, SH
5801 On SH targets this attribute specifies that the function or struct follows the
5805 @cindex @code{resbank} function attribute, SH
5806 On the SH2A target, this attribute enables the high-speed register
5807 saving and restoration using a register bank for @code{interrupt_handler}
5808 routines. Saving to the bank is performed automatically after the CPU
5809 accepts an interrupt that uses a register bank.
5811 The nineteen 32-bit registers comprising general register R0 to R14,
5812 control register GBR, and system registers MACH, MACL, and PR and the
5813 vector table address offset are saved into a register bank. Register
5814 banks are stacked in first-in last-out (FILO) sequence. Restoration
5815 from the bank is executed by issuing a RESBANK instruction.
5818 @cindex @code{sp_switch} function attribute, SH
5819 Use this attribute on the SH to indicate an @code{interrupt_handler}
5820 function should switch to an alternate stack. It expects a string
5821 argument that names a global variable holding the address of the
5826 void f () __attribute__ ((interrupt_handler,
5827 sp_switch ("alt_stack")));
5831 @cindex @code{trap_exit} function attribute, SH
5832 Use this attribute on the SH for an @code{interrupt_handler} to return using
5833 @code{trapa} instead of @code{rte}. This attribute expects an integer
5834 argument specifying the trap number to be used.
5837 @cindex @code{trapa_handler} function attribute, SH
5838 On SH targets this function attribute is similar to @code{interrupt_handler}
5839 but it does not save and restore all registers.
5842 @node SPU Function Attributes
5843 @subsection SPU Function Attributes
5845 These function attributes are supported by the SPU back end:
5849 @cindex @code{naked} function attribute, SPU
5850 This attribute allows the compiler to construct the
5851 requisite function declaration, while allowing the body of the
5852 function to be assembly code. The specified function will not have
5853 prologue/epilogue sequences generated by the compiler. Only basic
5854 @code{asm} statements can safely be included in naked functions
5855 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5856 basic @code{asm} and C code may appear to work, they cannot be
5857 depended upon to work reliably and are not supported.
5860 @node Symbian OS Function Attributes
5861 @subsection Symbian OS Function Attributes
5863 @xref{Microsoft Windows Function Attributes}, for discussion of the
5864 @code{dllexport} and @code{dllimport} attributes.
5866 @node V850 Function Attributes
5867 @subsection V850 Function Attributes
5869 The V850 back end supports these function attributes:
5873 @itemx interrupt_handler
5874 @cindex @code{interrupt} function attribute, V850
5875 @cindex @code{interrupt_handler} function attribute, V850
5876 Use these attributes to indicate
5877 that the specified function is an interrupt handler. The compiler generates
5878 function entry and exit sequences suitable for use in an interrupt handler
5879 when either attribute is present.
5882 @node Visium Function Attributes
5883 @subsection Visium Function Attributes
5885 These function attributes are supported by the Visium back end:
5889 @cindex @code{interrupt} function attribute, Visium
5890 Use this attribute to indicate
5891 that the specified function is an interrupt handler. The compiler generates
5892 function entry and exit sequences suitable for use in an interrupt handler
5893 when this attribute is present.
5896 @node x86 Function Attributes
5897 @subsection x86 Function Attributes
5899 These function attributes are supported by the x86 back end:
5903 @cindex @code{cdecl} function attribute, x86-32
5904 @cindex functions that pop the argument stack on x86-32
5906 On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
5907 assume that the calling function pops off the stack space used to
5908 pass arguments. This is
5909 useful to override the effects of the @option{-mrtd} switch.
5912 @cindex @code{fastcall} function attribute, x86-32
5913 @cindex functions that pop the argument stack on x86-32
5914 On x86-32 targets, the @code{fastcall} attribute causes the compiler to
5915 pass the first argument (if of integral type) in the register ECX and
5916 the second argument (if of integral type) in the register EDX@. Subsequent
5917 and other typed arguments are passed on the stack. The called function
5918 pops the arguments off the stack. If the number of arguments is variable all
5919 arguments are pushed on the stack.
5922 @cindex @code{thiscall} function attribute, x86-32
5923 @cindex functions that pop the argument stack on x86-32
5924 On x86-32 targets, the @code{thiscall} attribute causes the compiler to
5925 pass the first argument (if of integral type) in the register ECX.
5926 Subsequent and other typed arguments are passed on the stack. The called
5927 function pops the arguments off the stack.
5928 If the number of arguments is variable all arguments are pushed on the
5930 The @code{thiscall} attribute is intended for C++ non-static member functions.
5931 As a GCC extension, this calling convention can be used for C functions
5932 and for static member methods.
5936 @cindex @code{ms_abi} function attribute, x86
5937 @cindex @code{sysv_abi} function attribute, x86
5939 On 32-bit and 64-bit x86 targets, you can use an ABI attribute
5940 to indicate which calling convention should be used for a function. The
5941 @code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
5942 while the @code{sysv_abi} attribute tells the compiler to use the ABI
5943 used on GNU/Linux and other systems. The default is to use the Microsoft ABI
5944 when targeting Windows. On all other systems, the default is the x86/AMD ABI.
5946 Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
5947 requires the @option{-maccumulate-outgoing-args} option.
5949 @item callee_pop_aggregate_return (@var{number})
5950 @cindex @code{callee_pop_aggregate_return} function attribute, x86
5952 On x86-32 targets, you can use this attribute to control how
5953 aggregates are returned in memory. If the caller is responsible for
5954 popping the hidden pointer together with the rest of the arguments, specify
5955 @var{number} equal to zero. If callee is responsible for popping the
5956 hidden pointer, specify @var{number} equal to one.
5958 The default x86-32 ABI assumes that the callee pops the
5959 stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
5960 the compiler assumes that the
5961 caller pops the stack for hidden pointer.
5963 @item ms_hook_prologue
5964 @cindex @code{ms_hook_prologue} function attribute, x86
5966 On 32-bit and 64-bit x86 targets, you can use
5967 this function attribute to make GCC generate the ``hot-patching'' function
5968 prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
5972 @cindex @code{naked} function attribute, x86
5973 This attribute allows the compiler to construct the
5974 requisite function declaration, while allowing the body of the
5975 function to be assembly code. The specified function will not have
5976 prologue/epilogue sequences generated by the compiler. Only basic
5977 @code{asm} statements can safely be included in naked functions
5978 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5979 basic @code{asm} and C code may appear to work, they cannot be
5980 depended upon to work reliably and are not supported.
5982 @item regparm (@var{number})
5983 @cindex @code{regparm} function attribute, x86
5984 @cindex functions that are passed arguments in registers on x86-32
5985 On x86-32 targets, the @code{regparm} attribute causes the compiler to
5986 pass arguments number one to @var{number} if they are of integral type
5987 in registers EAX, EDX, and ECX instead of on the stack. Functions that
5988 take a variable number of arguments continue to be passed all of their
5989 arguments on the stack.
5991 Beware that on some ELF systems this attribute is unsuitable for
5992 global functions in shared libraries with lazy binding (which is the
5993 default). Lazy binding sends the first call via resolving code in
5994 the loader, which might assume EAX, EDX and ECX can be clobbered, as
5995 per the standard calling conventions. Solaris 8 is affected by this.
5996 Systems with the GNU C Library version 2.1 or higher
5997 and FreeBSD are believed to be
5998 safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
5999 disabled with the linker or the loader if desired, to avoid the
6003 @cindex @code{sseregparm} function attribute, x86
6004 On x86-32 targets with SSE support, the @code{sseregparm} attribute
6005 causes the compiler to pass up to 3 floating-point arguments in
6006 SSE registers instead of on the stack. Functions that take a
6007 variable number of arguments continue to pass all of their
6008 floating-point arguments on the stack.
6010 @item force_align_arg_pointer
6011 @cindex @code{force_align_arg_pointer} function attribute, x86
6012 On x86 targets, the @code{force_align_arg_pointer} attribute may be
6013 applied to individual function definitions, generating an alternate
6014 prologue and epilogue that realigns the run-time stack if necessary.
6015 This supports mixing legacy codes that run with a 4-byte aligned stack
6016 with modern codes that keep a 16-byte stack for SSE compatibility.
6019 @cindex @code{stdcall} function attribute, x86-32
6020 @cindex functions that pop the argument stack on x86-32
6021 On x86-32 targets, the @code{stdcall} attribute causes the compiler to
6022 assume that the called function pops off the stack space used to
6023 pass arguments, unless it takes a variable number of arguments.
6025 @item no_caller_saved_registers
6026 @cindex @code{no_caller_saved_registers} function attribute, x86
6027 Use this attribute to indicate that the specified function has no
6028 caller-saved registers. That is, all registers are callee-saved. For
6029 example, this attribute can be used for a function called from an
6030 interrupt handler. The compiler generates proper function entry and
6031 exit sequences to save and restore any modified registers, except for
6032 the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87
6033 states, the GCC option @option{-mgeneral-regs-only} should be used to
6034 compile functions with @code{no_caller_saved_registers} attribute.
6037 @cindex @code{interrupt} function attribute, x86
6038 Use this attribute to indicate that the specified function is an
6039 interrupt handler or an exception handler (depending on parameters passed
6040 to the function, explained further). The compiler generates function
6041 entry and exit sequences suitable for use in an interrupt handler when
6042 this attribute is present. The @code{IRET} instruction, instead of the
6043 @code{RET} instruction, is used to return from interrupt handlers. All
6044 registers, except for the EFLAGS register which is restored by the
6045 @code{IRET} instruction, are preserved by the compiler. Since GCC
6046 doesn't preserve SSE, MMX nor x87 states, the GCC option
6047 @option{-mgeneral-regs-only} should be used to compile interrupt and
6050 Any interruptible-without-stack-switch code must be compiled with
6051 @option{-mno-red-zone} since interrupt handlers can and will, because
6052 of the hardware design, touch the red zone.
6054 An interrupt handler must be declared with a mandatory pointer
6058 struct interrupt_frame;
6060 __attribute__ ((interrupt))
6062 f (struct interrupt_frame *frame)
6068 and you must define @code{struct interrupt_frame} as described in the
6071 Exception handlers differ from interrupt handlers because the system
6072 pushes an error code on the stack. An exception handler declaration is
6073 similar to that for an interrupt handler, but with a different mandatory
6074 function signature. The compiler arranges to pop the error code off the
6075 stack before the @code{IRET} instruction.
6079 typedef unsigned long long int uword_t;
6081 typedef unsigned int uword_t;
6084 struct interrupt_frame;
6086 __attribute__ ((interrupt))
6088 f (struct interrupt_frame *frame, uword_t error_code)
6094 Exception handlers should only be used for exceptions that push an error
6095 code; you should use an interrupt handler in other cases. The system
6096 will crash if the wrong kind of handler is used.
6098 @item target (@var{options})
6099 @cindex @code{target} function attribute
6100 As discussed in @ref{Common Function Attributes}, this attribute
6101 allows specification of target-specific compilation options.
6103 On the x86, the following options are allowed:
6107 @cindex @code{target("3dnow")} function attribute, x86
6108 Enable/disable the generation of the 3DNow!@: instructions.
6112 @cindex @code{target("3dnowa")} function attribute, x86
6113 Enable/disable the generation of the enhanced 3DNow!@: instructions.
6117 @cindex @code{target("abm")} function attribute, x86
6118 Enable/disable the generation of the advanced bit instructions.
6122 @cindex @code{target("adx")} function attribute, x86
6123 Enable/disable the generation of the ADX instructions.
6127 @cindex @code{target("aes")} function attribute, x86
6128 Enable/disable the generation of the AES instructions.
6132 @cindex @code{target("avx")} function attribute, x86
6133 Enable/disable the generation of the AVX instructions.
6137 @cindex @code{target("avx2")} function attribute, x86
6138 Enable/disable the generation of the AVX2 instructions.
6141 @itemx no-avx5124fmaps
6142 @cindex @code{target("avx5124fmaps")} function attribute, x86
6143 Enable/disable the generation of the AVX5124FMAPS instructions.
6146 @itemx no-avx5124vnniw
6147 @cindex @code{target("avx5124vnniw")} function attribute, x86
6148 Enable/disable the generation of the AVX5124VNNIW instructions.
6151 @itemx no-avx512bitalg
6152 @cindex @code{target("avx512bitalg")} function attribute, x86
6153 Enable/disable the generation of the AVX512BITALG instructions.
6157 @cindex @code{target("avx512bw")} function attribute, x86
6158 Enable/disable the generation of the AVX512BW instructions.
6162 @cindex @code{target("avx512cd")} function attribute, x86
6163 Enable/disable the generation of the AVX512CD instructions.
6167 @cindex @code{target("avx512dq")} function attribute, x86
6168 Enable/disable the generation of the AVX512DQ instructions.
6172 @cindex @code{target("avx512er")} function attribute, x86
6173 Enable/disable the generation of the AVX512ER instructions.
6177 @cindex @code{target("avx512f")} function attribute, x86
6178 Enable/disable the generation of the AVX512F instructions.
6181 @itemx no-avx512ifma
6182 @cindex @code{target("avx512ifma")} function attribute, x86
6183 Enable/disable the generation of the AVX512IFMA instructions.
6187 @cindex @code{target("avx512pf")} function attribute, x86
6188 Enable/disable the generation of the AVX512PF instructions.
6191 @itemx no-avx512vbmi
6192 @cindex @code{target("avx512vbmi")} function attribute, x86
6193 Enable/disable the generation of the AVX512VBMI instructions.
6196 @itemx no-avx512vbmi2
6197 @cindex @code{target("avx512vbmi2")} function attribute, x86
6198 Enable/disable the generation of the AVX512VBMI2 instructions.
6202 @cindex @code{target("avx512vl")} function attribute, x86
6203 Enable/disable the generation of the AVX512VL instructions.
6206 @itemx no-avx512vnni
6207 @cindex @code{target("avx512vnni")} function attribute, x86
6208 Enable/disable the generation of the AVX512VNNI instructions.
6210 @item avx512vpopcntdq
6211 @itemx no-avx512vpopcntdq
6212 @cindex @code{target("avx512vpopcntdq")} function attribute, x86
6213 Enable/disable the generation of the AVX512VPOPCNTDQ instructions.
6217 @cindex @code{target("bmi")} function attribute, x86
6218 Enable/disable the generation of the BMI instructions.
6222 @cindex @code{target("bmi2")} function attribute, x86
6223 Enable/disable the generation of the BMI2 instructions.
6227 @cindex @code{target("cldemote")} function attribute, x86
6228 Enable/disable the generation of the CLDEMOTE instructions.
6231 @itemx no-clflushopt
6232 @cindex @code{target("clflushopt")} function attribute, x86
6233 Enable/disable the generation of the CLFLUSHOPT instructions.
6237 @cindex @code{target("clwb")} function attribute, x86
6238 Enable/disable the generation of the CLWB instructions.
6242 @cindex @code{target("clzero")} function attribute, x86
6243 Enable/disable the generation of the CLZERO instructions.
6247 @cindex @code{target("crc32")} function attribute, x86
6248 Enable/disable the generation of the CRC32 instructions.
6252 @cindex @code{target("cx16")} function attribute, x86
6253 Enable/disable the generation of the CMPXCHG16B instructions.
6256 @cindex @code{target("default")} function attribute, x86
6257 @xref{Function Multiversioning}, where it is used to specify the
6258 default function version.
6262 @cindex @code{target("f16c")} function attribute, x86
6263 Enable/disable the generation of the F16C instructions.
6267 @cindex @code{target("fma")} function attribute, x86
6268 Enable/disable the generation of the FMA instructions.
6272 @cindex @code{target("fma4")} function attribute, x86
6273 Enable/disable the generation of the FMA4 instructions.
6277 @cindex @code{target("fsgsbase")} function attribute, x86
6278 Enable/disable the generation of the FSGSBASE instructions.
6282 @cindex @code{target("fxsr")} function attribute, x86
6283 Enable/disable the generation of the FXSR instructions.
6287 @cindex @code{target("gfni")} function attribute, x86
6288 Enable/disable the generation of the GFNI instructions.
6292 @cindex @code{target("hle")} function attribute, x86
6293 Enable/disable the generation of the HLE instruction prefixes.
6297 @cindex @code{target("lwp")} function attribute, x86
6298 Enable/disable the generation of the LWP instructions.
6302 @cindex @code{target("lzcnt")} function attribute, x86
6303 Enable/disable the generation of the LZCNT instructions.
6307 @cindex @code{target("mmx")} function attribute, x86
6308 Enable/disable the generation of the MMX instructions.
6312 @cindex @code{target("movbe")} function attribute, x86
6313 Enable/disable the generation of the MOVBE instructions.
6317 @cindex @code{target("movdir64b")} function attribute, x86
6318 Enable/disable the generation of the MOVDIR64B instructions.
6322 @cindex @code{target("movdiri")} function attribute, x86
6323 Enable/disable the generation of the MOVDIRI instructions.
6327 @cindex @code{target("mwaitx")} function attribute, x86
6328 Enable/disable the generation of the MWAITX instructions.
6332 @cindex @code{target("pclmul")} function attribute, x86
6333 Enable/disable the generation of the PCLMUL instructions.
6337 @cindex @code{target("pconfig")} function attribute, x86
6338 Enable/disable the generation of the PCONFIG instructions.
6342 @cindex @code{target("pku")} function attribute, x86
6343 Enable/disable the generation of the PKU instructions.
6347 @cindex @code{target("popcnt")} function attribute, x86
6348 Enable/disable the generation of the POPCNT instruction.
6351 @itemx no-prefetchwt1
6352 @cindex @code{target("prefetchwt1")} function attribute, x86
6353 Enable/disable the generation of the PREFETCHWT1 instructions.
6357 @cindex @code{target("prfchw")} function attribute, x86
6358 Enable/disable the generation of the PREFETCHW instruction.
6362 @cindex @code{target("ptwrite")} function attribute, x86
6363 Enable/disable the generation of the PTWRITE instructions.
6367 @cindex @code{target("rdpid")} function attribute, x86
6368 Enable/disable the generation of the RDPID instructions.
6372 @cindex @code{target("rdrnd")} function attribute, x86
6373 Enable/disable the generation of the RDRND instructions.
6377 @cindex @code{target("rdseed")} function attribute, x86
6378 Enable/disable the generation of the RDSEED instructions.
6382 @cindex @code{target("rtm")} function attribute, x86
6383 Enable/disable the generation of the RTM instructions.
6387 @cindex @code{target("sahf")} function attribute, x86
6388 Enable/disable the generation of the SAHF instructions.
6392 @cindex @code{target("sgx")} function attribute, x86
6393 Enable/disable the generation of the SGX instructions.
6397 @cindex @code{target("sha")} function attribute, x86
6398 Enable/disable the generation of the SHA instructions.
6402 @cindex @code{target("shstk")} function attribute, x86
6403 Enable/disable the shadow stack built-in functions from CET.
6407 @cindex @code{target("sse")} function attribute, x86
6408 Enable/disable the generation of the SSE instructions.
6412 @cindex @code{target("sse2")} function attribute, x86
6413 Enable/disable the generation of the SSE2 instructions.
6417 @cindex @code{target("sse3")} function attribute, x86
6418 Enable/disable the generation of the SSE3 instructions.
6422 @cindex @code{target("sse4")} function attribute, x86
6423 Enable/disable the generation of the SSE4 instructions (both SSE4.1
6428 @cindex @code{target("sse4.1")} function attribute, x86
6429 Enable/disable the generation of the sse4.1 instructions.
6433 @cindex @code{target("sse4.2")} function attribute, x86
6434 Enable/disable the generation of the sse4.2 instructions.
6438 @cindex @code{target("sse4a")} function attribute, x86
6439 Enable/disable the generation of the SSE4A instructions.
6443 @cindex @code{target("ssse3")} function attribute, x86
6444 Enable/disable the generation of the SSSE3 instructions.
6448 @cindex @code{target("tbm")} function attribute, x86
6449 Enable/disable the generation of the TBM instructions.
6453 @cindex @code{target("vaes")} function attribute, x86
6454 Enable/disable the generation of the VAES instructions.
6457 @itemx no-vpclmulqdq
6458 @cindex @code{target("vpclmulqdq")} function attribute, x86
6459 Enable/disable the generation of the VPCLMULQDQ instructions.
6463 @cindex @code{target("waitpkg")} function attribute, x86
6464 Enable/disable the generation of the WAITPKG instructions.
6468 @cindex @code{target("wbnoinvd")} function attribute, x86
6469 Enable/disable the generation of the WBNOINVD instructions.
6473 @cindex @code{target("xop")} function attribute, x86
6474 Enable/disable the generation of the XOP instructions.
6478 @cindex @code{target("xsave")} function attribute, x86
6479 Enable/disable the generation of the XSAVE instructions.
6483 @cindex @code{target("xsavec")} function attribute, x86
6484 Enable/disable the generation of the XSAVEC instructions.
6488 @cindex @code{target("xsaveopt")} function attribute, x86
6489 Enable/disable the generation of the XSAVEOPT instructions.
6493 @cindex @code{target("xsaves")} function attribute, x86
6494 Enable/disable the generation of the XSAVES instructions.
6498 @cindex @code{target("cld")} function attribute, x86
6499 Enable/disable the generation of the CLD before string moves.
6501 @item fancy-math-387
6502 @itemx no-fancy-math-387
6503 @cindex @code{target("fancy-math-387")} function attribute, x86
6504 Enable/disable the generation of the @code{sin}, @code{cos}, and
6505 @code{sqrt} instructions on the 387 floating-point unit.
6509 @cindex @code{target("ieee-fp")} function attribute, x86
6510 Enable/disable the generation of floating point that depends on IEEE arithmetic.
6512 @item inline-all-stringops
6513 @itemx no-inline-all-stringops
6514 @cindex @code{target("inline-all-stringops")} function attribute, x86
6515 Enable/disable inlining of string operations.
6517 @item inline-stringops-dynamically
6518 @itemx no-inline-stringops-dynamically
6519 @cindex @code{target("inline-stringops-dynamically")} function attribute, x86
6520 Enable/disable the generation of the inline code to do small string
6521 operations and calling the library routines for large operations.
6523 @item align-stringops
6524 @itemx no-align-stringops
6525 @cindex @code{target("align-stringops")} function attribute, x86
6526 Do/do not align destination of inlined string operations.
6530 @cindex @code{target("recip")} function attribute, x86
6531 Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
6532 instructions followed an additional Newton-Raphson step instead of
6533 doing a floating-point division.
6535 @item arch=@var{ARCH}
6536 @cindex @code{target("arch=@var{ARCH}")} function attribute, x86
6537 Specify the architecture to generate code for in compiling the function.
6539 @item tune=@var{TUNE}
6540 @cindex @code{target("tune=@var{TUNE}")} function attribute, x86
6541 Specify the architecture to tune for in compiling the function.
6543 @item fpmath=@var{FPMATH}
6544 @cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
6545 Specify which floating-point unit to use. You must specify the
6546 @code{target("fpmath=sse,387")} option as
6547 @code{target("fpmath=sse+387")} because the comma would separate
6550 @item indirect_branch("@var{choice}")
6551 @cindex @code{indirect_branch} function attribute, x86
6552 On x86 targets, the @code{indirect_branch} attribute causes the compiler
6553 to convert indirect call and jump with @var{choice}. @samp{keep}
6554 keeps indirect call and jump unmodified. @samp{thunk} converts indirect
6555 call and jump to call and return thunk. @samp{thunk-inline} converts
6556 indirect call and jump to inlined call and return thunk.
6557 @samp{thunk-extern} converts indirect call and jump to external call
6558 and return thunk provided in a separate object file.
6560 @item function_return("@var{choice}")
6561 @cindex @code{function_return} function attribute, x86
6562 On x86 targets, the @code{function_return} attribute causes the compiler
6563 to convert function return with @var{choice}. @samp{keep} keeps function
6564 return unmodified. @samp{thunk} converts function return to call and
6565 return thunk. @samp{thunk-inline} converts function return to inlined
6566 call and return thunk. @samp{thunk-extern} converts function return to
6567 external call and return thunk provided in a separate object file.
6570 @cindex @code{nocf_check} function attribute
6571 The @code{nocf_check} attribute on a function is used to inform the
6572 compiler that the function's prologue should not be instrumented when
6573 compiled with the @option{-fcf-protection=branch} option. The
6574 compiler assumes that the function's address is a valid target for a
6575 control-flow transfer.
6577 The @code{nocf_check} attribute on a type of pointer to function is
6578 used to inform the compiler that a call through the pointer should
6579 not be instrumented when compiled with the
6580 @option{-fcf-protection=branch} option. The compiler assumes
6581 that the function's address from the pointer is a valid target for
6582 a control-flow transfer. A direct function call through a function
6583 name is assumed to be a safe call thus direct calls are not
6584 instrumented by the compiler.
6586 The @code{nocf_check} attribute is applied to an object's type.
6587 In case of assignment of a function address or a function pointer to
6588 another pointer, the attribute is not carried over from the right-hand
6589 object's type; the type of left-hand object stays unchanged. The
6590 compiler checks for @code{nocf_check} attribute mismatch and reports
6591 a warning in case of mismatch.
6595 int foo (void) __attribute__(nocf_check);
6596 void (*foo1)(void) __attribute__(nocf_check);
6599 /* foo's address is assumed to be valid. */
6603 /* This call site is not checked for control-flow
6607 /* A warning is issued about attribute mismatch. */
6610 /* This call site is still not checked. */
6613 /* This call site is checked. */
6616 /* A warning is issued about attribute mismatch. */
6619 /* This call site is still checked. */
6627 @cindex @code{cf_check} function attribute, x86
6629 The @code{cf_check} attribute on a function is used to inform the
6630 compiler that ENDBR instruction should be placed at the function
6631 entry when @option{-fcf-protection=branch} is enabled.
6633 @item indirect_return
6634 @cindex @code{indirect_return} function attribute, x86
6636 The @code{indirect_return} attribute can be applied to a function,
6637 as well as variable or type of function pointer to inform the
6638 compiler that the function may return via indirect branch.
6640 @item fentry_name("@var{name}")
6641 @cindex @code{fentry_name} function attribute, x86
6642 On x86 targets, the @code{fentry_name} attribute sets the function to
6643 call on function entry when function instrumentation is enabled
6644 with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte
6645 nop sequence is generated.
6647 @item fentry_section("@var{name}")
6648 @cindex @code{fentry_section} function attribute, x86
6649 On x86 targets, the @code{fentry_section} attribute sets the name
6650 of the section to record function entry instrumentation calls in when
6651 enabled with @option{-pg -mrecord-mcount}
6655 On the x86, the inliner does not inline a
6656 function that has different target options than the caller, unless the
6657 callee has a subset of the target options of the caller. For example
6658 a function declared with @code{target("sse3")} can inline a function
6659 with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
6662 @node Xstormy16 Function Attributes
6663 @subsection Xstormy16 Function Attributes
6665 These function attributes are supported by the Xstormy16 back end:
6669 @cindex @code{interrupt} function attribute, Xstormy16
6670 Use this attribute to indicate
6671 that the specified function is an interrupt handler. The compiler generates
6672 function entry and exit sequences suitable for use in an interrupt handler
6673 when this attribute is present.
6676 @node Variable Attributes
6677 @section Specifying Attributes of Variables
6678 @cindex attribute of variables
6679 @cindex variable attributes
6681 The keyword @code{__attribute__} allows you to specify special properties
6682 of variables, function parameters, or structure, union, and, in C++, class
6683 members. This @code{__attribute__} keyword is followed by an attribute
6684 specification enclosed in double parentheses. Some attributes are currently
6685 defined generically for variables. Other attributes are defined for
6686 variables on particular target systems. Other attributes are available
6687 for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
6688 enumerators (@pxref{Enumerator Attributes}), statements
6689 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
6690 Other front ends might define more attributes
6691 (@pxref{C++ Extensions,,Extensions to the C++ Language}).
6693 @xref{Attribute Syntax}, for details of the exact syntax for using
6697 * Common Variable Attributes::
6698 * ARC Variable Attributes::
6699 * AVR Variable Attributes::
6700 * Blackfin Variable Attributes::
6701 * H8/300 Variable Attributes::
6702 * IA-64 Variable Attributes::
6703 * M32R/D Variable Attributes::
6704 * MeP Variable Attributes::
6705 * Microsoft Windows Variable Attributes::
6706 * MSP430 Variable Attributes::
6707 * Nvidia PTX Variable Attributes::
6708 * PowerPC Variable Attributes::
6709 * RL78 Variable Attributes::
6710 * SPU Variable Attributes::
6711 * V850 Variable Attributes::
6712 * x86 Variable Attributes::
6713 * Xstormy16 Variable Attributes::
6716 @node Common Variable Attributes
6717 @subsection Common Variable Attributes
6719 The following attributes are supported on most targets.
6722 @cindex @code{aligned} variable attribute
6724 @itemx aligned (@var{alignment})
6725 The @code{aligned} attribute specifies a minimum alignment for the variable
6726 or structure field, measured in bytes. When specified, @var{alignment} must
6727 be an integer constant power of 2. Specifying no @var{alignment} argument
6728 implies the maximum alignment for the target, which is often, but by no
6729 means always, 8 or 16 bytes.
6731 For example, the declaration:
6734 int x __attribute__ ((aligned (16))) = 0;
6738 causes the compiler to allocate the global variable @code{x} on a
6739 16-byte boundary. On a 68040, this could be used in conjunction with
6740 an @code{asm} expression to access the @code{move16} instruction which
6741 requires 16-byte aligned operands.
6743 You can also specify the alignment of structure fields. For example, to
6744 create a double-word aligned @code{int} pair, you could write:
6747 struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
6751 This is an alternative to creating a union with a @code{double} member,
6752 which forces the union to be double-word aligned.
6754 As in the preceding examples, you can explicitly specify the alignment
6755 (in bytes) that you wish the compiler to use for a given variable or
6756 structure field. Alternatively, you can leave out the alignment factor
6757 and just ask the compiler to align a variable or field to the
6758 default alignment for the target architecture you are compiling for.
6759 The default alignment is sufficient for all scalar types, but may not be
6760 enough for all vector types on a target that supports vector operations.
6761 The default alignment is fixed for a particular target ABI.
6763 GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
6764 which is the largest alignment ever used for any data type on the
6765 target machine you are compiling for. For example, you could write:
6768 short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
6771 The compiler automatically sets the alignment for the declared
6772 variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
6773 often make copy operations more efficient, because the compiler can
6774 use whatever instructions copy the biggest chunks of memory when
6775 performing copies to or from the variables or fields that you have
6776 aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
6777 may change depending on command-line options.
6779 When used on a struct, or struct member, the @code{aligned} attribute can
6780 only increase the alignment; in order to decrease it, the @code{packed}
6781 attribute must be specified as well. When used as part of a typedef, the
6782 @code{aligned} attribute can both increase and decrease alignment, and
6783 specifying the @code{packed} attribute generates a warning.
6785 Note that the effectiveness of @code{aligned} attributes for static
6786 variables may be limited by inherent limitations in the system linker
6787 and/or object file format. On some systems, the linker is
6788 only able to arrange for variables to be aligned up to a certain maximum
6789 alignment. (For some linkers, the maximum supported alignment may
6790 be very very small.) If your linker is only able to align variables
6791 up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
6792 in an @code{__attribute__} still only provides you with 8-byte
6793 alignment. See your linker documentation for further information.
6795 Stack variables are not affected by linker restrictions; GCC can properly
6796 align them on any target.
6798 The @code{aligned} attribute can also be used for functions
6799 (@pxref{Common Function Attributes}.)
6801 @cindex @code{warn_if_not_aligned} variable attribute
6802 @item warn_if_not_aligned (@var{alignment})
6803 This attribute specifies a threshold for the structure field, measured
6804 in bytes. If the structure field is aligned below the threshold, a
6805 warning will be issued. For example, the declaration:
6812 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
6817 causes the compiler to issue an warning on @code{struct foo}, like
6818 @samp{warning: alignment 8 of 'struct foo' is less than 16}.
6819 The compiler also issues a warning, like @samp{warning: 'x' offset
6820 8 in 'struct foo' isn't aligned to 16}, when the structure field has
6821 the misaligned offset:
6824 struct __attribute__ ((aligned (16))) foo
6828 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
6832 This warning can be disabled by @option{-Wno-if-not-aligned}.
6833 The @code{warn_if_not_aligned} attribute can also be used for types
6834 (@pxref{Common Type Attributes}.)
6836 @item alloc_size (@var{position})
6837 @itemx alloc_size (@var{position-1}, @var{position-2})
6838 @cindex @code{alloc_size} variable attribute
6839 The @code{alloc_size} variable attribute may be applied to the declaration
6840 of a pointer to a function that returns a pointer and takes at least one
6841 argument of an integer type. It indicates that the returned pointer points
6842 to an object whose size is given by the function argument at @var{position-1},
6843 or by the product of the arguments at @var{position-1} and @var{position-2}.
6844 Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other
6845 sizes are disagnosed when detected. GCC uses this information to improve
6846 the results of @code{__builtin_object_size}.
6848 For instance, the following declarations
6851 typedef __attribute__ ((alloc_size (1, 2))) void*
6852 (*calloc_ptr) (size_t, size_t);
6853 typedef __attribute__ ((alloc_size (1))) void*
6854 (*malloc_ptr) (size_t);
6858 specify that @code{calloc_ptr} is a pointer of a function that, like
6859 the standard C function @code{calloc}, returns an object whose size
6860 is given by the product of arguments 1 and 2, and similarly, that
6861 @code{malloc_ptr}, like the standard C function @code{malloc},
6862 returns an object whose size is given by argument 1 to the function.
6864 @item cleanup (@var{cleanup_function})
6865 @cindex @code{cleanup} variable attribute
6866 The @code{cleanup} attribute runs a function when the variable goes
6867 out of scope. This attribute can only be applied to auto function
6868 scope variables; it may not be applied to parameters or variables
6869 with static storage duration. The function must take one parameter,
6870 a pointer to a type compatible with the variable. The return value
6871 of the function (if any) is ignored.
6873 If @option{-fexceptions} is enabled, then @var{cleanup_function}
6874 is run during the stack unwinding that happens during the
6875 processing of the exception. Note that the @code{cleanup} attribute
6876 does not allow the exception to be caught, only to perform an action.
6877 It is undefined what happens if @var{cleanup_function} does not
6882 @cindex @code{common} variable attribute
6883 @cindex @code{nocommon} variable attribute
6886 The @code{common} attribute requests GCC to place a variable in
6887 ``common'' storage. The @code{nocommon} attribute requests the
6888 opposite---to allocate space for it directly.
6890 These attributes override the default chosen by the
6891 @option{-fno-common} and @option{-fcommon} flags respectively.
6894 @itemx copy (@var{variable})
6895 @cindex @code{copy} variable attribute
6896 The @code{copy} attribute applies the set of attributes with which
6897 @var{variable} has been declared to the declaration of the variable
6898 to which the attribute is applied. The attribute is designed for
6899 libraries that define aliases that are expected to specify the same
6900 set of attributes as the aliased symbols. The @code{copy} attribute
6901 can be used with variables, functions or types. However, the kind
6902 of symbol to which the attribute is applied (either varible or
6903 function) must match the kind of symbol to which the argument refers.
6904 The @code{copy} attribute copies only syntactic and semantic attributes
6905 but not attributes that affect a symbol's linkage or visibility such as
6906 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
6907 attribute is also not copied. @xref{Common Function Attributes}.
6908 @xref{Common Type Attributes}.
6911 @itemx deprecated (@var{msg})
6912 @cindex @code{deprecated} variable attribute
6913 The @code{deprecated} attribute results in a warning if the variable
6914 is used anywhere in the source file. This is useful when identifying
6915 variables that are expected to be removed in a future version of a
6916 program. The warning also includes the location of the declaration
6917 of the deprecated variable, to enable users to easily find further
6918 information about why the variable is deprecated, or what they should
6919 do instead. Note that the warning only occurs for uses:
6922 extern int old_var __attribute__ ((deprecated));
6924 int new_fn () @{ return old_var; @}
6928 results in a warning on line 3 but not line 2. The optional @var{msg}
6929 argument, which must be a string, is printed in the warning if
6932 The @code{deprecated} attribute can also be used for functions and
6933 types (@pxref{Common Function Attributes},
6934 @pxref{Common Type Attributes}).
6936 The message attached to the attribute is affected by the setting of
6937 the @option{-fmessage-length} option.
6939 @item mode (@var{mode})
6940 @cindex @code{mode} variable attribute
6941 This attribute specifies the data type for the declaration---whichever
6942 type corresponds to the mode @var{mode}. This in effect lets you
6943 request an integer or floating-point type according to its width.
6945 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
6946 for a list of the possible keywords for @var{mode}.
6947 You may also specify a mode of @code{byte} or @code{__byte__} to
6948 indicate the mode corresponding to a one-byte integer, @code{word} or
6949 @code{__word__} for the mode of a one-word integer, and @code{pointer}
6950 or @code{__pointer__} for the mode used to represent pointers.
6953 @cindex @code{nonstring} variable attribute
6954 The @code{nonstring} variable attribute specifies that an object or member
6955 declaration with type array of @code{char}, @code{signed char}, or
6956 @code{unsigned char}, or pointer to such a type is intended to store
6957 character arrays that do not necessarily contain a terminating @code{NUL}.
6958 This is useful in detecting uses of such arrays or pointers with functions
6959 that expect @code{NUL}-terminated strings, and to avoid warnings when such
6960 an array or pointer is used as an argument to a bounded string manipulation
6961 function such as @code{strncpy}. For example, without the attribute, GCC
6962 will issue a warning for the @code{strncpy} call below because it may
6963 truncate the copy without appending the terminating @code{NUL} character.
6964 Using the attribute makes it possible to suppress the warning. However,
6965 when the array is declared with the attribute the call to @code{strlen} is
6966 diagnosed because when the array doesn't contain a @code{NUL}-terminated
6967 string the call is undefined. To copy, compare, of search non-string
6968 character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr},
6969 and other functions that operate on arrays of bytes. In addition,
6970 calling @code{strnlen} and @code{strndup} with such arrays is safe
6971 provided a suitable bound is specified, and not diagnosed.
6976 char name [32] __attribute__ ((nonstring));
6979 int f (struct Data *pd, const char *s)
6981 strncpy (pd->name, s, sizeof pd->name);
6983 return strlen (pd->name); // unsafe, gets a warning
6988 @cindex @code{packed} variable attribute
6989 The @code{packed} attribute specifies that a structure member should have
6990 the smallest possible alignment---one bit for a bit-field and one byte
6991 otherwise, unless a larger value is specified with the @code{aligned}
6992 attribute. The attribute does not apply to non-member objects.
6994 For example in the structure below, the member array @code{x} is packed
6995 so that it immediately follows @code{a} with no intervening padding:
7001 int x[2] __attribute__ ((packed));
7005 @emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
7006 @code{packed} attribute on bit-fields of type @code{char}. This has
7007 been fixed in GCC 4.4 but the change can lead to differences in the
7008 structure layout. See the documentation of
7009 @option{-Wpacked-bitfield-compat} for more information.
7011 @item section ("@var{section-name}")
7012 @cindex @code{section} variable attribute
7013 Normally, the compiler places the objects it generates in sections like
7014 @code{data} and @code{bss}. Sometimes, however, you need additional sections,
7015 or you need certain particular variables to appear in special sections,
7016 for example to map to special hardware. The @code{section}
7017 attribute specifies that a variable (or function) lives in a particular
7018 section. For example, this small program uses several specific section names:
7021 struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
7022 struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
7023 char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
7024 int init_data __attribute__ ((section ("INITDATA")));
7028 /* @r{Initialize stack pointer} */
7029 init_sp (stack + sizeof (stack));
7031 /* @r{Initialize initialized data} */
7032 memcpy (&init_data, &data, &edata - &data);
7034 /* @r{Turn on the serial ports} */
7041 Use the @code{section} attribute with
7042 @emph{global} variables and not @emph{local} variables,
7043 as shown in the example.
7045 You may use the @code{section} attribute with initialized or
7046 uninitialized global variables but the linker requires
7047 each object be defined once, with the exception that uninitialized
7048 variables tentatively go in the @code{common} (or @code{bss}) section
7049 and can be multiply ``defined''. Using the @code{section} attribute
7050 changes what section the variable goes into and may cause the
7051 linker to issue an error if an uninitialized variable has multiple
7052 definitions. You can force a variable to be initialized with the
7053 @option{-fno-common} flag or the @code{nocommon} attribute.
7055 Some file formats do not support arbitrary sections so the @code{section}
7056 attribute is not available on all platforms.
7057 If you need to map the entire contents of a module to a particular
7058 section, consider using the facilities of the linker instead.
7060 @item tls_model ("@var{tls_model}")
7061 @cindex @code{tls_model} variable attribute
7062 The @code{tls_model} attribute sets thread-local storage model
7063 (@pxref{Thread-Local}) of a particular @code{__thread} variable,
7064 overriding @option{-ftls-model=} command-line switch on a per-variable
7066 The @var{tls_model} argument should be one of @code{global-dynamic},
7067 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
7069 Not all targets support this attribute.
7072 @cindex @code{unused} variable attribute
7073 This attribute, attached to a variable, means that the variable is meant
7074 to be possibly unused. GCC does not produce a warning for this
7078 @cindex @code{used} variable attribute
7079 This attribute, attached to a variable with static storage, means that
7080 the variable must be emitted even if it appears that the variable is not
7083 When applied to a static data member of a C++ class template, the
7084 attribute also means that the member is instantiated if the
7085 class itself is instantiated.
7087 @item vector_size (@var{bytes})
7088 @cindex @code{vector_size} variable attribute
7089 This attribute specifies the vector size for the type of the declared
7090 variable, measured in bytes. The type to which it applies is known as
7091 the @dfn{base type}. The @var{bytes} argument must be a positive
7092 power-of-two multiple of the base type size. For example, the declaration:
7095 int foo __attribute__ ((vector_size (16)));
7099 causes the compiler to set the mode for @code{foo}, to be 16 bytes,
7100 divided into @code{int} sized units. Assuming a 32-bit @code{int},
7101 @code{foo}'s type is a vector of four units of four bytes each, and
7102 the corresponding mode of @code{foo} is @code{V4SI}.
7103 @xref{Vector Extensions}, for details of manipulating vector variables.
7105 This attribute is only applicable to integral and floating scalars,
7106 although arrays, pointers, and function return values are allowed in
7107 conjunction with this construct.
7109 Aggregates with this attribute are invalid, even if they are of the same
7110 size as a corresponding scalar. For example, the declaration:
7113 struct S @{ int a; @};
7114 struct S __attribute__ ((vector_size (16))) foo;
7118 is invalid even if the size of the structure is the same as the size of
7121 @item visibility ("@var{visibility_type}")
7122 @cindex @code{visibility} variable attribute
7123 This attribute affects the linkage of the declaration to which it is attached.
7124 The @code{visibility} attribute is described in
7125 @ref{Common Function Attributes}.
7128 @cindex @code{weak} variable attribute
7129 The @code{weak} attribute is described in
7130 @ref{Common Function Attributes}.
7134 @node ARC Variable Attributes
7135 @subsection ARC Variable Attributes
7139 @cindex @code{aux} variable attribute, ARC
7140 The @code{aux} attribute is used to directly access the ARC's
7141 auxiliary register space from C. The auxilirary register number is
7142 given via attribute argument.
7146 @node AVR Variable Attributes
7147 @subsection AVR Variable Attributes
7151 @cindex @code{progmem} variable attribute, AVR
7152 The @code{progmem} attribute is used on the AVR to place read-only
7153 data in the non-volatile program memory (flash). The @code{progmem}
7154 attribute accomplishes this by putting respective variables into a
7155 section whose name starts with @code{.progmem}.
7157 This attribute works similar to the @code{section} attribute
7158 but adds additional checking.
7161 @item @bullet{}@tie{} Ordinary AVR cores with 32 general purpose registers:
7162 @code{progmem} affects the location
7163 of the data but not how this data is accessed.
7164 In order to read data located with the @code{progmem} attribute
7165 (inline) assembler must be used.
7167 /* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */
7168 #include <avr/pgmspace.h>
7170 /* Locate var in flash memory */
7171 const int var[2] PROGMEM = @{ 1, 2 @};
7173 int read_var (int i)
7175 /* Access var[] by accessor macro from avr/pgmspace.h */
7176 return (int) pgm_read_word (& var[i]);
7180 AVR is a Harvard architecture processor and data and read-only data
7181 normally resides in the data memory (RAM).
7183 See also the @ref{AVR Named Address Spaces} section for
7184 an alternate way to locate and access data in flash memory.
7186 @item @bullet{}@tie{} AVR cores with flash memory visible in the RAM address range:
7187 On such devices, there is no need for attribute @code{progmem} or
7188 @ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all.
7189 Just use standard C / C++. The compiler will generate @code{LD*}
7190 instructions. As flash memory is visible in the RAM address range,
7191 and the default linker script does @emph{not} locate @code{.rodata} in
7192 RAM, no special features are needed in order not to waste RAM for
7193 read-only data or to read from flash. You might even get slightly better
7195 avoiding @code{progmem} and @code{__flash}. This applies to devices from
7196 families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for
7199 @item @bullet{}@tie{}Reduced AVR Tiny cores like ATtiny40:
7200 The compiler adds @code{0x4000}
7201 to the addresses of objects and declarations in @code{progmem} and locates
7202 the objects in flash memory, namely in section @code{.progmem.data}.
7203 The offset is needed because the flash memory is visible in the RAM
7204 address space starting at address @code{0x4000}.
7206 Data in @code{progmem} can be accessed by means of ordinary C@tie{}code,
7207 no special functions or macros are needed.
7210 /* var is located in flash memory */
7211 extern const int var[2] __attribute__((progmem));
7213 int read_var (int i)
7219 Please notice that on these devices, there is no need for @code{progmem}
7225 @itemx io (@var{addr})
7226 @cindex @code{io} variable attribute, AVR
7227 Variables with the @code{io} attribute are used to address
7228 memory-mapped peripherals in the io address range.
7229 If an address is specified, the variable
7230 is assigned that address, and the value is interpreted as an
7231 address in the data address space.
7235 volatile int porta __attribute__((io (0x22)));
7238 The address specified in the address in the data address range.
7240 Otherwise, the variable it is not assigned an address, but the
7241 compiler will still use in/out instructions where applicable,
7242 assuming some other module assigns an address in the io address range.
7246 extern volatile int porta __attribute__((io));
7250 @itemx io_low (@var{addr})
7251 @cindex @code{io_low} variable attribute, AVR
7252 This is like the @code{io} attribute, but additionally it informs the
7253 compiler that the object lies in the lower half of the I/O area,
7254 allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis}
7258 @itemx address (@var{addr})
7259 @cindex @code{address} variable attribute, AVR
7260 Variables with the @code{address} attribute are used to address
7261 memory-mapped peripherals that may lie outside the io address range.
7264 volatile int porta __attribute__((address (0x600)));
7268 @cindex @code{absdata} variable attribute, AVR
7269 Variables in static storage and with the @code{absdata} attribute can
7270 be accessed by the @code{LDS} and @code{STS} instructions which take
7275 This attribute is only supported for the reduced AVR Tiny core
7279 You must make sure that respective data is located in the
7280 address range @code{0x40}@dots{}@code{0xbf} accessible by
7281 @code{LDS} and @code{STS}. One way to achieve this as an
7282 appropriate linker description file.
7285 If the location does not fit the address range of @code{LDS}
7286 and @code{STS}, there is currently (Binutils 2.26) just an unspecific
7289 @code{module.c:(.text+0x1c): warning: internal error: out of range error}
7294 See also the @option{-mabsdata} @ref{AVR Options,command-line option}.
7298 @node Blackfin Variable Attributes
7299 @subsection Blackfin Variable Attributes
7301 Three attributes are currently defined for the Blackfin.
7307 @cindex @code{l1_data} variable attribute, Blackfin
7308 @cindex @code{l1_data_A} variable attribute, Blackfin
7309 @cindex @code{l1_data_B} variable attribute, Blackfin
7310 Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
7311 Variables with @code{l1_data} attribute are put into the specific section
7312 named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into
7313 the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
7314 attribute are put into the specific section named @code{.l1.data.B}.
7317 @cindex @code{l2} variable attribute, Blackfin
7318 Use this attribute on the Blackfin to place the variable into L2 SRAM.
7319 Variables with @code{l2} attribute are put into the specific section
7320 named @code{.l2.data}.
7323 @node H8/300 Variable Attributes
7324 @subsection H8/300 Variable Attributes
7326 These variable attributes are available for H8/300 targets:
7330 @cindex @code{eightbit_data} variable attribute, H8/300
7331 @cindex eight-bit data on the H8/300, H8/300H, and H8S
7332 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
7333 variable should be placed into the eight-bit data section.
7334 The compiler generates more efficient code for certain operations
7335 on data in the eight-bit data area. Note the eight-bit data area is limited to
7338 You must use GAS and GLD from GNU binutils version 2.7 or later for
7339 this attribute to work correctly.
7342 @cindex @code{tiny_data} variable attribute, H8/300
7343 @cindex tiny data section on the H8/300H and H8S
7344 Use this attribute on the H8/300H and H8S to indicate that the specified
7345 variable should be placed into the tiny data section.
7346 The compiler generates more efficient code for loads and stores
7347 on data in the tiny data section. Note the tiny data area is limited to
7348 slightly under 32KB of data.
7352 @node IA-64 Variable Attributes
7353 @subsection IA-64 Variable Attributes
7355 The IA-64 back end supports the following variable attribute:
7358 @item model (@var{model-name})
7359 @cindex @code{model} variable attribute, IA-64
7361 On IA-64, use this attribute to set the addressability of an object.
7362 At present, the only supported identifier for @var{model-name} is
7363 @code{small}, indicating addressability via ``small'' (22-bit)
7364 addresses (so that their addresses can be loaded with the @code{addl}
7365 instruction). Caveat: such addressing is by definition not position
7366 independent and hence this attribute must not be used for objects
7367 defined by shared libraries.
7371 @node M32R/D Variable Attributes
7372 @subsection M32R/D Variable Attributes
7374 One attribute is currently defined for the M32R/D@.
7377 @item model (@var{model-name})
7378 @cindex @code{model-name} variable attribute, M32R/D
7379 @cindex variable addressability on the M32R/D
7380 Use this attribute on the M32R/D to set the addressability of an object.
7381 The identifier @var{model-name} is one of @code{small}, @code{medium},
7382 or @code{large}, representing each of the code models.
7384 Small model objects live in the lower 16MB of memory (so that their
7385 addresses can be loaded with the @code{ld24} instruction).
7387 Medium and large model objects may live anywhere in the 32-bit address space
7388 (the compiler generates @code{seth/add3} instructions to load their
7392 @node MeP Variable Attributes
7393 @subsection MeP Variable Attributes
7395 The MeP target has a number of addressing modes and busses. The
7396 @code{near} space spans the standard memory space's first 16 megabytes
7397 (24 bits). The @code{far} space spans the entire 32-bit memory space.
7398 The @code{based} space is a 128-byte region in the memory space that
7399 is addressed relative to the @code{$tp} register. The @code{tiny}
7400 space is a 65536-byte region relative to the @code{$gp} register. In
7401 addition to these memory regions, the MeP target has a separate 16-bit
7402 control bus which is specified with @code{cb} attributes.
7407 @cindex @code{based} variable attribute, MeP
7408 Any variable with the @code{based} attribute is assigned to the
7409 @code{.based} section, and is accessed with relative to the
7410 @code{$tp} register.
7413 @cindex @code{tiny} variable attribute, MeP
7414 Likewise, the @code{tiny} attribute assigned variables to the
7415 @code{.tiny} section, relative to the @code{$gp} register.
7418 @cindex @code{near} variable attribute, MeP
7419 Variables with the @code{near} attribute are assumed to have addresses
7420 that fit in a 24-bit addressing mode. This is the default for large
7421 variables (@code{-mtiny=4} is the default) but this attribute can
7422 override @code{-mtiny=} for small variables, or override @code{-ml}.
7425 @cindex @code{far} variable attribute, MeP
7426 Variables with the @code{far} attribute are addressed using a full
7427 32-bit address. Since this covers the entire memory space, this
7428 allows modules to make no assumptions about where variables might be
7432 @cindex @code{io} variable attribute, MeP
7433 @itemx io (@var{addr})
7434 Variables with the @code{io} attribute are used to address
7435 memory-mapped peripherals. If an address is specified, the variable
7436 is assigned that address, else it is not assigned an address (it is
7437 assumed some other module assigns an address). Example:
7440 int timer_count __attribute__((io(0x123)));
7444 @itemx cb (@var{addr})
7445 @cindex @code{cb} variable attribute, MeP
7446 Variables with the @code{cb} attribute are used to access the control
7447 bus, using special instructions. @code{addr} indicates the control bus
7451 int cpu_clock __attribute__((cb(0x123)));
7456 @node Microsoft Windows Variable Attributes
7457 @subsection Microsoft Windows Variable Attributes
7459 You can use these attributes on Microsoft Windows targets.
7460 @ref{x86 Variable Attributes} for additional Windows compatibility
7461 attributes available on all x86 targets.
7466 @cindex @code{dllimport} variable attribute
7467 @cindex @code{dllexport} variable attribute
7468 The @code{dllimport} and @code{dllexport} attributes are described in
7469 @ref{Microsoft Windows Function Attributes}.
7472 @cindex @code{selectany} variable attribute
7473 The @code{selectany} attribute causes an initialized global variable to
7474 have link-once semantics. When multiple definitions of the variable are
7475 encountered by the linker, the first is selected and the remainder are
7476 discarded. Following usage by the Microsoft compiler, the linker is told
7477 @emph{not} to warn about size or content differences of the multiple
7480 Although the primary usage of this attribute is for POD types, the
7481 attribute can also be applied to global C++ objects that are initialized
7482 by a constructor. In this case, the static initialization and destruction
7483 code for the object is emitted in each translation defining the object,
7484 but the calls to the constructor and destructor are protected by a
7485 link-once guard variable.
7487 The @code{selectany} attribute is only available on Microsoft Windows
7488 targets. You can use @code{__declspec (selectany)} as a synonym for
7489 @code{__attribute__ ((selectany))} for compatibility with other
7493 @cindex @code{shared} variable attribute
7494 On Microsoft Windows, in addition to putting variable definitions in a named
7495 section, the section can also be shared among all running copies of an
7496 executable or DLL@. For example, this small program defines shared data
7497 by putting it in a named section @code{shared} and marking the section
7501 int foo __attribute__((section ("shared"), shared)) = 0;
7506 /* @r{Read and write foo. All running
7507 copies see the same value.} */
7513 You may only use the @code{shared} attribute along with @code{section}
7514 attribute with a fully-initialized global definition because of the way
7515 linkers work. See @code{section} attribute for more information.
7517 The @code{shared} attribute is only available on Microsoft Windows@.
7521 @node MSP430 Variable Attributes
7522 @subsection MSP430 Variable Attributes
7526 @cindex @code{noinit} variable attribute, MSP430
7527 Any data with the @code{noinit} attribute will not be initialised by
7528 the C runtime startup code, or the program loader. Not initialising
7529 data in this way can reduce program startup times.
7532 @cindex @code{persistent} variable attribute, MSP430
7533 Any variable with the @code{persistent} attribute will not be
7534 initialised by the C runtime startup code. Instead its value will be
7535 set once, when the application is loaded, and then never initialised
7536 again, even if the processor is reset or the program restarts.
7537 Persistent data is intended to be placed into FLASH RAM, where its
7538 value will be retained across resets. The linker script being used to
7539 create the application should ensure that persistent data is correctly
7545 @cindex @code{lower} variable attribute, MSP430
7546 @cindex @code{upper} variable attribute, MSP430
7547 @cindex @code{either} variable attribute, MSP430
7548 These attributes are the same as the MSP430 function attributes of the
7549 same name (@pxref{MSP430 Function Attributes}).
7550 These attributes can be applied to both functions and variables.
7553 @node Nvidia PTX Variable Attributes
7554 @subsection Nvidia PTX Variable Attributes
7556 These variable attributes are supported by the Nvidia PTX back end:
7560 @cindex @code{shared} attribute, Nvidia PTX
7561 Use this attribute to place a variable in the @code{.shared} memory space.
7562 This memory space is private to each cooperative thread array; only threads
7563 within one thread block refer to the same instance of the variable.
7564 The runtime does not initialize variables in this memory space.
7567 @node PowerPC Variable Attributes
7568 @subsection PowerPC Variable Attributes
7570 Three attributes currently are defined for PowerPC configurations:
7571 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
7573 @cindex @code{ms_struct} variable attribute, PowerPC
7574 @cindex @code{gcc_struct} variable attribute, PowerPC
7575 For full documentation of the struct attributes please see the
7576 documentation in @ref{x86 Variable Attributes}.
7578 @cindex @code{altivec} variable attribute, PowerPC
7579 For documentation of @code{altivec} attribute please see the
7580 documentation in @ref{PowerPC Type Attributes}.
7582 @node RL78 Variable Attributes
7583 @subsection RL78 Variable Attributes
7585 @cindex @code{saddr} variable attribute, RL78
7586 The RL78 back end supports the @code{saddr} variable attribute. This
7587 specifies placement of the corresponding variable in the SADDR area,
7588 which can be accessed more efficiently than the default memory region.
7590 @node SPU Variable Attributes
7591 @subsection SPU Variable Attributes
7593 @cindex @code{spu_vector} variable attribute, SPU
7594 The SPU supports the @code{spu_vector} attribute for variables. For
7595 documentation of this attribute please see the documentation in
7596 @ref{SPU Type Attributes}.
7598 @node V850 Variable Attributes
7599 @subsection V850 Variable Attributes
7601 These variable attributes are supported by the V850 back end:
7606 @cindex @code{sda} variable attribute, V850
7607 Use this attribute to explicitly place a variable in the small data area,
7608 which can hold up to 64 kilobytes.
7611 @cindex @code{tda} variable attribute, V850
7612 Use this attribute to explicitly place a variable in the tiny data area,
7613 which can hold up to 256 bytes in total.
7616 @cindex @code{zda} variable attribute, V850
7617 Use this attribute to explicitly place a variable in the first 32 kilobytes
7621 @node x86 Variable Attributes
7622 @subsection x86 Variable Attributes
7624 Two attributes are currently defined for x86 configurations:
7625 @code{ms_struct} and @code{gcc_struct}.
7630 @cindex @code{ms_struct} variable attribute, x86
7631 @cindex @code{gcc_struct} variable attribute, x86
7633 If @code{packed} is used on a structure, or if bit-fields are used,
7634 it may be that the Microsoft ABI lays out the structure differently
7635 than the way GCC normally does. Particularly when moving packed
7636 data between functions compiled with GCC and the native Microsoft compiler
7637 (either via function call or as data in a file), it may be necessary to access
7640 The @code{ms_struct} and @code{gcc_struct} attributes correspond
7641 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
7642 command-line options, respectively;
7643 see @ref{x86 Options}, for details of how structure layout is affected.
7644 @xref{x86 Type Attributes}, for information about the corresponding
7645 attributes on types.
7649 @node Xstormy16 Variable Attributes
7650 @subsection Xstormy16 Variable Attributes
7652 One attribute is currently defined for xstormy16 configurations:
7657 @cindex @code{below100} variable attribute, Xstormy16
7659 If a variable has the @code{below100} attribute (@code{BELOW100} is
7660 allowed also), GCC places the variable in the first 0x100 bytes of
7661 memory and use special opcodes to access it. Such variables are
7662 placed in either the @code{.bss_below100} section or the
7663 @code{.data_below100} section.
7667 @node Type Attributes
7668 @section Specifying Attributes of Types
7669 @cindex attribute of types
7670 @cindex type attributes
7672 The keyword @code{__attribute__} allows you to specify various special
7673 properties of types. Some type attributes apply only to structure and
7674 union types, and in C++, also class types, while others can apply to
7675 any type defined via a @code{typedef} declaration. Unless otherwise
7676 specified, the same restrictions and effects apply to attributes regardless
7677 of whether a type is a trivial structure or a C++ class with user-defined
7678 constructors, destructors, or a copy assignment.
7680 Other attributes are defined for functions (@pxref{Function Attributes}),
7681 labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator
7682 Attributes}), statements (@pxref{Statement Attributes}), and for variables
7683 (@pxref{Variable Attributes}).
7685 The @code{__attribute__} keyword is followed by an attribute specification
7686 enclosed in double parentheses.
7688 You may specify type attributes in an enum, struct or union type
7689 declaration or definition by placing them immediately after the
7690 @code{struct}, @code{union} or @code{enum} keyword. You can also place
7691 them just past the closing curly brace of the definition, but this is less
7692 preferred because logically the type should be fully defined at
7695 You can also include type attributes in a @code{typedef} declaration.
7696 @xref{Attribute Syntax}, for details of the exact syntax for using
7700 * Common Type Attributes::
7701 * ARC Type Attributes::
7702 * ARM Type Attributes::
7703 * MeP Type Attributes::
7704 * PowerPC Type Attributes::
7705 * SPU Type Attributes::
7706 * x86 Type Attributes::
7709 @node Common Type Attributes
7710 @subsection Common Type Attributes
7712 The following type attributes are supported on most targets.
7715 @cindex @code{aligned} type attribute
7717 @itemx aligned (@var{alignment})
7718 The @code{aligned} attribute specifies a minimum alignment (in bytes) for
7719 variables of the specified type. When specified, @var{alignment} must be
7720 a power of 2. Specifying no @var{alignment} argument implies the maximum
7721 alignment for the target, which is often, but by no means always, 8 or 16
7722 bytes. For example, the declarations:
7725 struct __attribute__ ((aligned (8))) S @{ short f[3]; @};
7726 typedef int more_aligned_int __attribute__ ((aligned (8)));
7730 force the compiler to ensure (as far as it can) that each variable whose
7731 type is @code{struct S} or @code{more_aligned_int} is allocated and
7732 aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all
7733 variables of type @code{struct S} aligned to 8-byte boundaries allows
7734 the compiler to use the @code{ldd} and @code{std} (doubleword load and
7735 store) instructions when copying one variable of type @code{struct S} to
7736 another, thus improving run-time efficiency.
7738 Note that the alignment of any given @code{struct} or @code{union} type
7739 is required by the ISO C standard to be at least a perfect multiple of
7740 the lowest common multiple of the alignments of all of the members of
7741 the @code{struct} or @code{union} in question. This means that you @emph{can}
7742 effectively adjust the alignment of a @code{struct} or @code{union}
7743 type by attaching an @code{aligned} attribute to any one of the members
7744 of such a type, but the notation illustrated in the example above is a
7745 more obvious, intuitive, and readable way to request the compiler to
7746 adjust the alignment of an entire @code{struct} or @code{union} type.
7748 As in the preceding example, you can explicitly specify the alignment
7749 (in bytes) that you wish the compiler to use for a given @code{struct}
7750 or @code{union} type. Alternatively, you can leave out the alignment factor
7751 and just ask the compiler to align a type to the maximum
7752 useful alignment for the target machine you are compiling for. For
7753 example, you could write:
7756 struct __attribute__ ((aligned)) S @{ short f[3]; @};
7759 Whenever you leave out the alignment factor in an @code{aligned}
7760 attribute specification, the compiler automatically sets the alignment
7761 for the type to the largest alignment that is ever used for any data
7762 type on the target machine you are compiling for. Doing this can often
7763 make copy operations more efficient, because the compiler can use
7764 whatever instructions copy the biggest chunks of memory when performing
7765 copies to or from the variables that have types that you have aligned
7768 In the example above, if the size of each @code{short} is 2 bytes, then
7769 the size of the entire @code{struct S} type is 6 bytes. The smallest
7770 power of two that is greater than or equal to that is 8, so the
7771 compiler sets the alignment for the entire @code{struct S} type to 8
7774 Note that although you can ask the compiler to select a time-efficient
7775 alignment for a given type and then declare only individual stand-alone
7776 objects of that type, the compiler's ability to select a time-efficient
7777 alignment is primarily useful only when you plan to create arrays of
7778 variables having the relevant (efficiently aligned) type. If you
7779 declare or use arrays of variables of an efficiently-aligned type, then
7780 it is likely that your program also does pointer arithmetic (or
7781 subscripting, which amounts to the same thing) on pointers to the
7782 relevant type, and the code that the compiler generates for these
7783 pointer arithmetic operations is often more efficient for
7784 efficiently-aligned types than for other types.
7786 Note that the effectiveness of @code{aligned} attributes may be limited
7787 by inherent limitations in your linker. On many systems, the linker is
7788 only able to arrange for variables to be aligned up to a certain maximum
7789 alignment. (For some linkers, the maximum supported alignment may
7790 be very very small.) If your linker is only able to align variables
7791 up to a maximum of 8-byte alignment, then specifying @code{aligned (16)}
7792 in an @code{__attribute__} still only provides you with 8-byte
7793 alignment. See your linker documentation for further information.
7795 When used on a struct, or struct member, the @code{aligned} attribute can
7796 only increase the alignment; in order to decrease it, the @code{packed}
7797 attribute must be specified as well. When used as part of a typedef, the
7798 @code{aligned} attribute can both increase and decrease alignment, and
7799 specifying the @code{packed} attribute generates a warning.
7801 @cindex @code{warn_if_not_aligned} type attribute
7802 @item warn_if_not_aligned (@var{alignment})
7803 This attribute specifies a threshold for the structure field, measured
7804 in bytes. If the structure field is aligned below the threshold, a
7805 warning will be issued. For example, the declaration:
7808 typedef unsigned long long __u64
7809 __attribute__((aligned (4), warn_if_not_aligned (8)));
7820 causes the compiler to issue an warning on @code{struct foo}, like
7821 @samp{warning: alignment 4 of 'struct foo' is less than 8}.
7822 It is used to define @code{struct foo} in such a way that
7823 @code{struct foo} has the same layout and the structure field @code{x}
7824 has the same alignment when @code{__u64} is aligned at either 4 or
7825 8 bytes. Align @code{struct foo} to 8 bytes:
7828 struct __attribute__ ((aligned (8))) foo
7837 silences the warning. The compiler also issues a warning, like
7838 @samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8},
7839 when the structure field has the misaligned offset:
7842 struct __attribute__ ((aligned (8))) foo
7851 This warning can be disabled by @option{-Wno-if-not-aligned}.
7853 @item alloc_size (@var{position})
7854 @itemx alloc_size (@var{position-1}, @var{position-2})
7855 @cindex @code{alloc_size} type attribute
7856 The @code{alloc_size} type attribute may be applied to the definition
7857 of a type of a function that returns a pointer and takes at least one
7858 argument of an integer type. It indicates that the returned pointer
7859 points to an object whose size is given by the function argument at
7860 @var{position-1}, or by the product of the arguments at @var{position-1}
7861 and @var{position-2}. Meaningful sizes are positive values less than
7862 @code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses
7863 this information to improve the results of @code{__builtin_object_size}.
7865 For instance, the following declarations
7868 typedef __attribute__ ((alloc_size (1, 2))) void*
7869 calloc_type (size_t, size_t);
7870 typedef __attribute__ ((alloc_size (1))) void*
7871 malloc_type (size_t);
7875 specify that @code{calloc_type} is a type of a function that, like
7876 the standard C function @code{calloc}, returns an object whose size
7877 is given by the product of arguments 1 and 2, and that
7878 @code{malloc_type}, like the standard C function @code{malloc},
7879 returns an object whose size is given by argument 1 to the function.
7882 @itemx copy (@var{expression})
7883 @cindex @code{copy} type attribute
7884 The @code{copy} attribute applies the set of attributes with which
7885 the type of the @var{expression} has been declared to the declaration
7886 of the type to which the attribute is applied. The attribute is
7887 designed for libraries that define aliases that are expected to
7888 specify the same set of attributes as the aliased symbols.
7889 The @code{copy} attribute can be used with types, variables, or
7890 functions. However, the kind of symbol to which the attribute is
7891 applied (either varible or function) must match the kind of symbol
7892 to which the argument refers.
7893 The @code{copy} attribute copies only syntactic and semantic attributes
7894 but not attributes that affect a symbol's linkage or visibility such as
7895 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
7896 attribute is also not copied. @xref{Common Function Attributes}.
7897 @xref{Common Variable Attributes}.
7899 For example, suppose @code{struct A} below is defined in some third
7900 party library header to have the alignment requirement @code{N} and
7901 to force a warning whenever a variable of the type is not so aligned
7902 due to attribute @code{packed}. Specifying the @code{copy} attribute
7903 on the definition on the unrelated @code{struct B} has the effect of
7904 copying all relevant attributes from the type referenced by the pointer
7905 expression to @code{struct B}.
7908 struct __attribute__ ((aligned (N), warn_if_not_aligned (N)))
7909 A @{ /* @r{@dots{}} */ @};
7910 struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @};
7914 @itemx deprecated (@var{msg})
7915 @cindex @code{deprecated} type attribute
7916 The @code{deprecated} attribute results in a warning if the type
7917 is used anywhere in the source file. This is useful when identifying
7918 types that are expected to be removed in a future version of a program.
7919 If possible, the warning also includes the location of the declaration
7920 of the deprecated type, to enable users to easily find further
7921 information about why the type is deprecated, or what they should do
7922 instead. Note that the warnings only occur for uses and then only
7923 if the type is being applied to an identifier that itself is not being
7924 declared as deprecated.
7927 typedef int T1 __attribute__ ((deprecated));
7931 typedef T1 T3 __attribute__ ((deprecated));
7932 T3 z __attribute__ ((deprecated));
7936 results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
7937 warning is issued for line 4 because T2 is not explicitly
7938 deprecated. Line 5 has no warning because T3 is explicitly
7939 deprecated. Similarly for line 6. The optional @var{msg}
7940 argument, which must be a string, is printed in the warning if
7941 present. Control characters in the string will be replaced with
7942 escape sequences, and if the @option{-fmessage-length} option is set
7943 to 0 (its default value) then any newline characters will be ignored.
7945 The @code{deprecated} attribute can also be used for functions and
7946 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
7948 The message attached to the attribute is affected by the setting of
7949 the @option{-fmessage-length} option.
7951 @item designated_init
7952 @cindex @code{designated_init} type attribute
7953 This attribute may only be applied to structure types. It indicates
7954 that any initialization of an object of this type must use designated
7955 initializers rather than positional initializers. The intent of this
7956 attribute is to allow the programmer to indicate that a structure's
7957 layout may change, and that therefore relying on positional
7958 initialization will result in future breakage.
7960 GCC emits warnings based on this attribute by default; use
7961 @option{-Wno-designated-init} to suppress them.
7964 @cindex @code{may_alias} type attribute
7965 Accesses through pointers to types with this attribute are not subject
7966 to type-based alias analysis, but are instead assumed to be able to alias
7967 any other type of objects.
7968 In the context of section 6.5 paragraph 7 of the C99 standard,
7969 an lvalue expression
7970 dereferencing such a pointer is treated like having a character type.
7971 See @option{-fstrict-aliasing} for more information on aliasing issues.
7972 This extension exists to support some vector APIs, in which pointers to
7973 one vector type are permitted to alias pointers to a different vector type.
7975 Note that an object of a type with this attribute does not have any
7981 typedef short __attribute__ ((__may_alias__)) short_a;
7987 short_a *b = (short_a *) &a;
7991 if (a == 0x12345678)
7999 If you replaced @code{short_a} with @code{short} in the variable
8000 declaration, the above program would abort when compiled with
8001 @option{-fstrict-aliasing}, which is on by default at @option{-O2} or
8004 @item mode (@var{mode})
8005 @cindex @code{mode} type attribute
8006 This attribute specifies the data type for the declaration---whichever
8007 type corresponds to the mode @var{mode}. This in effect lets you
8008 request an integer or floating-point type according to its width.
8010 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
8011 for a list of the possible keywords for @var{mode}.
8012 You may also specify a mode of @code{byte} or @code{__byte__} to
8013 indicate the mode corresponding to a one-byte integer, @code{word} or
8014 @code{__word__} for the mode of a one-word integer, and @code{pointer}
8015 or @code{__pointer__} for the mode used to represent pointers.
8018 @cindex @code{packed} type attribute
8019 This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class}
8020 type definition, specifies that each of its members (other than zero-width
8021 bit-fields) is placed to minimize the memory required. This is equivalent
8022 to specifying the @code{packed} attribute on each of the members.
8024 @opindex fshort-enums
8025 When attached to an @code{enum} definition, the @code{packed} attribute
8026 indicates that the smallest integral type should be used.
8027 Specifying the @option{-fshort-enums} flag on the command line
8028 is equivalent to specifying the @code{packed}
8029 attribute on all @code{enum} definitions.
8031 In the following example @code{struct my_packed_struct}'s members are
8032 packed closely together, but the internal layout of its @code{s} member
8033 is not packed---to do that, @code{struct my_unpacked_struct} needs to
8037 struct my_unpacked_struct
8043 struct __attribute__ ((__packed__)) my_packed_struct
8047 struct my_unpacked_struct s;
8051 You may only specify the @code{packed} attribute on the definition
8052 of an @code{enum}, @code{struct}, @code{union}, or @code{class},
8053 not on a @code{typedef} that does not also define the enumerated type,
8054 structure, union, or class.
8056 @item scalar_storage_order ("@var{endianness}")
8057 @cindex @code{scalar_storage_order} type attribute
8058 When attached to a @code{union} or a @code{struct}, this attribute sets
8059 the storage order, aka endianness, of the scalar fields of the type, as
8060 well as the array fields whose component is scalar. The supported
8061 endiannesses are @code{big-endian} and @code{little-endian}. The attribute
8062 has no effects on fields which are themselves a @code{union}, a @code{struct}
8063 or an array whose component is a @code{union} or a @code{struct}, and it is
8064 possible for these fields to have a different scalar storage order than the
8067 This attribute is supported only for targets that use a uniform default
8068 scalar storage order (fortunately, most of them), i.e.@: targets that store
8069 the scalars either all in big-endian or all in little-endian.
8071 Additional restrictions are enforced for types with the reverse scalar
8072 storage order with regard to the scalar storage order of the target:
8075 @item Taking the address of a scalar field of a @code{union} or a
8076 @code{struct} with reverse scalar storage order is not permitted and yields
8078 @item Taking the address of an array field, whose component is scalar, of
8079 a @code{union} or a @code{struct} with reverse scalar storage order is
8080 permitted but yields a warning, unless @option{-Wno-scalar-storage-order}
8082 @item Taking the address of a @code{union} or a @code{struct} with reverse
8083 scalar storage order is permitted.
8086 These restrictions exist because the storage order attribute is lost when
8087 the address of a scalar or the address of an array with scalar component is
8088 taken, so storing indirectly through this address generally does not work.
8089 The second case is nevertheless allowed to be able to perform a block copy
8090 from or to the array.
8092 Moreover, the use of type punning or aliasing to toggle the storage order
8093 is not supported; that is to say, a given scalar object cannot be accessed
8094 through distinct types that assign a different storage order to it.
8096 @item transparent_union
8097 @cindex @code{transparent_union} type attribute
8099 This attribute, attached to a @code{union} type definition, indicates
8100 that any function parameter having that union type causes calls to that
8101 function to be treated in a special way.
8103 First, the argument corresponding to a transparent union type can be of
8104 any type in the union; no cast is required. Also, if the union contains
8105 a pointer type, the corresponding argument can be a null pointer
8106 constant or a void pointer expression; and if the union contains a void
8107 pointer type, the corresponding argument can be any pointer expression.
8108 If the union member type is a pointer, qualifiers like @code{const} on
8109 the referenced type must be respected, just as with normal pointer
8112 Second, the argument is passed to the function using the calling
8113 conventions of the first member of the transparent union, not the calling
8114 conventions of the union itself. All members of the union must have the
8115 same machine representation; this is necessary for this argument passing
8118 Transparent unions are designed for library functions that have multiple
8119 interfaces for compatibility reasons. For example, suppose the
8120 @code{wait} function must accept either a value of type @code{int *} to
8121 comply with POSIX, or a value of type @code{union wait *} to comply with
8122 the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
8123 @code{wait} would accept both kinds of arguments, but it would also
8124 accept any other pointer type and this would make argument type checking
8125 less useful. Instead, @code{<sys/wait.h>} might define the interface
8129 typedef union __attribute__ ((__transparent_union__))
8133 @} wait_status_ptr_t;
8135 pid_t wait (wait_status_ptr_t);
8139 This interface allows either @code{int *} or @code{union wait *}
8140 arguments to be passed, using the @code{int *} calling convention.
8141 The program can call @code{wait} with arguments of either type:
8144 int w1 () @{ int w; return wait (&w); @}
8145 int w2 () @{ union wait w; return wait (&w); @}
8149 With this interface, @code{wait}'s implementation might look like this:
8152 pid_t wait (wait_status_ptr_t p)
8154 return waitpid (-1, p.__ip, 0);
8159 @cindex @code{unused} type attribute
8160 When attached to a type (including a @code{union} or a @code{struct}),
8161 this attribute means that variables of that type are meant to appear
8162 possibly unused. GCC does not produce a warning for any variables of
8163 that type, even if the variable appears to do nothing. This is often
8164 the case with lock or thread classes, which are usually defined and then
8165 not referenced, but contain constructors and destructors that have
8166 nontrivial bookkeeping functions.
8168 @item vector_size (@var{bytes})
8169 @cindex @code{vector_size} type attribute
8170 This attribute specifies the vector size for the type, measured in bytes.
8171 The type to which it applies is known as the @dfn{base type}. The @var{bytes}
8172 argument must be a positive power-of-two multiple of the base type size. For
8173 example, the following declarations:
8176 typedef __attribute__ ((vector_size (32))) int int_vec32_t ;
8177 typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t;
8178 typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3];
8182 define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int}
8183 sized units. With @code{int} having a size of 4 bytes, the type defines
8184 a vector of eight units, four bytes each. The mode of variables of type
8185 @code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined
8186 to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be
8187 an array of three such vectors. @xref{Vector Extensions}, for details of
8188 manipulating objects of vector types.
8190 This attribute is only applicable to integral and floating scalar types.
8191 In function declarations the attribute applies to the function return
8194 For example, the following:
8196 __attribute__ ((vector_size (16))) float get_flt_vec16 (void);
8198 declares @code{get_flt_vec16} to be a function returning a 16-byte vector
8199 with the base type @code{float}.
8202 @cindex @code{visibility} type attribute
8203 In C++, attribute visibility (@pxref{Function Attributes}) can also be
8204 applied to class, struct, union and enum types. Unlike other type
8205 attributes, the attribute must appear between the initial keyword and
8206 the name of the type; it cannot appear after the body of the type.
8208 Note that the type visibility is applied to vague linkage entities
8209 associated with the class (vtable, typeinfo node, etc.). In
8210 particular, if a class is thrown as an exception in one shared object
8211 and caught in another, the class must have default visibility.
8212 Otherwise the two shared objects are unable to use the same
8213 typeinfo node and exception handling will break.
8217 To specify multiple attributes, separate them by commas within the
8218 double parentheses: for example, @samp{__attribute__ ((aligned (16),
8221 @node ARC Type Attributes
8222 @subsection ARC Type Attributes
8224 @cindex @code{uncached} type attribute, ARC
8225 Declaring objects with @code{uncached} allows you to exclude
8226 data-cache participation in load and store operations on those objects
8227 without involving the additional semantic implications of
8228 @code{volatile}. The @code{.di} instruction suffix is used for all
8229 loads and stores of data declared @code{uncached}.
8231 @node ARM Type Attributes
8232 @subsection ARM Type Attributes
8234 @cindex @code{notshared} type attribute, ARM
8235 On those ARM targets that support @code{dllimport} (such as Symbian
8236 OS), you can use the @code{notshared} attribute to indicate that the
8237 virtual table and other similar data for a class should not be
8238 exported from a DLL@. For example:
8241 class __declspec(notshared) C @{
8243 __declspec(dllimport) C();
8247 __declspec(dllexport)
8252 In this code, @code{C::C} is exported from the current DLL, but the
8253 virtual table for @code{C} is not exported. (You can use
8254 @code{__attribute__} instead of @code{__declspec} if you prefer, but
8255 most Symbian OS code uses @code{__declspec}.)
8257 @node MeP Type Attributes
8258 @subsection MeP Type Attributes
8260 @cindex @code{based} type attribute, MeP
8261 @cindex @code{tiny} type attribute, MeP
8262 @cindex @code{near} type attribute, MeP
8263 @cindex @code{far} type attribute, MeP
8264 Many of the MeP variable attributes may be applied to types as well.
8265 Specifically, the @code{based}, @code{tiny}, @code{near}, and
8266 @code{far} attributes may be applied to either. The @code{io} and
8267 @code{cb} attributes may not be applied to types.
8269 @node PowerPC Type Attributes
8270 @subsection PowerPC Type Attributes
8272 Three attributes currently are defined for PowerPC configurations:
8273 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
8275 @cindex @code{ms_struct} type attribute, PowerPC
8276 @cindex @code{gcc_struct} type attribute, PowerPC
8277 For full documentation of the @code{ms_struct} and @code{gcc_struct}
8278 attributes please see the documentation in @ref{x86 Type Attributes}.
8280 @cindex @code{altivec} type attribute, PowerPC
8281 The @code{altivec} attribute allows one to declare AltiVec vector data
8282 types supported by the AltiVec Programming Interface Manual. The
8283 attribute requires an argument to specify one of three vector types:
8284 @code{vector__}, @code{pixel__} (always followed by unsigned short),
8285 and @code{bool__} (always followed by unsigned).
8288 __attribute__((altivec(vector__)))
8289 __attribute__((altivec(pixel__))) unsigned short
8290 __attribute__((altivec(bool__))) unsigned
8293 These attributes mainly are intended to support the @code{__vector},
8294 @code{__pixel}, and @code{__bool} AltiVec keywords.
8296 @node SPU Type Attributes
8297 @subsection SPU Type Attributes
8299 @cindex @code{spu_vector} type attribute, SPU
8300 The SPU supports the @code{spu_vector} attribute for types. This attribute
8301 allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU
8302 Language Extensions Specification. It is intended to support the
8303 @code{__vector} keyword.
8305 @node x86 Type Attributes
8306 @subsection x86 Type Attributes
8308 Two attributes are currently defined for x86 configurations:
8309 @code{ms_struct} and @code{gcc_struct}.
8315 @cindex @code{ms_struct} type attribute, x86
8316 @cindex @code{gcc_struct} type attribute, x86
8318 If @code{packed} is used on a structure, or if bit-fields are used
8319 it may be that the Microsoft ABI packs them differently
8320 than GCC normally packs them. Particularly when moving packed
8321 data between functions compiled with GCC and the native Microsoft compiler
8322 (either via function call or as data in a file), it may be necessary to access
8325 The @code{ms_struct} and @code{gcc_struct} attributes correspond
8326 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
8327 command-line options, respectively;
8328 see @ref{x86 Options}, for details of how structure layout is affected.
8329 @xref{x86 Variable Attributes}, for information about the corresponding
8330 attributes on variables.
8334 @node Label Attributes
8335 @section Label Attributes
8336 @cindex Label Attributes
8338 GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for
8339 details of the exact syntax for using attributes. Other attributes are
8340 available for functions (@pxref{Function Attributes}), variables
8341 (@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}),
8342 statements (@pxref{Statement Attributes}), and for types
8343 (@pxref{Type Attributes}).
8345 This example uses the @code{cold} label attribute to indicate the
8346 @code{ErrorHandling} branch is unlikely to be taken and that the
8347 @code{ErrorHandling} label is unused:
8351 asm goto ("some asm" : : : : NoError);
8353 /* This branch (the fall-through from the asm) is less commonly used */
8355 __attribute__((cold, unused)); /* Semi-colon is required here */
8360 printf("no error\n");
8366 @cindex @code{unused} label attribute
8367 This feature is intended for program-generated code that may contain
8368 unused labels, but which is compiled with @option{-Wall}. It is
8369 not normally appropriate to use in it human-written code, though it
8370 could be useful in cases where the code that jumps to the label is
8371 contained within an @code{#ifdef} conditional.
8374 @cindex @code{hot} label attribute
8375 The @code{hot} attribute on a label is used to inform the compiler that
8376 the path following the label is more likely than paths that are not so
8377 annotated. This attribute is used in cases where @code{__builtin_expect}
8378 cannot be used, for instance with computed goto or @code{asm goto}.
8381 @cindex @code{cold} label attribute
8382 The @code{cold} attribute on labels is used to inform the compiler that
8383 the path following the label is unlikely to be executed. This attribute
8384 is used in cases where @code{__builtin_expect} cannot be used, for instance
8385 with computed goto or @code{asm goto}.
8389 @node Enumerator Attributes
8390 @section Enumerator Attributes
8391 @cindex Enumerator Attributes
8393 GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for
8394 details of the exact syntax for using attributes. Other attributes are
8395 available for functions (@pxref{Function Attributes}), variables
8396 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements
8397 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
8399 This example uses the @code{deprecated} enumerator attribute to indicate the
8400 @code{oldval} enumerator is deprecated:
8404 oldval __attribute__((deprecated)),
8417 @cindex @code{deprecated} enumerator attribute
8418 The @code{deprecated} attribute results in a warning if the enumerator
8419 is used anywhere in the source file. This is useful when identifying
8420 enumerators that are expected to be removed in a future version of a
8421 program. The warning also includes the location of the declaration
8422 of the deprecated enumerator, to enable users to easily find further
8423 information about why the enumerator is deprecated, or what they should
8424 do instead. Note that the warnings only occurs for uses.
8428 @node Statement Attributes
8429 @section Statement Attributes
8430 @cindex Statement Attributes
8432 GCC allows attributes to be set on null statements. @xref{Attribute Syntax},
8433 for details of the exact syntax for using attributes. Other attributes are
8434 available for functions (@pxref{Function Attributes}), variables
8435 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators
8436 (@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}).
8438 This example uses the @code{fallthrough} statement attribute to indicate that
8439 the @option{-Wimplicit-fallthrough} warning should not be emitted:
8446 __attribute__((fallthrough));
8454 @cindex @code{fallthrough} statement attribute
8455 The @code{fallthrough} attribute with a null statement serves as a
8456 fallthrough statement. It hints to the compiler that a statement
8457 that falls through to another case label, or user-defined label
8458 in a switch statement is intentional and thus the
8459 @option{-Wimplicit-fallthrough} warning must not trigger. The
8460 fallthrough attribute may appear at most once in each attribute
8461 list, and may not be mixed with other attributes. It can only
8462 be used in a switch statement (the compiler will issue an error
8463 otherwise), after a preceding statement and before a logically
8464 succeeding case label, or user-defined label.
8468 @node Attribute Syntax
8469 @section Attribute Syntax
8470 @cindex attribute syntax
8472 This section describes the syntax with which @code{__attribute__} may be
8473 used, and the constructs to which attribute specifiers bind, for the C
8474 language. Some details may vary for C++ and Objective-C@. Because of
8475 infelicities in the grammar for attributes, some forms described here
8476 may not be successfully parsed in all cases.
8478 There are some problems with the semantics of attributes in C++. For
8479 example, there are no manglings for attributes, although they may affect
8480 code generation, so problems may arise when attributed types are used in
8481 conjunction with templates or overloading. Similarly, @code{typeid}
8482 does not distinguish between types with different attributes. Support
8483 for attributes in C++ may be restricted in future to attributes on
8484 declarations only, but not on nested declarators.
8486 @xref{Function Attributes}, for details of the semantics of attributes
8487 applying to functions. @xref{Variable Attributes}, for details of the
8488 semantics of attributes applying to variables. @xref{Type Attributes},
8489 for details of the semantics of attributes applying to structure, union
8490 and enumerated types.
8491 @xref{Label Attributes}, for details of the semantics of attributes
8493 @xref{Enumerator Attributes}, for details of the semantics of attributes
8494 applying to enumerators.
8495 @xref{Statement Attributes}, for details of the semantics of attributes
8496 applying to statements.
8498 An @dfn{attribute specifier} is of the form
8499 @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
8500 is a possibly empty comma-separated sequence of @dfn{attributes}, where
8501 each attribute is one of the following:
8505 Empty. Empty attributes are ignored.
8509 (which may be an identifier such as @code{unused}, or a reserved
8510 word such as @code{const}).
8513 An attribute name followed by a parenthesized list of
8514 parameters for the attribute.
8515 These parameters take one of the following forms:
8519 An identifier. For example, @code{mode} attributes use this form.
8522 An identifier followed by a comma and a non-empty comma-separated list
8523 of expressions. For example, @code{format} attributes use this form.
8526 A possibly empty comma-separated list of expressions. For example,
8527 @code{format_arg} attributes use this form with the list being a single
8528 integer constant expression, and @code{alias} attributes use this form
8529 with the list being a single string constant.
8533 An @dfn{attribute specifier list} is a sequence of one or more attribute
8534 specifiers, not separated by any other tokens.
8536 You may optionally specify attribute names with @samp{__}
8537 preceding and following the name.
8538 This allows you to use them in header files without
8539 being concerned about a possible macro of the same name. For example,
8540 you may use the attribute name @code{__noreturn__} instead of @code{noreturn}.
8543 @subsubheading Label Attributes
8545 In GNU C, an attribute specifier list may appear after the colon following a
8546 label, other than a @code{case} or @code{default} label. GNU C++ only permits
8547 attributes on labels if the attribute specifier is immediately
8548 followed by a semicolon (i.e., the label applies to an empty
8549 statement). If the semicolon is missing, C++ label attributes are
8550 ambiguous, as it is permissible for a declaration, which could begin
8551 with an attribute list, to be labelled in C++. Declarations cannot be
8552 labelled in C90 or C99, so the ambiguity does not arise there.
8554 @subsubheading Enumerator Attributes
8556 In GNU C, an attribute specifier list may appear as part of an enumerator.
8557 The attribute goes after the enumeration constant, before @code{=}, if
8558 present. The optional attribute in the enumerator appertains to the
8559 enumeration constant. It is not possible to place the attribute after
8560 the constant expression, if present.
8562 @subsubheading Statement Attributes
8563 In GNU C, an attribute specifier list may appear as part of a null
8564 statement. The attribute goes before the semicolon.
8566 @subsubheading Type Attributes
8568 An attribute specifier list may appear as part of a @code{struct},
8569 @code{union} or @code{enum} specifier. It may go either immediately
8570 after the @code{struct}, @code{union} or @code{enum} keyword, or after
8571 the closing brace. The former syntax is preferred.
8572 Where attribute specifiers follow the closing brace, they are considered
8573 to relate to the structure, union or enumerated type defined, not to any
8574 enclosing declaration the type specifier appears in, and the type
8575 defined is not complete until after the attribute specifiers.
8576 @c Otherwise, there would be the following problems: a shift/reduce
8577 @c conflict between attributes binding the struct/union/enum and
8578 @c binding to the list of specifiers/qualifiers; and "aligned"
8579 @c attributes could use sizeof for the structure, but the size could be
8580 @c changed later by "packed" attributes.
8583 @subsubheading All other attributes
8585 Otherwise, an attribute specifier appears as part of a declaration,
8586 counting declarations of unnamed parameters and type names, and relates
8587 to that declaration (which may be nested in another declaration, for
8588 example in the case of a parameter declaration), or to a particular declarator
8589 within a declaration. Where an
8590 attribute specifier is applied to a parameter declared as a function or
8591 an array, it should apply to the function or array rather than the
8592 pointer to which the parameter is implicitly converted, but this is not
8593 yet correctly implemented.
8595 Any list of specifiers and qualifiers at the start of a declaration may
8596 contain attribute specifiers, whether or not such a list may in that
8597 context contain storage class specifiers. (Some attributes, however,
8598 are essentially in the nature of storage class specifiers, and only make
8599 sense where storage class specifiers may be used; for example,
8600 @code{section}.) There is one necessary limitation to this syntax: the
8601 first old-style parameter declaration in a function definition cannot
8602 begin with an attribute specifier, because such an attribute applies to
8603 the function instead by syntax described below (which, however, is not
8604 yet implemented in this case). In some other cases, attribute
8605 specifiers are permitted by this grammar but not yet supported by the
8606 compiler. All attribute specifiers in this place relate to the
8607 declaration as a whole. In the obsolescent usage where a type of
8608 @code{int} is implied by the absence of type specifiers, such a list of
8609 specifiers and qualifiers may be an attribute specifier list with no
8610 other specifiers or qualifiers.
8612 At present, the first parameter in a function prototype must have some
8613 type specifier that is not an attribute specifier; this resolves an
8614 ambiguity in the interpretation of @code{void f(int
8615 (__attribute__((foo)) x))}, but is subject to change. At present, if
8616 the parentheses of a function declarator contain only attributes then
8617 those attributes are ignored, rather than yielding an error or warning
8618 or implying a single parameter of type int, but this is subject to
8621 An attribute specifier list may appear immediately before a declarator
8622 (other than the first) in a comma-separated list of declarators in a
8623 declaration of more than one identifier using a single list of
8624 specifiers and qualifiers. Such attribute specifiers apply
8625 only to the identifier before whose declarator they appear. For
8629 __attribute__((noreturn)) void d0 (void),
8630 __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
8635 the @code{noreturn} attribute applies to all the functions
8636 declared; the @code{format} attribute only applies to @code{d1}.
8638 An attribute specifier list may appear immediately before the comma,
8639 @code{=} or semicolon terminating the declaration of an identifier other
8640 than a function definition. Such attribute specifiers apply
8641 to the declared object or function. Where an
8642 assembler name for an object or function is specified (@pxref{Asm
8643 Labels}), the attribute must follow the @code{asm}
8646 An attribute specifier list may, in future, be permitted to appear after
8647 the declarator in a function definition (before any old-style parameter
8648 declarations or the function body).
8650 Attribute specifiers may be mixed with type qualifiers appearing inside
8651 the @code{[]} of a parameter array declarator, in the C99 construct by
8652 which such qualifiers are applied to the pointer to which the array is
8653 implicitly converted. Such attribute specifiers apply to the pointer,
8654 not to the array, but at present this is not implemented and they are
8657 An attribute specifier list may appear at the start of a nested
8658 declarator. At present, there are some limitations in this usage: the
8659 attributes correctly apply to the declarator, but for most individual
8660 attributes the semantics this implies are not implemented.
8661 When attribute specifiers follow the @code{*} of a pointer
8662 declarator, they may be mixed with any type qualifiers present.
8663 The following describes the formal semantics of this syntax. It makes the
8664 most sense if you are familiar with the formal specification of
8665 declarators in the ISO C standard.
8667 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
8668 D1}, where @code{T} contains declaration specifiers that specify a type
8669 @var{Type} (such as @code{int}) and @code{D1} is a declarator that
8670 contains an identifier @var{ident}. The type specified for @var{ident}
8671 for derived declarators whose type does not include an attribute
8672 specifier is as in the ISO C standard.
8674 If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
8675 and the declaration @code{T D} specifies the type
8676 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
8677 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
8678 @var{attribute-specifier-list} @var{Type}'' for @var{ident}.
8680 If @code{D1} has the form @code{*
8681 @var{type-qualifier-and-attribute-specifier-list} D}, and the
8682 declaration @code{T D} specifies the type
8683 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
8684 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
8685 @var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for
8691 void (__attribute__((noreturn)) ****f) (void);
8695 specifies the type ``pointer to pointer to pointer to pointer to
8696 non-returning function returning @code{void}''. As another example,
8699 char *__attribute__((aligned(8))) *f;
8703 specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
8704 Note again that this does not work with most attributes; for example,
8705 the usage of @samp{aligned} and @samp{noreturn} attributes given above
8706 is not yet supported.
8708 For compatibility with existing code written for compiler versions that
8709 did not implement attributes on nested declarators, some laxity is
8710 allowed in the placing of attributes. If an attribute that only applies
8711 to types is applied to a declaration, it is treated as applying to
8712 the type of that declaration. If an attribute that only applies to
8713 declarations is applied to the type of a declaration, it is treated
8714 as applying to that declaration; and, for compatibility with code
8715 placing the attributes immediately before the identifier declared, such
8716 an attribute applied to a function return type is treated as
8717 applying to the function type, and such an attribute applied to an array
8718 element type is treated as applying to the array type. If an
8719 attribute that only applies to function types is applied to a
8720 pointer-to-function type, it is treated as applying to the pointer
8721 target type; if such an attribute is applied to a function return type
8722 that is not a pointer-to-function type, it is treated as applying
8723 to the function type.
8725 @node Function Prototypes
8726 @section Prototypes and Old-Style Function Definitions
8727 @cindex function prototype declarations
8728 @cindex old-style function definitions
8729 @cindex promotion of formal parameters
8731 GNU C extends ISO C to allow a function prototype to override a later
8732 old-style non-prototype definition. Consider the following example:
8735 /* @r{Use prototypes unless the compiler is old-fashioned.} */
8742 /* @r{Prototype function declaration.} */
8743 int isroot P((uid_t));
8745 /* @r{Old-style function definition.} */
8747 isroot (x) /* @r{??? lossage here ???} */
8754 Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
8755 not allow this example, because subword arguments in old-style
8756 non-prototype definitions are promoted. Therefore in this example the
8757 function definition's argument is really an @code{int}, which does not
8758 match the prototype argument type of @code{short}.
8760 This restriction of ISO C makes it hard to write code that is portable
8761 to traditional C compilers, because the programmer does not know
8762 whether the @code{uid_t} type is @code{short}, @code{int}, or
8763 @code{long}. Therefore, in cases like these GNU C allows a prototype
8764 to override a later old-style definition. More precisely, in GNU C, a
8765 function prototype argument type overrides the argument type specified
8766 by a later old-style definition if the former type is the same as the
8767 latter type before promotion. Thus in GNU C the above example is
8768 equivalent to the following:
8781 GNU C++ does not support old-style function definitions, so this
8782 extension is irrelevant.
8785 @section C++ Style Comments
8787 @cindex C++ comments
8788 @cindex comments, C++ style
8790 In GNU C, you may use C++ style comments, which start with @samp{//} and
8791 continue until the end of the line. Many other C implementations allow
8792 such comments, and they are included in the 1999 C standard. However,
8793 C++ style comments are not recognized if you specify an @option{-std}
8794 option specifying a version of ISO C before C99, or @option{-ansi}
8795 (equivalent to @option{-std=c90}).
8798 @section Dollar Signs in Identifier Names
8800 @cindex dollar signs in identifier names
8801 @cindex identifier names, dollar signs in
8803 In GNU C, you may normally use dollar signs in identifier names.
8804 This is because many traditional C implementations allow such identifiers.
8805 However, dollar signs in identifiers are not supported on a few target
8806 machines, typically because the target assembler does not allow them.
8808 @node Character Escapes
8809 @section The Character @key{ESC} in Constants
8811 You can use the sequence @samp{\e} in a string or character constant to
8812 stand for the ASCII character @key{ESC}.
8815 @section Determining the Alignment of Functions, Types or Variables
8817 @cindex type alignment
8818 @cindex variable alignment
8820 The keyword @code{__alignof__} determines the alignment requirement of
8821 a function, object, or a type, or the minimum alignment usually required
8822 by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}.
8824 For example, if the target machine requires a @code{double} value to be
8825 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
8826 This is true on many RISC machines. On more traditional machine
8827 designs, @code{__alignof__ (double)} is 4 or even 2.
8829 Some machines never actually require alignment; they allow references to any
8830 data type even at an odd address. For these machines, @code{__alignof__}
8831 reports the smallest alignment that GCC gives the data type, usually as
8832 mandated by the target ABI.
8834 If the operand of @code{__alignof__} is an lvalue rather than a type,
8835 its value is the required alignment for its type, taking into account
8836 any minimum alignment specified by attribute @code{aligned}
8837 (@pxref{Common Variable Attributes}). For example, after this
8841 struct foo @{ int x; char y; @} foo1;
8845 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
8846 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
8847 It is an error to ask for the alignment of an incomplete type other
8850 If the operand of the @code{__alignof__} expression is a function,
8851 the expression evaluates to the alignment of the function which may
8852 be specified by attribute @code{aligned} (@pxref{Common Function Attributes}).
8855 @section An Inline Function is As Fast As a Macro
8856 @cindex inline functions
8857 @cindex integrating function code
8859 @cindex macros, inline alternative
8861 By declaring a function inline, you can direct GCC to make
8862 calls to that function faster. One way GCC can achieve this is to
8863 integrate that function's code into the code for its callers. This
8864 makes execution faster by eliminating the function-call overhead; in
8865 addition, if any of the actual argument values are constant, their
8866 known values may permit simplifications at compile time so that not
8867 all of the inline function's code needs to be included. The effect on
8868 code size is less predictable; object code may be larger or smaller
8869 with function inlining, depending on the particular case. You can
8870 also direct GCC to try to integrate all ``simple enough'' functions
8871 into their callers with the option @option{-finline-functions}.
8873 GCC implements three different semantics of declaring a function
8874 inline. One is available with @option{-std=gnu89} or
8875 @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
8876 on all inline declarations, another when
8878 @option{-std=gnu99} or an option for a later C version is used
8879 (without @option{-fgnu89-inline}), and the third
8880 is used when compiling C++.
8882 To declare a function inline, use the @code{inline} keyword in its
8883 declaration, like this:
8893 If you are writing a header file to be included in ISO C90 programs, write
8894 @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
8896 The three types of inlining behave similarly in two important cases:
8897 when the @code{inline} keyword is used on a @code{static} function,
8898 like the example above, and when a function is first declared without
8899 using the @code{inline} keyword and then is defined with
8900 @code{inline}, like this:
8903 extern int inc (int *a);
8911 In both of these common cases, the program behaves the same as if you
8912 had not used the @code{inline} keyword, except for its speed.
8914 @cindex inline functions, omission of
8915 @opindex fkeep-inline-functions
8916 When a function is both inline and @code{static}, if all calls to the
8917 function are integrated into the caller, and the function's address is
8918 never used, then the function's own assembler code is never referenced.
8919 In this case, GCC does not actually output assembler code for the
8920 function, unless you specify the option @option{-fkeep-inline-functions}.
8921 If there is a nonintegrated call, then the function is compiled to
8922 assembler code as usual. The function must also be compiled as usual if
8923 the program refers to its address, because that cannot be inlined.
8926 Note that certain usages in a function definition can make it unsuitable
8927 for inline substitution. Among these usages are: variadic functions,
8928 use of @code{alloca}, use of computed goto (@pxref{Labels as Values}),
8929 use of nonlocal goto, use of nested functions, use of @code{setjmp}, use
8930 of @code{__builtin_longjmp} and use of @code{__builtin_return} or
8931 @code{__builtin_apply_args}. Using @option{-Winline} warns when a
8932 function marked @code{inline} could not be substituted, and gives the
8933 reason for the failure.
8935 @cindex automatic @code{inline} for C++ member fns
8936 @cindex @code{inline} automatic for C++ member fns
8937 @cindex member fns, automatically @code{inline}
8938 @cindex C++ member fns, automatically @code{inline}
8939 @opindex fno-default-inline
8940 As required by ISO C++, GCC considers member functions defined within
8941 the body of a class to be marked inline even if they are
8942 not explicitly declared with the @code{inline} keyword. You can
8943 override this with @option{-fno-default-inline}; @pxref{C++ Dialect
8944 Options,,Options Controlling C++ Dialect}.
8946 GCC does not inline any functions when not optimizing unless you specify
8947 the @samp{always_inline} attribute for the function, like this:
8950 /* @r{Prototype.} */
8951 inline void foo (const char) __attribute__((always_inline));
8954 The remainder of this section is specific to GNU C90 inlining.
8956 @cindex non-static inline function
8957 When an inline function is not @code{static}, then the compiler must assume
8958 that there may be calls from other source files; since a global symbol can
8959 be defined only once in any program, the function must not be defined in
8960 the other source files, so the calls therein cannot be integrated.
8961 Therefore, a non-@code{static} inline function is always compiled on its
8962 own in the usual fashion.
8964 If you specify both @code{inline} and @code{extern} in the function
8965 definition, then the definition is used only for inlining. In no case
8966 is the function compiled on its own, not even if you refer to its
8967 address explicitly. Such an address becomes an external reference, as
8968 if you had only declared the function, and had not defined it.
8970 This combination of @code{inline} and @code{extern} has almost the
8971 effect of a macro. The way to use it is to put a function definition in
8972 a header file with these keywords, and put another copy of the
8973 definition (lacking @code{inline} and @code{extern}) in a library file.
8974 The definition in the header file causes most calls to the function
8975 to be inlined. If any uses of the function remain, they refer to
8976 the single copy in the library.
8979 @section When is a Volatile Object Accessed?
8980 @cindex accessing volatiles
8981 @cindex volatile read
8982 @cindex volatile write
8983 @cindex volatile access
8985 C has the concept of volatile objects. These are normally accessed by
8986 pointers and used for accessing hardware or inter-thread
8987 communication. The standard encourages compilers to refrain from
8988 optimizations concerning accesses to volatile objects, but leaves it
8989 implementation defined as to what constitutes a volatile access. The
8990 minimum requirement is that at a sequence point all previous accesses
8991 to volatile objects have stabilized and no subsequent accesses have
8992 occurred. Thus an implementation is free to reorder and combine
8993 volatile accesses that occur between sequence points, but cannot do
8994 so for accesses across a sequence point. The use of volatile does
8995 not allow you to violate the restriction on updating objects multiple
8996 times between two sequence points.
8998 Accesses to non-volatile objects are not ordered with respect to
8999 volatile accesses. You cannot use a volatile object as a memory
9000 barrier to order a sequence of writes to non-volatile memory. For
9004 int *ptr = @var{something};
9006 *ptr = @var{something};
9011 Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed
9012 that the write to @var{*ptr} occurs by the time the update
9013 of @var{vobj} happens. If you need this guarantee, you must use
9014 a stronger memory barrier such as:
9017 int *ptr = @var{something};
9019 *ptr = @var{something};
9020 asm volatile ("" : : : "memory");
9024 A scalar volatile object is read when it is accessed in a void context:
9027 volatile int *src = @var{somevalue};
9031 Such expressions are rvalues, and GCC implements this as a
9032 read of the volatile object being pointed to.
9034 Assignments are also expressions and have an rvalue. However when
9035 assigning to a scalar volatile, the volatile object is not reread,
9036 regardless of whether the assignment expression's rvalue is used or
9037 not. If the assignment's rvalue is used, the value is that assigned
9038 to the volatile object. For instance, there is no read of @var{vobj}
9039 in all the following cases:
9044 vobj = @var{something};
9045 obj = vobj = @var{something};
9046 obj ? vobj = @var{onething} : vobj = @var{anotherthing};
9047 obj = (@var{something}, vobj = @var{anotherthing});
9050 If you need to read the volatile object after an assignment has
9051 occurred, you must use a separate expression with an intervening
9054 As bit-fields are not individually addressable, volatile bit-fields may
9055 be implicitly read when written to, or when adjacent bit-fields are
9056 accessed. Bit-field operations may be optimized such that adjacent
9057 bit-fields are only partially accessed, if they straddle a storage unit
9058 boundary. For these reasons it is unwise to use volatile bit-fields to
9061 @node Using Assembly Language with C
9062 @section How to Use Inline Assembly Language in C Code
9063 @cindex @code{asm} keyword
9064 @cindex assembly language in C
9065 @cindex inline assembly language
9066 @cindex mixing assembly language and C
9068 The @code{asm} keyword allows you to embed assembler instructions
9069 within C code. GCC provides two forms of inline @code{asm}
9070 statements. A @dfn{basic @code{asm}} statement is one with no
9071 operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}}
9072 statement (@pxref{Extended Asm}) includes one or more operands.
9073 The extended form is preferred for mixing C and assembly language
9074 within a function, but to include assembly language at
9075 top level you must use basic @code{asm}.
9077 You can also use the @code{asm} keyword to override the assembler name
9078 for a C symbol, or to place a C variable in a specific register.
9081 * Basic Asm:: Inline assembler without operands.
9082 * Extended Asm:: Inline assembler with operands.
9083 * Constraints:: Constraints for @code{asm} operands
9084 * Asm Labels:: Specifying the assembler name to use for a C symbol.
9085 * Explicit Register Variables:: Defining variables residing in specified
9087 * Size of an asm:: How GCC calculates the size of an @code{asm} block.
9091 @subsection Basic Asm --- Assembler Instructions Without Operands
9092 @cindex basic @code{asm}
9093 @cindex assembly language in C, basic
9095 A basic @code{asm} statement has the following syntax:
9098 asm @var{asm-qualifiers} ( @var{AssemblerInstructions} )
9101 The @code{asm} keyword is a GNU extension.
9102 When writing code that can be compiled with @option{-ansi} and the
9103 various @option{-std} options, use @code{__asm__} instead of
9104 @code{asm} (@pxref{Alternate Keywords}).
9106 @subsubheading Qualifiers
9109 The optional @code{volatile} qualifier has no effect.
9110 All basic @code{asm} blocks are implicitly volatile.
9113 If you use the @code{inline} qualifier, then for inlining purposes the size
9114 of the @code{asm} statement is taken as the smallest size possible (@pxref{Size
9118 @subsubheading Parameters
9121 @item AssemblerInstructions
9122 This is a literal string that specifies the assembler code. The string can
9123 contain any instructions recognized by the assembler, including directives.
9124 GCC does not parse the assembler instructions themselves and
9125 does not know what they mean or even whether they are valid assembler input.
9127 You may place multiple assembler instructions together in a single @code{asm}
9128 string, separated by the characters normally used in assembly code for the
9129 system. A combination that works in most places is a newline to break the
9130 line, plus a tab character (written as @samp{\n\t}).
9131 Some assemblers allow semicolons as a line separator. However,
9132 note that some assembler dialects use semicolons to start a comment.
9135 @subsubheading Remarks
9136 Using extended @code{asm} (@pxref{Extended Asm}) typically produces
9137 smaller, safer, and more efficient code, and in most cases it is a
9138 better solution than basic @code{asm}. However, there are two
9139 situations where only basic @code{asm} can be used:
9143 Extended @code{asm} statements have to be inside a C
9144 function, so to write inline assembly language at file scope (``top-level''),
9145 outside of C functions, you must use basic @code{asm}.
9146 You can use this technique to emit assembler directives,
9147 define assembly language macros that can be invoked elsewhere in the file,
9148 or write entire functions in assembly language.
9149 Basic @code{asm} statements outside of functions may not use any
9154 with the @code{naked} attribute also require basic @code{asm}
9155 (@pxref{Function Attributes}).
9158 Safely accessing C data and calling functions from basic @code{asm} is more
9159 complex than it may appear. To access C data, it is better to use extended
9162 Do not expect a sequence of @code{asm} statements to remain perfectly
9163 consecutive after compilation. If certain instructions need to remain
9164 consecutive in the output, put them in a single multi-instruction @code{asm}
9165 statement. Note that GCC's optimizers can move @code{asm} statements
9166 relative to other code, including across jumps.
9168 @code{asm} statements may not perform jumps into other @code{asm} statements.
9169 GCC does not know about these jumps, and therefore cannot take
9170 account of them when deciding how to optimize. Jumps from @code{asm} to C
9171 labels are only supported in extended @code{asm}.
9173 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
9174 assembly code when optimizing. This can lead to unexpected duplicate
9175 symbol errors during compilation if your assembly code defines symbols or
9178 @strong{Warning:} The C standards do not specify semantics for @code{asm},
9179 making it a potential source of incompatibilities between compilers. These
9180 incompatibilities may not produce compiler warnings/errors.
9182 GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which
9183 means there is no way to communicate to the compiler what is happening
9184 inside them. GCC has no visibility of symbols in the @code{asm} and may
9185 discard them as unreferenced. It also does not know about side effects of
9186 the assembler code, such as modifications to memory or registers. Unlike
9187 some compilers, GCC assumes that no changes to general purpose registers
9188 occur. This assumption may change in a future release.
9190 To avoid complications from future changes to the semantics and the
9191 compatibility issues between compilers, consider replacing basic @code{asm}
9192 with extended @code{asm}. See
9193 @uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert
9194 from basic asm to extended asm} for information about how to perform this
9197 The compiler copies the assembler instructions in a basic @code{asm}
9198 verbatim to the assembly language output file, without
9199 processing dialects or any of the @samp{%} operators that are available with
9200 extended @code{asm}. This results in minor differences between basic
9201 @code{asm} strings and extended @code{asm} templates. For example, to refer to
9202 registers you might use @samp{%eax} in basic @code{asm} and
9203 @samp{%%eax} in extended @code{asm}.
9205 On targets such as x86 that support multiple assembler dialects,
9206 all basic @code{asm} blocks use the assembler dialect specified by the
9207 @option{-masm} command-line option (@pxref{x86 Options}).
9208 Basic @code{asm} provides no
9209 mechanism to provide different assembler strings for different dialects.
9211 For basic @code{asm} with non-empty assembler string GCC assumes
9212 the assembler block does not change any general purpose registers,
9213 but it may read or write any globally accessible variable.
9215 Here is an example of basic @code{asm} for i386:
9218 /* Note that this code will not compile with -masm=intel */
9219 #define DebugBreak() asm("int $3")
9223 @subsection Extended Asm - Assembler Instructions with C Expression Operands
9224 @cindex extended @code{asm}
9225 @cindex assembly language in C, extended
9227 With extended @code{asm} you can read and write C variables from
9228 assembler and perform jumps from assembler code to C labels.
9229 Extended @code{asm} syntax uses colons (@samp{:}) to delimit
9230 the operand parameters after the assembler template:
9233 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9234 : @var{OutputOperands}
9235 @r{[} : @var{InputOperands}
9236 @r{[} : @var{Clobbers} @r{]} @r{]})
9238 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9240 : @var{InputOperands}
9244 where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the
9247 The @code{asm} keyword is a GNU extension.
9248 When writing code that can be compiled with @option{-ansi} and the
9249 various @option{-std} options, use @code{__asm__} instead of
9250 @code{asm} (@pxref{Alternate Keywords}).
9252 @subsubheading Qualifiers
9256 The typical use of extended @code{asm} statements is to manipulate input
9257 values to produce output values. However, your @code{asm} statements may
9258 also produce side effects. If so, you may need to use the @code{volatile}
9259 qualifier to disable certain optimizations. @xref{Volatile}.
9262 If you use the @code{inline} qualifier, then for inlining purposes the size
9263 of the @code{asm} statement is taken as the smallest size possible
9264 (@pxref{Size of an asm}).
9267 This qualifier informs the compiler that the @code{asm} statement may
9268 perform a jump to one of the labels listed in the @var{GotoLabels}.
9272 @subsubheading Parameters
9274 @item AssemblerTemplate
9275 This is a literal string that is the template for the assembler code. It is a
9276 combination of fixed text and tokens that refer to the input, output,
9277 and goto parameters. @xref{AssemblerTemplate}.
9279 @item OutputOperands
9280 A comma-separated list of the C variables modified by the instructions in the
9281 @var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}.
9284 A comma-separated list of C expressions read by the instructions in the
9285 @var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}.
9288 A comma-separated list of registers or other values changed by the
9289 @var{AssemblerTemplate}, beyond those listed as outputs.
9290 An empty list is permitted. @xref{Clobbers and Scratch Registers}.
9293 When you are using the @code{goto} form of @code{asm}, this section contains
9294 the list of all C labels to which the code in the
9295 @var{AssemblerTemplate} may jump.
9298 @code{asm} statements may not perform jumps into other @code{asm} statements,
9299 only to the listed @var{GotoLabels}.
9300 GCC's optimizers do not know about other jumps; therefore they cannot take
9301 account of them when deciding how to optimize.
9304 The total number of input + output + goto operands is limited to 30.
9306 @subsubheading Remarks
9307 The @code{asm} statement allows you to include assembly instructions directly
9308 within C code. This may help you to maximize performance in time-sensitive
9309 code or to access assembly instructions that are not readily available to C
9312 Note that extended @code{asm} statements must be inside a function. Only
9313 basic @code{asm} may be outside functions (@pxref{Basic Asm}).
9314 Functions declared with the @code{naked} attribute also require basic
9315 @code{asm} (@pxref{Function Attributes}).
9317 While the uses of @code{asm} are many and varied, it may help to think of an
9318 @code{asm} statement as a series of low-level instructions that convert input
9319 parameters to output parameters. So a simple (if not particularly useful)
9320 example for i386 using @code{asm} might look like this:
9326 asm ("mov %1, %0\n\t"
9331 printf("%d\n", dst);
9334 This code copies @code{src} to @code{dst} and add 1 to @code{dst}.
9337 @subsubsection Volatile
9338 @cindex volatile @code{asm}
9339 @cindex @code{asm} volatile
9341 GCC's optimizers sometimes discard @code{asm} statements if they determine
9342 there is no need for the output variables. Also, the optimizers may move
9343 code out of loops if they believe that the code will always return the same
9344 result (i.e.@: none of its input values change between calls). Using the
9345 @code{volatile} qualifier disables these optimizations. @code{asm} statements
9346 that have no output operands, including @code{asm goto} statements,
9347 are implicitly volatile.
9349 This i386 code demonstrates a case that does not use (or require) the
9350 @code{volatile} qualifier. If it is performing assertion checking, this code
9351 uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is
9352 unreferenced by any code. As a result, the optimizers can discard the
9353 @code{asm} statement, which in turn removes the need for the entire
9354 @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
9355 isn't needed you allow the optimizers to produce the most efficient code
9359 void DoCheck(uint32_t dwSomeValue)
9363 // Assumes dwSomeValue is not zero.
9373 The next example shows a case where the optimizers can recognize that the input
9374 (@code{dwSomeValue}) never changes during the execution of the function and can
9375 therefore move the @code{asm} outside the loop to produce more efficient code.
9376 Again, using the @code{volatile} qualifier disables this type of optimization.
9379 void do_print(uint32_t dwSomeValue)
9383 for (uint32_t x=0; x < 5; x++)
9385 // Assumes dwSomeValue is not zero.
9391 printf("%u: %u %u\n", x, dwSomeValue, dwRes);
9396 The following example demonstrates a case where you need to use the
9397 @code{volatile} qualifier.
9398 It uses the x86 @code{rdtsc} instruction, which reads
9399 the computer's time-stamp counter. Without the @code{volatile} qualifier,
9400 the optimizers might assume that the @code{asm} block will always return the
9401 same value and therefore optimize away the second call.
9406 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
9407 "shl $32, %%rdx\n\t" // Shift the upper bits left.
9408 "or %%rdx, %0" // 'Or' in the lower bits.
9413 printf("msr: %llx\n", msr);
9417 // Reprint the timestamp
9418 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
9419 "shl $32, %%rdx\n\t" // Shift the upper bits left.
9420 "or %%rdx, %0" // 'Or' in the lower bits.
9425 printf("msr: %llx\n", msr);
9428 GCC's optimizers do not treat this code like the non-volatile code in the
9429 earlier examples. They do not move it out of loops or omit it on the
9430 assumption that the result from a previous call is still valid.
9432 Note that the compiler can move even @code{volatile asm} instructions relative
9433 to other code, including across jump instructions. For example, on many
9434 targets there is a system register that controls the rounding mode of
9435 floating-point operations. Setting it with a @code{volatile asm} statement,
9436 as in the following PowerPC example, does not work reliably.
9439 asm volatile("mtfsf 255, %0" : : "f" (fpenv));
9443 The compiler may move the addition back before the @code{volatile asm}
9444 statement. To make it work as expected, add an artificial dependency to
9445 the @code{asm} by referencing a variable in the subsequent code, for
9449 asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
9453 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
9454 assembly code when optimizing. This can lead to unexpected duplicate symbol
9455 errors during compilation if your @code{asm} code defines symbols or labels.
9457 (@pxref{AssemblerTemplate}) may help resolve this problem.
9459 @anchor{AssemblerTemplate}
9460 @subsubsection Assembler Template
9461 @cindex @code{asm} assembler template
9463 An assembler template is a literal string containing assembler instructions.
9464 The compiler replaces tokens in the template that refer
9465 to inputs, outputs, and goto labels,
9466 and then outputs the resulting string to the assembler. The
9467 string can contain any instructions recognized by the assembler, including
9468 directives. GCC does not parse the assembler instructions
9469 themselves and does not know what they mean or even whether they are valid
9470 assembler input. However, it does count the statements
9471 (@pxref{Size of an asm}).
9473 You may place multiple assembler instructions together in a single @code{asm}
9474 string, separated by the characters normally used in assembly code for the
9475 system. A combination that works in most places is a newline to break the
9476 line, plus a tab character to move to the instruction field (written as
9478 Some assemblers allow semicolons as a line separator. However, note
9479 that some assembler dialects use semicolons to start a comment.
9481 Do not expect a sequence of @code{asm} statements to remain perfectly
9482 consecutive after compilation, even when you are using the @code{volatile}
9483 qualifier. If certain instructions need to remain consecutive in the output,
9484 put them in a single multi-instruction @code{asm} statement.
9486 Accessing data from C programs without using input/output operands (such as
9487 by using global symbols directly from the assembler template) may not work as
9488 expected. Similarly, calling functions directly from an assembler template
9489 requires a detailed understanding of the target assembler and ABI.
9491 Since GCC does not parse the assembler template,
9492 it has no visibility of any
9493 symbols it references. This may result in GCC discarding those symbols as
9494 unreferenced unless they are also listed as input, output, or goto operands.
9496 @subsubheading Special format strings
9498 In addition to the tokens described by the input, output, and goto operands,
9499 these tokens have special meanings in the assembler template:
9503 Outputs a single @samp{%} into the assembler code.
9506 Outputs a number that is unique to each instance of the @code{asm}
9507 statement in the entire compilation. This option is useful when creating local
9508 labels and referring to them multiple times in a single template that
9509 generates multiple assembler instructions.
9514 Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively)
9515 into the assembler code. When unescaped, these characters have special
9516 meaning to indicate multiple assembler dialects, as described below.
9519 @subsubheading Multiple assembler dialects in @code{asm} templates
9521 On targets such as x86, GCC supports multiple assembler dialects.
9522 The @option{-masm} option controls which dialect GCC uses as its
9523 default for inline assembler. The target-specific documentation for the
9524 @option{-masm} option contains the list of supported dialects, as well as the
9525 default dialect if the option is not specified. This information may be
9526 important to understand, since assembler code that works correctly when
9527 compiled using one dialect will likely fail if compiled using another.
9530 If your code needs to support multiple assembler dialects (for example, if
9531 you are writing public headers that need to support a variety of compilation
9532 options), use constructs of this form:
9535 @{ dialect0 | dialect1 | dialect2... @}
9538 This construct outputs @code{dialect0}
9539 when using dialect #0 to compile the code,
9540 @code{dialect1} for dialect #1, etc. If there are fewer alternatives within the
9541 braces than the number of dialects the compiler supports, the construct
9544 For example, if an x86 compiler supports two dialects
9545 (@samp{att}, @samp{intel}), an
9546 assembler template such as this:
9549 "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
9553 is equivalent to one of
9556 "btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */}
9557 "bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */}
9560 Using that same compiler, this code:
9563 "xchg@{l@}\t@{%%@}ebx, %1"
9567 corresponds to either
9570 "xchgl\t%%ebx, %1" @r{/* att dialect */}
9571 "xchg\tebx, %1" @r{/* intel dialect */}
9574 There is no support for nesting dialect alternatives.
9576 @anchor{OutputOperands}
9577 @subsubsection Output Operands
9578 @cindex @code{asm} output operands
9580 An @code{asm} statement has zero or more output operands indicating the names
9581 of C variables modified by the assembler code.
9583 In this i386 example, @code{old} (referred to in the template string as
9584 @code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset}
9585 (@code{%2}) is an input:
9590 __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
9591 "sbb %0,%0" // Use the CF to calculate old.
9592 : "=r" (old), "+rm" (*Base)
9599 Operands are separated by commas. Each operand has this format:
9602 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename})
9606 @item asmSymbolicName
9607 Specifies a symbolic name for the operand.
9608 Reference the name in the assembler template
9609 by enclosing it in square brackets
9610 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
9611 that contains the definition. Any valid C variable name is acceptable,
9612 including names already defined in the surrounding code. No two operands
9613 within the same @code{asm} statement can use the same symbolic name.
9615 When not using an @var{asmSymbolicName}, use the (zero-based) position
9617 in the list of operands in the assembler template. For example if there are
9618 three output operands, use @samp{%0} in the template to refer to the first,
9619 @samp{%1} for the second, and @samp{%2} for the third.
9622 A string constant specifying constraints on the placement of the operand;
9623 @xref{Constraints}, for details.
9625 Output constraints must begin with either @samp{=} (a variable overwriting an
9626 existing value) or @samp{+} (when reading and writing). When using
9627 @samp{=}, do not assume the location contains the existing value
9628 on entry to the @code{asm}, except
9629 when the operand is tied to an input; @pxref{InputOperands,,Input Operands}.
9631 After the prefix, there must be one or more additional constraints
9632 (@pxref{Constraints}) that describe where the value resides. Common
9633 constraints include @samp{r} for register and @samp{m} for memory.
9634 When you list more than one possible location (for example, @code{"=rm"}),
9635 the compiler chooses the most efficient one based on the current context.
9636 If you list as many alternates as the @code{asm} statement allows, you permit
9637 the optimizers to produce the best possible code.
9638 If you must use a specific register, but your Machine Constraints do not
9639 provide sufficient control to select the specific register you want,
9640 local register variables may provide a solution (@pxref{Local Register
9644 Specifies a C lvalue expression to hold the output, typically a variable name.
9645 The enclosing parentheses are a required part of the syntax.
9649 When the compiler selects the registers to use to
9650 represent the output operands, it does not use any of the clobbered registers
9651 (@pxref{Clobbers and Scratch Registers}).
9653 Output operand expressions must be lvalues. The compiler cannot check whether
9654 the operands have data types that are reasonable for the instruction being
9655 executed. For output expressions that are not directly addressable (for
9656 example a bit-field), the constraint must allow a register. In that case, GCC
9657 uses the register as the output of the @code{asm}, and then stores that
9658 register into the output.
9660 Operands using the @samp{+} constraint modifier count as two operands
9661 (that is, both as input and output) towards the total maximum of 30 operands
9662 per @code{asm} statement.
9664 Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output
9665 operands that must not overlap an input. Otherwise,
9666 GCC may allocate the output operand in the same register as an unrelated
9667 input operand, on the assumption that the assembler code consumes its
9668 inputs before producing outputs. This assumption may be false if the assembler
9669 code actually consists of more than one instruction.
9671 The same problem can occur if one output parameter (@var{a}) allows a register
9672 constraint and another output parameter (@var{b}) allows a memory constraint.
9673 The code generated by GCC to access the memory address in @var{b} can contain
9674 registers which @emph{might} be shared by @var{a}, and GCC considers those
9675 registers to be inputs to the asm. As above, GCC assumes that such input
9676 registers are consumed before any outputs are written. This assumption may
9677 result in incorrect behavior if the @code{asm} statement writes to @var{a}
9679 @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a}
9680 ensures that modifying @var{a} does not affect the address referenced by
9681 @var{b}. Otherwise, the location of @var{b}
9682 is undefined if @var{a} is modified before using @var{b}.
9684 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
9685 instead of simply @samp{%2}). Typically these qualifiers are hardware
9686 dependent. The list of supported modifiers for x86 is found at
9687 @ref{x86Operandmodifiers,x86 Operand modifiers}.
9689 If the C code that follows the @code{asm} makes no use of any of the output
9690 operands, use @code{volatile} for the @code{asm} statement to prevent the
9691 optimizers from discarding the @code{asm} statement as unneeded
9692 (see @ref{Volatile}).
9694 This code makes no use of the optional @var{asmSymbolicName}. Therefore it
9695 references the first output operand as @code{%0} (were there a second, it
9696 would be @code{%1}, etc). The number of the first input operand is one greater
9697 than that of the last output operand. In this i386 example, that makes
9698 @code{Mask} referenced as @code{%1}:
9701 uint32_t Mask = 1234;
9710 That code overwrites the variable @code{Index} (@samp{=}),
9711 placing the value in a register (@samp{r}).
9712 Using the generic @samp{r} constraint instead of a constraint for a specific
9713 register allows the compiler to pick the register to use, which can result
9714 in more efficient code. This may not be possible if an assembler instruction
9715 requires a specific register.
9717 The following i386 example uses the @var{asmSymbolicName} syntax.
9719 same result as the code above, but some may consider it more readable or more
9720 maintainable since reordering index numbers is not necessary when adding or
9721 removing operands. The names @code{aIndex} and @code{aMask}
9722 are only used in this example to emphasize which
9723 names get used where.
9724 It is acceptable to reuse the names @code{Index} and @code{Mask}.
9727 uint32_t Mask = 1234;
9730 asm ("bsfl %[aMask], %[aIndex]"
9731 : [aIndex] "=r" (Index)
9732 : [aMask] "r" (Mask)
9736 Here are some more examples of output operands.
9743 asm ("mov %[e], %[d]"
9748 Here, @code{d} may either be in a register or in memory. Since the compiler
9749 might already have the current value of the @code{uint32_t} location
9750 pointed to by @code{e}
9751 in a register, you can enable it to choose the best location
9752 for @code{d} by specifying both constraints.
9754 @anchor{FlagOutputOperands}
9755 @subsubsection Flag Output Operands
9756 @cindex @code{asm} flag output operands
9758 Some targets have a special register that holds the ``flags'' for the
9759 result of an operation or comparison. Normally, the contents of that
9760 register are either unmodifed by the asm, or the @code{asm} statement is
9761 considered to clobber the contents.
9763 On some targets, a special form of output operand exists by which
9764 conditions in the flags register may be outputs of the asm. The set of
9765 conditions supported are target specific, but the general rule is that
9766 the output variable must be a scalar integer, and the value is boolean.
9767 When supported, the target defines the preprocessor symbol
9768 @code{__GCC_ASM_FLAG_OUTPUTS__}.
9770 Because of the special nature of the flag output operands, the constraint
9771 may not include alternatives.
9773 Most often, the target has only one flags register, and thus is an implied
9774 operand of many instructions. In this case, the operand should not be
9775 referenced within the assembler template via @code{%0} etc, as there's
9776 no corresponding text in the assembly language.
9780 The flag output constraints for the x86 family are of the form
9781 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
9782 conditions defined in the ISA manual for @code{j@var{cc}} or
9787 ``above'' or unsigned greater than
9789 ``above or equal'' or unsigned greater than or equal
9791 ``below'' or unsigned less than
9793 ``below or equal'' or unsigned less than or equal
9798 ``equal'' or zero flag set
9802 signed greater than or equal
9806 signed less than or equal
9827 ``not'' @var{flag}, or inverted versions of those above
9832 @anchor{InputOperands}
9833 @subsubsection Input Operands
9834 @cindex @code{asm} input operands
9835 @cindex @code{asm} expressions
9837 Input operands make values from C variables and expressions available to the
9840 Operands are separated by commas. Each operand has this format:
9843 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression})
9847 @item asmSymbolicName
9848 Specifies a symbolic name for the operand.
9849 Reference the name in the assembler template
9850 by enclosing it in square brackets
9851 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
9852 that contains the definition. Any valid C variable name is acceptable,
9853 including names already defined in the surrounding code. No two operands
9854 within the same @code{asm} statement can use the same symbolic name.
9856 When not using an @var{asmSymbolicName}, use the (zero-based) position
9858 in the list of operands in the assembler template. For example if there are
9859 two output operands and three inputs,
9860 use @samp{%2} in the template to refer to the first input operand,
9861 @samp{%3} for the second, and @samp{%4} for the third.
9864 A string constant specifying constraints on the placement of the operand;
9865 @xref{Constraints}, for details.
9867 Input constraint strings may not begin with either @samp{=} or @samp{+}.
9868 When you list more than one possible location (for example, @samp{"irm"}),
9869 the compiler chooses the most efficient one based on the current context.
9870 If you must use a specific register, but your Machine Constraints do not
9871 provide sufficient control to select the specific register you want,
9872 local register variables may provide a solution (@pxref{Local Register
9875 Input constraints can also be digits (for example, @code{"0"}). This indicates
9876 that the specified input must be in the same place as the output constraint
9877 at the (zero-based) index in the output constraint list.
9878 When using @var{asmSymbolicName} syntax for the output operands,
9879 you may use these names (enclosed in brackets @samp{[]}) instead of digits.
9882 This is the C variable or expression being passed to the @code{asm} statement
9883 as input. The enclosing parentheses are a required part of the syntax.
9887 When the compiler selects the registers to use to represent the input
9888 operands, it does not use any of the clobbered registers
9889 (@pxref{Clobbers and Scratch Registers}).
9891 If there are no output operands but there are input operands, place two
9892 consecutive colons where the output operands would go:
9895 __asm__ ("some instructions"
9897 : "r" (Offset / 8));
9900 @strong{Warning:} Do @emph{not} modify the contents of input-only operands
9901 (except for inputs tied to outputs). The compiler assumes that on exit from
9902 the @code{asm} statement these operands contain the same values as they
9903 had before executing the statement.
9904 It is @emph{not} possible to use clobbers
9905 to inform the compiler that the values in these inputs are changing. One
9906 common work-around is to tie the changing input variable to an output variable
9907 that never gets used. Note, however, that if the code that follows the
9908 @code{asm} statement makes no use of any of the output operands, the GCC
9909 optimizers may discard the @code{asm} statement as unneeded
9910 (see @ref{Volatile}).
9912 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
9913 instead of simply @samp{%2}). Typically these qualifiers are hardware
9914 dependent. The list of supported modifiers for x86 is found at
9915 @ref{x86Operandmodifiers,x86 Operand modifiers}.
9917 In this example using the fictitious @code{combine} instruction, the
9918 constraint @code{"0"} for input operand 1 says that it must occupy the same
9919 location as output operand 0. Only input operands may use numbers in
9920 constraints, and they must each refer to an output operand. Only a number (or
9921 the symbolic assembler name) in the constraint can guarantee that one operand
9922 is in the same place as another. The mere fact that @code{foo} is the value of
9923 both operands is not enough to guarantee that they are in the same place in
9924 the generated assembler code.
9927 asm ("combine %2, %0"
9929 : "0" (foo), "g" (bar));
9932 Here is an example using symbolic names.
9935 asm ("cmoveq %1, %2, %[result]"
9936 : [result] "=r"(result)
9937 : "r" (test), "r" (new), "[result]" (old));
9940 @anchor{Clobbers and Scratch Registers}
9941 @subsubsection Clobbers and Scratch Registers
9942 @cindex @code{asm} clobbers
9943 @cindex @code{asm} scratch registers
9945 While the compiler is aware of changes to entries listed in the output
9946 operands, the inline @code{asm} code may modify more than just the outputs. For
9947 example, calculations may require additional registers, or the processor may
9948 overwrite a register as a side effect of a particular assembler instruction.
9949 In order to inform the compiler of these changes, list them in the clobber
9950 list. Clobber list items are either register names or the special clobbers
9951 (listed below). Each clobber list item is a string constant
9952 enclosed in double quotes and separated by commas.
9954 Clobber descriptions may not in any way overlap with an input or output
9955 operand. For example, you may not have an operand describing a register class
9956 with one member when listing that register in the clobber list. Variables
9957 declared to live in specific registers (@pxref{Explicit Register
9958 Variables}) and used
9959 as @code{asm} input or output operands must have no part mentioned in the
9960 clobber description. In particular, there is no way to specify that input
9961 operands get modified without also specifying them as output operands.
9963 When the compiler selects which registers to use to represent input and output
9964 operands, it does not use any of the clobbered registers. As a result,
9965 clobbered registers are available for any use in the assembler code.
9967 Another restriction is that the clobber list should not contain the
9968 stack pointer register. This is because the compiler requires the
9969 value of the stack pointer to be the same after an @code{asm}
9970 statement as it was on entry to the statement. However, previous
9971 versions of GCC did not enforce this rule and allowed the stack
9972 pointer to appear in the list, with unclear semantics. This behavior
9973 is deprecated and listing the stack pointer may become an error in
9974 future versions of GCC@.
9976 Here is a realistic example for the VAX showing the use of clobbered
9980 asm volatile ("movc3 %0, %1, %2"
9982 : "g" (from), "g" (to), "g" (count)
9983 : "r0", "r1", "r2", "r3", "r4", "r5", "memory");
9986 Also, there are two special clobber arguments:
9990 The @code{"cc"} clobber indicates that the assembler code modifies the flags
9991 register. On some machines, GCC represents the condition codes as a specific
9992 hardware register; @code{"cc"} serves to name this register.
9993 On other machines, condition code handling is different,
9994 and specifying @code{"cc"} has no effect. But
9995 it is valid no matter what the target.
9998 The @code{"memory"} clobber tells the compiler that the assembly code
10000 reads or writes to items other than those listed in the input and output
10001 operands (for example, accessing the memory pointed to by one of the input
10002 parameters). To ensure memory contains correct values, GCC may need to flush
10003 specific register values to memory before executing the @code{asm}. Further,
10004 the compiler does not assume that any values read from memory before an
10005 @code{asm} remain unchanged after that @code{asm}; it reloads them as
10007 Using the @code{"memory"} clobber effectively forms a read/write
10008 memory barrier for the compiler.
10010 Note that this clobber does not prevent the @emph{processor} from doing
10011 speculative reads past the @code{asm} statement. To prevent that, you need
10012 processor-specific fence instructions.
10016 Flushing registers to memory has performance implications and may be
10017 an issue for time-sensitive code. You can provide better information
10018 to GCC to avoid this, as shown in the following examples. At a
10019 minimum, aliasing rules allow GCC to know what memory @emph{doesn't}
10020 need to be flushed.
10022 Here is a fictitious sum of squares instruction, that takes two
10023 pointers to floating point values in memory and produces a floating
10024 point register output.
10025 Notice that @code{x}, and @code{y} both appear twice in the @code{asm}
10026 parameters, once to specify memory accessed, and once to specify a
10027 base register used by the @code{asm}. You won't normally be wasting a
10028 register by doing this as GCC can use the same register for both
10029 purposes. However, it would be foolish to use both @code{%1} and
10030 @code{%3} for @code{x} in this @code{asm} and expect them to be the
10031 same. In fact, @code{%3} may well not be a register. It might be a
10032 symbolic memory reference to the object pointed to by @code{x}.
10035 asm ("sumsq %0, %1, %2"
10037 : "r" (x), "r" (y), "m" (*x), "m" (*y));
10040 Here is a fictitious @code{*z++ = *x++ * *y++} instruction.
10041 Notice that the @code{x}, @code{y} and @code{z} pointer registers
10042 must be specified as input/output because the @code{asm} modifies
10046 asm ("vecmul %0, %1, %2"
10047 : "+r" (z), "+r" (x), "+r" (y), "=m" (*z)
10048 : "m" (*x), "m" (*y));
10051 An x86 example where the string memory argument is of unknown length.
10055 : "=c" (count), "+D" (p)
10056 : "m" (*(const char (*)[]) p), "0" (-1), "a" (0));
10059 If you know the above will only be reading a ten byte array then you
10060 could instead use a memory input like:
10061 @code{"m" (*(const char (*)[10]) p)}.
10063 Here is an example of a PowerPC vector scale implemented in assembly,
10064 complete with vector and condition code clobbers, and some initialized
10065 offset registers that are unchanged by the @code{asm}.
10069 dscal (size_t n, double *x, double alpha)
10071 asm ("/* lots of asm here */"
10072 : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x)
10073 : "d" (alpha), "b" (32), "b" (48), "b" (64),
10074 "b" (80), "b" (96), "b" (112)
10076 "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39",
10077 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47");
10081 Rather than allocating fixed registers via clobbers to provide scratch
10082 registers for an @code{asm} statement, an alternative is to define a
10083 variable and make it an early-clobber output as with @code{a2} and
10084 @code{a3} in the example below. This gives the compiler register
10085 allocator more freedom. You can also define a variable and make it an
10086 output tied to an input as with @code{a0} and @code{a1}, tied
10087 respectively to @code{ap} and @code{lda}. Of course, with tied
10088 outputs your @code{asm} can't use the input value after modifying the
10089 output register since they are one and the same register. What's
10090 more, if you omit the early-clobber on the output, it is possible that
10091 GCC might allocate the same register to another of the inputs if GCC
10092 could prove they had the same value on entry to the @code{asm}. This
10093 is why @code{a1} has an early-clobber. Its tied input, @code{lda}
10094 might conceivably be known to have the value 16 and without an
10095 early-clobber share the same register as @code{%11}. On the other
10096 hand, @code{ap} can't be the same as any of the other inputs, so an
10097 early-clobber on @code{a0} is not needed. It is also not desirable in
10098 this case. An early-clobber on @code{a0} would cause GCC to allocate
10099 a separate register for the @code{"m" (*(const double (*)[]) ap)}
10100 input. Note that tying an input to an output is the way to set up an
10101 initialized temporary register modified by an @code{asm} statement.
10102 An input not tied to an output is assumed by GCC to be unchanged, for
10103 example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might
10104 use that register in following code if the value 16 happened to be
10105 needed. You can even use a normal @code{asm} output for a scratch if
10106 all inputs that might share the same register are consumed before the
10107 scratch is used. The VSX registers clobbered by the @code{asm}
10108 statement could have used this technique except for GCC's limit on the
10109 number of @code{asm} parameters.
10113 dgemv_kernel_4x4 (long n, const double *ap, long lda,
10114 const double *x, double *y, double alpha)
10123 /* lots of asm here */
10124 "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n"
10125 "#a0=%3 a1=%4 a2=%5 a3=%6"
10127 "+m" (*(double (*)[n]) y),
10135 "m" (*(const double (*)[n]) x),
10136 "m" (*(const double (*)[]) ap),
10144 "vs32","vs33","vs34","vs35","vs36","vs37",
10145 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"
10150 @anchor{GotoLabels}
10151 @subsubsection Goto Labels
10152 @cindex @code{asm} goto labels
10154 @code{asm goto} allows assembly code to jump to one or more C labels. The
10155 @var{GotoLabels} section in an @code{asm goto} statement contains
10157 list of all C labels to which the assembler code may jump. GCC assumes that
10158 @code{asm} execution falls through to the next statement (if this is not the
10159 case, consider using the @code{__builtin_unreachable} intrinsic after the
10160 @code{asm} statement). Optimization of @code{asm goto} may be improved by
10161 using the @code{hot} and @code{cold} label attributes (@pxref{Label
10164 An @code{asm goto} statement cannot have outputs.
10165 This is due to an internal restriction of
10166 the compiler: control transfer instructions cannot have outputs.
10167 If the assembler code does modify anything, use the @code{"memory"} clobber
10169 optimizers to flush all register values to memory and reload them if
10170 necessary after the @code{asm} statement.
10172 Also note that an @code{asm goto} statement is always implicitly
10173 considered volatile.
10175 To reference a label in the assembler template,
10176 prefix it with @samp{%l} (lowercase @samp{L}) followed
10177 by its (zero-based) position in @var{GotoLabels} plus the number of input
10178 operands. For example, if the @code{asm} has three inputs and references two
10179 labels, refer to the first label as @samp{%l3} and the second as @samp{%l4}).
10181 Alternately, you can reference labels using the actual C label name enclosed
10182 in brackets. For example, to reference a label named @code{carry}, you can
10183 use @samp{%l[carry]}. The label must still be listed in the @var{GotoLabels}
10184 section when using this approach.
10186 Here is an example of @code{asm goto} for i386:
10192 : /* No outputs. */
10193 : "r" (p1), "r" (p2)
10203 The following example shows an @code{asm goto} that uses a memory clobber.
10209 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
10210 : /* No outputs. */
10220 @anchor{x86Operandmodifiers}
10221 @subsubsection x86 Operand Modifiers
10223 References to input, output, and goto operands in the assembler template
10224 of extended @code{asm} statements can use
10225 modifiers to affect the way the operands are formatted in
10226 the code output to the assembler. For example, the
10227 following code uses the @samp{h} and @samp{b} modifiers for x86:
10231 asm volatile ("xchg %h0, %b0" : "+a" (num) );
10235 These modifiers generate this assembler code:
10241 The rest of this discussion uses the following code for illustrative purposes.
10250 asm volatile goto ("some assembler instructions here"
10251 : /* No outputs. */
10252 : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42)
10253 : /* No clobbers. */
10258 With no modifiers, this is what the output from the operands would be
10259 for the @samp{att} and @samp{intel} dialects of assembler:
10261 @multitable {Operand} {$.L2} {OFFSET FLAT:.L2}
10262 @headitem Operand @tab @samp{att} @tab @samp{intel}
10271 @tab @code{OFFSET FLAT:.L3}
10274 The table below shows the list of supported modifiers and their effects.
10276 @multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}}
10277 @headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel}
10279 @tab Print an absolute memory reference.
10284 @tab Print the QImode name of the register.
10289 @tab Require a constant operand and print the constant expression with no punctuation.
10294 @tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit.
10295 Otherwise mode is unspecified (VOIDmode).
10300 @tab Print the QImode name for a ``high'' register.
10305 @tab Add 8 bytes to an offsettable memory reference. Useful when accessing the
10306 high 8 bytes of SSE values. For a memref in (%rax), it generates
10308 @tab @code{8(%rax)}
10311 @tab Print the SImode name of the register.
10316 @tab Print the label name with no punctuation.
10321 @tab Print raw symbol name (without syntax-specific prefixes).
10326 @tab If used for a function, print the PLT suffix and generate PIC code.
10327 For example, emit @code{foo@@PLT} instead of 'foo' for the function
10328 foo(). If used for a constant, drop all syntax-specific prefixes and
10329 issue the bare constant. See @code{p} above.
10331 @tab Print the DImode name of the register.
10336 @tab Print the HImode name of the register.
10341 @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}).
10347 @code{V} is a special modifier which prints the name of the full integer
10348 register without @code{%}.
10350 @anchor{x86floatingpointasmoperands}
10351 @subsubsection x86 Floating-Point @code{asm} Operands
10353 On x86 targets, there are several rules on the usage of stack-like registers
10354 in the operands of an @code{asm}. These rules apply only to the operands
10355 that are stack-like registers:
10359 Given a set of input registers that die in an @code{asm}, it is
10360 necessary to know which are implicitly popped by the @code{asm}, and
10361 which must be explicitly popped by GCC@.
10363 An input register that is implicitly popped by the @code{asm} must be
10364 explicitly clobbered, unless it is constrained to match an
10368 For any input register that is implicitly popped by an @code{asm}, it is
10369 necessary to know how to adjust the stack to compensate for the pop.
10370 If any non-popped input is closer to the top of the reg-stack than
10371 the implicitly popped register, it would not be possible to know what the
10372 stack looked like---it's not clear how the rest of the stack ``slides
10375 All implicitly popped input registers must be closer to the top of
10376 the reg-stack than any input that is not implicitly popped.
10378 It is possible that if an input dies in an @code{asm}, the compiler might
10379 use the input register for an output reload. Consider this example:
10382 asm ("foo" : "=t" (a) : "f" (b));
10386 This code says that input @code{b} is not popped by the @code{asm}, and that
10387 the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one
10388 deeper after the @code{asm} than it was before. But, it is possible that
10389 reload may think that it can use the same register for both the input and
10392 To prevent this from happening,
10393 if any input operand uses the @samp{f} constraint, all output register
10394 constraints must use the @samp{&} early-clobber modifier.
10396 The example above is correctly written as:
10399 asm ("foo" : "=&t" (a) : "f" (b));
10403 Some operands need to be in particular places on the stack. All
10404 output operands fall in this category---GCC has no other way to
10405 know which registers the outputs appear in unless you indicate
10406 this in the constraints.
10408 Output operands must specifically indicate which register an output
10409 appears in after an @code{asm}. @samp{=f} is not allowed: the operand
10410 constraints must select a class with a single register.
10413 Output operands may not be ``inserted'' between existing stack registers.
10414 Since no 387 opcode uses a read/write operand, all output operands
10415 are dead before the @code{asm}, and are pushed by the @code{asm}.
10416 It makes no sense to push anywhere but the top of the reg-stack.
10418 Output operands must start at the top of the reg-stack: output
10419 operands may not ``skip'' a register.
10422 Some @code{asm} statements may need extra stack space for internal
10423 calculations. This can be guaranteed by clobbering stack registers
10424 unrelated to the inputs and outputs.
10429 takes one input, which is internally popped, and produces two outputs.
10432 asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
10436 This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode,
10437 and replaces them with one output. The @code{st(1)} clobber is necessary
10438 for the compiler to know that @code{fyl2xp1} pops both inputs.
10441 asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
10449 @subsection Controlling Names Used in Assembler Code
10450 @cindex assembler names for identifiers
10451 @cindex names used in assembler code
10452 @cindex identifiers, names in assembler code
10454 You can specify the name to be used in the assembler code for a C
10455 function or variable by writing the @code{asm} (or @code{__asm__})
10456 keyword after the declarator.
10457 It is up to you to make sure that the assembler names you choose do not
10458 conflict with any other assembler symbols, or reference registers.
10460 @subsubheading Assembler names for data:
10462 This sample shows how to specify the assembler name for data:
10465 int foo asm ("myfoo") = 2;
10469 This specifies that the name to be used for the variable @code{foo} in
10470 the assembler code should be @samp{myfoo} rather than the usual
10473 On systems where an underscore is normally prepended to the name of a C
10474 variable, this feature allows you to define names for the
10475 linker that do not start with an underscore.
10477 GCC does not support using this feature with a non-static local variable
10478 since such variables do not have assembler names. If you are
10479 trying to put the variable in a particular register, see
10480 @ref{Explicit Register Variables}.
10482 @subsubheading Assembler names for functions:
10484 To specify the assembler name for functions, write a declaration for the
10485 function before its definition and put @code{asm} there, like this:
10488 int func (int x, int y) asm ("MYFUNC");
10490 int func (int x, int y)
10496 This specifies that the name to be used for the function @code{func} in
10497 the assembler code should be @code{MYFUNC}.
10499 @node Explicit Register Variables
10500 @subsection Variables in Specified Registers
10501 @anchor{Explicit Reg Vars}
10502 @cindex explicit register variables
10503 @cindex variables in specified registers
10504 @cindex specified registers
10506 GNU C allows you to associate specific hardware registers with C
10507 variables. In almost all cases, allowing the compiler to assign
10508 registers produces the best code. However under certain unusual
10509 circumstances, more precise control over the variable storage is
10512 Both global and local variables can be associated with a register. The
10513 consequences of performing this association are very different between
10514 the two, as explained in the sections below.
10517 * Global Register Variables:: Variables declared at global scope.
10518 * Local Register Variables:: Variables declared within a function.
10521 @node Global Register Variables
10522 @subsubsection Defining Global Register Variables
10523 @anchor{Global Reg Vars}
10524 @cindex global register variables
10525 @cindex registers, global variables in
10526 @cindex registers, global allocation
10528 You can define a global register variable and associate it with a specified
10529 register like this:
10532 register int *foo asm ("r12");
10536 Here @code{r12} is the name of the register that should be used. Note that
10537 this is the same syntax used for defining local register variables, but for
10538 a global variable the declaration appears outside a function. The
10539 @code{register} keyword is required, and cannot be combined with
10540 @code{static}. The register name must be a valid register name for the
10543 Do not use type qualifiers such as @code{const} and @code{volatile}, as
10544 the outcome may be contrary to expectations. In particular, using the
10545 @code{volatile} qualifier does not fully prevent the compiler from
10546 optimizing accesses to the register.
10548 Registers are a scarce resource on most systems and allowing the
10549 compiler to manage their usage usually results in the best code. However,
10550 under special circumstances it can make sense to reserve some globally.
10551 For example this may be useful in programs such as programming language
10552 interpreters that have a couple of global variables that are accessed
10555 After defining a global register variable, for the current compilation
10559 @item If the register is a call-saved register, call ABI is affected:
10560 the register will not be restored in function epilogue sequences after
10561 the variable has been assigned. Therefore, functions cannot safely
10562 return to callers that assume standard ABI.
10563 @item Conversely, if the register is a call-clobbered register, making
10564 calls to functions that use standard ABI may lose contents of the variable.
10565 Such calls may be created by the compiler even if none are evident in
10566 the original program, for example when libgcc functions are used to
10567 make up for unavailable instructions.
10568 @item Accesses to the variable may be optimized as usual and the register
10569 remains available for allocation and use in any computations, provided that
10570 observable values of the variable are not affected.
10571 @item If the variable is referenced in inline assembly, the type of access
10572 must be provided to the compiler via constraints (@pxref{Constraints}).
10573 Accesses from basic asms are not supported.
10576 Note that these points @emph{only} apply to code that is compiled with the
10577 definition. The behavior of code that is merely linked in (for example
10578 code from libraries) is not affected.
10580 If you want to recompile source files that do not actually use your global
10581 register variable so they do not use the specified register for any other
10582 purpose, you need not actually add the global register declaration to
10583 their source code. It suffices to specify the compiler option
10584 @option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the
10587 @subsubheading Declaring the variable
10589 Global register variables cannot have initial values, because an
10590 executable file has no means to supply initial contents for a register.
10592 When selecting a register, choose one that is normally saved and
10593 restored by function calls on your machine. This ensures that code
10594 which is unaware of this reservation (such as library routines) will
10595 restore it before returning.
10597 On machines with register windows, be sure to choose a global
10598 register that is not affected magically by the function call mechanism.
10600 @subsubheading Using the variable
10602 @cindex @code{qsort}, and global register variables
10603 When calling routines that are not aware of the reservation, be
10604 cautious if those routines call back into code which uses them. As an
10605 example, if you call the system library version of @code{qsort}, it may
10606 clobber your registers during execution, but (if you have selected
10607 appropriate registers) it will restore them before returning. However
10608 it will @emph{not} restore them before calling @code{qsort}'s comparison
10609 function. As a result, global values will not reliably be available to
10610 the comparison function unless the @code{qsort} function itself is rebuilt.
10612 Similarly, it is not safe to access the global register variables from signal
10613 handlers or from more than one thread of control. Unless you recompile
10614 them specially for the task at hand, the system library routines may
10615 temporarily use the register for other things. Furthermore, since the register
10616 is not reserved exclusively for the variable, accessing it from handlers of
10617 asynchronous signals may observe unrelated temporary values residing in the
10620 @cindex register variable after @code{longjmp}
10621 @cindex global register after @code{longjmp}
10622 @cindex value after @code{longjmp}
10625 On most machines, @code{longjmp} restores to each global register
10626 variable the value it had at the time of the @code{setjmp}. On some
10627 machines, however, @code{longjmp} does not change the value of global
10628 register variables. To be portable, the function that called @code{setjmp}
10629 should make other arrangements to save the values of the global register
10630 variables, and to restore them in a @code{longjmp}. This way, the same
10631 thing happens regardless of what @code{longjmp} does.
10633 @node Local Register Variables
10634 @subsubsection Specifying Registers for Local Variables
10635 @anchor{Local Reg Vars}
10636 @cindex local variables, specifying registers
10637 @cindex specifying registers for local variables
10638 @cindex registers for local variables
10640 You can define a local register variable and associate it with a specified
10641 register like this:
10644 register int *foo asm ("r12");
10648 Here @code{r12} is the name of the register that should be used. Note
10649 that this is the same syntax used for defining global register variables,
10650 but for a local variable the declaration appears within a function. The
10651 @code{register} keyword is required, and cannot be combined with
10652 @code{static}. The register name must be a valid register name for the
10655 Do not use type qualifiers such as @code{const} and @code{volatile}, as
10656 the outcome may be contrary to expectations. In particular, when the
10657 @code{const} qualifier is used, the compiler may substitute the
10658 variable with its initializer in @code{asm} statements, which may cause
10659 the corresponding operand to appear in a different register.
10661 As with global register variables, it is recommended that you choose
10662 a register that is normally saved and restored by function calls on your
10663 machine, so that calls to library routines will not clobber it.
10665 The only supported use for this feature is to specify registers
10666 for input and output operands when calling Extended @code{asm}
10667 (@pxref{Extended Asm}). This may be necessary if the constraints for a
10668 particular machine don't provide sufficient control to select the desired
10669 register. To force an operand into a register, create a local variable
10670 and specify the register name after the variable's declaration. Then use
10671 the local variable for the @code{asm} operand and specify any constraint
10672 letter that matches the register:
10675 register int *p1 asm ("r0") = @dots{};
10676 register int *p2 asm ("r1") = @dots{};
10677 register int *result asm ("r0");
10678 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
10681 @emph{Warning:} In the above example, be aware that a register (for example
10682 @code{r0}) can be call-clobbered by subsequent code, including function
10683 calls and library calls for arithmetic operators on other variables (for
10684 example the initialization of @code{p2}). In this case, use temporary
10685 variables for expressions between the register assignments:
10689 register int *p1 asm ("r0") = @dots{};
10690 register int *p2 asm ("r1") = t1;
10691 register int *result asm ("r0");
10692 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
10695 Defining a register variable does not reserve the register. Other than
10696 when invoking the Extended @code{asm}, the contents of the specified
10697 register are not guaranteed. For this reason, the following uses
10698 are explicitly @emph{not} supported. If they appear to work, it is only
10699 happenstance, and may stop working as intended due to (seemingly)
10700 unrelated changes in surrounding code, or even minor changes in the
10701 optimization of a future version of gcc:
10704 @item Passing parameters to or from Basic @code{asm}
10705 @item Passing parameters to or from Extended @code{asm} without using input
10706 or output operands.
10707 @item Passing parameters to or from routines written in assembler (or
10708 other languages) using non-standard calling conventions.
10711 Some developers use Local Register Variables in an attempt to improve
10712 gcc's allocation of registers, especially in large functions. In this
10713 case the register name is essentially a hint to the register allocator.
10714 While in some instances this can generate better code, improvements are
10715 subject to the whims of the allocator/optimizers. Since there are no
10716 guarantees that your improvements won't be lost, this usage of Local
10717 Register Variables is discouraged.
10719 On the MIPS platform, there is related use for local register variables
10720 with slightly different characteristics (@pxref{MIPS Coprocessors,,
10721 Defining coprocessor specifics for MIPS targets, gccint,
10722 GNU Compiler Collection (GCC) Internals}).
10724 @node Size of an asm
10725 @subsection Size of an @code{asm}
10727 Some targets require that GCC track the size of each instruction used
10728 in order to generate correct code. Because the final length of the
10729 code produced by an @code{asm} statement is only known by the
10730 assembler, GCC must make an estimate as to how big it will be. It
10731 does this by counting the number of instructions in the pattern of the
10732 @code{asm} and multiplying that by the length of the longest
10733 instruction supported by that processor. (When working out the number
10734 of instructions, it assumes that any occurrence of a newline or of
10735 whatever statement separator character is supported by the assembler ---
10736 typically @samp{;} --- indicates the end of an instruction.)
10738 Normally, GCC's estimate is adequate to ensure that correct
10739 code is generated, but it is possible to confuse the compiler if you use
10740 pseudo instructions or assembler macros that expand into multiple real
10741 instructions, or if you use assembler directives that expand to more
10742 space in the object file than is needed for a single instruction.
10743 If this happens then the assembler may produce a diagnostic saying that
10744 a label is unreachable.
10746 @cindex @code{asm inline}
10747 This size is also used for inlining decisions. If you use @code{asm inline}
10748 instead of just @code{asm}, then for inlining purposes the size of the asm
10749 is taken as the minimum size, ignoring how many instructions GCC thinks it is.
10751 @node Alternate Keywords
10752 @section Alternate Keywords
10753 @cindex alternate keywords
10754 @cindex keywords, alternate
10756 @option{-ansi} and the various @option{-std} options disable certain
10757 keywords. This causes trouble when you want to use GNU C extensions, or
10758 a general-purpose header file that should be usable by all programs,
10759 including ISO C programs. The keywords @code{asm}, @code{typeof} and
10760 @code{inline} are not available in programs compiled with
10761 @option{-ansi} or @option{-std} (although @code{inline} can be used in a
10762 program compiled with @option{-std=c99} or @option{-std=c11}). The
10764 @code{restrict} is only available when @option{-std=gnu99} (which will
10765 eventually be the default) or @option{-std=c99} (or the equivalent
10766 @option{-std=iso9899:1999}), or an option for a later standard
10769 The way to solve these problems is to put @samp{__} at the beginning and
10770 end of each problematical keyword. For example, use @code{__asm__}
10771 instead of @code{asm}, and @code{__inline__} instead of @code{inline}.
10773 Other C compilers won't accept these alternative keywords; if you want to
10774 compile with another compiler, you can define the alternate keywords as
10775 macros to replace them with the customary keywords. It looks like this:
10779 #define __asm__ asm
10783 @findex __extension__
10785 @option{-pedantic} and other options cause warnings for many GNU C extensions.
10787 prevent such warnings within one expression by writing
10788 @code{__extension__} before the expression. @code{__extension__} has no
10789 effect aside from this.
10791 @node Incomplete Enums
10792 @section Incomplete @code{enum} Types
10794 You can define an @code{enum} tag without specifying its possible values.
10795 This results in an incomplete type, much like what you get if you write
10796 @code{struct foo} without describing the elements. A later declaration
10797 that does specify the possible values completes the type.
10799 You cannot allocate variables or storage using the type while it is
10800 incomplete. However, you can work with pointers to that type.
10802 This extension may not be very useful, but it makes the handling of
10803 @code{enum} more consistent with the way @code{struct} and @code{union}
10806 This extension is not supported by GNU C++.
10808 @node Function Names
10809 @section Function Names as Strings
10810 @cindex @code{__func__} identifier
10811 @cindex @code{__FUNCTION__} identifier
10812 @cindex @code{__PRETTY_FUNCTION__} identifier
10814 GCC provides three magic constants that hold the name of the current
10815 function as a string. In C++11 and later modes, all three are treated
10816 as constant expressions and can be used in @code{constexpr} constexts.
10817 The first of these constants is @code{__func__}, which is part of
10820 The identifier @code{__func__} is implicitly declared by the translator
10821 as if, immediately following the opening brace of each function
10822 definition, the declaration
10825 static const char __func__[] = "function-name";
10829 appeared, where function-name is the name of the lexically-enclosing
10830 function. This name is the unadorned name of the function. As an
10831 extension, at file (or, in C++, namespace scope), @code{__func__}
10832 evaluates to the empty string.
10834 @code{__FUNCTION__} is another name for @code{__func__}, provided for
10835 backward compatibility with old versions of GCC.
10837 In C, @code{__PRETTY_FUNCTION__} is yet another name for
10838 @code{__func__}, except that at file scope (or, in C++, namespace scope),
10839 it evaluates to the string @code{"top level"}. In addition, in C++,
10840 @code{__PRETTY_FUNCTION__} contains the signature of the function as
10841 well as its bare name. For example, this program:
10844 extern "C" int printf (const char *, ...);
10850 printf ("__FUNCTION__ = %s\n", __FUNCTION__);
10851 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
10869 __PRETTY_FUNCTION__ = void a::sub(int)
10872 These identifiers are variables, not preprocessor macros, and may not
10873 be used to initialize @code{char} arrays or be concatenated with string
10876 @node Return Address
10877 @section Getting the Return or Frame Address of a Function
10879 These functions may be used to get information about the callers of a
10882 @deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level})
10883 This function returns the return address of the current function, or of
10884 one of its callers. The @var{level} argument is number of frames to
10885 scan up the call stack. A value of @code{0} yields the return address
10886 of the current function, a value of @code{1} yields the return address
10887 of the caller of the current function, and so forth. When inlining
10888 the expected behavior is that the function returns the address of
10889 the function that is returned to. To work around this behavior use
10890 the @code{noinline} function attribute.
10892 The @var{level} argument must be a constant integer.
10894 On some machines it may be impossible to determine the return address of
10895 any function other than the current one; in such cases, or when the top
10896 of the stack has been reached, this function returns @code{0} or a
10897 random value. In addition, @code{__builtin_frame_address} may be used
10898 to determine if the top of the stack has been reached.
10900 Additional post-processing of the returned value may be needed, see
10901 @code{__builtin_extract_return_addr}.
10903 Calling this function with a nonzero argument can have unpredictable
10904 effects, including crashing the calling program. As a result, calls
10905 that are considered unsafe are diagnosed when the @option{-Wframe-address}
10906 option is in effect. Such calls should only be made in debugging
10910 @deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr})
10911 The address as returned by @code{__builtin_return_address} may have to be fed
10912 through this function to get the actual encoded address. For example, on the
10913 31-bit S/390 platform the highest bit has to be masked out, or on SPARC
10914 platforms an offset has to be added for the true next instruction to be
10917 If no fixup is needed, this function simply passes through @var{addr}.
10920 @deftypefn {Built-in Function} {void *} __builtin_frob_return_address (void *@var{addr})
10921 This function does the reverse of @code{__builtin_extract_return_addr}.
10924 @deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level})
10925 This function is similar to @code{__builtin_return_address}, but it
10926 returns the address of the function frame rather than the return address
10927 of the function. Calling @code{__builtin_frame_address} with a value of
10928 @code{0} yields the frame address of the current function, a value of
10929 @code{1} yields the frame address of the caller of the current function,
10932 The frame is the area on the stack that holds local variables and saved
10933 registers. The frame address is normally the address of the first word
10934 pushed on to the stack by the function. However, the exact definition
10935 depends upon the processor and the calling convention. If the processor
10936 has a dedicated frame pointer register, and the function has a frame,
10937 then @code{__builtin_frame_address} returns the value of the frame
10940 On some machines it may be impossible to determine the frame address of
10941 any function other than the current one; in such cases, or when the top
10942 of the stack has been reached, this function returns @code{0} if
10943 the first frame pointer is properly initialized by the startup code.
10945 Calling this function with a nonzero argument can have unpredictable
10946 effects, including crashing the calling program. As a result, calls
10947 that are considered unsafe are diagnosed when the @option{-Wframe-address}
10948 option is in effect. Such calls should only be made in debugging
10952 @node Vector Extensions
10953 @section Using Vector Instructions through Built-in Functions
10955 On some targets, the instruction set contains SIMD vector instructions which
10956 operate on multiple values contained in one large register at the same time.
10957 For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used
10960 The first step in using these extensions is to provide the necessary data
10961 types. This should be done using an appropriate @code{typedef}:
10964 typedef int v4si __attribute__ ((vector_size (16)));
10968 The @code{int} type specifies the @dfn{base type}, while the attribute specifies
10969 the vector size for the variable, measured in bytes. For example, the
10970 declaration above causes the compiler to set the mode for the @code{v4si}
10971 type to be 16 bytes wide and divided into @code{int} sized units. For
10972 a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the
10973 corresponding mode of @code{foo} is @acronym{V4SI}.
10975 The @code{vector_size} attribute is only applicable to integral and
10976 floating scalars, although arrays, pointers, and function return values
10977 are allowed in conjunction with this construct. Only sizes that are
10978 positive power-of-two multiples of the base type size are currently allowed.
10980 All the basic integer types can be used as base types, both as signed
10981 and as unsigned: @code{char}, @code{short}, @code{int}, @code{long},
10982 @code{long long}. In addition, @code{float} and @code{double} can be
10983 used to build floating-point vector types.
10985 Specifying a combination that is not valid for the current architecture
10986 causes GCC to synthesize the instructions using a narrower mode.
10987 For example, if you specify a variable of type @code{V4SI} and your
10988 architecture does not allow for this specific SIMD type, GCC
10989 produces code that uses 4 @code{SIs}.
10991 The types defined in this manner can be used with a subset of normal C
10992 operations. Currently, GCC allows using the following operators
10993 on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@.
10995 The operations behave like C++ @code{valarrays}. Addition is defined as
10996 the addition of the corresponding elements of the operands. For
10997 example, in the code below, each of the 4 elements in @var{a} is
10998 added to the corresponding 4 elements in @var{b} and the resulting
10999 vector is stored in @var{c}.
11002 typedef int v4si __attribute__ ((vector_size (16)));
11009 Subtraction, multiplication, division, and the logical operations
11010 operate in a similar manner. Likewise, the result of using the unary
11011 minus or complement operators on a vector type is a vector whose
11012 elements are the negative or complemented values of the corresponding
11013 elements in the operand.
11015 It is possible to use shifting operators @code{<<}, @code{>>} on
11016 integer-type vectors. The operation is defined as following: @code{@{a0,
11017 a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1,
11018 @dots{}, an >> bn@}}@. Vector operands must have the same number of
11021 For convenience, it is allowed to use a binary vector operation
11022 where one operand is a scalar. In that case the compiler transforms
11023 the scalar operand into a vector where each element is the scalar from
11024 the operation. The transformation happens only if the scalar could be
11025 safely converted to the vector-element type.
11026 Consider the following code.
11029 typedef int v4si __attribute__ ((vector_size (16)));
11034 a = b + 1; /* a = b + @{1,1,1,1@}; */
11035 a = 2 * b; /* a = @{2,2,2,2@} * b; */
11037 a = l + a; /* Error, cannot convert long to int. */
11040 Vectors can be subscripted as if the vector were an array with
11041 the same number of elements and base type. Out of bound accesses
11042 invoke undefined behavior at run time. Warnings for out of bound
11043 accesses for vector subscription can be enabled with
11044 @option{-Warray-bounds}.
11046 Vector comparison is supported with standard comparison
11047 operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be
11048 vector expressions of integer-type or real-type. Comparison between
11049 integer-type vectors and real-type vectors are not supported. The
11050 result of the comparison is a vector of the same width and number of
11051 elements as the comparison operands with a signed integral element
11054 Vectors are compared element-wise producing 0 when comparison is false
11055 and -1 (constant of the appropriate type where all bits are set)
11056 otherwise. Consider the following example.
11059 typedef int v4si __attribute__ ((vector_size (16)));
11061 v4si a = @{1,2,3,4@};
11062 v4si b = @{3,2,1,4@};
11065 c = a > b; /* The result would be @{0, 0,-1, 0@} */
11066 c = a == b; /* The result would be @{0,-1, 0,-1@} */
11069 In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where
11070 @code{b} and @code{c} are vectors of the same type and @code{a} is an
11071 integer vector with the same number of elements of the same size as @code{b}
11072 and @code{c}, computes all three arguments and creates a vector
11073 @code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in
11074 OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}.
11075 As in the case of binary operations, this syntax is also accepted when
11076 one of @code{b} or @code{c} is a scalar that is then transformed into a
11077 vector. If both @code{b} and @code{c} are scalars and the type of
11078 @code{true?b:c} has the same size as the element type of @code{a}, then
11079 @code{b} and @code{c} are converted to a vector type whose elements have
11080 this type and with the same number of elements as @code{a}.
11082 In C++, the logic operators @code{!, &&, ||} are available for vectors.
11083 @code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to
11084 @code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}.
11085 For mixed operations between a scalar @code{s} and a vector @code{v},
11086 @code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is
11087 short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}.
11089 @findex __builtin_shuffle
11090 Vector shuffling is available using functions
11091 @code{__builtin_shuffle (vec, mask)} and
11092 @code{__builtin_shuffle (vec0, vec1, mask)}.
11093 Both functions construct a permutation of elements from one or two
11094 vectors and return a vector of the same type as the input vector(s).
11095 The @var{mask} is an integral vector with the same width (@var{W})
11096 and element count (@var{N}) as the output vector.
11098 The elements of the input vectors are numbered in memory ordering of
11099 @var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The
11100 elements of @var{mask} are considered modulo @var{N} in the single-operand
11101 case and modulo @math{2*@var{N}} in the two-operand case.
11103 Consider the following example,
11106 typedef int v4si __attribute__ ((vector_size (16)));
11108 v4si a = @{1,2,3,4@};
11109 v4si b = @{5,6,7,8@};
11110 v4si mask1 = @{0,1,1,3@};
11111 v4si mask2 = @{0,4,2,5@};
11114 res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */
11115 res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */
11118 Note that @code{__builtin_shuffle} is intentionally semantically
11119 compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions.
11121 You can declare variables and use them in function calls and returns, as
11122 well as in assignments and some casts. You can specify a vector type as
11123 a return type for a function. Vector types can also be used as function
11124 arguments. It is possible to cast from one vector type to another,
11125 provided they are of the same size (in fact, you can also cast vectors
11126 to and from other datatypes of the same size).
11128 You cannot operate between vectors of different lengths or different
11129 signedness without a cast.
11131 @findex __builtin_convertvector
11132 Vector conversion is available using the
11133 @code{__builtin_convertvector (vec, vectype)}
11134 function. @var{vec} must be an expression with integral or floating
11135 vector type and @var{vectype} an integral or floating vector type with the
11136 same number of elements. The result has @var{vectype} type and value of
11137 a C cast of every element of @var{vec} to the element type of @var{vectype}.
11139 Consider the following example,
11141 typedef int v4si __attribute__ ((vector_size (16)));
11142 typedef float v4sf __attribute__ ((vector_size (16)));
11143 typedef double v4df __attribute__ ((vector_size (32)));
11144 typedef unsigned long long v4di __attribute__ ((vector_size (32)));
11146 v4si a = @{1,-2,3,-4@};
11147 v4sf b = @{1.5f,-2.5f,3.f,7.f@};
11148 v4di c = @{1ULL,5ULL,0ULL,10ULL@};
11149 v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */
11151 v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */
11152 v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */
11153 v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */
11154 v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */
11155 v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */
11158 @cindex vector types, using with x86 intrinsics
11159 Sometimes it is desirable to write code using a mix of generic vector
11160 operations (for clarity) and machine-specific vector intrinsics (to
11161 access vector instructions that are not exposed via generic built-ins).
11162 On x86, intrinsic functions for integer vectors typically use the same
11163 vector type @code{__m128i} irrespective of how they interpret the vector,
11164 making it necessary to cast their arguments and return values from/to
11165 other vector types. In C, you can make use of a @code{union} type:
11166 @c In C++ such type punning via a union is not allowed by the language
11168 #include <immintrin.h>
11170 typedef unsigned char u8x16 __attribute__ ((vector_size (16)));
11171 typedef unsigned int u32x4 __attribute__ ((vector_size (16)));
11181 for variables that can be used with both built-in operators and x86
11185 v128 x, y = @{ 0 @};
11186 memcpy (&x, ptr, sizeof x);
11188 x.mm = _mm_adds_epu8 (x.mm, y.mm);
11191 /* Instead of a variable, a compound literal may be used to pass the
11192 return value of an intrinsic call to a function expecting the union: */
11194 x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@});
11195 @c This could be done implicitly with __attribute__((transparent_union)),
11196 @c but GCC does not accept it for unions of vector types (PR 88955).
11200 @section Support for @code{offsetof}
11201 @findex __builtin_offsetof
11203 GCC implements for both C and C++ a syntactic extension to implement
11204 the @code{offsetof} macro.
11208 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
11210 offsetof_member_designator:
11212 | offsetof_member_designator "." @code{identifier}
11213 | offsetof_member_designator "[" @code{expr} "]"
11216 This extension is sufficient such that
11219 #define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member})
11223 is a suitable definition of the @code{offsetof} macro. In C++, @var{type}
11224 may be dependent. In either case, @var{member} may consist of a single
11225 identifier, or a sequence of member accesses and array references.
11227 @node __sync Builtins
11228 @section Legacy @code{__sync} Built-in Functions for Atomic Memory Access
11230 The following built-in functions
11231 are intended to be compatible with those described
11232 in the @cite{Intel Itanium Processor-specific Application Binary Interface},
11233 section 7.4. As such, they depart from normal GCC practice by not using
11234 the @samp{__builtin_} prefix and also by being overloaded so that they
11235 work on multiple types.
11237 The definition given in the Intel documentation allows only for the use of
11238 the types @code{int}, @code{long}, @code{long long} or their unsigned
11239 counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in
11240 size other than the C type @code{_Bool} or the C++ type @code{bool}.
11241 Operations on pointer arguments are performed as if the operands were
11242 of the @code{uintptr_t} type. That is, they are not scaled by the size
11243 of the type to which the pointer points.
11245 These functions are implemented in terms of the @samp{__atomic}
11246 builtins (@pxref{__atomic Builtins}). They should not be used for new
11247 code which should use the @samp{__atomic} builtins instead.
11249 Not all operations are supported by all target processors. If a particular
11250 operation cannot be implemented on the target processor, a warning is
11251 generated and a call to an external function is generated. The external
11252 function carries the same name as the built-in version,
11253 with an additional suffix
11254 @samp{_@var{n}} where @var{n} is the size of the data type.
11256 @c ??? Should we have a mechanism to suppress this warning? This is almost
11257 @c useful for implementing the operation under the control of an external
11260 In most cases, these built-in functions are considered a @dfn{full barrier}.
11262 no memory operand is moved across the operation, either forward or
11263 backward. Further, instructions are issued as necessary to prevent the
11264 processor from speculating loads across the operation and from queuing stores
11265 after the operation.
11267 All of the routines are described in the Intel documentation to take
11268 ``an optional list of variables protected by the memory barrier''. It's
11269 not clear what is meant by that; it could mean that @emph{only} the
11270 listed variables are protected, or it could mean a list of additional
11271 variables to be protected. The list is ignored by GCC which treats it as
11272 empty. GCC interprets an empty list as meaning that all globally
11273 accessible variables should be protected.
11276 @item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...)
11277 @itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...)
11278 @itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...)
11279 @itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...)
11280 @itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...)
11281 @itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...)
11282 @findex __sync_fetch_and_add
11283 @findex __sync_fetch_and_sub
11284 @findex __sync_fetch_and_or
11285 @findex __sync_fetch_and_and
11286 @findex __sync_fetch_and_xor
11287 @findex __sync_fetch_and_nand
11288 These built-in functions perform the operation suggested by the name, and
11289 returns the value that had previously been in memory. That is, operations
11290 on integer operands have the following semantics. Operations on pointer
11291 arguments are performed as if the operands were of the @code{uintptr_t}
11292 type. That is, they are not scaled by the size of the type to which
11293 the pointer points.
11296 @{ tmp = *ptr; *ptr @var{op}= value; return tmp; @}
11297 @{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand
11300 The object pointed to by the first argument must be of integer or pointer
11301 type. It must not be a boolean type.
11303 @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand}
11304 as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}.
11306 @item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...)
11307 @itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...)
11308 @itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...)
11309 @itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...)
11310 @itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...)
11311 @itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...)
11312 @findex __sync_add_and_fetch
11313 @findex __sync_sub_and_fetch
11314 @findex __sync_or_and_fetch
11315 @findex __sync_and_and_fetch
11316 @findex __sync_xor_and_fetch
11317 @findex __sync_nand_and_fetch
11318 These built-in functions perform the operation suggested by the name, and
11319 return the new value. That is, operations on integer operands have
11320 the following semantics. Operations on pointer operands are performed as
11321 if the operand's type were @code{uintptr_t}.
11324 @{ *ptr @var{op}= value; return *ptr; @}
11325 @{ *ptr = ~(*ptr & value); return *ptr; @} // nand
11328 The same constraints on arguments apply as for the corresponding
11329 @code{__sync_op_and_fetch} built-in functions.
11331 @emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch}
11332 as @code{*ptr = ~(*ptr & value)} instead of
11333 @code{*ptr = ~*ptr & value}.
11335 @item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
11336 @itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
11337 @findex __sync_bool_compare_and_swap
11338 @findex __sync_val_compare_and_swap
11339 These built-in functions perform an atomic compare and swap.
11340 That is, if the current
11341 value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into
11344 The ``bool'' version returns @code{true} if the comparison is successful and
11345 @var{newval} is written. The ``val'' version returns the contents
11346 of @code{*@var{ptr}} before the operation.
11348 @item __sync_synchronize (...)
11349 @findex __sync_synchronize
11350 This built-in function issues a full memory barrier.
11352 @item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...)
11353 @findex __sync_lock_test_and_set
11354 This built-in function, as described by Intel, is not a traditional test-and-set
11355 operation, but rather an atomic exchange operation. It writes @var{value}
11356 into @code{*@var{ptr}}, and returns the previous contents of
11359 Many targets have only minimal support for such locks, and do not support
11360 a full exchange operation. In this case, a target may support reduced
11361 functionality here by which the @emph{only} valid value to store is the
11362 immediate constant 1. The exact value actually stored in @code{*@var{ptr}}
11363 is implementation defined.
11365 This built-in function is not a full barrier,
11366 but rather an @dfn{acquire barrier}.
11367 This means that references after the operation cannot move to (or be
11368 speculated to) before the operation, but previous memory stores may not
11369 be globally visible yet, and previous memory loads may not yet be
11372 @item void __sync_lock_release (@var{type} *ptr, ...)
11373 @findex __sync_lock_release
11374 This built-in function releases the lock acquired by
11375 @code{__sync_lock_test_and_set}.
11376 Normally this means writing the constant 0 to @code{*@var{ptr}}.
11378 This built-in function is not a full barrier,
11379 but rather a @dfn{release barrier}.
11380 This means that all previous memory stores are globally visible, and all
11381 previous memory loads have been satisfied, but following memory reads
11382 are not prevented from being speculated to before the barrier.
11385 @node __atomic Builtins
11386 @section Built-in Functions for Memory Model Aware Atomic Operations
11388 The following built-in functions approximately match the requirements
11389 for the C++11 memory model. They are all
11390 identified by being prefixed with @samp{__atomic} and most are
11391 overloaded so that they work with multiple types.
11393 These functions are intended to replace the legacy @samp{__sync}
11394 builtins. The main difference is that the memory order that is requested
11395 is a parameter to the functions. New code should always use the
11396 @samp{__atomic} builtins rather than the @samp{__sync} builtins.
11398 Note that the @samp{__atomic} builtins assume that programs will
11399 conform to the C++11 memory model. In particular, they assume
11400 that programs are free of data races. See the C++11 standard for
11401 detailed requirements.
11403 The @samp{__atomic} builtins can be used with any integral scalar or
11404 pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral
11405 types are also allowed if @samp{__int128} (@pxref{__int128}) is
11406 supported by the architecture.
11408 The four non-arithmetic functions (load, store, exchange, and
11409 compare_exchange) all have a generic version as well. This generic
11410 version works on any data type. It uses the lock-free built-in function
11411 if the specific data type size makes that possible; otherwise, an
11412 external call is left to be resolved at run time. This external call is
11413 the same format with the addition of a @samp{size_t} parameter inserted
11414 as the first parameter indicating the size of the object being pointed to.
11415 All objects must be the same size.
11417 There are 6 different memory orders that can be specified. These map
11418 to the C++11 memory orders with the same names, see the C++11 standard
11419 or the @uref{http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki
11420 on atomic synchronization} for detailed definitions. Individual
11421 targets may also support additional memory orders for use on specific
11422 architectures. Refer to the target documentation for details of
11425 An atomic operation can both constrain code motion and
11426 be mapped to hardware instructions for synchronization between threads
11427 (e.g., a fence). To which extent this happens is controlled by the
11428 memory orders, which are listed here in approximately ascending order of
11429 strength. The description of each memory order is only meant to roughly
11430 illustrate the effects and is not a specification; see the C++11
11431 memory model for precise semantics.
11434 @item __ATOMIC_RELAXED
11435 Implies no inter-thread ordering constraints.
11436 @item __ATOMIC_CONSUME
11437 This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE}
11438 memory order because of a deficiency in C++11's semantics for
11439 @code{memory_order_consume}.
11440 @item __ATOMIC_ACQUIRE
11441 Creates an inter-thread happens-before constraint from the release (or
11442 stronger) semantic store to this acquire load. Can prevent hoisting
11443 of code to before the operation.
11444 @item __ATOMIC_RELEASE
11445 Creates an inter-thread happens-before constraint to acquire (or stronger)
11446 semantic loads that read from this release store. Can prevent sinking
11447 of code to after the operation.
11448 @item __ATOMIC_ACQ_REL
11449 Combines the effects of both @code{__ATOMIC_ACQUIRE} and
11450 @code{__ATOMIC_RELEASE}.
11451 @item __ATOMIC_SEQ_CST
11452 Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations.
11455 Note that in the C++11 memory model, @emph{fences} (e.g.,
11456 @samp{__atomic_thread_fence}) take effect in combination with other
11457 atomic operations on specific memory locations (e.g., atomic loads);
11458 operations on specific memory locations do not necessarily affect other
11459 operations in the same way.
11461 Target architectures are encouraged to provide their own patterns for
11462 each of the atomic built-in functions. If no target is provided, the original
11463 non-memory model set of @samp{__sync} atomic built-in functions are
11464 used, along with any required synchronization fences surrounding it in
11465 order to achieve the proper behavior. Execution in this case is subject
11466 to the same restrictions as those built-in functions.
11468 If there is no pattern or mechanism to provide a lock-free instruction
11469 sequence, a call is made to an external routine with the same parameters
11470 to be resolved at run time.
11472 When implementing patterns for these built-in functions, the memory order
11473 parameter can be ignored as long as the pattern implements the most
11474 restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory
11475 orders execute correctly with this memory order but they may not execute as
11476 efficiently as they could with a more appropriate implementation of the
11477 relaxed requirements.
11479 Note that the C++11 standard allows for the memory order parameter to be
11480 determined at run time rather than at compile time. These built-in
11481 functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather
11482 than invoke a runtime library call or inline a switch statement. This is
11483 standard compliant, safe, and the simplest approach for now.
11485 The memory order parameter is a signed int, but only the lower 16 bits are
11486 reserved for the memory order. The remainder of the signed int is reserved
11487 for target use and should be 0. Use of the predefined atomic values
11488 ensures proper usage.
11490 @deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memorder)
11491 This built-in function implements an atomic load operation. It returns the
11492 contents of @code{*@var{ptr}}.
11494 The valid memory order variants are
11495 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
11496 and @code{__ATOMIC_CONSUME}.
11500 @deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder)
11501 This is the generic version of an atomic load. It returns the
11502 contents of @code{*@var{ptr}} in @code{*@var{ret}}.
11506 @deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder)
11507 This built-in function implements an atomic store operation. It writes
11508 @code{@var{val}} into @code{*@var{ptr}}.
11510 The valid memory order variants are
11511 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}.
11515 @deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder)
11516 This is the generic version of an atomic store. It stores the value
11517 of @code{*@var{val}} into @code{*@var{ptr}}.
11521 @deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder)
11522 This built-in function implements an atomic exchange operation. It writes
11523 @var{val} into @code{*@var{ptr}}, and returns the previous contents of
11526 The valid memory order variants are
11527 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
11528 @code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}.
11532 @deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder)
11533 This is the generic version of an atomic exchange. It stores the
11534 contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value
11535 of @code{*@var{ptr}} is copied into @code{*@var{ret}}.
11539 @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)
11540 This built-in function implements an atomic compare and exchange operation.
11541 This compares the contents of @code{*@var{ptr}} with the contents of
11542 @code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write}
11543 operation that writes @var{desired} into @code{*@var{ptr}}. If they are not
11544 equal, the operation is a @emph{read} and the current contents of
11545 @code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true}
11546 for weak compare_exchange, which may fail spuriously, and @code{false} for
11547 the strong variation, which never fails spuriously. Many targets
11548 only offer the strong variation and ignore the parameter. When in doubt, use
11549 the strong variation.
11551 If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned
11552 and memory is affected according to the
11553 memory order specified by @var{success_memorder}. There are no
11554 restrictions on what memory order can be used here.
11556 Otherwise, @code{false} is returned and memory is affected according
11557 to @var{failure_memorder}. This memory order cannot be
11558 @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a
11559 stronger order than that specified by @var{success_memorder}.
11563 @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)
11564 This built-in function implements the generic version of
11565 @code{__atomic_compare_exchange}. The function is virtually identical to
11566 @code{__atomic_compare_exchange_n}, except the desired value is also a
11571 @deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder)
11572 @deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder)
11573 @deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder)
11574 @deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder)
11575 @deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder)
11576 @deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder)
11577 These built-in functions perform the operation suggested by the name, and
11578 return the result of the operation. Operations on pointer arguments are
11579 performed as if the operands were of the @code{uintptr_t} type. That is,
11580 they are not scaled by the size of the type to which the pointer points.
11583 @{ *ptr @var{op}= val; return *ptr; @}
11584 @{ *ptr = ~(*ptr & val); return *ptr; @} // nand
11587 The object pointed to by the first argument must be of integer or pointer
11588 type. It must not be a boolean type. All memory orders are valid.
11592 @deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder)
11593 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder)
11594 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder)
11595 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder)
11596 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder)
11597 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder)
11598 These built-in functions perform the operation suggested by the name, and
11599 return the value that had previously been in @code{*@var{ptr}}. Operations
11600 on pointer arguments are performed as if the operands were of
11601 the @code{uintptr_t} type. That is, they are not scaled by the size of
11602 the type to which the pointer points.
11605 @{ tmp = *ptr; *ptr @var{op}= val; return tmp; @}
11606 @{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand
11609 The same constraints on arguments apply as for the corresponding
11610 @code{__atomic_op_fetch} built-in functions. All memory orders are valid.
11614 @deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memorder)
11616 This built-in function performs an atomic test-and-set operation on
11617 the byte at @code{*@var{ptr}}. The byte is set to some implementation
11618 defined nonzero ``set'' value and the return value is @code{true} if and only
11619 if the previous contents were ``set''.
11620 It should be only used for operands of type @code{bool} or @code{char}. For
11621 other types only part of the value may be set.
11623 All memory orders are valid.
11627 @deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memorder)
11629 This built-in function performs an atomic clear operation on
11630 @code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0.
11631 It should be only used for operands of type @code{bool} or @code{char} and
11632 in conjunction with @code{__atomic_test_and_set}.
11633 For other types it may only clear partially. If the type is not @code{bool}
11634 prefer using @code{__atomic_store}.
11636 The valid memory order variants are
11637 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and
11638 @code{__ATOMIC_RELEASE}.
11642 @deftypefn {Built-in Function} void __atomic_thread_fence (int memorder)
11644 This built-in function acts as a synchronization fence between threads
11645 based on the specified memory order.
11647 All memory orders are valid.
11651 @deftypefn {Built-in Function} void __atomic_signal_fence (int memorder)
11653 This built-in function acts as a synchronization fence between a thread
11654 and signal handlers based in the same thread.
11656 All memory orders are valid.
11660 @deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr)
11662 This built-in function returns @code{true} if objects of @var{size} bytes always
11663 generate lock-free atomic instructions for the target architecture.
11664 @var{size} must resolve to a compile-time constant and the result also
11665 resolves to a compile-time constant.
11667 @var{ptr} is an optional pointer to the object that may be used to determine
11668 alignment. A value of 0 indicates typical alignment should be used. The
11669 compiler may also ignore this parameter.
11672 if (__atomic_always_lock_free (sizeof (long long), 0))
11677 @deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr)
11679 This built-in function returns @code{true} if objects of @var{size} bytes always
11680 generate lock-free atomic instructions for the target architecture. If
11681 the built-in function is not known to be lock-free, a call is made to a
11682 runtime routine named @code{__atomic_is_lock_free}.
11684 @var{ptr} is an optional pointer to the object that may be used to determine
11685 alignment. A value of 0 indicates typical alignment should be used. The
11686 compiler may also ignore this parameter.
11689 @node Integer Overflow Builtins
11690 @section Built-in Functions to Perform Arithmetic with Overflow Checking
11692 The following built-in functions allow performing simple arithmetic operations
11693 together with checking whether the operations overflowed.
11695 @deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
11696 @deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res)
11697 @deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res)
11698 @deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res)
11699 @deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res)
11700 @deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
11701 @deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
11703 These built-in functions promote the first two operands into infinite precision signed
11704 type and perform addition on those promoted operands. The result is then
11705 cast to the type the third pointer argument points to and stored there.
11706 If the stored result is equal to the infinite precision result, the built-in
11707 functions return @code{false}, otherwise they return @code{true}. As the addition is
11708 performed in infinite signed precision, these built-in functions have fully defined
11709 behavior for all argument values.
11711 The first built-in function allows arbitrary integral types for operands and
11712 the result type must be pointer to some integral type other than enumerated or
11713 boolean type, the rest of the built-in functions have explicit integer types.
11715 The compiler will attempt to use hardware instructions to implement
11716 these built-in functions where possible, like conditional jump on overflow
11717 after addition, conditional jump on carry etc.
11721 @deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
11722 @deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res)
11723 @deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res)
11724 @deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res)
11725 @deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res)
11726 @deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
11727 @deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
11729 These built-in functions are similar to the add overflow checking built-in
11730 functions above, except they perform subtraction, subtract the second argument
11731 from the first one, instead of addition.
11735 @deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
11736 @deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res)
11737 @deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res)
11738 @deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res)
11739 @deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res)
11740 @deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
11741 @deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
11743 These built-in functions are similar to the add overflow checking built-in
11744 functions above, except they perform multiplication, instead of addition.
11748 The following built-in functions allow checking if simple arithmetic operation
11751 @deftypefn {Built-in Function} bool __builtin_add_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
11752 @deftypefnx {Built-in Function} bool __builtin_sub_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
11753 @deftypefnx {Built-in Function} bool __builtin_mul_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
11755 These built-in functions are similar to @code{__builtin_add_overflow},
11756 @code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that
11757 they don't store the result of the arithmetic operation anywhere and the
11758 last argument is not a pointer, but some expression with integral type other
11759 than enumerated or boolean type.
11761 The built-in functions promote the first two operands into infinite precision signed type
11762 and perform addition on those promoted operands. The result is then
11763 cast to the type of the third argument. If the cast result is equal to the infinite
11764 precision result, the built-in functions return @code{false}, otherwise they return @code{true}.
11765 The value of the third argument is ignored, just the side effects in the third argument
11766 are evaluated, and no integral argument promotions are performed on the last argument.
11767 If the third argument is a bit-field, the type used for the result cast has the
11768 precision and signedness of the given bit-field, rather than precision and signedness
11769 of the underlying type.
11771 For example, the following macro can be used to portably check, at
11772 compile-time, whether or not adding two constant integers will overflow,
11773 and perform the addition only when it is known to be safe and not to trigger
11774 a @option{-Woverflow} warning.
11777 #define INT_ADD_OVERFLOW_P(a, b) \
11778 __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0)
11781 A = INT_MAX, B = 3,
11782 C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B,
11783 D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0)
11787 The compiler will attempt to use hardware instructions to implement
11788 these built-in functions where possible, like conditional jump on overflow
11789 after addition, conditional jump on carry etc.
11793 @node x86 specific memory model extensions for transactional memory
11794 @section x86-Specific Memory Model Extensions for Transactional Memory
11796 The x86 architecture supports additional memory ordering flags
11797 to mark critical sections for hardware lock elision.
11798 These must be specified in addition to an existing memory order to
11802 @item __ATOMIC_HLE_ACQUIRE
11803 Start lock elision on a lock variable.
11804 Memory order must be @code{__ATOMIC_ACQUIRE} or stronger.
11805 @item __ATOMIC_HLE_RELEASE
11806 End lock elision on a lock variable.
11807 Memory order must be @code{__ATOMIC_RELEASE} or stronger.
11810 When a lock acquire fails, it is required for good performance to abort
11811 the transaction quickly. This can be done with a @code{_mm_pause}.
11814 #include <immintrin.h> // For _mm_pause
11818 /* Acquire lock with lock elision */
11819 while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE))
11820 _mm_pause(); /* Abort failed transaction */
11822 /* Free lock with lock elision */
11823 __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE);
11826 @node Object Size Checking
11827 @section Object Size Checking Built-in Functions
11828 @findex __builtin_object_size
11829 @findex __builtin___memcpy_chk
11830 @findex __builtin___mempcpy_chk
11831 @findex __builtin___memmove_chk
11832 @findex __builtin___memset_chk
11833 @findex __builtin___strcpy_chk
11834 @findex __builtin___stpcpy_chk
11835 @findex __builtin___strncpy_chk
11836 @findex __builtin___strcat_chk
11837 @findex __builtin___strncat_chk
11838 @findex __builtin___sprintf_chk
11839 @findex __builtin___snprintf_chk
11840 @findex __builtin___vsprintf_chk
11841 @findex __builtin___vsnprintf_chk
11842 @findex __builtin___printf_chk
11843 @findex __builtin___vprintf_chk
11844 @findex __builtin___fprintf_chk
11845 @findex __builtin___vfprintf_chk
11847 GCC implements a limited buffer overflow protection mechanism that can
11848 prevent some buffer overflow attacks by determining the sizes of objects
11849 into which data is about to be written and preventing the writes when
11850 the size isn't sufficient. The built-in functions described below yield
11851 the best results when used together and when optimization is enabled.
11852 For example, to detect object sizes across function boundaries or to
11853 follow pointer assignments through non-trivial control flow they rely
11854 on various optimization passes enabled with @option{-O2}. However, to
11855 a limited extent, they can be used without optimization as well.
11857 @deftypefn {Built-in Function} {size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
11858 is a built-in construct that returns a constant number of bytes from
11859 @var{ptr} to the end of the object @var{ptr} pointer points to
11860 (if known at compile time). To determine the sizes of dynamically allocated
11861 objects the function relies on the allocation functions called to obtain
11862 the storage to be declared with the @code{alloc_size} attribute (@pxref{Common
11863 Function Attributes}). @code{__builtin_object_size} never evaluates
11864 its arguments for side effects. If there are any side effects in them, it
11865 returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
11866 for @var{type} 2 or 3. If there are multiple objects @var{ptr} can
11867 point to and all of them are known at compile time, the returned number
11868 is the maximum of remaining byte counts in those objects if @var{type} & 2 is
11869 0 and minimum if nonzero. If it is not possible to determine which objects
11870 @var{ptr} points to at compile time, @code{__builtin_object_size} should
11871 return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
11872 for @var{type} 2 or 3.
11874 @var{type} is an integer constant from 0 to 3. If the least significant
11875 bit is clear, objects are whole variables, if it is set, a closest
11876 surrounding subobject is considered the object a pointer points to.
11877 The second bit determines if maximum or minimum of remaining bytes
11881 struct V @{ char buf1[10]; int b; char buf2[10]; @} var;
11882 char *p = &var.buf1[1], *q = &var.b;
11884 /* Here the object p points to is var. */
11885 assert (__builtin_object_size (p, 0) == sizeof (var) - 1);
11886 /* The subobject p points to is var.buf1. */
11887 assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1);
11888 /* The object q points to is var. */
11889 assert (__builtin_object_size (q, 0)
11890 == (char *) (&var + 1) - (char *) &var.b);
11891 /* The subobject q points to is var.b. */
11892 assert (__builtin_object_size (q, 1) == sizeof (var.b));
11896 There are built-in functions added for many common string operation
11897 functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk}
11898 built-in is provided. This built-in has an additional last argument,
11899 which is the number of bytes remaining in the object the @var{dest}
11900 argument points to or @code{(size_t) -1} if the size is not known.
11902 The built-in functions are optimized into the normal string functions
11903 like @code{memcpy} if the last argument is @code{(size_t) -1} or if
11904 it is known at compile time that the destination object will not
11905 be overflowed. If the compiler can determine at compile time that the
11906 object will always be overflowed, it issues a warning.
11908 The intended use can be e.g.@:
11912 #define bos0(dest) __builtin_object_size (dest, 0)
11913 #define memcpy(dest, src, n) \
11914 __builtin___memcpy_chk (dest, src, n, bos0 (dest))
11918 /* It is unknown what object p points to, so this is optimized
11919 into plain memcpy - no checking is possible. */
11920 memcpy (p, "abcde", n);
11921 /* Destination is known and length too. It is known at compile
11922 time there will be no overflow. */
11923 memcpy (&buf[5], "abcde", 5);
11924 /* Destination is known, but the length is not known at compile time.
11925 This will result in __memcpy_chk call that can check for overflow
11927 memcpy (&buf[5], "abcde", n);
11928 /* Destination is known and it is known at compile time there will
11929 be overflow. There will be a warning and __memcpy_chk call that
11930 will abort the program at run time. */
11931 memcpy (&buf[6], "abcde", 5);
11934 Such built-in functions are provided for @code{memcpy}, @code{mempcpy},
11935 @code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy},
11936 @code{strcat} and @code{strncat}.
11938 There are also checking built-in functions for formatted output functions.
11940 int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...);
11941 int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os,
11942 const char *fmt, ...);
11943 int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt,
11945 int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os,
11946 const char *fmt, va_list ap);
11949 The added @var{flag} argument is passed unchanged to @code{__sprintf_chk}
11950 etc.@: functions and can contain implementation specific flags on what
11951 additional security measures the checking function might take, such as
11952 handling @code{%n} differently.
11954 The @var{os} argument is the object size @var{s} points to, like in the
11955 other built-in functions. There is a small difference in the behavior
11956 though, if @var{os} is @code{(size_t) -1}, the built-in functions are
11957 optimized into the non-checking functions only if @var{flag} is 0, otherwise
11958 the checking function is called with @var{os} argument set to
11959 @code{(size_t) -1}.
11961 In addition to this, there are checking built-in functions
11962 @code{__builtin___printf_chk}, @code{__builtin___vprintf_chk},
11963 @code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}.
11964 These have just one additional argument, @var{flag}, right before
11965 format string @var{fmt}. If the compiler is able to optimize them to
11966 @code{fputc} etc.@: functions, it does, otherwise the checking function
11967 is called and the @var{flag} argument passed to it.
11969 @node Other Builtins
11970 @section Other Built-in Functions Provided by GCC
11971 @cindex built-in functions
11972 @findex __builtin_alloca
11973 @findex __builtin_alloca_with_align
11974 @findex __builtin_alloca_with_align_and_max
11975 @findex __builtin_call_with_static_chain
11976 @findex __builtin_extend_pointer
11977 @findex __builtin_fpclassify
11978 @findex __builtin_has_attribute
11979 @findex __builtin_isfinite
11980 @findex __builtin_isnormal
11981 @findex __builtin_isgreater
11982 @findex __builtin_isgreaterequal
11983 @findex __builtin_isinf_sign
11984 @findex __builtin_isless
11985 @findex __builtin_islessequal
11986 @findex __builtin_islessgreater
11987 @findex __builtin_isunordered
11988 @findex __builtin_object_size
11989 @findex __builtin_powi
11990 @findex __builtin_powif
11991 @findex __builtin_powil
11992 @findex __builtin_speculation_safe_value
12153 @findex fprintf_unlocked
12155 @findex fputs_unlocked
12263 @findex nexttowardf
12264 @findex nexttowardl
12272 @findex printf_unlocked
12302 @findex signbitd128
12303 @findex significand
12304 @findex significandf
12305 @findex significandl
12333 @findex strncasecmp
12377 GCC provides a large number of built-in functions other than the ones
12378 mentioned above. Some of these are for internal use in the processing
12379 of exceptions or variable-length argument lists and are not
12380 documented here because they may change from time to time; we do not
12381 recommend general use of these functions.
12383 The remaining functions are provided for optimization purposes.
12385 With the exception of built-ins that have library equivalents such as
12386 the standard C library functions discussed below, or that expand to
12387 library calls, GCC built-in functions are always expanded inline and
12388 thus do not have corresponding entry points and their address cannot
12389 be obtained. Attempting to use them in an expression other than
12390 a function call results in a compile-time error.
12392 @opindex fno-builtin
12393 GCC includes built-in versions of many of the functions in the standard
12394 C library. These functions come in two forms: one whose names start with
12395 the @code{__builtin_} prefix, and the other without. Both forms have the
12396 same type (including prototype), the same address (when their address is
12397 taken), and the same meaning as the C library functions even if you specify
12398 the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these
12399 functions are only optimized in certain cases; if they are not optimized in
12400 a particular case, a call to the library function is emitted.
12404 Outside strict ISO C mode (@option{-ansi}, @option{-std=c90},
12405 @option{-std=c99} or @option{-std=c11}), the functions
12406 @code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero},
12407 @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml},
12408 @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll},
12409 @code{ffsl}, @code{ffs}, @code{fprintf_unlocked},
12410 @code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma},
12411 @code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext},
12412 @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0},
12413 @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn},
12414 @code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy},
12415 @code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked},
12416 @code{rindex}, @code{scalbf}, @code{scalbl}, @code{scalb},
12417 @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32},
12418 @code{signbitd64}, @code{signbitd128}, @code{significandf},
12419 @code{significandl}, @code{significand}, @code{sincosf},
12420 @code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy},
12421 @code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp},
12422 @code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l},
12423 @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and
12425 may be handled as built-in functions.
12426 All these functions have corresponding versions
12427 prefixed with @code{__builtin_}, which may be used even in strict C90
12430 The ISO C99 functions
12431 @code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf},
12432 @code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh},
12433 @code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf},
12434 @code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos},
12435 @code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf},
12436 @code{casinhl}, @code{casinh}, @code{casinl}, @code{casin},
12437 @code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh},
12438 @code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt},
12439 @code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl},
12440 @code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf},
12441 @code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog},
12442 @code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl},
12443 @code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf},
12444 @code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal},
12445 @code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl},
12446 @code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf},
12447 @code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan},
12448 @code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl},
12449 @code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f},
12450 @code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim},
12451 @code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax},
12452 @code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf},
12453 @code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb},
12454 @code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf},
12455 @code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl},
12456 @code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround},
12457 @code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l},
12458 @code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf},
12459 @code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl},
12460 @code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint},
12461 @code{nextafterf}, @code{nextafterl}, @code{nextafter},
12462 @code{nexttowardf}, @code{nexttowardl}, @code{nexttoward},
12463 @code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof},
12464 @code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint},
12465 @code{roundf}, @code{roundl}, @code{round}, @code{scalblnf},
12466 @code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl},
12467 @code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal},
12468 @code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc},
12469 @code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf}
12470 are handled as built-in functions
12471 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
12473 There are also built-in versions of the ISO C99 functions
12474 @code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f},
12475 @code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill},
12476 @code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf},
12477 @code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl},
12478 @code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf},
12479 @code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl},
12480 @code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf},
12481 @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl},
12482 @code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl}
12483 that are recognized in any mode since ISO C90 reserves these names for
12484 the purpose to which ISO C99 puts them. All these functions have
12485 corresponding versions prefixed with @code{__builtin_}.
12487 There are also built-in functions @code{__builtin_fabsf@var{n}},
12488 @code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and
12489 @code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3
12490 functions @code{fabsf@var{n}}, @code{fabsf@var{n}x},
12491 @code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported
12492 types @code{_Float@var{n}} and @code{_Float@var{n}x}.
12494 There are also GNU extension functions @code{clog10}, @code{clog10f} and
12495 @code{clog10l} which names are reserved by ISO C99 for future use.
12496 All these functions have versions prefixed with @code{__builtin_}.
12498 The ISO C94 functions
12499 @code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit},
12500 @code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct},
12501 @code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and
12503 are handled as built-in functions
12504 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
12506 The ISO C90 functions
12507 @code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2},
12508 @code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos},
12509 @code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod},
12510 @code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf},
12511 @code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit},
12512 @code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct},
12513 @code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower},
12514 @code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log},
12515 @code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy},
12516 @code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar},
12517 @code{puts}, @code{scanf}, @code{sinh}, @code{sin}, @code{snprintf},
12518 @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat},
12519 @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn},
12520 @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy},
12521 @code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr},
12522 @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf}
12523 are all recognized as built-in functions unless
12524 @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}}
12525 is specified for an individual function). All of these functions have
12526 corresponding versions prefixed with @code{__builtin_}.
12528 GCC provides built-in versions of the ISO C99 floating-point comparison
12529 macros that avoid raising exceptions for unordered operands. They have
12530 the same names as the standard macros ( @code{isgreater},
12531 @code{isgreaterequal}, @code{isless}, @code{islessequal},
12532 @code{islessgreater}, and @code{isunordered}) , with @code{__builtin_}
12533 prefixed. We intend for a library implementor to be able to simply
12534 @code{#define} each standard macro to its built-in equivalent.
12535 In the same fashion, GCC provides @code{fpclassify}, @code{isfinite},
12536 @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with
12537 @code{__builtin_} prefixed. The @code{isinf} and @code{isnan}
12538 built-in functions appear both with and without the @code{__builtin_} prefix.
12540 @deftypefn {Built-in Function} void *__builtin_alloca (size_t size)
12541 The @code{__builtin_alloca} function must be called at block scope.
12542 The function allocates an object @var{size} bytes large on the stack
12543 of the calling function. The object is aligned on the default stack
12544 alignment boundary for the target determined by the
12545 @code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca}
12546 function returns a pointer to the first byte of the allocated object.
12547 The lifetime of the allocated object ends just before the calling
12548 function returns to its caller. This is so even when
12549 @code{__builtin_alloca} is called within a nested block.
12551 For example, the following function allocates eight objects of @code{n}
12552 bytes each on the stack, storing a pointer to each in consecutive elements
12553 of the array @code{a}. It then passes the array to function @code{g}
12554 which can safely use the storage pointed to by each of the array elements.
12557 void f (unsigned n)
12560 for (int i = 0; i != 8; ++i)
12561 a [i] = __builtin_alloca (n);
12563 g (a, n); // @r{safe}
12567 Since the @code{__builtin_alloca} function doesn't validate its argument
12568 it is the responsibility of its caller to make sure the argument doesn't
12569 cause it to exceed the stack size limit.
12570 The @code{__builtin_alloca} function is provided to make it possible to
12571 allocate on the stack arrays of bytes with an upper bound that may be
12572 computed at run time. Since C99 Variable Length Arrays offer
12573 similar functionality under a portable, more convenient, and safer
12574 interface they are recommended instead, in both C99 and C++ programs
12575 where GCC provides them as an extension.
12576 @xref{Variable Length}, for details.
12580 @deftypefn {Built-in Function} void *__builtin_alloca_with_align (size_t size, size_t alignment)
12581 The @code{__builtin_alloca_with_align} function must be called at block
12582 scope. The function allocates an object @var{size} bytes large on
12583 the stack of the calling function. The allocated object is aligned on
12584 the boundary specified by the argument @var{alignment} whose unit is given
12585 in bits (not bytes). The @var{size} argument must be positive and not
12586 exceed the stack size limit. The @var{alignment} argument must be a constant
12587 integer expression that evaluates to a power of 2 greater than or equal to
12588 @code{CHAR_BIT} and less than some unspecified maximum. Invocations
12589 with other values are rejected with an error indicating the valid bounds.
12590 The function returns a pointer to the first byte of the allocated object.
12591 The lifetime of the allocated object ends at the end of the block in which
12592 the function was called. The allocated storage is released no later than
12593 just before the calling function returns to its caller, but may be released
12594 at the end of the block in which the function was called.
12596 For example, in the following function the call to @code{g} is unsafe
12597 because when @code{overalign} is non-zero, the space allocated by
12598 @code{__builtin_alloca_with_align} may have been released at the end
12599 of the @code{if} statement in which it was called.
12602 void f (unsigned n, bool overalign)
12606 p = __builtin_alloca_with_align (n, 64 /* bits */);
12608 p = __builtin_alloc (n);
12610 g (p, n); // @r{unsafe}
12614 Since the @code{__builtin_alloca_with_align} function doesn't validate its
12615 @var{size} argument it is the responsibility of its caller to make sure
12616 the argument doesn't cause it to exceed the stack size limit.
12617 The @code{__builtin_alloca_with_align} function is provided to make
12618 it possible to allocate on the stack overaligned arrays of bytes with
12619 an upper bound that may be computed at run time. Since C99
12620 Variable Length Arrays offer the same functionality under
12621 a portable, more convenient, and safer interface they are recommended
12622 instead, in both C99 and C++ programs where GCC provides them as
12623 an extension. @xref{Variable Length}, for details.
12627 @deftypefn {Built-in Function} void *__builtin_alloca_with_align_and_max (size_t size, size_t alignment, size_t max_size)
12628 Similar to @code{__builtin_alloca_with_align} but takes an extra argument
12629 specifying an upper bound for @var{size} in case its value cannot be computed
12630 at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage}
12631 and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer
12632 expression, it has no effect on code generation and no attempt is made to
12633 check its compatibility with @var{size}.
12637 @deftypefn {Built-in Function} bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})
12638 The @code{__builtin_has_attribute} function evaluates to an integer constant
12639 expression equal to @code{true} if the symbol or type referenced by
12640 the @var{type-or-expression} argument has been declared with
12641 the @var{attribute} referenced by the second argument. For
12642 an @var{type-or-expression} argument that does not reference a symbol,
12643 since attributes do not apply to expressions the built-in consider
12644 the type of the argument. Neither argument is evaluated.
12645 The @var{type-or-expression} argument is subject to the same
12646 restrictions as the argument to @code{typeof} (@pxref{Typeof}). The
12647 @var{attribute} argument is an attribute name optionally followed by
12648 a comma-separated list of arguments enclosed in parentheses. Both forms
12649 of attribute names---with and without double leading and trailing
12650 underscores---are recognized. @xref{Attribute Syntax}, for details.
12651 When no attribute arguments are specified for an attribute that expects
12652 one or more arguments the function returns @code{true} if
12653 @var{type-or-expression} has been declared with the attribute regardless
12654 of the attribute argument values. Arguments provided for an attribute
12655 that expects some are validated and matched up to the provided number.
12656 The function returns @code{true} if all provided arguments match. For
12657 example, the first call to the function below evaluates to @code{true}
12658 because @code{x} is declared with the @code{aligned} attribute but
12659 the second call evaluates to @code{false} because @code{x} is declared
12660 @code{aligned (8)} and not @code{aligned (4)}.
12663 __attribute__ ((aligned (8))) int x;
12664 _Static_assert (__builtin_has_attribute (x, aligned), "aligned");
12665 _Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)");
12668 Due to a limitation the @code{__builtin_has_attribute} function returns
12669 @code{false} for the @code{mode} attribute even if the type or variable
12670 referenced by the @var{type-or-expression} argument was declared with one.
12671 The function is also not supported with labels, and in C with enumerators.
12673 Note that unlike the @code{__has_attribute} preprocessor operator which
12674 is suitable for use in @code{#if} preprocessing directives
12675 @code{__builtin_has_attribute} is an intrinsic function that is not
12676 recognized in such contexts.
12680 @deftypefn {Built-in Function} @var{type} __builtin_speculation_safe_value (@var{type} val, @var{type} failval)
12682 This built-in function can be used to help mitigate against unsafe
12683 speculative execution. @var{type} may be any integral type or any
12688 If the CPU is not speculatively executing the code, then @var{val}
12691 If the CPU is executing speculatively then either:
12694 The function may cause execution to pause until it is known that the
12695 code is no-longer being executed speculatively (in which case
12696 @var{val} can be returned, as above); or
12698 The function may use target-dependent speculation tracking state to cause
12699 @var{failval} to be returned when it is known that speculative
12700 execution has incorrectly predicted a conditional branch operation.
12704 The second argument, @var{failval}, is optional and defaults to zero
12707 GCC defines the preprocessor macro
12708 @code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been
12709 updated to support this builtin.
12711 The built-in function can be used where a variable appears to be used in a
12712 safe way, but the CPU, due to speculative execution may temporarily ignore
12713 the bounds checks. Consider, for example, the following function:
12717 int f (unsigned untrusted_index)
12719 if (untrusted_index < 500)
12720 return array[untrusted_index];
12725 If the function is called repeatedly with @code{untrusted_index} less
12726 than the limit of 500, then a branch predictor will learn that the
12727 block of code that returns a value stored in @code{array} will be
12728 executed. If the function is subsequently called with an
12729 out-of-range value it will still try to execute that block of code
12730 first until the CPU determines that the prediction was incorrect
12731 (the CPU will unwind any incorrect operations at that point).
12732 However, depending on how the result of the function is used, it might be
12733 possible to leave traces in the cache that can reveal what was stored
12734 at the out-of-bounds location. The built-in function can be used to
12735 provide some protection against leaking data in this way by changing
12740 int f (unsigned untrusted_index)
12742 if (untrusted_index < 500)
12743 return array[__builtin_speculation_safe_value (untrusted_index)];
12748 The built-in function will either cause execution to stall until the
12749 conditional branch has been fully resolved, or it may permit
12750 speculative execution to continue, but using 0 instead of
12751 @code{untrusted_value} if that exceeds the limit.
12753 If accessing any memory location is potentially unsafe when speculative
12754 execution is incorrect, then the code can be rewritten as
12758 int f (unsigned untrusted_index)
12760 if (untrusted_index < 500)
12761 return *__builtin_speculation_safe_value (&array[untrusted_index], NULL);
12766 which will cause a @code{NULL} pointer to be used for the unsafe case.
12770 @deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2})
12772 You can use the built-in function @code{__builtin_types_compatible_p} to
12773 determine whether two types are the same.
12775 This built-in function returns 1 if the unqualified versions of the
12776 types @var{type1} and @var{type2} (which are types, not expressions) are
12777 compatible, 0 otherwise. The result of this built-in function can be
12778 used in integer constant expressions.
12780 This built-in function ignores top level qualifiers (e.g., @code{const},
12781 @code{volatile}). For example, @code{int} is equivalent to @code{const
12784 The type @code{int[]} and @code{int[5]} are compatible. On the other
12785 hand, @code{int} and @code{char *} are not compatible, even if the size
12786 of their types, on the particular architecture are the same. Also, the
12787 amount of pointer indirection is taken into account when determining
12788 similarity. Consequently, @code{short *} is not similar to
12789 @code{short **}. Furthermore, two types that are typedefed are
12790 considered compatible if their underlying types are compatible.
12792 An @code{enum} type is not considered to be compatible with another
12793 @code{enum} type even if both are compatible with the same integer
12794 type; this is what the C standard specifies.
12795 For example, @code{enum @{foo, bar@}} is not similar to
12796 @code{enum @{hot, dog@}}.
12798 You typically use this function in code whose execution varies
12799 depending on the arguments' types. For example:
12804 typeof (x) tmp = (x); \
12805 if (__builtin_types_compatible_p (typeof (x), long double)) \
12806 tmp = foo_long_double (tmp); \
12807 else if (__builtin_types_compatible_p (typeof (x), double)) \
12808 tmp = foo_double (tmp); \
12809 else if (__builtin_types_compatible_p (typeof (x), float)) \
12810 tmp = foo_float (tmp); \
12817 @emph{Note:} This construct is only available for C@.
12821 @deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})
12823 The @var{call_exp} expression must be a function call, and the
12824 @var{pointer_exp} expression must be a pointer. The @var{pointer_exp}
12825 is passed to the function call in the target's static chain location.
12826 The result of builtin is the result of the function call.
12828 @emph{Note:} This builtin is only available for C@.
12829 This builtin can be used to call Go closures from C.
12833 @deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})
12835 You can use the built-in function @code{__builtin_choose_expr} to
12836 evaluate code depending on the value of a constant expression. This
12837 built-in function returns @var{exp1} if @var{const_exp}, which is an
12838 integer constant expression, is nonzero. Otherwise it returns @var{exp2}.
12840 This built-in function is analogous to the @samp{? :} operator in C,
12841 except that the expression returned has its type unaltered by promotion
12842 rules. Also, the built-in function does not evaluate the expression
12843 that is not chosen. For example, if @var{const_exp} evaluates to @code{true},
12844 @var{exp2} is not evaluated even if it has side effects.
12846 This built-in function can return an lvalue if the chosen argument is an
12849 If @var{exp1} is returned, the return type is the same as @var{exp1}'s
12850 type. Similarly, if @var{exp2} is returned, its return type is the same
12857 __builtin_choose_expr ( \
12858 __builtin_types_compatible_p (typeof (x), double), \
12860 __builtin_choose_expr ( \
12861 __builtin_types_compatible_p (typeof (x), float), \
12863 /* @r{The void expression results in a compile-time error} \
12864 @r{when assigning the result to something.} */ \
12868 @emph{Note:} This construct is only available for C@. Furthermore, the
12869 unused expression (@var{exp1} or @var{exp2} depending on the value of
12870 @var{const_exp}) may still generate syntax errors. This may change in
12875 @deftypefn {Built-in Function} @var{type} __builtin_tgmath (@var{functions}, @var{arguments})
12877 The built-in function @code{__builtin_tgmath}, available only for C
12878 and Objective-C, calls a function determined according to the rules of
12879 @code{<tgmath.h>} macros. It is intended to be used in
12880 implementations of that header, so that expansions of macros from that
12881 header only expand each of their arguments once, to avoid problems
12882 when calls to such macros are nested inside the arguments of other
12883 calls to such macros; in addition, it results in better diagnostics
12884 for invalid calls to @code{<tgmath.h>} macros than implementations
12885 using other GNU C language features. For example, the @code{pow}
12886 type-generic macro might be defined as:
12889 #define pow(a, b) __builtin_tgmath (powf, pow, powl, \
12890 cpowf, cpow, cpowl, a, b)
12893 The arguments to @code{__builtin_tgmath} are at least two pointers to
12894 functions, followed by the arguments to the type-generic macro (which
12895 will be passed as arguments to the selected function). All the
12896 pointers to functions must be pointers to prototyped functions, none
12897 of which may have variable arguments, and all of which must have the
12898 same number of parameters; the number of parameters of the first
12899 function determines how many arguments to @code{__builtin_tgmath} are
12900 interpreted as function pointers, and how many as the arguments to the
12903 The types of the specified functions must all be different, but
12904 related to each other in the same way as a set of functions that may
12905 be selected between by a macro in @code{<tgmath.h>}. This means that
12906 the functions are parameterized by a floating-point type @var{t},
12907 different for each such function. The function return types may all
12908 be the same type, or they may be @var{t} for each function, or they
12909 may be the real type corresponding to @var{t} for each function (if
12910 some of the types @var{t} are complex). Likewise, for each parameter
12911 position, the type of the parameter in that position may always be the
12912 same type, or may be @var{t} for each function (this case must apply
12913 for at least one parameter position), or may be the real type
12914 corresponding to @var{t} for each function.
12916 The standard rules for @code{<tgmath.h>} macros are used to find a
12917 common type @var{u} from the types of the arguments for parameters
12918 whose types vary between the functions; complex integer types (a GNU
12919 extension) are treated like @code{_Complex double} for this purpose
12920 (or @code{_Complex _Float64} if all the function return types are the
12921 same @code{_Float@var{n}} or @code{_Float@var{n}x} type).
12922 If the function return types vary, or are all the same integer type,
12923 the function called is the one for which @var{t} is @var{u}, and it is
12924 an error if there is no such function. If the function return types
12925 are all the same floating-point type, the type-generic macro is taken
12926 to be one of those from TS 18661 that rounds the result to a narrower
12927 type; if there is a function for which @var{t} is @var{u}, it is
12928 called, and otherwise the first function, if any, for which @var{t}
12929 has at least the range and precision of @var{u} is called, and it is
12930 an error if there is no such function.
12934 @deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag})
12936 The built-in function @code{__builtin_complex} is provided for use in
12937 implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
12938 @code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
12939 real binary floating-point type, and the result has the corresponding
12940 complex type with real and imaginary parts @var{real} and @var{imag}.
12941 Unlike @samp{@var{real} + I * @var{imag}}, this works even when
12942 infinities, NaNs and negative zeros are involved.
12946 @deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
12947 You can use the built-in function @code{__builtin_constant_p} to
12948 determine if a value is known to be constant at compile time and hence
12949 that GCC can perform constant-folding on expressions involving that
12950 value. The argument of the function is the value to test. The function
12951 returns the integer 1 if the argument is known to be a compile-time
12952 constant and 0 if it is not known to be a compile-time constant. A
12953 return of 0 does not indicate that the value is @emph{not} a constant,
12954 but merely that GCC cannot prove it is a constant with the specified
12955 value of the @option{-O} option.
12957 You typically use this function in an embedded application where
12958 memory is a critical resource. If you have some complex calculation,
12959 you may want it to be folded if it involves constants, but need to call
12960 a function if it does not. For example:
12963 #define Scale_Value(X) \
12964 (__builtin_constant_p (X) \
12965 ? ((X) * SCALE + OFFSET) : Scale (X))
12968 You may use this built-in function in either a macro or an inline
12969 function. However, if you use it in an inlined function and pass an
12970 argument of the function as the argument to the built-in, GCC
12971 never returns 1 when you call the inline function with a string constant
12972 or compound literal (@pxref{Compound Literals}) and does not return 1
12973 when you pass a constant numeric value to the inline function unless you
12974 specify the @option{-O} option.
12976 You may also use @code{__builtin_constant_p} in initializers for static
12977 data. For instance, you can write
12980 static const int table[] = @{
12981 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
12987 This is an acceptable initializer even if @var{EXPRESSION} is not a
12988 constant expression, including the case where
12989 @code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be
12990 folded to a constant but @var{EXPRESSION} contains operands that are
12991 not otherwise permitted in a static initializer (for example,
12992 @code{0 && foo ()}). GCC must be more conservative about evaluating the
12993 built-in in this case, because it has no opportunity to perform
12997 @deftypefn {Built-in Function} bool __builtin_is_constant_evaluated (void)
12998 The @code{__builtin_is_constant_evaluated} function is available only
12999 in C++. The built-in is intended to be used by implementations of
13000 the @code{std::is_constant_evaluated} C++ function. Programs should make
13001 use of the latter function rather than invoking the built-in directly.
13003 The main use case of the built-in is to determine whether a @code{constexpr}
13004 function is being called in a @code{constexpr} context. A call to
13005 the function evaluates to a core constant expression with the value
13006 @code{true} if and only if it occurs within the evaluation of an expression
13007 or conversion that is manifestly constant-evaluated as defined in the C++
13008 standard. Manifestly constant-evaluated contexts include constant-expressions,
13009 the conditions of @code{constexpr if} statements, constraint-expressions, and
13010 initializers of variables usable in constant expressions. For more details
13011 refer to the latest revision of the C++ standard.
13014 @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
13015 @opindex fprofile-arcs
13016 You may use @code{__builtin_expect} to provide the compiler with
13017 branch prediction information. In general, you should prefer to
13018 use actual profile feedback for this (@option{-fprofile-arcs}), as
13019 programmers are notoriously bad at predicting how their programs
13020 actually perform. However, there are applications in which this
13021 data is hard to collect.
13023 The return value is the value of @var{exp}, which should be an integral
13024 expression. The semantics of the built-in are that it is expected that
13025 @var{exp} == @var{c}. For example:
13028 if (__builtin_expect (x, 0))
13033 indicates that we do not expect to call @code{foo}, since
13034 we expect @code{x} to be zero. Since you are limited to integral
13035 expressions for @var{exp}, you should use constructions such as
13038 if (__builtin_expect (ptr != NULL, 1))
13043 when testing pointer or floating-point values.
13045 For the purposes of branch prediction optimizations, the probability that
13046 a @code{__builtin_expect} expression is @code{true} is controlled by GCC's
13047 @code{builtin-expect-probability} parameter, which defaults to 90%.
13048 You can also use @code{__builtin_expect_with_probability} to explicitly
13049 assign a probability value to individual expressions.
13052 @deftypefn {Built-in Function} long __builtin_expect_with_probability
13053 (long @var{exp}, long @var{c}, double @var{probability})
13055 This function has the same semantics as @code{__builtin_expect},
13056 but the caller provides the expected probability that @var{exp} == @var{c}.
13057 The last argument, @var{probability}, is a floating-point value in the
13058 range 0.0 to 1.0, inclusive. The @var{probability} argument must be
13059 constant floating-point expression.
13062 @deftypefn {Built-in Function} void __builtin_trap (void)
13063 This function causes the program to exit abnormally. GCC implements
13064 this function by using a target-dependent mechanism (such as
13065 intentionally executing an illegal instruction) or by calling
13066 @code{abort}. The mechanism used may vary from release to release so
13067 you should not rely on any particular implementation.
13070 @deftypefn {Built-in Function} void __builtin_unreachable (void)
13071 If control flow reaches the point of the @code{__builtin_unreachable},
13072 the program is undefined. It is useful in situations where the
13073 compiler cannot deduce the unreachability of the code.
13075 One such case is immediately following an @code{asm} statement that
13076 either never terminates, or one that transfers control elsewhere
13077 and never returns. In this example, without the
13078 @code{__builtin_unreachable}, GCC issues a warning that control
13079 reaches the end of a non-void function. It also generates code
13080 to return after the @code{asm}.
13083 int f (int c, int v)
13091 asm("jmp error_handler");
13092 __builtin_unreachable ();
13098 Because the @code{asm} statement unconditionally transfers control out
13099 of the function, control never reaches the end of the function
13100 body. The @code{__builtin_unreachable} is in fact unreachable and
13101 communicates this fact to the compiler.
13103 Another use for @code{__builtin_unreachable} is following a call a
13104 function that never returns but that is not declared
13105 @code{__attribute__((noreturn))}, as in this example:
13108 void function_that_never_returns (void);
13118 function_that_never_returns ();
13119 __builtin_unreachable ();
13126 @deftypefn {Built-in Function} {void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)
13127 This function returns its first argument, and allows the compiler
13128 to assume that the returned pointer is at least @var{align} bytes
13129 aligned. This built-in can have either two or three arguments,
13130 if it has three, the third argument should have integer type, and
13131 if it is nonzero means misalignment offset. For example:
13134 void *x = __builtin_assume_aligned (arg, 16);
13138 means that the compiler can assume @code{x}, set to @code{arg}, is at least
13139 16-byte aligned, while:
13142 void *x = __builtin_assume_aligned (arg, 32, 8);
13146 means that the compiler can assume for @code{x}, set to @code{arg}, that
13147 @code{(char *) x - 8} is 32-byte aligned.
13150 @deftypefn {Built-in Function} int __builtin_LINE ()
13151 This function is the equivalent of the preprocessor @code{__LINE__}
13152 macro and returns a constant integer expression that evaluates to
13153 the line number of the invocation of the built-in. When used as a C++
13154 default argument for a function @var{F}, it returns the line number
13155 of the call to @var{F}.
13158 @deftypefn {Built-in Function} {const char *} __builtin_FUNCTION ()
13159 This function is the equivalent of the @code{__FUNCTION__} symbol
13160 and returns an address constant pointing to the name of the function
13161 from which the built-in was invoked, or the empty string if
13162 the invocation is not at function scope. When used as a C++ default
13163 argument for a function @var{F}, it returns the name of @var{F}'s
13164 caller or the empty string if the call was not made at function
13168 @deftypefn {Built-in Function} {const char *} __builtin_FILE ()
13169 This function is the equivalent of the preprocessor @code{__FILE__}
13170 macro and returns an address constant pointing to the file name
13171 containing the invocation of the built-in, or the empty string if
13172 the invocation is not at function scope. When used as a C++ default
13173 argument for a function @var{F}, it returns the file name of the call
13174 to @var{F} or the empty string if the call was not made at function
13177 For example, in the following, each call to function @code{foo} will
13178 print a line similar to @code{"file.c:123: foo: message"} with the name
13179 of the file and the line number of the @code{printf} call, the name of
13180 the function @code{foo}, followed by the word @code{message}.
13184 function (const char *func = __builtin_FUNCTION ())
13191 printf ("%s:%i: %s: message\n", file (), line (), function ());
13197 @deftypefn {Built-in Function} void __builtin___clear_cache (void *@var{begin}, void *@var{end})
13198 This function is used to flush the processor's instruction cache for
13199 the region of memory between @var{begin} inclusive and @var{end}
13200 exclusive. Some targets require that the instruction cache be
13201 flushed, after modifying memory containing code, in order to obtain
13202 deterministic behavior.
13204 If the target does not require instruction cache flushes,
13205 @code{__builtin___clear_cache} has no effect. Otherwise either
13206 instructions are emitted in-line to clear the instruction cache or a
13207 call to the @code{__clear_cache} function in libgcc is made.
13210 @deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...)
13211 This function is used to minimize cache-miss latency by moving data into
13212 a cache before it is accessed.
13213 You can insert calls to @code{__builtin_prefetch} into code for which
13214 you know addresses of data in memory that is likely to be accessed soon.
13215 If the target supports them, data prefetch instructions are generated.
13216 If the prefetch is done early enough before the access then the data will
13217 be in the cache by the time it is accessed.
13219 The value of @var{addr} is the address of the memory to prefetch.
13220 There are two optional arguments, @var{rw} and @var{locality}.
13221 The value of @var{rw} is a compile-time constant one or zero; one
13222 means that the prefetch is preparing for a write to the memory address
13223 and zero, the default, means that the prefetch is preparing for a read.
13224 The value @var{locality} must be a compile-time constant integer between
13225 zero and three. A value of zero means that the data has no temporal
13226 locality, so it need not be left in the cache after the access. A value
13227 of three means that the data has a high degree of temporal locality and
13228 should be left in all levels of cache possible. Values of one and two
13229 mean, respectively, a low or moderate degree of temporal locality. The
13233 for (i = 0; i < n; i++)
13235 a[i] = a[i] + b[i];
13236 __builtin_prefetch (&a[i+j], 1, 1);
13237 __builtin_prefetch (&b[i+j], 0, 1);
13242 Data prefetch does not generate faults if @var{addr} is invalid, but
13243 the address expression itself must be valid. For example, a prefetch
13244 of @code{p->next} does not fault if @code{p->next} is not a valid
13245 address, but evaluation faults if @code{p} is not a valid address.
13247 If the target does not support data prefetch, the address expression
13248 is evaluated if it includes side effects but no other code is generated
13249 and GCC does not issue a warning.
13252 @deftypefn {Built-in Function}{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
13253 Returns the size of an object pointed to by @var{ptr}. @xref{Object Size
13254 Checking}, for a detailed description of the function.
13257 @deftypefn {Built-in Function} double __builtin_huge_val (void)
13258 Returns a positive infinity, if supported by the floating-point format,
13259 else @code{DBL_MAX}. This function is suitable for implementing the
13260 ISO C macro @code{HUGE_VAL}.
13263 @deftypefn {Built-in Function} float __builtin_huge_valf (void)
13264 Similar to @code{__builtin_huge_val}, except the return type is @code{float}.
13267 @deftypefn {Built-in Function} {long double} __builtin_huge_vall (void)
13268 Similar to @code{__builtin_huge_val}, except the return
13269 type is @code{long double}.
13272 @deftypefn {Built-in Function} _Float@var{n} __builtin_huge_valf@var{n} (void)
13273 Similar to @code{__builtin_huge_val}, except the return type is
13274 @code{_Float@var{n}}.
13277 @deftypefn {Built-in Function} _Float@var{n}x __builtin_huge_valf@var{n}x (void)
13278 Similar to @code{__builtin_huge_val}, except the return type is
13279 @code{_Float@var{n}x}.
13282 @deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...)
13283 This built-in implements the C99 fpclassify functionality. The first
13284 five int arguments should be the target library's notion of the
13285 possible FP classes and are used for return values. They must be
13286 constant values and they must appear in this order: @code{FP_NAN},
13287 @code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and
13288 @code{FP_ZERO}. The ellipsis is for exactly one floating-point value
13289 to classify. GCC treats the last argument as type-generic, which
13290 means it does not do default promotion from float to double.
13293 @deftypefn {Built-in Function} double __builtin_inf (void)
13294 Similar to @code{__builtin_huge_val}, except a warning is generated
13295 if the target floating-point format does not support infinities.
13298 @deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void)
13299 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}.
13302 @deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void)
13303 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}.
13306 @deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void)
13307 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}.
13310 @deftypefn {Built-in Function} float __builtin_inff (void)
13311 Similar to @code{__builtin_inf}, except the return type is @code{float}.
13312 This function is suitable for implementing the ISO C99 macro @code{INFINITY}.
13315 @deftypefn {Built-in Function} {long double} __builtin_infl (void)
13316 Similar to @code{__builtin_inf}, except the return
13317 type is @code{long double}.
13320 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n} (void)
13321 Similar to @code{__builtin_inf}, except the return
13322 type is @code{_Float@var{n}}.
13325 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n}x (void)
13326 Similar to @code{__builtin_inf}, except the return
13327 type is @code{_Float@var{n}x}.
13330 @deftypefn {Built-in Function} int __builtin_isinf_sign (...)
13331 Similar to @code{isinf}, except the return value is -1 for
13332 an argument of @code{-Inf} and 1 for an argument of @code{+Inf}.
13333 Note while the parameter list is an
13334 ellipsis, this function only accepts exactly one floating-point
13335 argument. GCC treats this parameter as type-generic, which means it
13336 does not do default promotion from float to double.
13339 @deftypefn {Built-in Function} double __builtin_nan (const char *str)
13340 This is an implementation of the ISO C99 function @code{nan}.
13342 Since ISO C99 defines this function in terms of @code{strtod}, which we
13343 do not implement, a description of the parsing is in order. The string
13344 is parsed as by @code{strtol}; that is, the base is recognized by
13345 leading @samp{0} or @samp{0x} prefixes. The number parsed is placed
13346 in the significand such that the least significant bit of the number
13347 is at the least significant bit of the significand. The number is
13348 truncated to fit the significand field provided. The significand is
13349 forced to be a quiet NaN@.
13351 This function, if given a string literal all of which would have been
13352 consumed by @code{strtol}, is evaluated early enough that it is considered a
13353 compile-time constant.
13356 @deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str)
13357 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}.
13360 @deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str)
13361 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}.
13364 @deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str)
13365 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}.
13368 @deftypefn {Built-in Function} float __builtin_nanf (const char *str)
13369 Similar to @code{__builtin_nan}, except the return type is @code{float}.
13372 @deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str)
13373 Similar to @code{__builtin_nan}, except the return type is @code{long double}.
13376 @deftypefn {Built-in Function} _Float@var{n} __builtin_nanf@var{n} (const char *str)
13377 Similar to @code{__builtin_nan}, except the return type is
13378 @code{_Float@var{n}}.
13381 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nanf@var{n}x (const char *str)
13382 Similar to @code{__builtin_nan}, except the return type is
13383 @code{_Float@var{n}x}.
13386 @deftypefn {Built-in Function} double __builtin_nans (const char *str)
13387 Similar to @code{__builtin_nan}, except the significand is forced
13388 to be a signaling NaN@. The @code{nans} function is proposed by
13389 @uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}.
13392 @deftypefn {Built-in Function} float __builtin_nansf (const char *str)
13393 Similar to @code{__builtin_nans}, except the return type is @code{float}.
13396 @deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str)
13397 Similar to @code{__builtin_nans}, except the return type is @code{long double}.
13400 @deftypefn {Built-in Function} _Float@var{n} __builtin_nansf@var{n} (const char *str)
13401 Similar to @code{__builtin_nans}, except the return type is
13402 @code{_Float@var{n}}.
13405 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nansf@var{n}x (const char *str)
13406 Similar to @code{__builtin_nans}, except the return type is
13407 @code{_Float@var{n}x}.
13410 @deftypefn {Built-in Function} int __builtin_ffs (int x)
13411 Returns one plus the index of the least significant 1-bit of @var{x}, or
13412 if @var{x} is zero, returns zero.
13415 @deftypefn {Built-in Function} int __builtin_clz (unsigned int x)
13416 Returns the number of leading 0-bits in @var{x}, starting at the most
13417 significant bit position. If @var{x} is 0, the result is undefined.
13420 @deftypefn {Built-in Function} int __builtin_ctz (unsigned int x)
13421 Returns the number of trailing 0-bits in @var{x}, starting at the least
13422 significant bit position. If @var{x} is 0, the result is undefined.
13425 @deftypefn {Built-in Function} int __builtin_clrsb (int x)
13426 Returns the number of leading redundant sign bits in @var{x}, i.e.@: the
13427 number of bits following the most significant bit that are identical
13428 to it. There are no special cases for 0 or other values.
13431 @deftypefn {Built-in Function} int __builtin_popcount (unsigned int x)
13432 Returns the number of 1-bits in @var{x}.
13435 @deftypefn {Built-in Function} int __builtin_parity (unsigned int x)
13436 Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x}
13440 @deftypefn {Built-in Function} int __builtin_ffsl (long)
13441 Similar to @code{__builtin_ffs}, except the argument type is
13445 @deftypefn {Built-in Function} int __builtin_clzl (unsigned long)
13446 Similar to @code{__builtin_clz}, except the argument type is
13447 @code{unsigned long}.
13450 @deftypefn {Built-in Function} int __builtin_ctzl (unsigned long)
13451 Similar to @code{__builtin_ctz}, except the argument type is
13452 @code{unsigned long}.
13455 @deftypefn {Built-in Function} int __builtin_clrsbl (long)
13456 Similar to @code{__builtin_clrsb}, except the argument type is
13460 @deftypefn {Built-in Function} int __builtin_popcountl (unsigned long)
13461 Similar to @code{__builtin_popcount}, except the argument type is
13462 @code{unsigned long}.
13465 @deftypefn {Built-in Function} int __builtin_parityl (unsigned long)
13466 Similar to @code{__builtin_parity}, except the argument type is
13467 @code{unsigned long}.
13470 @deftypefn {Built-in Function} int __builtin_ffsll (long long)
13471 Similar to @code{__builtin_ffs}, except the argument type is
13475 @deftypefn {Built-in Function} int __builtin_clzll (unsigned long long)
13476 Similar to @code{__builtin_clz}, except the argument type is
13477 @code{unsigned long long}.
13480 @deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long)
13481 Similar to @code{__builtin_ctz}, except the argument type is
13482 @code{unsigned long long}.
13485 @deftypefn {Built-in Function} int __builtin_clrsbll (long long)
13486 Similar to @code{__builtin_clrsb}, except the argument type is
13490 @deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long)
13491 Similar to @code{__builtin_popcount}, except the argument type is
13492 @code{unsigned long long}.
13495 @deftypefn {Built-in Function} int __builtin_parityll (unsigned long long)
13496 Similar to @code{__builtin_parity}, except the argument type is
13497 @code{unsigned long long}.
13500 @deftypefn {Built-in Function} double __builtin_powi (double, int)
13501 Returns the first argument raised to the power of the second. Unlike the
13502 @code{pow} function no guarantees about precision and rounding are made.
13505 @deftypefn {Built-in Function} float __builtin_powif (float, int)
13506 Similar to @code{__builtin_powi}, except the argument and return types
13510 @deftypefn {Built-in Function} {long double} __builtin_powil (long double, int)
13511 Similar to @code{__builtin_powi}, except the argument and return types
13512 are @code{long double}.
13515 @deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x)
13516 Returns @var{x} with the order of the bytes reversed; for example,
13517 @code{0xaabb} becomes @code{0xbbaa}. Byte here always means
13521 @deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x)
13522 Similar to @code{__builtin_bswap16}, except the argument and return types
13526 @deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x)
13527 Similar to @code{__builtin_bswap32}, except the argument and return types
13531 @deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x)
13532 On targets where the user visible pointer size is smaller than the size
13533 of an actual hardware address this function returns the extended user
13534 pointer. Targets where this is true included ILP32 mode on x86_64 or
13535 Aarch64. This function is mainly useful when writing inline assembly
13539 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_id (int x)
13540 Returns the openacc gang, worker or vector id depending on whether @var{x} is
13544 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_size (int x)
13545 Returns the openacc gang, worker or vector size depending on whether @var{x} is
13549 @node Target Builtins
13550 @section Built-in Functions Specific to Particular Target Machines
13552 On some target machines, GCC supports many built-in functions specific
13553 to those machines. Generally these generate calls to specific machine
13554 instructions, but allow the compiler to schedule those calls.
13557 * AArch64 Built-in Functions::
13558 * Alpha Built-in Functions::
13559 * Altera Nios II Built-in Functions::
13560 * ARC Built-in Functions::
13561 * ARC SIMD Built-in Functions::
13562 * ARM iWMMXt Built-in Functions::
13563 * ARM C Language Extensions (ACLE)::
13564 * ARM Floating Point Status and Control Intrinsics::
13565 * ARM ARMv8-M Security Extensions::
13566 * AVR Built-in Functions::
13567 * Blackfin Built-in Functions::
13568 * FR-V Built-in Functions::
13569 * MIPS DSP Built-in Functions::
13570 * MIPS Paired-Single Support::
13571 * MIPS Loongson Built-in Functions::
13572 * MIPS SIMD Architecture (MSA) Support::
13573 * Other MIPS Built-in Functions::
13574 * MSP430 Built-in Functions::
13575 * NDS32 Built-in Functions::
13576 * picoChip Built-in Functions::
13577 * Basic PowerPC Built-in Functions::
13578 * PowerPC AltiVec/VSX Built-in Functions::
13579 * PowerPC Hardware Transactional Memory Built-in Functions::
13580 * PowerPC Atomic Memory Operation Functions::
13581 * RX Built-in Functions::
13582 * S/390 System z Built-in Functions::
13583 * SH Built-in Functions::
13584 * SPARC VIS Built-in Functions::
13585 * SPU Built-in Functions::
13586 * TI C6X Built-in Functions::
13587 * TILE-Gx Built-in Functions::
13588 * TILEPro Built-in Functions::
13589 * x86 Built-in Functions::
13590 * x86 transactional memory intrinsics::
13591 * x86 control-flow protection intrinsics::
13594 @node AArch64 Built-in Functions
13595 @subsection AArch64 Built-in Functions
13597 These built-in functions are available for the AArch64 family of
13600 unsigned int __builtin_aarch64_get_fpcr ()
13601 void __builtin_aarch64_set_fpcr (unsigned int)
13602 unsigned int __builtin_aarch64_get_fpsr ()
13603 void __builtin_aarch64_set_fpsr (unsigned int)
13606 @node Alpha Built-in Functions
13607 @subsection Alpha Built-in Functions
13609 These built-in functions are available for the Alpha family of
13610 processors, depending on the command-line switches used.
13612 The following built-in functions are always available. They
13613 all generate the machine instruction that is part of the name.
13616 long __builtin_alpha_implver (void)
13617 long __builtin_alpha_rpcc (void)
13618 long __builtin_alpha_amask (long)
13619 long __builtin_alpha_cmpbge (long, long)
13620 long __builtin_alpha_extbl (long, long)
13621 long __builtin_alpha_extwl (long, long)
13622 long __builtin_alpha_extll (long, long)
13623 long __builtin_alpha_extql (long, long)
13624 long __builtin_alpha_extwh (long, long)
13625 long __builtin_alpha_extlh (long, long)
13626 long __builtin_alpha_extqh (long, long)
13627 long __builtin_alpha_insbl (long, long)
13628 long __builtin_alpha_inswl (long, long)
13629 long __builtin_alpha_insll (long, long)
13630 long __builtin_alpha_insql (long, long)
13631 long __builtin_alpha_inswh (long, long)
13632 long __builtin_alpha_inslh (long, long)
13633 long __builtin_alpha_insqh (long, long)
13634 long __builtin_alpha_mskbl (long, long)
13635 long __builtin_alpha_mskwl (long, long)
13636 long __builtin_alpha_mskll (long, long)
13637 long __builtin_alpha_mskql (long, long)
13638 long __builtin_alpha_mskwh (long, long)
13639 long __builtin_alpha_msklh (long, long)
13640 long __builtin_alpha_mskqh (long, long)
13641 long __builtin_alpha_umulh (long, long)
13642 long __builtin_alpha_zap (long, long)
13643 long __builtin_alpha_zapnot (long, long)
13646 The following built-in functions are always with @option{-mmax}
13647 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
13648 later. They all generate the machine instruction that is part
13652 long __builtin_alpha_pklb (long)
13653 long __builtin_alpha_pkwb (long)
13654 long __builtin_alpha_unpkbl (long)
13655 long __builtin_alpha_unpkbw (long)
13656 long __builtin_alpha_minub8 (long, long)
13657 long __builtin_alpha_minsb8 (long, long)
13658 long __builtin_alpha_minuw4 (long, long)
13659 long __builtin_alpha_minsw4 (long, long)
13660 long __builtin_alpha_maxub8 (long, long)
13661 long __builtin_alpha_maxsb8 (long, long)
13662 long __builtin_alpha_maxuw4 (long, long)
13663 long __builtin_alpha_maxsw4 (long, long)
13664 long __builtin_alpha_perr (long, long)
13667 The following built-in functions are always with @option{-mcix}
13668 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
13669 later. They all generate the machine instruction that is part
13673 long __builtin_alpha_cttz (long)
13674 long __builtin_alpha_ctlz (long)
13675 long __builtin_alpha_ctpop (long)
13678 The following built-in functions are available on systems that use the OSF/1
13679 PALcode. Normally they invoke the @code{rduniq} and @code{wruniq}
13680 PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
13681 @code{rdval} and @code{wrval}.
13684 void *__builtin_thread_pointer (void)
13685 void __builtin_set_thread_pointer (void *)
13688 @node Altera Nios II Built-in Functions
13689 @subsection Altera Nios II Built-in Functions
13691 These built-in functions are available for the Altera Nios II
13692 family of processors.
13694 The following built-in functions are always available. They
13695 all generate the machine instruction that is part of the name.
13698 int __builtin_ldbio (volatile const void *)
13699 int __builtin_ldbuio (volatile const void *)
13700 int __builtin_ldhio (volatile const void *)
13701 int __builtin_ldhuio (volatile const void *)
13702 int __builtin_ldwio (volatile const void *)
13703 void __builtin_stbio (volatile void *, int)
13704 void __builtin_sthio (volatile void *, int)
13705 void __builtin_stwio (volatile void *, int)
13706 void __builtin_sync (void)
13707 int __builtin_rdctl (int)
13708 int __builtin_rdprs (int, int)
13709 void __builtin_wrctl (int, int)
13710 void __builtin_flushd (volatile void *)
13711 void __builtin_flushda (volatile void *)
13712 int __builtin_wrpie (int);
13713 void __builtin_eni (int);
13714 int __builtin_ldex (volatile const void *)
13715 int __builtin_stex (volatile void *, int)
13716 int __builtin_ldsex (volatile const void *)
13717 int __builtin_stsex (volatile void *, int)
13720 The following built-in functions are always available. They
13721 all generate a Nios II Custom Instruction. The name of the
13722 function represents the types that the function takes and
13723 returns. The letter before the @code{n} is the return type
13724 or void if absent. The @code{n} represents the first parameter
13725 to all the custom instructions, the custom instruction number.
13726 The two letters after the @code{n} represent the up to two
13727 parameters to the function.
13729 The letters represent the following data types:
13732 @code{void} for return type and no parameter for parameter types.
13735 @code{int} for return type and parameter type
13738 @code{float} for return type and parameter type
13741 @code{void *} for return type and parameter type
13745 And the function names are:
13747 void __builtin_custom_n (void)
13748 void __builtin_custom_ni (int)
13749 void __builtin_custom_nf (float)
13750 void __builtin_custom_np (void *)
13751 void __builtin_custom_nii (int, int)
13752 void __builtin_custom_nif (int, float)
13753 void __builtin_custom_nip (int, void *)
13754 void __builtin_custom_nfi (float, int)
13755 void __builtin_custom_nff (float, float)
13756 void __builtin_custom_nfp (float, void *)
13757 void __builtin_custom_npi (void *, int)
13758 void __builtin_custom_npf (void *, float)
13759 void __builtin_custom_npp (void *, void *)
13760 int __builtin_custom_in (void)
13761 int __builtin_custom_ini (int)
13762 int __builtin_custom_inf (float)
13763 int __builtin_custom_inp (void *)
13764 int __builtin_custom_inii (int, int)
13765 int __builtin_custom_inif (int, float)
13766 int __builtin_custom_inip (int, void *)
13767 int __builtin_custom_infi (float, int)
13768 int __builtin_custom_inff (float, float)
13769 int __builtin_custom_infp (float, void *)
13770 int __builtin_custom_inpi (void *, int)
13771 int __builtin_custom_inpf (void *, float)
13772 int __builtin_custom_inpp (void *, void *)
13773 float __builtin_custom_fn (void)
13774 float __builtin_custom_fni (int)
13775 float __builtin_custom_fnf (float)
13776 float __builtin_custom_fnp (void *)
13777 float __builtin_custom_fnii (int, int)
13778 float __builtin_custom_fnif (int, float)
13779 float __builtin_custom_fnip (int, void *)
13780 float __builtin_custom_fnfi (float, int)
13781 float __builtin_custom_fnff (float, float)
13782 float __builtin_custom_fnfp (float, void *)
13783 float __builtin_custom_fnpi (void *, int)
13784 float __builtin_custom_fnpf (void *, float)
13785 float __builtin_custom_fnpp (void *, void *)
13786 void * __builtin_custom_pn (void)
13787 void * __builtin_custom_pni (int)
13788 void * __builtin_custom_pnf (float)
13789 void * __builtin_custom_pnp (void *)
13790 void * __builtin_custom_pnii (int, int)
13791 void * __builtin_custom_pnif (int, float)
13792 void * __builtin_custom_pnip (int, void *)
13793 void * __builtin_custom_pnfi (float, int)
13794 void * __builtin_custom_pnff (float, float)
13795 void * __builtin_custom_pnfp (float, void *)
13796 void * __builtin_custom_pnpi (void *, int)
13797 void * __builtin_custom_pnpf (void *, float)
13798 void * __builtin_custom_pnpp (void *, void *)
13801 @node ARC Built-in Functions
13802 @subsection ARC Built-in Functions
13804 The following built-in functions are provided for ARC targets. The
13805 built-ins generate the corresponding assembly instructions. In the
13806 examples given below, the generated code often requires an operand or
13807 result to be in a register. Where necessary further code will be
13808 generated to ensure this is true, but for brevity this is not
13809 described in each case.
13811 @emph{Note:} Using a built-in to generate an instruction not supported
13812 by a target may cause problems. At present the compiler is not
13813 guaranteed to detect such misuse, and as a result an internal compiler
13814 error may be generated.
13816 @deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval})
13817 Return 1 if @var{val} is known to have the byte alignment given
13818 by @var{alignval}, otherwise return 0.
13819 Note that this is different from
13821 __alignof__(*(char *)@var{val}) >= alignval
13823 because __alignof__ sees only the type of the dereference, whereas
13824 __builtin_arc_align uses alignment information from the pointer
13825 as well as from the pointed-to type.
13826 The information available will depend on optimization level.
13829 @deftypefn {Built-in Function} void __builtin_arc_brk (void)
13836 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno})
13837 The operand is the number of a register to be read. Generates:
13839 mov @var{dest}, r@var{regno}
13841 where the value in @var{dest} will be the result returned from the
13845 @deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val})
13846 The first operand is the number of a register to be written, the
13847 second operand is a compile time constant to write into that
13848 register. Generates:
13850 mov r@var{regno}, @var{val}
13854 @deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b})
13855 Only available if either @option{-mcpu=ARC700} or @option{-meA} is set.
13858 divaw @var{dest}, @var{a}, @var{b}
13860 where the value in @var{dest} will be the result returned from the
13864 @deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a})
13871 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr})
13872 The operand, @var{auxv}, is the address of an auxiliary register and
13873 must be a compile time constant. Generates:
13875 lr @var{dest}, [@var{auxr}]
13877 Where the value in @var{dest} will be the result returned from the
13881 @deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b})
13882 Only available with @option{-mmul64}. Generates:
13884 mul64 @var{a}, @var{b}
13888 @deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b})
13889 Only available with @option{-mmul64}. Generates:
13891 mulu64 @var{a}, @var{b}
13895 @deftypefn {Built-in Function} void __builtin_arc_nop (void)
13902 @deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src})
13903 Only valid if the @samp{norm} instruction is available through the
13904 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
13907 norm @var{dest}, @var{src}
13909 Where the value in @var{dest} will be the result returned from the
13913 @deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src})
13914 Only valid if the @samp{normw} instruction is available through the
13915 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
13918 normw @var{dest}, @var{src}
13920 Where the value in @var{dest} will be the result returned from the
13924 @deftypefn {Built-in Function} void __builtin_arc_rtie (void)
13931 @deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a}
13938 @deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{auxr}, unsigned int @var{val})
13939 The first argument, @var{auxv}, is the address of an auxiliary
13940 register, the second argument, @var{val}, is a compile time constant
13941 to be written to the register. Generates:
13943 sr @var{auxr}, [@var{val}]
13947 @deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src})
13948 Only valid with @option{-mswap}. Generates:
13950 swap @var{dest}, @var{src}
13952 Where the value in @var{dest} will be the result returned from the
13956 @deftypefn {Built-in Function} void __builtin_arc_swi (void)
13963 @deftypefn {Built-in Function} void __builtin_arc_sync (void)
13964 Only available with @option{-mcpu=ARC700}. Generates:
13970 @deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c})
13971 Only available with @option{-mcpu=ARC700}. Generates:
13977 @deftypefn {Built-in Function} void __builtin_arc_unimp_s (void)
13978 Only available with @option{-mcpu=ARC700}. Generates:
13984 The instructions generated by the following builtins are not
13985 considered as candidates for scheduling. They are not moved around by
13986 the compiler during scheduling, and thus can be expected to appear
13987 where they are put in the C code:
13989 __builtin_arc_brk()
13990 __builtin_arc_core_read()
13991 __builtin_arc_core_write()
13992 __builtin_arc_flag()
13994 __builtin_arc_sleep()
13996 __builtin_arc_swi()
13999 @node ARC SIMD Built-in Functions
14000 @subsection ARC SIMD Built-in Functions
14002 SIMD builtins provided by the compiler can be used to generate the
14003 vector instructions. This section describes the available builtins
14004 and their usage in programs. With the @option{-msimd} option, the
14005 compiler provides 128-bit vector types, which can be specified using
14006 the @code{vector_size} attribute. The header file @file{arc-simd.h}
14007 can be included to use the following predefined types:
14009 typedef int __v4si __attribute__((vector_size(16)));
14010 typedef short __v8hi __attribute__((vector_size(16)));
14013 These types can be used to define 128-bit variables. The built-in
14014 functions listed in the following section can be used on these
14015 variables to generate the vector operations.
14017 For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file
14018 @file{arc-simd.h} also provides equivalent macros called
14019 @code{_@var{someinsn}} that can be used for programming ease and
14020 improved readability. The following macros for DMA control are also
14023 #define _setup_dma_in_channel_reg _vdiwr
14024 #define _setup_dma_out_channel_reg _vdowr
14027 The following is a complete list of all the SIMD built-ins provided
14028 for ARC, grouped by calling signature.
14030 The following take two @code{__v8hi} arguments and return a
14031 @code{__v8hi} result:
14033 __v8hi __builtin_arc_vaddaw (__v8hi, __v8hi)
14034 __v8hi __builtin_arc_vaddw (__v8hi, __v8hi)
14035 __v8hi __builtin_arc_vand (__v8hi, __v8hi)
14036 __v8hi __builtin_arc_vandaw (__v8hi, __v8hi)
14037 __v8hi __builtin_arc_vavb (__v8hi, __v8hi)
14038 __v8hi __builtin_arc_vavrb (__v8hi, __v8hi)
14039 __v8hi __builtin_arc_vbic (__v8hi, __v8hi)
14040 __v8hi __builtin_arc_vbicaw (__v8hi, __v8hi)
14041 __v8hi __builtin_arc_vdifaw (__v8hi, __v8hi)
14042 __v8hi __builtin_arc_vdifw (__v8hi, __v8hi)
14043 __v8hi __builtin_arc_veqw (__v8hi, __v8hi)
14044 __v8hi __builtin_arc_vh264f (__v8hi, __v8hi)
14045 __v8hi __builtin_arc_vh264ft (__v8hi, __v8hi)
14046 __v8hi __builtin_arc_vh264fw (__v8hi, __v8hi)
14047 __v8hi __builtin_arc_vlew (__v8hi, __v8hi)
14048 __v8hi __builtin_arc_vltw (__v8hi, __v8hi)
14049 __v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi)
14050 __v8hi __builtin_arc_vmaxw (__v8hi, __v8hi)
14051 __v8hi __builtin_arc_vminaw (__v8hi, __v8hi)
14052 __v8hi __builtin_arc_vminw (__v8hi, __v8hi)
14053 __v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi)
14054 __v8hi __builtin_arc_vmr1w (__v8hi, __v8hi)
14055 __v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi)
14056 __v8hi __builtin_arc_vmr2w (__v8hi, __v8hi)
14057 __v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi)
14058 __v8hi __builtin_arc_vmr3w (__v8hi, __v8hi)
14059 __v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi)
14060 __v8hi __builtin_arc_vmr4w (__v8hi, __v8hi)
14061 __v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi)
14062 __v8hi __builtin_arc_vmr5w (__v8hi, __v8hi)
14063 __v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi)
14064 __v8hi __builtin_arc_vmr6w (__v8hi, __v8hi)
14065 __v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi)
14066 __v8hi __builtin_arc_vmr7w (__v8hi, __v8hi)
14067 __v8hi __builtin_arc_vmrb (__v8hi, __v8hi)
14068 __v8hi __builtin_arc_vmulaw (__v8hi, __v8hi)
14069 __v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi)
14070 __v8hi __builtin_arc_vmulfw (__v8hi, __v8hi)
14071 __v8hi __builtin_arc_vmulw (__v8hi, __v8hi)
14072 __v8hi __builtin_arc_vnew (__v8hi, __v8hi)
14073 __v8hi __builtin_arc_vor (__v8hi, __v8hi)
14074 __v8hi __builtin_arc_vsubaw (__v8hi, __v8hi)
14075 __v8hi __builtin_arc_vsubw (__v8hi, __v8hi)
14076 __v8hi __builtin_arc_vsummw (__v8hi, __v8hi)
14077 __v8hi __builtin_arc_vvc1f (__v8hi, __v8hi)
14078 __v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi)
14079 __v8hi __builtin_arc_vxor (__v8hi, __v8hi)
14080 __v8hi __builtin_arc_vxoraw (__v8hi, __v8hi)
14083 The following take one @code{__v8hi} and one @code{int} argument and return a
14084 @code{__v8hi} result:
14087 __v8hi __builtin_arc_vbaddw (__v8hi, int)
14088 __v8hi __builtin_arc_vbmaxw (__v8hi, int)
14089 __v8hi __builtin_arc_vbminw (__v8hi, int)
14090 __v8hi __builtin_arc_vbmulaw (__v8hi, int)
14091 __v8hi __builtin_arc_vbmulfw (__v8hi, int)
14092 __v8hi __builtin_arc_vbmulw (__v8hi, int)
14093 __v8hi __builtin_arc_vbrsubw (__v8hi, int)
14094 __v8hi __builtin_arc_vbsubw (__v8hi, int)
14097 The following take one @code{__v8hi} argument and one @code{int} argument which
14098 must be a 3-bit compile time constant indicating a register number
14099 I0-I7. They return a @code{__v8hi} result.
14101 __v8hi __builtin_arc_vasrw (__v8hi, const int)
14102 __v8hi __builtin_arc_vsr8 (__v8hi, const int)
14103 __v8hi __builtin_arc_vsr8aw (__v8hi, const int)
14106 The following take one @code{__v8hi} argument and one @code{int}
14107 argument which must be a 6-bit compile time constant. They return a
14108 @code{__v8hi} result.
14110 __v8hi __builtin_arc_vasrpwbi (__v8hi, const int)
14111 __v8hi __builtin_arc_vasrrpwbi (__v8hi, const int)
14112 __v8hi __builtin_arc_vasrrwi (__v8hi, const int)
14113 __v8hi __builtin_arc_vasrsrwi (__v8hi, const int)
14114 __v8hi __builtin_arc_vasrwi (__v8hi, const int)
14115 __v8hi __builtin_arc_vsr8awi (__v8hi, const int)
14116 __v8hi __builtin_arc_vsr8i (__v8hi, const int)
14119 The following take one @code{__v8hi} argument and one @code{int} argument which
14120 must be a 8-bit compile time constant. They return a @code{__v8hi}
14123 __v8hi __builtin_arc_vd6tapf (__v8hi, const int)
14124 __v8hi __builtin_arc_vmvaw (__v8hi, const int)
14125 __v8hi __builtin_arc_vmvw (__v8hi, const int)
14126 __v8hi __builtin_arc_vmvzw (__v8hi, const int)
14129 The following take two @code{int} arguments, the second of which which
14130 must be a 8-bit compile time constant. They return a @code{__v8hi}
14133 __v8hi __builtin_arc_vmovaw (int, const int)
14134 __v8hi __builtin_arc_vmovw (int, const int)
14135 __v8hi __builtin_arc_vmovzw (int, const int)
14138 The following take a single @code{__v8hi} argument and return a
14139 @code{__v8hi} result:
14141 __v8hi __builtin_arc_vabsaw (__v8hi)
14142 __v8hi __builtin_arc_vabsw (__v8hi)
14143 __v8hi __builtin_arc_vaddsuw (__v8hi)
14144 __v8hi __builtin_arc_vexch1 (__v8hi)
14145 __v8hi __builtin_arc_vexch2 (__v8hi)
14146 __v8hi __builtin_arc_vexch4 (__v8hi)
14147 __v8hi __builtin_arc_vsignw (__v8hi)
14148 __v8hi __builtin_arc_vupbaw (__v8hi)
14149 __v8hi __builtin_arc_vupbw (__v8hi)
14150 __v8hi __builtin_arc_vupsbaw (__v8hi)
14151 __v8hi __builtin_arc_vupsbw (__v8hi)
14154 The following take two @code{int} arguments and return no result:
14156 void __builtin_arc_vdirun (int, int)
14157 void __builtin_arc_vdorun (int, int)
14160 The following take two @code{int} arguments and return no result. The
14161 first argument must a 3-bit compile time constant indicating one of
14162 the DR0-DR7 DMA setup channels:
14164 void __builtin_arc_vdiwr (const int, int)
14165 void __builtin_arc_vdowr (const int, int)
14168 The following take an @code{int} argument and return no result:
14170 void __builtin_arc_vendrec (int)
14171 void __builtin_arc_vrec (int)
14172 void __builtin_arc_vrecrun (int)
14173 void __builtin_arc_vrun (int)
14176 The following take a @code{__v8hi} argument and two @code{int}
14177 arguments and return a @code{__v8hi} result. The second argument must
14178 be a 3-bit compile time constants, indicating one the registers I0-I7,
14179 and the third argument must be an 8-bit compile time constant.
14181 @emph{Note:} Although the equivalent hardware instructions do not take
14182 an SIMD register as an operand, these builtins overwrite the relevant
14183 bits of the @code{__v8hi} register provided as the first argument with
14184 the value loaded from the @code{[Ib, u8]} location in the SDM.
14187 __v8hi __builtin_arc_vld32 (__v8hi, const int, const int)
14188 __v8hi __builtin_arc_vld32wh (__v8hi, const int, const int)
14189 __v8hi __builtin_arc_vld32wl (__v8hi, const int, const int)
14190 __v8hi __builtin_arc_vld64 (__v8hi, const int, const int)
14193 The following take two @code{int} arguments and return a @code{__v8hi}
14194 result. The first argument must be a 3-bit compile time constants,
14195 indicating one the registers I0-I7, and the second argument must be an
14196 8-bit compile time constant.
14199 __v8hi __builtin_arc_vld128 (const int, const int)
14200 __v8hi __builtin_arc_vld64w (const int, const int)
14203 The following take a @code{__v8hi} argument and two @code{int}
14204 arguments and return no result. The second argument must be a 3-bit
14205 compile time constants, indicating one the registers I0-I7, and the
14206 third argument must be an 8-bit compile time constant.
14209 void __builtin_arc_vst128 (__v8hi, const int, const int)
14210 void __builtin_arc_vst64 (__v8hi, const int, const int)
14213 The following take a @code{__v8hi} argument and three @code{int}
14214 arguments and return no result. The second argument must be a 3-bit
14215 compile-time constant, identifying the 16-bit sub-register to be
14216 stored, the third argument must be a 3-bit compile time constants,
14217 indicating one the registers I0-I7, and the fourth argument must be an
14218 8-bit compile time constant.
14221 void __builtin_arc_vst16_n (__v8hi, const int, const int, const int)
14222 void __builtin_arc_vst32_n (__v8hi, const int, const int, const int)
14225 @node ARM iWMMXt Built-in Functions
14226 @subsection ARM iWMMXt Built-in Functions
14228 These built-in functions are available for the ARM family of
14229 processors when the @option{-mcpu=iwmmxt} switch is used:
14232 typedef int v2si __attribute__ ((vector_size (8)));
14233 typedef short v4hi __attribute__ ((vector_size (8)));
14234 typedef char v8qi __attribute__ ((vector_size (8)));
14236 int __builtin_arm_getwcgr0 (void)
14237 void __builtin_arm_setwcgr0 (int)
14238 int __builtin_arm_getwcgr1 (void)
14239 void __builtin_arm_setwcgr1 (int)
14240 int __builtin_arm_getwcgr2 (void)
14241 void __builtin_arm_setwcgr2 (int)
14242 int __builtin_arm_getwcgr3 (void)
14243 void __builtin_arm_setwcgr3 (int)
14244 int __builtin_arm_textrmsb (v8qi, int)
14245 int __builtin_arm_textrmsh (v4hi, int)
14246 int __builtin_arm_textrmsw (v2si, int)
14247 int __builtin_arm_textrmub (v8qi, int)
14248 int __builtin_arm_textrmuh (v4hi, int)
14249 int __builtin_arm_textrmuw (v2si, int)
14250 v8qi __builtin_arm_tinsrb (v8qi, int, int)
14251 v4hi __builtin_arm_tinsrh (v4hi, int, int)
14252 v2si __builtin_arm_tinsrw (v2si, int, int)
14253 long long __builtin_arm_tmia (long long, int, int)
14254 long long __builtin_arm_tmiabb (long long, int, int)
14255 long long __builtin_arm_tmiabt (long long, int, int)
14256 long long __builtin_arm_tmiaph (long long, int, int)
14257 long long __builtin_arm_tmiatb (long long, int, int)
14258 long long __builtin_arm_tmiatt (long long, int, int)
14259 int __builtin_arm_tmovmskb (v8qi)
14260 int __builtin_arm_tmovmskh (v4hi)
14261 int __builtin_arm_tmovmskw (v2si)
14262 long long __builtin_arm_waccb (v8qi)
14263 long long __builtin_arm_wacch (v4hi)
14264 long long __builtin_arm_waccw (v2si)
14265 v8qi __builtin_arm_waddb (v8qi, v8qi)
14266 v8qi __builtin_arm_waddbss (v8qi, v8qi)
14267 v8qi __builtin_arm_waddbus (v8qi, v8qi)
14268 v4hi __builtin_arm_waddh (v4hi, v4hi)
14269 v4hi __builtin_arm_waddhss (v4hi, v4hi)
14270 v4hi __builtin_arm_waddhus (v4hi, v4hi)
14271 v2si __builtin_arm_waddw (v2si, v2si)
14272 v2si __builtin_arm_waddwss (v2si, v2si)
14273 v2si __builtin_arm_waddwus (v2si, v2si)
14274 v8qi __builtin_arm_walign (v8qi, v8qi, int)
14275 long long __builtin_arm_wand(long long, long long)
14276 long long __builtin_arm_wandn (long long, long long)
14277 v8qi __builtin_arm_wavg2b (v8qi, v8qi)
14278 v8qi __builtin_arm_wavg2br (v8qi, v8qi)
14279 v4hi __builtin_arm_wavg2h (v4hi, v4hi)
14280 v4hi __builtin_arm_wavg2hr (v4hi, v4hi)
14281 v8qi __builtin_arm_wcmpeqb (v8qi, v8qi)
14282 v4hi __builtin_arm_wcmpeqh (v4hi, v4hi)
14283 v2si __builtin_arm_wcmpeqw (v2si, v2si)
14284 v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi)
14285 v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi)
14286 v2si __builtin_arm_wcmpgtsw (v2si, v2si)
14287 v8qi __builtin_arm_wcmpgtub (v8qi, v8qi)
14288 v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi)
14289 v2si __builtin_arm_wcmpgtuw (v2si, v2si)
14290 long long __builtin_arm_wmacs (long long, v4hi, v4hi)
14291 long long __builtin_arm_wmacsz (v4hi, v4hi)
14292 long long __builtin_arm_wmacu (long long, v4hi, v4hi)
14293 long long __builtin_arm_wmacuz (v4hi, v4hi)
14294 v4hi __builtin_arm_wmadds (v4hi, v4hi)
14295 v4hi __builtin_arm_wmaddu (v4hi, v4hi)
14296 v8qi __builtin_arm_wmaxsb (v8qi, v8qi)
14297 v4hi __builtin_arm_wmaxsh (v4hi, v4hi)
14298 v2si __builtin_arm_wmaxsw (v2si, v2si)
14299 v8qi __builtin_arm_wmaxub (v8qi, v8qi)
14300 v4hi __builtin_arm_wmaxuh (v4hi, v4hi)
14301 v2si __builtin_arm_wmaxuw (v2si, v2si)
14302 v8qi __builtin_arm_wminsb (v8qi, v8qi)
14303 v4hi __builtin_arm_wminsh (v4hi, v4hi)
14304 v2si __builtin_arm_wminsw (v2si, v2si)
14305 v8qi __builtin_arm_wminub (v8qi, v8qi)
14306 v4hi __builtin_arm_wminuh (v4hi, v4hi)
14307 v2si __builtin_arm_wminuw (v2si, v2si)
14308 v4hi __builtin_arm_wmulsm (v4hi, v4hi)
14309 v4hi __builtin_arm_wmulul (v4hi, v4hi)
14310 v4hi __builtin_arm_wmulum (v4hi, v4hi)
14311 long long __builtin_arm_wor (long long, long long)
14312 v2si __builtin_arm_wpackdss (long long, long long)
14313 v2si __builtin_arm_wpackdus (long long, long long)
14314 v8qi __builtin_arm_wpackhss (v4hi, v4hi)
14315 v8qi __builtin_arm_wpackhus (v4hi, v4hi)
14316 v4hi __builtin_arm_wpackwss (v2si, v2si)
14317 v4hi __builtin_arm_wpackwus (v2si, v2si)
14318 long long __builtin_arm_wrord (long long, long long)
14319 long long __builtin_arm_wrordi (long long, int)
14320 v4hi __builtin_arm_wrorh (v4hi, long long)
14321 v4hi __builtin_arm_wrorhi (v4hi, int)
14322 v2si __builtin_arm_wrorw (v2si, long long)
14323 v2si __builtin_arm_wrorwi (v2si, int)
14324 v2si __builtin_arm_wsadb (v2si, v8qi, v8qi)
14325 v2si __builtin_arm_wsadbz (v8qi, v8qi)
14326 v2si __builtin_arm_wsadh (v2si, v4hi, v4hi)
14327 v2si __builtin_arm_wsadhz (v4hi, v4hi)
14328 v4hi __builtin_arm_wshufh (v4hi, int)
14329 long long __builtin_arm_wslld (long long, long long)
14330 long long __builtin_arm_wslldi (long long, int)
14331 v4hi __builtin_arm_wsllh (v4hi, long long)
14332 v4hi __builtin_arm_wsllhi (v4hi, int)
14333 v2si __builtin_arm_wsllw (v2si, long long)
14334 v2si __builtin_arm_wsllwi (v2si, int)
14335 long long __builtin_arm_wsrad (long long, long long)
14336 long long __builtin_arm_wsradi (long long, int)
14337 v4hi __builtin_arm_wsrah (v4hi, long long)
14338 v4hi __builtin_arm_wsrahi (v4hi, int)
14339 v2si __builtin_arm_wsraw (v2si, long long)
14340 v2si __builtin_arm_wsrawi (v2si, int)
14341 long long __builtin_arm_wsrld (long long, long long)
14342 long long __builtin_arm_wsrldi (long long, int)
14343 v4hi __builtin_arm_wsrlh (v4hi, long long)
14344 v4hi __builtin_arm_wsrlhi (v4hi, int)
14345 v2si __builtin_arm_wsrlw (v2si, long long)
14346 v2si __builtin_arm_wsrlwi (v2si, int)
14347 v8qi __builtin_arm_wsubb (v8qi, v8qi)
14348 v8qi __builtin_arm_wsubbss (v8qi, v8qi)
14349 v8qi __builtin_arm_wsubbus (v8qi, v8qi)
14350 v4hi __builtin_arm_wsubh (v4hi, v4hi)
14351 v4hi __builtin_arm_wsubhss (v4hi, v4hi)
14352 v4hi __builtin_arm_wsubhus (v4hi, v4hi)
14353 v2si __builtin_arm_wsubw (v2si, v2si)
14354 v2si __builtin_arm_wsubwss (v2si, v2si)
14355 v2si __builtin_arm_wsubwus (v2si, v2si)
14356 v4hi __builtin_arm_wunpckehsb (v8qi)
14357 v2si __builtin_arm_wunpckehsh (v4hi)
14358 long long __builtin_arm_wunpckehsw (v2si)
14359 v4hi __builtin_arm_wunpckehub (v8qi)
14360 v2si __builtin_arm_wunpckehuh (v4hi)
14361 long long __builtin_arm_wunpckehuw (v2si)
14362 v4hi __builtin_arm_wunpckelsb (v8qi)
14363 v2si __builtin_arm_wunpckelsh (v4hi)
14364 long long __builtin_arm_wunpckelsw (v2si)
14365 v4hi __builtin_arm_wunpckelub (v8qi)
14366 v2si __builtin_arm_wunpckeluh (v4hi)
14367 long long __builtin_arm_wunpckeluw (v2si)
14368 v8qi __builtin_arm_wunpckihb (v8qi, v8qi)
14369 v4hi __builtin_arm_wunpckihh (v4hi, v4hi)
14370 v2si __builtin_arm_wunpckihw (v2si, v2si)
14371 v8qi __builtin_arm_wunpckilb (v8qi, v8qi)
14372 v4hi __builtin_arm_wunpckilh (v4hi, v4hi)
14373 v2si __builtin_arm_wunpckilw (v2si, v2si)
14374 long long __builtin_arm_wxor (long long, long long)
14375 long long __builtin_arm_wzero ()
14379 @node ARM C Language Extensions (ACLE)
14380 @subsection ARM C Language Extensions (ACLE)
14382 GCC implements extensions for C as described in the ARM C Language
14383 Extensions (ACLE) specification, which can be found at
14384 @uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf}.
14386 As a part of ACLE, GCC implements extensions for Advanced SIMD as described in
14387 the ARM C Language Extensions Specification. The complete list of Advanced SIMD
14388 intrinsics can be found at
14389 @uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0073a/IHI0073A_arm_neon_intrinsics_ref.pdf}.
14390 The built-in intrinsics for the Advanced SIMD extension are available when
14393 Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both
14394 back ends support CRC32 intrinsics and the ARM back end supports the
14395 Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit
14396 floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1.
14397 AArch64's back end does not have support for 16-bit floating point Advanced SIMD
14400 See @ref{ARM Options} and @ref{AArch64 Options} for more information on the
14401 availability of extensions.
14403 @node ARM Floating Point Status and Control Intrinsics
14404 @subsection ARM Floating Point Status and Control Intrinsics
14406 These built-in functions are available for the ARM family of
14407 processors with floating-point unit.
14410 unsigned int __builtin_arm_get_fpscr ()
14411 void __builtin_arm_set_fpscr (unsigned int)
14414 @node ARM ARMv8-M Security Extensions
14415 @subsection ARM ARMv8-M Security Extensions
14417 GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M
14418 Security Extensions: Requirements on Development Tools Engineering
14419 Specification, which can be found at
14420 @uref{http://infocenter.arm.com/help/topic/com.arm.doc.ecm0359818/ECM0359818_armv8m_security_extensions_reqs_on_dev_tools_1_0.pdf}.
14422 As part of the Security Extensions GCC implements two new function attributes:
14423 @code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}.
14425 As part of the Security Extensions GCC implements the intrinsics below. FPTR
14426 is used here to mean any function pointer type.
14429 cmse_address_info_t cmse_TT (void *)
14430 cmse_address_info_t cmse_TT_fptr (FPTR)
14431 cmse_address_info_t cmse_TTT (void *)
14432 cmse_address_info_t cmse_TTT_fptr (FPTR)
14433 cmse_address_info_t cmse_TTA (void *)
14434 cmse_address_info_t cmse_TTA_fptr (FPTR)
14435 cmse_address_info_t cmse_TTAT (void *)
14436 cmse_address_info_t cmse_TTAT_fptr (FPTR)
14437 void * cmse_check_address_range (void *, size_t, int)
14438 typeof(p) cmse_nsfptr_create (FPTR p)
14439 intptr_t cmse_is_nsfptr (FPTR)
14440 int cmse_nonsecure_caller (void)
14443 @node AVR Built-in Functions
14444 @subsection AVR Built-in Functions
14446 For each built-in function for AVR, there is an equally named,
14447 uppercase built-in macro defined. That way users can easily query if
14448 or if not a specific built-in is implemented or not. For example, if
14449 @code{__builtin_avr_nop} is available the macro
14450 @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise.
14454 @item void __builtin_avr_nop (void)
14455 @itemx void __builtin_avr_sei (void)
14456 @itemx void __builtin_avr_cli (void)
14457 @itemx void __builtin_avr_sleep (void)
14458 @itemx void __builtin_avr_wdr (void)
14459 @itemx unsigned char __builtin_avr_swap (unsigned char)
14460 @itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char)
14461 @itemx int __builtin_avr_fmuls (char, char)
14462 @itemx int __builtin_avr_fmulsu (char, unsigned char)
14463 These built-in functions map to the respective machine
14464 instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep},
14465 @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls}
14466 resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented
14467 as library call if no hardware multiplier is available.
14469 @item void __builtin_avr_delay_cycles (unsigned long ticks)
14470 Delay execution for @var{ticks} cycles. Note that this
14471 built-in does not take into account the effect of interrupts that
14472 might increase delay time. @var{ticks} must be a compile-time
14473 integer constant; delays with a variable number of cycles are not supported.
14475 @item char __builtin_avr_flash_segment (const __memx void*)
14476 This built-in takes a byte address to the 24-bit
14477 @ref{AVR Named Address Spaces,address space} @code{__memx} and returns
14478 the number of the flash segment (the 64 KiB chunk) where the address
14479 points to. Counting starts at @code{0}.
14480 If the address does not point to flash memory, return @code{-1}.
14482 @item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val)
14483 Insert bits from @var{bits} into @var{val} and return the resulting
14484 value. The nibbles of @var{map} determine how the insertion is
14485 performed: Let @var{X} be the @var{n}-th nibble of @var{map}
14487 @item If @var{X} is @code{0xf},
14488 then the @var{n}-th bit of @var{val} is returned unaltered.
14490 @item If X is in the range 0@dots{}7,
14491 then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits}
14493 @item If X is in the range 8@dots{}@code{0xe},
14494 then the @var{n}-th result bit is undefined.
14498 One typical use case for this built-in is adjusting input and
14499 output values to non-contiguous port layouts. Some examples:
14502 // same as val, bits is unused
14503 __builtin_avr_insert_bits (0xffffffff, bits, val)
14507 // same as bits, val is unused
14508 __builtin_avr_insert_bits (0x76543210, bits, val)
14512 // same as rotating bits by 4
14513 __builtin_avr_insert_bits (0x32107654, bits, 0)
14517 // high nibble of result is the high nibble of val
14518 // low nibble of result is the low nibble of bits
14519 __builtin_avr_insert_bits (0xffff3210, bits, val)
14523 // reverse the bit order of bits
14524 __builtin_avr_insert_bits (0x01234567, bits, 0)
14527 @item void __builtin_avr_nops (unsigned count)
14528 Insert @var{count} @code{NOP} instructions.
14529 The number of instructions must be a compile-time integer constant.
14534 There are many more AVR-specific built-in functions that are used to
14535 implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of
14536 section 7.18a.6. You don't need to use these built-ins directly.
14537 Instead, use the declarations as supplied by the @code{stdfix.h} header
14541 #include <stdfix.h>
14543 // Re-interpret the bit representation of unsigned 16-bit
14544 // integer @var{uval} as Q-format 0.16 value.
14545 unsigned fract get_bits (uint_ur_t uval)
14547 return urbits (uval);
14551 @node Blackfin Built-in Functions
14552 @subsection Blackfin Built-in Functions
14554 Currently, there are two Blackfin-specific built-in functions. These are
14555 used for generating @code{CSYNC} and @code{SSYNC} machine insns without
14556 using inline assembly; by using these built-in functions the compiler can
14557 automatically add workarounds for hardware errata involving these
14558 instructions. These functions are named as follows:
14561 void __builtin_bfin_csync (void)
14562 void __builtin_bfin_ssync (void)
14565 @node FR-V Built-in Functions
14566 @subsection FR-V Built-in Functions
14568 GCC provides many FR-V-specific built-in functions. In general,
14569 these functions are intended to be compatible with those described
14570 by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu
14571 Semiconductor}. The two exceptions are @code{__MDUNPACKH} and
14572 @code{__MBTOHE}, the GCC forms of which pass 128-bit values by
14573 pointer rather than by value.
14575 Most of the functions are named after specific FR-V instructions.
14576 Such functions are said to be ``directly mapped'' and are summarized
14577 here in tabular form.
14581 * Directly-mapped Integer Functions::
14582 * Directly-mapped Media Functions::
14583 * Raw read/write Functions::
14584 * Other Built-in Functions::
14587 @node Argument Types
14588 @subsubsection Argument Types
14590 The arguments to the built-in functions can be divided into three groups:
14591 register numbers, compile-time constants and run-time values. In order
14592 to make this classification clear at a glance, the arguments and return
14593 values are given the following pseudo types:
14595 @multitable @columnfractions .20 .30 .15 .35
14596 @item Pseudo type @tab Real C type @tab Constant? @tab Description
14597 @item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword
14598 @item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word
14599 @item @code{sw1} @tab @code{int} @tab No @tab a signed word
14600 @item @code{uw2} @tab @code{unsigned long long} @tab No
14601 @tab an unsigned doubleword
14602 @item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword
14603 @item @code{const} @tab @code{int} @tab Yes @tab an integer constant
14604 @item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number
14605 @item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number
14608 These pseudo types are not defined by GCC, they are simply a notational
14609 convenience used in this manual.
14611 Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2}
14612 and @code{sw2} are evaluated at run time. They correspond to
14613 register operands in the underlying FR-V instructions.
14615 @code{const} arguments represent immediate operands in the underlying
14616 FR-V instructions. They must be compile-time constants.
14618 @code{acc} arguments are evaluated at compile time and specify the number
14619 of an accumulator register. For example, an @code{acc} argument of 2
14620 selects the ACC2 register.
14622 @code{iacc} arguments are similar to @code{acc} arguments but specify the
14623 number of an IACC register. See @pxref{Other Built-in Functions}
14626 @node Directly-mapped Integer Functions
14627 @subsubsection Directly-Mapped Integer Functions
14629 The functions listed below map directly to FR-V I-type instructions.
14631 @multitable @columnfractions .45 .32 .23
14632 @item Function prototype @tab Example usage @tab Assembly output
14633 @item @code{sw1 __ADDSS (sw1, sw1)}
14634 @tab @code{@var{c} = __ADDSS (@var{a}, @var{b})}
14635 @tab @code{ADDSS @var{a},@var{b},@var{c}}
14636 @item @code{sw1 __SCAN (sw1, sw1)}
14637 @tab @code{@var{c} = __SCAN (@var{a}, @var{b})}
14638 @tab @code{SCAN @var{a},@var{b},@var{c}}
14639 @item @code{sw1 __SCUTSS (sw1)}
14640 @tab @code{@var{b} = __SCUTSS (@var{a})}
14641 @tab @code{SCUTSS @var{a},@var{b}}
14642 @item @code{sw1 __SLASS (sw1, sw1)}
14643 @tab @code{@var{c} = __SLASS (@var{a}, @var{b})}
14644 @tab @code{SLASS @var{a},@var{b},@var{c}}
14645 @item @code{void __SMASS (sw1, sw1)}
14646 @tab @code{__SMASS (@var{a}, @var{b})}
14647 @tab @code{SMASS @var{a},@var{b}}
14648 @item @code{void __SMSSS (sw1, sw1)}
14649 @tab @code{__SMSSS (@var{a}, @var{b})}
14650 @tab @code{SMSSS @var{a},@var{b}}
14651 @item @code{void __SMU (sw1, sw1)}
14652 @tab @code{__SMU (@var{a}, @var{b})}
14653 @tab @code{SMU @var{a},@var{b}}
14654 @item @code{sw2 __SMUL (sw1, sw1)}
14655 @tab @code{@var{c} = __SMUL (@var{a}, @var{b})}
14656 @tab @code{SMUL @var{a},@var{b},@var{c}}
14657 @item @code{sw1 __SUBSS (sw1, sw1)}
14658 @tab @code{@var{c} = __SUBSS (@var{a}, @var{b})}
14659 @tab @code{SUBSS @var{a},@var{b},@var{c}}
14660 @item @code{uw2 __UMUL (uw1, uw1)}
14661 @tab @code{@var{c} = __UMUL (@var{a}, @var{b})}
14662 @tab @code{UMUL @var{a},@var{b},@var{c}}
14665 @node Directly-mapped Media Functions
14666 @subsubsection Directly-Mapped Media Functions
14668 The functions listed below map directly to FR-V M-type instructions.
14670 @multitable @columnfractions .45 .32 .23
14671 @item Function prototype @tab Example usage @tab Assembly output
14672 @item @code{uw1 __MABSHS (sw1)}
14673 @tab @code{@var{b} = __MABSHS (@var{a})}
14674 @tab @code{MABSHS @var{a},@var{b}}
14675 @item @code{void __MADDACCS (acc, acc)}
14676 @tab @code{__MADDACCS (@var{b}, @var{a})}
14677 @tab @code{MADDACCS @var{a},@var{b}}
14678 @item @code{sw1 __MADDHSS (sw1, sw1)}
14679 @tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})}
14680 @tab @code{MADDHSS @var{a},@var{b},@var{c}}
14681 @item @code{uw1 __MADDHUS (uw1, uw1)}
14682 @tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})}
14683 @tab @code{MADDHUS @var{a},@var{b},@var{c}}
14684 @item @code{uw1 __MAND (uw1, uw1)}
14685 @tab @code{@var{c} = __MAND (@var{a}, @var{b})}
14686 @tab @code{MAND @var{a},@var{b},@var{c}}
14687 @item @code{void __MASACCS (acc, acc)}
14688 @tab @code{__MASACCS (@var{b}, @var{a})}
14689 @tab @code{MASACCS @var{a},@var{b}}
14690 @item @code{uw1 __MAVEH (uw1, uw1)}
14691 @tab @code{@var{c} = __MAVEH (@var{a}, @var{b})}
14692 @tab @code{MAVEH @var{a},@var{b},@var{c}}
14693 @item @code{uw2 __MBTOH (uw1)}
14694 @tab @code{@var{b} = __MBTOH (@var{a})}
14695 @tab @code{MBTOH @var{a},@var{b}}
14696 @item @code{void __MBTOHE (uw1 *, uw1)}
14697 @tab @code{__MBTOHE (&@var{b}, @var{a})}
14698 @tab @code{MBTOHE @var{a},@var{b}}
14699 @item @code{void __MCLRACC (acc)}
14700 @tab @code{__MCLRACC (@var{a})}
14701 @tab @code{MCLRACC @var{a}}
14702 @item @code{void __MCLRACCA (void)}
14703 @tab @code{__MCLRACCA ()}
14704 @tab @code{MCLRACCA}
14705 @item @code{uw1 __Mcop1 (uw1, uw1)}
14706 @tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})}
14707 @tab @code{Mcop1 @var{a},@var{b},@var{c}}
14708 @item @code{uw1 __Mcop2 (uw1, uw1)}
14709 @tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})}
14710 @tab @code{Mcop2 @var{a},@var{b},@var{c}}
14711 @item @code{uw1 __MCPLHI (uw2, const)}
14712 @tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})}
14713 @tab @code{MCPLHI @var{a},#@var{b},@var{c}}
14714 @item @code{uw1 __MCPLI (uw2, const)}
14715 @tab @code{@var{c} = __MCPLI (@var{a}, @var{b})}
14716 @tab @code{MCPLI @var{a},#@var{b},@var{c}}
14717 @item @code{void __MCPXIS (acc, sw1, sw1)}
14718 @tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})}
14719 @tab @code{MCPXIS @var{a},@var{b},@var{c}}
14720 @item @code{void __MCPXIU (acc, uw1, uw1)}
14721 @tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})}
14722 @tab @code{MCPXIU @var{a},@var{b},@var{c}}
14723 @item @code{void __MCPXRS (acc, sw1, sw1)}
14724 @tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})}
14725 @tab @code{MCPXRS @var{a},@var{b},@var{c}}
14726 @item @code{void __MCPXRU (acc, uw1, uw1)}
14727 @tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})}
14728 @tab @code{MCPXRU @var{a},@var{b},@var{c}}
14729 @item @code{uw1 __MCUT (acc, uw1)}
14730 @tab @code{@var{c} = __MCUT (@var{a}, @var{b})}
14731 @tab @code{MCUT @var{a},@var{b},@var{c}}
14732 @item @code{uw1 __MCUTSS (acc, sw1)}
14733 @tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})}
14734 @tab @code{MCUTSS @var{a},@var{b},@var{c}}
14735 @item @code{void __MDADDACCS (acc, acc)}
14736 @tab @code{__MDADDACCS (@var{b}, @var{a})}
14737 @tab @code{MDADDACCS @var{a},@var{b}}
14738 @item @code{void __MDASACCS (acc, acc)}
14739 @tab @code{__MDASACCS (@var{b}, @var{a})}
14740 @tab @code{MDASACCS @var{a},@var{b}}
14741 @item @code{uw2 __MDCUTSSI (acc, const)}
14742 @tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})}
14743 @tab @code{MDCUTSSI @var{a},#@var{b},@var{c}}
14744 @item @code{uw2 __MDPACKH (uw2, uw2)}
14745 @tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})}
14746 @tab @code{MDPACKH @var{a},@var{b},@var{c}}
14747 @item @code{uw2 __MDROTLI (uw2, const)}
14748 @tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})}
14749 @tab @code{MDROTLI @var{a},#@var{b},@var{c}}
14750 @item @code{void __MDSUBACCS (acc, acc)}
14751 @tab @code{__MDSUBACCS (@var{b}, @var{a})}
14752 @tab @code{MDSUBACCS @var{a},@var{b}}
14753 @item @code{void __MDUNPACKH (uw1 *, uw2)}
14754 @tab @code{__MDUNPACKH (&@var{b}, @var{a})}
14755 @tab @code{MDUNPACKH @var{a},@var{b}}
14756 @item @code{uw2 __MEXPDHD (uw1, const)}
14757 @tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})}
14758 @tab @code{MEXPDHD @var{a},#@var{b},@var{c}}
14759 @item @code{uw1 __MEXPDHW (uw1, const)}
14760 @tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})}
14761 @tab @code{MEXPDHW @var{a},#@var{b},@var{c}}
14762 @item @code{uw1 __MHDSETH (uw1, const)}
14763 @tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})}
14764 @tab @code{MHDSETH @var{a},#@var{b},@var{c}}
14765 @item @code{sw1 __MHDSETS (const)}
14766 @tab @code{@var{b} = __MHDSETS (@var{a})}
14767 @tab @code{MHDSETS #@var{a},@var{b}}
14768 @item @code{uw1 __MHSETHIH (uw1, const)}
14769 @tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})}
14770 @tab @code{MHSETHIH #@var{a},@var{b}}
14771 @item @code{sw1 __MHSETHIS (sw1, const)}
14772 @tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})}
14773 @tab @code{MHSETHIS #@var{a},@var{b}}
14774 @item @code{uw1 __MHSETLOH (uw1, const)}
14775 @tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})}
14776 @tab @code{MHSETLOH #@var{a},@var{b}}
14777 @item @code{sw1 __MHSETLOS (sw1, const)}
14778 @tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})}
14779 @tab @code{MHSETLOS #@var{a},@var{b}}
14780 @item @code{uw1 __MHTOB (uw2)}
14781 @tab @code{@var{b} = __MHTOB (@var{a})}
14782 @tab @code{MHTOB @var{a},@var{b}}
14783 @item @code{void __MMACHS (acc, sw1, sw1)}
14784 @tab @code{__MMACHS (@var{c}, @var{a}, @var{b})}
14785 @tab @code{MMACHS @var{a},@var{b},@var{c}}
14786 @item @code{void __MMACHU (acc, uw1, uw1)}
14787 @tab @code{__MMACHU (@var{c}, @var{a}, @var{b})}
14788 @tab @code{MMACHU @var{a},@var{b},@var{c}}
14789 @item @code{void __MMRDHS (acc, sw1, sw1)}
14790 @tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})}
14791 @tab @code{MMRDHS @var{a},@var{b},@var{c}}
14792 @item @code{void __MMRDHU (acc, uw1, uw1)}
14793 @tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})}
14794 @tab @code{MMRDHU @var{a},@var{b},@var{c}}
14795 @item @code{void __MMULHS (acc, sw1, sw1)}
14796 @tab @code{__MMULHS (@var{c}, @var{a}, @var{b})}
14797 @tab @code{MMULHS @var{a},@var{b},@var{c}}
14798 @item @code{void __MMULHU (acc, uw1, uw1)}
14799 @tab @code{__MMULHU (@var{c}, @var{a}, @var{b})}
14800 @tab @code{MMULHU @var{a},@var{b},@var{c}}
14801 @item @code{void __MMULXHS (acc, sw1, sw1)}
14802 @tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})}
14803 @tab @code{MMULXHS @var{a},@var{b},@var{c}}
14804 @item @code{void __MMULXHU (acc, uw1, uw1)}
14805 @tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})}
14806 @tab @code{MMULXHU @var{a},@var{b},@var{c}}
14807 @item @code{uw1 __MNOT (uw1)}
14808 @tab @code{@var{b} = __MNOT (@var{a})}
14809 @tab @code{MNOT @var{a},@var{b}}
14810 @item @code{uw1 __MOR (uw1, uw1)}
14811 @tab @code{@var{c} = __MOR (@var{a}, @var{b})}
14812 @tab @code{MOR @var{a},@var{b},@var{c}}
14813 @item @code{uw1 __MPACKH (uh, uh)}
14814 @tab @code{@var{c} = __MPACKH (@var{a}, @var{b})}
14815 @tab @code{MPACKH @var{a},@var{b},@var{c}}
14816 @item @code{sw2 __MQADDHSS (sw2, sw2)}
14817 @tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})}
14818 @tab @code{MQADDHSS @var{a},@var{b},@var{c}}
14819 @item @code{uw2 __MQADDHUS (uw2, uw2)}
14820 @tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})}
14821 @tab @code{MQADDHUS @var{a},@var{b},@var{c}}
14822 @item @code{void __MQCPXIS (acc, sw2, sw2)}
14823 @tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})}
14824 @tab @code{MQCPXIS @var{a},@var{b},@var{c}}
14825 @item @code{void __MQCPXIU (acc, uw2, uw2)}
14826 @tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})}
14827 @tab @code{MQCPXIU @var{a},@var{b},@var{c}}
14828 @item @code{void __MQCPXRS (acc, sw2, sw2)}
14829 @tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})}
14830 @tab @code{MQCPXRS @var{a},@var{b},@var{c}}
14831 @item @code{void __MQCPXRU (acc, uw2, uw2)}
14832 @tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})}
14833 @tab @code{MQCPXRU @var{a},@var{b},@var{c}}
14834 @item @code{sw2 __MQLCLRHS (sw2, sw2)}
14835 @tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})}
14836 @tab @code{MQLCLRHS @var{a},@var{b},@var{c}}
14837 @item @code{sw2 __MQLMTHS (sw2, sw2)}
14838 @tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})}
14839 @tab @code{MQLMTHS @var{a},@var{b},@var{c}}
14840 @item @code{void __MQMACHS (acc, sw2, sw2)}
14841 @tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})}
14842 @tab @code{MQMACHS @var{a},@var{b},@var{c}}
14843 @item @code{void __MQMACHU (acc, uw2, uw2)}
14844 @tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})}
14845 @tab @code{MQMACHU @var{a},@var{b},@var{c}}
14846 @item @code{void __MQMACXHS (acc, sw2, sw2)}
14847 @tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})}
14848 @tab @code{MQMACXHS @var{a},@var{b},@var{c}}
14849 @item @code{void __MQMULHS (acc, sw2, sw2)}
14850 @tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})}
14851 @tab @code{MQMULHS @var{a},@var{b},@var{c}}
14852 @item @code{void __MQMULHU (acc, uw2, uw2)}
14853 @tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})}
14854 @tab @code{MQMULHU @var{a},@var{b},@var{c}}
14855 @item @code{void __MQMULXHS (acc, sw2, sw2)}
14856 @tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})}
14857 @tab @code{MQMULXHS @var{a},@var{b},@var{c}}
14858 @item @code{void __MQMULXHU (acc, uw2, uw2)}
14859 @tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})}
14860 @tab @code{MQMULXHU @var{a},@var{b},@var{c}}
14861 @item @code{sw2 __MQSATHS (sw2, sw2)}
14862 @tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})}
14863 @tab @code{MQSATHS @var{a},@var{b},@var{c}}
14864 @item @code{uw2 __MQSLLHI (uw2, int)}
14865 @tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})}
14866 @tab @code{MQSLLHI @var{a},@var{b},@var{c}}
14867 @item @code{sw2 __MQSRAHI (sw2, int)}
14868 @tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})}
14869 @tab @code{MQSRAHI @var{a},@var{b},@var{c}}
14870 @item @code{sw2 __MQSUBHSS (sw2, sw2)}
14871 @tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})}
14872 @tab @code{MQSUBHSS @var{a},@var{b},@var{c}}
14873 @item @code{uw2 __MQSUBHUS (uw2, uw2)}
14874 @tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})}
14875 @tab @code{MQSUBHUS @var{a},@var{b},@var{c}}
14876 @item @code{void __MQXMACHS (acc, sw2, sw2)}
14877 @tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})}
14878 @tab @code{MQXMACHS @var{a},@var{b},@var{c}}
14879 @item @code{void __MQXMACXHS (acc, sw2, sw2)}
14880 @tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})}
14881 @tab @code{MQXMACXHS @var{a},@var{b},@var{c}}
14882 @item @code{uw1 __MRDACC (acc)}
14883 @tab @code{@var{b} = __MRDACC (@var{a})}
14884 @tab @code{MRDACC @var{a},@var{b}}
14885 @item @code{uw1 __MRDACCG (acc)}
14886 @tab @code{@var{b} = __MRDACCG (@var{a})}
14887 @tab @code{MRDACCG @var{a},@var{b}}
14888 @item @code{uw1 __MROTLI (uw1, const)}
14889 @tab @code{@var{c} = __MROTLI (@var{a}, @var{b})}
14890 @tab @code{MROTLI @var{a},#@var{b},@var{c}}
14891 @item @code{uw1 __MROTRI (uw1, const)}
14892 @tab @code{@var{c} = __MROTRI (@var{a}, @var{b})}
14893 @tab @code{MROTRI @var{a},#@var{b},@var{c}}
14894 @item @code{sw1 __MSATHS (sw1, sw1)}
14895 @tab @code{@var{c} = __MSATHS (@var{a}, @var{b})}
14896 @tab @code{MSATHS @var{a},@var{b},@var{c}}
14897 @item @code{uw1 __MSATHU (uw1, uw1)}
14898 @tab @code{@var{c} = __MSATHU (@var{a}, @var{b})}
14899 @tab @code{MSATHU @var{a},@var{b},@var{c}}
14900 @item @code{uw1 __MSLLHI (uw1, const)}
14901 @tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})}
14902 @tab @code{MSLLHI @var{a},#@var{b},@var{c}}
14903 @item @code{sw1 __MSRAHI (sw1, const)}
14904 @tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})}
14905 @tab @code{MSRAHI @var{a},#@var{b},@var{c}}
14906 @item @code{uw1 __MSRLHI (uw1, const)}
14907 @tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})}
14908 @tab @code{MSRLHI @var{a},#@var{b},@var{c}}
14909 @item @code{void __MSUBACCS (acc, acc)}
14910 @tab @code{__MSUBACCS (@var{b}, @var{a})}
14911 @tab @code{MSUBACCS @var{a},@var{b}}
14912 @item @code{sw1 __MSUBHSS (sw1, sw1)}
14913 @tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})}
14914 @tab @code{MSUBHSS @var{a},@var{b},@var{c}}
14915 @item @code{uw1 __MSUBHUS (uw1, uw1)}
14916 @tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})}
14917 @tab @code{MSUBHUS @var{a},@var{b},@var{c}}
14918 @item @code{void __MTRAP (void)}
14919 @tab @code{__MTRAP ()}
14921 @item @code{uw2 __MUNPACKH (uw1)}
14922 @tab @code{@var{b} = __MUNPACKH (@var{a})}
14923 @tab @code{MUNPACKH @var{a},@var{b}}
14924 @item @code{uw1 __MWCUT (uw2, uw1)}
14925 @tab @code{@var{c} = __MWCUT (@var{a}, @var{b})}
14926 @tab @code{MWCUT @var{a},@var{b},@var{c}}
14927 @item @code{void __MWTACC (acc, uw1)}
14928 @tab @code{__MWTACC (@var{b}, @var{a})}
14929 @tab @code{MWTACC @var{a},@var{b}}
14930 @item @code{void __MWTACCG (acc, uw1)}
14931 @tab @code{__MWTACCG (@var{b}, @var{a})}
14932 @tab @code{MWTACCG @var{a},@var{b}}
14933 @item @code{uw1 __MXOR (uw1, uw1)}
14934 @tab @code{@var{c} = __MXOR (@var{a}, @var{b})}
14935 @tab @code{MXOR @var{a},@var{b},@var{c}}
14938 @node Raw read/write Functions
14939 @subsubsection Raw Read/Write Functions
14941 This sections describes built-in functions related to read and write
14942 instructions to access memory. These functions generate
14943 @code{membar} instructions to flush the I/O load and stores where
14944 appropriate, as described in Fujitsu's manual described above.
14948 @item unsigned char __builtin_read8 (void *@var{data})
14949 @item unsigned short __builtin_read16 (void *@var{data})
14950 @item unsigned long __builtin_read32 (void *@var{data})
14951 @item unsigned long long __builtin_read64 (void *@var{data})
14953 @item void __builtin_write8 (void *@var{data}, unsigned char @var{datum})
14954 @item void __builtin_write16 (void *@var{data}, unsigned short @var{datum})
14955 @item void __builtin_write32 (void *@var{data}, unsigned long @var{datum})
14956 @item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum})
14959 @node Other Built-in Functions
14960 @subsubsection Other Built-in Functions
14962 This section describes built-in functions that are not named after
14963 a specific FR-V instruction.
14966 @item sw2 __IACCreadll (iacc @var{reg})
14967 Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved
14968 for future expansion and must be 0.
14970 @item sw1 __IACCreadl (iacc @var{reg})
14971 Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1.
14972 Other values of @var{reg} are rejected as invalid.
14974 @item void __IACCsetll (iacc @var{reg}, sw2 @var{x})
14975 Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument
14976 is reserved for future expansion and must be 0.
14978 @item void __IACCsetl (iacc @var{reg}, sw1 @var{x})
14979 Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg}
14980 is 1. Other values of @var{reg} are rejected as invalid.
14982 @item void __data_prefetch0 (const void *@var{x})
14983 Use the @code{dcpl} instruction to load the contents of address @var{x}
14984 into the data cache.
14986 @item void __data_prefetch (const void *@var{x})
14987 Use the @code{nldub} instruction to load the contents of address @var{x}
14988 into the data cache. The instruction is issued in slot I1@.
14991 @node MIPS DSP Built-in Functions
14992 @subsection MIPS DSP Built-in Functions
14994 The MIPS DSP Application-Specific Extension (ASE) includes new
14995 instructions that are designed to improve the performance of DSP and
14996 media applications. It provides instructions that operate on packed
14997 8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data.
14999 GCC supports MIPS DSP operations using both the generic
15000 vector extensions (@pxref{Vector Extensions}) and a collection of
15001 MIPS-specific built-in functions. Both kinds of support are
15002 enabled by the @option{-mdsp} command-line option.
15004 Revision 2 of the ASE was introduced in the second half of 2006.
15005 This revision adds extra instructions to the original ASE, but is
15006 otherwise backwards-compatible with it. You can select revision 2
15007 using the command-line option @option{-mdspr2}; this option implies
15010 The SCOUNT and POS bits of the DSP control register are global. The
15011 WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and
15012 POS bits. During optimization, the compiler does not delete these
15013 instructions and it does not delete calls to functions containing
15014 these instructions.
15016 At present, GCC only provides support for operations on 32-bit
15017 vectors. The vector type associated with 8-bit integer data is
15018 usually called @code{v4i8}, the vector type associated with Q7
15019 is usually called @code{v4q7}, the vector type associated with 16-bit
15020 integer data is usually called @code{v2i16}, and the vector type
15021 associated with Q15 is usually called @code{v2q15}. They can be
15022 defined in C as follows:
15025 typedef signed char v4i8 __attribute__ ((vector_size(4)));
15026 typedef signed char v4q7 __attribute__ ((vector_size(4)));
15027 typedef short v2i16 __attribute__ ((vector_size(4)));
15028 typedef short v2q15 __attribute__ ((vector_size(4)));
15031 @code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are
15032 initialized in the same way as aggregates. For example:
15035 v4i8 a = @{1, 2, 3, 4@};
15037 b = (v4i8) @{5, 6, 7, 8@};
15039 v2q15 c = @{0x0fcb, 0x3a75@};
15041 d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@};
15044 @emph{Note:} The CPU's endianness determines the order in which values
15045 are packed. On little-endian targets, the first value is the least
15046 significant and the last value is the most significant. The opposite
15047 order applies to big-endian targets. For example, the code above
15048 sets the lowest byte of @code{a} to @code{1} on little-endian targets
15049 and @code{4} on big-endian targets.
15051 @emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer
15052 representation. As shown in this example, the integer representation
15053 of a Q7 value can be obtained by multiplying the fractional value by
15054 @code{0x1.0p7}. The equivalent for Q15 values is to multiply by
15055 @code{0x1.0p15}. The equivalent for Q31 values is to multiply by
15058 The table below lists the @code{v4i8} and @code{v2q15} operations for which
15059 hardware support exists. @code{a} and @code{b} are @code{v4i8} values,
15060 and @code{c} and @code{d} are @code{v2q15} values.
15062 @multitable @columnfractions .50 .50
15063 @item C code @tab MIPS instruction
15064 @item @code{a + b} @tab @code{addu.qb}
15065 @item @code{c + d} @tab @code{addq.ph}
15066 @item @code{a - b} @tab @code{subu.qb}
15067 @item @code{c - d} @tab @code{subq.ph}
15070 The table below lists the @code{v2i16} operation for which
15071 hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are
15072 @code{v2i16} values.
15074 @multitable @columnfractions .50 .50
15075 @item C code @tab MIPS instruction
15076 @item @code{e * f} @tab @code{mul.ph}
15079 It is easier to describe the DSP built-in functions if we first define
15080 the following types:
15085 typedef unsigned int ui32;
15086 typedef long long a64;
15089 @code{q31} and @code{i32} are actually the same as @code{int}, but we
15090 use @code{q31} to indicate a Q31 fractional value and @code{i32} to
15091 indicate a 32-bit integer value. Similarly, @code{a64} is the same as
15092 @code{long long}, but we use @code{a64} to indicate values that are
15093 placed in one of the four DSP accumulators (@code{$ac0},
15094 @code{$ac1}, @code{$ac2} or @code{$ac3}).
15096 Also, some built-in functions prefer or require immediate numbers as
15097 parameters, because the corresponding DSP instructions accept both immediate
15098 numbers and register operands, or accept immediate numbers only. The
15099 immediate parameters are listed as follows.
15107 imm0_255: 0 to 255.
15108 imm_n32_31: -32 to 31.
15109 imm_n512_511: -512 to 511.
15112 The following built-in functions map directly to a particular MIPS DSP
15113 instruction. Please refer to the architecture specification
15114 for details on what each instruction does.
15117 v2q15 __builtin_mips_addq_ph (v2q15, v2q15)
15118 v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15)
15119 q31 __builtin_mips_addq_s_w (q31, q31)
15120 v4i8 __builtin_mips_addu_qb (v4i8, v4i8)
15121 v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8)
15122 v2q15 __builtin_mips_subq_ph (v2q15, v2q15)
15123 v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15)
15124 q31 __builtin_mips_subq_s_w (q31, q31)
15125 v4i8 __builtin_mips_subu_qb (v4i8, v4i8)
15126 v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8)
15127 i32 __builtin_mips_addsc (i32, i32)
15128 i32 __builtin_mips_addwc (i32, i32)
15129 i32 __builtin_mips_modsub (i32, i32)
15130 i32 __builtin_mips_raddu_w_qb (v4i8)
15131 v2q15 __builtin_mips_absq_s_ph (v2q15)
15132 q31 __builtin_mips_absq_s_w (q31)
15133 v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15)
15134 v2q15 __builtin_mips_precrq_ph_w (q31, q31)
15135 v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31)
15136 v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15)
15137 q31 __builtin_mips_preceq_w_phl (v2q15)
15138 q31 __builtin_mips_preceq_w_phr (v2q15)
15139 v2q15 __builtin_mips_precequ_ph_qbl (v4i8)
15140 v2q15 __builtin_mips_precequ_ph_qbr (v4i8)
15141 v2q15 __builtin_mips_precequ_ph_qbla (v4i8)
15142 v2q15 __builtin_mips_precequ_ph_qbra (v4i8)
15143 v2q15 __builtin_mips_preceu_ph_qbl (v4i8)
15144 v2q15 __builtin_mips_preceu_ph_qbr (v4i8)
15145 v2q15 __builtin_mips_preceu_ph_qbla (v4i8)
15146 v2q15 __builtin_mips_preceu_ph_qbra (v4i8)
15147 v4i8 __builtin_mips_shll_qb (v4i8, imm0_7)
15148 v4i8 __builtin_mips_shll_qb (v4i8, i32)
15149 v2q15 __builtin_mips_shll_ph (v2q15, imm0_15)
15150 v2q15 __builtin_mips_shll_ph (v2q15, i32)
15151 v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15)
15152 v2q15 __builtin_mips_shll_s_ph (v2q15, i32)
15153 q31 __builtin_mips_shll_s_w (q31, imm0_31)
15154 q31 __builtin_mips_shll_s_w (q31, i32)
15155 v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7)
15156 v4i8 __builtin_mips_shrl_qb (v4i8, i32)
15157 v2q15 __builtin_mips_shra_ph (v2q15, imm0_15)
15158 v2q15 __builtin_mips_shra_ph (v2q15, i32)
15159 v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15)
15160 v2q15 __builtin_mips_shra_r_ph (v2q15, i32)
15161 q31 __builtin_mips_shra_r_w (q31, imm0_31)
15162 q31 __builtin_mips_shra_r_w (q31, i32)
15163 v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15)
15164 v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15)
15165 v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15)
15166 q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15)
15167 q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15)
15168 a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8)
15169 a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8)
15170 a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8)
15171 a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8)
15172 a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15)
15173 a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31)
15174 a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15)
15175 a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31)
15176 a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15)
15177 a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15)
15178 a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15)
15179 a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15)
15180 a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15)
15181 i32 __builtin_mips_bitrev (i32)
15182 i32 __builtin_mips_insv (i32, i32)
15183 v4i8 __builtin_mips_repl_qb (imm0_255)
15184 v4i8 __builtin_mips_repl_qb (i32)
15185 v2q15 __builtin_mips_repl_ph (imm_n512_511)
15186 v2q15 __builtin_mips_repl_ph (i32)
15187 void __builtin_mips_cmpu_eq_qb (v4i8, v4i8)
15188 void __builtin_mips_cmpu_lt_qb (v4i8, v4i8)
15189 void __builtin_mips_cmpu_le_qb (v4i8, v4i8)
15190 i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8)
15191 i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8)
15192 i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8)
15193 void __builtin_mips_cmp_eq_ph (v2q15, v2q15)
15194 void __builtin_mips_cmp_lt_ph (v2q15, v2q15)
15195 void __builtin_mips_cmp_le_ph (v2q15, v2q15)
15196 v4i8 __builtin_mips_pick_qb (v4i8, v4i8)
15197 v2q15 __builtin_mips_pick_ph (v2q15, v2q15)
15198 v2q15 __builtin_mips_packrl_ph (v2q15, v2q15)
15199 i32 __builtin_mips_extr_w (a64, imm0_31)
15200 i32 __builtin_mips_extr_w (a64, i32)
15201 i32 __builtin_mips_extr_r_w (a64, imm0_31)
15202 i32 __builtin_mips_extr_s_h (a64, i32)
15203 i32 __builtin_mips_extr_rs_w (a64, imm0_31)
15204 i32 __builtin_mips_extr_rs_w (a64, i32)
15205 i32 __builtin_mips_extr_s_h (a64, imm0_31)
15206 i32 __builtin_mips_extr_r_w (a64, i32)
15207 i32 __builtin_mips_extp (a64, imm0_31)
15208 i32 __builtin_mips_extp (a64, i32)
15209 i32 __builtin_mips_extpdp (a64, imm0_31)
15210 i32 __builtin_mips_extpdp (a64, i32)
15211 a64 __builtin_mips_shilo (a64, imm_n32_31)
15212 a64 __builtin_mips_shilo (a64, i32)
15213 a64 __builtin_mips_mthlip (a64, i32)
15214 void __builtin_mips_wrdsp (i32, imm0_63)
15215 i32 __builtin_mips_rddsp (imm0_63)
15216 i32 __builtin_mips_lbux (void *, i32)
15217 i32 __builtin_mips_lhx (void *, i32)
15218 i32 __builtin_mips_lwx (void *, i32)
15219 a64 __builtin_mips_ldx (void *, i32) [MIPS64 only]
15220 i32 __builtin_mips_bposge32 (void)
15221 a64 __builtin_mips_madd (a64, i32, i32);
15222 a64 __builtin_mips_maddu (a64, ui32, ui32);
15223 a64 __builtin_mips_msub (a64, i32, i32);
15224 a64 __builtin_mips_msubu (a64, ui32, ui32);
15225 a64 __builtin_mips_mult (i32, i32);
15226 a64 __builtin_mips_multu (ui32, ui32);
15229 The following built-in functions map directly to a particular MIPS DSP REV 2
15230 instruction. Please refer to the architecture specification
15231 for details on what each instruction does.
15234 v4q7 __builtin_mips_absq_s_qb (v4q7);
15235 v2i16 __builtin_mips_addu_ph (v2i16, v2i16);
15236 v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16);
15237 v4i8 __builtin_mips_adduh_qb (v4i8, v4i8);
15238 v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8);
15239 i32 __builtin_mips_append (i32, i32, imm0_31);
15240 i32 __builtin_mips_balign (i32, i32, imm0_3);
15241 i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8);
15242 i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8);
15243 i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8);
15244 a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16);
15245 a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16);
15246 v2i16 __builtin_mips_mul_ph (v2i16, v2i16);
15247 v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16);
15248 q31 __builtin_mips_mulq_rs_w (q31, q31);
15249 v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15);
15250 q31 __builtin_mips_mulq_s_w (q31, q31);
15251 a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16);
15252 v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16);
15253 v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31);
15254 v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31);
15255 i32 __builtin_mips_prepend (i32, i32, imm0_31);
15256 v4i8 __builtin_mips_shra_qb (v4i8, imm0_7);
15257 v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7);
15258 v4i8 __builtin_mips_shra_qb (v4i8, i32);
15259 v4i8 __builtin_mips_shra_r_qb (v4i8, i32);
15260 v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15);
15261 v2i16 __builtin_mips_shrl_ph (v2i16, i32);
15262 v2i16 __builtin_mips_subu_ph (v2i16, v2i16);
15263 v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16);
15264 v4i8 __builtin_mips_subuh_qb (v4i8, v4i8);
15265 v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8);
15266 v2q15 __builtin_mips_addqh_ph (v2q15, v2q15);
15267 v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15);
15268 q31 __builtin_mips_addqh_w (q31, q31);
15269 q31 __builtin_mips_addqh_r_w (q31, q31);
15270 v2q15 __builtin_mips_subqh_ph (v2q15, v2q15);
15271 v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15);
15272 q31 __builtin_mips_subqh_w (q31, q31);
15273 q31 __builtin_mips_subqh_r_w (q31, q31);
15274 a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16);
15275 a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16);
15276 a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15);
15277 a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15);
15278 a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15);
15279 a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15);
15283 @node MIPS Paired-Single Support
15284 @subsection MIPS Paired-Single Support
15286 The MIPS64 architecture includes a number of instructions that
15287 operate on pairs of single-precision floating-point values.
15288 Each pair is packed into a 64-bit floating-point register,
15289 with one element being designated the ``upper half'' and
15290 the other being designated the ``lower half''.
15292 GCC supports paired-single operations using both the generic
15293 vector extensions (@pxref{Vector Extensions}) and a collection of
15294 MIPS-specific built-in functions. Both kinds of support are
15295 enabled by the @option{-mpaired-single} command-line option.
15297 The vector type associated with paired-single values is usually
15298 called @code{v2sf}. It can be defined in C as follows:
15301 typedef float v2sf __attribute__ ((vector_size (8)));
15304 @code{v2sf} values are initialized in the same way as aggregates.
15308 v2sf a = @{1.5, 9.1@};
15311 b = (v2sf) @{e, f@};
15314 @emph{Note:} The CPU's endianness determines which value is stored in
15315 the upper half of a register and which value is stored in the lower half.
15316 On little-endian targets, the first value is the lower one and the second
15317 value is the upper one. The opposite order applies to big-endian targets.
15318 For example, the code above sets the lower half of @code{a} to
15319 @code{1.5} on little-endian targets and @code{9.1} on big-endian targets.
15321 @node MIPS Loongson Built-in Functions
15322 @subsection MIPS Loongson Built-in Functions
15324 GCC provides intrinsics to access the SIMD instructions provided by the
15325 ST Microelectronics Loongson-2E and -2F processors. These intrinsics,
15326 available after inclusion of the @code{loongson.h} header file,
15327 operate on the following 64-bit vector types:
15330 @item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers;
15331 @item @code{uint16x4_t}, a vector of four unsigned 16-bit integers;
15332 @item @code{uint32x2_t}, a vector of two unsigned 32-bit integers;
15333 @item @code{int8x8_t}, a vector of eight signed 8-bit integers;
15334 @item @code{int16x4_t}, a vector of four signed 16-bit integers;
15335 @item @code{int32x2_t}, a vector of two signed 32-bit integers.
15338 The intrinsics provided are listed below; each is named after the
15339 machine instruction to which it corresponds, with suffixes added as
15340 appropriate to distinguish intrinsics that expand to the same machine
15341 instruction yet have different argument types. Refer to the architecture
15342 documentation for a description of the functionality of each
15346 int16x4_t packsswh (int32x2_t s, int32x2_t t);
15347 int8x8_t packsshb (int16x4_t s, int16x4_t t);
15348 uint8x8_t packushb (uint16x4_t s, uint16x4_t t);
15349 uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t);
15350 uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t);
15351 uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t);
15352 int32x2_t paddw_s (int32x2_t s, int32x2_t t);
15353 int16x4_t paddh_s (int16x4_t s, int16x4_t t);
15354 int8x8_t paddb_s (int8x8_t s, int8x8_t t);
15355 uint64_t paddd_u (uint64_t s, uint64_t t);
15356 int64_t paddd_s (int64_t s, int64_t t);
15357 int16x4_t paddsh (int16x4_t s, int16x4_t t);
15358 int8x8_t paddsb (int8x8_t s, int8x8_t t);
15359 uint16x4_t paddush (uint16x4_t s, uint16x4_t t);
15360 uint8x8_t paddusb (uint8x8_t s, uint8x8_t t);
15361 uint64_t pandn_ud (uint64_t s, uint64_t t);
15362 uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t);
15363 uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t);
15364 uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t);
15365 int64_t pandn_sd (int64_t s, int64_t t);
15366 int32x2_t pandn_sw (int32x2_t s, int32x2_t t);
15367 int16x4_t pandn_sh (int16x4_t s, int16x4_t t);
15368 int8x8_t pandn_sb (int8x8_t s, int8x8_t t);
15369 uint16x4_t pavgh (uint16x4_t s, uint16x4_t t);
15370 uint8x8_t pavgb (uint8x8_t s, uint8x8_t t);
15371 uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t);
15372 uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t);
15373 uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t);
15374 int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t);
15375 int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t);
15376 int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t);
15377 uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t);
15378 uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t);
15379 uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t);
15380 int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t);
15381 int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t);
15382 int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t);
15383 uint16x4_t pextrh_u (uint16x4_t s, int field);
15384 int16x4_t pextrh_s (int16x4_t s, int field);
15385 uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t);
15386 uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t);
15387 uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t);
15388 uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t);
15389 int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t);
15390 int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t);
15391 int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t);
15392 int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t);
15393 int32x2_t pmaddhw (int16x4_t s, int16x4_t t);
15394 int16x4_t pmaxsh (int16x4_t s, int16x4_t t);
15395 uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t);
15396 int16x4_t pminsh (int16x4_t s, int16x4_t t);
15397 uint8x8_t pminub (uint8x8_t s, uint8x8_t t);
15398 uint8x8_t pmovmskb_u (uint8x8_t s);
15399 int8x8_t pmovmskb_s (int8x8_t s);
15400 uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t);
15401 int16x4_t pmulhh (int16x4_t s, int16x4_t t);
15402 int16x4_t pmullh (int16x4_t s, int16x4_t t);
15403 int64_t pmuluw (uint32x2_t s, uint32x2_t t);
15404 uint8x8_t pasubub (uint8x8_t s, uint8x8_t t);
15405 uint16x4_t biadd (uint8x8_t s);
15406 uint16x4_t psadbh (uint8x8_t s, uint8x8_t t);
15407 uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order);
15408 int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order);
15409 uint16x4_t psllh_u (uint16x4_t s, uint8_t amount);
15410 int16x4_t psllh_s (int16x4_t s, uint8_t amount);
15411 uint32x2_t psllw_u (uint32x2_t s, uint8_t amount);
15412 int32x2_t psllw_s (int32x2_t s, uint8_t amount);
15413 uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount);
15414 int16x4_t psrlh_s (int16x4_t s, uint8_t amount);
15415 uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount);
15416 int32x2_t psrlw_s (int32x2_t s, uint8_t amount);
15417 uint16x4_t psrah_u (uint16x4_t s, uint8_t amount);
15418 int16x4_t psrah_s (int16x4_t s, uint8_t amount);
15419 uint32x2_t psraw_u (uint32x2_t s, uint8_t amount);
15420 int32x2_t psraw_s (int32x2_t s, uint8_t amount);
15421 uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t);
15422 uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t);
15423 uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t);
15424 int32x2_t psubw_s (int32x2_t s, int32x2_t t);
15425 int16x4_t psubh_s (int16x4_t s, int16x4_t t);
15426 int8x8_t psubb_s (int8x8_t s, int8x8_t t);
15427 uint64_t psubd_u (uint64_t s, uint64_t t);
15428 int64_t psubd_s (int64_t s, int64_t t);
15429 int16x4_t psubsh (int16x4_t s, int16x4_t t);
15430 int8x8_t psubsb (int8x8_t s, int8x8_t t);
15431 uint16x4_t psubush (uint16x4_t s, uint16x4_t t);
15432 uint8x8_t psubusb (uint8x8_t s, uint8x8_t t);
15433 uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t);
15434 uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t);
15435 uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t);
15436 int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t);
15437 int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t);
15438 int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t);
15439 uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t);
15440 uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t);
15441 uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t);
15442 int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t);
15443 int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t);
15444 int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t);
15448 * Paired-Single Arithmetic::
15449 * Paired-Single Built-in Functions::
15450 * MIPS-3D Built-in Functions::
15453 @node Paired-Single Arithmetic
15454 @subsubsection Paired-Single Arithmetic
15456 The table below lists the @code{v2sf} operations for which hardware
15457 support exists. @code{a}, @code{b} and @code{c} are @code{v2sf}
15458 values and @code{x} is an integral value.
15460 @multitable @columnfractions .50 .50
15461 @item C code @tab MIPS instruction
15462 @item @code{a + b} @tab @code{add.ps}
15463 @item @code{a - b} @tab @code{sub.ps}
15464 @item @code{-a} @tab @code{neg.ps}
15465 @item @code{a * b} @tab @code{mul.ps}
15466 @item @code{a * b + c} @tab @code{madd.ps}
15467 @item @code{a * b - c} @tab @code{msub.ps}
15468 @item @code{-(a * b + c)} @tab @code{nmadd.ps}
15469 @item @code{-(a * b - c)} @tab @code{nmsub.ps}
15470 @item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps}
15473 Note that the multiply-accumulate instructions can be disabled
15474 using the command-line option @code{-mno-fused-madd}.
15476 @node Paired-Single Built-in Functions
15477 @subsubsection Paired-Single Built-in Functions
15479 The following paired-single functions map directly to a particular
15480 MIPS instruction. Please refer to the architecture specification
15481 for details on what each instruction does.
15484 @item v2sf __builtin_mips_pll_ps (v2sf, v2sf)
15485 Pair lower lower (@code{pll.ps}).
15487 @item v2sf __builtin_mips_pul_ps (v2sf, v2sf)
15488 Pair upper lower (@code{pul.ps}).
15490 @item v2sf __builtin_mips_plu_ps (v2sf, v2sf)
15491 Pair lower upper (@code{plu.ps}).
15493 @item v2sf __builtin_mips_puu_ps (v2sf, v2sf)
15494 Pair upper upper (@code{puu.ps}).
15496 @item v2sf __builtin_mips_cvt_ps_s (float, float)
15497 Convert pair to paired single (@code{cvt.ps.s}).
15499 @item float __builtin_mips_cvt_s_pl (v2sf)
15500 Convert pair lower to single (@code{cvt.s.pl}).
15502 @item float __builtin_mips_cvt_s_pu (v2sf)
15503 Convert pair upper to single (@code{cvt.s.pu}).
15505 @item v2sf __builtin_mips_abs_ps (v2sf)
15506 Absolute value (@code{abs.ps}).
15508 @item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int)
15509 Align variable (@code{alnv.ps}).
15511 @emph{Note:} The value of the third parameter must be 0 or 4
15512 modulo 8, otherwise the result is unpredictable. Please read the
15513 instruction description for details.
15516 The following multi-instruction functions are also available.
15517 In each case, @var{cond} can be any of the 16 floating-point conditions:
15518 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
15519 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl},
15520 @code{lt}, @code{nge}, @code{le} or @code{ngt}.
15523 @item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15524 @itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15525 Conditional move based on floating-point comparison (@code{c.@var{cond}.ps},
15526 @code{movt.ps}/@code{movf.ps}).
15528 The @code{movt} functions return the value @var{x} computed by:
15531 c.@var{cond}.ps @var{cc},@var{a},@var{b}
15532 mov.ps @var{x},@var{c}
15533 movt.ps @var{x},@var{d},@var{cc}
15536 The @code{movf} functions are similar but use @code{movf.ps} instead
15539 @item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15540 @itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15541 Comparison of two paired-single values (@code{c.@var{cond}.ps},
15542 @code{bc1t}/@code{bc1f}).
15544 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
15545 and return either the upper or lower half of the result. For example:
15549 if (__builtin_mips_upper_c_eq_ps (a, b))
15550 upper_halves_are_equal ();
15552 upper_halves_are_unequal ();
15554 if (__builtin_mips_lower_c_eq_ps (a, b))
15555 lower_halves_are_equal ();
15557 lower_halves_are_unequal ();
15561 @node MIPS-3D Built-in Functions
15562 @subsubsection MIPS-3D Built-in Functions
15564 The MIPS-3D Application-Specific Extension (ASE) includes additional
15565 paired-single instructions that are designed to improve the performance
15566 of 3D graphics operations. Support for these instructions is controlled
15567 by the @option{-mips3d} command-line option.
15569 The functions listed below map directly to a particular MIPS-3D
15570 instruction. Please refer to the architecture specification for
15571 more details on what each instruction does.
15574 @item v2sf __builtin_mips_addr_ps (v2sf, v2sf)
15575 Reduction add (@code{addr.ps}).
15577 @item v2sf __builtin_mips_mulr_ps (v2sf, v2sf)
15578 Reduction multiply (@code{mulr.ps}).
15580 @item v2sf __builtin_mips_cvt_pw_ps (v2sf)
15581 Convert paired single to paired word (@code{cvt.pw.ps}).
15583 @item v2sf __builtin_mips_cvt_ps_pw (v2sf)
15584 Convert paired word to paired single (@code{cvt.ps.pw}).
15586 @item float __builtin_mips_recip1_s (float)
15587 @itemx double __builtin_mips_recip1_d (double)
15588 @itemx v2sf __builtin_mips_recip1_ps (v2sf)
15589 Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}).
15591 @item float __builtin_mips_recip2_s (float, float)
15592 @itemx double __builtin_mips_recip2_d (double, double)
15593 @itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf)
15594 Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}).
15596 @item float __builtin_mips_rsqrt1_s (float)
15597 @itemx double __builtin_mips_rsqrt1_d (double)
15598 @itemx v2sf __builtin_mips_rsqrt1_ps (v2sf)
15599 Reduced-precision reciprocal square root (sequence step 1)
15600 (@code{rsqrt1.@var{fmt}}).
15602 @item float __builtin_mips_rsqrt2_s (float, float)
15603 @itemx double __builtin_mips_rsqrt2_d (double, double)
15604 @itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf)
15605 Reduced-precision reciprocal square root (sequence step 2)
15606 (@code{rsqrt2.@var{fmt}}).
15609 The following multi-instruction functions are also available.
15610 In each case, @var{cond} can be any of the 16 floating-point conditions:
15611 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
15612 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq},
15613 @code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}.
15616 @item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b})
15617 @itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b})
15618 Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}},
15619 @code{bc1t}/@code{bc1f}).
15621 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s}
15622 or @code{cabs.@var{cond}.d} and return the result as a boolean value.
15627 if (__builtin_mips_cabs_eq_s (a, b))
15633 @item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15634 @itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15635 Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps},
15636 @code{bc1t}/@code{bc1f}).
15638 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps}
15639 and return either the upper or lower half of the result. For example:
15643 if (__builtin_mips_upper_cabs_eq_ps (a, b))
15644 upper_halves_are_equal ();
15646 upper_halves_are_unequal ();
15648 if (__builtin_mips_lower_cabs_eq_ps (a, b))
15649 lower_halves_are_equal ();
15651 lower_halves_are_unequal ();
15654 @item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15655 @itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15656 Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps},
15657 @code{movt.ps}/@code{movf.ps}).
15659 The @code{movt} functions return the value @var{x} computed by:
15662 cabs.@var{cond}.ps @var{cc},@var{a},@var{b}
15663 mov.ps @var{x},@var{c}
15664 movt.ps @var{x},@var{d},@var{cc}
15667 The @code{movf} functions are similar but use @code{movf.ps} instead
15670 @item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15671 @itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15672 @itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15673 @itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15674 Comparison of two paired-single values
15675 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
15676 @code{bc1any2t}/@code{bc1any2f}).
15678 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
15679 or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either
15680 result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}.
15685 if (__builtin_mips_any_c_eq_ps (a, b))
15690 if (__builtin_mips_all_c_eq_ps (a, b))
15696 @item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15697 @itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15698 @itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15699 @itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15700 Comparison of four paired-single values
15701 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
15702 @code{bc1any4t}/@code{bc1any4f}).
15704 These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps}
15705 to compare @var{a} with @var{b} and to compare @var{c} with @var{d}.
15706 The @code{any} forms return @code{true} if any of the four results are @code{true}
15707 and the @code{all} forms return @code{true} if all four results are @code{true}.
15712 if (__builtin_mips_any_c_eq_4s (a, b, c, d))
15717 if (__builtin_mips_all_c_eq_4s (a, b, c, d))
15724 @node MIPS SIMD Architecture (MSA) Support
15725 @subsection MIPS SIMD Architecture (MSA) Support
15728 * MIPS SIMD Architecture Built-in Functions::
15731 GCC provides intrinsics to access the SIMD instructions provided by the
15732 MSA MIPS SIMD Architecture. The interface is made available by including
15733 @code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}.
15734 For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic,
15737 MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and
15738 64-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point
15739 data elements. The following vectors typedefs are included in @code{msa.h}:
15741 @item @code{v16i8}, a vector of sixteen signed 8-bit integers;
15742 @item @code{v16u8}, a vector of sixteen unsigned 8-bit integers;
15743 @item @code{v8i16}, a vector of eight signed 16-bit integers;
15744 @item @code{v8u16}, a vector of eight unsigned 16-bit integers;
15745 @item @code{v4i32}, a vector of four signed 32-bit integers;
15746 @item @code{v4u32}, a vector of four unsigned 32-bit integers;
15747 @item @code{v2i64}, a vector of two signed 64-bit integers;
15748 @item @code{v2u64}, a vector of two unsigned 64-bit integers;
15749 @item @code{v4f32}, a vector of four 32-bit floats;
15750 @item @code{v2f64}, a vector of two 64-bit doubles.
15753 Instructions and corresponding built-ins may have additional restrictions and/or
15754 input/output values manipulated:
15756 @item @code{imm0_1}, an integer literal in range 0 to 1;
15757 @item @code{imm0_3}, an integer literal in range 0 to 3;
15758 @item @code{imm0_7}, an integer literal in range 0 to 7;
15759 @item @code{imm0_15}, an integer literal in range 0 to 15;
15760 @item @code{imm0_31}, an integer literal in range 0 to 31;
15761 @item @code{imm0_63}, an integer literal in range 0 to 63;
15762 @item @code{imm0_255}, an integer literal in range 0 to 255;
15763 @item @code{imm_n16_15}, an integer literal in range -16 to 15;
15764 @item @code{imm_n512_511}, an integer literal in range -512 to 511;
15765 @item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left
15766 shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022;
15767 @item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left
15768 shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044;
15769 @item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left
15770 shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088;
15771 @item @code{imm1_4}, an integer literal in range 1 to 4;
15772 @item @code{i32, i64, u32, u64, f32, f64}, defined as follows:
15778 #if __LONG_MAX__ == __LONG_LONG_MAX__
15781 typedef long long i64;
15784 typedef unsigned int u32;
15785 #if __LONG_MAX__ == __LONG_LONG_MAX__
15786 typedef unsigned long u64;
15788 typedef unsigned long long u64;
15791 typedef double f64;
15796 @node MIPS SIMD Architecture Built-in Functions
15797 @subsubsection MIPS SIMD Architecture Built-in Functions
15799 The intrinsics provided are listed below; each is named after the
15800 machine instruction.
15803 v16i8 __builtin_msa_add_a_b (v16i8, v16i8);
15804 v8i16 __builtin_msa_add_a_h (v8i16, v8i16);
15805 v4i32 __builtin_msa_add_a_w (v4i32, v4i32);
15806 v2i64 __builtin_msa_add_a_d (v2i64, v2i64);
15808 v16i8 __builtin_msa_adds_a_b (v16i8, v16i8);
15809 v8i16 __builtin_msa_adds_a_h (v8i16, v8i16);
15810 v4i32 __builtin_msa_adds_a_w (v4i32, v4i32);
15811 v2i64 __builtin_msa_adds_a_d (v2i64, v2i64);
15813 v16i8 __builtin_msa_adds_s_b (v16i8, v16i8);
15814 v8i16 __builtin_msa_adds_s_h (v8i16, v8i16);
15815 v4i32 __builtin_msa_adds_s_w (v4i32, v4i32);
15816 v2i64 __builtin_msa_adds_s_d (v2i64, v2i64);
15818 v16u8 __builtin_msa_adds_u_b (v16u8, v16u8);
15819 v8u16 __builtin_msa_adds_u_h (v8u16, v8u16);
15820 v4u32 __builtin_msa_adds_u_w (v4u32, v4u32);
15821 v2u64 __builtin_msa_adds_u_d (v2u64, v2u64);
15823 v16i8 __builtin_msa_addv_b (v16i8, v16i8);
15824 v8i16 __builtin_msa_addv_h (v8i16, v8i16);
15825 v4i32 __builtin_msa_addv_w (v4i32, v4i32);
15826 v2i64 __builtin_msa_addv_d (v2i64, v2i64);
15828 v16i8 __builtin_msa_addvi_b (v16i8, imm0_31);
15829 v8i16 __builtin_msa_addvi_h (v8i16, imm0_31);
15830 v4i32 __builtin_msa_addvi_w (v4i32, imm0_31);
15831 v2i64 __builtin_msa_addvi_d (v2i64, imm0_31);
15833 v16u8 __builtin_msa_and_v (v16u8, v16u8);
15835 v16u8 __builtin_msa_andi_b (v16u8, imm0_255);
15837 v16i8 __builtin_msa_asub_s_b (v16i8, v16i8);
15838 v8i16 __builtin_msa_asub_s_h (v8i16, v8i16);
15839 v4i32 __builtin_msa_asub_s_w (v4i32, v4i32);
15840 v2i64 __builtin_msa_asub_s_d (v2i64, v2i64);
15842 v16u8 __builtin_msa_asub_u_b (v16u8, v16u8);
15843 v8u16 __builtin_msa_asub_u_h (v8u16, v8u16);
15844 v4u32 __builtin_msa_asub_u_w (v4u32, v4u32);
15845 v2u64 __builtin_msa_asub_u_d (v2u64, v2u64);
15847 v16i8 __builtin_msa_ave_s_b (v16i8, v16i8);
15848 v8i16 __builtin_msa_ave_s_h (v8i16, v8i16);
15849 v4i32 __builtin_msa_ave_s_w (v4i32, v4i32);
15850 v2i64 __builtin_msa_ave_s_d (v2i64, v2i64);
15852 v16u8 __builtin_msa_ave_u_b (v16u8, v16u8);
15853 v8u16 __builtin_msa_ave_u_h (v8u16, v8u16);
15854 v4u32 __builtin_msa_ave_u_w (v4u32, v4u32);
15855 v2u64 __builtin_msa_ave_u_d (v2u64, v2u64);
15857 v16i8 __builtin_msa_aver_s_b (v16i8, v16i8);
15858 v8i16 __builtin_msa_aver_s_h (v8i16, v8i16);
15859 v4i32 __builtin_msa_aver_s_w (v4i32, v4i32);
15860 v2i64 __builtin_msa_aver_s_d (v2i64, v2i64);
15862 v16u8 __builtin_msa_aver_u_b (v16u8, v16u8);
15863 v8u16 __builtin_msa_aver_u_h (v8u16, v8u16);
15864 v4u32 __builtin_msa_aver_u_w (v4u32, v4u32);
15865 v2u64 __builtin_msa_aver_u_d (v2u64, v2u64);
15867 v16u8 __builtin_msa_bclr_b (v16u8, v16u8);
15868 v8u16 __builtin_msa_bclr_h (v8u16, v8u16);
15869 v4u32 __builtin_msa_bclr_w (v4u32, v4u32);
15870 v2u64 __builtin_msa_bclr_d (v2u64, v2u64);
15872 v16u8 __builtin_msa_bclri_b (v16u8, imm0_7);
15873 v8u16 __builtin_msa_bclri_h (v8u16, imm0_15);
15874 v4u32 __builtin_msa_bclri_w (v4u32, imm0_31);
15875 v2u64 __builtin_msa_bclri_d (v2u64, imm0_63);
15877 v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8);
15878 v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16);
15879 v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32);
15880 v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64);
15882 v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7);
15883 v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15);
15884 v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31);
15885 v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63);
15887 v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8);
15888 v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16);
15889 v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32);
15890 v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64);
15892 v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7);
15893 v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15);
15894 v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31);
15895 v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63);
15897 v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8);
15899 v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255);
15901 v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8);
15903 v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255);
15905 v16u8 __builtin_msa_bneg_b (v16u8, v16u8);
15906 v8u16 __builtin_msa_bneg_h (v8u16, v8u16);
15907 v4u32 __builtin_msa_bneg_w (v4u32, v4u32);
15908 v2u64 __builtin_msa_bneg_d (v2u64, v2u64);
15910 v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7);
15911 v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15);
15912 v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31);
15913 v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63);
15915 i32 __builtin_msa_bnz_b (v16u8);
15916 i32 __builtin_msa_bnz_h (v8u16);
15917 i32 __builtin_msa_bnz_w (v4u32);
15918 i32 __builtin_msa_bnz_d (v2u64);
15920 i32 __builtin_msa_bnz_v (v16u8);
15922 v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8);
15924 v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255);
15926 v16u8 __builtin_msa_bset_b (v16u8, v16u8);
15927 v8u16 __builtin_msa_bset_h (v8u16, v8u16);
15928 v4u32 __builtin_msa_bset_w (v4u32, v4u32);
15929 v2u64 __builtin_msa_bset_d (v2u64, v2u64);
15931 v16u8 __builtin_msa_bseti_b (v16u8, imm0_7);
15932 v8u16 __builtin_msa_bseti_h (v8u16, imm0_15);
15933 v4u32 __builtin_msa_bseti_w (v4u32, imm0_31);
15934 v2u64 __builtin_msa_bseti_d (v2u64, imm0_63);
15936 i32 __builtin_msa_bz_b (v16u8);
15937 i32 __builtin_msa_bz_h (v8u16);
15938 i32 __builtin_msa_bz_w (v4u32);
15939 i32 __builtin_msa_bz_d (v2u64);
15941 i32 __builtin_msa_bz_v (v16u8);
15943 v16i8 __builtin_msa_ceq_b (v16i8, v16i8);
15944 v8i16 __builtin_msa_ceq_h (v8i16, v8i16);
15945 v4i32 __builtin_msa_ceq_w (v4i32, v4i32);
15946 v2i64 __builtin_msa_ceq_d (v2i64, v2i64);
15948 v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15);
15949 v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15);
15950 v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15);
15951 v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15);
15953 i32 __builtin_msa_cfcmsa (imm0_31);
15955 v16i8 __builtin_msa_cle_s_b (v16i8, v16i8);
15956 v8i16 __builtin_msa_cle_s_h (v8i16, v8i16);
15957 v4i32 __builtin_msa_cle_s_w (v4i32, v4i32);
15958 v2i64 __builtin_msa_cle_s_d (v2i64, v2i64);
15960 v16i8 __builtin_msa_cle_u_b (v16u8, v16u8);
15961 v8i16 __builtin_msa_cle_u_h (v8u16, v8u16);
15962 v4i32 __builtin_msa_cle_u_w (v4u32, v4u32);
15963 v2i64 __builtin_msa_cle_u_d (v2u64, v2u64);
15965 v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15);
15966 v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15);
15967 v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15);
15968 v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15);
15970 v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31);
15971 v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31);
15972 v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31);
15973 v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31);
15975 v16i8 __builtin_msa_clt_s_b (v16i8, v16i8);
15976 v8i16 __builtin_msa_clt_s_h (v8i16, v8i16);
15977 v4i32 __builtin_msa_clt_s_w (v4i32, v4i32);
15978 v2i64 __builtin_msa_clt_s_d (v2i64, v2i64);
15980 v16i8 __builtin_msa_clt_u_b (v16u8, v16u8);
15981 v8i16 __builtin_msa_clt_u_h (v8u16, v8u16);
15982 v4i32 __builtin_msa_clt_u_w (v4u32, v4u32);
15983 v2i64 __builtin_msa_clt_u_d (v2u64, v2u64);
15985 v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15);
15986 v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15);
15987 v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15);
15988 v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15);
15990 v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31);
15991 v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31);
15992 v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31);
15993 v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31);
15995 i32 __builtin_msa_copy_s_b (v16i8, imm0_15);
15996 i32 __builtin_msa_copy_s_h (v8i16, imm0_7);
15997 i32 __builtin_msa_copy_s_w (v4i32, imm0_3);
15998 i64 __builtin_msa_copy_s_d (v2i64, imm0_1);
16000 u32 __builtin_msa_copy_u_b (v16i8, imm0_15);
16001 u32 __builtin_msa_copy_u_h (v8i16, imm0_7);
16002 u32 __builtin_msa_copy_u_w (v4i32, imm0_3);
16003 u64 __builtin_msa_copy_u_d (v2i64, imm0_1);
16005 void __builtin_msa_ctcmsa (imm0_31, i32);
16007 v16i8 __builtin_msa_div_s_b (v16i8, v16i8);
16008 v8i16 __builtin_msa_div_s_h (v8i16, v8i16);
16009 v4i32 __builtin_msa_div_s_w (v4i32, v4i32);
16010 v2i64 __builtin_msa_div_s_d (v2i64, v2i64);
16012 v16u8 __builtin_msa_div_u_b (v16u8, v16u8);
16013 v8u16 __builtin_msa_div_u_h (v8u16, v8u16);
16014 v4u32 __builtin_msa_div_u_w (v4u32, v4u32);
16015 v2u64 __builtin_msa_div_u_d (v2u64, v2u64);
16017 v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8);
16018 v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16);
16019 v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32);
16021 v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8);
16022 v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16);
16023 v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32);
16025 v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8);
16026 v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16);
16027 v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32);
16029 v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8);
16030 v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16);
16031 v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32);
16033 v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8);
16034 v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16);
16035 v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32);
16037 v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8);
16038 v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16);
16039 v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32);
16041 v4f32 __builtin_msa_fadd_w (v4f32, v4f32);
16042 v2f64 __builtin_msa_fadd_d (v2f64, v2f64);
16044 v4i32 __builtin_msa_fcaf_w (v4f32, v4f32);
16045 v2i64 __builtin_msa_fcaf_d (v2f64, v2f64);
16047 v4i32 __builtin_msa_fceq_w (v4f32, v4f32);
16048 v2i64 __builtin_msa_fceq_d (v2f64, v2f64);
16050 v4i32 __builtin_msa_fclass_w (v4f32);
16051 v2i64 __builtin_msa_fclass_d (v2f64);
16053 v4i32 __builtin_msa_fcle_w (v4f32, v4f32);
16054 v2i64 __builtin_msa_fcle_d (v2f64, v2f64);
16056 v4i32 __builtin_msa_fclt_w (v4f32, v4f32);
16057 v2i64 __builtin_msa_fclt_d (v2f64, v2f64);
16059 v4i32 __builtin_msa_fcne_w (v4f32, v4f32);
16060 v2i64 __builtin_msa_fcne_d (v2f64, v2f64);
16062 v4i32 __builtin_msa_fcor_w (v4f32, v4f32);
16063 v2i64 __builtin_msa_fcor_d (v2f64, v2f64);
16065 v4i32 __builtin_msa_fcueq_w (v4f32, v4f32);
16066 v2i64 __builtin_msa_fcueq_d (v2f64, v2f64);
16068 v4i32 __builtin_msa_fcule_w (v4f32, v4f32);
16069 v2i64 __builtin_msa_fcule_d (v2f64, v2f64);
16071 v4i32 __builtin_msa_fcult_w (v4f32, v4f32);
16072 v2i64 __builtin_msa_fcult_d (v2f64, v2f64);
16074 v4i32 __builtin_msa_fcun_w (v4f32, v4f32);
16075 v2i64 __builtin_msa_fcun_d (v2f64, v2f64);
16077 v4i32 __builtin_msa_fcune_w (v4f32, v4f32);
16078 v2i64 __builtin_msa_fcune_d (v2f64, v2f64);
16080 v4f32 __builtin_msa_fdiv_w (v4f32, v4f32);
16081 v2f64 __builtin_msa_fdiv_d (v2f64, v2f64);
16083 v8i16 __builtin_msa_fexdo_h (v4f32, v4f32);
16084 v4f32 __builtin_msa_fexdo_w (v2f64, v2f64);
16086 v4f32 __builtin_msa_fexp2_w (v4f32, v4i32);
16087 v2f64 __builtin_msa_fexp2_d (v2f64, v2i64);
16089 v4f32 __builtin_msa_fexupl_w (v8i16);
16090 v2f64 __builtin_msa_fexupl_d (v4f32);
16092 v4f32 __builtin_msa_fexupr_w (v8i16);
16093 v2f64 __builtin_msa_fexupr_d (v4f32);
16095 v4f32 __builtin_msa_ffint_s_w (v4i32);
16096 v2f64 __builtin_msa_ffint_s_d (v2i64);
16098 v4f32 __builtin_msa_ffint_u_w (v4u32);
16099 v2f64 __builtin_msa_ffint_u_d (v2u64);
16101 v4f32 __builtin_msa_ffql_w (v8i16);
16102 v2f64 __builtin_msa_ffql_d (v4i32);
16104 v4f32 __builtin_msa_ffqr_w (v8i16);
16105 v2f64 __builtin_msa_ffqr_d (v4i32);
16107 v16i8 __builtin_msa_fill_b (i32);
16108 v8i16 __builtin_msa_fill_h (i32);
16109 v4i32 __builtin_msa_fill_w (i32);
16110 v2i64 __builtin_msa_fill_d (i64);
16112 v4f32 __builtin_msa_flog2_w (v4f32);
16113 v2f64 __builtin_msa_flog2_d (v2f64);
16115 v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32);
16116 v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64);
16118 v4f32 __builtin_msa_fmax_w (v4f32, v4f32);
16119 v2f64 __builtin_msa_fmax_d (v2f64, v2f64);
16121 v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32);
16122 v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64);
16124 v4f32 __builtin_msa_fmin_w (v4f32, v4f32);
16125 v2f64 __builtin_msa_fmin_d (v2f64, v2f64);
16127 v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32);
16128 v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64);
16130 v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32);
16131 v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64);
16133 v4f32 __builtin_msa_fmul_w (v4f32, v4f32);
16134 v2f64 __builtin_msa_fmul_d (v2f64, v2f64);
16136 v4f32 __builtin_msa_frint_w (v4f32);
16137 v2f64 __builtin_msa_frint_d (v2f64);
16139 v4f32 __builtin_msa_frcp_w (v4f32);
16140 v2f64 __builtin_msa_frcp_d (v2f64);
16142 v4f32 __builtin_msa_frsqrt_w (v4f32);
16143 v2f64 __builtin_msa_frsqrt_d (v2f64);
16145 v4i32 __builtin_msa_fsaf_w (v4f32, v4f32);
16146 v2i64 __builtin_msa_fsaf_d (v2f64, v2f64);
16148 v4i32 __builtin_msa_fseq_w (v4f32, v4f32);
16149 v2i64 __builtin_msa_fseq_d (v2f64, v2f64);
16151 v4i32 __builtin_msa_fsle_w (v4f32, v4f32);
16152 v2i64 __builtin_msa_fsle_d (v2f64, v2f64);
16154 v4i32 __builtin_msa_fslt_w (v4f32, v4f32);
16155 v2i64 __builtin_msa_fslt_d (v2f64, v2f64);
16157 v4i32 __builtin_msa_fsne_w (v4f32, v4f32);
16158 v2i64 __builtin_msa_fsne_d (v2f64, v2f64);
16160 v4i32 __builtin_msa_fsor_w (v4f32, v4f32);
16161 v2i64 __builtin_msa_fsor_d (v2f64, v2f64);
16163 v4f32 __builtin_msa_fsqrt_w (v4f32);
16164 v2f64 __builtin_msa_fsqrt_d (v2f64);
16166 v4f32 __builtin_msa_fsub_w (v4f32, v4f32);
16167 v2f64 __builtin_msa_fsub_d (v2f64, v2f64);
16169 v4i32 __builtin_msa_fsueq_w (v4f32, v4f32);
16170 v2i64 __builtin_msa_fsueq_d (v2f64, v2f64);
16172 v4i32 __builtin_msa_fsule_w (v4f32, v4f32);
16173 v2i64 __builtin_msa_fsule_d (v2f64, v2f64);
16175 v4i32 __builtin_msa_fsult_w (v4f32, v4f32);
16176 v2i64 __builtin_msa_fsult_d (v2f64, v2f64);
16178 v4i32 __builtin_msa_fsun_w (v4f32, v4f32);
16179 v2i64 __builtin_msa_fsun_d (v2f64, v2f64);
16181 v4i32 __builtin_msa_fsune_w (v4f32, v4f32);
16182 v2i64 __builtin_msa_fsune_d (v2f64, v2f64);
16184 v4i32 __builtin_msa_ftint_s_w (v4f32);
16185 v2i64 __builtin_msa_ftint_s_d (v2f64);
16187 v4u32 __builtin_msa_ftint_u_w (v4f32);
16188 v2u64 __builtin_msa_ftint_u_d (v2f64);
16190 v8i16 __builtin_msa_ftq_h (v4f32, v4f32);
16191 v4i32 __builtin_msa_ftq_w (v2f64, v2f64);
16193 v4i32 __builtin_msa_ftrunc_s_w (v4f32);
16194 v2i64 __builtin_msa_ftrunc_s_d (v2f64);
16196 v4u32 __builtin_msa_ftrunc_u_w (v4f32);
16197 v2u64 __builtin_msa_ftrunc_u_d (v2f64);
16199 v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8);
16200 v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16);
16201 v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32);
16203 v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8);
16204 v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16);
16205 v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32);
16207 v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8);
16208 v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16);
16209 v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32);
16211 v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8);
16212 v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16);
16213 v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32);
16215 v16i8 __builtin_msa_ilvev_b (v16i8, v16i8);
16216 v8i16 __builtin_msa_ilvev_h (v8i16, v8i16);
16217 v4i32 __builtin_msa_ilvev_w (v4i32, v4i32);
16218 v2i64 __builtin_msa_ilvev_d (v2i64, v2i64);
16220 v16i8 __builtin_msa_ilvl_b (v16i8, v16i8);
16221 v8i16 __builtin_msa_ilvl_h (v8i16, v8i16);
16222 v4i32 __builtin_msa_ilvl_w (v4i32, v4i32);
16223 v2i64 __builtin_msa_ilvl_d (v2i64, v2i64);
16225 v16i8 __builtin_msa_ilvod_b (v16i8, v16i8);
16226 v8i16 __builtin_msa_ilvod_h (v8i16, v8i16);
16227 v4i32 __builtin_msa_ilvod_w (v4i32, v4i32);
16228 v2i64 __builtin_msa_ilvod_d (v2i64, v2i64);
16230 v16i8 __builtin_msa_ilvr_b (v16i8, v16i8);
16231 v8i16 __builtin_msa_ilvr_h (v8i16, v8i16);
16232 v4i32 __builtin_msa_ilvr_w (v4i32, v4i32);
16233 v2i64 __builtin_msa_ilvr_d (v2i64, v2i64);
16235 v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32);
16236 v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32);
16237 v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32);
16238 v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64);
16240 v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8);
16241 v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16);
16242 v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32);
16243 v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64);
16245 v16i8 __builtin_msa_ld_b (void *, imm_n512_511);
16246 v8i16 __builtin_msa_ld_h (void *, imm_n1024_1022);
16247 v4i32 __builtin_msa_ld_w (void *, imm_n2048_2044);
16248 v2i64 __builtin_msa_ld_d (void *, imm_n4096_4088);
16250 v16i8 __builtin_msa_ldi_b (imm_n512_511);
16251 v8i16 __builtin_msa_ldi_h (imm_n512_511);
16252 v4i32 __builtin_msa_ldi_w (imm_n512_511);
16253 v2i64 __builtin_msa_ldi_d (imm_n512_511);
16255 v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16);
16256 v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32);
16258 v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16);
16259 v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32);
16261 v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8);
16262 v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16);
16263 v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32);
16264 v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64);
16266 v16i8 __builtin_msa_max_a_b (v16i8, v16i8);
16267 v8i16 __builtin_msa_max_a_h (v8i16, v8i16);
16268 v4i32 __builtin_msa_max_a_w (v4i32, v4i32);
16269 v2i64 __builtin_msa_max_a_d (v2i64, v2i64);
16271 v16i8 __builtin_msa_max_s_b (v16i8, v16i8);
16272 v8i16 __builtin_msa_max_s_h (v8i16, v8i16);
16273 v4i32 __builtin_msa_max_s_w (v4i32, v4i32);
16274 v2i64 __builtin_msa_max_s_d (v2i64, v2i64);
16276 v16u8 __builtin_msa_max_u_b (v16u8, v16u8);
16277 v8u16 __builtin_msa_max_u_h (v8u16, v8u16);
16278 v4u32 __builtin_msa_max_u_w (v4u32, v4u32);
16279 v2u64 __builtin_msa_max_u_d (v2u64, v2u64);
16281 v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15);
16282 v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15);
16283 v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15);
16284 v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15);
16286 v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31);
16287 v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31);
16288 v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31);
16289 v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31);
16291 v16i8 __builtin_msa_min_a_b (v16i8, v16i8);
16292 v8i16 __builtin_msa_min_a_h (v8i16, v8i16);
16293 v4i32 __builtin_msa_min_a_w (v4i32, v4i32);
16294 v2i64 __builtin_msa_min_a_d (v2i64, v2i64);
16296 v16i8 __builtin_msa_min_s_b (v16i8, v16i8);
16297 v8i16 __builtin_msa_min_s_h (v8i16, v8i16);
16298 v4i32 __builtin_msa_min_s_w (v4i32, v4i32);
16299 v2i64 __builtin_msa_min_s_d (v2i64, v2i64);
16301 v16u8 __builtin_msa_min_u_b (v16u8, v16u8);
16302 v8u16 __builtin_msa_min_u_h (v8u16, v8u16);
16303 v4u32 __builtin_msa_min_u_w (v4u32, v4u32);
16304 v2u64 __builtin_msa_min_u_d (v2u64, v2u64);
16306 v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15);
16307 v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15);
16308 v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15);
16309 v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15);
16311 v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31);
16312 v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31);
16313 v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31);
16314 v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31);
16316 v16i8 __builtin_msa_mod_s_b (v16i8, v16i8);
16317 v8i16 __builtin_msa_mod_s_h (v8i16, v8i16);
16318 v4i32 __builtin_msa_mod_s_w (v4i32, v4i32);
16319 v2i64 __builtin_msa_mod_s_d (v2i64, v2i64);
16321 v16u8 __builtin_msa_mod_u_b (v16u8, v16u8);
16322 v8u16 __builtin_msa_mod_u_h (v8u16, v8u16);
16323 v4u32 __builtin_msa_mod_u_w (v4u32, v4u32);
16324 v2u64 __builtin_msa_mod_u_d (v2u64, v2u64);
16326 v16i8 __builtin_msa_move_v (v16i8);
16328 v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16);
16329 v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32);
16331 v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16);
16332 v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32);
16334 v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8);
16335 v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16);
16336 v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32);
16337 v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64);
16339 v8i16 __builtin_msa_mul_q_h (v8i16, v8i16);
16340 v4i32 __builtin_msa_mul_q_w (v4i32, v4i32);
16342 v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16);
16343 v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32);
16345 v16i8 __builtin_msa_mulv_b (v16i8, v16i8);
16346 v8i16 __builtin_msa_mulv_h (v8i16, v8i16);
16347 v4i32 __builtin_msa_mulv_w (v4i32, v4i32);
16348 v2i64 __builtin_msa_mulv_d (v2i64, v2i64);
16350 v16i8 __builtin_msa_nloc_b (v16i8);
16351 v8i16 __builtin_msa_nloc_h (v8i16);
16352 v4i32 __builtin_msa_nloc_w (v4i32);
16353 v2i64 __builtin_msa_nloc_d (v2i64);
16355 v16i8 __builtin_msa_nlzc_b (v16i8);
16356 v8i16 __builtin_msa_nlzc_h (v8i16);
16357 v4i32 __builtin_msa_nlzc_w (v4i32);
16358 v2i64 __builtin_msa_nlzc_d (v2i64);
16360 v16u8 __builtin_msa_nor_v (v16u8, v16u8);
16362 v16u8 __builtin_msa_nori_b (v16u8, imm0_255);
16364 v16u8 __builtin_msa_or_v (v16u8, v16u8);
16366 v16u8 __builtin_msa_ori_b (v16u8, imm0_255);
16368 v16i8 __builtin_msa_pckev_b (v16i8, v16i8);
16369 v8i16 __builtin_msa_pckev_h (v8i16, v8i16);
16370 v4i32 __builtin_msa_pckev_w (v4i32, v4i32);
16371 v2i64 __builtin_msa_pckev_d (v2i64, v2i64);
16373 v16i8 __builtin_msa_pckod_b (v16i8, v16i8);
16374 v8i16 __builtin_msa_pckod_h (v8i16, v8i16);
16375 v4i32 __builtin_msa_pckod_w (v4i32, v4i32);
16376 v2i64 __builtin_msa_pckod_d (v2i64, v2i64);
16378 v16i8 __builtin_msa_pcnt_b (v16i8);
16379 v8i16 __builtin_msa_pcnt_h (v8i16);
16380 v4i32 __builtin_msa_pcnt_w (v4i32);
16381 v2i64 __builtin_msa_pcnt_d (v2i64);
16383 v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7);
16384 v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15);
16385 v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31);
16386 v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63);
16388 v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7);
16389 v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15);
16390 v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31);
16391 v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63);
16393 v16i8 __builtin_msa_shf_b (v16i8, imm0_255);
16394 v8i16 __builtin_msa_shf_h (v8i16, imm0_255);
16395 v4i32 __builtin_msa_shf_w (v4i32, imm0_255);
16397 v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32);
16398 v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32);
16399 v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32);
16400 v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32);
16402 v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15);
16403 v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7);
16404 v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3);
16405 v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1);
16407 v16i8 __builtin_msa_sll_b (v16i8, v16i8);
16408 v8i16 __builtin_msa_sll_h (v8i16, v8i16);
16409 v4i32 __builtin_msa_sll_w (v4i32, v4i32);
16410 v2i64 __builtin_msa_sll_d (v2i64, v2i64);
16412 v16i8 __builtin_msa_slli_b (v16i8, imm0_7);
16413 v8i16 __builtin_msa_slli_h (v8i16, imm0_15);
16414 v4i32 __builtin_msa_slli_w (v4i32, imm0_31);
16415 v2i64 __builtin_msa_slli_d (v2i64, imm0_63);
16417 v16i8 __builtin_msa_splat_b (v16i8, i32);
16418 v8i16 __builtin_msa_splat_h (v8i16, i32);
16419 v4i32 __builtin_msa_splat_w (v4i32, i32);
16420 v2i64 __builtin_msa_splat_d (v2i64, i32);
16422 v16i8 __builtin_msa_splati_b (v16i8, imm0_15);
16423 v8i16 __builtin_msa_splati_h (v8i16, imm0_7);
16424 v4i32 __builtin_msa_splati_w (v4i32, imm0_3);
16425 v2i64 __builtin_msa_splati_d (v2i64, imm0_1);
16427 v16i8 __builtin_msa_sra_b (v16i8, v16i8);
16428 v8i16 __builtin_msa_sra_h (v8i16, v8i16);
16429 v4i32 __builtin_msa_sra_w (v4i32, v4i32);
16430 v2i64 __builtin_msa_sra_d (v2i64, v2i64);
16432 v16i8 __builtin_msa_srai_b (v16i8, imm0_7);
16433 v8i16 __builtin_msa_srai_h (v8i16, imm0_15);
16434 v4i32 __builtin_msa_srai_w (v4i32, imm0_31);
16435 v2i64 __builtin_msa_srai_d (v2i64, imm0_63);
16437 v16i8 __builtin_msa_srar_b (v16i8, v16i8);
16438 v8i16 __builtin_msa_srar_h (v8i16, v8i16);
16439 v4i32 __builtin_msa_srar_w (v4i32, v4i32);
16440 v2i64 __builtin_msa_srar_d (v2i64, v2i64);
16442 v16i8 __builtin_msa_srari_b (v16i8, imm0_7);
16443 v8i16 __builtin_msa_srari_h (v8i16, imm0_15);
16444 v4i32 __builtin_msa_srari_w (v4i32, imm0_31);
16445 v2i64 __builtin_msa_srari_d (v2i64, imm0_63);
16447 v16i8 __builtin_msa_srl_b (v16i8, v16i8);
16448 v8i16 __builtin_msa_srl_h (v8i16, v8i16);
16449 v4i32 __builtin_msa_srl_w (v4i32, v4i32);
16450 v2i64 __builtin_msa_srl_d (v2i64, v2i64);
16452 v16i8 __builtin_msa_srli_b (v16i8, imm0_7);
16453 v8i16 __builtin_msa_srli_h (v8i16, imm0_15);
16454 v4i32 __builtin_msa_srli_w (v4i32, imm0_31);
16455 v2i64 __builtin_msa_srli_d (v2i64, imm0_63);
16457 v16i8 __builtin_msa_srlr_b (v16i8, v16i8);
16458 v8i16 __builtin_msa_srlr_h (v8i16, v8i16);
16459 v4i32 __builtin_msa_srlr_w (v4i32, v4i32);
16460 v2i64 __builtin_msa_srlr_d (v2i64, v2i64);
16462 v16i8 __builtin_msa_srlri_b (v16i8, imm0_7);
16463 v8i16 __builtin_msa_srlri_h (v8i16, imm0_15);
16464 v4i32 __builtin_msa_srlri_w (v4i32, imm0_31);
16465 v2i64 __builtin_msa_srlri_d (v2i64, imm0_63);
16467 void __builtin_msa_st_b (v16i8, void *, imm_n512_511);
16468 void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022);
16469 void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044);
16470 void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088);
16472 v16i8 __builtin_msa_subs_s_b (v16i8, v16i8);
16473 v8i16 __builtin_msa_subs_s_h (v8i16, v8i16);
16474 v4i32 __builtin_msa_subs_s_w (v4i32, v4i32);
16475 v2i64 __builtin_msa_subs_s_d (v2i64, v2i64);
16477 v16u8 __builtin_msa_subs_u_b (v16u8, v16u8);
16478 v8u16 __builtin_msa_subs_u_h (v8u16, v8u16);
16479 v4u32 __builtin_msa_subs_u_w (v4u32, v4u32);
16480 v2u64 __builtin_msa_subs_u_d (v2u64, v2u64);
16482 v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8);
16483 v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16);
16484 v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32);
16485 v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64);
16487 v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8);
16488 v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16);
16489 v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32);
16490 v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64);
16492 v16i8 __builtin_msa_subv_b (v16i8, v16i8);
16493 v8i16 __builtin_msa_subv_h (v8i16, v8i16);
16494 v4i32 __builtin_msa_subv_w (v4i32, v4i32);
16495 v2i64 __builtin_msa_subv_d (v2i64, v2i64);
16497 v16i8 __builtin_msa_subvi_b (v16i8, imm0_31);
16498 v8i16 __builtin_msa_subvi_h (v8i16, imm0_31);
16499 v4i32 __builtin_msa_subvi_w (v4i32, imm0_31);
16500 v2i64 __builtin_msa_subvi_d (v2i64, imm0_31);
16502 v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8);
16503 v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16);
16504 v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32);
16505 v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64);
16507 v16u8 __builtin_msa_xor_v (v16u8, v16u8);
16509 v16u8 __builtin_msa_xori_b (v16u8, imm0_255);
16512 @node Other MIPS Built-in Functions
16513 @subsection Other MIPS Built-in Functions
16515 GCC provides other MIPS-specific built-in functions:
16518 @item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr})
16519 Insert a @samp{cache} instruction with operands @var{op} and @var{addr}.
16520 GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE}
16521 when this function is available.
16523 @item unsigned int __builtin_mips_get_fcsr (void)
16524 @itemx void __builtin_mips_set_fcsr (unsigned int @var{value})
16525 Get and set the contents of the floating-point control and status register
16526 (FPU control register 31). These functions are only available in hard-float
16527 code but can be called in both MIPS16 and non-MIPS16 contexts.
16529 @code{__builtin_mips_set_fcsr} can be used to change any bit of the
16530 register except the condition codes, which GCC assumes are preserved.
16533 @node MSP430 Built-in Functions
16534 @subsection MSP430 Built-in Functions
16536 GCC provides a couple of special builtin functions to aid in the
16537 writing of interrupt handlers in C.
16540 @item __bic_SR_register_on_exit (int @var{mask})
16541 This clears the indicated bits in the saved copy of the status register
16542 currently residing on the stack. This only works inside interrupt
16543 handlers and the changes to the status register will only take affect
16544 once the handler returns.
16546 @item __bis_SR_register_on_exit (int @var{mask})
16547 This sets the indicated bits in the saved copy of the status register
16548 currently residing on the stack. This only works inside interrupt
16549 handlers and the changes to the status register will only take affect
16550 once the handler returns.
16552 @item __delay_cycles (long long @var{cycles})
16553 This inserts an instruction sequence that takes exactly @var{cycles}
16554 cycles (between 0 and about 17E9) to complete. The inserted sequence
16555 may use jumps, loops, or no-ops, and does not interfere with any other
16556 instructions. Note that @var{cycles} must be a compile-time constant
16557 integer - that is, you must pass a number, not a variable that may be
16558 optimized to a constant later. The number of cycles delayed by this
16562 @node NDS32 Built-in Functions
16563 @subsection NDS32 Built-in Functions
16565 These built-in functions are available for the NDS32 target:
16567 @deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr})
16568 Insert an ISYNC instruction into the instruction stream where
16569 @var{addr} is an instruction address for serialization.
16572 @deftypefn {Built-in Function} void __builtin_nds32_isb (void)
16573 Insert an ISB instruction into the instruction stream.
16576 @deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr})
16577 Return the content of a system register which is mapped by @var{sr}.
16580 @deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr})
16581 Return the content of a user space register which is mapped by @var{usr}.
16584 @deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr})
16585 Move the @var{value} to a system register which is mapped by @var{sr}.
16588 @deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr})
16589 Move the @var{value} to a user space register which is mapped by @var{usr}.
16592 @deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void)
16593 Enable global interrupt.
16596 @deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void)
16597 Disable global interrupt.
16600 @node picoChip Built-in Functions
16601 @subsection picoChip Built-in Functions
16603 GCC provides an interface to selected machine instructions from the
16604 picoChip instruction set.
16607 @item int __builtin_sbc (int @var{value})
16608 Sign bit count. Return the number of consecutive bits in @var{value}
16609 that have the same value as the sign bit. The result is the number of
16610 leading sign bits minus one, giving the number of redundant sign bits in
16613 @item int __builtin_byteswap (int @var{value})
16614 Byte swap. Return the result of swapping the upper and lower bytes of
16617 @item int __builtin_brev (int @var{value})
16618 Bit reversal. Return the result of reversing the bits in
16619 @var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1,
16622 @item int __builtin_adds (int @var{x}, int @var{y})
16623 Saturating addition. Return the result of adding @var{x} and @var{y},
16624 storing the value 32767 if the result overflows.
16626 @item int __builtin_subs (int @var{x}, int @var{y})
16627 Saturating subtraction. Return the result of subtracting @var{y} from
16628 @var{x}, storing the value @minus{}32768 if the result overflows.
16630 @item void __builtin_halt (void)
16631 Halt. The processor stops execution. This built-in is useful for
16632 implementing assertions.
16636 @node Basic PowerPC Built-in Functions
16637 @subsection Basic PowerPC Built-in Functions
16640 * Basic PowerPC Built-in Functions Available on all Configurations::
16641 * Basic PowerPC Built-in Functions Available on ISA 2.05::
16642 * Basic PowerPC Built-in Functions Available on ISA 2.06::
16643 * Basic PowerPC Built-in Functions Available on ISA 2.07::
16644 * Basic PowerPC Built-in Functions Available on ISA 3.0::
16647 This section describes PowerPC built-in functions that do not require
16648 the inclusion of any special header files to declare prototypes or
16649 provide macro definitions. The sections that follow describe
16650 additional PowerPC built-in functions.
16652 @node Basic PowerPC Built-in Functions Available on all Configurations
16653 @subsubsection Basic PowerPC Built-in Functions Available on all Configurations
16655 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
16656 This function is a @code{nop} on the PowerPC platform and is included solely
16657 to maintain API compatibility with the x86 builtins.
16660 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
16661 This function returns a value of @code{1} if the run-time CPU is of type
16662 @var{cpuname} and returns @code{0} otherwise
16664 The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer
16665 which exports the hardware capability bits. GCC defines the macro
16666 @code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports}
16667 built-in function is fully supported.
16669 If GCC was configured to use a GLIBC before 2.23, the built-in
16670 function @code{__builtin_cpu_is} always returns a 0 and the compiler
16673 The following CPU names can be detected:
16677 IBM POWER9 Server CPU.
16679 IBM POWER8 Server CPU.
16681 IBM POWER7 Server CPU.
16683 IBM POWER6 Server CPU (RAW mode).
16685 IBM POWER6 Server CPU (Architected mode).
16687 IBM POWER5+ Server CPU.
16689 IBM POWER5 Server CPU.
16691 IBM 970 Server CPU (ie, Apple G5).
16693 IBM POWER4 Server CPU.
16695 IBM A2 64-bit Embedded CPU
16697 IBM PowerPC 476FP 32-bit Embedded CPU.
16699 IBM PowerPC 464 32-bit Embedded CPU.
16701 PowerPC 440 32-bit Embedded CPU.
16703 PowerPC 405 32-bit Embedded CPU.
16705 IBM PowerPC Cell Broadband Engine Architecture CPU.
16708 Here is an example:
16710 #ifdef __BUILTIN_CPU_SUPPORTS__
16711 if (__builtin_cpu_is ("power8"))
16713 do_power8 (); // POWER8 specific implementation.
16718 do_generic (); // Generic implementation.
16723 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
16724 This function returns a value of @code{1} if the run-time CPU supports the HWCAP
16725 feature @var{feature} and returns @code{0} otherwise.
16727 The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or
16728 newer which exports the hardware capability bits. GCC defines the
16729 macro @code{__BUILTIN_CPU_SUPPORTS__} if the
16730 @code{__builtin_cpu_supports} built-in function is fully supported.
16732 If GCC was configured to use a GLIBC before 2.23, the built-in
16733 function @code{__builtin_cpu_suports} always returns a 0 and the
16734 compiler issues a warning.
16736 The following features can be
16741 4xx CPU has a Multiply Accumulator.
16743 CPU has a SIMD/Vector Unit.
16745 CPU supports ISA 2.05 (eg, POWER6)
16747 CPU supports ISA 2.06 (eg, POWER7)
16749 CPU supports ISA 2.07 (eg, POWER8)
16751 CPU supports ISA 3.0 (eg, POWER9)
16753 CPU supports the set of compatible performance monitoring events.
16755 CPU supports the Embedded ISA category.
16757 CPU has a CELL broadband engine.
16759 CPU supports the @code{darn} (deliver a random number) instruction.
16761 CPU has a decimal floating point unit.
16763 CPU supports the data stream control register.
16765 CPU supports event base branching.
16767 CPU has a SPE double precision floating point unit.
16769 CPU has a SPE single precision floating point unit.
16771 CPU has a floating point unit.
16773 CPU has hardware transaction memory instructions.
16775 Kernel aborts hardware transactions when a syscall is made.
16776 @item htm-no-suspend
16777 CPU supports hardware transaction memory but does not support the
16778 @code{tsuspend.} instruction.
16780 CPU supports icache snooping capabilities.
16782 CPU supports 128-bit IEEE binary floating point instructions.
16784 CPU supports the integer select instruction.
16786 CPU has a memory management unit.
16788 CPU does not have a timebase (eg, 601 and 403gx).
16790 CPU supports the PA Semi 6T CORE ISA.
16792 CPU supports ISA 2.00 (eg, POWER4)
16794 CPU supports ISA 2.02 (eg, POWER5)
16796 CPU supports ISA 2.03 (eg, POWER5+)
16798 CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr.
16800 CPU supports 32-bit mode execution.
16802 CPU supports the old POWER ISA (eg, 601)
16804 CPU supports 64-bit mode execution.
16806 CPU supports a little-endian mode that uses address swizzling.
16808 Kernel supports system call vectored.
16810 CPU support simultaneous multi-threading.
16812 CPU has a signal processing extension unit.
16814 CPU supports the target address register.
16816 CPU supports true little-endian mode.
16818 CPU has unified I/D cache.
16820 CPU supports the vector cryptography instructions.
16822 CPU supports the vector-scalar extension.
16825 Here is an example:
16827 #ifdef __BUILTIN_CPU_SUPPORTS__
16828 if (__builtin_cpu_supports ("fpu"))
16830 asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2));
16835 dst = __fadd (src1, src2); // Software FP addition function.
16840 The following built-in functions are also available on all PowerPC
16843 uint64_t __builtin_ppc_get_timebase ();
16844 unsigned long __builtin_ppc_mftb ();
16845 double __builtin_unpack_ibm128 (__ibm128, int);
16846 __ibm128 __builtin_pack_ibm128 (double, double);
16847 double __builtin_mffs (void);
16848 void __builtin_mtfsb0 (const int);
16849 void __builtin_mtfsb1 (const int);
16850 void __builtin_set_fpscr_rn (int);
16853 The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb}
16854 functions generate instructions to read the Time Base Register. The
16855 @code{__builtin_ppc_get_timebase} function may generate multiple
16856 instructions and always returns the 64 bits of the Time Base Register.
16857 The @code{__builtin_ppc_mftb} function always generates one instruction and
16858 returns the Time Base Register value as an unsigned long, throwing away
16859 the most significant word on 32-bit environments. The @code{__builtin_mffs}
16860 return the value of the FPSCR register. Note, ISA 3.0 supports the
16861 @code{__builtin_mffsl()} which permits software to read the control and
16862 non-sticky status bits in the FSPCR without the higher latency associated with
16863 accessing the sticky status bits. The
16864 @code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change
16865 as an argument. The valid bit range is between 0 and 31. The builtins map to
16866 the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and
16867 add 32. Hence these instructions only modify the FPSCR[32:63] bits by
16868 changing the specified bit to a zero or one respectively. The
16869 @code{__builtin_set_fpscr_rn} builtin allows changing both of the floating
16870 point rounding mode bits. The argument is a 2-bit value. The argument can
16871 either be a @code{const int} or stored in a variable. The builtin uses
16873 instruction @code{mffscrn} if available, otherwise it reads the FPSCR, masks
16874 the current rounding mode bits out and OR's in the new value.
16876 @node Basic PowerPC Built-in Functions Available on ISA 2.05
16877 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05
16879 The basic built-in functions described in this section are
16880 available on the PowerPC family of processors starting with ISA 2.05
16881 or later. Unless specific options are explicitly disabled on the
16882 command line, specifying option @option{-mcpu=power6} has the effect of
16883 enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
16884 @option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb},
16885 @option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and
16886 @option{-mrecip-precision} options. Specify the
16887 @option{-maltivec} option explicitly in
16888 combination with the above options if desired.
16890 The following functions require option @option{-mcmpb}.
16892 unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int);
16893 unsigned int __builtin_cmpb (unsigned int, unsigned int);
16896 The @code{__builtin_cmpb} function
16897 performs a byte-wise compare on the contents of its two arguments,
16898 returning the result of the byte-wise comparison as the returned
16899 value. For each byte comparison, the corresponding byte of the return
16900 value holds 0xff if the input bytes are equal and 0 if the input bytes
16901 are not equal. If either of the arguments to this built-in function
16902 is wider than 32 bits, the function call expands into the form that
16903 expects @code{unsigned long long int} arguments
16904 which is only available on 64-bit targets.
16906 The following built-in functions are available
16907 when hardware decimal floating point
16908 (@option{-mhard-dfp}) is available:
16910 void __builtin_set_fpscr_drn(int);
16911 _Decimal64 __builtin_ddedpd (int, _Decimal64);
16912 _Decimal128 __builtin_ddedpdq (int, _Decimal128);
16913 _Decimal64 __builtin_denbcd (int, _Decimal64);
16914 _Decimal128 __builtin_denbcdq (int, _Decimal128);
16915 _Decimal64 __builtin_diex (long long, _Decimal64);
16916 _Decimal128 _builtin_diexq (long long, _Decimal128);
16917 _Decimal64 __builtin_dscli (_Decimal64, int);
16918 _Decimal128 __builtin_dscliq (_Decimal128, int);
16919 _Decimal64 __builtin_dscri (_Decimal64, int);
16920 _Decimal128 __builtin_dscriq (_Decimal128, int);
16921 long long __builtin_dxex (_Decimal64);
16922 long long __builtin_dxexq (_Decimal128);
16923 _Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long);
16924 unsigned long long __builtin_unpack_dec128 (_Decimal128, int);
16926 The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal
16927 floating point rounding mode bits. The argument is a 3-bit value. The
16928 argument can either be a @code{const int} or the value can be stored in
16930 The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available.
16931 Otherwise the builtin reads the FPSCR, masks the current decimal rounding
16932 mode bits out and OR's in the new value.
16936 The following functions require @option{-mhard-float},
16937 @option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options.
16940 double __builtin_recipdiv (double, double);
16941 float __builtin_recipdivf (float, float);
16942 double __builtin_rsqrt (double);
16943 float __builtin_rsqrtf (float);
16946 The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and
16947 @code{__builtin_rsqrtf} functions generate multiple instructions to
16948 implement the reciprocal sqrt functionality using reciprocal sqrt
16949 estimate instructions.
16951 The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf}
16952 functions generate multiple instructions to implement division using
16953 the reciprocal estimate instructions.
16955 The following functions require @option{-mhard-float} and
16956 @option{-mmultiple} options.
16958 The @code{__builtin_unpack_longdouble} function takes a
16959 @code{long double} argument and a compile time constant of 0 or 1. If
16960 the constant is 0, the first @code{double} within the
16961 @code{long double} is returned, otherwise the second @code{double}
16962 is returned. The @code{__builtin_unpack_longdouble} function is only
16963 available if @code{long double} uses the IBM extended double
16966 The @code{__builtin_pack_longdouble} function takes two @code{double}
16967 arguments and returns a @code{long double} value that combines the two
16968 arguments. The @code{__builtin_pack_longdouble} function is only
16969 available if @code{long double} uses the IBM extended double
16972 The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128}
16973 argument and a compile time constant of 0 or 1. If the constant is 0,
16974 the first @code{double} within the @code{__ibm128} is returned,
16975 otherwise the second @code{double} is returned.
16977 The @code{__builtin_pack_ibm128} function takes two @code{double}
16978 arguments and returns a @code{__ibm128} value that combines the two
16981 Additional built-in functions are available for the 64-bit PowerPC
16982 family of processors, for efficient use of 128-bit floating point
16983 (@code{__float128}) values.
16985 @node Basic PowerPC Built-in Functions Available on ISA 2.06
16986 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06
16988 The basic built-in functions described in this section are
16989 available on the PowerPC family of processors starting with ISA 2.05
16990 or later. Unless specific options are explicitly disabled on the
16991 command line, specifying option @option{-mcpu=power7} has the effect of
16992 enabling all the same options as for @option{-mcpu=power6} in
16993 addition to the @option{-maltivec}, @option{-mpopcntd}, and
16994 @option{-mvsx} options.
16996 The following basic built-in functions require @option{-mpopcntd}:
16998 unsigned int __builtin_addg6s (unsigned int, unsigned int);
16999 long long __builtin_bpermd (long long, long long);
17000 unsigned int __builtin_cbcdtd (unsigned int);
17001 unsigned int __builtin_cdtbcd (unsigned int);
17002 long long __builtin_divde (long long, long long);
17003 unsigned long long __builtin_divdeu (unsigned long long, unsigned long long);
17004 int __builtin_divwe (int, int);
17005 unsigned int __builtin_divweu (unsigned int, unsigned int);
17006 vector __int128 __builtin_pack_vector_int128 (long long, long long);
17007 void __builtin_rs6000_speculation_barrier (void);
17008 long long __builtin_unpack_vector_int128 (vector __int128, signed char);
17011 Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions
17012 require a 64-bit environment.
17014 The following basic built-in functions, which are also supported on
17015 x86 targets, require @option{-mfloat128}.
17017 __float128 __builtin_fabsq (__float128);
17018 __float128 __builtin_copysignq (__float128, __float128);
17019 __float128 __builtin_infq (void);
17020 __float128 __builtin_huge_valq (void);
17021 __float128 __builtin_nanq (void);
17022 __float128 __builtin_nansq (void);
17024 __float128 __builtin_sqrtf128 (__float128);
17025 __float128 __builtin_fmaf128 (__float128, __float128, __float128);
17028 @node Basic PowerPC Built-in Functions Available on ISA 2.07
17029 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07
17031 The basic built-in functions described in this section are
17032 available on the PowerPC family of processors starting with ISA 2.07
17033 or later. Unless specific options are explicitly disabled on the
17034 command line, specifying option @option{-mcpu=power8} has the effect of
17035 enabling all the same options as for @option{-mcpu=power7} in
17036 addition to the @option{-mpower8-fusion}, @option{-mpower8-vector},
17037 @option{-mcrypto}, @option{-mhtm}, @option{-mquad-memory}, and
17038 @option{-mquad-memory-atomic} options.
17040 This section intentionally empty.
17042 @node Basic PowerPC Built-in Functions Available on ISA 3.0
17043 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0
17045 The basic built-in functions described in this section are
17046 available on the PowerPC family of processors starting with ISA 3.0
17047 or later. Unless specific options are explicitly disabled on the
17048 command line, specifying option @option{-mcpu=power9} has the effect of
17049 enabling all the same options as for @option{-mcpu=power8} in
17050 addition to the @option{-misel} option.
17052 The following built-in functions are available on Linux 64-bit systems
17053 that use the ISA 3.0 instruction set (@option{-mcpu=power9}):
17056 @item __float128 __builtin_addf128_round_to_odd (__float128, __float128)
17057 Perform a 128-bit IEEE floating point add using round to odd as the
17059 @findex __builtin_addf128_round_to_odd
17061 @item __float128 __builtin_subf128_round_to_odd (__float128, __float128)
17062 Perform a 128-bit IEEE floating point subtract using round to odd as
17064 @findex __builtin_subf128_round_to_odd
17066 @item __float128 __builtin_mulf128_round_to_odd (__float128, __float128)
17067 Perform a 128-bit IEEE floating point multiply using round to odd as
17069 @findex __builtin_mulf128_round_to_odd
17071 @item __float128 __builtin_divf128_round_to_odd (__float128, __float128)
17072 Perform a 128-bit IEEE floating point divide using round to odd as
17074 @findex __builtin_divf128_round_to_odd
17076 @item __float128 __builtin_sqrtf128_round_to_odd (__float128)
17077 Perform a 128-bit IEEE floating point square root using round to odd
17078 as the rounding mode.
17079 @findex __builtin_sqrtf128_round_to_odd
17081 @item __float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128)
17082 Perform a 128-bit IEEE floating point fused multiply and add operation
17083 using round to odd as the rounding mode.
17084 @findex __builtin_fmaf128_round_to_odd
17086 @item double __builtin_truncf128_round_to_odd (__float128)
17087 Convert a 128-bit IEEE floating point value to @code{double} using
17088 round to odd as the rounding mode.
17089 @findex __builtin_truncf128_round_to_odd
17092 The following additional built-in functions are also available for the
17093 PowerPC family of processors, starting with ISA 3.0 or later:
17095 long long __builtin_darn (void);
17096 long long __builtin_darn_raw (void);
17097 int __builtin_darn_32 (void);
17100 The @code{__builtin_darn} and @code{__builtin_darn_raw}
17101 functions require a
17102 64-bit environment supporting ISA 3.0 or later.
17103 The @code{__builtin_darn} function provides a 64-bit conditioned
17104 random number. The @code{__builtin_darn_raw} function provides a
17105 64-bit raw random number. The @code{__builtin_darn_32} function
17106 provides a 32-bit conditioned random number.
17108 The following additional built-in functions are also available for the
17109 PowerPC family of processors, starting with ISA 3.0 or later:
17112 int __builtin_byte_in_set (unsigned char u, unsigned long long set);
17113 int __builtin_byte_in_range (unsigned char u, unsigned int range);
17114 int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges);
17116 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value);
17117 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value);
17118 int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value);
17119 int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value);
17121 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value);
17122 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value);
17123 int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value);
17124 int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value);
17126 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value);
17127 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value);
17128 int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value);
17129 int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value);
17131 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value);
17132 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value);
17133 int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value);
17134 int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value);
17136 double __builtin_mffsl(void);
17139 The @code{__builtin_byte_in_set} function requires a
17140 64-bit environment supporting ISA 3.0 or later. This function returns
17141 a non-zero value if and only if its @code{u} argument exactly equals one of
17142 the eight bytes contained within its 64-bit @code{set} argument.
17144 The @code{__builtin_byte_in_range} and
17145 @code{__builtin_byte_in_either_range} require an environment
17146 supporting ISA 3.0 or later. For these two functions, the
17147 @code{range} argument is encoded as 4 bytes, organized as
17148 @code{hi_1:lo_1:hi_2:lo_2}.
17149 The @code{__builtin_byte_in_range} function returns a
17150 non-zero value if and only if its @code{u} argument is within the
17151 range bounded between @code{lo_2} and @code{hi_2} inclusive.
17152 The @code{__builtin_byte_in_either_range} function returns non-zero if
17153 and only if its @code{u} argument is within either the range bounded
17154 between @code{lo_1} and @code{hi_1} inclusive or the range bounded
17155 between @code{lo_2} and @code{hi_2} inclusive.
17157 The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value
17158 if and only if the number of signficant digits of its @code{value} argument
17159 is less than its @code{comparison} argument. The
17160 @code{__builtin_dfp_dtstsfi_lt_dd} and
17161 @code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but
17162 require that the type of the @code{value} argument be
17163 @code{__Decimal64} and @code{__Decimal128} respectively.
17165 The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value
17166 if and only if the number of signficant digits of its @code{value} argument
17167 is greater than its @code{comparison} argument. The
17168 @code{__builtin_dfp_dtstsfi_gt_dd} and
17169 @code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but
17170 require that the type of the @code{value} argument be
17171 @code{__Decimal64} and @code{__Decimal128} respectively.
17173 The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value
17174 if and only if the number of signficant digits of its @code{value} argument
17175 equals its @code{comparison} argument. The
17176 @code{__builtin_dfp_dtstsfi_eq_dd} and
17177 @code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but
17178 require that the type of the @code{value} argument be
17179 @code{__Decimal64} and @code{__Decimal128} respectively.
17181 The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value
17182 if and only if its @code{value} argument has an undefined number of
17183 significant digits, such as when @code{value} is an encoding of @code{NaN}.
17184 The @code{__builtin_dfp_dtstsfi_ov_dd} and
17185 @code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but
17186 require that the type of the @code{value} argument be
17187 @code{__Decimal64} and @code{__Decimal128} respectively.
17189 The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read
17190 the FPSCR. The instruction is a lower latency version of the @code{mffs}
17191 instruction. If the @code{mffsl} instruction is not available, then the
17192 builtin uses the older @code{mffs} instruction to read the FPSCR.
17195 @node PowerPC AltiVec/VSX Built-in Functions
17196 @subsection PowerPC AltiVec/VSX Built-in Functions
17198 GCC provides an interface for the PowerPC family of processors to access
17199 the AltiVec operations described in Motorola's AltiVec Programming
17200 Interface Manual. The interface is made available by including
17201 @code{<altivec.h>} and using @option{-maltivec} and
17202 @option{-mabi=altivec}. The interface supports the following vector
17206 vector unsigned char
17210 vector unsigned short
17211 vector signed short
17215 vector unsigned int
17221 GCC's implementation of the high-level language interface available from
17222 C and C++ code differs from Motorola's documentation in several ways.
17227 A vector constant is a list of constant expressions within curly braces.
17230 A vector initializer requires no cast if the vector constant is of the
17231 same type as the variable it is initializing.
17234 If @code{signed} or @code{unsigned} is omitted, the signedness of the
17235 vector type is the default signedness of the base type. The default
17236 varies depending on the operating system, so a portable program should
17237 always specify the signedness.
17240 Compiling with @option{-maltivec} adds keywords @code{__vector},
17241 @code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and
17242 @code{bool}. When compiling ISO C, the context-sensitive substitution
17243 of the keywords @code{vector}, @code{pixel} and @code{bool} is
17244 disabled. To use them, you must include @code{<altivec.h>} instead.
17247 GCC allows using a @code{typedef} name as the type specifier for a
17248 vector type, but only under the following circumstances:
17253 When using @code{__vector} instead of @code{vector}; for example,
17256 typedef signed short int16;
17257 __vector int16 data;
17261 When using @code{vector} in keyword-and-predefine mode; for example,
17264 typedef signed short int16;
17268 Note that keyword-and-predefine mode is enabled by disabling GNU
17269 extensions (e.g., by using @code{-std=c11}) and including
17270 @code{<altivec.h>}.
17274 For C, overloaded functions are implemented with macros so the following
17278 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo);
17282 Since @code{vec_add} is a macro, the vector constant in the example
17283 is treated as four separate arguments. Wrap the entire argument in
17284 parentheses for this to work.
17287 @emph{Note:} Only the @code{<altivec.h>} interface is supported.
17288 Internally, GCC uses built-in functions to achieve the functionality in
17289 the aforementioned header file, but they are not supported and are
17290 subject to change without notice.
17292 GCC complies with the OpenPOWER 64-Bit ELF V2 ABI Specification,
17293 which may be found at
17294 @uref{http://openpowerfoundation.org/wp-content/uploads/resources/leabi-prd/content/index.html}.
17295 Appendix A of this document lists the vector API interfaces that must be
17296 provided by compliant compilers. Programmers should preferentially use
17297 the interfaces described therein. However, historically GCC has provided
17298 additional interfaces for access to vector instructions. These are
17299 briefly described below.
17302 * PowerPC AltiVec Built-in Functions on ISA 2.05::
17303 * PowerPC AltiVec Built-in Functions Available on ISA 2.06::
17304 * PowerPC AltiVec Built-in Functions Available on ISA 2.07::
17305 * PowerPC AltiVec Built-in Functions Available on ISA 3.0::
17308 @node PowerPC AltiVec Built-in Functions on ISA 2.05
17309 @subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05
17311 The following interfaces are supported for the generic and specific
17312 AltiVec operations and the AltiVec predicates. In cases where there
17313 is a direct mapping between generic and specific operations, only the
17314 generic names are shown here, although the specific operations can also
17317 Arguments that are documented as @code{const int} require literal
17318 integral values within the range required for that operation.
17321 vector signed char vec_abs (vector signed char);
17322 vector signed short vec_abs (vector signed short);
17323 vector signed int vec_abs (vector signed int);
17324 vector float vec_abs (vector float);
17326 vector signed char vec_abss (vector signed char);
17327 vector signed short vec_abss (vector signed short);
17328 vector signed int vec_abss (vector signed int);
17330 vector signed char vec_add (vector bool char, vector signed char);
17331 vector signed char vec_add (vector signed char, vector bool char);
17332 vector signed char vec_add (vector signed char, vector signed char);
17333 vector unsigned char vec_add (vector bool char, vector unsigned char);
17334 vector unsigned char vec_add (vector unsigned char, vector bool char);
17335 vector unsigned char vec_add (vector unsigned char, vector unsigned char);
17336 vector signed short vec_add (vector bool short, vector signed short);
17337 vector signed short vec_add (vector signed short, vector bool short);
17338 vector signed short vec_add (vector signed short, vector signed short);
17339 vector unsigned short vec_add (vector bool short, vector unsigned short);
17340 vector unsigned short vec_add (vector unsigned short, vector bool short);
17341 vector unsigned short vec_add (vector unsigned short, vector unsigned short);
17342 vector signed int vec_add (vector bool int, vector signed int);
17343 vector signed int vec_add (vector signed int, vector bool int);
17344 vector signed int vec_add (vector signed int, vector signed int);
17345 vector unsigned int vec_add (vector bool int, vector unsigned int);
17346 vector unsigned int vec_add (vector unsigned int, vector bool int);
17347 vector unsigned int vec_add (vector unsigned int, vector unsigned int);
17348 vector float vec_add (vector float, vector float);
17350 vector unsigned int vec_addc (vector unsigned int, vector unsigned int);
17352 vector unsigned char vec_adds (vector bool char, vector unsigned char);
17353 vector unsigned char vec_adds (vector unsigned char, vector bool char);
17354 vector unsigned char vec_adds (vector unsigned char, vector unsigned char);
17355 vector signed char vec_adds (vector bool char, vector signed char);
17356 vector signed char vec_adds (vector signed char, vector bool char);
17357 vector signed char vec_adds (vector signed char, vector signed char);
17358 vector unsigned short vec_adds (vector bool short, vector unsigned short);
17359 vector unsigned short vec_adds (vector unsigned short, vector bool short);
17360 vector unsigned short vec_adds (vector unsigned short, vector unsigned short);
17361 vector signed short vec_adds (vector bool short, vector signed short);
17362 vector signed short vec_adds (vector signed short, vector bool short);
17363 vector signed short vec_adds (vector signed short, vector signed short);
17364 vector unsigned int vec_adds (vector bool int, vector unsigned int);
17365 vector unsigned int vec_adds (vector unsigned int, vector bool int);
17366 vector unsigned int vec_adds (vector unsigned int, vector unsigned int);
17367 vector signed int vec_adds (vector bool int, vector signed int);
17368 vector signed int vec_adds (vector signed int, vector bool int);
17369 vector signed int vec_adds (vector signed int, vector signed int);
17371 int vec_all_eq (vector signed char, vector bool char);
17372 int vec_all_eq (vector signed char, vector signed char);
17373 int vec_all_eq (vector unsigned char, vector bool char);
17374 int vec_all_eq (vector unsigned char, vector unsigned char);
17375 int vec_all_eq (vector bool char, vector bool char);
17376 int vec_all_eq (vector bool char, vector unsigned char);
17377 int vec_all_eq (vector bool char, vector signed char);
17378 int vec_all_eq (vector signed short, vector bool short);
17379 int vec_all_eq (vector signed short, vector signed short);
17380 int vec_all_eq (vector unsigned short, vector bool short);
17381 int vec_all_eq (vector unsigned short, vector unsigned short);
17382 int vec_all_eq (vector bool short, vector bool short);
17383 int vec_all_eq (vector bool short, vector unsigned short);
17384 int vec_all_eq (vector bool short, vector signed short);
17385 int vec_all_eq (vector pixel, vector pixel);
17386 int vec_all_eq (vector signed int, vector bool int);
17387 int vec_all_eq (vector signed int, vector signed int);
17388 int vec_all_eq (vector unsigned int, vector bool int);
17389 int vec_all_eq (vector unsigned int, vector unsigned int);
17390 int vec_all_eq (vector bool int, vector bool int);
17391 int vec_all_eq (vector bool int, vector unsigned int);
17392 int vec_all_eq (vector bool int, vector signed int);
17393 int vec_all_eq (vector float, vector float);
17395 int vec_all_ge (vector bool char, vector unsigned char);
17396 int vec_all_ge (vector unsigned char, vector bool char);
17397 int vec_all_ge (vector unsigned char, vector unsigned char);
17398 int vec_all_ge (vector bool char, vector signed char);
17399 int vec_all_ge (vector signed char, vector bool char);
17400 int vec_all_ge (vector signed char, vector signed char);
17401 int vec_all_ge (vector bool short, vector unsigned short);
17402 int vec_all_ge (vector unsigned short, vector bool short);
17403 int vec_all_ge (vector unsigned short, vector unsigned short);
17404 int vec_all_ge (vector signed short, vector signed short);
17405 int vec_all_ge (vector bool short, vector signed short);
17406 int vec_all_ge (vector signed short, vector bool short);
17407 int vec_all_ge (vector bool int, vector unsigned int);
17408 int vec_all_ge (vector unsigned int, vector bool int);
17409 int vec_all_ge (vector unsigned int, vector unsigned int);
17410 int vec_all_ge (vector bool int, vector signed int);
17411 int vec_all_ge (vector signed int, vector bool int);
17412 int vec_all_ge (vector signed int, vector signed int);
17413 int vec_all_ge (vector float, vector float);
17415 int vec_all_gt (vector bool char, vector unsigned char);
17416 int vec_all_gt (vector unsigned char, vector bool char);
17417 int vec_all_gt (vector unsigned char, vector unsigned char);
17418 int vec_all_gt (vector bool char, vector signed char);
17419 int vec_all_gt (vector signed char, vector bool char);
17420 int vec_all_gt (vector signed char, vector signed char);
17421 int vec_all_gt (vector bool short, vector unsigned short);
17422 int vec_all_gt (vector unsigned short, vector bool short);
17423 int vec_all_gt (vector unsigned short, vector unsigned short);
17424 int vec_all_gt (vector bool short, vector signed short);
17425 int vec_all_gt (vector signed short, vector bool short);
17426 int vec_all_gt (vector signed short, vector signed short);
17427 int vec_all_gt (vector bool int, vector unsigned int);
17428 int vec_all_gt (vector unsigned int, vector bool int);
17429 int vec_all_gt (vector unsigned int, vector unsigned int);
17430 int vec_all_gt (vector bool int, vector signed int);
17431 int vec_all_gt (vector signed int, vector bool int);
17432 int vec_all_gt (vector signed int, vector signed int);
17433 int vec_all_gt (vector float, vector float);
17435 int vec_all_in (vector float, vector float);
17437 int vec_all_le (vector bool char, vector unsigned char);
17438 int vec_all_le (vector unsigned char, vector bool char);
17439 int vec_all_le (vector unsigned char, vector unsigned char);
17440 int vec_all_le (vector bool char, vector signed char);
17441 int vec_all_le (vector signed char, vector bool char);
17442 int vec_all_le (vector signed char, vector signed char);
17443 int vec_all_le (vector bool short, vector unsigned short);
17444 int vec_all_le (vector unsigned short, vector bool short);
17445 int vec_all_le (vector unsigned short, vector unsigned short);
17446 int vec_all_le (vector bool short, vector signed short);
17447 int vec_all_le (vector signed short, vector bool short);
17448 int vec_all_le (vector signed short, vector signed short);
17449 int vec_all_le (vector bool int, vector unsigned int);
17450 int vec_all_le (vector unsigned int, vector bool int);
17451 int vec_all_le (vector unsigned int, vector unsigned int);
17452 int vec_all_le (vector bool int, vector signed int);
17453 int vec_all_le (vector signed int, vector bool int);
17454 int vec_all_le (vector signed int, vector signed int);
17455 int vec_all_le (vector float, vector float);
17457 int vec_all_lt (vector bool char, vector unsigned char);
17458 int vec_all_lt (vector unsigned char, vector bool char);
17459 int vec_all_lt (vector unsigned char, vector unsigned char);
17460 int vec_all_lt (vector bool char, vector signed char);
17461 int vec_all_lt (vector signed char, vector bool char);
17462 int vec_all_lt (vector signed char, vector signed char);
17463 int vec_all_lt (vector bool short, vector unsigned short);
17464 int vec_all_lt (vector unsigned short, vector bool short);
17465 int vec_all_lt (vector unsigned short, vector unsigned short);
17466 int vec_all_lt (vector bool short, vector signed short);
17467 int vec_all_lt (vector signed short, vector bool short);
17468 int vec_all_lt (vector signed short, vector signed short);
17469 int vec_all_lt (vector bool int, vector unsigned int);
17470 int vec_all_lt (vector unsigned int, vector bool int);
17471 int vec_all_lt (vector unsigned int, vector unsigned int);
17472 int vec_all_lt (vector bool int, vector signed int);
17473 int vec_all_lt (vector signed int, vector bool int);
17474 int vec_all_lt (vector signed int, vector signed int);
17475 int vec_all_lt (vector float, vector float);
17477 int vec_all_nan (vector float);
17479 int vec_all_ne (vector signed char, vector bool char);
17480 int vec_all_ne (vector signed char, vector signed char);
17481 int vec_all_ne (vector unsigned char, vector bool char);
17482 int vec_all_ne (vector unsigned char, vector unsigned char);
17483 int vec_all_ne (vector bool char, vector bool char);
17484 int vec_all_ne (vector bool char, vector unsigned char);
17485 int vec_all_ne (vector bool char, vector signed char);
17486 int vec_all_ne (vector signed short, vector bool short);
17487 int vec_all_ne (vector signed short, vector signed short);
17488 int vec_all_ne (vector unsigned short, vector bool short);
17489 int vec_all_ne (vector unsigned short, vector unsigned short);
17490 int vec_all_ne (vector bool short, vector bool short);
17491 int vec_all_ne (vector bool short, vector unsigned short);
17492 int vec_all_ne (vector bool short, vector signed short);
17493 int vec_all_ne (vector pixel, vector pixel);
17494 int vec_all_ne (vector signed int, vector bool int);
17495 int vec_all_ne (vector signed int, vector signed int);
17496 int vec_all_ne (vector unsigned int, vector bool int);
17497 int vec_all_ne (vector unsigned int, vector unsigned int);
17498 int vec_all_ne (vector bool int, vector bool int);
17499 int vec_all_ne (vector bool int, vector unsigned int);
17500 int vec_all_ne (vector bool int, vector signed int);
17501 int vec_all_ne (vector float, vector float);
17503 int vec_all_nge (vector float, vector float);
17505 int vec_all_ngt (vector float, vector float);
17507 int vec_all_nle (vector float, vector float);
17509 int vec_all_nlt (vector float, vector float);
17511 int vec_all_numeric (vector float);
17513 vector float vec_and (vector float, vector float);
17514 vector float vec_and (vector float, vector bool int);
17515 vector float vec_and (vector bool int, vector float);
17516 vector bool int vec_and (vector bool int, vector bool int);
17517 vector signed int vec_and (vector bool int, vector signed int);
17518 vector signed int vec_and (vector signed int, vector bool int);
17519 vector signed int vec_and (vector signed int, vector signed int);
17520 vector unsigned int vec_and (vector bool int, vector unsigned int);
17521 vector unsigned int vec_and (vector unsigned int, vector bool int);
17522 vector unsigned int vec_and (vector unsigned int, vector unsigned int);
17523 vector bool short vec_and (vector bool short, vector bool short);
17524 vector signed short vec_and (vector bool short, vector signed short);
17525 vector signed short vec_and (vector signed short, vector bool short);
17526 vector signed short vec_and (vector signed short, vector signed short);
17527 vector unsigned short vec_and (vector bool short, vector unsigned short);
17528 vector unsigned short vec_and (vector unsigned short, vector bool short);
17529 vector unsigned short vec_and (vector unsigned short, vector unsigned short);
17530 vector signed char vec_and (vector bool char, vector signed char);
17531 vector bool char vec_and (vector bool char, vector bool char);
17532 vector signed char vec_and (vector signed char, vector bool char);
17533 vector signed char vec_and (vector signed char, vector signed char);
17534 vector unsigned char vec_and (vector bool char, vector unsigned char);
17535 vector unsigned char vec_and (vector unsigned char, vector bool char);
17536 vector unsigned char vec_and (vector unsigned char, vector unsigned char);
17538 vector float vec_andc (vector float, vector float);
17539 vector float vec_andc (vector float, vector bool int);
17540 vector float vec_andc (vector bool int, vector float);
17541 vector bool int vec_andc (vector bool int, vector bool int);
17542 vector signed int vec_andc (vector bool int, vector signed int);
17543 vector signed int vec_andc (vector signed int, vector bool int);
17544 vector signed int vec_andc (vector signed int, vector signed int);
17545 vector unsigned int vec_andc (vector bool int, vector unsigned int);
17546 vector unsigned int vec_andc (vector unsigned int, vector bool int);
17547 vector unsigned int vec_andc (vector unsigned int, vector unsigned int);
17548 vector bool short vec_andc (vector bool short, vector bool short);
17549 vector signed short vec_andc (vector bool short, vector signed short);
17550 vector signed short vec_andc (vector signed short, vector bool short);
17551 vector signed short vec_andc (vector signed short, vector signed short);
17552 vector unsigned short vec_andc (vector bool short, vector unsigned short);
17553 vector unsigned short vec_andc (vector unsigned short, vector bool short);
17554 vector unsigned short vec_andc (vector unsigned short, vector unsigned short);
17555 vector signed char vec_andc (vector bool char, vector signed char);
17556 vector bool char vec_andc (vector bool char, vector bool char);
17557 vector signed char vec_andc (vector signed char, vector bool char);
17558 vector signed char vec_andc (vector signed char, vector signed char);
17559 vector unsigned char vec_andc (vector bool char, vector unsigned char);
17560 vector unsigned char vec_andc (vector unsigned char, vector bool char);
17561 vector unsigned char vec_andc (vector unsigned char, vector unsigned char);
17563 int vec_any_eq (vector signed char, vector bool char);
17564 int vec_any_eq (vector signed char, vector signed char);
17565 int vec_any_eq (vector unsigned char, vector bool char);
17566 int vec_any_eq (vector unsigned char, vector unsigned char);
17567 int vec_any_eq (vector bool char, vector bool char);
17568 int vec_any_eq (vector bool char, vector unsigned char);
17569 int vec_any_eq (vector bool char, vector signed char);
17570 int vec_any_eq (vector signed short, vector bool short);
17571 int vec_any_eq (vector signed short, vector signed short);
17572 int vec_any_eq (vector unsigned short, vector bool short);
17573 int vec_any_eq (vector unsigned short, vector unsigned short);
17574 int vec_any_eq (vector bool short, vector bool short);
17575 int vec_any_eq (vector bool short, vector unsigned short);
17576 int vec_any_eq (vector bool short, vector signed short);
17577 int vec_any_eq (vector pixel, vector pixel);
17578 int vec_any_eq (vector signed int, vector bool int);
17579 int vec_any_eq (vector signed int, vector signed int);
17580 int vec_any_eq (vector unsigned int, vector bool int);
17581 int vec_any_eq (vector unsigned int, vector unsigned int);
17582 int vec_any_eq (vector bool int, vector bool int);
17583 int vec_any_eq (vector bool int, vector unsigned int);
17584 int vec_any_eq (vector bool int, vector signed int);
17585 int vec_any_eq (vector float, vector float);
17587 int vec_any_ge (vector signed char, vector bool char);
17588 int vec_any_ge (vector unsigned char, vector bool char);
17589 int vec_any_ge (vector unsigned char, vector unsigned char);
17590 int vec_any_ge (vector signed char, vector signed char);
17591 int vec_any_ge (vector bool char, vector unsigned char);
17592 int vec_any_ge (vector bool char, vector signed char);
17593 int vec_any_ge (vector unsigned short, vector bool short);
17594 int vec_any_ge (vector unsigned short, vector unsigned short);
17595 int vec_any_ge (vector signed short, vector signed short);
17596 int vec_any_ge (vector signed short, vector bool short);
17597 int vec_any_ge (vector bool short, vector unsigned short);
17598 int vec_any_ge (vector bool short, vector signed short);
17599 int vec_any_ge (vector signed int, vector bool int);
17600 int vec_any_ge (vector unsigned int, vector bool int);
17601 int vec_any_ge (vector unsigned int, vector unsigned int);
17602 int vec_any_ge (vector signed int, vector signed int);
17603 int vec_any_ge (vector bool int, vector unsigned int);
17604 int vec_any_ge (vector bool int, vector signed int);
17605 int vec_any_ge (vector float, vector float);
17607 int vec_any_gt (vector bool char, vector unsigned char);
17608 int vec_any_gt (vector unsigned char, vector bool char);
17609 int vec_any_gt (vector unsigned char, vector unsigned char);
17610 int vec_any_gt (vector bool char, vector signed char);
17611 int vec_any_gt (vector signed char, vector bool char);
17612 int vec_any_gt (vector signed char, vector signed char);
17613 int vec_any_gt (vector bool short, vector unsigned short);
17614 int vec_any_gt (vector unsigned short, vector bool short);
17615 int vec_any_gt (vector unsigned short, vector unsigned short);
17616 int vec_any_gt (vector bool short, vector signed short);
17617 int vec_any_gt (vector signed short, vector bool short);
17618 int vec_any_gt (vector signed short, vector signed short);
17619 int vec_any_gt (vector bool int, vector unsigned int);
17620 int vec_any_gt (vector unsigned int, vector bool int);
17621 int vec_any_gt (vector unsigned int, vector unsigned int);
17622 int vec_any_gt (vector bool int, vector signed int);
17623 int vec_any_gt (vector signed int, vector bool int);
17624 int vec_any_gt (vector signed int, vector signed int);
17625 int vec_any_gt (vector float, vector float);
17627 int vec_any_le (vector bool char, vector unsigned char);
17628 int vec_any_le (vector unsigned char, vector bool char);
17629 int vec_any_le (vector unsigned char, vector unsigned char);
17630 int vec_any_le (vector bool char, vector signed char);
17631 int vec_any_le (vector signed char, vector bool char);
17632 int vec_any_le (vector signed char, vector signed char);
17633 int vec_any_le (vector bool short, vector unsigned short);
17634 int vec_any_le (vector unsigned short, vector bool short);
17635 int vec_any_le (vector unsigned short, vector unsigned short);
17636 int vec_any_le (vector bool short, vector signed short);
17637 int vec_any_le (vector signed short, vector bool short);
17638 int vec_any_le (vector signed short, vector signed short);
17639 int vec_any_le (vector bool int, vector unsigned int);
17640 int vec_any_le (vector unsigned int, vector bool int);
17641 int vec_any_le (vector unsigned int, vector unsigned int);
17642 int vec_any_le (vector bool int, vector signed int);
17643 int vec_any_le (vector signed int, vector bool int);
17644 int vec_any_le (vector signed int, vector signed int);
17645 int vec_any_le (vector float, vector float);
17647 int vec_any_lt (vector bool char, vector unsigned char);
17648 int vec_any_lt (vector unsigned char, vector bool char);
17649 int vec_any_lt (vector unsigned char, vector unsigned char);
17650 int vec_any_lt (vector bool char, vector signed char);
17651 int vec_any_lt (vector signed char, vector bool char);
17652 int vec_any_lt (vector signed char, vector signed char);
17653 int vec_any_lt (vector bool short, vector unsigned short);
17654 int vec_any_lt (vector unsigned short, vector bool short);
17655 int vec_any_lt (vector unsigned short, vector unsigned short);
17656 int vec_any_lt (vector bool short, vector signed short);
17657 int vec_any_lt (vector signed short, vector bool short);
17658 int vec_any_lt (vector signed short, vector signed short);
17659 int vec_any_lt (vector bool int, vector unsigned int);
17660 int vec_any_lt (vector unsigned int, vector bool int);
17661 int vec_any_lt (vector unsigned int, vector unsigned int);
17662 int vec_any_lt (vector bool int, vector signed int);
17663 int vec_any_lt (vector signed int, vector bool int);
17664 int vec_any_lt (vector signed int, vector signed int);
17665 int vec_any_lt (vector float, vector float);
17667 int vec_any_nan (vector float);
17669 int vec_any_ne (vector signed char, vector bool char);
17670 int vec_any_ne (vector signed char, vector signed char);
17671 int vec_any_ne (vector unsigned char, vector bool char);
17672 int vec_any_ne (vector unsigned char, vector unsigned char);
17673 int vec_any_ne (vector bool char, vector bool char);
17674 int vec_any_ne (vector bool char, vector unsigned char);
17675 int vec_any_ne (vector bool char, vector signed char);
17676 int vec_any_ne (vector signed short, vector bool short);
17677 int vec_any_ne (vector signed short, vector signed short);
17678 int vec_any_ne (vector unsigned short, vector bool short);
17679 int vec_any_ne (vector unsigned short, vector unsigned short);
17680 int vec_any_ne (vector bool short, vector bool short);
17681 int vec_any_ne (vector bool short, vector unsigned short);
17682 int vec_any_ne (vector bool short, vector signed short);
17683 int vec_any_ne (vector pixel, vector pixel);
17684 int vec_any_ne (vector signed int, vector bool int);
17685 int vec_any_ne (vector signed int, vector signed int);
17686 int vec_any_ne (vector unsigned int, vector bool int);
17687 int vec_any_ne (vector unsigned int, vector unsigned int);
17688 int vec_any_ne (vector bool int, vector bool int);
17689 int vec_any_ne (vector bool int, vector unsigned int);
17690 int vec_any_ne (vector bool int, vector signed int);
17691 int vec_any_ne (vector float, vector float);
17693 int vec_any_nge (vector float, vector float);
17695 int vec_any_ngt (vector float, vector float);
17697 int vec_any_nle (vector float, vector float);
17699 int vec_any_nlt (vector float, vector float);
17701 int vec_any_numeric (vector float);
17703 int vec_any_out (vector float, vector float);
17705 vector unsigned char vec_avg (vector unsigned char, vector unsigned char);
17706 vector signed char vec_avg (vector signed char, vector signed char);
17707 vector unsigned short vec_avg (vector unsigned short, vector unsigned short);
17708 vector signed short vec_avg (vector signed short, vector signed short);
17709 vector unsigned int vec_avg (vector unsigned int, vector unsigned int);
17710 vector signed int vec_avg (vector signed int, vector signed int);
17712 vector float vec_ceil (vector float);
17714 vector signed int vec_cmpb (vector float, vector float);
17716 vector bool char vec_cmpeq (vector bool char, vector bool char);
17717 vector bool short vec_cmpeq (vector bool short, vector bool short);
17718 vector bool int vec_cmpeq (vector bool int, vector bool int);
17719 vector bool char vec_cmpeq (vector signed char, vector signed char);
17720 vector bool char vec_cmpeq (vector unsigned char, vector unsigned char);
17721 vector bool short vec_cmpeq (vector signed short, vector signed short);
17722 vector bool short vec_cmpeq (vector unsigned short, vector unsigned short);
17723 vector bool int vec_cmpeq (vector signed int, vector signed int);
17724 vector bool int vec_cmpeq (vector unsigned int, vector unsigned int);
17725 vector bool int vec_cmpeq (vector float, vector float);
17727 vector bool int vec_cmpge (vector float, vector float);
17729 vector bool char vec_cmpgt (vector unsigned char, vector unsigned char);
17730 vector bool char vec_cmpgt (vector signed char, vector signed char);
17731 vector bool short vec_cmpgt (vector unsigned short, vector unsigned short);
17732 vector bool short vec_cmpgt (vector signed short, vector signed short);
17733 vector bool int vec_cmpgt (vector unsigned int, vector unsigned int);
17734 vector bool int vec_cmpgt (vector signed int, vector signed int);
17735 vector bool int vec_cmpgt (vector float, vector float);
17737 vector bool int vec_cmple (vector float, vector float);
17739 vector bool char vec_cmplt (vector unsigned char, vector unsigned char);
17740 vector bool char vec_cmplt (vector signed char, vector signed char);
17741 vector bool short vec_cmplt (vector unsigned short, vector unsigned short);
17742 vector bool short vec_cmplt (vector signed short, vector signed short);
17743 vector bool int vec_cmplt (vector unsigned int, vector unsigned int);
17744 vector bool int vec_cmplt (vector signed int, vector signed int);
17745 vector bool int vec_cmplt (vector float, vector float);
17747 vector float vec_cpsgn (vector float, vector float);
17749 vector float vec_ctf (vector unsigned int, const int);
17750 vector float vec_ctf (vector signed int, const int);
17752 vector signed int vec_cts (vector float, const int);
17754 vector unsigned int vec_ctu (vector float, const int);
17756 void vec_dss (const int);
17758 void vec_dssall (void);
17760 void vec_dst (const vector unsigned char *, int, const int);
17761 void vec_dst (const vector signed char *, int, const int);
17762 void vec_dst (const vector bool char *, int, const int);
17763 void vec_dst (const vector unsigned short *, int, const int);
17764 void vec_dst (const vector signed short *, int, const int);
17765 void vec_dst (const vector bool short *, int, const int);
17766 void vec_dst (const vector pixel *, int, const int);
17767 void vec_dst (const vector unsigned int *, int, const int);
17768 void vec_dst (const vector signed int *, int, const int);
17769 void vec_dst (const vector bool int *, int, const int);
17770 void vec_dst (const vector float *, int, const int);
17771 void vec_dst (const unsigned char *, int, const int);
17772 void vec_dst (const signed char *, int, const int);
17773 void vec_dst (const unsigned short *, int, const int);
17774 void vec_dst (const short *, int, const int);
17775 void vec_dst (const unsigned int *, int, const int);
17776 void vec_dst (const int *, int, const int);
17777 void vec_dst (const float *, int, const int);
17779 void vec_dstst (const vector unsigned char *, int, const int);
17780 void vec_dstst (const vector signed char *, int, const int);
17781 void vec_dstst (const vector bool char *, int, const int);
17782 void vec_dstst (const vector unsigned short *, int, const int);
17783 void vec_dstst (const vector signed short *, int, const int);
17784 void vec_dstst (const vector bool short *, int, const int);
17785 void vec_dstst (const vector pixel *, int, const int);
17786 void vec_dstst (const vector unsigned int *, int, const int);
17787 void vec_dstst (const vector signed int *, int, const int);
17788 void vec_dstst (const vector bool int *, int, const int);
17789 void vec_dstst (const vector float *, int, const int);
17790 void vec_dstst (const unsigned char *, int, const int);
17791 void vec_dstst (const signed char *, int, const int);
17792 void vec_dstst (const unsigned short *, int, const int);
17793 void vec_dstst (const short *, int, const int);
17794 void vec_dstst (const unsigned int *, int, const int);
17795 void vec_dstst (const int *, int, const int);
17796 void vec_dstst (const unsigned long *, int, const int);
17797 void vec_dstst (const long *, int, const int);
17798 void vec_dstst (const float *, int, const int);
17800 void vec_dststt (const vector unsigned char *, int, const int);
17801 void vec_dststt (const vector signed char *, int, const int);
17802 void vec_dststt (const vector bool char *, int, const int);
17803 void vec_dststt (const vector unsigned short *, int, const int);
17804 void vec_dststt (const vector signed short *, int, const int);
17805 void vec_dststt (const vector bool short *, int, const int);
17806 void vec_dststt (const vector pixel *, int, const int);
17807 void vec_dststt (const vector unsigned int *, int, const int);
17808 void vec_dststt (const vector signed int *, int, const int);
17809 void vec_dststt (const vector bool int *, int, const int);
17810 void vec_dststt (const vector float *, int, const int);
17811 void vec_dststt (const unsigned char *, int, const int);
17812 void vec_dststt (const signed char *, int, const int);
17813 void vec_dststt (const unsigned short *, int, const int);
17814 void vec_dststt (const short *, int, const int);
17815 void vec_dststt (const unsigned int *, int, const int);
17816 void vec_dststt (const int *, int, const int);
17817 void vec_dststt (const float *, int, const int);
17819 void vec_dstt (const vector unsigned char *, int, const int);
17820 void vec_dstt (const vector signed char *, int, const int);
17821 void vec_dstt (const vector bool char *, int, const int);
17822 void vec_dstt (const vector unsigned short *, int, const int);
17823 void vec_dstt (const vector signed short *, int, const int);
17824 void vec_dstt (const vector bool short *, int, const int);
17825 void vec_dstt (const vector pixel *, int, const int);
17826 void vec_dstt (const vector unsigned int *, int, const int);
17827 void vec_dstt (const vector signed int *, int, const int);
17828 void vec_dstt (const vector bool int *, int, const int);
17829 void vec_dstt (const vector float *, int, const int);
17830 void vec_dstt (const unsigned char *, int, const int);
17831 void vec_dstt (const signed char *, int, const int);
17832 void vec_dstt (const unsigned short *, int, const int);
17833 void vec_dstt (const short *, int, const int);
17834 void vec_dstt (const unsigned int *, int, const int);
17835 void vec_dstt (const int *, int, const int);
17836 void vec_dstt (const float *, int, const int);
17838 vector float vec_expte (vector float);
17840 vector float vec_floor (vector float);
17842 vector float vec_ld (int, const vector float *);
17843 vector float vec_ld (int, const float *);
17844 vector bool int vec_ld (int, const vector bool int *);
17845 vector signed int vec_ld (int, const vector signed int *);
17846 vector signed int vec_ld (int, const int *);
17847 vector unsigned int vec_ld (int, const vector unsigned int *);
17848 vector unsigned int vec_ld (int, const unsigned int *);
17849 vector bool short vec_ld (int, const vector bool short *);
17850 vector pixel vec_ld (int, const vector pixel *);
17851 vector signed short vec_ld (int, const vector signed short *);
17852 vector signed short vec_ld (int, const short *);
17853 vector unsigned short vec_ld (int, const vector unsigned short *);
17854 vector unsigned short vec_ld (int, const unsigned short *);
17855 vector bool char vec_ld (int, const vector bool char *);
17856 vector signed char vec_ld (int, const vector signed char *);
17857 vector signed char vec_ld (int, const signed char *);
17858 vector unsigned char vec_ld (int, const vector unsigned char *);
17859 vector unsigned char vec_ld (int, const unsigned char *);
17861 vector signed char vec_lde (int, const signed char *);
17862 vector unsigned char vec_lde (int, const unsigned char *);
17863 vector signed short vec_lde (int, const short *);
17864 vector unsigned short vec_lde (int, const unsigned short *);
17865 vector float vec_lde (int, const float *);
17866 vector signed int vec_lde (int, const int *);
17867 vector unsigned int vec_lde (int, const unsigned int *);
17869 vector float vec_ldl (int, const vector float *);
17870 vector float vec_ldl (int, const float *);
17871 vector bool int vec_ldl (int, const vector bool int *);
17872 vector signed int vec_ldl (int, const vector signed int *);
17873 vector signed int vec_ldl (int, const int *);
17874 vector unsigned int vec_ldl (int, const vector unsigned int *);
17875 vector unsigned int vec_ldl (int, const unsigned int *);
17876 vector bool short vec_ldl (int, const vector bool short *);
17877 vector pixel vec_ldl (int, const vector pixel *);
17878 vector signed short vec_ldl (int, const vector signed short *);
17879 vector signed short vec_ldl (int, const short *);
17880 vector unsigned short vec_ldl (int, const vector unsigned short *);
17881 vector unsigned short vec_ldl (int, const unsigned short *);
17882 vector bool char vec_ldl (int, const vector bool char *);
17883 vector signed char vec_ldl (int, const vector signed char *);
17884 vector signed char vec_ldl (int, const signed char *);
17885 vector unsigned char vec_ldl (int, const vector unsigned char *);
17886 vector unsigned char vec_ldl (int, const unsigned char *);
17888 vector float vec_loge (vector float);
17890 vector signed char vec_lvebx (int, char *);
17891 vector unsigned char vec_lvebx (int, unsigned char *);
17893 vector signed short vec_lvehx (int, short *);
17894 vector unsigned short vec_lvehx (int, unsigned short *);
17896 vector float vec_lvewx (int, float *);
17897 vector signed int vec_lvewx (int, int *);
17898 vector unsigned int vec_lvewx (int, unsigned int *);
17900 vector unsigned char vec_lvsl (int, const unsigned char *);
17901 vector unsigned char vec_lvsl (int, const signed char *);
17902 vector unsigned char vec_lvsl (int, const unsigned short *);
17903 vector unsigned char vec_lvsl (int, const short *);
17904 vector unsigned char vec_lvsl (int, const unsigned int *);
17905 vector unsigned char vec_lvsl (int, const int *);
17906 vector unsigned char vec_lvsl (int, const float *);
17908 vector unsigned char vec_lvsr (int, const unsigned char *);
17909 vector unsigned char vec_lvsr (int, const signed char *);
17910 vector unsigned char vec_lvsr (int, const unsigned short *);
17911 vector unsigned char vec_lvsr (int, const short *);
17912 vector unsigned char vec_lvsr (int, const unsigned int *);
17913 vector unsigned char vec_lvsr (int, const int *);
17914 vector unsigned char vec_lvsr (int, const float *);
17916 vector float vec_madd (vector float, vector float, vector float);
17918 vector signed short vec_madds (vector signed short, vector signed short,
17919 vector signed short);
17921 vector unsigned char vec_max (vector bool char, vector unsigned char);
17922 vector unsigned char vec_max (vector unsigned char, vector bool char);
17923 vector unsigned char vec_max (vector unsigned char, vector unsigned char);
17924 vector signed char vec_max (vector bool char, vector signed char);
17925 vector signed char vec_max (vector signed char, vector bool char);
17926 vector signed char vec_max (vector signed char, vector signed char);
17927 vector unsigned short vec_max (vector bool short, vector unsigned short);
17928 vector unsigned short vec_max (vector unsigned short, vector bool short);
17929 vector unsigned short vec_max (vector unsigned short, vector unsigned short);
17930 vector signed short vec_max (vector bool short, vector signed short);
17931 vector signed short vec_max (vector signed short, vector bool short);
17932 vector signed short vec_max (vector signed short, vector signed short);
17933 vector unsigned int vec_max (vector bool int, vector unsigned int);
17934 vector unsigned int vec_max (vector unsigned int, vector bool int);
17935 vector unsigned int vec_max (vector unsigned int, vector unsigned int);
17936 vector signed int vec_max (vector bool int, vector signed int);
17937 vector signed int vec_max (vector signed int, vector bool int);
17938 vector signed int vec_max (vector signed int, vector signed int);
17939 vector float vec_max (vector float, vector float);
17941 vector bool char vec_mergeh (vector bool char, vector bool char);
17942 vector signed char vec_mergeh (vector signed char, vector signed char);
17943 vector unsigned char vec_mergeh (vector unsigned char, vector unsigned char);
17944 vector bool short vec_mergeh (vector bool short, vector bool short);
17945 vector pixel vec_mergeh (vector pixel, vector pixel);
17946 vector signed short vec_mergeh (vector signed short, vector signed short);
17947 vector unsigned short vec_mergeh (vector unsigned short, vector unsigned short);
17948 vector float vec_mergeh (vector float, vector float);
17949 vector bool int vec_mergeh (vector bool int, vector bool int);
17950 vector signed int vec_mergeh (vector signed int, vector signed int);
17951 vector unsigned int vec_mergeh (vector unsigned int, vector unsigned int);
17953 vector bool char vec_mergel (vector bool char, vector bool char);
17954 vector signed char vec_mergel (vector signed char, vector signed char);
17955 vector unsigned char vec_mergel (vector unsigned char, vector unsigned char);
17956 vector bool short vec_mergel (vector bool short, vector bool short);
17957 vector pixel vec_mergel (vector pixel, vector pixel);
17958 vector signed short vec_mergel (vector signed short, vector signed short);
17959 vector unsigned short vec_mergel (vector unsigned short, vector unsigned short);
17960 vector float vec_mergel (vector float, vector float);
17961 vector bool int vec_mergel (vector bool int, vector bool int);
17962 vector signed int vec_mergel (vector signed int, vector signed int);
17963 vector unsigned int vec_mergel (vector unsigned int, vector unsigned int);
17965 vector unsigned short vec_mfvscr (void);
17967 vector unsigned char vec_min (vector bool char, vector unsigned char);
17968 vector unsigned char vec_min (vector unsigned char, vector bool char);
17969 vector unsigned char vec_min (vector unsigned char, vector unsigned char);
17970 vector signed char vec_min (vector bool char, vector signed char);
17971 vector signed char vec_min (vector signed char, vector bool char);
17972 vector signed char vec_min (vector signed char, vector signed char);
17973 vector unsigned short vec_min (vector bool short, vector unsigned short);
17974 vector unsigned short vec_min (vector unsigned short, vector bool short);
17975 vector unsigned short vec_min (vector unsigned short, vector unsigned short);
17976 vector signed short vec_min (vector bool short, vector signed short);
17977 vector signed short vec_min (vector signed short, vector bool short);
17978 vector signed short vec_min (vector signed short, vector signed short);
17979 vector unsigned int vec_min (vector bool int, vector unsigned int);
17980 vector unsigned int vec_min (vector unsigned int, vector bool int);
17981 vector unsigned int vec_min (vector unsigned int, vector unsigned int);
17982 vector signed int vec_min (vector bool int, vector signed int);
17983 vector signed int vec_min (vector signed int, vector bool int);
17984 vector signed int vec_min (vector signed int, vector signed int);
17985 vector float vec_min (vector float, vector float);
17987 vector signed short vec_mladd (vector signed short, vector signed short,
17988 vector signed short);
17989 vector signed short vec_mladd (vector signed short, vector unsigned short,
17990 vector unsigned short);
17991 vector signed short vec_mladd (vector unsigned short, vector signed short,
17992 vector signed short);
17993 vector unsigned short vec_mladd (vector unsigned short, vector unsigned short,
17994 vector unsigned short);
17996 vector signed short vec_mradds (vector signed short, vector signed short,
17997 vector signed short);
17999 vector unsigned int vec_msum (vector unsigned char, vector unsigned char,
18000 vector unsigned int);
18001 vector signed int vec_msum (vector signed char, vector unsigned char,
18002 vector signed int);
18003 vector unsigned int vec_msum (vector unsigned short, vector unsigned short,
18004 vector unsigned int);
18005 vector signed int vec_msum (vector signed short, vector signed short,
18006 vector signed int);
18008 vector unsigned int vec_msums (vector unsigned short, vector unsigned short,
18009 vector unsigned int);
18010 vector signed int vec_msums (vector signed short, vector signed short,
18011 vector signed int);
18013 void vec_mtvscr (vector signed int);
18014 void vec_mtvscr (vector unsigned int);
18015 void vec_mtvscr (vector bool int);
18016 void vec_mtvscr (vector signed short);
18017 void vec_mtvscr (vector unsigned short);
18018 void vec_mtvscr (vector bool short);
18019 void vec_mtvscr (vector pixel);
18020 void vec_mtvscr (vector signed char);
18021 void vec_mtvscr (vector unsigned char);
18022 void vec_mtvscr (vector bool char);
18024 vector float vec_mul (vector float, vector float);
18026 vector unsigned short vec_mule (vector unsigned char, vector unsigned char);
18027 vector signed short vec_mule (vector signed char, vector signed char);
18028 vector unsigned int vec_mule (vector unsigned short, vector unsigned short);
18029 vector signed int vec_mule (vector signed short, vector signed short);
18031 vector unsigned short vec_mulo (vector unsigned char, vector unsigned char);
18032 vector signed short vec_mulo (vector signed char, vector signed char);
18033 vector unsigned int vec_mulo (vector unsigned short, vector unsigned short);
18034 vector signed int vec_mulo (vector signed short, vector signed short);
18036 vector signed char vec_nabs (vector signed char);
18037 vector signed short vec_nabs (vector signed short);
18038 vector signed int vec_nabs (vector signed int);
18039 vector float vec_nabs (vector float);
18041 vector float vec_nmsub (vector float, vector float, vector float);
18043 vector float vec_nor (vector float, vector float);
18044 vector signed int vec_nor (vector signed int, vector signed int);
18045 vector unsigned int vec_nor (vector unsigned int, vector unsigned int);
18046 vector bool int vec_nor (vector bool int, vector bool int);
18047 vector signed short vec_nor (vector signed short, vector signed short);
18048 vector unsigned short vec_nor (vector unsigned short, vector unsigned short);
18049 vector bool short vec_nor (vector bool short, vector bool short);
18050 vector signed char vec_nor (vector signed char, vector signed char);
18051 vector unsigned char vec_nor (vector unsigned char, vector unsigned char);
18052 vector bool char vec_nor (vector bool char, vector bool char);
18054 vector float vec_or (vector float, vector float);
18055 vector float vec_or (vector float, vector bool int);
18056 vector float vec_or (vector bool int, vector float);
18057 vector bool int vec_or (vector bool int, vector bool int);
18058 vector signed int vec_or (vector bool int, vector signed int);
18059 vector signed int vec_or (vector signed int, vector bool int);
18060 vector signed int vec_or (vector signed int, vector signed int);
18061 vector unsigned int vec_or (vector bool int, vector unsigned int);
18062 vector unsigned int vec_or (vector unsigned int, vector bool int);
18063 vector unsigned int vec_or (vector unsigned int, vector unsigned int);
18064 vector bool short vec_or (vector bool short, vector bool short);
18065 vector signed short vec_or (vector bool short, vector signed short);
18066 vector signed short vec_or (vector signed short, vector bool short);
18067 vector signed short vec_or (vector signed short, vector signed short);
18068 vector unsigned short vec_or (vector bool short, vector unsigned short);
18069 vector unsigned short vec_or (vector unsigned short, vector bool short);
18070 vector unsigned short vec_or (vector unsigned short, vector unsigned short);
18071 vector signed char vec_or (vector bool char, vector signed char);
18072 vector bool char vec_or (vector bool char, vector bool char);
18073 vector signed char vec_or (vector signed char, vector bool char);
18074 vector signed char vec_or (vector signed char, vector signed char);
18075 vector unsigned char vec_or (vector bool char, vector unsigned char);
18076 vector unsigned char vec_or (vector unsigned char, vector bool char);
18077 vector unsigned char vec_or (vector unsigned char, vector unsigned char);
18079 vector signed char vec_pack (vector signed short, vector signed short);
18080 vector unsigned char vec_pack (vector unsigned short, vector unsigned short);
18081 vector bool char vec_pack (vector bool short, vector bool short);
18082 vector signed short vec_pack (vector signed int, vector signed int);
18083 vector unsigned short vec_pack (vector unsigned int, vector unsigned int);
18084 vector bool short vec_pack (vector bool int, vector bool int);
18086 vector pixel vec_packpx (vector unsigned int, vector unsigned int);
18088 vector unsigned char vec_packs (vector unsigned short, vector unsigned short);
18089 vector signed char vec_packs (vector signed short, vector signed short);
18090 vector unsigned short vec_packs (vector unsigned int, vector unsigned int);
18091 vector signed short vec_packs (vector signed int, vector signed int);
18093 vector unsigned char vec_packsu (vector unsigned short, vector unsigned short);
18094 vector unsigned char vec_packsu (vector signed short, vector signed short);
18095 vector unsigned short vec_packsu (vector unsigned int, vector unsigned int);
18096 vector unsigned short vec_packsu (vector signed int, vector signed int);
18098 vector float vec_perm (vector float, vector float, vector unsigned char);
18099 vector signed int vec_perm (vector signed int, vector signed int, vector unsigned char);
18100 vector unsigned int vec_perm (vector unsigned int, vector unsigned int,
18101 vector unsigned char);
18102 vector bool int vec_perm (vector bool int, vector bool int, vector unsigned char);
18103 vector signed short vec_perm (vector signed short, vector signed short,
18104 vector unsigned char);
18105 vector unsigned short vec_perm (vector unsigned short, vector unsigned short,
18106 vector unsigned char);
18107 vector bool short vec_perm (vector bool short, vector bool short, vector unsigned char);
18108 vector pixel vec_perm (vector pixel, vector pixel, vector unsigned char);
18109 vector signed char vec_perm (vector signed char, vector signed char,
18110 vector unsigned char);
18111 vector unsigned char vec_perm (vector unsigned char, vector unsigned char,
18112 vector unsigned char);
18113 vector bool char vec_perm (vector bool char, vector bool char, vector unsigned char);
18115 vector float vec_re (vector float);
18117 vector bool char vec_reve (vector bool char);
18118 vector signed char vec_reve (vector signed char);
18119 vector unsigned char vec_reve (vector unsigned char);
18120 vector bool int vec_reve (vector bool int);
18121 vector signed int vec_reve (vector signed int);
18122 vector unsigned int vec_reve (vector unsigned int);
18123 vector bool short vec_reve (vector bool short);
18124 vector signed short vec_reve (vector signed short);
18125 vector unsigned short vec_reve (vector unsigned short);
18127 vector signed char vec_rl (vector signed char, vector unsigned char);
18128 vector unsigned char vec_rl (vector unsigned char, vector unsigned char);
18129 vector signed short vec_rl (vector signed short, vector unsigned short);
18130 vector unsigned short vec_rl (vector unsigned short, vector unsigned short);
18131 vector signed int vec_rl (vector signed int, vector unsigned int);
18132 vector unsigned int vec_rl (vector unsigned int, vector unsigned int);
18134 vector float vec_round (vector float);
18136 vector float vec_rsqrt (vector float);
18138 vector float vec_rsqrte (vector float);
18140 vector float vec_sel (vector float, vector float, vector bool int);
18141 vector float vec_sel (vector float, vector float, vector unsigned int);
18142 vector signed int vec_sel (vector signed int, vector signed int, vector bool int);
18143 vector signed int vec_sel (vector signed int, vector signed int, vector unsigned int);
18144 vector unsigned int vec_sel (vector unsigned int, vector unsigned int, vector bool int);
18145 vector unsigned int vec_sel (vector unsigned int, vector unsigned int,
18146 vector unsigned int);
18147 vector bool int vec_sel (vector bool int, vector bool int, vector bool int);
18148 vector bool int vec_sel (vector bool int, vector bool int, vector unsigned int);
18149 vector signed short vec_sel (vector signed short, vector signed short,
18150 vector bool short);
18151 vector signed short vec_sel (vector signed short, vector signed short,
18152 vector unsigned short);
18153 vector unsigned short vec_sel (vector unsigned short, vector unsigned short,
18154 vector bool short);
18155 vector unsigned short vec_sel (vector unsigned short, vector unsigned short,
18156 vector unsigned short);
18157 vector bool short vec_sel (vector bool short, vector bool short, vector bool short);
18158 vector bool short vec_sel (vector bool short, vector bool short, vector unsigned short);
18159 vector signed char vec_sel (vector signed char, vector signed char, vector bool char);
18160 vector signed char vec_sel (vector signed char, vector signed char,
18161 vector unsigned char);
18162 vector unsigned char vec_sel (vector unsigned char, vector unsigned char,
18164 vector unsigned char vec_sel (vector unsigned char, vector unsigned char,
18165 vector unsigned char);
18166 vector bool char vec_sel (vector bool char, vector bool char, vector bool char);
18167 vector bool char vec_sel (vector bool char, vector bool char, vector unsigned char);
18169 vector signed char vec_sl (vector signed char, vector unsigned char);
18170 vector unsigned char vec_sl (vector unsigned char, vector unsigned char);
18171 vector signed short vec_sl (vector signed short, vector unsigned short);
18172 vector unsigned short vec_sl (vector unsigned short, vector unsigned short);
18173 vector signed int vec_sl (vector signed int, vector unsigned int);
18174 vector unsigned int vec_sl (vector unsigned int, vector unsigned int);
18176 vector float vec_sld (vector float, vector float, const int);
18177 vector signed int vec_sld (vector signed int, vector signed int, const int);
18178 vector unsigned int vec_sld (vector unsigned int, vector unsigned int, const int);
18179 vector bool int vec_sld (vector bool int, vector bool int, const int);
18180 vector signed short vec_sld (vector signed short, vector signed short, const int);
18181 vector unsigned short vec_sld (vector unsigned short, vector unsigned short, const int);
18182 vector bool short vec_sld (vector bool short, vector bool short, const int);
18183 vector pixel vec_sld (vector pixel, vector pixel, const int);
18184 vector signed char vec_sld (vector signed char, vector signed char, const int);
18185 vector unsigned char vec_sld (vector unsigned char, vector unsigned char, const int);
18186 vector bool char vec_sld (vector bool char, vector bool char, const int);
18188 vector signed int vec_sll (vector signed int, vector unsigned int);
18189 vector signed int vec_sll (vector signed int, vector unsigned short);
18190 vector signed int vec_sll (vector signed int, vector unsigned char);
18191 vector unsigned int vec_sll (vector unsigned int, vector unsigned int);
18192 vector unsigned int vec_sll (vector unsigned int, vector unsigned short);
18193 vector unsigned int vec_sll (vector unsigned int, vector unsigned char);
18194 vector bool int vec_sll (vector bool int, vector unsigned int);
18195 vector bool int vec_sll (vector bool int, vector unsigned short);
18196 vector bool int vec_sll (vector bool int, vector unsigned char);
18197 vector signed short vec_sll (vector signed short, vector unsigned int);
18198 vector signed short vec_sll (vector signed short, vector unsigned short);
18199 vector signed short vec_sll (vector signed short, vector unsigned char);
18200 vector unsigned short vec_sll (vector unsigned short, vector unsigned int);
18201 vector unsigned short vec_sll (vector unsigned short, vector unsigned short);
18202 vector unsigned short vec_sll (vector unsigned short, vector unsigned char);
18203 vector bool short vec_sll (vector bool short, vector unsigned int);
18204 vector bool short vec_sll (vector bool short, vector unsigned short);
18205 vector bool short vec_sll (vector bool short, vector unsigned char);
18206 vector pixel vec_sll (vector pixel, vector unsigned int);
18207 vector pixel vec_sll (vector pixel, vector unsigned short);
18208 vector pixel vec_sll (vector pixel, vector unsigned char);
18209 vector signed char vec_sll (vector signed char, vector unsigned int);
18210 vector signed char vec_sll (vector signed char, vector unsigned short);
18211 vector signed char vec_sll (vector signed char, vector unsigned char);
18212 vector unsigned char vec_sll (vector unsigned char, vector unsigned int);
18213 vector unsigned char vec_sll (vector unsigned char, vector unsigned short);
18214 vector unsigned char vec_sll (vector unsigned char, vector unsigned char);
18215 vector bool char vec_sll (vector bool char, vector unsigned int);
18216 vector bool char vec_sll (vector bool char, vector unsigned short);
18217 vector bool char vec_sll (vector bool char, vector unsigned char);
18219 vector float vec_slo (vector float, vector signed char);
18220 vector float vec_slo (vector float, vector unsigned char);
18221 vector signed int vec_slo (vector signed int, vector signed char);
18222 vector signed int vec_slo (vector signed int, vector unsigned char);
18223 vector unsigned int vec_slo (vector unsigned int, vector signed char);
18224 vector unsigned int vec_slo (vector unsigned int, vector unsigned char);
18225 vector signed short vec_slo (vector signed short, vector signed char);
18226 vector signed short vec_slo (vector signed short, vector unsigned char);
18227 vector unsigned short vec_slo (vector unsigned short, vector signed char);
18228 vector unsigned short vec_slo (vector unsigned short, vector unsigned char);
18229 vector pixel vec_slo (vector pixel, vector signed char);
18230 vector pixel vec_slo (vector pixel, vector unsigned char);
18231 vector signed char vec_slo (vector signed char, vector signed char);
18232 vector signed char vec_slo (vector signed char, vector unsigned char);
18233 vector unsigned char vec_slo (vector unsigned char, vector signed char);
18234 vector unsigned char vec_slo (vector unsigned char, vector unsigned char);
18236 vector signed char vec_splat (vector signed char, const int);
18237 vector unsigned char vec_splat (vector unsigned char, const int);
18238 vector bool char vec_splat (vector bool char, const int);
18239 vector signed short vec_splat (vector signed short, const int);
18240 vector unsigned short vec_splat (vector unsigned short, const int);
18241 vector bool short vec_splat (vector bool short, const int);
18242 vector pixel vec_splat (vector pixel, const int);
18243 vector float vec_splat (vector float, const int);
18244 vector signed int vec_splat (vector signed int, const int);
18245 vector unsigned int vec_splat (vector unsigned int, const int);
18246 vector bool int vec_splat (vector bool int, const int);
18248 vector signed short vec_splat_s16 (const int);
18250 vector signed int vec_splat_s32 (const int);
18252 vector signed char vec_splat_s8 (const int);
18254 vector unsigned short vec_splat_u16 (const int);
18256 vector unsigned int vec_splat_u32 (const int);
18258 vector unsigned char vec_splat_u8 (const int);
18260 vector signed char vec_splats (signed char);
18261 vector unsigned char vec_splats (unsigned char);
18262 vector signed short vec_splats (signed short);
18263 vector unsigned short vec_splats (unsigned short);
18264 vector signed int vec_splats (signed int);
18265 vector unsigned int vec_splats (unsigned int);
18266 vector float vec_splats (float);
18268 vector signed char vec_sr (vector signed char, vector unsigned char);
18269 vector unsigned char vec_sr (vector unsigned char, vector unsigned char);
18270 vector signed short vec_sr (vector signed short, vector unsigned short);
18271 vector unsigned short vec_sr (vector unsigned short, vector unsigned short);
18272 vector signed int vec_sr (vector signed int, vector unsigned int);
18273 vector unsigned int vec_sr (vector unsigned int, vector unsigned int);
18275 vector signed char vec_sra (vector signed char, vector unsigned char);
18276 vector unsigned char vec_sra (vector unsigned char, vector unsigned char);
18277 vector signed short vec_sra (vector signed short, vector unsigned short);
18278 vector unsigned short vec_sra (vector unsigned short, vector unsigned short);
18279 vector signed int vec_sra (vector signed int, vector unsigned int);
18280 vector unsigned int vec_sra (vector unsigned int, vector unsigned int);
18282 vector signed int vec_srl (vector signed int, vector unsigned int);
18283 vector signed int vec_srl (vector signed int, vector unsigned short);
18284 vector signed int vec_srl (vector signed int, vector unsigned char);
18285 vector unsigned int vec_srl (vector unsigned int, vector unsigned int);
18286 vector unsigned int vec_srl (vector unsigned int, vector unsigned short);
18287 vector unsigned int vec_srl (vector unsigned int, vector unsigned char);
18288 vector bool int vec_srl (vector bool int, vector unsigned int);
18289 vector bool int vec_srl (vector bool int, vector unsigned short);
18290 vector bool int vec_srl (vector bool int, vector unsigned char);
18291 vector signed short vec_srl (vector signed short, vector unsigned int);
18292 vector signed short vec_srl (vector signed short, vector unsigned short);
18293 vector signed short vec_srl (vector signed short, vector unsigned char);
18294 vector unsigned short vec_srl (vector unsigned short, vector unsigned int);
18295 vector unsigned short vec_srl (vector unsigned short, vector unsigned short);
18296 vector unsigned short vec_srl (vector unsigned short, vector unsigned char);
18297 vector bool short vec_srl (vector bool short, vector unsigned int);
18298 vector bool short vec_srl (vector bool short, vector unsigned short);
18299 vector bool short vec_srl (vector bool short, vector unsigned char);
18300 vector pixel vec_srl (vector pixel, vector unsigned int);
18301 vector pixel vec_srl (vector pixel, vector unsigned short);
18302 vector pixel vec_srl (vector pixel, vector unsigned char);
18303 vector signed char vec_srl (vector signed char, vector unsigned int);
18304 vector signed char vec_srl (vector signed char, vector unsigned short);
18305 vector signed char vec_srl (vector signed char, vector unsigned char);
18306 vector unsigned char vec_srl (vector unsigned char, vector unsigned int);
18307 vector unsigned char vec_srl (vector unsigned char, vector unsigned short);
18308 vector unsigned char vec_srl (vector unsigned char, vector unsigned char);
18309 vector bool char vec_srl (vector bool char, vector unsigned int);
18310 vector bool char vec_srl (vector bool char, vector unsigned short);
18311 vector bool char vec_srl (vector bool char, vector unsigned char);
18313 vector float vec_sro (vector float, vector signed char);
18314 vector float vec_sro (vector float, vector unsigned char);
18315 vector signed int vec_sro (vector signed int, vector signed char);
18316 vector signed int vec_sro (vector signed int, vector unsigned char);
18317 vector unsigned int vec_sro (vector unsigned int, vector signed char);
18318 vector unsigned int vec_sro (vector unsigned int, vector unsigned char);
18319 vector signed short vec_sro (vector signed short, vector signed char);
18320 vector signed short vec_sro (vector signed short, vector unsigned char);
18321 vector unsigned short vec_sro (vector unsigned short, vector signed char);
18322 vector unsigned short vec_sro (vector unsigned short, vector unsigned char);
18323 vector pixel vec_sro (vector pixel, vector signed char);
18324 vector pixel vec_sro (vector pixel, vector unsigned char);
18325 vector signed char vec_sro (vector signed char, vector signed char);
18326 vector signed char vec_sro (vector signed char, vector unsigned char);
18327 vector unsigned char vec_sro (vector unsigned char, vector signed char);
18328 vector unsigned char vec_sro (vector unsigned char, vector unsigned char);
18330 void vec_st (vector float, int, vector float *);
18331 void vec_st (vector float, int, float *);
18332 void vec_st (vector signed int, int, vector signed int *);
18333 void vec_st (vector signed int, int, int *);
18334 void vec_st (vector unsigned int, int, vector unsigned int *);
18335 void vec_st (vector unsigned int, int, unsigned int *);
18336 void vec_st (vector bool int, int, vector bool int *);
18337 void vec_st (vector bool int, int, unsigned int *);
18338 void vec_st (vector bool int, int, int *);
18339 void vec_st (vector signed short, int, vector signed short *);
18340 void vec_st (vector signed short, int, short *);
18341 void vec_st (vector unsigned short, int, vector unsigned short *);
18342 void vec_st (vector unsigned short, int, unsigned short *);
18343 void vec_st (vector bool short, int, vector bool short *);
18344 void vec_st (vector bool short, int, unsigned short *);
18345 void vec_st (vector pixel, int, vector pixel *);
18346 void vec_st (vector bool short, int, short *);
18347 void vec_st (vector signed char, int, vector signed char *);
18348 void vec_st (vector signed char, int, signed char *);
18349 void vec_st (vector unsigned char, int, vector unsigned char *);
18350 void vec_st (vector unsigned char, int, unsigned char *);
18351 void vec_st (vector bool char, int, vector bool char *);
18352 void vec_st (vector bool char, int, unsigned char *);
18353 void vec_st (vector bool char, int, signed char *);
18355 void vec_ste (vector signed char, int, signed char *);
18356 void vec_ste (vector unsigned char, int, unsigned char *);
18357 void vec_ste (vector bool char, int, signed char *);
18358 void vec_ste (vector bool char, int, unsigned char *);
18359 void vec_ste (vector signed short, int, short *);
18360 void vec_ste (vector unsigned short, int, unsigned short *);
18361 void vec_ste (vector bool short, int, short *);
18362 void vec_ste (vector bool short, int, unsigned short *);
18363 void vec_ste (vector pixel, int, short *);
18364 void vec_ste (vector pixel, int, unsigned short *);
18365 void vec_ste (vector float, int, float *);
18366 void vec_ste (vector signed int, int, int *);
18367 void vec_ste (vector unsigned int, int, unsigned int *);
18368 void vec_ste (vector bool int, int, int *);
18369 void vec_ste (vector bool int, int, unsigned int *);
18371 void vec_stl (vector float, int, vector float *);
18372 void vec_stl (vector float, int, float *);
18373 void vec_stl (vector signed int, int, vector signed int *);
18374 void vec_stl (vector signed int, int, int *);
18375 void vec_stl (vector unsigned int, int, vector unsigned int *);
18376 void vec_stl (vector unsigned int, int, unsigned int *);
18377 void vec_stl (vector bool int, int, vector bool int *);
18378 void vec_stl (vector bool int, int, unsigned int *);
18379 void vec_stl (vector bool int, int, int *);
18380 void vec_stl (vector signed short, int, vector signed short *);
18381 void vec_stl (vector signed short, int, short *);
18382 void vec_stl (vector unsigned short, int, vector unsigned short *);
18383 void vec_stl (vector unsigned short, int, unsigned short *);
18384 void vec_stl (vector bool short, int, vector bool short *);
18385 void vec_stl (vector bool short, int, unsigned short *);
18386 void vec_stl (vector bool short, int, short *);
18387 void vec_stl (vector pixel, int, vector pixel *);
18388 void vec_stl (vector signed char, int, vector signed char *);
18389 void vec_stl (vector signed char, int, signed char *);
18390 void vec_stl (vector unsigned char, int, vector unsigned char *);
18391 void vec_stl (vector unsigned char, int, unsigned char *);
18392 void vec_stl (vector bool char, int, vector bool char *);
18393 void vec_stl (vector bool char, int, unsigned char *);
18394 void vec_stl (vector bool char, int, signed char *);
18396 void vec_stvebx (vector signed char, int, signed char *);
18397 void vec_stvebx (vector unsigned char, int, unsigned char *);
18398 void vec_stvebx (vector bool char, int, signed char *);
18399 void vec_stvebx (vector bool char, int, unsigned char *);
18401 void vec_stvehx (vector signed short, int, short *);
18402 void vec_stvehx (vector unsigned short, int, unsigned short *);
18403 void vec_stvehx (vector bool short, int, short *);
18404 void vec_stvehx (vector bool short, int, unsigned short *);
18406 void vec_stvewx (vector float, int, float *);
18407 void vec_stvewx (vector signed int, int, int *);
18408 void vec_stvewx (vector unsigned int, int, unsigned int *);
18409 void vec_stvewx (vector bool int, int, int *);
18410 void vec_stvewx (vector bool int, int, unsigned int *);
18412 vector signed char vec_sub (vector bool char, vector signed char);
18413 vector signed char vec_sub (vector signed char, vector bool char);
18414 vector signed char vec_sub (vector signed char, vector signed char);
18415 vector unsigned char vec_sub (vector bool char, vector unsigned char);
18416 vector unsigned char vec_sub (vector unsigned char, vector bool char);
18417 vector unsigned char vec_sub (vector unsigned char, vector unsigned char);
18418 vector signed short vec_sub (vector bool short, vector signed short);
18419 vector signed short vec_sub (vector signed short, vector bool short);
18420 vector signed short vec_sub (vector signed short, vector signed short);
18421 vector unsigned short vec_sub (vector bool short, vector unsigned short);
18422 vector unsigned short vec_sub (vector unsigned short, vector bool short);
18423 vector unsigned short vec_sub (vector unsigned short, vector unsigned short);
18424 vector signed int vec_sub (vector bool int, vector signed int);
18425 vector signed int vec_sub (vector signed int, vector bool int);
18426 vector signed int vec_sub (vector signed int, vector signed int);
18427 vector unsigned int vec_sub (vector bool int, vector unsigned int);
18428 vector unsigned int vec_sub (vector unsigned int, vector bool int);
18429 vector unsigned int vec_sub (vector unsigned int, vector unsigned int);
18430 vector float vec_sub (vector float, vector float);
18432 vector signed int vec_subc (vector signed int, vector signed int);
18433 vector unsigned int vec_subc (vector unsigned int, vector unsigned int);
18435 vector signed int vec_sube (vector signed int, vector signed int,
18436 vector signed int);
18437 vector unsigned int vec_sube (vector unsigned int, vector unsigned int,
18438 vector unsigned int);
18440 vector signed int vec_subec (vector signed int, vector signed int,
18441 vector signed int);
18442 vector unsigned int vec_subec (vector unsigned int, vector unsigned int,
18443 vector unsigned int);
18445 vector unsigned char vec_subs (vector bool char, vector unsigned char);
18446 vector unsigned char vec_subs (vector unsigned char, vector bool char);
18447 vector unsigned char vec_subs (vector unsigned char, vector unsigned char);
18448 vector signed char vec_subs (vector bool char, vector signed char);
18449 vector signed char vec_subs (vector signed char, vector bool char);
18450 vector signed char vec_subs (vector signed char, vector signed char);
18451 vector unsigned short vec_subs (vector bool short, vector unsigned short);
18452 vector unsigned short vec_subs (vector unsigned short, vector bool short);
18453 vector unsigned short vec_subs (vector unsigned short, vector unsigned short);
18454 vector signed short vec_subs (vector bool short, vector signed short);
18455 vector signed short vec_subs (vector signed short, vector bool short);
18456 vector signed short vec_subs (vector signed short, vector signed short);
18457 vector unsigned int vec_subs (vector bool int, vector unsigned int);
18458 vector unsigned int vec_subs (vector unsigned int, vector bool int);
18459 vector unsigned int vec_subs (vector unsigned int, vector unsigned int);
18460 vector signed int vec_subs (vector bool int, vector signed int);
18461 vector signed int vec_subs (vector signed int, vector bool int);
18462 vector signed int vec_subs (vector signed int, vector signed int);
18464 vector signed int vec_sum2s (vector signed int, vector signed int);
18466 vector unsigned int vec_sum4s (vector unsigned char, vector unsigned int);
18467 vector signed int vec_sum4s (vector signed char, vector signed int);
18468 vector signed int vec_sum4s (vector signed short, vector signed int);
18470 vector signed int vec_sums (vector signed int, vector signed int);
18472 vector float vec_trunc (vector float);
18474 vector signed short vec_unpackh (vector signed char);
18475 vector bool short vec_unpackh (vector bool char);
18476 vector signed int vec_unpackh (vector signed short);
18477 vector bool int vec_unpackh (vector bool short);
18478 vector unsigned int vec_unpackh (vector pixel);
18480 vector signed short vec_unpackl (vector signed char);
18481 vector bool short vec_unpackl (vector bool char);
18482 vector unsigned int vec_unpackl (vector pixel);
18483 vector signed int vec_unpackl (vector signed short);
18484 vector bool int vec_unpackl (vector bool short);
18486 vector float vec_vaddfp (vector float, vector float);
18488 vector signed char vec_vaddsbs (vector bool char, vector signed char);
18489 vector signed char vec_vaddsbs (vector signed char, vector bool char);
18490 vector signed char vec_vaddsbs (vector signed char, vector signed char);
18492 vector signed short vec_vaddshs (vector bool short, vector signed short);
18493 vector signed short vec_vaddshs (vector signed short, vector bool short);
18494 vector signed short vec_vaddshs (vector signed short, vector signed short);
18496 vector signed int vec_vaddsws (vector bool int, vector signed int);
18497 vector signed int vec_vaddsws (vector signed int, vector bool int);
18498 vector signed int vec_vaddsws (vector signed int, vector signed int);
18500 vector signed char vec_vaddubm (vector bool char, vector signed char);
18501 vector signed char vec_vaddubm (vector signed char, vector bool char);
18502 vector signed char vec_vaddubm (vector signed char, vector signed char);
18503 vector unsigned char vec_vaddubm (vector bool char, vector unsigned char);
18504 vector unsigned char vec_vaddubm (vector unsigned char, vector bool char);
18505 vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char);
18507 vector unsigned char vec_vaddubs (vector bool char, vector unsigned char);
18508 vector unsigned char vec_vaddubs (vector unsigned char, vector bool char);
18509 vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char);
18511 vector signed short vec_vadduhm (vector bool short, vector signed short);
18512 vector signed short vec_vadduhm (vector signed short, vector bool short);
18513 vector signed short vec_vadduhm (vector signed short, vector signed short);
18514 vector unsigned short vec_vadduhm (vector bool short, vector unsigned short);
18515 vector unsigned short vec_vadduhm (vector unsigned short, vector bool short);
18516 vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short);
18518 vector unsigned short vec_vadduhs (vector bool short, vector unsigned short);
18519 vector unsigned short vec_vadduhs (vector unsigned short, vector bool short);
18520 vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short);
18522 vector signed int vec_vadduwm (vector bool int, vector signed int);
18523 vector signed int vec_vadduwm (vector signed int, vector bool int);
18524 vector signed int vec_vadduwm (vector signed int, vector signed int);
18525 vector unsigned int vec_vadduwm (vector bool int, vector unsigned int);
18526 vector unsigned int vec_vadduwm (vector unsigned int, vector bool int);
18527 vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int);
18529 vector unsigned int vec_vadduws (vector bool int, vector unsigned int);
18530 vector unsigned int vec_vadduws (vector unsigned int, vector bool int);
18531 vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int);
18533 vector signed char vec_vavgsb (vector signed char, vector signed char);
18535 vector signed short vec_vavgsh (vector signed short, vector signed short);
18537 vector signed int vec_vavgsw (vector signed int, vector signed int);
18539 vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char);
18541 vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short);
18543 vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int);
18545 vector float vec_vcfsx (vector signed int, const int);
18547 vector float vec_vcfux (vector unsigned int, const int);
18549 vector bool int vec_vcmpeqfp (vector float, vector float);
18551 vector bool char vec_vcmpequb (vector signed char, vector signed char);
18552 vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char);
18554 vector bool short vec_vcmpequh (vector signed short, vector signed short);
18555 vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short);
18557 vector bool int vec_vcmpequw (vector signed int, vector signed int);
18558 vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int);
18560 vector bool int vec_vcmpgtfp (vector float, vector float);
18562 vector bool char vec_vcmpgtsb (vector signed char, vector signed char);
18564 vector bool short vec_vcmpgtsh (vector signed short, vector signed short);
18566 vector bool int vec_vcmpgtsw (vector signed int, vector signed int);
18568 vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char);
18570 vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short);
18572 vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int);
18574 vector float vec_vmaxfp (vector float, vector float);
18576 vector signed char vec_vmaxsb (vector bool char, vector signed char);
18577 vector signed char vec_vmaxsb (vector signed char, vector bool char);
18578 vector signed char vec_vmaxsb (vector signed char, vector signed char);
18580 vector signed short vec_vmaxsh (vector bool short, vector signed short);
18581 vector signed short vec_vmaxsh (vector signed short, vector bool short);
18582 vector signed short vec_vmaxsh (vector signed short, vector signed short);
18584 vector signed int vec_vmaxsw (vector bool int, vector signed int);
18585 vector signed int vec_vmaxsw (vector signed int, vector bool int);
18586 vector signed int vec_vmaxsw (vector signed int, vector signed int);
18588 vector unsigned char vec_vmaxub (vector bool char, vector unsigned char);
18589 vector unsigned char vec_vmaxub (vector unsigned char, vector bool char);
18590 vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char);
18592 vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short);
18593 vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short);
18594 vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short);
18596 vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int);
18597 vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int);
18598 vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int);
18600 vector float vec_vminfp (vector float, vector float);
18602 vector signed char vec_vminsb (vector bool char, vector signed char);
18603 vector signed char vec_vminsb (vector signed char, vector bool char);
18604 vector signed char vec_vminsb (vector signed char, vector signed char);
18606 vector signed short vec_vminsh (vector bool short, vector signed short);
18607 vector signed short vec_vminsh (vector signed short, vector bool short);
18608 vector signed short vec_vminsh (vector signed short, vector signed short);
18610 vector signed int vec_vminsw (vector bool int, vector signed int);
18611 vector signed int vec_vminsw (vector signed int, vector bool int);
18612 vector signed int vec_vminsw (vector signed int, vector signed int);
18614 vector unsigned char vec_vminub (vector bool char, vector unsigned char);
18615 vector unsigned char vec_vminub (vector unsigned char, vector bool char);
18616 vector unsigned char vec_vminub (vector unsigned char, vector unsigned char);
18618 vector unsigned short vec_vminuh (vector bool short, vector unsigned short);
18619 vector unsigned short vec_vminuh (vector unsigned short, vector bool short);
18620 vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short);
18622 vector unsigned int vec_vminuw (vector bool int, vector unsigned int);
18623 vector unsigned int vec_vminuw (vector unsigned int, vector bool int);
18624 vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int);
18626 vector bool char vec_vmrghb (vector bool char, vector bool char);
18627 vector signed char vec_vmrghb (vector signed char, vector signed char);
18628 vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char);
18630 vector bool short vec_vmrghh (vector bool short, vector bool short);
18631 vector signed short vec_vmrghh (vector signed short, vector signed short);
18632 vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short);
18633 vector pixel vec_vmrghh (vector pixel, vector pixel);
18635 vector float vec_vmrghw (vector float, vector float);
18636 vector bool int vec_vmrghw (vector bool int, vector bool int);
18637 vector signed int vec_vmrghw (vector signed int, vector signed int);
18638 vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int);
18640 vector bool char vec_vmrglb (vector bool char, vector bool char);
18641 vector signed char vec_vmrglb (vector signed char, vector signed char);
18642 vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char);
18644 vector bool short vec_vmrglh (vector bool short, vector bool short);
18645 vector signed short vec_vmrglh (vector signed short, vector signed short);
18646 vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short);
18647 vector pixel vec_vmrglh (vector pixel, vector pixel);
18649 vector float vec_vmrglw (vector float, vector float);
18650 vector signed int vec_vmrglw (vector signed int, vector signed int);
18651 vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int);
18652 vector bool int vec_vmrglw (vector bool int, vector bool int);
18654 vector signed int vec_vmsummbm (vector signed char, vector unsigned char,
18655 vector signed int);
18657 vector signed int vec_vmsumshm (vector signed short, vector signed short,
18658 vector signed int);
18660 vector signed int vec_vmsumshs (vector signed short, vector signed short,
18661 vector signed int);
18663 vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char,
18664 vector unsigned int);
18666 vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short,
18667 vector unsigned int);
18669 vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short,
18670 vector unsigned int);
18672 vector signed short vec_vmulesb (vector signed char, vector signed char);
18674 vector signed int vec_vmulesh (vector signed short, vector signed short);
18676 vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char);
18678 vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short);
18680 vector signed short vec_vmulosb (vector signed char, vector signed char);
18682 vector signed int vec_vmulosh (vector signed short, vector signed short);
18684 vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char);
18686 vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short);
18688 vector signed char vec_vpkshss (vector signed short, vector signed short);
18690 vector unsigned char vec_vpkshus (vector signed short, vector signed short);
18692 vector signed short vec_vpkswss (vector signed int, vector signed int);
18694 vector unsigned short vec_vpkswus (vector signed int, vector signed int);
18696 vector bool char vec_vpkuhum (vector bool short, vector bool short);
18697 vector signed char vec_vpkuhum (vector signed short, vector signed short);
18698 vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short);
18700 vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short);
18702 vector bool short vec_vpkuwum (vector bool int, vector bool int);
18703 vector signed short vec_vpkuwum (vector signed int, vector signed int);
18704 vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int);
18706 vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int);
18708 vector signed char vec_vrlb (vector signed char, vector unsigned char);
18709 vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char);
18711 vector signed short vec_vrlh (vector signed short, vector unsigned short);
18712 vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short);
18714 vector signed int vec_vrlw (vector signed int, vector unsigned int);
18715 vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int);
18717 vector signed char vec_vslb (vector signed char, vector unsigned char);
18718 vector unsigned char vec_vslb (vector unsigned char, vector unsigned char);
18720 vector signed short vec_vslh (vector signed short, vector unsigned short);
18721 vector unsigned short vec_vslh (vector unsigned short, vector unsigned short);
18723 vector signed int vec_vslw (vector signed int, vector unsigned int);
18724 vector unsigned int vec_vslw (vector unsigned int, vector unsigned int);
18726 vector signed char vec_vspltb (vector signed char, const int);
18727 vector unsigned char vec_vspltb (vector unsigned char, const int);
18728 vector bool char vec_vspltb (vector bool char, const int);
18730 vector bool short vec_vsplth (vector bool short, const int);
18731 vector signed short vec_vsplth (vector signed short, const int);
18732 vector unsigned short vec_vsplth (vector unsigned short, const int);
18733 vector pixel vec_vsplth (vector pixel, const int);
18735 vector float vec_vspltw (vector float, const int);
18736 vector signed int vec_vspltw (vector signed int, const int);
18737 vector unsigned int vec_vspltw (vector unsigned int, const int);
18738 vector bool int vec_vspltw (vector bool int, const int);
18740 vector signed char vec_vsrab (vector signed char, vector unsigned char);
18741 vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char);
18743 vector signed short vec_vsrah (vector signed short, vector unsigned short);
18744 vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short);
18746 vector signed int vec_vsraw (vector signed int, vector unsigned int);
18747 vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int);
18749 vector signed char vec_vsrb (vector signed char, vector unsigned char);
18750 vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char);
18752 vector signed short vec_vsrh (vector signed short, vector unsigned short);
18753 vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short);
18755 vector signed int vec_vsrw (vector signed int, vector unsigned int);
18756 vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int);
18758 vector float vec_vsubfp (vector float, vector float);
18760 vector signed char vec_vsubsbs (vector bool char, vector signed char);
18761 vector signed char vec_vsubsbs (vector signed char, vector bool char);
18762 vector signed char vec_vsubsbs (vector signed char, vector signed char);
18764 vector signed short vec_vsubshs (vector bool short, vector signed short);
18765 vector signed short vec_vsubshs (vector signed short, vector bool short);
18766 vector signed short vec_vsubshs (vector signed short, vector signed short);
18768 vector signed int vec_vsubsws (vector bool int, vector signed int);
18769 vector signed int vec_vsubsws (vector signed int, vector bool int);
18770 vector signed int vec_vsubsws (vector signed int, vector signed int);
18772 vector signed char vec_vsububm (vector bool char, vector signed char);
18773 vector signed char vec_vsububm (vector signed char, vector bool char);
18774 vector signed char vec_vsububm (vector signed char, vector signed char);
18775 vector unsigned char vec_vsububm (vector bool char, vector unsigned char);
18776 vector unsigned char vec_vsububm (vector unsigned char, vector bool char);
18777 vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char);
18779 vector unsigned char vec_vsububs (vector bool char, vector unsigned char);
18780 vector unsigned char vec_vsububs (vector unsigned char, vector bool char);
18781 vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char);
18783 vector signed short vec_vsubuhm (vector bool short, vector signed short);
18784 vector signed short vec_vsubuhm (vector signed short, vector bool short);
18785 vector signed short vec_vsubuhm (vector signed short, vector signed short);
18786 vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short);
18787 vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short);
18788 vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short);
18790 vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short);
18791 vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short);
18792 vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short);
18794 vector signed int vec_vsubuwm (vector bool int, vector signed int);
18795 vector signed int vec_vsubuwm (vector signed int, vector bool int);
18796 vector signed int vec_vsubuwm (vector signed int, vector signed int);
18797 vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int);
18798 vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int);
18799 vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int);
18801 vector unsigned int vec_vsubuws (vector bool int, vector unsigned int);
18802 vector unsigned int vec_vsubuws (vector unsigned int, vector bool int);
18803 vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int);
18805 vector signed int vec_vsum4sbs (vector signed char, vector signed int);
18807 vector signed int vec_vsum4shs (vector signed short, vector signed int);
18809 vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int);
18811 vector unsigned int vec_vupkhpx (vector pixel);
18813 vector bool short vec_vupkhsb (vector bool char);
18814 vector signed short vec_vupkhsb (vector signed char);
18816 vector bool int vec_vupkhsh (vector bool short);
18817 vector signed int vec_vupkhsh (vector signed short);
18819 vector unsigned int vec_vupklpx (vector pixel);
18821 vector bool short vec_vupklsb (vector bool char);
18822 vector signed short vec_vupklsb (vector signed char);
18824 vector bool int vec_vupklsh (vector bool short);
18825 vector signed int vec_vupklsh (vector signed short);
18827 vector float vec_xor (vector float, vector float);
18828 vector float vec_xor (vector float, vector bool int);
18829 vector float vec_xor (vector bool int, vector float);
18830 vector bool int vec_xor (vector bool int, vector bool int);
18831 vector signed int vec_xor (vector bool int, vector signed int);
18832 vector signed int vec_xor (vector signed int, vector bool int);
18833 vector signed int vec_xor (vector signed int, vector signed int);
18834 vector unsigned int vec_xor (vector bool int, vector unsigned int);
18835 vector unsigned int vec_xor (vector unsigned int, vector bool int);
18836 vector unsigned int vec_xor (vector unsigned int, vector unsigned int);
18837 vector bool short vec_xor (vector bool short, vector bool short);
18838 vector signed short vec_xor (vector bool short, vector signed short);
18839 vector signed short vec_xor (vector signed short, vector bool short);
18840 vector signed short vec_xor (vector signed short, vector signed short);
18841 vector unsigned short vec_xor (vector bool short, vector unsigned short);
18842 vector unsigned short vec_xor (vector unsigned short, vector bool short);
18843 vector unsigned short vec_xor (vector unsigned short, vector unsigned short);
18844 vector signed char vec_xor (vector bool char, vector signed char);
18845 vector bool char vec_xor (vector bool char, vector bool char);
18846 vector signed char vec_xor (vector signed char, vector bool char);
18847 vector signed char vec_xor (vector signed char, vector signed char);
18848 vector unsigned char vec_xor (vector bool char, vector unsigned char);
18849 vector unsigned char vec_xor (vector unsigned char, vector bool char);
18850 vector unsigned char vec_xor (vector unsigned char, vector unsigned char);
18853 @node PowerPC AltiVec Built-in Functions Available on ISA 2.06
18854 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06
18856 The AltiVec built-in functions described in this section are
18857 available on the PowerPC family of processors starting with ISA 2.06
18858 or later. These are normally enabled by adding @option{-mvsx} to the
18861 When @option{-mvsx} is used, the following additional vector types are
18865 vector unsigned __int128
18866 vector signed __int128
18867 vector unsigned long long int
18868 vector signed long long int
18872 The long long types are only implemented for 64-bit code generation.
18876 vector bool long long vec_and (vector bool long long int, vector bool long long);
18878 vector double vec_ctf (vector unsigned long, const int);
18879 vector double vec_ctf (vector signed long, const int);
18881 vector signed long vec_cts (vector double, const int);
18883 vector unsigned long vec_ctu (vector double, const int);
18885 void vec_dst (const unsigned long *, int, const int);
18886 void vec_dst (const long *, int, const int);
18888 void vec_dststt (const unsigned long *, int, const int);
18889 void vec_dststt (const long *, int, const int);
18891 void vec_dstt (const unsigned long *, int, const int);
18892 void vec_dstt (const long *, int, const int);
18894 vector unsigned char vec_lvsl (int, const unsigned long *);
18895 vector unsigned char vec_lvsl (int, const long *);
18897 vector unsigned char vec_lvsr (int, const unsigned long *);
18898 vector unsigned char vec_lvsr (int, const long *);
18900 vector double vec_mul (vector double, vector double);
18901 vector long vec_mul (vector long, vector long);
18902 vector unsigned long vec_mul (vector unsigned long, vector unsigned long);
18904 vector unsigned long long vec_mule (vector unsigned int, vector unsigned int);
18905 vector signed long long vec_mule (vector signed int, vector signed int);
18907 vector unsigned long long vec_mulo (vector unsigned int, vector unsigned int);
18908 vector signed long long vec_mulo (vector signed int, vector signed int);
18910 vector double vec_nabs (vector double);
18912 vector bool long long vec_reve (vector bool long long);
18913 vector signed long long vec_reve (vector signed long long);
18914 vector unsigned long long vec_reve (vector unsigned long long);
18915 vector double vec_sld (vector double, vector double, const int);
18917 vector bool long long int vec_sld (vector bool long long int,
18918 vector bool long long int, const int);
18919 vector long long int vec_sld (vector long long int, vector long long int, const int);
18920 vector unsigned long long int vec_sld (vector unsigned long long int,
18921 vector unsigned long long int, const int);
18923 vector long long int vec_sll (vector long long int, vector unsigned char);
18924 vector unsigned long long int vec_sll (vector unsigned long long int,
18925 vector unsigned char);
18927 vector signed long long vec_slo (vector signed long long, vector signed char);
18928 vector signed long long vec_slo (vector signed long long, vector unsigned char);
18929 vector unsigned long long vec_slo (vector unsigned long long, vector signed char);
18930 vector unsigned long long vec_slo (vector unsigned long long, vector unsigned char);
18932 vector signed long vec_splat (vector signed long, const int);
18933 vector unsigned long vec_splat (vector unsigned long, const int);
18935 vector long long int vec_srl (vector long long int, vector unsigned char);
18936 vector unsigned long long int vec_srl (vector unsigned long long int,
18937 vector unsigned char);
18939 vector long long int vec_sro (vector long long int, vector char);
18940 vector long long int vec_sro (vector long long int, vector unsigned char);
18941 vector unsigned long long int vec_sro (vector unsigned long long int, vector char);
18942 vector unsigned long long int vec_sro (vector unsigned long long int,
18943 vector unsigned char);
18945 vector signed __int128 vec_subc (vector signed __int128, vector signed __int128);
18946 vector unsigned __int128 vec_subc (vector unsigned __int128, vector unsigned __int128);
18948 vector signed __int128 vec_sube (vector signed __int128, vector signed __int128,
18949 vector signed __int128);
18950 vector unsigned __int128 vec_sube (vector unsigned __int128, vector unsigned __int128,
18951 vector unsigned __int128);
18953 vector signed __int128 vec_subec (vector signed __int128, vector signed __int128,
18954 vector signed __int128);
18955 vector unsigned __int128 vec_subec (vector unsigned __int128, vector unsigned __int128,
18956 vector unsigned __int128);
18958 vector double vec_unpackh (vector float);
18960 vector double vec_unpackl (vector float);
18962 vector double vec_doublee (vector float);
18963 vector double vec_doublee (vector signed int);
18964 vector double vec_doublee (vector unsigned int);
18966 vector double vec_doubleo (vector float);
18967 vector double vec_doubleo (vector signed int);
18968 vector double vec_doubleo (vector unsigned int);
18970 vector double vec_doubleh (vector float);
18971 vector double vec_doubleh (vector signed int);
18972 vector double vec_doubleh (vector unsigned int);
18974 vector double vec_doublel (vector float);
18975 vector double vec_doublel (vector signed int);
18976 vector double vec_doublel (vector unsigned int);
18978 vector float vec_float (vector signed int);
18979 vector float vec_float (vector unsigned int);
18981 vector float vec_float2 (vector signed long long, vector signed long long);
18982 vector float vec_float2 (vector unsigned long long, vector signed long long);
18984 vector float vec_floate (vector double);
18985 vector float vec_floate (vector signed long long);
18986 vector float vec_floate (vector unsigned long long);
18988 vector float vec_floato (vector double);
18989 vector float vec_floato (vector signed long long);
18990 vector float vec_floato (vector unsigned long long);
18992 vector signed long long vec_signed (vector double);
18993 vector signed int vec_signed (vector float);
18995 vector signed int vec_signede (vector double);
18997 vector signed int vec_signedo (vector double);
18999 vector signed char vec_sldw (vector signed char, vector signed char, const int);
19000 vector unsigned char vec_sldw (vector unsigned char, vector unsigned char, const int);
19001 vector signed short vec_sldw (vector signed short, vector signed short, const int);
19002 vector unsigned short vec_sldw (vector unsigned short,
19003 vector unsigned short, const int);
19004 vector signed int vec_sldw (vector signed int, vector signed int, const int);
19005 vector unsigned int vec_sldw (vector unsigned int, vector unsigned int, const int);
19006 vector signed long long vec_sldw (vector signed long long,
19007 vector signed long long, const int);
19008 vector unsigned long long vec_sldw (vector unsigned long long,
19009 vector unsigned long long, const int);
19011 vector signed long long vec_unsigned (vector double);
19012 vector signed int vec_unsigned (vector float);
19014 vector signed int vec_unsignede (vector double);
19016 vector signed int vec_unsignedo (vector double);
19018 vector double vec_abs (vector double);
19019 vector double vec_add (vector double, vector double);
19020 vector double vec_and (vector double, vector double);
19021 vector double vec_and (vector double, vector bool long);
19022 vector double vec_and (vector bool long, vector double);
19023 vector long vec_and (vector long, vector long);
19024 vector long vec_and (vector long, vector bool long);
19025 vector long vec_and (vector bool long, vector long);
19026 vector unsigned long vec_and (vector unsigned long, vector unsigned long);
19027 vector unsigned long vec_and (vector unsigned long, vector bool long);
19028 vector unsigned long vec_and (vector bool long, vector unsigned long);
19029 vector double vec_andc (vector double, vector double);
19030 vector double vec_andc (vector double, vector bool long);
19031 vector double vec_andc (vector bool long, vector double);
19032 vector long vec_andc (vector long, vector long);
19033 vector long vec_andc (vector long, vector bool long);
19034 vector long vec_andc (vector bool long, vector long);
19035 vector unsigned long vec_andc (vector unsigned long, vector unsigned long);
19036 vector unsigned long vec_andc (vector unsigned long, vector bool long);
19037 vector unsigned long vec_andc (vector bool long, vector unsigned long);
19038 vector double vec_ceil (vector double);
19039 vector bool long vec_cmpeq (vector double, vector double);
19040 vector bool long vec_cmpge (vector double, vector double);
19041 vector bool long vec_cmpgt (vector double, vector double);
19042 vector bool long vec_cmple (vector double, vector double);
19043 vector bool long vec_cmplt (vector double, vector double);
19044 vector double vec_cpsgn (vector double, vector double);
19045 vector float vec_div (vector float, vector float);
19046 vector double vec_div (vector double, vector double);
19047 vector long vec_div (vector long, vector long);
19048 vector unsigned long vec_div (vector unsigned long, vector unsigned long);
19049 vector double vec_floor (vector double);
19050 vector signed long long vec_ld (int, const vector signed long long *);
19051 vector signed long long vec_ld (int, const signed long long *);
19052 vector unsigned long long vec_ld (int, const vector unsigned long long *);
19053 vector unsigned long long vec_ld (int, const unsigned long long *);
19054 vector __int128 vec_ld (int, const vector __int128 *);
19055 vector unsigned __int128 vec_ld (int, const vector unsigned __int128 *);
19056 vector __int128 vec_ld (int, const __int128 *);
19057 vector unsigned __int128 vec_ld (int, const unsigned __int128 *);
19058 vector double vec_ld (int, const vector double *);
19059 vector double vec_ld (int, const double *);
19060 vector double vec_ldl (int, const vector double *);
19061 vector double vec_ldl (int, const double *);
19062 vector unsigned char vec_lvsl (int, const double *);
19063 vector unsigned char vec_lvsr (int, const double *);
19064 vector double vec_madd (vector double, vector double, vector double);
19065 vector double vec_max (vector double, vector double);
19066 vector signed long vec_mergeh (vector signed long, vector signed long);
19067 vector signed long vec_mergeh (vector signed long, vector bool long);
19068 vector signed long vec_mergeh (vector bool long, vector signed long);
19069 vector unsigned long vec_mergeh (vector unsigned long, vector unsigned long);
19070 vector unsigned long vec_mergeh (vector unsigned long, vector bool long);
19071 vector unsigned long vec_mergeh (vector bool long, vector unsigned long);
19072 vector signed long vec_mergel (vector signed long, vector signed long);
19073 vector signed long vec_mergel (vector signed long, vector bool long);
19074 vector signed long vec_mergel (vector bool long, vector signed long);
19075 vector unsigned long vec_mergel (vector unsigned long, vector unsigned long);
19076 vector unsigned long vec_mergel (vector unsigned long, vector bool long);
19077 vector unsigned long vec_mergel (vector bool long, vector unsigned long);
19078 vector double vec_min (vector double, vector double);
19079 vector float vec_msub (vector float, vector float, vector float);
19080 vector double vec_msub (vector double, vector double, vector double);
19081 vector float vec_nearbyint (vector float);
19082 vector double vec_nearbyint (vector double);
19083 vector float vec_nmadd (vector float, vector float, vector float);
19084 vector double vec_nmadd (vector double, vector double, vector double);
19085 vector double vec_nmsub (vector double, vector double, vector double);
19086 vector double vec_nor (vector double, vector double);
19087 vector long vec_nor (vector long, vector long);
19088 vector long vec_nor (vector long, vector bool long);
19089 vector long vec_nor (vector bool long, vector long);
19090 vector unsigned long vec_nor (vector unsigned long, vector unsigned long);
19091 vector unsigned long vec_nor (vector unsigned long, vector bool long);
19092 vector unsigned long vec_nor (vector bool long, vector unsigned long);
19093 vector double vec_or (vector double, vector double);
19094 vector double vec_or (vector double, vector bool long);
19095 vector double vec_or (vector bool long, vector double);
19096 vector long vec_or (vector long, vector long);
19097 vector long vec_or (vector long, vector bool long);
19098 vector long vec_or (vector bool long, vector long);
19099 vector unsigned long vec_or (vector unsigned long, vector unsigned long);
19100 vector unsigned long vec_or (vector unsigned long, vector bool long);
19101 vector unsigned long vec_or (vector bool long, vector unsigned long);
19102 vector double vec_perm (vector double, vector double, vector unsigned char);
19103 vector long vec_perm (vector long, vector long, vector unsigned char);
19104 vector unsigned long vec_perm (vector unsigned long, vector unsigned long,
19105 vector unsigned char);
19106 vector bool char vec_permxor (vector bool char, vector bool char,
19108 vector unsigned char vec_permxor (vector signed char, vector signed char,
19109 vector signed char);
19110 vector unsigned char vec_permxor (vector unsigned char, vector unsigned char,
19111 vector unsigned char);
19112 vector double vec_rint (vector double);
19113 vector double vec_recip (vector double, vector double);
19114 vector double vec_rsqrt (vector double);
19115 vector double vec_rsqrte (vector double);
19116 vector double vec_sel (vector double, vector double, vector bool long);
19117 vector double vec_sel (vector double, vector double, vector unsigned long);
19118 vector long vec_sel (vector long, vector long, vector long);
19119 vector long vec_sel (vector long, vector long, vector unsigned long);
19120 vector long vec_sel (vector long, vector long, vector bool long);
19121 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19123 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19124 vector unsigned long);
19125 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19127 vector double vec_splats (double);
19128 vector signed long vec_splats (signed long);
19129 vector unsigned long vec_splats (unsigned long);
19130 vector float vec_sqrt (vector float);
19131 vector double vec_sqrt (vector double);
19132 void vec_st (vector signed long long, int, vector signed long long *);
19133 void vec_st (vector signed long long, int, signed long long *);
19134 void vec_st (vector unsigned long long, int, vector unsigned long long *);
19135 void vec_st (vector unsigned long long, int, unsigned long long *);
19136 void vec_st (vector bool long long, int, vector bool long long *);
19137 void vec_st (vector bool long long, int, signed long long *);
19138 void vec_st (vector bool long long, int, unsigned long long *);
19139 void vec_st (vector double, int, vector double *);
19140 void vec_st (vector double, int, double *);
19141 vector double vec_sub (vector double, vector double);
19142 vector double vec_trunc (vector double);
19143 vector double vec_xl (int, vector double *);
19144 vector double vec_xl (int, double *);
19145 vector long long vec_xl (int, vector long long *);
19146 vector long long vec_xl (int, long long *);
19147 vector unsigned long long vec_xl (int, vector unsigned long long *);
19148 vector unsigned long long vec_xl (int, unsigned long long *);
19149 vector float vec_xl (int, vector float *);
19150 vector float vec_xl (int, float *);
19151 vector int vec_xl (int, vector int *);
19152 vector int vec_xl (int, int *);
19153 vector unsigned int vec_xl (int, vector unsigned int *);
19154 vector unsigned int vec_xl (int, unsigned int *);
19155 vector double vec_xor (vector double, vector double);
19156 vector double vec_xor (vector double, vector bool long);
19157 vector double vec_xor (vector bool long, vector double);
19158 vector long vec_xor (vector long, vector long);
19159 vector long vec_xor (vector long, vector bool long);
19160 vector long vec_xor (vector bool long, vector long);
19161 vector unsigned long vec_xor (vector unsigned long, vector unsigned long);
19162 vector unsigned long vec_xor (vector unsigned long, vector bool long);
19163 vector unsigned long vec_xor (vector bool long, vector unsigned long);
19164 void vec_xst (vector double, int, vector double *);
19165 void vec_xst (vector double, int, double *);
19166 void vec_xst (vector long long, int, vector long long *);
19167 void vec_xst (vector long long, int, long long *);
19168 void vec_xst (vector unsigned long long, int, vector unsigned long long *);
19169 void vec_xst (vector unsigned long long, int, unsigned long long *);
19170 void vec_xst (vector float, int, vector float *);
19171 void vec_xst (vector float, int, float *);
19172 void vec_xst (vector int, int, vector int *);
19173 void vec_xst (vector int, int, int *);
19174 void vec_xst (vector unsigned int, int, vector unsigned int *);
19175 void vec_xst (vector unsigned int, int, unsigned int *);
19176 int vec_all_eq (vector double, vector double);
19177 int vec_all_ge (vector double, vector double);
19178 int vec_all_gt (vector double, vector double);
19179 int vec_all_le (vector double, vector double);
19180 int vec_all_lt (vector double, vector double);
19181 int vec_all_nan (vector double);
19182 int vec_all_ne (vector double, vector double);
19183 int vec_all_nge (vector double, vector double);
19184 int vec_all_ngt (vector double, vector double);
19185 int vec_all_nle (vector double, vector double);
19186 int vec_all_nlt (vector double, vector double);
19187 int vec_all_numeric (vector double);
19188 int vec_any_eq (vector double, vector double);
19189 int vec_any_ge (vector double, vector double);
19190 int vec_any_gt (vector double, vector double);
19191 int vec_any_le (vector double, vector double);
19192 int vec_any_lt (vector double, vector double);
19193 int vec_any_nan (vector double);
19194 int vec_any_ne (vector double, vector double);
19195 int vec_any_nge (vector double, vector double);
19196 int vec_any_ngt (vector double, vector double);
19197 int vec_any_nle (vector double, vector double);
19198 int vec_any_nlt (vector double, vector double);
19199 int vec_any_numeric (vector double);
19201 vector double vec_vsx_ld (int, const vector double *);
19202 vector double vec_vsx_ld (int, const double *);
19203 vector float vec_vsx_ld (int, const vector float *);
19204 vector float vec_vsx_ld (int, const float *);
19205 vector bool int vec_vsx_ld (int, const vector bool int *);
19206 vector signed int vec_vsx_ld (int, const vector signed int *);
19207 vector signed int vec_vsx_ld (int, const int *);
19208 vector signed int vec_vsx_ld (int, const long *);
19209 vector unsigned int vec_vsx_ld (int, const vector unsigned int *);
19210 vector unsigned int vec_vsx_ld (int, const unsigned int *);
19211 vector unsigned int vec_vsx_ld (int, const unsigned long *);
19212 vector bool short vec_vsx_ld (int, const vector bool short *);
19213 vector pixel vec_vsx_ld (int, const vector pixel *);
19214 vector signed short vec_vsx_ld (int, const vector signed short *);
19215 vector signed short vec_vsx_ld (int, const short *);
19216 vector unsigned short vec_vsx_ld (int, const vector unsigned short *);
19217 vector unsigned short vec_vsx_ld (int, const unsigned short *);
19218 vector bool char vec_vsx_ld (int, const vector bool char *);
19219 vector signed char vec_vsx_ld (int, const vector signed char *);
19220 vector signed char vec_vsx_ld (int, const signed char *);
19221 vector unsigned char vec_vsx_ld (int, const vector unsigned char *);
19222 vector unsigned char vec_vsx_ld (int, const unsigned char *);
19224 void vec_vsx_st (vector double, int, vector double *);
19225 void vec_vsx_st (vector double, int, double *);
19226 void vec_vsx_st (vector float, int, vector float *);
19227 void vec_vsx_st (vector float, int, float *);
19228 void vec_vsx_st (vector signed int, int, vector signed int *);
19229 void vec_vsx_st (vector signed int, int, int *);
19230 void vec_vsx_st (vector unsigned int, int, vector unsigned int *);
19231 void vec_vsx_st (vector unsigned int, int, unsigned int *);
19232 void vec_vsx_st (vector bool int, int, vector bool int *);
19233 void vec_vsx_st (vector bool int, int, unsigned int *);
19234 void vec_vsx_st (vector bool int, int, int *);
19235 void vec_vsx_st (vector signed short, int, vector signed short *);
19236 void vec_vsx_st (vector signed short, int, short *);
19237 void vec_vsx_st (vector unsigned short, int, vector unsigned short *);
19238 void vec_vsx_st (vector unsigned short, int, unsigned short *);
19239 void vec_vsx_st (vector bool short, int, vector bool short *);
19240 void vec_vsx_st (vector bool short, int, unsigned short *);
19241 void vec_vsx_st (vector pixel, int, vector pixel *);
19242 void vec_vsx_st (vector pixel, int, unsigned short *);
19243 void vec_vsx_st (vector pixel, int, short *);
19244 void vec_vsx_st (vector bool short, int, short *);
19245 void vec_vsx_st (vector signed char, int, vector signed char *);
19246 void vec_vsx_st (vector signed char, int, signed char *);
19247 void vec_vsx_st (vector unsigned char, int, vector unsigned char *);
19248 void vec_vsx_st (vector unsigned char, int, unsigned char *);
19249 void vec_vsx_st (vector bool char, int, vector bool char *);
19250 void vec_vsx_st (vector bool char, int, unsigned char *);
19251 void vec_vsx_st (vector bool char, int, signed char *);
19253 vector double vec_xxpermdi (vector double, vector double, const int);
19254 vector float vec_xxpermdi (vector float, vector float, const int);
19255 vector long long vec_xxpermdi (vector long long, vector long long, const int);
19256 vector unsigned long long vec_xxpermdi (vector unsigned long long,
19257 vector unsigned long long, const int);
19258 vector int vec_xxpermdi (vector int, vector int, const int);
19259 vector unsigned int vec_xxpermdi (vector unsigned int,
19260 vector unsigned int, const int);
19261 vector short vec_xxpermdi (vector short, vector short, const int);
19262 vector unsigned short vec_xxpermdi (vector unsigned short,
19263 vector unsigned short, const int);
19264 vector signed char vec_xxpermdi (vector signed char, vector signed char,
19266 vector unsigned char vec_xxpermdi (vector unsigned char,
19267 vector unsigned char, const int);
19269 vector double vec_xxsldi (vector double, vector double, int);
19270 vector float vec_xxsldi (vector float, vector float, int);
19271 vector long long vec_xxsldi (vector long long, vector long long, int);
19272 vector unsigned long long vec_xxsldi (vector unsigned long long,
19273 vector unsigned long long, int);
19274 vector int vec_xxsldi (vector int, vector int, int);
19275 vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int);
19276 vector short vec_xxsldi (vector short, vector short, int);
19277 vector unsigned short vec_xxsldi (vector unsigned short,
19278 vector unsigned short, int);
19279 vector signed char vec_xxsldi (vector signed char, vector signed char, int);
19280 vector unsigned char vec_xxsldi (vector unsigned char,
19281 vector unsigned char, int);
19284 Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always
19285 generate the AltiVec @samp{LVX} and @samp{STVX} instructions even
19286 if the VSX instruction set is available. The @samp{vec_vsx_ld} and
19287 @samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X},
19288 @samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions.
19290 @node PowerPC AltiVec Built-in Functions Available on ISA 2.07
19291 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07
19293 If the ISA 2.07 additions to the vector/scalar (power8-vector)
19294 instruction set are available, the following additional functions are
19295 available for both 32-bit and 64-bit targets. For 64-bit targets, you
19296 can use @var{vector long} instead of @var{vector long long},
19297 @var{vector bool long} instead of @var{vector bool long long}, and
19298 @var{vector unsigned long} instead of @var{vector unsigned long long}.
19301 vector signed char vec_neg (vector signed char);
19302 vector signed short vec_neg (vector signed short);
19303 vector signed int vec_neg (vector signed int);
19304 vector signed long long vec_neg (vector signed long long);
19305 vector float char vec_neg (vector float);
19306 vector double vec_neg (vector double);
19308 vector signed int vec_signed2 (vector double, vector double);
19310 vector signed int vec_unsigned2 (vector double, vector double);
19312 vector long long vec_abs (vector long long);
19314 vector long long vec_add (vector long long, vector long long);
19315 vector unsigned long long vec_add (vector unsigned long long,
19316 vector unsigned long long);
19318 int vec_all_eq (vector long long, vector long long);
19319 int vec_all_eq (vector unsigned long long, vector unsigned long long);
19320 int vec_all_ge (vector long long, vector long long);
19321 int vec_all_ge (vector unsigned long long, vector unsigned long long);
19322 int vec_all_gt (vector long long, vector long long);
19323 int vec_all_gt (vector unsigned long long, vector unsigned long long);
19324 int vec_all_le (vector long long, vector long long);
19325 int vec_all_le (vector unsigned long long, vector unsigned long long);
19326 int vec_all_lt (vector long long, vector long long);
19327 int vec_all_lt (vector unsigned long long, vector unsigned long long);
19328 int vec_all_ne (vector long long, vector long long);
19329 int vec_all_ne (vector unsigned long long, vector unsigned long long);
19331 int vec_any_eq (vector long long, vector long long);
19332 int vec_any_eq (vector unsigned long long, vector unsigned long long);
19333 int vec_any_ge (vector long long, vector long long);
19334 int vec_any_ge (vector unsigned long long, vector unsigned long long);
19335 int vec_any_gt (vector long long, vector long long);
19336 int vec_any_gt (vector unsigned long long, vector unsigned long long);
19337 int vec_any_le (vector long long, vector long long);
19338 int vec_any_le (vector unsigned long long, vector unsigned long long);
19339 int vec_any_lt (vector long long, vector long long);
19340 int vec_any_lt (vector unsigned long long, vector unsigned long long);
19341 int vec_any_ne (vector long long, vector long long);
19342 int vec_any_ne (vector unsigned long long, vector unsigned long long);
19344 vector bool long long vec_cmpeq (vector bool long long, vector bool long long);
19346 vector long long vec_eqv (vector long long, vector long long);
19347 vector long long vec_eqv (vector bool long long, vector long long);
19348 vector long long vec_eqv (vector long long, vector bool long long);
19349 vector unsigned long long vec_eqv (vector unsigned long long, vector unsigned long long);
19350 vector unsigned long long vec_eqv (vector bool long long, vector unsigned long long);
19351 vector unsigned long long vec_eqv (vector unsigned long long,
19352 vector bool long long);
19353 vector int vec_eqv (vector int, vector int);
19354 vector int vec_eqv (vector bool int, vector int);
19355 vector int vec_eqv (vector int, vector bool int);
19356 vector unsigned int vec_eqv (vector unsigned int, vector unsigned int);
19357 vector unsigned int vec_eqv (vector bool unsigned int, vector unsigned int);
19358 vector unsigned int vec_eqv (vector unsigned int, vector bool unsigned int);
19359 vector short vec_eqv (vector short, vector short);
19360 vector short vec_eqv (vector bool short, vector short);
19361 vector short vec_eqv (vector short, vector bool short);
19362 vector unsigned short vec_eqv (vector unsigned short, vector unsigned short);
19363 vector unsigned short vec_eqv (vector bool unsigned short, vector unsigned short);
19364 vector unsigned short vec_eqv (vector unsigned short, vector bool unsigned short);
19365 vector signed char vec_eqv (vector signed char, vector signed char);
19366 vector signed char vec_eqv (vector bool signed char, vector signed char);
19367 vector signed char vec_eqv (vector signed char, vector bool signed char);
19368 vector unsigned char vec_eqv (vector unsigned char, vector unsigned char);
19369 vector unsigned char vec_eqv (vector bool unsigned char, vector unsigned char);
19370 vector unsigned char vec_eqv (vector unsigned char, vector bool unsigned char);
19372 vector long long vec_max (vector long long, vector long long);
19373 vector unsigned long long vec_max (vector unsigned long long,
19374 vector unsigned long long);
19376 vector signed int vec_mergee (vector signed int, vector signed int);
19377 vector unsigned int vec_mergee (vector unsigned int, vector unsigned int);
19378 vector bool int vec_mergee (vector bool int, vector bool int);
19380 vector signed int vec_mergeo (vector signed int, vector signed int);
19381 vector unsigned int vec_mergeo (vector unsigned int, vector unsigned int);
19382 vector bool int vec_mergeo (vector bool int, vector bool int);
19384 vector long long vec_min (vector long long, vector long long);
19385 vector unsigned long long vec_min (vector unsigned long long,
19386 vector unsigned long long);
19388 vector signed long long vec_nabs (vector signed long long);
19390 vector long long vec_nand (vector long long, vector long long);
19391 vector long long vec_nand (vector bool long long, vector long long);
19392 vector long long vec_nand (vector long long, vector bool long long);
19393 vector unsigned long long vec_nand (vector unsigned long long,
19394 vector unsigned long long);
19395 vector unsigned long long vec_nand (vector bool long long, vector unsigned long long);
19396 vector unsigned long long vec_nand (vector unsigned long long, vector bool long long);
19397 vector int vec_nand (vector int, vector int);
19398 vector int vec_nand (vector bool int, vector int);
19399 vector int vec_nand (vector int, vector bool int);
19400 vector unsigned int vec_nand (vector unsigned int, vector unsigned int);
19401 vector unsigned int vec_nand (vector bool unsigned int, vector unsigned int);
19402 vector unsigned int vec_nand (vector unsigned int, vector bool unsigned int);
19403 vector short vec_nand (vector short, vector short);
19404 vector short vec_nand (vector bool short, vector short);
19405 vector short vec_nand (vector short, vector bool short);
19406 vector unsigned short vec_nand (vector unsigned short, vector unsigned short);
19407 vector unsigned short vec_nand (vector bool unsigned short, vector unsigned short);
19408 vector unsigned short vec_nand (vector unsigned short, vector bool unsigned short);
19409 vector signed char vec_nand (vector signed char, vector signed char);
19410 vector signed char vec_nand (vector bool signed char, vector signed char);
19411 vector signed char vec_nand (vector signed char, vector bool signed char);
19412 vector unsigned char vec_nand (vector unsigned char, vector unsigned char);
19413 vector unsigned char vec_nand (vector bool unsigned char, vector unsigned char);
19414 vector unsigned char vec_nand (vector unsigned char, vector bool unsigned char);
19416 vector long long vec_orc (vector long long, vector long long);
19417 vector long long vec_orc (vector bool long long, vector long long);
19418 vector long long vec_orc (vector long long, vector bool long long);
19419 vector unsigned long long vec_orc (vector unsigned long long,
19420 vector unsigned long long);
19421 vector unsigned long long vec_orc (vector bool long long, vector unsigned long long);
19422 vector unsigned long long vec_orc (vector unsigned long long, vector bool long long);
19423 vector int vec_orc (vector int, vector int);
19424 vector int vec_orc (vector bool int, vector int);
19425 vector int vec_orc (vector int, vector bool int);
19426 vector unsigned int vec_orc (vector unsigned int, vector unsigned int);
19427 vector unsigned int vec_orc (vector bool unsigned int, vector unsigned int);
19428 vector unsigned int vec_orc (vector unsigned int, vector bool unsigned int);
19429 vector short vec_orc (vector short, vector short);
19430 vector short vec_orc (vector bool short, vector short);
19431 vector short vec_orc (vector short, vector bool short);
19432 vector unsigned short vec_orc (vector unsigned short, vector unsigned short);
19433 vector unsigned short vec_orc (vector bool unsigned short, vector unsigned short);
19434 vector unsigned short vec_orc (vector unsigned short, vector bool unsigned short);
19435 vector signed char vec_orc (vector signed char, vector signed char);
19436 vector signed char vec_orc (vector bool signed char, vector signed char);
19437 vector signed char vec_orc (vector signed char, vector bool signed char);
19438 vector unsigned char vec_orc (vector unsigned char, vector unsigned char);
19439 vector unsigned char vec_orc (vector bool unsigned char, vector unsigned char);
19440 vector unsigned char vec_orc (vector unsigned char, vector bool unsigned char);
19442 vector int vec_pack (vector long long, vector long long);
19443 vector unsigned int vec_pack (vector unsigned long long, vector unsigned long long);
19444 vector bool int vec_pack (vector bool long long, vector bool long long);
19445 vector float vec_pack (vector double, vector double);
19447 vector int vec_packs (vector long long, vector long long);
19448 vector unsigned int vec_packs (vector unsigned long long, vector unsigned long long);
19450 vector unsigned char vec_packsu (vector signed short, vector signed short)
19451 vector unsigned char vec_packsu (vector unsigned short, vector unsigned short)
19452 vector unsigned short int vec_packsu (vector signed int, vector signed int);
19453 vector unsigned short int vec_packsu (vector unsigned int, vector unsigned int);
19454 vector unsigned int vec_packsu (vector long long, vector long long);
19455 vector unsigned int vec_packsu (vector unsigned long long, vector unsigned long long);
19456 vector unsigned int vec_packsu (vector signed long long, vector signed long long);
19458 vector unsigned char vec_popcnt (vector signed char);
19459 vector unsigned char vec_popcnt (vector unsigned char);
19460 vector unsigned short vec_popcnt (vector signed short);
19461 vector unsigned short vec_popcnt (vector unsigned short);
19462 vector unsigned int vec_popcnt (vector signed int);
19463 vector unsigned int vec_popcnt (vector unsigned int);
19464 vector unsigned long long vec_popcnt (vector signed long long);
19465 vector unsigned long long vec_popcnt (vector unsigned long long);
19467 vector long long vec_rl (vector long long, vector unsigned long long);
19468 vector long long vec_rl (vector unsigned long long, vector unsigned long long);
19470 vector long long vec_sl (vector long long, vector unsigned long long);
19471 vector long long vec_sl (vector unsigned long long, vector unsigned long long);
19473 vector long long vec_sr (vector long long, vector unsigned long long);
19474 vector unsigned long long char vec_sr (vector unsigned long long,
19475 vector unsigned long long);
19477 vector long long vec_sra (vector long long, vector unsigned long long);
19478 vector unsigned long long vec_sra (vector unsigned long long,
19479 vector unsigned long long);
19481 vector long long vec_sub (vector long long, vector long long);
19482 vector unsigned long long vec_sub (vector unsigned long long,
19483 vector unsigned long long);
19485 vector long long vec_unpackh (vector int);
19486 vector unsigned long long vec_unpackh (vector unsigned int);
19488 vector long long vec_unpackl (vector int);
19489 vector unsigned long long vec_unpackl (vector unsigned int);
19491 vector long long vec_vaddudm (vector long long, vector long long);
19492 vector long long vec_vaddudm (vector bool long long, vector long long);
19493 vector long long vec_vaddudm (vector long long, vector bool long long);
19494 vector unsigned long long vec_vaddudm (vector unsigned long long,
19495 vector unsigned long long);
19496 vector unsigned long long vec_vaddudm (vector bool unsigned long long,
19497 vector unsigned long long);
19498 vector unsigned long long vec_vaddudm (vector unsigned long long,
19499 vector bool unsigned long long);
19501 vector long long vec_vbpermq (vector signed char, vector signed char);
19502 vector long long vec_vbpermq (vector unsigned char, vector unsigned char);
19504 vector unsigned char vec_bperm (vector unsigned char, vector unsigned char);
19505 vector unsigned char vec_bperm (vector unsigned long long, vector unsigned char);
19506 vector unsigned long long vec_bperm (vector unsigned __int128, vector unsigned char);
19508 vector long long vec_cntlz (vector long long);
19509 vector unsigned long long vec_cntlz (vector unsigned long long);
19510 vector int vec_cntlz (vector int);
19511 vector unsigned int vec_cntlz (vector int);
19512 vector short vec_cntlz (vector short);
19513 vector unsigned short vec_cntlz (vector unsigned short);
19514 vector signed char vec_cntlz (vector signed char);
19515 vector unsigned char vec_cntlz (vector unsigned char);
19517 vector long long vec_vclz (vector long long);
19518 vector unsigned long long vec_vclz (vector unsigned long long);
19519 vector int vec_vclz (vector int);
19520 vector unsigned int vec_vclz (vector int);
19521 vector short vec_vclz (vector short);
19522 vector unsigned short vec_vclz (vector unsigned short);
19523 vector signed char vec_vclz (vector signed char);
19524 vector unsigned char vec_vclz (vector unsigned char);
19526 vector signed char vec_vclzb (vector signed char);
19527 vector unsigned char vec_vclzb (vector unsigned char);
19529 vector long long vec_vclzd (vector long long);
19530 vector unsigned long long vec_vclzd (vector unsigned long long);
19532 vector short vec_vclzh (vector short);
19533 vector unsigned short vec_vclzh (vector unsigned short);
19535 vector int vec_vclzw (vector int);
19536 vector unsigned int vec_vclzw (vector int);
19538 vector signed char vec_vgbbd (vector signed char);
19539 vector unsigned char vec_vgbbd (vector unsigned char);
19541 vector long long vec_vmaxsd (vector long long, vector long long);
19543 vector unsigned long long vec_vmaxud (vector unsigned long long,
19544 unsigned vector long long);
19546 vector long long vec_vminsd (vector long long, vector long long);
19548 vector unsigned long long vec_vminud (vector long long, vector long long);
19550 vector int vec_vpksdss (vector long long, vector long long);
19551 vector unsigned int vec_vpksdss (vector long long, vector long long);
19553 vector unsigned int vec_vpkudus (vector unsigned long long,
19554 vector unsigned long long);
19556 vector int vec_vpkudum (vector long long, vector long long);
19557 vector unsigned int vec_vpkudum (vector unsigned long long,
19558 vector unsigned long long);
19559 vector bool int vec_vpkudum (vector bool long long, vector bool long long);
19561 vector long long vec_vpopcnt (vector long long);
19562 vector unsigned long long vec_vpopcnt (vector unsigned long long);
19563 vector int vec_vpopcnt (vector int);
19564 vector unsigned int vec_vpopcnt (vector int);
19565 vector short vec_vpopcnt (vector short);
19566 vector unsigned short vec_vpopcnt (vector unsigned short);
19567 vector signed char vec_vpopcnt (vector signed char);
19568 vector unsigned char vec_vpopcnt (vector unsigned char);
19570 vector signed char vec_vpopcntb (vector signed char);
19571 vector unsigned char vec_vpopcntb (vector unsigned char);
19573 vector long long vec_vpopcntd (vector long long);
19574 vector unsigned long long vec_vpopcntd (vector unsigned long long);
19576 vector short vec_vpopcnth (vector short);
19577 vector unsigned short vec_vpopcnth (vector unsigned short);
19579 vector int vec_vpopcntw (vector int);
19580 vector unsigned int vec_vpopcntw (vector int);
19582 vector long long vec_vrld (vector long long, vector unsigned long long);
19583 vector unsigned long long vec_vrld (vector unsigned long long,
19584 vector unsigned long long);
19586 vector long long vec_vsld (vector long long, vector unsigned long long);
19587 vector long long vec_vsld (vector unsigned long long,
19588 vector unsigned long long);
19590 vector long long vec_vsrad (vector long long, vector unsigned long long);
19591 vector unsigned long long vec_vsrad (vector unsigned long long,
19592 vector unsigned long long);
19594 vector long long vec_vsrd (vector long long, vector unsigned long long);
19595 vector unsigned long long char vec_vsrd (vector unsigned long long,
19596 vector unsigned long long);
19598 vector long long vec_vsubudm (vector long long, vector long long);
19599 vector long long vec_vsubudm (vector bool long long, vector long long);
19600 vector long long vec_vsubudm (vector long long, vector bool long long);
19601 vector unsigned long long vec_vsubudm (vector unsigned long long,
19602 vector unsigned long long);
19603 vector unsigned long long vec_vsubudm (vector bool long long,
19604 vector unsigned long long);
19605 vector unsigned long long vec_vsubudm (vector unsigned long long,
19606 vector bool long long);
19608 vector long long vec_vupkhsw (vector int);
19609 vector unsigned long long vec_vupkhsw (vector unsigned int);
19611 vector long long vec_vupklsw (vector int);
19612 vector unsigned long long vec_vupklsw (vector int);
19615 If the ISA 2.07 additions to the vector/scalar (power8-vector)
19616 instruction set are available, the following additional functions are
19617 available for 64-bit targets. New vector types
19618 (@var{vector __int128} and @var{vector __uint128}) are available
19619 to hold the @var{__int128} and @var{__uint128} types to use these
19622 The normal vector extract, and set operations work on
19623 @var{vector __int128} and @var{vector __uint128} types,
19624 but the index value must be 0.
19627 vector __int128 vec_vaddcuq (vector __int128, vector __int128);
19628 vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128);
19630 vector __int128 vec_vadduqm (vector __int128, vector __int128);
19631 vector __uint128 vec_vadduqm (vector __uint128, vector __uint128);
19633 vector __int128 vec_vaddecuq (vector __int128, vector __int128,
19635 vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128,
19638 vector __int128 vec_vaddeuqm (vector __int128, vector __int128,
19640 vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128,
19643 vector __int128 vec_vsubecuq (vector __int128, vector __int128,
19645 vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128,
19648 vector __int128 vec_vsubeuqm (vector __int128, vector __int128,
19650 vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128,
19653 vector __int128 vec_vsubcuq (vector __int128, vector __int128);
19654 vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128);
19656 __int128 vec_vsubuqm (__int128, __int128);
19657 __uint128 vec_vsubuqm (__uint128, __uint128);
19659 vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int);
19660 int __builtin_bcdadd_lt (vector __int128, vector __int128, const int);
19661 int __builtin_bcdadd_eq (vector __int128, vector __int128, const int);
19662 int __builtin_bcdadd_gt (vector __int128, vector __int128, const int);
19663 int __builtin_bcdadd_ov (vector __int128, vector __int128, const int);
19664 vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int);
19665 int __builtin_bcdsub_lt (vector __int128, vector __int128, const int);
19666 int __builtin_bcdsub_eq (vector __int128, vector __int128, const int);
19667 int __builtin_bcdsub_gt (vector __int128, vector __int128, const int);
19668 int __builtin_bcdsub_ov (vector __int128, vector __int128, const int);
19671 @node PowerPC AltiVec Built-in Functions Available on ISA 3.0
19672 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0
19674 The following additional built-in functions are also available for the
19675 PowerPC family of processors, starting with ISA 3.0
19676 (@option{-mcpu=power9}) or later:
19678 unsigned int scalar_extract_exp (double source);
19679 unsigned long long int scalar_extract_exp (__ieee128 source);
19681 unsigned long long int scalar_extract_sig (double source);
19682 unsigned __int128 scalar_extract_sig (__ieee128 source);
19684 double scalar_insert_exp (unsigned long long int significand,
19685 unsigned long long int exponent);
19686 double scalar_insert_exp (double significand, unsigned long long int exponent);
19688 ieee_128 scalar_insert_exp (unsigned __int128 significand,
19689 unsigned long long int exponent);
19690 ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent);
19692 int scalar_cmp_exp_gt (double arg1, double arg2);
19693 int scalar_cmp_exp_lt (double arg1, double arg2);
19694 int scalar_cmp_exp_eq (double arg1, double arg2);
19695 int scalar_cmp_exp_unordered (double arg1, double arg2);
19697 bool scalar_test_data_class (float source, const int condition);
19698 bool scalar_test_data_class (double source, const int condition);
19699 bool scalar_test_data_class (__ieee128 source, const int condition);
19701 bool scalar_test_neg (float source);
19702 bool scalar_test_neg (double source);
19703 bool scalar_test_neg (__ieee128 source);
19706 The @code{scalar_extract_exp} and @code{scalar_extract_sig}
19707 functions require a 64-bit environment supporting ISA 3.0 or later.
19708 The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in
19709 functions return the significand and the biased exponent value
19710 respectively of their @code{source} arguments.
19711 When supplied with a 64-bit @code{source} argument, the
19712 result returned by @code{scalar_extract_sig} has
19713 the @code{0x0010000000000000} bit set if the
19714 function's @code{source} argument is in normalized form.
19715 Otherwise, this bit is set to 0.
19716 When supplied with a 128-bit @code{source} argument, the
19717 @code{0x00010000000000000000000000000000} bit of the result is
19719 Note that the sign of the significand is not represented in the result
19720 returned from the @code{scalar_extract_sig} function. Use the
19721 @code{scalar_test_neg} function to test the sign of its @code{double}
19724 The @code{scalar_insert_exp}
19725 functions require a 64-bit environment supporting ISA 3.0 or later.
19726 When supplied with a 64-bit first argument, the
19727 @code{scalar_insert_exp} built-in function returns a double-precision
19728 floating point value that is constructed by assembling the values of its
19729 @code{significand} and @code{exponent} arguments. The sign of the
19730 result is copied from the most significant bit of the
19731 @code{significand} argument. The significand and exponent components
19732 of the result are composed of the least significant 11 bits of the
19733 @code{exponent} argument and the least significant 52 bits of the
19734 @code{significand} argument respectively.
19736 When supplied with a 128-bit first argument, the
19737 @code{scalar_insert_exp} built-in function returns a quad-precision
19738 ieee floating point value. The sign bit of the result is copied from
19739 the most significant bit of the @code{significand} argument.
19740 The significand and exponent components of the result are composed of
19741 the least significant 15 bits of the @code{exponent} argument and the
19742 least significant 112 bits of the @code{significand} argument respectively.
19744 The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt},
19745 @code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in
19746 functions return a non-zero value if @code{arg1} is greater than, less
19747 than, equal to, or not comparable to @code{arg2} respectively. The
19748 arguments are not comparable if one or the other equals NaN (not a
19751 The @code{scalar_test_data_class} built-in function returns 1
19752 if any of the condition tests enabled by the value of the
19753 @code{condition} variable are true, and 0 otherwise. The
19754 @code{condition} argument must be a compile-time constant integer with
19755 value not exceeding 127. The
19756 @code{condition} argument is encoded as a bitmask with each bit
19757 enabling the testing of a different condition, as characterized by the
19761 0x20 Test for +Infinity
19762 0x10 Test for -Infinity
19763 0x08 Test for +Zero
19764 0x04 Test for -Zero
19765 0x02 Test for +Denormal
19766 0x01 Test for -Denormal
19769 The @code{scalar_test_neg} built-in function returns 1 if its
19770 @code{source} argument holds a negative value, 0 otherwise.
19772 The following built-in functions are also available for the PowerPC family
19773 of processors, starting with ISA 3.0 or later
19774 (@option{-mcpu=power9}). These string functions are described
19775 separately in order to group the descriptions closer to the function
19778 int vec_all_nez (vector signed char, vector signed char);
19779 int vec_all_nez (vector unsigned char, vector unsigned char);
19780 int vec_all_nez (vector signed short, vector signed short);
19781 int vec_all_nez (vector unsigned short, vector unsigned short);
19782 int vec_all_nez (vector signed int, vector signed int);
19783 int vec_all_nez (vector unsigned int, vector unsigned int);
19785 int vec_any_eqz (vector signed char, vector signed char);
19786 int vec_any_eqz (vector unsigned char, vector unsigned char);
19787 int vec_any_eqz (vector signed short, vector signed short);
19788 int vec_any_eqz (vector unsigned short, vector unsigned short);
19789 int vec_any_eqz (vector signed int, vector signed int);
19790 int vec_any_eqz (vector unsigned int, vector unsigned int);
19792 vector bool char vec_cmpnez (vector signed char arg1, vector signed char arg2);
19793 vector bool char vec_cmpnez (vector unsigned char arg1, vector unsigned char arg2);
19794 vector bool short vec_cmpnez (vector signed short arg1, vector signed short arg2);
19795 vector bool short vec_cmpnez (vector unsigned short arg1, vector unsigned short arg2);
19796 vector bool int vec_cmpnez (vector signed int arg1, vector signed int arg2);
19797 vector bool int vec_cmpnez (vector unsigned int, vector unsigned int);
19799 vector signed char vec_cnttz (vector signed char);
19800 vector unsigned char vec_cnttz (vector unsigned char);
19801 vector signed short vec_cnttz (vector signed short);
19802 vector unsigned short vec_cnttz (vector unsigned short);
19803 vector signed int vec_cnttz (vector signed int);
19804 vector unsigned int vec_cnttz (vector unsigned int);
19805 vector signed long long vec_cnttz (vector signed long long);
19806 vector unsigned long long vec_cnttz (vector unsigned long long);
19808 signed int vec_cntlz_lsbb (vector signed char);
19809 signed int vec_cntlz_lsbb (vector unsigned char);
19811 signed int vec_cnttz_lsbb (vector signed char);
19812 signed int vec_cnttz_lsbb (vector unsigned char);
19814 unsigned int vec_first_match_index (vector signed char, vector signed char);
19815 unsigned int vec_first_match_index (vector unsigned char, vector unsigned char);
19816 unsigned int vec_first_match_index (vector signed int, vector signed int);
19817 unsigned int vec_first_match_index (vector unsigned int, vector unsigned int);
19818 unsigned int vec_first_match_index (vector signed short, vector signed short);
19819 unsigned int vec_first_match_index (vector unsigned short, vector unsigned short);
19820 unsigned int vec_first_match_or_eos_index (vector signed char, vector signed char);
19821 unsigned int vec_first_match_or_eos_index (vector unsigned char, vector unsigned char);
19822 unsigned int vec_first_match_or_eos_index (vector signed int, vector signed int);
19823 unsigned int vec_first_match_or_eos_index (vector unsigned int, vector unsigned int);
19824 unsigned int vec_first_match_or_eos_index (vector signed short, vector signed short);
19825 unsigned int vec_first_match_or_eos_index (vector unsigned short,
19826 vector unsigned short);
19827 unsigned int vec_first_mismatch_index (vector signed char, vector signed char);
19828 unsigned int vec_first_mismatch_index (vector unsigned char, vector unsigned char);
19829 unsigned int vec_first_mismatch_index (vector signed int, vector signed int);
19830 unsigned int vec_first_mismatch_index (vector unsigned int, vector unsigned int);
19831 unsigned int vec_first_mismatch_index (vector signed short, vector signed short);
19832 unsigned int vec_first_mismatch_index (vector unsigned short, vector unsigned short);
19833 unsigned int vec_first_mismatch_or_eos_index (vector signed char, vector signed char);
19834 unsigned int vec_first_mismatch_or_eos_index (vector unsigned char,
19835 vector unsigned char);
19836 unsigned int vec_first_mismatch_or_eos_index (vector signed int, vector signed int);
19837 unsigned int vec_first_mismatch_or_eos_index (vector unsigned int, vector unsigned int);
19838 unsigned int vec_first_mismatch_or_eos_index (vector signed short, vector signed short);
19839 unsigned int vec_first_mismatch_or_eos_index (vector unsigned short,
19840 vector unsigned short);
19842 vector unsigned short vec_pack_to_short_fp32 (vector float, vector float);
19844 vector signed char vec_xl_be (signed long long, signed char *);
19845 vector unsigned char vec_xl_be (signed long long, unsigned char *);
19846 vector signed int vec_xl_be (signed long long, signed int *);
19847 vector unsigned int vec_xl_be (signed long long, unsigned int *);
19848 vector signed __int128 vec_xl_be (signed long long, signed __int128 *);
19849 vector unsigned __int128 vec_xl_be (signed long long, unsigned __int128 *);
19850 vector signed long long vec_xl_be (signed long long, signed long long *);
19851 vector unsigned long long vec_xl_be (signed long long, unsigned long long *);
19852 vector signed short vec_xl_be (signed long long, signed short *);
19853 vector unsigned short vec_xl_be (signed long long, unsigned short *);
19854 vector double vec_xl_be (signed long long, double *);
19855 vector float vec_xl_be (signed long long, float *);
19857 vector signed char vec_xl_len (signed char *addr, size_t len);
19858 vector unsigned char vec_xl_len (unsigned char *addr, size_t len);
19859 vector signed int vec_xl_len (signed int *addr, size_t len);
19860 vector unsigned int vec_xl_len (unsigned int *addr, size_t len);
19861 vector signed __int128 vec_xl_len (signed __int128 *addr, size_t len);
19862 vector unsigned __int128 vec_xl_len (unsigned __int128 *addr, size_t len);
19863 vector signed long long vec_xl_len (signed long long *addr, size_t len);
19864 vector unsigned long long vec_xl_len (unsigned long long *addr, size_t len);
19865 vector signed short vec_xl_len (signed short *addr, size_t len);
19866 vector unsigned short vec_xl_len (unsigned short *addr, size_t len);
19867 vector double vec_xl_len (double *addr, size_t len);
19868 vector float vec_xl_len (float *addr, size_t len);
19870 vector unsigned char vec_xl_len_r (unsigned char *addr, size_t len);
19872 void vec_xst_len (vector signed char data, signed char *addr, size_t len);
19873 void vec_xst_len (vector unsigned char data, unsigned char *addr, size_t len);
19874 void vec_xst_len (vector signed int data, signed int *addr, size_t len);
19875 void vec_xst_len (vector unsigned int data, unsigned int *addr, size_t len);
19876 void vec_xst_len (vector unsigned __int128 data, unsigned __int128 *addr, size_t len);
19877 void vec_xst_len (vector signed long long data, signed long long *addr, size_t len);
19878 void vec_xst_len (vector unsigned long long data, unsigned long long *addr, size_t len);
19879 void vec_xst_len (vector signed short data, signed short *addr, size_t len);
19880 void vec_xst_len (vector unsigned short data, unsigned short *addr, size_t len);
19881 void vec_xst_len (vector signed __int128 data, signed __int128 *addr, size_t len);
19882 void vec_xst_len (vector double data, double *addr, size_t len);
19883 void vec_xst_len (vector float data, float *addr, size_t len);
19885 void vec_xst_len_r (vector unsigned char data, unsigned char *addr, size_t len);
19887 signed char vec_xlx (unsigned int index, vector signed char data);
19888 unsigned char vec_xlx (unsigned int index, vector unsigned char data);
19889 signed short vec_xlx (unsigned int index, vector signed short data);
19890 unsigned short vec_xlx (unsigned int index, vector unsigned short data);
19891 signed int vec_xlx (unsigned int index, vector signed int data);
19892 unsigned int vec_xlx (unsigned int index, vector unsigned int data);
19893 float vec_xlx (unsigned int index, vector float data);
19895 signed char vec_xrx (unsigned int index, vector signed char data);
19896 unsigned char vec_xrx (unsigned int index, vector unsigned char data);
19897 signed short vec_xrx (unsigned int index, vector signed short data);
19898 unsigned short vec_xrx (unsigned int index, vector unsigned short data);
19899 signed int vec_xrx (unsigned int index, vector signed int data);
19900 unsigned int vec_xrx (unsigned int index, vector unsigned int data);
19901 float vec_xrx (unsigned int index, vector float data);
19904 The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez}
19905 perform pairwise comparisons between the elements at the same
19906 positions within their two vector arguments.
19907 The @code{vec_all_nez} function returns a
19908 non-zero value if and only if all pairwise comparisons are not
19909 equal and no element of either vector argument contains a zero.
19910 The @code{vec_any_eqz} function returns a
19911 non-zero value if and only if at least one pairwise comparison is equal
19912 or if at least one element of either vector argument contains a zero.
19913 The @code{vec_cmpnez} function returns a vector of the same type as
19914 its two arguments, within which each element consists of all ones to
19915 denote that either the corresponding elements of the incoming arguments are
19916 not equal or that at least one of the corresponding elements contains
19917 zero. Otherwise, the element of the returned vector contains all zeros.
19919 The @code{vec_cntlz_lsbb} function returns the count of the number of
19920 consecutive leading byte elements (starting from position 0 within the
19921 supplied vector argument) for which the least-significant bit
19922 equals zero. The @code{vec_cnttz_lsbb} function returns the count of
19923 the number of consecutive trailing byte elements (starting from
19924 position 15 and counting backwards within the supplied vector
19925 argument) for which the least-significant bit equals zero.
19927 The @code{vec_xl_len} and @code{vec_xst_len} functions require a
19928 64-bit environment supporting ISA 3.0 or later. The @code{vec_xl_len}
19929 function loads a variable length vector from memory. The
19930 @code{vec_xst_len} function stores a variable length vector to memory.
19931 With both the @code{vec_xl_len} and @code{vec_xst_len} functions, the
19932 @code{addr} argument represents the memory address to or from which
19933 data will be transferred, and the
19934 @code{len} argument represents the number of bytes to be
19935 transferred, as computed by the C expression @code{min((len & 0xff), 16)}.
19936 If this expression's value is not a multiple of the vector element's
19937 size, the behavior of this function is undefined.
19938 In the case that the underlying computer is configured to run in
19939 big-endian mode, the data transfer moves bytes 0 to @code{(len - 1)} of
19940 the corresponding vector. In little-endian mode, the data transfer
19941 moves bytes @code{(16 - len)} to @code{15} of the corresponding
19942 vector. For the load function, any bytes of the result vector that
19943 are not loaded from memory are set to zero.
19944 The value of the @code{addr} argument need not be aligned on a
19945 multiple of the vector's element size.
19947 The @code{vec_xlx} and @code{vec_xrx} functions extract the single
19948 element selected by the @code{index} argument from the vector
19949 represented by the @code{data} argument. The @code{index} argument
19950 always specifies a byte offset, regardless of the size of the vector
19951 element. With @code{vec_xlx}, @code{index} is the offset of the first
19952 byte of the element to be extracted. With @code{vec_xrx}, @code{index}
19953 represents the last byte of the element to be extracted, measured
19954 from the right end of the vector. In other words, the last byte of
19955 the element to be extracted is found at position @code{(15 - index)}.
19956 There is no requirement that @code{index} be a multiple of the vector
19957 element size. However, if the size of the vector element added to
19958 @code{index} is greater than 15, the content of the returned value is
19961 If the ISA 3.0 instruction set additions (@option{-mcpu=power9})
19965 vector unsigned long long vec_bperm (vector unsigned long long, vector unsigned char);
19967 vector bool char vec_cmpne (vector bool char, vector bool char);
19968 vector bool char vec_cmpne (vector signed char, vector signed char);
19969 vector bool char vec_cmpne (vector unsigned char, vector unsigned char);
19970 vector bool int vec_cmpne (vector bool int, vector bool int);
19971 vector bool int vec_cmpne (vector signed int, vector signed int);
19972 vector bool int vec_cmpne (vector unsigned int, vector unsigned int);
19973 vector bool long long vec_cmpne (vector bool long long, vector bool long long);
19974 vector bool long long vec_cmpne (vector signed long long, vector signed long long);
19975 vector bool long long vec_cmpne (vector unsigned long long, vector unsigned long long);
19976 vector bool short vec_cmpne (vector bool short, vector bool short);
19977 vector bool short vec_cmpne (vector signed short, vector signed short);
19978 vector bool short vec_cmpne (vector unsigned short, vector unsigned short);
19979 vector bool long long vec_cmpne (vector double, vector double);
19980 vector bool int vec_cmpne (vector float, vector float);
19982 vector float vec_extract_fp32_from_shorth (vector unsigned short);
19983 vector float vec_extract_fp32_from_shortl (vector unsigned short);
19985 vector long long vec_vctz (vector long long);
19986 vector unsigned long long vec_vctz (vector unsigned long long);
19987 vector int vec_vctz (vector int);
19988 vector unsigned int vec_vctz (vector int);
19989 vector short vec_vctz (vector short);
19990 vector unsigned short vec_vctz (vector unsigned short);
19991 vector signed char vec_vctz (vector signed char);
19992 vector unsigned char vec_vctz (vector unsigned char);
19994 vector signed char vec_vctzb (vector signed char);
19995 vector unsigned char vec_vctzb (vector unsigned char);
19997 vector long long vec_vctzd (vector long long);
19998 vector unsigned long long vec_vctzd (vector unsigned long long);
20000 vector short vec_vctzh (vector short);
20001 vector unsigned short vec_vctzh (vector unsigned short);
20003 vector int vec_vctzw (vector int);
20004 vector unsigned int vec_vctzw (vector int);
20006 vector unsigned long long vec_extract4b (vector unsigned char, const int);
20008 vector unsigned char vec_insert4b (vector signed int, vector unsigned char,
20010 vector unsigned char vec_insert4b (vector unsigned int, vector unsigned char,
20013 vector unsigned int vec_parity_lsbb (vector signed int);
20014 vector unsigned int vec_parity_lsbb (vector unsigned int);
20015 vector unsigned __int128 vec_parity_lsbb (vector signed __int128);
20016 vector unsigned __int128 vec_parity_lsbb (vector unsigned __int128);
20017 vector unsigned long long vec_parity_lsbb (vector signed long long);
20018 vector unsigned long long vec_parity_lsbb (vector unsigned long long);
20020 vector int vec_vprtyb (vector int);
20021 vector unsigned int vec_vprtyb (vector unsigned int);
20022 vector long long vec_vprtyb (vector long long);
20023 vector unsigned long long vec_vprtyb (vector unsigned long long);
20025 vector int vec_vprtybw (vector int);
20026 vector unsigned int vec_vprtybw (vector unsigned int);
20028 vector long long vec_vprtybd (vector long long);
20029 vector unsigned long long vec_vprtybd (vector unsigned long long);
20032 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
20036 vector long vec_vprtyb (vector long);
20037 vector unsigned long vec_vprtyb (vector unsigned long);
20038 vector __int128 vec_vprtyb (vector __int128);
20039 vector __uint128 vec_vprtyb (vector __uint128);
20041 vector long vec_vprtybd (vector long);
20042 vector unsigned long vec_vprtybd (vector unsigned long);
20044 vector __int128 vec_vprtybq (vector __int128);
20045 vector __uint128 vec_vprtybd (vector __uint128);
20048 The following built-in vector functions are available for the PowerPC family
20049 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20051 __vector unsigned char
20052 vec_slv (__vector unsigned char src, __vector unsigned char shift_distance);
20053 __vector unsigned char
20054 vec_srv (__vector unsigned char src, __vector unsigned char shift_distance);
20057 The @code{vec_slv} and @code{vec_srv} functions operate on
20058 all of the bytes of their @code{src} and @code{shift_distance}
20059 arguments in parallel. The behavior of the @code{vec_slv} is as if
20060 there existed a temporary array of 17 unsigned characters
20061 @code{slv_array} within which elements 0 through 15 are the same as
20062 the entries in the @code{src} array and element 16 equals 0. The
20063 result returned from the @code{vec_slv} function is a
20064 @code{__vector} of 16 unsigned characters within which element
20065 @code{i} is computed using the C expression
20066 @code{0xff & (*((unsigned short *)(slv_array + i)) << (0x07 &
20067 shift_distance[i]))},
20068 with this resulting value coerced to the @code{unsigned char} type.
20069 The behavior of the @code{vec_srv} is as if
20070 there existed a temporary array of 17 unsigned characters
20071 @code{srv_array} within which element 0 equals zero and
20072 elements 1 through 16 equal the elements 0 through 15 of
20073 the @code{src} array. The
20074 result returned from the @code{vec_srv} function is a
20075 @code{__vector} of 16 unsigned characters within which element
20076 @code{i} is computed using the C expression
20077 @code{0xff & (*((unsigned short *)(srv_array + i)) >>
20078 (0x07 & shift_distance[i]))},
20079 with this resulting value coerced to the @code{unsigned char} type.
20081 The following built-in functions are available for the PowerPC family
20082 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20084 __vector unsigned char
20085 vec_absd (__vector unsigned char arg1, __vector unsigned char arg2);
20086 __vector unsigned short
20087 vec_absd (__vector unsigned short arg1, __vector unsigned short arg2);
20088 __vector unsigned int
20089 vec_absd (__vector unsigned int arg1, __vector unsigned int arg2);
20091 __vector unsigned char
20092 vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2);
20093 __vector unsigned short
20094 vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2);
20095 __vector unsigned int
20096 vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2);
20099 The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and
20100 @code{vec_absdw} built-in functions each computes the absolute
20101 differences of the pairs of vector elements supplied in its two vector
20102 arguments, placing the absolute differences into the corresponding
20103 elements of the vector result.
20105 The following built-in functions are available for the PowerPC family
20106 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20108 __vector unsigned int vec_extract_exp (__vector float source);
20109 __vector unsigned long long int vec_extract_exp (__vector double source);
20111 __vector unsigned int vec_extract_sig (__vector float source);
20112 __vector unsigned long long int vec_extract_sig (__vector double source);
20114 __vector float vec_insert_exp (__vector unsigned int significands,
20115 __vector unsigned int exponents);
20116 __vector float vec_insert_exp (__vector unsigned float significands,
20117 __vector unsigned int exponents);
20118 __vector double vec_insert_exp (__vector unsigned long long int significands,
20119 __vector unsigned long long int exponents);
20120 __vector double vec_insert_exp (__vector unsigned double significands,
20121 __vector unsigned long long int exponents);
20123 __vector bool int vec_test_data_class (__vector float source, const int condition);
20124 __vector bool long long int vec_test_data_class (__vector double source,
20125 const int condition);
20128 The @code{vec_extract_sig} and @code{vec_extract_exp} built-in
20129 functions return vectors representing the significands and biased
20130 exponent values of their @code{source} arguments respectively.
20131 Within the result vector returned by @code{vec_extract_sig}, the
20132 @code{0x800000} bit of each vector element returned when the
20133 function's @code{source} argument is of type @code{float} is set to 1
20134 if the corresponding floating point value is in normalized form.
20135 Otherwise, this bit is set to 0. When the @code{source} argument is
20136 of type @code{double}, the @code{0x10000000000000} bit within each of
20137 the result vector's elements is set according to the same rules.
20138 Note that the sign of the significand is not represented in the result
20139 returned from the @code{vec_extract_sig} function. To extract the
20141 @code{vec_cpsgn} function, which returns a new vector within which all
20142 of the sign bits of its second argument vector are overwritten with the
20143 sign bits copied from the coresponding elements of its first argument
20144 vector, and all other (non-sign) bits of the second argument vector
20145 are copied unchanged into the result vector.
20147 The @code{vec_insert_exp} built-in functions return a vector of
20148 single- or double-precision floating
20149 point values constructed by assembling the values of their
20150 @code{significands} and @code{exponents} arguments into the
20151 corresponding elements of the returned vector.
20153 element of the result is copied from the most significant bit of the
20154 corresponding entry within the @code{significands} argument.
20155 Note that the relevant
20156 bits of the @code{significands} argument are the same, for both integer
20157 and floating point types.
20159 significand and exponent components of each element of the result are
20160 composed of the least significant bits of the corresponding
20161 @code{significands} element and the least significant bits of the
20162 corresponding @code{exponents} element.
20164 The @code{vec_test_data_class} built-in function returns a vector
20165 representing the results of testing the @code{source} vector for the
20166 condition selected by the @code{condition} argument. The
20167 @code{condition} argument must be a compile-time constant integer with
20168 value not exceeding 127. The
20169 @code{condition} argument is encoded as a bitmask with each bit
20170 enabling the testing of a different condition, as characterized by the
20174 0x20 Test for +Infinity
20175 0x10 Test for -Infinity
20176 0x08 Test for +Zero
20177 0x04 Test for -Zero
20178 0x02 Test for +Denormal
20179 0x01 Test for -Denormal
20182 If any of the enabled test conditions is true, the corresponding entry
20183 in the result vector is -1. Otherwise (all of the enabled test
20184 conditions are false), the corresponding entry of the result vector is 0.
20186 The following built-in functions are available for the PowerPC family
20187 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20189 vector unsigned int vec_rlmi (vector unsigned int, vector unsigned int,
20190 vector unsigned int);
20191 vector unsigned long long vec_rlmi (vector unsigned long long,
20192 vector unsigned long long,
20193 vector unsigned long long);
20194 vector unsigned int vec_rlnm (vector unsigned int, vector unsigned int,
20195 vector unsigned int);
20196 vector unsigned long long vec_rlnm (vector unsigned long long,
20197 vector unsigned long long,
20198 vector unsigned long long);
20199 vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int);
20200 vector unsigned long long vec_vrlnm (vector unsigned long long,
20201 vector unsigned long long);
20204 The result of @code{vec_rlmi} is obtained by rotating each element of
20205 the first argument vector left and inserting it under mask into the
20206 second argument vector. The third argument vector contains the mask
20207 beginning in bits 11:15, the mask end in bits 19:23, and the shift
20208 count in bits 27:31, of each element.
20210 The result of @code{vec_rlnm} is obtained by rotating each element of
20211 the first argument vector left and ANDing it with a mask specified by
20212 the second and third argument vectors. The second argument vector
20213 contains the shift count for each element in the low-order byte. The
20214 third argument vector contains the mask end for each element in the
20215 low-order byte, with the mask begin in the next higher byte.
20217 The result of @code{vec_vrlnm} is obtained by rotating each element
20218 of the first argument vector left and ANDing it with a mask. The
20219 second argument vector contains the mask beginning in bits 11:15,
20220 the mask end in bits 19:23, and the shift count in bits 27:31,
20223 If the ISA 3.0 instruction set additions (@option{-mcpu=power9})
20226 vector signed bool char vec_revb (vector signed char);
20227 vector signed char vec_revb (vector signed char);
20228 vector unsigned char vec_revb (vector unsigned char);
20229 vector bool short vec_revb (vector bool short);
20230 vector short vec_revb (vector short);
20231 vector unsigned short vec_revb (vector unsigned short);
20232 vector bool int vec_revb (vector bool int);
20233 vector int vec_revb (vector int);
20234 vector unsigned int vec_revb (vector unsigned int);
20235 vector float vec_revb (vector float);
20236 vector bool long long vec_revb (vector bool long long);
20237 vector long long vec_revb (vector long long);
20238 vector unsigned long long vec_revb (vector unsigned long long);
20239 vector double vec_revb (vector double);
20242 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
20245 vector long vec_revb (vector long);
20246 vector unsigned long vec_revb (vector unsigned long);
20247 vector __int128 vec_revb (vector __int128);
20248 vector __uint128 vec_revb (vector __uint128);
20251 The @code{vec_revb} built-in function reverses the bytes on an element
20252 by element basis. A vector of @code{vector unsigned char} or
20253 @code{vector signed char} reverses the bytes in the whole word.
20255 If the cryptographic instructions are enabled (@option{-mcrypto} or
20256 @option{-mcpu=power8}), the following builtins are enabled.
20259 vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long);
20261 vector unsigned char vec_sbox_be (vector unsigned char);
20263 vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long,
20264 vector unsigned long long);
20266 vector unsigned char vec_cipher_be (vector unsigned char, vector unsigned char);
20268 vector unsigned long long __builtin_crypto_vcipherlast
20269 (vector unsigned long long,
20270 vector unsigned long long);
20272 vector unsigned char vec_cipherlast_be (vector unsigned char,
20273 vector unsigned char);
20275 vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long,
20276 vector unsigned long long);
20278 vector unsigned char vec_ncipher_be (vector unsigned char,
20279 vector unsigned char);
20281 vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long,
20282 vector unsigned long long);
20284 vector unsigned char vec_ncipherlast_be (vector unsigned char,
20285 vector unsigned char);
20287 vector unsigned char __builtin_crypto_vpermxor (vector unsigned char,
20288 vector unsigned char,
20289 vector unsigned char);
20291 vector unsigned short __builtin_crypto_vpermxor (vector unsigned short,
20292 vector unsigned short,
20293 vector unsigned short);
20295 vector unsigned int __builtin_crypto_vpermxor (vector unsigned int,
20296 vector unsigned int,
20297 vector unsigned int);
20299 vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long,
20300 vector unsigned long long,
20301 vector unsigned long long);
20303 vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char,
20304 vector unsigned char);
20306 vector unsigned short __builtin_crypto_vpmsumb (vector unsigned short,
20307 vector unsigned short);
20309 vector unsigned int __builtin_crypto_vpmsumb (vector unsigned int,
20310 vector unsigned int);
20312 vector unsigned long long __builtin_crypto_vpmsumb (vector unsigned long long,
20313 vector unsigned long long);
20315 vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long,
20318 vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int);
20321 The second argument to @var{__builtin_crypto_vshasigmad} and
20322 @var{__builtin_crypto_vshasigmaw} must be a constant
20323 integer that is 0 or 1. The third argument to these built-in functions
20324 must be a constant integer in the range of 0 to 15.
20326 If the ISA 3.0 instruction set additions
20327 are enabled (@option{-mcpu=power9}), the following additional
20328 functions are available for both 32-bit and 64-bit targets.
20330 vector short vec_xl (int, vector short *);
20331 vector short vec_xl (int, short *);
20332 vector unsigned short vec_xl (int, vector unsigned short *);
20333 vector unsigned short vec_xl (int, unsigned short *);
20334 vector char vec_xl (int, vector char *);
20335 vector char vec_xl (int, char *);
20336 vector unsigned char vec_xl (int, vector unsigned char *);
20337 vector unsigned char vec_xl (int, unsigned char *);
20339 void vec_xst (vector short, int, vector short *);
20340 void vec_xst (vector short, int, short *);
20341 void vec_xst (vector unsigned short, int, vector unsigned short *);
20342 void vec_xst (vector unsigned short, int, unsigned short *);
20343 void vec_xst (vector char, int, vector char *);
20344 void vec_xst (vector char, int, char *);
20345 void vec_xst (vector unsigned char, int, vector unsigned char *);
20346 void vec_xst (vector unsigned char, int, unsigned char *);
20348 @node PowerPC Hardware Transactional Memory Built-in Functions
20349 @subsection PowerPC Hardware Transactional Memory Built-in Functions
20350 GCC provides two interfaces for accessing the Hardware Transactional
20351 Memory (HTM) instructions available on some of the PowerPC family
20352 of processors (eg, POWER8). The two interfaces come in a low level
20353 interface, consisting of built-in functions specific to PowerPC and a
20354 higher level interface consisting of inline functions that are common
20355 between PowerPC and S/390.
20357 @subsubsection PowerPC HTM Low Level Built-in Functions
20359 The following low level built-in functions are available with
20360 @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later.
20361 They all generate the machine instruction that is part of the name.
20363 The HTM builtins (with the exception of @code{__builtin_tbegin}) return
20364 the full 4-bit condition register value set by their associated hardware
20365 instruction. The header file @code{htmintrin.h} defines some macros that can
20366 be used to decipher the return value. The @code{__builtin_tbegin} builtin
20367 returns a simple @code{true} or @code{false} value depending on whether a transaction was
20368 successfully started or not. The arguments of the builtins match exactly the
20369 type and order of the associated hardware instruction's operands, except for
20370 the @code{__builtin_tcheck} builtin, which does not take any input arguments.
20371 Refer to the ISA manual for a description of each instruction's operands.
20374 unsigned int __builtin_tbegin (unsigned int)
20375 unsigned int __builtin_tend (unsigned int)
20377 unsigned int __builtin_tabort (unsigned int)
20378 unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int)
20379 unsigned int __builtin_tabortdci (unsigned int, unsigned int, int)
20380 unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int)
20381 unsigned int __builtin_tabortwci (unsigned int, unsigned int, int)
20383 unsigned int __builtin_tcheck (void)
20384 unsigned int __builtin_treclaim (unsigned int)
20385 unsigned int __builtin_trechkpt (void)
20386 unsigned int __builtin_tsr (unsigned int)
20389 In addition to the above HTM built-ins, we have added built-ins for
20390 some common extended mnemonics of the HTM instructions:
20393 unsigned int __builtin_tendall (void)
20394 unsigned int __builtin_tresume (void)
20395 unsigned int __builtin_tsuspend (void)
20398 Note that the semantics of the above HTM builtins are required to mimic
20399 the locking semantics used for critical sections. Builtins that are used
20400 to create a new transaction or restart a suspended transaction must have
20401 lock acquisition like semantics while those builtins that end or suspend a
20402 transaction must have lock release like semantics. Specifically, this must
20403 mimic lock semantics as specified by C++11, for example: Lock acquisition is
20404 as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE)
20405 that returns 0, and lock release is as-if an execution of
20406 __atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an
20407 implicit implementation-defined lock used for all transactions. The HTM
20408 instructions associated with with the builtins inherently provide the
20409 correct acquisition and release hardware barriers required. However,
20410 the compiler must also be prohibited from moving loads and stores across
20411 the builtins in a way that would violate their semantics. This has been
20412 accomplished by adding memory barriers to the associated HTM instructions
20413 (which is a conservative approach to provide acquire and release semantics).
20414 Earlier versions of the compiler did not treat the HTM instructions as
20415 memory barriers. A @code{__TM_FENCE__} macro has been added, which can
20416 be used to determine whether the current compiler treats HTM instructions
20417 as memory barriers or not. This allows the user to explicitly add memory
20418 barriers to their code when using an older version of the compiler.
20420 The following set of built-in functions are available to gain access
20421 to the HTM specific special purpose registers.
20424 unsigned long __builtin_get_texasr (void)
20425 unsigned long __builtin_get_texasru (void)
20426 unsigned long __builtin_get_tfhar (void)
20427 unsigned long __builtin_get_tfiar (void)
20429 void __builtin_set_texasr (unsigned long);
20430 void __builtin_set_texasru (unsigned long);
20431 void __builtin_set_tfhar (unsigned long);
20432 void __builtin_set_tfiar (unsigned long);
20435 Example usage of these low level built-in functions may look like:
20438 #include <htmintrin.h>
20440 int num_retries = 10;
20444 if (__builtin_tbegin (0))
20446 /* Transaction State Initiated. */
20447 if (is_locked (lock))
20448 __builtin_tabort (0);
20449 ... transaction code...
20450 __builtin_tend (0);
20455 /* Transaction State Failed. Use locks if the transaction
20456 failure is "persistent" or we've tried too many times. */
20457 if (num_retries-- <= 0
20458 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ()))
20460 acquire_lock (lock);
20461 ... non transactional fallback path...
20462 release_lock (lock);
20469 One final built-in function has been added that returns the value of
20470 the 2-bit Transaction State field of the Machine Status Register (MSR)
20471 as stored in @code{CR0}.
20474 unsigned long __builtin_ttest (void)
20477 This built-in can be used to determine the current transaction state
20478 using the following code example:
20481 #include <htmintrin.h>
20483 unsigned char tx_state = _HTM_STATE (__builtin_ttest ());
20485 if (tx_state == _HTM_TRANSACTIONAL)
20487 /* Code to use in transactional state. */
20489 else if (tx_state == _HTM_NONTRANSACTIONAL)
20491 /* Code to use in non-transactional state. */
20493 else if (tx_state == _HTM_SUSPENDED)
20495 /* Code to use in transaction suspended state. */
20499 @subsubsection PowerPC HTM High Level Inline Functions
20501 The following high level HTM interface is made available by including
20502 @code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU}
20503 where CPU is `power8' or later. This interface is common between PowerPC
20504 and S/390, allowing users to write one HTM source implementation that
20505 can be compiled and executed on either system.
20508 long __TM_simple_begin (void)
20509 long __TM_begin (void* const TM_buff)
20510 long __TM_end (void)
20511 void __TM_abort (void)
20512 void __TM_named_abort (unsigned char const code)
20513 void __TM_resume (void)
20514 void __TM_suspend (void)
20516 long __TM_is_user_abort (void* const TM_buff)
20517 long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code)
20518 long __TM_is_illegal (void* const TM_buff)
20519 long __TM_is_footprint_exceeded (void* const TM_buff)
20520 long __TM_nesting_depth (void* const TM_buff)
20521 long __TM_is_nested_too_deep(void* const TM_buff)
20522 long __TM_is_conflict(void* const TM_buff)
20523 long __TM_is_failure_persistent(void* const TM_buff)
20524 long __TM_failure_address(void* const TM_buff)
20525 long long __TM_failure_code(void* const TM_buff)
20528 Using these common set of HTM inline functions, we can create
20529 a more portable version of the HTM example in the previous
20530 section that will work on either PowerPC or S/390:
20533 #include <htmxlintrin.h>
20535 int num_retries = 10;
20536 TM_buff_type TM_buff;
20540 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED)
20542 /* Transaction State Initiated. */
20543 if (is_locked (lock))
20545 ... transaction code...
20551 /* Transaction State Failed. Use locks if the transaction
20552 failure is "persistent" or we've tried too many times. */
20553 if (num_retries-- <= 0
20554 || __TM_is_failure_persistent (TM_buff))
20556 acquire_lock (lock);
20557 ... non transactional fallback path...
20558 release_lock (lock);
20565 @node PowerPC Atomic Memory Operation Functions
20566 @subsection PowerPC Atomic Memory Operation Functions
20567 ISA 3.0 of the PowerPC added new atomic memory operation (amo)
20568 instructions. GCC provides support for these instructions in 64-bit
20569 environments. All of the functions are declared in the include file
20572 The functions supported are:
20577 uint32_t amo_lwat_add (uint32_t *, uint32_t);
20578 uint32_t amo_lwat_xor (uint32_t *, uint32_t);
20579 uint32_t amo_lwat_ior (uint32_t *, uint32_t);
20580 uint32_t amo_lwat_and (uint32_t *, uint32_t);
20581 uint32_t amo_lwat_umax (uint32_t *, uint32_t);
20582 uint32_t amo_lwat_umin (uint32_t *, uint32_t);
20583 uint32_t amo_lwat_swap (uint32_t *, uint32_t);
20585 int32_t amo_lwat_sadd (int32_t *, int32_t);
20586 int32_t amo_lwat_smax (int32_t *, int32_t);
20587 int32_t amo_lwat_smin (int32_t *, int32_t);
20588 int32_t amo_lwat_sswap (int32_t *, int32_t);
20590 uint64_t amo_ldat_add (uint64_t *, uint64_t);
20591 uint64_t amo_ldat_xor (uint64_t *, uint64_t);
20592 uint64_t amo_ldat_ior (uint64_t *, uint64_t);
20593 uint64_t amo_ldat_and (uint64_t *, uint64_t);
20594 uint64_t amo_ldat_umax (uint64_t *, uint64_t);
20595 uint64_t amo_ldat_umin (uint64_t *, uint64_t);
20596 uint64_t amo_ldat_swap (uint64_t *, uint64_t);
20598 int64_t amo_ldat_sadd (int64_t *, int64_t);
20599 int64_t amo_ldat_smax (int64_t *, int64_t);
20600 int64_t amo_ldat_smin (int64_t *, int64_t);
20601 int64_t amo_ldat_sswap (int64_t *, int64_t);
20603 void amo_stwat_add (uint32_t *, uint32_t);
20604 void amo_stwat_xor (uint32_t *, uint32_t);
20605 void amo_stwat_ior (uint32_t *, uint32_t);
20606 void amo_stwat_and (uint32_t *, uint32_t);
20607 void amo_stwat_umax (uint32_t *, uint32_t);
20608 void amo_stwat_umin (uint32_t *, uint32_t);
20610 void amo_stwat_sadd (int32_t *, int32_t);
20611 void amo_stwat_smax (int32_t *, int32_t);
20612 void amo_stwat_smin (int32_t *, int32_t);
20614 void amo_stdat_add (uint64_t *, uint64_t);
20615 void amo_stdat_xor (uint64_t *, uint64_t);
20616 void amo_stdat_ior (uint64_t *, uint64_t);
20617 void amo_stdat_and (uint64_t *, uint64_t);
20618 void amo_stdat_umax (uint64_t *, uint64_t);
20619 void amo_stdat_umin (uint64_t *, uint64_t);
20621 void amo_stdat_sadd (int64_t *, int64_t);
20622 void amo_stdat_smax (int64_t *, int64_t);
20623 void amo_stdat_smin (int64_t *, int64_t);
20626 @node RX Built-in Functions
20627 @subsection RX Built-in Functions
20628 GCC supports some of the RX instructions which cannot be expressed in
20629 the C programming language via the use of built-in functions. The
20630 following functions are supported:
20632 @deftypefn {Built-in Function} void __builtin_rx_brk (void)
20633 Generates the @code{brk} machine instruction.
20636 @deftypefn {Built-in Function} void __builtin_rx_clrpsw (int)
20637 Generates the @code{clrpsw} machine instruction to clear the specified
20638 bit in the processor status word.
20641 @deftypefn {Built-in Function} void __builtin_rx_int (int)
20642 Generates the @code{int} machine instruction to generate an interrupt
20643 with the specified value.
20646 @deftypefn {Built-in Function} void __builtin_rx_machi (int, int)
20647 Generates the @code{machi} machine instruction to add the result of
20648 multiplying the top 16 bits of the two arguments into the
20652 @deftypefn {Built-in Function} void __builtin_rx_maclo (int, int)
20653 Generates the @code{maclo} machine instruction to add the result of
20654 multiplying the bottom 16 bits of the two arguments into the
20658 @deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int)
20659 Generates the @code{mulhi} machine instruction to place the result of
20660 multiplying the top 16 bits of the two arguments into the
20664 @deftypefn {Built-in Function} void __builtin_rx_mullo (int, int)
20665 Generates the @code{mullo} machine instruction to place the result of
20666 multiplying the bottom 16 bits of the two arguments into the
20670 @deftypefn {Built-in Function} int __builtin_rx_mvfachi (void)
20671 Generates the @code{mvfachi} machine instruction to read the top
20672 32 bits of the accumulator.
20675 @deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void)
20676 Generates the @code{mvfacmi} machine instruction to read the middle
20677 32 bits of the accumulator.
20680 @deftypefn {Built-in Function} int __builtin_rx_mvfc (int)
20681 Generates the @code{mvfc} machine instruction which reads the control
20682 register specified in its argument and returns its value.
20685 @deftypefn {Built-in Function} void __builtin_rx_mvtachi (int)
20686 Generates the @code{mvtachi} machine instruction to set the top
20687 32 bits of the accumulator.
20690 @deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int)
20691 Generates the @code{mvtaclo} machine instruction to set the bottom
20692 32 bits of the accumulator.
20695 @deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val)
20696 Generates the @code{mvtc} machine instruction which sets control
20697 register number @code{reg} to @code{val}.
20700 @deftypefn {Built-in Function} void __builtin_rx_mvtipl (int)
20701 Generates the @code{mvtipl} machine instruction set the interrupt
20705 @deftypefn {Built-in Function} void __builtin_rx_racw (int)
20706 Generates the @code{racw} machine instruction to round the accumulator
20707 according to the specified mode.
20710 @deftypefn {Built-in Function} int __builtin_rx_revw (int)
20711 Generates the @code{revw} machine instruction which swaps the bytes in
20712 the argument so that bits 0--7 now occupy bits 8--15 and vice versa,
20713 and also bits 16--23 occupy bits 24--31 and vice versa.
20716 @deftypefn {Built-in Function} void __builtin_rx_rmpa (void)
20717 Generates the @code{rmpa} machine instruction which initiates a
20718 repeated multiply and accumulate sequence.
20721 @deftypefn {Built-in Function} void __builtin_rx_round (float)
20722 Generates the @code{round} machine instruction which returns the
20723 floating-point argument rounded according to the current rounding mode
20724 set in the floating-point status word register.
20727 @deftypefn {Built-in Function} int __builtin_rx_sat (int)
20728 Generates the @code{sat} machine instruction which returns the
20729 saturated value of the argument.
20732 @deftypefn {Built-in Function} void __builtin_rx_setpsw (int)
20733 Generates the @code{setpsw} machine instruction to set the specified
20734 bit in the processor status word.
20737 @deftypefn {Built-in Function} void __builtin_rx_wait (void)
20738 Generates the @code{wait} machine instruction.
20741 @node S/390 System z Built-in Functions
20742 @subsection S/390 System z Built-in Functions
20743 @deftypefn {Built-in Function} int __builtin_tbegin (void*)
20744 Generates the @code{tbegin} machine instruction starting a
20745 non-constrained hardware transaction. If the parameter is non-NULL the
20746 memory area is used to store the transaction diagnostic buffer and
20747 will be passed as first operand to @code{tbegin}. This buffer can be
20748 defined using the @code{struct __htm_tdb} C struct defined in
20749 @code{htmintrin.h} and must reside on a double-word boundary. The
20750 second tbegin operand is set to @code{0xff0c}. This enables
20751 save/restore of all GPRs and disables aborts for FPR and AR
20752 manipulations inside the transaction body. The condition code set by
20753 the tbegin instruction is returned as integer value. The tbegin
20754 instruction by definition overwrites the content of all FPRs. The
20755 compiler will generate code which saves and restores the FPRs. For
20756 soft-float code it is recommended to used the @code{*_nofloat}
20757 variant. In order to prevent a TDB from being written it is required
20758 to pass a constant zero value as parameter. Passing a zero value
20759 through a variable is not sufficient. Although modifications of
20760 access registers inside the transaction will not trigger an
20761 transaction abort it is not supported to actually modify them. Access
20762 registers do not get saved when entering a transaction. They will have
20763 undefined state when reaching the abort code.
20766 Macros for the possible return codes of tbegin are defined in the
20767 @code{htmintrin.h} header file:
20770 @item _HTM_TBEGIN_STARTED
20771 @code{tbegin} has been executed as part of normal processing. The
20772 transaction body is supposed to be executed.
20773 @item _HTM_TBEGIN_INDETERMINATE
20774 The transaction was aborted due to an indeterminate condition which
20775 might be persistent.
20776 @item _HTM_TBEGIN_TRANSIENT
20777 The transaction aborted due to a transient failure. The transaction
20778 should be re-executed in that case.
20779 @item _HTM_TBEGIN_PERSISTENT
20780 The transaction aborted due to a persistent failure. Re-execution
20781 under same circumstances will not be productive.
20784 @defmac _HTM_FIRST_USER_ABORT_CODE
20785 The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h}
20786 specifies the first abort code which can be used for
20787 @code{__builtin_tabort}. Values below this threshold are reserved for
20791 @deftp {Data type} {struct __htm_tdb}
20792 The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes
20793 the structure of the transaction diagnostic block as specified in the
20794 Principles of Operation manual chapter 5-91.
20797 @deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*)
20798 Same as @code{__builtin_tbegin} but without FPR saves and restores.
20799 Using this variant in code making use of FPRs will leave the FPRs in
20800 undefined state when entering the transaction abort handler code.
20803 @deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int)
20804 In addition to @code{__builtin_tbegin} a loop for transient failures
20805 is generated. If tbegin returns a condition code of 2 the transaction
20806 will be retried as often as specified in the second argument. The
20807 perform processor assist instruction is used to tell the CPU about the
20808 number of fails so far.
20811 @deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int)
20812 Same as @code{__builtin_tbegin_retry} but without FPR saves and
20813 restores. Using this variant in code making use of FPRs will leave
20814 the FPRs in undefined state when entering the transaction abort
20818 @deftypefn {Built-in Function} void __builtin_tbeginc (void)
20819 Generates the @code{tbeginc} machine instruction starting a constrained
20820 hardware transaction. The second operand is set to @code{0xff08}.
20823 @deftypefn {Built-in Function} int __builtin_tend (void)
20824 Generates the @code{tend} machine instruction finishing a transaction
20825 and making the changes visible to other threads. The condition code
20826 generated by tend is returned as integer value.
20829 @deftypefn {Built-in Function} void __builtin_tabort (int)
20830 Generates the @code{tabort} machine instruction with the specified
20831 abort code. Abort codes from 0 through 255 are reserved and will
20832 result in an error message.
20835 @deftypefn {Built-in Function} void __builtin_tx_assist (int)
20836 Generates the @code{ppa rX,rY,1} machine instruction. Where the
20837 integer parameter is loaded into rX and a value of zero is loaded into
20838 rY. The integer parameter specifies the number of times the
20839 transaction repeatedly aborted.
20842 @deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void)
20843 Generates the @code{etnd} machine instruction. The current nesting
20844 depth is returned as integer value. For a nesting depth of 0 the code
20845 is not executed as part of an transaction.
20848 @deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t)
20850 Generates the @code{ntstg} machine instruction. The second argument
20851 is written to the first arguments location. The store operation will
20852 not be rolled-back in case of an transaction abort.
20855 @node SH Built-in Functions
20856 @subsection SH Built-in Functions
20857 The following built-in functions are supported on the SH1, SH2, SH3 and SH4
20858 families of processors:
20860 @deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr})
20861 Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually
20862 used by system code that manages threads and execution contexts. The compiler
20863 normally does not generate code that modifies the contents of @samp{GBR} and
20864 thus the value is preserved across function calls. Changing the @samp{GBR}
20865 value in user code must be done with caution, since the compiler might use
20866 @samp{GBR} in order to access thread local variables.
20870 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
20871 Returns the value that is currently set in the @samp{GBR} register.
20872 Memory loads and stores that use the thread pointer as a base address are
20873 turned into @samp{GBR} based displacement loads and stores, if possible.
20881 int get_tcb_value (void)
20883 // Generate @samp{mov.l @@(8,gbr),r0} instruction
20884 return ((my_tcb*)__builtin_thread_pointer ())->c;
20890 @deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void)
20891 Returns the value that is currently set in the @samp{FPSCR} register.
20894 @deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val})
20895 Sets the @samp{FPSCR} register to the specified value @var{val}, while
20896 preserving the current values of the FR, SZ and PR bits.
20899 @node SPARC VIS Built-in Functions
20900 @subsection SPARC VIS Built-in Functions
20902 GCC supports SIMD operations on the SPARC using both the generic vector
20903 extensions (@pxref{Vector Extensions}) as well as built-in functions for
20904 the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis}
20905 switch, the VIS extension is exposed as the following built-in functions:
20908 typedef int v1si __attribute__ ((vector_size (4)));
20909 typedef int v2si __attribute__ ((vector_size (8)));
20910 typedef short v4hi __attribute__ ((vector_size (8)));
20911 typedef short v2hi __attribute__ ((vector_size (4)));
20912 typedef unsigned char v8qi __attribute__ ((vector_size (8)));
20913 typedef unsigned char v4qi __attribute__ ((vector_size (4)));
20915 void __builtin_vis_write_gsr (int64_t);
20916 int64_t __builtin_vis_read_gsr (void);
20918 void * __builtin_vis_alignaddr (void *, long);
20919 void * __builtin_vis_alignaddrl (void *, long);
20920 int64_t __builtin_vis_faligndatadi (int64_t, int64_t);
20921 v2si __builtin_vis_faligndatav2si (v2si, v2si);
20922 v4hi __builtin_vis_faligndatav4hi (v4si, v4si);
20923 v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi);
20925 v4hi __builtin_vis_fexpand (v4qi);
20927 v4hi __builtin_vis_fmul8x16 (v4qi, v4hi);
20928 v4hi __builtin_vis_fmul8x16au (v4qi, v2hi);
20929 v4hi __builtin_vis_fmul8x16al (v4qi, v2hi);
20930 v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi);
20931 v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi);
20932 v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi);
20933 v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi);
20935 v4qi __builtin_vis_fpack16 (v4hi);
20936 v8qi __builtin_vis_fpack32 (v2si, v8qi);
20937 v2hi __builtin_vis_fpackfix (v2si);
20938 v8qi __builtin_vis_fpmerge (v4qi, v4qi);
20940 int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t);
20942 long __builtin_vis_edge8 (void *, void *);
20943 long __builtin_vis_edge8l (void *, void *);
20944 long __builtin_vis_edge16 (void *, void *);
20945 long __builtin_vis_edge16l (void *, void *);
20946 long __builtin_vis_edge32 (void *, void *);
20947 long __builtin_vis_edge32l (void *, void *);
20949 long __builtin_vis_fcmple16 (v4hi, v4hi);
20950 long __builtin_vis_fcmple32 (v2si, v2si);
20951 long __builtin_vis_fcmpne16 (v4hi, v4hi);
20952 long __builtin_vis_fcmpne32 (v2si, v2si);
20953 long __builtin_vis_fcmpgt16 (v4hi, v4hi);
20954 long __builtin_vis_fcmpgt32 (v2si, v2si);
20955 long __builtin_vis_fcmpeq16 (v4hi, v4hi);
20956 long __builtin_vis_fcmpeq32 (v2si, v2si);
20958 v4hi __builtin_vis_fpadd16 (v4hi, v4hi);
20959 v2hi __builtin_vis_fpadd16s (v2hi, v2hi);
20960 v2si __builtin_vis_fpadd32 (v2si, v2si);
20961 v1si __builtin_vis_fpadd32s (v1si, v1si);
20962 v4hi __builtin_vis_fpsub16 (v4hi, v4hi);
20963 v2hi __builtin_vis_fpsub16s (v2hi, v2hi);
20964 v2si __builtin_vis_fpsub32 (v2si, v2si);
20965 v1si __builtin_vis_fpsub32s (v1si, v1si);
20967 long __builtin_vis_array8 (long, long);
20968 long __builtin_vis_array16 (long, long);
20969 long __builtin_vis_array32 (long, long);
20972 When you use the @option{-mvis2} switch, the VIS version 2.0 built-in
20973 functions also become available:
20976 long __builtin_vis_bmask (long, long);
20977 int64_t __builtin_vis_bshuffledi (int64_t, int64_t);
20978 v2si __builtin_vis_bshufflev2si (v2si, v2si);
20979 v4hi __builtin_vis_bshufflev2si (v4hi, v4hi);
20980 v8qi __builtin_vis_bshufflev2si (v8qi, v8qi);
20982 long __builtin_vis_edge8n (void *, void *);
20983 long __builtin_vis_edge8ln (void *, void *);
20984 long __builtin_vis_edge16n (void *, void *);
20985 long __builtin_vis_edge16ln (void *, void *);
20986 long __builtin_vis_edge32n (void *, void *);
20987 long __builtin_vis_edge32ln (void *, void *);
20990 When you use the @option{-mvis3} switch, the VIS version 3.0 built-in
20991 functions also become available:
20994 void __builtin_vis_cmask8 (long);
20995 void __builtin_vis_cmask16 (long);
20996 void __builtin_vis_cmask32 (long);
20998 v4hi __builtin_vis_fchksm16 (v4hi, v4hi);
21000 v4hi __builtin_vis_fsll16 (v4hi, v4hi);
21001 v4hi __builtin_vis_fslas16 (v4hi, v4hi);
21002 v4hi __builtin_vis_fsrl16 (v4hi, v4hi);
21003 v4hi __builtin_vis_fsra16 (v4hi, v4hi);
21004 v2si __builtin_vis_fsll16 (v2si, v2si);
21005 v2si __builtin_vis_fslas16 (v2si, v2si);
21006 v2si __builtin_vis_fsrl16 (v2si, v2si);
21007 v2si __builtin_vis_fsra16 (v2si, v2si);
21009 long __builtin_vis_pdistn (v8qi, v8qi);
21011 v4hi __builtin_vis_fmean16 (v4hi, v4hi);
21013 int64_t __builtin_vis_fpadd64 (int64_t, int64_t);
21014 int64_t __builtin_vis_fpsub64 (int64_t, int64_t);
21016 v4hi __builtin_vis_fpadds16 (v4hi, v4hi);
21017 v2hi __builtin_vis_fpadds16s (v2hi, v2hi);
21018 v4hi __builtin_vis_fpsubs16 (v4hi, v4hi);
21019 v2hi __builtin_vis_fpsubs16s (v2hi, v2hi);
21020 v2si __builtin_vis_fpadds32 (v2si, v2si);
21021 v1si __builtin_vis_fpadds32s (v1si, v1si);
21022 v2si __builtin_vis_fpsubs32 (v2si, v2si);
21023 v1si __builtin_vis_fpsubs32s (v1si, v1si);
21025 long __builtin_vis_fucmple8 (v8qi, v8qi);
21026 long __builtin_vis_fucmpne8 (v8qi, v8qi);
21027 long __builtin_vis_fucmpgt8 (v8qi, v8qi);
21028 long __builtin_vis_fucmpeq8 (v8qi, v8qi);
21030 float __builtin_vis_fhadds (float, float);
21031 double __builtin_vis_fhaddd (double, double);
21032 float __builtin_vis_fhsubs (float, float);
21033 double __builtin_vis_fhsubd (double, double);
21034 float __builtin_vis_fnhadds (float, float);
21035 double __builtin_vis_fnhaddd (double, double);
21037 int64_t __builtin_vis_umulxhi (int64_t, int64_t);
21038 int64_t __builtin_vis_xmulx (int64_t, int64_t);
21039 int64_t __builtin_vis_xmulxhi (int64_t, int64_t);
21042 When you use the @option{-mvis4} switch, the VIS version 4.0 built-in
21043 functions also become available:
21046 v8qi __builtin_vis_fpadd8 (v8qi, v8qi);
21047 v8qi __builtin_vis_fpadds8 (v8qi, v8qi);
21048 v8qi __builtin_vis_fpaddus8 (v8qi, v8qi);
21049 v4hi __builtin_vis_fpaddus16 (v4hi, v4hi);
21051 v8qi __builtin_vis_fpsub8 (v8qi, v8qi);
21052 v8qi __builtin_vis_fpsubs8 (v8qi, v8qi);
21053 v8qi __builtin_vis_fpsubus8 (v8qi, v8qi);
21054 v4hi __builtin_vis_fpsubus16 (v4hi, v4hi);
21056 long __builtin_vis_fpcmple8 (v8qi, v8qi);
21057 long __builtin_vis_fpcmpgt8 (v8qi, v8qi);
21058 long __builtin_vis_fpcmpule16 (v4hi, v4hi);
21059 long __builtin_vis_fpcmpugt16 (v4hi, v4hi);
21060 long __builtin_vis_fpcmpule32 (v2si, v2si);
21061 long __builtin_vis_fpcmpugt32 (v2si, v2si);
21063 v8qi __builtin_vis_fpmax8 (v8qi, v8qi);
21064 v4hi __builtin_vis_fpmax16 (v4hi, v4hi);
21065 v2si __builtin_vis_fpmax32 (v2si, v2si);
21067 v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi);
21068 v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi);
21069 v2si __builtin_vis_fpmaxu32 (v2si, v2si);
21072 v8qi __builtin_vis_fpmin8 (v8qi, v8qi);
21073 v4hi __builtin_vis_fpmin16 (v4hi, v4hi);
21074 v2si __builtin_vis_fpmin32 (v2si, v2si);
21076 v8qi __builtin_vis_fpminu8 (v8qi, v8qi);
21077 v4hi __builtin_vis_fpminu16 (v4hi, v4hi);
21078 v2si __builtin_vis_fpminu32 (v2si, v2si);
21081 When you use the @option{-mvis4b} switch, the VIS version 4.0B
21082 built-in functions also become available:
21085 v8qi __builtin_vis_dictunpack8 (double, int);
21086 v4hi __builtin_vis_dictunpack16 (double, int);
21087 v2si __builtin_vis_dictunpack32 (double, int);
21089 long __builtin_vis_fpcmple8shl (v8qi, v8qi, int);
21090 long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int);
21091 long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int);
21092 long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int);
21094 long __builtin_vis_fpcmple16shl (v4hi, v4hi, int);
21095 long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int);
21096 long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int);
21097 long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int);
21099 long __builtin_vis_fpcmple32shl (v2si, v2si, int);
21100 long __builtin_vis_fpcmpgt32shl (v2si, v2si, int);
21101 long __builtin_vis_fpcmpeq32shl (v2si, v2si, int);
21102 long __builtin_vis_fpcmpne32shl (v2si, v2si, int);
21104 long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int);
21105 long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int);
21106 long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int);
21107 long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int);
21108 long __builtin_vis_fpcmpule32shl (v2si, v2si, int);
21109 long __builtin_vis_fpcmpugt32shl (v2si, v2si, int);
21111 long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int);
21112 long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int);
21113 long __builtin_vis_fpcmpde32shl (v2si, v2si, int);
21115 long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int);
21116 long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int);
21117 long __builtin_vis_fpcmpur32shl (v2si, v2si, int);
21120 @node SPU Built-in Functions
21121 @subsection SPU Built-in Functions
21123 GCC provides extensions for the SPU processor as described in the
21124 Sony/Toshiba/IBM SPU Language Extensions Specification. GCC's
21125 implementation differs in several ways.
21130 The optional extension of specifying vector constants in parentheses is
21134 A vector initializer requires no cast if the vector constant is of the
21135 same type as the variable it is initializing.
21138 If @code{signed} or @code{unsigned} is omitted, the signedness of the
21139 vector type is the default signedness of the base type. The default
21140 varies depending on the operating system, so a portable program should
21141 always specify the signedness.
21144 By default, the keyword @code{__vector} is added. The macro
21145 @code{vector} is defined in @code{<spu_intrinsics.h>} and can be
21149 GCC allows using a @code{typedef} name as the type specifier for a
21153 For C, overloaded functions are implemented with macros so the following
21157 spu_add ((vector signed int)@{1, 2, 3, 4@}, foo);
21161 Since @code{spu_add} is a macro, the vector constant in the example
21162 is treated as four separate arguments. Wrap the entire argument in
21163 parentheses for this to work.
21166 The extended version of @code{__builtin_expect} is not supported.
21170 @emph{Note:} Only the interface described in the aforementioned
21171 specification is supported. Internally, GCC uses built-in functions to
21172 implement the required functionality, but these are not supported and
21173 are subject to change without notice.
21175 @node TI C6X Built-in Functions
21176 @subsection TI C6X Built-in Functions
21178 GCC provides intrinsics to access certain instructions of the TI C6X
21179 processors. These intrinsics, listed below, are available after
21180 inclusion of the @code{c6x_intrinsics.h} header file. They map directly
21181 to C6X instructions.
21185 int _sadd (int, int)
21186 int _ssub (int, int)
21187 int _sadd2 (int, int)
21188 int _ssub2 (int, int)
21189 long long _mpy2 (int, int)
21190 long long _smpy2 (int, int)
21191 int _add4 (int, int)
21192 int _sub4 (int, int)
21193 int _saddu4 (int, int)
21195 int _smpy (int, int)
21196 int _smpyh (int, int)
21197 int _smpyhl (int, int)
21198 int _smpylh (int, int)
21200 int _sshl (int, int)
21201 int _subc (int, int)
21203 int _avg2 (int, int)
21204 int _avgu4 (int, int)
21206 int _clrr (int, int)
21207 int _extr (int, int)
21208 int _extru (int, int)
21214 @node TILE-Gx Built-in Functions
21215 @subsection TILE-Gx Built-in Functions
21217 GCC provides intrinsics to access every instruction of the TILE-Gx
21218 processor. The intrinsics are of the form:
21222 unsigned long long __insn_@var{op} (...)
21226 Where @var{op} is the name of the instruction. Refer to the ISA manual
21227 for the complete list of instructions.
21229 GCC also provides intrinsics to directly access the network registers.
21230 The intrinsics are:
21234 unsigned long long __tile_idn0_receive (void)
21235 unsigned long long __tile_idn1_receive (void)
21236 unsigned long long __tile_udn0_receive (void)
21237 unsigned long long __tile_udn1_receive (void)
21238 unsigned long long __tile_udn2_receive (void)
21239 unsigned long long __tile_udn3_receive (void)
21240 void __tile_idn_send (unsigned long long)
21241 void __tile_udn_send (unsigned long long)
21245 The intrinsic @code{void __tile_network_barrier (void)} is used to
21246 guarantee that no network operations before it are reordered with
21249 @node TILEPro Built-in Functions
21250 @subsection TILEPro Built-in Functions
21252 GCC provides intrinsics to access every instruction of the TILEPro
21253 processor. The intrinsics are of the form:
21257 unsigned __insn_@var{op} (...)
21262 where @var{op} is the name of the instruction. Refer to the ISA manual
21263 for the complete list of instructions.
21265 GCC also provides intrinsics to directly access the network registers.
21266 The intrinsics are:
21270 unsigned __tile_idn0_receive (void)
21271 unsigned __tile_idn1_receive (void)
21272 unsigned __tile_sn_receive (void)
21273 unsigned __tile_udn0_receive (void)
21274 unsigned __tile_udn1_receive (void)
21275 unsigned __tile_udn2_receive (void)
21276 unsigned __tile_udn3_receive (void)
21277 void __tile_idn_send (unsigned)
21278 void __tile_sn_send (unsigned)
21279 void __tile_udn_send (unsigned)
21283 The intrinsic @code{void __tile_network_barrier (void)} is used to
21284 guarantee that no network operations before it are reordered with
21287 @node x86 Built-in Functions
21288 @subsection x86 Built-in Functions
21290 These built-in functions are available for the x86-32 and x86-64 family
21291 of computers, depending on the command-line switches used.
21293 If you specify command-line switches such as @option{-msse},
21294 the compiler could use the extended instruction sets even if the built-ins
21295 are not used explicitly in the program. For this reason, applications
21296 that perform run-time CPU detection must compile separate files for each
21297 supported architecture, using the appropriate flags. In particular,
21298 the file containing the CPU detection code should be compiled without
21301 The following machine modes are available for use with MMX built-in functions
21302 (@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers,
21303 @code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a
21304 vector of eight 8-bit integers. Some of the built-in functions operate on
21305 MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode.
21307 If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector
21308 of two 32-bit floating-point values.
21310 If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit
21311 floating-point values. Some instructions use a vector of four 32-bit
21312 integers, these use @code{V4SI}. Finally, some instructions operate on an
21313 entire vector register, interpreting it as a 128-bit integer, these use mode
21316 The x86-32 and x86-64 family of processors use additional built-in
21317 functions for efficient use of @code{TF} (@code{__float128}) 128-bit
21318 floating point and @code{TC} 128-bit complex floating-point values.
21320 The following floating-point built-in functions are always available. All
21321 of them implement the function that is part of the name.
21324 __float128 __builtin_fabsq (__float128)
21325 __float128 __builtin_copysignq (__float128, __float128)
21328 The following built-in functions are always available.
21331 @item __float128 __builtin_infq (void)
21332 Similar to @code{__builtin_inf}, except the return type is @code{__float128}.
21333 @findex __builtin_infq
21335 @item __float128 __builtin_huge_valq (void)
21336 Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}.
21337 @findex __builtin_huge_valq
21339 @item __float128 __builtin_nanq (void)
21340 Similar to @code{__builtin_nan}, except the return type is @code{__float128}.
21341 @findex __builtin_nanq
21343 @item __float128 __builtin_nansq (void)
21344 Similar to @code{__builtin_nans}, except the return type is @code{__float128}.
21345 @findex __builtin_nansq
21348 The following built-in function is always available.
21351 @item void __builtin_ia32_pause (void)
21352 Generates the @code{pause} machine instruction with a compiler memory
21356 The following built-in functions are always available and can be used to
21357 check the target platform type.
21359 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
21360 This function runs the CPU detection code to check the type of CPU and the
21361 features supported. This built-in function needs to be invoked along with the built-in functions
21362 to check CPU type and features, @code{__builtin_cpu_is} and
21363 @code{__builtin_cpu_supports}, only when used in a function that is
21364 executed before any constructors are called. The CPU detection code is
21365 automatically executed in a very high priority constructor.
21367 For example, this function has to be used in @code{ifunc} resolvers that
21368 check for CPU type using the built-in functions @code{__builtin_cpu_is}
21369 and @code{__builtin_cpu_supports}, or in constructors on targets that
21370 don't support constructor priority.
21373 static void (*resolve_memcpy (void)) (void)
21375 // ifunc resolvers fire before constructors, explicitly call the init
21377 __builtin_cpu_init ();
21378 if (__builtin_cpu_supports ("ssse3"))
21379 return ssse3_memcpy; // super fast memcpy with ssse3 instructions.
21381 return default_memcpy;
21384 void *memcpy (void *, const void *, size_t)
21385 __attribute__ ((ifunc ("resolve_memcpy")));
21390 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
21391 This function returns a positive integer if the run-time CPU
21392 is of type @var{cpuname}
21393 and returns @code{0} otherwise. The following CPU names can be detected:
21406 Intel Silvermont CPU.
21415 Intel Core i7 Nehalem CPU.
21418 Intel Core i7 Westmere CPU.
21421 Intel Core i7 Sandy Bridge CPU.
21424 Intel Core i7 Ivy Bridge CPU.
21427 Intel Core i7 Haswell CPU.
21430 Intel Core i7 Broadwell CPU.
21433 Intel Core i7 Skylake CPU.
21435 @item skylake-avx512
21436 Intel Core i7 Skylake AVX512 CPU.
21439 Intel Core i7 Cannon Lake CPU.
21441 @item icelake-client
21442 Intel Core i7 Ice Lake Client CPU.
21444 @item icelake-server
21445 Intel Core i7 Ice Lake Server CPU.
21448 Intel Core i7 Cascadelake CPU.
21451 Intel Atom Bonnell CPU.
21454 Intel Atom Silvermont CPU.
21457 Intel Atom Goldmont CPU.
21459 @item goldmont-plus
21460 Intel Atom Goldmont Plus CPU.
21463 Intel Atom Tremont CPU.
21466 Intel Knights Landing CPU.
21469 Intel Knights Mill CPU.
21472 AMD Family 10h CPU.
21475 AMD Family 10h Barcelona CPU.
21478 AMD Family 10h Shanghai CPU.
21481 AMD Family 10h Istanbul CPU.
21484 AMD Family 14h CPU.
21487 AMD Family 15h CPU.
21490 AMD Family 15h Bulldozer version 1.
21493 AMD Family 15h Bulldozer version 2.
21496 AMD Family 15h Bulldozer version 3.
21499 AMD Family 15h Bulldozer version 4.
21502 AMD Family 16h CPU.
21505 AMD Family 17h CPU.
21508 AMD Family 17h Zen version 1.
21511 AMD Family 17h Zen version 2.
21514 Here is an example:
21516 if (__builtin_cpu_is ("corei7"))
21518 do_corei7 (); // Core i7 specific implementation.
21522 do_generic (); // Generic implementation.
21527 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
21528 This function returns a positive integer if the run-time CPU
21529 supports @var{feature}
21530 and returns @code{0} otherwise. The following features can be detected:
21538 POPCNT instruction.
21546 SSSE3 instructions.
21548 SSE4.1 instructions.
21550 SSE4.2 instructions.
21556 SSE4A instructions.
21564 AVX512F instructions.
21572 PCLMUL instructions.
21574 AVX512VL instructions.
21576 AVX512BW instructions.
21578 AVX512DQ instructions.
21580 AVX512CD instructions.
21582 AVX512ER instructions.
21584 AVX512PF instructions.
21586 AVX512VBMI instructions.
21588 AVX512IFMA instructions.
21590 AVX5124VNNIW instructions.
21592 AVX5124FMAPS instructions.
21593 @item avx512vpopcntdq
21594 AVX512VPOPCNTDQ instructions.
21596 AVX512VBMI2 instructions.
21600 VPCLMULQDQ instructions.
21602 AVX512VNNI instructions.
21604 AVX512BITALG instructions.
21607 Here is an example:
21609 if (__builtin_cpu_supports ("popcnt"))
21611 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc");
21615 count = generic_countbits (n); //generic implementation.
21621 The following built-in functions are made available by @option{-mmmx}.
21622 All of them generate the machine instruction that is part of the name.
21625 v8qi __builtin_ia32_paddb (v8qi, v8qi)
21626 v4hi __builtin_ia32_paddw (v4hi, v4hi)
21627 v2si __builtin_ia32_paddd (v2si, v2si)
21628 v8qi __builtin_ia32_psubb (v8qi, v8qi)
21629 v4hi __builtin_ia32_psubw (v4hi, v4hi)
21630 v2si __builtin_ia32_psubd (v2si, v2si)
21631 v8qi __builtin_ia32_paddsb (v8qi, v8qi)
21632 v4hi __builtin_ia32_paddsw (v4hi, v4hi)
21633 v8qi __builtin_ia32_psubsb (v8qi, v8qi)
21634 v4hi __builtin_ia32_psubsw (v4hi, v4hi)
21635 v8qi __builtin_ia32_paddusb (v8qi, v8qi)
21636 v4hi __builtin_ia32_paddusw (v4hi, v4hi)
21637 v8qi __builtin_ia32_psubusb (v8qi, v8qi)
21638 v4hi __builtin_ia32_psubusw (v4hi, v4hi)
21639 v4hi __builtin_ia32_pmullw (v4hi, v4hi)
21640 v4hi __builtin_ia32_pmulhw (v4hi, v4hi)
21641 di __builtin_ia32_pand (di, di)
21642 di __builtin_ia32_pandn (di,di)
21643 di __builtin_ia32_por (di, di)
21644 di __builtin_ia32_pxor (di, di)
21645 v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi)
21646 v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi)
21647 v2si __builtin_ia32_pcmpeqd (v2si, v2si)
21648 v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi)
21649 v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi)
21650 v2si __builtin_ia32_pcmpgtd (v2si, v2si)
21651 v8qi __builtin_ia32_punpckhbw (v8qi, v8qi)
21652 v4hi __builtin_ia32_punpckhwd (v4hi, v4hi)
21653 v2si __builtin_ia32_punpckhdq (v2si, v2si)
21654 v8qi __builtin_ia32_punpcklbw (v8qi, v8qi)
21655 v4hi __builtin_ia32_punpcklwd (v4hi, v4hi)
21656 v2si __builtin_ia32_punpckldq (v2si, v2si)
21657 v8qi __builtin_ia32_packsswb (v4hi, v4hi)
21658 v4hi __builtin_ia32_packssdw (v2si, v2si)
21659 v8qi __builtin_ia32_packuswb (v4hi, v4hi)
21661 v4hi __builtin_ia32_psllw (v4hi, v4hi)
21662 v2si __builtin_ia32_pslld (v2si, v2si)
21663 v1di __builtin_ia32_psllq (v1di, v1di)
21664 v4hi __builtin_ia32_psrlw (v4hi, v4hi)
21665 v2si __builtin_ia32_psrld (v2si, v2si)
21666 v1di __builtin_ia32_psrlq (v1di, v1di)
21667 v4hi __builtin_ia32_psraw (v4hi, v4hi)
21668 v2si __builtin_ia32_psrad (v2si, v2si)
21669 v4hi __builtin_ia32_psllwi (v4hi, int)
21670 v2si __builtin_ia32_pslldi (v2si, int)
21671 v1di __builtin_ia32_psllqi (v1di, int)
21672 v4hi __builtin_ia32_psrlwi (v4hi, int)
21673 v2si __builtin_ia32_psrldi (v2si, int)
21674 v1di __builtin_ia32_psrlqi (v1di, int)
21675 v4hi __builtin_ia32_psrawi (v4hi, int)
21676 v2si __builtin_ia32_psradi (v2si, int)
21680 The following built-in functions are made available either with
21681 @option{-msse}, or with @option{-m3dnowa}. All of them generate
21682 the machine instruction that is part of the name.
21685 v4hi __builtin_ia32_pmulhuw (v4hi, v4hi)
21686 v8qi __builtin_ia32_pavgb (v8qi, v8qi)
21687 v4hi __builtin_ia32_pavgw (v4hi, v4hi)
21688 v1di __builtin_ia32_psadbw (v8qi, v8qi)
21689 v8qi __builtin_ia32_pmaxub (v8qi, v8qi)
21690 v4hi __builtin_ia32_pmaxsw (v4hi, v4hi)
21691 v8qi __builtin_ia32_pminub (v8qi, v8qi)
21692 v4hi __builtin_ia32_pminsw (v4hi, v4hi)
21693 int __builtin_ia32_pmovmskb (v8qi)
21694 void __builtin_ia32_maskmovq (v8qi, v8qi, char *)
21695 void __builtin_ia32_movntq (di *, di)
21696 void __builtin_ia32_sfence (void)
21699 The following built-in functions are available when @option{-msse} is used.
21700 All of them generate the machine instruction that is part of the name.
21703 int __builtin_ia32_comieq (v4sf, v4sf)
21704 int __builtin_ia32_comineq (v4sf, v4sf)
21705 int __builtin_ia32_comilt (v4sf, v4sf)
21706 int __builtin_ia32_comile (v4sf, v4sf)
21707 int __builtin_ia32_comigt (v4sf, v4sf)
21708 int __builtin_ia32_comige (v4sf, v4sf)
21709 int __builtin_ia32_ucomieq (v4sf, v4sf)
21710 int __builtin_ia32_ucomineq (v4sf, v4sf)
21711 int __builtin_ia32_ucomilt (v4sf, v4sf)
21712 int __builtin_ia32_ucomile (v4sf, v4sf)
21713 int __builtin_ia32_ucomigt (v4sf, v4sf)
21714 int __builtin_ia32_ucomige (v4sf, v4sf)
21715 v4sf __builtin_ia32_addps (v4sf, v4sf)
21716 v4sf __builtin_ia32_subps (v4sf, v4sf)
21717 v4sf __builtin_ia32_mulps (v4sf, v4sf)
21718 v4sf __builtin_ia32_divps (v4sf, v4sf)
21719 v4sf __builtin_ia32_addss (v4sf, v4sf)
21720 v4sf __builtin_ia32_subss (v4sf, v4sf)
21721 v4sf __builtin_ia32_mulss (v4sf, v4sf)
21722 v4sf __builtin_ia32_divss (v4sf, v4sf)
21723 v4sf __builtin_ia32_cmpeqps (v4sf, v4sf)
21724 v4sf __builtin_ia32_cmpltps (v4sf, v4sf)
21725 v4sf __builtin_ia32_cmpleps (v4sf, v4sf)
21726 v4sf __builtin_ia32_cmpgtps (v4sf, v4sf)
21727 v4sf __builtin_ia32_cmpgeps (v4sf, v4sf)
21728 v4sf __builtin_ia32_cmpunordps (v4sf, v4sf)
21729 v4sf __builtin_ia32_cmpneqps (v4sf, v4sf)
21730 v4sf __builtin_ia32_cmpnltps (v4sf, v4sf)
21731 v4sf __builtin_ia32_cmpnleps (v4sf, v4sf)
21732 v4sf __builtin_ia32_cmpngtps (v4sf, v4sf)
21733 v4sf __builtin_ia32_cmpngeps (v4sf, v4sf)
21734 v4sf __builtin_ia32_cmpordps (v4sf, v4sf)
21735 v4sf __builtin_ia32_cmpeqss (v4sf, v4sf)
21736 v4sf __builtin_ia32_cmpltss (v4sf, v4sf)
21737 v4sf __builtin_ia32_cmpless (v4sf, v4sf)
21738 v4sf __builtin_ia32_cmpunordss (v4sf, v4sf)
21739 v4sf __builtin_ia32_cmpneqss (v4sf, v4sf)
21740 v4sf __builtin_ia32_cmpnltss (v4sf, v4sf)
21741 v4sf __builtin_ia32_cmpnless (v4sf, v4sf)
21742 v4sf __builtin_ia32_cmpordss (v4sf, v4sf)
21743 v4sf __builtin_ia32_maxps (v4sf, v4sf)
21744 v4sf __builtin_ia32_maxss (v4sf, v4sf)
21745 v4sf __builtin_ia32_minps (v4sf, v4sf)
21746 v4sf __builtin_ia32_minss (v4sf, v4sf)
21747 v4sf __builtin_ia32_andps (v4sf, v4sf)
21748 v4sf __builtin_ia32_andnps (v4sf, v4sf)
21749 v4sf __builtin_ia32_orps (v4sf, v4sf)
21750 v4sf __builtin_ia32_xorps (v4sf, v4sf)
21751 v4sf __builtin_ia32_movss (v4sf, v4sf)
21752 v4sf __builtin_ia32_movhlps (v4sf, v4sf)
21753 v4sf __builtin_ia32_movlhps (v4sf, v4sf)
21754 v4sf __builtin_ia32_unpckhps (v4sf, v4sf)
21755 v4sf __builtin_ia32_unpcklps (v4sf, v4sf)
21756 v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si)
21757 v4sf __builtin_ia32_cvtsi2ss (v4sf, int)
21758 v2si __builtin_ia32_cvtps2pi (v4sf)
21759 int __builtin_ia32_cvtss2si (v4sf)
21760 v2si __builtin_ia32_cvttps2pi (v4sf)
21761 int __builtin_ia32_cvttss2si (v4sf)
21762 v4sf __builtin_ia32_rcpps (v4sf)
21763 v4sf __builtin_ia32_rsqrtps (v4sf)
21764 v4sf __builtin_ia32_sqrtps (v4sf)
21765 v4sf __builtin_ia32_rcpss (v4sf)
21766 v4sf __builtin_ia32_rsqrtss (v4sf)
21767 v4sf __builtin_ia32_sqrtss (v4sf)
21768 v4sf __builtin_ia32_shufps (v4sf, v4sf, int)
21769 void __builtin_ia32_movntps (float *, v4sf)
21770 int __builtin_ia32_movmskps (v4sf)
21773 The following built-in functions are available when @option{-msse} is used.
21776 @item v4sf __builtin_ia32_loadups (float *)
21777 Generates the @code{movups} machine instruction as a load from memory.
21778 @item void __builtin_ia32_storeups (float *, v4sf)
21779 Generates the @code{movups} machine instruction as a store to memory.
21780 @item v4sf __builtin_ia32_loadss (float *)
21781 Generates the @code{movss} machine instruction as a load from memory.
21782 @item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)
21783 Generates the @code{movhps} machine instruction as a load from memory.
21784 @item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)
21785 Generates the @code{movlps} machine instruction as a load from memory
21786 @item void __builtin_ia32_storehps (v2sf *, v4sf)
21787 Generates the @code{movhps} machine instruction as a store to memory.
21788 @item void __builtin_ia32_storelps (v2sf *, v4sf)
21789 Generates the @code{movlps} machine instruction as a store to memory.
21792 The following built-in functions are available when @option{-msse2} is used.
21793 All of them generate the machine instruction that is part of the name.
21796 int __builtin_ia32_comisdeq (v2df, v2df)
21797 int __builtin_ia32_comisdlt (v2df, v2df)
21798 int __builtin_ia32_comisdle (v2df, v2df)
21799 int __builtin_ia32_comisdgt (v2df, v2df)
21800 int __builtin_ia32_comisdge (v2df, v2df)
21801 int __builtin_ia32_comisdneq (v2df, v2df)
21802 int __builtin_ia32_ucomisdeq (v2df, v2df)
21803 int __builtin_ia32_ucomisdlt (v2df, v2df)
21804 int __builtin_ia32_ucomisdle (v2df, v2df)
21805 int __builtin_ia32_ucomisdgt (v2df, v2df)
21806 int __builtin_ia32_ucomisdge (v2df, v2df)
21807 int __builtin_ia32_ucomisdneq (v2df, v2df)
21808 v2df __builtin_ia32_cmpeqpd (v2df, v2df)
21809 v2df __builtin_ia32_cmpltpd (v2df, v2df)
21810 v2df __builtin_ia32_cmplepd (v2df, v2df)
21811 v2df __builtin_ia32_cmpgtpd (v2df, v2df)
21812 v2df __builtin_ia32_cmpgepd (v2df, v2df)
21813 v2df __builtin_ia32_cmpunordpd (v2df, v2df)
21814 v2df __builtin_ia32_cmpneqpd (v2df, v2df)
21815 v2df __builtin_ia32_cmpnltpd (v2df, v2df)
21816 v2df __builtin_ia32_cmpnlepd (v2df, v2df)
21817 v2df __builtin_ia32_cmpngtpd (v2df, v2df)
21818 v2df __builtin_ia32_cmpngepd (v2df, v2df)
21819 v2df __builtin_ia32_cmpordpd (v2df, v2df)
21820 v2df __builtin_ia32_cmpeqsd (v2df, v2df)
21821 v2df __builtin_ia32_cmpltsd (v2df, v2df)
21822 v2df __builtin_ia32_cmplesd (v2df, v2df)
21823 v2df __builtin_ia32_cmpunordsd (v2df, v2df)
21824 v2df __builtin_ia32_cmpneqsd (v2df, v2df)
21825 v2df __builtin_ia32_cmpnltsd (v2df, v2df)
21826 v2df __builtin_ia32_cmpnlesd (v2df, v2df)
21827 v2df __builtin_ia32_cmpordsd (v2df, v2df)
21828 v2di __builtin_ia32_paddq (v2di, v2di)
21829 v2di __builtin_ia32_psubq (v2di, v2di)
21830 v2df __builtin_ia32_addpd (v2df, v2df)
21831 v2df __builtin_ia32_subpd (v2df, v2df)
21832 v2df __builtin_ia32_mulpd (v2df, v2df)
21833 v2df __builtin_ia32_divpd (v2df, v2df)
21834 v2df __builtin_ia32_addsd (v2df, v2df)
21835 v2df __builtin_ia32_subsd (v2df, v2df)
21836 v2df __builtin_ia32_mulsd (v2df, v2df)
21837 v2df __builtin_ia32_divsd (v2df, v2df)
21838 v2df __builtin_ia32_minpd (v2df, v2df)
21839 v2df __builtin_ia32_maxpd (v2df, v2df)
21840 v2df __builtin_ia32_minsd (v2df, v2df)
21841 v2df __builtin_ia32_maxsd (v2df, v2df)
21842 v2df __builtin_ia32_andpd (v2df, v2df)
21843 v2df __builtin_ia32_andnpd (v2df, v2df)
21844 v2df __builtin_ia32_orpd (v2df, v2df)
21845 v2df __builtin_ia32_xorpd (v2df, v2df)
21846 v2df __builtin_ia32_movsd (v2df, v2df)
21847 v2df __builtin_ia32_unpckhpd (v2df, v2df)
21848 v2df __builtin_ia32_unpcklpd (v2df, v2df)
21849 v16qi __builtin_ia32_paddb128 (v16qi, v16qi)
21850 v8hi __builtin_ia32_paddw128 (v8hi, v8hi)
21851 v4si __builtin_ia32_paddd128 (v4si, v4si)
21852 v2di __builtin_ia32_paddq128 (v2di, v2di)
21853 v16qi __builtin_ia32_psubb128 (v16qi, v16qi)
21854 v8hi __builtin_ia32_psubw128 (v8hi, v8hi)
21855 v4si __builtin_ia32_psubd128 (v4si, v4si)
21856 v2di __builtin_ia32_psubq128 (v2di, v2di)
21857 v8hi __builtin_ia32_pmullw128 (v8hi, v8hi)
21858 v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi)
21859 v2di __builtin_ia32_pand128 (v2di, v2di)
21860 v2di __builtin_ia32_pandn128 (v2di, v2di)
21861 v2di __builtin_ia32_por128 (v2di, v2di)
21862 v2di __builtin_ia32_pxor128 (v2di, v2di)
21863 v16qi __builtin_ia32_pavgb128 (v16qi, v16qi)
21864 v8hi __builtin_ia32_pavgw128 (v8hi, v8hi)
21865 v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi)
21866 v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi)
21867 v4si __builtin_ia32_pcmpeqd128 (v4si, v4si)
21868 v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi)
21869 v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi)
21870 v4si __builtin_ia32_pcmpgtd128 (v4si, v4si)
21871 v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi)
21872 v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi)
21873 v16qi __builtin_ia32_pminub128 (v16qi, v16qi)
21874 v8hi __builtin_ia32_pminsw128 (v8hi, v8hi)
21875 v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi)
21876 v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi)
21877 v4si __builtin_ia32_punpckhdq128 (v4si, v4si)
21878 v2di __builtin_ia32_punpckhqdq128 (v2di, v2di)
21879 v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi)
21880 v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi)
21881 v4si __builtin_ia32_punpckldq128 (v4si, v4si)
21882 v2di __builtin_ia32_punpcklqdq128 (v2di, v2di)
21883 v16qi __builtin_ia32_packsswb128 (v8hi, v8hi)
21884 v8hi __builtin_ia32_packssdw128 (v4si, v4si)
21885 v16qi __builtin_ia32_packuswb128 (v8hi, v8hi)
21886 v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi)
21887 void __builtin_ia32_maskmovdqu (v16qi, v16qi)
21888 v2df __builtin_ia32_loadupd (double *)
21889 void __builtin_ia32_storeupd (double *, v2df)
21890 v2df __builtin_ia32_loadhpd (v2df, double const *)
21891 v2df __builtin_ia32_loadlpd (v2df, double const *)
21892 int __builtin_ia32_movmskpd (v2df)
21893 int __builtin_ia32_pmovmskb128 (v16qi)
21894 void __builtin_ia32_movnti (int *, int)
21895 void __builtin_ia32_movnti64 (long long int *, long long int)
21896 void __builtin_ia32_movntpd (double *, v2df)
21897 void __builtin_ia32_movntdq (v2df *, v2df)
21898 v4si __builtin_ia32_pshufd (v4si, int)
21899 v8hi __builtin_ia32_pshuflw (v8hi, int)
21900 v8hi __builtin_ia32_pshufhw (v8hi, int)
21901 v2di __builtin_ia32_psadbw128 (v16qi, v16qi)
21902 v2df __builtin_ia32_sqrtpd (v2df)
21903 v2df __builtin_ia32_sqrtsd (v2df)
21904 v2df __builtin_ia32_shufpd (v2df, v2df, int)
21905 v2df __builtin_ia32_cvtdq2pd (v4si)
21906 v4sf __builtin_ia32_cvtdq2ps (v4si)
21907 v4si __builtin_ia32_cvtpd2dq (v2df)
21908 v2si __builtin_ia32_cvtpd2pi (v2df)
21909 v4sf __builtin_ia32_cvtpd2ps (v2df)
21910 v4si __builtin_ia32_cvttpd2dq (v2df)
21911 v2si __builtin_ia32_cvttpd2pi (v2df)
21912 v2df __builtin_ia32_cvtpi2pd (v2si)
21913 int __builtin_ia32_cvtsd2si (v2df)
21914 int __builtin_ia32_cvttsd2si (v2df)
21915 long long __builtin_ia32_cvtsd2si64 (v2df)
21916 long long __builtin_ia32_cvttsd2si64 (v2df)
21917 v4si __builtin_ia32_cvtps2dq (v4sf)
21918 v2df __builtin_ia32_cvtps2pd (v4sf)
21919 v4si __builtin_ia32_cvttps2dq (v4sf)
21920 v2df __builtin_ia32_cvtsi2sd (v2df, int)
21921 v2df __builtin_ia32_cvtsi642sd (v2df, long long)
21922 v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df)
21923 v2df __builtin_ia32_cvtss2sd (v2df, v4sf)
21924 void __builtin_ia32_clflush (const void *)
21925 void __builtin_ia32_lfence (void)
21926 void __builtin_ia32_mfence (void)
21927 v16qi __builtin_ia32_loaddqu (const char *)
21928 void __builtin_ia32_storedqu (char *, v16qi)
21929 v1di __builtin_ia32_pmuludq (v2si, v2si)
21930 v2di __builtin_ia32_pmuludq128 (v4si, v4si)
21931 v8hi __builtin_ia32_psllw128 (v8hi, v8hi)
21932 v4si __builtin_ia32_pslld128 (v4si, v4si)
21933 v2di __builtin_ia32_psllq128 (v2di, v2di)
21934 v8hi __builtin_ia32_psrlw128 (v8hi, v8hi)
21935 v4si __builtin_ia32_psrld128 (v4si, v4si)
21936 v2di __builtin_ia32_psrlq128 (v2di, v2di)
21937 v8hi __builtin_ia32_psraw128 (v8hi, v8hi)
21938 v4si __builtin_ia32_psrad128 (v4si, v4si)
21939 v2di __builtin_ia32_pslldqi128 (v2di, int)
21940 v8hi __builtin_ia32_psllwi128 (v8hi, int)
21941 v4si __builtin_ia32_pslldi128 (v4si, int)
21942 v2di __builtin_ia32_psllqi128 (v2di, int)
21943 v2di __builtin_ia32_psrldqi128 (v2di, int)
21944 v8hi __builtin_ia32_psrlwi128 (v8hi, int)
21945 v4si __builtin_ia32_psrldi128 (v4si, int)
21946 v2di __builtin_ia32_psrlqi128 (v2di, int)
21947 v8hi __builtin_ia32_psrawi128 (v8hi, int)
21948 v4si __builtin_ia32_psradi128 (v4si, int)
21949 v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi)
21950 v2di __builtin_ia32_movq128 (v2di)
21953 The following built-in functions are available when @option{-msse3} is used.
21954 All of them generate the machine instruction that is part of the name.
21957 v2df __builtin_ia32_addsubpd (v2df, v2df)
21958 v4sf __builtin_ia32_addsubps (v4sf, v4sf)
21959 v2df __builtin_ia32_haddpd (v2df, v2df)
21960 v4sf __builtin_ia32_haddps (v4sf, v4sf)
21961 v2df __builtin_ia32_hsubpd (v2df, v2df)
21962 v4sf __builtin_ia32_hsubps (v4sf, v4sf)
21963 v16qi __builtin_ia32_lddqu (char const *)
21964 void __builtin_ia32_monitor (void *, unsigned int, unsigned int)
21965 v4sf __builtin_ia32_movshdup (v4sf)
21966 v4sf __builtin_ia32_movsldup (v4sf)
21967 void __builtin_ia32_mwait (unsigned int, unsigned int)
21970 The following built-in functions are available when @option{-mssse3} is used.
21971 All of them generate the machine instruction that is part of the name.
21974 v2si __builtin_ia32_phaddd (v2si, v2si)
21975 v4hi __builtin_ia32_phaddw (v4hi, v4hi)
21976 v4hi __builtin_ia32_phaddsw (v4hi, v4hi)
21977 v2si __builtin_ia32_phsubd (v2si, v2si)
21978 v4hi __builtin_ia32_phsubw (v4hi, v4hi)
21979 v4hi __builtin_ia32_phsubsw (v4hi, v4hi)
21980 v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi)
21981 v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi)
21982 v8qi __builtin_ia32_pshufb (v8qi, v8qi)
21983 v8qi __builtin_ia32_psignb (v8qi, v8qi)
21984 v2si __builtin_ia32_psignd (v2si, v2si)
21985 v4hi __builtin_ia32_psignw (v4hi, v4hi)
21986 v1di __builtin_ia32_palignr (v1di, v1di, int)
21987 v8qi __builtin_ia32_pabsb (v8qi)
21988 v2si __builtin_ia32_pabsd (v2si)
21989 v4hi __builtin_ia32_pabsw (v4hi)
21992 The following built-in functions are available when @option{-mssse3} is used.
21993 All of them generate the machine instruction that is part of the name.
21996 v4si __builtin_ia32_phaddd128 (v4si, v4si)
21997 v8hi __builtin_ia32_phaddw128 (v8hi, v8hi)
21998 v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi)
21999 v4si __builtin_ia32_phsubd128 (v4si, v4si)
22000 v8hi __builtin_ia32_phsubw128 (v8hi, v8hi)
22001 v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi)
22002 v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi)
22003 v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi)
22004 v16qi __builtin_ia32_pshufb128 (v16qi, v16qi)
22005 v16qi __builtin_ia32_psignb128 (v16qi, v16qi)
22006 v4si __builtin_ia32_psignd128 (v4si, v4si)
22007 v8hi __builtin_ia32_psignw128 (v8hi, v8hi)
22008 v2di __builtin_ia32_palignr128 (v2di, v2di, int)
22009 v16qi __builtin_ia32_pabsb128 (v16qi)
22010 v4si __builtin_ia32_pabsd128 (v4si)
22011 v8hi __builtin_ia32_pabsw128 (v8hi)
22014 The following built-in functions are available when @option{-msse4.1} is
22015 used. All of them generate the machine instruction that is part of the
22019 v2df __builtin_ia32_blendpd (v2df, v2df, const int)
22020 v4sf __builtin_ia32_blendps (v4sf, v4sf, const int)
22021 v2df __builtin_ia32_blendvpd (v2df, v2df, v2df)
22022 v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf)
22023 v2df __builtin_ia32_dppd (v2df, v2df, const int)
22024 v4sf __builtin_ia32_dpps (v4sf, v4sf, const int)
22025 v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int)
22026 v2di __builtin_ia32_movntdqa (v2di *);
22027 v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int)
22028 v8hi __builtin_ia32_packusdw128 (v4si, v4si)
22029 v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi)
22030 v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int)
22031 v2di __builtin_ia32_pcmpeqq (v2di, v2di)
22032 v8hi __builtin_ia32_phminposuw128 (v8hi)
22033 v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi)
22034 v4si __builtin_ia32_pmaxsd128 (v4si, v4si)
22035 v4si __builtin_ia32_pmaxud128 (v4si, v4si)
22036 v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi)
22037 v16qi __builtin_ia32_pminsb128 (v16qi, v16qi)
22038 v4si __builtin_ia32_pminsd128 (v4si, v4si)
22039 v4si __builtin_ia32_pminud128 (v4si, v4si)
22040 v8hi __builtin_ia32_pminuw128 (v8hi, v8hi)
22041 v4si __builtin_ia32_pmovsxbd128 (v16qi)
22042 v2di __builtin_ia32_pmovsxbq128 (v16qi)
22043 v8hi __builtin_ia32_pmovsxbw128 (v16qi)
22044 v2di __builtin_ia32_pmovsxdq128 (v4si)
22045 v4si __builtin_ia32_pmovsxwd128 (v8hi)
22046 v2di __builtin_ia32_pmovsxwq128 (v8hi)
22047 v4si __builtin_ia32_pmovzxbd128 (v16qi)
22048 v2di __builtin_ia32_pmovzxbq128 (v16qi)
22049 v8hi __builtin_ia32_pmovzxbw128 (v16qi)
22050 v2di __builtin_ia32_pmovzxdq128 (v4si)
22051 v4si __builtin_ia32_pmovzxwd128 (v8hi)
22052 v2di __builtin_ia32_pmovzxwq128 (v8hi)
22053 v2di __builtin_ia32_pmuldq128 (v4si, v4si)
22054 v4si __builtin_ia32_pmulld128 (v4si, v4si)
22055 int __builtin_ia32_ptestc128 (v2di, v2di)
22056 int __builtin_ia32_ptestnzc128 (v2di, v2di)
22057 int __builtin_ia32_ptestz128 (v2di, v2di)
22058 v2df __builtin_ia32_roundpd (v2df, const int)
22059 v4sf __builtin_ia32_roundps (v4sf, const int)
22060 v2df __builtin_ia32_roundsd (v2df, v2df, const int)
22061 v4sf __builtin_ia32_roundss (v4sf, v4sf, const int)
22064 The following built-in functions are available when @option{-msse4.1} is
22068 @item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)
22069 Generates the @code{insertps} machine instruction.
22070 @item int __builtin_ia32_vec_ext_v16qi (v16qi, const int)
22071 Generates the @code{pextrb} machine instruction.
22072 @item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)
22073 Generates the @code{pinsrb} machine instruction.
22074 @item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)
22075 Generates the @code{pinsrd} machine instruction.
22076 @item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)
22077 Generates the @code{pinsrq} machine instruction in 64bit mode.
22080 The following built-in functions are changed to generate new SSE4.1
22081 instructions when @option{-msse4.1} is used.
22084 @item float __builtin_ia32_vec_ext_v4sf (v4sf, const int)
22085 Generates the @code{extractps} machine instruction.
22086 @item int __builtin_ia32_vec_ext_v4si (v4si, const int)
22087 Generates the @code{pextrd} machine instruction.
22088 @item long long __builtin_ia32_vec_ext_v2di (v2di, const int)
22089 Generates the @code{pextrq} machine instruction in 64bit mode.
22092 The following built-in functions are available when @option{-msse4.2} is
22093 used. All of them generate the machine instruction that is part of the
22097 v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int)
22098 int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int)
22099 int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int)
22100 int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int)
22101 int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int)
22102 int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int)
22103 int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int)
22104 v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int)
22105 int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int)
22106 int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int)
22107 int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int)
22108 int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int)
22109 int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int)
22110 int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int)
22111 v2di __builtin_ia32_pcmpgtq (v2di, v2di)
22114 The following built-in functions are available when @option{-msse4.2} is
22118 @item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char)
22119 Generates the @code{crc32b} machine instruction.
22120 @item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short)
22121 Generates the @code{crc32w} machine instruction.
22122 @item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int)
22123 Generates the @code{crc32l} machine instruction.
22124 @item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long)
22125 Generates the @code{crc32q} machine instruction.
22128 The following built-in functions are changed to generate new SSE4.2
22129 instructions when @option{-msse4.2} is used.
22132 @item int __builtin_popcount (unsigned int)
22133 Generates the @code{popcntl} machine instruction.
22134 @item int __builtin_popcountl (unsigned long)
22135 Generates the @code{popcntl} or @code{popcntq} machine instruction,
22136 depending on the size of @code{unsigned long}.
22137 @item int __builtin_popcountll (unsigned long long)
22138 Generates the @code{popcntq} machine instruction.
22141 The following built-in functions are available when @option{-mavx} is
22142 used. All of them generate the machine instruction that is part of the
22146 v4df __builtin_ia32_addpd256 (v4df,v4df)
22147 v8sf __builtin_ia32_addps256 (v8sf,v8sf)
22148 v4df __builtin_ia32_addsubpd256 (v4df,v4df)
22149 v8sf __builtin_ia32_addsubps256 (v8sf,v8sf)
22150 v4df __builtin_ia32_andnpd256 (v4df,v4df)
22151 v8sf __builtin_ia32_andnps256 (v8sf,v8sf)
22152 v4df __builtin_ia32_andpd256 (v4df,v4df)
22153 v8sf __builtin_ia32_andps256 (v8sf,v8sf)
22154 v4df __builtin_ia32_blendpd256 (v4df,v4df,int)
22155 v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int)
22156 v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df)
22157 v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf)
22158 v2df __builtin_ia32_cmppd (v2df,v2df,int)
22159 v4df __builtin_ia32_cmppd256 (v4df,v4df,int)
22160 v4sf __builtin_ia32_cmpps (v4sf,v4sf,int)
22161 v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int)
22162 v2df __builtin_ia32_cmpsd (v2df,v2df,int)
22163 v4sf __builtin_ia32_cmpss (v4sf,v4sf,int)
22164 v4df __builtin_ia32_cvtdq2pd256 (v4si)
22165 v8sf __builtin_ia32_cvtdq2ps256 (v8si)
22166 v4si __builtin_ia32_cvtpd2dq256 (v4df)
22167 v4sf __builtin_ia32_cvtpd2ps256 (v4df)
22168 v8si __builtin_ia32_cvtps2dq256 (v8sf)
22169 v4df __builtin_ia32_cvtps2pd256 (v4sf)
22170 v4si __builtin_ia32_cvttpd2dq256 (v4df)
22171 v8si __builtin_ia32_cvttps2dq256 (v8sf)
22172 v4df __builtin_ia32_divpd256 (v4df,v4df)
22173 v8sf __builtin_ia32_divps256 (v8sf,v8sf)
22174 v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int)
22175 v4df __builtin_ia32_haddpd256 (v4df,v4df)
22176 v8sf __builtin_ia32_haddps256 (v8sf,v8sf)
22177 v4df __builtin_ia32_hsubpd256 (v4df,v4df)
22178 v8sf __builtin_ia32_hsubps256 (v8sf,v8sf)
22179 v32qi __builtin_ia32_lddqu256 (pcchar)
22180 v32qi __builtin_ia32_loaddqu256 (pcchar)
22181 v4df __builtin_ia32_loadupd256 (pcdouble)
22182 v8sf __builtin_ia32_loadups256 (pcfloat)
22183 v2df __builtin_ia32_maskloadpd (pcv2df,v2df)
22184 v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df)
22185 v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf)
22186 v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf)
22187 void __builtin_ia32_maskstorepd (pv2df,v2df,v2df)
22188 void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df)
22189 void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf)
22190 void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf)
22191 v4df __builtin_ia32_maxpd256 (v4df,v4df)
22192 v8sf __builtin_ia32_maxps256 (v8sf,v8sf)
22193 v4df __builtin_ia32_minpd256 (v4df,v4df)
22194 v8sf __builtin_ia32_minps256 (v8sf,v8sf)
22195 v4df __builtin_ia32_movddup256 (v4df)
22196 int __builtin_ia32_movmskpd256 (v4df)
22197 int __builtin_ia32_movmskps256 (v8sf)
22198 v8sf __builtin_ia32_movshdup256 (v8sf)
22199 v8sf __builtin_ia32_movsldup256 (v8sf)
22200 v4df __builtin_ia32_mulpd256 (v4df,v4df)
22201 v8sf __builtin_ia32_mulps256 (v8sf,v8sf)
22202 v4df __builtin_ia32_orpd256 (v4df,v4df)
22203 v8sf __builtin_ia32_orps256 (v8sf,v8sf)
22204 v2df __builtin_ia32_pd_pd256 (v4df)
22205 v4df __builtin_ia32_pd256_pd (v2df)
22206 v4sf __builtin_ia32_ps_ps256 (v8sf)
22207 v8sf __builtin_ia32_ps256_ps (v4sf)
22208 int __builtin_ia32_ptestc256 (v4di,v4di,ptest)
22209 int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest)
22210 int __builtin_ia32_ptestz256 (v4di,v4di,ptest)
22211 v8sf __builtin_ia32_rcpps256 (v8sf)
22212 v4df __builtin_ia32_roundpd256 (v4df,int)
22213 v8sf __builtin_ia32_roundps256 (v8sf,int)
22214 v8sf __builtin_ia32_rsqrtps_nr256 (v8sf)
22215 v8sf __builtin_ia32_rsqrtps256 (v8sf)
22216 v4df __builtin_ia32_shufpd256 (v4df,v4df,int)
22217 v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int)
22218 v4si __builtin_ia32_si_si256 (v8si)
22219 v8si __builtin_ia32_si256_si (v4si)
22220 v4df __builtin_ia32_sqrtpd256 (v4df)
22221 v8sf __builtin_ia32_sqrtps_nr256 (v8sf)
22222 v8sf __builtin_ia32_sqrtps256 (v8sf)
22223 void __builtin_ia32_storedqu256 (pchar,v32qi)
22224 void __builtin_ia32_storeupd256 (pdouble,v4df)
22225 void __builtin_ia32_storeups256 (pfloat,v8sf)
22226 v4df __builtin_ia32_subpd256 (v4df,v4df)
22227 v8sf __builtin_ia32_subps256 (v8sf,v8sf)
22228 v4df __builtin_ia32_unpckhpd256 (v4df,v4df)
22229 v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf)
22230 v4df __builtin_ia32_unpcklpd256 (v4df,v4df)
22231 v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf)
22232 v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df)
22233 v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf)
22234 v4df __builtin_ia32_vbroadcastsd256 (pcdouble)
22235 v4sf __builtin_ia32_vbroadcastss (pcfloat)
22236 v8sf __builtin_ia32_vbroadcastss256 (pcfloat)
22237 v2df __builtin_ia32_vextractf128_pd256 (v4df,int)
22238 v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int)
22239 v4si __builtin_ia32_vextractf128_si256 (v8si,int)
22240 v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int)
22241 v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int)
22242 v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int)
22243 v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int)
22244 v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int)
22245 v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int)
22246 v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int)
22247 v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int)
22248 v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int)
22249 v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int)
22250 v2df __builtin_ia32_vpermilpd (v2df,int)
22251 v4df __builtin_ia32_vpermilpd256 (v4df,int)
22252 v4sf __builtin_ia32_vpermilps (v4sf,int)
22253 v8sf __builtin_ia32_vpermilps256 (v8sf,int)
22254 v2df __builtin_ia32_vpermilvarpd (v2df,v2di)
22255 v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di)
22256 v4sf __builtin_ia32_vpermilvarps (v4sf,v4si)
22257 v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si)
22258 int __builtin_ia32_vtestcpd (v2df,v2df,ptest)
22259 int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest)
22260 int __builtin_ia32_vtestcps (v4sf,v4sf,ptest)
22261 int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest)
22262 int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest)
22263 int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest)
22264 int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest)
22265 int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest)
22266 int __builtin_ia32_vtestzpd (v2df,v2df,ptest)
22267 int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest)
22268 int __builtin_ia32_vtestzps (v4sf,v4sf,ptest)
22269 int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest)
22270 void __builtin_ia32_vzeroall (void)
22271 void __builtin_ia32_vzeroupper (void)
22272 v4df __builtin_ia32_xorpd256 (v4df,v4df)
22273 v8sf __builtin_ia32_xorps256 (v8sf,v8sf)
22276 The following built-in functions are available when @option{-mavx2} is
22277 used. All of them generate the machine instruction that is part of the
22281 v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int)
22282 v32qi __builtin_ia32_pabsb256 (v32qi)
22283 v16hi __builtin_ia32_pabsw256 (v16hi)
22284 v8si __builtin_ia32_pabsd256 (v8si)
22285 v16hi __builtin_ia32_packssdw256 (v8si,v8si)
22286 v32qi __builtin_ia32_packsswb256 (v16hi,v16hi)
22287 v16hi __builtin_ia32_packusdw256 (v8si,v8si)
22288 v32qi __builtin_ia32_packuswb256 (v16hi,v16hi)
22289 v32qi __builtin_ia32_paddb256 (v32qi,v32qi)
22290 v16hi __builtin_ia32_paddw256 (v16hi,v16hi)
22291 v8si __builtin_ia32_paddd256 (v8si,v8si)
22292 v4di __builtin_ia32_paddq256 (v4di,v4di)
22293 v32qi __builtin_ia32_paddsb256 (v32qi,v32qi)
22294 v16hi __builtin_ia32_paddsw256 (v16hi,v16hi)
22295 v32qi __builtin_ia32_paddusb256 (v32qi,v32qi)
22296 v16hi __builtin_ia32_paddusw256 (v16hi,v16hi)
22297 v4di __builtin_ia32_palignr256 (v4di,v4di,int)
22298 v4di __builtin_ia32_andsi256 (v4di,v4di)
22299 v4di __builtin_ia32_andnotsi256 (v4di,v4di)
22300 v32qi __builtin_ia32_pavgb256 (v32qi,v32qi)
22301 v16hi __builtin_ia32_pavgw256 (v16hi,v16hi)
22302 v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi)
22303 v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int)
22304 v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi)
22305 v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi)
22306 v8si __builtin_ia32_pcmpeqd256 (c8si,v8si)
22307 v4di __builtin_ia32_pcmpeqq256 (v4di,v4di)
22308 v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi)
22309 v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi)
22310 v8si __builtin_ia32_pcmpgtd256 (v8si,v8si)
22311 v4di __builtin_ia32_pcmpgtq256 (v4di,v4di)
22312 v16hi __builtin_ia32_phaddw256 (v16hi,v16hi)
22313 v8si __builtin_ia32_phaddd256 (v8si,v8si)
22314 v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi)
22315 v16hi __builtin_ia32_phsubw256 (v16hi,v16hi)
22316 v8si __builtin_ia32_phsubd256 (v8si,v8si)
22317 v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi)
22318 v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi)
22319 v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi)
22320 v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi)
22321 v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi)
22322 v8si __builtin_ia32_pmaxsd256 (v8si,v8si)
22323 v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi)
22324 v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi)
22325 v8si __builtin_ia32_pmaxud256 (v8si,v8si)
22326 v32qi __builtin_ia32_pminsb256 (v32qi,v32qi)
22327 v16hi __builtin_ia32_pminsw256 (v16hi,v16hi)
22328 v8si __builtin_ia32_pminsd256 (v8si,v8si)
22329 v32qi __builtin_ia32_pminub256 (v32qi,v32qi)
22330 v16hi __builtin_ia32_pminuw256 (v16hi,v16hi)
22331 v8si __builtin_ia32_pminud256 (v8si,v8si)
22332 int __builtin_ia32_pmovmskb256 (v32qi)
22333 v16hi __builtin_ia32_pmovsxbw256 (v16qi)
22334 v8si __builtin_ia32_pmovsxbd256 (v16qi)
22335 v4di __builtin_ia32_pmovsxbq256 (v16qi)
22336 v8si __builtin_ia32_pmovsxwd256 (v8hi)
22337 v4di __builtin_ia32_pmovsxwq256 (v8hi)
22338 v4di __builtin_ia32_pmovsxdq256 (v4si)
22339 v16hi __builtin_ia32_pmovzxbw256 (v16qi)
22340 v8si __builtin_ia32_pmovzxbd256 (v16qi)
22341 v4di __builtin_ia32_pmovzxbq256 (v16qi)
22342 v8si __builtin_ia32_pmovzxwd256 (v8hi)
22343 v4di __builtin_ia32_pmovzxwq256 (v8hi)
22344 v4di __builtin_ia32_pmovzxdq256 (v4si)
22345 v4di __builtin_ia32_pmuldq256 (v8si,v8si)
22346 v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi)
22347 v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi)
22348 v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi)
22349 v16hi __builtin_ia32_pmullw256 (v16hi,v16hi)
22350 v8si __builtin_ia32_pmulld256 (v8si,v8si)
22351 v4di __builtin_ia32_pmuludq256 (v8si,v8si)
22352 v4di __builtin_ia32_por256 (v4di,v4di)
22353 v16hi __builtin_ia32_psadbw256 (v32qi,v32qi)
22354 v32qi __builtin_ia32_pshufb256 (v32qi,v32qi)
22355 v8si __builtin_ia32_pshufd256 (v8si,int)
22356 v16hi __builtin_ia32_pshufhw256 (v16hi,int)
22357 v16hi __builtin_ia32_pshuflw256 (v16hi,int)
22358 v32qi __builtin_ia32_psignb256 (v32qi,v32qi)
22359 v16hi __builtin_ia32_psignw256 (v16hi,v16hi)
22360 v8si __builtin_ia32_psignd256 (v8si,v8si)
22361 v4di __builtin_ia32_pslldqi256 (v4di,int)
22362 v16hi __builtin_ia32_psllwi256 (16hi,int)
22363 v16hi __builtin_ia32_psllw256(v16hi,v8hi)
22364 v8si __builtin_ia32_pslldi256 (v8si,int)
22365 v8si __builtin_ia32_pslld256(v8si,v4si)
22366 v4di __builtin_ia32_psllqi256 (v4di,int)
22367 v4di __builtin_ia32_psllq256(v4di,v2di)
22368 v16hi __builtin_ia32_psrawi256 (v16hi,int)
22369 v16hi __builtin_ia32_psraw256 (v16hi,v8hi)
22370 v8si __builtin_ia32_psradi256 (v8si,int)
22371 v8si __builtin_ia32_psrad256 (v8si,v4si)
22372 v4di __builtin_ia32_psrldqi256 (v4di, int)
22373 v16hi __builtin_ia32_psrlwi256 (v16hi,int)
22374 v16hi __builtin_ia32_psrlw256 (v16hi,v8hi)
22375 v8si __builtin_ia32_psrldi256 (v8si,int)
22376 v8si __builtin_ia32_psrld256 (v8si,v4si)
22377 v4di __builtin_ia32_psrlqi256 (v4di,int)
22378 v4di __builtin_ia32_psrlq256(v4di,v2di)
22379 v32qi __builtin_ia32_psubb256 (v32qi,v32qi)
22380 v32hi __builtin_ia32_psubw256 (v16hi,v16hi)
22381 v8si __builtin_ia32_psubd256 (v8si,v8si)
22382 v4di __builtin_ia32_psubq256 (v4di,v4di)
22383 v32qi __builtin_ia32_psubsb256 (v32qi,v32qi)
22384 v16hi __builtin_ia32_psubsw256 (v16hi,v16hi)
22385 v32qi __builtin_ia32_psubusb256 (v32qi,v32qi)
22386 v16hi __builtin_ia32_psubusw256 (v16hi,v16hi)
22387 v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi)
22388 v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi)
22389 v8si __builtin_ia32_punpckhdq256 (v8si,v8si)
22390 v4di __builtin_ia32_punpckhqdq256 (v4di,v4di)
22391 v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi)
22392 v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi)
22393 v8si __builtin_ia32_punpckldq256 (v8si,v8si)
22394 v4di __builtin_ia32_punpcklqdq256 (v4di,v4di)
22395 v4di __builtin_ia32_pxor256 (v4di,v4di)
22396 v4di __builtin_ia32_movntdqa256 (pv4di)
22397 v4sf __builtin_ia32_vbroadcastss_ps (v4sf)
22398 v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf)
22399 v4df __builtin_ia32_vbroadcastsd_pd256 (v2df)
22400 v4di __builtin_ia32_vbroadcastsi256 (v2di)
22401 v4si __builtin_ia32_pblendd128 (v4si,v4si)
22402 v8si __builtin_ia32_pblendd256 (v8si,v8si)
22403 v32qi __builtin_ia32_pbroadcastb256 (v16qi)
22404 v16hi __builtin_ia32_pbroadcastw256 (v8hi)
22405 v8si __builtin_ia32_pbroadcastd256 (v4si)
22406 v4di __builtin_ia32_pbroadcastq256 (v2di)
22407 v16qi __builtin_ia32_pbroadcastb128 (v16qi)
22408 v8hi __builtin_ia32_pbroadcastw128 (v8hi)
22409 v4si __builtin_ia32_pbroadcastd128 (v4si)
22410 v2di __builtin_ia32_pbroadcastq128 (v2di)
22411 v8si __builtin_ia32_permvarsi256 (v8si,v8si)
22412 v4df __builtin_ia32_permdf256 (v4df,int)
22413 v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf)
22414 v4di __builtin_ia32_permdi256 (v4di,int)
22415 v4di __builtin_ia32_permti256 (v4di,v4di,int)
22416 v4di __builtin_ia32_extract128i256 (v4di,int)
22417 v4di __builtin_ia32_insert128i256 (v4di,v2di,int)
22418 v8si __builtin_ia32_maskloadd256 (pcv8si,v8si)
22419 v4di __builtin_ia32_maskloadq256 (pcv4di,v4di)
22420 v4si __builtin_ia32_maskloadd (pcv4si,v4si)
22421 v2di __builtin_ia32_maskloadq (pcv2di,v2di)
22422 void __builtin_ia32_maskstored256 (pv8si,v8si,v8si)
22423 void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di)
22424 void __builtin_ia32_maskstored (pv4si,v4si,v4si)
22425 void __builtin_ia32_maskstoreq (pv2di,v2di,v2di)
22426 v8si __builtin_ia32_psllv8si (v8si,v8si)
22427 v4si __builtin_ia32_psllv4si (v4si,v4si)
22428 v4di __builtin_ia32_psllv4di (v4di,v4di)
22429 v2di __builtin_ia32_psllv2di (v2di,v2di)
22430 v8si __builtin_ia32_psrav8si (v8si,v8si)
22431 v4si __builtin_ia32_psrav4si (v4si,v4si)
22432 v8si __builtin_ia32_psrlv8si (v8si,v8si)
22433 v4si __builtin_ia32_psrlv4si (v4si,v4si)
22434 v4di __builtin_ia32_psrlv4di (v4di,v4di)
22435 v2di __builtin_ia32_psrlv2di (v2di,v2di)
22436 v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int)
22437 v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int)
22438 v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int)
22439 v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int)
22440 v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int)
22441 v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int)
22442 v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int)
22443 v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int)
22444 v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int)
22445 v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int)
22446 v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int)
22447 v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int)
22448 v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int)
22449 v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int)
22450 v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int)
22451 v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int)
22454 The following built-in functions are available when @option{-maes} is
22455 used. All of them generate the machine instruction that is part of the
22459 v2di __builtin_ia32_aesenc128 (v2di, v2di)
22460 v2di __builtin_ia32_aesenclast128 (v2di, v2di)
22461 v2di __builtin_ia32_aesdec128 (v2di, v2di)
22462 v2di __builtin_ia32_aesdeclast128 (v2di, v2di)
22463 v2di __builtin_ia32_aeskeygenassist128 (v2di, const int)
22464 v2di __builtin_ia32_aesimc128 (v2di)
22467 The following built-in function is available when @option{-mpclmul} is
22471 @item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)
22472 Generates the @code{pclmulqdq} machine instruction.
22475 The following built-in function is available when @option{-mfsgsbase} is
22476 used. All of them generate the machine instruction that is part of the
22480 unsigned int __builtin_ia32_rdfsbase32 (void)
22481 unsigned long long __builtin_ia32_rdfsbase64 (void)
22482 unsigned int __builtin_ia32_rdgsbase32 (void)
22483 unsigned long long __builtin_ia32_rdgsbase64 (void)
22484 void _writefsbase_u32 (unsigned int)
22485 void _writefsbase_u64 (unsigned long long)
22486 void _writegsbase_u32 (unsigned int)
22487 void _writegsbase_u64 (unsigned long long)
22490 The following built-in function is available when @option{-mrdrnd} is
22491 used. All of them generate the machine instruction that is part of the
22495 unsigned int __builtin_ia32_rdrand16_step (unsigned short *)
22496 unsigned int __builtin_ia32_rdrand32_step (unsigned int *)
22497 unsigned int __builtin_ia32_rdrand64_step (unsigned long long *)
22500 The following built-in function is available when @option{-mptwrite} is
22501 used. All of them generate the machine instruction that is part of the
22505 void __builtin_ia32_ptwrite32 (unsigned)
22506 void __builtin_ia32_ptwrite64 (unsigned long long)
22509 The following built-in functions are available when @option{-msse4a} is used.
22510 All of them generate the machine instruction that is part of the name.
22513 void __builtin_ia32_movntsd (double *, v2df)
22514 void __builtin_ia32_movntss (float *, v4sf)
22515 v2di __builtin_ia32_extrq (v2di, v16qi)
22516 v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int)
22517 v2di __builtin_ia32_insertq (v2di, v2di)
22518 v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int)
22521 The following built-in functions are available when @option{-mxop} is used.
22523 v2df __builtin_ia32_vfrczpd (v2df)
22524 v4sf __builtin_ia32_vfrczps (v4sf)
22525 v2df __builtin_ia32_vfrczsd (v2df)
22526 v4sf __builtin_ia32_vfrczss (v4sf)
22527 v4df __builtin_ia32_vfrczpd256 (v4df)
22528 v8sf __builtin_ia32_vfrczps256 (v8sf)
22529 v2di __builtin_ia32_vpcmov (v2di, v2di, v2di)
22530 v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di)
22531 v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si)
22532 v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi)
22533 v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi)
22534 v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df)
22535 v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf)
22536 v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di)
22537 v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si)
22538 v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi)
22539 v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi)
22540 v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df)
22541 v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf)
22542 v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi)
22543 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
22544 v4si __builtin_ia32_vpcomeqd (v4si, v4si)
22545 v2di __builtin_ia32_vpcomeqq (v2di, v2di)
22546 v16qi __builtin_ia32_vpcomequb (v16qi, v16qi)
22547 v4si __builtin_ia32_vpcomequd (v4si, v4si)
22548 v2di __builtin_ia32_vpcomequq (v2di, v2di)
22549 v8hi __builtin_ia32_vpcomequw (v8hi, v8hi)
22550 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
22551 v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi)
22552 v4si __builtin_ia32_vpcomfalsed (v4si, v4si)
22553 v2di __builtin_ia32_vpcomfalseq (v2di, v2di)
22554 v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi)
22555 v4si __builtin_ia32_vpcomfalseud (v4si, v4si)
22556 v2di __builtin_ia32_vpcomfalseuq (v2di, v2di)
22557 v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi)
22558 v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi)
22559 v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi)
22560 v4si __builtin_ia32_vpcomged (v4si, v4si)
22561 v2di __builtin_ia32_vpcomgeq (v2di, v2di)
22562 v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi)
22563 v4si __builtin_ia32_vpcomgeud (v4si, v4si)
22564 v2di __builtin_ia32_vpcomgeuq (v2di, v2di)
22565 v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi)
22566 v8hi __builtin_ia32_vpcomgew (v8hi, v8hi)
22567 v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi)
22568 v4si __builtin_ia32_vpcomgtd (v4si, v4si)
22569 v2di __builtin_ia32_vpcomgtq (v2di, v2di)
22570 v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi)
22571 v4si __builtin_ia32_vpcomgtud (v4si, v4si)
22572 v2di __builtin_ia32_vpcomgtuq (v2di, v2di)
22573 v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi)
22574 v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi)
22575 v16qi __builtin_ia32_vpcomleb (v16qi, v16qi)
22576 v4si __builtin_ia32_vpcomled (v4si, v4si)
22577 v2di __builtin_ia32_vpcomleq (v2di, v2di)
22578 v16qi __builtin_ia32_vpcomleub (v16qi, v16qi)
22579 v4si __builtin_ia32_vpcomleud (v4si, v4si)
22580 v2di __builtin_ia32_vpcomleuq (v2di, v2di)
22581 v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi)
22582 v8hi __builtin_ia32_vpcomlew (v8hi, v8hi)
22583 v16qi __builtin_ia32_vpcomltb (v16qi, v16qi)
22584 v4si __builtin_ia32_vpcomltd (v4si, v4si)
22585 v2di __builtin_ia32_vpcomltq (v2di, v2di)
22586 v16qi __builtin_ia32_vpcomltub (v16qi, v16qi)
22587 v4si __builtin_ia32_vpcomltud (v4si, v4si)
22588 v2di __builtin_ia32_vpcomltuq (v2di, v2di)
22589 v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi)
22590 v8hi __builtin_ia32_vpcomltw (v8hi, v8hi)
22591 v16qi __builtin_ia32_vpcomneb (v16qi, v16qi)
22592 v4si __builtin_ia32_vpcomned (v4si, v4si)
22593 v2di __builtin_ia32_vpcomneq (v2di, v2di)
22594 v16qi __builtin_ia32_vpcomneub (v16qi, v16qi)
22595 v4si __builtin_ia32_vpcomneud (v4si, v4si)
22596 v2di __builtin_ia32_vpcomneuq (v2di, v2di)
22597 v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi)
22598 v8hi __builtin_ia32_vpcomnew (v8hi, v8hi)
22599 v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi)
22600 v4si __builtin_ia32_vpcomtrued (v4si, v4si)
22601 v2di __builtin_ia32_vpcomtrueq (v2di, v2di)
22602 v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi)
22603 v4si __builtin_ia32_vpcomtrueud (v4si, v4si)
22604 v2di __builtin_ia32_vpcomtrueuq (v2di, v2di)
22605 v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi)
22606 v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi)
22607 v4si __builtin_ia32_vphaddbd (v16qi)
22608 v2di __builtin_ia32_vphaddbq (v16qi)
22609 v8hi __builtin_ia32_vphaddbw (v16qi)
22610 v2di __builtin_ia32_vphadddq (v4si)
22611 v4si __builtin_ia32_vphaddubd (v16qi)
22612 v2di __builtin_ia32_vphaddubq (v16qi)
22613 v8hi __builtin_ia32_vphaddubw (v16qi)
22614 v2di __builtin_ia32_vphaddudq (v4si)
22615 v4si __builtin_ia32_vphadduwd (v8hi)
22616 v2di __builtin_ia32_vphadduwq (v8hi)
22617 v4si __builtin_ia32_vphaddwd (v8hi)
22618 v2di __builtin_ia32_vphaddwq (v8hi)
22619 v8hi __builtin_ia32_vphsubbw (v16qi)
22620 v2di __builtin_ia32_vphsubdq (v4si)
22621 v4si __builtin_ia32_vphsubwd (v8hi)
22622 v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si)
22623 v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di)
22624 v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di)
22625 v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si)
22626 v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di)
22627 v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di)
22628 v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si)
22629 v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi)
22630 v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si)
22631 v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi)
22632 v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si)
22633 v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si)
22634 v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi)
22635 v16qi __builtin_ia32_vprotb (v16qi, v16qi)
22636 v4si __builtin_ia32_vprotd (v4si, v4si)
22637 v2di __builtin_ia32_vprotq (v2di, v2di)
22638 v8hi __builtin_ia32_vprotw (v8hi, v8hi)
22639 v16qi __builtin_ia32_vpshab (v16qi, v16qi)
22640 v4si __builtin_ia32_vpshad (v4si, v4si)
22641 v2di __builtin_ia32_vpshaq (v2di, v2di)
22642 v8hi __builtin_ia32_vpshaw (v8hi, v8hi)
22643 v16qi __builtin_ia32_vpshlb (v16qi, v16qi)
22644 v4si __builtin_ia32_vpshld (v4si, v4si)
22645 v2di __builtin_ia32_vpshlq (v2di, v2di)
22646 v8hi __builtin_ia32_vpshlw (v8hi, v8hi)
22649 The following built-in functions are available when @option{-mfma4} is used.
22650 All of them generate the machine instruction that is part of the name.
22653 v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df)
22654 v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf)
22655 v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df)
22656 v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf)
22657 v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df)
22658 v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf)
22659 v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df)
22660 v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf)
22661 v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df)
22662 v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf)
22663 v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df)
22664 v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf)
22665 v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df)
22666 v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf)
22667 v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df)
22668 v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf)
22669 v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df)
22670 v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf)
22671 v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df)
22672 v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf)
22673 v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df)
22674 v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf)
22675 v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df)
22676 v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf)
22677 v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df)
22678 v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf)
22679 v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df)
22680 v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf)
22681 v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df)
22682 v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf)
22683 v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df)
22684 v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf)
22688 The following built-in functions are available when @option{-mlwp} is used.
22691 void __builtin_ia32_llwpcb16 (void *);
22692 void __builtin_ia32_llwpcb32 (void *);
22693 void __builtin_ia32_llwpcb64 (void *);
22694 void * __builtin_ia32_llwpcb16 (void);
22695 void * __builtin_ia32_llwpcb32 (void);
22696 void * __builtin_ia32_llwpcb64 (void);
22697 void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short)
22698 void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int)
22699 void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int)
22700 unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short)
22701 unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int)
22702 unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int)
22705 The following built-in functions are available when @option{-mbmi} is used.
22706 All of them generate the machine instruction that is part of the name.
22708 unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int);
22709 unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long);
22712 The following built-in functions are available when @option{-mbmi2} is used.
22713 All of them generate the machine instruction that is part of the name.
22715 unsigned int _bzhi_u32 (unsigned int, unsigned int)
22716 unsigned int _pdep_u32 (unsigned int, unsigned int)
22717 unsigned int _pext_u32 (unsigned int, unsigned int)
22718 unsigned long long _bzhi_u64 (unsigned long long, unsigned long long)
22719 unsigned long long _pdep_u64 (unsigned long long, unsigned long long)
22720 unsigned long long _pext_u64 (unsigned long long, unsigned long long)
22723 The following built-in functions are available when @option{-mlzcnt} is used.
22724 All of them generate the machine instruction that is part of the name.
22726 unsigned short __builtin_ia32_lzcnt_u16(unsigned short);
22727 unsigned int __builtin_ia32_lzcnt_u32(unsigned int);
22728 unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long);
22731 The following built-in functions are available when @option{-mfxsr} is used.
22732 All of them generate the machine instruction that is part of the name.
22734 void __builtin_ia32_fxsave (void *)
22735 void __builtin_ia32_fxrstor (void *)
22736 void __builtin_ia32_fxsave64 (void *)
22737 void __builtin_ia32_fxrstor64 (void *)
22740 The following built-in functions are available when @option{-mxsave} is used.
22741 All of them generate the machine instruction that is part of the name.
22743 void __builtin_ia32_xsave (void *, long long)
22744 void __builtin_ia32_xrstor (void *, long long)
22745 void __builtin_ia32_xsave64 (void *, long long)
22746 void __builtin_ia32_xrstor64 (void *, long long)
22749 The following built-in functions are available when @option{-mxsaveopt} is used.
22750 All of them generate the machine instruction that is part of the name.
22752 void __builtin_ia32_xsaveopt (void *, long long)
22753 void __builtin_ia32_xsaveopt64 (void *, long long)
22756 The following built-in functions are available when @option{-mtbm} is used.
22757 Both of them generate the immediate form of the bextr machine instruction.
22759 unsigned int __builtin_ia32_bextri_u32 (unsigned int,
22760 const unsigned int);
22761 unsigned long long __builtin_ia32_bextri_u64 (unsigned long long,
22762 const unsigned long long);
22766 The following built-in functions are available when @option{-m3dnow} is used.
22767 All of them generate the machine instruction that is part of the name.
22770 void __builtin_ia32_femms (void)
22771 v8qi __builtin_ia32_pavgusb (v8qi, v8qi)
22772 v2si __builtin_ia32_pf2id (v2sf)
22773 v2sf __builtin_ia32_pfacc (v2sf, v2sf)
22774 v2sf __builtin_ia32_pfadd (v2sf, v2sf)
22775 v2si __builtin_ia32_pfcmpeq (v2sf, v2sf)
22776 v2si __builtin_ia32_pfcmpge (v2sf, v2sf)
22777 v2si __builtin_ia32_pfcmpgt (v2sf, v2sf)
22778 v2sf __builtin_ia32_pfmax (v2sf, v2sf)
22779 v2sf __builtin_ia32_pfmin (v2sf, v2sf)
22780 v2sf __builtin_ia32_pfmul (v2sf, v2sf)
22781 v2sf __builtin_ia32_pfrcp (v2sf)
22782 v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf)
22783 v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf)
22784 v2sf __builtin_ia32_pfrsqrt (v2sf)
22785 v2sf __builtin_ia32_pfsub (v2sf, v2sf)
22786 v2sf __builtin_ia32_pfsubr (v2sf, v2sf)
22787 v2sf __builtin_ia32_pi2fd (v2si)
22788 v4hi __builtin_ia32_pmulhrw (v4hi, v4hi)
22791 The following built-in functions are available when @option{-m3dnowa} is used.
22792 All of them generate the machine instruction that is part of the name.
22795 v2si __builtin_ia32_pf2iw (v2sf)
22796 v2sf __builtin_ia32_pfnacc (v2sf, v2sf)
22797 v2sf __builtin_ia32_pfpnacc (v2sf, v2sf)
22798 v2sf __builtin_ia32_pi2fw (v2si)
22799 v2sf __builtin_ia32_pswapdsf (v2sf)
22800 v2si __builtin_ia32_pswapdsi (v2si)
22803 The following built-in functions are available when @option{-mrtm} is used
22804 They are used for restricted transactional memory. These are the internal
22805 low level functions. Normally the functions in
22806 @ref{x86 transactional memory intrinsics} should be used instead.
22809 int __builtin_ia32_xbegin ()
22810 void __builtin_ia32_xend ()
22811 void __builtin_ia32_xabort (status)
22812 int __builtin_ia32_xtest ()
22815 The following built-in functions are available when @option{-mmwaitx} is used.
22816 All of them generate the machine instruction that is part of the name.
22818 void __builtin_ia32_monitorx (void *, unsigned int, unsigned int)
22819 void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int)
22822 The following built-in functions are available when @option{-mclzero} is used.
22823 All of them generate the machine instruction that is part of the name.
22825 void __builtin_i32_clzero (void *)
22828 The following built-in functions are available when @option{-mpku} is used.
22829 They generate reads and writes to PKRU.
22831 void __builtin_ia32_wrpkru (unsigned int)
22832 unsigned int __builtin_ia32_rdpkru ()
22835 The following built-in functions are available when @option{-mcet} or
22836 @option{-mshstk} option is used. They support shadow stack
22837 machine instructions from Intel Control-flow Enforcement Technology (CET).
22838 Each built-in function generates the machine instruction that is part
22839 of the function's name. These are the internal low-level functions.
22840 Normally the functions in @ref{x86 control-flow protection intrinsics}
22841 should be used instead.
22844 unsigned int __builtin_ia32_rdsspd (void)
22845 unsigned long long __builtin_ia32_rdsspq (void)
22846 void __builtin_ia32_incsspd (unsigned int)
22847 void __builtin_ia32_incsspq (unsigned long long)
22848 void __builtin_ia32_saveprevssp(void);
22849 void __builtin_ia32_rstorssp(void *);
22850 void __builtin_ia32_wrssd(unsigned int, void *);
22851 void __builtin_ia32_wrssq(unsigned long long, void *);
22852 void __builtin_ia32_wrussd(unsigned int, void *);
22853 void __builtin_ia32_wrussq(unsigned long long, void *);
22854 void __builtin_ia32_setssbsy(void);
22855 void __builtin_ia32_clrssbsy(void *);
22858 @node x86 transactional memory intrinsics
22859 @subsection x86 Transactional Memory Intrinsics
22861 These hardware transactional memory intrinsics for x86 allow you to use
22862 memory transactions with RTM (Restricted Transactional Memory).
22863 This support is enabled with the @option{-mrtm} option.
22864 For using HLE (Hardware Lock Elision) see
22865 @ref{x86 specific memory model extensions for transactional memory} instead.
22867 A memory transaction commits all changes to memory in an atomic way,
22868 as visible to other threads. If the transaction fails it is rolled back
22869 and all side effects discarded.
22871 Generally there is no guarantee that a memory transaction ever succeeds
22872 and suitable fallback code always needs to be supplied.
22874 @deftypefn {RTM Function} {unsigned} _xbegin ()
22875 Start a RTM (Restricted Transactional Memory) transaction.
22876 Returns @code{_XBEGIN_STARTED} when the transaction
22877 started successfully (note this is not 0, so the constant has to be
22878 explicitly tested).
22880 If the transaction aborts, all side effects
22881 are undone and an abort code encoded as a bit mask is returned.
22882 The following macros are defined:
22885 @item _XABORT_EXPLICIT
22886 Transaction was explicitly aborted with @code{_xabort}. The parameter passed
22887 to @code{_xabort} is available with @code{_XABORT_CODE(status)}.
22888 @item _XABORT_RETRY
22889 Transaction retry is possible.
22890 @item _XABORT_CONFLICT
22891 Transaction abort due to a memory conflict with another thread.
22892 @item _XABORT_CAPACITY
22893 Transaction abort due to the transaction using too much memory.
22894 @item _XABORT_DEBUG
22895 Transaction abort due to a debug trap.
22896 @item _XABORT_NESTED
22897 Transaction abort in an inner nested transaction.
22900 There is no guarantee
22901 any transaction ever succeeds, so there always needs to be a valid
22905 @deftypefn {RTM Function} {void} _xend ()
22906 Commit the current transaction. When no transaction is active this faults.
22907 All memory side effects of the transaction become visible
22908 to other threads in an atomic manner.
22911 @deftypefn {RTM Function} {int} _xtest ()
22912 Return a nonzero value if a transaction is currently active, otherwise 0.
22915 @deftypefn {RTM Function} {void} _xabort (status)
22916 Abort the current transaction. When no transaction is active this is a no-op.
22917 The @var{status} is an 8-bit constant; its value is encoded in the return
22918 value from @code{_xbegin}.
22921 Here is an example showing handling for @code{_XABORT_RETRY}
22922 and a fallback path for other failures:
22925 #include <immintrin.h>
22927 int n_tries, max_tries;
22928 unsigned status = _XABORT_EXPLICIT;
22931 for (n_tries = 0; n_tries < max_tries; n_tries++)
22933 status = _xbegin ();
22934 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY))
22937 if (status == _XBEGIN_STARTED)
22939 ... transaction code...
22944 ... non-transactional fallback path...
22949 Note that, in most cases, the transactional and non-transactional code
22950 must synchronize together to ensure consistency.
22952 @node x86 control-flow protection intrinsics
22953 @subsection x86 Control-Flow Protection Intrinsics
22955 @deftypefn {CET Function} {ret_type} _get_ssp (void)
22956 Get the current value of shadow stack pointer if shadow stack support
22957 from Intel CET is enabled in the hardware or @code{0} otherwise.
22958 The @code{ret_type} is @code{unsigned long long} for 64-bit targets
22959 and @code{unsigned int} for 32-bit targets.
22962 @deftypefn {CET Function} void _inc_ssp (unsigned int)
22963 Increment the current shadow stack pointer by the size specified by the
22964 function argument. The argument is masked to a byte value for security
22965 reasons, so to increment by more than 255 bytes you must call the function
22969 The shadow stack unwind code looks like:
22972 #include <immintrin.h>
22974 /* Unwind the shadow stack for EH. */
22975 #define _Unwind_Frames_Extra(x) \
22978 _Unwind_Word ssp = _get_ssp (); \
22981 _Unwind_Word tmp = (x); \
22982 while (tmp > 255) \
22994 This code runs unconditionally on all 64-bit processors. For 32-bit
22995 processors the code runs on those that support multi-byte NOP instructions.
22997 @node Target Format Checks
22998 @section Format Checks Specific to Particular Target Machines
23000 For some target machines, GCC supports additional options to the
23002 (@pxref{Function Attributes,,Declaring Attributes of Functions}).
23005 * Solaris Format Checks::
23006 * Darwin Format Checks::
23009 @node Solaris Format Checks
23010 @subsection Solaris Format Checks
23012 Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format
23013 check. @code{cmn_err} accepts a subset of the standard @code{printf}
23014 conversions, and the two-argument @code{%b} conversion for displaying
23015 bit-fields. See the Solaris man page for @code{cmn_err} for more information.
23017 @node Darwin Format Checks
23018 @subsection Darwin Format Checks
23020 In addition to the full set of format archetypes (attribute format style
23021 arguments such as @code{printf}, @code{scanf}, @code{strftime}, and
23022 @code{strfmon}), Darwin targets also support the @code{CFString} (or
23023 @code{__CFString__}) archetype in the @code{format} attribute.
23024 Declarations with this archetype are parsed for correct syntax
23025 and argument types. However, parsing of the format string itself and
23026 validating arguments against it in calls to such functions is currently
23029 Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may
23030 also be used as format arguments. Note that the relevant headers are only likely to be
23031 available on Darwin (OSX) installations. On such installations, the XCode and system
23032 documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and
23033 associated functions.
23036 @section Pragmas Accepted by GCC
23038 @cindex @code{#pragma}
23040 GCC supports several types of pragmas, primarily in order to compile
23041 code originally written for other compilers. Note that in general
23042 we do not recommend the use of pragmas; @xref{Function Attributes},
23043 for further explanation.
23045 The GNU C preprocessor recognizes several pragmas in addition to the
23046 compiler pragmas documented here. Refer to the CPP manual for more
23050 * AArch64 Pragmas::
23055 * RS/6000 and PowerPC Pragmas::
23058 * Solaris Pragmas::
23059 * Symbol-Renaming Pragmas::
23060 * Structure-Layout Pragmas::
23062 * Diagnostic Pragmas::
23063 * Visibility Pragmas::
23064 * Push/Pop Macro Pragmas::
23065 * Function Specific Option Pragmas::
23066 * Loop-Specific Pragmas::
23069 @node AArch64 Pragmas
23070 @subsection AArch64 Pragmas
23072 The pragmas defined by the AArch64 target correspond to the AArch64
23073 target function attributes. They can be specified as below:
23075 #pragma GCC target("string")
23078 where @code{@var{string}} can be any string accepted as an AArch64 target
23079 attribute. @xref{AArch64 Function Attributes}, for more details
23080 on the permissible values of @code{string}.
23083 @subsection ARM Pragmas
23085 The ARM target defines pragmas for controlling the default addition of
23086 @code{long_call} and @code{short_call} attributes to functions.
23087 @xref{Function Attributes}, for information about the effects of these
23092 @cindex pragma, long_calls
23093 Set all subsequent functions to have the @code{long_call} attribute.
23095 @item no_long_calls
23096 @cindex pragma, no_long_calls
23097 Set all subsequent functions to have the @code{short_call} attribute.
23099 @item long_calls_off
23100 @cindex pragma, long_calls_off
23101 Do not affect the @code{long_call} or @code{short_call} attributes of
23102 subsequent functions.
23106 @subsection M32C Pragmas
23109 @item GCC memregs @var{number}
23110 @cindex pragma, memregs
23111 Overrides the command-line option @code{-memregs=} for the current
23112 file. Use with care! This pragma must be before any function in the
23113 file, and mixing different memregs values in different objects may
23114 make them incompatible. This pragma is useful when a
23115 performance-critical function uses a memreg for temporary values,
23116 as it may allow you to reduce the number of memregs used.
23118 @item ADDRESS @var{name} @var{address}
23119 @cindex pragma, address
23120 For any declared symbols matching @var{name}, this does three things
23121 to that symbol: it forces the symbol to be located at the given
23122 address (a number), it forces the symbol to be volatile, and it
23123 changes the symbol's scope to be static. This pragma exists for
23124 compatibility with other compilers, but note that the common
23125 @code{1234H} numeric syntax is not supported (use @code{0x1234}
23129 #pragma ADDRESS port3 0x103
23136 @subsection MeP Pragmas
23140 @item custom io_volatile (on|off)
23141 @cindex pragma, custom io_volatile
23142 Overrides the command-line option @code{-mio-volatile} for the current
23143 file. Note that for compatibility with future GCC releases, this
23144 option should only be used once before any @code{io} variables in each
23147 @item GCC coprocessor available @var{registers}
23148 @cindex pragma, coprocessor available
23149 Specifies which coprocessor registers are available to the register
23150 allocator. @var{registers} may be a single register, register range
23151 separated by ellipses, or comma-separated list of those. Example:
23154 #pragma GCC coprocessor available $c0...$c10, $c28
23157 @item GCC coprocessor call_saved @var{registers}
23158 @cindex pragma, coprocessor call_saved
23159 Specifies which coprocessor registers are to be saved and restored by
23160 any function using them. @var{registers} may be a single register,
23161 register range separated by ellipses, or comma-separated list of
23165 #pragma GCC coprocessor call_saved $c4...$c6, $c31
23168 @item GCC coprocessor subclass '(A|B|C|D)' = @var{registers}
23169 @cindex pragma, coprocessor subclass
23170 Creates and defines a register class. These register classes can be
23171 used by inline @code{asm} constructs. @var{registers} may be a single
23172 register, register range separated by ellipses, or comma-separated
23173 list of those. Example:
23176 #pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6
23178 asm ("cpfoo %0" : "=B" (x));
23181 @item GCC disinterrupt @var{name} , @var{name} @dots{}
23182 @cindex pragma, disinterrupt
23183 For the named functions, the compiler adds code to disable interrupts
23184 for the duration of those functions. If any functions so named
23185 are not encountered in the source, a warning is emitted that the pragma is
23186 not used. Examples:
23189 #pragma disinterrupt foo
23190 #pragma disinterrupt bar, grill
23191 int foo () @{ @dots{} @}
23194 @item GCC call @var{name} , @var{name} @dots{}
23195 @cindex pragma, call
23196 For the named functions, the compiler always uses a register-indirect
23197 call model when calling the named functions. Examples:
23207 @subsection PRU Pragmas
23211 @item ctable_entry @var{index} @var{constant_address}
23212 @cindex pragma, ctable_entry
23213 Specifies that the PRU CTABLE entry given by @var{index} has the value
23214 @var{constant_address}. This enables GCC to emit LBCO/SBCO instructions
23215 when the load/store address is known and can be addressed with some CTABLE
23216 entry. For example:
23219 /* will compile to "sbco Rx, 2, 0x10, 4" */
23220 #pragma ctable_entry 2 0x4802a000
23221 *(unsigned int *)0x4802a010 = val;
23226 @node RS/6000 and PowerPC Pragmas
23227 @subsection RS/6000 and PowerPC Pragmas
23229 The RS/6000 and PowerPC targets define one pragma for controlling
23230 whether or not the @code{longcall} attribute is added to function
23231 declarations by default. This pragma overrides the @option{-mlongcall}
23232 option, but not the @code{longcall} and @code{shortcall} attributes.
23233 @xref{RS/6000 and PowerPC Options}, for more information about when long
23234 calls are and are not necessary.
23238 @cindex pragma, longcall
23239 Apply the @code{longcall} attribute to all subsequent function
23243 Do not apply the @code{longcall} attribute to subsequent function
23247 @c Describe h8300 pragmas here.
23248 @c Describe sh pragmas here.
23249 @c Describe v850 pragmas here.
23251 @node S/390 Pragmas
23252 @subsection S/390 Pragmas
23254 The pragmas defined by the S/390 target correspond to the S/390
23255 target function attributes and some the additional options:
23262 Note that options of the pragma, unlike options of the target
23263 attribute, do change the value of preprocessor macros like
23264 @code{__VEC__}. They can be specified as below:
23267 #pragma GCC target("string[,string]...")
23268 #pragma GCC target("string"[,"string"]...)
23271 @node Darwin Pragmas
23272 @subsection Darwin Pragmas
23274 The following pragmas are available for all architectures running the
23275 Darwin operating system. These are useful for compatibility with other
23279 @item mark @var{tokens}@dots{}
23280 @cindex pragma, mark
23281 This pragma is accepted, but has no effect.
23283 @item options align=@var{alignment}
23284 @cindex pragma, options align
23285 This pragma sets the alignment of fields in structures. The values of
23286 @var{alignment} may be @code{mac68k}, to emulate m68k alignment, or
23287 @code{power}, to emulate PowerPC alignment. Uses of this pragma nest
23288 properly; to restore the previous setting, use @code{reset} for the
23291 @item segment @var{tokens}@dots{}
23292 @cindex pragma, segment
23293 This pragma is accepted, but has no effect.
23295 @item unused (@var{var} [, @var{var}]@dots{})
23296 @cindex pragma, unused
23297 This pragma declares variables to be possibly unused. GCC does not
23298 produce warnings for the listed variables. The effect is similar to
23299 that of the @code{unused} attribute, except that this pragma may appear
23300 anywhere within the variables' scopes.
23303 @node Solaris Pragmas
23304 @subsection Solaris Pragmas
23306 The Solaris target supports @code{#pragma redefine_extname}
23307 (@pxref{Symbol-Renaming Pragmas}). It also supports additional
23308 @code{#pragma} directives for compatibility with the system compiler.
23311 @item align @var{alignment} (@var{variable} [, @var{variable}]...)
23312 @cindex pragma, align
23314 Increase the minimum alignment of each @var{variable} to @var{alignment}.
23315 This is the same as GCC's @code{aligned} attribute @pxref{Variable
23316 Attributes}). Macro expansion occurs on the arguments to this pragma
23317 when compiling C and Objective-C@. It does not currently occur when
23318 compiling C++, but this is a bug which may be fixed in a future
23321 @item fini (@var{function} [, @var{function}]...)
23322 @cindex pragma, fini
23324 This pragma causes each listed @var{function} to be called after
23325 main, or during shared module unloading, by adding a call to the
23326 @code{.fini} section.
23328 @item init (@var{function} [, @var{function}]...)
23329 @cindex pragma, init
23331 This pragma causes each listed @var{function} to be called during
23332 initialization (before @code{main}) or during shared module loading, by
23333 adding a call to the @code{.init} section.
23337 @node Symbol-Renaming Pragmas
23338 @subsection Symbol-Renaming Pragmas
23340 GCC supports a @code{#pragma} directive that changes the name used in
23341 assembly for a given declaration. While this pragma is supported on all
23342 platforms, it is intended primarily to provide compatibility with the
23343 Solaris system headers. This effect can also be achieved using the asm
23344 labels extension (@pxref{Asm Labels}).
23347 @item redefine_extname @var{oldname} @var{newname}
23348 @cindex pragma, redefine_extname
23350 This pragma gives the C function @var{oldname} the assembly symbol
23351 @var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME}
23352 is defined if this pragma is available (currently on all platforms).
23355 This pragma and the @code{asm} labels extension interact in a complicated
23356 manner. Here are some corner cases you may want to be aware of:
23359 @item This pragma silently applies only to declarations with external
23360 linkage. The @code{asm} label feature does not have this restriction.
23362 @item In C++, this pragma silently applies only to declarations with
23363 ``C'' linkage. Again, @code{asm} labels do not have this restriction.
23365 @item If either of the ways of changing the assembly name of a
23366 declaration are applied to a declaration whose assembly name has
23367 already been determined (either by a previous use of one of these
23368 features, or because the compiler needed the assembly name in order to
23369 generate code), and the new name is different, a warning issues and
23370 the name does not change.
23372 @item The @var{oldname} used by @code{#pragma redefine_extname} is
23373 always the C-language name.
23376 @node Structure-Layout Pragmas
23377 @subsection Structure-Layout Pragmas
23379 For compatibility with Microsoft Windows compilers, GCC supports a
23380 set of @code{#pragma} directives that change the maximum alignment of
23381 members of structures (other than zero-width bit-fields), unions, and
23382 classes subsequently defined. The @var{n} value below always is required
23383 to be a small power of two and specifies the new alignment in bytes.
23386 @item @code{#pragma pack(@var{n})} simply sets the new alignment.
23387 @item @code{#pragma pack()} sets the alignment to the one that was in
23388 effect when compilation started (see also command-line option
23389 @option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}).
23390 @item @code{#pragma pack(push[,@var{n}])} pushes the current alignment
23391 setting on an internal stack and then optionally sets the new alignment.
23392 @item @code{#pragma pack(pop)} restores the alignment setting to the one
23393 saved at the top of the internal stack (and removes that stack entry).
23394 Note that @code{#pragma pack([@var{n}])} does not influence this internal
23395 stack; thus it is possible to have @code{#pragma pack(push)} followed by
23396 multiple @code{#pragma pack(@var{n})} instances and finalized by a single
23397 @code{#pragma pack(pop)}.
23400 Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct}
23401 directive which lays out structures and unions subsequently defined as the
23402 documented @code{__attribute__ ((ms_struct))}.
23405 @item @code{#pragma ms_struct on} turns on the Microsoft layout.
23406 @item @code{#pragma ms_struct off} turns off the Microsoft layout.
23407 @item @code{#pragma ms_struct reset} goes back to the default layout.
23410 Most targets also support the @code{#pragma scalar_storage_order} directive
23411 which lays out structures and unions subsequently defined as the documented
23412 @code{__attribute__ ((scalar_storage_order))}.
23415 @item @code{#pragma scalar_storage_order big-endian} sets the storage order
23416 of the scalar fields to big-endian.
23417 @item @code{#pragma scalar_storage_order little-endian} sets the storage order
23418 of the scalar fields to little-endian.
23419 @item @code{#pragma scalar_storage_order default} goes back to the endianness
23420 that was in effect when compilation started (see also command-line option
23421 @option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}).
23425 @subsection Weak Pragmas
23427 For compatibility with SVR4, GCC supports a set of @code{#pragma}
23428 directives for declaring symbols to be weak, and defining weak
23432 @item #pragma weak @var{symbol}
23433 @cindex pragma, weak
23434 This pragma declares @var{symbol} to be weak, as if the declaration
23435 had the attribute of the same name. The pragma may appear before
23436 or after the declaration of @var{symbol}. It is not an error for
23437 @var{symbol} to never be defined at all.
23439 @item #pragma weak @var{symbol1} = @var{symbol2}
23440 This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}.
23441 It is an error if @var{symbol2} is not defined in the current
23445 @node Diagnostic Pragmas
23446 @subsection Diagnostic Pragmas
23448 GCC allows the user to selectively enable or disable certain types of
23449 diagnostics, and change the kind of the diagnostic. For example, a
23450 project's policy might require that all sources compile with
23451 @option{-Werror} but certain files might have exceptions allowing
23452 specific types of warnings. Or, a project might selectively enable
23453 diagnostics and treat them as errors depending on which preprocessor
23454 macros are defined.
23457 @item #pragma GCC diagnostic @var{kind} @var{option}
23458 @cindex pragma, diagnostic
23460 Modifies the disposition of a diagnostic. Note that not all
23461 diagnostics are modifiable; at the moment only warnings (normally
23462 controlled by @samp{-W@dots{}}) can be controlled, and not all of them.
23463 Use @option{-fdiagnostics-show-option} to determine which diagnostics
23464 are controllable and which option controls them.
23466 @var{kind} is @samp{error} to treat this diagnostic as an error,
23467 @samp{warning} to treat it like a warning (even if @option{-Werror} is
23468 in effect), or @samp{ignored} if the diagnostic is to be ignored.
23469 @var{option} is a double quoted string that matches the command-line
23473 #pragma GCC diagnostic warning "-Wformat"
23474 #pragma GCC diagnostic error "-Wformat"
23475 #pragma GCC diagnostic ignored "-Wformat"
23478 Note that these pragmas override any command-line options. GCC keeps
23479 track of the location of each pragma, and issues diagnostics according
23480 to the state as of that point in the source file. Thus, pragmas occurring
23481 after a line do not affect diagnostics caused by that line.
23483 @item #pragma GCC diagnostic push
23484 @itemx #pragma GCC diagnostic pop
23486 Causes GCC to remember the state of the diagnostics as of each
23487 @code{push}, and restore to that point at each @code{pop}. If a
23488 @code{pop} has no matching @code{push}, the command-line options are
23492 #pragma GCC diagnostic error "-Wuninitialized"
23493 foo(a); /* error is given for this one */
23494 #pragma GCC diagnostic push
23495 #pragma GCC diagnostic ignored "-Wuninitialized"
23496 foo(b); /* no diagnostic for this one */
23497 #pragma GCC diagnostic pop
23498 foo(c); /* error is given for this one */
23499 #pragma GCC diagnostic pop
23500 foo(d); /* depends on command-line options */
23505 GCC also offers a simple mechanism for printing messages during
23509 @item #pragma message @var{string}
23510 @cindex pragma, diagnostic
23512 Prints @var{string} as a compiler message on compilation. The message
23513 is informational only, and is neither a compilation warning nor an
23514 error. Newlines can be included in the string by using the @samp{\n}
23518 #pragma message "Compiling " __FILE__ "..."
23521 @var{string} may be parenthesized, and is printed with location
23522 information. For example,
23525 #define DO_PRAGMA(x) _Pragma (#x)
23526 #define TODO(x) DO_PRAGMA(message ("TODO - " #x))
23528 TODO(Remember to fix this)
23532 prints @samp{/tmp/file.c:4: note: #pragma message:
23533 TODO - Remember to fix this}.
23535 @item #pragma GCC error @var{message}
23536 @cindex pragma, diagnostic
23537 Generates an error message. This pragma @emph{is} considered to
23538 indicate an error in the compilation, and it will be treated as such.
23540 Newlines can be included in the string by using the @samp{\n}
23541 escape sequence. They will be displayed as newlines even if the
23542 @option{-fmessage-length} option is set to zero.
23544 The error is only generated if the pragma is present in the code after
23545 pre-processing has been completed. It does not matter however if the
23546 code containing the pragma is unreachable:
23550 #pragma GCC error "this error is not seen"
23555 #pragma GCC error "this error is seen"
23559 @item #pragma GCC warning @var{message}
23560 @cindex pragma, diagnostic
23561 This is just like @samp{pragma GCC error} except that a warning
23562 message is issued instead of an error message. Unless
23563 @option{-Werror} is in effect, in which case this pragma will generate
23568 @node Visibility Pragmas
23569 @subsection Visibility Pragmas
23572 @item #pragma GCC visibility push(@var{visibility})
23573 @itemx #pragma GCC visibility pop
23574 @cindex pragma, visibility
23576 This pragma allows the user to set the visibility for multiple
23577 declarations without having to give each a visibility attribute
23578 (@pxref{Function Attributes}).
23580 In C++, @samp{#pragma GCC visibility} affects only namespace-scope
23581 declarations. Class members and template specializations are not
23582 affected; if you want to override the visibility for a particular
23583 member or instantiation, you must use an attribute.
23588 @node Push/Pop Macro Pragmas
23589 @subsection Push/Pop Macro Pragmas
23591 For compatibility with Microsoft Windows compilers, GCC supports
23592 @samp{#pragma push_macro(@var{"macro_name"})}
23593 and @samp{#pragma pop_macro(@var{"macro_name"})}.
23596 @item #pragma push_macro(@var{"macro_name"})
23597 @cindex pragma, push_macro
23598 This pragma saves the value of the macro named as @var{macro_name} to
23599 the top of the stack for this macro.
23601 @item #pragma pop_macro(@var{"macro_name"})
23602 @cindex pragma, pop_macro
23603 This pragma sets the value of the macro named as @var{macro_name} to
23604 the value on top of the stack for this macro. If the stack for
23605 @var{macro_name} is empty, the value of the macro remains unchanged.
23612 #pragma push_macro("X")
23615 #pragma pop_macro("X")
23620 In this example, the definition of X as 1 is saved by @code{#pragma
23621 push_macro} and restored by @code{#pragma pop_macro}.
23623 @node Function Specific Option Pragmas
23624 @subsection Function Specific Option Pragmas
23627 @item #pragma GCC target (@var{string}, @dots{})
23628 @cindex pragma GCC target
23630 This pragma allows you to set target-specific options for functions
23631 defined later in the source file. One or more strings can be
23632 specified. Each function that is defined after this point is treated
23633 as if it had been declared with one @code{target(}@var{string}@code{)}
23634 attribute for each @var{string} argument. The parentheses around
23635 the strings in the pragma are optional. @xref{Function Attributes},
23636 for more information about the @code{target} attribute and the attribute
23639 The @code{#pragma GCC target} pragma is presently implemented for
23640 x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only.
23642 @item #pragma GCC optimize (@var{string}, @dots{})
23643 @cindex pragma GCC optimize
23645 This pragma allows you to set global optimization options for functions
23646 defined later in the source file. One or more strings can be
23647 specified. Each function that is defined after this point is treated
23648 as if it had been declared with one @code{optimize(}@var{string}@code{)}
23649 attribute for each @var{string} argument. The parentheses around
23650 the strings in the pragma are optional. @xref{Function Attributes},
23651 for more information about the @code{optimize} attribute and the attribute
23654 @item #pragma GCC push_options
23655 @itemx #pragma GCC pop_options
23656 @cindex pragma GCC push_options
23657 @cindex pragma GCC pop_options
23659 These pragmas maintain a stack of the current target and optimization
23660 options. It is intended for include files where you temporarily want
23661 to switch to using a different @samp{#pragma GCC target} or
23662 @samp{#pragma GCC optimize} and then to pop back to the previous
23665 @item #pragma GCC reset_options
23666 @cindex pragma GCC reset_options
23668 This pragma clears the current @code{#pragma GCC target} and
23669 @code{#pragma GCC optimize} to use the default switches as specified
23670 on the command line.
23674 @node Loop-Specific Pragmas
23675 @subsection Loop-Specific Pragmas
23678 @item #pragma GCC ivdep
23679 @cindex pragma GCC ivdep
23681 With this pragma, the programmer asserts that there are no loop-carried
23682 dependencies which would prevent consecutive iterations of
23683 the following loop from executing concurrently with SIMD
23684 (single instruction multiple data) instructions.
23686 For example, the compiler can only unconditionally vectorize the following
23687 loop with the pragma:
23690 void foo (int n, int *a, int *b, int *c)
23694 for (i = 0; i < n; ++i)
23695 a[i] = b[i] + c[i];
23700 In this example, using the @code{restrict} qualifier had the same
23701 effect. In the following example, that would not be possible. Assume
23702 @math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows
23703 that it can unconditionally vectorize the following loop:
23706 void ignore_vec_dep (int *a, int k, int c, int m)
23709 for (int i = 0; i < m; i++)
23710 a[i] = a[i + k] * c;
23714 @item #pragma GCC unroll @var{n}
23715 @cindex pragma GCC unroll @var{n}
23717 You can use this pragma to control how many times a loop should be unrolled.
23718 It must be placed immediately before a @code{for}, @code{while} or @code{do}
23719 loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows.
23720 @var{n} is an integer constant expression specifying the unrolling factor.
23721 The values of @math{0} and @math{1} block any unrolling of the loop.
23725 @node Unnamed Fields
23726 @section Unnamed Structure and Union Fields
23727 @cindex @code{struct}
23728 @cindex @code{union}
23730 As permitted by ISO C11 and for compatibility with other compilers,
23731 GCC allows you to define
23732 a structure or union that contains, as fields, structures and unions
23733 without names. For example:
23747 In this example, you are able to access members of the unnamed
23748 union with code like @samp{foo.b}. Note that only unnamed structs and
23749 unions are allowed, you may not have, for example, an unnamed
23752 You must never create such structures that cause ambiguous field definitions.
23753 For example, in this structure:
23765 it is ambiguous which @code{a} is being referred to with @samp{foo.a}.
23766 The compiler gives errors for such constructs.
23768 @opindex fms-extensions
23769 Unless @option{-fms-extensions} is used, the unnamed field must be a
23770 structure or union definition without a tag (for example, @samp{struct
23771 @{ int a; @};}). If @option{-fms-extensions} is used, the field may
23772 also be a definition with a tag such as @samp{struct foo @{ int a;
23773 @};}, a reference to a previously defined structure or union such as
23774 @samp{struct foo;}, or a reference to a @code{typedef} name for a
23775 previously defined structure or union type.
23777 @opindex fplan9-extensions
23778 The option @option{-fplan9-extensions} enables
23779 @option{-fms-extensions} as well as two other extensions. First, a
23780 pointer to a structure is automatically converted to a pointer to an
23781 anonymous field for assignments and function calls. For example:
23784 struct s1 @{ int a; @};
23785 struct s2 @{ struct s1; @};
23786 extern void f1 (struct s1 *);
23787 void f2 (struct s2 *p) @{ f1 (p); @}
23791 In the call to @code{f1} inside @code{f2}, the pointer @code{p} is
23792 converted into a pointer to the anonymous field.
23794 Second, when the type of an anonymous field is a @code{typedef} for a
23795 @code{struct} or @code{union}, code may refer to the field using the
23796 name of the @code{typedef}.
23799 typedef struct @{ int a; @} s1;
23800 struct s2 @{ s1; @};
23801 s1 f1 (struct s2 *p) @{ return p->s1; @}
23804 These usages are only permitted when they are not ambiguous.
23807 @section Thread-Local Storage
23808 @cindex Thread-Local Storage
23809 @cindex @acronym{TLS}
23810 @cindex @code{__thread}
23812 Thread-local storage (@acronym{TLS}) is a mechanism by which variables
23813 are allocated such that there is one instance of the variable per extant
23814 thread. The runtime model GCC uses to implement this originates
23815 in the IA-64 processor-specific ABI, but has since been migrated
23816 to other processors as well. It requires significant support from
23817 the linker (@command{ld}), dynamic linker (@command{ld.so}), and
23818 system libraries (@file{libc.so} and @file{libpthread.so}), so it
23819 is not available everywhere.
23821 At the user level, the extension is visible with a new storage
23822 class keyword: @code{__thread}. For example:
23826 extern __thread struct state s;
23827 static __thread char *p;
23830 The @code{__thread} specifier may be used alone, with the @code{extern}
23831 or @code{static} specifiers, but with no other storage class specifier.
23832 When used with @code{extern} or @code{static}, @code{__thread} must appear
23833 immediately after the other storage class specifier.
23835 The @code{__thread} specifier may be applied to any global, file-scoped
23836 static, function-scoped static, or static data member of a class. It may
23837 not be applied to block-scoped automatic or non-static data member.
23839 When the address-of operator is applied to a thread-local variable, it is
23840 evaluated at run time and returns the address of the current thread's
23841 instance of that variable. An address so obtained may be used by any
23842 thread. When a thread terminates, any pointers to thread-local variables
23843 in that thread become invalid.
23845 No static initialization may refer to the address of a thread-local variable.
23847 In C++, if an initializer is present for a thread-local variable, it must
23848 be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++
23851 See @uref{https://www.akkadia.org/drepper/tls.pdf,
23852 ELF Handling For Thread-Local Storage} for a detailed explanation of
23853 the four thread-local storage addressing models, and how the runtime
23854 is expected to function.
23857 * C99 Thread-Local Edits::
23858 * C++98 Thread-Local Edits::
23861 @node C99 Thread-Local Edits
23862 @subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage
23864 The following are a set of changes to ISO/IEC 9899:1999 (aka C99)
23865 that document the exact semantics of the language extension.
23869 @cite{5.1.2 Execution environments}
23871 Add new text after paragraph 1
23874 Within either execution environment, a @dfn{thread} is a flow of
23875 control within a program. It is implementation defined whether
23876 or not there may be more than one thread associated with a program.
23877 It is implementation defined how threads beyond the first are
23878 created, the name and type of the function called at thread
23879 startup, and how threads may be terminated. However, objects
23880 with thread storage duration shall be initialized before thread
23885 @cite{6.2.4 Storage durations of objects}
23887 Add new text before paragraph 3
23890 An object whose identifier is declared with the storage-class
23891 specifier @w{@code{__thread}} has @dfn{thread storage duration}.
23892 Its lifetime is the entire execution of the thread, and its
23893 stored value is initialized only once, prior to thread startup.
23897 @cite{6.4.1 Keywords}
23899 Add @code{__thread}.
23902 @cite{6.7.1 Storage-class specifiers}
23904 Add @code{__thread} to the list of storage class specifiers in
23907 Change paragraph 2 to
23910 With the exception of @code{__thread}, at most one storage-class
23911 specifier may be given [@dots{}]. The @code{__thread} specifier may
23912 be used alone, or immediately following @code{extern} or
23916 Add new text after paragraph 6
23919 The declaration of an identifier for a variable that has
23920 block scope that specifies @code{__thread} shall also
23921 specify either @code{extern} or @code{static}.
23923 The @code{__thread} specifier shall be used only with
23928 @node C++98 Thread-Local Edits
23929 @subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage
23931 The following are a set of changes to ISO/IEC 14882:1998 (aka C++98)
23932 that document the exact semantics of the language extension.
23936 @b{[intro.execution]}
23938 New text after paragraph 4
23941 A @dfn{thread} is a flow of control within the abstract machine.
23942 It is implementation defined whether or not there may be more than
23946 New text after paragraph 7
23949 It is unspecified whether additional action must be taken to
23950 ensure when and whether side effects are visible to other threads.
23956 Add @code{__thread}.
23959 @b{[basic.start.main]}
23961 Add after paragraph 5
23964 The thread that begins execution at the @code{main} function is called
23965 the @dfn{main thread}. It is implementation defined how functions
23966 beginning threads other than the main thread are designated or typed.
23967 A function so designated, as well as the @code{main} function, is called
23968 a @dfn{thread startup function}. It is implementation defined what
23969 happens if a thread startup function returns. It is implementation
23970 defined what happens to other threads when any thread calls @code{exit}.
23974 @b{[basic.start.init]}
23976 Add after paragraph 4
23979 The storage for an object of thread storage duration shall be
23980 statically initialized before the first statement of the thread startup
23981 function. An object of thread storage duration shall not require
23982 dynamic initialization.
23986 @b{[basic.start.term]}
23988 Add after paragraph 3
23991 The type of an object with thread storage duration shall not have a
23992 non-trivial destructor, nor shall it be an array type whose elements
23993 (directly or indirectly) have non-trivial destructors.
23999 Add ``thread storage duration'' to the list in paragraph 1.
24004 Thread, static, and automatic storage durations are associated with
24005 objects introduced by declarations [@dots{}].
24008 Add @code{__thread} to the list of specifiers in paragraph 3.
24011 @b{[basic.stc.thread]}
24013 New section before @b{[basic.stc.static]}
24016 The keyword @code{__thread} applied to a non-local object gives the
24017 object thread storage duration.
24019 A local variable or class data member declared both @code{static}
24020 and @code{__thread} gives the variable or member thread storage
24025 @b{[basic.stc.static]}
24030 All objects that have neither thread storage duration, dynamic
24031 storage duration nor are local [@dots{}].
24037 Add @code{__thread} to the list in paragraph 1.
24042 With the exception of @code{__thread}, at most one
24043 @var{storage-class-specifier} shall appear in a given
24044 @var{decl-specifier-seq}. The @code{__thread} specifier may
24045 be used alone, or immediately following the @code{extern} or
24046 @code{static} specifiers. [@dots{}]
24049 Add after paragraph 5
24052 The @code{__thread} specifier can be applied only to the names of objects
24053 and to anonymous unions.
24059 Add after paragraph 6
24062 Non-@code{static} members shall not be @code{__thread}.
24066 @node Binary constants
24067 @section Binary Constants using the @samp{0b} Prefix
24068 @cindex Binary constants using the @samp{0b} prefix
24070 Integer constants can be written as binary constants, consisting of a
24071 sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
24072 @samp{0B}. This is particularly useful in environments that operate a
24073 lot on the bit level (like microcontrollers).
24075 The following statements are identical:
24084 The type of these constants follows the same rules as for octal or
24085 hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
24088 @node C++ Extensions
24089 @chapter Extensions to the C++ Language
24090 @cindex extensions, C++ language
24091 @cindex C++ language extensions
24093 The GNU compiler provides these extensions to the C++ language (and you
24094 can also use most of the C language extensions in your C++ programs). If you
24095 want to write code that checks whether these features are available, you can
24096 test for the GNU compiler the same way as for C programs: check for a
24097 predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to
24098 test specifically for GNU C++ (@pxref{Common Predefined Macros,,
24099 Predefined Macros,cpp,The GNU C Preprocessor}).
24102 * C++ Volatiles:: What constitutes an access to a volatile object.
24103 * Restricted Pointers:: C99 restricted pointers and references.
24104 * Vague Linkage:: Where G++ puts inlines, vtables and such.
24105 * C++ Interface:: You can use a single C++ header file for both
24106 declarations and definitions.
24107 * Template Instantiation:: Methods for ensuring that exactly one copy of
24108 each needed template instantiation is emitted.
24109 * Bound member functions:: You can extract a function pointer to the
24110 method denoted by a @samp{->*} or @samp{.*} expression.
24111 * C++ Attributes:: Variable, function, and type attributes for C++ only.
24112 * Function Multiversioning:: Declaring multiple function versions.
24113 * Type Traits:: Compiler support for type traits.
24114 * C++ Concepts:: Improved support for generic programming.
24115 * Deprecated Features:: Things will disappear from G++.
24116 * Backwards Compatibility:: Compatibilities with earlier definitions of C++.
24119 @node C++ Volatiles
24120 @section When is a Volatile C++ Object Accessed?
24121 @cindex accessing volatiles
24122 @cindex volatile read
24123 @cindex volatile write
24124 @cindex volatile access
24126 The C++ standard differs from the C standard in its treatment of
24127 volatile objects. It fails to specify what constitutes a volatile
24128 access, except to say that C++ should behave in a similar manner to C
24129 with respect to volatiles, where possible. However, the different
24130 lvalueness of expressions between C and C++ complicate the behavior.
24131 G++ behaves the same as GCC for volatile access, @xref{C
24132 Extensions,,Volatiles}, for a description of GCC's behavior.
24134 The C and C++ language specifications differ when an object is
24135 accessed in a void context:
24138 volatile int *src = @var{somevalue};
24142 The C++ standard specifies that such expressions do not undergo lvalue
24143 to rvalue conversion, and that the type of the dereferenced object may
24144 be incomplete. The C++ standard does not specify explicitly that it
24145 is lvalue to rvalue conversion that is responsible for causing an
24146 access. There is reason to believe that it is, because otherwise
24147 certain simple expressions become undefined. However, because it
24148 would surprise most programmers, G++ treats dereferencing a pointer to
24149 volatile object of complete type as GCC would do for an equivalent
24150 type in C@. When the object has incomplete type, G++ issues a
24151 warning; if you wish to force an error, you must force a conversion to
24152 rvalue with, for instance, a static cast.
24154 When using a reference to volatile, G++ does not treat equivalent
24155 expressions as accesses to volatiles, but instead issues a warning that
24156 no volatile is accessed. The rationale for this is that otherwise it
24157 becomes difficult to determine where volatile access occur, and not
24158 possible to ignore the return value from functions returning volatile
24159 references. Again, if you wish to force a read, cast the reference to
24162 G++ implements the same behavior as GCC does when assigning to a
24163 volatile object---there is no reread of the assigned-to object, the
24164 assigned rvalue is reused. Note that in C++ assignment expressions
24165 are lvalues, and if used as an lvalue, the volatile object is
24166 referred to. For instance, @var{vref} refers to @var{vobj}, as
24167 expected, in the following example:
24171 volatile int &vref = vobj = @var{something};
24174 @node Restricted Pointers
24175 @section Restricting Pointer Aliasing
24176 @cindex restricted pointers
24177 @cindex restricted references
24178 @cindex restricted this pointer
24180 As with the C front end, G++ understands the C99 feature of restricted pointers,
24181 specified with the @code{__restrict__}, or @code{__restrict} type
24182 qualifier. Because you cannot compile C++ by specifying the @option{-std=c99}
24183 language flag, @code{restrict} is not a keyword in C++.
24185 In addition to allowing restricted pointers, you can specify restricted
24186 references, which indicate that the reference is not aliased in the local
24190 void fn (int *__restrict__ rptr, int &__restrict__ rref)
24197 In the body of @code{fn}, @var{rptr} points to an unaliased integer and
24198 @var{rref} refers to a (different) unaliased integer.
24200 You may also specify whether a member function's @var{this} pointer is
24201 unaliased by using @code{__restrict__} as a member function qualifier.
24204 void T::fn () __restrict__
24211 Within the body of @code{T::fn}, @var{this} has the effective
24212 definition @code{T *__restrict__ const this}. Notice that the
24213 interpretation of a @code{__restrict__} member function qualifier is
24214 different to that of @code{const} or @code{volatile} qualifier, in that it
24215 is applied to the pointer rather than the object. This is consistent with
24216 other compilers that implement restricted pointers.
24218 As with all outermost parameter qualifiers, @code{__restrict__} is
24219 ignored in function definition matching. This means you only need to
24220 specify @code{__restrict__} in a function definition, rather than
24221 in a function prototype as well.
24223 @node Vague Linkage
24224 @section Vague Linkage
24225 @cindex vague linkage
24227 There are several constructs in C++ that require space in the object
24228 file but are not clearly tied to a single translation unit. We say that
24229 these constructs have ``vague linkage''. Typically such constructs are
24230 emitted wherever they are needed, though sometimes we can be more
24234 @item Inline Functions
24235 Inline functions are typically defined in a header file which can be
24236 included in many different compilations. Hopefully they can usually be
24237 inlined, but sometimes an out-of-line copy is necessary, if the address
24238 of the function is taken or if inlining fails. In general, we emit an
24239 out-of-line copy in all translation units where one is needed. As an
24240 exception, we only emit inline virtual functions with the vtable, since
24241 it always requires a copy.
24243 Local static variables and string constants used in an inline function
24244 are also considered to have vague linkage, since they must be shared
24245 between all inlined and out-of-line instances of the function.
24249 C++ virtual functions are implemented in most compilers using a lookup
24250 table, known as a vtable. The vtable contains pointers to the virtual
24251 functions provided by a class, and each object of the class contains a
24252 pointer to its vtable (or vtables, in some multiple-inheritance
24253 situations). If the class declares any non-inline, non-pure virtual
24254 functions, the first one is chosen as the ``key method'' for the class,
24255 and the vtable is only emitted in the translation unit where the key
24258 @emph{Note:} If the chosen key method is later defined as inline, the
24259 vtable is still emitted in every translation unit that defines it.
24260 Make sure that any inline virtuals are declared inline in the class
24261 body, even if they are not defined there.
24263 @item @code{type_info} objects
24264 @cindex @code{type_info}
24266 C++ requires information about types to be written out in order to
24267 implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
24268 For polymorphic classes (classes with virtual functions), the @samp{type_info}
24269 object is written out along with the vtable so that @samp{dynamic_cast}
24270 can determine the dynamic type of a class object at run time. For all
24271 other types, we write out the @samp{type_info} object when it is used: when
24272 applying @samp{typeid} to an expression, throwing an object, or
24273 referring to a type in a catch clause or exception specification.
24275 @item Template Instantiations
24276 Most everything in this section also applies to template instantiations,
24277 but there are other options as well.
24278 @xref{Template Instantiation,,Where's the Template?}.
24282 When used with GNU ld version 2.8 or later on an ELF system such as
24283 GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of
24284 these constructs will be discarded at link time. This is known as
24287 On targets that don't support COMDAT, but do support weak symbols, GCC
24288 uses them. This way one copy overrides all the others, but
24289 the unused copies still take up space in the executable.
24291 For targets that do not support either COMDAT or weak symbols,
24292 most entities with vague linkage are emitted as local symbols to
24293 avoid duplicate definition errors from the linker. This does not happen
24294 for local statics in inlines, however, as having multiple copies
24295 almost certainly breaks things.
24297 @xref{C++ Interface,,Declarations and Definitions in One Header}, for
24298 another way to control placement of these constructs.
24300 @node C++ Interface
24301 @section C++ Interface and Implementation Pragmas
24303 @cindex interface and implementation headers, C++
24304 @cindex C++ interface and implementation headers
24305 @cindex pragmas, interface and implementation
24307 @code{#pragma interface} and @code{#pragma implementation} provide the
24308 user with a way of explicitly directing the compiler to emit entities
24309 with vague linkage (and debugging information) in a particular
24312 @emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2
24313 by COMDAT support and the ``key method'' heuristic
24314 mentioned in @ref{Vague Linkage}. Using them can actually cause your
24315 program to grow due to unnecessary out-of-line copies of inline
24319 @item #pragma interface
24320 @itemx #pragma interface "@var{subdir}/@var{objects}.h"
24321 @kindex #pragma interface
24322 Use this directive in @emph{header files} that define object classes, to save
24323 space in most of the object files that use those classes. Normally,
24324 local copies of certain information (backup copies of inline member
24325 functions, debugging information, and the internal tables that implement
24326 virtual functions) must be kept in each object file that includes class
24327 definitions. You can use this pragma to avoid such duplication. When a
24328 header file containing @samp{#pragma interface} is included in a
24329 compilation, this auxiliary information is not generated (unless
24330 the main input source file itself uses @samp{#pragma implementation}).
24331 Instead, the object files contain references to be resolved at link
24334 The second form of this directive is useful for the case where you have
24335 multiple headers with the same name in different directories. If you
24336 use this form, you must specify the same string to @samp{#pragma
24339 @item #pragma implementation
24340 @itemx #pragma implementation "@var{objects}.h"
24341 @kindex #pragma implementation
24342 Use this pragma in a @emph{main input file}, when you want full output from
24343 included header files to be generated (and made globally visible). The
24344 included header file, in turn, should use @samp{#pragma interface}.
24345 Backup copies of inline member functions, debugging information, and the
24346 internal tables used to implement virtual functions are all generated in
24347 implementation files.
24349 @cindex implied @code{#pragma implementation}
24350 @cindex @code{#pragma implementation}, implied
24351 @cindex naming convention, implementation headers
24352 If you use @samp{#pragma implementation} with no argument, it applies to
24353 an include file with the same basename@footnote{A file's @dfn{basename}
24354 is the name stripped of all leading path information and of trailing
24355 suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source
24356 file. For example, in @file{allclass.cc}, giving just
24357 @samp{#pragma implementation}
24358 by itself is equivalent to @samp{#pragma implementation "allclass.h"}.
24360 Use the string argument if you want a single implementation file to
24361 include code from multiple header files. (You must also use
24362 @samp{#include} to include the header file; @samp{#pragma
24363 implementation} only specifies how to use the file---it doesn't actually
24366 There is no way to split up the contents of a single header file into
24367 multiple implementation files.
24370 @cindex inlining and C++ pragmas
24371 @cindex C++ pragmas, effect on inlining
24372 @cindex pragmas in C++, effect on inlining
24373 @samp{#pragma implementation} and @samp{#pragma interface} also have an
24374 effect on function inlining.
24376 If you define a class in a header file marked with @samp{#pragma
24377 interface}, the effect on an inline function defined in that class is
24378 similar to an explicit @code{extern} declaration---the compiler emits
24379 no code at all to define an independent version of the function. Its
24380 definition is used only for inlining with its callers.
24382 @opindex fno-implement-inlines
24383 Conversely, when you include the same header file in a main source file
24384 that declares it as @samp{#pragma implementation}, the compiler emits
24385 code for the function itself; this defines a version of the function
24386 that can be found via pointers (or by callers compiled without
24387 inlining). If all calls to the function can be inlined, you can avoid
24388 emitting the function by compiling with @option{-fno-implement-inlines}.
24389 If any calls are not inlined, you will get linker errors.
24391 @node Template Instantiation
24392 @section Where's the Template?
24393 @cindex template instantiation
24395 C++ templates were the first language feature to require more
24396 intelligence from the environment than was traditionally found on a UNIX
24397 system. Somehow the compiler and linker have to make sure that each
24398 template instance occurs exactly once in the executable if it is needed,
24399 and not at all otherwise. There are two basic approaches to this
24400 problem, which are referred to as the Borland model and the Cfront model.
24403 @item Borland model
24404 Borland C++ solved the template instantiation problem by adding the code
24405 equivalent of common blocks to their linker; the compiler emits template
24406 instances in each translation unit that uses them, and the linker
24407 collapses them together. The advantage of this model is that the linker
24408 only has to consider the object files themselves; there is no external
24409 complexity to worry about. The disadvantage is that compilation time
24410 is increased because the template code is being compiled repeatedly.
24411 Code written for this model tends to include definitions of all
24412 templates in the header file, since they must be seen to be
24416 The AT&T C++ translator, Cfront, solved the template instantiation
24417 problem by creating the notion of a template repository, an
24418 automatically maintained place where template instances are stored. A
24419 more modern version of the repository works as follows: As individual
24420 object files are built, the compiler places any template definitions and
24421 instantiations encountered in the repository. At link time, the link
24422 wrapper adds in the objects in the repository and compiles any needed
24423 instances that were not previously emitted. The advantages of this
24424 model are more optimal compilation speed and the ability to use the
24425 system linker; to implement the Borland model a compiler vendor also
24426 needs to replace the linker. The disadvantages are vastly increased
24427 complexity, and thus potential for error; for some code this can be
24428 just as transparent, but in practice it can been very difficult to build
24429 multiple programs in one directory and one program in multiple
24430 directories. Code written for this model tends to separate definitions
24431 of non-inline member templates into a separate file, which should be
24432 compiled separately.
24435 G++ implements the Borland model on targets where the linker supports it,
24436 including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows.
24437 Otherwise G++ implements neither automatic model.
24439 You have the following options for dealing with template instantiations:
24443 Do nothing. Code written for the Borland model works fine, but
24444 each translation unit contains instances of each of the templates it
24445 uses. The duplicate instances will be discarded by the linker, but in
24446 a large program, this can lead to an unacceptable amount of code
24447 duplication in object files or shared libraries.
24449 Duplicate instances of a template can be avoided by defining an explicit
24450 instantiation in one object file, and preventing the compiler from doing
24451 implicit instantiations in any other object files by using an explicit
24452 instantiation declaration, using the @code{extern template} syntax:
24455 extern template int max (int, int);
24458 This syntax is defined in the C++ 2011 standard, but has been supported by
24459 G++ and other compilers since well before 2011.
24461 Explicit instantiations can be used for the largest or most frequently
24462 duplicated instances, without having to know exactly which other instances
24463 are used in the rest of the program. You can scatter the explicit
24464 instantiations throughout your program, perhaps putting them in the
24465 translation units where the instances are used or the translation units
24466 that define the templates themselves; you can put all of the explicit
24467 instantiations you need into one big file; or you can create small files
24474 template class Foo<int>;
24475 template ostream& operator <<
24476 (ostream&, const Foo<int>&);
24480 for each of the instances you need, and create a template instantiation
24481 library from those.
24483 This is the simplest option, but also offers flexibility and
24484 fine-grained control when necessary. It is also the most portable
24485 alternative and programs using this approach will work with most modern
24490 Compile your template-using code with @option{-frepo}. The compiler
24491 generates files with the extension @samp{.rpo} listing all of the
24492 template instantiations used in the corresponding object files that
24493 could be instantiated there; the link wrapper, @samp{collect2},
24494 then updates the @samp{.rpo} files to tell the compiler where to place
24495 those instantiations and rebuild any affected object files. The
24496 link-time overhead is negligible after the first pass, as the compiler
24497 continues to place the instantiations in the same files.
24499 This can be a suitable option for application code written for the Borland
24500 model, as it usually just works. Code written for the Cfront model
24501 needs to be modified so that the template definitions are available at
24502 one or more points of instantiation; usually this is as simple as adding
24503 @code{#include <tmethods.cc>} to the end of each template header.
24505 For library code, if you want the library to provide all of the template
24506 instantiations it needs, just try to link all of its object files
24507 together; the link will fail, but cause the instantiations to be
24508 generated as a side effect. Be warned, however, that this may cause
24509 conflicts if multiple libraries try to provide the same instantiations.
24510 For greater control, use explicit instantiation as described in the next
24514 @opindex fno-implicit-templates
24515 Compile your code with @option{-fno-implicit-templates} to disable the
24516 implicit generation of template instances, and explicitly instantiate
24517 all the ones you use. This approach requires more knowledge of exactly
24518 which instances you need than do the others, but it's less
24519 mysterious and allows greater control if you want to ensure that only
24520 the intended instances are used.
24522 If you are using Cfront-model code, you can probably get away with not
24523 using @option{-fno-implicit-templates} when compiling files that don't
24524 @samp{#include} the member template definitions.
24526 If you use one big file to do the instantiations, you may want to
24527 compile it without @option{-fno-implicit-templates} so you get all of the
24528 instances required by your explicit instantiations (but not by any
24529 other files) without having to specify them as well.
24531 In addition to forward declaration of explicit instantiations
24532 (with @code{extern}), G++ has extended the template instantiation
24533 syntax to support instantiation of the compiler support data for a
24534 template class (i.e.@: the vtable) without instantiating any of its
24535 members (with @code{inline}), and instantiation of only the static data
24536 members of a template class, without the support data or member
24537 functions (with @code{static}):
24540 inline template class Foo<int>;
24541 static template class Foo<int>;
24545 @node Bound member functions
24546 @section Extracting the Function Pointer from a Bound Pointer to Member Function
24548 @cindex pointer to member function
24549 @cindex bound pointer to member function
24551 In C++, pointer to member functions (PMFs) are implemented using a wide
24552 pointer of sorts to handle all the possible call mechanisms; the PMF
24553 needs to store information about how to adjust the @samp{this} pointer,
24554 and if the function pointed to is virtual, where to find the vtable, and
24555 where in the vtable to look for the member function. If you are using
24556 PMFs in an inner loop, you should really reconsider that decision. If
24557 that is not an option, you can extract the pointer to the function that
24558 would be called for a given object/PMF pair and call it directly inside
24559 the inner loop, to save a bit of time.
24561 Note that you still pay the penalty for the call through a
24562 function pointer; on most modern architectures, such a call defeats the
24563 branch prediction features of the CPU@. This is also true of normal
24564 virtual function calls.
24566 The syntax for this extension is
24570 extern int (A::*fp)();
24571 typedef int (*fptr)(A *);
24573 fptr p = (fptr)(a.*fp);
24576 For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}),
24577 no object is needed to obtain the address of the function. They can be
24578 converted to function pointers directly:
24581 fptr p1 = (fptr)(&A::foo);
24584 @opindex Wno-pmf-conversions
24585 You must specify @option{-Wno-pmf-conversions} to use this extension.
24587 @node C++ Attributes
24588 @section C++-Specific Variable, Function, and Type Attributes
24590 Some attributes only make sense for C++ programs.
24593 @item abi_tag ("@var{tag}", ...)
24594 @cindex @code{abi_tag} function attribute
24595 @cindex @code{abi_tag} variable attribute
24596 @cindex @code{abi_tag} type attribute
24597 The @code{abi_tag} attribute can be applied to a function, variable, or class
24598 declaration. It modifies the mangled name of the entity to
24599 incorporate the tag name, in order to distinguish the function or
24600 class from an earlier version with a different ABI; perhaps the class
24601 has changed size, or the function has a different return type that is
24602 not encoded in the mangled name.
24604 The attribute can also be applied to an inline namespace, but does not
24605 affect the mangled name of the namespace; in this case it is only used
24606 for @option{-Wabi-tag} warnings and automatic tagging of functions and
24607 variables. Tagging inline namespaces is generally preferable to
24608 tagging individual declarations, but the latter is sometimes
24609 necessary, such as when only certain members of a class need to be
24612 The argument can be a list of strings of arbitrary length. The
24613 strings are sorted on output, so the order of the list is
24616 A redeclaration of an entity must not add new ABI tags,
24617 since doing so would change the mangled name.
24619 The ABI tags apply to a name, so all instantiations and
24620 specializations of a template have the same tags. The attribute will
24621 be ignored if applied to an explicit specialization or instantiation.
24623 The @option{-Wabi-tag} flag enables a warning about a class which does
24624 not have all the ABI tags used by its subobjects and virtual functions; for users with code
24625 that needs to coexist with an earlier ABI, using this option can help
24626 to find all affected types that need to be tagged.
24628 When a type involving an ABI tag is used as the type of a variable or
24629 return type of a function where that tag is not already present in the
24630 signature of the function, the tag is automatically applied to the
24631 variable or function. @option{-Wabi-tag} also warns about this
24632 situation; this warning can be avoided by explicitly tagging the
24633 variable or function or moving it into a tagged inline namespace.
24635 @item init_priority (@var{priority})
24636 @cindex @code{init_priority} variable attribute
24638 In Standard C++, objects defined at namespace scope are guaranteed to be
24639 initialized in an order in strict accordance with that of their definitions
24640 @emph{in a given translation unit}. No guarantee is made for initializations
24641 across translation units. However, GNU C++ allows users to control the
24642 order of initialization of objects defined at namespace scope with the
24643 @code{init_priority} attribute by specifying a relative @var{priority},
24644 a constant integral expression currently bounded between 101 and 65535
24645 inclusive. Lower numbers indicate a higher priority.
24647 In the following example, @code{A} would normally be created before
24648 @code{B}, but the @code{init_priority} attribute reverses that order:
24651 Some_Class A __attribute__ ((init_priority (2000)));
24652 Some_Class B __attribute__ ((init_priority (543)));
24656 Note that the particular values of @var{priority} do not matter; only their
24660 @cindex @code{warn_unused} type attribute
24662 For C++ types with non-trivial constructors and/or destructors it is
24663 impossible for the compiler to determine whether a variable of this
24664 type is truly unused if it is not referenced. This type attribute
24665 informs the compiler that variables of this type should be warned
24666 about if they appear to be unused, just like variables of fundamental
24669 This attribute is appropriate for types which just represent a value,
24670 such as @code{std::string}; it is not appropriate for types which
24671 control a resource, such as @code{std::lock_guard}.
24673 This attribute is also accepted in C, but it is unnecessary because C
24674 does not have constructors or destructors.
24678 @node Function Multiversioning
24679 @section Function Multiversioning
24680 @cindex function versions
24682 With the GNU C++ front end, for x86 targets, you may specify multiple
24683 versions of a function, where each function is specialized for a
24684 specific target feature. At runtime, the appropriate version of the
24685 function is automatically executed depending on the characteristics of
24686 the execution platform. Here is an example.
24689 __attribute__ ((target ("default")))
24692 // The default version of foo.
24696 __attribute__ ((target ("sse4.2")))
24699 // foo version for SSE4.2
24703 __attribute__ ((target ("arch=atom")))
24706 // foo version for the Intel ATOM processor
24710 __attribute__ ((target ("arch=amdfam10")))
24713 // foo version for the AMD Family 0x10 processors.
24720 assert ((*p) () == foo ());
24725 In the above example, four versions of function foo are created. The
24726 first version of foo with the target attribute "default" is the default
24727 version. This version gets executed when no other target specific
24728 version qualifies for execution on a particular platform. A new version
24729 of foo is created by using the same function signature but with a
24730 different target string. Function foo is called or a pointer to it is
24731 taken just like a regular function. GCC takes care of doing the
24732 dispatching to call the right version at runtime. Refer to the
24733 @uref{http://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
24734 Function Multiversioning} for more details.
24737 @section Type Traits
24739 The C++ front end implements syntactic extensions that allow
24740 compile-time determination of
24741 various characteristics of a type (or of a
24745 @item __has_nothrow_assign (type)
24746 If @code{type} is @code{const}-qualified or is a reference type then
24747 the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)}
24748 is @code{true} then the trait is @code{true}, else if @code{type} is
24749 a cv-qualified class or union type with copy assignment operators that are
24750 known not to throw an exception then the trait is @code{true}, else it is
24752 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24753 @code{void}, or an array of unknown bound.
24755 @item __has_nothrow_copy (type)
24756 If @code{__has_trivial_copy (type)} is @code{true} then the trait is
24757 @code{true}, else if @code{type} is a cv-qualified class or union type
24758 with copy constructors that are known not to throw an exception then
24759 the trait is @code{true}, else it is @code{false}.
24760 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24761 @code{void}, or an array of unknown bound.
24763 @item __has_nothrow_constructor (type)
24764 If @code{__has_trivial_constructor (type)} is @code{true} then the trait
24765 is @code{true}, else if @code{type} is a cv class or union type (or array
24766 thereof) with a default constructor that is known not to throw an
24767 exception then the trait is @code{true}, else it is @code{false}.
24768 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24769 @code{void}, or an array of unknown bound.
24771 @item __has_trivial_assign (type)
24772 If @code{type} is @code{const}- qualified or is a reference type then
24773 the trait is @code{false}. Otherwise if @code{__is_pod (type)} is
24774 @code{true} then the trait is @code{true}, else if @code{type} is
24775 a cv-qualified class or union type with a trivial copy assignment
24776 ([class.copy]) then the trait is @code{true}, else it is @code{false}.
24777 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24778 @code{void}, or an array of unknown bound.
24780 @item __has_trivial_copy (type)
24781 If @code{__is_pod (type)} is @code{true} or @code{type} is a reference
24782 type then the trait is @code{true}, else if @code{type} is a cv class
24783 or union type with a trivial copy constructor ([class.copy]) then the trait
24784 is @code{true}, else it is @code{false}. Requires: @code{type} shall be
24785 a complete type, (possibly cv-qualified) @code{void}, or an array of unknown
24788 @item __has_trivial_constructor (type)
24789 If @code{__is_pod (type)} is @code{true} then the trait is @code{true},
24790 else if @code{type} is a cv-qualified class or union type (or array thereof)
24791 with a trivial default constructor ([class.ctor]) then the trait is @code{true},
24792 else it is @code{false}.
24793 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24794 @code{void}, or an array of unknown bound.
24796 @item __has_trivial_destructor (type)
24797 If @code{__is_pod (type)} is @code{true} or @code{type} is a reference type
24798 then the trait is @code{true}, else if @code{type} is a cv class or union
24799 type (or array thereof) with a trivial destructor ([class.dtor]) then
24800 the trait is @code{true}, else it is @code{false}.
24801 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24802 @code{void}, or an array of unknown bound.
24804 @item __has_virtual_destructor (type)
24805 If @code{type} is a class type with a virtual destructor
24806 ([class.dtor]) then the trait is @code{true}, else it is @code{false}.
24807 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24808 @code{void}, or an array of unknown bound.
24810 @item __is_abstract (type)
24811 If @code{type} is an abstract class ([class.abstract]) then the trait
24812 is @code{true}, else it is @code{false}.
24813 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24814 @code{void}, or an array of unknown bound.
24816 @item __is_base_of (base_type, derived_type)
24817 If @code{base_type} is a base class of @code{derived_type}
24818 ([class.derived]) then the trait is @code{true}, otherwise it is @code{false}.
24819 Top-level cv-qualifications of @code{base_type} and
24820 @code{derived_type} are ignored. For the purposes of this trait, a
24821 class type is considered is own base.
24822 Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)}
24823 are @code{true} and @code{base_type} and @code{derived_type} are not the same
24824 type (disregarding cv-qualifiers), @code{derived_type} shall be a complete
24825 type. A diagnostic is produced if this requirement is not met.
24827 @item __is_class (type)
24828 If @code{type} is a cv-qualified class type, and not a union type
24829 ([basic.compound]) the trait is @code{true}, else it is @code{false}.
24831 @item __is_empty (type)
24832 If @code{__is_class (type)} is @code{false} then the trait is @code{false}.
24833 Otherwise @code{type} is considered empty if and only if: @code{type}
24834 has no non-static data members, or all non-static data members, if
24835 any, are bit-fields of length 0, and @code{type} has no virtual
24836 members, and @code{type} has no virtual base classes, and @code{type}
24837 has no base classes @code{base_type} for which
24838 @code{__is_empty (base_type)} is @code{false}.
24839 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24840 @code{void}, or an array of unknown bound.
24842 @item __is_enum (type)
24843 If @code{type} is a cv enumeration type ([basic.compound]) the trait is
24844 @code{true}, else it is @code{false}.
24846 @item __is_literal_type (type)
24847 If @code{type} is a literal type ([basic.types]) the trait is
24848 @code{true}, else it is @code{false}.
24849 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24850 @code{void}, or an array of unknown bound.
24852 @item __is_pod (type)
24853 If @code{type} is a cv POD type ([basic.types]) then the trait is @code{true},
24854 else it is @code{false}.
24855 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24856 @code{void}, or an array of unknown bound.
24858 @item __is_polymorphic (type)
24859 If @code{type} is a polymorphic class ([class.virtual]) then the trait
24860 is @code{true}, else it is @code{false}.
24861 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24862 @code{void}, or an array of unknown bound.
24864 @item __is_standard_layout (type)
24865 If @code{type} is a standard-layout type ([basic.types]) the trait is
24866 @code{true}, else it is @code{false}.
24867 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24868 @code{void}, or an array of unknown bound.
24870 @item __is_trivial (type)
24871 If @code{type} is a trivial type ([basic.types]) the trait is
24872 @code{true}, else it is @code{false}.
24873 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24874 @code{void}, or an array of unknown bound.
24876 @item __is_union (type)
24877 If @code{type} is a cv union type ([basic.compound]) the trait is
24878 @code{true}, else it is @code{false}.
24880 @item __underlying_type (type)
24881 The underlying type of @code{type}.
24882 Requires: @code{type} shall be an enumeration type ([dcl.enum]).
24884 @item __integer_pack (length)
24885 When used as the pattern of a pack expansion within a template
24886 definition, expands to a template argument pack containing integers
24887 from @code{0} to @code{length-1}. This is provided for efficient
24888 implementation of @code{std::make_integer_sequence}.
24894 @section C++ Concepts
24896 C++ concepts provide much-improved support for generic programming. In
24897 particular, they allow the specification of constraints on template arguments.
24898 The constraints are used to extend the usual overloading and partial
24899 specialization capabilities of the language, allowing generic data structures
24900 and algorithms to be ``refined'' based on their properties rather than their
24903 The following keywords are reserved for concepts.
24907 States an expression as an assumption, and if possible, verifies that the
24908 assumption is valid. For example, @code{assume(n > 0)}.
24911 Introduces an axiom definition. Axioms introduce requirements on values.
24914 Introduces a universally quantified object in an axiom. For example,
24915 @code{forall (int n) n + 0 == n}).
24918 Introduces a concept definition. Concepts are sets of syntactic and semantic
24919 requirements on types and their values.
24922 Introduces constraints on template arguments or requirements for a member
24923 function of a class template.
24927 The front end also exposes a number of internal mechanism that can be used
24928 to simplify the writing of type traits. Note that some of these traits are
24929 likely to be removed in the future.
24932 @item __is_same (type1, type2)
24933 A binary type trait: @code{true} whenever the type arguments are the same.
24938 @node Deprecated Features
24939 @section Deprecated Features
24941 In the past, the GNU C++ compiler was extended to experiment with new
24942 features, at a time when the C++ language was still evolving. Now that
24943 the C++ standard is complete, some of those features are superseded by
24944 superior alternatives. Using the old features might cause a warning in
24945 some cases that the feature will be dropped in the future. In other
24946 cases, the feature might be gone already.
24948 G++ allows a virtual function returning @samp{void *} to be overridden
24949 by one returning a different pointer type. This extension to the
24950 covariant return type rules is now deprecated and will be removed from a
24953 The use of default arguments in function pointers, function typedefs
24954 and other places where they are not permitted by the standard is
24955 deprecated and will be removed from a future version of G++.
24957 G++ allows floating-point literals to appear in integral constant expressions,
24958 e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} }
24959 This extension is deprecated and will be removed from a future version.
24961 G++ allows static data members of const floating-point type to be declared
24962 with an initializer in a class definition. The standard only allows
24963 initializers for static members of const integral types and const
24964 enumeration types so this extension has been deprecated and will be removed
24965 from a future version.
24967 G++ allows attributes to follow a parenthesized direct initializer,
24968 e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension
24969 has been ignored since G++ 3.3 and is deprecated.
24971 G++ allows anonymous structs and unions to have members that are not
24972 public non-static data members (i.e.@: fields). These extensions are
24975 @node Backwards Compatibility
24976 @section Backwards Compatibility
24977 @cindex Backwards Compatibility
24978 @cindex ARM [Annotated C++ Reference Manual]
24980 Now that there is a definitive ISO standard C++, G++ has a specification
24981 to adhere to. The C++ language evolved over time, and features that
24982 used to be acceptable in previous drafts of the standard, such as the ARM
24983 [Annotated C++ Reference Manual], are no longer accepted. In order to allow
24984 compilation of C++ written to such drafts, G++ contains some backwards
24985 compatibilities. @emph{All such backwards compatibility features are
24986 liable to disappear in future versions of G++.} They should be considered
24987 deprecated. @xref{Deprecated Features}.
24991 @item Implicit C language
24992 Old C system header files did not contain an @code{extern "C" @{@dots{}@}}
24993 scope to set the language. On such systems, all system header files are
24994 implicitly scoped inside a C language scope. Such headers must
24995 correctly prototype function argument types, there is no leeway for
24996 @code{()} to indicate an unspecified set of arguments.
25000 @c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd
25001 @c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr