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, M32C, RL78, and x86 targets support
1389 address spaces other than the generic address space.
1391 Address space identifiers may be used exactly like any other C type
1392 qualifier (e.g., @code{const} or @code{volatile}). See the N1275
1393 document for more details.
1395 @anchor{AVR Named Address Spaces}
1396 @subsection AVR Named Address Spaces
1398 On the AVR target, there are several address spaces that can be used
1399 in order to put read-only data into the flash memory and access that
1400 data by means of the special instructions @code{LPM} or @code{ELPM}
1401 needed to read from flash.
1403 Devices belonging to @code{avrtiny} and @code{avrxmega3} can access
1404 flash memory by means of @code{LD*} instructions because the flash
1405 memory is mapped into the RAM address space. There is @emph{no need}
1406 for language extensions like @code{__flash} or attribute
1407 @ref{AVR Variable Attributes,,@code{progmem}}.
1408 The default linker description files for these devices cater for that
1409 feature and @code{.rodata} stays in flash: The compiler just generates
1410 @code{LD*} instructions, and the linker script adds core specific
1411 offsets to all @code{.rodata} symbols: @code{0x4000} in the case of
1412 @code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}.
1413 See @ref{AVR Options} for a list of respective devices.
1415 For devices not in @code{avrtiny} or @code{avrxmega3},
1416 any data including read-only data is located in RAM (the generic
1417 address space) because flash memory is not visible in the RAM address
1418 space. In order to locate read-only data in flash memory @emph{and}
1419 to generate the right instructions to access this data without
1420 using (inline) assembler code, special address spaces are needed.
1424 @cindex @code{__flash} AVR Named Address Spaces
1425 The @code{__flash} qualifier locates data in the
1426 @code{.progmem.data} section. Data is read using the @code{LPM}
1427 instruction. Pointers to this address space are 16 bits wide.
1434 @cindex @code{__flash1} AVR Named Address Spaces
1435 @cindex @code{__flash2} AVR Named Address Spaces
1436 @cindex @code{__flash3} AVR Named Address Spaces
1437 @cindex @code{__flash4} AVR Named Address Spaces
1438 @cindex @code{__flash5} AVR Named Address Spaces
1439 These are 16-bit address spaces locating data in section
1440 @code{.progmem@var{N}.data} where @var{N} refers to
1441 address space @code{__flash@var{N}}.
1442 The compiler sets the @code{RAMPZ} segment register appropriately
1443 before reading data by means of the @code{ELPM} instruction.
1446 @cindex @code{__memx} AVR Named Address Spaces
1447 This is a 24-bit address space that linearizes flash and RAM:
1448 If the high bit of the address is set, data is read from
1449 RAM using the lower two bytes as RAM address.
1450 If the high bit of the address is clear, data is read from flash
1451 with @code{RAMPZ} set according to the high byte of the address.
1452 @xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}.
1454 Objects in this address space are located in @code{.progmemx.data}.
1460 char my_read (const __flash char ** p)
1462 /* p is a pointer to RAM that points to a pointer to flash.
1463 The first indirection of p reads that flash pointer
1464 from RAM and the second indirection reads a char from this
1470 /* Locate array[] in flash memory */
1471 const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @};
1477 /* Return 17 by reading from flash memory */
1478 return array[array[i]];
1483 For each named address space supported by avr-gcc there is an equally
1484 named but uppercase built-in macro defined.
1485 The purpose is to facilitate testing if respective address space
1486 support is available or not:
1490 const __flash int var = 1;
1497 #include <avr/pgmspace.h> /* From AVR-LibC */
1499 const int var PROGMEM = 1;
1503 return (int) pgm_read_word (&var);
1505 #endif /* __FLASH */
1509 Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}}
1510 locates data in flash but
1511 accesses to these data read from generic address space, i.e.@:
1513 so that you need special accessors like @code{pgm_read_byte}
1514 from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}}
1515 together with attribute @code{progmem}.
1518 @b{Limitations and caveats}
1522 Reading across the 64@tie{}KiB section boundary of
1523 the @code{__flash} or @code{__flash@var{N}} address spaces
1524 shows undefined behavior. The only address space that
1525 supports reading across the 64@tie{}KiB flash segment boundaries is
1529 If you use one of the @code{__flash@var{N}} address spaces
1530 you must arrange your linker script to locate the
1531 @code{.progmem@var{N}.data} sections according to your needs.
1534 Any data or pointers to the non-generic address spaces must
1535 be qualified as @code{const}, i.e.@: as read-only data.
1536 This still applies if the data in one of these address
1537 spaces like software version number or calibration lookup table are intended to
1538 be changed after load time by, say, a boot loader. In this case
1539 the right qualification is @code{const} @code{volatile} so that the compiler
1540 must not optimize away known values or insert them
1541 as immediates into operands of instructions.
1544 The following code initializes a variable @code{pfoo}
1545 located in static storage with a 24-bit address:
1547 extern const __memx char foo;
1548 const __memx void *pfoo = &foo;
1552 On the reduced Tiny devices like ATtiny40, no address spaces are supported.
1553 Just use vanilla C / C++ code without overhead as outlined above.
1554 Attribute @code{progmem} is supported but works differently,
1555 see @ref{AVR Variable Attributes}.
1559 @subsection M32C Named Address Spaces
1560 @cindex @code{__far} M32C Named Address Spaces
1562 On the M32C target, with the R8C and M16C CPU variants, variables
1563 qualified with @code{__far} are accessed using 32-bit addresses in
1564 order to access memory beyond the first 64@tie{}Ki bytes. If
1565 @code{__far} is used with the M32CM or M32C CPU variants, it has no
1568 @subsection RL78 Named Address Spaces
1569 @cindex @code{__far} RL78 Named Address Spaces
1571 On the RL78 target, variables qualified with @code{__far} are accessed
1572 with 32-bit pointers (20-bit addresses) rather than the default 16-bit
1573 addresses. Non-far variables are assumed to appear in the topmost
1574 64@tie{}KiB of the address space.
1576 @subsection x86 Named Address Spaces
1577 @cindex x86 named address spaces
1579 On the x86 target, variables may be declared as being relative
1580 to the @code{%fs} or @code{%gs} segments.
1585 @cindex @code{__seg_fs} x86 named address space
1586 @cindex @code{__seg_gs} x86 named address space
1587 The object is accessed with the respective segment override prefix.
1589 The respective segment base must be set via some method specific to
1590 the operating system. Rather than require an expensive system call
1591 to retrieve the segment base, these address spaces are not considered
1592 to be subspaces of the generic (flat) address space. This means that
1593 explicit casts are required to convert pointers between these address
1594 spaces and the generic address space. In practice the application
1595 should cast to @code{uintptr_t} and apply the segment base offset
1596 that it installed previously.
1598 The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are
1599 defined when these address spaces are supported.
1603 @section Arrays of Length Zero
1604 @cindex arrays of length zero
1605 @cindex zero-length arrays
1606 @cindex length-zero arrays
1607 @cindex flexible array members
1609 Declaring zero-length arrays is allowed in GNU C as an extension.
1610 A zero-length array can be useful as the last element of a structure
1611 that is really a header for a variable-length object:
1619 struct line *thisline = (struct line *)
1620 malloc (sizeof (struct line) + this_length);
1621 thisline->length = this_length;
1624 Although the size of a zero-length array is zero, an array member of
1625 this kind may increase the size of the enclosing type as a result of tail
1626 padding. The offset of a zero-length array member from the beginning
1627 of the enclosing structure is the same as the offset of an array with
1628 one or more elements of the same type. The alignment of a zero-length
1629 array is the same as the alignment of its elements.
1631 Declaring zero-length arrays in other contexts, including as interior
1632 members of structure objects or as non-member objects, is discouraged.
1633 Accessing elements of zero-length arrays declared in such contexts is
1634 undefined and may be diagnosed.
1636 In the absence of the zero-length array extension, in ISO C90
1637 the @code{contents} array in the example above would typically be declared
1638 to have a single element. Unlike a zero-length array which only contributes
1639 to the size of the enclosing structure for the purposes of alignment,
1640 a one-element array always occupies at least as much space as a single
1641 object of the type. Although using one-element arrays this way is
1642 discouraged, GCC handles accesses to trailing one-element array members
1643 analogously to zero-length arrays.
1645 The preferred mechanism to declare variable-length types like
1646 @code{struct line} above is the ISO C99 @dfn{flexible array member},
1647 with slightly different syntax and semantics:
1651 Flexible array members are written as @code{contents[]} without
1655 Flexible array members have incomplete type, and so the @code{sizeof}
1656 operator may not be applied. As a quirk of the original implementation
1657 of zero-length arrays, @code{sizeof} evaluates to zero.
1660 Flexible array members may only appear as the last member of a
1661 @code{struct} that is otherwise non-empty.
1664 A structure containing a flexible array member, or a union containing
1665 such a structure (possibly recursively), may not be a member of a
1666 structure or an element of an array. (However, these uses are
1667 permitted by GCC as extensions.)
1670 Non-empty initialization of zero-length
1671 arrays is treated like any case where there are more initializer
1672 elements than the array holds, in that a suitable warning about ``excess
1673 elements in array'' is given, and the excess elements (all of them, in
1674 this case) are ignored.
1676 GCC allows static initialization of flexible array members.
1677 This is equivalent to defining a new structure containing the original
1678 structure followed by an array of sufficient size to contain the data.
1679 E.g.@: in the following, @code{f1} is constructed as if it were declared
1685 @} f1 = @{ 1, @{ 2, 3, 4 @} @};
1688 struct f1 f1; int data[3];
1689 @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
1693 The convenience of this extension is that @code{f1} has the desired
1694 type, eliminating the need to consistently refer to @code{f2.f1}.
1696 This has symmetry with normal static arrays, in that an array of
1697 unknown size is also written with @code{[]}.
1699 Of course, this extension only makes sense if the extra data comes at
1700 the end of a top-level object, as otherwise we would be overwriting
1701 data at subsequent offsets. To avoid undue complication and confusion
1702 with initialization of deeply nested arrays, we simply disallow any
1703 non-empty initialization except when the structure is the top-level
1704 object. For example:
1707 struct foo @{ int x; int y[]; @};
1708 struct bar @{ struct foo z; @};
1710 struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
1711 struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1712 struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
1713 struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1716 @node Empty Structures
1717 @section Structures with No Members
1718 @cindex empty structures
1719 @cindex zero-size structures
1721 GCC permits a C structure to have no members:
1728 The structure has size zero. In C++, empty structures are part
1729 of the language. G++ treats empty structures as if they had a single
1730 member of type @code{char}.
1732 @node Variable Length
1733 @section Arrays of Variable Length
1734 @cindex variable-length arrays
1735 @cindex arrays of variable length
1738 Variable-length automatic arrays are allowed in ISO C99, and as an
1739 extension GCC accepts them in C90 mode and in C++. These arrays are
1740 declared like any other automatic arrays, but with a length that is not
1741 a constant expression. The storage is allocated at the point of
1742 declaration and deallocated when the block scope containing the declaration
1748 concat_fopen (char *s1, char *s2, char *mode)
1750 char str[strlen (s1) + strlen (s2) + 1];
1753 return fopen (str, mode);
1757 @cindex scope of a variable length array
1758 @cindex variable-length array scope
1759 @cindex deallocating variable length arrays
1760 Jumping or breaking out of the scope of the array name deallocates the
1761 storage. Jumping into the scope is not allowed; you get an error
1764 @cindex variable-length array in a structure
1765 As an extension, GCC accepts variable-length arrays as a member of
1766 a structure or a union. For example:
1772 struct S @{ int x[n]; @};
1776 @cindex @code{alloca} vs variable-length arrays
1777 You can use the function @code{alloca} to get an effect much like
1778 variable-length arrays. The function @code{alloca} is available in
1779 many other C implementations (but not in all). On the other hand,
1780 variable-length arrays are more elegant.
1782 There are other differences between these two methods. Space allocated
1783 with @code{alloca} exists until the containing @emph{function} returns.
1784 The space for a variable-length array is deallocated as soon as the array
1785 name's scope ends, unless you also use @code{alloca} in this scope.
1787 You can also use variable-length arrays as arguments to functions:
1791 tester (int len, char data[len][len])
1797 The length of an array is computed once when the storage is allocated
1798 and is remembered for the scope of the array in case you access it with
1801 If you want to pass the array first and the length afterward, you can
1802 use a forward declaration in the parameter list---another GNU extension.
1806 tester (int len; char data[len][len], int len)
1812 @cindex parameter forward declaration
1813 The @samp{int len} before the semicolon is a @dfn{parameter forward
1814 declaration}, and it serves the purpose of making the name @code{len}
1815 known when the declaration of @code{data} is parsed.
1817 You can write any number of such parameter forward declarations in the
1818 parameter list. They can be separated by commas or semicolons, but the
1819 last one must end with a semicolon, which is followed by the ``real''
1820 parameter declarations. Each forward declaration must match a ``real''
1821 declaration in parameter name and data type. ISO C99 does not support
1822 parameter forward declarations.
1824 @node Variadic Macros
1825 @section Macros with a Variable Number of Arguments.
1826 @cindex variable number of arguments
1827 @cindex macro with variable arguments
1828 @cindex rest argument (in macro)
1829 @cindex variadic macros
1831 In the ISO C standard of 1999, a macro can be declared to accept a
1832 variable number of arguments much as a function can. The syntax for
1833 defining the macro is similar to that of a function. Here is an
1837 #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
1841 Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
1842 such a macro, it represents the zero or more tokens until the closing
1843 parenthesis that ends the invocation, including any commas. This set of
1844 tokens replaces the identifier @code{__VA_ARGS__} in the macro body
1845 wherever it appears. See the CPP manual for more information.
1847 GCC has long supported variadic macros, and used a different syntax that
1848 allowed you to give a name to the variable arguments just like any other
1849 argument. Here is an example:
1852 #define debug(format, args...) fprintf (stderr, format, args)
1856 This is in all ways equivalent to the ISO C example above, but arguably
1857 more readable and descriptive.
1859 GNU CPP has two further variadic macro extensions, and permits them to
1860 be used with either of the above forms of macro definition.
1862 In standard C, you are not allowed to leave the variable argument out
1863 entirely; but you are allowed to pass an empty argument. For example,
1864 this invocation is invalid in ISO C, because there is no comma after
1871 GNU CPP permits you to completely omit the variable arguments in this
1872 way. In the above examples, the compiler would complain, though since
1873 the expansion of the macro still has the extra comma after the format
1876 To help solve this problem, CPP behaves specially for variable arguments
1877 used with the token paste operator, @samp{##}. If instead you write
1880 #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
1884 and if the variable arguments are omitted or empty, the @samp{##}
1885 operator causes the preprocessor to remove the comma before it. If you
1886 do provide some variable arguments in your macro invocation, GNU CPP
1887 does not complain about the paste operation and instead places the
1888 variable arguments after the comma. Just like any other pasted macro
1889 argument, these arguments are not macro expanded.
1891 @node Escaped Newlines
1892 @section Slightly Looser Rules for Escaped Newlines
1893 @cindex escaped newlines
1894 @cindex newlines (escaped)
1896 The preprocessor treatment of escaped newlines is more relaxed
1897 than that specified by the C90 standard, which requires the newline
1898 to immediately follow a backslash.
1899 GCC's implementation allows whitespace in the form
1900 of spaces, horizontal and vertical tabs, and form feeds between the
1901 backslash and the subsequent newline. The preprocessor issues a
1902 warning, but treats it as a valid escaped newline and combines the two
1903 lines to form a single logical line. This works within comments and
1904 tokens, as well as between tokens. Comments are @emph{not} treated as
1905 whitespace for the purposes of this relaxation, since they have not
1906 yet been replaced with spaces.
1909 @section Non-Lvalue Arrays May Have Subscripts
1910 @cindex subscripting
1911 @cindex arrays, non-lvalue
1913 @cindex subscripting and function values
1914 In ISO C99, arrays that are not lvalues still decay to pointers, and
1915 may be subscripted, although they may not be modified or used after
1916 the next sequence point and the unary @samp{&} operator may not be
1917 applied to them. As an extension, GNU C allows such arrays to be
1918 subscripted in C90 mode, though otherwise they do not decay to
1919 pointers outside C99 mode. For example,
1920 this is valid in GNU C though not valid in C90:
1924 struct foo @{int a[4];@};
1930 return f().a[index];
1936 @section Arithmetic on @code{void}- and Function-Pointers
1937 @cindex void pointers, arithmetic
1938 @cindex void, size of pointer to
1939 @cindex function pointers, arithmetic
1940 @cindex function, size of pointer to
1942 In GNU C, addition and subtraction operations are supported on pointers to
1943 @code{void} and on pointers to functions. This is done by treating the
1944 size of a @code{void} or of a function as 1.
1946 A consequence of this is that @code{sizeof} is also allowed on @code{void}
1947 and on function types, and returns 1.
1949 @opindex Wpointer-arith
1950 The option @option{-Wpointer-arith} requests a warning if these extensions
1953 @node Variadic Pointer Args
1954 @section Pointer Arguments in Variadic Functions
1955 @cindex pointer arguments in variadic functions
1956 @cindex variadic functions, pointer arguments
1958 Standard C requires that pointer types used with @code{va_arg} in
1959 functions with variable argument lists either must be compatible with
1960 that of the actual argument, or that one type must be a pointer to
1961 @code{void} and the other a pointer to a character type. GNU C
1962 implements the POSIX XSI extension that additionally permits the use
1963 of @code{va_arg} with a pointer type to receive arguments of any other
1966 In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used
1967 to consume an argument of any pointer type.
1969 @node Pointers to Arrays
1970 @section Pointers to Arrays with Qualifiers Work as Expected
1971 @cindex pointers to arrays
1972 @cindex const qualifier
1974 In GNU C, pointers to arrays with qualifiers work similar to pointers
1975 to other qualified types. For example, a value of type @code{int (*)[5]}
1976 can be used to initialize a variable of type @code{const int (*)[5]}.
1977 These types are incompatible in ISO C because the @code{const} qualifier
1978 is formally attached to the element type of the array and not the
1983 transpose (int N, int M, double out[M][N], const double in[N][M]);
1987 transpose(3, 2, y, x);
1991 @section Non-Constant Initializers
1992 @cindex initializers, non-constant
1993 @cindex non-constant initializers
1995 As in standard C++ and ISO C99, the elements of an aggregate initializer for an
1996 automatic variable are not required to be constant expressions in GNU C@.
1997 Here is an example of an initializer with run-time varying elements:
2000 foo (float f, float g)
2002 float beat_freqs[2] = @{ f-g, f+g @};
2007 @node Compound Literals
2008 @section Compound Literals
2009 @cindex constructor expressions
2010 @cindex initializations in expressions
2011 @cindex structures, constructor expression
2012 @cindex expressions, constructor
2013 @cindex compound literals
2014 @c The GNU C name for what C99 calls compound literals was "constructor expressions".
2016 A compound literal looks like a cast of a brace-enclosed aggregate
2017 initializer list. Its value is an object of the type specified in
2018 the cast, containing the elements specified in the initializer.
2019 Unlike the result of a cast, a compound literal is an lvalue. ISO
2020 C99 and later support compound literals. As an extension, GCC
2021 supports compound literals also in C90 mode and in C++, although
2022 as explained below, the C++ semantics are somewhat different.
2024 Usually, the specified type of a compound literal is a structure. Assume
2025 that @code{struct foo} and @code{structure} are declared as shown:
2028 struct foo @{int a; char b[2];@} structure;
2032 Here is an example of constructing a @code{struct foo} with a compound literal:
2035 structure = ((struct foo) @{x + y, 'a', 0@});
2039 This is equivalent to writing the following:
2043 struct foo temp = @{x + y, 'a', 0@};
2048 You can also construct an array, though this is dangerous in C++, as
2049 explained below. If all the elements of the compound literal are
2050 (made up of) simple constant expressions suitable for use in
2051 initializers of objects of static storage duration, then the compound
2052 literal can be coerced to a pointer to its first element and used in
2053 such an initializer, as shown here:
2056 char **foo = (char *[]) @{ "x", "y", "z" @};
2059 Compound literals for scalar types and union types are also allowed. In
2060 the following example the variable @code{i} is initialized to the value
2061 @code{2}, the result of incrementing the unnamed object created by
2062 the compound literal.
2065 int i = ++(int) @{ 1 @};
2068 As a GNU extension, GCC allows initialization of objects with static storage
2069 duration by compound literals (which is not possible in ISO C99 because
2070 the initializer is not a constant).
2071 It is handled as if the object were initialized only with the brace-enclosed
2072 list if the types of the compound literal and the object match.
2073 The elements of the compound literal must be constant.
2074 If the object being initialized has array type of unknown size, the size is
2075 determined by the size of the compound literal.
2078 static struct foo x = (struct foo) @{1, 'a', 'b'@};
2079 static int y[] = (int []) @{1, 2, 3@};
2080 static int z[] = (int [3]) @{1@};
2084 The above lines are equivalent to the following:
2086 static struct foo x = @{1, 'a', 'b'@};
2087 static int y[] = @{1, 2, 3@};
2088 static int z[] = @{1, 0, 0@};
2091 In C, a compound literal designates an unnamed object with static or
2092 automatic storage duration. In C++, a compound literal designates a
2093 temporary object that only lives until the end of its full-expression.
2094 As a result, well-defined C code that takes the address of a subobject
2095 of a compound literal can be undefined in C++, so G++ rejects
2096 the conversion of a temporary array to a pointer. For instance, if
2097 the array compound literal example above appeared inside a function,
2098 any subsequent use of @code{foo} in C++ would have undefined behavior
2099 because the lifetime of the array ends after the declaration of @code{foo}.
2101 As an optimization, G++ sometimes gives array compound literals longer
2102 lifetimes: when the array either appears outside a function or has
2103 a @code{const}-qualified type. If @code{foo} and its initializer had
2104 elements of type @code{char *const} rather than @code{char *}, or if
2105 @code{foo} were a global variable, the array would have static storage
2106 duration. But it is probably safest just to avoid the use of array
2107 compound literals in C++ code.
2109 @node Designated Inits
2110 @section Designated Initializers
2111 @cindex initializers with labeled elements
2112 @cindex labeled elements in initializers
2113 @cindex case labels in initializers
2114 @cindex designated initializers
2116 Standard C90 requires the elements of an initializer to appear in a fixed
2117 order, the same as the order of the elements in the array or structure
2120 In ISO C99 you can give the elements in any order, specifying the array
2121 indices or structure field names they apply to, and GNU C allows this as
2122 an extension in C90 mode as well. This extension is not
2123 implemented in GNU C++.
2125 To specify an array index, write
2126 @samp{[@var{index}] =} before the element value. For example,
2129 int a[6] = @{ [4] = 29, [2] = 15 @};
2136 int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
2140 The index values must be constant expressions, even if the array being
2141 initialized is automatic.
2143 An alternative syntax for this that has been obsolete since GCC 2.5 but
2144 GCC still accepts is to write @samp{[@var{index}]} before the element
2145 value, with no @samp{=}.
2147 To initialize a range of elements to the same value, write
2148 @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
2149 extension. For example,
2152 int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
2156 If the value in it has side effects, the side effects happen only once,
2157 not for each initialized field by the range initializer.
2160 Note that the length of the array is the highest value specified
2163 In a structure initializer, specify the name of a field to initialize
2164 with @samp{.@var{fieldname} =} before the element value. For example,
2165 given the following structure,
2168 struct point @{ int x, y; @};
2172 the following initialization
2175 struct point p = @{ .y = yvalue, .x = xvalue @};
2182 struct point p = @{ xvalue, yvalue @};
2185 Another syntax that has the same meaning, obsolete since GCC 2.5, is
2186 @samp{@var{fieldname}:}, as shown here:
2189 struct point p = @{ y: yvalue, x: xvalue @};
2192 Omitted fields are implicitly initialized the same as for objects
2193 that have static storage duration.
2196 The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
2197 @dfn{designator}. You can also use a designator (or the obsolete colon
2198 syntax) when initializing a union, to specify which element of the union
2199 should be used. For example,
2202 union foo @{ int i; double d; @};
2204 union foo f = @{ .d = 4 @};
2208 converts 4 to a @code{double} to store it in the union using
2209 the second element. By contrast, casting 4 to type @code{union foo}
2210 stores it into the union as the integer @code{i}, since it is
2211 an integer. @xref{Cast to Union}.
2213 You can combine this technique of naming elements with ordinary C
2214 initialization of successive elements. Each initializer element that
2215 does not have a designator applies to the next consecutive element of the
2216 array or structure. For example,
2219 int a[6] = @{ [1] = v1, v2, [4] = v4 @};
2226 int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
2229 Labeling the elements of an array initializer is especially useful
2230 when the indices are characters or belong to an @code{enum} type.
2235 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
2236 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
2239 @cindex designator lists
2240 You can also write a series of @samp{.@var{fieldname}} and
2241 @samp{[@var{index}]} designators before an @samp{=} to specify a
2242 nested subobject to initialize; the list is taken relative to the
2243 subobject corresponding to the closest surrounding brace pair. For
2244 example, with the @samp{struct point} declaration above:
2247 struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
2250 If the same field is initialized multiple times, or overlapping
2251 fields of a union are initialized, the value from the last
2252 initialization is used. When a field of a union is itself a structure,
2253 the entire structure from the last field initialized is used. If any previous
2254 initializer has side effect, it is unspecified whether the side effect
2255 happens or not. Currently, GCC discards the side-effecting
2256 initializer expressions and issues a warning.
2259 @section Case Ranges
2261 @cindex ranges in case statements
2263 You can specify a range of consecutive values in a single @code{case} label,
2267 case @var{low} ... @var{high}:
2271 This has the same effect as the proper number of individual @code{case}
2272 labels, one for each integer value from @var{low} to @var{high}, inclusive.
2274 This feature is especially useful for ranges of ASCII character codes:
2280 @strong{Be careful:} Write spaces around the @code{...}, for otherwise
2281 it may be parsed wrong when you use it with integer values. For example,
2296 @section Cast to a Union Type
2297 @cindex cast to a union
2298 @cindex union, casting to a
2300 A cast to a union type is a C extension not available in C++. It looks
2301 just like ordinary casts with the constraint that the type specified is
2302 a union type. You can specify the type either with the @code{union}
2303 keyword or with a @code{typedef} name that refers to a union. The result
2304 of a cast to a union is a temporary rvalue of the union type with a member
2305 whose type matches that of the operand initialized to the value of
2306 the operand. The effect of a cast to a union is similar to a compound
2307 literal except that it yields an rvalue like standard casts do.
2308 @xref{Compound Literals}.
2310 Expressions that may be cast to the union type are those whose type matches
2311 at least one of the members of the union. Thus, given the following union
2315 union foo @{ int i; double d; @};
2322 both @code{x} and @code{y} can be cast to type @code{union foo} and
2323 the following assignments
2328 are shorthand equivalents of these
2330 z = (union foo) @{ .i = x @};
2331 z = (union foo) @{ .d = y @};
2334 However, @code{(union foo) FLT_MAX;} is not a valid cast because the union
2335 has no member of type @code{float}.
2337 Using the cast as the right-hand side of an assignment to a variable of
2338 union type is equivalent to storing in a member of the union with
2344 u = (union foo) x @equiv{} u.i = x
2345 u = (union foo) y @equiv{} u.d = y
2348 You can also use the union cast as a function argument:
2351 void hack (union foo);
2353 hack ((union foo) x);
2356 @node Mixed Declarations
2357 @section Mixed Declarations and Code
2358 @cindex mixed declarations and code
2359 @cindex declarations, mixed with code
2360 @cindex code, mixed with declarations
2362 ISO C99 and ISO C++ allow declarations and code to be freely mixed
2363 within compound statements. As an extension, GNU C also allows this in
2364 C90 mode. For example, you could do:
2373 Each identifier is visible from where it is declared until the end of
2374 the enclosing block.
2376 @node Function Attributes
2377 @section Declaring Attributes of Functions
2378 @cindex function attributes
2379 @cindex declaring attributes of functions
2380 @cindex @code{volatile} applied to function
2381 @cindex @code{const} applied to function
2383 In GNU C and C++, you can use function attributes to specify certain
2384 function properties that may help the compiler optimize calls or
2385 check code more carefully for correctness. For example, you
2386 can use attributes to specify that a function never returns
2387 (@code{noreturn}), returns a value depending only on the values of
2388 its arguments (@code{const}), or has @code{printf}-style arguments
2391 You can also use attributes to control memory placement, code
2392 generation options or call/return conventions within the function
2393 being annotated. Many of these attributes are target-specific. For
2394 example, many targets support attributes for defining interrupt
2395 handler functions, which typically must follow special register usage
2396 and return conventions. Such attributes are described in the subsection
2397 for each target. However, a considerable number of attributes are
2398 supported by most, if not all targets. Those are described in
2399 the @ref{Common Function Attributes} section.
2401 Function attributes are introduced by the @code{__attribute__} keyword
2402 in the declaration of a function, followed by an attribute specification
2403 enclosed in double parentheses. You can specify multiple attributes in
2404 a declaration by separating them by commas within the double parentheses
2405 or by immediately following one attribute specification with another.
2406 @xref{Attribute Syntax}, for the exact rules on attribute syntax and
2407 placement. Compatible attribute specifications on distinct declarations
2408 of the same function are merged. An attribute specification that is not
2409 compatible with attributes already applied to a declaration of the same
2410 function is ignored with a warning.
2412 Some function attributes take one or more arguments that refer to
2413 the function's parameters by their positions within the function parameter
2414 list. Such attribute arguments are referred to as @dfn{positional arguments}.
2415 Unless specified otherwise, positional arguments that specify properties
2416 of parameters with pointer types can also specify the same properties of
2417 the implicit C++ @code{this} argument in non-static member functions, and
2418 of parameters of reference to a pointer type. For ordinary functions,
2419 position one refers to the first parameter on the list. In C++ non-static
2420 member functions, position one refers to the implicit @code{this} pointer.
2421 The same restrictions and effects apply to function attributes used with
2422 ordinary functions or C++ member functions.
2424 GCC also supports attributes on
2425 variable declarations (@pxref{Variable Attributes}),
2426 labels (@pxref{Label Attributes}),
2427 enumerators (@pxref{Enumerator Attributes}),
2428 statements (@pxref{Statement Attributes}),
2429 and types (@pxref{Type Attributes}).
2431 There is some overlap between the purposes of attributes and pragmas
2432 (@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been
2433 found convenient to use @code{__attribute__} to achieve a natural
2434 attachment of attributes to their corresponding declarations, whereas
2435 @code{#pragma} is of use for compatibility with other compilers
2436 or constructs that do not naturally form part of the grammar.
2438 In addition to the attributes documented here,
2439 GCC plugins may provide their own attributes.
2442 * Common Function Attributes::
2443 * AArch64 Function Attributes::
2444 * AMD GCN Function Attributes::
2445 * ARC Function Attributes::
2446 * ARM Function Attributes::
2447 * AVR Function Attributes::
2448 * Blackfin Function Attributes::
2449 * CR16 Function Attributes::
2450 * C-SKY Function Attributes::
2451 * Epiphany Function Attributes::
2452 * H8/300 Function Attributes::
2453 * IA-64 Function Attributes::
2454 * M32C Function Attributes::
2455 * M32R/D Function Attributes::
2456 * m68k Function Attributes::
2457 * MCORE Function Attributes::
2458 * MeP Function Attributes::
2459 * MicroBlaze Function Attributes::
2460 * Microsoft Windows Function Attributes::
2461 * MIPS Function Attributes::
2462 * MSP430 Function Attributes::
2463 * NDS32 Function Attributes::
2464 * Nios II Function Attributes::
2465 * Nvidia PTX Function Attributes::
2466 * PowerPC Function Attributes::
2467 * RISC-V Function Attributes::
2468 * RL78 Function Attributes::
2469 * RX Function Attributes::
2470 * S/390 Function Attributes::
2471 * SH Function Attributes::
2472 * Symbian OS Function Attributes::
2473 * V850 Function Attributes::
2474 * Visium Function Attributes::
2475 * x86 Function Attributes::
2476 * Xstormy16 Function Attributes::
2479 @node Common Function Attributes
2480 @subsection Common Function Attributes
2482 The following attributes are supported on most targets.
2485 @c Keep this table alphabetized by attribute name. Treat _ as space.
2487 @item alias ("@var{target}")
2488 @cindex @code{alias} function attribute
2489 The @code{alias} attribute causes the declaration to be emitted as an
2490 alias for another symbol, which must be specified. For instance,
2493 void __f () @{ /* @r{Do something.} */; @}
2494 void f () __attribute__ ((weak, alias ("__f")));
2498 defines @samp{f} to be a weak alias for @samp{__f}. In C++, the
2499 mangled name for the target must be used. It is an error if @samp{__f}
2500 is not defined in the same translation unit.
2502 This attribute requires assembler and object file support,
2503 and may not be available on all targets.
2506 @itemx aligned (@var{alignment})
2507 @cindex @code{aligned} function attribute
2508 The @code{aligned} attribute specifies a minimum alignment for
2509 the first instruction of the function, measured in bytes. When specified,
2510 @var{alignment} must be an integer constant power of 2. Specifying no
2511 @var{alignment} argument implies the ideal alignment for the target.
2512 The @code{__alignof__} operator can be used to determine what that is
2513 (@pxref{Alignment}). The attribute has no effect when a definition for
2514 the function is not provided in the same translation unit.
2516 The attribute cannot be used to decrease the alignment of a function
2517 previously declared with a more restrictive alignment; only to increase
2518 it. Attempts to do otherwise are diagnosed. Some targets specify
2519 a minimum default alignment for functions that is greater than 1. On
2520 such targets, specifying a less restrictive alignment is silently ignored.
2521 Using the attribute overrides the effect of the @option{-falign-functions}
2522 (@pxref{Optimize Options}) option for this function.
2524 Note that the effectiveness of @code{aligned} attributes may be
2525 limited by inherent limitations in the system linker
2526 and/or object file format. On some systems, the
2527 linker is only able to arrange for functions to be aligned up to a
2528 certain maximum alignment. (For some linkers, the maximum supported
2529 alignment may be very very small.) See your linker documentation for
2530 further information.
2532 The @code{aligned} attribute can also be used for variables and fields
2533 (@pxref{Variable Attributes}.)
2535 @item alloc_align (@var{position})
2536 @cindex @code{alloc_align} function attribute
2537 The @code{alloc_align} attribute may be applied to a function that
2538 returns a pointer and takes at least one argument of an integer or
2540 It indicates that the returned pointer is aligned on a boundary given
2541 by the function argument at @var{position}. Meaningful alignments are
2542 powers of 2 greater than one. GCC uses this information to improve
2543 pointer alignment analysis.
2545 The function parameter denoting the allocated alignment is specified by
2546 one constant integer argument whose number is the argument of the attribute.
2547 Argument numbering starts at one.
2552 void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1)));
2556 declares that @code{my_memalign} returns memory with minimum alignment
2557 given by parameter 1.
2559 @item alloc_size (@var{position})
2560 @itemx alloc_size (@var{position-1}, @var{position-2})
2561 @cindex @code{alloc_size} function attribute
2562 The @code{alloc_size} attribute may be applied to a function that
2563 returns a pointer and takes at least one argument of an integer or
2565 It indicates that the returned pointer points to memory whose size is
2566 given by the function argument at @var{position-1}, or by the product
2567 of the arguments at @var{position-1} and @var{position-2}. Meaningful
2568 sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this
2569 information to improve the results of @code{__builtin_object_size}.
2571 The function parameter(s) denoting the allocated size are specified by
2572 one or two integer arguments supplied to the attribute. The allocated size
2573 is either the value of the single function argument specified or the product
2574 of the two function arguments specified. Argument numbering starts at
2575 one for ordinary functions, and at two for C++ non-static member functions.
2580 void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2)));
2581 void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2)));
2585 declares that @code{my_calloc} returns memory of the size given by
2586 the product of parameter 1 and 2 and that @code{my_realloc} returns memory
2587 of the size given by parameter 2.
2590 @cindex @code{always_inline} function attribute
2591 Generally, functions are not inlined unless optimization is specified.
2592 For functions declared inline, this attribute inlines the function
2593 independent of any restrictions that otherwise apply to inlining.
2594 Failure to inline such a function is diagnosed as an error.
2595 Note that if such a function is called indirectly the compiler may
2596 or may not inline it depending on optimization level and a failure
2597 to inline an indirect call may or may not be diagnosed.
2600 @cindex @code{artificial} function attribute
2601 This attribute is useful for small inline wrappers that if possible
2602 should appear during debugging as a unit. Depending on the debug
2603 info format it either means marking the function as artificial
2604 or using the caller location for all instructions within the inlined
2607 @item assume_aligned (@var{alignment})
2608 @itemx assume_aligned (@var{alignment}, @var{offset})
2609 @cindex @code{assume_aligned} function attribute
2610 The @code{assume_aligned} attribute may be applied to a function that
2611 returns a pointer. It indicates that the returned pointer is aligned
2612 on a boundary given by @var{alignment}. If the attribute has two
2613 arguments, the second argument is misalignment @var{offset}. Meaningful
2614 values of @var{alignment} are powers of 2 greater than one. Meaningful
2615 values of @var{offset} are greater than zero and less than @var{alignment}.
2620 void* my_alloc1 (size_t) __attribute__((assume_aligned (16)));
2621 void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8)));
2625 declares that @code{my_alloc1} returns 16-byte aligned pointers and
2626 that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
2630 @cindex @code{cold} function attribute
2631 The @code{cold} attribute on functions is used to inform the compiler that
2632 the function is unlikely to be executed. The function is optimized for
2633 size rather than speed and on many targets it is placed into a special
2634 subsection of the text section so all cold functions appear close together,
2635 improving code locality of non-cold parts of program. The paths leading
2636 to calls of cold functions within code are marked as unlikely by the branch
2637 prediction mechanism. It is thus useful to mark functions used to handle
2638 unlikely conditions, such as @code{perror}, as cold to improve optimization
2639 of hot functions that do call marked functions in rare occasions.
2641 When profile feedback is available, via @option{-fprofile-use}, cold functions
2642 are automatically detected and this attribute is ignored.
2645 @cindex @code{const} function attribute
2646 @cindex functions that have no side effects
2647 Calls to functions whose return value is not affected by changes to
2648 the observable state of the program and that have no observable effects
2649 on such state other than to return a value may lend themselves to
2650 optimizations such as common subexpression elimination. Declaring such
2651 functions with the @code{const} attribute allows GCC to avoid emitting
2652 some calls in repeated invocations of the function with the same argument
2658 int square (int) __attribute__ ((const));
2662 tells GCC that subsequent calls to function @code{square} with the same
2663 argument value can be replaced by the result of the first call regardless
2664 of the statements in between.
2666 The @code{const} attribute prohibits a function from reading objects
2667 that affect its return value between successive invocations. However,
2668 functions declared with the attribute can safely read objects that do
2669 not change their return value, such as non-volatile constants.
2671 The @code{const} attribute imposes greater restrictions on a function's
2672 definition than the similar @code{pure} attribute. Declaring the same
2673 function with both the @code{const} and the @code{pure} attribute is
2674 diagnosed. Because a const function cannot have any observable side
2675 effects it does not make sense for it to return @code{void}. Declaring
2676 such a function is diagnosed.
2678 @cindex pointer arguments
2679 Note that a function that has pointer arguments and examines the data
2680 pointed to must @emph{not} be declared @code{const} if the pointed-to
2681 data might change between successive invocations of the function. In
2682 general, since a function cannot distinguish data that might change
2683 from data that cannot, const functions should never take pointer or,
2684 in C++, reference arguments. Likewise, a function that calls a non-const
2685 function usually must not be const itself.
2689 @itemx constructor (@var{priority})
2690 @itemx destructor (@var{priority})
2691 @cindex @code{constructor} function attribute
2692 @cindex @code{destructor} function attribute
2693 The @code{constructor} attribute causes the function to be called
2694 automatically before execution enters @code{main ()}. Similarly, the
2695 @code{destructor} attribute causes the function to be called
2696 automatically after @code{main ()} completes or @code{exit ()} is
2697 called. Functions with these attributes are useful for
2698 initializing data that is used implicitly during the execution of
2701 On some targets the attributes also accept an integer argument to
2702 specify a priority to control the order in which constructor and
2703 destructor functions are run. A constructor
2704 with a smaller priority number runs before a constructor with a larger
2705 priority number; the opposite relationship holds for destructors. So,
2706 if you have a constructor that allocates a resource and a destructor
2707 that deallocates the same resource, both functions typically have the
2708 same priority. The priorities for constructor and destructor
2709 functions are the same as those specified for namespace-scope C++
2710 objects (@pxref{C++ Attributes}). However, at present, the order in which
2711 constructors for C++ objects with static storage duration and functions
2712 decorated with attribute @code{constructor} are invoked is unspecified.
2713 In mixed declarations, attribute @code{init_priority} can be used to
2714 impose a specific ordering.
2716 Using the argument forms of the @code{constructor} and @code{destructor}
2717 attributes on targets where the feature is not supported is rejected with
2721 @itemx copy (@var{function})
2722 @cindex @code{copy} function attribute
2723 The @code{copy} attribute applies the set of attributes with which
2724 @var{function} has been declared to the declaration of the function
2725 to which the attribute is applied. The attribute is designed for
2726 libraries that define aliases or function resolvers that are expected
2727 to specify the same set of attributes as their targets. The @code{copy}
2728 attribute can be used with functions, variables, or types. However,
2729 the kind of symbol to which the attribute is applied (either function
2730 or variable) must match the kind of symbol to which the argument refers.
2731 The @code{copy} attribute copies only syntactic and semantic attributes
2732 but not attributes that affect a symbol's linkage or visibility such as
2733 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
2734 and @code{target_clones} attribute are also not copied.
2735 @xref{Common Type Attributes}.
2736 @xref{Common Variable Attributes}.
2738 For example, the @var{StrongAlias} macro below makes use of the @code{alias}
2739 and @code{copy} attributes to define an alias named @var{alloc} for function
2740 @var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and
2741 @var{nothrow}. Thanks to the @code{__typeof__} operator the alias has
2742 the same type as the target function. As a result of the @code{copy}
2743 attribute the alias also shares the same attributes as the target.
2746 #define StrongAlias(TagetFunc, AliasDecl) \
2747 extern __typeof__ (TargetFunc) AliasDecl \
2748 __attribute__ ((alias (#TargetFunc), copy (TargetFunc)));
2750 extern __attribute__ ((alloc_size (1), malloc, nothrow))
2751 void* allocate (size_t);
2752 StrongAlias (allocate, alloc);
2756 @itemx deprecated (@var{msg})
2757 @cindex @code{deprecated} function attribute
2758 The @code{deprecated} attribute results in a warning if the function
2759 is used anywhere in the source file. This is useful when identifying
2760 functions that are expected to be removed in a future version of a
2761 program. The warning also includes the location of the declaration
2762 of the deprecated function, to enable users to easily find further
2763 information about why the function is deprecated, or what they should
2764 do instead. Note that the warnings only occurs for uses:
2767 int old_fn () __attribute__ ((deprecated));
2769 int (*fn_ptr)() = old_fn;
2773 results in a warning on line 3 but not line 2. The optional @var{msg}
2774 argument, which must be a string, is printed in the warning if
2777 The @code{deprecated} attribute can also be used for variables and
2778 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
2780 The message attached to the attribute is affected by the setting of
2781 the @option{-fmessage-length} option.
2783 @item error ("@var{message}")
2784 @itemx warning ("@var{message}")
2785 @cindex @code{error} function attribute
2786 @cindex @code{warning} function attribute
2787 If the @code{error} or @code{warning} attribute
2788 is used on a function declaration and a call to such a function
2789 is not eliminated through dead code elimination or other optimizations,
2790 an error or warning (respectively) that includes @var{message} is diagnosed.
2792 for compile-time checking, especially together with @code{__builtin_constant_p}
2793 and inline functions where checking the inline function arguments is not
2794 possible through @code{extern char [(condition) ? 1 : -1];} tricks.
2796 While it is possible to leave the function undefined and thus invoke
2797 a link failure (to define the function with
2798 a message in @code{.gnu.warning*} section),
2799 when using these attributes the problem is diagnosed
2800 earlier and with exact location of the call even in presence of inline
2801 functions or when not emitting debugging information.
2803 @item externally_visible
2804 @cindex @code{externally_visible} function attribute
2805 This attribute, attached to a global variable or function, nullifies
2806 the effect of the @option{-fwhole-program} command-line option, so the
2807 object remains visible outside the current compilation unit.
2809 If @option{-fwhole-program} is used together with @option{-flto} and
2810 @command{gold} is used as the linker plugin,
2811 @code{externally_visible} attributes are automatically added to functions
2812 (not variable yet due to a current @command{gold} issue)
2813 that are accessed outside of LTO objects according to resolution file
2814 produced by @command{gold}.
2815 For other linkers that cannot generate resolution file,
2816 explicit @code{externally_visible} attributes are still necessary.
2819 @cindex @code{flatten} function attribute
2820 Generally, inlining into a function is limited. For a function marked with
2821 this attribute, every call inside this function is inlined, if possible.
2822 Functions declared with attribute @code{noinline} and similar are not
2823 inlined. Whether the function itself is considered for inlining depends
2824 on its size and the current inlining parameters.
2826 @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
2827 @cindex @code{format} function attribute
2828 @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
2830 The @code{format} attribute specifies that a function takes @code{printf},
2831 @code{scanf}, @code{strftime} or @code{strfmon} style arguments that
2832 should be type-checked against a format string. For example, the
2837 my_printf (void *my_object, const char *my_format, ...)
2838 __attribute__ ((format (printf, 2, 3)));
2842 causes the compiler to check the arguments in calls to @code{my_printf}
2843 for consistency with the @code{printf} style format string argument
2846 The parameter @var{archetype} determines how the format string is
2847 interpreted, and should be @code{printf}, @code{scanf}, @code{strftime},
2848 @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or
2849 @code{strfmon}. (You can also use @code{__printf__},
2850 @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On
2851 MinGW targets, @code{ms_printf}, @code{ms_scanf}, and
2852 @code{ms_strftime} are also present.
2853 @var{archetype} values such as @code{printf} refer to the formats accepted
2854 by the system's C runtime library,
2855 while values prefixed with @samp{gnu_} always refer
2856 to the formats accepted by the GNU C Library. On Microsoft Windows
2857 targets, values prefixed with @samp{ms_} refer to the formats accepted by the
2858 @file{msvcrt.dll} library.
2859 The parameter @var{string-index}
2860 specifies which argument is the format string argument (starting
2861 from 1), while @var{first-to-check} is the number of the first
2862 argument to check against the format string. For functions
2863 where the arguments are not available to be checked (such as
2864 @code{vprintf}), specify the third parameter as zero. In this case the
2865 compiler only checks the format string for consistency. For
2866 @code{strftime} formats, the third parameter is required to be zero.
2867 Since non-static C++ methods have an implicit @code{this} argument, the
2868 arguments of such methods should be counted from two, not one, when
2869 giving values for @var{string-index} and @var{first-to-check}.
2871 In the example above, the format string (@code{my_format}) is the second
2872 argument of the function @code{my_print}, and the arguments to check
2873 start with the third argument, so the correct parameters for the format
2874 attribute are 2 and 3.
2876 @opindex ffreestanding
2877 @opindex fno-builtin
2878 The @code{format} attribute allows you to identify your own functions
2879 that take format strings as arguments, so that GCC can check the
2880 calls to these functions for errors. The compiler always (unless
2881 @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
2882 for the standard library functions @code{printf}, @code{fprintf},
2883 @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
2884 @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
2885 warnings are requested (using @option{-Wformat}), so there is no need to
2886 modify the header file @file{stdio.h}. In C99 mode, the functions
2887 @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
2888 @code{vsscanf} are also checked. Except in strictly conforming C
2889 standard modes, the X/Open function @code{strfmon} is also checked as
2890 are @code{printf_unlocked} and @code{fprintf_unlocked}.
2891 @xref{C Dialect Options,,Options Controlling C Dialect}.
2893 For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is
2894 recognized in the same context. Declarations including these format attributes
2895 are parsed for correct syntax, however the result of checking of such format
2896 strings is not yet defined, and is not carried out by this version of the
2899 The target may also provide additional types of format checks.
2900 @xref{Target Format Checks,,Format Checks Specific to Particular
2903 @item format_arg (@var{string-index})
2904 @cindex @code{format_arg} function attribute
2905 @opindex Wformat-nonliteral
2906 The @code{format_arg} attribute specifies that a function takes one or
2907 more format strings for a @code{printf}, @code{scanf}, @code{strftime} or
2908 @code{strfmon} style function and modifies it (for example, to translate
2909 it into another language), so the result can be passed to a
2910 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
2911 function (with the remaining arguments to the format function the same
2912 as they would have been for the unmodified string). Multiple
2913 @code{format_arg} attributes may be applied to the same function, each
2914 designating a distinct parameter as a format string. For example, the
2919 my_dgettext (char *my_domain, const char *my_format)
2920 __attribute__ ((format_arg (2)));
2924 causes the compiler to check the arguments in calls to a @code{printf},
2925 @code{scanf}, @code{strftime} or @code{strfmon} type function, whose
2926 format string argument is a call to the @code{my_dgettext} function, for
2927 consistency with the format string argument @code{my_format}. If the
2928 @code{format_arg} attribute had not been specified, all the compiler
2929 could tell in such calls to format functions would be that the format
2930 string argument is not constant; this would generate a warning when
2931 @option{-Wformat-nonliteral} is used, but the calls could not be checked
2932 without the attribute.
2934 In calls to a function declared with more than one @code{format_arg}
2935 attribute, each with a distinct argument value, the corresponding
2936 actual function arguments are checked against all format strings
2937 designated by the attributes. This capability is designed to support
2938 the GNU @code{ngettext} family of functions.
2940 The parameter @var{string-index} specifies which argument is the format
2941 string argument (starting from one). Since non-static C++ methods have
2942 an implicit @code{this} argument, the arguments of such methods should
2943 be counted from two.
2945 The @code{format_arg} attribute allows you to identify your own
2946 functions that modify format strings, so that GCC can check the
2947 calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
2948 type function whose operands are a call to one of your own function.
2949 The compiler always treats @code{gettext}, @code{dgettext}, and
2950 @code{dcgettext} in this manner except when strict ISO C support is
2951 requested by @option{-ansi} or an appropriate @option{-std} option, or
2952 @option{-ffreestanding} or @option{-fno-builtin}
2953 is used. @xref{C Dialect Options,,Options
2954 Controlling C Dialect}.
2956 For Objective-C dialects, the @code{format-arg} attribute may refer to an
2957 @code{NSString} reference for compatibility with the @code{format} attribute
2960 The target may also allow additional types in @code{format-arg} attributes.
2961 @xref{Target Format Checks,,Format Checks Specific to Particular
2965 @cindex @code{gnu_inline} function attribute
2966 This attribute should be used with a function that is also declared
2967 with the @code{inline} keyword. It directs GCC to treat the function
2968 as if it were defined in gnu90 mode even when compiling in C99 or
2971 If the function is declared @code{extern}, then this definition of the
2972 function is used only for inlining. In no case is the function
2973 compiled as a standalone function, not even if you take its address
2974 explicitly. Such an address becomes an external reference, as if you
2975 had only declared the function, and had not defined it. This has
2976 almost the effect of a macro. The way to use this is to put a
2977 function definition in a header file with this attribute, and put
2978 another copy of the function, without @code{extern}, in a library
2979 file. The definition in the header file causes most calls to the
2980 function to be inlined. If any uses of the function remain, they
2981 refer to the single copy in the library. Note that the two
2982 definitions of the functions need not be precisely the same, although
2983 if they do not have the same effect your program may behave oddly.
2985 In C, if the function is neither @code{extern} nor @code{static}, then
2986 the function is compiled as a standalone function, as well as being
2987 inlined where possible.
2989 This is how GCC traditionally handled functions declared
2990 @code{inline}. Since ISO C99 specifies a different semantics for
2991 @code{inline}, this function attribute is provided as a transition
2992 measure and as a useful feature in its own right. This attribute is
2993 available in GCC 4.1.3 and later. It is available if either of the
2994 preprocessor macros @code{__GNUC_GNU_INLINE__} or
2995 @code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
2996 Function is As Fast As a Macro}.
2998 In C++, this attribute does not depend on @code{extern} in any way,
2999 but it still requires the @code{inline} keyword to enable its special
3003 @cindex @code{hot} function attribute
3004 The @code{hot} attribute on a function is used to inform the compiler that
3005 the function is a hot spot of the compiled program. The function is
3006 optimized more aggressively and on many targets it is placed into a special
3007 subsection of the text section so all hot functions appear close together,
3010 When profile feedback is available, via @option{-fprofile-use}, hot functions
3011 are automatically detected and this attribute is ignored.
3013 @item ifunc ("@var{resolver}")
3014 @cindex @code{ifunc} function attribute
3015 @cindex indirect functions
3016 @cindex functions that are dynamically resolved
3017 The @code{ifunc} attribute is used to mark a function as an indirect
3018 function using the STT_GNU_IFUNC symbol type extension to the ELF
3019 standard. This allows the resolution of the symbol value to be
3020 determined dynamically at load time, and an optimized version of the
3021 routine to be selected for the particular processor or other system
3022 characteristics determined then. To use this attribute, first define
3023 the implementation functions available, and a resolver function that
3024 returns a pointer to the selected implementation function. The
3025 implementation functions' declarations must match the API of the
3026 function being implemented. The resolver should be declared to
3027 be a function taking no arguments and returning a pointer to
3028 a function of the same type as the implementation. For example:
3031 void *my_memcpy (void *dst, const void *src, size_t len)
3037 static void * (*resolve_memcpy (void))(void *, const void *, size_t)
3039 return my_memcpy; // we will just always select this routine
3044 The exported header file declaring the function the user calls would
3048 extern void *memcpy (void *, const void *, size_t);
3052 allowing the user to call @code{memcpy} as a regular function, unaware of
3053 the actual implementation. Finally, the indirect function needs to be
3054 defined in the same translation unit as the resolver function:
3057 void *memcpy (void *, const void *, size_t)
3058 __attribute__ ((ifunc ("resolve_memcpy")));
3061 In C++, the @code{ifunc} attribute takes a string that is the mangled name
3062 of the resolver function. A C++ resolver for a non-static member function
3063 of class @code{C} should be declared to return a pointer to a non-member
3064 function taking pointer to @code{C} as the first argument, followed by
3065 the same arguments as of the implementation function. G++ checks
3066 the signatures of the two functions and issues
3067 a @option{-Wattribute-alias} warning for mismatches. To suppress a warning
3068 for the necessary cast from a pointer to the implementation member function
3069 to the type of the corresponding non-member function use
3070 the @option{-Wno-pmf-conversions} option. For example:
3076 int debug_impl (int);
3077 int optimized_impl (int);
3079 typedef int Func (S*, int);
3081 static Func* resolver ();
3084 int interface (int);
3087 int S::debug_impl (int) @{ /* @r{@dots{}} */ @}
3088 int S::optimized_impl (int) @{ /* @r{@dots{}} */ @}
3090 S::Func* S::resolver ()
3092 int (S::*pimpl) (int)
3093 = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl;
3095 // Cast triggers -Wno-pmf-conversions.
3096 return reinterpret_cast<Func*>(pimpl);
3099 int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv")));
3102 Indirect functions cannot be weak. Binutils version 2.20.1 or higher
3103 and GNU C Library version 2.11.1 are required to use this feature.
3106 @itemx interrupt_handler
3107 Many GCC back ends support attributes to indicate that a function is
3108 an interrupt handler, which tells the compiler to generate function
3109 entry and exit sequences that differ from those from regular
3110 functions. The exact syntax and behavior are target-specific;
3111 refer to the following subsections for details.
3114 @cindex @code{leaf} function attribute
3115 Calls to external functions with this attribute must return to the
3116 current compilation unit only by return or by exception handling. In
3117 particular, a leaf function is not allowed to invoke callback functions
3118 passed to it from the current compilation unit, directly call functions
3119 exported by the unit, or @code{longjmp} into the unit. Leaf functions
3120 might still call functions from other compilation units and thus they
3121 are not necessarily leaf in the sense that they contain no function
3124 The attribute is intended for library functions to improve dataflow
3125 analysis. The compiler takes the hint that any data not escaping the
3126 current compilation unit cannot be used or modified by the leaf
3127 function. For example, the @code{sin} function is a leaf function, but
3128 @code{qsort} is not.
3130 Note that leaf functions might indirectly run a signal handler defined
3131 in the current compilation unit that uses static variables. Similarly,
3132 when lazy symbol resolution is in effect, leaf functions might invoke
3133 indirect functions whose resolver function or implementation function is
3134 defined in the current compilation unit and uses static variables. There
3135 is no standard-compliant way to write such a signal handler, resolver
3136 function, or implementation function, and the best that you can do is to
3137 remove the @code{leaf} attribute or mark all such static variables
3138 @code{volatile}. Lastly, for ELF-based systems that support symbol
3139 interposition, care should be taken that functions defined in the
3140 current compilation unit do not unexpectedly interpose other symbols
3141 based on the defined standards mode and defined feature test macros;
3142 otherwise an inadvertent callback would be added.
3144 The attribute has no effect on functions defined within the current
3145 compilation unit. This is to allow easy merging of multiple compilation
3146 units into one, for example, by using the link-time optimization. For
3147 this reason the attribute is not allowed on types to annotate indirect
3151 @cindex @code{malloc} function attribute
3152 @cindex functions that behave like malloc
3153 This tells the compiler that a function is @code{malloc}-like, i.e.,
3154 that the pointer @var{P} returned by the function cannot alias any
3155 other pointer valid when the function returns, and moreover no
3156 pointers to valid objects occur in any storage addressed by @var{P}.
3158 Using this attribute can improve optimization. Compiler predicts
3159 that a function with the attribute returns non-null in most cases.
3161 @code{malloc} and @code{calloc} have this property because they return
3162 a pointer to uninitialized or zeroed-out storage. However, functions
3163 like @code{realloc} do not have this property, as they can return a
3164 pointer to storage containing pointers.
3167 @cindex @code{no_icf} function attribute
3168 This function attribute prevents a functions from being merged with another
3169 semantically equivalent function.
3171 @item no_instrument_function
3172 @cindex @code{no_instrument_function} function attribute
3173 @opindex finstrument-functions
3176 If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are
3177 given, profiling function calls are
3178 generated at entry and exit of most user-compiled functions.
3179 Functions with this attribute are not so instrumented.
3181 @item no_profile_instrument_function
3182 @cindex @code{no_profile_instrument_function} function attribute
3183 The @code{no_profile_instrument_function} attribute on functions is used
3184 to inform the compiler that it should not process any profile feedback based
3185 optimization code instrumentation.
3188 @cindex @code{no_reorder} function attribute
3189 Do not reorder functions or variables marked @code{no_reorder}
3190 against each other or top level assembler statements the executable.
3191 The actual order in the program will depend on the linker command
3192 line. Static variables marked like this are also not removed.
3193 This has a similar effect
3194 as the @option{-fno-toplevel-reorder} option, but only applies to the
3197 @item no_sanitize ("@var{sanitize_option}")
3198 @cindex @code{no_sanitize} function attribute
3199 The @code{no_sanitize} attribute on functions is used
3200 to inform the compiler that it should not do sanitization of any option
3201 mentioned in @var{sanitize_option}. A list of values acceptable by
3202 the @option{-fsanitize} option can be provided.
3205 void __attribute__ ((no_sanitize ("alignment", "object-size")))
3206 f () @{ /* @r{Do something.} */; @}
3207 void __attribute__ ((no_sanitize ("alignment,object-size")))
3208 g () @{ /* @r{Do something.} */; @}
3211 @item no_sanitize_address
3212 @itemx no_address_safety_analysis
3213 @cindex @code{no_sanitize_address} function attribute
3214 The @code{no_sanitize_address} attribute on functions is used
3215 to inform the compiler that it should not instrument memory accesses
3216 in the function when compiling with the @option{-fsanitize=address} option.
3217 The @code{no_address_safety_analysis} is a deprecated alias of the
3218 @code{no_sanitize_address} attribute, new code should use
3219 @code{no_sanitize_address}.
3221 @item no_sanitize_thread
3222 @cindex @code{no_sanitize_thread} function attribute
3223 The @code{no_sanitize_thread} attribute on functions is used
3224 to inform the compiler that it should not instrument memory accesses
3225 in the function when compiling with the @option{-fsanitize=thread} option.
3227 @item no_sanitize_undefined
3228 @cindex @code{no_sanitize_undefined} function attribute
3229 The @code{no_sanitize_undefined} attribute on functions is used
3230 to inform the compiler that it should not check for undefined behavior
3231 in the function when compiling with the @option{-fsanitize=undefined} option.
3233 @item no_split_stack
3234 @cindex @code{no_split_stack} function attribute
3235 @opindex fsplit-stack
3236 If @option{-fsplit-stack} is given, functions have a small
3237 prologue which decides whether to split the stack. Functions with the
3238 @code{no_split_stack} attribute do not have that prologue, and thus
3239 may run with only a small amount of stack space available.
3241 @item no_stack_limit
3242 @cindex @code{no_stack_limit} function attribute
3243 This attribute locally overrides the @option{-fstack-limit-register}
3244 and @option{-fstack-limit-symbol} command-line options; it has the effect
3245 of disabling stack limit checking in the function it applies to.
3248 @cindex @code{noclone} function attribute
3249 This function attribute prevents a function from being considered for
3250 cloning---a mechanism that produces specialized copies of functions
3251 and which is (currently) performed by interprocedural constant
3255 @cindex @code{noinline} function attribute
3256 This function attribute prevents a function from being considered for
3258 @c Don't enumerate the optimizations by name here; we try to be
3259 @c future-compatible with this mechanism.
3260 If the function does not have side effects, there are optimizations
3261 other than inlining that cause function calls to be optimized away,
3262 although the function call is live. To keep such calls from being
3269 (@pxref{Extended Asm}) in the called function, to serve as a special
3273 @cindex @code{noipa} function attribute
3274 Disable interprocedural optimizations between the function with this
3275 attribute and its callers, as if the body of the function is not available
3276 when optimizing callers and the callers are unavailable when optimizing
3277 the body. This attribute implies @code{noinline}, @code{noclone} and
3278 @code{no_icf} attributes. However, this attribute is not equivalent
3279 to a combination of other attributes, because its purpose is to suppress
3280 existing and future optimizations employing interprocedural analysis,
3281 including those that do not have an attribute suitable for disabling
3282 them individually. This attribute is supported mainly for the purpose
3283 of testing the compiler.
3286 @itemx nonnull (@var{arg-index}, @dots{})
3287 @cindex @code{nonnull} function attribute
3288 @cindex functions with non-null pointer arguments
3289 The @code{nonnull} attribute may be applied to a function that takes at
3290 least one argument of a pointer type. It indicates that the referenced
3291 arguments must be non-null pointers. For instance, the declaration:
3295 my_memcpy (void *dest, const void *src, size_t len)
3296 __attribute__((nonnull (1, 2)));
3300 causes the compiler to check that, in calls to @code{my_memcpy},
3301 arguments @var{dest} and @var{src} are non-null. If the compiler
3302 determines that a null pointer is passed in an argument slot marked
3303 as non-null, and the @option{-Wnonnull} option is enabled, a warning
3304 is issued. @xref{Warning Options}. Unless disabled by
3305 the @option{-fno-delete-null-pointer-checks} option the compiler may
3306 also perform optimizations based on the knowledge that certain function
3307 arguments cannot be null. In addition,
3308 the @option{-fisolate-erroneous-paths-attribute} option can be specified
3309 to have GCC transform calls with null arguments to non-null functions
3310 into traps. @xref{Optimize Options}.
3312 If no @var{arg-index} is given to the @code{nonnull} attribute,
3313 all pointer arguments are marked as non-null. To illustrate, the
3314 following declaration is equivalent to the previous example:
3318 my_memcpy (void *dest, const void *src, size_t len)
3319 __attribute__((nonnull));
3323 @cindex @code{noplt} function attribute
3324 The @code{noplt} attribute is the counterpart to option @option{-fno-plt}.
3325 Calls to functions marked with this attribute in position-independent code
3330 /* Externally defined function foo. */
3331 int foo () __attribute__ ((noplt));
3334 main (/* @r{@dots{}} */)
3343 The @code{noplt} attribute on function @code{foo}
3344 tells the compiler to assume that
3345 the function @code{foo} is externally defined and that the call to
3346 @code{foo} must avoid the PLT
3347 in position-independent code.
3349 In position-dependent code, a few targets also convert calls to
3350 functions that are marked to not use the PLT to use the GOT instead.
3353 @cindex @code{noreturn} function attribute
3354 @cindex functions that never return
3355 A few standard library functions, such as @code{abort} and @code{exit},
3356 cannot return. GCC knows this automatically. Some programs define
3357 their own functions that never return. You can declare them
3358 @code{noreturn} to tell the compiler this fact. For example,
3362 void fatal () __attribute__ ((noreturn));
3365 fatal (/* @r{@dots{}} */)
3367 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
3373 The @code{noreturn} keyword tells the compiler to assume that
3374 @code{fatal} cannot return. It can then optimize without regard to what
3375 would happen if @code{fatal} ever did return. This makes slightly
3376 better code. More importantly, it helps avoid spurious warnings of
3377 uninitialized variables.
3379 The @code{noreturn} keyword does not affect the exceptional path when that
3380 applies: a @code{noreturn}-marked function may still return to the caller
3381 by throwing an exception or calling @code{longjmp}.
3383 In order to preserve backtraces, GCC will never turn calls to
3384 @code{noreturn} functions into tail calls.
3386 Do not assume that registers saved by the calling function are
3387 restored before calling the @code{noreturn} function.
3389 It does not make sense for a @code{noreturn} function to have a return
3390 type other than @code{void}.
3393 @cindex @code{nothrow} function attribute
3394 The @code{nothrow} attribute is used to inform the compiler that a
3395 function cannot throw an exception. For example, most functions in
3396 the standard C library can be guaranteed not to throw an exception
3397 with the notable exceptions of @code{qsort} and @code{bsearch} that
3398 take function pointer arguments.
3400 @item optimize (@var{level}, @dots{})
3401 @item optimize (@var{string}, @dots{})
3402 @cindex @code{optimize} function attribute
3403 The @code{optimize} attribute is used to specify that a function is to
3404 be compiled with different optimization options than specified on the
3405 command line. Valid arguments are constant non-negative integers and
3406 strings. Each numeric argument specifies an optimization @var{level}.
3407 Each @var{string} argument consists of one or more comma-separated
3408 substrings. Each substring that begins with the letter @code{O} refers
3409 to an optimization option such as @option{-O0} or @option{-Os}. Other
3410 substrings are taken as suffixes to the @code{-f} prefix jointly
3411 forming the name of an optimization option. @xref{Optimize Options}.
3413 @samp{#pragma GCC optimize} can be used to set optimization options
3414 for more than one function. @xref{Function Specific Option Pragmas},
3415 for details about the pragma.
3417 Providing multiple strings as arguments separated by commas to specify
3418 multiple options is equivalent to separating the option suffixes with
3419 a comma (@samp{,}) within a single string. Spaces are not permitted
3422 Not every optimization option that starts with the @var{-f} prefix
3423 specified by the attribute necessarily has an effect on the function.
3424 The @code{optimize} attribute should be used for debugging purposes only.
3425 It is not suitable in production code.
3427 @item patchable_function_entry
3428 @cindex @code{patchable_function_entry} function attribute
3429 @cindex extra NOP instructions at the function entry point
3430 In case the target's text segment can be made writable at run time by
3431 any means, padding the function entry with a number of NOPs can be
3432 used to provide a universal tool for instrumentation.
3434 The @code{patchable_function_entry} function attribute can be used to
3435 change the number of NOPs to any desired value. The two-value syntax
3436 is the same as for the command-line switch
3437 @option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with
3438 the function entry point before the @var{M}th NOP instruction.
3439 @var{M} defaults to 0 if omitted e.g.@: function entry point is before
3442 If patchable function entries are enabled globally using the command-line
3443 option @option{-fpatchable-function-entry=N,M}, then you must disable
3444 instrumentation on all functions that are part of the instrumentation
3445 framework with the attribute @code{patchable_function_entry (0)}
3446 to prevent recursion.
3449 @cindex @code{pure} function attribute
3450 @cindex functions that have no side effects
3452 Calls to functions that have no observable effects on the state of
3453 the program other than to return a value may lend themselves to optimizations
3454 such as common subexpression elimination. Declaring such functions with
3455 the @code{pure} attribute allows GCC to avoid emitting some calls in repeated
3456 invocations of the function with the same argument values.
3458 The @code{pure} attribute prohibits a function from modifying the state
3459 of the program that is observable by means other than inspecting
3460 the function's return value. However, functions declared with the @code{pure}
3461 attribute can safely read any non-volatile objects, and modify the value of
3462 objects in a way that does not affect their return value or the observable
3463 state of the program.
3468 int hash (char *) __attribute__ ((pure));
3472 tells GCC that subsequent calls to the function @code{hash} with the same
3473 string can be replaced by the result of the first call provided the state
3474 of the program observable by @code{hash}, including the contents of the array
3475 itself, does not change in between. Even though @code{hash} takes a non-const
3476 pointer argument it must not modify the array it points to, or any other object
3477 whose value the rest of the program may depend on. However, the caller may
3478 safely change the contents of the array between successive calls to
3479 the function (doing so disables the optimization). The restriction also
3480 applies to member objects referenced by the @code{this} pointer in C++
3481 non-static member functions.
3483 Some common examples of pure functions are @code{strlen} or @code{memcmp}.
3484 Interesting non-pure functions are functions with infinite loops or those
3485 depending on volatile memory or other system resource, that may change between
3486 consecutive calls (such as the standard C @code{feof} function in
3487 a multithreading environment).
3489 The @code{pure} attribute imposes similar but looser restrictions on
3490 a function's definition than the @code{const} attribute: @code{pure}
3491 allows the function to read any non-volatile memory, even if it changes
3492 in between successive invocations of the function. Declaring the same
3493 function with both the @code{pure} and the @code{const} attribute is
3494 diagnosed. Because a pure function cannot have any observable side
3495 effects it does not make sense for such a function to return @code{void}.
3496 Declaring such a function is diagnosed.
3498 @item returns_nonnull
3499 @cindex @code{returns_nonnull} function attribute
3500 The @code{returns_nonnull} attribute specifies that the function
3501 return value should be a non-null pointer. For instance, the declaration:
3505 mymalloc (size_t len) __attribute__((returns_nonnull));
3509 lets the compiler optimize callers based on the knowledge
3510 that the return value will never be null.
3513 @cindex @code{returns_twice} function attribute
3514 @cindex functions that return more than once
3515 The @code{returns_twice} attribute tells the compiler that a function may
3516 return more than one time. The compiler ensures that all registers
3517 are dead before calling such a function and emits a warning about
3518 the variables that may be clobbered after the second return from the
3519 function. Examples of such functions are @code{setjmp} and @code{vfork}.
3520 The @code{longjmp}-like counterpart of such function, if any, might need
3521 to be marked with the @code{noreturn} attribute.
3523 @item section ("@var{section-name}")
3524 @cindex @code{section} function attribute
3525 @cindex functions in arbitrary sections
3526 Normally, the compiler places the code it generates in the @code{text} section.
3527 Sometimes, however, you need additional sections, or you need certain
3528 particular functions to appear in special sections. The @code{section}
3529 attribute specifies that a function lives in a particular section.
3530 For example, the declaration:
3533 extern void foobar (void) __attribute__ ((section ("bar")));
3537 puts the function @code{foobar} in the @code{bar} section.
3539 Some file formats do not support arbitrary sections so the @code{section}
3540 attribute is not available on all platforms.
3541 If you need to map the entire contents of a module to a particular
3542 section, consider using the facilities of the linker instead.
3545 @itemx sentinel (@var{position})
3546 @cindex @code{sentinel} function attribute
3547 This function attribute indicates that an argument in a call to the function
3548 is expected to be an explicit @code{NULL}. The attribute is only valid on
3549 variadic functions. By default, the sentinel is expected to be the last
3550 argument of the function call. If the optional @var{position} argument
3551 is specified to the attribute, the sentinel must be located at
3552 @var{position} counting backwards from the end of the argument list.
3555 __attribute__ ((sentinel))
3557 __attribute__ ((sentinel(0)))
3560 The attribute is automatically set with a position of 0 for the built-in
3561 functions @code{execl} and @code{execlp}. The built-in function
3562 @code{execle} has the attribute set with a position of 1.
3564 A valid @code{NULL} in this context is defined as zero with any object
3565 pointer type. If your system defines the @code{NULL} macro with
3566 an integer type then you need to add an explicit cast. During
3567 installation GCC replaces the system @code{<stddef.h>} header with
3568 a copy that redefines NULL appropriately.
3570 The warnings for missing or incorrect sentinels are enabled with
3574 @itemx simd("@var{mask}")
3575 @cindex @code{simd} function attribute
3576 This attribute enables creation of one or more function versions that
3577 can process multiple arguments using SIMD instructions from a
3578 single invocation. Specifying this attribute allows compiler to
3579 assume that such versions are available at link time (provided
3580 in the same or another translation unit). Generated versions are
3581 target-dependent and described in the corresponding Vector ABI document. For
3582 x86_64 target this document can be found
3583 @w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}.
3585 The optional argument @var{mask} may have the value
3586 @code{notinbranch} or @code{inbranch},
3587 and instructs the compiler to generate non-masked or masked
3588 clones correspondingly. By default, all clones are generated.
3590 If the attribute is specified and @code{#pragma omp declare simd} is
3591 present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd}
3592 switch is specified, then the attribute is ignored.
3595 @cindex @code{stack_protect} function attribute
3596 This attribute adds stack protection code to the function if
3597 flags @option{-fstack-protector}, @option{-fstack-protector-strong}
3598 or @option{-fstack-protector-explicit} are set.
3600 @item target (@var{string}, @dots{})
3601 @cindex @code{target} function attribute
3602 Multiple target back ends implement the @code{target} attribute
3603 to specify that a function is to
3604 be compiled with different target options than specified on the
3605 command line. One or more strings can be provided as arguments.
3606 Each string consists of one or more comma-separated suffixes to
3607 the @code{-m} prefix jointly forming the name of a machine-dependent
3608 option. @xref{Submodel Options,,Machine-Dependent Options}.
3610 The @code{target} attribute can be used for instance to have a function
3611 compiled with a different ISA (instruction set architecture) than the
3612 default. @samp{#pragma GCC target} can be used to specify target-specific
3613 options for more than one function. @xref{Function Specific Option Pragmas},
3614 for details about the pragma.
3616 For instance, on an x86, you could declare one function with the
3617 @code{target("sse4.1,arch=core2")} attribute and another with
3618 @code{target("sse4a,arch=amdfam10")}. This is equivalent to
3619 compiling the first function with @option{-msse4.1} and
3620 @option{-march=core2} options, and the second function with
3621 @option{-msse4a} and @option{-march=amdfam10} options. It is up to you
3622 to make sure that a function is only invoked on a machine that
3623 supports the particular ISA it is compiled for (for example by using
3624 @code{cpuid} on x86 to determine what feature bits and architecture
3628 int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
3629 int sse3_func (void) __attribute__ ((__target__ ("sse3")));
3632 Providing multiple strings as arguments separated by commas to specify
3633 multiple options is equivalent to separating the option suffixes with
3634 a comma (@samp{,}) within a single string. Spaces are not permitted
3637 The options supported are specific to each target; refer to @ref{x86
3638 Function Attributes}, @ref{PowerPC Function Attributes},
3639 @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
3640 @ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
3643 @item target_clones (@var{options})
3644 @cindex @code{target_clones} function attribute
3645 The @code{target_clones} attribute is used to specify that a function
3646 be cloned into multiple versions compiled with different target options
3647 than specified on the command line. The supported options and restrictions
3648 are the same as for @code{target} attribute.
3650 For instance, on an x86, you could compile a function with
3651 @code{target_clones("sse4.1,avx")}. GCC creates two function clones,
3652 one compiled with @option{-msse4.1} and another with @option{-mavx}.
3654 On a PowerPC, you can compile a function with
3655 @code{target_clones("cpu=power9,default")}. GCC will create two
3656 function clones, one compiled with @option{-mcpu=power9} and another
3657 with the default options. GCC must be configured to use GLIBC 2.23 or
3658 newer in order to use the @code{target_clones} attribute.
3660 It also creates a resolver function (see
3661 the @code{ifunc} attribute above) that dynamically selects a clone
3662 suitable for current architecture. The resolver is created only if there
3663 is a usage of a function with @code{target_clones} attribute.
3666 @cindex @code{unused} function attribute
3667 This attribute, attached to a function, means that the function is meant
3668 to be possibly unused. GCC does not produce a warning for this
3672 @cindex @code{used} function attribute
3673 This attribute, attached to a function, means that code must be emitted
3674 for the function even if it appears that the function is not referenced.
3675 This is useful, for example, when the function is referenced only in
3678 When applied to a member function of a C++ class template, the
3679 attribute also means that the function is instantiated if the
3680 class itself is instantiated.
3682 @item visibility ("@var{visibility_type}")
3683 @cindex @code{visibility} function attribute
3684 This attribute affects the linkage of the declaration to which it is attached.
3685 It can be applied to variables (@pxref{Common Variable Attributes}) and types
3686 (@pxref{Common Type Attributes}) as well as functions.
3688 There are four supported @var{visibility_type} values: default,
3689 hidden, protected or internal visibility.
3692 void __attribute__ ((visibility ("protected")))
3693 f () @{ /* @r{Do something.} */; @}
3694 int i __attribute__ ((visibility ("hidden")));
3697 The possible values of @var{visibility_type} correspond to the
3698 visibility settings in the ELF gABI.
3701 @c keep this list of visibilities in alphabetical order.
3704 Default visibility is the normal case for the object file format.
3705 This value is available for the visibility attribute to override other
3706 options that may change the assumed visibility of entities.
3708 On ELF, default visibility means that the declaration is visible to other
3709 modules and, in shared libraries, means that the declared entity may be
3712 On Darwin, default visibility means that the declaration is visible to
3715 Default visibility corresponds to ``external linkage'' in the language.
3718 Hidden visibility indicates that the entity declared has a new
3719 form of linkage, which we call ``hidden linkage''. Two
3720 declarations of an object with hidden linkage refer to the same object
3721 if they are in the same shared object.
3724 Internal visibility is like hidden visibility, but with additional
3725 processor specific semantics. Unless otherwise specified by the
3726 psABI, GCC defines internal visibility to mean that a function is
3727 @emph{never} called from another module. Compare this with hidden
3728 functions which, while they cannot be referenced directly by other
3729 modules, can be referenced indirectly via function pointers. By
3730 indicating that a function cannot be called from outside the module,
3731 GCC may for instance omit the load of a PIC register since it is known
3732 that the calling function loaded the correct value.
3735 Protected visibility is like default visibility except that it
3736 indicates that references within the defining module bind to the
3737 definition in that module. That is, the declared entity cannot be
3738 overridden by another module.
3742 All visibilities are supported on many, but not all, ELF targets
3743 (supported when the assembler supports the @samp{.visibility}
3744 pseudo-op). Default visibility is supported everywhere. Hidden
3745 visibility is supported on Darwin targets.
3747 The visibility attribute should be applied only to declarations that
3748 would otherwise have external linkage. The attribute should be applied
3749 consistently, so that the same entity should not be declared with
3750 different settings of the attribute.
3752 In C++, the visibility attribute applies to types as well as functions
3753 and objects, because in C++ types have linkage. A class must not have
3754 greater visibility than its non-static data member types and bases,
3755 and class members default to the visibility of their class. Also, a
3756 declaration without explicit visibility is limited to the visibility
3759 In C++, you can mark member functions and static member variables of a
3760 class with the visibility attribute. This is useful if you know a
3761 particular method or static member variable should only be used from
3762 one shared object; then you can mark it hidden while the rest of the
3763 class has default visibility. Care must be taken to avoid breaking
3764 the One Definition Rule; for example, it is usually not useful to mark
3765 an inline method as hidden without marking the whole class as hidden.
3767 A C++ namespace declaration can also have the visibility attribute.
3770 namespace nspace1 __attribute__ ((visibility ("protected")))
3771 @{ /* @r{Do something.} */; @}
3774 This attribute applies only to the particular namespace body, not to
3775 other definitions of the same namespace; it is equivalent to using
3776 @samp{#pragma GCC visibility} before and after the namespace
3777 definition (@pxref{Visibility Pragmas}).
3779 In C++, if a template argument has limited visibility, this
3780 restriction is implicitly propagated to the template instantiation.
3781 Otherwise, template instantiations and specializations default to the
3782 visibility of their template.
3784 If both the template and enclosing class have explicit visibility, the
3785 visibility from the template is used.
3787 @item warn_unused_result
3788 @cindex @code{warn_unused_result} function attribute
3789 The @code{warn_unused_result} attribute causes a warning to be emitted
3790 if a caller of the function with this attribute does not use its
3791 return value. This is useful for functions where not checking
3792 the result is either a security problem or always a bug, such as
3796 int fn () __attribute__ ((warn_unused_result));
3799 if (fn () < 0) return -1;
3806 results in warning on line 5.
3809 @cindex @code{weak} function attribute
3810 The @code{weak} attribute causes the declaration to be emitted as a weak
3811 symbol rather than a global. This is primarily useful in defining
3812 library functions that can be overridden in user code, though it can
3813 also be used with non-function declarations. Weak symbols are supported
3814 for ELF targets, and also for a.out targets when using the GNU assembler
3818 @itemx weakref ("@var{target}")
3819 @cindex @code{weakref} function attribute
3820 The @code{weakref} attribute marks a declaration as a weak reference.
3821 Without arguments, it should be accompanied by an @code{alias} attribute
3822 naming the target symbol. Optionally, the @var{target} may be given as
3823 an argument to @code{weakref} itself. In either case, @code{weakref}
3824 implicitly marks the declaration as @code{weak}. Without a
3825 @var{target}, given as an argument to @code{weakref} or to @code{alias},
3826 @code{weakref} is equivalent to @code{weak}.
3829 static int x() __attribute__ ((weakref ("y")));
3830 /* is equivalent to... */
3831 static int x() __attribute__ ((weak, weakref, alias ("y")));
3833 static int x() __attribute__ ((weakref));
3834 static int x() __attribute__ ((alias ("y")));
3837 A weak reference is an alias that does not by itself require a
3838 definition to be given for the target symbol. If the target symbol is
3839 only referenced through weak references, then it becomes a @code{weak}
3840 undefined symbol. If it is directly referenced, however, then such
3841 strong references prevail, and a definition is required for the
3842 symbol, not necessarily in the same translation unit.
3844 The effect is equivalent to moving all references to the alias to a
3845 separate translation unit, renaming the alias to the aliased symbol,
3846 declaring it as weak, compiling the two separate translation units and
3847 performing a link with relocatable output (ie: @code{ld -r}) on them.
3849 At present, a declaration to which @code{weakref} is attached can
3850 only be @code{static}.
3855 @c This is the end of the target-independent attribute table
3857 @node AArch64 Function Attributes
3858 @subsection AArch64 Function Attributes
3860 The following target-specific function attributes are available for the
3861 AArch64 target. For the most part, these options mirror the behavior of
3862 similar command-line options (@pxref{AArch64 Options}), but on a
3866 @item general-regs-only
3867 @cindex @code{general-regs-only} function attribute, AArch64
3868 Indicates that no floating-point or Advanced SIMD registers should be
3869 used when generating code for this function. If the function explicitly
3870 uses floating-point code, then the compiler gives an error. This is
3871 the same behavior as that of the command-line option
3872 @option{-mgeneral-regs-only}.
3874 @item fix-cortex-a53-835769
3875 @cindex @code{fix-cortex-a53-835769} function attribute, AArch64
3876 Indicates that the workaround for the Cortex-A53 erratum 835769 should be
3877 applied to this function. To explicitly disable the workaround for this
3878 function specify the negated form: @code{no-fix-cortex-a53-835769}.
3879 This corresponds to the behavior of the command line options
3880 @option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
3883 @cindex @code{cmodel=} function attribute, AArch64
3884 Indicates that code should be generated for a particular code model for
3885 this function. The behavior and permissible arguments are the same as
3886 for the command line option @option{-mcmodel=}.
3889 @itemx no-strict-align
3890 @cindex @code{strict-align} function attribute, AArch64
3891 @code{strict-align} indicates that the compiler should not assume that unaligned
3892 memory references are handled by the system. To allow the compiler to assume
3893 that aligned memory references are handled by the system, the inverse attribute
3894 @code{no-strict-align} can be specified. The behavior is same as for the
3895 command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
3897 @item omit-leaf-frame-pointer
3898 @cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
3899 Indicates that the frame pointer should be omitted for a leaf function call.
3900 To keep the frame pointer, the inverse attribute
3901 @code{no-omit-leaf-frame-pointer} can be specified. These attributes have
3902 the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
3903 and @option{-mno-omit-leaf-frame-pointer}.
3906 @cindex @code{tls-dialect=} function attribute, AArch64
3907 Specifies the TLS dialect to use for this function. The behavior and
3908 permissible arguments are the same as for the command-line option
3909 @option{-mtls-dialect=}.
3912 @cindex @code{arch=} function attribute, AArch64
3913 Specifies the architecture version and architectural extensions to use
3914 for this function. The behavior and permissible arguments are the same as
3915 for the @option{-march=} command-line option.
3918 @cindex @code{tune=} function attribute, AArch64
3919 Specifies the core for which to tune the performance of this function.
3920 The behavior and permissible arguments are the same as for the @option{-mtune=}
3921 command-line option.
3924 @cindex @code{cpu=} function attribute, AArch64
3925 Specifies the core for which to tune the performance of this function and also
3926 whose architectural features to use. The behavior and valid arguments are the
3927 same as for the @option{-mcpu=} command-line option.
3929 @item sign-return-address
3930 @cindex @code{sign-return-address} function attribute, AArch64
3931 Select the function scope on which return address signing will be applied. The
3932 behavior and permissible arguments are the same as for the command-line option
3933 @option{-msign-return-address=}. The default value is @code{none}. This
3934 attribute is deprecated. The @code{branch-protection} attribute should
3937 @item branch-protection
3938 @cindex @code{branch-protection} function attribute, AArch64
3939 Select the function scope on which branch protection will be applied. The
3940 behavior and permissible arguments are the same as for the command-line option
3941 @option{-mbranch-protection=}. The default value is @code{none}.
3945 The above target attributes can be specified as follows:
3948 __attribute__((target("@var{attr-string}")))
3956 where @code{@var{attr-string}} is one of the attribute strings specified above.
3958 Additionally, the architectural extension string may be specified on its
3959 own. This can be used to turn on and off particular architectural extensions
3960 without having to specify a particular architecture version or core. Example:
3963 __attribute__((target("+crc+nocrypto")))
3971 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
3972 extension and disables the @code{crypto} extension for the function @code{foo}
3973 without modifying an existing @option{-march=} or @option{-mcpu} option.
3975 Multiple target function attributes can be specified by separating them with
3976 a comma. For example:
3978 __attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
3986 is valid and compiles function @code{foo} for ARMv8-A with @code{crc}
3987 and @code{crypto} extensions and tunes it for @code{cortex-a53}.
3989 @subsubsection Inlining rules
3990 Specifying target attributes on individual functions or performing link-time
3991 optimization across translation units compiled with different target options
3992 can affect function inlining rules:
3994 In particular, a caller function can inline a callee function only if the
3995 architectural features available to the callee are a subset of the features
3996 available to the caller.
3997 For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
3998 or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
3999 can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
4000 because the all the architectural features that function @code{bar} requires
4001 are available to function @code{foo}. Conversely, function @code{bar} cannot
4002 inline function @code{foo}.
4004 Additionally inlining a function compiled with @option{-mstrict-align} into a
4005 function compiled without @code{-mstrict-align} is not allowed.
4006 However, inlining a function compiled without @option{-mstrict-align} into a
4007 function compiled with @option{-mstrict-align} is allowed.
4009 Note that CPU tuning options and attributes such as the @option{-mcpu=},
4010 @option{-mtune=} do not inhibit inlining unless the CPU specified by the
4011 @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
4012 architectural feature rules specified above.
4014 @node AMD GCN Function Attributes
4015 @subsection AMD GCN Function Attributes
4017 These function attributes are supported by the AMD GCN back end:
4020 @item amdgpu_hsa_kernel
4021 @cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN
4022 This attribute indicates that the corresponding function should be compiled as
4023 a kernel function, that is an entry point that can be invoked from the host
4024 via the HSA runtime library. By default functions are only callable only from
4025 other GCN functions.
4027 This attribute is implicitly applied to any function named @code{main}, using
4030 Kernel functions may return an integer value, which will be written to a
4031 conventional place within the HSA "kernargs" region.
4033 The attribute parameters configure what values are passed into the kernel
4034 function by the GPU drivers, via the initial register state. Some values are
4035 used by the compiler, and therefore forced on. Enabling other options may
4036 break assumptions in the compiler and/or run-time libraries.
4039 @item private_segment_buffer
4040 Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to
4044 Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the
4048 Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address
4051 @item kernarg_segment_ptr
4052 Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to
4053 locate the kernel arguments, "kernargs").
4056 Set @code{enable_sgpr_dispatch_id} flag.
4058 @item flat_scratch_init
4059 Set @code{enable_sgpr_flat_scratch_init} flag.
4061 @item private_segment_size
4062 Set @code{enable_sgpr_private_segment_size} flag.
4064 @item grid_workgroup_count_X
4065 Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to
4066 use OpenACC/OpenMP).
4068 @item grid_workgroup_count_Y
4069 Set @code{enable_sgpr_grid_workgroup_count_y} flag.
4071 @item grid_workgroup_count_Z
4072 Set @code{enable_sgpr_grid_workgroup_count_z} flag.
4074 @item workgroup_id_X
4075 Set @code{enable_sgpr_workgroup_id_x} flag.
4077 @item workgroup_id_Y
4078 Set @code{enable_sgpr_workgroup_id_y} flag.
4080 @item workgroup_id_Z
4081 Set @code{enable_sgpr_workgroup_id_z} flag.
4083 @item workgroup_info
4084 Set @code{enable_sgpr_workgroup_info} flag.
4086 @item private_segment_wave_offset
4087 Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on
4088 (required to locate the stack).
4090 @item work_item_id_X
4091 Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled).
4093 @item work_item_id_Y
4094 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable
4097 @item work_item_id_Z
4098 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use
4104 @node ARC Function Attributes
4105 @subsection ARC Function Attributes
4107 These function attributes are supported by the ARC back end:
4111 @cindex @code{interrupt} function attribute, ARC
4112 Use this attribute to indicate
4113 that the specified function is an interrupt handler. The compiler generates
4114 function entry and exit sequences suitable for use in an interrupt handler
4115 when this attribute is present.
4117 On the ARC, you must specify the kind of interrupt to be handled
4118 in a parameter to the interrupt attribute like this:
4121 void f () __attribute__ ((interrupt ("ilink1")));
4124 Permissible values for this parameter are: @w{@code{ilink1}} and
4125 @w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and
4126 @w{@code{firq}} for ARCv2 architecture.
4131 @cindex @code{long_call} function attribute, ARC
4132 @cindex @code{medium_call} function attribute, ARC
4133 @cindex @code{short_call} function attribute, ARC
4134 @cindex indirect calls, ARC
4135 These attributes specify how a particular function is called.
4136 These attributes override the
4137 @option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
4138 command-line switches and @code{#pragma long_calls} settings.
4140 For ARC, a function marked with the @code{long_call} attribute is
4141 always called using register-indirect jump-and-link instructions,
4142 thereby enabling the called function to be placed anywhere within the
4143 32-bit address space. A function marked with the @code{medium_call}
4144 attribute will always be close enough to be called with an unconditional
4145 branch-and-link instruction, which has a 25-bit offset from
4146 the call site. A function marked with the @code{short_call}
4147 attribute will always be close enough to be called with a conditional
4148 branch-and-link instruction, which has a 21-bit offset from
4152 @cindex @code{jli_always} function attribute, ARC
4153 Forces a particular function to be called using @code{jli}
4154 instruction. The @code{jli} instruction makes use of a table stored
4155 into @code{.jlitab} section, which holds the location of the functions
4156 which are addressed using this instruction.
4159 @cindex @code{jli_fixed} function attribute, ARC
4160 Identical like the above one, but the location of the function in the
4161 @code{jli} table is known and given as an attribute parameter.
4164 @cindex @code{secure_call} function attribute, ARC
4165 This attribute allows one to mark secure-code functions that are
4166 callable from normal mode. The location of the secure call function
4167 into the @code{sjli} table needs to be passed as argument.
4170 @cindex @code{naked} function attribute, ARC
4171 This attribute allows the compiler to construct the requisite function
4172 declaration, while allowing the body of the function to be assembly
4173 code. The specified function will not have prologue/epilogue
4174 sequences generated by the compiler. Only basic @code{asm} statements
4175 can safely be included in naked functions (@pxref{Basic Asm}). While
4176 using extended @code{asm} or a mixture of basic @code{asm} and C code
4177 may appear to work, they cannot be depended upon to work reliably and
4182 @node ARM Function Attributes
4183 @subsection ARM Function Attributes
4185 These function attributes are supported for ARM targets:
4189 @item general-regs-only
4190 @cindex @code{general-regs-only} function attribute, ARM
4191 Indicates that no floating-point or Advanced SIMD registers should be
4192 used when generating code for this function. If the function explicitly
4193 uses floating-point code, then the compiler gives an error. This is
4194 the same behavior as that of the command-line option
4195 @option{-mgeneral-regs-only}.
4198 @cindex @code{interrupt} function attribute, ARM
4199 Use this attribute to indicate
4200 that the specified function is an interrupt handler. The compiler generates
4201 function entry and exit sequences suitable for use in an interrupt handler
4202 when this attribute is present.
4204 You can specify the kind of interrupt to be handled by
4205 adding an optional parameter to the interrupt attribute like this:
4208 void f () __attribute__ ((interrupt ("IRQ")));
4212 Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
4213 @code{SWI}, @code{ABORT} and @code{UNDEF}.
4215 On ARMv7-M the interrupt type is ignored, and the attribute means the function
4216 may be called with a word-aligned stack pointer.
4219 @cindex @code{isr} function attribute, ARM
4220 Use this attribute on ARM to write Interrupt Service Routines. This is an
4221 alias to the @code{interrupt} attribute above.
4225 @cindex @code{long_call} function attribute, ARM
4226 @cindex @code{short_call} function attribute, ARM
4227 @cindex indirect calls, ARM
4228 These attributes specify how a particular function is called.
4229 These attributes override the
4230 @option{-mlong-calls} (@pxref{ARM Options})
4231 command-line switch and @code{#pragma long_calls} settings. For ARM, the
4232 @code{long_call} attribute indicates that the function might be far
4233 away from the call site and require a different (more expensive)
4234 calling sequence. The @code{short_call} attribute always places
4235 the offset to the function from the call site into the @samp{BL}
4236 instruction directly.
4239 @cindex @code{naked} function attribute, ARM
4240 This attribute allows the compiler to construct the
4241 requisite function declaration, while allowing the body of the
4242 function to be assembly code. The specified function will not have
4243 prologue/epilogue sequences generated by the compiler. Only basic
4244 @code{asm} statements can safely be included in naked functions
4245 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4246 basic @code{asm} and C code may appear to work, they cannot be
4247 depended upon to work reliably and are not supported.
4250 @cindex @code{pcs} function attribute, ARM
4252 The @code{pcs} attribute can be used to control the calling convention
4253 used for a function on ARM. The attribute takes an argument that specifies
4254 the calling convention to use.
4256 When compiling using the AAPCS ABI (or a variant of it) then valid
4257 values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
4258 order to use a variant other than @code{"aapcs"} then the compiler must
4259 be permitted to use the appropriate co-processor registers (i.e., the
4260 VFP registers must be available in order to use @code{"aapcs-vfp"}).
4264 /* Argument passed in r0, and result returned in r0+r1. */
4265 double f2d (float) __attribute__((pcs("aapcs")));
4268 Variadic functions always use the @code{"aapcs"} calling convention and
4269 the compiler rejects attempts to specify an alternative.
4271 @item target (@var{options})
4272 @cindex @code{target} function attribute
4273 As discussed in @ref{Common Function Attributes}, this attribute
4274 allows specification of target-specific compilation options.
4276 On ARM, the following options are allowed:
4280 @cindex @code{target("thumb")} function attribute, ARM
4281 Force code generation in the Thumb (T16/T32) ISA, depending on the
4285 @cindex @code{target("arm")} function attribute, ARM
4286 Force code generation in the ARM (A32) ISA.
4288 Functions from different modes can be inlined in the caller's mode.
4291 @cindex @code{target("fpu=")} function attribute, ARM
4292 Specifies the fpu for which to tune the performance of this function.
4293 The behavior and permissible arguments are the same as for the @option{-mfpu=}
4294 command-line option.
4297 @cindex @code{arch=} function attribute, ARM
4298 Specifies the architecture version and architectural extensions to use
4299 for this function. The behavior and permissible arguments are the same as
4300 for the @option{-march=} command-line option.
4302 The above target attributes can be specified as follows:
4305 __attribute__((target("arch=armv8-a+crc")))
4313 Additionally, the architectural extension string may be specified on its
4314 own. This can be used to turn on and off particular architectural extensions
4315 without having to specify a particular architecture version or core. Example:
4318 __attribute__((target("+crc+nocrypto")))
4326 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
4327 extension and disables the @code{crypto} extension for the function @code{foo}
4328 without modifying an existing @option{-march=} or @option{-mcpu} option.
4334 @node AVR Function Attributes
4335 @subsection AVR Function Attributes
4337 These function attributes are supported by the AVR back end:
4341 @cindex @code{interrupt} function attribute, AVR
4342 Use this attribute to indicate
4343 that the specified function is an interrupt handler. The compiler generates
4344 function entry and exit sequences suitable for use in an interrupt handler
4345 when this attribute is present.
4347 On the AVR, the hardware globally disables interrupts when an
4348 interrupt is executed. The first instruction of an interrupt handler
4349 declared with this attribute is a @code{SEI} instruction to
4350 re-enable interrupts. See also the @code{signal} function attribute
4351 that does not insert a @code{SEI} instruction. If both @code{signal} and
4352 @code{interrupt} are specified for the same function, @code{signal}
4353 is silently ignored.
4356 @cindex @code{naked} function attribute, AVR
4357 This attribute allows the compiler to construct the
4358 requisite function declaration, while allowing the body of the
4359 function to be assembly code. The specified function will not have
4360 prologue/epilogue sequences generated by the compiler. Only basic
4361 @code{asm} statements can safely be included in naked functions
4362 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4363 basic @code{asm} and C code may appear to work, they cannot be
4364 depended upon to work reliably and are not supported.
4367 @cindex @code{no_gccisr} function attribute, AVR
4368 Do not use @code{__gcc_isr} pseudo instructions in a function with
4369 the @code{interrupt} or @code{signal} attribute aka. interrupt
4370 service routine (ISR).
4371 Use this attribute if the preamble of the ISR prologue should always read
4375 in __tmp_reg__, __SREG__
4379 and accordingly for the postamble of the epilogue --- no matter whether
4380 the mentioned registers are actually used in the ISR or not.
4381 Situations where you might want to use this attribute include:
4384 Code that (effectively) clobbers bits of @code{SREG} other than the
4385 @code{I}-flag by writing to the memory location of @code{SREG}.
4387 Code that uses inline assembler to jump to a different function which
4388 expects (parts of) the prologue code as outlined above to be present.
4390 To disable @code{__gcc_isr} generation for the whole compilation unit,
4391 there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}.
4395 @cindex @code{OS_main} function attribute, AVR
4396 @cindex @code{OS_task} function attribute, AVR
4397 On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
4398 do not save/restore any call-saved register in their prologue/epilogue.
4400 The @code{OS_main} attribute can be used when there @emph{is
4401 guarantee} that interrupts are disabled at the time when the function
4402 is entered. This saves resources when the stack pointer has to be
4403 changed to set up a frame for local variables.
4405 The @code{OS_task} attribute can be used when there is @emph{no
4406 guarantee} that interrupts are disabled at that time when the function
4407 is entered like for, e@.g@. task functions in a multi-threading operating
4408 system. In that case, changing the stack pointer register is
4409 guarded by save/clear/restore of the global interrupt enable flag.
4411 The differences to the @code{naked} function attribute are:
4413 @item @code{naked} functions do not have a return instruction whereas
4414 @code{OS_main} and @code{OS_task} functions have a @code{RET} or
4415 @code{RETI} return instruction.
4416 @item @code{naked} functions do not set up a frame for local variables
4417 or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
4422 @cindex @code{signal} function attribute, AVR
4423 Use this attribute on the AVR to indicate that the specified
4424 function is an interrupt handler. The compiler generates function
4425 entry and exit sequences suitable for use in an interrupt handler when this
4426 attribute is present.
4428 See also the @code{interrupt} function attribute.
4430 The AVR hardware globally disables interrupts when an interrupt is executed.
4431 Interrupt handler functions defined with the @code{signal} attribute
4432 do not re-enable interrupts. It is save to enable interrupts in a
4433 @code{signal} handler. This ``save'' only applies to the code
4434 generated by the compiler and not to the IRQ layout of the
4435 application which is responsibility of the application.
4437 If both @code{signal} and @code{interrupt} are specified for the same
4438 function, @code{signal} is silently ignored.
4441 @node Blackfin Function Attributes
4442 @subsection Blackfin Function Attributes
4444 These function attributes are supported by the Blackfin back end:
4448 @item exception_handler
4449 @cindex @code{exception_handler} function attribute
4450 @cindex exception handler functions, Blackfin
4451 Use this attribute on the Blackfin to indicate that the specified function
4452 is an exception handler. The compiler generates function entry and
4453 exit sequences suitable for use in an exception handler when this
4454 attribute is present.
4456 @item interrupt_handler
4457 @cindex @code{interrupt_handler} function attribute, Blackfin
4458 Use this attribute to
4459 indicate that the specified function is an interrupt handler. The compiler
4460 generates function entry and exit sequences suitable for use in an
4461 interrupt handler when this attribute is present.
4464 @cindex @code{kspisusp} function attribute, Blackfin
4465 @cindex User stack pointer in interrupts on the Blackfin
4466 When used together with @code{interrupt_handler}, @code{exception_handler}
4467 or @code{nmi_handler}, code is generated to load the stack pointer
4468 from the USP register in the function prologue.
4471 @cindex @code{l1_text} function attribute, Blackfin
4472 This attribute specifies a function to be placed into L1 Instruction
4473 SRAM@. The function is put into a specific section named @code{.l1.text}.
4474 With @option{-mfdpic}, function calls with a such function as the callee
4475 or caller uses inlined PLT.
4478 @cindex @code{l2} function attribute, Blackfin
4479 This attribute specifies a function to be placed into L2
4480 SRAM. The function is put into a specific section named
4481 @code{.l2.text}. With @option{-mfdpic}, callers of such functions use
4486 @cindex indirect calls, Blackfin
4487 @cindex @code{longcall} function attribute, Blackfin
4488 @cindex @code{shortcall} function attribute, Blackfin
4489 The @code{longcall} attribute
4490 indicates that the function might be far away from the call site and
4491 require a different (more expensive) calling sequence. The
4492 @code{shortcall} attribute indicates that the function is always close
4493 enough for the shorter calling sequence to be used. These attributes
4494 override the @option{-mlongcall} switch.
4497 @cindex @code{nesting} function attribute, Blackfin
4498 @cindex Allow nesting in an interrupt handler on the Blackfin processor
4499 Use this attribute together with @code{interrupt_handler},
4500 @code{exception_handler} or @code{nmi_handler} to indicate that the function
4501 entry code should enable nested interrupts or exceptions.
4504 @cindex @code{nmi_handler} function attribute, Blackfin
4505 @cindex NMI handler functions on the Blackfin processor
4506 Use this attribute on the Blackfin to indicate that the specified function
4507 is an NMI handler. The compiler generates function entry and
4508 exit sequences suitable for use in an NMI handler when this
4509 attribute is present.
4512 @cindex @code{saveall} function attribute, Blackfin
4513 @cindex save all registers on the Blackfin
4514 Use this attribute to indicate that
4515 all registers except the stack pointer should be saved in the prologue
4516 regardless of whether they are used or not.
4519 @node CR16 Function Attributes
4520 @subsection CR16 Function Attributes
4522 These function attributes are supported by the CR16 back end:
4526 @cindex @code{interrupt} function attribute, CR16
4527 Use this attribute to indicate
4528 that the specified function is an interrupt handler. The compiler generates
4529 function entry and exit sequences suitable for use in an interrupt handler
4530 when this attribute is present.
4533 @node C-SKY Function Attributes
4534 @subsection C-SKY Function Attributes
4536 These function attributes are supported by the C-SKY back end:
4541 @cindex @code{interrupt} function attribute, C-SKY
4542 @cindex @code{isr} function attribute, C-SKY
4543 Use these attributes to indicate that the specified function
4544 is an interrupt handler.
4545 The compiler generates function entry and exit sequences suitable for
4546 use in an interrupt handler when either of these attributes are present.
4548 Use of these options requires the @option{-mistack} command-line option
4549 to enable support for the necessary interrupt stack instructions. They
4550 are ignored with a warning otherwise. @xref{C-SKY Options}.
4553 @cindex @code{naked} function attribute, C-SKY
4554 This attribute allows the compiler to construct the
4555 requisite function declaration, while allowing the body of the
4556 function to be assembly code. The specified function will not have
4557 prologue/epilogue sequences generated by the compiler. Only basic
4558 @code{asm} statements can safely be included in naked functions
4559 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4560 basic @code{asm} and C code may appear to work, they cannot be
4561 depended upon to work reliably and are not supported.
4565 @node Epiphany Function Attributes
4566 @subsection Epiphany Function Attributes
4568 These function attributes are supported by the Epiphany back end:
4572 @cindex @code{disinterrupt} function attribute, Epiphany
4573 This attribute causes the compiler to emit
4574 instructions to disable interrupts for the duration of the given
4577 @item forwarder_section
4578 @cindex @code{forwarder_section} function attribute, Epiphany
4579 This attribute modifies the behavior of an interrupt handler.
4580 The interrupt handler may be in external memory which cannot be
4581 reached by a branch instruction, so generate a local memory trampoline
4582 to transfer control. The single parameter identifies the section where
4583 the trampoline is placed.
4586 @cindex @code{interrupt} function attribute, Epiphany
4587 Use this attribute to indicate
4588 that the specified function is an interrupt handler. The compiler generates
4589 function entry and exit sequences suitable for use in an interrupt handler
4590 when this attribute is present. It may also generate
4591 a special section with code to initialize the interrupt vector table.
4593 On Epiphany targets one or more optional parameters can be added like this:
4596 void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
4599 Permissible values for these parameters are: @w{@code{reset}},
4600 @w{@code{software_exception}}, @w{@code{page_miss}},
4601 @w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
4602 @w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
4603 Multiple parameters indicate that multiple entries in the interrupt
4604 vector table should be initialized for this function, i.e.@: for each
4605 parameter @w{@var{name}}, a jump to the function is emitted in
4606 the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
4607 entirely, in which case no interrupt vector table entry is provided.
4609 Note that interrupts are enabled inside the function
4610 unless the @code{disinterrupt} attribute is also specified.
4612 The following examples are all valid uses of these attributes on
4615 void __attribute__ ((interrupt)) universal_handler ();
4616 void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
4617 void __attribute__ ((interrupt ("dma0, dma1")))
4618 universal_dma_handler ();
4619 void __attribute__ ((interrupt ("timer0"), disinterrupt))
4620 fast_timer_handler ();
4621 void __attribute__ ((interrupt ("dma0, dma1"),
4622 forwarder_section ("tramp")))
4623 external_dma_handler ();
4628 @cindex @code{long_call} function attribute, Epiphany
4629 @cindex @code{short_call} function attribute, Epiphany
4630 @cindex indirect calls, Epiphany
4631 These attributes specify how a particular function is called.
4632 These attributes override the
4633 @option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
4634 command-line switch and @code{#pragma long_calls} settings.
4638 @node H8/300 Function Attributes
4639 @subsection H8/300 Function Attributes
4641 These function attributes are available for H8/300 targets:
4644 @item function_vector
4645 @cindex @code{function_vector} function attribute, H8/300
4646 Use this attribute on the H8/300, H8/300H, and H8S to indicate
4647 that the specified function should be called through the function vector.
4648 Calling a function through the function vector reduces code size; however,
4649 the function vector has a limited size (maximum 128 entries on the H8/300
4650 and 64 entries on the H8/300H and H8S)
4651 and shares space with the interrupt vector.
4653 @item interrupt_handler
4654 @cindex @code{interrupt_handler} function attribute, H8/300
4655 Use this attribute on the H8/300, H8/300H, and H8S to
4656 indicate that the specified function is an interrupt handler. The compiler
4657 generates function entry and exit sequences suitable for use in an
4658 interrupt handler when this attribute is present.
4661 @cindex @code{saveall} function attribute, H8/300
4662 @cindex save all registers on the H8/300, H8/300H, and H8S
4663 Use this attribute on the H8/300, H8/300H, and H8S to indicate that
4664 all registers except the stack pointer should be saved in the prologue
4665 regardless of whether they are used or not.
4668 @node IA-64 Function Attributes
4669 @subsection IA-64 Function Attributes
4671 These function attributes are supported on IA-64 targets:
4674 @item syscall_linkage
4675 @cindex @code{syscall_linkage} function attribute, IA-64
4676 This attribute is used to modify the IA-64 calling convention by marking
4677 all input registers as live at all function exits. This makes it possible
4678 to restart a system call after an interrupt without having to save/restore
4679 the input registers. This also prevents kernel data from leaking into
4683 @cindex @code{version_id} function attribute, IA-64
4684 This IA-64 HP-UX attribute, attached to a global variable or function, renames a
4685 symbol to contain a version string, thus allowing for function level
4686 versioning. HP-UX system header files may use function level versioning
4687 for some system calls.
4690 extern int foo () __attribute__((version_id ("20040821")));
4694 Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
4697 @node M32C Function Attributes
4698 @subsection M32C Function Attributes
4700 These function attributes are supported by the M32C back end:
4704 @cindex @code{bank_switch} function attribute, M32C
4705 When added to an interrupt handler with the M32C port, causes the
4706 prologue and epilogue to use bank switching to preserve the registers
4707 rather than saving them on the stack.
4709 @item fast_interrupt
4710 @cindex @code{fast_interrupt} function attribute, M32C
4711 Use this attribute on the M32C port to indicate that the specified
4712 function is a fast interrupt handler. This is just like the
4713 @code{interrupt} attribute, except that @code{freit} is used to return
4714 instead of @code{reit}.
4716 @item function_vector
4717 @cindex @code{function_vector} function attribute, M16C/M32C
4718 On M16C/M32C targets, the @code{function_vector} attribute declares a
4719 special page subroutine call function. Use of this attribute reduces
4720 the code size by 2 bytes for each call generated to the
4721 subroutine. The argument to the attribute is the vector number entry
4722 from the special page vector table which contains the 16 low-order
4723 bits of the subroutine's entry address. Each vector table has special
4724 page number (18 to 255) that is used in @code{jsrs} instructions.
4725 Jump addresses of the routines are generated by adding 0x0F0000 (in
4726 case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
4727 2-byte addresses set in the vector table. Therefore you need to ensure
4728 that all the special page vector routines should get mapped within the
4729 address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
4732 In the following example 2 bytes are saved for each call to
4733 function @code{foo}.
4736 void foo (void) __attribute__((function_vector(0x18)));
4747 If functions are defined in one file and are called in another file,
4748 then be sure to write this declaration in both files.
4750 This attribute is ignored for R8C target.
4753 @cindex @code{interrupt} function attribute, M32C
4754 Use this attribute to indicate
4755 that the specified function is an interrupt handler. The compiler generates
4756 function entry and exit sequences suitable for use in an interrupt handler
4757 when this attribute is present.
4760 @node M32R/D Function Attributes
4761 @subsection M32R/D Function Attributes
4763 These function attributes are supported by the M32R/D back end:
4767 @cindex @code{interrupt} function attribute, M32R/D
4768 Use this attribute to indicate
4769 that the specified function is an interrupt handler. The compiler generates
4770 function entry and exit sequences suitable for use in an interrupt handler
4771 when this attribute is present.
4773 @item model (@var{model-name})
4774 @cindex @code{model} function attribute, M32R/D
4775 @cindex function addressability on the M32R/D
4777 On the M32R/D, use this attribute to set the addressability of an
4778 object, and of the code generated for a function. The identifier
4779 @var{model-name} is one of @code{small}, @code{medium}, or
4780 @code{large}, representing each of the code models.
4782 Small model objects live in the lower 16MB of memory (so that their
4783 addresses can be loaded with the @code{ld24} instruction), and are
4784 callable with the @code{bl} instruction.
4786 Medium model objects may live anywhere in the 32-bit address space (the
4787 compiler generates @code{seth/add3} instructions to load their addresses),
4788 and are callable with the @code{bl} instruction.
4790 Large model objects may live anywhere in the 32-bit address space (the
4791 compiler generates @code{seth/add3} instructions to load their addresses),
4792 and may not be reachable with the @code{bl} instruction (the compiler
4793 generates the much slower @code{seth/add3/jl} instruction sequence).
4796 @node m68k Function Attributes
4797 @subsection m68k Function Attributes
4799 These function attributes are supported by the m68k back end:
4803 @itemx interrupt_handler
4804 @cindex @code{interrupt} function attribute, m68k
4805 @cindex @code{interrupt_handler} function attribute, m68k
4806 Use this attribute to
4807 indicate that the specified function is an interrupt handler. The compiler
4808 generates function entry and exit sequences suitable for use in an
4809 interrupt handler when this attribute is present. Either name may be used.
4811 @item interrupt_thread
4812 @cindex @code{interrupt_thread} function attribute, fido
4813 Use this attribute on fido, a subarchitecture of the m68k, to indicate
4814 that the specified function is an interrupt handler that is designed
4815 to run as a thread. The compiler omits generate prologue/epilogue
4816 sequences and replaces the return instruction with a @code{sleep}
4817 instruction. This attribute is available only on fido.
4820 @node MCORE Function Attributes
4821 @subsection MCORE Function Attributes
4823 These function attributes are supported by the MCORE back end:
4827 @cindex @code{naked} function attribute, MCORE
4828 This attribute allows the compiler to construct the
4829 requisite function declaration, while allowing the body of the
4830 function to be assembly code. The specified function will not have
4831 prologue/epilogue sequences generated by the compiler. Only basic
4832 @code{asm} statements can safely be included in naked functions
4833 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4834 basic @code{asm} and C code may appear to work, they cannot be
4835 depended upon to work reliably and are not supported.
4838 @node MeP Function Attributes
4839 @subsection MeP Function Attributes
4841 These function attributes are supported by the MeP back end:
4845 @cindex @code{disinterrupt} function attribute, MeP
4846 On MeP targets, this attribute causes the compiler to emit
4847 instructions to disable interrupts for the duration of the given
4851 @cindex @code{interrupt} function attribute, MeP
4852 Use this attribute to indicate
4853 that the specified function is an interrupt handler. The compiler generates
4854 function entry and exit sequences suitable for use in an interrupt handler
4855 when this attribute is present.
4858 @cindex @code{near} function attribute, MeP
4859 This attribute causes the compiler to assume the called
4860 function is close enough to use the normal calling convention,
4861 overriding the @option{-mtf} command-line option.
4864 @cindex @code{far} function attribute, MeP
4865 On MeP targets this causes the compiler to use a calling convention
4866 that assumes the called function is too far away for the built-in
4870 @cindex @code{vliw} function attribute, MeP
4871 The @code{vliw} attribute tells the compiler to emit
4872 instructions in VLIW mode instead of core mode. Note that this
4873 attribute is not allowed unless a VLIW coprocessor has been configured
4874 and enabled through command-line options.
4877 @node MicroBlaze Function Attributes
4878 @subsection MicroBlaze Function Attributes
4880 These function attributes are supported on MicroBlaze targets:
4883 @item save_volatiles
4884 @cindex @code{save_volatiles} function attribute, MicroBlaze
4885 Use this attribute to indicate that the function is
4886 an interrupt handler. All volatile registers (in addition to non-volatile
4887 registers) are saved in the function prologue. If the function is a leaf
4888 function, only volatiles used by the function are saved. A normal function
4889 return is generated instead of a return from interrupt.
4892 @cindex @code{break_handler} function attribute, MicroBlaze
4893 @cindex break handler functions
4894 Use this attribute to indicate that
4895 the specified function is a break handler. The compiler generates function
4896 entry and exit sequences suitable for use in an break handler when this
4897 attribute is present. The return from @code{break_handler} is done through
4898 the @code{rtbd} instead of @code{rtsd}.
4901 void f () __attribute__ ((break_handler));
4904 @item interrupt_handler
4905 @itemx fast_interrupt
4906 @cindex @code{interrupt_handler} function attribute, MicroBlaze
4907 @cindex @code{fast_interrupt} function attribute, MicroBlaze
4908 These attributes indicate that the specified function is an interrupt
4909 handler. Use the @code{fast_interrupt} attribute to indicate handlers
4910 used in low-latency interrupt mode, and @code{interrupt_handler} for
4911 interrupts that do not use low-latency handlers. In both cases, GCC
4912 emits appropriate prologue code and generates a return from the handler
4913 using @code{rtid} instead of @code{rtsd}.
4916 @node Microsoft Windows Function Attributes
4917 @subsection Microsoft Windows Function Attributes
4919 The following attributes are available on Microsoft Windows and Symbian OS
4924 @cindex @code{dllexport} function attribute
4925 @cindex @code{__declspec(dllexport)}
4926 On Microsoft Windows targets and Symbian OS targets the
4927 @code{dllexport} attribute causes the compiler to provide a global
4928 pointer to a pointer in a DLL, so that it can be referenced with the
4929 @code{dllimport} attribute. On Microsoft Windows targets, the pointer
4930 name is formed by combining @code{_imp__} and the function or variable
4933 You can use @code{__declspec(dllexport)} as a synonym for
4934 @code{__attribute__ ((dllexport))} for compatibility with other
4937 On systems that support the @code{visibility} attribute, this
4938 attribute also implies ``default'' visibility. It is an error to
4939 explicitly specify any other visibility.
4941 GCC's default behavior is to emit all inline functions with the
4942 @code{dllexport} attribute. Since this can cause object file-size bloat,
4943 you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
4944 ignore the attribute for inlined functions unless the
4945 @option{-fkeep-inline-functions} flag is used instead.
4947 The attribute is ignored for undefined symbols.
4949 When applied to C++ classes, the attribute marks defined non-inlined
4950 member functions and static data members as exports. Static consts
4951 initialized in-class are not marked unless they are also defined
4954 For Microsoft Windows targets there are alternative methods for
4955 including the symbol in the DLL's export table such as using a
4956 @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
4957 the @option{--export-all} linker flag.
4960 @cindex @code{dllimport} function attribute
4961 @cindex @code{__declspec(dllimport)}
4962 On Microsoft Windows and Symbian OS targets, the @code{dllimport}
4963 attribute causes the compiler to reference a function or variable via
4964 a global pointer to a pointer that is set up by the DLL exporting the
4965 symbol. The attribute implies @code{extern}. On Microsoft Windows
4966 targets, the pointer name is formed by combining @code{_imp__} and the
4967 function or variable name.
4969 You can use @code{__declspec(dllimport)} as a synonym for
4970 @code{__attribute__ ((dllimport))} for compatibility with other
4973 On systems that support the @code{visibility} attribute, this
4974 attribute also implies ``default'' visibility. It is an error to
4975 explicitly specify any other visibility.
4977 Currently, the attribute is ignored for inlined functions. If the
4978 attribute is applied to a symbol @emph{definition}, an error is reported.
4979 If a symbol previously declared @code{dllimport} is later defined, the
4980 attribute is ignored in subsequent references, and a warning is emitted.
4981 The attribute is also overridden by a subsequent declaration as
4984 When applied to C++ classes, the attribute marks non-inlined
4985 member functions and static data members as imports. However, the
4986 attribute is ignored for virtual methods to allow creation of vtables
4989 On the SH Symbian OS target the @code{dllimport} attribute also has
4990 another affect---it can cause the vtable and run-time type information
4991 for a class to be exported. This happens when the class has a
4992 dllimported constructor or a non-inline, non-pure virtual function
4993 and, for either of those two conditions, the class also has an inline
4994 constructor or destructor and has a key function that is defined in
4995 the current translation unit.
4997 For Microsoft Windows targets the use of the @code{dllimport}
4998 attribute on functions is not necessary, but provides a small
4999 performance benefit by eliminating a thunk in the DLL@. The use of the
5000 @code{dllimport} attribute on imported variables can be avoided by passing the
5001 @option{--enable-auto-import} switch to the GNU linker. As with
5002 functions, using the attribute for a variable eliminates a thunk in
5005 One drawback to using this attribute is that a pointer to a
5006 @emph{variable} marked as @code{dllimport} cannot be used as a constant
5007 address. However, a pointer to a @emph{function} with the
5008 @code{dllimport} attribute can be used as a constant initializer; in
5009 this case, the address of a stub function in the import lib is
5010 referenced. On Microsoft Windows targets, the attribute can be disabled
5011 for functions by setting the @option{-mnop-fun-dllimport} flag.
5014 @node MIPS Function Attributes
5015 @subsection MIPS Function Attributes
5017 These function attributes are supported by the MIPS back end:
5021 @cindex @code{interrupt} function attribute, MIPS
5022 Use this attribute to indicate that the specified function is an interrupt
5023 handler. The compiler generates function entry and exit sequences suitable
5024 for use in an interrupt handler when this attribute is present.
5025 An optional argument is supported for the interrupt attribute which allows
5026 the interrupt mode to be described. By default GCC assumes the external
5027 interrupt controller (EIC) mode is in use, this can be explicitly set using
5028 @code{eic}. When interrupts are non-masked then the requested Interrupt
5029 Priority Level (IPL) is copied to the current IPL which has the effect of only
5030 enabling higher priority interrupts. To use vectored interrupt mode use
5031 the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
5032 the behavior of the non-masked interrupt support and GCC will arrange to mask
5033 all interrupts from sw0 up to and including the specified interrupt vector.
5035 You can use the following attributes to modify the behavior
5036 of an interrupt handler:
5038 @item use_shadow_register_set
5039 @cindex @code{use_shadow_register_set} function attribute, MIPS
5040 Assume that the handler uses a shadow register set, instead of
5041 the main general-purpose registers. An optional argument @code{intstack} is
5042 supported to indicate that the shadow register set contains a valid stack
5045 @item keep_interrupts_masked
5046 @cindex @code{keep_interrupts_masked} function attribute, MIPS
5047 Keep interrupts masked for the whole function. Without this attribute,
5048 GCC tries to reenable interrupts for as much of the function as it can.
5050 @item use_debug_exception_return
5051 @cindex @code{use_debug_exception_return} function attribute, MIPS
5052 Return using the @code{deret} instruction. Interrupt handlers that don't
5053 have this attribute return using @code{eret} instead.
5056 You can use any combination of these attributes, as shown below:
5058 void __attribute__ ((interrupt)) v0 ();
5059 void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
5060 void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
5061 void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
5062 void __attribute__ ((interrupt, use_shadow_register_set,
5063 keep_interrupts_masked)) v4 ();
5064 void __attribute__ ((interrupt, use_shadow_register_set,
5065 use_debug_exception_return)) v5 ();
5066 void __attribute__ ((interrupt, keep_interrupts_masked,
5067 use_debug_exception_return)) v6 ();
5068 void __attribute__ ((interrupt, use_shadow_register_set,
5069 keep_interrupts_masked,
5070 use_debug_exception_return)) v7 ();
5071 void __attribute__ ((interrupt("eic"))) v8 ();
5072 void __attribute__ ((interrupt("vector=hw3"))) v9 ();
5079 @cindex indirect calls, MIPS
5080 @cindex @code{long_call} function attribute, MIPS
5081 @cindex @code{short_call} function attribute, MIPS
5082 @cindex @code{near} function attribute, MIPS
5083 @cindex @code{far} function attribute, MIPS
5084 These attributes specify how a particular function is called on MIPS@.
5085 The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
5086 command-line switch. The @code{long_call} and @code{far} attributes are
5087 synonyms, and cause the compiler to always call
5088 the function by first loading its address into a register, and then using
5089 the contents of that register. The @code{short_call} and @code{near}
5090 attributes are synonyms, and have the opposite
5091 effect; they specify that non-PIC calls should be made using the more
5092 efficient @code{jal} instruction.
5096 @cindex @code{mips16} function attribute, MIPS
5097 @cindex @code{nomips16} function attribute, MIPS
5099 On MIPS targets, you can use the @code{mips16} and @code{nomips16}
5100 function attributes to locally select or turn off MIPS16 code generation.
5101 A function with the @code{mips16} attribute is emitted as MIPS16 code,
5102 while MIPS16 code generation is disabled for functions with the
5103 @code{nomips16} attribute. These attributes override the
5104 @option{-mips16} and @option{-mno-mips16} options on the command line
5105 (@pxref{MIPS Options}).
5107 When compiling files containing mixed MIPS16 and non-MIPS16 code, the
5108 preprocessor symbol @code{__mips16} reflects the setting on the command line,
5109 not that within individual functions. Mixed MIPS16 and non-MIPS16 code
5110 may interact badly with some GCC extensions such as @code{__builtin_apply}
5111 (@pxref{Constructing Calls}).
5113 @item micromips, MIPS
5114 @itemx nomicromips, MIPS
5115 @cindex @code{micromips} function attribute
5116 @cindex @code{nomicromips} function attribute
5118 On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
5119 function attributes to locally select or turn off microMIPS code generation.
5120 A function with the @code{micromips} attribute is emitted as microMIPS code,
5121 while microMIPS code generation is disabled for functions with the
5122 @code{nomicromips} attribute. These attributes override the
5123 @option{-mmicromips} and @option{-mno-micromips} options on the command line
5124 (@pxref{MIPS Options}).
5126 When compiling files containing mixed microMIPS and non-microMIPS code, the
5127 preprocessor symbol @code{__mips_micromips} reflects the setting on the
5129 not that within individual functions. Mixed microMIPS and non-microMIPS code
5130 may interact badly with some GCC extensions such as @code{__builtin_apply}
5131 (@pxref{Constructing Calls}).
5134 @cindex @code{nocompression} function attribute, MIPS
5135 On MIPS targets, you can use the @code{nocompression} function attribute
5136 to locally turn off MIPS16 and microMIPS code generation. This attribute
5137 overrides the @option{-mips16} and @option{-mmicromips} options on the
5138 command line (@pxref{MIPS Options}).
5141 @node MSP430 Function Attributes
5142 @subsection MSP430 Function Attributes
5144 These function attributes are supported by the MSP430 back end:
5148 @cindex @code{critical} function attribute, MSP430
5149 Critical functions disable interrupts upon entry and restore the
5150 previous interrupt state upon exit. Critical functions cannot also
5151 have the @code{naked}, @code{reentrant} or @code{interrupt} attributes.
5153 The MSP430 hardware ensures that interrupts are disabled on entry to
5154 @code{interrupt} functions, and restores the previous interrupt state
5155 on exit. The @code{critical} attribute is therefore redundant on
5156 @code{interrupt} functions.
5159 @cindex @code{interrupt} function attribute, MSP430
5160 Use this attribute to indicate
5161 that the specified function is an interrupt handler. The compiler generates
5162 function entry and exit sequences suitable for use in an interrupt handler
5163 when this attribute is present.
5165 You can provide an argument to the interrupt
5166 attribute which specifies a name or number. If the argument is a
5167 number it indicates the slot in the interrupt vector table (0 - 31) to
5168 which this handler should be assigned. If the argument is a name it
5169 is treated as a symbolic name for the vector slot. These names should
5170 match up with appropriate entries in the linker script. By default
5171 the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
5172 @code{reset} for vector 31 are recognized.
5175 @cindex @code{naked} function attribute, MSP430
5176 This attribute allows the compiler to construct the
5177 requisite function declaration, while allowing the body of the
5178 function to be assembly code. The specified function will not have
5179 prologue/epilogue sequences generated by the compiler. Only basic
5180 @code{asm} statements can safely be included in naked functions
5181 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5182 basic @code{asm} and C code may appear to work, they cannot be
5183 depended upon to work reliably and are not supported.
5186 @cindex @code{reentrant} function attribute, MSP430
5187 Reentrant functions disable interrupts upon entry and enable them
5188 upon exit. Reentrant functions cannot also have the @code{naked}
5189 or @code{critical} attributes. They can have the @code{interrupt}
5193 @cindex @code{wakeup} function attribute, MSP430
5194 This attribute only applies to interrupt functions. It is silently
5195 ignored if applied to a non-interrupt function. A wakeup interrupt
5196 function will rouse the processor from any low-power state that it
5197 might be in when the function exits.
5202 @cindex @code{lower} function attribute, MSP430
5203 @cindex @code{upper} function attribute, MSP430
5204 @cindex @code{either} function attribute, MSP430
5205 On the MSP430 target these attributes can be used to specify whether
5206 the function or variable should be placed into low memory, high
5207 memory, or the placement should be left to the linker to decide. The
5208 attributes are only significant if compiling for the MSP430X
5211 The attributes work in conjunction with a linker script that has been
5212 augmented to specify where to place sections with a @code{.lower} and
5213 a @code{.upper} prefix. So, for example, as well as placing the
5214 @code{.data} section, the script also specifies the placement of a
5215 @code{.lower.data} and a @code{.upper.data} section. The intention
5216 is that @code{lower} sections are placed into a small but easier to
5217 access memory region and the upper sections are placed into a larger, but
5218 slower to access, region.
5220 The @code{either} attribute is special. It tells the linker to place
5221 the object into the corresponding @code{lower} section if there is
5222 room for it. If there is insufficient room then the object is placed
5223 into the corresponding @code{upper} section instead. Note that the
5224 placement algorithm is not very sophisticated. It does not attempt to
5225 find an optimal packing of the @code{lower} sections. It just makes
5226 one pass over the objects and does the best that it can. Using the
5227 @option{-ffunction-sections} and @option{-fdata-sections} command-line
5228 options can help the packing, however, since they produce smaller,
5229 easier to pack regions.
5232 @node NDS32 Function Attributes
5233 @subsection NDS32 Function Attributes
5235 These function attributes are supported by the NDS32 back end:
5239 @cindex @code{exception} function attribute
5240 @cindex exception handler functions, NDS32
5241 Use this attribute on the NDS32 target to indicate that the specified function
5242 is an exception handler. The compiler will generate corresponding sections
5243 for use in an exception handler.
5246 @cindex @code{interrupt} function attribute, NDS32
5247 On NDS32 target, this attribute indicates that the specified function
5248 is an interrupt handler. The compiler generates corresponding sections
5249 for use in an interrupt handler. You can use the following attributes
5250 to modify the behavior:
5253 @cindex @code{nested} function attribute, NDS32
5254 This interrupt service routine is interruptible.
5256 @cindex @code{not_nested} function attribute, NDS32
5257 This interrupt service routine is not interruptible.
5259 @cindex @code{nested_ready} function attribute, NDS32
5260 This interrupt service routine is interruptible after @code{PSW.GIE}
5261 (global interrupt enable) is set. This allows interrupt service routine to
5262 finish some short critical code before enabling interrupts.
5264 @cindex @code{save_all} function attribute, NDS32
5265 The system will help save all registers into stack before entering
5268 @cindex @code{partial_save} function attribute, NDS32
5269 The system will help save caller registers into stack before entering
5274 @cindex @code{naked} function attribute, NDS32
5275 This attribute allows the compiler to construct the
5276 requisite function declaration, while allowing the body of the
5277 function to be assembly code. The specified function will not have
5278 prologue/epilogue sequences generated by the compiler. Only basic
5279 @code{asm} statements can safely be included in naked functions
5280 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5281 basic @code{asm} and C code may appear to work, they cannot be
5282 depended upon to work reliably and are not supported.
5285 @cindex @code{reset} function attribute, NDS32
5286 @cindex reset handler functions
5287 Use this attribute on the NDS32 target to indicate that the specified function
5288 is a reset handler. The compiler will generate corresponding sections
5289 for use in a reset handler. You can use the following attributes
5290 to provide extra exception handling:
5293 @cindex @code{nmi} function attribute, NDS32
5294 Provide a user-defined function to handle NMI exception.
5296 @cindex @code{warm} function attribute, NDS32
5297 Provide a user-defined function to handle warm reset exception.
5301 @node Nios II Function Attributes
5302 @subsection Nios II Function Attributes
5304 These function attributes are supported by the Nios II back end:
5307 @item target (@var{options})
5308 @cindex @code{target} function attribute
5309 As discussed in @ref{Common Function Attributes}, this attribute
5310 allows specification of target-specific compilation options.
5312 When compiling for Nios II, the following options are allowed:
5315 @item custom-@var{insn}=@var{N}
5316 @itemx no-custom-@var{insn}
5317 @cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II
5318 @cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II
5319 Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a
5320 custom instruction with encoding @var{N} when generating code that uses
5321 @var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of
5322 the custom instruction @var{insn}.
5323 These target attributes correspond to the
5324 @option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}}
5325 command-line options, and support the same set of @var{insn} keywords.
5326 @xref{Nios II Options}, for more information.
5328 @item custom-fpu-cfg=@var{name}
5329 @cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II
5330 This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}}
5331 command-line option, to select a predefined set of custom instructions
5333 @xref{Nios II Options}, for more information.
5337 @node Nvidia PTX Function Attributes
5338 @subsection Nvidia PTX Function Attributes
5340 These function attributes are supported by the Nvidia PTX back end:
5344 @cindex @code{kernel} attribute, Nvidia PTX
5345 This attribute indicates that the corresponding function should be compiled
5346 as a kernel function, which can be invoked from the host via the CUDA RT
5348 By default functions are only callable only from other PTX functions.
5350 Kernel functions must have @code{void} return type.
5353 @node PowerPC Function Attributes
5354 @subsection PowerPC Function Attributes
5356 These function attributes are supported by the PowerPC back end:
5361 @cindex indirect calls, PowerPC
5362 @cindex @code{longcall} function attribute, PowerPC
5363 @cindex @code{shortcall} function attribute, PowerPC
5364 The @code{longcall} attribute
5365 indicates that the function might be far away from the call site and
5366 require a different (more expensive) calling sequence. The
5367 @code{shortcall} attribute indicates that the function is always close
5368 enough for the shorter calling sequence to be used. These attributes
5369 override both the @option{-mlongcall} switch and
5370 the @code{#pragma longcall} setting.
5372 @xref{RS/6000 and PowerPC Options}, for more information on whether long
5373 calls are necessary.
5375 @item target (@var{options})
5376 @cindex @code{target} function attribute
5377 As discussed in @ref{Common Function Attributes}, this attribute
5378 allows specification of target-specific compilation options.
5380 On the PowerPC, the following options are allowed:
5385 @cindex @code{target("altivec")} function attribute, PowerPC
5386 Generate code that uses (does not use) AltiVec instructions. In
5387 32-bit code, you cannot enable AltiVec instructions unless
5388 @option{-mabi=altivec} is used on the command line.
5392 @cindex @code{target("cmpb")} function attribute, PowerPC
5393 Generate code that uses (does not use) the compare bytes instruction
5394 implemented on the POWER6 processor and other processors that support
5395 the PowerPC V2.05 architecture.
5399 @cindex @code{target("dlmzb")} function attribute, PowerPC
5400 Generate code that uses (does not use) the string-search @samp{dlmzb}
5401 instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
5402 generated by default when targeting those processors.
5406 @cindex @code{target("fprnd")} function attribute, PowerPC
5407 Generate code that uses (does not use) the FP round to integer
5408 instructions implemented on the POWER5+ processor and other processors
5409 that support the PowerPC V2.03 architecture.
5413 @cindex @code{target("hard-dfp")} function attribute, PowerPC
5414 Generate code that uses (does not use) the decimal floating-point
5415 instructions implemented on some POWER processors.
5419 @cindex @code{target("isel")} function attribute, PowerPC
5420 Generate code that uses (does not use) ISEL instruction.
5424 @cindex @code{target("mfcrf")} function attribute, PowerPC
5425 Generate code that uses (does not use) the move from condition
5426 register field instruction implemented on the POWER4 processor and
5427 other processors that support the PowerPC V2.01 architecture.
5431 @cindex @code{target("mulhw")} function attribute, PowerPC
5432 Generate code that uses (does not use) the half-word multiply and
5433 multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
5434 These instructions are generated by default when targeting those
5439 @cindex @code{target("multiple")} function attribute, PowerPC
5440 Generate code that uses (does not use) the load multiple word
5441 instructions and the store multiple word instructions.
5445 @cindex @code{target("update")} function attribute, PowerPC
5446 Generate code that uses (does not use) the load or store instructions
5447 that update the base register to the address of the calculated memory
5452 @cindex @code{target("popcntb")} function attribute, PowerPC
5453 Generate code that uses (does not use) the popcount and double-precision
5454 FP reciprocal estimate instruction implemented on the POWER5
5455 processor and other processors that support the PowerPC V2.02
5460 @cindex @code{target("popcntd")} function attribute, PowerPC
5461 Generate code that uses (does not use) the popcount instruction
5462 implemented on the POWER7 processor and other processors that support
5463 the PowerPC V2.06 architecture.
5465 @item powerpc-gfxopt
5466 @itemx no-powerpc-gfxopt
5467 @cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
5468 Generate code that uses (does not use) the optional PowerPC
5469 architecture instructions in the Graphics group, including
5470 floating-point select.
5473 @itemx no-powerpc-gpopt
5474 @cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
5475 Generate code that uses (does not use) the optional PowerPC
5476 architecture instructions in the General Purpose group, including
5477 floating-point square root.
5479 @item recip-precision
5480 @itemx no-recip-precision
5481 @cindex @code{target("recip-precision")} function attribute, PowerPC
5482 Assume (do not assume) that the reciprocal estimate instructions
5483 provide higher-precision estimates than is mandated by the PowerPC
5488 @cindex @code{target("string")} function attribute, PowerPC
5489 Generate code that uses (does not use) the load string instructions
5490 and the store string word instructions to save multiple registers and
5491 do small block moves.
5495 @cindex @code{target("vsx")} function attribute, PowerPC
5496 Generate code that uses (does not use) vector/scalar (VSX)
5497 instructions, and also enable the use of built-in functions that allow
5498 more direct access to the VSX instruction set. In 32-bit code, you
5499 cannot enable VSX or AltiVec instructions unless
5500 @option{-mabi=altivec} is used on the command line.
5504 @cindex @code{target("friz")} function attribute, PowerPC
5505 Generate (do not generate) the @code{friz} instruction when the
5506 @option{-funsafe-math-optimizations} option is used to optimize
5507 rounding a floating-point value to 64-bit integer and back to floating
5508 point. The @code{friz} instruction does not return the same value if
5509 the floating-point number is too large to fit in an integer.
5511 @item avoid-indexed-addresses
5512 @itemx no-avoid-indexed-addresses
5513 @cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
5514 Generate code that tries to avoid (not avoid) the use of indexed load
5515 or store instructions.
5519 @cindex @code{target("paired")} function attribute, PowerPC
5520 Generate code that uses (does not use) the generation of PAIRED simd
5525 @cindex @code{target("longcall")} function attribute, PowerPC
5526 Generate code that assumes (does not assume) that all calls are far
5527 away so that a longer more expensive calling sequence is required.
5530 @cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
5531 Specify the architecture to generate code for when compiling the
5532 function. If you select the @code{target("cpu=power7")} attribute when
5533 generating 32-bit code, VSX and AltiVec instructions are not generated
5534 unless you use the @option{-mabi=altivec} option on the command line.
5536 @item tune=@var{TUNE}
5537 @cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
5538 Specify the architecture to tune for when compiling the function. If
5539 you do not specify the @code{target("tune=@var{TUNE}")} attribute and
5540 you do specify the @code{target("cpu=@var{CPU}")} attribute,
5541 compilation tunes for the @var{CPU} architecture, and not the
5542 default tuning specified on the command line.
5545 On the PowerPC, the inliner does not inline a
5546 function that has different target options than the caller, unless the
5547 callee has a subset of the target options of the caller.
5550 @node RISC-V Function Attributes
5551 @subsection RISC-V Function Attributes
5553 These function attributes are supported by the RISC-V back end:
5557 @cindex @code{naked} function attribute, RISC-V
5558 This attribute allows the compiler to construct the
5559 requisite function declaration, while allowing the body of the
5560 function to be assembly code. The specified function will not have
5561 prologue/epilogue sequences generated by the compiler. Only basic
5562 @code{asm} statements can safely be included in naked functions
5563 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5564 basic @code{asm} and C code may appear to work, they cannot be
5565 depended upon to work reliably and are not supported.
5568 @cindex @code{interrupt} function attribute, RISC-V
5569 Use this attribute to indicate that the specified function is an interrupt
5570 handler. The compiler generates function entry and exit sequences suitable
5571 for use in an interrupt handler when this attribute is present.
5573 You can specify the kind of interrupt to be handled by adding an optional
5574 parameter to the interrupt attribute like this:
5577 void f (void) __attribute__ ((interrupt ("user")));
5580 Permissible values for this parameter are @code{user}, @code{supervisor},
5581 and @code{machine}. If there is no parameter, then it defaults to
5585 @node RL78 Function Attributes
5586 @subsection RL78 Function Attributes
5588 These function attributes are supported by the RL78 back end:
5592 @itemx brk_interrupt
5593 @cindex @code{interrupt} function attribute, RL78
5594 @cindex @code{brk_interrupt} function attribute, RL78
5595 These attributes indicate
5596 that the specified function is an interrupt handler. The compiler generates
5597 function entry and exit sequences suitable for use in an interrupt handler
5598 when this attribute is present.
5600 Use @code{brk_interrupt} instead of @code{interrupt} for
5601 handlers intended to be used with the @code{BRK} opcode (i.e.@: those
5602 that must end with @code{RETB} instead of @code{RETI}).
5605 @cindex @code{naked} function attribute, RL78
5606 This attribute allows the compiler to construct the
5607 requisite function declaration, while allowing the body of the
5608 function to be assembly code. The specified function will not have
5609 prologue/epilogue sequences generated by the compiler. Only basic
5610 @code{asm} statements can safely be included in naked functions
5611 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5612 basic @code{asm} and C code may appear to work, they cannot be
5613 depended upon to work reliably and are not supported.
5616 @node RX Function Attributes
5617 @subsection RX Function Attributes
5619 These function attributes are supported by the RX back end:
5622 @item fast_interrupt
5623 @cindex @code{fast_interrupt} function attribute, RX
5624 Use this attribute on the RX port to indicate that the specified
5625 function is a fast interrupt handler. This is just like the
5626 @code{interrupt} attribute, except that @code{freit} is used to return
5627 instead of @code{reit}.
5630 @cindex @code{interrupt} function attribute, RX
5631 Use this attribute to indicate
5632 that the specified function is an interrupt handler. The compiler generates
5633 function entry and exit sequences suitable for use in an interrupt handler
5634 when this attribute is present.
5636 On RX and RL78 targets, you may specify one or more vector numbers as arguments
5637 to the attribute, as well as naming an alternate table name.
5638 Parameters are handled sequentially, so one handler can be assigned to
5639 multiple entries in multiple tables. One may also pass the magic
5640 string @code{"$default"} which causes the function to be used for any
5641 unfilled slots in the current table.
5643 This example shows a simple assignment of a function to one vector in
5644 the default table (note that preprocessor macros may be used for
5645 chip-specific symbolic vector names):
5647 void __attribute__ ((interrupt (5))) txd1_handler ();
5650 This example assigns a function to two slots in the default table
5651 (using preprocessor macros defined elsewhere) and makes it the default
5652 for the @code{dct} table:
5654 void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
5659 @cindex @code{naked} function attribute, RX
5660 This attribute allows the compiler to construct the
5661 requisite function declaration, while allowing the body of the
5662 function to be assembly code. The specified function will not have
5663 prologue/epilogue sequences generated by the compiler. Only basic
5664 @code{asm} statements can safely be included in naked functions
5665 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5666 basic @code{asm} and C code may appear to work, they cannot be
5667 depended upon to work reliably and are not supported.
5670 @cindex @code{vector} function attribute, RX
5671 This RX attribute is similar to the @code{interrupt} attribute, including its
5672 parameters, but does not make the function an interrupt-handler type
5673 function (i.e.@: it retains the normal C function calling ABI). See the
5674 @code{interrupt} attribute for a description of its arguments.
5677 @node S/390 Function Attributes
5678 @subsection S/390 Function Attributes
5680 These function attributes are supported on the S/390:
5683 @item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
5684 @cindex @code{hotpatch} function attribute, S/390
5686 On S/390 System z targets, you can use this function attribute to
5687 make GCC generate a ``hot-patching'' function prologue. If the
5688 @option{-mhotpatch=} command-line option is used at the same time,
5689 the @code{hotpatch} attribute takes precedence. The first of the
5690 two arguments specifies the number of halfwords to be added before
5691 the function label. A second argument can be used to specify the
5692 number of halfwords to be added after the function label. For
5693 both arguments the maximum allowed value is 1000000.
5695 If both arguments are zero, hotpatching is disabled.
5697 @item target (@var{options})
5698 @cindex @code{target} function attribute
5699 As discussed in @ref{Common Function Attributes}, this attribute
5700 allows specification of target-specific compilation options.
5702 On S/390, the following options are supported:
5710 @item warn-framesize=
5722 @itemx no-packed-stack
5724 @itemx no-small-exec
5727 @item warn-dynamicstack
5728 @itemx no-warn-dynamicstack
5731 The options work exactly like the S/390 specific command line
5732 options (without the prefix @option{-m}) except that they do not
5733 change any feature macros. For example,
5736 @code{target("no-vx")}
5739 does not undefine the @code{__VEC__} macro.
5742 @node SH Function Attributes
5743 @subsection SH Function Attributes
5745 These function attributes are supported on the SH family of processors:
5748 @item function_vector
5749 @cindex @code{function_vector} function attribute, SH
5750 @cindex calling functions through the function vector on SH2A
5751 On SH2A targets, this attribute declares a function to be called using the
5752 TBR relative addressing mode. The argument to this attribute is the entry
5753 number of the same function in a vector table containing all the TBR
5754 relative addressable functions. For correct operation the TBR must be setup
5755 accordingly to point to the start of the vector table before any functions with
5756 this attribute are invoked. Usually a good place to do the initialization is
5757 the startup routine. The TBR relative vector table can have at max 256 function
5758 entries. The jumps to these functions are generated using a SH2A specific,
5759 non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD
5760 from GNU binutils version 2.7 or later for this attribute to work correctly.
5762 In an application, for a function being called once, this attribute
5763 saves at least 8 bytes of code; and if other successive calls are being
5764 made to the same function, it saves 2 bytes of code per each of these
5767 @item interrupt_handler
5768 @cindex @code{interrupt_handler} function attribute, SH
5769 Use this attribute to
5770 indicate that the specified function is an interrupt handler. The compiler
5771 generates function entry and exit sequences suitable for use in an
5772 interrupt handler when this attribute is present.
5774 @item nosave_low_regs
5775 @cindex @code{nosave_low_regs} function attribute, SH
5776 Use this attribute on SH targets to indicate that an @code{interrupt_handler}
5777 function should not save and restore registers R0..R7. This can be used on SH3*
5778 and SH4* targets that have a second R0..R7 register bank for non-reentrant
5782 @cindex @code{renesas} function attribute, SH
5783 On SH targets this attribute specifies that the function or struct follows the
5787 @cindex @code{resbank} function attribute, SH
5788 On the SH2A target, this attribute enables the high-speed register
5789 saving and restoration using a register bank for @code{interrupt_handler}
5790 routines. Saving to the bank is performed automatically after the CPU
5791 accepts an interrupt that uses a register bank.
5793 The nineteen 32-bit registers comprising general register R0 to R14,
5794 control register GBR, and system registers MACH, MACL, and PR and the
5795 vector table address offset are saved into a register bank. Register
5796 banks are stacked in first-in last-out (FILO) sequence. Restoration
5797 from the bank is executed by issuing a RESBANK instruction.
5800 @cindex @code{sp_switch} function attribute, SH
5801 Use this attribute on the SH to indicate an @code{interrupt_handler}
5802 function should switch to an alternate stack. It expects a string
5803 argument that names a global variable holding the address of the
5808 void f () __attribute__ ((interrupt_handler,
5809 sp_switch ("alt_stack")));
5813 @cindex @code{trap_exit} function attribute, SH
5814 Use this attribute on the SH for an @code{interrupt_handler} to return using
5815 @code{trapa} instead of @code{rte}. This attribute expects an integer
5816 argument specifying the trap number to be used.
5819 @cindex @code{trapa_handler} function attribute, SH
5820 On SH targets this function attribute is similar to @code{interrupt_handler}
5821 but it does not save and restore all registers.
5824 @node Symbian OS Function Attributes
5825 @subsection Symbian OS Function Attributes
5827 @xref{Microsoft Windows Function Attributes}, for discussion of the
5828 @code{dllexport} and @code{dllimport} attributes.
5830 @node V850 Function Attributes
5831 @subsection V850 Function Attributes
5833 The V850 back end supports these function attributes:
5837 @itemx interrupt_handler
5838 @cindex @code{interrupt} function attribute, V850
5839 @cindex @code{interrupt_handler} function attribute, V850
5840 Use these attributes to indicate
5841 that the specified function is an interrupt handler. The compiler generates
5842 function entry and exit sequences suitable for use in an interrupt handler
5843 when either attribute is present.
5846 @node Visium Function Attributes
5847 @subsection Visium Function Attributes
5849 These function attributes are supported by the Visium back end:
5853 @cindex @code{interrupt} function attribute, Visium
5854 Use this attribute to indicate
5855 that the specified function is an interrupt handler. The compiler generates
5856 function entry and exit sequences suitable for use in an interrupt handler
5857 when this attribute is present.
5860 @node x86 Function Attributes
5861 @subsection x86 Function Attributes
5863 These function attributes are supported by the x86 back end:
5867 @cindex @code{cdecl} function attribute, x86-32
5868 @cindex functions that pop the argument stack on x86-32
5870 On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
5871 assume that the calling function pops off the stack space used to
5872 pass arguments. This is
5873 useful to override the effects of the @option{-mrtd} switch.
5876 @cindex @code{fastcall} function attribute, x86-32
5877 @cindex functions that pop the argument stack on x86-32
5878 On x86-32 targets, the @code{fastcall} attribute causes the compiler to
5879 pass the first argument (if of integral type) in the register ECX and
5880 the second argument (if of integral type) in the register EDX@. Subsequent
5881 and other typed arguments are passed on the stack. The called function
5882 pops the arguments off the stack. If the number of arguments is variable all
5883 arguments are pushed on the stack.
5886 @cindex @code{thiscall} function attribute, x86-32
5887 @cindex functions that pop the argument stack on x86-32
5888 On x86-32 targets, the @code{thiscall} attribute causes the compiler to
5889 pass the first argument (if of integral type) in the register ECX.
5890 Subsequent and other typed arguments are passed on the stack. The called
5891 function pops the arguments off the stack.
5892 If the number of arguments is variable all arguments are pushed on the
5894 The @code{thiscall} attribute is intended for C++ non-static member functions.
5895 As a GCC extension, this calling convention can be used for C functions
5896 and for static member methods.
5900 @cindex @code{ms_abi} function attribute, x86
5901 @cindex @code{sysv_abi} function attribute, x86
5903 On 32-bit and 64-bit x86 targets, you can use an ABI attribute
5904 to indicate which calling convention should be used for a function. The
5905 @code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
5906 while the @code{sysv_abi} attribute tells the compiler to use the ABI
5907 used on GNU/Linux and other systems. The default is to use the Microsoft ABI
5908 when targeting Windows. On all other systems, the default is the x86/AMD ABI.
5910 Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
5911 requires the @option{-maccumulate-outgoing-args} option.
5913 @item callee_pop_aggregate_return (@var{number})
5914 @cindex @code{callee_pop_aggregate_return} function attribute, x86
5916 On x86-32 targets, you can use this attribute to control how
5917 aggregates are returned in memory. If the caller is responsible for
5918 popping the hidden pointer together with the rest of the arguments, specify
5919 @var{number} equal to zero. If callee is responsible for popping the
5920 hidden pointer, specify @var{number} equal to one.
5922 The default x86-32 ABI assumes that the callee pops the
5923 stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
5924 the compiler assumes that the
5925 caller pops the stack for hidden pointer.
5927 @item ms_hook_prologue
5928 @cindex @code{ms_hook_prologue} function attribute, x86
5930 On 32-bit and 64-bit x86 targets, you can use
5931 this function attribute to make GCC generate the ``hot-patching'' function
5932 prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
5936 @cindex @code{naked} function attribute, x86
5937 This attribute allows the compiler to construct the
5938 requisite function declaration, while allowing the body of the
5939 function to be assembly code. The specified function will not have
5940 prologue/epilogue sequences generated by the compiler. Only basic
5941 @code{asm} statements can safely be included in naked functions
5942 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5943 basic @code{asm} and C code may appear to work, they cannot be
5944 depended upon to work reliably and are not supported.
5946 @item regparm (@var{number})
5947 @cindex @code{regparm} function attribute, x86
5948 @cindex functions that are passed arguments in registers on x86-32
5949 On x86-32 targets, the @code{regparm} attribute causes the compiler to
5950 pass arguments number one to @var{number} if they are of integral type
5951 in registers EAX, EDX, and ECX instead of on the stack. Functions that
5952 take a variable number of arguments continue to be passed all of their
5953 arguments on the stack.
5955 Beware that on some ELF systems this attribute is unsuitable for
5956 global functions in shared libraries with lazy binding (which is the
5957 default). Lazy binding sends the first call via resolving code in
5958 the loader, which might assume EAX, EDX and ECX can be clobbered, as
5959 per the standard calling conventions. Solaris 8 is affected by this.
5960 Systems with the GNU C Library version 2.1 or higher
5961 and FreeBSD are believed to be
5962 safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
5963 disabled with the linker or the loader if desired, to avoid the
5967 @cindex @code{sseregparm} function attribute, x86
5968 On x86-32 targets with SSE support, the @code{sseregparm} attribute
5969 causes the compiler to pass up to 3 floating-point arguments in
5970 SSE registers instead of on the stack. Functions that take a
5971 variable number of arguments continue to pass all of their
5972 floating-point arguments on the stack.
5974 @item force_align_arg_pointer
5975 @cindex @code{force_align_arg_pointer} function attribute, x86
5976 On x86 targets, the @code{force_align_arg_pointer} attribute may be
5977 applied to individual function definitions, generating an alternate
5978 prologue and epilogue that realigns the run-time stack if necessary.
5979 This supports mixing legacy codes that run with a 4-byte aligned stack
5980 with modern codes that keep a 16-byte stack for SSE compatibility.
5983 @cindex @code{stdcall} function attribute, x86-32
5984 @cindex functions that pop the argument stack on x86-32
5985 On x86-32 targets, the @code{stdcall} attribute causes the compiler to
5986 assume that the called function pops off the stack space used to
5987 pass arguments, unless it takes a variable number of arguments.
5989 @item no_caller_saved_registers
5990 @cindex @code{no_caller_saved_registers} function attribute, x86
5991 Use this attribute to indicate that the specified function has no
5992 caller-saved registers. That is, all registers are callee-saved. For
5993 example, this attribute can be used for a function called from an
5994 interrupt handler. The compiler generates proper function entry and
5995 exit sequences to save and restore any modified registers, except for
5996 the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87
5997 states, the GCC option @option{-mgeneral-regs-only} should be used to
5998 compile functions with @code{no_caller_saved_registers} attribute.
6001 @cindex @code{interrupt} function attribute, x86
6002 Use this attribute to indicate that the specified function is an
6003 interrupt handler or an exception handler (depending on parameters passed
6004 to the function, explained further). The compiler generates function
6005 entry and exit sequences suitable for use in an interrupt handler when
6006 this attribute is present. The @code{IRET} instruction, instead of the
6007 @code{RET} instruction, is used to return from interrupt handlers. All
6008 registers, except for the EFLAGS register which is restored by the
6009 @code{IRET} instruction, are preserved by the compiler. Since GCC
6010 doesn't preserve SSE, MMX nor x87 states, the GCC option
6011 @option{-mgeneral-regs-only} should be used to compile interrupt and
6014 Any interruptible-without-stack-switch code must be compiled with
6015 @option{-mno-red-zone} since interrupt handlers can and will, because
6016 of the hardware design, touch the red zone.
6018 An interrupt handler must be declared with a mandatory pointer
6022 struct interrupt_frame;
6024 __attribute__ ((interrupt))
6026 f (struct interrupt_frame *frame)
6032 and you must define @code{struct interrupt_frame} as described in the
6035 Exception handlers differ from interrupt handlers because the system
6036 pushes an error code on the stack. An exception handler declaration is
6037 similar to that for an interrupt handler, but with a different mandatory
6038 function signature. The compiler arranges to pop the error code off the
6039 stack before the @code{IRET} instruction.
6043 typedef unsigned long long int uword_t;
6045 typedef unsigned int uword_t;
6048 struct interrupt_frame;
6050 __attribute__ ((interrupt))
6052 f (struct interrupt_frame *frame, uword_t error_code)
6058 Exception handlers should only be used for exceptions that push an error
6059 code; you should use an interrupt handler in other cases. The system
6060 will crash if the wrong kind of handler is used.
6062 @item target (@var{options})
6063 @cindex @code{target} function attribute
6064 As discussed in @ref{Common Function Attributes}, this attribute
6065 allows specification of target-specific compilation options.
6067 On the x86, the following options are allowed:
6071 @cindex @code{target("3dnow")} function attribute, x86
6072 Enable/disable the generation of the 3DNow!@: instructions.
6076 @cindex @code{target("3dnowa")} function attribute, x86
6077 Enable/disable the generation of the enhanced 3DNow!@: instructions.
6081 @cindex @code{target("abm")} function attribute, x86
6082 Enable/disable the generation of the advanced bit instructions.
6086 @cindex @code{target("adx")} function attribute, x86
6087 Enable/disable the generation of the ADX instructions.
6091 @cindex @code{target("aes")} function attribute, x86
6092 Enable/disable the generation of the AES instructions.
6096 @cindex @code{target("avx")} function attribute, x86
6097 Enable/disable the generation of the AVX instructions.
6101 @cindex @code{target("avx2")} function attribute, x86
6102 Enable/disable the generation of the AVX2 instructions.
6105 @itemx no-avx5124fmaps
6106 @cindex @code{target("avx5124fmaps")} function attribute, x86
6107 Enable/disable the generation of the AVX5124FMAPS instructions.
6110 @itemx no-avx5124vnniw
6111 @cindex @code{target("avx5124vnniw")} function attribute, x86
6112 Enable/disable the generation of the AVX5124VNNIW instructions.
6115 @itemx no-avx512bitalg
6116 @cindex @code{target("avx512bitalg")} function attribute, x86
6117 Enable/disable the generation of the AVX512BITALG instructions.
6121 @cindex @code{target("avx512bw")} function attribute, x86
6122 Enable/disable the generation of the AVX512BW instructions.
6126 @cindex @code{target("avx512cd")} function attribute, x86
6127 Enable/disable the generation of the AVX512CD instructions.
6131 @cindex @code{target("avx512dq")} function attribute, x86
6132 Enable/disable the generation of the AVX512DQ instructions.
6136 @cindex @code{target("avx512er")} function attribute, x86
6137 Enable/disable the generation of the AVX512ER instructions.
6141 @cindex @code{target("avx512f")} function attribute, x86
6142 Enable/disable the generation of the AVX512F instructions.
6145 @itemx no-avx512ifma
6146 @cindex @code{target("avx512ifma")} function attribute, x86
6147 Enable/disable the generation of the AVX512IFMA instructions.
6151 @cindex @code{target("avx512pf")} function attribute, x86
6152 Enable/disable the generation of the AVX512PF instructions.
6155 @itemx no-avx512vbmi
6156 @cindex @code{target("avx512vbmi")} function attribute, x86
6157 Enable/disable the generation of the AVX512VBMI instructions.
6160 @itemx no-avx512vbmi2
6161 @cindex @code{target("avx512vbmi2")} function attribute, x86
6162 Enable/disable the generation of the AVX512VBMI2 instructions.
6166 @cindex @code{target("avx512vl")} function attribute, x86
6167 Enable/disable the generation of the AVX512VL instructions.
6170 @itemx no-avx512vnni
6171 @cindex @code{target("avx512vnni")} function attribute, x86
6172 Enable/disable the generation of the AVX512VNNI instructions.
6174 @item avx512vpopcntdq
6175 @itemx no-avx512vpopcntdq
6176 @cindex @code{target("avx512vpopcntdq")} function attribute, x86
6177 Enable/disable the generation of the AVX512VPOPCNTDQ instructions.
6181 @cindex @code{target("bmi")} function attribute, x86
6182 Enable/disable the generation of the BMI instructions.
6186 @cindex @code{target("bmi2")} function attribute, x86
6187 Enable/disable the generation of the BMI2 instructions.
6191 @cindex @code{target("cldemote")} function attribute, x86
6192 Enable/disable the generation of the CLDEMOTE instructions.
6195 @itemx no-clflushopt
6196 @cindex @code{target("clflushopt")} function attribute, x86
6197 Enable/disable the generation of the CLFLUSHOPT instructions.
6201 @cindex @code{target("clwb")} function attribute, x86
6202 Enable/disable the generation of the CLWB instructions.
6206 @cindex @code{target("clzero")} function attribute, x86
6207 Enable/disable the generation of the CLZERO instructions.
6211 @cindex @code{target("crc32")} function attribute, x86
6212 Enable/disable the generation of the CRC32 instructions.
6216 @cindex @code{target("cx16")} function attribute, x86
6217 Enable/disable the generation of the CMPXCHG16B instructions.
6220 @cindex @code{target("default")} function attribute, x86
6221 @xref{Function Multiversioning}, where it is used to specify the
6222 default function version.
6226 @cindex @code{target("f16c")} function attribute, x86
6227 Enable/disable the generation of the F16C instructions.
6231 @cindex @code{target("fma")} function attribute, x86
6232 Enable/disable the generation of the FMA instructions.
6236 @cindex @code{target("fma4")} function attribute, x86
6237 Enable/disable the generation of the FMA4 instructions.
6241 @cindex @code{target("fsgsbase")} function attribute, x86
6242 Enable/disable the generation of the FSGSBASE instructions.
6246 @cindex @code{target("fxsr")} function attribute, x86
6247 Enable/disable the generation of the FXSR instructions.
6251 @cindex @code{target("gfni")} function attribute, x86
6252 Enable/disable the generation of the GFNI instructions.
6256 @cindex @code{target("hle")} function attribute, x86
6257 Enable/disable the generation of the HLE instruction prefixes.
6261 @cindex @code{target("lwp")} function attribute, x86
6262 Enable/disable the generation of the LWP instructions.
6266 @cindex @code{target("lzcnt")} function attribute, x86
6267 Enable/disable the generation of the LZCNT instructions.
6271 @cindex @code{target("mmx")} function attribute, x86
6272 Enable/disable the generation of the MMX instructions.
6276 @cindex @code{target("movbe")} function attribute, x86
6277 Enable/disable the generation of the MOVBE instructions.
6281 @cindex @code{target("movdir64b")} function attribute, x86
6282 Enable/disable the generation of the MOVDIR64B instructions.
6286 @cindex @code{target("movdiri")} function attribute, x86
6287 Enable/disable the generation of the MOVDIRI instructions.
6291 @cindex @code{target("mwaitx")} function attribute, x86
6292 Enable/disable the generation of the MWAITX instructions.
6296 @cindex @code{target("pclmul")} function attribute, x86
6297 Enable/disable the generation of the PCLMUL instructions.
6301 @cindex @code{target("pconfig")} function attribute, x86
6302 Enable/disable the generation of the PCONFIG instructions.
6306 @cindex @code{target("pku")} function attribute, x86
6307 Enable/disable the generation of the PKU instructions.
6311 @cindex @code{target("popcnt")} function attribute, x86
6312 Enable/disable the generation of the POPCNT instruction.
6315 @itemx no-prefetchwt1
6316 @cindex @code{target("prefetchwt1")} function attribute, x86
6317 Enable/disable the generation of the PREFETCHWT1 instructions.
6321 @cindex @code{target("prfchw")} function attribute, x86
6322 Enable/disable the generation of the PREFETCHW instruction.
6326 @cindex @code{target("ptwrite")} function attribute, x86
6327 Enable/disable the generation of the PTWRITE instructions.
6331 @cindex @code{target("rdpid")} function attribute, x86
6332 Enable/disable the generation of the RDPID instructions.
6336 @cindex @code{target("rdrnd")} function attribute, x86
6337 Enable/disable the generation of the RDRND instructions.
6341 @cindex @code{target("rdseed")} function attribute, x86
6342 Enable/disable the generation of the RDSEED instructions.
6346 @cindex @code{target("rtm")} function attribute, x86
6347 Enable/disable the generation of the RTM instructions.
6351 @cindex @code{target("sahf")} function attribute, x86
6352 Enable/disable the generation of the SAHF instructions.
6356 @cindex @code{target("sgx")} function attribute, x86
6357 Enable/disable the generation of the SGX instructions.
6361 @cindex @code{target("sha")} function attribute, x86
6362 Enable/disable the generation of the SHA instructions.
6366 @cindex @code{target("shstk")} function attribute, x86
6367 Enable/disable the shadow stack built-in functions from CET.
6371 @cindex @code{target("sse")} function attribute, x86
6372 Enable/disable the generation of the SSE instructions.
6376 @cindex @code{target("sse2")} function attribute, x86
6377 Enable/disable the generation of the SSE2 instructions.
6381 @cindex @code{target("sse3")} function attribute, x86
6382 Enable/disable the generation of the SSE3 instructions.
6386 @cindex @code{target("sse4")} function attribute, x86
6387 Enable/disable the generation of the SSE4 instructions (both SSE4.1
6392 @cindex @code{target("sse4.1")} function attribute, x86
6393 Enable/disable the generation of the sse4.1 instructions.
6397 @cindex @code{target("sse4.2")} function attribute, x86
6398 Enable/disable the generation of the sse4.2 instructions.
6402 @cindex @code{target("sse4a")} function attribute, x86
6403 Enable/disable the generation of the SSE4A instructions.
6407 @cindex @code{target("ssse3")} function attribute, x86
6408 Enable/disable the generation of the SSSE3 instructions.
6412 @cindex @code{target("tbm")} function attribute, x86
6413 Enable/disable the generation of the TBM instructions.
6417 @cindex @code{target("vaes")} function attribute, x86
6418 Enable/disable the generation of the VAES instructions.
6421 @itemx no-vpclmulqdq
6422 @cindex @code{target("vpclmulqdq")} function attribute, x86
6423 Enable/disable the generation of the VPCLMULQDQ instructions.
6427 @cindex @code{target("waitpkg")} function attribute, x86
6428 Enable/disable the generation of the WAITPKG instructions.
6432 @cindex @code{target("wbnoinvd")} function attribute, x86
6433 Enable/disable the generation of the WBNOINVD instructions.
6437 @cindex @code{target("xop")} function attribute, x86
6438 Enable/disable the generation of the XOP instructions.
6442 @cindex @code{target("xsave")} function attribute, x86
6443 Enable/disable the generation of the XSAVE instructions.
6447 @cindex @code{target("xsavec")} function attribute, x86
6448 Enable/disable the generation of the XSAVEC instructions.
6452 @cindex @code{target("xsaveopt")} function attribute, x86
6453 Enable/disable the generation of the XSAVEOPT instructions.
6457 @cindex @code{target("xsaves")} function attribute, x86
6458 Enable/disable the generation of the XSAVES instructions.
6462 @cindex @code{target("cld")} function attribute, x86
6463 Enable/disable the generation of the CLD before string moves.
6465 @item fancy-math-387
6466 @itemx no-fancy-math-387
6467 @cindex @code{target("fancy-math-387")} function attribute, x86
6468 Enable/disable the generation of the @code{sin}, @code{cos}, and
6469 @code{sqrt} instructions on the 387 floating-point unit.
6473 @cindex @code{target("ieee-fp")} function attribute, x86
6474 Enable/disable the generation of floating point that depends on IEEE arithmetic.
6476 @item inline-all-stringops
6477 @itemx no-inline-all-stringops
6478 @cindex @code{target("inline-all-stringops")} function attribute, x86
6479 Enable/disable inlining of string operations.
6481 @item inline-stringops-dynamically
6482 @itemx no-inline-stringops-dynamically
6483 @cindex @code{target("inline-stringops-dynamically")} function attribute, x86
6484 Enable/disable the generation of the inline code to do small string
6485 operations and calling the library routines for large operations.
6487 @item align-stringops
6488 @itemx no-align-stringops
6489 @cindex @code{target("align-stringops")} function attribute, x86
6490 Do/do not align destination of inlined string operations.
6494 @cindex @code{target("recip")} function attribute, x86
6495 Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
6496 instructions followed an additional Newton-Raphson step instead of
6497 doing a floating-point division.
6499 @item arch=@var{ARCH}
6500 @cindex @code{target("arch=@var{ARCH}")} function attribute, x86
6501 Specify the architecture to generate code for in compiling the function.
6503 @item tune=@var{TUNE}
6504 @cindex @code{target("tune=@var{TUNE}")} function attribute, x86
6505 Specify the architecture to tune for in compiling the function.
6507 @item fpmath=@var{FPMATH}
6508 @cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
6509 Specify which floating-point unit to use. You must specify the
6510 @code{target("fpmath=sse,387")} option as
6511 @code{target("fpmath=sse+387")} because the comma would separate
6514 @item indirect_branch("@var{choice}")
6515 @cindex @code{indirect_branch} function attribute, x86
6516 On x86 targets, the @code{indirect_branch} attribute causes the compiler
6517 to convert indirect call and jump with @var{choice}. @samp{keep}
6518 keeps indirect call and jump unmodified. @samp{thunk} converts indirect
6519 call and jump to call and return thunk. @samp{thunk-inline} converts
6520 indirect call and jump to inlined call and return thunk.
6521 @samp{thunk-extern} converts indirect call and jump to external call
6522 and return thunk provided in a separate object file.
6524 @item function_return("@var{choice}")
6525 @cindex @code{function_return} function attribute, x86
6526 On x86 targets, the @code{function_return} attribute causes the compiler
6527 to convert function return with @var{choice}. @samp{keep} keeps function
6528 return unmodified. @samp{thunk} converts function return to call and
6529 return thunk. @samp{thunk-inline} converts function return to inlined
6530 call and return thunk. @samp{thunk-extern} converts function return to
6531 external call and return thunk provided in a separate object file.
6534 @cindex @code{nocf_check} function attribute
6535 The @code{nocf_check} attribute on a function is used to inform the
6536 compiler that the function's prologue should not be instrumented when
6537 compiled with the @option{-fcf-protection=branch} option. The
6538 compiler assumes that the function's address is a valid target for a
6539 control-flow transfer.
6541 The @code{nocf_check} attribute on a type of pointer to function is
6542 used to inform the compiler that a call through the pointer should
6543 not be instrumented when compiled with the
6544 @option{-fcf-protection=branch} option. The compiler assumes
6545 that the function's address from the pointer is a valid target for
6546 a control-flow transfer. A direct function call through a function
6547 name is assumed to be a safe call thus direct calls are not
6548 instrumented by the compiler.
6550 The @code{nocf_check} attribute is applied to an object's type.
6551 In case of assignment of a function address or a function pointer to
6552 another pointer, the attribute is not carried over from the right-hand
6553 object's type; the type of left-hand object stays unchanged. The
6554 compiler checks for @code{nocf_check} attribute mismatch and reports
6555 a warning in case of mismatch.
6559 int foo (void) __attribute__(nocf_check);
6560 void (*foo1)(void) __attribute__(nocf_check);
6563 /* foo's address is assumed to be valid. */
6567 /* This call site is not checked for control-flow
6571 /* A warning is issued about attribute mismatch. */
6574 /* This call site is still not checked. */
6577 /* This call site is checked. */
6580 /* A warning is issued about attribute mismatch. */
6583 /* This call site is still checked. */
6591 @cindex @code{cf_check} function attribute, x86
6593 The @code{cf_check} attribute on a function is used to inform the
6594 compiler that ENDBR instruction should be placed at the function
6595 entry when @option{-fcf-protection=branch} is enabled.
6597 @item indirect_return
6598 @cindex @code{indirect_return} function attribute, x86
6600 The @code{indirect_return} attribute can be applied to a function,
6601 as well as variable or type of function pointer to inform the
6602 compiler that the function may return via indirect branch.
6604 @item fentry_name("@var{name}")
6605 @cindex @code{fentry_name} function attribute, x86
6606 On x86 targets, the @code{fentry_name} attribute sets the function to
6607 call on function entry when function instrumentation is enabled
6608 with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte
6609 nop sequence is generated.
6611 @item fentry_section("@var{name}")
6612 @cindex @code{fentry_section} function attribute, x86
6613 On x86 targets, the @code{fentry_section} attribute sets the name
6614 of the section to record function entry instrumentation calls in when
6615 enabled with @option{-pg -mrecord-mcount}
6619 On the x86, the inliner does not inline a
6620 function that has different target options than the caller, unless the
6621 callee has a subset of the target options of the caller. For example
6622 a function declared with @code{target("sse3")} can inline a function
6623 with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
6626 @node Xstormy16 Function Attributes
6627 @subsection Xstormy16 Function Attributes
6629 These function attributes are supported by the Xstormy16 back end:
6633 @cindex @code{interrupt} function attribute, Xstormy16
6634 Use this attribute to indicate
6635 that the specified function is an interrupt handler. The compiler generates
6636 function entry and exit sequences suitable for use in an interrupt handler
6637 when this attribute is present.
6640 @node Variable Attributes
6641 @section Specifying Attributes of Variables
6642 @cindex attribute of variables
6643 @cindex variable attributes
6645 The keyword @code{__attribute__} allows you to specify special properties
6646 of variables, function parameters, or structure, union, and, in C++, class
6647 members. This @code{__attribute__} keyword is followed by an attribute
6648 specification enclosed in double parentheses. Some attributes are currently
6649 defined generically for variables. Other attributes are defined for
6650 variables on particular target systems. Other attributes are available
6651 for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
6652 enumerators (@pxref{Enumerator Attributes}), statements
6653 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
6654 Other front ends might define more attributes
6655 (@pxref{C++ Extensions,,Extensions to the C++ Language}).
6657 @xref{Attribute Syntax}, for details of the exact syntax for using
6661 * Common Variable Attributes::
6662 * ARC Variable Attributes::
6663 * AVR Variable Attributes::
6664 * Blackfin Variable Attributes::
6665 * H8/300 Variable Attributes::
6666 * IA-64 Variable Attributes::
6667 * M32R/D Variable Attributes::
6668 * MeP Variable Attributes::
6669 * Microsoft Windows Variable Attributes::
6670 * MSP430 Variable Attributes::
6671 * Nvidia PTX Variable Attributes::
6672 * PowerPC Variable Attributes::
6673 * RL78 Variable Attributes::
6674 * V850 Variable Attributes::
6675 * x86 Variable Attributes::
6676 * Xstormy16 Variable Attributes::
6679 @node Common Variable Attributes
6680 @subsection Common Variable Attributes
6682 The following attributes are supported on most targets.
6686 @item alias ("@var{target}")
6687 @cindex @code{alias} variable attribute
6688 The @code{alias} variable attribute causes the declaration to be emitted
6689 as an alias for another symbol known as an @dfn{alias target}. Except
6690 for top-level qualifiers the alias target must have the same type as
6691 the alias. For instance, the following
6695 extern int __attribute__ ((alias ("var_target"))) var_alias;
6699 defines @code{var_alias} to be an alias for the @code{var_target} variable.
6701 It is an error if the alias target is not defined in the same translation
6704 Note that in the absence of the attribute GCC assumes that distinct
6705 declarations with external linkage denote distinct objects. Using both
6706 the alias and the alias target to access the same object is undefined
6707 in a translation unit without a declaration of the alias with the attribute.
6709 This attribute requires assembler and object file support, and may not be
6710 available on all targets.
6712 @cindex @code{aligned} variable attribute
6714 @itemx aligned (@var{alignment})
6715 The @code{aligned} attribute specifies a minimum alignment for the variable
6716 or structure field, measured in bytes. When specified, @var{alignment} must
6717 be an integer constant power of 2. Specifying no @var{alignment} argument
6718 implies the maximum alignment for the target, which is often, but by no
6719 means always, 8 or 16 bytes.
6721 For example, the declaration:
6724 int x __attribute__ ((aligned (16))) = 0;
6728 causes the compiler to allocate the global variable @code{x} on a
6729 16-byte boundary. On a 68040, this could be used in conjunction with
6730 an @code{asm} expression to access the @code{move16} instruction which
6731 requires 16-byte aligned operands.
6733 You can also specify the alignment of structure fields. For example, to
6734 create a double-word aligned @code{int} pair, you could write:
6737 struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
6741 This is an alternative to creating a union with a @code{double} member,
6742 which forces the union to be double-word aligned.
6744 As in the preceding examples, you can explicitly specify the alignment
6745 (in bytes) that you wish the compiler to use for a given variable or
6746 structure field. Alternatively, you can leave out the alignment factor
6747 and just ask the compiler to align a variable or field to the
6748 default alignment for the target architecture you are compiling for.
6749 The default alignment is sufficient for all scalar types, but may not be
6750 enough for all vector types on a target that supports vector operations.
6751 The default alignment is fixed for a particular target ABI.
6753 GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
6754 which is the largest alignment ever used for any data type on the
6755 target machine you are compiling for. For example, you could write:
6758 short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
6761 The compiler automatically sets the alignment for the declared
6762 variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
6763 often make copy operations more efficient, because the compiler can
6764 use whatever instructions copy the biggest chunks of memory when
6765 performing copies to or from the variables or fields that you have
6766 aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
6767 may change depending on command-line options.
6769 When used on a struct, or struct member, the @code{aligned} attribute can
6770 only increase the alignment; in order to decrease it, the @code{packed}
6771 attribute must be specified as well. When used as part of a typedef, the
6772 @code{aligned} attribute can both increase and decrease alignment, and
6773 specifying the @code{packed} attribute generates a warning.
6775 Note that the effectiveness of @code{aligned} attributes for static
6776 variables may be limited by inherent limitations in the system linker
6777 and/or object file format. On some systems, the linker is
6778 only able to arrange for variables to be aligned up to a certain maximum
6779 alignment. (For some linkers, the maximum supported alignment may
6780 be very very small.) If your linker is only able to align variables
6781 up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
6782 in an @code{__attribute__} still only provides you with 8-byte
6783 alignment. See your linker documentation for further information.
6785 Stack variables are not affected by linker restrictions; GCC can properly
6786 align them on any target.
6788 The @code{aligned} attribute can also be used for functions
6789 (@pxref{Common Function Attributes}.)
6791 @cindex @code{warn_if_not_aligned} variable attribute
6792 @item warn_if_not_aligned (@var{alignment})
6793 This attribute specifies a threshold for the structure field, measured
6794 in bytes. If the structure field is aligned below the threshold, a
6795 warning will be issued. For example, the declaration:
6802 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
6807 causes the compiler to issue an warning on @code{struct foo}, like
6808 @samp{warning: alignment 8 of 'struct foo' is less than 16}.
6809 The compiler also issues a warning, like @samp{warning: 'x' offset
6810 8 in 'struct foo' isn't aligned to 16}, when the structure field has
6811 the misaligned offset:
6814 struct __attribute__ ((aligned (16))) foo
6818 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
6822 This warning can be disabled by @option{-Wno-if-not-aligned}.
6823 The @code{warn_if_not_aligned} attribute can also be used for types
6824 (@pxref{Common Type Attributes}.)
6826 @item alloc_size (@var{position})
6827 @itemx alloc_size (@var{position-1}, @var{position-2})
6828 @cindex @code{alloc_size} variable attribute
6829 The @code{alloc_size} variable attribute may be applied to the declaration
6830 of a pointer to a function that returns a pointer and takes at least one
6831 argument of an integer type. It indicates that the returned pointer points
6832 to an object whose size is given by the function argument at @var{position-1},
6833 or by the product of the arguments at @var{position-1} and @var{position-2}.
6834 Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other
6835 sizes are disagnosed when detected. GCC uses this information to improve
6836 the results of @code{__builtin_object_size}.
6838 For instance, the following declarations
6841 typedef __attribute__ ((alloc_size (1, 2))) void*
6842 (*calloc_ptr) (size_t, size_t);
6843 typedef __attribute__ ((alloc_size (1))) void*
6844 (*malloc_ptr) (size_t);
6848 specify that @code{calloc_ptr} is a pointer of a function that, like
6849 the standard C function @code{calloc}, returns an object whose size
6850 is given by the product of arguments 1 and 2, and similarly, that
6851 @code{malloc_ptr}, like the standard C function @code{malloc},
6852 returns an object whose size is given by argument 1 to the function.
6854 @item cleanup (@var{cleanup_function})
6855 @cindex @code{cleanup} variable attribute
6856 The @code{cleanup} attribute runs a function when the variable goes
6857 out of scope. This attribute can only be applied to auto function
6858 scope variables; it may not be applied to parameters or variables
6859 with static storage duration. The function must take one parameter,
6860 a pointer to a type compatible with the variable. The return value
6861 of the function (if any) is ignored.
6863 If @option{-fexceptions} is enabled, then @var{cleanup_function}
6864 is run during the stack unwinding that happens during the
6865 processing of the exception. Note that the @code{cleanup} attribute
6866 does not allow the exception to be caught, only to perform an action.
6867 It is undefined what happens if @var{cleanup_function} does not
6872 @cindex @code{common} variable attribute
6873 @cindex @code{nocommon} variable attribute
6876 The @code{common} attribute requests GCC to place a variable in
6877 ``common'' storage. The @code{nocommon} attribute requests the
6878 opposite---to allocate space for it directly.
6880 These attributes override the default chosen by the
6881 @option{-fno-common} and @option{-fcommon} flags respectively.
6884 @itemx copy (@var{variable})
6885 @cindex @code{copy} variable attribute
6886 The @code{copy} attribute applies the set of attributes with which
6887 @var{variable} has been declared to the declaration of the variable
6888 to which the attribute is applied. The attribute is designed for
6889 libraries that define aliases that are expected to specify the same
6890 set of attributes as the aliased symbols. The @code{copy} attribute
6891 can be used with variables, functions or types. However, the kind
6892 of symbol to which the attribute is applied (either varible or
6893 function) must match the kind of symbol to which the argument refers.
6894 The @code{copy} attribute copies only syntactic and semantic attributes
6895 but not attributes that affect a symbol's linkage or visibility such as
6896 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
6897 attribute is also not copied. @xref{Common Function Attributes}.
6898 @xref{Common Type Attributes}.
6901 @itemx deprecated (@var{msg})
6902 @cindex @code{deprecated} variable attribute
6903 The @code{deprecated} attribute results in a warning if the variable
6904 is used anywhere in the source file. This is useful when identifying
6905 variables that are expected to be removed in a future version of a
6906 program. The warning also includes the location of the declaration
6907 of the deprecated variable, to enable users to easily find further
6908 information about why the variable is deprecated, or what they should
6909 do instead. Note that the warning only occurs for uses:
6912 extern int old_var __attribute__ ((deprecated));
6914 int new_fn () @{ return old_var; @}
6918 results in a warning on line 3 but not line 2. The optional @var{msg}
6919 argument, which must be a string, is printed in the warning if
6922 The @code{deprecated} attribute can also be used for functions and
6923 types (@pxref{Common Function Attributes},
6924 @pxref{Common Type Attributes}).
6926 The message attached to the attribute is affected by the setting of
6927 the @option{-fmessage-length} option.
6929 @item mode (@var{mode})
6930 @cindex @code{mode} variable attribute
6931 This attribute specifies the data type for the declaration---whichever
6932 type corresponds to the mode @var{mode}. This in effect lets you
6933 request an integer or floating-point type according to its width.
6935 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
6936 for a list of the possible keywords for @var{mode}.
6937 You may also specify a mode of @code{byte} or @code{__byte__} to
6938 indicate the mode corresponding to a one-byte integer, @code{word} or
6939 @code{__word__} for the mode of a one-word integer, and @code{pointer}
6940 or @code{__pointer__} for the mode used to represent pointers.
6943 @cindex @code{nonstring} variable attribute
6944 The @code{nonstring} variable attribute specifies that an object or member
6945 declaration with type array of @code{char}, @code{signed char}, or
6946 @code{unsigned char}, or pointer to such a type is intended to store
6947 character arrays that do not necessarily contain a terminating @code{NUL}.
6948 This is useful in detecting uses of such arrays or pointers with functions
6949 that expect @code{NUL}-terminated strings, and to avoid warnings when such
6950 an array or pointer is used as an argument to a bounded string manipulation
6951 function such as @code{strncpy}. For example, without the attribute, GCC
6952 will issue a warning for the @code{strncpy} call below because it may
6953 truncate the copy without appending the terminating @code{NUL} character.
6954 Using the attribute makes it possible to suppress the warning. However,
6955 when the array is declared with the attribute the call to @code{strlen} is
6956 diagnosed because when the array doesn't contain a @code{NUL}-terminated
6957 string the call is undefined. To copy, compare, of search non-string
6958 character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr},
6959 and other functions that operate on arrays of bytes. In addition,
6960 calling @code{strnlen} and @code{strndup} with such arrays is safe
6961 provided a suitable bound is specified, and not diagnosed.
6966 char name [32] __attribute__ ((nonstring));
6969 int f (struct Data *pd, const char *s)
6971 strncpy (pd->name, s, sizeof pd->name);
6973 return strlen (pd->name); // unsafe, gets a warning
6978 @cindex @code{packed} variable attribute
6979 The @code{packed} attribute specifies that a structure member should have
6980 the smallest possible alignment---one bit for a bit-field and one byte
6981 otherwise, unless a larger value is specified with the @code{aligned}
6982 attribute. The attribute does not apply to non-member objects.
6984 For example in the structure below, the member array @code{x} is packed
6985 so that it immediately follows @code{a} with no intervening padding:
6991 int x[2] __attribute__ ((packed));
6995 @emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
6996 @code{packed} attribute on bit-fields of type @code{char}. This has
6997 been fixed in GCC 4.4 but the change can lead to differences in the
6998 structure layout. See the documentation of
6999 @option{-Wpacked-bitfield-compat} for more information.
7001 @item section ("@var{section-name}")
7002 @cindex @code{section} variable attribute
7003 Normally, the compiler places the objects it generates in sections like
7004 @code{data} and @code{bss}. Sometimes, however, you need additional sections,
7005 or you need certain particular variables to appear in special sections,
7006 for example to map to special hardware. The @code{section}
7007 attribute specifies that a variable (or function) lives in a particular
7008 section. For example, this small program uses several specific section names:
7011 struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
7012 struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
7013 char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
7014 int init_data __attribute__ ((section ("INITDATA")));
7018 /* @r{Initialize stack pointer} */
7019 init_sp (stack + sizeof (stack));
7021 /* @r{Initialize initialized data} */
7022 memcpy (&init_data, &data, &edata - &data);
7024 /* @r{Turn on the serial ports} */
7031 Use the @code{section} attribute with
7032 @emph{global} variables and not @emph{local} variables,
7033 as shown in the example.
7035 You may use the @code{section} attribute with initialized or
7036 uninitialized global variables but the linker requires
7037 each object be defined once, with the exception that uninitialized
7038 variables tentatively go in the @code{common} (or @code{bss}) section
7039 and can be multiply ``defined''. Using the @code{section} attribute
7040 changes what section the variable goes into and may cause the
7041 linker to issue an error if an uninitialized variable has multiple
7042 definitions. You can force a variable to be initialized with the
7043 @option{-fno-common} flag or the @code{nocommon} attribute.
7045 Some file formats do not support arbitrary sections so the @code{section}
7046 attribute is not available on all platforms.
7047 If you need to map the entire contents of a module to a particular
7048 section, consider using the facilities of the linker instead.
7050 @item tls_model ("@var{tls_model}")
7051 @cindex @code{tls_model} variable attribute
7052 The @code{tls_model} attribute sets thread-local storage model
7053 (@pxref{Thread-Local}) of a particular @code{__thread} variable,
7054 overriding @option{-ftls-model=} command-line switch on a per-variable
7056 The @var{tls_model} argument should be one of @code{global-dynamic},
7057 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
7059 Not all targets support this attribute.
7062 @cindex @code{unused} variable attribute
7063 This attribute, attached to a variable, means that the variable is meant
7064 to be possibly unused. GCC does not produce a warning for this
7068 @cindex @code{used} variable attribute
7069 This attribute, attached to a variable with static storage, means that
7070 the variable must be emitted even if it appears that the variable is not
7073 When applied to a static data member of a C++ class template, the
7074 attribute also means that the member is instantiated if the
7075 class itself is instantiated.
7077 @item vector_size (@var{bytes})
7078 @cindex @code{vector_size} variable attribute
7079 This attribute specifies the vector size for the type of the declared
7080 variable, measured in bytes. The type to which it applies is known as
7081 the @dfn{base type}. The @var{bytes} argument must be a positive
7082 power-of-two multiple of the base type size. For example, the declaration:
7085 int foo __attribute__ ((vector_size (16)));
7089 causes the compiler to set the mode for @code{foo}, to be 16 bytes,
7090 divided into @code{int} sized units. Assuming a 32-bit @code{int},
7091 @code{foo}'s type is a vector of four units of four bytes each, and
7092 the corresponding mode of @code{foo} is @code{V4SI}.
7093 @xref{Vector Extensions}, for details of manipulating vector variables.
7095 This attribute is only applicable to integral and floating scalars,
7096 although arrays, pointers, and function return values are allowed in
7097 conjunction with this construct.
7099 Aggregates with this attribute are invalid, even if they are of the same
7100 size as a corresponding scalar. For example, the declaration:
7103 struct S @{ int a; @};
7104 struct S __attribute__ ((vector_size (16))) foo;
7108 is invalid even if the size of the structure is the same as the size of
7111 @item visibility ("@var{visibility_type}")
7112 @cindex @code{visibility} variable attribute
7113 This attribute affects the linkage of the declaration to which it is attached.
7114 The @code{visibility} attribute is described in
7115 @ref{Common Function Attributes}.
7118 @cindex @code{weak} variable attribute
7119 The @code{weak} attribute is described in
7120 @ref{Common Function Attributes}.
7123 @cindex @code{noinit} variable attribute
7124 Any data with the @code{noinit} attribute will not be initialized by
7125 the C runtime startup code, or the program loader. Not initializing
7126 data in this way can reduce program startup times. This attribute is
7127 specific to ELF targets and relies on the linker to place such data in
7132 @node ARC Variable Attributes
7133 @subsection ARC Variable Attributes
7137 @cindex @code{aux} variable attribute, ARC
7138 The @code{aux} attribute is used to directly access the ARC's
7139 auxiliary register space from C. The auxilirary register number is
7140 given via attribute argument.
7144 @node AVR Variable Attributes
7145 @subsection AVR Variable Attributes
7149 @cindex @code{progmem} variable attribute, AVR
7150 The @code{progmem} attribute is used on the AVR to place read-only
7151 data in the non-volatile program memory (flash). The @code{progmem}
7152 attribute accomplishes this by putting respective variables into a
7153 section whose name starts with @code{.progmem}.
7155 This attribute works similar to the @code{section} attribute
7156 but adds additional checking.
7159 @item @bullet{}@tie{} Ordinary AVR cores with 32 general purpose registers:
7160 @code{progmem} affects the location
7161 of the data but not how this data is accessed.
7162 In order to read data located with the @code{progmem} attribute
7163 (inline) assembler must be used.
7165 /* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */
7166 #include <avr/pgmspace.h>
7168 /* Locate var in flash memory */
7169 const int var[2] PROGMEM = @{ 1, 2 @};
7171 int read_var (int i)
7173 /* Access var[] by accessor macro from avr/pgmspace.h */
7174 return (int) pgm_read_word (& var[i]);
7178 AVR is a Harvard architecture processor and data and read-only data
7179 normally resides in the data memory (RAM).
7181 See also the @ref{AVR Named Address Spaces} section for
7182 an alternate way to locate and access data in flash memory.
7184 @item @bullet{}@tie{} AVR cores with flash memory visible in the RAM address range:
7185 On such devices, there is no need for attribute @code{progmem} or
7186 @ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all.
7187 Just use standard C / C++. The compiler will generate @code{LD*}
7188 instructions. As flash memory is visible in the RAM address range,
7189 and the default linker script does @emph{not} locate @code{.rodata} in
7190 RAM, no special features are needed in order not to waste RAM for
7191 read-only data or to read from flash. You might even get slightly better
7193 avoiding @code{progmem} and @code{__flash}. This applies to devices from
7194 families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for
7197 @item @bullet{}@tie{}Reduced AVR Tiny cores like ATtiny40:
7198 The compiler adds @code{0x4000}
7199 to the addresses of objects and declarations in @code{progmem} and locates
7200 the objects in flash memory, namely in section @code{.progmem.data}.
7201 The offset is needed because the flash memory is visible in the RAM
7202 address space starting at address @code{0x4000}.
7204 Data in @code{progmem} can be accessed by means of ordinary C@tie{}code,
7205 no special functions or macros are needed.
7208 /* var is located in flash memory */
7209 extern const int var[2] __attribute__((progmem));
7211 int read_var (int i)
7217 Please notice that on these devices, there is no need for @code{progmem}
7223 @itemx io (@var{addr})
7224 @cindex @code{io} variable attribute, AVR
7225 Variables with the @code{io} attribute are used to address
7226 memory-mapped peripherals in the io address range.
7227 If an address is specified, the variable
7228 is assigned that address, and the value is interpreted as an
7229 address in the data address space.
7233 volatile int porta __attribute__((io (0x22)));
7236 The address specified in the address in the data address range.
7238 Otherwise, the variable it is not assigned an address, but the
7239 compiler will still use in/out instructions where applicable,
7240 assuming some other module assigns an address in the io address range.
7244 extern volatile int porta __attribute__((io));
7248 @itemx io_low (@var{addr})
7249 @cindex @code{io_low} variable attribute, AVR
7250 This is like the @code{io} attribute, but additionally it informs the
7251 compiler that the object lies in the lower half of the I/O area,
7252 allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis}
7256 @itemx address (@var{addr})
7257 @cindex @code{address} variable attribute, AVR
7258 Variables with the @code{address} attribute are used to address
7259 memory-mapped peripherals that may lie outside the io address range.
7262 volatile int porta __attribute__((address (0x600)));
7266 @cindex @code{absdata} variable attribute, AVR
7267 Variables in static storage and with the @code{absdata} attribute can
7268 be accessed by the @code{LDS} and @code{STS} instructions which take
7273 This attribute is only supported for the reduced AVR Tiny core
7277 You must make sure that respective data is located in the
7278 address range @code{0x40}@dots{}@code{0xbf} accessible by
7279 @code{LDS} and @code{STS}. One way to achieve this as an
7280 appropriate linker description file.
7283 If the location does not fit the address range of @code{LDS}
7284 and @code{STS}, there is currently (Binutils 2.26) just an unspecific
7287 @code{module.c:(.text+0x1c): warning: internal error: out of range error}
7292 See also the @option{-mabsdata} @ref{AVR Options,command-line option}.
7296 @node Blackfin Variable Attributes
7297 @subsection Blackfin Variable Attributes
7299 Three attributes are currently defined for the Blackfin.
7305 @cindex @code{l1_data} variable attribute, Blackfin
7306 @cindex @code{l1_data_A} variable attribute, Blackfin
7307 @cindex @code{l1_data_B} variable attribute, Blackfin
7308 Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
7309 Variables with @code{l1_data} attribute are put into the specific section
7310 named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into
7311 the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
7312 attribute are put into the specific section named @code{.l1.data.B}.
7315 @cindex @code{l2} variable attribute, Blackfin
7316 Use this attribute on the Blackfin to place the variable into L2 SRAM.
7317 Variables with @code{l2} attribute are put into the specific section
7318 named @code{.l2.data}.
7321 @node H8/300 Variable Attributes
7322 @subsection H8/300 Variable Attributes
7324 These variable attributes are available for H8/300 targets:
7328 @cindex @code{eightbit_data} variable attribute, H8/300
7329 @cindex eight-bit data on the H8/300, H8/300H, and H8S
7330 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
7331 variable should be placed into the eight-bit data section.
7332 The compiler generates more efficient code for certain operations
7333 on data in the eight-bit data area. Note the eight-bit data area is limited to
7336 You must use GAS and GLD from GNU binutils version 2.7 or later for
7337 this attribute to work correctly.
7340 @cindex @code{tiny_data} variable attribute, H8/300
7341 @cindex tiny data section on the H8/300H and H8S
7342 Use this attribute on the H8/300H and H8S to indicate that the specified
7343 variable should be placed into the tiny data section.
7344 The compiler generates more efficient code for loads and stores
7345 on data in the tiny data section. Note the tiny data area is limited to
7346 slightly under 32KB of data.
7350 @node IA-64 Variable Attributes
7351 @subsection IA-64 Variable Attributes
7353 The IA-64 back end supports the following variable attribute:
7356 @item model (@var{model-name})
7357 @cindex @code{model} variable attribute, IA-64
7359 On IA-64, use this attribute to set the addressability of an object.
7360 At present, the only supported identifier for @var{model-name} is
7361 @code{small}, indicating addressability via ``small'' (22-bit)
7362 addresses (so that their addresses can be loaded with the @code{addl}
7363 instruction). Caveat: such addressing is by definition not position
7364 independent and hence this attribute must not be used for objects
7365 defined by shared libraries.
7369 @node M32R/D Variable Attributes
7370 @subsection M32R/D Variable Attributes
7372 One attribute is currently defined for the M32R/D@.
7375 @item model (@var{model-name})
7376 @cindex @code{model-name} variable attribute, M32R/D
7377 @cindex variable addressability on the M32R/D
7378 Use this attribute on the M32R/D to set the addressability of an object.
7379 The identifier @var{model-name} is one of @code{small}, @code{medium},
7380 or @code{large}, representing each of the code models.
7382 Small model objects live in the lower 16MB of memory (so that their
7383 addresses can be loaded with the @code{ld24} instruction).
7385 Medium and large model objects may live anywhere in the 32-bit address space
7386 (the compiler generates @code{seth/add3} instructions to load their
7390 @node MeP Variable Attributes
7391 @subsection MeP Variable Attributes
7393 The MeP target has a number of addressing modes and busses. The
7394 @code{near} space spans the standard memory space's first 16 megabytes
7395 (24 bits). The @code{far} space spans the entire 32-bit memory space.
7396 The @code{based} space is a 128-byte region in the memory space that
7397 is addressed relative to the @code{$tp} register. The @code{tiny}
7398 space is a 65536-byte region relative to the @code{$gp} register. In
7399 addition to these memory regions, the MeP target has a separate 16-bit
7400 control bus which is specified with @code{cb} attributes.
7405 @cindex @code{based} variable attribute, MeP
7406 Any variable with the @code{based} attribute is assigned to the
7407 @code{.based} section, and is accessed with relative to the
7408 @code{$tp} register.
7411 @cindex @code{tiny} variable attribute, MeP
7412 Likewise, the @code{tiny} attribute assigned variables to the
7413 @code{.tiny} section, relative to the @code{$gp} register.
7416 @cindex @code{near} variable attribute, MeP
7417 Variables with the @code{near} attribute are assumed to have addresses
7418 that fit in a 24-bit addressing mode. This is the default for large
7419 variables (@code{-mtiny=4} is the default) but this attribute can
7420 override @code{-mtiny=} for small variables, or override @code{-ml}.
7423 @cindex @code{far} variable attribute, MeP
7424 Variables with the @code{far} attribute are addressed using a full
7425 32-bit address. Since this covers the entire memory space, this
7426 allows modules to make no assumptions about where variables might be
7430 @cindex @code{io} variable attribute, MeP
7431 @itemx io (@var{addr})
7432 Variables with the @code{io} attribute are used to address
7433 memory-mapped peripherals. If an address is specified, the variable
7434 is assigned that address, else it is not assigned an address (it is
7435 assumed some other module assigns an address). Example:
7438 int timer_count __attribute__((io(0x123)));
7442 @itemx cb (@var{addr})
7443 @cindex @code{cb} variable attribute, MeP
7444 Variables with the @code{cb} attribute are used to access the control
7445 bus, using special instructions. @code{addr} indicates the control bus
7449 int cpu_clock __attribute__((cb(0x123)));
7454 @node Microsoft Windows Variable Attributes
7455 @subsection Microsoft Windows Variable Attributes
7457 You can use these attributes on Microsoft Windows targets.
7458 @ref{x86 Variable Attributes} for additional Windows compatibility
7459 attributes available on all x86 targets.
7464 @cindex @code{dllimport} variable attribute
7465 @cindex @code{dllexport} variable attribute
7466 The @code{dllimport} and @code{dllexport} attributes are described in
7467 @ref{Microsoft Windows Function Attributes}.
7470 @cindex @code{selectany} variable attribute
7471 The @code{selectany} attribute causes an initialized global variable to
7472 have link-once semantics. When multiple definitions of the variable are
7473 encountered by the linker, the first is selected and the remainder are
7474 discarded. Following usage by the Microsoft compiler, the linker is told
7475 @emph{not} to warn about size or content differences of the multiple
7478 Although the primary usage of this attribute is for POD types, the
7479 attribute can also be applied to global C++ objects that are initialized
7480 by a constructor. In this case, the static initialization and destruction
7481 code for the object is emitted in each translation defining the object,
7482 but the calls to the constructor and destructor are protected by a
7483 link-once guard variable.
7485 The @code{selectany} attribute is only available on Microsoft Windows
7486 targets. You can use @code{__declspec (selectany)} as a synonym for
7487 @code{__attribute__ ((selectany))} for compatibility with other
7491 @cindex @code{shared} variable attribute
7492 On Microsoft Windows, in addition to putting variable definitions in a named
7493 section, the section can also be shared among all running copies of an
7494 executable or DLL@. For example, this small program defines shared data
7495 by putting it in a named section @code{shared} and marking the section
7499 int foo __attribute__((section ("shared"), shared)) = 0;
7504 /* @r{Read and write foo. All running
7505 copies see the same value.} */
7511 You may only use the @code{shared} attribute along with @code{section}
7512 attribute with a fully-initialized global definition because of the way
7513 linkers work. See @code{section} attribute for more information.
7515 The @code{shared} attribute is only available on Microsoft Windows@.
7519 @node MSP430 Variable Attributes
7520 @subsection MSP430 Variable Attributes
7524 @cindex @code{noinit} variable attribute, MSP430
7525 Any data with the @code{noinit} attribute will not be initialised by
7526 the C runtime startup code, or the program loader. Not initialising
7527 data in this way can reduce program startup times.
7530 @cindex @code{persistent} variable attribute, MSP430
7531 Any variable with the @code{persistent} attribute will not be
7532 initialised by the C runtime startup code. Instead its value will be
7533 set once, when the application is loaded, and then never initialised
7534 again, even if the processor is reset or the program restarts.
7535 Persistent data is intended to be placed into FLASH RAM, where its
7536 value will be retained across resets. The linker script being used to
7537 create the application should ensure that persistent data is correctly
7543 @cindex @code{lower} variable attribute, MSP430
7544 @cindex @code{upper} variable attribute, MSP430
7545 @cindex @code{either} variable attribute, MSP430
7546 These attributes are the same as the MSP430 function attributes of the
7547 same name (@pxref{MSP430 Function Attributes}).
7548 These attributes can be applied to both functions and variables.
7551 @node Nvidia PTX Variable Attributes
7552 @subsection Nvidia PTX Variable Attributes
7554 These variable attributes are supported by the Nvidia PTX back end:
7558 @cindex @code{shared} attribute, Nvidia PTX
7559 Use this attribute to place a variable in the @code{.shared} memory space.
7560 This memory space is private to each cooperative thread array; only threads
7561 within one thread block refer to the same instance of the variable.
7562 The runtime does not initialize variables in this memory space.
7565 @node PowerPC Variable Attributes
7566 @subsection PowerPC Variable Attributes
7568 Three attributes currently are defined for PowerPC configurations:
7569 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
7571 @cindex @code{ms_struct} variable attribute, PowerPC
7572 @cindex @code{gcc_struct} variable attribute, PowerPC
7573 For full documentation of the struct attributes please see the
7574 documentation in @ref{x86 Variable Attributes}.
7576 @cindex @code{altivec} variable attribute, PowerPC
7577 For documentation of @code{altivec} attribute please see the
7578 documentation in @ref{PowerPC Type Attributes}.
7580 @node RL78 Variable Attributes
7581 @subsection RL78 Variable Attributes
7583 @cindex @code{saddr} variable attribute, RL78
7584 The RL78 back end supports the @code{saddr} variable attribute. This
7585 specifies placement of the corresponding variable in the SADDR area,
7586 which can be accessed more efficiently than the default memory region.
7588 @node V850 Variable Attributes
7589 @subsection V850 Variable Attributes
7591 These variable attributes are supported by the V850 back end:
7596 @cindex @code{sda} variable attribute, V850
7597 Use this attribute to explicitly place a variable in the small data area,
7598 which can hold up to 64 kilobytes.
7601 @cindex @code{tda} variable attribute, V850
7602 Use this attribute to explicitly place a variable in the tiny data area,
7603 which can hold up to 256 bytes in total.
7606 @cindex @code{zda} variable attribute, V850
7607 Use this attribute to explicitly place a variable in the first 32 kilobytes
7611 @node x86 Variable Attributes
7612 @subsection x86 Variable Attributes
7614 Two attributes are currently defined for x86 configurations:
7615 @code{ms_struct} and @code{gcc_struct}.
7620 @cindex @code{ms_struct} variable attribute, x86
7621 @cindex @code{gcc_struct} variable attribute, x86
7623 If @code{packed} is used on a structure, or if bit-fields are used,
7624 it may be that the Microsoft ABI lays out the structure differently
7625 than the way GCC normally does. Particularly when moving packed
7626 data between functions compiled with GCC and the native Microsoft compiler
7627 (either via function call or as data in a file), it may be necessary to access
7630 The @code{ms_struct} and @code{gcc_struct} attributes correspond
7631 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
7632 command-line options, respectively;
7633 see @ref{x86 Options}, for details of how structure layout is affected.
7634 @xref{x86 Type Attributes}, for information about the corresponding
7635 attributes on types.
7639 @node Xstormy16 Variable Attributes
7640 @subsection Xstormy16 Variable Attributes
7642 One attribute is currently defined for xstormy16 configurations:
7647 @cindex @code{below100} variable attribute, Xstormy16
7649 If a variable has the @code{below100} attribute (@code{BELOW100} is
7650 allowed also), GCC places the variable in the first 0x100 bytes of
7651 memory and use special opcodes to access it. Such variables are
7652 placed in either the @code{.bss_below100} section or the
7653 @code{.data_below100} section.
7657 @node Type Attributes
7658 @section Specifying Attributes of Types
7659 @cindex attribute of types
7660 @cindex type attributes
7662 The keyword @code{__attribute__} allows you to specify various special
7663 properties of types. Some type attributes apply only to structure and
7664 union types, and in C++, also class types, while others can apply to
7665 any type defined via a @code{typedef} declaration. Unless otherwise
7666 specified, the same restrictions and effects apply to attributes regardless
7667 of whether a type is a trivial structure or a C++ class with user-defined
7668 constructors, destructors, or a copy assignment.
7670 Other attributes are defined for functions (@pxref{Function Attributes}),
7671 labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator
7672 Attributes}), statements (@pxref{Statement Attributes}), and for variables
7673 (@pxref{Variable Attributes}).
7675 The @code{__attribute__} keyword is followed by an attribute specification
7676 enclosed in double parentheses.
7678 You may specify type attributes in an enum, struct or union type
7679 declaration or definition by placing them immediately after the
7680 @code{struct}, @code{union} or @code{enum} keyword. You can also place
7681 them just past the closing curly brace of the definition, but this is less
7682 preferred because logically the type should be fully defined at
7685 You can also include type attributes in a @code{typedef} declaration.
7686 @xref{Attribute Syntax}, for details of the exact syntax for using
7690 * Common Type Attributes::
7691 * ARC Type Attributes::
7692 * ARM Type Attributes::
7693 * MeP Type Attributes::
7694 * PowerPC Type Attributes::
7695 * x86 Type Attributes::
7698 @node Common Type Attributes
7699 @subsection Common Type Attributes
7701 The following type attributes are supported on most targets.
7704 @cindex @code{aligned} type attribute
7706 @itemx aligned (@var{alignment})
7707 The @code{aligned} attribute specifies a minimum alignment (in bytes) for
7708 variables of the specified type. When specified, @var{alignment} must be
7709 a power of 2. Specifying no @var{alignment} argument implies the maximum
7710 alignment for the target, which is often, but by no means always, 8 or 16
7711 bytes. For example, the declarations:
7714 struct __attribute__ ((aligned (8))) S @{ short f[3]; @};
7715 typedef int more_aligned_int __attribute__ ((aligned (8)));
7719 force the compiler to ensure (as far as it can) that each variable whose
7720 type is @code{struct S} or @code{more_aligned_int} is allocated and
7721 aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all
7722 variables of type @code{struct S} aligned to 8-byte boundaries allows
7723 the compiler to use the @code{ldd} and @code{std} (doubleword load and
7724 store) instructions when copying one variable of type @code{struct S} to
7725 another, thus improving run-time efficiency.
7727 Note that the alignment of any given @code{struct} or @code{union} type
7728 is required by the ISO C standard to be at least a perfect multiple of
7729 the lowest common multiple of the alignments of all of the members of
7730 the @code{struct} or @code{union} in question. This means that you @emph{can}
7731 effectively adjust the alignment of a @code{struct} or @code{union}
7732 type by attaching an @code{aligned} attribute to any one of the members
7733 of such a type, but the notation illustrated in the example above is a
7734 more obvious, intuitive, and readable way to request the compiler to
7735 adjust the alignment of an entire @code{struct} or @code{union} type.
7737 As in the preceding example, you can explicitly specify the alignment
7738 (in bytes) that you wish the compiler to use for a given @code{struct}
7739 or @code{union} type. Alternatively, you can leave out the alignment factor
7740 and just ask the compiler to align a type to the maximum
7741 useful alignment for the target machine you are compiling for. For
7742 example, you could write:
7745 struct __attribute__ ((aligned)) S @{ short f[3]; @};
7748 Whenever you leave out the alignment factor in an @code{aligned}
7749 attribute specification, the compiler automatically sets the alignment
7750 for the type to the largest alignment that is ever used for any data
7751 type on the target machine you are compiling for. Doing this can often
7752 make copy operations more efficient, because the compiler can use
7753 whatever instructions copy the biggest chunks of memory when performing
7754 copies to or from the variables that have types that you have aligned
7757 In the example above, if the size of each @code{short} is 2 bytes, then
7758 the size of the entire @code{struct S} type is 6 bytes. The smallest
7759 power of two that is greater than or equal to that is 8, so the
7760 compiler sets the alignment for the entire @code{struct S} type to 8
7763 Note that although you can ask the compiler to select a time-efficient
7764 alignment for a given type and then declare only individual stand-alone
7765 objects of that type, the compiler's ability to select a time-efficient
7766 alignment is primarily useful only when you plan to create arrays of
7767 variables having the relevant (efficiently aligned) type. If you
7768 declare or use arrays of variables of an efficiently-aligned type, then
7769 it is likely that your program also does pointer arithmetic (or
7770 subscripting, which amounts to the same thing) on pointers to the
7771 relevant type, and the code that the compiler generates for these
7772 pointer arithmetic operations is often more efficient for
7773 efficiently-aligned types than for other types.
7775 Note that the effectiveness of @code{aligned} attributes may be limited
7776 by inherent limitations in your linker. On many systems, the linker is
7777 only able to arrange for variables to be aligned up to a certain maximum
7778 alignment. (For some linkers, the maximum supported alignment may
7779 be very very small.) If your linker is only able to align variables
7780 up to a maximum of 8-byte alignment, then specifying @code{aligned (16)}
7781 in an @code{__attribute__} still only provides you with 8-byte
7782 alignment. See your linker documentation for further information.
7784 When used on a struct, or struct member, the @code{aligned} attribute can
7785 only increase the alignment; in order to decrease it, the @code{packed}
7786 attribute must be specified as well. When used as part of a typedef, the
7787 @code{aligned} attribute can both increase and decrease alignment, and
7788 specifying the @code{packed} attribute generates a warning.
7790 @cindex @code{warn_if_not_aligned} type attribute
7791 @item warn_if_not_aligned (@var{alignment})
7792 This attribute specifies a threshold for the structure field, measured
7793 in bytes. If the structure field is aligned below the threshold, a
7794 warning will be issued. For example, the declaration:
7797 typedef unsigned long long __u64
7798 __attribute__((aligned (4), warn_if_not_aligned (8)));
7809 causes the compiler to issue an warning on @code{struct foo}, like
7810 @samp{warning: alignment 4 of 'struct foo' is less than 8}.
7811 It is used to define @code{struct foo} in such a way that
7812 @code{struct foo} has the same layout and the structure field @code{x}
7813 has the same alignment when @code{__u64} is aligned at either 4 or
7814 8 bytes. Align @code{struct foo} to 8 bytes:
7817 struct __attribute__ ((aligned (8))) foo
7826 silences the warning. The compiler also issues a warning, like
7827 @samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8},
7828 when the structure field has the misaligned offset:
7831 struct __attribute__ ((aligned (8))) foo
7840 This warning can be disabled by @option{-Wno-if-not-aligned}.
7842 @item alloc_size (@var{position})
7843 @itemx alloc_size (@var{position-1}, @var{position-2})
7844 @cindex @code{alloc_size} type attribute
7845 The @code{alloc_size} type attribute may be applied to the definition
7846 of a type of a function that returns a pointer and takes at least one
7847 argument of an integer type. It indicates that the returned pointer
7848 points to an object whose size is given by the function argument at
7849 @var{position-1}, or by the product of the arguments at @var{position-1}
7850 and @var{position-2}. Meaningful sizes are positive values less than
7851 @code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses
7852 this information to improve the results of @code{__builtin_object_size}.
7854 For instance, the following declarations
7857 typedef __attribute__ ((alloc_size (1, 2))) void*
7858 calloc_type (size_t, size_t);
7859 typedef __attribute__ ((alloc_size (1))) void*
7860 malloc_type (size_t);
7864 specify that @code{calloc_type} is a type of a function that, like
7865 the standard C function @code{calloc}, returns an object whose size
7866 is given by the product of arguments 1 and 2, and that
7867 @code{malloc_type}, like the standard C function @code{malloc},
7868 returns an object whose size is given by argument 1 to the function.
7871 @itemx copy (@var{expression})
7872 @cindex @code{copy} type attribute
7873 The @code{copy} attribute applies the set of attributes with which
7874 the type of the @var{expression} has been declared to the declaration
7875 of the type to which the attribute is applied. The attribute is
7876 designed for libraries that define aliases that are expected to
7877 specify the same set of attributes as the aliased symbols.
7878 The @code{copy} attribute can be used with types, variables, or
7879 functions. However, the kind of symbol to which the attribute is
7880 applied (either varible or function) must match the kind of symbol
7881 to which the argument refers.
7882 The @code{copy} attribute copies only syntactic and semantic attributes
7883 but not attributes that affect a symbol's linkage or visibility such as
7884 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
7885 attribute is also not copied. @xref{Common Function Attributes}.
7886 @xref{Common Variable Attributes}.
7888 For example, suppose @code{struct A} below is defined in some third
7889 party library header to have the alignment requirement @code{N} and
7890 to force a warning whenever a variable of the type is not so aligned
7891 due to attribute @code{packed}. Specifying the @code{copy} attribute
7892 on the definition on the unrelated @code{struct B} has the effect of
7893 copying all relevant attributes from the type referenced by the pointer
7894 expression to @code{struct B}.
7897 struct __attribute__ ((aligned (N), warn_if_not_aligned (N)))
7898 A @{ /* @r{@dots{}} */ @};
7899 struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @};
7903 @itemx deprecated (@var{msg})
7904 @cindex @code{deprecated} type attribute
7905 The @code{deprecated} attribute results in a warning if the type
7906 is used anywhere in the source file. This is useful when identifying
7907 types that are expected to be removed in a future version of a program.
7908 If possible, the warning also includes the location of the declaration
7909 of the deprecated type, to enable users to easily find further
7910 information about why the type is deprecated, or what they should do
7911 instead. Note that the warnings only occur for uses and then only
7912 if the type is being applied to an identifier that itself is not being
7913 declared as deprecated.
7916 typedef int T1 __attribute__ ((deprecated));
7920 typedef T1 T3 __attribute__ ((deprecated));
7921 T3 z __attribute__ ((deprecated));
7925 results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
7926 warning is issued for line 4 because T2 is not explicitly
7927 deprecated. Line 5 has no warning because T3 is explicitly
7928 deprecated. Similarly for line 6. The optional @var{msg}
7929 argument, which must be a string, is printed in the warning if
7930 present. Control characters in the string will be replaced with
7931 escape sequences, and if the @option{-fmessage-length} option is set
7932 to 0 (its default value) then any newline characters will be ignored.
7934 The @code{deprecated} attribute can also be used for functions and
7935 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
7937 The message attached to the attribute is affected by the setting of
7938 the @option{-fmessage-length} option.
7940 @item designated_init
7941 @cindex @code{designated_init} type attribute
7942 This attribute may only be applied to structure types. It indicates
7943 that any initialization of an object of this type must use designated
7944 initializers rather than positional initializers. The intent of this
7945 attribute is to allow the programmer to indicate that a structure's
7946 layout may change, and that therefore relying on positional
7947 initialization will result in future breakage.
7949 GCC emits warnings based on this attribute by default; use
7950 @option{-Wno-designated-init} to suppress them.
7953 @cindex @code{may_alias} type attribute
7954 Accesses through pointers to types with this attribute are not subject
7955 to type-based alias analysis, but are instead assumed to be able to alias
7956 any other type of objects.
7957 In the context of section 6.5 paragraph 7 of the C99 standard,
7958 an lvalue expression
7959 dereferencing such a pointer is treated like having a character type.
7960 See @option{-fstrict-aliasing} for more information on aliasing issues.
7961 This extension exists to support some vector APIs, in which pointers to
7962 one vector type are permitted to alias pointers to a different vector type.
7964 Note that an object of a type with this attribute does not have any
7970 typedef short __attribute__ ((__may_alias__)) short_a;
7976 short_a *b = (short_a *) &a;
7980 if (a == 0x12345678)
7988 If you replaced @code{short_a} with @code{short} in the variable
7989 declaration, the above program would abort when compiled with
7990 @option{-fstrict-aliasing}, which is on by default at @option{-O2} or
7993 @item mode (@var{mode})
7994 @cindex @code{mode} type attribute
7995 This attribute specifies the data type for the declaration---whichever
7996 type corresponds to the mode @var{mode}. This in effect lets you
7997 request an integer or floating-point type according to its width.
7999 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
8000 for a list of the possible keywords for @var{mode}.
8001 You may also specify a mode of @code{byte} or @code{__byte__} to
8002 indicate the mode corresponding to a one-byte integer, @code{word} or
8003 @code{__word__} for the mode of a one-word integer, and @code{pointer}
8004 or @code{__pointer__} for the mode used to represent pointers.
8007 @cindex @code{packed} type attribute
8008 This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class}
8009 type definition, specifies that each of its members (other than zero-width
8010 bit-fields) is placed to minimize the memory required. This is equivalent
8011 to specifying the @code{packed} attribute on each of the members.
8013 @opindex fshort-enums
8014 When attached to an @code{enum} definition, the @code{packed} attribute
8015 indicates that the smallest integral type should be used.
8016 Specifying the @option{-fshort-enums} flag on the command line
8017 is equivalent to specifying the @code{packed}
8018 attribute on all @code{enum} definitions.
8020 In the following example @code{struct my_packed_struct}'s members are
8021 packed closely together, but the internal layout of its @code{s} member
8022 is not packed---to do that, @code{struct my_unpacked_struct} needs to
8026 struct my_unpacked_struct
8032 struct __attribute__ ((__packed__)) my_packed_struct
8036 struct my_unpacked_struct s;
8040 You may only specify the @code{packed} attribute on the definition
8041 of an @code{enum}, @code{struct}, @code{union}, or @code{class},
8042 not on a @code{typedef} that does not also define the enumerated type,
8043 structure, union, or class.
8045 @item scalar_storage_order ("@var{endianness}")
8046 @cindex @code{scalar_storage_order} type attribute
8047 When attached to a @code{union} or a @code{struct}, this attribute sets
8048 the storage order, aka endianness, of the scalar fields of the type, as
8049 well as the array fields whose component is scalar. The supported
8050 endiannesses are @code{big-endian} and @code{little-endian}. The attribute
8051 has no effects on fields which are themselves a @code{union}, a @code{struct}
8052 or an array whose component is a @code{union} or a @code{struct}, and it is
8053 possible for these fields to have a different scalar storage order than the
8056 This attribute is supported only for targets that use a uniform default
8057 scalar storage order (fortunately, most of them), i.e.@: targets that store
8058 the scalars either all in big-endian or all in little-endian.
8060 Additional restrictions are enforced for types with the reverse scalar
8061 storage order with regard to the scalar storage order of the target:
8064 @item Taking the address of a scalar field of a @code{union} or a
8065 @code{struct} with reverse scalar storage order is not permitted and yields
8067 @item Taking the address of an array field, whose component is scalar, of
8068 a @code{union} or a @code{struct} with reverse scalar storage order is
8069 permitted but yields a warning, unless @option{-Wno-scalar-storage-order}
8071 @item Taking the address of a @code{union} or a @code{struct} with reverse
8072 scalar storage order is permitted.
8075 These restrictions exist because the storage order attribute is lost when
8076 the address of a scalar or the address of an array with scalar component is
8077 taken, so storing indirectly through this address generally does not work.
8078 The second case is nevertheless allowed to be able to perform a block copy
8079 from or to the array.
8081 Moreover, the use of type punning or aliasing to toggle the storage order
8082 is not supported; that is to say, a given scalar object cannot be accessed
8083 through distinct types that assign a different storage order to it.
8085 @item transparent_union
8086 @cindex @code{transparent_union} type attribute
8088 This attribute, attached to a @code{union} type definition, indicates
8089 that any function parameter having that union type causes calls to that
8090 function to be treated in a special way.
8092 First, the argument corresponding to a transparent union type can be of
8093 any type in the union; no cast is required. Also, if the union contains
8094 a pointer type, the corresponding argument can be a null pointer
8095 constant or a void pointer expression; and if the union contains a void
8096 pointer type, the corresponding argument can be any pointer expression.
8097 If the union member type is a pointer, qualifiers like @code{const} on
8098 the referenced type must be respected, just as with normal pointer
8101 Second, the argument is passed to the function using the calling
8102 conventions of the first member of the transparent union, not the calling
8103 conventions of the union itself. All members of the union must have the
8104 same machine representation; this is necessary for this argument passing
8107 Transparent unions are designed for library functions that have multiple
8108 interfaces for compatibility reasons. For example, suppose the
8109 @code{wait} function must accept either a value of type @code{int *} to
8110 comply with POSIX, or a value of type @code{union wait *} to comply with
8111 the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
8112 @code{wait} would accept both kinds of arguments, but it would also
8113 accept any other pointer type and this would make argument type checking
8114 less useful. Instead, @code{<sys/wait.h>} might define the interface
8118 typedef union __attribute__ ((__transparent_union__))
8122 @} wait_status_ptr_t;
8124 pid_t wait (wait_status_ptr_t);
8128 This interface allows either @code{int *} or @code{union wait *}
8129 arguments to be passed, using the @code{int *} calling convention.
8130 The program can call @code{wait} with arguments of either type:
8133 int w1 () @{ int w; return wait (&w); @}
8134 int w2 () @{ union wait w; return wait (&w); @}
8138 With this interface, @code{wait}'s implementation might look like this:
8141 pid_t wait (wait_status_ptr_t p)
8143 return waitpid (-1, p.__ip, 0);
8148 @cindex @code{unused} type attribute
8149 When attached to a type (including a @code{union} or a @code{struct}),
8150 this attribute means that variables of that type are meant to appear
8151 possibly unused. GCC does not produce a warning for any variables of
8152 that type, even if the variable appears to do nothing. This is often
8153 the case with lock or thread classes, which are usually defined and then
8154 not referenced, but contain constructors and destructors that have
8155 nontrivial bookkeeping functions.
8157 @item vector_size (@var{bytes})
8158 @cindex @code{vector_size} type attribute
8159 This attribute specifies the vector size for the type, measured in bytes.
8160 The type to which it applies is known as the @dfn{base type}. The @var{bytes}
8161 argument must be a positive power-of-two multiple of the base type size. For
8162 example, the following declarations:
8165 typedef __attribute__ ((vector_size (32))) int int_vec32_t ;
8166 typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t;
8167 typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3];
8171 define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int}
8172 sized units. With @code{int} having a size of 4 bytes, the type defines
8173 a vector of eight units, four bytes each. The mode of variables of type
8174 @code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined
8175 to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be
8176 an array of three such vectors. @xref{Vector Extensions}, for details of
8177 manipulating objects of vector types.
8179 This attribute is only applicable to integral and floating scalar types.
8180 In function declarations the attribute applies to the function return
8183 For example, the following:
8185 __attribute__ ((vector_size (16))) float get_flt_vec16 (void);
8187 declares @code{get_flt_vec16} to be a function returning a 16-byte vector
8188 with the base type @code{float}.
8191 @cindex @code{visibility} type attribute
8192 In C++, attribute visibility (@pxref{Function Attributes}) can also be
8193 applied to class, struct, union and enum types. Unlike other type
8194 attributes, the attribute must appear between the initial keyword and
8195 the name of the type; it cannot appear after the body of the type.
8197 Note that the type visibility is applied to vague linkage entities
8198 associated with the class (vtable, typeinfo node, etc.). In
8199 particular, if a class is thrown as an exception in one shared object
8200 and caught in another, the class must have default visibility.
8201 Otherwise the two shared objects are unable to use the same
8202 typeinfo node and exception handling will break.
8206 To specify multiple attributes, separate them by commas within the
8207 double parentheses: for example, @samp{__attribute__ ((aligned (16),
8210 @node ARC Type Attributes
8211 @subsection ARC Type Attributes
8213 @cindex @code{uncached} type attribute, ARC
8214 Declaring objects with @code{uncached} allows you to exclude
8215 data-cache participation in load and store operations on those objects
8216 without involving the additional semantic implications of
8217 @code{volatile}. The @code{.di} instruction suffix is used for all
8218 loads and stores of data declared @code{uncached}.
8220 @node ARM Type Attributes
8221 @subsection ARM Type Attributes
8223 @cindex @code{notshared} type attribute, ARM
8224 On those ARM targets that support @code{dllimport} (such as Symbian
8225 OS), you can use the @code{notshared} attribute to indicate that the
8226 virtual table and other similar data for a class should not be
8227 exported from a DLL@. For example:
8230 class __declspec(notshared) C @{
8232 __declspec(dllimport) C();
8236 __declspec(dllexport)
8241 In this code, @code{C::C} is exported from the current DLL, but the
8242 virtual table for @code{C} is not exported. (You can use
8243 @code{__attribute__} instead of @code{__declspec} if you prefer, but
8244 most Symbian OS code uses @code{__declspec}.)
8246 @node MeP Type Attributes
8247 @subsection MeP Type Attributes
8249 @cindex @code{based} type attribute, MeP
8250 @cindex @code{tiny} type attribute, MeP
8251 @cindex @code{near} type attribute, MeP
8252 @cindex @code{far} type attribute, MeP
8253 Many of the MeP variable attributes may be applied to types as well.
8254 Specifically, the @code{based}, @code{tiny}, @code{near}, and
8255 @code{far} attributes may be applied to either. The @code{io} and
8256 @code{cb} attributes may not be applied to types.
8258 @node PowerPC Type Attributes
8259 @subsection PowerPC Type Attributes
8261 Three attributes currently are defined for PowerPC configurations:
8262 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
8264 @cindex @code{ms_struct} type attribute, PowerPC
8265 @cindex @code{gcc_struct} type attribute, PowerPC
8266 For full documentation of the @code{ms_struct} and @code{gcc_struct}
8267 attributes please see the documentation in @ref{x86 Type Attributes}.
8269 @cindex @code{altivec} type attribute, PowerPC
8270 The @code{altivec} attribute allows one to declare AltiVec vector data
8271 types supported by the AltiVec Programming Interface Manual. The
8272 attribute requires an argument to specify one of three vector types:
8273 @code{vector__}, @code{pixel__} (always followed by unsigned short),
8274 and @code{bool__} (always followed by unsigned).
8277 __attribute__((altivec(vector__)))
8278 __attribute__((altivec(pixel__))) unsigned short
8279 __attribute__((altivec(bool__))) unsigned
8282 These attributes mainly are intended to support the @code{__vector},
8283 @code{__pixel}, and @code{__bool} AltiVec keywords.
8285 @node x86 Type Attributes
8286 @subsection x86 Type Attributes
8288 Two attributes are currently defined for x86 configurations:
8289 @code{ms_struct} and @code{gcc_struct}.
8295 @cindex @code{ms_struct} type attribute, x86
8296 @cindex @code{gcc_struct} type attribute, x86
8298 If @code{packed} is used on a structure, or if bit-fields are used
8299 it may be that the Microsoft ABI packs them differently
8300 than GCC normally packs them. Particularly when moving packed
8301 data between functions compiled with GCC and the native Microsoft compiler
8302 (either via function call or as data in a file), it may be necessary to access
8305 The @code{ms_struct} and @code{gcc_struct} attributes correspond
8306 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
8307 command-line options, respectively;
8308 see @ref{x86 Options}, for details of how structure layout is affected.
8309 @xref{x86 Variable Attributes}, for information about the corresponding
8310 attributes on variables.
8314 @node Label Attributes
8315 @section Label Attributes
8316 @cindex Label Attributes
8318 GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for
8319 details of the exact syntax for using attributes. Other attributes are
8320 available for functions (@pxref{Function Attributes}), variables
8321 (@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}),
8322 statements (@pxref{Statement Attributes}), and for types
8323 (@pxref{Type Attributes}).
8325 This example uses the @code{cold} label attribute to indicate the
8326 @code{ErrorHandling} branch is unlikely to be taken and that the
8327 @code{ErrorHandling} label is unused:
8331 asm goto ("some asm" : : : : NoError);
8333 /* This branch (the fall-through from the asm) is less commonly used */
8335 __attribute__((cold, unused)); /* Semi-colon is required here */
8340 printf("no error\n");
8346 @cindex @code{unused} label attribute
8347 This feature is intended for program-generated code that may contain
8348 unused labels, but which is compiled with @option{-Wall}. It is
8349 not normally appropriate to use in it human-written code, though it
8350 could be useful in cases where the code that jumps to the label is
8351 contained within an @code{#ifdef} conditional.
8354 @cindex @code{hot} label attribute
8355 The @code{hot} attribute on a label is used to inform the compiler that
8356 the path following the label is more likely than paths that are not so
8357 annotated. This attribute is used in cases where @code{__builtin_expect}
8358 cannot be used, for instance with computed goto or @code{asm goto}.
8361 @cindex @code{cold} label attribute
8362 The @code{cold} attribute on labels is used to inform the compiler that
8363 the path following the label is unlikely to be executed. This attribute
8364 is used in cases where @code{__builtin_expect} cannot be used, for instance
8365 with computed goto or @code{asm goto}.
8369 @node Enumerator Attributes
8370 @section Enumerator Attributes
8371 @cindex Enumerator Attributes
8373 GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for
8374 details of the exact syntax for using attributes. Other attributes are
8375 available for functions (@pxref{Function Attributes}), variables
8376 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements
8377 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
8379 This example uses the @code{deprecated} enumerator attribute to indicate the
8380 @code{oldval} enumerator is deprecated:
8384 oldval __attribute__((deprecated)),
8397 @cindex @code{deprecated} enumerator attribute
8398 The @code{deprecated} attribute results in a warning if the enumerator
8399 is used anywhere in the source file. This is useful when identifying
8400 enumerators that are expected to be removed in a future version of a
8401 program. The warning also includes the location of the declaration
8402 of the deprecated enumerator, to enable users to easily find further
8403 information about why the enumerator is deprecated, or what they should
8404 do instead. Note that the warnings only occurs for uses.
8408 @node Statement Attributes
8409 @section Statement Attributes
8410 @cindex Statement Attributes
8412 GCC allows attributes to be set on null statements. @xref{Attribute Syntax},
8413 for details of the exact syntax for using attributes. Other attributes are
8414 available for functions (@pxref{Function Attributes}), variables
8415 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators
8416 (@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}).
8418 This example uses the @code{fallthrough} statement attribute to indicate that
8419 the @option{-Wimplicit-fallthrough} warning should not be emitted:
8426 __attribute__((fallthrough));
8434 @cindex @code{fallthrough} statement attribute
8435 The @code{fallthrough} attribute with a null statement serves as a
8436 fallthrough statement. It hints to the compiler that a statement
8437 that falls through to another case label, or user-defined label
8438 in a switch statement is intentional and thus the
8439 @option{-Wimplicit-fallthrough} warning must not trigger. The
8440 fallthrough attribute may appear at most once in each attribute
8441 list, and may not be mixed with other attributes. It can only
8442 be used in a switch statement (the compiler will issue an error
8443 otherwise), after a preceding statement and before a logically
8444 succeeding case label, or user-defined label.
8448 @node Attribute Syntax
8449 @section Attribute Syntax
8450 @cindex attribute syntax
8452 This section describes the syntax with which @code{__attribute__} may be
8453 used, and the constructs to which attribute specifiers bind, for the C
8454 language. Some details may vary for C++ and Objective-C@. Because of
8455 infelicities in the grammar for attributes, some forms described here
8456 may not be successfully parsed in all cases.
8458 There are some problems with the semantics of attributes in C++. For
8459 example, there are no manglings for attributes, although they may affect
8460 code generation, so problems may arise when attributed types are used in
8461 conjunction with templates or overloading. Similarly, @code{typeid}
8462 does not distinguish between types with different attributes. Support
8463 for attributes in C++ may be restricted in future to attributes on
8464 declarations only, but not on nested declarators.
8466 @xref{Function Attributes}, for details of the semantics of attributes
8467 applying to functions. @xref{Variable Attributes}, for details of the
8468 semantics of attributes applying to variables. @xref{Type Attributes},
8469 for details of the semantics of attributes applying to structure, union
8470 and enumerated types.
8471 @xref{Label Attributes}, for details of the semantics of attributes
8473 @xref{Enumerator Attributes}, for details of the semantics of attributes
8474 applying to enumerators.
8475 @xref{Statement Attributes}, for details of the semantics of attributes
8476 applying to statements.
8478 An @dfn{attribute specifier} is of the form
8479 @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
8480 is a possibly empty comma-separated sequence of @dfn{attributes}, where
8481 each attribute is one of the following:
8485 Empty. Empty attributes are ignored.
8489 (which may be an identifier such as @code{unused}, or a reserved
8490 word such as @code{const}).
8493 An attribute name followed by a parenthesized list of
8494 parameters for the attribute.
8495 These parameters take one of the following forms:
8499 An identifier. For example, @code{mode} attributes use this form.
8502 An identifier followed by a comma and a non-empty comma-separated list
8503 of expressions. For example, @code{format} attributes use this form.
8506 A possibly empty comma-separated list of expressions. For example,
8507 @code{format_arg} attributes use this form with the list being a single
8508 integer constant expression, and @code{alias} attributes use this form
8509 with the list being a single string constant.
8513 An @dfn{attribute specifier list} is a sequence of one or more attribute
8514 specifiers, not separated by any other tokens.
8516 You may optionally specify attribute names with @samp{__}
8517 preceding and following the name.
8518 This allows you to use them in header files without
8519 being concerned about a possible macro of the same name. For example,
8520 you may use the attribute name @code{__noreturn__} instead of @code{noreturn}.
8523 @subsubheading Label Attributes
8525 In GNU C, an attribute specifier list may appear after the colon following a
8526 label, other than a @code{case} or @code{default} label. GNU C++ only permits
8527 attributes on labels if the attribute specifier is immediately
8528 followed by a semicolon (i.e., the label applies to an empty
8529 statement). If the semicolon is missing, C++ label attributes are
8530 ambiguous, as it is permissible for a declaration, which could begin
8531 with an attribute list, to be labelled in C++. Declarations cannot be
8532 labelled in C90 or C99, so the ambiguity does not arise there.
8534 @subsubheading Enumerator Attributes
8536 In GNU C, an attribute specifier list may appear as part of an enumerator.
8537 The attribute goes after the enumeration constant, before @code{=}, if
8538 present. The optional attribute in the enumerator appertains to the
8539 enumeration constant. It is not possible to place the attribute after
8540 the constant expression, if present.
8542 @subsubheading Statement Attributes
8543 In GNU C, an attribute specifier list may appear as part of a null
8544 statement. The attribute goes before the semicolon.
8546 @subsubheading Type Attributes
8548 An attribute specifier list may appear as part of a @code{struct},
8549 @code{union} or @code{enum} specifier. It may go either immediately
8550 after the @code{struct}, @code{union} or @code{enum} keyword, or after
8551 the closing brace. The former syntax is preferred.
8552 Where attribute specifiers follow the closing brace, they are considered
8553 to relate to the structure, union or enumerated type defined, not to any
8554 enclosing declaration the type specifier appears in, and the type
8555 defined is not complete until after the attribute specifiers.
8556 @c Otherwise, there would be the following problems: a shift/reduce
8557 @c conflict between attributes binding the struct/union/enum and
8558 @c binding to the list of specifiers/qualifiers; and "aligned"
8559 @c attributes could use sizeof for the structure, but the size could be
8560 @c changed later by "packed" attributes.
8563 @subsubheading All other attributes
8565 Otherwise, an attribute specifier appears as part of a declaration,
8566 counting declarations of unnamed parameters and type names, and relates
8567 to that declaration (which may be nested in another declaration, for
8568 example in the case of a parameter declaration), or to a particular declarator
8569 within a declaration. Where an
8570 attribute specifier is applied to a parameter declared as a function or
8571 an array, it should apply to the function or array rather than the
8572 pointer to which the parameter is implicitly converted, but this is not
8573 yet correctly implemented.
8575 Any list of specifiers and qualifiers at the start of a declaration may
8576 contain attribute specifiers, whether or not such a list may in that
8577 context contain storage class specifiers. (Some attributes, however,
8578 are essentially in the nature of storage class specifiers, and only make
8579 sense where storage class specifiers may be used; for example,
8580 @code{section}.) There is one necessary limitation to this syntax: the
8581 first old-style parameter declaration in a function definition cannot
8582 begin with an attribute specifier, because such an attribute applies to
8583 the function instead by syntax described below (which, however, is not
8584 yet implemented in this case). In some other cases, attribute
8585 specifiers are permitted by this grammar but not yet supported by the
8586 compiler. All attribute specifiers in this place relate to the
8587 declaration as a whole. In the obsolescent usage where a type of
8588 @code{int} is implied by the absence of type specifiers, such a list of
8589 specifiers and qualifiers may be an attribute specifier list with no
8590 other specifiers or qualifiers.
8592 At present, the first parameter in a function prototype must have some
8593 type specifier that is not an attribute specifier; this resolves an
8594 ambiguity in the interpretation of @code{void f(int
8595 (__attribute__((foo)) x))}, but is subject to change. At present, if
8596 the parentheses of a function declarator contain only attributes then
8597 those attributes are ignored, rather than yielding an error or warning
8598 or implying a single parameter of type int, but this is subject to
8601 An attribute specifier list may appear immediately before a declarator
8602 (other than the first) in a comma-separated list of declarators in a
8603 declaration of more than one identifier using a single list of
8604 specifiers and qualifiers. Such attribute specifiers apply
8605 only to the identifier before whose declarator they appear. For
8609 __attribute__((noreturn)) void d0 (void),
8610 __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
8615 the @code{noreturn} attribute applies to all the functions
8616 declared; the @code{format} attribute only applies to @code{d1}.
8618 An attribute specifier list may appear immediately before the comma,
8619 @code{=} or semicolon terminating the declaration of an identifier other
8620 than a function definition. Such attribute specifiers apply
8621 to the declared object or function. Where an
8622 assembler name for an object or function is specified (@pxref{Asm
8623 Labels}), the attribute must follow the @code{asm}
8626 An attribute specifier list may, in future, be permitted to appear after
8627 the declarator in a function definition (before any old-style parameter
8628 declarations or the function body).
8630 Attribute specifiers may be mixed with type qualifiers appearing inside
8631 the @code{[]} of a parameter array declarator, in the C99 construct by
8632 which such qualifiers are applied to the pointer to which the array is
8633 implicitly converted. Such attribute specifiers apply to the pointer,
8634 not to the array, but at present this is not implemented and they are
8637 An attribute specifier list may appear at the start of a nested
8638 declarator. At present, there are some limitations in this usage: the
8639 attributes correctly apply to the declarator, but for most individual
8640 attributes the semantics this implies are not implemented.
8641 When attribute specifiers follow the @code{*} of a pointer
8642 declarator, they may be mixed with any type qualifiers present.
8643 The following describes the formal semantics of this syntax. It makes the
8644 most sense if you are familiar with the formal specification of
8645 declarators in the ISO C standard.
8647 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
8648 D1}, where @code{T} contains declaration specifiers that specify a type
8649 @var{Type} (such as @code{int}) and @code{D1} is a declarator that
8650 contains an identifier @var{ident}. The type specified for @var{ident}
8651 for derived declarators whose type does not include an attribute
8652 specifier is as in the ISO C standard.
8654 If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
8655 and the declaration @code{T D} specifies the type
8656 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
8657 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
8658 @var{attribute-specifier-list} @var{Type}'' for @var{ident}.
8660 If @code{D1} has the form @code{*
8661 @var{type-qualifier-and-attribute-specifier-list} D}, and the
8662 declaration @code{T D} specifies the type
8663 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
8664 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
8665 @var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for
8671 void (__attribute__((noreturn)) ****f) (void);
8675 specifies the type ``pointer to pointer to pointer to pointer to
8676 non-returning function returning @code{void}''. As another example,
8679 char *__attribute__((aligned(8))) *f;
8683 specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
8684 Note again that this does not work with most attributes; for example,
8685 the usage of @samp{aligned} and @samp{noreturn} attributes given above
8686 is not yet supported.
8688 For compatibility with existing code written for compiler versions that
8689 did not implement attributes on nested declarators, some laxity is
8690 allowed in the placing of attributes. If an attribute that only applies
8691 to types is applied to a declaration, it is treated as applying to
8692 the type of that declaration. If an attribute that only applies to
8693 declarations is applied to the type of a declaration, it is treated
8694 as applying to that declaration; and, for compatibility with code
8695 placing the attributes immediately before the identifier declared, such
8696 an attribute applied to a function return type is treated as
8697 applying to the function type, and such an attribute applied to an array
8698 element type is treated as applying to the array type. If an
8699 attribute that only applies to function types is applied to a
8700 pointer-to-function type, it is treated as applying to the pointer
8701 target type; if such an attribute is applied to a function return type
8702 that is not a pointer-to-function type, it is treated as applying
8703 to the function type.
8705 @node Function Prototypes
8706 @section Prototypes and Old-Style Function Definitions
8707 @cindex function prototype declarations
8708 @cindex old-style function definitions
8709 @cindex promotion of formal parameters
8711 GNU C extends ISO C to allow a function prototype to override a later
8712 old-style non-prototype definition. Consider the following example:
8715 /* @r{Use prototypes unless the compiler is old-fashioned.} */
8722 /* @r{Prototype function declaration.} */
8723 int isroot P((uid_t));
8725 /* @r{Old-style function definition.} */
8727 isroot (x) /* @r{??? lossage here ???} */
8734 Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
8735 not allow this example, because subword arguments in old-style
8736 non-prototype definitions are promoted. Therefore in this example the
8737 function definition's argument is really an @code{int}, which does not
8738 match the prototype argument type of @code{short}.
8740 This restriction of ISO C makes it hard to write code that is portable
8741 to traditional C compilers, because the programmer does not know
8742 whether the @code{uid_t} type is @code{short}, @code{int}, or
8743 @code{long}. Therefore, in cases like these GNU C allows a prototype
8744 to override a later old-style definition. More precisely, in GNU C, a
8745 function prototype argument type overrides the argument type specified
8746 by a later old-style definition if the former type is the same as the
8747 latter type before promotion. Thus in GNU C the above example is
8748 equivalent to the following:
8761 GNU C++ does not support old-style function definitions, so this
8762 extension is irrelevant.
8765 @section C++ Style Comments
8767 @cindex C++ comments
8768 @cindex comments, C++ style
8770 In GNU C, you may use C++ style comments, which start with @samp{//} and
8771 continue until the end of the line. Many other C implementations allow
8772 such comments, and they are included in the 1999 C standard. However,
8773 C++ style comments are not recognized if you specify an @option{-std}
8774 option specifying a version of ISO C before C99, or @option{-ansi}
8775 (equivalent to @option{-std=c90}).
8778 @section Dollar Signs in Identifier Names
8780 @cindex dollar signs in identifier names
8781 @cindex identifier names, dollar signs in
8783 In GNU C, you may normally use dollar signs in identifier names.
8784 This is because many traditional C implementations allow such identifiers.
8785 However, dollar signs in identifiers are not supported on a few target
8786 machines, typically because the target assembler does not allow them.
8788 @node Character Escapes
8789 @section The Character @key{ESC} in Constants
8791 You can use the sequence @samp{\e} in a string or character constant to
8792 stand for the ASCII character @key{ESC}.
8795 @section Determining the Alignment of Functions, Types or Variables
8797 @cindex type alignment
8798 @cindex variable alignment
8800 The keyword @code{__alignof__} determines the alignment requirement of
8801 a function, object, or a type, or the minimum alignment usually required
8802 by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}.
8804 For example, if the target machine requires a @code{double} value to be
8805 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
8806 This is true on many RISC machines. On more traditional machine
8807 designs, @code{__alignof__ (double)} is 4 or even 2.
8809 Some machines never actually require alignment; they allow references to any
8810 data type even at an odd address. For these machines, @code{__alignof__}
8811 reports the smallest alignment that GCC gives the data type, usually as
8812 mandated by the target ABI.
8814 If the operand of @code{__alignof__} is an lvalue rather than a type,
8815 its value is the required alignment for its type, taking into account
8816 any minimum alignment specified by attribute @code{aligned}
8817 (@pxref{Common Variable Attributes}). For example, after this
8821 struct foo @{ int x; char y; @} foo1;
8825 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
8826 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
8827 It is an error to ask for the alignment of an incomplete type other
8830 If the operand of the @code{__alignof__} expression is a function,
8831 the expression evaluates to the alignment of the function which may
8832 be specified by attribute @code{aligned} (@pxref{Common Function Attributes}).
8835 @section An Inline Function is As Fast As a Macro
8836 @cindex inline functions
8837 @cindex integrating function code
8839 @cindex macros, inline alternative
8841 By declaring a function inline, you can direct GCC to make
8842 calls to that function faster. One way GCC can achieve this is to
8843 integrate that function's code into the code for its callers. This
8844 makes execution faster by eliminating the function-call overhead; in
8845 addition, if any of the actual argument values are constant, their
8846 known values may permit simplifications at compile time so that not
8847 all of the inline function's code needs to be included. The effect on
8848 code size is less predictable; object code may be larger or smaller
8849 with function inlining, depending on the particular case. You can
8850 also direct GCC to try to integrate all ``simple enough'' functions
8851 into their callers with the option @option{-finline-functions}.
8853 GCC implements three different semantics of declaring a function
8854 inline. One is available with @option{-std=gnu89} or
8855 @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
8856 on all inline declarations, another when
8858 @option{-std=gnu99} or an option for a later C version is used
8859 (without @option{-fgnu89-inline}), and the third
8860 is used when compiling C++.
8862 To declare a function inline, use the @code{inline} keyword in its
8863 declaration, like this:
8873 If you are writing a header file to be included in ISO C90 programs, write
8874 @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
8876 The three types of inlining behave similarly in two important cases:
8877 when the @code{inline} keyword is used on a @code{static} function,
8878 like the example above, and when a function is first declared without
8879 using the @code{inline} keyword and then is defined with
8880 @code{inline}, like this:
8883 extern int inc (int *a);
8891 In both of these common cases, the program behaves the same as if you
8892 had not used the @code{inline} keyword, except for its speed.
8894 @cindex inline functions, omission of
8895 @opindex fkeep-inline-functions
8896 When a function is both inline and @code{static}, if all calls to the
8897 function are integrated into the caller, and the function's address is
8898 never used, then the function's own assembler code is never referenced.
8899 In this case, GCC does not actually output assembler code for the
8900 function, unless you specify the option @option{-fkeep-inline-functions}.
8901 If there is a nonintegrated call, then the function is compiled to
8902 assembler code as usual. The function must also be compiled as usual if
8903 the program refers to its address, because that cannot be inlined.
8906 Note that certain usages in a function definition can make it unsuitable
8907 for inline substitution. Among these usages are: variadic functions,
8908 use of @code{alloca}, use of computed goto (@pxref{Labels as Values}),
8909 use of nonlocal goto, use of nested functions, use of @code{setjmp}, use
8910 of @code{__builtin_longjmp} and use of @code{__builtin_return} or
8911 @code{__builtin_apply_args}. Using @option{-Winline} warns when a
8912 function marked @code{inline} could not be substituted, and gives the
8913 reason for the failure.
8915 @cindex automatic @code{inline} for C++ member fns
8916 @cindex @code{inline} automatic for C++ member fns
8917 @cindex member fns, automatically @code{inline}
8918 @cindex C++ member fns, automatically @code{inline}
8919 @opindex fno-default-inline
8920 As required by ISO C++, GCC considers member functions defined within
8921 the body of a class to be marked inline even if they are
8922 not explicitly declared with the @code{inline} keyword. You can
8923 override this with @option{-fno-default-inline}; @pxref{C++ Dialect
8924 Options,,Options Controlling C++ Dialect}.
8926 GCC does not inline any functions when not optimizing unless you specify
8927 the @samp{always_inline} attribute for the function, like this:
8930 /* @r{Prototype.} */
8931 inline void foo (const char) __attribute__((always_inline));
8934 The remainder of this section is specific to GNU C90 inlining.
8936 @cindex non-static inline function
8937 When an inline function is not @code{static}, then the compiler must assume
8938 that there may be calls from other source files; since a global symbol can
8939 be defined only once in any program, the function must not be defined in
8940 the other source files, so the calls therein cannot be integrated.
8941 Therefore, a non-@code{static} inline function is always compiled on its
8942 own in the usual fashion.
8944 If you specify both @code{inline} and @code{extern} in the function
8945 definition, then the definition is used only for inlining. In no case
8946 is the function compiled on its own, not even if you refer to its
8947 address explicitly. Such an address becomes an external reference, as
8948 if you had only declared the function, and had not defined it.
8950 This combination of @code{inline} and @code{extern} has almost the
8951 effect of a macro. The way to use it is to put a function definition in
8952 a header file with these keywords, and put another copy of the
8953 definition (lacking @code{inline} and @code{extern}) in a library file.
8954 The definition in the header file causes most calls to the function
8955 to be inlined. If any uses of the function remain, they refer to
8956 the single copy in the library.
8959 @section When is a Volatile Object Accessed?
8960 @cindex accessing volatiles
8961 @cindex volatile read
8962 @cindex volatile write
8963 @cindex volatile access
8965 C has the concept of volatile objects. These are normally accessed by
8966 pointers and used for accessing hardware or inter-thread
8967 communication. The standard encourages compilers to refrain from
8968 optimizations concerning accesses to volatile objects, but leaves it
8969 implementation defined as to what constitutes a volatile access. The
8970 minimum requirement is that at a sequence point all previous accesses
8971 to volatile objects have stabilized and no subsequent accesses have
8972 occurred. Thus an implementation is free to reorder and combine
8973 volatile accesses that occur between sequence points, but cannot do
8974 so for accesses across a sequence point. The use of volatile does
8975 not allow you to violate the restriction on updating objects multiple
8976 times between two sequence points.
8978 Accesses to non-volatile objects are not ordered with respect to
8979 volatile accesses. You cannot use a volatile object as a memory
8980 barrier to order a sequence of writes to non-volatile memory. For
8984 int *ptr = @var{something};
8986 *ptr = @var{something};
8991 Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed
8992 that the write to @var{*ptr} occurs by the time the update
8993 of @var{vobj} happens. If you need this guarantee, you must use
8994 a stronger memory barrier such as:
8997 int *ptr = @var{something};
8999 *ptr = @var{something};
9000 asm volatile ("" : : : "memory");
9004 A scalar volatile object is read when it is accessed in a void context:
9007 volatile int *src = @var{somevalue};
9011 Such expressions are rvalues, and GCC implements this as a
9012 read of the volatile object being pointed to.
9014 Assignments are also expressions and have an rvalue. However when
9015 assigning to a scalar volatile, the volatile object is not reread,
9016 regardless of whether the assignment expression's rvalue is used or
9017 not. If the assignment's rvalue is used, the value is that assigned
9018 to the volatile object. For instance, there is no read of @var{vobj}
9019 in all the following cases:
9024 vobj = @var{something};
9025 obj = vobj = @var{something};
9026 obj ? vobj = @var{onething} : vobj = @var{anotherthing};
9027 obj = (@var{something}, vobj = @var{anotherthing});
9030 If you need to read the volatile object after an assignment has
9031 occurred, you must use a separate expression with an intervening
9034 As bit-fields are not individually addressable, volatile bit-fields may
9035 be implicitly read when written to, or when adjacent bit-fields are
9036 accessed. Bit-field operations may be optimized such that adjacent
9037 bit-fields are only partially accessed, if they straddle a storage unit
9038 boundary. For these reasons it is unwise to use volatile bit-fields to
9041 @node Using Assembly Language with C
9042 @section How to Use Inline Assembly Language in C Code
9043 @cindex @code{asm} keyword
9044 @cindex assembly language in C
9045 @cindex inline assembly language
9046 @cindex mixing assembly language and C
9048 The @code{asm} keyword allows you to embed assembler instructions
9049 within C code. GCC provides two forms of inline @code{asm}
9050 statements. A @dfn{basic @code{asm}} statement is one with no
9051 operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}}
9052 statement (@pxref{Extended Asm}) includes one or more operands.
9053 The extended form is preferred for mixing C and assembly language
9054 within a function, but to include assembly language at
9055 top level you must use basic @code{asm}.
9057 You can also use the @code{asm} keyword to override the assembler name
9058 for a C symbol, or to place a C variable in a specific register.
9061 * Basic Asm:: Inline assembler without operands.
9062 * Extended Asm:: Inline assembler with operands.
9063 * Constraints:: Constraints for @code{asm} operands
9064 * Asm Labels:: Specifying the assembler name to use for a C symbol.
9065 * Explicit Register Variables:: Defining variables residing in specified
9067 * Size of an asm:: How GCC calculates the size of an @code{asm} block.
9071 @subsection Basic Asm --- Assembler Instructions Without Operands
9072 @cindex basic @code{asm}
9073 @cindex assembly language in C, basic
9075 A basic @code{asm} statement has the following syntax:
9078 asm @var{asm-qualifiers} ( @var{AssemblerInstructions} )
9081 The @code{asm} keyword is a GNU extension.
9082 When writing code that can be compiled with @option{-ansi} and the
9083 various @option{-std} options, use @code{__asm__} instead of
9084 @code{asm} (@pxref{Alternate Keywords}).
9086 @subsubheading Qualifiers
9089 The optional @code{volatile} qualifier has no effect.
9090 All basic @code{asm} blocks are implicitly volatile.
9093 If you use the @code{inline} qualifier, then for inlining purposes the size
9094 of the @code{asm} statement is taken as the smallest size possible (@pxref{Size
9098 @subsubheading Parameters
9101 @item AssemblerInstructions
9102 This is a literal string that specifies the assembler code. The string can
9103 contain any instructions recognized by the assembler, including directives.
9104 GCC does not parse the assembler instructions themselves and
9105 does not know what they mean or even whether they are valid assembler input.
9107 You may place multiple assembler instructions together in a single @code{asm}
9108 string, separated by the characters normally used in assembly code for the
9109 system. A combination that works in most places is a newline to break the
9110 line, plus a tab character (written as @samp{\n\t}).
9111 Some assemblers allow semicolons as a line separator. However,
9112 note that some assembler dialects use semicolons to start a comment.
9115 @subsubheading Remarks
9116 Using extended @code{asm} (@pxref{Extended Asm}) typically produces
9117 smaller, safer, and more efficient code, and in most cases it is a
9118 better solution than basic @code{asm}. However, there are two
9119 situations where only basic @code{asm} can be used:
9123 Extended @code{asm} statements have to be inside a C
9124 function, so to write inline assembly language at file scope (``top-level''),
9125 outside of C functions, you must use basic @code{asm}.
9126 You can use this technique to emit assembler directives,
9127 define assembly language macros that can be invoked elsewhere in the file,
9128 or write entire functions in assembly language.
9129 Basic @code{asm} statements outside of functions may not use any
9134 with the @code{naked} attribute also require basic @code{asm}
9135 (@pxref{Function Attributes}).
9138 Safely accessing C data and calling functions from basic @code{asm} is more
9139 complex than it may appear. To access C data, it is better to use extended
9142 Do not expect a sequence of @code{asm} statements to remain perfectly
9143 consecutive after compilation. If certain instructions need to remain
9144 consecutive in the output, put them in a single multi-instruction @code{asm}
9145 statement. Note that GCC's optimizers can move @code{asm} statements
9146 relative to other code, including across jumps.
9148 @code{asm} statements may not perform jumps into other @code{asm} statements.
9149 GCC does not know about these jumps, and therefore cannot take
9150 account of them when deciding how to optimize. Jumps from @code{asm} to C
9151 labels are only supported in extended @code{asm}.
9153 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
9154 assembly code when optimizing. This can lead to unexpected duplicate
9155 symbol errors during compilation if your assembly code defines symbols or
9158 @strong{Warning:} The C standards do not specify semantics for @code{asm},
9159 making it a potential source of incompatibilities between compilers. These
9160 incompatibilities may not produce compiler warnings/errors.
9162 GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which
9163 means there is no way to communicate to the compiler what is happening
9164 inside them. GCC has no visibility of symbols in the @code{asm} and may
9165 discard them as unreferenced. It also does not know about side effects of
9166 the assembler code, such as modifications to memory or registers. Unlike
9167 some compilers, GCC assumes that no changes to general purpose registers
9168 occur. This assumption may change in a future release.
9170 To avoid complications from future changes to the semantics and the
9171 compatibility issues between compilers, consider replacing basic @code{asm}
9172 with extended @code{asm}. See
9173 @uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert
9174 from basic asm to extended asm} for information about how to perform this
9177 The compiler copies the assembler instructions in a basic @code{asm}
9178 verbatim to the assembly language output file, without
9179 processing dialects or any of the @samp{%} operators that are available with
9180 extended @code{asm}. This results in minor differences between basic
9181 @code{asm} strings and extended @code{asm} templates. For example, to refer to
9182 registers you might use @samp{%eax} in basic @code{asm} and
9183 @samp{%%eax} in extended @code{asm}.
9185 On targets such as x86 that support multiple assembler dialects,
9186 all basic @code{asm} blocks use the assembler dialect specified by the
9187 @option{-masm} command-line option (@pxref{x86 Options}).
9188 Basic @code{asm} provides no
9189 mechanism to provide different assembler strings for different dialects.
9191 For basic @code{asm} with non-empty assembler string GCC assumes
9192 the assembler block does not change any general purpose registers,
9193 but it may read or write any globally accessible variable.
9195 Here is an example of basic @code{asm} for i386:
9198 /* Note that this code will not compile with -masm=intel */
9199 #define DebugBreak() asm("int $3")
9203 @subsection Extended Asm - Assembler Instructions with C Expression Operands
9204 @cindex extended @code{asm}
9205 @cindex assembly language in C, extended
9207 With extended @code{asm} you can read and write C variables from
9208 assembler and perform jumps from assembler code to C labels.
9209 Extended @code{asm} syntax uses colons (@samp{:}) to delimit
9210 the operand parameters after the assembler template:
9213 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9214 : @var{OutputOperands}
9215 @r{[} : @var{InputOperands}
9216 @r{[} : @var{Clobbers} @r{]} @r{]})
9218 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9220 : @var{InputOperands}
9224 where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the
9227 The @code{asm} keyword is a GNU extension.
9228 When writing code that can be compiled with @option{-ansi} and the
9229 various @option{-std} options, use @code{__asm__} instead of
9230 @code{asm} (@pxref{Alternate Keywords}).
9232 @subsubheading Qualifiers
9236 The typical use of extended @code{asm} statements is to manipulate input
9237 values to produce output values. However, your @code{asm} statements may
9238 also produce side effects. If so, you may need to use the @code{volatile}
9239 qualifier to disable certain optimizations. @xref{Volatile}.
9242 If you use the @code{inline} qualifier, then for inlining purposes the size
9243 of the @code{asm} statement is taken as the smallest size possible
9244 (@pxref{Size of an asm}).
9247 This qualifier informs the compiler that the @code{asm} statement may
9248 perform a jump to one of the labels listed in the @var{GotoLabels}.
9252 @subsubheading Parameters
9254 @item AssemblerTemplate
9255 This is a literal string that is the template for the assembler code. It is a
9256 combination of fixed text and tokens that refer to the input, output,
9257 and goto parameters. @xref{AssemblerTemplate}.
9259 @item OutputOperands
9260 A comma-separated list of the C variables modified by the instructions in the
9261 @var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}.
9264 A comma-separated list of C expressions read by the instructions in the
9265 @var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}.
9268 A comma-separated list of registers or other values changed by the
9269 @var{AssemblerTemplate}, beyond those listed as outputs.
9270 An empty list is permitted. @xref{Clobbers and Scratch Registers}.
9273 When you are using the @code{goto} form of @code{asm}, this section contains
9274 the list of all C labels to which the code in the
9275 @var{AssemblerTemplate} may jump.
9278 @code{asm} statements may not perform jumps into other @code{asm} statements,
9279 only to the listed @var{GotoLabels}.
9280 GCC's optimizers do not know about other jumps; therefore they cannot take
9281 account of them when deciding how to optimize.
9284 The total number of input + output + goto operands is limited to 30.
9286 @subsubheading Remarks
9287 The @code{asm} statement allows you to include assembly instructions directly
9288 within C code. This may help you to maximize performance in time-sensitive
9289 code or to access assembly instructions that are not readily available to C
9292 Note that extended @code{asm} statements must be inside a function. Only
9293 basic @code{asm} may be outside functions (@pxref{Basic Asm}).
9294 Functions declared with the @code{naked} attribute also require basic
9295 @code{asm} (@pxref{Function Attributes}).
9297 While the uses of @code{asm} are many and varied, it may help to think of an
9298 @code{asm} statement as a series of low-level instructions that convert input
9299 parameters to output parameters. So a simple (if not particularly useful)
9300 example for i386 using @code{asm} might look like this:
9306 asm ("mov %1, %0\n\t"
9311 printf("%d\n", dst);
9314 This code copies @code{src} to @code{dst} and add 1 to @code{dst}.
9317 @subsubsection Volatile
9318 @cindex volatile @code{asm}
9319 @cindex @code{asm} volatile
9321 GCC's optimizers sometimes discard @code{asm} statements if they determine
9322 there is no need for the output variables. Also, the optimizers may move
9323 code out of loops if they believe that the code will always return the same
9324 result (i.e.@: none of its input values change between calls). Using the
9325 @code{volatile} qualifier disables these optimizations. @code{asm} statements
9326 that have no output operands, including @code{asm goto} statements,
9327 are implicitly volatile.
9329 This i386 code demonstrates a case that does not use (or require) the
9330 @code{volatile} qualifier. If it is performing assertion checking, this code
9331 uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is
9332 unreferenced by any code. As a result, the optimizers can discard the
9333 @code{asm} statement, which in turn removes the need for the entire
9334 @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
9335 isn't needed you allow the optimizers to produce the most efficient code
9339 void DoCheck(uint32_t dwSomeValue)
9343 // Assumes dwSomeValue is not zero.
9353 The next example shows a case where the optimizers can recognize that the input
9354 (@code{dwSomeValue}) never changes during the execution of the function and can
9355 therefore move the @code{asm} outside the loop to produce more efficient code.
9356 Again, using the @code{volatile} qualifier disables this type of optimization.
9359 void do_print(uint32_t dwSomeValue)
9363 for (uint32_t x=0; x < 5; x++)
9365 // Assumes dwSomeValue is not zero.
9371 printf("%u: %u %u\n", x, dwSomeValue, dwRes);
9376 The following example demonstrates a case where you need to use the
9377 @code{volatile} qualifier.
9378 It uses the x86 @code{rdtsc} instruction, which reads
9379 the computer's time-stamp counter. Without the @code{volatile} qualifier,
9380 the optimizers might assume that the @code{asm} block will always return the
9381 same value and therefore optimize away the second call.
9386 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
9387 "shl $32, %%rdx\n\t" // Shift the upper bits left.
9388 "or %%rdx, %0" // 'Or' in the lower bits.
9393 printf("msr: %llx\n", msr);
9397 // Reprint the timestamp
9398 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
9399 "shl $32, %%rdx\n\t" // Shift the upper bits left.
9400 "or %%rdx, %0" // 'Or' in the lower bits.
9405 printf("msr: %llx\n", msr);
9408 GCC's optimizers do not treat this code like the non-volatile code in the
9409 earlier examples. They do not move it out of loops or omit it on the
9410 assumption that the result from a previous call is still valid.
9412 Note that the compiler can move even @code{volatile asm} instructions relative
9413 to other code, including across jump instructions. For example, on many
9414 targets there is a system register that controls the rounding mode of
9415 floating-point operations. Setting it with a @code{volatile asm} statement,
9416 as in the following PowerPC example, does not work reliably.
9419 asm volatile("mtfsf 255, %0" : : "f" (fpenv));
9423 The compiler may move the addition back before the @code{volatile asm}
9424 statement. To make it work as expected, add an artificial dependency to
9425 the @code{asm} by referencing a variable in the subsequent code, for
9429 asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
9433 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
9434 assembly code when optimizing. This can lead to unexpected duplicate symbol
9435 errors during compilation if your @code{asm} code defines symbols or labels.
9437 (@pxref{AssemblerTemplate}) may help resolve this problem.
9439 @anchor{AssemblerTemplate}
9440 @subsubsection Assembler Template
9441 @cindex @code{asm} assembler template
9443 An assembler template is a literal string containing assembler instructions.
9444 The compiler replaces tokens in the template that refer
9445 to inputs, outputs, and goto labels,
9446 and then outputs the resulting string to the assembler. The
9447 string can contain any instructions recognized by the assembler, including
9448 directives. GCC does not parse the assembler instructions
9449 themselves and does not know what they mean or even whether they are valid
9450 assembler input. However, it does count the statements
9451 (@pxref{Size of an asm}).
9453 You may place multiple assembler instructions together in a single @code{asm}
9454 string, separated by the characters normally used in assembly code for the
9455 system. A combination that works in most places is a newline to break the
9456 line, plus a tab character to move to the instruction field (written as
9458 Some assemblers allow semicolons as a line separator. However, note
9459 that some assembler dialects use semicolons to start a comment.
9461 Do not expect a sequence of @code{asm} statements to remain perfectly
9462 consecutive after compilation, even when you are using the @code{volatile}
9463 qualifier. If certain instructions need to remain consecutive in the output,
9464 put them in a single multi-instruction @code{asm} statement.
9466 Accessing data from C programs without using input/output operands (such as
9467 by using global symbols directly from the assembler template) may not work as
9468 expected. Similarly, calling functions directly from an assembler template
9469 requires a detailed understanding of the target assembler and ABI.
9471 Since GCC does not parse the assembler template,
9472 it has no visibility of any
9473 symbols it references. This may result in GCC discarding those symbols as
9474 unreferenced unless they are also listed as input, output, or goto operands.
9476 @subsubheading Special format strings
9478 In addition to the tokens described by the input, output, and goto operands,
9479 these tokens have special meanings in the assembler template:
9483 Outputs a single @samp{%} into the assembler code.
9486 Outputs a number that is unique to each instance of the @code{asm}
9487 statement in the entire compilation. This option is useful when creating local
9488 labels and referring to them multiple times in a single template that
9489 generates multiple assembler instructions.
9494 Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively)
9495 into the assembler code. When unescaped, these characters have special
9496 meaning to indicate multiple assembler dialects, as described below.
9499 @subsubheading Multiple assembler dialects in @code{asm} templates
9501 On targets such as x86, GCC supports multiple assembler dialects.
9502 The @option{-masm} option controls which dialect GCC uses as its
9503 default for inline assembler. The target-specific documentation for the
9504 @option{-masm} option contains the list of supported dialects, as well as the
9505 default dialect if the option is not specified. This information may be
9506 important to understand, since assembler code that works correctly when
9507 compiled using one dialect will likely fail if compiled using another.
9510 If your code needs to support multiple assembler dialects (for example, if
9511 you are writing public headers that need to support a variety of compilation
9512 options), use constructs of this form:
9515 @{ dialect0 | dialect1 | dialect2... @}
9518 This construct outputs @code{dialect0}
9519 when using dialect #0 to compile the code,
9520 @code{dialect1} for dialect #1, etc. If there are fewer alternatives within the
9521 braces than the number of dialects the compiler supports, the construct
9524 For example, if an x86 compiler supports two dialects
9525 (@samp{att}, @samp{intel}), an
9526 assembler template such as this:
9529 "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
9533 is equivalent to one of
9536 "btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */}
9537 "bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */}
9540 Using that same compiler, this code:
9543 "xchg@{l@}\t@{%%@}ebx, %1"
9547 corresponds to either
9550 "xchgl\t%%ebx, %1" @r{/* att dialect */}
9551 "xchg\tebx, %1" @r{/* intel dialect */}
9554 There is no support for nesting dialect alternatives.
9556 @anchor{OutputOperands}
9557 @subsubsection Output Operands
9558 @cindex @code{asm} output operands
9560 An @code{asm} statement has zero or more output operands indicating the names
9561 of C variables modified by the assembler code.
9563 In this i386 example, @code{old} (referred to in the template string as
9564 @code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset}
9565 (@code{%2}) is an input:
9570 __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
9571 "sbb %0,%0" // Use the CF to calculate old.
9572 : "=r" (old), "+rm" (*Base)
9579 Operands are separated by commas. Each operand has this format:
9582 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename})
9586 @item asmSymbolicName
9587 Specifies a symbolic name for the operand.
9588 Reference the name in the assembler template
9589 by enclosing it in square brackets
9590 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
9591 that contains the definition. Any valid C variable name is acceptable,
9592 including names already defined in the surrounding code. No two operands
9593 within the same @code{asm} statement can use the same symbolic name.
9595 When not using an @var{asmSymbolicName}, use the (zero-based) position
9597 in the list of operands in the assembler template. For example if there are
9598 three output operands, use @samp{%0} in the template to refer to the first,
9599 @samp{%1} for the second, and @samp{%2} for the third.
9602 A string constant specifying constraints on the placement of the operand;
9603 @xref{Constraints}, for details.
9605 Output constraints must begin with either @samp{=} (a variable overwriting an
9606 existing value) or @samp{+} (when reading and writing). When using
9607 @samp{=}, do not assume the location contains the existing value
9608 on entry to the @code{asm}, except
9609 when the operand is tied to an input; @pxref{InputOperands,,Input Operands}.
9611 After the prefix, there must be one or more additional constraints
9612 (@pxref{Constraints}) that describe where the value resides. Common
9613 constraints include @samp{r} for register and @samp{m} for memory.
9614 When you list more than one possible location (for example, @code{"=rm"}),
9615 the compiler chooses the most efficient one based on the current context.
9616 If you list as many alternates as the @code{asm} statement allows, you permit
9617 the optimizers to produce the best possible code.
9618 If you must use a specific register, but your Machine Constraints do not
9619 provide sufficient control to select the specific register you want,
9620 local register variables may provide a solution (@pxref{Local Register
9624 Specifies a C lvalue expression to hold the output, typically a variable name.
9625 The enclosing parentheses are a required part of the syntax.
9629 When the compiler selects the registers to use to
9630 represent the output operands, it does not use any of the clobbered registers
9631 (@pxref{Clobbers and Scratch Registers}).
9633 Output operand expressions must be lvalues. The compiler cannot check whether
9634 the operands have data types that are reasonable for the instruction being
9635 executed. For output expressions that are not directly addressable (for
9636 example a bit-field), the constraint must allow a register. In that case, GCC
9637 uses the register as the output of the @code{asm}, and then stores that
9638 register into the output.
9640 Operands using the @samp{+} constraint modifier count as two operands
9641 (that is, both as input and output) towards the total maximum of 30 operands
9642 per @code{asm} statement.
9644 Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output
9645 operands that must not overlap an input. Otherwise,
9646 GCC may allocate the output operand in the same register as an unrelated
9647 input operand, on the assumption that the assembler code consumes its
9648 inputs before producing outputs. This assumption may be false if the assembler
9649 code actually consists of more than one instruction.
9651 The same problem can occur if one output parameter (@var{a}) allows a register
9652 constraint and another output parameter (@var{b}) allows a memory constraint.
9653 The code generated by GCC to access the memory address in @var{b} can contain
9654 registers which @emph{might} be shared by @var{a}, and GCC considers those
9655 registers to be inputs to the asm. As above, GCC assumes that such input
9656 registers are consumed before any outputs are written. This assumption may
9657 result in incorrect behavior if the @code{asm} statement writes to @var{a}
9659 @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a}
9660 ensures that modifying @var{a} does not affect the address referenced by
9661 @var{b}. Otherwise, the location of @var{b}
9662 is undefined if @var{a} is modified before using @var{b}.
9664 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
9665 instead of simply @samp{%2}). Typically these qualifiers are hardware
9666 dependent. The list of supported modifiers for x86 is found at
9667 @ref{x86Operandmodifiers,x86 Operand modifiers}.
9669 If the C code that follows the @code{asm} makes no use of any of the output
9670 operands, use @code{volatile} for the @code{asm} statement to prevent the
9671 optimizers from discarding the @code{asm} statement as unneeded
9672 (see @ref{Volatile}).
9674 This code makes no use of the optional @var{asmSymbolicName}. Therefore it
9675 references the first output operand as @code{%0} (were there a second, it
9676 would be @code{%1}, etc). The number of the first input operand is one greater
9677 than that of the last output operand. In this i386 example, that makes
9678 @code{Mask} referenced as @code{%1}:
9681 uint32_t Mask = 1234;
9690 That code overwrites the variable @code{Index} (@samp{=}),
9691 placing the value in a register (@samp{r}).
9692 Using the generic @samp{r} constraint instead of a constraint for a specific
9693 register allows the compiler to pick the register to use, which can result
9694 in more efficient code. This may not be possible if an assembler instruction
9695 requires a specific register.
9697 The following i386 example uses the @var{asmSymbolicName} syntax.
9699 same result as the code above, but some may consider it more readable or more
9700 maintainable since reordering index numbers is not necessary when adding or
9701 removing operands. The names @code{aIndex} and @code{aMask}
9702 are only used in this example to emphasize which
9703 names get used where.
9704 It is acceptable to reuse the names @code{Index} and @code{Mask}.
9707 uint32_t Mask = 1234;
9710 asm ("bsfl %[aMask], %[aIndex]"
9711 : [aIndex] "=r" (Index)
9712 : [aMask] "r" (Mask)
9716 Here are some more examples of output operands.
9723 asm ("mov %[e], %[d]"
9728 Here, @code{d} may either be in a register or in memory. Since the compiler
9729 might already have the current value of the @code{uint32_t} location
9730 pointed to by @code{e}
9731 in a register, you can enable it to choose the best location
9732 for @code{d} by specifying both constraints.
9734 @anchor{FlagOutputOperands}
9735 @subsubsection Flag Output Operands
9736 @cindex @code{asm} flag output operands
9738 Some targets have a special register that holds the ``flags'' for the
9739 result of an operation or comparison. Normally, the contents of that
9740 register are either unmodifed by the asm, or the @code{asm} statement is
9741 considered to clobber the contents.
9743 On some targets, a special form of output operand exists by which
9744 conditions in the flags register may be outputs of the asm. The set of
9745 conditions supported are target specific, but the general rule is that
9746 the output variable must be a scalar integer, and the value is boolean.
9747 When supported, the target defines the preprocessor symbol
9748 @code{__GCC_ASM_FLAG_OUTPUTS__}.
9750 Because of the special nature of the flag output operands, the constraint
9751 may not include alternatives.
9753 Most often, the target has only one flags register, and thus is an implied
9754 operand of many instructions. In this case, the operand should not be
9755 referenced within the assembler template via @code{%0} etc, as there's
9756 no corresponding text in the assembly language.
9760 The flag output constraints for the x86 family are of the form
9761 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
9762 conditions defined in the ISA manual for @code{j@var{cc}} or
9767 ``above'' or unsigned greater than
9769 ``above or equal'' or unsigned greater than or equal
9771 ``below'' or unsigned less than
9773 ``below or equal'' or unsigned less than or equal
9778 ``equal'' or zero flag set
9782 signed greater than or equal
9786 signed less than or equal
9807 ``not'' @var{flag}, or inverted versions of those above
9812 @anchor{InputOperands}
9813 @subsubsection Input Operands
9814 @cindex @code{asm} input operands
9815 @cindex @code{asm} expressions
9817 Input operands make values from C variables and expressions available to the
9820 Operands are separated by commas. Each operand has this format:
9823 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression})
9827 @item asmSymbolicName
9828 Specifies a symbolic name for the operand.
9829 Reference the name in the assembler template
9830 by enclosing it in square brackets
9831 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
9832 that contains the definition. Any valid C variable name is acceptable,
9833 including names already defined in the surrounding code. No two operands
9834 within the same @code{asm} statement can use the same symbolic name.
9836 When not using an @var{asmSymbolicName}, use the (zero-based) position
9838 in the list of operands in the assembler template. For example if there are
9839 two output operands and three inputs,
9840 use @samp{%2} in the template to refer to the first input operand,
9841 @samp{%3} for the second, and @samp{%4} for the third.
9844 A string constant specifying constraints on the placement of the operand;
9845 @xref{Constraints}, for details.
9847 Input constraint strings may not begin with either @samp{=} or @samp{+}.
9848 When you list more than one possible location (for example, @samp{"irm"}),
9849 the compiler chooses the most efficient one based on the current context.
9850 If you must use a specific register, but your Machine Constraints do not
9851 provide sufficient control to select the specific register you want,
9852 local register variables may provide a solution (@pxref{Local Register
9855 Input constraints can also be digits (for example, @code{"0"}). This indicates
9856 that the specified input must be in the same place as the output constraint
9857 at the (zero-based) index in the output constraint list.
9858 When using @var{asmSymbolicName} syntax for the output operands,
9859 you may use these names (enclosed in brackets @samp{[]}) instead of digits.
9862 This is the C variable or expression being passed to the @code{asm} statement
9863 as input. The enclosing parentheses are a required part of the syntax.
9867 When the compiler selects the registers to use to represent the input
9868 operands, it does not use any of the clobbered registers
9869 (@pxref{Clobbers and Scratch Registers}).
9871 If there are no output operands but there are input operands, place two
9872 consecutive colons where the output operands would go:
9875 __asm__ ("some instructions"
9877 : "r" (Offset / 8));
9880 @strong{Warning:} Do @emph{not} modify the contents of input-only operands
9881 (except for inputs tied to outputs). The compiler assumes that on exit from
9882 the @code{asm} statement these operands contain the same values as they
9883 had before executing the statement.
9884 It is @emph{not} possible to use clobbers
9885 to inform the compiler that the values in these inputs are changing. One
9886 common work-around is to tie the changing input variable to an output variable
9887 that never gets used. Note, however, that if the code that follows the
9888 @code{asm} statement makes no use of any of the output operands, the GCC
9889 optimizers may discard the @code{asm} statement as unneeded
9890 (see @ref{Volatile}).
9892 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
9893 instead of simply @samp{%2}). Typically these qualifiers are hardware
9894 dependent. The list of supported modifiers for x86 is found at
9895 @ref{x86Operandmodifiers,x86 Operand modifiers}.
9897 In this example using the fictitious @code{combine} instruction, the
9898 constraint @code{"0"} for input operand 1 says that it must occupy the same
9899 location as output operand 0. Only input operands may use numbers in
9900 constraints, and they must each refer to an output operand. Only a number (or
9901 the symbolic assembler name) in the constraint can guarantee that one operand
9902 is in the same place as another. The mere fact that @code{foo} is the value of
9903 both operands is not enough to guarantee that they are in the same place in
9904 the generated assembler code.
9907 asm ("combine %2, %0"
9909 : "0" (foo), "g" (bar));
9912 Here is an example using symbolic names.
9915 asm ("cmoveq %1, %2, %[result]"
9916 : [result] "=r"(result)
9917 : "r" (test), "r" (new), "[result]" (old));
9920 @anchor{Clobbers and Scratch Registers}
9921 @subsubsection Clobbers and Scratch Registers
9922 @cindex @code{asm} clobbers
9923 @cindex @code{asm} scratch registers
9925 While the compiler is aware of changes to entries listed in the output
9926 operands, the inline @code{asm} code may modify more than just the outputs. For
9927 example, calculations may require additional registers, or the processor may
9928 overwrite a register as a side effect of a particular assembler instruction.
9929 In order to inform the compiler of these changes, list them in the clobber
9930 list. Clobber list items are either register names or the special clobbers
9931 (listed below). Each clobber list item is a string constant
9932 enclosed in double quotes and separated by commas.
9934 Clobber descriptions may not in any way overlap with an input or output
9935 operand. For example, you may not have an operand describing a register class
9936 with one member when listing that register in the clobber list. Variables
9937 declared to live in specific registers (@pxref{Explicit Register
9938 Variables}) and used
9939 as @code{asm} input or output operands must have no part mentioned in the
9940 clobber description. In particular, there is no way to specify that input
9941 operands get modified without also specifying them as output operands.
9943 When the compiler selects which registers to use to represent input and output
9944 operands, it does not use any of the clobbered registers. As a result,
9945 clobbered registers are available for any use in the assembler code.
9947 Another restriction is that the clobber list should not contain the
9948 stack pointer register. This is because the compiler requires the
9949 value of the stack pointer to be the same after an @code{asm}
9950 statement as it was on entry to the statement. However, previous
9951 versions of GCC did not enforce this rule and allowed the stack
9952 pointer to appear in the list, with unclear semantics. This behavior
9953 is deprecated and listing the stack pointer may become an error in
9954 future versions of GCC@.
9956 Here is a realistic example for the VAX showing the use of clobbered
9960 asm volatile ("movc3 %0, %1, %2"
9962 : "g" (from), "g" (to), "g" (count)
9963 : "r0", "r1", "r2", "r3", "r4", "r5", "memory");
9966 Also, there are two special clobber arguments:
9970 The @code{"cc"} clobber indicates that the assembler code modifies the flags
9971 register. On some machines, GCC represents the condition codes as a specific
9972 hardware register; @code{"cc"} serves to name this register.
9973 On other machines, condition code handling is different,
9974 and specifying @code{"cc"} has no effect. But
9975 it is valid no matter what the target.
9978 The @code{"memory"} clobber tells the compiler that the assembly code
9980 reads or writes to items other than those listed in the input and output
9981 operands (for example, accessing the memory pointed to by one of the input
9982 parameters). To ensure memory contains correct values, GCC may need to flush
9983 specific register values to memory before executing the @code{asm}. Further,
9984 the compiler does not assume that any values read from memory before an
9985 @code{asm} remain unchanged after that @code{asm}; it reloads them as
9987 Using the @code{"memory"} clobber effectively forms a read/write
9988 memory barrier for the compiler.
9990 Note that this clobber does not prevent the @emph{processor} from doing
9991 speculative reads past the @code{asm} statement. To prevent that, you need
9992 processor-specific fence instructions.
9996 Flushing registers to memory has performance implications and may be
9997 an issue for time-sensitive code. You can provide better information
9998 to GCC to avoid this, as shown in the following examples. At a
9999 minimum, aliasing rules allow GCC to know what memory @emph{doesn't}
10000 need to be flushed.
10002 Here is a fictitious sum of squares instruction, that takes two
10003 pointers to floating point values in memory and produces a floating
10004 point register output.
10005 Notice that @code{x}, and @code{y} both appear twice in the @code{asm}
10006 parameters, once to specify memory accessed, and once to specify a
10007 base register used by the @code{asm}. You won't normally be wasting a
10008 register by doing this as GCC can use the same register for both
10009 purposes. However, it would be foolish to use both @code{%1} and
10010 @code{%3} for @code{x} in this @code{asm} and expect them to be the
10011 same. In fact, @code{%3} may well not be a register. It might be a
10012 symbolic memory reference to the object pointed to by @code{x}.
10015 asm ("sumsq %0, %1, %2"
10017 : "r" (x), "r" (y), "m" (*x), "m" (*y));
10020 Here is a fictitious @code{*z++ = *x++ * *y++} instruction.
10021 Notice that the @code{x}, @code{y} and @code{z} pointer registers
10022 must be specified as input/output because the @code{asm} modifies
10026 asm ("vecmul %0, %1, %2"
10027 : "+r" (z), "+r" (x), "+r" (y), "=m" (*z)
10028 : "m" (*x), "m" (*y));
10031 An x86 example where the string memory argument is of unknown length.
10035 : "=c" (count), "+D" (p)
10036 : "m" (*(const char (*)[]) p), "0" (-1), "a" (0));
10039 If you know the above will only be reading a ten byte array then you
10040 could instead use a memory input like:
10041 @code{"m" (*(const char (*)[10]) p)}.
10043 Here is an example of a PowerPC vector scale implemented in assembly,
10044 complete with vector and condition code clobbers, and some initialized
10045 offset registers that are unchanged by the @code{asm}.
10049 dscal (size_t n, double *x, double alpha)
10051 asm ("/* lots of asm here */"
10052 : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x)
10053 : "d" (alpha), "b" (32), "b" (48), "b" (64),
10054 "b" (80), "b" (96), "b" (112)
10056 "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39",
10057 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47");
10061 Rather than allocating fixed registers via clobbers to provide scratch
10062 registers for an @code{asm} statement, an alternative is to define a
10063 variable and make it an early-clobber output as with @code{a2} and
10064 @code{a3} in the example below. This gives the compiler register
10065 allocator more freedom. You can also define a variable and make it an
10066 output tied to an input as with @code{a0} and @code{a1}, tied
10067 respectively to @code{ap} and @code{lda}. Of course, with tied
10068 outputs your @code{asm} can't use the input value after modifying the
10069 output register since they are one and the same register. What's
10070 more, if you omit the early-clobber on the output, it is possible that
10071 GCC might allocate the same register to another of the inputs if GCC
10072 could prove they had the same value on entry to the @code{asm}. This
10073 is why @code{a1} has an early-clobber. Its tied input, @code{lda}
10074 might conceivably be known to have the value 16 and without an
10075 early-clobber share the same register as @code{%11}. On the other
10076 hand, @code{ap} can't be the same as any of the other inputs, so an
10077 early-clobber on @code{a0} is not needed. It is also not desirable in
10078 this case. An early-clobber on @code{a0} would cause GCC to allocate
10079 a separate register for the @code{"m" (*(const double (*)[]) ap)}
10080 input. Note that tying an input to an output is the way to set up an
10081 initialized temporary register modified by an @code{asm} statement.
10082 An input not tied to an output is assumed by GCC to be unchanged, for
10083 example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might
10084 use that register in following code if the value 16 happened to be
10085 needed. You can even use a normal @code{asm} output for a scratch if
10086 all inputs that might share the same register are consumed before the
10087 scratch is used. The VSX registers clobbered by the @code{asm}
10088 statement could have used this technique except for GCC's limit on the
10089 number of @code{asm} parameters.
10093 dgemv_kernel_4x4 (long n, const double *ap, long lda,
10094 const double *x, double *y, double alpha)
10103 /* lots of asm here */
10104 "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n"
10105 "#a0=%3 a1=%4 a2=%5 a3=%6"
10107 "+m" (*(double (*)[n]) y),
10115 "m" (*(const double (*)[n]) x),
10116 "m" (*(const double (*)[]) ap),
10124 "vs32","vs33","vs34","vs35","vs36","vs37",
10125 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"
10130 @anchor{GotoLabels}
10131 @subsubsection Goto Labels
10132 @cindex @code{asm} goto labels
10134 @code{asm goto} allows assembly code to jump to one or more C labels. The
10135 @var{GotoLabels} section in an @code{asm goto} statement contains
10137 list of all C labels to which the assembler code may jump. GCC assumes that
10138 @code{asm} execution falls through to the next statement (if this is not the
10139 case, consider using the @code{__builtin_unreachable} intrinsic after the
10140 @code{asm} statement). Optimization of @code{asm goto} may be improved by
10141 using the @code{hot} and @code{cold} label attributes (@pxref{Label
10144 An @code{asm goto} statement cannot have outputs.
10145 This is due to an internal restriction of
10146 the compiler: control transfer instructions cannot have outputs.
10147 If the assembler code does modify anything, use the @code{"memory"} clobber
10149 optimizers to flush all register values to memory and reload them if
10150 necessary after the @code{asm} statement.
10152 Also note that an @code{asm goto} statement is always implicitly
10153 considered volatile.
10155 To reference a label in the assembler template,
10156 prefix it with @samp{%l} (lowercase @samp{L}) followed
10157 by its (zero-based) position in @var{GotoLabels} plus the number of input
10158 operands. For example, if the @code{asm} has three inputs and references two
10159 labels, refer to the first label as @samp{%l3} and the second as @samp{%l4}).
10161 Alternately, you can reference labels using the actual C label name enclosed
10162 in brackets. For example, to reference a label named @code{carry}, you can
10163 use @samp{%l[carry]}. The label must still be listed in the @var{GotoLabels}
10164 section when using this approach.
10166 Here is an example of @code{asm goto} for i386:
10172 : /* No outputs. */
10173 : "r" (p1), "r" (p2)
10183 The following example shows an @code{asm goto} that uses a memory clobber.
10189 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
10190 : /* No outputs. */
10200 @anchor{x86Operandmodifiers}
10201 @subsubsection x86 Operand Modifiers
10203 References to input, output, and goto operands in the assembler template
10204 of extended @code{asm} statements can use
10205 modifiers to affect the way the operands are formatted in
10206 the code output to the assembler. For example, the
10207 following code uses the @samp{h} and @samp{b} modifiers for x86:
10211 asm volatile ("xchg %h0, %b0" : "+a" (num) );
10215 These modifiers generate this assembler code:
10221 The rest of this discussion uses the following code for illustrative purposes.
10230 asm volatile goto ("some assembler instructions here"
10231 : /* No outputs. */
10232 : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42)
10233 : /* No clobbers. */
10238 With no modifiers, this is what the output from the operands would be
10239 for the @samp{att} and @samp{intel} dialects of assembler:
10241 @multitable {Operand} {$.L2} {OFFSET FLAT:.L2}
10242 @headitem Operand @tab @samp{att} @tab @samp{intel}
10251 @tab @code{OFFSET FLAT:.L3}
10254 The table below shows the list of supported modifiers and their effects.
10256 @multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}}
10257 @headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel}
10259 @tab Print an absolute memory reference.
10264 @tab Print the QImode name of the register.
10269 @tab Require a constant operand and print the constant expression with no punctuation.
10274 @tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit.
10275 Otherwise mode is unspecified (VOIDmode).
10280 @tab Print the QImode name for a ``high'' register.
10285 @tab Add 8 bytes to an offsettable memory reference. Useful when accessing the
10286 high 8 bytes of SSE values. For a memref in (%rax), it generates
10288 @tab @code{8(%rax)}
10291 @tab Print the SImode name of the register.
10296 @tab Print the label name with no punctuation.
10301 @tab Print raw symbol name (without syntax-specific prefixes).
10306 @tab If used for a function, print the PLT suffix and generate PIC code.
10307 For example, emit @code{foo@@PLT} instead of 'foo' for the function
10308 foo(). If used for a constant, drop all syntax-specific prefixes and
10309 issue the bare constant. See @code{p} above.
10311 @tab Print the DImode name of the register.
10316 @tab Print the HImode name of the register.
10321 @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}).
10327 @code{V} is a special modifier which prints the name of the full integer
10328 register without @code{%}.
10330 @anchor{x86floatingpointasmoperands}
10331 @subsubsection x86 Floating-Point @code{asm} Operands
10333 On x86 targets, there are several rules on the usage of stack-like registers
10334 in the operands of an @code{asm}. These rules apply only to the operands
10335 that are stack-like registers:
10339 Given a set of input registers that die in an @code{asm}, it is
10340 necessary to know which are implicitly popped by the @code{asm}, and
10341 which must be explicitly popped by GCC@.
10343 An input register that is implicitly popped by the @code{asm} must be
10344 explicitly clobbered, unless it is constrained to match an
10348 For any input register that is implicitly popped by an @code{asm}, it is
10349 necessary to know how to adjust the stack to compensate for the pop.
10350 If any non-popped input is closer to the top of the reg-stack than
10351 the implicitly popped register, it would not be possible to know what the
10352 stack looked like---it's not clear how the rest of the stack ``slides
10355 All implicitly popped input registers must be closer to the top of
10356 the reg-stack than any input that is not implicitly popped.
10358 It is possible that if an input dies in an @code{asm}, the compiler might
10359 use the input register for an output reload. Consider this example:
10362 asm ("foo" : "=t" (a) : "f" (b));
10366 This code says that input @code{b} is not popped by the @code{asm}, and that
10367 the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one
10368 deeper after the @code{asm} than it was before. But, it is possible that
10369 reload may think that it can use the same register for both the input and
10372 To prevent this from happening,
10373 if any input operand uses the @samp{f} constraint, all output register
10374 constraints must use the @samp{&} early-clobber modifier.
10376 The example above is correctly written as:
10379 asm ("foo" : "=&t" (a) : "f" (b));
10383 Some operands need to be in particular places on the stack. All
10384 output operands fall in this category---GCC has no other way to
10385 know which registers the outputs appear in unless you indicate
10386 this in the constraints.
10388 Output operands must specifically indicate which register an output
10389 appears in after an @code{asm}. @samp{=f} is not allowed: the operand
10390 constraints must select a class with a single register.
10393 Output operands may not be ``inserted'' between existing stack registers.
10394 Since no 387 opcode uses a read/write operand, all output operands
10395 are dead before the @code{asm}, and are pushed by the @code{asm}.
10396 It makes no sense to push anywhere but the top of the reg-stack.
10398 Output operands must start at the top of the reg-stack: output
10399 operands may not ``skip'' a register.
10402 Some @code{asm} statements may need extra stack space for internal
10403 calculations. This can be guaranteed by clobbering stack registers
10404 unrelated to the inputs and outputs.
10409 takes one input, which is internally popped, and produces two outputs.
10412 asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
10416 This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode,
10417 and replaces them with one output. The @code{st(1)} clobber is necessary
10418 for the compiler to know that @code{fyl2xp1} pops both inputs.
10421 asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
10429 @subsection Controlling Names Used in Assembler Code
10430 @cindex assembler names for identifiers
10431 @cindex names used in assembler code
10432 @cindex identifiers, names in assembler code
10434 You can specify the name to be used in the assembler code for a C
10435 function or variable by writing the @code{asm} (or @code{__asm__})
10436 keyword after the declarator.
10437 It is up to you to make sure that the assembler names you choose do not
10438 conflict with any other assembler symbols, or reference registers.
10440 @subsubheading Assembler names for data:
10442 This sample shows how to specify the assembler name for data:
10445 int foo asm ("myfoo") = 2;
10449 This specifies that the name to be used for the variable @code{foo} in
10450 the assembler code should be @samp{myfoo} rather than the usual
10453 On systems where an underscore is normally prepended to the name of a C
10454 variable, this feature allows you to define names for the
10455 linker that do not start with an underscore.
10457 GCC does not support using this feature with a non-static local variable
10458 since such variables do not have assembler names. If you are
10459 trying to put the variable in a particular register, see
10460 @ref{Explicit Register Variables}.
10462 @subsubheading Assembler names for functions:
10464 To specify the assembler name for functions, write a declaration for the
10465 function before its definition and put @code{asm} there, like this:
10468 int func (int x, int y) asm ("MYFUNC");
10470 int func (int x, int y)
10476 This specifies that the name to be used for the function @code{func} in
10477 the assembler code should be @code{MYFUNC}.
10479 @node Explicit Register Variables
10480 @subsection Variables in Specified Registers
10481 @anchor{Explicit Reg Vars}
10482 @cindex explicit register variables
10483 @cindex variables in specified registers
10484 @cindex specified registers
10486 GNU C allows you to associate specific hardware registers with C
10487 variables. In almost all cases, allowing the compiler to assign
10488 registers produces the best code. However under certain unusual
10489 circumstances, more precise control over the variable storage is
10492 Both global and local variables can be associated with a register. The
10493 consequences of performing this association are very different between
10494 the two, as explained in the sections below.
10497 * Global Register Variables:: Variables declared at global scope.
10498 * Local Register Variables:: Variables declared within a function.
10501 @node Global Register Variables
10502 @subsubsection Defining Global Register Variables
10503 @anchor{Global Reg Vars}
10504 @cindex global register variables
10505 @cindex registers, global variables in
10506 @cindex registers, global allocation
10508 You can define a global register variable and associate it with a specified
10509 register like this:
10512 register int *foo asm ("r12");
10516 Here @code{r12} is the name of the register that should be used. Note that
10517 this is the same syntax used for defining local register variables, but for
10518 a global variable the declaration appears outside a function. The
10519 @code{register} keyword is required, and cannot be combined with
10520 @code{static}. The register name must be a valid register name for the
10523 Do not use type qualifiers such as @code{const} and @code{volatile}, as
10524 the outcome may be contrary to expectations. In particular, using the
10525 @code{volatile} qualifier does not fully prevent the compiler from
10526 optimizing accesses to the register.
10528 Registers are a scarce resource on most systems and allowing the
10529 compiler to manage their usage usually results in the best code. However,
10530 under special circumstances it can make sense to reserve some globally.
10531 For example this may be useful in programs such as programming language
10532 interpreters that have a couple of global variables that are accessed
10535 After defining a global register variable, for the current compilation
10539 @item If the register is a call-saved register, call ABI is affected:
10540 the register will not be restored in function epilogue sequences after
10541 the variable has been assigned. Therefore, functions cannot safely
10542 return to callers that assume standard ABI.
10543 @item Conversely, if the register is a call-clobbered register, making
10544 calls to functions that use standard ABI may lose contents of the variable.
10545 Such calls may be created by the compiler even if none are evident in
10546 the original program, for example when libgcc functions are used to
10547 make up for unavailable instructions.
10548 @item Accesses to the variable may be optimized as usual and the register
10549 remains available for allocation and use in any computations, provided that
10550 observable values of the variable are not affected.
10551 @item If the variable is referenced in inline assembly, the type of access
10552 must be provided to the compiler via constraints (@pxref{Constraints}).
10553 Accesses from basic asms are not supported.
10556 Note that these points @emph{only} apply to code that is compiled with the
10557 definition. The behavior of code that is merely linked in (for example
10558 code from libraries) is not affected.
10560 If you want to recompile source files that do not actually use your global
10561 register variable so they do not use the specified register for any other
10562 purpose, you need not actually add the global register declaration to
10563 their source code. It suffices to specify the compiler option
10564 @option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the
10567 @subsubheading Declaring the variable
10569 Global register variables cannot have initial values, because an
10570 executable file has no means to supply initial contents for a register.
10572 When selecting a register, choose one that is normally saved and
10573 restored by function calls on your machine. This ensures that code
10574 which is unaware of this reservation (such as library routines) will
10575 restore it before returning.
10577 On machines with register windows, be sure to choose a global
10578 register that is not affected magically by the function call mechanism.
10580 @subsubheading Using the variable
10582 @cindex @code{qsort}, and global register variables
10583 When calling routines that are not aware of the reservation, be
10584 cautious if those routines call back into code which uses them. As an
10585 example, if you call the system library version of @code{qsort}, it may
10586 clobber your registers during execution, but (if you have selected
10587 appropriate registers) it will restore them before returning. However
10588 it will @emph{not} restore them before calling @code{qsort}'s comparison
10589 function. As a result, global values will not reliably be available to
10590 the comparison function unless the @code{qsort} function itself is rebuilt.
10592 Similarly, it is not safe to access the global register variables from signal
10593 handlers or from more than one thread of control. Unless you recompile
10594 them specially for the task at hand, the system library routines may
10595 temporarily use the register for other things. Furthermore, since the register
10596 is not reserved exclusively for the variable, accessing it from handlers of
10597 asynchronous signals may observe unrelated temporary values residing in the
10600 @cindex register variable after @code{longjmp}
10601 @cindex global register after @code{longjmp}
10602 @cindex value after @code{longjmp}
10605 On most machines, @code{longjmp} restores to each global register
10606 variable the value it had at the time of the @code{setjmp}. On some
10607 machines, however, @code{longjmp} does not change the value of global
10608 register variables. To be portable, the function that called @code{setjmp}
10609 should make other arrangements to save the values of the global register
10610 variables, and to restore them in a @code{longjmp}. This way, the same
10611 thing happens regardless of what @code{longjmp} does.
10613 @node Local Register Variables
10614 @subsubsection Specifying Registers for Local Variables
10615 @anchor{Local Reg Vars}
10616 @cindex local variables, specifying registers
10617 @cindex specifying registers for local variables
10618 @cindex registers for local variables
10620 You can define a local register variable and associate it with a specified
10621 register like this:
10624 register int *foo asm ("r12");
10628 Here @code{r12} is the name of the register that should be used. Note
10629 that this is the same syntax used for defining global register variables,
10630 but for a local variable the declaration appears within a function. The
10631 @code{register} keyword is required, and cannot be combined with
10632 @code{static}. The register name must be a valid register name for the
10635 Do not use type qualifiers such as @code{const} and @code{volatile}, as
10636 the outcome may be contrary to expectations. In particular, when the
10637 @code{const} qualifier is used, the compiler may substitute the
10638 variable with its initializer in @code{asm} statements, which may cause
10639 the corresponding operand to appear in a different register.
10641 As with global register variables, it is recommended that you choose
10642 a register that is normally saved and restored by function calls on your
10643 machine, so that calls to library routines will not clobber it.
10645 The only supported use for this feature is to specify registers
10646 for input and output operands when calling Extended @code{asm}
10647 (@pxref{Extended Asm}). This may be necessary if the constraints for a
10648 particular machine don't provide sufficient control to select the desired
10649 register. To force an operand into a register, create a local variable
10650 and specify the register name after the variable's declaration. Then use
10651 the local variable for the @code{asm} operand and specify any constraint
10652 letter that matches the register:
10655 register int *p1 asm ("r0") = @dots{};
10656 register int *p2 asm ("r1") = @dots{};
10657 register int *result asm ("r0");
10658 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
10661 @emph{Warning:} In the above example, be aware that a register (for example
10662 @code{r0}) can be call-clobbered by subsequent code, including function
10663 calls and library calls for arithmetic operators on other variables (for
10664 example the initialization of @code{p2}). In this case, use temporary
10665 variables for expressions between the register assignments:
10669 register int *p1 asm ("r0") = @dots{};
10670 register int *p2 asm ("r1") = t1;
10671 register int *result asm ("r0");
10672 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
10675 Defining a register variable does not reserve the register. Other than
10676 when invoking the Extended @code{asm}, the contents of the specified
10677 register are not guaranteed. For this reason, the following uses
10678 are explicitly @emph{not} supported. If they appear to work, it is only
10679 happenstance, and may stop working as intended due to (seemingly)
10680 unrelated changes in surrounding code, or even minor changes in the
10681 optimization of a future version of gcc:
10684 @item Passing parameters to or from Basic @code{asm}
10685 @item Passing parameters to or from Extended @code{asm} without using input
10686 or output operands.
10687 @item Passing parameters to or from routines written in assembler (or
10688 other languages) using non-standard calling conventions.
10691 Some developers use Local Register Variables in an attempt to improve
10692 gcc's allocation of registers, especially in large functions. In this
10693 case the register name is essentially a hint to the register allocator.
10694 While in some instances this can generate better code, improvements are
10695 subject to the whims of the allocator/optimizers. Since there are no
10696 guarantees that your improvements won't be lost, this usage of Local
10697 Register Variables is discouraged.
10699 On the MIPS platform, there is related use for local register variables
10700 with slightly different characteristics (@pxref{MIPS Coprocessors,,
10701 Defining coprocessor specifics for MIPS targets, gccint,
10702 GNU Compiler Collection (GCC) Internals}).
10704 @node Size of an asm
10705 @subsection Size of an @code{asm}
10707 Some targets require that GCC track the size of each instruction used
10708 in order to generate correct code. Because the final length of the
10709 code produced by an @code{asm} statement is only known by the
10710 assembler, GCC must make an estimate as to how big it will be. It
10711 does this by counting the number of instructions in the pattern of the
10712 @code{asm} and multiplying that by the length of the longest
10713 instruction supported by that processor. (When working out the number
10714 of instructions, it assumes that any occurrence of a newline or of
10715 whatever statement separator character is supported by the assembler ---
10716 typically @samp{;} --- indicates the end of an instruction.)
10718 Normally, GCC's estimate is adequate to ensure that correct
10719 code is generated, but it is possible to confuse the compiler if you use
10720 pseudo instructions or assembler macros that expand into multiple real
10721 instructions, or if you use assembler directives that expand to more
10722 space in the object file than is needed for a single instruction.
10723 If this happens then the assembler may produce a diagnostic saying that
10724 a label is unreachable.
10726 @cindex @code{asm inline}
10727 This size is also used for inlining decisions. If you use @code{asm inline}
10728 instead of just @code{asm}, then for inlining purposes the size of the asm
10729 is taken as the minimum size, ignoring how many instructions GCC thinks it is.
10731 @node Alternate Keywords
10732 @section Alternate Keywords
10733 @cindex alternate keywords
10734 @cindex keywords, alternate
10736 @option{-ansi} and the various @option{-std} options disable certain
10737 keywords. This causes trouble when you want to use GNU C extensions, or
10738 a general-purpose header file that should be usable by all programs,
10739 including ISO C programs. The keywords @code{asm}, @code{typeof} and
10740 @code{inline} are not available in programs compiled with
10741 @option{-ansi} or @option{-std} (although @code{inline} can be used in a
10742 program compiled with @option{-std=c99} or @option{-std=c11}). The
10744 @code{restrict} is only available when @option{-std=gnu99} (which will
10745 eventually be the default) or @option{-std=c99} (or the equivalent
10746 @option{-std=iso9899:1999}), or an option for a later standard
10749 The way to solve these problems is to put @samp{__} at the beginning and
10750 end of each problematical keyword. For example, use @code{__asm__}
10751 instead of @code{asm}, and @code{__inline__} instead of @code{inline}.
10753 Other C compilers won't accept these alternative keywords; if you want to
10754 compile with another compiler, you can define the alternate keywords as
10755 macros to replace them with the customary keywords. It looks like this:
10759 #define __asm__ asm
10763 @findex __extension__
10765 @option{-pedantic} and other options cause warnings for many GNU C extensions.
10767 prevent such warnings within one expression by writing
10768 @code{__extension__} before the expression. @code{__extension__} has no
10769 effect aside from this.
10771 @node Incomplete Enums
10772 @section Incomplete @code{enum} Types
10774 You can define an @code{enum} tag without specifying its possible values.
10775 This results in an incomplete type, much like what you get if you write
10776 @code{struct foo} without describing the elements. A later declaration
10777 that does specify the possible values completes the type.
10779 You cannot allocate variables or storage using the type while it is
10780 incomplete. However, you can work with pointers to that type.
10782 This extension may not be very useful, but it makes the handling of
10783 @code{enum} more consistent with the way @code{struct} and @code{union}
10786 This extension is not supported by GNU C++.
10788 @node Function Names
10789 @section Function Names as Strings
10790 @cindex @code{__func__} identifier
10791 @cindex @code{__FUNCTION__} identifier
10792 @cindex @code{__PRETTY_FUNCTION__} identifier
10794 GCC provides three magic constants that hold the name of the current
10795 function as a string. In C++11 and later modes, all three are treated
10796 as constant expressions and can be used in @code{constexpr} constexts.
10797 The first of these constants is @code{__func__}, which is part of
10800 The identifier @code{__func__} is implicitly declared by the translator
10801 as if, immediately following the opening brace of each function
10802 definition, the declaration
10805 static const char __func__[] = "function-name";
10809 appeared, where function-name is the name of the lexically-enclosing
10810 function. This name is the unadorned name of the function. As an
10811 extension, at file (or, in C++, namespace scope), @code{__func__}
10812 evaluates to the empty string.
10814 @code{__FUNCTION__} is another name for @code{__func__}, provided for
10815 backward compatibility with old versions of GCC.
10817 In C, @code{__PRETTY_FUNCTION__} is yet another name for
10818 @code{__func__}, except that at file scope (or, in C++, namespace scope),
10819 it evaluates to the string @code{"top level"}. In addition, in C++,
10820 @code{__PRETTY_FUNCTION__} contains the signature of the function as
10821 well as its bare name. For example, this program:
10824 extern "C" int printf (const char *, ...);
10830 printf ("__FUNCTION__ = %s\n", __FUNCTION__);
10831 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
10849 __PRETTY_FUNCTION__ = void a::sub(int)
10852 These identifiers are variables, not preprocessor macros, and may not
10853 be used to initialize @code{char} arrays or be concatenated with string
10856 @node Return Address
10857 @section Getting the Return or Frame Address of a Function
10859 These functions may be used to get information about the callers of a
10862 @deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level})
10863 This function returns the return address of the current function, or of
10864 one of its callers. The @var{level} argument is number of frames to
10865 scan up the call stack. A value of @code{0} yields the return address
10866 of the current function, a value of @code{1} yields the return address
10867 of the caller of the current function, and so forth. When inlining
10868 the expected behavior is that the function returns the address of
10869 the function that is returned to. To work around this behavior use
10870 the @code{noinline} function attribute.
10872 The @var{level} argument must be a constant integer.
10874 On some machines it may be impossible to determine the return address of
10875 any function other than the current one; in such cases, or when the top
10876 of the stack has been reached, this function returns @code{0} or a
10877 random value. In addition, @code{__builtin_frame_address} may be used
10878 to determine if the top of the stack has been reached.
10880 Additional post-processing of the returned value may be needed, see
10881 @code{__builtin_extract_return_addr}.
10883 Calling this function with a nonzero argument can have unpredictable
10884 effects, including crashing the calling program. As a result, calls
10885 that are considered unsafe are diagnosed when the @option{-Wframe-address}
10886 option is in effect. Such calls should only be made in debugging
10890 @deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr})
10891 The address as returned by @code{__builtin_return_address} may have to be fed
10892 through this function to get the actual encoded address. For example, on the
10893 31-bit S/390 platform the highest bit has to be masked out, or on SPARC
10894 platforms an offset has to be added for the true next instruction to be
10897 If no fixup is needed, this function simply passes through @var{addr}.
10900 @deftypefn {Built-in Function} {void *} __builtin_frob_return_address (void *@var{addr})
10901 This function does the reverse of @code{__builtin_extract_return_addr}.
10904 @deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level})
10905 This function is similar to @code{__builtin_return_address}, but it
10906 returns the address of the function frame rather than the return address
10907 of the function. Calling @code{__builtin_frame_address} with a value of
10908 @code{0} yields the frame address of the current function, a value of
10909 @code{1} yields the frame address of the caller of the current function,
10912 The frame is the area on the stack that holds local variables and saved
10913 registers. The frame address is normally the address of the first word
10914 pushed on to the stack by the function. However, the exact definition
10915 depends upon the processor and the calling convention. If the processor
10916 has a dedicated frame pointer register, and the function has a frame,
10917 then @code{__builtin_frame_address} returns the value of the frame
10920 On some machines it may be impossible to determine the frame address of
10921 any function other than the current one; in such cases, or when the top
10922 of the stack has been reached, this function returns @code{0} if
10923 the first frame pointer is properly initialized by the startup code.
10925 Calling this function with a nonzero argument can have unpredictable
10926 effects, including crashing the calling program. As a result, calls
10927 that are considered unsafe are diagnosed when the @option{-Wframe-address}
10928 option is in effect. Such calls should only be made in debugging
10932 @node Vector Extensions
10933 @section Using Vector Instructions through Built-in Functions
10935 On some targets, the instruction set contains SIMD vector instructions which
10936 operate on multiple values contained in one large register at the same time.
10937 For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used
10940 The first step in using these extensions is to provide the necessary data
10941 types. This should be done using an appropriate @code{typedef}:
10944 typedef int v4si __attribute__ ((vector_size (16)));
10948 The @code{int} type specifies the @dfn{base type}, while the attribute specifies
10949 the vector size for the variable, measured in bytes. For example, the
10950 declaration above causes the compiler to set the mode for the @code{v4si}
10951 type to be 16 bytes wide and divided into @code{int} sized units. For
10952 a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the
10953 corresponding mode of @code{foo} is @acronym{V4SI}.
10955 The @code{vector_size} attribute is only applicable to integral and
10956 floating scalars, although arrays, pointers, and function return values
10957 are allowed in conjunction with this construct. Only sizes that are
10958 positive power-of-two multiples of the base type size are currently allowed.
10960 All the basic integer types can be used as base types, both as signed
10961 and as unsigned: @code{char}, @code{short}, @code{int}, @code{long},
10962 @code{long long}. In addition, @code{float} and @code{double} can be
10963 used to build floating-point vector types.
10965 Specifying a combination that is not valid for the current architecture
10966 causes GCC to synthesize the instructions using a narrower mode.
10967 For example, if you specify a variable of type @code{V4SI} and your
10968 architecture does not allow for this specific SIMD type, GCC
10969 produces code that uses 4 @code{SIs}.
10971 The types defined in this manner can be used with a subset of normal C
10972 operations. Currently, GCC allows using the following operators
10973 on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@.
10975 The operations behave like C++ @code{valarrays}. Addition is defined as
10976 the addition of the corresponding elements of the operands. For
10977 example, in the code below, each of the 4 elements in @var{a} is
10978 added to the corresponding 4 elements in @var{b} and the resulting
10979 vector is stored in @var{c}.
10982 typedef int v4si __attribute__ ((vector_size (16)));
10989 Subtraction, multiplication, division, and the logical operations
10990 operate in a similar manner. Likewise, the result of using the unary
10991 minus or complement operators on a vector type is a vector whose
10992 elements are the negative or complemented values of the corresponding
10993 elements in the operand.
10995 It is possible to use shifting operators @code{<<}, @code{>>} on
10996 integer-type vectors. The operation is defined as following: @code{@{a0,
10997 a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1,
10998 @dots{}, an >> bn@}}@. Vector operands must have the same number of
11001 For convenience, it is allowed to use a binary vector operation
11002 where one operand is a scalar. In that case the compiler transforms
11003 the scalar operand into a vector where each element is the scalar from
11004 the operation. The transformation happens only if the scalar could be
11005 safely converted to the vector-element type.
11006 Consider the following code.
11009 typedef int v4si __attribute__ ((vector_size (16)));
11014 a = b + 1; /* a = b + @{1,1,1,1@}; */
11015 a = 2 * b; /* a = @{2,2,2,2@} * b; */
11017 a = l + a; /* Error, cannot convert long to int. */
11020 Vectors can be subscripted as if the vector were an array with
11021 the same number of elements and base type. Out of bound accesses
11022 invoke undefined behavior at run time. Warnings for out of bound
11023 accesses for vector subscription can be enabled with
11024 @option{-Warray-bounds}.
11026 Vector comparison is supported with standard comparison
11027 operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be
11028 vector expressions of integer-type or real-type. Comparison between
11029 integer-type vectors and real-type vectors are not supported. The
11030 result of the comparison is a vector of the same width and number of
11031 elements as the comparison operands with a signed integral element
11034 Vectors are compared element-wise producing 0 when comparison is false
11035 and -1 (constant of the appropriate type where all bits are set)
11036 otherwise. Consider the following example.
11039 typedef int v4si __attribute__ ((vector_size (16)));
11041 v4si a = @{1,2,3,4@};
11042 v4si b = @{3,2,1,4@};
11045 c = a > b; /* The result would be @{0, 0,-1, 0@} */
11046 c = a == b; /* The result would be @{0,-1, 0,-1@} */
11049 In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where
11050 @code{b} and @code{c} are vectors of the same type and @code{a} is an
11051 integer vector with the same number of elements of the same size as @code{b}
11052 and @code{c}, computes all three arguments and creates a vector
11053 @code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in
11054 OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}.
11055 As in the case of binary operations, this syntax is also accepted when
11056 one of @code{b} or @code{c} is a scalar that is then transformed into a
11057 vector. If both @code{b} and @code{c} are scalars and the type of
11058 @code{true?b:c} has the same size as the element type of @code{a}, then
11059 @code{b} and @code{c} are converted to a vector type whose elements have
11060 this type and with the same number of elements as @code{a}.
11062 In C++, the logic operators @code{!, &&, ||} are available for vectors.
11063 @code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to
11064 @code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}.
11065 For mixed operations between a scalar @code{s} and a vector @code{v},
11066 @code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is
11067 short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}.
11069 @findex __builtin_shuffle
11070 Vector shuffling is available using functions
11071 @code{__builtin_shuffle (vec, mask)} and
11072 @code{__builtin_shuffle (vec0, vec1, mask)}.
11073 Both functions construct a permutation of elements from one or two
11074 vectors and return a vector of the same type as the input vector(s).
11075 The @var{mask} is an integral vector with the same width (@var{W})
11076 and element count (@var{N}) as the output vector.
11078 The elements of the input vectors are numbered in memory ordering of
11079 @var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The
11080 elements of @var{mask} are considered modulo @var{N} in the single-operand
11081 case and modulo @math{2*@var{N}} in the two-operand case.
11083 Consider the following example,
11086 typedef int v4si __attribute__ ((vector_size (16)));
11088 v4si a = @{1,2,3,4@};
11089 v4si b = @{5,6,7,8@};
11090 v4si mask1 = @{0,1,1,3@};
11091 v4si mask2 = @{0,4,2,5@};
11094 res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */
11095 res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */
11098 Note that @code{__builtin_shuffle} is intentionally semantically
11099 compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions.
11101 You can declare variables and use them in function calls and returns, as
11102 well as in assignments and some casts. You can specify a vector type as
11103 a return type for a function. Vector types can also be used as function
11104 arguments. It is possible to cast from one vector type to another,
11105 provided they are of the same size (in fact, you can also cast vectors
11106 to and from other datatypes of the same size).
11108 You cannot operate between vectors of different lengths or different
11109 signedness without a cast.
11111 @findex __builtin_convertvector
11112 Vector conversion is available using the
11113 @code{__builtin_convertvector (vec, vectype)}
11114 function. @var{vec} must be an expression with integral or floating
11115 vector type and @var{vectype} an integral or floating vector type with the
11116 same number of elements. The result has @var{vectype} type and value of
11117 a C cast of every element of @var{vec} to the element type of @var{vectype}.
11119 Consider the following example,
11121 typedef int v4si __attribute__ ((vector_size (16)));
11122 typedef float v4sf __attribute__ ((vector_size (16)));
11123 typedef double v4df __attribute__ ((vector_size (32)));
11124 typedef unsigned long long v4di __attribute__ ((vector_size (32)));
11126 v4si a = @{1,-2,3,-4@};
11127 v4sf b = @{1.5f,-2.5f,3.f,7.f@};
11128 v4di c = @{1ULL,5ULL,0ULL,10ULL@};
11129 v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */
11131 v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */
11132 v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */
11133 v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */
11134 v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */
11135 v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */
11138 @cindex vector types, using with x86 intrinsics
11139 Sometimes it is desirable to write code using a mix of generic vector
11140 operations (for clarity) and machine-specific vector intrinsics (to
11141 access vector instructions that are not exposed via generic built-ins).
11142 On x86, intrinsic functions for integer vectors typically use the same
11143 vector type @code{__m128i} irrespective of how they interpret the vector,
11144 making it necessary to cast their arguments and return values from/to
11145 other vector types. In C, you can make use of a @code{union} type:
11146 @c In C++ such type punning via a union is not allowed by the language
11148 #include <immintrin.h>
11150 typedef unsigned char u8x16 __attribute__ ((vector_size (16)));
11151 typedef unsigned int u32x4 __attribute__ ((vector_size (16)));
11161 for variables that can be used with both built-in operators and x86
11165 v128 x, y = @{ 0 @};
11166 memcpy (&x, ptr, sizeof x);
11168 x.mm = _mm_adds_epu8 (x.mm, y.mm);
11171 /* Instead of a variable, a compound literal may be used to pass the
11172 return value of an intrinsic call to a function expecting the union: */
11174 x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@});
11175 @c This could be done implicitly with __attribute__((transparent_union)),
11176 @c but GCC does not accept it for unions of vector types (PR 88955).
11180 @section Support for @code{offsetof}
11181 @findex __builtin_offsetof
11183 GCC implements for both C and C++ a syntactic extension to implement
11184 the @code{offsetof} macro.
11188 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
11190 offsetof_member_designator:
11192 | offsetof_member_designator "." @code{identifier}
11193 | offsetof_member_designator "[" @code{expr} "]"
11196 This extension is sufficient such that
11199 #define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member})
11203 is a suitable definition of the @code{offsetof} macro. In C++, @var{type}
11204 may be dependent. In either case, @var{member} may consist of a single
11205 identifier, or a sequence of member accesses and array references.
11207 @node __sync Builtins
11208 @section Legacy @code{__sync} Built-in Functions for Atomic Memory Access
11210 The following built-in functions
11211 are intended to be compatible with those described
11212 in the @cite{Intel Itanium Processor-specific Application Binary Interface},
11213 section 7.4. As such, they depart from normal GCC practice by not using
11214 the @samp{__builtin_} prefix and also by being overloaded so that they
11215 work on multiple types.
11217 The definition given in the Intel documentation allows only for the use of
11218 the types @code{int}, @code{long}, @code{long long} or their unsigned
11219 counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in
11220 size other than the C type @code{_Bool} or the C++ type @code{bool}.
11221 Operations on pointer arguments are performed as if the operands were
11222 of the @code{uintptr_t} type. That is, they are not scaled by the size
11223 of the type to which the pointer points.
11225 These functions are implemented in terms of the @samp{__atomic}
11226 builtins (@pxref{__atomic Builtins}). They should not be used for new
11227 code which should use the @samp{__atomic} builtins instead.
11229 Not all operations are supported by all target processors. If a particular
11230 operation cannot be implemented on the target processor, a warning is
11231 generated and a call to an external function is generated. The external
11232 function carries the same name as the built-in version,
11233 with an additional suffix
11234 @samp{_@var{n}} where @var{n} is the size of the data type.
11236 @c ??? Should we have a mechanism to suppress this warning? This is almost
11237 @c useful for implementing the operation under the control of an external
11240 In most cases, these built-in functions are considered a @dfn{full barrier}.
11242 no memory operand is moved across the operation, either forward or
11243 backward. Further, instructions are issued as necessary to prevent the
11244 processor from speculating loads across the operation and from queuing stores
11245 after the operation.
11247 All of the routines are described in the Intel documentation to take
11248 ``an optional list of variables protected by the memory barrier''. It's
11249 not clear what is meant by that; it could mean that @emph{only} the
11250 listed variables are protected, or it could mean a list of additional
11251 variables to be protected. The list is ignored by GCC which treats it as
11252 empty. GCC interprets an empty list as meaning that all globally
11253 accessible variables should be protected.
11256 @item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...)
11257 @itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...)
11258 @itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...)
11259 @itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...)
11260 @itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...)
11261 @itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...)
11262 @findex __sync_fetch_and_add
11263 @findex __sync_fetch_and_sub
11264 @findex __sync_fetch_and_or
11265 @findex __sync_fetch_and_and
11266 @findex __sync_fetch_and_xor
11267 @findex __sync_fetch_and_nand
11268 These built-in functions perform the operation suggested by the name, and
11269 returns the value that had previously been in memory. That is, operations
11270 on integer operands have the following semantics. Operations on pointer
11271 arguments are performed as if the operands were of the @code{uintptr_t}
11272 type. That is, they are not scaled by the size of the type to which
11273 the pointer points.
11276 @{ tmp = *ptr; *ptr @var{op}= value; return tmp; @}
11277 @{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand
11280 The object pointed to by the first argument must be of integer or pointer
11281 type. It must not be a boolean type.
11283 @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand}
11284 as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}.
11286 @item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...)
11287 @itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...)
11288 @itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...)
11289 @itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...)
11290 @itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...)
11291 @itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...)
11292 @findex __sync_add_and_fetch
11293 @findex __sync_sub_and_fetch
11294 @findex __sync_or_and_fetch
11295 @findex __sync_and_and_fetch
11296 @findex __sync_xor_and_fetch
11297 @findex __sync_nand_and_fetch
11298 These built-in functions perform the operation suggested by the name, and
11299 return the new value. That is, operations on integer operands have
11300 the following semantics. Operations on pointer operands are performed as
11301 if the operand's type were @code{uintptr_t}.
11304 @{ *ptr @var{op}= value; return *ptr; @}
11305 @{ *ptr = ~(*ptr & value); return *ptr; @} // nand
11308 The same constraints on arguments apply as for the corresponding
11309 @code{__sync_op_and_fetch} built-in functions.
11311 @emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch}
11312 as @code{*ptr = ~(*ptr & value)} instead of
11313 @code{*ptr = ~*ptr & value}.
11315 @item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
11316 @itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
11317 @findex __sync_bool_compare_and_swap
11318 @findex __sync_val_compare_and_swap
11319 These built-in functions perform an atomic compare and swap.
11320 That is, if the current
11321 value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into
11324 The ``bool'' version returns @code{true} if the comparison is successful and
11325 @var{newval} is written. The ``val'' version returns the contents
11326 of @code{*@var{ptr}} before the operation.
11328 @item __sync_synchronize (...)
11329 @findex __sync_synchronize
11330 This built-in function issues a full memory barrier.
11332 @item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...)
11333 @findex __sync_lock_test_and_set
11334 This built-in function, as described by Intel, is not a traditional test-and-set
11335 operation, but rather an atomic exchange operation. It writes @var{value}
11336 into @code{*@var{ptr}}, and returns the previous contents of
11339 Many targets have only minimal support for such locks, and do not support
11340 a full exchange operation. In this case, a target may support reduced
11341 functionality here by which the @emph{only} valid value to store is the
11342 immediate constant 1. The exact value actually stored in @code{*@var{ptr}}
11343 is implementation defined.
11345 This built-in function is not a full barrier,
11346 but rather an @dfn{acquire barrier}.
11347 This means that references after the operation cannot move to (or be
11348 speculated to) before the operation, but previous memory stores may not
11349 be globally visible yet, and previous memory loads may not yet be
11352 @item void __sync_lock_release (@var{type} *ptr, ...)
11353 @findex __sync_lock_release
11354 This built-in function releases the lock acquired by
11355 @code{__sync_lock_test_and_set}.
11356 Normally this means writing the constant 0 to @code{*@var{ptr}}.
11358 This built-in function is not a full barrier,
11359 but rather a @dfn{release barrier}.
11360 This means that all previous memory stores are globally visible, and all
11361 previous memory loads have been satisfied, but following memory reads
11362 are not prevented from being speculated to before the barrier.
11365 @node __atomic Builtins
11366 @section Built-in Functions for Memory Model Aware Atomic Operations
11368 The following built-in functions approximately match the requirements
11369 for the C++11 memory model. They are all
11370 identified by being prefixed with @samp{__atomic} and most are
11371 overloaded so that they work with multiple types.
11373 These functions are intended to replace the legacy @samp{__sync}
11374 builtins. The main difference is that the memory order that is requested
11375 is a parameter to the functions. New code should always use the
11376 @samp{__atomic} builtins rather than the @samp{__sync} builtins.
11378 Note that the @samp{__atomic} builtins assume that programs will
11379 conform to the C++11 memory model. In particular, they assume
11380 that programs are free of data races. See the C++11 standard for
11381 detailed requirements.
11383 The @samp{__atomic} builtins can be used with any integral scalar or
11384 pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral
11385 types are also allowed if @samp{__int128} (@pxref{__int128}) is
11386 supported by the architecture.
11388 The four non-arithmetic functions (load, store, exchange, and
11389 compare_exchange) all have a generic version as well. This generic
11390 version works on any data type. It uses the lock-free built-in function
11391 if the specific data type size makes that possible; otherwise, an
11392 external call is left to be resolved at run time. This external call is
11393 the same format with the addition of a @samp{size_t} parameter inserted
11394 as the first parameter indicating the size of the object being pointed to.
11395 All objects must be the same size.
11397 There are 6 different memory orders that can be specified. These map
11398 to the C++11 memory orders with the same names, see the C++11 standard
11399 or the @uref{http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki
11400 on atomic synchronization} for detailed definitions. Individual
11401 targets may also support additional memory orders for use on specific
11402 architectures. Refer to the target documentation for details of
11405 An atomic operation can both constrain code motion and
11406 be mapped to hardware instructions for synchronization between threads
11407 (e.g., a fence). To which extent this happens is controlled by the
11408 memory orders, which are listed here in approximately ascending order of
11409 strength. The description of each memory order is only meant to roughly
11410 illustrate the effects and is not a specification; see the C++11
11411 memory model for precise semantics.
11414 @item __ATOMIC_RELAXED
11415 Implies no inter-thread ordering constraints.
11416 @item __ATOMIC_CONSUME
11417 This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE}
11418 memory order because of a deficiency in C++11's semantics for
11419 @code{memory_order_consume}.
11420 @item __ATOMIC_ACQUIRE
11421 Creates an inter-thread happens-before constraint from the release (or
11422 stronger) semantic store to this acquire load. Can prevent hoisting
11423 of code to before the operation.
11424 @item __ATOMIC_RELEASE
11425 Creates an inter-thread happens-before constraint to acquire (or stronger)
11426 semantic loads that read from this release store. Can prevent sinking
11427 of code to after the operation.
11428 @item __ATOMIC_ACQ_REL
11429 Combines the effects of both @code{__ATOMIC_ACQUIRE} and
11430 @code{__ATOMIC_RELEASE}.
11431 @item __ATOMIC_SEQ_CST
11432 Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations.
11435 Note that in the C++11 memory model, @emph{fences} (e.g.,
11436 @samp{__atomic_thread_fence}) take effect in combination with other
11437 atomic operations on specific memory locations (e.g., atomic loads);
11438 operations on specific memory locations do not necessarily affect other
11439 operations in the same way.
11441 Target architectures are encouraged to provide their own patterns for
11442 each of the atomic built-in functions. If no target is provided, the original
11443 non-memory model set of @samp{__sync} atomic built-in functions are
11444 used, along with any required synchronization fences surrounding it in
11445 order to achieve the proper behavior. Execution in this case is subject
11446 to the same restrictions as those built-in functions.
11448 If there is no pattern or mechanism to provide a lock-free instruction
11449 sequence, a call is made to an external routine with the same parameters
11450 to be resolved at run time.
11452 When implementing patterns for these built-in functions, the memory order
11453 parameter can be ignored as long as the pattern implements the most
11454 restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory
11455 orders execute correctly with this memory order but they may not execute as
11456 efficiently as they could with a more appropriate implementation of the
11457 relaxed requirements.
11459 Note that the C++11 standard allows for the memory order parameter to be
11460 determined at run time rather than at compile time. These built-in
11461 functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather
11462 than invoke a runtime library call or inline a switch statement. This is
11463 standard compliant, safe, and the simplest approach for now.
11465 The memory order parameter is a signed int, but only the lower 16 bits are
11466 reserved for the memory order. The remainder of the signed int is reserved
11467 for target use and should be 0. Use of the predefined atomic values
11468 ensures proper usage.
11470 @deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memorder)
11471 This built-in function implements an atomic load operation. It returns the
11472 contents of @code{*@var{ptr}}.
11474 The valid memory order variants are
11475 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
11476 and @code{__ATOMIC_CONSUME}.
11480 @deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder)
11481 This is the generic version of an atomic load. It returns the
11482 contents of @code{*@var{ptr}} in @code{*@var{ret}}.
11486 @deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder)
11487 This built-in function implements an atomic store operation. It writes
11488 @code{@var{val}} into @code{*@var{ptr}}.
11490 The valid memory order variants are
11491 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}.
11495 @deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder)
11496 This is the generic version of an atomic store. It stores the value
11497 of @code{*@var{val}} into @code{*@var{ptr}}.
11501 @deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder)
11502 This built-in function implements an atomic exchange operation. It writes
11503 @var{val} into @code{*@var{ptr}}, and returns the previous contents of
11506 The valid memory order variants are
11507 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
11508 @code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}.
11512 @deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder)
11513 This is the generic version of an atomic exchange. It stores the
11514 contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value
11515 of @code{*@var{ptr}} is copied into @code{*@var{ret}}.
11519 @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)
11520 This built-in function implements an atomic compare and exchange operation.
11521 This compares the contents of @code{*@var{ptr}} with the contents of
11522 @code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write}
11523 operation that writes @var{desired} into @code{*@var{ptr}}. If they are not
11524 equal, the operation is a @emph{read} and the current contents of
11525 @code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true}
11526 for weak compare_exchange, which may fail spuriously, and @code{false} for
11527 the strong variation, which never fails spuriously. Many targets
11528 only offer the strong variation and ignore the parameter. When in doubt, use
11529 the strong variation.
11531 If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned
11532 and memory is affected according to the
11533 memory order specified by @var{success_memorder}. There are no
11534 restrictions on what memory order can be used here.
11536 Otherwise, @code{false} is returned and memory is affected according
11537 to @var{failure_memorder}. This memory order cannot be
11538 @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a
11539 stronger order than that specified by @var{success_memorder}.
11543 @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)
11544 This built-in function implements the generic version of
11545 @code{__atomic_compare_exchange}. The function is virtually identical to
11546 @code{__atomic_compare_exchange_n}, except the desired value is also a
11551 @deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder)
11552 @deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder)
11553 @deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder)
11554 @deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder)
11555 @deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder)
11556 @deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder)
11557 These built-in functions perform the operation suggested by the name, and
11558 return the result of the operation. Operations on pointer arguments are
11559 performed as if the operands were of the @code{uintptr_t} type. That is,
11560 they are not scaled by the size of the type to which the pointer points.
11563 @{ *ptr @var{op}= val; return *ptr; @}
11564 @{ *ptr = ~(*ptr & val); return *ptr; @} // nand
11567 The object pointed to by the first argument must be of integer or pointer
11568 type. It must not be a boolean type. All memory orders are valid.
11572 @deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder)
11573 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder)
11574 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder)
11575 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder)
11576 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder)
11577 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder)
11578 These built-in functions perform the operation suggested by the name, and
11579 return the value that had previously been in @code{*@var{ptr}}. Operations
11580 on pointer arguments are performed as if the operands were of
11581 the @code{uintptr_t} type. That is, they are not scaled by the size of
11582 the type to which the pointer points.
11585 @{ tmp = *ptr; *ptr @var{op}= val; return tmp; @}
11586 @{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand
11589 The same constraints on arguments apply as for the corresponding
11590 @code{__atomic_op_fetch} built-in functions. All memory orders are valid.
11594 @deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memorder)
11596 This built-in function performs an atomic test-and-set operation on
11597 the byte at @code{*@var{ptr}}. The byte is set to some implementation
11598 defined nonzero ``set'' value and the return value is @code{true} if and only
11599 if the previous contents were ``set''.
11600 It should be only used for operands of type @code{bool} or @code{char}. For
11601 other types only part of the value may be set.
11603 All memory orders are valid.
11607 @deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memorder)
11609 This built-in function performs an atomic clear operation on
11610 @code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0.
11611 It should be only used for operands of type @code{bool} or @code{char} and
11612 in conjunction with @code{__atomic_test_and_set}.
11613 For other types it may only clear partially. If the type is not @code{bool}
11614 prefer using @code{__atomic_store}.
11616 The valid memory order variants are
11617 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and
11618 @code{__ATOMIC_RELEASE}.
11622 @deftypefn {Built-in Function} void __atomic_thread_fence (int memorder)
11624 This built-in function acts as a synchronization fence between threads
11625 based on the specified memory order.
11627 All memory orders are valid.
11631 @deftypefn {Built-in Function} void __atomic_signal_fence (int memorder)
11633 This built-in function acts as a synchronization fence between a thread
11634 and signal handlers based in the same thread.
11636 All memory orders are valid.
11640 @deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr)
11642 This built-in function returns @code{true} if objects of @var{size} bytes always
11643 generate lock-free atomic instructions for the target architecture.
11644 @var{size} must resolve to a compile-time constant and the result also
11645 resolves to a compile-time constant.
11647 @var{ptr} is an optional pointer to the object that may be used to determine
11648 alignment. A value of 0 indicates typical alignment should be used. The
11649 compiler may also ignore this parameter.
11652 if (__atomic_always_lock_free (sizeof (long long), 0))
11657 @deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr)
11659 This built-in function returns @code{true} if objects of @var{size} bytes always
11660 generate lock-free atomic instructions for the target architecture. If
11661 the built-in function is not known to be lock-free, a call is made to a
11662 runtime routine named @code{__atomic_is_lock_free}.
11664 @var{ptr} is an optional pointer to the object that may be used to determine
11665 alignment. A value of 0 indicates typical alignment should be used. The
11666 compiler may also ignore this parameter.
11669 @node Integer Overflow Builtins
11670 @section Built-in Functions to Perform Arithmetic with Overflow Checking
11672 The following built-in functions allow performing simple arithmetic operations
11673 together with checking whether the operations overflowed.
11675 @deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
11676 @deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res)
11677 @deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res)
11678 @deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res)
11679 @deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res)
11680 @deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
11681 @deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
11683 These built-in functions promote the first two operands into infinite precision signed
11684 type and perform addition on those promoted operands. The result is then
11685 cast to the type the third pointer argument points to and stored there.
11686 If the stored result is equal to the infinite precision result, the built-in
11687 functions return @code{false}, otherwise they return @code{true}. As the addition is
11688 performed in infinite signed precision, these built-in functions have fully defined
11689 behavior for all argument values.
11691 The first built-in function allows arbitrary integral types for operands and
11692 the result type must be pointer to some integral type other than enumerated or
11693 boolean type, the rest of the built-in functions have explicit integer types.
11695 The compiler will attempt to use hardware instructions to implement
11696 these built-in functions where possible, like conditional jump on overflow
11697 after addition, conditional jump on carry etc.
11701 @deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
11702 @deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res)
11703 @deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res)
11704 @deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res)
11705 @deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res)
11706 @deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
11707 @deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
11709 These built-in functions are similar to the add overflow checking built-in
11710 functions above, except they perform subtraction, subtract the second argument
11711 from the first one, instead of addition.
11715 @deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
11716 @deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res)
11717 @deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res)
11718 @deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res)
11719 @deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res)
11720 @deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
11721 @deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
11723 These built-in functions are similar to the add overflow checking built-in
11724 functions above, except they perform multiplication, instead of addition.
11728 The following built-in functions allow checking if simple arithmetic operation
11731 @deftypefn {Built-in Function} bool __builtin_add_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
11732 @deftypefnx {Built-in Function} bool __builtin_sub_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
11733 @deftypefnx {Built-in Function} bool __builtin_mul_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
11735 These built-in functions are similar to @code{__builtin_add_overflow},
11736 @code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that
11737 they don't store the result of the arithmetic operation anywhere and the
11738 last argument is not a pointer, but some expression with integral type other
11739 than enumerated or boolean type.
11741 The built-in functions promote the first two operands into infinite precision signed type
11742 and perform addition on those promoted operands. The result is then
11743 cast to the type of the third argument. If the cast result is equal to the infinite
11744 precision result, the built-in functions return @code{false}, otherwise they return @code{true}.
11745 The value of the third argument is ignored, just the side effects in the third argument
11746 are evaluated, and no integral argument promotions are performed on the last argument.
11747 If the third argument is a bit-field, the type used for the result cast has the
11748 precision and signedness of the given bit-field, rather than precision and signedness
11749 of the underlying type.
11751 For example, the following macro can be used to portably check, at
11752 compile-time, whether or not adding two constant integers will overflow,
11753 and perform the addition only when it is known to be safe and not to trigger
11754 a @option{-Woverflow} warning.
11757 #define INT_ADD_OVERFLOW_P(a, b) \
11758 __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0)
11761 A = INT_MAX, B = 3,
11762 C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B,
11763 D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0)
11767 The compiler will attempt to use hardware instructions to implement
11768 these built-in functions where possible, like conditional jump on overflow
11769 after addition, conditional jump on carry etc.
11773 @node x86 specific memory model extensions for transactional memory
11774 @section x86-Specific Memory Model Extensions for Transactional Memory
11776 The x86 architecture supports additional memory ordering flags
11777 to mark critical sections for hardware lock elision.
11778 These must be specified in addition to an existing memory order to
11782 @item __ATOMIC_HLE_ACQUIRE
11783 Start lock elision on a lock variable.
11784 Memory order must be @code{__ATOMIC_ACQUIRE} or stronger.
11785 @item __ATOMIC_HLE_RELEASE
11786 End lock elision on a lock variable.
11787 Memory order must be @code{__ATOMIC_RELEASE} or stronger.
11790 When a lock acquire fails, it is required for good performance to abort
11791 the transaction quickly. This can be done with a @code{_mm_pause}.
11794 #include <immintrin.h> // For _mm_pause
11798 /* Acquire lock with lock elision */
11799 while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE))
11800 _mm_pause(); /* Abort failed transaction */
11802 /* Free lock with lock elision */
11803 __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE);
11806 @node Object Size Checking
11807 @section Object Size Checking Built-in Functions
11808 @findex __builtin_object_size
11809 @findex __builtin___memcpy_chk
11810 @findex __builtin___mempcpy_chk
11811 @findex __builtin___memmove_chk
11812 @findex __builtin___memset_chk
11813 @findex __builtin___strcpy_chk
11814 @findex __builtin___stpcpy_chk
11815 @findex __builtin___strncpy_chk
11816 @findex __builtin___strcat_chk
11817 @findex __builtin___strncat_chk
11818 @findex __builtin___sprintf_chk
11819 @findex __builtin___snprintf_chk
11820 @findex __builtin___vsprintf_chk
11821 @findex __builtin___vsnprintf_chk
11822 @findex __builtin___printf_chk
11823 @findex __builtin___vprintf_chk
11824 @findex __builtin___fprintf_chk
11825 @findex __builtin___vfprintf_chk
11827 GCC implements a limited buffer overflow protection mechanism that can
11828 prevent some buffer overflow attacks by determining the sizes of objects
11829 into which data is about to be written and preventing the writes when
11830 the size isn't sufficient. The built-in functions described below yield
11831 the best results when used together and when optimization is enabled.
11832 For example, to detect object sizes across function boundaries or to
11833 follow pointer assignments through non-trivial control flow they rely
11834 on various optimization passes enabled with @option{-O2}. However, to
11835 a limited extent, they can be used without optimization as well.
11837 @deftypefn {Built-in Function} {size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
11838 is a built-in construct that returns a constant number of bytes from
11839 @var{ptr} to the end of the object @var{ptr} pointer points to
11840 (if known at compile time). To determine the sizes of dynamically allocated
11841 objects the function relies on the allocation functions called to obtain
11842 the storage to be declared with the @code{alloc_size} attribute (@pxref{Common
11843 Function Attributes}). @code{__builtin_object_size} never evaluates
11844 its arguments for side effects. If there are any side effects in them, it
11845 returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
11846 for @var{type} 2 or 3. If there are multiple objects @var{ptr} can
11847 point to and all of them are known at compile time, the returned number
11848 is the maximum of remaining byte counts in those objects if @var{type} & 2 is
11849 0 and minimum if nonzero. If it is not possible to determine which objects
11850 @var{ptr} points to at compile time, @code{__builtin_object_size} should
11851 return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
11852 for @var{type} 2 or 3.
11854 @var{type} is an integer constant from 0 to 3. If the least significant
11855 bit is clear, objects are whole variables, if it is set, a closest
11856 surrounding subobject is considered the object a pointer points to.
11857 The second bit determines if maximum or minimum of remaining bytes
11861 struct V @{ char buf1[10]; int b; char buf2[10]; @} var;
11862 char *p = &var.buf1[1], *q = &var.b;
11864 /* Here the object p points to is var. */
11865 assert (__builtin_object_size (p, 0) == sizeof (var) - 1);
11866 /* The subobject p points to is var.buf1. */
11867 assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1);
11868 /* The object q points to is var. */
11869 assert (__builtin_object_size (q, 0)
11870 == (char *) (&var + 1) - (char *) &var.b);
11871 /* The subobject q points to is var.b. */
11872 assert (__builtin_object_size (q, 1) == sizeof (var.b));
11876 There are built-in functions added for many common string operation
11877 functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk}
11878 built-in is provided. This built-in has an additional last argument,
11879 which is the number of bytes remaining in the object the @var{dest}
11880 argument points to or @code{(size_t) -1} if the size is not known.
11882 The built-in functions are optimized into the normal string functions
11883 like @code{memcpy} if the last argument is @code{(size_t) -1} or if
11884 it is known at compile time that the destination object will not
11885 be overflowed. If the compiler can determine at compile time that the
11886 object will always be overflowed, it issues a warning.
11888 The intended use can be e.g.@:
11892 #define bos0(dest) __builtin_object_size (dest, 0)
11893 #define memcpy(dest, src, n) \
11894 __builtin___memcpy_chk (dest, src, n, bos0 (dest))
11898 /* It is unknown what object p points to, so this is optimized
11899 into plain memcpy - no checking is possible. */
11900 memcpy (p, "abcde", n);
11901 /* Destination is known and length too. It is known at compile
11902 time there will be no overflow. */
11903 memcpy (&buf[5], "abcde", 5);
11904 /* Destination is known, but the length is not known at compile time.
11905 This will result in __memcpy_chk call that can check for overflow
11907 memcpy (&buf[5], "abcde", n);
11908 /* Destination is known and it is known at compile time there will
11909 be overflow. There will be a warning and __memcpy_chk call that
11910 will abort the program at run time. */
11911 memcpy (&buf[6], "abcde", 5);
11914 Such built-in functions are provided for @code{memcpy}, @code{mempcpy},
11915 @code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy},
11916 @code{strcat} and @code{strncat}.
11918 There are also checking built-in functions for formatted output functions.
11920 int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...);
11921 int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os,
11922 const char *fmt, ...);
11923 int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt,
11925 int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os,
11926 const char *fmt, va_list ap);
11929 The added @var{flag} argument is passed unchanged to @code{__sprintf_chk}
11930 etc.@: functions and can contain implementation specific flags on what
11931 additional security measures the checking function might take, such as
11932 handling @code{%n} differently.
11934 The @var{os} argument is the object size @var{s} points to, like in the
11935 other built-in functions. There is a small difference in the behavior
11936 though, if @var{os} is @code{(size_t) -1}, the built-in functions are
11937 optimized into the non-checking functions only if @var{flag} is 0, otherwise
11938 the checking function is called with @var{os} argument set to
11939 @code{(size_t) -1}.
11941 In addition to this, there are checking built-in functions
11942 @code{__builtin___printf_chk}, @code{__builtin___vprintf_chk},
11943 @code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}.
11944 These have just one additional argument, @var{flag}, right before
11945 format string @var{fmt}. If the compiler is able to optimize them to
11946 @code{fputc} etc.@: functions, it does, otherwise the checking function
11947 is called and the @var{flag} argument passed to it.
11949 @node Other Builtins
11950 @section Other Built-in Functions Provided by GCC
11951 @cindex built-in functions
11952 @findex __builtin_alloca
11953 @findex __builtin_alloca_with_align
11954 @findex __builtin_alloca_with_align_and_max
11955 @findex __builtin_call_with_static_chain
11956 @findex __builtin_extend_pointer
11957 @findex __builtin_fpclassify
11958 @findex __builtin_has_attribute
11959 @findex __builtin_isfinite
11960 @findex __builtin_isnormal
11961 @findex __builtin_isgreater
11962 @findex __builtin_isgreaterequal
11963 @findex __builtin_isinf_sign
11964 @findex __builtin_isless
11965 @findex __builtin_islessequal
11966 @findex __builtin_islessgreater
11967 @findex __builtin_isunordered
11968 @findex __builtin_object_size
11969 @findex __builtin_powi
11970 @findex __builtin_powif
11971 @findex __builtin_powil
11972 @findex __builtin_speculation_safe_value
12133 @findex fprintf_unlocked
12135 @findex fputs_unlocked
12243 @findex nexttowardf
12244 @findex nexttowardl
12252 @findex printf_unlocked
12282 @findex signbitd128
12283 @findex significand
12284 @findex significandf
12285 @findex significandl
12313 @findex strncasecmp
12357 GCC provides a large number of built-in functions other than the ones
12358 mentioned above. Some of these are for internal use in the processing
12359 of exceptions or variable-length argument lists and are not
12360 documented here because they may change from time to time; we do not
12361 recommend general use of these functions.
12363 The remaining functions are provided for optimization purposes.
12365 With the exception of built-ins that have library equivalents such as
12366 the standard C library functions discussed below, or that expand to
12367 library calls, GCC built-in functions are always expanded inline and
12368 thus do not have corresponding entry points and their address cannot
12369 be obtained. Attempting to use them in an expression other than
12370 a function call results in a compile-time error.
12372 @opindex fno-builtin
12373 GCC includes built-in versions of many of the functions in the standard
12374 C library. These functions come in two forms: one whose names start with
12375 the @code{__builtin_} prefix, and the other without. Both forms have the
12376 same type (including prototype), the same address (when their address is
12377 taken), and the same meaning as the C library functions even if you specify
12378 the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these
12379 functions are only optimized in certain cases; if they are not optimized in
12380 a particular case, a call to the library function is emitted.
12384 Outside strict ISO C mode (@option{-ansi}, @option{-std=c90},
12385 @option{-std=c99} or @option{-std=c11}), the functions
12386 @code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero},
12387 @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml},
12388 @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll},
12389 @code{ffsl}, @code{ffs}, @code{fprintf_unlocked},
12390 @code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma},
12391 @code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext},
12392 @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0},
12393 @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn},
12394 @code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy},
12395 @code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked},
12396 @code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roudnevenl},
12397 @code{scalbf}, @code{scalbl}, @code{scalb},
12398 @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32},
12399 @code{signbitd64}, @code{signbitd128}, @code{significandf},
12400 @code{significandl}, @code{significand}, @code{sincosf},
12401 @code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy},
12402 @code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp},
12403 @code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l},
12404 @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and
12406 may be handled as built-in functions.
12407 All these functions have corresponding versions
12408 prefixed with @code{__builtin_}, which may be used even in strict C90
12411 The ISO C99 functions
12412 @code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf},
12413 @code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh},
12414 @code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf},
12415 @code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos},
12416 @code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf},
12417 @code{casinhl}, @code{casinh}, @code{casinl}, @code{casin},
12418 @code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh},
12419 @code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt},
12420 @code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl},
12421 @code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf},
12422 @code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog},
12423 @code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl},
12424 @code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf},
12425 @code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal},
12426 @code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl},
12427 @code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf},
12428 @code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan},
12429 @code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl},
12430 @code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f},
12431 @code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim},
12432 @code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax},
12433 @code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf},
12434 @code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb},
12435 @code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf},
12436 @code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl},
12437 @code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround},
12438 @code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l},
12439 @code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf},
12440 @code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl},
12441 @code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint},
12442 @code{nextafterf}, @code{nextafterl}, @code{nextafter},
12443 @code{nexttowardf}, @code{nexttowardl}, @code{nexttoward},
12444 @code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof},
12445 @code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint},
12446 @code{roundf}, @code{roundl}, @code{round}, @code{scalblnf},
12447 @code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl},
12448 @code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal},
12449 @code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc},
12450 @code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf}
12451 are handled as built-in functions
12452 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
12454 There are also built-in versions of the ISO C99 functions
12455 @code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f},
12456 @code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill},
12457 @code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf},
12458 @code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl},
12459 @code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf},
12460 @code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl},
12461 @code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf},
12462 @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl},
12463 @code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl}
12464 that are recognized in any mode since ISO C90 reserves these names for
12465 the purpose to which ISO C99 puts them. All these functions have
12466 corresponding versions prefixed with @code{__builtin_}.
12468 There are also built-in functions @code{__builtin_fabsf@var{n}},
12469 @code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and
12470 @code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3
12471 functions @code{fabsf@var{n}}, @code{fabsf@var{n}x},
12472 @code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported
12473 types @code{_Float@var{n}} and @code{_Float@var{n}x}.
12475 There are also GNU extension functions @code{clog10}, @code{clog10f} and
12476 @code{clog10l} which names are reserved by ISO C99 for future use.
12477 All these functions have versions prefixed with @code{__builtin_}.
12479 The ISO C94 functions
12480 @code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit},
12481 @code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct},
12482 @code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and
12484 are handled as built-in functions
12485 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
12487 The ISO C90 functions
12488 @code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2},
12489 @code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos},
12490 @code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod},
12491 @code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf},
12492 @code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit},
12493 @code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct},
12494 @code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower},
12495 @code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log},
12496 @code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy},
12497 @code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar},
12498 @code{puts}, @code{scanf}, @code{sinh}, @code{sin}, @code{snprintf},
12499 @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat},
12500 @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn},
12501 @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy},
12502 @code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr},
12503 @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf}
12504 are all recognized as built-in functions unless
12505 @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}}
12506 is specified for an individual function). All of these functions have
12507 corresponding versions prefixed with @code{__builtin_}.
12509 GCC provides built-in versions of the ISO C99 floating-point comparison
12510 macros that avoid raising exceptions for unordered operands. They have
12511 the same names as the standard macros ( @code{isgreater},
12512 @code{isgreaterequal}, @code{isless}, @code{islessequal},
12513 @code{islessgreater}, and @code{isunordered}) , with @code{__builtin_}
12514 prefixed. We intend for a library implementor to be able to simply
12515 @code{#define} each standard macro to its built-in equivalent.
12516 In the same fashion, GCC provides @code{fpclassify}, @code{isfinite},
12517 @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with
12518 @code{__builtin_} prefixed. The @code{isinf} and @code{isnan}
12519 built-in functions appear both with and without the @code{__builtin_} prefix.
12521 @deftypefn {Built-in Function} void *__builtin_alloca (size_t size)
12522 The @code{__builtin_alloca} function must be called at block scope.
12523 The function allocates an object @var{size} bytes large on the stack
12524 of the calling function. The object is aligned on the default stack
12525 alignment boundary for the target determined by the
12526 @code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca}
12527 function returns a pointer to the first byte of the allocated object.
12528 The lifetime of the allocated object ends just before the calling
12529 function returns to its caller. This is so even when
12530 @code{__builtin_alloca} is called within a nested block.
12532 For example, the following function allocates eight objects of @code{n}
12533 bytes each on the stack, storing a pointer to each in consecutive elements
12534 of the array @code{a}. It then passes the array to function @code{g}
12535 which can safely use the storage pointed to by each of the array elements.
12538 void f (unsigned n)
12541 for (int i = 0; i != 8; ++i)
12542 a [i] = __builtin_alloca (n);
12544 g (a, n); // @r{safe}
12548 Since the @code{__builtin_alloca} function doesn't validate its argument
12549 it is the responsibility of its caller to make sure the argument doesn't
12550 cause it to exceed the stack size limit.
12551 The @code{__builtin_alloca} function is provided to make it possible to
12552 allocate on the stack arrays of bytes with an upper bound that may be
12553 computed at run time. Since C99 Variable Length Arrays offer
12554 similar functionality under a portable, more convenient, and safer
12555 interface they are recommended instead, in both C99 and C++ programs
12556 where GCC provides them as an extension.
12557 @xref{Variable Length}, for details.
12561 @deftypefn {Built-in Function} void *__builtin_alloca_with_align (size_t size, size_t alignment)
12562 The @code{__builtin_alloca_with_align} function must be called at block
12563 scope. The function allocates an object @var{size} bytes large on
12564 the stack of the calling function. The allocated object is aligned on
12565 the boundary specified by the argument @var{alignment} whose unit is given
12566 in bits (not bytes). The @var{size} argument must be positive and not
12567 exceed the stack size limit. The @var{alignment} argument must be a constant
12568 integer expression that evaluates to a power of 2 greater than or equal to
12569 @code{CHAR_BIT} and less than some unspecified maximum. Invocations
12570 with other values are rejected with an error indicating the valid bounds.
12571 The function returns a pointer to the first byte of the allocated object.
12572 The lifetime of the allocated object ends at the end of the block in which
12573 the function was called. The allocated storage is released no later than
12574 just before the calling function returns to its caller, but may be released
12575 at the end of the block in which the function was called.
12577 For example, in the following function the call to @code{g} is unsafe
12578 because when @code{overalign} is non-zero, the space allocated by
12579 @code{__builtin_alloca_with_align} may have been released at the end
12580 of the @code{if} statement in which it was called.
12583 void f (unsigned n, bool overalign)
12587 p = __builtin_alloca_with_align (n, 64 /* bits */);
12589 p = __builtin_alloc (n);
12591 g (p, n); // @r{unsafe}
12595 Since the @code{__builtin_alloca_with_align} function doesn't validate its
12596 @var{size} argument it is the responsibility of its caller to make sure
12597 the argument doesn't cause it to exceed the stack size limit.
12598 The @code{__builtin_alloca_with_align} function is provided to make
12599 it possible to allocate on the stack overaligned arrays of bytes with
12600 an upper bound that may be computed at run time. Since C99
12601 Variable Length Arrays offer the same functionality under
12602 a portable, more convenient, and safer interface they are recommended
12603 instead, in both C99 and C++ programs where GCC provides them as
12604 an extension. @xref{Variable Length}, for details.
12608 @deftypefn {Built-in Function} void *__builtin_alloca_with_align_and_max (size_t size, size_t alignment, size_t max_size)
12609 Similar to @code{__builtin_alloca_with_align} but takes an extra argument
12610 specifying an upper bound for @var{size} in case its value cannot be computed
12611 at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage}
12612 and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer
12613 expression, it has no effect on code generation and no attempt is made to
12614 check its compatibility with @var{size}.
12618 @deftypefn {Built-in Function} bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})
12619 The @code{__builtin_has_attribute} function evaluates to an integer constant
12620 expression equal to @code{true} if the symbol or type referenced by
12621 the @var{type-or-expression} argument has been declared with
12622 the @var{attribute} referenced by the second argument. For
12623 an @var{type-or-expression} argument that does not reference a symbol,
12624 since attributes do not apply to expressions the built-in consider
12625 the type of the argument. Neither argument is evaluated.
12626 The @var{type-or-expression} argument is subject to the same
12627 restrictions as the argument to @code{typeof} (@pxref{Typeof}). The
12628 @var{attribute} argument is an attribute name optionally followed by
12629 a comma-separated list of arguments enclosed in parentheses. Both forms
12630 of attribute names---with and without double leading and trailing
12631 underscores---are recognized. @xref{Attribute Syntax}, for details.
12632 When no attribute arguments are specified for an attribute that expects
12633 one or more arguments the function returns @code{true} if
12634 @var{type-or-expression} has been declared with the attribute regardless
12635 of the attribute argument values. Arguments provided for an attribute
12636 that expects some are validated and matched up to the provided number.
12637 The function returns @code{true} if all provided arguments match. For
12638 example, the first call to the function below evaluates to @code{true}
12639 because @code{x} is declared with the @code{aligned} attribute but
12640 the second call evaluates to @code{false} because @code{x} is declared
12641 @code{aligned (8)} and not @code{aligned (4)}.
12644 __attribute__ ((aligned (8))) int x;
12645 _Static_assert (__builtin_has_attribute (x, aligned), "aligned");
12646 _Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)");
12649 Due to a limitation the @code{__builtin_has_attribute} function returns
12650 @code{false} for the @code{mode} attribute even if the type or variable
12651 referenced by the @var{type-or-expression} argument was declared with one.
12652 The function is also not supported with labels, and in C with enumerators.
12654 Note that unlike the @code{__has_attribute} preprocessor operator which
12655 is suitable for use in @code{#if} preprocessing directives
12656 @code{__builtin_has_attribute} is an intrinsic function that is not
12657 recognized in such contexts.
12661 @deftypefn {Built-in Function} @var{type} __builtin_speculation_safe_value (@var{type} val, @var{type} failval)
12663 This built-in function can be used to help mitigate against unsafe
12664 speculative execution. @var{type} may be any integral type or any
12669 If the CPU is not speculatively executing the code, then @var{val}
12672 If the CPU is executing speculatively then either:
12675 The function may cause execution to pause until it is known that the
12676 code is no-longer being executed speculatively (in which case
12677 @var{val} can be returned, as above); or
12679 The function may use target-dependent speculation tracking state to cause
12680 @var{failval} to be returned when it is known that speculative
12681 execution has incorrectly predicted a conditional branch operation.
12685 The second argument, @var{failval}, is optional and defaults to zero
12688 GCC defines the preprocessor macro
12689 @code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been
12690 updated to support this builtin.
12692 The built-in function can be used where a variable appears to be used in a
12693 safe way, but the CPU, due to speculative execution may temporarily ignore
12694 the bounds checks. Consider, for example, the following function:
12698 int f (unsigned untrusted_index)
12700 if (untrusted_index < 500)
12701 return array[untrusted_index];
12706 If the function is called repeatedly with @code{untrusted_index} less
12707 than the limit of 500, then a branch predictor will learn that the
12708 block of code that returns a value stored in @code{array} will be
12709 executed. If the function is subsequently called with an
12710 out-of-range value it will still try to execute that block of code
12711 first until the CPU determines that the prediction was incorrect
12712 (the CPU will unwind any incorrect operations at that point).
12713 However, depending on how the result of the function is used, it might be
12714 possible to leave traces in the cache that can reveal what was stored
12715 at the out-of-bounds location. The built-in function can be used to
12716 provide some protection against leaking data in this way by changing
12721 int f (unsigned untrusted_index)
12723 if (untrusted_index < 500)
12724 return array[__builtin_speculation_safe_value (untrusted_index)];
12729 The built-in function will either cause execution to stall until the
12730 conditional branch has been fully resolved, or it may permit
12731 speculative execution to continue, but using 0 instead of
12732 @code{untrusted_value} if that exceeds the limit.
12734 If accessing any memory location is potentially unsafe when speculative
12735 execution is incorrect, then the code can be rewritten as
12739 int f (unsigned untrusted_index)
12741 if (untrusted_index < 500)
12742 return *__builtin_speculation_safe_value (&array[untrusted_index], NULL);
12747 which will cause a @code{NULL} pointer to be used for the unsafe case.
12751 @deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2})
12753 You can use the built-in function @code{__builtin_types_compatible_p} to
12754 determine whether two types are the same.
12756 This built-in function returns 1 if the unqualified versions of the
12757 types @var{type1} and @var{type2} (which are types, not expressions) are
12758 compatible, 0 otherwise. The result of this built-in function can be
12759 used in integer constant expressions.
12761 This built-in function ignores top level qualifiers (e.g., @code{const},
12762 @code{volatile}). For example, @code{int} is equivalent to @code{const
12765 The type @code{int[]} and @code{int[5]} are compatible. On the other
12766 hand, @code{int} and @code{char *} are not compatible, even if the size
12767 of their types, on the particular architecture are the same. Also, the
12768 amount of pointer indirection is taken into account when determining
12769 similarity. Consequently, @code{short *} is not similar to
12770 @code{short **}. Furthermore, two types that are typedefed are
12771 considered compatible if their underlying types are compatible.
12773 An @code{enum} type is not considered to be compatible with another
12774 @code{enum} type even if both are compatible with the same integer
12775 type; this is what the C standard specifies.
12776 For example, @code{enum @{foo, bar@}} is not similar to
12777 @code{enum @{hot, dog@}}.
12779 You typically use this function in code whose execution varies
12780 depending on the arguments' types. For example:
12785 typeof (x) tmp = (x); \
12786 if (__builtin_types_compatible_p (typeof (x), long double)) \
12787 tmp = foo_long_double (tmp); \
12788 else if (__builtin_types_compatible_p (typeof (x), double)) \
12789 tmp = foo_double (tmp); \
12790 else if (__builtin_types_compatible_p (typeof (x), float)) \
12791 tmp = foo_float (tmp); \
12798 @emph{Note:} This construct is only available for C@.
12802 @deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})
12804 The @var{call_exp} expression must be a function call, and the
12805 @var{pointer_exp} expression must be a pointer. The @var{pointer_exp}
12806 is passed to the function call in the target's static chain location.
12807 The result of builtin is the result of the function call.
12809 @emph{Note:} This builtin is only available for C@.
12810 This builtin can be used to call Go closures from C.
12814 @deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})
12816 You can use the built-in function @code{__builtin_choose_expr} to
12817 evaluate code depending on the value of a constant expression. This
12818 built-in function returns @var{exp1} if @var{const_exp}, which is an
12819 integer constant expression, is nonzero. Otherwise it returns @var{exp2}.
12821 This built-in function is analogous to the @samp{? :} operator in C,
12822 except that the expression returned has its type unaltered by promotion
12823 rules. Also, the built-in function does not evaluate the expression
12824 that is not chosen. For example, if @var{const_exp} evaluates to @code{true},
12825 @var{exp2} is not evaluated even if it has side effects.
12827 This built-in function can return an lvalue if the chosen argument is an
12830 If @var{exp1} is returned, the return type is the same as @var{exp1}'s
12831 type. Similarly, if @var{exp2} is returned, its return type is the same
12838 __builtin_choose_expr ( \
12839 __builtin_types_compatible_p (typeof (x), double), \
12841 __builtin_choose_expr ( \
12842 __builtin_types_compatible_p (typeof (x), float), \
12844 /* @r{The void expression results in a compile-time error} \
12845 @r{when assigning the result to something.} */ \
12849 @emph{Note:} This construct is only available for C@. Furthermore, the
12850 unused expression (@var{exp1} or @var{exp2} depending on the value of
12851 @var{const_exp}) may still generate syntax errors. This may change in
12856 @deftypefn {Built-in Function} @var{type} __builtin_tgmath (@var{functions}, @var{arguments})
12858 The built-in function @code{__builtin_tgmath}, available only for C
12859 and Objective-C, calls a function determined according to the rules of
12860 @code{<tgmath.h>} macros. It is intended to be used in
12861 implementations of that header, so that expansions of macros from that
12862 header only expand each of their arguments once, to avoid problems
12863 when calls to such macros are nested inside the arguments of other
12864 calls to such macros; in addition, it results in better diagnostics
12865 for invalid calls to @code{<tgmath.h>} macros than implementations
12866 using other GNU C language features. For example, the @code{pow}
12867 type-generic macro might be defined as:
12870 #define pow(a, b) __builtin_tgmath (powf, pow, powl, \
12871 cpowf, cpow, cpowl, a, b)
12874 The arguments to @code{__builtin_tgmath} are at least two pointers to
12875 functions, followed by the arguments to the type-generic macro (which
12876 will be passed as arguments to the selected function). All the
12877 pointers to functions must be pointers to prototyped functions, none
12878 of which may have variable arguments, and all of which must have the
12879 same number of parameters; the number of parameters of the first
12880 function determines how many arguments to @code{__builtin_tgmath} are
12881 interpreted as function pointers, and how many as the arguments to the
12884 The types of the specified functions must all be different, but
12885 related to each other in the same way as a set of functions that may
12886 be selected between by a macro in @code{<tgmath.h>}. This means that
12887 the functions are parameterized by a floating-point type @var{t},
12888 different for each such function. The function return types may all
12889 be the same type, or they may be @var{t} for each function, or they
12890 may be the real type corresponding to @var{t} for each function (if
12891 some of the types @var{t} are complex). Likewise, for each parameter
12892 position, the type of the parameter in that position may always be the
12893 same type, or may be @var{t} for each function (this case must apply
12894 for at least one parameter position), or may be the real type
12895 corresponding to @var{t} for each function.
12897 The standard rules for @code{<tgmath.h>} macros are used to find a
12898 common type @var{u} from the types of the arguments for parameters
12899 whose types vary between the functions; complex integer types (a GNU
12900 extension) are treated like @code{_Complex double} for this purpose
12901 (or @code{_Complex _Float64} if all the function return types are the
12902 same @code{_Float@var{n}} or @code{_Float@var{n}x} type).
12903 If the function return types vary, or are all the same integer type,
12904 the function called is the one for which @var{t} is @var{u}, and it is
12905 an error if there is no such function. If the function return types
12906 are all the same floating-point type, the type-generic macro is taken
12907 to be one of those from TS 18661 that rounds the result to a narrower
12908 type; if there is a function for which @var{t} is @var{u}, it is
12909 called, and otherwise the first function, if any, for which @var{t}
12910 has at least the range and precision of @var{u} is called, and it is
12911 an error if there is no such function.
12915 @deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag})
12917 The built-in function @code{__builtin_complex} is provided for use in
12918 implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
12919 @code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
12920 real binary floating-point type, and the result has the corresponding
12921 complex type with real and imaginary parts @var{real} and @var{imag}.
12922 Unlike @samp{@var{real} + I * @var{imag}}, this works even when
12923 infinities, NaNs and negative zeros are involved.
12927 @deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
12928 You can use the built-in function @code{__builtin_constant_p} to
12929 determine if a value is known to be constant at compile time and hence
12930 that GCC can perform constant-folding on expressions involving that
12931 value. The argument of the function is the value to test. The function
12932 returns the integer 1 if the argument is known to be a compile-time
12933 constant and 0 if it is not known to be a compile-time constant. A
12934 return of 0 does not indicate that the value is @emph{not} a constant,
12935 but merely that GCC cannot prove it is a constant with the specified
12936 value of the @option{-O} option.
12938 You typically use this function in an embedded application where
12939 memory is a critical resource. If you have some complex calculation,
12940 you may want it to be folded if it involves constants, but need to call
12941 a function if it does not. For example:
12944 #define Scale_Value(X) \
12945 (__builtin_constant_p (X) \
12946 ? ((X) * SCALE + OFFSET) : Scale (X))
12949 You may use this built-in function in either a macro or an inline
12950 function. However, if you use it in an inlined function and pass an
12951 argument of the function as the argument to the built-in, GCC
12952 never returns 1 when you call the inline function with a string constant
12953 or compound literal (@pxref{Compound Literals}) and does not return 1
12954 when you pass a constant numeric value to the inline function unless you
12955 specify the @option{-O} option.
12957 You may also use @code{__builtin_constant_p} in initializers for static
12958 data. For instance, you can write
12961 static const int table[] = @{
12962 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
12968 This is an acceptable initializer even if @var{EXPRESSION} is not a
12969 constant expression, including the case where
12970 @code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be
12971 folded to a constant but @var{EXPRESSION} contains operands that are
12972 not otherwise permitted in a static initializer (for example,
12973 @code{0 && foo ()}). GCC must be more conservative about evaluating the
12974 built-in in this case, because it has no opportunity to perform
12978 @deftypefn {Built-in Function} bool __builtin_is_constant_evaluated (void)
12979 The @code{__builtin_is_constant_evaluated} function is available only
12980 in C++. The built-in is intended to be used by implementations of
12981 the @code{std::is_constant_evaluated} C++ function. Programs should make
12982 use of the latter function rather than invoking the built-in directly.
12984 The main use case of the built-in is to determine whether a @code{constexpr}
12985 function is being called in a @code{constexpr} context. A call to
12986 the function evaluates to a core constant expression with the value
12987 @code{true} if and only if it occurs within the evaluation of an expression
12988 or conversion that is manifestly constant-evaluated as defined in the C++
12989 standard. Manifestly constant-evaluated contexts include constant-expressions,
12990 the conditions of @code{constexpr if} statements, constraint-expressions, and
12991 initializers of variables usable in constant expressions. For more details
12992 refer to the latest revision of the C++ standard.
12995 @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
12996 @opindex fprofile-arcs
12997 You may use @code{__builtin_expect} to provide the compiler with
12998 branch prediction information. In general, you should prefer to
12999 use actual profile feedback for this (@option{-fprofile-arcs}), as
13000 programmers are notoriously bad at predicting how their programs
13001 actually perform. However, there are applications in which this
13002 data is hard to collect.
13004 The return value is the value of @var{exp}, which should be an integral
13005 expression. The semantics of the built-in are that it is expected that
13006 @var{exp} == @var{c}. For example:
13009 if (__builtin_expect (x, 0))
13014 indicates that we do not expect to call @code{foo}, since
13015 we expect @code{x} to be zero. Since you are limited to integral
13016 expressions for @var{exp}, you should use constructions such as
13019 if (__builtin_expect (ptr != NULL, 1))
13024 when testing pointer or floating-point values.
13026 For the purposes of branch prediction optimizations, the probability that
13027 a @code{__builtin_expect} expression is @code{true} is controlled by GCC's
13028 @code{builtin-expect-probability} parameter, which defaults to 90%.
13030 You can also use @code{__builtin_expect_with_probability} to explicitly
13031 assign a probability value to individual expressions. If the built-in
13032 is used in a loop construct, the provided probability will influence
13033 the expected number of iterations made by loop optimizations.
13036 @deftypefn {Built-in Function} long __builtin_expect_with_probability
13037 (long @var{exp}, long @var{c}, double @var{probability})
13039 This function has the same semantics as @code{__builtin_expect},
13040 but the caller provides the expected probability that @var{exp} == @var{c}.
13041 The last argument, @var{probability}, is a floating-point value in the
13042 range 0.0 to 1.0, inclusive. The @var{probability} argument must be
13043 constant floating-point expression.
13046 @deftypefn {Built-in Function} void __builtin_trap (void)
13047 This function causes the program to exit abnormally. GCC implements
13048 this function by using a target-dependent mechanism (such as
13049 intentionally executing an illegal instruction) or by calling
13050 @code{abort}. The mechanism used may vary from release to release so
13051 you should not rely on any particular implementation.
13054 @deftypefn {Built-in Function} void __builtin_unreachable (void)
13055 If control flow reaches the point of the @code{__builtin_unreachable},
13056 the program is undefined. It is useful in situations where the
13057 compiler cannot deduce the unreachability of the code.
13059 One such case is immediately following an @code{asm} statement that
13060 either never terminates, or one that transfers control elsewhere
13061 and never returns. In this example, without the
13062 @code{__builtin_unreachable}, GCC issues a warning that control
13063 reaches the end of a non-void function. It also generates code
13064 to return after the @code{asm}.
13067 int f (int c, int v)
13075 asm("jmp error_handler");
13076 __builtin_unreachable ();
13082 Because the @code{asm} statement unconditionally transfers control out
13083 of the function, control never reaches the end of the function
13084 body. The @code{__builtin_unreachable} is in fact unreachable and
13085 communicates this fact to the compiler.
13087 Another use for @code{__builtin_unreachable} is following a call a
13088 function that never returns but that is not declared
13089 @code{__attribute__((noreturn))}, as in this example:
13092 void function_that_never_returns (void);
13102 function_that_never_returns ();
13103 __builtin_unreachable ();
13110 @deftypefn {Built-in Function} {void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)
13111 This function returns its first argument, and allows the compiler
13112 to assume that the returned pointer is at least @var{align} bytes
13113 aligned. This built-in can have either two or three arguments,
13114 if it has three, the third argument should have integer type, and
13115 if it is nonzero means misalignment offset. For example:
13118 void *x = __builtin_assume_aligned (arg, 16);
13122 means that the compiler can assume @code{x}, set to @code{arg}, is at least
13123 16-byte aligned, while:
13126 void *x = __builtin_assume_aligned (arg, 32, 8);
13130 means that the compiler can assume for @code{x}, set to @code{arg}, that
13131 @code{(char *) x - 8} is 32-byte aligned.
13134 @deftypefn {Built-in Function} int __builtin_LINE ()
13135 This function is the equivalent of the preprocessor @code{__LINE__}
13136 macro and returns a constant integer expression that evaluates to
13137 the line number of the invocation of the built-in. When used as a C++
13138 default argument for a function @var{F}, it returns the line number
13139 of the call to @var{F}.
13142 @deftypefn {Built-in Function} {const char *} __builtin_FUNCTION ()
13143 This function is the equivalent of the @code{__FUNCTION__} symbol
13144 and returns an address constant pointing to the name of the function
13145 from which the built-in was invoked, or the empty string if
13146 the invocation is not at function scope. When used as a C++ default
13147 argument for a function @var{F}, it returns the name of @var{F}'s
13148 caller or the empty string if the call was not made at function
13152 @deftypefn {Built-in Function} {const char *} __builtin_FILE ()
13153 This function is the equivalent of the preprocessor @code{__FILE__}
13154 macro and returns an address constant pointing to the file name
13155 containing the invocation of the built-in, or the empty string if
13156 the invocation is not at function scope. When used as a C++ default
13157 argument for a function @var{F}, it returns the file name of the call
13158 to @var{F} or the empty string if the call was not made at function
13161 For example, in the following, each call to function @code{foo} will
13162 print a line similar to @code{"file.c:123: foo: message"} with the name
13163 of the file and the line number of the @code{printf} call, the name of
13164 the function @code{foo}, followed by the word @code{message}.
13168 function (const char *func = __builtin_FUNCTION ())
13175 printf ("%s:%i: %s: message\n", file (), line (), function ());
13181 @deftypefn {Built-in Function} void __builtin___clear_cache (void *@var{begin}, void *@var{end})
13182 This function is used to flush the processor's instruction cache for
13183 the region of memory between @var{begin} inclusive and @var{end}
13184 exclusive. Some targets require that the instruction cache be
13185 flushed, after modifying memory containing code, in order to obtain
13186 deterministic behavior.
13188 If the target does not require instruction cache flushes,
13189 @code{__builtin___clear_cache} has no effect. Otherwise either
13190 instructions are emitted in-line to clear the instruction cache or a
13191 call to the @code{__clear_cache} function in libgcc is made.
13194 @deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...)
13195 This function is used to minimize cache-miss latency by moving data into
13196 a cache before it is accessed.
13197 You can insert calls to @code{__builtin_prefetch} into code for which
13198 you know addresses of data in memory that is likely to be accessed soon.
13199 If the target supports them, data prefetch instructions are generated.
13200 If the prefetch is done early enough before the access then the data will
13201 be in the cache by the time it is accessed.
13203 The value of @var{addr} is the address of the memory to prefetch.
13204 There are two optional arguments, @var{rw} and @var{locality}.
13205 The value of @var{rw} is a compile-time constant one or zero; one
13206 means that the prefetch is preparing for a write to the memory address
13207 and zero, the default, means that the prefetch is preparing for a read.
13208 The value @var{locality} must be a compile-time constant integer between
13209 zero and three. A value of zero means that the data has no temporal
13210 locality, so it need not be left in the cache after the access. A value
13211 of three means that the data has a high degree of temporal locality and
13212 should be left in all levels of cache possible. Values of one and two
13213 mean, respectively, a low or moderate degree of temporal locality. The
13217 for (i = 0; i < n; i++)
13219 a[i] = a[i] + b[i];
13220 __builtin_prefetch (&a[i+j], 1, 1);
13221 __builtin_prefetch (&b[i+j], 0, 1);
13226 Data prefetch does not generate faults if @var{addr} is invalid, but
13227 the address expression itself must be valid. For example, a prefetch
13228 of @code{p->next} does not fault if @code{p->next} is not a valid
13229 address, but evaluation faults if @code{p} is not a valid address.
13231 If the target does not support data prefetch, the address expression
13232 is evaluated if it includes side effects but no other code is generated
13233 and GCC does not issue a warning.
13236 @deftypefn {Built-in Function}{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
13237 Returns the size of an object pointed to by @var{ptr}. @xref{Object Size
13238 Checking}, for a detailed description of the function.
13241 @deftypefn {Built-in Function} double __builtin_huge_val (void)
13242 Returns a positive infinity, if supported by the floating-point format,
13243 else @code{DBL_MAX}. This function is suitable for implementing the
13244 ISO C macro @code{HUGE_VAL}.
13247 @deftypefn {Built-in Function} float __builtin_huge_valf (void)
13248 Similar to @code{__builtin_huge_val}, except the return type is @code{float}.
13251 @deftypefn {Built-in Function} {long double} __builtin_huge_vall (void)
13252 Similar to @code{__builtin_huge_val}, except the return
13253 type is @code{long double}.
13256 @deftypefn {Built-in Function} _Float@var{n} __builtin_huge_valf@var{n} (void)
13257 Similar to @code{__builtin_huge_val}, except the return type is
13258 @code{_Float@var{n}}.
13261 @deftypefn {Built-in Function} _Float@var{n}x __builtin_huge_valf@var{n}x (void)
13262 Similar to @code{__builtin_huge_val}, except the return type is
13263 @code{_Float@var{n}x}.
13266 @deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...)
13267 This built-in implements the C99 fpclassify functionality. The first
13268 five int arguments should be the target library's notion of the
13269 possible FP classes and are used for return values. They must be
13270 constant values and they must appear in this order: @code{FP_NAN},
13271 @code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and
13272 @code{FP_ZERO}. The ellipsis is for exactly one floating-point value
13273 to classify. GCC treats the last argument as type-generic, which
13274 means it does not do default promotion from float to double.
13277 @deftypefn {Built-in Function} double __builtin_inf (void)
13278 Similar to @code{__builtin_huge_val}, except a warning is generated
13279 if the target floating-point format does not support infinities.
13282 @deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void)
13283 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}.
13286 @deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void)
13287 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}.
13290 @deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void)
13291 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}.
13294 @deftypefn {Built-in Function} float __builtin_inff (void)
13295 Similar to @code{__builtin_inf}, except the return type is @code{float}.
13296 This function is suitable for implementing the ISO C99 macro @code{INFINITY}.
13299 @deftypefn {Built-in Function} {long double} __builtin_infl (void)
13300 Similar to @code{__builtin_inf}, except the return
13301 type is @code{long double}.
13304 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n} (void)
13305 Similar to @code{__builtin_inf}, except the return
13306 type is @code{_Float@var{n}}.
13309 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n}x (void)
13310 Similar to @code{__builtin_inf}, except the return
13311 type is @code{_Float@var{n}x}.
13314 @deftypefn {Built-in Function} int __builtin_isinf_sign (...)
13315 Similar to @code{isinf}, except the return value is -1 for
13316 an argument of @code{-Inf} and 1 for an argument of @code{+Inf}.
13317 Note while the parameter list is an
13318 ellipsis, this function only accepts exactly one floating-point
13319 argument. GCC treats this parameter as type-generic, which means it
13320 does not do default promotion from float to double.
13323 @deftypefn {Built-in Function} double __builtin_nan (const char *str)
13324 This is an implementation of the ISO C99 function @code{nan}.
13326 Since ISO C99 defines this function in terms of @code{strtod}, which we
13327 do not implement, a description of the parsing is in order. The string
13328 is parsed as by @code{strtol}; that is, the base is recognized by
13329 leading @samp{0} or @samp{0x} prefixes. The number parsed is placed
13330 in the significand such that the least significant bit of the number
13331 is at the least significant bit of the significand. The number is
13332 truncated to fit the significand field provided. The significand is
13333 forced to be a quiet NaN@.
13335 This function, if given a string literal all of which would have been
13336 consumed by @code{strtol}, is evaluated early enough that it is considered a
13337 compile-time constant.
13340 @deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str)
13341 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}.
13344 @deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str)
13345 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}.
13348 @deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str)
13349 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}.
13352 @deftypefn {Built-in Function} float __builtin_nanf (const char *str)
13353 Similar to @code{__builtin_nan}, except the return type is @code{float}.
13356 @deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str)
13357 Similar to @code{__builtin_nan}, except the return type is @code{long double}.
13360 @deftypefn {Built-in Function} _Float@var{n} __builtin_nanf@var{n} (const char *str)
13361 Similar to @code{__builtin_nan}, except the return type is
13362 @code{_Float@var{n}}.
13365 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nanf@var{n}x (const char *str)
13366 Similar to @code{__builtin_nan}, except the return type is
13367 @code{_Float@var{n}x}.
13370 @deftypefn {Built-in Function} double __builtin_nans (const char *str)
13371 Similar to @code{__builtin_nan}, except the significand is forced
13372 to be a signaling NaN@. The @code{nans} function is proposed by
13373 @uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}.
13376 @deftypefn {Built-in Function} float __builtin_nansf (const char *str)
13377 Similar to @code{__builtin_nans}, except the return type is @code{float}.
13380 @deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str)
13381 Similar to @code{__builtin_nans}, except the return type is @code{long double}.
13384 @deftypefn {Built-in Function} _Float@var{n} __builtin_nansf@var{n} (const char *str)
13385 Similar to @code{__builtin_nans}, except the return type is
13386 @code{_Float@var{n}}.
13389 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nansf@var{n}x (const char *str)
13390 Similar to @code{__builtin_nans}, except the return type is
13391 @code{_Float@var{n}x}.
13394 @deftypefn {Built-in Function} int __builtin_ffs (int x)
13395 Returns one plus the index of the least significant 1-bit of @var{x}, or
13396 if @var{x} is zero, returns zero.
13399 @deftypefn {Built-in Function} int __builtin_clz (unsigned int x)
13400 Returns the number of leading 0-bits in @var{x}, starting at the most
13401 significant bit position. If @var{x} is 0, the result is undefined.
13404 @deftypefn {Built-in Function} int __builtin_ctz (unsigned int x)
13405 Returns the number of trailing 0-bits in @var{x}, starting at the least
13406 significant bit position. If @var{x} is 0, the result is undefined.
13409 @deftypefn {Built-in Function} int __builtin_clrsb (int x)
13410 Returns the number of leading redundant sign bits in @var{x}, i.e.@: the
13411 number of bits following the most significant bit that are identical
13412 to it. There are no special cases for 0 or other values.
13415 @deftypefn {Built-in Function} int __builtin_popcount (unsigned int x)
13416 Returns the number of 1-bits in @var{x}.
13419 @deftypefn {Built-in Function} int __builtin_parity (unsigned int x)
13420 Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x}
13424 @deftypefn {Built-in Function} int __builtin_ffsl (long)
13425 Similar to @code{__builtin_ffs}, except the argument type is
13429 @deftypefn {Built-in Function} int __builtin_clzl (unsigned long)
13430 Similar to @code{__builtin_clz}, except the argument type is
13431 @code{unsigned long}.
13434 @deftypefn {Built-in Function} int __builtin_ctzl (unsigned long)
13435 Similar to @code{__builtin_ctz}, except the argument type is
13436 @code{unsigned long}.
13439 @deftypefn {Built-in Function} int __builtin_clrsbl (long)
13440 Similar to @code{__builtin_clrsb}, except the argument type is
13444 @deftypefn {Built-in Function} int __builtin_popcountl (unsigned long)
13445 Similar to @code{__builtin_popcount}, except the argument type is
13446 @code{unsigned long}.
13449 @deftypefn {Built-in Function} int __builtin_parityl (unsigned long)
13450 Similar to @code{__builtin_parity}, except the argument type is
13451 @code{unsigned long}.
13454 @deftypefn {Built-in Function} int __builtin_ffsll (long long)
13455 Similar to @code{__builtin_ffs}, except the argument type is
13459 @deftypefn {Built-in Function} int __builtin_clzll (unsigned long long)
13460 Similar to @code{__builtin_clz}, except the argument type is
13461 @code{unsigned long long}.
13464 @deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long)
13465 Similar to @code{__builtin_ctz}, except the argument type is
13466 @code{unsigned long long}.
13469 @deftypefn {Built-in Function} int __builtin_clrsbll (long long)
13470 Similar to @code{__builtin_clrsb}, except the argument type is
13474 @deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long)
13475 Similar to @code{__builtin_popcount}, except the argument type is
13476 @code{unsigned long long}.
13479 @deftypefn {Built-in Function} int __builtin_parityll (unsigned long long)
13480 Similar to @code{__builtin_parity}, except the argument type is
13481 @code{unsigned long long}.
13484 @deftypefn {Built-in Function} double __builtin_powi (double, int)
13485 Returns the first argument raised to the power of the second. Unlike the
13486 @code{pow} function no guarantees about precision and rounding are made.
13489 @deftypefn {Built-in Function} float __builtin_powif (float, int)
13490 Similar to @code{__builtin_powi}, except the argument and return types
13494 @deftypefn {Built-in Function} {long double} __builtin_powil (long double, int)
13495 Similar to @code{__builtin_powi}, except the argument and return types
13496 are @code{long double}.
13499 @deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x)
13500 Returns @var{x} with the order of the bytes reversed; for example,
13501 @code{0xaabb} becomes @code{0xbbaa}. Byte here always means
13505 @deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x)
13506 Similar to @code{__builtin_bswap16}, except the argument and return types
13510 @deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x)
13511 Similar to @code{__builtin_bswap32}, except the argument and return types
13515 @deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x)
13516 On targets where the user visible pointer size is smaller than the size
13517 of an actual hardware address this function returns the extended user
13518 pointer. Targets where this is true included ILP32 mode on x86_64 or
13519 Aarch64. This function is mainly useful when writing inline assembly
13523 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_id (int x)
13524 Returns the openacc gang, worker or vector id depending on whether @var{x} is
13528 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_size (int x)
13529 Returns the openacc gang, worker or vector size depending on whether @var{x} is
13533 @node Target Builtins
13534 @section Built-in Functions Specific to Particular Target Machines
13536 On some target machines, GCC supports many built-in functions specific
13537 to those machines. Generally these generate calls to specific machine
13538 instructions, but allow the compiler to schedule those calls.
13541 * AArch64 Built-in Functions::
13542 * Alpha Built-in Functions::
13543 * Altera Nios II Built-in Functions::
13544 * ARC Built-in Functions::
13545 * ARC SIMD Built-in Functions::
13546 * ARM iWMMXt Built-in Functions::
13547 * ARM C Language Extensions (ACLE)::
13548 * ARM Floating Point Status and Control Intrinsics::
13549 * ARM ARMv8-M Security Extensions::
13550 * AVR Built-in Functions::
13551 * Blackfin Built-in Functions::
13552 * BPF Built-in Functions::
13553 * BPF Kernel Helpers::
13554 * FR-V Built-in Functions::
13555 * MIPS DSP Built-in Functions::
13556 * MIPS Paired-Single Support::
13557 * MIPS Loongson Built-in Functions::
13558 * MIPS SIMD Architecture (MSA) Support::
13559 * Other MIPS Built-in Functions::
13560 * MSP430 Built-in Functions::
13561 * NDS32 Built-in Functions::
13562 * picoChip Built-in Functions::
13563 * Basic PowerPC Built-in Functions::
13564 * PowerPC AltiVec/VSX Built-in Functions::
13565 * PowerPC Hardware Transactional Memory Built-in Functions::
13566 * PowerPC Atomic Memory Operation Functions::
13567 * RX Built-in Functions::
13568 * S/390 System z Built-in Functions::
13569 * SH Built-in Functions::
13570 * SPARC VIS Built-in Functions::
13571 * TI C6X Built-in Functions::
13572 * TILE-Gx Built-in Functions::
13573 * TILEPro Built-in Functions::
13574 * x86 Built-in Functions::
13575 * x86 transactional memory intrinsics::
13576 * x86 control-flow protection intrinsics::
13579 @node AArch64 Built-in Functions
13580 @subsection AArch64 Built-in Functions
13582 These built-in functions are available for the AArch64 family of
13585 unsigned int __builtin_aarch64_get_fpcr ()
13586 void __builtin_aarch64_set_fpcr (unsigned int)
13587 unsigned int __builtin_aarch64_get_fpsr ()
13588 void __builtin_aarch64_set_fpsr (unsigned int)
13591 @node Alpha Built-in Functions
13592 @subsection Alpha Built-in Functions
13594 These built-in functions are available for the Alpha family of
13595 processors, depending on the command-line switches used.
13597 The following built-in functions are always available. They
13598 all generate the machine instruction that is part of the name.
13601 long __builtin_alpha_implver (void)
13602 long __builtin_alpha_rpcc (void)
13603 long __builtin_alpha_amask (long)
13604 long __builtin_alpha_cmpbge (long, long)
13605 long __builtin_alpha_extbl (long, long)
13606 long __builtin_alpha_extwl (long, long)
13607 long __builtin_alpha_extll (long, long)
13608 long __builtin_alpha_extql (long, long)
13609 long __builtin_alpha_extwh (long, long)
13610 long __builtin_alpha_extlh (long, long)
13611 long __builtin_alpha_extqh (long, long)
13612 long __builtin_alpha_insbl (long, long)
13613 long __builtin_alpha_inswl (long, long)
13614 long __builtin_alpha_insll (long, long)
13615 long __builtin_alpha_insql (long, long)
13616 long __builtin_alpha_inswh (long, long)
13617 long __builtin_alpha_inslh (long, long)
13618 long __builtin_alpha_insqh (long, long)
13619 long __builtin_alpha_mskbl (long, long)
13620 long __builtin_alpha_mskwl (long, long)
13621 long __builtin_alpha_mskll (long, long)
13622 long __builtin_alpha_mskql (long, long)
13623 long __builtin_alpha_mskwh (long, long)
13624 long __builtin_alpha_msklh (long, long)
13625 long __builtin_alpha_mskqh (long, long)
13626 long __builtin_alpha_umulh (long, long)
13627 long __builtin_alpha_zap (long, long)
13628 long __builtin_alpha_zapnot (long, long)
13631 The following built-in functions are always with @option{-mmax}
13632 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
13633 later. They all generate the machine instruction that is part
13637 long __builtin_alpha_pklb (long)
13638 long __builtin_alpha_pkwb (long)
13639 long __builtin_alpha_unpkbl (long)
13640 long __builtin_alpha_unpkbw (long)
13641 long __builtin_alpha_minub8 (long, long)
13642 long __builtin_alpha_minsb8 (long, long)
13643 long __builtin_alpha_minuw4 (long, long)
13644 long __builtin_alpha_minsw4 (long, long)
13645 long __builtin_alpha_maxub8 (long, long)
13646 long __builtin_alpha_maxsb8 (long, long)
13647 long __builtin_alpha_maxuw4 (long, long)
13648 long __builtin_alpha_maxsw4 (long, long)
13649 long __builtin_alpha_perr (long, long)
13652 The following built-in functions are always with @option{-mcix}
13653 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
13654 later. They all generate the machine instruction that is part
13658 long __builtin_alpha_cttz (long)
13659 long __builtin_alpha_ctlz (long)
13660 long __builtin_alpha_ctpop (long)
13663 The following built-in functions are available on systems that use the OSF/1
13664 PALcode. Normally they invoke the @code{rduniq} and @code{wruniq}
13665 PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
13666 @code{rdval} and @code{wrval}.
13669 void *__builtin_thread_pointer (void)
13670 void __builtin_set_thread_pointer (void *)
13673 @node Altera Nios II Built-in Functions
13674 @subsection Altera Nios II Built-in Functions
13676 These built-in functions are available for the Altera Nios II
13677 family of processors.
13679 The following built-in functions are always available. They
13680 all generate the machine instruction that is part of the name.
13683 int __builtin_ldbio (volatile const void *)
13684 int __builtin_ldbuio (volatile const void *)
13685 int __builtin_ldhio (volatile const void *)
13686 int __builtin_ldhuio (volatile const void *)
13687 int __builtin_ldwio (volatile const void *)
13688 void __builtin_stbio (volatile void *, int)
13689 void __builtin_sthio (volatile void *, int)
13690 void __builtin_stwio (volatile void *, int)
13691 void __builtin_sync (void)
13692 int __builtin_rdctl (int)
13693 int __builtin_rdprs (int, int)
13694 void __builtin_wrctl (int, int)
13695 void __builtin_flushd (volatile void *)
13696 void __builtin_flushda (volatile void *)
13697 int __builtin_wrpie (int);
13698 void __builtin_eni (int);
13699 int __builtin_ldex (volatile const void *)
13700 int __builtin_stex (volatile void *, int)
13701 int __builtin_ldsex (volatile const void *)
13702 int __builtin_stsex (volatile void *, int)
13705 The following built-in functions are always available. They
13706 all generate a Nios II Custom Instruction. The name of the
13707 function represents the types that the function takes and
13708 returns. The letter before the @code{n} is the return type
13709 or void if absent. The @code{n} represents the first parameter
13710 to all the custom instructions, the custom instruction number.
13711 The two letters after the @code{n} represent the up to two
13712 parameters to the function.
13714 The letters represent the following data types:
13717 @code{void} for return type and no parameter for parameter types.
13720 @code{int} for return type and parameter type
13723 @code{float} for return type and parameter type
13726 @code{void *} for return type and parameter type
13730 And the function names are:
13732 void __builtin_custom_n (void)
13733 void __builtin_custom_ni (int)
13734 void __builtin_custom_nf (float)
13735 void __builtin_custom_np (void *)
13736 void __builtin_custom_nii (int, int)
13737 void __builtin_custom_nif (int, float)
13738 void __builtin_custom_nip (int, void *)
13739 void __builtin_custom_nfi (float, int)
13740 void __builtin_custom_nff (float, float)
13741 void __builtin_custom_nfp (float, void *)
13742 void __builtin_custom_npi (void *, int)
13743 void __builtin_custom_npf (void *, float)
13744 void __builtin_custom_npp (void *, void *)
13745 int __builtin_custom_in (void)
13746 int __builtin_custom_ini (int)
13747 int __builtin_custom_inf (float)
13748 int __builtin_custom_inp (void *)
13749 int __builtin_custom_inii (int, int)
13750 int __builtin_custom_inif (int, float)
13751 int __builtin_custom_inip (int, void *)
13752 int __builtin_custom_infi (float, int)
13753 int __builtin_custom_inff (float, float)
13754 int __builtin_custom_infp (float, void *)
13755 int __builtin_custom_inpi (void *, int)
13756 int __builtin_custom_inpf (void *, float)
13757 int __builtin_custom_inpp (void *, void *)
13758 float __builtin_custom_fn (void)
13759 float __builtin_custom_fni (int)
13760 float __builtin_custom_fnf (float)
13761 float __builtin_custom_fnp (void *)
13762 float __builtin_custom_fnii (int, int)
13763 float __builtin_custom_fnif (int, float)
13764 float __builtin_custom_fnip (int, void *)
13765 float __builtin_custom_fnfi (float, int)
13766 float __builtin_custom_fnff (float, float)
13767 float __builtin_custom_fnfp (float, void *)
13768 float __builtin_custom_fnpi (void *, int)
13769 float __builtin_custom_fnpf (void *, float)
13770 float __builtin_custom_fnpp (void *, void *)
13771 void * __builtin_custom_pn (void)
13772 void * __builtin_custom_pni (int)
13773 void * __builtin_custom_pnf (float)
13774 void * __builtin_custom_pnp (void *)
13775 void * __builtin_custom_pnii (int, int)
13776 void * __builtin_custom_pnif (int, float)
13777 void * __builtin_custom_pnip (int, void *)
13778 void * __builtin_custom_pnfi (float, int)
13779 void * __builtin_custom_pnff (float, float)
13780 void * __builtin_custom_pnfp (float, void *)
13781 void * __builtin_custom_pnpi (void *, int)
13782 void * __builtin_custom_pnpf (void *, float)
13783 void * __builtin_custom_pnpp (void *, void *)
13786 @node ARC Built-in Functions
13787 @subsection ARC Built-in Functions
13789 The following built-in functions are provided for ARC targets. The
13790 built-ins generate the corresponding assembly instructions. In the
13791 examples given below, the generated code often requires an operand or
13792 result to be in a register. Where necessary further code will be
13793 generated to ensure this is true, but for brevity this is not
13794 described in each case.
13796 @emph{Note:} Using a built-in to generate an instruction not supported
13797 by a target may cause problems. At present the compiler is not
13798 guaranteed to detect such misuse, and as a result an internal compiler
13799 error may be generated.
13801 @deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval})
13802 Return 1 if @var{val} is known to have the byte alignment given
13803 by @var{alignval}, otherwise return 0.
13804 Note that this is different from
13806 __alignof__(*(char *)@var{val}) >= alignval
13808 because __alignof__ sees only the type of the dereference, whereas
13809 __builtin_arc_align uses alignment information from the pointer
13810 as well as from the pointed-to type.
13811 The information available will depend on optimization level.
13814 @deftypefn {Built-in Function} void __builtin_arc_brk (void)
13821 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno})
13822 The operand is the number of a register to be read. Generates:
13824 mov @var{dest}, r@var{regno}
13826 where the value in @var{dest} will be the result returned from the
13830 @deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val})
13831 The first operand is the number of a register to be written, the
13832 second operand is a compile time constant to write into that
13833 register. Generates:
13835 mov r@var{regno}, @var{val}
13839 @deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b})
13840 Only available if either @option{-mcpu=ARC700} or @option{-meA} is set.
13843 divaw @var{dest}, @var{a}, @var{b}
13845 where the value in @var{dest} will be the result returned from the
13849 @deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a})
13856 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr})
13857 The operand, @var{auxv}, is the address of an auxiliary register and
13858 must be a compile time constant. Generates:
13860 lr @var{dest}, [@var{auxr}]
13862 Where the value in @var{dest} will be the result returned from the
13866 @deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b})
13867 Only available with @option{-mmul64}. Generates:
13869 mul64 @var{a}, @var{b}
13873 @deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b})
13874 Only available with @option{-mmul64}. Generates:
13876 mulu64 @var{a}, @var{b}
13880 @deftypefn {Built-in Function} void __builtin_arc_nop (void)
13887 @deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src})
13888 Only valid if the @samp{norm} instruction is available through the
13889 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
13892 norm @var{dest}, @var{src}
13894 Where the value in @var{dest} will be the result returned from the
13898 @deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src})
13899 Only valid if the @samp{normw} instruction is available through the
13900 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
13903 normw @var{dest}, @var{src}
13905 Where the value in @var{dest} will be the result returned from the
13909 @deftypefn {Built-in Function} void __builtin_arc_rtie (void)
13916 @deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a}
13923 @deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{auxr}, unsigned int @var{val})
13924 The first argument, @var{auxv}, is the address of an auxiliary
13925 register, the second argument, @var{val}, is a compile time constant
13926 to be written to the register. Generates:
13928 sr @var{auxr}, [@var{val}]
13932 @deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src})
13933 Only valid with @option{-mswap}. Generates:
13935 swap @var{dest}, @var{src}
13937 Where the value in @var{dest} will be the result returned from the
13941 @deftypefn {Built-in Function} void __builtin_arc_swi (void)
13948 @deftypefn {Built-in Function} void __builtin_arc_sync (void)
13949 Only available with @option{-mcpu=ARC700}. Generates:
13955 @deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c})
13956 Only available with @option{-mcpu=ARC700}. Generates:
13962 @deftypefn {Built-in Function} void __builtin_arc_unimp_s (void)
13963 Only available with @option{-mcpu=ARC700}. Generates:
13969 The instructions generated by the following builtins are not
13970 considered as candidates for scheduling. They are not moved around by
13971 the compiler during scheduling, and thus can be expected to appear
13972 where they are put in the C code:
13974 __builtin_arc_brk()
13975 __builtin_arc_core_read()
13976 __builtin_arc_core_write()
13977 __builtin_arc_flag()
13979 __builtin_arc_sleep()
13981 __builtin_arc_swi()
13984 @node ARC SIMD Built-in Functions
13985 @subsection ARC SIMD Built-in Functions
13987 SIMD builtins provided by the compiler can be used to generate the
13988 vector instructions. This section describes the available builtins
13989 and their usage in programs. With the @option{-msimd} option, the
13990 compiler provides 128-bit vector types, which can be specified using
13991 the @code{vector_size} attribute. The header file @file{arc-simd.h}
13992 can be included to use the following predefined types:
13994 typedef int __v4si __attribute__((vector_size(16)));
13995 typedef short __v8hi __attribute__((vector_size(16)));
13998 These types can be used to define 128-bit variables. The built-in
13999 functions listed in the following section can be used on these
14000 variables to generate the vector operations.
14002 For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file
14003 @file{arc-simd.h} also provides equivalent macros called
14004 @code{_@var{someinsn}} that can be used for programming ease and
14005 improved readability. The following macros for DMA control are also
14008 #define _setup_dma_in_channel_reg _vdiwr
14009 #define _setup_dma_out_channel_reg _vdowr
14012 The following is a complete list of all the SIMD built-ins provided
14013 for ARC, grouped by calling signature.
14015 The following take two @code{__v8hi} arguments and return a
14016 @code{__v8hi} result:
14018 __v8hi __builtin_arc_vaddaw (__v8hi, __v8hi)
14019 __v8hi __builtin_arc_vaddw (__v8hi, __v8hi)
14020 __v8hi __builtin_arc_vand (__v8hi, __v8hi)
14021 __v8hi __builtin_arc_vandaw (__v8hi, __v8hi)
14022 __v8hi __builtin_arc_vavb (__v8hi, __v8hi)
14023 __v8hi __builtin_arc_vavrb (__v8hi, __v8hi)
14024 __v8hi __builtin_arc_vbic (__v8hi, __v8hi)
14025 __v8hi __builtin_arc_vbicaw (__v8hi, __v8hi)
14026 __v8hi __builtin_arc_vdifaw (__v8hi, __v8hi)
14027 __v8hi __builtin_arc_vdifw (__v8hi, __v8hi)
14028 __v8hi __builtin_arc_veqw (__v8hi, __v8hi)
14029 __v8hi __builtin_arc_vh264f (__v8hi, __v8hi)
14030 __v8hi __builtin_arc_vh264ft (__v8hi, __v8hi)
14031 __v8hi __builtin_arc_vh264fw (__v8hi, __v8hi)
14032 __v8hi __builtin_arc_vlew (__v8hi, __v8hi)
14033 __v8hi __builtin_arc_vltw (__v8hi, __v8hi)
14034 __v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi)
14035 __v8hi __builtin_arc_vmaxw (__v8hi, __v8hi)
14036 __v8hi __builtin_arc_vminaw (__v8hi, __v8hi)
14037 __v8hi __builtin_arc_vminw (__v8hi, __v8hi)
14038 __v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi)
14039 __v8hi __builtin_arc_vmr1w (__v8hi, __v8hi)
14040 __v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi)
14041 __v8hi __builtin_arc_vmr2w (__v8hi, __v8hi)
14042 __v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi)
14043 __v8hi __builtin_arc_vmr3w (__v8hi, __v8hi)
14044 __v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi)
14045 __v8hi __builtin_arc_vmr4w (__v8hi, __v8hi)
14046 __v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi)
14047 __v8hi __builtin_arc_vmr5w (__v8hi, __v8hi)
14048 __v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi)
14049 __v8hi __builtin_arc_vmr6w (__v8hi, __v8hi)
14050 __v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi)
14051 __v8hi __builtin_arc_vmr7w (__v8hi, __v8hi)
14052 __v8hi __builtin_arc_vmrb (__v8hi, __v8hi)
14053 __v8hi __builtin_arc_vmulaw (__v8hi, __v8hi)
14054 __v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi)
14055 __v8hi __builtin_arc_vmulfw (__v8hi, __v8hi)
14056 __v8hi __builtin_arc_vmulw (__v8hi, __v8hi)
14057 __v8hi __builtin_arc_vnew (__v8hi, __v8hi)
14058 __v8hi __builtin_arc_vor (__v8hi, __v8hi)
14059 __v8hi __builtin_arc_vsubaw (__v8hi, __v8hi)
14060 __v8hi __builtin_arc_vsubw (__v8hi, __v8hi)
14061 __v8hi __builtin_arc_vsummw (__v8hi, __v8hi)
14062 __v8hi __builtin_arc_vvc1f (__v8hi, __v8hi)
14063 __v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi)
14064 __v8hi __builtin_arc_vxor (__v8hi, __v8hi)
14065 __v8hi __builtin_arc_vxoraw (__v8hi, __v8hi)
14068 The following take one @code{__v8hi} and one @code{int} argument and return a
14069 @code{__v8hi} result:
14072 __v8hi __builtin_arc_vbaddw (__v8hi, int)
14073 __v8hi __builtin_arc_vbmaxw (__v8hi, int)
14074 __v8hi __builtin_arc_vbminw (__v8hi, int)
14075 __v8hi __builtin_arc_vbmulaw (__v8hi, int)
14076 __v8hi __builtin_arc_vbmulfw (__v8hi, int)
14077 __v8hi __builtin_arc_vbmulw (__v8hi, int)
14078 __v8hi __builtin_arc_vbrsubw (__v8hi, int)
14079 __v8hi __builtin_arc_vbsubw (__v8hi, int)
14082 The following take one @code{__v8hi} argument and one @code{int} argument which
14083 must be a 3-bit compile time constant indicating a register number
14084 I0-I7. They return a @code{__v8hi} result.
14086 __v8hi __builtin_arc_vasrw (__v8hi, const int)
14087 __v8hi __builtin_arc_vsr8 (__v8hi, const int)
14088 __v8hi __builtin_arc_vsr8aw (__v8hi, const int)
14091 The following take one @code{__v8hi} argument and one @code{int}
14092 argument which must be a 6-bit compile time constant. They return a
14093 @code{__v8hi} result.
14095 __v8hi __builtin_arc_vasrpwbi (__v8hi, const int)
14096 __v8hi __builtin_arc_vasrrpwbi (__v8hi, const int)
14097 __v8hi __builtin_arc_vasrrwi (__v8hi, const int)
14098 __v8hi __builtin_arc_vasrsrwi (__v8hi, const int)
14099 __v8hi __builtin_arc_vasrwi (__v8hi, const int)
14100 __v8hi __builtin_arc_vsr8awi (__v8hi, const int)
14101 __v8hi __builtin_arc_vsr8i (__v8hi, const int)
14104 The following take one @code{__v8hi} argument and one @code{int} argument which
14105 must be a 8-bit compile time constant. They return a @code{__v8hi}
14108 __v8hi __builtin_arc_vd6tapf (__v8hi, const int)
14109 __v8hi __builtin_arc_vmvaw (__v8hi, const int)
14110 __v8hi __builtin_arc_vmvw (__v8hi, const int)
14111 __v8hi __builtin_arc_vmvzw (__v8hi, const int)
14114 The following take two @code{int} arguments, the second of which which
14115 must be a 8-bit compile time constant. They return a @code{__v8hi}
14118 __v8hi __builtin_arc_vmovaw (int, const int)
14119 __v8hi __builtin_arc_vmovw (int, const int)
14120 __v8hi __builtin_arc_vmovzw (int, const int)
14123 The following take a single @code{__v8hi} argument and return a
14124 @code{__v8hi} result:
14126 __v8hi __builtin_arc_vabsaw (__v8hi)
14127 __v8hi __builtin_arc_vabsw (__v8hi)
14128 __v8hi __builtin_arc_vaddsuw (__v8hi)
14129 __v8hi __builtin_arc_vexch1 (__v8hi)
14130 __v8hi __builtin_arc_vexch2 (__v8hi)
14131 __v8hi __builtin_arc_vexch4 (__v8hi)
14132 __v8hi __builtin_arc_vsignw (__v8hi)
14133 __v8hi __builtin_arc_vupbaw (__v8hi)
14134 __v8hi __builtin_arc_vupbw (__v8hi)
14135 __v8hi __builtin_arc_vupsbaw (__v8hi)
14136 __v8hi __builtin_arc_vupsbw (__v8hi)
14139 The following take two @code{int} arguments and return no result:
14141 void __builtin_arc_vdirun (int, int)
14142 void __builtin_arc_vdorun (int, int)
14145 The following take two @code{int} arguments and return no result. The
14146 first argument must a 3-bit compile time constant indicating one of
14147 the DR0-DR7 DMA setup channels:
14149 void __builtin_arc_vdiwr (const int, int)
14150 void __builtin_arc_vdowr (const int, int)
14153 The following take an @code{int} argument and return no result:
14155 void __builtin_arc_vendrec (int)
14156 void __builtin_arc_vrec (int)
14157 void __builtin_arc_vrecrun (int)
14158 void __builtin_arc_vrun (int)
14161 The following take a @code{__v8hi} argument and two @code{int}
14162 arguments and return a @code{__v8hi} result. The second argument must
14163 be a 3-bit compile time constants, indicating one the registers I0-I7,
14164 and the third argument must be an 8-bit compile time constant.
14166 @emph{Note:} Although the equivalent hardware instructions do not take
14167 an SIMD register as an operand, these builtins overwrite the relevant
14168 bits of the @code{__v8hi} register provided as the first argument with
14169 the value loaded from the @code{[Ib, u8]} location in the SDM.
14172 __v8hi __builtin_arc_vld32 (__v8hi, const int, const int)
14173 __v8hi __builtin_arc_vld32wh (__v8hi, const int, const int)
14174 __v8hi __builtin_arc_vld32wl (__v8hi, const int, const int)
14175 __v8hi __builtin_arc_vld64 (__v8hi, const int, const int)
14178 The following take two @code{int} arguments and return a @code{__v8hi}
14179 result. The first argument must be a 3-bit compile time constants,
14180 indicating one the registers I0-I7, and the second argument must be an
14181 8-bit compile time constant.
14184 __v8hi __builtin_arc_vld128 (const int, const int)
14185 __v8hi __builtin_arc_vld64w (const int, const int)
14188 The following take a @code{__v8hi} argument and two @code{int}
14189 arguments and return no result. The second argument must be a 3-bit
14190 compile time constants, indicating one the registers I0-I7, and the
14191 third argument must be an 8-bit compile time constant.
14194 void __builtin_arc_vst128 (__v8hi, const int, const int)
14195 void __builtin_arc_vst64 (__v8hi, const int, const int)
14198 The following take a @code{__v8hi} argument and three @code{int}
14199 arguments and return no result. The second argument must be a 3-bit
14200 compile-time constant, identifying the 16-bit sub-register to be
14201 stored, the third argument must be a 3-bit compile time constants,
14202 indicating one the registers I0-I7, and the fourth argument must be an
14203 8-bit compile time constant.
14206 void __builtin_arc_vst16_n (__v8hi, const int, const int, const int)
14207 void __builtin_arc_vst32_n (__v8hi, const int, const int, const int)
14210 @node ARM iWMMXt Built-in Functions
14211 @subsection ARM iWMMXt Built-in Functions
14213 These built-in functions are available for the ARM family of
14214 processors when the @option{-mcpu=iwmmxt} switch is used:
14217 typedef int v2si __attribute__ ((vector_size (8)));
14218 typedef short v4hi __attribute__ ((vector_size (8)));
14219 typedef char v8qi __attribute__ ((vector_size (8)));
14221 int __builtin_arm_getwcgr0 (void)
14222 void __builtin_arm_setwcgr0 (int)
14223 int __builtin_arm_getwcgr1 (void)
14224 void __builtin_arm_setwcgr1 (int)
14225 int __builtin_arm_getwcgr2 (void)
14226 void __builtin_arm_setwcgr2 (int)
14227 int __builtin_arm_getwcgr3 (void)
14228 void __builtin_arm_setwcgr3 (int)
14229 int __builtin_arm_textrmsb (v8qi, int)
14230 int __builtin_arm_textrmsh (v4hi, int)
14231 int __builtin_arm_textrmsw (v2si, int)
14232 int __builtin_arm_textrmub (v8qi, int)
14233 int __builtin_arm_textrmuh (v4hi, int)
14234 int __builtin_arm_textrmuw (v2si, int)
14235 v8qi __builtin_arm_tinsrb (v8qi, int, int)
14236 v4hi __builtin_arm_tinsrh (v4hi, int, int)
14237 v2si __builtin_arm_tinsrw (v2si, int, int)
14238 long long __builtin_arm_tmia (long long, int, int)
14239 long long __builtin_arm_tmiabb (long long, int, int)
14240 long long __builtin_arm_tmiabt (long long, int, int)
14241 long long __builtin_arm_tmiaph (long long, int, int)
14242 long long __builtin_arm_tmiatb (long long, int, int)
14243 long long __builtin_arm_tmiatt (long long, int, int)
14244 int __builtin_arm_tmovmskb (v8qi)
14245 int __builtin_arm_tmovmskh (v4hi)
14246 int __builtin_arm_tmovmskw (v2si)
14247 long long __builtin_arm_waccb (v8qi)
14248 long long __builtin_arm_wacch (v4hi)
14249 long long __builtin_arm_waccw (v2si)
14250 v8qi __builtin_arm_waddb (v8qi, v8qi)
14251 v8qi __builtin_arm_waddbss (v8qi, v8qi)
14252 v8qi __builtin_arm_waddbus (v8qi, v8qi)
14253 v4hi __builtin_arm_waddh (v4hi, v4hi)
14254 v4hi __builtin_arm_waddhss (v4hi, v4hi)
14255 v4hi __builtin_arm_waddhus (v4hi, v4hi)
14256 v2si __builtin_arm_waddw (v2si, v2si)
14257 v2si __builtin_arm_waddwss (v2si, v2si)
14258 v2si __builtin_arm_waddwus (v2si, v2si)
14259 v8qi __builtin_arm_walign (v8qi, v8qi, int)
14260 long long __builtin_arm_wand(long long, long long)
14261 long long __builtin_arm_wandn (long long, long long)
14262 v8qi __builtin_arm_wavg2b (v8qi, v8qi)
14263 v8qi __builtin_arm_wavg2br (v8qi, v8qi)
14264 v4hi __builtin_arm_wavg2h (v4hi, v4hi)
14265 v4hi __builtin_arm_wavg2hr (v4hi, v4hi)
14266 v8qi __builtin_arm_wcmpeqb (v8qi, v8qi)
14267 v4hi __builtin_arm_wcmpeqh (v4hi, v4hi)
14268 v2si __builtin_arm_wcmpeqw (v2si, v2si)
14269 v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi)
14270 v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi)
14271 v2si __builtin_arm_wcmpgtsw (v2si, v2si)
14272 v8qi __builtin_arm_wcmpgtub (v8qi, v8qi)
14273 v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi)
14274 v2si __builtin_arm_wcmpgtuw (v2si, v2si)
14275 long long __builtin_arm_wmacs (long long, v4hi, v4hi)
14276 long long __builtin_arm_wmacsz (v4hi, v4hi)
14277 long long __builtin_arm_wmacu (long long, v4hi, v4hi)
14278 long long __builtin_arm_wmacuz (v4hi, v4hi)
14279 v4hi __builtin_arm_wmadds (v4hi, v4hi)
14280 v4hi __builtin_arm_wmaddu (v4hi, v4hi)
14281 v8qi __builtin_arm_wmaxsb (v8qi, v8qi)
14282 v4hi __builtin_arm_wmaxsh (v4hi, v4hi)
14283 v2si __builtin_arm_wmaxsw (v2si, v2si)
14284 v8qi __builtin_arm_wmaxub (v8qi, v8qi)
14285 v4hi __builtin_arm_wmaxuh (v4hi, v4hi)
14286 v2si __builtin_arm_wmaxuw (v2si, v2si)
14287 v8qi __builtin_arm_wminsb (v8qi, v8qi)
14288 v4hi __builtin_arm_wminsh (v4hi, v4hi)
14289 v2si __builtin_arm_wminsw (v2si, v2si)
14290 v8qi __builtin_arm_wminub (v8qi, v8qi)
14291 v4hi __builtin_arm_wminuh (v4hi, v4hi)
14292 v2si __builtin_arm_wminuw (v2si, v2si)
14293 v4hi __builtin_arm_wmulsm (v4hi, v4hi)
14294 v4hi __builtin_arm_wmulul (v4hi, v4hi)
14295 v4hi __builtin_arm_wmulum (v4hi, v4hi)
14296 long long __builtin_arm_wor (long long, long long)
14297 v2si __builtin_arm_wpackdss (long long, long long)
14298 v2si __builtin_arm_wpackdus (long long, long long)
14299 v8qi __builtin_arm_wpackhss (v4hi, v4hi)
14300 v8qi __builtin_arm_wpackhus (v4hi, v4hi)
14301 v4hi __builtin_arm_wpackwss (v2si, v2si)
14302 v4hi __builtin_arm_wpackwus (v2si, v2si)
14303 long long __builtin_arm_wrord (long long, long long)
14304 long long __builtin_arm_wrordi (long long, int)
14305 v4hi __builtin_arm_wrorh (v4hi, long long)
14306 v4hi __builtin_arm_wrorhi (v4hi, int)
14307 v2si __builtin_arm_wrorw (v2si, long long)
14308 v2si __builtin_arm_wrorwi (v2si, int)
14309 v2si __builtin_arm_wsadb (v2si, v8qi, v8qi)
14310 v2si __builtin_arm_wsadbz (v8qi, v8qi)
14311 v2si __builtin_arm_wsadh (v2si, v4hi, v4hi)
14312 v2si __builtin_arm_wsadhz (v4hi, v4hi)
14313 v4hi __builtin_arm_wshufh (v4hi, int)
14314 long long __builtin_arm_wslld (long long, long long)
14315 long long __builtin_arm_wslldi (long long, int)
14316 v4hi __builtin_arm_wsllh (v4hi, long long)
14317 v4hi __builtin_arm_wsllhi (v4hi, int)
14318 v2si __builtin_arm_wsllw (v2si, long long)
14319 v2si __builtin_arm_wsllwi (v2si, int)
14320 long long __builtin_arm_wsrad (long long, long long)
14321 long long __builtin_arm_wsradi (long long, int)
14322 v4hi __builtin_arm_wsrah (v4hi, long long)
14323 v4hi __builtin_arm_wsrahi (v4hi, int)
14324 v2si __builtin_arm_wsraw (v2si, long long)
14325 v2si __builtin_arm_wsrawi (v2si, int)
14326 long long __builtin_arm_wsrld (long long, long long)
14327 long long __builtin_arm_wsrldi (long long, int)
14328 v4hi __builtin_arm_wsrlh (v4hi, long long)
14329 v4hi __builtin_arm_wsrlhi (v4hi, int)
14330 v2si __builtin_arm_wsrlw (v2si, long long)
14331 v2si __builtin_arm_wsrlwi (v2si, int)
14332 v8qi __builtin_arm_wsubb (v8qi, v8qi)
14333 v8qi __builtin_arm_wsubbss (v8qi, v8qi)
14334 v8qi __builtin_arm_wsubbus (v8qi, v8qi)
14335 v4hi __builtin_arm_wsubh (v4hi, v4hi)
14336 v4hi __builtin_arm_wsubhss (v4hi, v4hi)
14337 v4hi __builtin_arm_wsubhus (v4hi, v4hi)
14338 v2si __builtin_arm_wsubw (v2si, v2si)
14339 v2si __builtin_arm_wsubwss (v2si, v2si)
14340 v2si __builtin_arm_wsubwus (v2si, v2si)
14341 v4hi __builtin_arm_wunpckehsb (v8qi)
14342 v2si __builtin_arm_wunpckehsh (v4hi)
14343 long long __builtin_arm_wunpckehsw (v2si)
14344 v4hi __builtin_arm_wunpckehub (v8qi)
14345 v2si __builtin_arm_wunpckehuh (v4hi)
14346 long long __builtin_arm_wunpckehuw (v2si)
14347 v4hi __builtin_arm_wunpckelsb (v8qi)
14348 v2si __builtin_arm_wunpckelsh (v4hi)
14349 long long __builtin_arm_wunpckelsw (v2si)
14350 v4hi __builtin_arm_wunpckelub (v8qi)
14351 v2si __builtin_arm_wunpckeluh (v4hi)
14352 long long __builtin_arm_wunpckeluw (v2si)
14353 v8qi __builtin_arm_wunpckihb (v8qi, v8qi)
14354 v4hi __builtin_arm_wunpckihh (v4hi, v4hi)
14355 v2si __builtin_arm_wunpckihw (v2si, v2si)
14356 v8qi __builtin_arm_wunpckilb (v8qi, v8qi)
14357 v4hi __builtin_arm_wunpckilh (v4hi, v4hi)
14358 v2si __builtin_arm_wunpckilw (v2si, v2si)
14359 long long __builtin_arm_wxor (long long, long long)
14360 long long __builtin_arm_wzero ()
14364 @node ARM C Language Extensions (ACLE)
14365 @subsection ARM C Language Extensions (ACLE)
14367 GCC implements extensions for C as described in the ARM C Language
14368 Extensions (ACLE) specification, which can be found at
14369 @uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf}.
14371 As a part of ACLE, GCC implements extensions for Advanced SIMD as described in
14372 the ARM C Language Extensions Specification. The complete list of Advanced SIMD
14373 intrinsics can be found at
14374 @uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0073a/IHI0073A_arm_neon_intrinsics_ref.pdf}.
14375 The built-in intrinsics for the Advanced SIMD extension are available when
14378 Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both
14379 back ends support CRC32 intrinsics and the ARM back end supports the
14380 Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit
14381 floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1.
14382 AArch64's back end does not have support for 16-bit floating point Advanced SIMD
14385 See @ref{ARM Options} and @ref{AArch64 Options} for more information on the
14386 availability of extensions.
14388 @node ARM Floating Point Status and Control Intrinsics
14389 @subsection ARM Floating Point Status and Control Intrinsics
14391 These built-in functions are available for the ARM family of
14392 processors with floating-point unit.
14395 unsigned int __builtin_arm_get_fpscr ()
14396 void __builtin_arm_set_fpscr (unsigned int)
14399 @node ARM ARMv8-M Security Extensions
14400 @subsection ARM ARMv8-M Security Extensions
14402 GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M
14403 Security Extensions: Requirements on Development Tools Engineering
14404 Specification, which can be found at
14405 @uref{http://infocenter.arm.com/help/topic/com.arm.doc.ecm0359818/ECM0359818_armv8m_security_extensions_reqs_on_dev_tools_1_0.pdf}.
14407 As part of the Security Extensions GCC implements two new function attributes:
14408 @code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}.
14410 As part of the Security Extensions GCC implements the intrinsics below. FPTR
14411 is used here to mean any function pointer type.
14414 cmse_address_info_t cmse_TT (void *)
14415 cmse_address_info_t cmse_TT_fptr (FPTR)
14416 cmse_address_info_t cmse_TTT (void *)
14417 cmse_address_info_t cmse_TTT_fptr (FPTR)
14418 cmse_address_info_t cmse_TTA (void *)
14419 cmse_address_info_t cmse_TTA_fptr (FPTR)
14420 cmse_address_info_t cmse_TTAT (void *)
14421 cmse_address_info_t cmse_TTAT_fptr (FPTR)
14422 void * cmse_check_address_range (void *, size_t, int)
14423 typeof(p) cmse_nsfptr_create (FPTR p)
14424 intptr_t cmse_is_nsfptr (FPTR)
14425 int cmse_nonsecure_caller (void)
14428 @node AVR Built-in Functions
14429 @subsection AVR Built-in Functions
14431 For each built-in function for AVR, there is an equally named,
14432 uppercase built-in macro defined. That way users can easily query if
14433 or if not a specific built-in is implemented or not. For example, if
14434 @code{__builtin_avr_nop} is available the macro
14435 @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise.
14439 @item void __builtin_avr_nop (void)
14440 @itemx void __builtin_avr_sei (void)
14441 @itemx void __builtin_avr_cli (void)
14442 @itemx void __builtin_avr_sleep (void)
14443 @itemx void __builtin_avr_wdr (void)
14444 @itemx unsigned char __builtin_avr_swap (unsigned char)
14445 @itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char)
14446 @itemx int __builtin_avr_fmuls (char, char)
14447 @itemx int __builtin_avr_fmulsu (char, unsigned char)
14448 These built-in functions map to the respective machine
14449 instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep},
14450 @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls}
14451 resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented
14452 as library call if no hardware multiplier is available.
14454 @item void __builtin_avr_delay_cycles (unsigned long ticks)
14455 Delay execution for @var{ticks} cycles. Note that this
14456 built-in does not take into account the effect of interrupts that
14457 might increase delay time. @var{ticks} must be a compile-time
14458 integer constant; delays with a variable number of cycles are not supported.
14460 @item char __builtin_avr_flash_segment (const __memx void*)
14461 This built-in takes a byte address to the 24-bit
14462 @ref{AVR Named Address Spaces,address space} @code{__memx} and returns
14463 the number of the flash segment (the 64 KiB chunk) where the address
14464 points to. Counting starts at @code{0}.
14465 If the address does not point to flash memory, return @code{-1}.
14467 @item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val)
14468 Insert bits from @var{bits} into @var{val} and return the resulting
14469 value. The nibbles of @var{map} determine how the insertion is
14470 performed: Let @var{X} be the @var{n}-th nibble of @var{map}
14472 @item If @var{X} is @code{0xf},
14473 then the @var{n}-th bit of @var{val} is returned unaltered.
14475 @item If X is in the range 0@dots{}7,
14476 then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits}
14478 @item If X is in the range 8@dots{}@code{0xe},
14479 then the @var{n}-th result bit is undefined.
14483 One typical use case for this built-in is adjusting input and
14484 output values to non-contiguous port layouts. Some examples:
14487 // same as val, bits is unused
14488 __builtin_avr_insert_bits (0xffffffff, bits, val)
14492 // same as bits, val is unused
14493 __builtin_avr_insert_bits (0x76543210, bits, val)
14497 // same as rotating bits by 4
14498 __builtin_avr_insert_bits (0x32107654, bits, 0)
14502 // high nibble of result is the high nibble of val
14503 // low nibble of result is the low nibble of bits
14504 __builtin_avr_insert_bits (0xffff3210, bits, val)
14508 // reverse the bit order of bits
14509 __builtin_avr_insert_bits (0x01234567, bits, 0)
14512 @item void __builtin_avr_nops (unsigned count)
14513 Insert @var{count} @code{NOP} instructions.
14514 The number of instructions must be a compile-time integer constant.
14519 There are many more AVR-specific built-in functions that are used to
14520 implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of
14521 section 7.18a.6. You don't need to use these built-ins directly.
14522 Instead, use the declarations as supplied by the @code{stdfix.h} header
14526 #include <stdfix.h>
14528 // Re-interpret the bit representation of unsigned 16-bit
14529 // integer @var{uval} as Q-format 0.16 value.
14530 unsigned fract get_bits (uint_ur_t uval)
14532 return urbits (uval);
14536 @node Blackfin Built-in Functions
14537 @subsection Blackfin Built-in Functions
14539 Currently, there are two Blackfin-specific built-in functions. These are
14540 used for generating @code{CSYNC} and @code{SSYNC} machine insns without
14541 using inline assembly; by using these built-in functions the compiler can
14542 automatically add workarounds for hardware errata involving these
14543 instructions. These functions are named as follows:
14546 void __builtin_bfin_csync (void)
14547 void __builtin_bfin_ssync (void)
14550 @node BPF Built-in Functions
14551 @subsection BPF Built-in Functions
14553 The following built-in functions are available for eBPF targets.
14555 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_byte (unsigned long long @var{offset})
14556 Load a byte from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
14559 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_half (unsigned long long @var{offset})
14560 Load 16-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
14563 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_word (unsigned long long @var{offset})
14564 Load 32-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it.
14567 @node BPF Kernel Helpers
14568 @subsection BPF Kernel Helpers
14570 These built-in functions are available for calling kernel helpers, and
14571 they are available depending on the kernel version selected as the
14574 Rather than using the built-ins directly, it is preferred for programs
14575 to include @file{bpf-helpers.h} and use the wrappers defined there.
14577 For a full description of what the helpers do, the arguments they
14578 take, and the returned value, see the
14579 @file{linux/include/uapi/linux/bpf.h} in a Linux source tree.
14582 void *__builtin_bpf_helper_map_lookup_elem (void *map, void *key)
14583 int __builtin_bpf_helper_map_update_elem (void *map, void *key,
14585 unsigned long long flags)
14586 int __builtin_bpf_helper_map_delete_elem (void *map, const void *key)
14587 int __builtin_bpf_helper_map_push_elem (void *map, const void *value,
14588 unsigned long long flags)
14589 int __builtin_bpf_helper_map_pop_elem (void *map, void *value)
14590 int __builtin_bpf_helper_map_peek_elem (void *map, void *value)
14591 int __builtin_bpf_helper_clone_redirect (void *skb,
14592 unsigned int ifindex,
14593 unsigned long long flags)
14594 int __builtin_bpf_helper_skb_get_tunnel_key (void *ctx, void *key, int size, int flags)
14595 int __builtin_bpf_helper_skb_set_tunnel_key (void *ctx, void *key, int size, int flags)
14596 int __builtin_bpf_helper_skb_get_tunnel_opt (void *ctx, void *md, int size)
14597 int __builtin_bpf_helper_skb_set_tunnel_opt (void *ctx, void *md, int size)
14598 int __builtin_bpf_helper_skb_get_xfrm_state (void *ctx, int index, void *state,
14599 int size, int flags)
14600 static unsigned long long __builtin_bpf_helper_skb_cgroup_id (void *ctx)
14601 static unsigned long long __builtin_bpf_helper_skb_ancestor_cgroup_id
14602 (void *ctx, int level)
14603 int __builtin_bpf_helper_skb_vlan_push (void *ctx, __be16 vlan_proto, __u16 vlan_tci)
14604 int __builtin_bpf_helper_skb_vlan_pop (void *ctx)
14605 int __builtin_bpf_helper_skb_ecn_set_ce (void *ctx)
14607 int __builtin_bpf_helper_skb_load_bytes (void *ctx, int off, void *to, int len)
14608 int __builtin_bpf_helper_skb_load_bytes_relative (void *ctx, int off, void *to, int len, __u32 start_header)
14609 int __builtin_bpf_helper_skb_store_bytes (void *ctx, int off, void *from, int len, int flags)
14610 int __builtin_bpf_helper_skb_under_cgroup (void *ctx, void *map, int index)
14611 int __builtin_bpf_helper_skb_change_head (void *, int len, int flags)
14612 int __builtin_bpf_helper_skb_pull_data (void *, int len)
14613 int __builtin_bpf_helper_skb_change_proto (void *ctx, __be16 proto, __u64 flags)
14614 int __builtin_bpf_helper_skb_change_type (void *ctx, __u32 type)
14615 int __builtin_bpf_helper_skb_change_tail (void *ctx, __u32 len, __u64 flags)
14616 int __builtin_bpf_helper_skb_adjust_room (void *ctx, __s32 len_diff, __u32 mode,
14617 unsigned long long flags)
14623 int __builtin_bpf_helper_probe_read (void *dst, unsigned int size, void *src)
14624 unsigned long long __builtin_bpf_helper_ktime_get_ns (void)
14625 int __builtin_bpf_helper_trace_printk (const char *fmt, unsigned int fmt_size, ...)
14626 void __builtin_bpf_helper_tail_call (void *ctx, void *prog_array_map, unsigned int index)
14627 unsigned int __builtin_bpf_helper_get_smp_processor_id (void)
14628 unsigned long long __builtin_bpf_helper_get_current_pid_tgid (void)
14629 unsigned long long __builtin_bpf_helper_get_current_uid_gid (void)
14630 int __builtin_bpf_helper_get_current_comm (void *buf, unsigned int size_of_buf)
14631 unsigned long long __builtin_bpf_helper_perf_event_read (void *map, unsigned long long flags)
14633 int __builtin_bpf_helper_redirect (unsigned int ifindex, unsigned long long flags)
14634 int __builtin_bpf_helper_redirect_map (void *map, unsigned int key, unsigned long long flags)
14635 int __builtin_bpf_helper_perf_event_output (void *ctx,void *map, unsigned long long flags, void *data, unsigned long long size)
14636 int __builtin_bpf_helper_get_stackid (void *ctx, void *map, unsigned long long flags)
14637 int __builtin_bpf_helper_probe_write_user (void *dst, const void *src, unsigned int len)
14638 int __builtin_bpf_helper_current_task_under_cgroup (void *map, unsigned int index)
14640 static unsigned long long __builtin_bpf_helper_get_prandom_u32 (void)
14641 int __builtin_bpf_helper_xdp_adjust_head (void *ctx, int offset)
14642 int __builtin_bpf_helper_xdp_adjust_meta (void *ctx, int offset)
14643 int __builtin_bpf_helper_get_socket_cookie (void *ctx)
14644 int __builtin_bpf_helper_setsockopt (void *ctx, int level, int optname, void *optval,
14646 int __builtin_bpf_helper_getsockopt (void *ctx, int level, int optname, void *optval,
14648 int __builtin_bpf_helper_sock_ops_cb_flags_set (void *ctx, int flags)
14649 int __builtin_bpf_helper_sk_redirect_map (void *ctx, void *map, int key, int flags)
14650 int __builtin_bpf_helper_sk_redirect_hash (void *ctx, void *map, void *key, int flags)
14651 int __builtin_bpf_helper_sock_map_update (void *map, void *key, void *value,
14652 unsigned long long flags)
14653 int __builtin_bpf_helper_sock_hash_update (void *map, void *key, void *value,
14654 unsigned long long flags)
14655 int __builtin_bpf_helper_perf_event_read_value (void *map, unsigned long long flags,
14656 void *buf, unsigned int buf_size)
14657 int __builtin_bpf_helper_perf_prog_read_value (void *ctx, void *buf,
14658 unsigned int buf_size)
14660 int __builtin_bpf_helper_override_return (void *ctx, unsigned long rc)
14661 int __builtin_bpf_helper_msg_redirect_map (void *ctx, void *map, int key, int flags)
14662 int __builtin_bpf_helper_msg_redirect_hash (void *ctx,
14663 void *map, void *key, int flags)
14664 int __builtin_bpf_helper_msg_apply_bytes (void *ctx, int len)
14665 int __builtin_bpf_helper_msg_cork_bytes (void *ctx, int len)
14666 int __builtin_bpf_helper_msg_pull_data (void *ctx, int start, int end, int flags)
14667 int __builtin_bpf_helper_msg_push_data (void *ctx, int start, int end, int flags)
14668 int __builtin_bpf_helper_msg_pop_data (void *ctx, int start, int cut, int flags)
14669 int __builtin_bpf_helper_bind (void *ctx, void *addr, int addr_len)
14670 int __builtin_bpf_helper_xdp_adjust_tail (void *ctx, int offset)
14671 int __builtin_bpf_helper_sk_select_reuseport (void *ctx, void *map, void *key, __u32 flags)
14672 int __builtin_bpf_helper_get_stack (void *ctx, void *buf, int size, int flags)
14673 int __builtin_bpf_helper_fib_lookup (void *ctx, struct bpf_fib_lookup *params,
14674 int plen, __u32 flags)
14676 int __builtin_bpf_helper_lwt_push_encap (void *ctx, unsigned int type, void *hdr,
14678 int __builtin_bpf_helper_lwt_seg6_store_bytes (void *ctx, unsigned int offset,
14679 void *from, unsigned int len)
14680 int __builtin_bpf_helper_lwt_seg6_action (void *ctx, unsigned int action, void *param,
14681 unsigned int param_len)
14682 int __builtin_bpf_helper_lwt_seg6_adjust_srh (void *ctx, unsigned int offset,
14684 int __builtin_bpf_helper_rc_repeat (void *ctx)
14685 int __builtin_bpf_helper_rc_keydown (void *ctx, unsigned int protocol,
14686 unsigned long long scancode, unsigned int toggle)
14687 static unsigned long long __builtin_bpf_helper_get_current_cgroup_id (void)
14688 static void *__builtin_bpf_helper_get_local_storage (void *map, unsigned long long flags)
14689 static struct bpf_sock *__builtin_bpf_helper_sk_lookup_tcp (void *ctx, void *tuple, int size, unsigned long long netns_id, unsigned long long flags)
14690 static struct bpf_sock *__builtin_bpf_helper_sk_lookup_udp (void *ctx, void *tuple, int size, unsigned long long netns_id, unsigned long long flags)
14691 int __builtin_bpf_helper_sk_release (struct bpf_sock *sk)
14692 int __builtin_bpf_helper_rc_pointer_rel (void *ctx, int rel_x, int rel_y)
14693 static void __builtin_bpf_helper_spin_lock (struct bpf_spin_lock *lock)
14694 static void __builtin_bpf_helper_spin_unlock (struct bpf_spin_lock *lock)
14696 static struct bpf_sock *__builtin_bpf_helper_sk_fullsock (struct bpf_sock *sk)
14697 static struct bpf_tcp_sock *__builtin_bpf_helper_tcp_sock (struct bpf_sock *sk)
14698 static struct bpf_sock *__builtin_bpf_helper_get_listener_sock (struct bpf_sock *sk)
14700 int __builtin_bpf_helper_l3_csum_replace (void *ctx, int off, int from, int to, int flags)
14701 int __builtin_bpf_helper_l4_csum_replace (void *ctx, int off, int from, int to, int flags)
14702 int __builtin_bpf_helper_csum_diff (void *from, int from_size, void *to, int to_size, int seed)
14704 static unsigned int __builtin_bpf_helper_get_cgroup_classid (void *ctx)
14705 static unsigned int __builtin_bpf_helper_get_route_realm (void *ctx)
14706 static unsigned int __builtin_bpf_helper_get_hash_recalc (void *ctx)
14707 static unsigned long long __builtin_bpf_helper_get_current_task (void *ctx)
14709 static long long __builtin_bpf_helper_csum_update (void *ctx, __u32 csum)
14710 static void __builtin_bpf_helper_set_hash_invalid (void *ctx)
14711 int __builtin_bpf_helper_get_numa_node_id (void)
14712 int __builtin_bpf_helper_probe_read_str (void *ctx, __u32 size,
14713 const void *unsafe_ptr)
14714 static unsigned int __builtin_bpf_helper_get_socket_uid (void *ctx)
14715 static unsigned int __builtin_bpf_helper_set_hash (void *ctx, __u32 hash)
14719 @node FR-V Built-in Functions
14720 @subsection FR-V Built-in Functions
14722 GCC provides many FR-V-specific built-in functions. In general,
14723 these functions are intended to be compatible with those described
14724 by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu
14725 Semiconductor}. The two exceptions are @code{__MDUNPACKH} and
14726 @code{__MBTOHE}, the GCC forms of which pass 128-bit values by
14727 pointer rather than by value.
14729 Most of the functions are named after specific FR-V instructions.
14730 Such functions are said to be ``directly mapped'' and are summarized
14731 here in tabular form.
14735 * Directly-mapped Integer Functions::
14736 * Directly-mapped Media Functions::
14737 * Raw read/write Functions::
14738 * Other Built-in Functions::
14741 @node Argument Types
14742 @subsubsection Argument Types
14744 The arguments to the built-in functions can be divided into three groups:
14745 register numbers, compile-time constants and run-time values. In order
14746 to make this classification clear at a glance, the arguments and return
14747 values are given the following pseudo types:
14749 @multitable @columnfractions .20 .30 .15 .35
14750 @item Pseudo type @tab Real C type @tab Constant? @tab Description
14751 @item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword
14752 @item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word
14753 @item @code{sw1} @tab @code{int} @tab No @tab a signed word
14754 @item @code{uw2} @tab @code{unsigned long long} @tab No
14755 @tab an unsigned doubleword
14756 @item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword
14757 @item @code{const} @tab @code{int} @tab Yes @tab an integer constant
14758 @item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number
14759 @item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number
14762 These pseudo types are not defined by GCC, they are simply a notational
14763 convenience used in this manual.
14765 Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2}
14766 and @code{sw2} are evaluated at run time. They correspond to
14767 register operands in the underlying FR-V instructions.
14769 @code{const} arguments represent immediate operands in the underlying
14770 FR-V instructions. They must be compile-time constants.
14772 @code{acc} arguments are evaluated at compile time and specify the number
14773 of an accumulator register. For example, an @code{acc} argument of 2
14774 selects the ACC2 register.
14776 @code{iacc} arguments are similar to @code{acc} arguments but specify the
14777 number of an IACC register. See @pxref{Other Built-in Functions}
14780 @node Directly-mapped Integer Functions
14781 @subsubsection Directly-Mapped Integer Functions
14783 The functions listed below map directly to FR-V I-type instructions.
14785 @multitable @columnfractions .45 .32 .23
14786 @item Function prototype @tab Example usage @tab Assembly output
14787 @item @code{sw1 __ADDSS (sw1, sw1)}
14788 @tab @code{@var{c} = __ADDSS (@var{a}, @var{b})}
14789 @tab @code{ADDSS @var{a},@var{b},@var{c}}
14790 @item @code{sw1 __SCAN (sw1, sw1)}
14791 @tab @code{@var{c} = __SCAN (@var{a}, @var{b})}
14792 @tab @code{SCAN @var{a},@var{b},@var{c}}
14793 @item @code{sw1 __SCUTSS (sw1)}
14794 @tab @code{@var{b} = __SCUTSS (@var{a})}
14795 @tab @code{SCUTSS @var{a},@var{b}}
14796 @item @code{sw1 __SLASS (sw1, sw1)}
14797 @tab @code{@var{c} = __SLASS (@var{a}, @var{b})}
14798 @tab @code{SLASS @var{a},@var{b},@var{c}}
14799 @item @code{void __SMASS (sw1, sw1)}
14800 @tab @code{__SMASS (@var{a}, @var{b})}
14801 @tab @code{SMASS @var{a},@var{b}}
14802 @item @code{void __SMSSS (sw1, sw1)}
14803 @tab @code{__SMSSS (@var{a}, @var{b})}
14804 @tab @code{SMSSS @var{a},@var{b}}
14805 @item @code{void __SMU (sw1, sw1)}
14806 @tab @code{__SMU (@var{a}, @var{b})}
14807 @tab @code{SMU @var{a},@var{b}}
14808 @item @code{sw2 __SMUL (sw1, sw1)}
14809 @tab @code{@var{c} = __SMUL (@var{a}, @var{b})}
14810 @tab @code{SMUL @var{a},@var{b},@var{c}}
14811 @item @code{sw1 __SUBSS (sw1, sw1)}
14812 @tab @code{@var{c} = __SUBSS (@var{a}, @var{b})}
14813 @tab @code{SUBSS @var{a},@var{b},@var{c}}
14814 @item @code{uw2 __UMUL (uw1, uw1)}
14815 @tab @code{@var{c} = __UMUL (@var{a}, @var{b})}
14816 @tab @code{UMUL @var{a},@var{b},@var{c}}
14819 @node Directly-mapped Media Functions
14820 @subsubsection Directly-Mapped Media Functions
14822 The functions listed below map directly to FR-V M-type instructions.
14824 @multitable @columnfractions .45 .32 .23
14825 @item Function prototype @tab Example usage @tab Assembly output
14826 @item @code{uw1 __MABSHS (sw1)}
14827 @tab @code{@var{b} = __MABSHS (@var{a})}
14828 @tab @code{MABSHS @var{a},@var{b}}
14829 @item @code{void __MADDACCS (acc, acc)}
14830 @tab @code{__MADDACCS (@var{b}, @var{a})}
14831 @tab @code{MADDACCS @var{a},@var{b}}
14832 @item @code{sw1 __MADDHSS (sw1, sw1)}
14833 @tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})}
14834 @tab @code{MADDHSS @var{a},@var{b},@var{c}}
14835 @item @code{uw1 __MADDHUS (uw1, uw1)}
14836 @tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})}
14837 @tab @code{MADDHUS @var{a},@var{b},@var{c}}
14838 @item @code{uw1 __MAND (uw1, uw1)}
14839 @tab @code{@var{c} = __MAND (@var{a}, @var{b})}
14840 @tab @code{MAND @var{a},@var{b},@var{c}}
14841 @item @code{void __MASACCS (acc, acc)}
14842 @tab @code{__MASACCS (@var{b}, @var{a})}
14843 @tab @code{MASACCS @var{a},@var{b}}
14844 @item @code{uw1 __MAVEH (uw1, uw1)}
14845 @tab @code{@var{c} = __MAVEH (@var{a}, @var{b})}
14846 @tab @code{MAVEH @var{a},@var{b},@var{c}}
14847 @item @code{uw2 __MBTOH (uw1)}
14848 @tab @code{@var{b} = __MBTOH (@var{a})}
14849 @tab @code{MBTOH @var{a},@var{b}}
14850 @item @code{void __MBTOHE (uw1 *, uw1)}
14851 @tab @code{__MBTOHE (&@var{b}, @var{a})}
14852 @tab @code{MBTOHE @var{a},@var{b}}
14853 @item @code{void __MCLRACC (acc)}
14854 @tab @code{__MCLRACC (@var{a})}
14855 @tab @code{MCLRACC @var{a}}
14856 @item @code{void __MCLRACCA (void)}
14857 @tab @code{__MCLRACCA ()}
14858 @tab @code{MCLRACCA}
14859 @item @code{uw1 __Mcop1 (uw1, uw1)}
14860 @tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})}
14861 @tab @code{Mcop1 @var{a},@var{b},@var{c}}
14862 @item @code{uw1 __Mcop2 (uw1, uw1)}
14863 @tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})}
14864 @tab @code{Mcop2 @var{a},@var{b},@var{c}}
14865 @item @code{uw1 __MCPLHI (uw2, const)}
14866 @tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})}
14867 @tab @code{MCPLHI @var{a},#@var{b},@var{c}}
14868 @item @code{uw1 __MCPLI (uw2, const)}
14869 @tab @code{@var{c} = __MCPLI (@var{a}, @var{b})}
14870 @tab @code{MCPLI @var{a},#@var{b},@var{c}}
14871 @item @code{void __MCPXIS (acc, sw1, sw1)}
14872 @tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})}
14873 @tab @code{MCPXIS @var{a},@var{b},@var{c}}
14874 @item @code{void __MCPXIU (acc, uw1, uw1)}
14875 @tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})}
14876 @tab @code{MCPXIU @var{a},@var{b},@var{c}}
14877 @item @code{void __MCPXRS (acc, sw1, sw1)}
14878 @tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})}
14879 @tab @code{MCPXRS @var{a},@var{b},@var{c}}
14880 @item @code{void __MCPXRU (acc, uw1, uw1)}
14881 @tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})}
14882 @tab @code{MCPXRU @var{a},@var{b},@var{c}}
14883 @item @code{uw1 __MCUT (acc, uw1)}
14884 @tab @code{@var{c} = __MCUT (@var{a}, @var{b})}
14885 @tab @code{MCUT @var{a},@var{b},@var{c}}
14886 @item @code{uw1 __MCUTSS (acc, sw1)}
14887 @tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})}
14888 @tab @code{MCUTSS @var{a},@var{b},@var{c}}
14889 @item @code{void __MDADDACCS (acc, acc)}
14890 @tab @code{__MDADDACCS (@var{b}, @var{a})}
14891 @tab @code{MDADDACCS @var{a},@var{b}}
14892 @item @code{void __MDASACCS (acc, acc)}
14893 @tab @code{__MDASACCS (@var{b}, @var{a})}
14894 @tab @code{MDASACCS @var{a},@var{b}}
14895 @item @code{uw2 __MDCUTSSI (acc, const)}
14896 @tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})}
14897 @tab @code{MDCUTSSI @var{a},#@var{b},@var{c}}
14898 @item @code{uw2 __MDPACKH (uw2, uw2)}
14899 @tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})}
14900 @tab @code{MDPACKH @var{a},@var{b},@var{c}}
14901 @item @code{uw2 __MDROTLI (uw2, const)}
14902 @tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})}
14903 @tab @code{MDROTLI @var{a},#@var{b},@var{c}}
14904 @item @code{void __MDSUBACCS (acc, acc)}
14905 @tab @code{__MDSUBACCS (@var{b}, @var{a})}
14906 @tab @code{MDSUBACCS @var{a},@var{b}}
14907 @item @code{void __MDUNPACKH (uw1 *, uw2)}
14908 @tab @code{__MDUNPACKH (&@var{b}, @var{a})}
14909 @tab @code{MDUNPACKH @var{a},@var{b}}
14910 @item @code{uw2 __MEXPDHD (uw1, const)}
14911 @tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})}
14912 @tab @code{MEXPDHD @var{a},#@var{b},@var{c}}
14913 @item @code{uw1 __MEXPDHW (uw1, const)}
14914 @tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})}
14915 @tab @code{MEXPDHW @var{a},#@var{b},@var{c}}
14916 @item @code{uw1 __MHDSETH (uw1, const)}
14917 @tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})}
14918 @tab @code{MHDSETH @var{a},#@var{b},@var{c}}
14919 @item @code{sw1 __MHDSETS (const)}
14920 @tab @code{@var{b} = __MHDSETS (@var{a})}
14921 @tab @code{MHDSETS #@var{a},@var{b}}
14922 @item @code{uw1 __MHSETHIH (uw1, const)}
14923 @tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})}
14924 @tab @code{MHSETHIH #@var{a},@var{b}}
14925 @item @code{sw1 __MHSETHIS (sw1, const)}
14926 @tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})}
14927 @tab @code{MHSETHIS #@var{a},@var{b}}
14928 @item @code{uw1 __MHSETLOH (uw1, const)}
14929 @tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})}
14930 @tab @code{MHSETLOH #@var{a},@var{b}}
14931 @item @code{sw1 __MHSETLOS (sw1, const)}
14932 @tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})}
14933 @tab @code{MHSETLOS #@var{a},@var{b}}
14934 @item @code{uw1 __MHTOB (uw2)}
14935 @tab @code{@var{b} = __MHTOB (@var{a})}
14936 @tab @code{MHTOB @var{a},@var{b}}
14937 @item @code{void __MMACHS (acc, sw1, sw1)}
14938 @tab @code{__MMACHS (@var{c}, @var{a}, @var{b})}
14939 @tab @code{MMACHS @var{a},@var{b},@var{c}}
14940 @item @code{void __MMACHU (acc, uw1, uw1)}
14941 @tab @code{__MMACHU (@var{c}, @var{a}, @var{b})}
14942 @tab @code{MMACHU @var{a},@var{b},@var{c}}
14943 @item @code{void __MMRDHS (acc, sw1, sw1)}
14944 @tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})}
14945 @tab @code{MMRDHS @var{a},@var{b},@var{c}}
14946 @item @code{void __MMRDHU (acc, uw1, uw1)}
14947 @tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})}
14948 @tab @code{MMRDHU @var{a},@var{b},@var{c}}
14949 @item @code{void __MMULHS (acc, sw1, sw1)}
14950 @tab @code{__MMULHS (@var{c}, @var{a}, @var{b})}
14951 @tab @code{MMULHS @var{a},@var{b},@var{c}}
14952 @item @code{void __MMULHU (acc, uw1, uw1)}
14953 @tab @code{__MMULHU (@var{c}, @var{a}, @var{b})}
14954 @tab @code{MMULHU @var{a},@var{b},@var{c}}
14955 @item @code{void __MMULXHS (acc, sw1, sw1)}
14956 @tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})}
14957 @tab @code{MMULXHS @var{a},@var{b},@var{c}}
14958 @item @code{void __MMULXHU (acc, uw1, uw1)}
14959 @tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})}
14960 @tab @code{MMULXHU @var{a},@var{b},@var{c}}
14961 @item @code{uw1 __MNOT (uw1)}
14962 @tab @code{@var{b} = __MNOT (@var{a})}
14963 @tab @code{MNOT @var{a},@var{b}}
14964 @item @code{uw1 __MOR (uw1, uw1)}
14965 @tab @code{@var{c} = __MOR (@var{a}, @var{b})}
14966 @tab @code{MOR @var{a},@var{b},@var{c}}
14967 @item @code{uw1 __MPACKH (uh, uh)}
14968 @tab @code{@var{c} = __MPACKH (@var{a}, @var{b})}
14969 @tab @code{MPACKH @var{a},@var{b},@var{c}}
14970 @item @code{sw2 __MQADDHSS (sw2, sw2)}
14971 @tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})}
14972 @tab @code{MQADDHSS @var{a},@var{b},@var{c}}
14973 @item @code{uw2 __MQADDHUS (uw2, uw2)}
14974 @tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})}
14975 @tab @code{MQADDHUS @var{a},@var{b},@var{c}}
14976 @item @code{void __MQCPXIS (acc, sw2, sw2)}
14977 @tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})}
14978 @tab @code{MQCPXIS @var{a},@var{b},@var{c}}
14979 @item @code{void __MQCPXIU (acc, uw2, uw2)}
14980 @tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})}
14981 @tab @code{MQCPXIU @var{a},@var{b},@var{c}}
14982 @item @code{void __MQCPXRS (acc, sw2, sw2)}
14983 @tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})}
14984 @tab @code{MQCPXRS @var{a},@var{b},@var{c}}
14985 @item @code{void __MQCPXRU (acc, uw2, uw2)}
14986 @tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})}
14987 @tab @code{MQCPXRU @var{a},@var{b},@var{c}}
14988 @item @code{sw2 __MQLCLRHS (sw2, sw2)}
14989 @tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})}
14990 @tab @code{MQLCLRHS @var{a},@var{b},@var{c}}
14991 @item @code{sw2 __MQLMTHS (sw2, sw2)}
14992 @tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})}
14993 @tab @code{MQLMTHS @var{a},@var{b},@var{c}}
14994 @item @code{void __MQMACHS (acc, sw2, sw2)}
14995 @tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})}
14996 @tab @code{MQMACHS @var{a},@var{b},@var{c}}
14997 @item @code{void __MQMACHU (acc, uw2, uw2)}
14998 @tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})}
14999 @tab @code{MQMACHU @var{a},@var{b},@var{c}}
15000 @item @code{void __MQMACXHS (acc, sw2, sw2)}
15001 @tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})}
15002 @tab @code{MQMACXHS @var{a},@var{b},@var{c}}
15003 @item @code{void __MQMULHS (acc, sw2, sw2)}
15004 @tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})}
15005 @tab @code{MQMULHS @var{a},@var{b},@var{c}}
15006 @item @code{void __MQMULHU (acc, uw2, uw2)}
15007 @tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})}
15008 @tab @code{MQMULHU @var{a},@var{b},@var{c}}
15009 @item @code{void __MQMULXHS (acc, sw2, sw2)}
15010 @tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})}
15011 @tab @code{MQMULXHS @var{a},@var{b},@var{c}}
15012 @item @code{void __MQMULXHU (acc, uw2, uw2)}
15013 @tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})}
15014 @tab @code{MQMULXHU @var{a},@var{b},@var{c}}
15015 @item @code{sw2 __MQSATHS (sw2, sw2)}
15016 @tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})}
15017 @tab @code{MQSATHS @var{a},@var{b},@var{c}}
15018 @item @code{uw2 __MQSLLHI (uw2, int)}
15019 @tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})}
15020 @tab @code{MQSLLHI @var{a},@var{b},@var{c}}
15021 @item @code{sw2 __MQSRAHI (sw2, int)}
15022 @tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})}
15023 @tab @code{MQSRAHI @var{a},@var{b},@var{c}}
15024 @item @code{sw2 __MQSUBHSS (sw2, sw2)}
15025 @tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})}
15026 @tab @code{MQSUBHSS @var{a},@var{b},@var{c}}
15027 @item @code{uw2 __MQSUBHUS (uw2, uw2)}
15028 @tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})}
15029 @tab @code{MQSUBHUS @var{a},@var{b},@var{c}}
15030 @item @code{void __MQXMACHS (acc, sw2, sw2)}
15031 @tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})}
15032 @tab @code{MQXMACHS @var{a},@var{b},@var{c}}
15033 @item @code{void __MQXMACXHS (acc, sw2, sw2)}
15034 @tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})}
15035 @tab @code{MQXMACXHS @var{a},@var{b},@var{c}}
15036 @item @code{uw1 __MRDACC (acc)}
15037 @tab @code{@var{b} = __MRDACC (@var{a})}
15038 @tab @code{MRDACC @var{a},@var{b}}
15039 @item @code{uw1 __MRDACCG (acc)}
15040 @tab @code{@var{b} = __MRDACCG (@var{a})}
15041 @tab @code{MRDACCG @var{a},@var{b}}
15042 @item @code{uw1 __MROTLI (uw1, const)}
15043 @tab @code{@var{c} = __MROTLI (@var{a}, @var{b})}
15044 @tab @code{MROTLI @var{a},#@var{b},@var{c}}
15045 @item @code{uw1 __MROTRI (uw1, const)}
15046 @tab @code{@var{c} = __MROTRI (@var{a}, @var{b})}
15047 @tab @code{MROTRI @var{a},#@var{b},@var{c}}
15048 @item @code{sw1 __MSATHS (sw1, sw1)}
15049 @tab @code{@var{c} = __MSATHS (@var{a}, @var{b})}
15050 @tab @code{MSATHS @var{a},@var{b},@var{c}}
15051 @item @code{uw1 __MSATHU (uw1, uw1)}
15052 @tab @code{@var{c} = __MSATHU (@var{a}, @var{b})}
15053 @tab @code{MSATHU @var{a},@var{b},@var{c}}
15054 @item @code{uw1 __MSLLHI (uw1, const)}
15055 @tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})}
15056 @tab @code{MSLLHI @var{a},#@var{b},@var{c}}
15057 @item @code{sw1 __MSRAHI (sw1, const)}
15058 @tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})}
15059 @tab @code{MSRAHI @var{a},#@var{b},@var{c}}
15060 @item @code{uw1 __MSRLHI (uw1, const)}
15061 @tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})}
15062 @tab @code{MSRLHI @var{a},#@var{b},@var{c}}
15063 @item @code{void __MSUBACCS (acc, acc)}
15064 @tab @code{__MSUBACCS (@var{b}, @var{a})}
15065 @tab @code{MSUBACCS @var{a},@var{b}}
15066 @item @code{sw1 __MSUBHSS (sw1, sw1)}
15067 @tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})}
15068 @tab @code{MSUBHSS @var{a},@var{b},@var{c}}
15069 @item @code{uw1 __MSUBHUS (uw1, uw1)}
15070 @tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})}
15071 @tab @code{MSUBHUS @var{a},@var{b},@var{c}}
15072 @item @code{void __MTRAP (void)}
15073 @tab @code{__MTRAP ()}
15075 @item @code{uw2 __MUNPACKH (uw1)}
15076 @tab @code{@var{b} = __MUNPACKH (@var{a})}
15077 @tab @code{MUNPACKH @var{a},@var{b}}
15078 @item @code{uw1 __MWCUT (uw2, uw1)}
15079 @tab @code{@var{c} = __MWCUT (@var{a}, @var{b})}
15080 @tab @code{MWCUT @var{a},@var{b},@var{c}}
15081 @item @code{void __MWTACC (acc, uw1)}
15082 @tab @code{__MWTACC (@var{b}, @var{a})}
15083 @tab @code{MWTACC @var{a},@var{b}}
15084 @item @code{void __MWTACCG (acc, uw1)}
15085 @tab @code{__MWTACCG (@var{b}, @var{a})}
15086 @tab @code{MWTACCG @var{a},@var{b}}
15087 @item @code{uw1 __MXOR (uw1, uw1)}
15088 @tab @code{@var{c} = __MXOR (@var{a}, @var{b})}
15089 @tab @code{MXOR @var{a},@var{b},@var{c}}
15092 @node Raw read/write Functions
15093 @subsubsection Raw Read/Write Functions
15095 This sections describes built-in functions related to read and write
15096 instructions to access memory. These functions generate
15097 @code{membar} instructions to flush the I/O load and stores where
15098 appropriate, as described in Fujitsu's manual described above.
15102 @item unsigned char __builtin_read8 (void *@var{data})
15103 @item unsigned short __builtin_read16 (void *@var{data})
15104 @item unsigned long __builtin_read32 (void *@var{data})
15105 @item unsigned long long __builtin_read64 (void *@var{data})
15107 @item void __builtin_write8 (void *@var{data}, unsigned char @var{datum})
15108 @item void __builtin_write16 (void *@var{data}, unsigned short @var{datum})
15109 @item void __builtin_write32 (void *@var{data}, unsigned long @var{datum})
15110 @item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum})
15113 @node Other Built-in Functions
15114 @subsubsection Other Built-in Functions
15116 This section describes built-in functions that are not named after
15117 a specific FR-V instruction.
15120 @item sw2 __IACCreadll (iacc @var{reg})
15121 Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved
15122 for future expansion and must be 0.
15124 @item sw1 __IACCreadl (iacc @var{reg})
15125 Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1.
15126 Other values of @var{reg} are rejected as invalid.
15128 @item void __IACCsetll (iacc @var{reg}, sw2 @var{x})
15129 Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument
15130 is reserved for future expansion and must be 0.
15132 @item void __IACCsetl (iacc @var{reg}, sw1 @var{x})
15133 Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg}
15134 is 1. Other values of @var{reg} are rejected as invalid.
15136 @item void __data_prefetch0 (const void *@var{x})
15137 Use the @code{dcpl} instruction to load the contents of address @var{x}
15138 into the data cache.
15140 @item void __data_prefetch (const void *@var{x})
15141 Use the @code{nldub} instruction to load the contents of address @var{x}
15142 into the data cache. The instruction is issued in slot I1@.
15145 @node MIPS DSP Built-in Functions
15146 @subsection MIPS DSP Built-in Functions
15148 The MIPS DSP Application-Specific Extension (ASE) includes new
15149 instructions that are designed to improve the performance of DSP and
15150 media applications. It provides instructions that operate on packed
15151 8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data.
15153 GCC supports MIPS DSP operations using both the generic
15154 vector extensions (@pxref{Vector Extensions}) and a collection of
15155 MIPS-specific built-in functions. Both kinds of support are
15156 enabled by the @option{-mdsp} command-line option.
15158 Revision 2 of the ASE was introduced in the second half of 2006.
15159 This revision adds extra instructions to the original ASE, but is
15160 otherwise backwards-compatible with it. You can select revision 2
15161 using the command-line option @option{-mdspr2}; this option implies
15164 The SCOUNT and POS bits of the DSP control register are global. The
15165 WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and
15166 POS bits. During optimization, the compiler does not delete these
15167 instructions and it does not delete calls to functions containing
15168 these instructions.
15170 At present, GCC only provides support for operations on 32-bit
15171 vectors. The vector type associated with 8-bit integer data is
15172 usually called @code{v4i8}, the vector type associated with Q7
15173 is usually called @code{v4q7}, the vector type associated with 16-bit
15174 integer data is usually called @code{v2i16}, and the vector type
15175 associated with Q15 is usually called @code{v2q15}. They can be
15176 defined in C as follows:
15179 typedef signed char v4i8 __attribute__ ((vector_size(4)));
15180 typedef signed char v4q7 __attribute__ ((vector_size(4)));
15181 typedef short v2i16 __attribute__ ((vector_size(4)));
15182 typedef short v2q15 __attribute__ ((vector_size(4)));
15185 @code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are
15186 initialized in the same way as aggregates. For example:
15189 v4i8 a = @{1, 2, 3, 4@};
15191 b = (v4i8) @{5, 6, 7, 8@};
15193 v2q15 c = @{0x0fcb, 0x3a75@};
15195 d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@};
15198 @emph{Note:} The CPU's endianness determines the order in which values
15199 are packed. On little-endian targets, the first value is the least
15200 significant and the last value is the most significant. The opposite
15201 order applies to big-endian targets. For example, the code above
15202 sets the lowest byte of @code{a} to @code{1} on little-endian targets
15203 and @code{4} on big-endian targets.
15205 @emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer
15206 representation. As shown in this example, the integer representation
15207 of a Q7 value can be obtained by multiplying the fractional value by
15208 @code{0x1.0p7}. The equivalent for Q15 values is to multiply by
15209 @code{0x1.0p15}. The equivalent for Q31 values is to multiply by
15212 The table below lists the @code{v4i8} and @code{v2q15} operations for which
15213 hardware support exists. @code{a} and @code{b} are @code{v4i8} values,
15214 and @code{c} and @code{d} are @code{v2q15} values.
15216 @multitable @columnfractions .50 .50
15217 @item C code @tab MIPS instruction
15218 @item @code{a + b} @tab @code{addu.qb}
15219 @item @code{c + d} @tab @code{addq.ph}
15220 @item @code{a - b} @tab @code{subu.qb}
15221 @item @code{c - d} @tab @code{subq.ph}
15224 The table below lists the @code{v2i16} operation for which
15225 hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are
15226 @code{v2i16} values.
15228 @multitable @columnfractions .50 .50
15229 @item C code @tab MIPS instruction
15230 @item @code{e * f} @tab @code{mul.ph}
15233 It is easier to describe the DSP built-in functions if we first define
15234 the following types:
15239 typedef unsigned int ui32;
15240 typedef long long a64;
15243 @code{q31} and @code{i32} are actually the same as @code{int}, but we
15244 use @code{q31} to indicate a Q31 fractional value and @code{i32} to
15245 indicate a 32-bit integer value. Similarly, @code{a64} is the same as
15246 @code{long long}, but we use @code{a64} to indicate values that are
15247 placed in one of the four DSP accumulators (@code{$ac0},
15248 @code{$ac1}, @code{$ac2} or @code{$ac3}).
15250 Also, some built-in functions prefer or require immediate numbers as
15251 parameters, because the corresponding DSP instructions accept both immediate
15252 numbers and register operands, or accept immediate numbers only. The
15253 immediate parameters are listed as follows.
15261 imm0_255: 0 to 255.
15262 imm_n32_31: -32 to 31.
15263 imm_n512_511: -512 to 511.
15266 The following built-in functions map directly to a particular MIPS DSP
15267 instruction. Please refer to the architecture specification
15268 for details on what each instruction does.
15271 v2q15 __builtin_mips_addq_ph (v2q15, v2q15)
15272 v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15)
15273 q31 __builtin_mips_addq_s_w (q31, q31)
15274 v4i8 __builtin_mips_addu_qb (v4i8, v4i8)
15275 v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8)
15276 v2q15 __builtin_mips_subq_ph (v2q15, v2q15)
15277 v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15)
15278 q31 __builtin_mips_subq_s_w (q31, q31)
15279 v4i8 __builtin_mips_subu_qb (v4i8, v4i8)
15280 v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8)
15281 i32 __builtin_mips_addsc (i32, i32)
15282 i32 __builtin_mips_addwc (i32, i32)
15283 i32 __builtin_mips_modsub (i32, i32)
15284 i32 __builtin_mips_raddu_w_qb (v4i8)
15285 v2q15 __builtin_mips_absq_s_ph (v2q15)
15286 q31 __builtin_mips_absq_s_w (q31)
15287 v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15)
15288 v2q15 __builtin_mips_precrq_ph_w (q31, q31)
15289 v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31)
15290 v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15)
15291 q31 __builtin_mips_preceq_w_phl (v2q15)
15292 q31 __builtin_mips_preceq_w_phr (v2q15)
15293 v2q15 __builtin_mips_precequ_ph_qbl (v4i8)
15294 v2q15 __builtin_mips_precequ_ph_qbr (v4i8)
15295 v2q15 __builtin_mips_precequ_ph_qbla (v4i8)
15296 v2q15 __builtin_mips_precequ_ph_qbra (v4i8)
15297 v2q15 __builtin_mips_preceu_ph_qbl (v4i8)
15298 v2q15 __builtin_mips_preceu_ph_qbr (v4i8)
15299 v2q15 __builtin_mips_preceu_ph_qbla (v4i8)
15300 v2q15 __builtin_mips_preceu_ph_qbra (v4i8)
15301 v4i8 __builtin_mips_shll_qb (v4i8, imm0_7)
15302 v4i8 __builtin_mips_shll_qb (v4i8, i32)
15303 v2q15 __builtin_mips_shll_ph (v2q15, imm0_15)
15304 v2q15 __builtin_mips_shll_ph (v2q15, i32)
15305 v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15)
15306 v2q15 __builtin_mips_shll_s_ph (v2q15, i32)
15307 q31 __builtin_mips_shll_s_w (q31, imm0_31)
15308 q31 __builtin_mips_shll_s_w (q31, i32)
15309 v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7)
15310 v4i8 __builtin_mips_shrl_qb (v4i8, i32)
15311 v2q15 __builtin_mips_shra_ph (v2q15, imm0_15)
15312 v2q15 __builtin_mips_shra_ph (v2q15, i32)
15313 v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15)
15314 v2q15 __builtin_mips_shra_r_ph (v2q15, i32)
15315 q31 __builtin_mips_shra_r_w (q31, imm0_31)
15316 q31 __builtin_mips_shra_r_w (q31, i32)
15317 v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15)
15318 v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15)
15319 v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15)
15320 q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15)
15321 q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15)
15322 a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8)
15323 a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8)
15324 a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8)
15325 a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8)
15326 a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15)
15327 a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31)
15328 a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15)
15329 a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31)
15330 a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15)
15331 a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15)
15332 a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15)
15333 a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15)
15334 a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15)
15335 i32 __builtin_mips_bitrev (i32)
15336 i32 __builtin_mips_insv (i32, i32)
15337 v4i8 __builtin_mips_repl_qb (imm0_255)
15338 v4i8 __builtin_mips_repl_qb (i32)
15339 v2q15 __builtin_mips_repl_ph (imm_n512_511)
15340 v2q15 __builtin_mips_repl_ph (i32)
15341 void __builtin_mips_cmpu_eq_qb (v4i8, v4i8)
15342 void __builtin_mips_cmpu_lt_qb (v4i8, v4i8)
15343 void __builtin_mips_cmpu_le_qb (v4i8, v4i8)
15344 i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8)
15345 i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8)
15346 i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8)
15347 void __builtin_mips_cmp_eq_ph (v2q15, v2q15)
15348 void __builtin_mips_cmp_lt_ph (v2q15, v2q15)
15349 void __builtin_mips_cmp_le_ph (v2q15, v2q15)
15350 v4i8 __builtin_mips_pick_qb (v4i8, v4i8)
15351 v2q15 __builtin_mips_pick_ph (v2q15, v2q15)
15352 v2q15 __builtin_mips_packrl_ph (v2q15, v2q15)
15353 i32 __builtin_mips_extr_w (a64, imm0_31)
15354 i32 __builtin_mips_extr_w (a64, i32)
15355 i32 __builtin_mips_extr_r_w (a64, imm0_31)
15356 i32 __builtin_mips_extr_s_h (a64, i32)
15357 i32 __builtin_mips_extr_rs_w (a64, imm0_31)
15358 i32 __builtin_mips_extr_rs_w (a64, i32)
15359 i32 __builtin_mips_extr_s_h (a64, imm0_31)
15360 i32 __builtin_mips_extr_r_w (a64, i32)
15361 i32 __builtin_mips_extp (a64, imm0_31)
15362 i32 __builtin_mips_extp (a64, i32)
15363 i32 __builtin_mips_extpdp (a64, imm0_31)
15364 i32 __builtin_mips_extpdp (a64, i32)
15365 a64 __builtin_mips_shilo (a64, imm_n32_31)
15366 a64 __builtin_mips_shilo (a64, i32)
15367 a64 __builtin_mips_mthlip (a64, i32)
15368 void __builtin_mips_wrdsp (i32, imm0_63)
15369 i32 __builtin_mips_rddsp (imm0_63)
15370 i32 __builtin_mips_lbux (void *, i32)
15371 i32 __builtin_mips_lhx (void *, i32)
15372 i32 __builtin_mips_lwx (void *, i32)
15373 a64 __builtin_mips_ldx (void *, i32) [MIPS64 only]
15374 i32 __builtin_mips_bposge32 (void)
15375 a64 __builtin_mips_madd (a64, i32, i32);
15376 a64 __builtin_mips_maddu (a64, ui32, ui32);
15377 a64 __builtin_mips_msub (a64, i32, i32);
15378 a64 __builtin_mips_msubu (a64, ui32, ui32);
15379 a64 __builtin_mips_mult (i32, i32);
15380 a64 __builtin_mips_multu (ui32, ui32);
15383 The following built-in functions map directly to a particular MIPS DSP REV 2
15384 instruction. Please refer to the architecture specification
15385 for details on what each instruction does.
15388 v4q7 __builtin_mips_absq_s_qb (v4q7);
15389 v2i16 __builtin_mips_addu_ph (v2i16, v2i16);
15390 v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16);
15391 v4i8 __builtin_mips_adduh_qb (v4i8, v4i8);
15392 v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8);
15393 i32 __builtin_mips_append (i32, i32, imm0_31);
15394 i32 __builtin_mips_balign (i32, i32, imm0_3);
15395 i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8);
15396 i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8);
15397 i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8);
15398 a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16);
15399 a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16);
15400 v2i16 __builtin_mips_mul_ph (v2i16, v2i16);
15401 v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16);
15402 q31 __builtin_mips_mulq_rs_w (q31, q31);
15403 v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15);
15404 q31 __builtin_mips_mulq_s_w (q31, q31);
15405 a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16);
15406 v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16);
15407 v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31);
15408 v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31);
15409 i32 __builtin_mips_prepend (i32, i32, imm0_31);
15410 v4i8 __builtin_mips_shra_qb (v4i8, imm0_7);
15411 v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7);
15412 v4i8 __builtin_mips_shra_qb (v4i8, i32);
15413 v4i8 __builtin_mips_shra_r_qb (v4i8, i32);
15414 v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15);
15415 v2i16 __builtin_mips_shrl_ph (v2i16, i32);
15416 v2i16 __builtin_mips_subu_ph (v2i16, v2i16);
15417 v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16);
15418 v4i8 __builtin_mips_subuh_qb (v4i8, v4i8);
15419 v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8);
15420 v2q15 __builtin_mips_addqh_ph (v2q15, v2q15);
15421 v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15);
15422 q31 __builtin_mips_addqh_w (q31, q31);
15423 q31 __builtin_mips_addqh_r_w (q31, q31);
15424 v2q15 __builtin_mips_subqh_ph (v2q15, v2q15);
15425 v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15);
15426 q31 __builtin_mips_subqh_w (q31, q31);
15427 q31 __builtin_mips_subqh_r_w (q31, q31);
15428 a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16);
15429 a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16);
15430 a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15);
15431 a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15);
15432 a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15);
15433 a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15);
15437 @node MIPS Paired-Single Support
15438 @subsection MIPS Paired-Single Support
15440 The MIPS64 architecture includes a number of instructions that
15441 operate on pairs of single-precision floating-point values.
15442 Each pair is packed into a 64-bit floating-point register,
15443 with one element being designated the ``upper half'' and
15444 the other being designated the ``lower half''.
15446 GCC supports paired-single operations using both the generic
15447 vector extensions (@pxref{Vector Extensions}) and a collection of
15448 MIPS-specific built-in functions. Both kinds of support are
15449 enabled by the @option{-mpaired-single} command-line option.
15451 The vector type associated with paired-single values is usually
15452 called @code{v2sf}. It can be defined in C as follows:
15455 typedef float v2sf __attribute__ ((vector_size (8)));
15458 @code{v2sf} values are initialized in the same way as aggregates.
15462 v2sf a = @{1.5, 9.1@};
15465 b = (v2sf) @{e, f@};
15468 @emph{Note:} The CPU's endianness determines which value is stored in
15469 the upper half of a register and which value is stored in the lower half.
15470 On little-endian targets, the first value is the lower one and the second
15471 value is the upper one. The opposite order applies to big-endian targets.
15472 For example, the code above sets the lower half of @code{a} to
15473 @code{1.5} on little-endian targets and @code{9.1} on big-endian targets.
15475 @node MIPS Loongson Built-in Functions
15476 @subsection MIPS Loongson Built-in Functions
15478 GCC provides intrinsics to access the SIMD instructions provided by the
15479 ST Microelectronics Loongson-2E and -2F processors. These intrinsics,
15480 available after inclusion of the @code{loongson.h} header file,
15481 operate on the following 64-bit vector types:
15484 @item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers;
15485 @item @code{uint16x4_t}, a vector of four unsigned 16-bit integers;
15486 @item @code{uint32x2_t}, a vector of two unsigned 32-bit integers;
15487 @item @code{int8x8_t}, a vector of eight signed 8-bit integers;
15488 @item @code{int16x4_t}, a vector of four signed 16-bit integers;
15489 @item @code{int32x2_t}, a vector of two signed 32-bit integers.
15492 The intrinsics provided are listed below; each is named after the
15493 machine instruction to which it corresponds, with suffixes added as
15494 appropriate to distinguish intrinsics that expand to the same machine
15495 instruction yet have different argument types. Refer to the architecture
15496 documentation for a description of the functionality of each
15500 int16x4_t packsswh (int32x2_t s, int32x2_t t);
15501 int8x8_t packsshb (int16x4_t s, int16x4_t t);
15502 uint8x8_t packushb (uint16x4_t s, uint16x4_t t);
15503 uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t);
15504 uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t);
15505 uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t);
15506 int32x2_t paddw_s (int32x2_t s, int32x2_t t);
15507 int16x4_t paddh_s (int16x4_t s, int16x4_t t);
15508 int8x8_t paddb_s (int8x8_t s, int8x8_t t);
15509 uint64_t paddd_u (uint64_t s, uint64_t t);
15510 int64_t paddd_s (int64_t s, int64_t t);
15511 int16x4_t paddsh (int16x4_t s, int16x4_t t);
15512 int8x8_t paddsb (int8x8_t s, int8x8_t t);
15513 uint16x4_t paddush (uint16x4_t s, uint16x4_t t);
15514 uint8x8_t paddusb (uint8x8_t s, uint8x8_t t);
15515 uint64_t pandn_ud (uint64_t s, uint64_t t);
15516 uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t);
15517 uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t);
15518 uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t);
15519 int64_t pandn_sd (int64_t s, int64_t t);
15520 int32x2_t pandn_sw (int32x2_t s, int32x2_t t);
15521 int16x4_t pandn_sh (int16x4_t s, int16x4_t t);
15522 int8x8_t pandn_sb (int8x8_t s, int8x8_t t);
15523 uint16x4_t pavgh (uint16x4_t s, uint16x4_t t);
15524 uint8x8_t pavgb (uint8x8_t s, uint8x8_t t);
15525 uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t);
15526 uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t);
15527 uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t);
15528 int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t);
15529 int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t);
15530 int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t);
15531 uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t);
15532 uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t);
15533 uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t);
15534 int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t);
15535 int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t);
15536 int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t);
15537 uint16x4_t pextrh_u (uint16x4_t s, int field);
15538 int16x4_t pextrh_s (int16x4_t s, int field);
15539 uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t);
15540 uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t);
15541 uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t);
15542 uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t);
15543 int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t);
15544 int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t);
15545 int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t);
15546 int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t);
15547 int32x2_t pmaddhw (int16x4_t s, int16x4_t t);
15548 int16x4_t pmaxsh (int16x4_t s, int16x4_t t);
15549 uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t);
15550 int16x4_t pminsh (int16x4_t s, int16x4_t t);
15551 uint8x8_t pminub (uint8x8_t s, uint8x8_t t);
15552 uint8x8_t pmovmskb_u (uint8x8_t s);
15553 int8x8_t pmovmskb_s (int8x8_t s);
15554 uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t);
15555 int16x4_t pmulhh (int16x4_t s, int16x4_t t);
15556 int16x4_t pmullh (int16x4_t s, int16x4_t t);
15557 int64_t pmuluw (uint32x2_t s, uint32x2_t t);
15558 uint8x8_t pasubub (uint8x8_t s, uint8x8_t t);
15559 uint16x4_t biadd (uint8x8_t s);
15560 uint16x4_t psadbh (uint8x8_t s, uint8x8_t t);
15561 uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order);
15562 int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order);
15563 uint16x4_t psllh_u (uint16x4_t s, uint8_t amount);
15564 int16x4_t psllh_s (int16x4_t s, uint8_t amount);
15565 uint32x2_t psllw_u (uint32x2_t s, uint8_t amount);
15566 int32x2_t psllw_s (int32x2_t s, uint8_t amount);
15567 uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount);
15568 int16x4_t psrlh_s (int16x4_t s, uint8_t amount);
15569 uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount);
15570 int32x2_t psrlw_s (int32x2_t s, uint8_t amount);
15571 uint16x4_t psrah_u (uint16x4_t s, uint8_t amount);
15572 int16x4_t psrah_s (int16x4_t s, uint8_t amount);
15573 uint32x2_t psraw_u (uint32x2_t s, uint8_t amount);
15574 int32x2_t psraw_s (int32x2_t s, uint8_t amount);
15575 uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t);
15576 uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t);
15577 uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t);
15578 int32x2_t psubw_s (int32x2_t s, int32x2_t t);
15579 int16x4_t psubh_s (int16x4_t s, int16x4_t t);
15580 int8x8_t psubb_s (int8x8_t s, int8x8_t t);
15581 uint64_t psubd_u (uint64_t s, uint64_t t);
15582 int64_t psubd_s (int64_t s, int64_t t);
15583 int16x4_t psubsh (int16x4_t s, int16x4_t t);
15584 int8x8_t psubsb (int8x8_t s, int8x8_t t);
15585 uint16x4_t psubush (uint16x4_t s, uint16x4_t t);
15586 uint8x8_t psubusb (uint8x8_t s, uint8x8_t t);
15587 uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t);
15588 uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t);
15589 uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t);
15590 int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t);
15591 int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t);
15592 int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t);
15593 uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t);
15594 uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t);
15595 uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t);
15596 int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t);
15597 int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t);
15598 int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t);
15602 * Paired-Single Arithmetic::
15603 * Paired-Single Built-in Functions::
15604 * MIPS-3D Built-in Functions::
15607 @node Paired-Single Arithmetic
15608 @subsubsection Paired-Single Arithmetic
15610 The table below lists the @code{v2sf} operations for which hardware
15611 support exists. @code{a}, @code{b} and @code{c} are @code{v2sf}
15612 values and @code{x} is an integral value.
15614 @multitable @columnfractions .50 .50
15615 @item C code @tab MIPS instruction
15616 @item @code{a + b} @tab @code{add.ps}
15617 @item @code{a - b} @tab @code{sub.ps}
15618 @item @code{-a} @tab @code{neg.ps}
15619 @item @code{a * b} @tab @code{mul.ps}
15620 @item @code{a * b + c} @tab @code{madd.ps}
15621 @item @code{a * b - c} @tab @code{msub.ps}
15622 @item @code{-(a * b + c)} @tab @code{nmadd.ps}
15623 @item @code{-(a * b - c)} @tab @code{nmsub.ps}
15624 @item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps}
15627 Note that the multiply-accumulate instructions can be disabled
15628 using the command-line option @code{-mno-fused-madd}.
15630 @node Paired-Single Built-in Functions
15631 @subsubsection Paired-Single Built-in Functions
15633 The following paired-single functions map directly to a particular
15634 MIPS instruction. Please refer to the architecture specification
15635 for details on what each instruction does.
15638 @item v2sf __builtin_mips_pll_ps (v2sf, v2sf)
15639 Pair lower lower (@code{pll.ps}).
15641 @item v2sf __builtin_mips_pul_ps (v2sf, v2sf)
15642 Pair upper lower (@code{pul.ps}).
15644 @item v2sf __builtin_mips_plu_ps (v2sf, v2sf)
15645 Pair lower upper (@code{plu.ps}).
15647 @item v2sf __builtin_mips_puu_ps (v2sf, v2sf)
15648 Pair upper upper (@code{puu.ps}).
15650 @item v2sf __builtin_mips_cvt_ps_s (float, float)
15651 Convert pair to paired single (@code{cvt.ps.s}).
15653 @item float __builtin_mips_cvt_s_pl (v2sf)
15654 Convert pair lower to single (@code{cvt.s.pl}).
15656 @item float __builtin_mips_cvt_s_pu (v2sf)
15657 Convert pair upper to single (@code{cvt.s.pu}).
15659 @item v2sf __builtin_mips_abs_ps (v2sf)
15660 Absolute value (@code{abs.ps}).
15662 @item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int)
15663 Align variable (@code{alnv.ps}).
15665 @emph{Note:} The value of the third parameter must be 0 or 4
15666 modulo 8, otherwise the result is unpredictable. Please read the
15667 instruction description for details.
15670 The following multi-instruction functions are also available.
15671 In each case, @var{cond} can be any of the 16 floating-point conditions:
15672 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
15673 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl},
15674 @code{lt}, @code{nge}, @code{le} or @code{ngt}.
15677 @item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15678 @itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15679 Conditional move based on floating-point comparison (@code{c.@var{cond}.ps},
15680 @code{movt.ps}/@code{movf.ps}).
15682 The @code{movt} functions return the value @var{x} computed by:
15685 c.@var{cond}.ps @var{cc},@var{a},@var{b}
15686 mov.ps @var{x},@var{c}
15687 movt.ps @var{x},@var{d},@var{cc}
15690 The @code{movf} functions are similar but use @code{movf.ps} instead
15693 @item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15694 @itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15695 Comparison of two paired-single values (@code{c.@var{cond}.ps},
15696 @code{bc1t}/@code{bc1f}).
15698 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
15699 and return either the upper or lower half of the result. For example:
15703 if (__builtin_mips_upper_c_eq_ps (a, b))
15704 upper_halves_are_equal ();
15706 upper_halves_are_unequal ();
15708 if (__builtin_mips_lower_c_eq_ps (a, b))
15709 lower_halves_are_equal ();
15711 lower_halves_are_unequal ();
15715 @node MIPS-3D Built-in Functions
15716 @subsubsection MIPS-3D Built-in Functions
15718 The MIPS-3D Application-Specific Extension (ASE) includes additional
15719 paired-single instructions that are designed to improve the performance
15720 of 3D graphics operations. Support for these instructions is controlled
15721 by the @option{-mips3d} command-line option.
15723 The functions listed below map directly to a particular MIPS-3D
15724 instruction. Please refer to the architecture specification for
15725 more details on what each instruction does.
15728 @item v2sf __builtin_mips_addr_ps (v2sf, v2sf)
15729 Reduction add (@code{addr.ps}).
15731 @item v2sf __builtin_mips_mulr_ps (v2sf, v2sf)
15732 Reduction multiply (@code{mulr.ps}).
15734 @item v2sf __builtin_mips_cvt_pw_ps (v2sf)
15735 Convert paired single to paired word (@code{cvt.pw.ps}).
15737 @item v2sf __builtin_mips_cvt_ps_pw (v2sf)
15738 Convert paired word to paired single (@code{cvt.ps.pw}).
15740 @item float __builtin_mips_recip1_s (float)
15741 @itemx double __builtin_mips_recip1_d (double)
15742 @itemx v2sf __builtin_mips_recip1_ps (v2sf)
15743 Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}).
15745 @item float __builtin_mips_recip2_s (float, float)
15746 @itemx double __builtin_mips_recip2_d (double, double)
15747 @itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf)
15748 Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}).
15750 @item float __builtin_mips_rsqrt1_s (float)
15751 @itemx double __builtin_mips_rsqrt1_d (double)
15752 @itemx v2sf __builtin_mips_rsqrt1_ps (v2sf)
15753 Reduced-precision reciprocal square root (sequence step 1)
15754 (@code{rsqrt1.@var{fmt}}).
15756 @item float __builtin_mips_rsqrt2_s (float, float)
15757 @itemx double __builtin_mips_rsqrt2_d (double, double)
15758 @itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf)
15759 Reduced-precision reciprocal square root (sequence step 2)
15760 (@code{rsqrt2.@var{fmt}}).
15763 The following multi-instruction functions are also available.
15764 In each case, @var{cond} can be any of the 16 floating-point conditions:
15765 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
15766 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq},
15767 @code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}.
15770 @item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b})
15771 @itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b})
15772 Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}},
15773 @code{bc1t}/@code{bc1f}).
15775 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s}
15776 or @code{cabs.@var{cond}.d} and return the result as a boolean value.
15781 if (__builtin_mips_cabs_eq_s (a, b))
15787 @item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15788 @itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15789 Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps},
15790 @code{bc1t}/@code{bc1f}).
15792 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps}
15793 and return either the upper or lower half of the result. For example:
15797 if (__builtin_mips_upper_cabs_eq_ps (a, b))
15798 upper_halves_are_equal ();
15800 upper_halves_are_unequal ();
15802 if (__builtin_mips_lower_cabs_eq_ps (a, b))
15803 lower_halves_are_equal ();
15805 lower_halves_are_unequal ();
15808 @item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15809 @itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15810 Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps},
15811 @code{movt.ps}/@code{movf.ps}).
15813 The @code{movt} functions return the value @var{x} computed by:
15816 cabs.@var{cond}.ps @var{cc},@var{a},@var{b}
15817 mov.ps @var{x},@var{c}
15818 movt.ps @var{x},@var{d},@var{cc}
15821 The @code{movf} functions are similar but use @code{movf.ps} instead
15824 @item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15825 @itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15826 @itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15827 @itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15828 Comparison of two paired-single values
15829 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
15830 @code{bc1any2t}/@code{bc1any2f}).
15832 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
15833 or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either
15834 result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}.
15839 if (__builtin_mips_any_c_eq_ps (a, b))
15844 if (__builtin_mips_all_c_eq_ps (a, b))
15850 @item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15851 @itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15852 @itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15853 @itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15854 Comparison of four paired-single values
15855 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
15856 @code{bc1any4t}/@code{bc1any4f}).
15858 These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps}
15859 to compare @var{a} with @var{b} and to compare @var{c} with @var{d}.
15860 The @code{any} forms return @code{true} if any of the four results are @code{true}
15861 and the @code{all} forms return @code{true} if all four results are @code{true}.
15866 if (__builtin_mips_any_c_eq_4s (a, b, c, d))
15871 if (__builtin_mips_all_c_eq_4s (a, b, c, d))
15878 @node MIPS SIMD Architecture (MSA) Support
15879 @subsection MIPS SIMD Architecture (MSA) Support
15882 * MIPS SIMD Architecture Built-in Functions::
15885 GCC provides intrinsics to access the SIMD instructions provided by the
15886 MSA MIPS SIMD Architecture. The interface is made available by including
15887 @code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}.
15888 For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic,
15891 MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and
15892 64-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point
15893 data elements. The following vectors typedefs are included in @code{msa.h}:
15895 @item @code{v16i8}, a vector of sixteen signed 8-bit integers;
15896 @item @code{v16u8}, a vector of sixteen unsigned 8-bit integers;
15897 @item @code{v8i16}, a vector of eight signed 16-bit integers;
15898 @item @code{v8u16}, a vector of eight unsigned 16-bit integers;
15899 @item @code{v4i32}, a vector of four signed 32-bit integers;
15900 @item @code{v4u32}, a vector of four unsigned 32-bit integers;
15901 @item @code{v2i64}, a vector of two signed 64-bit integers;
15902 @item @code{v2u64}, a vector of two unsigned 64-bit integers;
15903 @item @code{v4f32}, a vector of four 32-bit floats;
15904 @item @code{v2f64}, a vector of two 64-bit doubles.
15907 Instructions and corresponding built-ins may have additional restrictions and/or
15908 input/output values manipulated:
15910 @item @code{imm0_1}, an integer literal in range 0 to 1;
15911 @item @code{imm0_3}, an integer literal in range 0 to 3;
15912 @item @code{imm0_7}, an integer literal in range 0 to 7;
15913 @item @code{imm0_15}, an integer literal in range 0 to 15;
15914 @item @code{imm0_31}, an integer literal in range 0 to 31;
15915 @item @code{imm0_63}, an integer literal in range 0 to 63;
15916 @item @code{imm0_255}, an integer literal in range 0 to 255;
15917 @item @code{imm_n16_15}, an integer literal in range -16 to 15;
15918 @item @code{imm_n512_511}, an integer literal in range -512 to 511;
15919 @item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left
15920 shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022;
15921 @item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left
15922 shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044;
15923 @item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left
15924 shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088;
15925 @item @code{imm1_4}, an integer literal in range 1 to 4;
15926 @item @code{i32, i64, u32, u64, f32, f64}, defined as follows:
15932 #if __LONG_MAX__ == __LONG_LONG_MAX__
15935 typedef long long i64;
15938 typedef unsigned int u32;
15939 #if __LONG_MAX__ == __LONG_LONG_MAX__
15940 typedef unsigned long u64;
15942 typedef unsigned long long u64;
15945 typedef double f64;
15950 @node MIPS SIMD Architecture Built-in Functions
15951 @subsubsection MIPS SIMD Architecture Built-in Functions
15953 The intrinsics provided are listed below; each is named after the
15954 machine instruction.
15957 v16i8 __builtin_msa_add_a_b (v16i8, v16i8);
15958 v8i16 __builtin_msa_add_a_h (v8i16, v8i16);
15959 v4i32 __builtin_msa_add_a_w (v4i32, v4i32);
15960 v2i64 __builtin_msa_add_a_d (v2i64, v2i64);
15962 v16i8 __builtin_msa_adds_a_b (v16i8, v16i8);
15963 v8i16 __builtin_msa_adds_a_h (v8i16, v8i16);
15964 v4i32 __builtin_msa_adds_a_w (v4i32, v4i32);
15965 v2i64 __builtin_msa_adds_a_d (v2i64, v2i64);
15967 v16i8 __builtin_msa_adds_s_b (v16i8, v16i8);
15968 v8i16 __builtin_msa_adds_s_h (v8i16, v8i16);
15969 v4i32 __builtin_msa_adds_s_w (v4i32, v4i32);
15970 v2i64 __builtin_msa_adds_s_d (v2i64, v2i64);
15972 v16u8 __builtin_msa_adds_u_b (v16u8, v16u8);
15973 v8u16 __builtin_msa_adds_u_h (v8u16, v8u16);
15974 v4u32 __builtin_msa_adds_u_w (v4u32, v4u32);
15975 v2u64 __builtin_msa_adds_u_d (v2u64, v2u64);
15977 v16i8 __builtin_msa_addv_b (v16i8, v16i8);
15978 v8i16 __builtin_msa_addv_h (v8i16, v8i16);
15979 v4i32 __builtin_msa_addv_w (v4i32, v4i32);
15980 v2i64 __builtin_msa_addv_d (v2i64, v2i64);
15982 v16i8 __builtin_msa_addvi_b (v16i8, imm0_31);
15983 v8i16 __builtin_msa_addvi_h (v8i16, imm0_31);
15984 v4i32 __builtin_msa_addvi_w (v4i32, imm0_31);
15985 v2i64 __builtin_msa_addvi_d (v2i64, imm0_31);
15987 v16u8 __builtin_msa_and_v (v16u8, v16u8);
15989 v16u8 __builtin_msa_andi_b (v16u8, imm0_255);
15991 v16i8 __builtin_msa_asub_s_b (v16i8, v16i8);
15992 v8i16 __builtin_msa_asub_s_h (v8i16, v8i16);
15993 v4i32 __builtin_msa_asub_s_w (v4i32, v4i32);
15994 v2i64 __builtin_msa_asub_s_d (v2i64, v2i64);
15996 v16u8 __builtin_msa_asub_u_b (v16u8, v16u8);
15997 v8u16 __builtin_msa_asub_u_h (v8u16, v8u16);
15998 v4u32 __builtin_msa_asub_u_w (v4u32, v4u32);
15999 v2u64 __builtin_msa_asub_u_d (v2u64, v2u64);
16001 v16i8 __builtin_msa_ave_s_b (v16i8, v16i8);
16002 v8i16 __builtin_msa_ave_s_h (v8i16, v8i16);
16003 v4i32 __builtin_msa_ave_s_w (v4i32, v4i32);
16004 v2i64 __builtin_msa_ave_s_d (v2i64, v2i64);
16006 v16u8 __builtin_msa_ave_u_b (v16u8, v16u8);
16007 v8u16 __builtin_msa_ave_u_h (v8u16, v8u16);
16008 v4u32 __builtin_msa_ave_u_w (v4u32, v4u32);
16009 v2u64 __builtin_msa_ave_u_d (v2u64, v2u64);
16011 v16i8 __builtin_msa_aver_s_b (v16i8, v16i8);
16012 v8i16 __builtin_msa_aver_s_h (v8i16, v8i16);
16013 v4i32 __builtin_msa_aver_s_w (v4i32, v4i32);
16014 v2i64 __builtin_msa_aver_s_d (v2i64, v2i64);
16016 v16u8 __builtin_msa_aver_u_b (v16u8, v16u8);
16017 v8u16 __builtin_msa_aver_u_h (v8u16, v8u16);
16018 v4u32 __builtin_msa_aver_u_w (v4u32, v4u32);
16019 v2u64 __builtin_msa_aver_u_d (v2u64, v2u64);
16021 v16u8 __builtin_msa_bclr_b (v16u8, v16u8);
16022 v8u16 __builtin_msa_bclr_h (v8u16, v8u16);
16023 v4u32 __builtin_msa_bclr_w (v4u32, v4u32);
16024 v2u64 __builtin_msa_bclr_d (v2u64, v2u64);
16026 v16u8 __builtin_msa_bclri_b (v16u8, imm0_7);
16027 v8u16 __builtin_msa_bclri_h (v8u16, imm0_15);
16028 v4u32 __builtin_msa_bclri_w (v4u32, imm0_31);
16029 v2u64 __builtin_msa_bclri_d (v2u64, imm0_63);
16031 v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8);
16032 v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16);
16033 v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32);
16034 v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64);
16036 v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7);
16037 v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15);
16038 v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31);
16039 v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63);
16041 v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8);
16042 v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16);
16043 v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32);
16044 v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64);
16046 v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7);
16047 v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15);
16048 v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31);
16049 v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63);
16051 v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8);
16053 v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255);
16055 v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8);
16057 v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255);
16059 v16u8 __builtin_msa_bneg_b (v16u8, v16u8);
16060 v8u16 __builtin_msa_bneg_h (v8u16, v8u16);
16061 v4u32 __builtin_msa_bneg_w (v4u32, v4u32);
16062 v2u64 __builtin_msa_bneg_d (v2u64, v2u64);
16064 v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7);
16065 v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15);
16066 v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31);
16067 v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63);
16069 i32 __builtin_msa_bnz_b (v16u8);
16070 i32 __builtin_msa_bnz_h (v8u16);
16071 i32 __builtin_msa_bnz_w (v4u32);
16072 i32 __builtin_msa_bnz_d (v2u64);
16074 i32 __builtin_msa_bnz_v (v16u8);
16076 v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8);
16078 v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255);
16080 v16u8 __builtin_msa_bset_b (v16u8, v16u8);
16081 v8u16 __builtin_msa_bset_h (v8u16, v8u16);
16082 v4u32 __builtin_msa_bset_w (v4u32, v4u32);
16083 v2u64 __builtin_msa_bset_d (v2u64, v2u64);
16085 v16u8 __builtin_msa_bseti_b (v16u8, imm0_7);
16086 v8u16 __builtin_msa_bseti_h (v8u16, imm0_15);
16087 v4u32 __builtin_msa_bseti_w (v4u32, imm0_31);
16088 v2u64 __builtin_msa_bseti_d (v2u64, imm0_63);
16090 i32 __builtin_msa_bz_b (v16u8);
16091 i32 __builtin_msa_bz_h (v8u16);
16092 i32 __builtin_msa_bz_w (v4u32);
16093 i32 __builtin_msa_bz_d (v2u64);
16095 i32 __builtin_msa_bz_v (v16u8);
16097 v16i8 __builtin_msa_ceq_b (v16i8, v16i8);
16098 v8i16 __builtin_msa_ceq_h (v8i16, v8i16);
16099 v4i32 __builtin_msa_ceq_w (v4i32, v4i32);
16100 v2i64 __builtin_msa_ceq_d (v2i64, v2i64);
16102 v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15);
16103 v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15);
16104 v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15);
16105 v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15);
16107 i32 __builtin_msa_cfcmsa (imm0_31);
16109 v16i8 __builtin_msa_cle_s_b (v16i8, v16i8);
16110 v8i16 __builtin_msa_cle_s_h (v8i16, v8i16);
16111 v4i32 __builtin_msa_cle_s_w (v4i32, v4i32);
16112 v2i64 __builtin_msa_cle_s_d (v2i64, v2i64);
16114 v16i8 __builtin_msa_cle_u_b (v16u8, v16u8);
16115 v8i16 __builtin_msa_cle_u_h (v8u16, v8u16);
16116 v4i32 __builtin_msa_cle_u_w (v4u32, v4u32);
16117 v2i64 __builtin_msa_cle_u_d (v2u64, v2u64);
16119 v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15);
16120 v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15);
16121 v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15);
16122 v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15);
16124 v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31);
16125 v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31);
16126 v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31);
16127 v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31);
16129 v16i8 __builtin_msa_clt_s_b (v16i8, v16i8);
16130 v8i16 __builtin_msa_clt_s_h (v8i16, v8i16);
16131 v4i32 __builtin_msa_clt_s_w (v4i32, v4i32);
16132 v2i64 __builtin_msa_clt_s_d (v2i64, v2i64);
16134 v16i8 __builtin_msa_clt_u_b (v16u8, v16u8);
16135 v8i16 __builtin_msa_clt_u_h (v8u16, v8u16);
16136 v4i32 __builtin_msa_clt_u_w (v4u32, v4u32);
16137 v2i64 __builtin_msa_clt_u_d (v2u64, v2u64);
16139 v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15);
16140 v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15);
16141 v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15);
16142 v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15);
16144 v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31);
16145 v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31);
16146 v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31);
16147 v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31);
16149 i32 __builtin_msa_copy_s_b (v16i8, imm0_15);
16150 i32 __builtin_msa_copy_s_h (v8i16, imm0_7);
16151 i32 __builtin_msa_copy_s_w (v4i32, imm0_3);
16152 i64 __builtin_msa_copy_s_d (v2i64, imm0_1);
16154 u32 __builtin_msa_copy_u_b (v16i8, imm0_15);
16155 u32 __builtin_msa_copy_u_h (v8i16, imm0_7);
16156 u32 __builtin_msa_copy_u_w (v4i32, imm0_3);
16157 u64 __builtin_msa_copy_u_d (v2i64, imm0_1);
16159 void __builtin_msa_ctcmsa (imm0_31, i32);
16161 v16i8 __builtin_msa_div_s_b (v16i8, v16i8);
16162 v8i16 __builtin_msa_div_s_h (v8i16, v8i16);
16163 v4i32 __builtin_msa_div_s_w (v4i32, v4i32);
16164 v2i64 __builtin_msa_div_s_d (v2i64, v2i64);
16166 v16u8 __builtin_msa_div_u_b (v16u8, v16u8);
16167 v8u16 __builtin_msa_div_u_h (v8u16, v8u16);
16168 v4u32 __builtin_msa_div_u_w (v4u32, v4u32);
16169 v2u64 __builtin_msa_div_u_d (v2u64, v2u64);
16171 v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8);
16172 v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16);
16173 v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32);
16175 v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8);
16176 v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16);
16177 v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32);
16179 v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8);
16180 v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16);
16181 v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32);
16183 v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8);
16184 v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16);
16185 v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32);
16187 v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8);
16188 v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16);
16189 v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32);
16191 v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8);
16192 v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16);
16193 v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32);
16195 v4f32 __builtin_msa_fadd_w (v4f32, v4f32);
16196 v2f64 __builtin_msa_fadd_d (v2f64, v2f64);
16198 v4i32 __builtin_msa_fcaf_w (v4f32, v4f32);
16199 v2i64 __builtin_msa_fcaf_d (v2f64, v2f64);
16201 v4i32 __builtin_msa_fceq_w (v4f32, v4f32);
16202 v2i64 __builtin_msa_fceq_d (v2f64, v2f64);
16204 v4i32 __builtin_msa_fclass_w (v4f32);
16205 v2i64 __builtin_msa_fclass_d (v2f64);
16207 v4i32 __builtin_msa_fcle_w (v4f32, v4f32);
16208 v2i64 __builtin_msa_fcle_d (v2f64, v2f64);
16210 v4i32 __builtin_msa_fclt_w (v4f32, v4f32);
16211 v2i64 __builtin_msa_fclt_d (v2f64, v2f64);
16213 v4i32 __builtin_msa_fcne_w (v4f32, v4f32);
16214 v2i64 __builtin_msa_fcne_d (v2f64, v2f64);
16216 v4i32 __builtin_msa_fcor_w (v4f32, v4f32);
16217 v2i64 __builtin_msa_fcor_d (v2f64, v2f64);
16219 v4i32 __builtin_msa_fcueq_w (v4f32, v4f32);
16220 v2i64 __builtin_msa_fcueq_d (v2f64, v2f64);
16222 v4i32 __builtin_msa_fcule_w (v4f32, v4f32);
16223 v2i64 __builtin_msa_fcule_d (v2f64, v2f64);
16225 v4i32 __builtin_msa_fcult_w (v4f32, v4f32);
16226 v2i64 __builtin_msa_fcult_d (v2f64, v2f64);
16228 v4i32 __builtin_msa_fcun_w (v4f32, v4f32);
16229 v2i64 __builtin_msa_fcun_d (v2f64, v2f64);
16231 v4i32 __builtin_msa_fcune_w (v4f32, v4f32);
16232 v2i64 __builtin_msa_fcune_d (v2f64, v2f64);
16234 v4f32 __builtin_msa_fdiv_w (v4f32, v4f32);
16235 v2f64 __builtin_msa_fdiv_d (v2f64, v2f64);
16237 v8i16 __builtin_msa_fexdo_h (v4f32, v4f32);
16238 v4f32 __builtin_msa_fexdo_w (v2f64, v2f64);
16240 v4f32 __builtin_msa_fexp2_w (v4f32, v4i32);
16241 v2f64 __builtin_msa_fexp2_d (v2f64, v2i64);
16243 v4f32 __builtin_msa_fexupl_w (v8i16);
16244 v2f64 __builtin_msa_fexupl_d (v4f32);
16246 v4f32 __builtin_msa_fexupr_w (v8i16);
16247 v2f64 __builtin_msa_fexupr_d (v4f32);
16249 v4f32 __builtin_msa_ffint_s_w (v4i32);
16250 v2f64 __builtin_msa_ffint_s_d (v2i64);
16252 v4f32 __builtin_msa_ffint_u_w (v4u32);
16253 v2f64 __builtin_msa_ffint_u_d (v2u64);
16255 v4f32 __builtin_msa_ffql_w (v8i16);
16256 v2f64 __builtin_msa_ffql_d (v4i32);
16258 v4f32 __builtin_msa_ffqr_w (v8i16);
16259 v2f64 __builtin_msa_ffqr_d (v4i32);
16261 v16i8 __builtin_msa_fill_b (i32);
16262 v8i16 __builtin_msa_fill_h (i32);
16263 v4i32 __builtin_msa_fill_w (i32);
16264 v2i64 __builtin_msa_fill_d (i64);
16266 v4f32 __builtin_msa_flog2_w (v4f32);
16267 v2f64 __builtin_msa_flog2_d (v2f64);
16269 v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32);
16270 v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64);
16272 v4f32 __builtin_msa_fmax_w (v4f32, v4f32);
16273 v2f64 __builtin_msa_fmax_d (v2f64, v2f64);
16275 v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32);
16276 v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64);
16278 v4f32 __builtin_msa_fmin_w (v4f32, v4f32);
16279 v2f64 __builtin_msa_fmin_d (v2f64, v2f64);
16281 v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32);
16282 v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64);
16284 v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32);
16285 v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64);
16287 v4f32 __builtin_msa_fmul_w (v4f32, v4f32);
16288 v2f64 __builtin_msa_fmul_d (v2f64, v2f64);
16290 v4f32 __builtin_msa_frint_w (v4f32);
16291 v2f64 __builtin_msa_frint_d (v2f64);
16293 v4f32 __builtin_msa_frcp_w (v4f32);
16294 v2f64 __builtin_msa_frcp_d (v2f64);
16296 v4f32 __builtin_msa_frsqrt_w (v4f32);
16297 v2f64 __builtin_msa_frsqrt_d (v2f64);
16299 v4i32 __builtin_msa_fsaf_w (v4f32, v4f32);
16300 v2i64 __builtin_msa_fsaf_d (v2f64, v2f64);
16302 v4i32 __builtin_msa_fseq_w (v4f32, v4f32);
16303 v2i64 __builtin_msa_fseq_d (v2f64, v2f64);
16305 v4i32 __builtin_msa_fsle_w (v4f32, v4f32);
16306 v2i64 __builtin_msa_fsle_d (v2f64, v2f64);
16308 v4i32 __builtin_msa_fslt_w (v4f32, v4f32);
16309 v2i64 __builtin_msa_fslt_d (v2f64, v2f64);
16311 v4i32 __builtin_msa_fsne_w (v4f32, v4f32);
16312 v2i64 __builtin_msa_fsne_d (v2f64, v2f64);
16314 v4i32 __builtin_msa_fsor_w (v4f32, v4f32);
16315 v2i64 __builtin_msa_fsor_d (v2f64, v2f64);
16317 v4f32 __builtin_msa_fsqrt_w (v4f32);
16318 v2f64 __builtin_msa_fsqrt_d (v2f64);
16320 v4f32 __builtin_msa_fsub_w (v4f32, v4f32);
16321 v2f64 __builtin_msa_fsub_d (v2f64, v2f64);
16323 v4i32 __builtin_msa_fsueq_w (v4f32, v4f32);
16324 v2i64 __builtin_msa_fsueq_d (v2f64, v2f64);
16326 v4i32 __builtin_msa_fsule_w (v4f32, v4f32);
16327 v2i64 __builtin_msa_fsule_d (v2f64, v2f64);
16329 v4i32 __builtin_msa_fsult_w (v4f32, v4f32);
16330 v2i64 __builtin_msa_fsult_d (v2f64, v2f64);
16332 v4i32 __builtin_msa_fsun_w (v4f32, v4f32);
16333 v2i64 __builtin_msa_fsun_d (v2f64, v2f64);
16335 v4i32 __builtin_msa_fsune_w (v4f32, v4f32);
16336 v2i64 __builtin_msa_fsune_d (v2f64, v2f64);
16338 v4i32 __builtin_msa_ftint_s_w (v4f32);
16339 v2i64 __builtin_msa_ftint_s_d (v2f64);
16341 v4u32 __builtin_msa_ftint_u_w (v4f32);
16342 v2u64 __builtin_msa_ftint_u_d (v2f64);
16344 v8i16 __builtin_msa_ftq_h (v4f32, v4f32);
16345 v4i32 __builtin_msa_ftq_w (v2f64, v2f64);
16347 v4i32 __builtin_msa_ftrunc_s_w (v4f32);
16348 v2i64 __builtin_msa_ftrunc_s_d (v2f64);
16350 v4u32 __builtin_msa_ftrunc_u_w (v4f32);
16351 v2u64 __builtin_msa_ftrunc_u_d (v2f64);
16353 v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8);
16354 v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16);
16355 v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32);
16357 v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8);
16358 v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16);
16359 v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32);
16361 v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8);
16362 v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16);
16363 v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32);
16365 v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8);
16366 v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16);
16367 v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32);
16369 v16i8 __builtin_msa_ilvev_b (v16i8, v16i8);
16370 v8i16 __builtin_msa_ilvev_h (v8i16, v8i16);
16371 v4i32 __builtin_msa_ilvev_w (v4i32, v4i32);
16372 v2i64 __builtin_msa_ilvev_d (v2i64, v2i64);
16374 v16i8 __builtin_msa_ilvl_b (v16i8, v16i8);
16375 v8i16 __builtin_msa_ilvl_h (v8i16, v8i16);
16376 v4i32 __builtin_msa_ilvl_w (v4i32, v4i32);
16377 v2i64 __builtin_msa_ilvl_d (v2i64, v2i64);
16379 v16i8 __builtin_msa_ilvod_b (v16i8, v16i8);
16380 v8i16 __builtin_msa_ilvod_h (v8i16, v8i16);
16381 v4i32 __builtin_msa_ilvod_w (v4i32, v4i32);
16382 v2i64 __builtin_msa_ilvod_d (v2i64, v2i64);
16384 v16i8 __builtin_msa_ilvr_b (v16i8, v16i8);
16385 v8i16 __builtin_msa_ilvr_h (v8i16, v8i16);
16386 v4i32 __builtin_msa_ilvr_w (v4i32, v4i32);
16387 v2i64 __builtin_msa_ilvr_d (v2i64, v2i64);
16389 v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32);
16390 v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32);
16391 v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32);
16392 v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64);
16394 v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8);
16395 v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16);
16396 v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32);
16397 v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64);
16399 v16i8 __builtin_msa_ld_b (const void *, imm_n512_511);
16400 v8i16 __builtin_msa_ld_h (const void *, imm_n1024_1022);
16401 v4i32 __builtin_msa_ld_w (const void *, imm_n2048_2044);
16402 v2i64 __builtin_msa_ld_d (const void *, imm_n4096_4088);
16404 v16i8 __builtin_msa_ldi_b (imm_n512_511);
16405 v8i16 __builtin_msa_ldi_h (imm_n512_511);
16406 v4i32 __builtin_msa_ldi_w (imm_n512_511);
16407 v2i64 __builtin_msa_ldi_d (imm_n512_511);
16409 v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16);
16410 v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32);
16412 v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16);
16413 v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32);
16415 v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8);
16416 v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16);
16417 v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32);
16418 v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64);
16420 v16i8 __builtin_msa_max_a_b (v16i8, v16i8);
16421 v8i16 __builtin_msa_max_a_h (v8i16, v8i16);
16422 v4i32 __builtin_msa_max_a_w (v4i32, v4i32);
16423 v2i64 __builtin_msa_max_a_d (v2i64, v2i64);
16425 v16i8 __builtin_msa_max_s_b (v16i8, v16i8);
16426 v8i16 __builtin_msa_max_s_h (v8i16, v8i16);
16427 v4i32 __builtin_msa_max_s_w (v4i32, v4i32);
16428 v2i64 __builtin_msa_max_s_d (v2i64, v2i64);
16430 v16u8 __builtin_msa_max_u_b (v16u8, v16u8);
16431 v8u16 __builtin_msa_max_u_h (v8u16, v8u16);
16432 v4u32 __builtin_msa_max_u_w (v4u32, v4u32);
16433 v2u64 __builtin_msa_max_u_d (v2u64, v2u64);
16435 v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15);
16436 v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15);
16437 v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15);
16438 v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15);
16440 v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31);
16441 v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31);
16442 v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31);
16443 v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31);
16445 v16i8 __builtin_msa_min_a_b (v16i8, v16i8);
16446 v8i16 __builtin_msa_min_a_h (v8i16, v8i16);
16447 v4i32 __builtin_msa_min_a_w (v4i32, v4i32);
16448 v2i64 __builtin_msa_min_a_d (v2i64, v2i64);
16450 v16i8 __builtin_msa_min_s_b (v16i8, v16i8);
16451 v8i16 __builtin_msa_min_s_h (v8i16, v8i16);
16452 v4i32 __builtin_msa_min_s_w (v4i32, v4i32);
16453 v2i64 __builtin_msa_min_s_d (v2i64, v2i64);
16455 v16u8 __builtin_msa_min_u_b (v16u8, v16u8);
16456 v8u16 __builtin_msa_min_u_h (v8u16, v8u16);
16457 v4u32 __builtin_msa_min_u_w (v4u32, v4u32);
16458 v2u64 __builtin_msa_min_u_d (v2u64, v2u64);
16460 v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15);
16461 v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15);
16462 v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15);
16463 v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15);
16465 v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31);
16466 v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31);
16467 v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31);
16468 v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31);
16470 v16i8 __builtin_msa_mod_s_b (v16i8, v16i8);
16471 v8i16 __builtin_msa_mod_s_h (v8i16, v8i16);
16472 v4i32 __builtin_msa_mod_s_w (v4i32, v4i32);
16473 v2i64 __builtin_msa_mod_s_d (v2i64, v2i64);
16475 v16u8 __builtin_msa_mod_u_b (v16u8, v16u8);
16476 v8u16 __builtin_msa_mod_u_h (v8u16, v8u16);
16477 v4u32 __builtin_msa_mod_u_w (v4u32, v4u32);
16478 v2u64 __builtin_msa_mod_u_d (v2u64, v2u64);
16480 v16i8 __builtin_msa_move_v (v16i8);
16482 v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16);
16483 v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32);
16485 v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16);
16486 v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32);
16488 v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8);
16489 v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16);
16490 v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32);
16491 v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64);
16493 v8i16 __builtin_msa_mul_q_h (v8i16, v8i16);
16494 v4i32 __builtin_msa_mul_q_w (v4i32, v4i32);
16496 v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16);
16497 v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32);
16499 v16i8 __builtin_msa_mulv_b (v16i8, v16i8);
16500 v8i16 __builtin_msa_mulv_h (v8i16, v8i16);
16501 v4i32 __builtin_msa_mulv_w (v4i32, v4i32);
16502 v2i64 __builtin_msa_mulv_d (v2i64, v2i64);
16504 v16i8 __builtin_msa_nloc_b (v16i8);
16505 v8i16 __builtin_msa_nloc_h (v8i16);
16506 v4i32 __builtin_msa_nloc_w (v4i32);
16507 v2i64 __builtin_msa_nloc_d (v2i64);
16509 v16i8 __builtin_msa_nlzc_b (v16i8);
16510 v8i16 __builtin_msa_nlzc_h (v8i16);
16511 v4i32 __builtin_msa_nlzc_w (v4i32);
16512 v2i64 __builtin_msa_nlzc_d (v2i64);
16514 v16u8 __builtin_msa_nor_v (v16u8, v16u8);
16516 v16u8 __builtin_msa_nori_b (v16u8, imm0_255);
16518 v16u8 __builtin_msa_or_v (v16u8, v16u8);
16520 v16u8 __builtin_msa_ori_b (v16u8, imm0_255);
16522 v16i8 __builtin_msa_pckev_b (v16i8, v16i8);
16523 v8i16 __builtin_msa_pckev_h (v8i16, v8i16);
16524 v4i32 __builtin_msa_pckev_w (v4i32, v4i32);
16525 v2i64 __builtin_msa_pckev_d (v2i64, v2i64);
16527 v16i8 __builtin_msa_pckod_b (v16i8, v16i8);
16528 v8i16 __builtin_msa_pckod_h (v8i16, v8i16);
16529 v4i32 __builtin_msa_pckod_w (v4i32, v4i32);
16530 v2i64 __builtin_msa_pckod_d (v2i64, v2i64);
16532 v16i8 __builtin_msa_pcnt_b (v16i8);
16533 v8i16 __builtin_msa_pcnt_h (v8i16);
16534 v4i32 __builtin_msa_pcnt_w (v4i32);
16535 v2i64 __builtin_msa_pcnt_d (v2i64);
16537 v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7);
16538 v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15);
16539 v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31);
16540 v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63);
16542 v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7);
16543 v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15);
16544 v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31);
16545 v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63);
16547 v16i8 __builtin_msa_shf_b (v16i8, imm0_255);
16548 v8i16 __builtin_msa_shf_h (v8i16, imm0_255);
16549 v4i32 __builtin_msa_shf_w (v4i32, imm0_255);
16551 v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32);
16552 v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32);
16553 v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32);
16554 v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32);
16556 v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15);
16557 v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7);
16558 v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3);
16559 v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1);
16561 v16i8 __builtin_msa_sll_b (v16i8, v16i8);
16562 v8i16 __builtin_msa_sll_h (v8i16, v8i16);
16563 v4i32 __builtin_msa_sll_w (v4i32, v4i32);
16564 v2i64 __builtin_msa_sll_d (v2i64, v2i64);
16566 v16i8 __builtin_msa_slli_b (v16i8, imm0_7);
16567 v8i16 __builtin_msa_slli_h (v8i16, imm0_15);
16568 v4i32 __builtin_msa_slli_w (v4i32, imm0_31);
16569 v2i64 __builtin_msa_slli_d (v2i64, imm0_63);
16571 v16i8 __builtin_msa_splat_b (v16i8, i32);
16572 v8i16 __builtin_msa_splat_h (v8i16, i32);
16573 v4i32 __builtin_msa_splat_w (v4i32, i32);
16574 v2i64 __builtin_msa_splat_d (v2i64, i32);
16576 v16i8 __builtin_msa_splati_b (v16i8, imm0_15);
16577 v8i16 __builtin_msa_splati_h (v8i16, imm0_7);
16578 v4i32 __builtin_msa_splati_w (v4i32, imm0_3);
16579 v2i64 __builtin_msa_splati_d (v2i64, imm0_1);
16581 v16i8 __builtin_msa_sra_b (v16i8, v16i8);
16582 v8i16 __builtin_msa_sra_h (v8i16, v8i16);
16583 v4i32 __builtin_msa_sra_w (v4i32, v4i32);
16584 v2i64 __builtin_msa_sra_d (v2i64, v2i64);
16586 v16i8 __builtin_msa_srai_b (v16i8, imm0_7);
16587 v8i16 __builtin_msa_srai_h (v8i16, imm0_15);
16588 v4i32 __builtin_msa_srai_w (v4i32, imm0_31);
16589 v2i64 __builtin_msa_srai_d (v2i64, imm0_63);
16591 v16i8 __builtin_msa_srar_b (v16i8, v16i8);
16592 v8i16 __builtin_msa_srar_h (v8i16, v8i16);
16593 v4i32 __builtin_msa_srar_w (v4i32, v4i32);
16594 v2i64 __builtin_msa_srar_d (v2i64, v2i64);
16596 v16i8 __builtin_msa_srari_b (v16i8, imm0_7);
16597 v8i16 __builtin_msa_srari_h (v8i16, imm0_15);
16598 v4i32 __builtin_msa_srari_w (v4i32, imm0_31);
16599 v2i64 __builtin_msa_srari_d (v2i64, imm0_63);
16601 v16i8 __builtin_msa_srl_b (v16i8, v16i8);
16602 v8i16 __builtin_msa_srl_h (v8i16, v8i16);
16603 v4i32 __builtin_msa_srl_w (v4i32, v4i32);
16604 v2i64 __builtin_msa_srl_d (v2i64, v2i64);
16606 v16i8 __builtin_msa_srli_b (v16i8, imm0_7);
16607 v8i16 __builtin_msa_srli_h (v8i16, imm0_15);
16608 v4i32 __builtin_msa_srli_w (v4i32, imm0_31);
16609 v2i64 __builtin_msa_srli_d (v2i64, imm0_63);
16611 v16i8 __builtin_msa_srlr_b (v16i8, v16i8);
16612 v8i16 __builtin_msa_srlr_h (v8i16, v8i16);
16613 v4i32 __builtin_msa_srlr_w (v4i32, v4i32);
16614 v2i64 __builtin_msa_srlr_d (v2i64, v2i64);
16616 v16i8 __builtin_msa_srlri_b (v16i8, imm0_7);
16617 v8i16 __builtin_msa_srlri_h (v8i16, imm0_15);
16618 v4i32 __builtin_msa_srlri_w (v4i32, imm0_31);
16619 v2i64 __builtin_msa_srlri_d (v2i64, imm0_63);
16621 void __builtin_msa_st_b (v16i8, void *, imm_n512_511);
16622 void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022);
16623 void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044);
16624 void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088);
16626 v16i8 __builtin_msa_subs_s_b (v16i8, v16i8);
16627 v8i16 __builtin_msa_subs_s_h (v8i16, v8i16);
16628 v4i32 __builtin_msa_subs_s_w (v4i32, v4i32);
16629 v2i64 __builtin_msa_subs_s_d (v2i64, v2i64);
16631 v16u8 __builtin_msa_subs_u_b (v16u8, v16u8);
16632 v8u16 __builtin_msa_subs_u_h (v8u16, v8u16);
16633 v4u32 __builtin_msa_subs_u_w (v4u32, v4u32);
16634 v2u64 __builtin_msa_subs_u_d (v2u64, v2u64);
16636 v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8);
16637 v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16);
16638 v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32);
16639 v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64);
16641 v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8);
16642 v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16);
16643 v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32);
16644 v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64);
16646 v16i8 __builtin_msa_subv_b (v16i8, v16i8);
16647 v8i16 __builtin_msa_subv_h (v8i16, v8i16);
16648 v4i32 __builtin_msa_subv_w (v4i32, v4i32);
16649 v2i64 __builtin_msa_subv_d (v2i64, v2i64);
16651 v16i8 __builtin_msa_subvi_b (v16i8, imm0_31);
16652 v8i16 __builtin_msa_subvi_h (v8i16, imm0_31);
16653 v4i32 __builtin_msa_subvi_w (v4i32, imm0_31);
16654 v2i64 __builtin_msa_subvi_d (v2i64, imm0_31);
16656 v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8);
16657 v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16);
16658 v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32);
16659 v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64);
16661 v16u8 __builtin_msa_xor_v (v16u8, v16u8);
16663 v16u8 __builtin_msa_xori_b (v16u8, imm0_255);
16666 @node Other MIPS Built-in Functions
16667 @subsection Other MIPS Built-in Functions
16669 GCC provides other MIPS-specific built-in functions:
16672 @item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr})
16673 Insert a @samp{cache} instruction with operands @var{op} and @var{addr}.
16674 GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE}
16675 when this function is available.
16677 @item unsigned int __builtin_mips_get_fcsr (void)
16678 @itemx void __builtin_mips_set_fcsr (unsigned int @var{value})
16679 Get and set the contents of the floating-point control and status register
16680 (FPU control register 31). These functions are only available in hard-float
16681 code but can be called in both MIPS16 and non-MIPS16 contexts.
16683 @code{__builtin_mips_set_fcsr} can be used to change any bit of the
16684 register except the condition codes, which GCC assumes are preserved.
16687 @node MSP430 Built-in Functions
16688 @subsection MSP430 Built-in Functions
16690 GCC provides a couple of special builtin functions to aid in the
16691 writing of interrupt handlers in C.
16694 @item __bic_SR_register_on_exit (int @var{mask})
16695 This clears the indicated bits in the saved copy of the status register
16696 currently residing on the stack. This only works inside interrupt
16697 handlers and the changes to the status register will only take affect
16698 once the handler returns.
16700 @item __bis_SR_register_on_exit (int @var{mask})
16701 This sets the indicated bits in the saved copy of the status register
16702 currently residing on the stack. This only works inside interrupt
16703 handlers and the changes to the status register will only take affect
16704 once the handler returns.
16706 @item __delay_cycles (long long @var{cycles})
16707 This inserts an instruction sequence that takes exactly @var{cycles}
16708 cycles (between 0 and about 17E9) to complete. The inserted sequence
16709 may use jumps, loops, or no-ops, and does not interfere with any other
16710 instructions. Note that @var{cycles} must be a compile-time constant
16711 integer - that is, you must pass a number, not a variable that may be
16712 optimized to a constant later. The number of cycles delayed by this
16716 @node NDS32 Built-in Functions
16717 @subsection NDS32 Built-in Functions
16719 These built-in functions are available for the NDS32 target:
16721 @deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr})
16722 Insert an ISYNC instruction into the instruction stream where
16723 @var{addr} is an instruction address for serialization.
16726 @deftypefn {Built-in Function} void __builtin_nds32_isb (void)
16727 Insert an ISB instruction into the instruction stream.
16730 @deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr})
16731 Return the content of a system register which is mapped by @var{sr}.
16734 @deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr})
16735 Return the content of a user space register which is mapped by @var{usr}.
16738 @deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr})
16739 Move the @var{value} to a system register which is mapped by @var{sr}.
16742 @deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr})
16743 Move the @var{value} to a user space register which is mapped by @var{usr}.
16746 @deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void)
16747 Enable global interrupt.
16750 @deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void)
16751 Disable global interrupt.
16754 @node picoChip Built-in Functions
16755 @subsection picoChip Built-in Functions
16757 GCC provides an interface to selected machine instructions from the
16758 picoChip instruction set.
16761 @item int __builtin_sbc (int @var{value})
16762 Sign bit count. Return the number of consecutive bits in @var{value}
16763 that have the same value as the sign bit. The result is the number of
16764 leading sign bits minus one, giving the number of redundant sign bits in
16767 @item int __builtin_byteswap (int @var{value})
16768 Byte swap. Return the result of swapping the upper and lower bytes of
16771 @item int __builtin_brev (int @var{value})
16772 Bit reversal. Return the result of reversing the bits in
16773 @var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1,
16776 @item int __builtin_adds (int @var{x}, int @var{y})
16777 Saturating addition. Return the result of adding @var{x} and @var{y},
16778 storing the value 32767 if the result overflows.
16780 @item int __builtin_subs (int @var{x}, int @var{y})
16781 Saturating subtraction. Return the result of subtracting @var{y} from
16782 @var{x}, storing the value @minus{}32768 if the result overflows.
16784 @item void __builtin_halt (void)
16785 Halt. The processor stops execution. This built-in is useful for
16786 implementing assertions.
16790 @node Basic PowerPC Built-in Functions
16791 @subsection Basic PowerPC Built-in Functions
16794 * Basic PowerPC Built-in Functions Available on all Configurations::
16795 * Basic PowerPC Built-in Functions Available on ISA 2.05::
16796 * Basic PowerPC Built-in Functions Available on ISA 2.06::
16797 * Basic PowerPC Built-in Functions Available on ISA 2.07::
16798 * Basic PowerPC Built-in Functions Available on ISA 3.0::
16801 This section describes PowerPC built-in functions that do not require
16802 the inclusion of any special header files to declare prototypes or
16803 provide macro definitions. The sections that follow describe
16804 additional PowerPC built-in functions.
16806 @node Basic PowerPC Built-in Functions Available on all Configurations
16807 @subsubsection Basic PowerPC Built-in Functions Available on all Configurations
16809 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
16810 This function is a @code{nop} on the PowerPC platform and is included solely
16811 to maintain API compatibility with the x86 builtins.
16814 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
16815 This function returns a value of @code{1} if the run-time CPU is of type
16816 @var{cpuname} and returns @code{0} otherwise
16818 The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer
16819 which exports the hardware capability bits. GCC defines the macro
16820 @code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports}
16821 built-in function is fully supported.
16823 If GCC was configured to use a GLIBC before 2.23, the built-in
16824 function @code{__builtin_cpu_is} always returns a 0 and the compiler
16827 The following CPU names can be detected:
16831 IBM POWER9 Server CPU.
16833 IBM POWER8 Server CPU.
16835 IBM POWER7 Server CPU.
16837 IBM POWER6 Server CPU (RAW mode).
16839 IBM POWER6 Server CPU (Architected mode).
16841 IBM POWER5+ Server CPU.
16843 IBM POWER5 Server CPU.
16845 IBM 970 Server CPU (ie, Apple G5).
16847 IBM POWER4 Server CPU.
16849 IBM A2 64-bit Embedded CPU
16851 IBM PowerPC 476FP 32-bit Embedded CPU.
16853 IBM PowerPC 464 32-bit Embedded CPU.
16855 PowerPC 440 32-bit Embedded CPU.
16857 PowerPC 405 32-bit Embedded CPU.
16859 IBM PowerPC Cell Broadband Engine Architecture CPU.
16862 Here is an example:
16864 #ifdef __BUILTIN_CPU_SUPPORTS__
16865 if (__builtin_cpu_is ("power8"))
16867 do_power8 (); // POWER8 specific implementation.
16872 do_generic (); // Generic implementation.
16877 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
16878 This function returns a value of @code{1} if the run-time CPU supports the HWCAP
16879 feature @var{feature} and returns @code{0} otherwise.
16881 The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or
16882 newer which exports the hardware capability bits. GCC defines the
16883 macro @code{__BUILTIN_CPU_SUPPORTS__} if the
16884 @code{__builtin_cpu_supports} built-in function is fully supported.
16886 If GCC was configured to use a GLIBC before 2.23, the built-in
16887 function @code{__builtin_cpu_suports} always returns a 0 and the
16888 compiler issues a warning.
16890 The following features can be
16895 4xx CPU has a Multiply Accumulator.
16897 CPU has a SIMD/Vector Unit.
16899 CPU supports ISA 2.05 (eg, POWER6)
16901 CPU supports ISA 2.06 (eg, POWER7)
16903 CPU supports ISA 2.07 (eg, POWER8)
16905 CPU supports ISA 3.0 (eg, POWER9)
16907 CPU supports the set of compatible performance monitoring events.
16909 CPU supports the Embedded ISA category.
16911 CPU has a CELL broadband engine.
16913 CPU supports the @code{darn} (deliver a random number) instruction.
16915 CPU has a decimal floating point unit.
16917 CPU supports the data stream control register.
16919 CPU supports event base branching.
16921 CPU has a SPE double precision floating point unit.
16923 CPU has a SPE single precision floating point unit.
16925 CPU has a floating point unit.
16927 CPU has hardware transaction memory instructions.
16929 Kernel aborts hardware transactions when a syscall is made.
16930 @item htm-no-suspend
16931 CPU supports hardware transaction memory but does not support the
16932 @code{tsuspend.} instruction.
16934 CPU supports icache snooping capabilities.
16936 CPU supports 128-bit IEEE binary floating point instructions.
16938 CPU supports the integer select instruction.
16940 CPU has a memory management unit.
16942 CPU does not have a timebase (eg, 601 and 403gx).
16944 CPU supports the PA Semi 6T CORE ISA.
16946 CPU supports ISA 2.00 (eg, POWER4)
16948 CPU supports ISA 2.02 (eg, POWER5)
16950 CPU supports ISA 2.03 (eg, POWER5+)
16952 CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr.
16954 CPU supports 32-bit mode execution.
16956 CPU supports the old POWER ISA (eg, 601)
16958 CPU supports 64-bit mode execution.
16960 CPU supports a little-endian mode that uses address swizzling.
16962 Kernel supports system call vectored.
16964 CPU support simultaneous multi-threading.
16966 CPU has a signal processing extension unit.
16968 CPU supports the target address register.
16970 CPU supports true little-endian mode.
16972 CPU has unified I/D cache.
16974 CPU supports the vector cryptography instructions.
16976 CPU supports the vector-scalar extension.
16979 Here is an example:
16981 #ifdef __BUILTIN_CPU_SUPPORTS__
16982 if (__builtin_cpu_supports ("fpu"))
16984 asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2));
16989 dst = __fadd (src1, src2); // Software FP addition function.
16994 The following built-in functions are also available on all PowerPC
16997 uint64_t __builtin_ppc_get_timebase ();
16998 unsigned long __builtin_ppc_mftb ();
16999 double __builtin_unpack_ibm128 (__ibm128, int);
17000 __ibm128 __builtin_pack_ibm128 (double, double);
17001 double __builtin_mffs (void);
17002 double __builtin_mtfsf (const int, double);
17003 void __builtin_mtfsb0 (const int);
17004 void __builtin_mtfsb1 (const int);
17005 void __builtin_set_fpscr_rn (int);
17008 The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb}
17009 functions generate instructions to read the Time Base Register. The
17010 @code{__builtin_ppc_get_timebase} function may generate multiple
17011 instructions and always returns the 64 bits of the Time Base Register.
17012 The @code{__builtin_ppc_mftb} function always generates one instruction and
17013 returns the Time Base Register value as an unsigned long, throwing away
17014 the most significant word on 32-bit environments. The @code{__builtin_mffs}
17015 return the value of the FPSCR register. Note, ISA 3.0 supports the
17016 @code{__builtin_mffsl()} which permits software to read the control and
17017 non-sticky status bits in the FSPCR without the higher latency associated with
17018 accessing the sticky status bits. The @code{__builtin_mtfsf} takes a constant
17019 8-bit integer field mask and a double precision floating point argument
17020 and generates the @code{mtfsf} (extended mnemonic) instruction to write new
17021 values to selected fields of the FPSCR. The
17022 @code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change
17023 as an argument. The valid bit range is between 0 and 31. The builtins map to
17024 the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and
17025 add 32. Hence these instructions only modify the FPSCR[32:63] bits by
17026 changing the specified bit to a zero or one respectively. The
17027 @code{__builtin_set_fpscr_rn} builtin allows changing both of the floating
17028 point rounding mode bits. The argument is a 2-bit value. The argument can
17029 either be a @code{const int} or stored in a variable. The builtin uses
17031 instruction @code{mffscrn} if available, otherwise it reads the FPSCR, masks
17032 the current rounding mode bits out and OR's in the new value.
17034 @node Basic PowerPC Built-in Functions Available on ISA 2.05
17035 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05
17037 The basic built-in functions described in this section are
17038 available on the PowerPC family of processors starting with ISA 2.05
17039 or later. Unless specific options are explicitly disabled on the
17040 command line, specifying option @option{-mcpu=power6} has the effect of
17041 enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
17042 @option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb},
17043 @option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and
17044 @option{-mrecip-precision} options. Specify the
17045 @option{-maltivec} option explicitly in
17046 combination with the above options if desired.
17048 The following functions require option @option{-mcmpb}.
17050 unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int);
17051 unsigned int __builtin_cmpb (unsigned int, unsigned int);
17054 The @code{__builtin_cmpb} function
17055 performs a byte-wise compare on the contents of its two arguments,
17056 returning the result of the byte-wise comparison as the returned
17057 value. For each byte comparison, the corresponding byte of the return
17058 value holds 0xff if the input bytes are equal and 0 if the input bytes
17059 are not equal. If either of the arguments to this built-in function
17060 is wider than 32 bits, the function call expands into the form that
17061 expects @code{unsigned long long int} arguments
17062 which is only available on 64-bit targets.
17064 The following built-in functions are available
17065 when hardware decimal floating point
17066 (@option{-mhard-dfp}) is available:
17068 void __builtin_set_fpscr_drn(int);
17069 _Decimal64 __builtin_ddedpd (int, _Decimal64);
17070 _Decimal128 __builtin_ddedpdq (int, _Decimal128);
17071 _Decimal64 __builtin_denbcd (int, _Decimal64);
17072 _Decimal128 __builtin_denbcdq (int, _Decimal128);
17073 _Decimal64 __builtin_diex (long long, _Decimal64);
17074 _Decimal128 _builtin_diexq (long long, _Decimal128);
17075 _Decimal64 __builtin_dscli (_Decimal64, int);
17076 _Decimal128 __builtin_dscliq (_Decimal128, int);
17077 _Decimal64 __builtin_dscri (_Decimal64, int);
17078 _Decimal128 __builtin_dscriq (_Decimal128, int);
17079 long long __builtin_dxex (_Decimal64);
17080 long long __builtin_dxexq (_Decimal128);
17081 _Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long);
17082 unsigned long long __builtin_unpack_dec128 (_Decimal128, int);
17084 The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal
17085 floating point rounding mode bits. The argument is a 3-bit value. The
17086 argument can either be a @code{const int} or the value can be stored in
17088 The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available.
17089 Otherwise the builtin reads the FPSCR, masks the current decimal rounding
17090 mode bits out and OR's in the new value.
17094 The following functions require @option{-mhard-float},
17095 @option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options.
17098 double __builtin_recipdiv (double, double);
17099 float __builtin_recipdivf (float, float);
17100 double __builtin_rsqrt (double);
17101 float __builtin_rsqrtf (float);
17104 The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and
17105 @code{__builtin_rsqrtf} functions generate multiple instructions to
17106 implement the reciprocal sqrt functionality using reciprocal sqrt
17107 estimate instructions.
17109 The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf}
17110 functions generate multiple instructions to implement division using
17111 the reciprocal estimate instructions.
17113 The following functions require @option{-mhard-float} and
17114 @option{-mmultiple} options.
17116 The @code{__builtin_unpack_longdouble} function takes a
17117 @code{long double} argument and a compile time constant of 0 or 1. If
17118 the constant is 0, the first @code{double} within the
17119 @code{long double} is returned, otherwise the second @code{double}
17120 is returned. The @code{__builtin_unpack_longdouble} function is only
17121 available if @code{long double} uses the IBM extended double
17124 The @code{__builtin_pack_longdouble} function takes two @code{double}
17125 arguments and returns a @code{long double} value that combines the two
17126 arguments. The @code{__builtin_pack_longdouble} function is only
17127 available if @code{long double} uses the IBM extended double
17130 The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128}
17131 argument and a compile time constant of 0 or 1. If the constant is 0,
17132 the first @code{double} within the @code{__ibm128} is returned,
17133 otherwise the second @code{double} is returned.
17135 The @code{__builtin_pack_ibm128} function takes two @code{double}
17136 arguments and returns a @code{__ibm128} value that combines the two
17139 Additional built-in functions are available for the 64-bit PowerPC
17140 family of processors, for efficient use of 128-bit floating point
17141 (@code{__float128}) values.
17143 @node Basic PowerPC Built-in Functions Available on ISA 2.06
17144 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06
17146 The basic built-in functions described in this section are
17147 available on the PowerPC family of processors starting with ISA 2.05
17148 or later. Unless specific options are explicitly disabled on the
17149 command line, specifying option @option{-mcpu=power7} has the effect of
17150 enabling all the same options as for @option{-mcpu=power6} in
17151 addition to the @option{-maltivec}, @option{-mpopcntd}, and
17152 @option{-mvsx} options.
17154 The following basic built-in functions require @option{-mpopcntd}:
17156 unsigned int __builtin_addg6s (unsigned int, unsigned int);
17157 long long __builtin_bpermd (long long, long long);
17158 unsigned int __builtin_cbcdtd (unsigned int);
17159 unsigned int __builtin_cdtbcd (unsigned int);
17160 long long __builtin_divde (long long, long long);
17161 unsigned long long __builtin_divdeu (unsigned long long, unsigned long long);
17162 int __builtin_divwe (int, int);
17163 unsigned int __builtin_divweu (unsigned int, unsigned int);
17164 vector __int128 __builtin_pack_vector_int128 (long long, long long);
17165 void __builtin_rs6000_speculation_barrier (void);
17166 long long __builtin_unpack_vector_int128 (vector __int128, signed char);
17169 Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions
17170 require a 64-bit environment.
17172 The following basic built-in functions, which are also supported on
17173 x86 targets, require @option{-mfloat128}.
17175 __float128 __builtin_fabsq (__float128);
17176 __float128 __builtin_copysignq (__float128, __float128);
17177 __float128 __builtin_infq (void);
17178 __float128 __builtin_huge_valq (void);
17179 __float128 __builtin_nanq (void);
17180 __float128 __builtin_nansq (void);
17182 __float128 __builtin_sqrtf128 (__float128);
17183 __float128 __builtin_fmaf128 (__float128, __float128, __float128);
17186 @node Basic PowerPC Built-in Functions Available on ISA 2.07
17187 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07
17189 The basic built-in functions described in this section are
17190 available on the PowerPC family of processors starting with ISA 2.07
17191 or later. Unless specific options are explicitly disabled on the
17192 command line, specifying option @option{-mcpu=power8} has the effect of
17193 enabling all the same options as for @option{-mcpu=power7} in
17194 addition to the @option{-mpower8-fusion}, @option{-mpower8-vector},
17195 @option{-mcrypto}, @option{-mhtm}, @option{-mquad-memory}, and
17196 @option{-mquad-memory-atomic} options.
17198 This section intentionally empty.
17200 @node Basic PowerPC Built-in Functions Available on ISA 3.0
17201 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0
17203 The basic built-in functions described in this section are
17204 available on the PowerPC family of processors starting with ISA 3.0
17205 or later. Unless specific options are explicitly disabled on the
17206 command line, specifying option @option{-mcpu=power9} has the effect of
17207 enabling all the same options as for @option{-mcpu=power8} in
17208 addition to the @option{-misel} option.
17210 The following built-in functions are available on Linux 64-bit systems
17211 that use the ISA 3.0 instruction set (@option{-mcpu=power9}):
17214 @item __float128 __builtin_addf128_round_to_odd (__float128, __float128)
17215 Perform a 128-bit IEEE floating point add using round to odd as the
17217 @findex __builtin_addf128_round_to_odd
17219 @item __float128 __builtin_subf128_round_to_odd (__float128, __float128)
17220 Perform a 128-bit IEEE floating point subtract using round to odd as
17222 @findex __builtin_subf128_round_to_odd
17224 @item __float128 __builtin_mulf128_round_to_odd (__float128, __float128)
17225 Perform a 128-bit IEEE floating point multiply using round to odd as
17227 @findex __builtin_mulf128_round_to_odd
17229 @item __float128 __builtin_divf128_round_to_odd (__float128, __float128)
17230 Perform a 128-bit IEEE floating point divide using round to odd as
17232 @findex __builtin_divf128_round_to_odd
17234 @item __float128 __builtin_sqrtf128_round_to_odd (__float128)
17235 Perform a 128-bit IEEE floating point square root using round to odd
17236 as the rounding mode.
17237 @findex __builtin_sqrtf128_round_to_odd
17239 @item __float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128)
17240 Perform a 128-bit IEEE floating point fused multiply and add operation
17241 using round to odd as the rounding mode.
17242 @findex __builtin_fmaf128_round_to_odd
17244 @item double __builtin_truncf128_round_to_odd (__float128)
17245 Convert a 128-bit IEEE floating point value to @code{double} using
17246 round to odd as the rounding mode.
17247 @findex __builtin_truncf128_round_to_odd
17250 The following additional built-in functions are also available for the
17251 PowerPC family of processors, starting with ISA 3.0 or later:
17253 long long __builtin_darn (void);
17254 long long __builtin_darn_raw (void);
17255 int __builtin_darn_32 (void);
17258 The @code{__builtin_darn} and @code{__builtin_darn_raw}
17259 functions require a
17260 64-bit environment supporting ISA 3.0 or later.
17261 The @code{__builtin_darn} function provides a 64-bit conditioned
17262 random number. The @code{__builtin_darn_raw} function provides a
17263 64-bit raw random number. The @code{__builtin_darn_32} function
17264 provides a 32-bit conditioned random number.
17266 The following additional built-in functions are also available for the
17267 PowerPC family of processors, starting with ISA 3.0 or later:
17270 int __builtin_byte_in_set (unsigned char u, unsigned long long set);
17271 int __builtin_byte_in_range (unsigned char u, unsigned int range);
17272 int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges);
17274 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value);
17275 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value);
17276 int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value);
17277 int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value);
17279 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value);
17280 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value);
17281 int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value);
17282 int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value);
17284 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value);
17285 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value);
17286 int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value);
17287 int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value);
17289 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value);
17290 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value);
17291 int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value);
17292 int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value);
17294 double __builtin_mffsl(void);
17297 The @code{__builtin_byte_in_set} function requires a
17298 64-bit environment supporting ISA 3.0 or later. This function returns
17299 a non-zero value if and only if its @code{u} argument exactly equals one of
17300 the eight bytes contained within its 64-bit @code{set} argument.
17302 The @code{__builtin_byte_in_range} and
17303 @code{__builtin_byte_in_either_range} require an environment
17304 supporting ISA 3.0 or later. For these two functions, the
17305 @code{range} argument is encoded as 4 bytes, organized as
17306 @code{hi_1:lo_1:hi_2:lo_2}.
17307 The @code{__builtin_byte_in_range} function returns a
17308 non-zero value if and only if its @code{u} argument is within the
17309 range bounded between @code{lo_2} and @code{hi_2} inclusive.
17310 The @code{__builtin_byte_in_either_range} function returns non-zero if
17311 and only if its @code{u} argument is within either the range bounded
17312 between @code{lo_1} and @code{hi_1} inclusive or the range bounded
17313 between @code{lo_2} and @code{hi_2} inclusive.
17315 The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value
17316 if and only if the number of signficant digits of its @code{value} argument
17317 is less than its @code{comparison} argument. The
17318 @code{__builtin_dfp_dtstsfi_lt_dd} and
17319 @code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but
17320 require that the type of the @code{value} argument be
17321 @code{__Decimal64} and @code{__Decimal128} respectively.
17323 The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value
17324 if and only if the number of signficant digits of its @code{value} argument
17325 is greater than its @code{comparison} argument. The
17326 @code{__builtin_dfp_dtstsfi_gt_dd} and
17327 @code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but
17328 require that the type of the @code{value} argument be
17329 @code{__Decimal64} and @code{__Decimal128} respectively.
17331 The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value
17332 if and only if the number of signficant digits of its @code{value} argument
17333 equals its @code{comparison} argument. The
17334 @code{__builtin_dfp_dtstsfi_eq_dd} and
17335 @code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but
17336 require that the type of the @code{value} argument be
17337 @code{__Decimal64} and @code{__Decimal128} respectively.
17339 The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value
17340 if and only if its @code{value} argument has an undefined number of
17341 significant digits, such as when @code{value} is an encoding of @code{NaN}.
17342 The @code{__builtin_dfp_dtstsfi_ov_dd} and
17343 @code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but
17344 require that the type of the @code{value} argument be
17345 @code{__Decimal64} and @code{__Decimal128} respectively.
17347 The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read
17348 the FPSCR. The instruction is a lower latency version of the @code{mffs}
17349 instruction. If the @code{mffsl} instruction is not available, then the
17350 builtin uses the older @code{mffs} instruction to read the FPSCR.
17353 @node PowerPC AltiVec/VSX Built-in Functions
17354 @subsection PowerPC AltiVec/VSX Built-in Functions
17356 GCC provides an interface for the PowerPC family of processors to access
17357 the AltiVec operations described in Motorola's AltiVec Programming
17358 Interface Manual. The interface is made available by including
17359 @code{<altivec.h>} and using @option{-maltivec} and
17360 @option{-mabi=altivec}. The interface supports the following vector
17364 vector unsigned char
17368 vector unsigned short
17369 vector signed short
17373 vector unsigned int
17379 GCC's implementation of the high-level language interface available from
17380 C and C++ code differs from Motorola's documentation in several ways.
17385 A vector constant is a list of constant expressions within curly braces.
17388 A vector initializer requires no cast if the vector constant is of the
17389 same type as the variable it is initializing.
17392 If @code{signed} or @code{unsigned} is omitted, the signedness of the
17393 vector type is the default signedness of the base type. The default
17394 varies depending on the operating system, so a portable program should
17395 always specify the signedness.
17398 Compiling with @option{-maltivec} adds keywords @code{__vector},
17399 @code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and
17400 @code{bool}. When compiling ISO C, the context-sensitive substitution
17401 of the keywords @code{vector}, @code{pixel} and @code{bool} is
17402 disabled. To use them, you must include @code{<altivec.h>} instead.
17405 GCC allows using a @code{typedef} name as the type specifier for a
17406 vector type, but only under the following circumstances:
17411 When using @code{__vector} instead of @code{vector}; for example,
17414 typedef signed short int16;
17415 __vector int16 data;
17419 When using @code{vector} in keyword-and-predefine mode; for example,
17422 typedef signed short int16;
17426 Note that keyword-and-predefine mode is enabled by disabling GNU
17427 extensions (e.g., by using @code{-std=c11}) and including
17428 @code{<altivec.h>}.
17432 For C, overloaded functions are implemented with macros so the following
17436 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo);
17440 Since @code{vec_add} is a macro, the vector constant in the example
17441 is treated as four separate arguments. Wrap the entire argument in
17442 parentheses for this to work.
17445 @emph{Note:} Only the @code{<altivec.h>} interface is supported.
17446 Internally, GCC uses built-in functions to achieve the functionality in
17447 the aforementioned header file, but they are not supported and are
17448 subject to change without notice.
17450 GCC complies with the OpenPOWER 64-Bit ELF V2 ABI Specification,
17451 which may be found at
17452 @uref{http://openpowerfoundation.org/wp-content/uploads/resources/leabi-prd/content/index.html}.
17453 Appendix A of this document lists the vector API interfaces that must be
17454 provided by compliant compilers. Programmers should preferentially use
17455 the interfaces described therein. However, historically GCC has provided
17456 additional interfaces for access to vector instructions. These are
17457 briefly described below.
17460 * PowerPC AltiVec Built-in Functions on ISA 2.05::
17461 * PowerPC AltiVec Built-in Functions Available on ISA 2.06::
17462 * PowerPC AltiVec Built-in Functions Available on ISA 2.07::
17463 * PowerPC AltiVec Built-in Functions Available on ISA 3.0::
17466 @node PowerPC AltiVec Built-in Functions on ISA 2.05
17467 @subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05
17469 The following interfaces are supported for the generic and specific
17470 AltiVec operations and the AltiVec predicates. In cases where there
17471 is a direct mapping between generic and specific operations, only the
17472 generic names are shown here, although the specific operations can also
17475 Arguments that are documented as @code{const int} require literal
17476 integral values within the range required for that operation.
17479 vector signed char vec_abs (vector signed char);
17480 vector signed short vec_abs (vector signed short);
17481 vector signed int vec_abs (vector signed int);
17482 vector float vec_abs (vector float);
17484 vector signed char vec_abss (vector signed char);
17485 vector signed short vec_abss (vector signed short);
17486 vector signed int vec_abss (vector signed int);
17488 vector signed char vec_add (vector bool char, vector signed char);
17489 vector signed char vec_add (vector signed char, vector bool char);
17490 vector signed char vec_add (vector signed char, vector signed char);
17491 vector unsigned char vec_add (vector bool char, vector unsigned char);
17492 vector unsigned char vec_add (vector unsigned char, vector bool char);
17493 vector unsigned char vec_add (vector unsigned char, vector unsigned char);
17494 vector signed short vec_add (vector bool short, vector signed short);
17495 vector signed short vec_add (vector signed short, vector bool short);
17496 vector signed short vec_add (vector signed short, vector signed short);
17497 vector unsigned short vec_add (vector bool short, vector unsigned short);
17498 vector unsigned short vec_add (vector unsigned short, vector bool short);
17499 vector unsigned short vec_add (vector unsigned short, vector unsigned short);
17500 vector signed int vec_add (vector bool int, vector signed int);
17501 vector signed int vec_add (vector signed int, vector bool int);
17502 vector signed int vec_add (vector signed int, vector signed int);
17503 vector unsigned int vec_add (vector bool int, vector unsigned int);
17504 vector unsigned int vec_add (vector unsigned int, vector bool int);
17505 vector unsigned int vec_add (vector unsigned int, vector unsigned int);
17506 vector float vec_add (vector float, vector float);
17508 vector unsigned int vec_addc (vector unsigned int, vector unsigned int);
17510 vector unsigned char vec_adds (vector bool char, vector unsigned char);
17511 vector unsigned char vec_adds (vector unsigned char, vector bool char);
17512 vector unsigned char vec_adds (vector unsigned char, vector unsigned char);
17513 vector signed char vec_adds (vector bool char, vector signed char);
17514 vector signed char vec_adds (vector signed char, vector bool char);
17515 vector signed char vec_adds (vector signed char, vector signed char);
17516 vector unsigned short vec_adds (vector bool short, vector unsigned short);
17517 vector unsigned short vec_adds (vector unsigned short, vector bool short);
17518 vector unsigned short vec_adds (vector unsigned short, vector unsigned short);
17519 vector signed short vec_adds (vector bool short, vector signed short);
17520 vector signed short vec_adds (vector signed short, vector bool short);
17521 vector signed short vec_adds (vector signed short, vector signed short);
17522 vector unsigned int vec_adds (vector bool int, vector unsigned int);
17523 vector unsigned int vec_adds (vector unsigned int, vector bool int);
17524 vector unsigned int vec_adds (vector unsigned int, vector unsigned int);
17525 vector signed int vec_adds (vector bool int, vector signed int);
17526 vector signed int vec_adds (vector signed int, vector bool int);
17527 vector signed int vec_adds (vector signed int, vector signed int);
17529 int vec_all_eq (vector signed char, vector bool char);
17530 int vec_all_eq (vector signed char, vector signed char);
17531 int vec_all_eq (vector unsigned char, vector bool char);
17532 int vec_all_eq (vector unsigned char, vector unsigned char);
17533 int vec_all_eq (vector bool char, vector bool char);
17534 int vec_all_eq (vector bool char, vector unsigned char);
17535 int vec_all_eq (vector bool char, vector signed char);
17536 int vec_all_eq (vector signed short, vector bool short);
17537 int vec_all_eq (vector signed short, vector signed short);
17538 int vec_all_eq (vector unsigned short, vector bool short);
17539 int vec_all_eq (vector unsigned short, vector unsigned short);
17540 int vec_all_eq (vector bool short, vector bool short);
17541 int vec_all_eq (vector bool short, vector unsigned short);
17542 int vec_all_eq (vector bool short, vector signed short);
17543 int vec_all_eq (vector pixel, vector pixel);
17544 int vec_all_eq (vector signed int, vector bool int);
17545 int vec_all_eq (vector signed int, vector signed int);
17546 int vec_all_eq (vector unsigned int, vector bool int);
17547 int vec_all_eq (vector unsigned int, vector unsigned int);
17548 int vec_all_eq (vector bool int, vector bool int);
17549 int vec_all_eq (vector bool int, vector unsigned int);
17550 int vec_all_eq (vector bool int, vector signed int);
17551 int vec_all_eq (vector float, vector float);
17553 int vec_all_ge (vector bool char, vector unsigned char);
17554 int vec_all_ge (vector unsigned char, vector bool char);
17555 int vec_all_ge (vector unsigned char, vector unsigned char);
17556 int vec_all_ge (vector bool char, vector signed char);
17557 int vec_all_ge (vector signed char, vector bool char);
17558 int vec_all_ge (vector signed char, vector signed char);
17559 int vec_all_ge (vector bool short, vector unsigned short);
17560 int vec_all_ge (vector unsigned short, vector bool short);
17561 int vec_all_ge (vector unsigned short, vector unsigned short);
17562 int vec_all_ge (vector signed short, vector signed short);
17563 int vec_all_ge (vector bool short, vector signed short);
17564 int vec_all_ge (vector signed short, vector bool short);
17565 int vec_all_ge (vector bool int, vector unsigned int);
17566 int vec_all_ge (vector unsigned int, vector bool int);
17567 int vec_all_ge (vector unsigned int, vector unsigned int);
17568 int vec_all_ge (vector bool int, vector signed int);
17569 int vec_all_ge (vector signed int, vector bool int);
17570 int vec_all_ge (vector signed int, vector signed int);
17571 int vec_all_ge (vector float, vector float);
17573 int vec_all_gt (vector bool char, vector unsigned char);
17574 int vec_all_gt (vector unsigned char, vector bool char);
17575 int vec_all_gt (vector unsigned char, vector unsigned char);
17576 int vec_all_gt (vector bool char, vector signed char);
17577 int vec_all_gt (vector signed char, vector bool char);
17578 int vec_all_gt (vector signed char, vector signed char);
17579 int vec_all_gt (vector bool short, vector unsigned short);
17580 int vec_all_gt (vector unsigned short, vector bool short);
17581 int vec_all_gt (vector unsigned short, vector unsigned short);
17582 int vec_all_gt (vector bool short, vector signed short);
17583 int vec_all_gt (vector signed short, vector bool short);
17584 int vec_all_gt (vector signed short, vector signed short);
17585 int vec_all_gt (vector bool int, vector unsigned int);
17586 int vec_all_gt (vector unsigned int, vector bool int);
17587 int vec_all_gt (vector unsigned int, vector unsigned int);
17588 int vec_all_gt (vector bool int, vector signed int);
17589 int vec_all_gt (vector signed int, vector bool int);
17590 int vec_all_gt (vector signed int, vector signed int);
17591 int vec_all_gt (vector float, vector float);
17593 int vec_all_in (vector float, vector float);
17595 int vec_all_le (vector bool char, vector unsigned char);
17596 int vec_all_le (vector unsigned char, vector bool char);
17597 int vec_all_le (vector unsigned char, vector unsigned char);
17598 int vec_all_le (vector bool char, vector signed char);
17599 int vec_all_le (vector signed char, vector bool char);
17600 int vec_all_le (vector signed char, vector signed char);
17601 int vec_all_le (vector bool short, vector unsigned short);
17602 int vec_all_le (vector unsigned short, vector bool short);
17603 int vec_all_le (vector unsigned short, vector unsigned short);
17604 int vec_all_le (vector bool short, vector signed short);
17605 int vec_all_le (vector signed short, vector bool short);
17606 int vec_all_le (vector signed short, vector signed short);
17607 int vec_all_le (vector bool int, vector unsigned int);
17608 int vec_all_le (vector unsigned int, vector bool int);
17609 int vec_all_le (vector unsigned int, vector unsigned int);
17610 int vec_all_le (vector bool int, vector signed int);
17611 int vec_all_le (vector signed int, vector bool int);
17612 int vec_all_le (vector signed int, vector signed int);
17613 int vec_all_le (vector float, vector float);
17615 int vec_all_lt (vector bool char, vector unsigned char);
17616 int vec_all_lt (vector unsigned char, vector bool char);
17617 int vec_all_lt (vector unsigned char, vector unsigned char);
17618 int vec_all_lt (vector bool char, vector signed char);
17619 int vec_all_lt (vector signed char, vector bool char);
17620 int vec_all_lt (vector signed char, vector signed char);
17621 int vec_all_lt (vector bool short, vector unsigned short);
17622 int vec_all_lt (vector unsigned short, vector bool short);
17623 int vec_all_lt (vector unsigned short, vector unsigned short);
17624 int vec_all_lt (vector bool short, vector signed short);
17625 int vec_all_lt (vector signed short, vector bool short);
17626 int vec_all_lt (vector signed short, vector signed short);
17627 int vec_all_lt (vector bool int, vector unsigned int);
17628 int vec_all_lt (vector unsigned int, vector bool int);
17629 int vec_all_lt (vector unsigned int, vector unsigned int);
17630 int vec_all_lt (vector bool int, vector signed int);
17631 int vec_all_lt (vector signed int, vector bool int);
17632 int vec_all_lt (vector signed int, vector signed int);
17633 int vec_all_lt (vector float, vector float);
17635 int vec_all_nan (vector float);
17637 int vec_all_ne (vector signed char, vector bool char);
17638 int vec_all_ne (vector signed char, vector signed char);
17639 int vec_all_ne (vector unsigned char, vector bool char);
17640 int vec_all_ne (vector unsigned char, vector unsigned char);
17641 int vec_all_ne (vector bool char, vector bool char);
17642 int vec_all_ne (vector bool char, vector unsigned char);
17643 int vec_all_ne (vector bool char, vector signed char);
17644 int vec_all_ne (vector signed short, vector bool short);
17645 int vec_all_ne (vector signed short, vector signed short);
17646 int vec_all_ne (vector unsigned short, vector bool short);
17647 int vec_all_ne (vector unsigned short, vector unsigned short);
17648 int vec_all_ne (vector bool short, vector bool short);
17649 int vec_all_ne (vector bool short, vector unsigned short);
17650 int vec_all_ne (vector bool short, vector signed short);
17651 int vec_all_ne (vector pixel, vector pixel);
17652 int vec_all_ne (vector signed int, vector bool int);
17653 int vec_all_ne (vector signed int, vector signed int);
17654 int vec_all_ne (vector unsigned int, vector bool int);
17655 int vec_all_ne (vector unsigned int, vector unsigned int);
17656 int vec_all_ne (vector bool int, vector bool int);
17657 int vec_all_ne (vector bool int, vector unsigned int);
17658 int vec_all_ne (vector bool int, vector signed int);
17659 int vec_all_ne (vector float, vector float);
17661 int vec_all_nge (vector float, vector float);
17663 int vec_all_ngt (vector float, vector float);
17665 int vec_all_nle (vector float, vector float);
17667 int vec_all_nlt (vector float, vector float);
17669 int vec_all_numeric (vector float);
17671 vector float vec_and (vector float, vector float);
17672 vector float vec_and (vector float, vector bool int);
17673 vector float vec_and (vector bool int, vector float);
17674 vector bool int vec_and (vector bool int, vector bool int);
17675 vector signed int vec_and (vector bool int, vector signed int);
17676 vector signed int vec_and (vector signed int, vector bool int);
17677 vector signed int vec_and (vector signed int, vector signed int);
17678 vector unsigned int vec_and (vector bool int, vector unsigned int);
17679 vector unsigned int vec_and (vector unsigned int, vector bool int);
17680 vector unsigned int vec_and (vector unsigned int, vector unsigned int);
17681 vector bool short vec_and (vector bool short, vector bool short);
17682 vector signed short vec_and (vector bool short, vector signed short);
17683 vector signed short vec_and (vector signed short, vector bool short);
17684 vector signed short vec_and (vector signed short, vector signed short);
17685 vector unsigned short vec_and (vector bool short, vector unsigned short);
17686 vector unsigned short vec_and (vector unsigned short, vector bool short);
17687 vector unsigned short vec_and (vector unsigned short, vector unsigned short);
17688 vector signed char vec_and (vector bool char, vector signed char);
17689 vector bool char vec_and (vector bool char, vector bool char);
17690 vector signed char vec_and (vector signed char, vector bool char);
17691 vector signed char vec_and (vector signed char, vector signed char);
17692 vector unsigned char vec_and (vector bool char, vector unsigned char);
17693 vector unsigned char vec_and (vector unsigned char, vector bool char);
17694 vector unsigned char vec_and (vector unsigned char, vector unsigned char);
17696 vector float vec_andc (vector float, vector float);
17697 vector float vec_andc (vector float, vector bool int);
17698 vector float vec_andc (vector bool int, vector float);
17699 vector bool int vec_andc (vector bool int, vector bool int);
17700 vector signed int vec_andc (vector bool int, vector signed int);
17701 vector signed int vec_andc (vector signed int, vector bool int);
17702 vector signed int vec_andc (vector signed int, vector signed int);
17703 vector unsigned int vec_andc (vector bool int, vector unsigned int);
17704 vector unsigned int vec_andc (vector unsigned int, vector bool int);
17705 vector unsigned int vec_andc (vector unsigned int, vector unsigned int);
17706 vector bool short vec_andc (vector bool short, vector bool short);
17707 vector signed short vec_andc (vector bool short, vector signed short);
17708 vector signed short vec_andc (vector signed short, vector bool short);
17709 vector signed short vec_andc (vector signed short, vector signed short);
17710 vector unsigned short vec_andc (vector bool short, vector unsigned short);
17711 vector unsigned short vec_andc (vector unsigned short, vector bool short);
17712 vector unsigned short vec_andc (vector unsigned short, vector unsigned short);
17713 vector signed char vec_andc (vector bool char, vector signed char);
17714 vector bool char vec_andc (vector bool char, vector bool char);
17715 vector signed char vec_andc (vector signed char, vector bool char);
17716 vector signed char vec_andc (vector signed char, vector signed char);
17717 vector unsigned char vec_andc (vector bool char, vector unsigned char);
17718 vector unsigned char vec_andc (vector unsigned char, vector bool char);
17719 vector unsigned char vec_andc (vector unsigned char, vector unsigned char);
17721 int vec_any_eq (vector signed char, vector bool char);
17722 int vec_any_eq (vector signed char, vector signed char);
17723 int vec_any_eq (vector unsigned char, vector bool char);
17724 int vec_any_eq (vector unsigned char, vector unsigned char);
17725 int vec_any_eq (vector bool char, vector bool char);
17726 int vec_any_eq (vector bool char, vector unsigned char);
17727 int vec_any_eq (vector bool char, vector signed char);
17728 int vec_any_eq (vector signed short, vector bool short);
17729 int vec_any_eq (vector signed short, vector signed short);
17730 int vec_any_eq (vector unsigned short, vector bool short);
17731 int vec_any_eq (vector unsigned short, vector unsigned short);
17732 int vec_any_eq (vector bool short, vector bool short);
17733 int vec_any_eq (vector bool short, vector unsigned short);
17734 int vec_any_eq (vector bool short, vector signed short);
17735 int vec_any_eq (vector pixel, vector pixel);
17736 int vec_any_eq (vector signed int, vector bool int);
17737 int vec_any_eq (vector signed int, vector signed int);
17738 int vec_any_eq (vector unsigned int, vector bool int);
17739 int vec_any_eq (vector unsigned int, vector unsigned int);
17740 int vec_any_eq (vector bool int, vector bool int);
17741 int vec_any_eq (vector bool int, vector unsigned int);
17742 int vec_any_eq (vector bool int, vector signed int);
17743 int vec_any_eq (vector float, vector float);
17745 int vec_any_ge (vector signed char, vector bool char);
17746 int vec_any_ge (vector unsigned char, vector bool char);
17747 int vec_any_ge (vector unsigned char, vector unsigned char);
17748 int vec_any_ge (vector signed char, vector signed char);
17749 int vec_any_ge (vector bool char, vector unsigned char);
17750 int vec_any_ge (vector bool char, vector signed char);
17751 int vec_any_ge (vector unsigned short, vector bool short);
17752 int vec_any_ge (vector unsigned short, vector unsigned short);
17753 int vec_any_ge (vector signed short, vector signed short);
17754 int vec_any_ge (vector signed short, vector bool short);
17755 int vec_any_ge (vector bool short, vector unsigned short);
17756 int vec_any_ge (vector bool short, vector signed short);
17757 int vec_any_ge (vector signed int, vector bool int);
17758 int vec_any_ge (vector unsigned int, vector bool int);
17759 int vec_any_ge (vector unsigned int, vector unsigned int);
17760 int vec_any_ge (vector signed int, vector signed int);
17761 int vec_any_ge (vector bool int, vector unsigned int);
17762 int vec_any_ge (vector bool int, vector signed int);
17763 int vec_any_ge (vector float, vector float);
17765 int vec_any_gt (vector bool char, vector unsigned char);
17766 int vec_any_gt (vector unsigned char, vector bool char);
17767 int vec_any_gt (vector unsigned char, vector unsigned char);
17768 int vec_any_gt (vector bool char, vector signed char);
17769 int vec_any_gt (vector signed char, vector bool char);
17770 int vec_any_gt (vector signed char, vector signed char);
17771 int vec_any_gt (vector bool short, vector unsigned short);
17772 int vec_any_gt (vector unsigned short, vector bool short);
17773 int vec_any_gt (vector unsigned short, vector unsigned short);
17774 int vec_any_gt (vector bool short, vector signed short);
17775 int vec_any_gt (vector signed short, vector bool short);
17776 int vec_any_gt (vector signed short, vector signed short);
17777 int vec_any_gt (vector bool int, vector unsigned int);
17778 int vec_any_gt (vector unsigned int, vector bool int);
17779 int vec_any_gt (vector unsigned int, vector unsigned int);
17780 int vec_any_gt (vector bool int, vector signed int);
17781 int vec_any_gt (vector signed int, vector bool int);
17782 int vec_any_gt (vector signed int, vector signed int);
17783 int vec_any_gt (vector float, vector float);
17785 int vec_any_le (vector bool char, vector unsigned char);
17786 int vec_any_le (vector unsigned char, vector bool char);
17787 int vec_any_le (vector unsigned char, vector unsigned char);
17788 int vec_any_le (vector bool char, vector signed char);
17789 int vec_any_le (vector signed char, vector bool char);
17790 int vec_any_le (vector signed char, vector signed char);
17791 int vec_any_le (vector bool short, vector unsigned short);
17792 int vec_any_le (vector unsigned short, vector bool short);
17793 int vec_any_le (vector unsigned short, vector unsigned short);
17794 int vec_any_le (vector bool short, vector signed short);
17795 int vec_any_le (vector signed short, vector bool short);
17796 int vec_any_le (vector signed short, vector signed short);
17797 int vec_any_le (vector bool int, vector unsigned int);
17798 int vec_any_le (vector unsigned int, vector bool int);
17799 int vec_any_le (vector unsigned int, vector unsigned int);
17800 int vec_any_le (vector bool int, vector signed int);
17801 int vec_any_le (vector signed int, vector bool int);
17802 int vec_any_le (vector signed int, vector signed int);
17803 int vec_any_le (vector float, vector float);
17805 int vec_any_lt (vector bool char, vector unsigned char);
17806 int vec_any_lt (vector unsigned char, vector bool char);
17807 int vec_any_lt (vector unsigned char, vector unsigned char);
17808 int vec_any_lt (vector bool char, vector signed char);
17809 int vec_any_lt (vector signed char, vector bool char);
17810 int vec_any_lt (vector signed char, vector signed char);
17811 int vec_any_lt (vector bool short, vector unsigned short);
17812 int vec_any_lt (vector unsigned short, vector bool short);
17813 int vec_any_lt (vector unsigned short, vector unsigned short);
17814 int vec_any_lt (vector bool short, vector signed short);
17815 int vec_any_lt (vector signed short, vector bool short);
17816 int vec_any_lt (vector signed short, vector signed short);
17817 int vec_any_lt (vector bool int, vector unsigned int);
17818 int vec_any_lt (vector unsigned int, vector bool int);
17819 int vec_any_lt (vector unsigned int, vector unsigned int);
17820 int vec_any_lt (vector bool int, vector signed int);
17821 int vec_any_lt (vector signed int, vector bool int);
17822 int vec_any_lt (vector signed int, vector signed int);
17823 int vec_any_lt (vector float, vector float);
17825 int vec_any_nan (vector float);
17827 int vec_any_ne (vector signed char, vector bool char);
17828 int vec_any_ne (vector signed char, vector signed char);
17829 int vec_any_ne (vector unsigned char, vector bool char);
17830 int vec_any_ne (vector unsigned char, vector unsigned char);
17831 int vec_any_ne (vector bool char, vector bool char);
17832 int vec_any_ne (vector bool char, vector unsigned char);
17833 int vec_any_ne (vector bool char, vector signed char);
17834 int vec_any_ne (vector signed short, vector bool short);
17835 int vec_any_ne (vector signed short, vector signed short);
17836 int vec_any_ne (vector unsigned short, vector bool short);
17837 int vec_any_ne (vector unsigned short, vector unsigned short);
17838 int vec_any_ne (vector bool short, vector bool short);
17839 int vec_any_ne (vector bool short, vector unsigned short);
17840 int vec_any_ne (vector bool short, vector signed short);
17841 int vec_any_ne (vector pixel, vector pixel);
17842 int vec_any_ne (vector signed int, vector bool int);
17843 int vec_any_ne (vector signed int, vector signed int);
17844 int vec_any_ne (vector unsigned int, vector bool int);
17845 int vec_any_ne (vector unsigned int, vector unsigned int);
17846 int vec_any_ne (vector bool int, vector bool int);
17847 int vec_any_ne (vector bool int, vector unsigned int);
17848 int vec_any_ne (vector bool int, vector signed int);
17849 int vec_any_ne (vector float, vector float);
17851 int vec_any_nge (vector float, vector float);
17853 int vec_any_ngt (vector float, vector float);
17855 int vec_any_nle (vector float, vector float);
17857 int vec_any_nlt (vector float, vector float);
17859 int vec_any_numeric (vector float);
17861 int vec_any_out (vector float, vector float);
17863 vector unsigned char vec_avg (vector unsigned char, vector unsigned char);
17864 vector signed char vec_avg (vector signed char, vector signed char);
17865 vector unsigned short vec_avg (vector unsigned short, vector unsigned short);
17866 vector signed short vec_avg (vector signed short, vector signed short);
17867 vector unsigned int vec_avg (vector unsigned int, vector unsigned int);
17868 vector signed int vec_avg (vector signed int, vector signed int);
17870 vector float vec_ceil (vector float);
17872 vector signed int vec_cmpb (vector float, vector float);
17874 vector bool char vec_cmpeq (vector bool char, vector bool char);
17875 vector bool short vec_cmpeq (vector bool short, vector bool short);
17876 vector bool int vec_cmpeq (vector bool int, vector bool int);
17877 vector bool char vec_cmpeq (vector signed char, vector signed char);
17878 vector bool char vec_cmpeq (vector unsigned char, vector unsigned char);
17879 vector bool short vec_cmpeq (vector signed short, vector signed short);
17880 vector bool short vec_cmpeq (vector unsigned short, vector unsigned short);
17881 vector bool int vec_cmpeq (vector signed int, vector signed int);
17882 vector bool int vec_cmpeq (vector unsigned int, vector unsigned int);
17883 vector bool int vec_cmpeq (vector float, vector float);
17885 vector bool int vec_cmpge (vector float, vector float);
17887 vector bool char vec_cmpgt (vector unsigned char, vector unsigned char);
17888 vector bool char vec_cmpgt (vector signed char, vector signed char);
17889 vector bool short vec_cmpgt (vector unsigned short, vector unsigned short);
17890 vector bool short vec_cmpgt (vector signed short, vector signed short);
17891 vector bool int vec_cmpgt (vector unsigned int, vector unsigned int);
17892 vector bool int vec_cmpgt (vector signed int, vector signed int);
17893 vector bool int vec_cmpgt (vector float, vector float);
17895 vector bool int vec_cmple (vector float, vector float);
17897 vector bool char vec_cmplt (vector unsigned char, vector unsigned char);
17898 vector bool char vec_cmplt (vector signed char, vector signed char);
17899 vector bool short vec_cmplt (vector unsigned short, vector unsigned short);
17900 vector bool short vec_cmplt (vector signed short, vector signed short);
17901 vector bool int vec_cmplt (vector unsigned int, vector unsigned int);
17902 vector bool int vec_cmplt (vector signed int, vector signed int);
17903 vector bool int vec_cmplt (vector float, vector float);
17905 vector float vec_cpsgn (vector float, vector float);
17907 vector float vec_ctf (vector unsigned int, const int);
17908 vector float vec_ctf (vector signed int, const int);
17910 vector signed int vec_cts (vector float, const int);
17912 vector unsigned int vec_ctu (vector float, const int);
17914 void vec_dss (const int);
17916 void vec_dssall (void);
17918 void vec_dst (const vector unsigned char *, int, const int);
17919 void vec_dst (const vector signed char *, int, const int);
17920 void vec_dst (const vector bool char *, int, const int);
17921 void vec_dst (const vector unsigned short *, int, const int);
17922 void vec_dst (const vector signed short *, int, const int);
17923 void vec_dst (const vector bool short *, int, const int);
17924 void vec_dst (const vector pixel *, int, const int);
17925 void vec_dst (const vector unsigned int *, int, const int);
17926 void vec_dst (const vector signed int *, int, const int);
17927 void vec_dst (const vector bool int *, int, const int);
17928 void vec_dst (const vector float *, int, const int);
17929 void vec_dst (const unsigned char *, int, const int);
17930 void vec_dst (const signed char *, int, const int);
17931 void vec_dst (const unsigned short *, int, const int);
17932 void vec_dst (const short *, int, const int);
17933 void vec_dst (const unsigned int *, int, const int);
17934 void vec_dst (const int *, int, const int);
17935 void vec_dst (const float *, int, const int);
17937 void vec_dstst (const vector unsigned char *, int, const int);
17938 void vec_dstst (const vector signed char *, int, const int);
17939 void vec_dstst (const vector bool char *, int, const int);
17940 void vec_dstst (const vector unsigned short *, int, const int);
17941 void vec_dstst (const vector signed short *, int, const int);
17942 void vec_dstst (const vector bool short *, int, const int);
17943 void vec_dstst (const vector pixel *, int, const int);
17944 void vec_dstst (const vector unsigned int *, int, const int);
17945 void vec_dstst (const vector signed int *, int, const int);
17946 void vec_dstst (const vector bool int *, int, const int);
17947 void vec_dstst (const vector float *, int, const int);
17948 void vec_dstst (const unsigned char *, int, const int);
17949 void vec_dstst (const signed char *, int, const int);
17950 void vec_dstst (const unsigned short *, int, const int);
17951 void vec_dstst (const short *, int, const int);
17952 void vec_dstst (const unsigned int *, int, const int);
17953 void vec_dstst (const int *, int, const int);
17954 void vec_dstst (const unsigned long *, int, const int);
17955 void vec_dstst (const long *, int, const int);
17956 void vec_dstst (const float *, int, const int);
17958 void vec_dststt (const vector unsigned char *, int, const int);
17959 void vec_dststt (const vector signed char *, int, const int);
17960 void vec_dststt (const vector bool char *, int, const int);
17961 void vec_dststt (const vector unsigned short *, int, const int);
17962 void vec_dststt (const vector signed short *, int, const int);
17963 void vec_dststt (const vector bool short *, int, const int);
17964 void vec_dststt (const vector pixel *, int, const int);
17965 void vec_dststt (const vector unsigned int *, int, const int);
17966 void vec_dststt (const vector signed int *, int, const int);
17967 void vec_dststt (const vector bool int *, int, const int);
17968 void vec_dststt (const vector float *, int, const int);
17969 void vec_dststt (const unsigned char *, int, const int);
17970 void vec_dststt (const signed char *, int, const int);
17971 void vec_dststt (const unsigned short *, int, const int);
17972 void vec_dststt (const short *, int, const int);
17973 void vec_dststt (const unsigned int *, int, const int);
17974 void vec_dststt (const int *, int, const int);
17975 void vec_dststt (const float *, int, const int);
17977 void vec_dstt (const vector unsigned char *, int, const int);
17978 void vec_dstt (const vector signed char *, int, const int);
17979 void vec_dstt (const vector bool char *, int, const int);
17980 void vec_dstt (const vector unsigned short *, int, const int);
17981 void vec_dstt (const vector signed short *, int, const int);
17982 void vec_dstt (const vector bool short *, int, const int);
17983 void vec_dstt (const vector pixel *, int, const int);
17984 void vec_dstt (const vector unsigned int *, int, const int);
17985 void vec_dstt (const vector signed int *, int, const int);
17986 void vec_dstt (const vector bool int *, int, const int);
17987 void vec_dstt (const vector float *, int, const int);
17988 void vec_dstt (const unsigned char *, int, const int);
17989 void vec_dstt (const signed char *, int, const int);
17990 void vec_dstt (const unsigned short *, int, const int);
17991 void vec_dstt (const short *, int, const int);
17992 void vec_dstt (const unsigned int *, int, const int);
17993 void vec_dstt (const int *, int, const int);
17994 void vec_dstt (const float *, int, const int);
17996 vector float vec_expte (vector float);
17998 vector float vec_floor (vector float);
18000 vector float vec_ld (int, const vector float *);
18001 vector float vec_ld (int, const float *);
18002 vector bool int vec_ld (int, const vector bool int *);
18003 vector signed int vec_ld (int, const vector signed int *);
18004 vector signed int vec_ld (int, const int *);
18005 vector unsigned int vec_ld (int, const vector unsigned int *);
18006 vector unsigned int vec_ld (int, const unsigned int *);
18007 vector bool short vec_ld (int, const vector bool short *);
18008 vector pixel vec_ld (int, const vector pixel *);
18009 vector signed short vec_ld (int, const vector signed short *);
18010 vector signed short vec_ld (int, const short *);
18011 vector unsigned short vec_ld (int, const vector unsigned short *);
18012 vector unsigned short vec_ld (int, const unsigned short *);
18013 vector bool char vec_ld (int, const vector bool char *);
18014 vector signed char vec_ld (int, const vector signed char *);
18015 vector signed char vec_ld (int, const signed char *);
18016 vector unsigned char vec_ld (int, const vector unsigned char *);
18017 vector unsigned char vec_ld (int, const unsigned char *);
18019 vector signed char vec_lde (int, const signed char *);
18020 vector unsigned char vec_lde (int, const unsigned char *);
18021 vector signed short vec_lde (int, const short *);
18022 vector unsigned short vec_lde (int, const unsigned short *);
18023 vector float vec_lde (int, const float *);
18024 vector signed int vec_lde (int, const int *);
18025 vector unsigned int vec_lde (int, const unsigned int *);
18027 vector float vec_ldl (int, const vector float *);
18028 vector float vec_ldl (int, const float *);
18029 vector bool int vec_ldl (int, const vector bool int *);
18030 vector signed int vec_ldl (int, const vector signed int *);
18031 vector signed int vec_ldl (int, const int *);
18032 vector unsigned int vec_ldl (int, const vector unsigned int *);
18033 vector unsigned int vec_ldl (int, const unsigned int *);
18034 vector bool short vec_ldl (int, const vector bool short *);
18035 vector pixel vec_ldl (int, const vector pixel *);
18036 vector signed short vec_ldl (int, const vector signed short *);
18037 vector signed short vec_ldl (int, const short *);
18038 vector unsigned short vec_ldl (int, const vector unsigned short *);
18039 vector unsigned short vec_ldl (int, const unsigned short *);
18040 vector bool char vec_ldl (int, const vector bool char *);
18041 vector signed char vec_ldl (int, const vector signed char *);
18042 vector signed char vec_ldl (int, const signed char *);
18043 vector unsigned char vec_ldl (int, const vector unsigned char *);
18044 vector unsigned char vec_ldl (int, const unsigned char *);
18046 vector float vec_loge (vector float);
18048 vector signed char vec_lvebx (int, char *);
18049 vector unsigned char vec_lvebx (int, unsigned char *);
18051 vector signed short vec_lvehx (int, short *);
18052 vector unsigned short vec_lvehx (int, unsigned short *);
18054 vector float vec_lvewx (int, float *);
18055 vector signed int vec_lvewx (int, int *);
18056 vector unsigned int vec_lvewx (int, unsigned int *);
18058 vector unsigned char vec_lvsl (int, const unsigned char *);
18059 vector unsigned char vec_lvsl (int, const signed char *);
18060 vector unsigned char vec_lvsl (int, const unsigned short *);
18061 vector unsigned char vec_lvsl (int, const short *);
18062 vector unsigned char vec_lvsl (int, const unsigned int *);
18063 vector unsigned char vec_lvsl (int, const int *);
18064 vector unsigned char vec_lvsl (int, const float *);
18066 vector unsigned char vec_lvsr (int, const unsigned char *);
18067 vector unsigned char vec_lvsr (int, const signed char *);
18068 vector unsigned char vec_lvsr (int, const unsigned short *);
18069 vector unsigned char vec_lvsr (int, const short *);
18070 vector unsigned char vec_lvsr (int, const unsigned int *);
18071 vector unsigned char vec_lvsr (int, const int *);
18072 vector unsigned char vec_lvsr (int, const float *);
18074 vector float vec_madd (vector float, vector float, vector float);
18076 vector signed short vec_madds (vector signed short, vector signed short,
18077 vector signed short);
18079 vector unsigned char vec_max (vector bool char, vector unsigned char);
18080 vector unsigned char vec_max (vector unsigned char, vector bool char);
18081 vector unsigned char vec_max (vector unsigned char, vector unsigned char);
18082 vector signed char vec_max (vector bool char, vector signed char);
18083 vector signed char vec_max (vector signed char, vector bool char);
18084 vector signed char vec_max (vector signed char, vector signed char);
18085 vector unsigned short vec_max (vector bool short, vector unsigned short);
18086 vector unsigned short vec_max (vector unsigned short, vector bool short);
18087 vector unsigned short vec_max (vector unsigned short, vector unsigned short);
18088 vector signed short vec_max (vector bool short, vector signed short);
18089 vector signed short vec_max (vector signed short, vector bool short);
18090 vector signed short vec_max (vector signed short, vector signed short);
18091 vector unsigned int vec_max (vector bool int, vector unsigned int);
18092 vector unsigned int vec_max (vector unsigned int, vector bool int);
18093 vector unsigned int vec_max (vector unsigned int, vector unsigned int);
18094 vector signed int vec_max (vector bool int, vector signed int);
18095 vector signed int vec_max (vector signed int, vector bool int);
18096 vector signed int vec_max (vector signed int, vector signed int);
18097 vector float vec_max (vector float, vector float);
18099 vector bool char vec_mergeh (vector bool char, vector bool char);
18100 vector signed char vec_mergeh (vector signed char, vector signed char);
18101 vector unsigned char vec_mergeh (vector unsigned char, vector unsigned char);
18102 vector bool short vec_mergeh (vector bool short, vector bool short);
18103 vector pixel vec_mergeh (vector pixel, vector pixel);
18104 vector signed short vec_mergeh (vector signed short, vector signed short);
18105 vector unsigned short vec_mergeh (vector unsigned short, vector unsigned short);
18106 vector float vec_mergeh (vector float, vector float);
18107 vector bool int vec_mergeh (vector bool int, vector bool int);
18108 vector signed int vec_mergeh (vector signed int, vector signed int);
18109 vector unsigned int vec_mergeh (vector unsigned int, vector unsigned int);
18111 vector bool char vec_mergel (vector bool char, vector bool char);
18112 vector signed char vec_mergel (vector signed char, vector signed char);
18113 vector unsigned char vec_mergel (vector unsigned char, vector unsigned char);
18114 vector bool short vec_mergel (vector bool short, vector bool short);
18115 vector pixel vec_mergel (vector pixel, vector pixel);
18116 vector signed short vec_mergel (vector signed short, vector signed short);
18117 vector unsigned short vec_mergel (vector unsigned short, vector unsigned short);
18118 vector float vec_mergel (vector float, vector float);
18119 vector bool int vec_mergel (vector bool int, vector bool int);
18120 vector signed int vec_mergel (vector signed int, vector signed int);
18121 vector unsigned int vec_mergel (vector unsigned int, vector unsigned int);
18123 vector unsigned short vec_mfvscr (void);
18125 vector unsigned char vec_min (vector bool char, vector unsigned char);
18126 vector unsigned char vec_min (vector unsigned char, vector bool char);
18127 vector unsigned char vec_min (vector unsigned char, vector unsigned char);
18128 vector signed char vec_min (vector bool char, vector signed char);
18129 vector signed char vec_min (vector signed char, vector bool char);
18130 vector signed char vec_min (vector signed char, vector signed char);
18131 vector unsigned short vec_min (vector bool short, vector unsigned short);
18132 vector unsigned short vec_min (vector unsigned short, vector bool short);
18133 vector unsigned short vec_min (vector unsigned short, vector unsigned short);
18134 vector signed short vec_min (vector bool short, vector signed short);
18135 vector signed short vec_min (vector signed short, vector bool short);
18136 vector signed short vec_min (vector signed short, vector signed short);
18137 vector unsigned int vec_min (vector bool int, vector unsigned int);
18138 vector unsigned int vec_min (vector unsigned int, vector bool int);
18139 vector unsigned int vec_min (vector unsigned int, vector unsigned int);
18140 vector signed int vec_min (vector bool int, vector signed int);
18141 vector signed int vec_min (vector signed int, vector bool int);
18142 vector signed int vec_min (vector signed int, vector signed int);
18143 vector float vec_min (vector float, vector float);
18145 vector signed short vec_mladd (vector signed short, vector signed short,
18146 vector signed short);
18147 vector signed short vec_mladd (vector signed short, vector unsigned short,
18148 vector unsigned short);
18149 vector signed short vec_mladd (vector unsigned short, vector signed short,
18150 vector signed short);
18151 vector unsigned short vec_mladd (vector unsigned short, vector unsigned short,
18152 vector unsigned short);
18154 vector signed short vec_mradds (vector signed short, vector signed short,
18155 vector signed short);
18157 vector unsigned int vec_msum (vector unsigned char, vector unsigned char,
18158 vector unsigned int);
18159 vector signed int vec_msum (vector signed char, vector unsigned char,
18160 vector signed int);
18161 vector unsigned int vec_msum (vector unsigned short, vector unsigned short,
18162 vector unsigned int);
18163 vector signed int vec_msum (vector signed short, vector signed short,
18164 vector signed int);
18166 vector unsigned int vec_msums (vector unsigned short, vector unsigned short,
18167 vector unsigned int);
18168 vector signed int vec_msums (vector signed short, vector signed short,
18169 vector signed int);
18171 void vec_mtvscr (vector signed int);
18172 void vec_mtvscr (vector unsigned int);
18173 void vec_mtvscr (vector bool int);
18174 void vec_mtvscr (vector signed short);
18175 void vec_mtvscr (vector unsigned short);
18176 void vec_mtvscr (vector bool short);
18177 void vec_mtvscr (vector pixel);
18178 void vec_mtvscr (vector signed char);
18179 void vec_mtvscr (vector unsigned char);
18180 void vec_mtvscr (vector bool char);
18182 vector float vec_mul (vector float, vector float);
18184 vector unsigned short vec_mule (vector unsigned char, vector unsigned char);
18185 vector signed short vec_mule (vector signed char, vector signed char);
18186 vector unsigned int vec_mule (vector unsigned short, vector unsigned short);
18187 vector signed int vec_mule (vector signed short, vector signed short);
18189 vector unsigned short vec_mulo (vector unsigned char, vector unsigned char);
18190 vector signed short vec_mulo (vector signed char, vector signed char);
18191 vector unsigned int vec_mulo (vector unsigned short, vector unsigned short);
18192 vector signed int vec_mulo (vector signed short, vector signed short);
18194 vector signed char vec_nabs (vector signed char);
18195 vector signed short vec_nabs (vector signed short);
18196 vector signed int vec_nabs (vector signed int);
18197 vector float vec_nabs (vector float);
18199 vector float vec_nmsub (vector float, vector float, vector float);
18201 vector float vec_nor (vector float, vector float);
18202 vector signed int vec_nor (vector signed int, vector signed int);
18203 vector unsigned int vec_nor (vector unsigned int, vector unsigned int);
18204 vector bool int vec_nor (vector bool int, vector bool int);
18205 vector signed short vec_nor (vector signed short, vector signed short);
18206 vector unsigned short vec_nor (vector unsigned short, vector unsigned short);
18207 vector bool short vec_nor (vector bool short, vector bool short);
18208 vector signed char vec_nor (vector signed char, vector signed char);
18209 vector unsigned char vec_nor (vector unsigned char, vector unsigned char);
18210 vector bool char vec_nor (vector bool char, vector bool char);
18212 vector float vec_or (vector float, vector float);
18213 vector float vec_or (vector float, vector bool int);
18214 vector float vec_or (vector bool int, vector float);
18215 vector bool int vec_or (vector bool int, vector bool int);
18216 vector signed int vec_or (vector bool int, vector signed int);
18217 vector signed int vec_or (vector signed int, vector bool int);
18218 vector signed int vec_or (vector signed int, vector signed int);
18219 vector unsigned int vec_or (vector bool int, vector unsigned int);
18220 vector unsigned int vec_or (vector unsigned int, vector bool int);
18221 vector unsigned int vec_or (vector unsigned int, vector unsigned int);
18222 vector bool short vec_or (vector bool short, vector bool short);
18223 vector signed short vec_or (vector bool short, vector signed short);
18224 vector signed short vec_or (vector signed short, vector bool short);
18225 vector signed short vec_or (vector signed short, vector signed short);
18226 vector unsigned short vec_or (vector bool short, vector unsigned short);
18227 vector unsigned short vec_or (vector unsigned short, vector bool short);
18228 vector unsigned short vec_or (vector unsigned short, vector unsigned short);
18229 vector signed char vec_or (vector bool char, vector signed char);
18230 vector bool char vec_or (vector bool char, vector bool char);
18231 vector signed char vec_or (vector signed char, vector bool char);
18232 vector signed char vec_or (vector signed char, vector signed char);
18233 vector unsigned char vec_or (vector bool char, vector unsigned char);
18234 vector unsigned char vec_or (vector unsigned char, vector bool char);
18235 vector unsigned char vec_or (vector unsigned char, vector unsigned char);
18237 vector signed char vec_pack (vector signed short, vector signed short);
18238 vector unsigned char vec_pack (vector unsigned short, vector unsigned short);
18239 vector bool char vec_pack (vector bool short, vector bool short);
18240 vector signed short vec_pack (vector signed int, vector signed int);
18241 vector unsigned short vec_pack (vector unsigned int, vector unsigned int);
18242 vector bool short vec_pack (vector bool int, vector bool int);
18244 vector pixel vec_packpx (vector unsigned int, vector unsigned int);
18246 vector unsigned char vec_packs (vector unsigned short, vector unsigned short);
18247 vector signed char vec_packs (vector signed short, vector signed short);
18248 vector unsigned short vec_packs (vector unsigned int, vector unsigned int);
18249 vector signed short vec_packs (vector signed int, vector signed int);
18251 vector unsigned char vec_packsu (vector unsigned short, vector unsigned short);
18252 vector unsigned char vec_packsu (vector signed short, vector signed short);
18253 vector unsigned short vec_packsu (vector unsigned int, vector unsigned int);
18254 vector unsigned short vec_packsu (vector signed int, vector signed int);
18256 vector float vec_perm (vector float, vector float, vector unsigned char);
18257 vector signed int vec_perm (vector signed int, vector signed int, vector unsigned char);
18258 vector unsigned int vec_perm (vector unsigned int, vector unsigned int,
18259 vector unsigned char);
18260 vector bool int vec_perm (vector bool int, vector bool int, vector unsigned char);
18261 vector signed short vec_perm (vector signed short, vector signed short,
18262 vector unsigned char);
18263 vector unsigned short vec_perm (vector unsigned short, vector unsigned short,
18264 vector unsigned char);
18265 vector bool short vec_perm (vector bool short, vector bool short, vector unsigned char);
18266 vector pixel vec_perm (vector pixel, vector pixel, vector unsigned char);
18267 vector signed char vec_perm (vector signed char, vector signed char,
18268 vector unsigned char);
18269 vector unsigned char vec_perm (vector unsigned char, vector unsigned char,
18270 vector unsigned char);
18271 vector bool char vec_perm (vector bool char, vector bool char, vector unsigned char);
18273 vector float vec_re (vector float);
18275 vector bool char vec_reve (vector bool char);
18276 vector signed char vec_reve (vector signed char);
18277 vector unsigned char vec_reve (vector unsigned char);
18278 vector bool int vec_reve (vector bool int);
18279 vector signed int vec_reve (vector signed int);
18280 vector unsigned int vec_reve (vector unsigned int);
18281 vector bool short vec_reve (vector bool short);
18282 vector signed short vec_reve (vector signed short);
18283 vector unsigned short vec_reve (vector unsigned short);
18285 vector signed char vec_rl (vector signed char, vector unsigned char);
18286 vector unsigned char vec_rl (vector unsigned char, vector unsigned char);
18287 vector signed short vec_rl (vector signed short, vector unsigned short);
18288 vector unsigned short vec_rl (vector unsigned short, vector unsigned short);
18289 vector signed int vec_rl (vector signed int, vector unsigned int);
18290 vector unsigned int vec_rl (vector unsigned int, vector unsigned int);
18292 vector float vec_round (vector float);
18294 vector float vec_rsqrt (vector float);
18296 vector float vec_rsqrte (vector float);
18298 vector float vec_sel (vector float, vector float, vector bool int);
18299 vector float vec_sel (vector float, vector float, vector unsigned int);
18300 vector signed int vec_sel (vector signed int, vector signed int, vector bool int);
18301 vector signed int vec_sel (vector signed int, vector signed int, vector unsigned int);
18302 vector unsigned int vec_sel (vector unsigned int, vector unsigned int, vector bool int);
18303 vector unsigned int vec_sel (vector unsigned int, vector unsigned int,
18304 vector unsigned int);
18305 vector bool int vec_sel (vector bool int, vector bool int, vector bool int);
18306 vector bool int vec_sel (vector bool int, vector bool int, vector unsigned int);
18307 vector signed short vec_sel (vector signed short, vector signed short,
18308 vector bool short);
18309 vector signed short vec_sel (vector signed short, vector signed short,
18310 vector unsigned short);
18311 vector unsigned short vec_sel (vector unsigned short, vector unsigned short,
18312 vector bool short);
18313 vector unsigned short vec_sel (vector unsigned short, vector unsigned short,
18314 vector unsigned short);
18315 vector bool short vec_sel (vector bool short, vector bool short, vector bool short);
18316 vector bool short vec_sel (vector bool short, vector bool short, vector unsigned short);
18317 vector signed char vec_sel (vector signed char, vector signed char, vector bool char);
18318 vector signed char vec_sel (vector signed char, vector signed char,
18319 vector unsigned char);
18320 vector unsigned char vec_sel (vector unsigned char, vector unsigned char,
18322 vector unsigned char vec_sel (vector unsigned char, vector unsigned char,
18323 vector unsigned char);
18324 vector bool char vec_sel (vector bool char, vector bool char, vector bool char);
18325 vector bool char vec_sel (vector bool char, vector bool char, vector unsigned char);
18327 vector signed char vec_sl (vector signed char, vector unsigned char);
18328 vector unsigned char vec_sl (vector unsigned char, vector unsigned char);
18329 vector signed short vec_sl (vector signed short, vector unsigned short);
18330 vector unsigned short vec_sl (vector unsigned short, vector unsigned short);
18331 vector signed int vec_sl (vector signed int, vector unsigned int);
18332 vector unsigned int vec_sl (vector unsigned int, vector unsigned int);
18334 vector float vec_sld (vector float, vector float, const int);
18335 vector signed int vec_sld (vector signed int, vector signed int, const int);
18336 vector unsigned int vec_sld (vector unsigned int, vector unsigned int, const int);
18337 vector bool int vec_sld (vector bool int, vector bool int, const int);
18338 vector signed short vec_sld (vector signed short, vector signed short, const int);
18339 vector unsigned short vec_sld (vector unsigned short, vector unsigned short, const int);
18340 vector bool short vec_sld (vector bool short, vector bool short, const int);
18341 vector pixel vec_sld (vector pixel, vector pixel, const int);
18342 vector signed char vec_sld (vector signed char, vector signed char, const int);
18343 vector unsigned char vec_sld (vector unsigned char, vector unsigned char, const int);
18344 vector bool char vec_sld (vector bool char, vector bool char, const int);
18346 vector signed int vec_sll (vector signed int, vector unsigned int);
18347 vector signed int vec_sll (vector signed int, vector unsigned short);
18348 vector signed int vec_sll (vector signed int, vector unsigned char);
18349 vector unsigned int vec_sll (vector unsigned int, vector unsigned int);
18350 vector unsigned int vec_sll (vector unsigned int, vector unsigned short);
18351 vector unsigned int vec_sll (vector unsigned int, vector unsigned char);
18352 vector bool int vec_sll (vector bool int, vector unsigned int);
18353 vector bool int vec_sll (vector bool int, vector unsigned short);
18354 vector bool int vec_sll (vector bool int, vector unsigned char);
18355 vector signed short vec_sll (vector signed short, vector unsigned int);
18356 vector signed short vec_sll (vector signed short, vector unsigned short);
18357 vector signed short vec_sll (vector signed short, vector unsigned char);
18358 vector unsigned short vec_sll (vector unsigned short, vector unsigned int);
18359 vector unsigned short vec_sll (vector unsigned short, vector unsigned short);
18360 vector unsigned short vec_sll (vector unsigned short, vector unsigned char);
18361 vector bool short vec_sll (vector bool short, vector unsigned int);
18362 vector bool short vec_sll (vector bool short, vector unsigned short);
18363 vector bool short vec_sll (vector bool short, vector unsigned char);
18364 vector pixel vec_sll (vector pixel, vector unsigned int);
18365 vector pixel vec_sll (vector pixel, vector unsigned short);
18366 vector pixel vec_sll (vector pixel, vector unsigned char);
18367 vector signed char vec_sll (vector signed char, vector unsigned int);
18368 vector signed char vec_sll (vector signed char, vector unsigned short);
18369 vector signed char vec_sll (vector signed char, vector unsigned char);
18370 vector unsigned char vec_sll (vector unsigned char, vector unsigned int);
18371 vector unsigned char vec_sll (vector unsigned char, vector unsigned short);
18372 vector unsigned char vec_sll (vector unsigned char, vector unsigned char);
18373 vector bool char vec_sll (vector bool char, vector unsigned int);
18374 vector bool char vec_sll (vector bool char, vector unsigned short);
18375 vector bool char vec_sll (vector bool char, vector unsigned char);
18377 vector float vec_slo (vector float, vector signed char);
18378 vector float vec_slo (vector float, vector unsigned char);
18379 vector signed int vec_slo (vector signed int, vector signed char);
18380 vector signed int vec_slo (vector signed int, vector unsigned char);
18381 vector unsigned int vec_slo (vector unsigned int, vector signed char);
18382 vector unsigned int vec_slo (vector unsigned int, vector unsigned char);
18383 vector signed short vec_slo (vector signed short, vector signed char);
18384 vector signed short vec_slo (vector signed short, vector unsigned char);
18385 vector unsigned short vec_slo (vector unsigned short, vector signed char);
18386 vector unsigned short vec_slo (vector unsigned short, vector unsigned char);
18387 vector pixel vec_slo (vector pixel, vector signed char);
18388 vector pixel vec_slo (vector pixel, vector unsigned char);
18389 vector signed char vec_slo (vector signed char, vector signed char);
18390 vector signed char vec_slo (vector signed char, vector unsigned char);
18391 vector unsigned char vec_slo (vector unsigned char, vector signed char);
18392 vector unsigned char vec_slo (vector unsigned char, vector unsigned char);
18394 vector signed char vec_splat (vector signed char, const int);
18395 vector unsigned char vec_splat (vector unsigned char, const int);
18396 vector bool char vec_splat (vector bool char, const int);
18397 vector signed short vec_splat (vector signed short, const int);
18398 vector unsigned short vec_splat (vector unsigned short, const int);
18399 vector bool short vec_splat (vector bool short, const int);
18400 vector pixel vec_splat (vector pixel, const int);
18401 vector float vec_splat (vector float, const int);
18402 vector signed int vec_splat (vector signed int, const int);
18403 vector unsigned int vec_splat (vector unsigned int, const int);
18404 vector bool int vec_splat (vector bool int, const int);
18406 vector signed short vec_splat_s16 (const int);
18408 vector signed int vec_splat_s32 (const int);
18410 vector signed char vec_splat_s8 (const int);
18412 vector unsigned short vec_splat_u16 (const int);
18414 vector unsigned int vec_splat_u32 (const int);
18416 vector unsigned char vec_splat_u8 (const int);
18418 vector signed char vec_splats (signed char);
18419 vector unsigned char vec_splats (unsigned char);
18420 vector signed short vec_splats (signed short);
18421 vector unsigned short vec_splats (unsigned short);
18422 vector signed int vec_splats (signed int);
18423 vector unsigned int vec_splats (unsigned int);
18424 vector float vec_splats (float);
18426 vector signed char vec_sr (vector signed char, vector unsigned char);
18427 vector unsigned char vec_sr (vector unsigned char, vector unsigned char);
18428 vector signed short vec_sr (vector signed short, vector unsigned short);
18429 vector unsigned short vec_sr (vector unsigned short, vector unsigned short);
18430 vector signed int vec_sr (vector signed int, vector unsigned int);
18431 vector unsigned int vec_sr (vector unsigned int, vector unsigned int);
18433 vector signed char vec_sra (vector signed char, vector unsigned char);
18434 vector unsigned char vec_sra (vector unsigned char, vector unsigned char);
18435 vector signed short vec_sra (vector signed short, vector unsigned short);
18436 vector unsigned short vec_sra (vector unsigned short, vector unsigned short);
18437 vector signed int vec_sra (vector signed int, vector unsigned int);
18438 vector unsigned int vec_sra (vector unsigned int, vector unsigned int);
18440 vector signed int vec_srl (vector signed int, vector unsigned int);
18441 vector signed int vec_srl (vector signed int, vector unsigned short);
18442 vector signed int vec_srl (vector signed int, vector unsigned char);
18443 vector unsigned int vec_srl (vector unsigned int, vector unsigned int);
18444 vector unsigned int vec_srl (vector unsigned int, vector unsigned short);
18445 vector unsigned int vec_srl (vector unsigned int, vector unsigned char);
18446 vector bool int vec_srl (vector bool int, vector unsigned int);
18447 vector bool int vec_srl (vector bool int, vector unsigned short);
18448 vector bool int vec_srl (vector bool int, vector unsigned char);
18449 vector signed short vec_srl (vector signed short, vector unsigned int);
18450 vector signed short vec_srl (vector signed short, vector unsigned short);
18451 vector signed short vec_srl (vector signed short, vector unsigned char);
18452 vector unsigned short vec_srl (vector unsigned short, vector unsigned int);
18453 vector unsigned short vec_srl (vector unsigned short, vector unsigned short);
18454 vector unsigned short vec_srl (vector unsigned short, vector unsigned char);
18455 vector bool short vec_srl (vector bool short, vector unsigned int);
18456 vector bool short vec_srl (vector bool short, vector unsigned short);
18457 vector bool short vec_srl (vector bool short, vector unsigned char);
18458 vector pixel vec_srl (vector pixel, vector unsigned int);
18459 vector pixel vec_srl (vector pixel, vector unsigned short);
18460 vector pixel vec_srl (vector pixel, vector unsigned char);
18461 vector signed char vec_srl (vector signed char, vector unsigned int);
18462 vector signed char vec_srl (vector signed char, vector unsigned short);
18463 vector signed char vec_srl (vector signed char, vector unsigned char);
18464 vector unsigned char vec_srl (vector unsigned char, vector unsigned int);
18465 vector unsigned char vec_srl (vector unsigned char, vector unsigned short);
18466 vector unsigned char vec_srl (vector unsigned char, vector unsigned char);
18467 vector bool char vec_srl (vector bool char, vector unsigned int);
18468 vector bool char vec_srl (vector bool char, vector unsigned short);
18469 vector bool char vec_srl (vector bool char, vector unsigned char);
18471 vector float vec_sro (vector float, vector signed char);
18472 vector float vec_sro (vector float, vector unsigned char);
18473 vector signed int vec_sro (vector signed int, vector signed char);
18474 vector signed int vec_sro (vector signed int, vector unsigned char);
18475 vector unsigned int vec_sro (vector unsigned int, vector signed char);
18476 vector unsigned int vec_sro (vector unsigned int, vector unsigned char);
18477 vector signed short vec_sro (vector signed short, vector signed char);
18478 vector signed short vec_sro (vector signed short, vector unsigned char);
18479 vector unsigned short vec_sro (vector unsigned short, vector signed char);
18480 vector unsigned short vec_sro (vector unsigned short, vector unsigned char);
18481 vector pixel vec_sro (vector pixel, vector signed char);
18482 vector pixel vec_sro (vector pixel, vector unsigned char);
18483 vector signed char vec_sro (vector signed char, vector signed char);
18484 vector signed char vec_sro (vector signed char, vector unsigned char);
18485 vector unsigned char vec_sro (vector unsigned char, vector signed char);
18486 vector unsigned char vec_sro (vector unsigned char, vector unsigned char);
18488 void vec_st (vector float, int, vector float *);
18489 void vec_st (vector float, int, float *);
18490 void vec_st (vector signed int, int, vector signed int *);
18491 void vec_st (vector signed int, int, int *);
18492 void vec_st (vector unsigned int, int, vector unsigned int *);
18493 void vec_st (vector unsigned int, int, unsigned int *);
18494 void vec_st (vector bool int, int, vector bool int *);
18495 void vec_st (vector bool int, int, unsigned int *);
18496 void vec_st (vector bool int, int, int *);
18497 void vec_st (vector signed short, int, vector signed short *);
18498 void vec_st (vector signed short, int, short *);
18499 void vec_st (vector unsigned short, int, vector unsigned short *);
18500 void vec_st (vector unsigned short, int, unsigned short *);
18501 void vec_st (vector bool short, int, vector bool short *);
18502 void vec_st (vector bool short, int, unsigned short *);
18503 void vec_st (vector pixel, int, vector pixel *);
18504 void vec_st (vector bool short, int, short *);
18505 void vec_st (vector signed char, int, vector signed char *);
18506 void vec_st (vector signed char, int, signed char *);
18507 void vec_st (vector unsigned char, int, vector unsigned char *);
18508 void vec_st (vector unsigned char, int, unsigned char *);
18509 void vec_st (vector bool char, int, vector bool char *);
18510 void vec_st (vector bool char, int, unsigned char *);
18511 void vec_st (vector bool char, int, signed char *);
18513 void vec_ste (vector signed char, int, signed char *);
18514 void vec_ste (vector unsigned char, int, unsigned char *);
18515 void vec_ste (vector bool char, int, signed char *);
18516 void vec_ste (vector bool char, int, unsigned char *);
18517 void vec_ste (vector signed short, int, short *);
18518 void vec_ste (vector unsigned short, int, unsigned short *);
18519 void vec_ste (vector bool short, int, short *);
18520 void vec_ste (vector bool short, int, unsigned short *);
18521 void vec_ste (vector pixel, int, short *);
18522 void vec_ste (vector pixel, int, unsigned short *);
18523 void vec_ste (vector float, int, float *);
18524 void vec_ste (vector signed int, int, int *);
18525 void vec_ste (vector unsigned int, int, unsigned int *);
18526 void vec_ste (vector bool int, int, int *);
18527 void vec_ste (vector bool int, int, unsigned int *);
18529 void vec_stl (vector float, int, vector float *);
18530 void vec_stl (vector float, int, float *);
18531 void vec_stl (vector signed int, int, vector signed int *);
18532 void vec_stl (vector signed int, int, int *);
18533 void vec_stl (vector unsigned int, int, vector unsigned int *);
18534 void vec_stl (vector unsigned int, int, unsigned int *);
18535 void vec_stl (vector bool int, int, vector bool int *);
18536 void vec_stl (vector bool int, int, unsigned int *);
18537 void vec_stl (vector bool int, int, int *);
18538 void vec_stl (vector signed short, int, vector signed short *);
18539 void vec_stl (vector signed short, int, short *);
18540 void vec_stl (vector unsigned short, int, vector unsigned short *);
18541 void vec_stl (vector unsigned short, int, unsigned short *);
18542 void vec_stl (vector bool short, int, vector bool short *);
18543 void vec_stl (vector bool short, int, unsigned short *);
18544 void vec_stl (vector bool short, int, short *);
18545 void vec_stl (vector pixel, int, vector pixel *);
18546 void vec_stl (vector signed char, int, vector signed char *);
18547 void vec_stl (vector signed char, int, signed char *);
18548 void vec_stl (vector unsigned char, int, vector unsigned char *);
18549 void vec_stl (vector unsigned char, int, unsigned char *);
18550 void vec_stl (vector bool char, int, vector bool char *);
18551 void vec_stl (vector bool char, int, unsigned char *);
18552 void vec_stl (vector bool char, int, signed char *);
18554 void vec_stvebx (vector signed char, int, signed char *);
18555 void vec_stvebx (vector unsigned char, int, unsigned char *);
18556 void vec_stvebx (vector bool char, int, signed char *);
18557 void vec_stvebx (vector bool char, int, unsigned char *);
18559 void vec_stvehx (vector signed short, int, short *);
18560 void vec_stvehx (vector unsigned short, int, unsigned short *);
18561 void vec_stvehx (vector bool short, int, short *);
18562 void vec_stvehx (vector bool short, int, unsigned short *);
18564 void vec_stvewx (vector float, int, float *);
18565 void vec_stvewx (vector signed int, int, int *);
18566 void vec_stvewx (vector unsigned int, int, unsigned int *);
18567 void vec_stvewx (vector bool int, int, int *);
18568 void vec_stvewx (vector bool int, int, unsigned int *);
18570 vector signed char vec_sub (vector bool char, vector signed char);
18571 vector signed char vec_sub (vector signed char, vector bool char);
18572 vector signed char vec_sub (vector signed char, vector signed char);
18573 vector unsigned char vec_sub (vector bool char, vector unsigned char);
18574 vector unsigned char vec_sub (vector unsigned char, vector bool char);
18575 vector unsigned char vec_sub (vector unsigned char, vector unsigned char);
18576 vector signed short vec_sub (vector bool short, vector signed short);
18577 vector signed short vec_sub (vector signed short, vector bool short);
18578 vector signed short vec_sub (vector signed short, vector signed short);
18579 vector unsigned short vec_sub (vector bool short, vector unsigned short);
18580 vector unsigned short vec_sub (vector unsigned short, vector bool short);
18581 vector unsigned short vec_sub (vector unsigned short, vector unsigned short);
18582 vector signed int vec_sub (vector bool int, vector signed int);
18583 vector signed int vec_sub (vector signed int, vector bool int);
18584 vector signed int vec_sub (vector signed int, vector signed int);
18585 vector unsigned int vec_sub (vector bool int, vector unsigned int);
18586 vector unsigned int vec_sub (vector unsigned int, vector bool int);
18587 vector unsigned int vec_sub (vector unsigned int, vector unsigned int);
18588 vector float vec_sub (vector float, vector float);
18590 vector signed int vec_subc (vector signed int, vector signed int);
18591 vector unsigned int vec_subc (vector unsigned int, vector unsigned int);
18593 vector signed int vec_sube (vector signed int, vector signed int,
18594 vector signed int);
18595 vector unsigned int vec_sube (vector unsigned int, vector unsigned int,
18596 vector unsigned int);
18598 vector signed int vec_subec (vector signed int, vector signed int,
18599 vector signed int);
18600 vector unsigned int vec_subec (vector unsigned int, vector unsigned int,
18601 vector unsigned int);
18603 vector unsigned char vec_subs (vector bool char, vector unsigned char);
18604 vector unsigned char vec_subs (vector unsigned char, vector bool char);
18605 vector unsigned char vec_subs (vector unsigned char, vector unsigned char);
18606 vector signed char vec_subs (vector bool char, vector signed char);
18607 vector signed char vec_subs (vector signed char, vector bool char);
18608 vector signed char vec_subs (vector signed char, vector signed char);
18609 vector unsigned short vec_subs (vector bool short, vector unsigned short);
18610 vector unsigned short vec_subs (vector unsigned short, vector bool short);
18611 vector unsigned short vec_subs (vector unsigned short, vector unsigned short);
18612 vector signed short vec_subs (vector bool short, vector signed short);
18613 vector signed short vec_subs (vector signed short, vector bool short);
18614 vector signed short vec_subs (vector signed short, vector signed short);
18615 vector unsigned int vec_subs (vector bool int, vector unsigned int);
18616 vector unsigned int vec_subs (vector unsigned int, vector bool int);
18617 vector unsigned int vec_subs (vector unsigned int, vector unsigned int);
18618 vector signed int vec_subs (vector bool int, vector signed int);
18619 vector signed int vec_subs (vector signed int, vector bool int);
18620 vector signed int vec_subs (vector signed int, vector signed int);
18622 vector signed int vec_sum2s (vector signed int, vector signed int);
18624 vector unsigned int vec_sum4s (vector unsigned char, vector unsigned int);
18625 vector signed int vec_sum4s (vector signed char, vector signed int);
18626 vector signed int vec_sum4s (vector signed short, vector signed int);
18628 vector signed int vec_sums (vector signed int, vector signed int);
18630 vector float vec_trunc (vector float);
18632 vector signed short vec_unpackh (vector signed char);
18633 vector bool short vec_unpackh (vector bool char);
18634 vector signed int vec_unpackh (vector signed short);
18635 vector bool int vec_unpackh (vector bool short);
18636 vector unsigned int vec_unpackh (vector pixel);
18638 vector signed short vec_unpackl (vector signed char);
18639 vector bool short vec_unpackl (vector bool char);
18640 vector unsigned int vec_unpackl (vector pixel);
18641 vector signed int vec_unpackl (vector signed short);
18642 vector bool int vec_unpackl (vector bool short);
18644 vector float vec_vaddfp (vector float, vector float);
18646 vector signed char vec_vaddsbs (vector bool char, vector signed char);
18647 vector signed char vec_vaddsbs (vector signed char, vector bool char);
18648 vector signed char vec_vaddsbs (vector signed char, vector signed char);
18650 vector signed short vec_vaddshs (vector bool short, vector signed short);
18651 vector signed short vec_vaddshs (vector signed short, vector bool short);
18652 vector signed short vec_vaddshs (vector signed short, vector signed short);
18654 vector signed int vec_vaddsws (vector bool int, vector signed int);
18655 vector signed int vec_vaddsws (vector signed int, vector bool int);
18656 vector signed int vec_vaddsws (vector signed int, vector signed int);
18658 vector signed char vec_vaddubm (vector bool char, vector signed char);
18659 vector signed char vec_vaddubm (vector signed char, vector bool char);
18660 vector signed char vec_vaddubm (vector signed char, vector signed char);
18661 vector unsigned char vec_vaddubm (vector bool char, vector unsigned char);
18662 vector unsigned char vec_vaddubm (vector unsigned char, vector bool char);
18663 vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char);
18665 vector unsigned char vec_vaddubs (vector bool char, vector unsigned char);
18666 vector unsigned char vec_vaddubs (vector unsigned char, vector bool char);
18667 vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char);
18669 vector signed short vec_vadduhm (vector bool short, vector signed short);
18670 vector signed short vec_vadduhm (vector signed short, vector bool short);
18671 vector signed short vec_vadduhm (vector signed short, vector signed short);
18672 vector unsigned short vec_vadduhm (vector bool short, vector unsigned short);
18673 vector unsigned short vec_vadduhm (vector unsigned short, vector bool short);
18674 vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short);
18676 vector unsigned short vec_vadduhs (vector bool short, vector unsigned short);
18677 vector unsigned short vec_vadduhs (vector unsigned short, vector bool short);
18678 vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short);
18680 vector signed int vec_vadduwm (vector bool int, vector signed int);
18681 vector signed int vec_vadduwm (vector signed int, vector bool int);
18682 vector signed int vec_vadduwm (vector signed int, vector signed int);
18683 vector unsigned int vec_vadduwm (vector bool int, vector unsigned int);
18684 vector unsigned int vec_vadduwm (vector unsigned int, vector bool int);
18685 vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int);
18687 vector unsigned int vec_vadduws (vector bool int, vector unsigned int);
18688 vector unsigned int vec_vadduws (vector unsigned int, vector bool int);
18689 vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int);
18691 vector signed char vec_vavgsb (vector signed char, vector signed char);
18693 vector signed short vec_vavgsh (vector signed short, vector signed short);
18695 vector signed int vec_vavgsw (vector signed int, vector signed int);
18697 vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char);
18699 vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short);
18701 vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int);
18703 vector float vec_vcfsx (vector signed int, const int);
18705 vector float vec_vcfux (vector unsigned int, const int);
18707 vector bool int vec_vcmpeqfp (vector float, vector float);
18709 vector bool char vec_vcmpequb (vector signed char, vector signed char);
18710 vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char);
18712 vector bool short vec_vcmpequh (vector signed short, vector signed short);
18713 vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short);
18715 vector bool int vec_vcmpequw (vector signed int, vector signed int);
18716 vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int);
18718 vector bool int vec_vcmpgtfp (vector float, vector float);
18720 vector bool char vec_vcmpgtsb (vector signed char, vector signed char);
18722 vector bool short vec_vcmpgtsh (vector signed short, vector signed short);
18724 vector bool int vec_vcmpgtsw (vector signed int, vector signed int);
18726 vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char);
18728 vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short);
18730 vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int);
18732 vector float vec_vmaxfp (vector float, vector float);
18734 vector signed char vec_vmaxsb (vector bool char, vector signed char);
18735 vector signed char vec_vmaxsb (vector signed char, vector bool char);
18736 vector signed char vec_vmaxsb (vector signed char, vector signed char);
18738 vector signed short vec_vmaxsh (vector bool short, vector signed short);
18739 vector signed short vec_vmaxsh (vector signed short, vector bool short);
18740 vector signed short vec_vmaxsh (vector signed short, vector signed short);
18742 vector signed int vec_vmaxsw (vector bool int, vector signed int);
18743 vector signed int vec_vmaxsw (vector signed int, vector bool int);
18744 vector signed int vec_vmaxsw (vector signed int, vector signed int);
18746 vector unsigned char vec_vmaxub (vector bool char, vector unsigned char);
18747 vector unsigned char vec_vmaxub (vector unsigned char, vector bool char);
18748 vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char);
18750 vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short);
18751 vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short);
18752 vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short);
18754 vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int);
18755 vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int);
18756 vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int);
18758 vector float vec_vminfp (vector float, vector float);
18760 vector signed char vec_vminsb (vector bool char, vector signed char);
18761 vector signed char vec_vminsb (vector signed char, vector bool char);
18762 vector signed char vec_vminsb (vector signed char, vector signed char);
18764 vector signed short vec_vminsh (vector bool short, vector signed short);
18765 vector signed short vec_vminsh (vector signed short, vector bool short);
18766 vector signed short vec_vminsh (vector signed short, vector signed short);
18768 vector signed int vec_vminsw (vector bool int, vector signed int);
18769 vector signed int vec_vminsw (vector signed int, vector bool int);
18770 vector signed int vec_vminsw (vector signed int, vector signed int);
18772 vector unsigned char vec_vminub (vector bool char, vector unsigned char);
18773 vector unsigned char vec_vminub (vector unsigned char, vector bool char);
18774 vector unsigned char vec_vminub (vector unsigned char, vector unsigned char);
18776 vector unsigned short vec_vminuh (vector bool short, vector unsigned short);
18777 vector unsigned short vec_vminuh (vector unsigned short, vector bool short);
18778 vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short);
18780 vector unsigned int vec_vminuw (vector bool int, vector unsigned int);
18781 vector unsigned int vec_vminuw (vector unsigned int, vector bool int);
18782 vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int);
18784 vector bool char vec_vmrghb (vector bool char, vector bool char);
18785 vector signed char vec_vmrghb (vector signed char, vector signed char);
18786 vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char);
18788 vector bool short vec_vmrghh (vector bool short, vector bool short);
18789 vector signed short vec_vmrghh (vector signed short, vector signed short);
18790 vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short);
18791 vector pixel vec_vmrghh (vector pixel, vector pixel);
18793 vector float vec_vmrghw (vector float, vector float);
18794 vector bool int vec_vmrghw (vector bool int, vector bool int);
18795 vector signed int vec_vmrghw (vector signed int, vector signed int);
18796 vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int);
18798 vector bool char vec_vmrglb (vector bool char, vector bool char);
18799 vector signed char vec_vmrglb (vector signed char, vector signed char);
18800 vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char);
18802 vector bool short vec_vmrglh (vector bool short, vector bool short);
18803 vector signed short vec_vmrglh (vector signed short, vector signed short);
18804 vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short);
18805 vector pixel vec_vmrglh (vector pixel, vector pixel);
18807 vector float vec_vmrglw (vector float, vector float);
18808 vector signed int vec_vmrglw (vector signed int, vector signed int);
18809 vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int);
18810 vector bool int vec_vmrglw (vector bool int, vector bool int);
18812 vector signed int vec_vmsummbm (vector signed char, vector unsigned char,
18813 vector signed int);
18815 vector signed int vec_vmsumshm (vector signed short, vector signed short,
18816 vector signed int);
18818 vector signed int vec_vmsumshs (vector signed short, vector signed short,
18819 vector signed int);
18821 vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char,
18822 vector unsigned int);
18824 vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short,
18825 vector unsigned int);
18827 vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short,
18828 vector unsigned int);
18830 vector signed short vec_vmulesb (vector signed char, vector signed char);
18832 vector signed int vec_vmulesh (vector signed short, vector signed short);
18834 vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char);
18836 vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short);
18838 vector signed short vec_vmulosb (vector signed char, vector signed char);
18840 vector signed int vec_vmulosh (vector signed short, vector signed short);
18842 vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char);
18844 vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short);
18846 vector signed char vec_vpkshss (vector signed short, vector signed short);
18848 vector unsigned char vec_vpkshus (vector signed short, vector signed short);
18850 vector signed short vec_vpkswss (vector signed int, vector signed int);
18852 vector unsigned short vec_vpkswus (vector signed int, vector signed int);
18854 vector bool char vec_vpkuhum (vector bool short, vector bool short);
18855 vector signed char vec_vpkuhum (vector signed short, vector signed short);
18856 vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short);
18858 vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short);
18860 vector bool short vec_vpkuwum (vector bool int, vector bool int);
18861 vector signed short vec_vpkuwum (vector signed int, vector signed int);
18862 vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int);
18864 vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int);
18866 vector signed char vec_vrlb (vector signed char, vector unsigned char);
18867 vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char);
18869 vector signed short vec_vrlh (vector signed short, vector unsigned short);
18870 vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short);
18872 vector signed int vec_vrlw (vector signed int, vector unsigned int);
18873 vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int);
18875 vector signed char vec_vslb (vector signed char, vector unsigned char);
18876 vector unsigned char vec_vslb (vector unsigned char, vector unsigned char);
18878 vector signed short vec_vslh (vector signed short, vector unsigned short);
18879 vector unsigned short vec_vslh (vector unsigned short, vector unsigned short);
18881 vector signed int vec_vslw (vector signed int, vector unsigned int);
18882 vector unsigned int vec_vslw (vector unsigned int, vector unsigned int);
18884 vector signed char vec_vspltb (vector signed char, const int);
18885 vector unsigned char vec_vspltb (vector unsigned char, const int);
18886 vector bool char vec_vspltb (vector bool char, const int);
18888 vector bool short vec_vsplth (vector bool short, const int);
18889 vector signed short vec_vsplth (vector signed short, const int);
18890 vector unsigned short vec_vsplth (vector unsigned short, const int);
18891 vector pixel vec_vsplth (vector pixel, const int);
18893 vector float vec_vspltw (vector float, const int);
18894 vector signed int vec_vspltw (vector signed int, const int);
18895 vector unsigned int vec_vspltw (vector unsigned int, const int);
18896 vector bool int vec_vspltw (vector bool int, const int);
18898 vector signed char vec_vsrab (vector signed char, vector unsigned char);
18899 vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char);
18901 vector signed short vec_vsrah (vector signed short, vector unsigned short);
18902 vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short);
18904 vector signed int vec_vsraw (vector signed int, vector unsigned int);
18905 vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int);
18907 vector signed char vec_vsrb (vector signed char, vector unsigned char);
18908 vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char);
18910 vector signed short vec_vsrh (vector signed short, vector unsigned short);
18911 vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short);
18913 vector signed int vec_vsrw (vector signed int, vector unsigned int);
18914 vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int);
18916 vector float vec_vsubfp (vector float, vector float);
18918 vector signed char vec_vsubsbs (vector bool char, vector signed char);
18919 vector signed char vec_vsubsbs (vector signed char, vector bool char);
18920 vector signed char vec_vsubsbs (vector signed char, vector signed char);
18922 vector signed short vec_vsubshs (vector bool short, vector signed short);
18923 vector signed short vec_vsubshs (vector signed short, vector bool short);
18924 vector signed short vec_vsubshs (vector signed short, vector signed short);
18926 vector signed int vec_vsubsws (vector bool int, vector signed int);
18927 vector signed int vec_vsubsws (vector signed int, vector bool int);
18928 vector signed int vec_vsubsws (vector signed int, vector signed int);
18930 vector signed char vec_vsububm (vector bool char, vector signed char);
18931 vector signed char vec_vsububm (vector signed char, vector bool char);
18932 vector signed char vec_vsububm (vector signed char, vector signed char);
18933 vector unsigned char vec_vsububm (vector bool char, vector unsigned char);
18934 vector unsigned char vec_vsububm (vector unsigned char, vector bool char);
18935 vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char);
18937 vector unsigned char vec_vsububs (vector bool char, vector unsigned char);
18938 vector unsigned char vec_vsububs (vector unsigned char, vector bool char);
18939 vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char);
18941 vector signed short vec_vsubuhm (vector bool short, vector signed short);
18942 vector signed short vec_vsubuhm (vector signed short, vector bool short);
18943 vector signed short vec_vsubuhm (vector signed short, vector signed short);
18944 vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short);
18945 vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short);
18946 vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short);
18948 vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short);
18949 vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short);
18950 vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short);
18952 vector signed int vec_vsubuwm (vector bool int, vector signed int);
18953 vector signed int vec_vsubuwm (vector signed int, vector bool int);
18954 vector signed int vec_vsubuwm (vector signed int, vector signed int);
18955 vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int);
18956 vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int);
18957 vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int);
18959 vector unsigned int vec_vsubuws (vector bool int, vector unsigned int);
18960 vector unsigned int vec_vsubuws (vector unsigned int, vector bool int);
18961 vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int);
18963 vector signed int vec_vsum4sbs (vector signed char, vector signed int);
18965 vector signed int vec_vsum4shs (vector signed short, vector signed int);
18967 vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int);
18969 vector unsigned int vec_vupkhpx (vector pixel);
18971 vector bool short vec_vupkhsb (vector bool char);
18972 vector signed short vec_vupkhsb (vector signed char);
18974 vector bool int vec_vupkhsh (vector bool short);
18975 vector signed int vec_vupkhsh (vector signed short);
18977 vector unsigned int vec_vupklpx (vector pixel);
18979 vector bool short vec_vupklsb (vector bool char);
18980 vector signed short vec_vupklsb (vector signed char);
18982 vector bool int vec_vupklsh (vector bool short);
18983 vector signed int vec_vupklsh (vector signed short);
18985 vector float vec_xor (vector float, vector float);
18986 vector float vec_xor (vector float, vector bool int);
18987 vector float vec_xor (vector bool int, vector float);
18988 vector bool int vec_xor (vector bool int, vector bool int);
18989 vector signed int vec_xor (vector bool int, vector signed int);
18990 vector signed int vec_xor (vector signed int, vector bool int);
18991 vector signed int vec_xor (vector signed int, vector signed int);
18992 vector unsigned int vec_xor (vector bool int, vector unsigned int);
18993 vector unsigned int vec_xor (vector unsigned int, vector bool int);
18994 vector unsigned int vec_xor (vector unsigned int, vector unsigned int);
18995 vector bool short vec_xor (vector bool short, vector bool short);
18996 vector signed short vec_xor (vector bool short, vector signed short);
18997 vector signed short vec_xor (vector signed short, vector bool short);
18998 vector signed short vec_xor (vector signed short, vector signed short);
18999 vector unsigned short vec_xor (vector bool short, vector unsigned short);
19000 vector unsigned short vec_xor (vector unsigned short, vector bool short);
19001 vector unsigned short vec_xor (vector unsigned short, vector unsigned short);
19002 vector signed char vec_xor (vector bool char, vector signed char);
19003 vector bool char vec_xor (vector bool char, vector bool char);
19004 vector signed char vec_xor (vector signed char, vector bool char);
19005 vector signed char vec_xor (vector signed char, vector signed char);
19006 vector unsigned char vec_xor (vector bool char, vector unsigned char);
19007 vector unsigned char vec_xor (vector unsigned char, vector bool char);
19008 vector unsigned char vec_xor (vector unsigned char, vector unsigned char);
19011 @node PowerPC AltiVec Built-in Functions Available on ISA 2.06
19012 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06
19014 The AltiVec built-in functions described in this section are
19015 available on the PowerPC family of processors starting with ISA 2.06
19016 or later. These are normally enabled by adding @option{-mvsx} to the
19019 When @option{-mvsx} is used, the following additional vector types are
19023 vector unsigned __int128
19024 vector signed __int128
19025 vector unsigned long long int
19026 vector signed long long int
19030 The long long types are only implemented for 64-bit code generation.
19034 vector bool long long vec_and (vector bool long long int, vector bool long long);
19036 vector double vec_ctf (vector unsigned long, const int);
19037 vector double vec_ctf (vector signed long, const int);
19039 vector signed long vec_cts (vector double, const int);
19041 vector unsigned long vec_ctu (vector double, const int);
19043 void vec_dst (const unsigned long *, int, const int);
19044 void vec_dst (const long *, int, const int);
19046 void vec_dststt (const unsigned long *, int, const int);
19047 void vec_dststt (const long *, int, const int);
19049 void vec_dstt (const unsigned long *, int, const int);
19050 void vec_dstt (const long *, int, const int);
19052 vector unsigned char vec_lvsl (int, const unsigned long *);
19053 vector unsigned char vec_lvsl (int, const long *);
19055 vector unsigned char vec_lvsr (int, const unsigned long *);
19056 vector unsigned char vec_lvsr (int, const long *);
19058 vector double vec_mul (vector double, vector double);
19059 vector long vec_mul (vector long, vector long);
19060 vector unsigned long vec_mul (vector unsigned long, vector unsigned long);
19062 vector unsigned long long vec_mule (vector unsigned int, vector unsigned int);
19063 vector signed long long vec_mule (vector signed int, vector signed int);
19065 vector unsigned long long vec_mulo (vector unsigned int, vector unsigned int);
19066 vector signed long long vec_mulo (vector signed int, vector signed int);
19068 vector double vec_nabs (vector double);
19070 vector bool long long vec_reve (vector bool long long);
19071 vector signed long long vec_reve (vector signed long long);
19072 vector unsigned long long vec_reve (vector unsigned long long);
19073 vector double vec_sld (vector double, vector double, const int);
19075 vector bool long long int vec_sld (vector bool long long int,
19076 vector bool long long int, const int);
19077 vector long long int vec_sld (vector long long int, vector long long int, const int);
19078 vector unsigned long long int vec_sld (vector unsigned long long int,
19079 vector unsigned long long int, const int);
19081 vector long long int vec_sll (vector long long int, vector unsigned char);
19082 vector unsigned long long int vec_sll (vector unsigned long long int,
19083 vector unsigned char);
19085 vector signed long long vec_slo (vector signed long long, vector signed char);
19086 vector signed long long vec_slo (vector signed long long, vector unsigned char);
19087 vector unsigned long long vec_slo (vector unsigned long long, vector signed char);
19088 vector unsigned long long vec_slo (vector unsigned long long, vector unsigned char);
19090 vector signed long vec_splat (vector signed long, const int);
19091 vector unsigned long vec_splat (vector unsigned long, const int);
19093 vector long long int vec_srl (vector long long int, vector unsigned char);
19094 vector unsigned long long int vec_srl (vector unsigned long long int,
19095 vector unsigned char);
19097 vector long long int vec_sro (vector long long int, vector char);
19098 vector long long int vec_sro (vector long long int, vector unsigned char);
19099 vector unsigned long long int vec_sro (vector unsigned long long int, vector char);
19100 vector unsigned long long int vec_sro (vector unsigned long long int,
19101 vector unsigned char);
19103 vector signed __int128 vec_subc (vector signed __int128, vector signed __int128);
19104 vector unsigned __int128 vec_subc (vector unsigned __int128, vector unsigned __int128);
19106 vector signed __int128 vec_sube (vector signed __int128, vector signed __int128,
19107 vector signed __int128);
19108 vector unsigned __int128 vec_sube (vector unsigned __int128, vector unsigned __int128,
19109 vector unsigned __int128);
19111 vector signed __int128 vec_subec (vector signed __int128, vector signed __int128,
19112 vector signed __int128);
19113 vector unsigned __int128 vec_subec (vector unsigned __int128, vector unsigned __int128,
19114 vector unsigned __int128);
19116 vector double vec_unpackh (vector float);
19118 vector double vec_unpackl (vector float);
19120 vector double vec_doublee (vector float);
19121 vector double vec_doublee (vector signed int);
19122 vector double vec_doublee (vector unsigned int);
19124 vector double vec_doubleo (vector float);
19125 vector double vec_doubleo (vector signed int);
19126 vector double vec_doubleo (vector unsigned int);
19128 vector double vec_doubleh (vector float);
19129 vector double vec_doubleh (vector signed int);
19130 vector double vec_doubleh (vector unsigned int);
19132 vector double vec_doublel (vector float);
19133 vector double vec_doublel (vector signed int);
19134 vector double vec_doublel (vector unsigned int);
19136 vector float vec_float (vector signed int);
19137 vector float vec_float (vector unsigned int);
19139 vector float vec_float2 (vector signed long long, vector signed long long);
19140 vector float vec_float2 (vector unsigned long long, vector signed long long);
19142 vector float vec_floate (vector double);
19143 vector float vec_floate (vector signed long long);
19144 vector float vec_floate (vector unsigned long long);
19146 vector float vec_floato (vector double);
19147 vector float vec_floato (vector signed long long);
19148 vector float vec_floato (vector unsigned long long);
19150 vector signed long long vec_signed (vector double);
19151 vector signed int vec_signed (vector float);
19153 vector signed int vec_signede (vector double);
19155 vector signed int vec_signedo (vector double);
19157 vector signed char vec_sldw (vector signed char, vector signed char, const int);
19158 vector unsigned char vec_sldw (vector unsigned char, vector unsigned char, const int);
19159 vector signed short vec_sldw (vector signed short, vector signed short, const int);
19160 vector unsigned short vec_sldw (vector unsigned short,
19161 vector unsigned short, const int);
19162 vector signed int vec_sldw (vector signed int, vector signed int, const int);
19163 vector unsigned int vec_sldw (vector unsigned int, vector unsigned int, const int);
19164 vector signed long long vec_sldw (vector signed long long,
19165 vector signed long long, const int);
19166 vector unsigned long long vec_sldw (vector unsigned long long,
19167 vector unsigned long long, const int);
19169 vector signed long long vec_unsigned (vector double);
19170 vector signed int vec_unsigned (vector float);
19172 vector signed int vec_unsignede (vector double);
19174 vector signed int vec_unsignedo (vector double);
19176 vector double vec_abs (vector double);
19177 vector double vec_add (vector double, vector double);
19178 vector double vec_and (vector double, vector double);
19179 vector double vec_and (vector double, vector bool long);
19180 vector double vec_and (vector bool long, vector double);
19181 vector long vec_and (vector long, vector long);
19182 vector long vec_and (vector long, vector bool long);
19183 vector long vec_and (vector bool long, vector long);
19184 vector unsigned long vec_and (vector unsigned long, vector unsigned long);
19185 vector unsigned long vec_and (vector unsigned long, vector bool long);
19186 vector unsigned long vec_and (vector bool long, vector unsigned long);
19187 vector double vec_andc (vector double, vector double);
19188 vector double vec_andc (vector double, vector bool long);
19189 vector double vec_andc (vector bool long, vector double);
19190 vector long vec_andc (vector long, vector long);
19191 vector long vec_andc (vector long, vector bool long);
19192 vector long vec_andc (vector bool long, vector long);
19193 vector unsigned long vec_andc (vector unsigned long, vector unsigned long);
19194 vector unsigned long vec_andc (vector unsigned long, vector bool long);
19195 vector unsigned long vec_andc (vector bool long, vector unsigned long);
19196 vector double vec_ceil (vector double);
19197 vector bool long vec_cmpeq (vector double, vector double);
19198 vector bool long vec_cmpge (vector double, vector double);
19199 vector bool long vec_cmpgt (vector double, vector double);
19200 vector bool long vec_cmple (vector double, vector double);
19201 vector bool long vec_cmplt (vector double, vector double);
19202 vector double vec_cpsgn (vector double, vector double);
19203 vector float vec_div (vector float, vector float);
19204 vector double vec_div (vector double, vector double);
19205 vector long vec_div (vector long, vector long);
19206 vector unsigned long vec_div (vector unsigned long, vector unsigned long);
19207 vector double vec_floor (vector double);
19208 vector signed long long vec_ld (int, const vector signed long long *);
19209 vector signed long long vec_ld (int, const signed long long *);
19210 vector unsigned long long vec_ld (int, const vector unsigned long long *);
19211 vector unsigned long long vec_ld (int, const unsigned long long *);
19212 vector __int128 vec_ld (int, const vector __int128 *);
19213 vector unsigned __int128 vec_ld (int, const vector unsigned __int128 *);
19214 vector __int128 vec_ld (int, const __int128 *);
19215 vector unsigned __int128 vec_ld (int, const unsigned __int128 *);
19216 vector double vec_ld (int, const vector double *);
19217 vector double vec_ld (int, const double *);
19218 vector double vec_ldl (int, const vector double *);
19219 vector double vec_ldl (int, const double *);
19220 vector unsigned char vec_lvsl (int, const double *);
19221 vector unsigned char vec_lvsr (int, const double *);
19222 vector double vec_madd (vector double, vector double, vector double);
19223 vector double vec_max (vector double, vector double);
19224 vector signed long vec_mergeh (vector signed long, vector signed long);
19225 vector signed long vec_mergeh (vector signed long, vector bool long);
19226 vector signed long vec_mergeh (vector bool long, vector signed long);
19227 vector unsigned long vec_mergeh (vector unsigned long, vector unsigned long);
19228 vector unsigned long vec_mergeh (vector unsigned long, vector bool long);
19229 vector unsigned long vec_mergeh (vector bool long, vector unsigned long);
19230 vector signed long vec_mergel (vector signed long, vector signed long);
19231 vector signed long vec_mergel (vector signed long, vector bool long);
19232 vector signed long vec_mergel (vector bool long, vector signed long);
19233 vector unsigned long vec_mergel (vector unsigned long, vector unsigned long);
19234 vector unsigned long vec_mergel (vector unsigned long, vector bool long);
19235 vector unsigned long vec_mergel (vector bool long, vector unsigned long);
19236 vector double vec_min (vector double, vector double);
19237 vector float vec_msub (vector float, vector float, vector float);
19238 vector double vec_msub (vector double, vector double, vector double);
19239 vector float vec_nearbyint (vector float);
19240 vector double vec_nearbyint (vector double);
19241 vector float vec_nmadd (vector float, vector float, vector float);
19242 vector double vec_nmadd (vector double, vector double, vector double);
19243 vector double vec_nmsub (vector double, vector double, vector double);
19244 vector double vec_nor (vector double, vector double);
19245 vector long vec_nor (vector long, vector long);
19246 vector long vec_nor (vector long, vector bool long);
19247 vector long vec_nor (vector bool long, vector long);
19248 vector unsigned long vec_nor (vector unsigned long, vector unsigned long);
19249 vector unsigned long vec_nor (vector unsigned long, vector bool long);
19250 vector unsigned long vec_nor (vector bool long, vector unsigned long);
19251 vector double vec_or (vector double, vector double);
19252 vector double vec_or (vector double, vector bool long);
19253 vector double vec_or (vector bool long, vector double);
19254 vector long vec_or (vector long, vector long);
19255 vector long vec_or (vector long, vector bool long);
19256 vector long vec_or (vector bool long, vector long);
19257 vector unsigned long vec_or (vector unsigned long, vector unsigned long);
19258 vector unsigned long vec_or (vector unsigned long, vector bool long);
19259 vector unsigned long vec_or (vector bool long, vector unsigned long);
19260 vector double vec_perm (vector double, vector double, vector unsigned char);
19261 vector long vec_perm (vector long, vector long, vector unsigned char);
19262 vector unsigned long vec_perm (vector unsigned long, vector unsigned long,
19263 vector unsigned char);
19264 vector bool char vec_permxor (vector bool char, vector bool char,
19266 vector unsigned char vec_permxor (vector signed char, vector signed char,
19267 vector signed char);
19268 vector unsigned char vec_permxor (vector unsigned char, vector unsigned char,
19269 vector unsigned char);
19270 vector double vec_rint (vector double);
19271 vector double vec_recip (vector double, vector double);
19272 vector double vec_rsqrt (vector double);
19273 vector double vec_rsqrte (vector double);
19274 vector double vec_sel (vector double, vector double, vector bool long);
19275 vector double vec_sel (vector double, vector double, vector unsigned long);
19276 vector long vec_sel (vector long, vector long, vector long);
19277 vector long vec_sel (vector long, vector long, vector unsigned long);
19278 vector long vec_sel (vector long, vector long, vector bool long);
19279 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19281 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19282 vector unsigned long);
19283 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19285 vector double vec_splats (double);
19286 vector signed long vec_splats (signed long);
19287 vector unsigned long vec_splats (unsigned long);
19288 vector float vec_sqrt (vector float);
19289 vector double vec_sqrt (vector double);
19290 void vec_st (vector signed long long, int, vector signed long long *);
19291 void vec_st (vector signed long long, int, signed long long *);
19292 void vec_st (vector unsigned long long, int, vector unsigned long long *);
19293 void vec_st (vector unsigned long long, int, unsigned long long *);
19294 void vec_st (vector bool long long, int, vector bool long long *);
19295 void vec_st (vector bool long long, int, signed long long *);
19296 void vec_st (vector bool long long, int, unsigned long long *);
19297 void vec_st (vector double, int, vector double *);
19298 void vec_st (vector double, int, double *);
19299 vector double vec_sub (vector double, vector double);
19300 vector double vec_trunc (vector double);
19301 vector double vec_xl (int, vector double *);
19302 vector double vec_xl (int, double *);
19303 vector long long vec_xl (int, vector long long *);
19304 vector long long vec_xl (int, long long *);
19305 vector unsigned long long vec_xl (int, vector unsigned long long *);
19306 vector unsigned long long vec_xl (int, unsigned long long *);
19307 vector float vec_xl (int, vector float *);
19308 vector float vec_xl (int, float *);
19309 vector int vec_xl (int, vector int *);
19310 vector int vec_xl (int, int *);
19311 vector unsigned int vec_xl (int, vector unsigned int *);
19312 vector unsigned int vec_xl (int, unsigned int *);
19313 vector double vec_xor (vector double, vector double);
19314 vector double vec_xor (vector double, vector bool long);
19315 vector double vec_xor (vector bool long, vector double);
19316 vector long vec_xor (vector long, vector long);
19317 vector long vec_xor (vector long, vector bool long);
19318 vector long vec_xor (vector bool long, vector long);
19319 vector unsigned long vec_xor (vector unsigned long, vector unsigned long);
19320 vector unsigned long vec_xor (vector unsigned long, vector bool long);
19321 vector unsigned long vec_xor (vector bool long, vector unsigned long);
19322 void vec_xst (vector double, int, vector double *);
19323 void vec_xst (vector double, int, double *);
19324 void vec_xst (vector long long, int, vector long long *);
19325 void vec_xst (vector long long, int, long long *);
19326 void vec_xst (vector unsigned long long, int, vector unsigned long long *);
19327 void vec_xst (vector unsigned long long, int, unsigned long long *);
19328 void vec_xst (vector float, int, vector float *);
19329 void vec_xst (vector float, int, float *);
19330 void vec_xst (vector int, int, vector int *);
19331 void vec_xst (vector int, int, int *);
19332 void vec_xst (vector unsigned int, int, vector unsigned int *);
19333 void vec_xst (vector unsigned int, int, unsigned int *);
19334 int vec_all_eq (vector double, vector double);
19335 int vec_all_ge (vector double, vector double);
19336 int vec_all_gt (vector double, vector double);
19337 int vec_all_le (vector double, vector double);
19338 int vec_all_lt (vector double, vector double);
19339 int vec_all_nan (vector double);
19340 int vec_all_ne (vector double, vector double);
19341 int vec_all_nge (vector double, vector double);
19342 int vec_all_ngt (vector double, vector double);
19343 int vec_all_nle (vector double, vector double);
19344 int vec_all_nlt (vector double, vector double);
19345 int vec_all_numeric (vector double);
19346 int vec_any_eq (vector double, vector double);
19347 int vec_any_ge (vector double, vector double);
19348 int vec_any_gt (vector double, vector double);
19349 int vec_any_le (vector double, vector double);
19350 int vec_any_lt (vector double, vector double);
19351 int vec_any_nan (vector double);
19352 int vec_any_ne (vector double, vector double);
19353 int vec_any_nge (vector double, vector double);
19354 int vec_any_ngt (vector double, vector double);
19355 int vec_any_nle (vector double, vector double);
19356 int vec_any_nlt (vector double, vector double);
19357 int vec_any_numeric (vector double);
19359 vector double vec_vsx_ld (int, const vector double *);
19360 vector double vec_vsx_ld (int, const double *);
19361 vector float vec_vsx_ld (int, const vector float *);
19362 vector float vec_vsx_ld (int, const float *);
19363 vector bool int vec_vsx_ld (int, const vector bool int *);
19364 vector signed int vec_vsx_ld (int, const vector signed int *);
19365 vector signed int vec_vsx_ld (int, const int *);
19366 vector signed int vec_vsx_ld (int, const long *);
19367 vector unsigned int vec_vsx_ld (int, const vector unsigned int *);
19368 vector unsigned int vec_vsx_ld (int, const unsigned int *);
19369 vector unsigned int vec_vsx_ld (int, const unsigned long *);
19370 vector bool short vec_vsx_ld (int, const vector bool short *);
19371 vector pixel vec_vsx_ld (int, const vector pixel *);
19372 vector signed short vec_vsx_ld (int, const vector signed short *);
19373 vector signed short vec_vsx_ld (int, const short *);
19374 vector unsigned short vec_vsx_ld (int, const vector unsigned short *);
19375 vector unsigned short vec_vsx_ld (int, const unsigned short *);
19376 vector bool char vec_vsx_ld (int, const vector bool char *);
19377 vector signed char vec_vsx_ld (int, const vector signed char *);
19378 vector signed char vec_vsx_ld (int, const signed char *);
19379 vector unsigned char vec_vsx_ld (int, const vector unsigned char *);
19380 vector unsigned char vec_vsx_ld (int, const unsigned char *);
19382 void vec_vsx_st (vector double, int, vector double *);
19383 void vec_vsx_st (vector double, int, double *);
19384 void vec_vsx_st (vector float, int, vector float *);
19385 void vec_vsx_st (vector float, int, float *);
19386 void vec_vsx_st (vector signed int, int, vector signed int *);
19387 void vec_vsx_st (vector signed int, int, int *);
19388 void vec_vsx_st (vector unsigned int, int, vector unsigned int *);
19389 void vec_vsx_st (vector unsigned int, int, unsigned int *);
19390 void vec_vsx_st (vector bool int, int, vector bool int *);
19391 void vec_vsx_st (vector bool int, int, unsigned int *);
19392 void vec_vsx_st (vector bool int, int, int *);
19393 void vec_vsx_st (vector signed short, int, vector signed short *);
19394 void vec_vsx_st (vector signed short, int, short *);
19395 void vec_vsx_st (vector unsigned short, int, vector unsigned short *);
19396 void vec_vsx_st (vector unsigned short, int, unsigned short *);
19397 void vec_vsx_st (vector bool short, int, vector bool short *);
19398 void vec_vsx_st (vector bool short, int, unsigned short *);
19399 void vec_vsx_st (vector pixel, int, vector pixel *);
19400 void vec_vsx_st (vector pixel, int, unsigned short *);
19401 void vec_vsx_st (vector pixel, int, short *);
19402 void vec_vsx_st (vector bool short, int, short *);
19403 void vec_vsx_st (vector signed char, int, vector signed char *);
19404 void vec_vsx_st (vector signed char, int, signed char *);
19405 void vec_vsx_st (vector unsigned char, int, vector unsigned char *);
19406 void vec_vsx_st (vector unsigned char, int, unsigned char *);
19407 void vec_vsx_st (vector bool char, int, vector bool char *);
19408 void vec_vsx_st (vector bool char, int, unsigned char *);
19409 void vec_vsx_st (vector bool char, int, signed char *);
19411 vector double vec_xxpermdi (vector double, vector double, const int);
19412 vector float vec_xxpermdi (vector float, vector float, const int);
19413 vector long long vec_xxpermdi (vector long long, vector long long, const int);
19414 vector unsigned long long vec_xxpermdi (vector unsigned long long,
19415 vector unsigned long long, const int);
19416 vector int vec_xxpermdi (vector int, vector int, const int);
19417 vector unsigned int vec_xxpermdi (vector unsigned int,
19418 vector unsigned int, const int);
19419 vector short vec_xxpermdi (vector short, vector short, const int);
19420 vector unsigned short vec_xxpermdi (vector unsigned short,
19421 vector unsigned short, const int);
19422 vector signed char vec_xxpermdi (vector signed char, vector signed char,
19424 vector unsigned char vec_xxpermdi (vector unsigned char,
19425 vector unsigned char, const int);
19427 vector double vec_xxsldi (vector double, vector double, int);
19428 vector float vec_xxsldi (vector float, vector float, int);
19429 vector long long vec_xxsldi (vector long long, vector long long, int);
19430 vector unsigned long long vec_xxsldi (vector unsigned long long,
19431 vector unsigned long long, int);
19432 vector int vec_xxsldi (vector int, vector int, int);
19433 vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int);
19434 vector short vec_xxsldi (vector short, vector short, int);
19435 vector unsigned short vec_xxsldi (vector unsigned short,
19436 vector unsigned short, int);
19437 vector signed char vec_xxsldi (vector signed char, vector signed char, int);
19438 vector unsigned char vec_xxsldi (vector unsigned char,
19439 vector unsigned char, int);
19442 Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always
19443 generate the AltiVec @samp{LVX} and @samp{STVX} instructions even
19444 if the VSX instruction set is available. The @samp{vec_vsx_ld} and
19445 @samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X},
19446 @samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions.
19448 @node PowerPC AltiVec Built-in Functions Available on ISA 2.07
19449 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07
19451 If the ISA 2.07 additions to the vector/scalar (power8-vector)
19452 instruction set are available, the following additional functions are
19453 available for both 32-bit and 64-bit targets. For 64-bit targets, you
19454 can use @var{vector long} instead of @var{vector long long},
19455 @var{vector bool long} instead of @var{vector bool long long}, and
19456 @var{vector unsigned long} instead of @var{vector unsigned long long}.
19459 vector signed char vec_neg (vector signed char);
19460 vector signed short vec_neg (vector signed short);
19461 vector signed int vec_neg (vector signed int);
19462 vector signed long long vec_neg (vector signed long long);
19463 vector float char vec_neg (vector float);
19464 vector double vec_neg (vector double);
19466 vector signed int vec_signed2 (vector double, vector double);
19468 vector signed int vec_unsigned2 (vector double, vector double);
19470 vector long long vec_abs (vector long long);
19472 vector long long vec_add (vector long long, vector long long);
19473 vector unsigned long long vec_add (vector unsigned long long,
19474 vector unsigned long long);
19476 int vec_all_eq (vector long long, vector long long);
19477 int vec_all_eq (vector unsigned long long, vector unsigned long long);
19478 int vec_all_ge (vector long long, vector long long);
19479 int vec_all_ge (vector unsigned long long, vector unsigned long long);
19480 int vec_all_gt (vector long long, vector long long);
19481 int vec_all_gt (vector unsigned long long, vector unsigned long long);
19482 int vec_all_le (vector long long, vector long long);
19483 int vec_all_le (vector unsigned long long, vector unsigned long long);
19484 int vec_all_lt (vector long long, vector long long);
19485 int vec_all_lt (vector unsigned long long, vector unsigned long long);
19486 int vec_all_ne (vector long long, vector long long);
19487 int vec_all_ne (vector unsigned long long, vector unsigned long long);
19489 int vec_any_eq (vector long long, vector long long);
19490 int vec_any_eq (vector unsigned long long, vector unsigned long long);
19491 int vec_any_ge (vector long long, vector long long);
19492 int vec_any_ge (vector unsigned long long, vector unsigned long long);
19493 int vec_any_gt (vector long long, vector long long);
19494 int vec_any_gt (vector unsigned long long, vector unsigned long long);
19495 int vec_any_le (vector long long, vector long long);
19496 int vec_any_le (vector unsigned long long, vector unsigned long long);
19497 int vec_any_lt (vector long long, vector long long);
19498 int vec_any_lt (vector unsigned long long, vector unsigned long long);
19499 int vec_any_ne (vector long long, vector long long);
19500 int vec_any_ne (vector unsigned long long, vector unsigned long long);
19502 vector bool long long vec_cmpeq (vector bool long long, vector bool long long);
19504 vector long long vec_eqv (vector long long, vector long long);
19505 vector long long vec_eqv (vector bool long long, vector long long);
19506 vector long long vec_eqv (vector long long, vector bool long long);
19507 vector unsigned long long vec_eqv (vector unsigned long long, vector unsigned long long);
19508 vector unsigned long long vec_eqv (vector bool long long, vector unsigned long long);
19509 vector unsigned long long vec_eqv (vector unsigned long long,
19510 vector bool long long);
19511 vector int vec_eqv (vector int, vector int);
19512 vector int vec_eqv (vector bool int, vector int);
19513 vector int vec_eqv (vector int, vector bool int);
19514 vector unsigned int vec_eqv (vector unsigned int, vector unsigned int);
19515 vector unsigned int vec_eqv (vector bool unsigned int, vector unsigned int);
19516 vector unsigned int vec_eqv (vector unsigned int, vector bool unsigned int);
19517 vector short vec_eqv (vector short, vector short);
19518 vector short vec_eqv (vector bool short, vector short);
19519 vector short vec_eqv (vector short, vector bool short);
19520 vector unsigned short vec_eqv (vector unsigned short, vector unsigned short);
19521 vector unsigned short vec_eqv (vector bool unsigned short, vector unsigned short);
19522 vector unsigned short vec_eqv (vector unsigned short, vector bool unsigned short);
19523 vector signed char vec_eqv (vector signed char, vector signed char);
19524 vector signed char vec_eqv (vector bool signed char, vector signed char);
19525 vector signed char vec_eqv (vector signed char, vector bool signed char);
19526 vector unsigned char vec_eqv (vector unsigned char, vector unsigned char);
19527 vector unsigned char vec_eqv (vector bool unsigned char, vector unsigned char);
19528 vector unsigned char vec_eqv (vector unsigned char, vector bool unsigned char);
19530 vector long long vec_max (vector long long, vector long long);
19531 vector unsigned long long vec_max (vector unsigned long long,
19532 vector unsigned long long);
19534 vector signed int vec_mergee (vector signed int, vector signed int);
19535 vector unsigned int vec_mergee (vector unsigned int, vector unsigned int);
19536 vector bool int vec_mergee (vector bool int, vector bool int);
19538 vector signed int vec_mergeo (vector signed int, vector signed int);
19539 vector unsigned int vec_mergeo (vector unsigned int, vector unsigned int);
19540 vector bool int vec_mergeo (vector bool int, vector bool int);
19542 vector long long vec_min (vector long long, vector long long);
19543 vector unsigned long long vec_min (vector unsigned long long,
19544 vector unsigned long long);
19546 vector signed long long vec_nabs (vector signed long long);
19548 vector long long vec_nand (vector long long, vector long long);
19549 vector long long vec_nand (vector bool long long, vector long long);
19550 vector long long vec_nand (vector long long, vector bool long long);
19551 vector unsigned long long vec_nand (vector unsigned long long,
19552 vector unsigned long long);
19553 vector unsigned long long vec_nand (vector bool long long, vector unsigned long long);
19554 vector unsigned long long vec_nand (vector unsigned long long, vector bool long long);
19555 vector int vec_nand (vector int, vector int);
19556 vector int vec_nand (vector bool int, vector int);
19557 vector int vec_nand (vector int, vector bool int);
19558 vector unsigned int vec_nand (vector unsigned int, vector unsigned int);
19559 vector unsigned int vec_nand (vector bool unsigned int, vector unsigned int);
19560 vector unsigned int vec_nand (vector unsigned int, vector bool unsigned int);
19561 vector short vec_nand (vector short, vector short);
19562 vector short vec_nand (vector bool short, vector short);
19563 vector short vec_nand (vector short, vector bool short);
19564 vector unsigned short vec_nand (vector unsigned short, vector unsigned short);
19565 vector unsigned short vec_nand (vector bool unsigned short, vector unsigned short);
19566 vector unsigned short vec_nand (vector unsigned short, vector bool unsigned short);
19567 vector signed char vec_nand (vector signed char, vector signed char);
19568 vector signed char vec_nand (vector bool signed char, vector signed char);
19569 vector signed char vec_nand (vector signed char, vector bool signed char);
19570 vector unsigned char vec_nand (vector unsigned char, vector unsigned char);
19571 vector unsigned char vec_nand (vector bool unsigned char, vector unsigned char);
19572 vector unsigned char vec_nand (vector unsigned char, vector bool unsigned char);
19574 vector long long vec_orc (vector long long, vector long long);
19575 vector long long vec_orc (vector bool long long, vector long long);
19576 vector long long vec_orc (vector long long, vector bool long long);
19577 vector unsigned long long vec_orc (vector unsigned long long,
19578 vector unsigned long long);
19579 vector unsigned long long vec_orc (vector bool long long, vector unsigned long long);
19580 vector unsigned long long vec_orc (vector unsigned long long, vector bool long long);
19581 vector int vec_orc (vector int, vector int);
19582 vector int vec_orc (vector bool int, vector int);
19583 vector int vec_orc (vector int, vector bool int);
19584 vector unsigned int vec_orc (vector unsigned int, vector unsigned int);
19585 vector unsigned int vec_orc (vector bool unsigned int, vector unsigned int);
19586 vector unsigned int vec_orc (vector unsigned int, vector bool unsigned int);
19587 vector short vec_orc (vector short, vector short);
19588 vector short vec_orc (vector bool short, vector short);
19589 vector short vec_orc (vector short, vector bool short);
19590 vector unsigned short vec_orc (vector unsigned short, vector unsigned short);
19591 vector unsigned short vec_orc (vector bool unsigned short, vector unsigned short);
19592 vector unsigned short vec_orc (vector unsigned short, vector bool unsigned short);
19593 vector signed char vec_orc (vector signed char, vector signed char);
19594 vector signed char vec_orc (vector bool signed char, vector signed char);
19595 vector signed char vec_orc (vector signed char, vector bool signed char);
19596 vector unsigned char vec_orc (vector unsigned char, vector unsigned char);
19597 vector unsigned char vec_orc (vector bool unsigned char, vector unsigned char);
19598 vector unsigned char vec_orc (vector unsigned char, vector bool unsigned char);
19600 vector int vec_pack (vector long long, vector long long);
19601 vector unsigned int vec_pack (vector unsigned long long, vector unsigned long long);
19602 vector bool int vec_pack (vector bool long long, vector bool long long);
19603 vector float vec_pack (vector double, vector double);
19605 vector int vec_packs (vector long long, vector long long);
19606 vector unsigned int vec_packs (vector unsigned long long, vector unsigned long long);
19608 vector unsigned char vec_packsu (vector signed short, vector signed short)
19609 vector unsigned char vec_packsu (vector unsigned short, vector unsigned short)
19610 vector unsigned short int vec_packsu (vector signed int, vector signed int);
19611 vector unsigned short int vec_packsu (vector unsigned int, vector unsigned int);
19612 vector unsigned int vec_packsu (vector long long, vector long long);
19613 vector unsigned int vec_packsu (vector unsigned long long, vector unsigned long long);
19614 vector unsigned int vec_packsu (vector signed long long, vector signed long long);
19616 vector unsigned char vec_popcnt (vector signed char);
19617 vector unsigned char vec_popcnt (vector unsigned char);
19618 vector unsigned short vec_popcnt (vector signed short);
19619 vector unsigned short vec_popcnt (vector unsigned short);
19620 vector unsigned int vec_popcnt (vector signed int);
19621 vector unsigned int vec_popcnt (vector unsigned int);
19622 vector unsigned long long vec_popcnt (vector signed long long);
19623 vector unsigned long long vec_popcnt (vector unsigned long long);
19625 vector long long vec_rl (vector long long, vector unsigned long long);
19626 vector long long vec_rl (vector unsigned long long, vector unsigned long long);
19628 vector long long vec_sl (vector long long, vector unsigned long long);
19629 vector long long vec_sl (vector unsigned long long, vector unsigned long long);
19631 vector long long vec_sr (vector long long, vector unsigned long long);
19632 vector unsigned long long char vec_sr (vector unsigned long long,
19633 vector unsigned long long);
19635 vector long long vec_sra (vector long long, vector unsigned long long);
19636 vector unsigned long long vec_sra (vector unsigned long long,
19637 vector unsigned long long);
19639 vector long long vec_sub (vector long long, vector long long);
19640 vector unsigned long long vec_sub (vector unsigned long long,
19641 vector unsigned long long);
19643 vector long long vec_unpackh (vector int);
19644 vector unsigned long long vec_unpackh (vector unsigned int);
19646 vector long long vec_unpackl (vector int);
19647 vector unsigned long long vec_unpackl (vector unsigned int);
19649 vector long long vec_vaddudm (vector long long, vector long long);
19650 vector long long vec_vaddudm (vector bool long long, vector long long);
19651 vector long long vec_vaddudm (vector long long, vector bool long long);
19652 vector unsigned long long vec_vaddudm (vector unsigned long long,
19653 vector unsigned long long);
19654 vector unsigned long long vec_vaddudm (vector bool unsigned long long,
19655 vector unsigned long long);
19656 vector unsigned long long vec_vaddudm (vector unsigned long long,
19657 vector bool unsigned long long);
19659 vector long long vec_vbpermq (vector signed char, vector signed char);
19660 vector long long vec_vbpermq (vector unsigned char, vector unsigned char);
19662 vector unsigned char vec_bperm (vector unsigned char, vector unsigned char);
19663 vector unsigned char vec_bperm (vector unsigned long long, vector unsigned char);
19664 vector unsigned long long vec_bperm (vector unsigned __int128, vector unsigned char);
19666 vector long long vec_cntlz (vector long long);
19667 vector unsigned long long vec_cntlz (vector unsigned long long);
19668 vector int vec_cntlz (vector int);
19669 vector unsigned int vec_cntlz (vector int);
19670 vector short vec_cntlz (vector short);
19671 vector unsigned short vec_cntlz (vector unsigned short);
19672 vector signed char vec_cntlz (vector signed char);
19673 vector unsigned char vec_cntlz (vector unsigned char);
19675 vector long long vec_vclz (vector long long);
19676 vector unsigned long long vec_vclz (vector unsigned long long);
19677 vector int vec_vclz (vector int);
19678 vector unsigned int vec_vclz (vector int);
19679 vector short vec_vclz (vector short);
19680 vector unsigned short vec_vclz (vector unsigned short);
19681 vector signed char vec_vclz (vector signed char);
19682 vector unsigned char vec_vclz (vector unsigned char);
19684 vector signed char vec_vclzb (vector signed char);
19685 vector unsigned char vec_vclzb (vector unsigned char);
19687 vector long long vec_vclzd (vector long long);
19688 vector unsigned long long vec_vclzd (vector unsigned long long);
19690 vector short vec_vclzh (vector short);
19691 vector unsigned short vec_vclzh (vector unsigned short);
19693 vector int vec_vclzw (vector int);
19694 vector unsigned int vec_vclzw (vector int);
19696 vector signed char vec_vgbbd (vector signed char);
19697 vector unsigned char vec_vgbbd (vector unsigned char);
19699 vector long long vec_vmaxsd (vector long long, vector long long);
19701 vector unsigned long long vec_vmaxud (vector unsigned long long,
19702 unsigned vector long long);
19704 vector long long vec_vminsd (vector long long, vector long long);
19706 vector unsigned long long vec_vminud (vector long long, vector long long);
19708 vector int vec_vpksdss (vector long long, vector long long);
19709 vector unsigned int vec_vpksdss (vector long long, vector long long);
19711 vector unsigned int vec_vpkudus (vector unsigned long long,
19712 vector unsigned long long);
19714 vector int vec_vpkudum (vector long long, vector long long);
19715 vector unsigned int vec_vpkudum (vector unsigned long long,
19716 vector unsigned long long);
19717 vector bool int vec_vpkudum (vector bool long long, vector bool long long);
19719 vector long long vec_vpopcnt (vector long long);
19720 vector unsigned long long vec_vpopcnt (vector unsigned long long);
19721 vector int vec_vpopcnt (vector int);
19722 vector unsigned int vec_vpopcnt (vector int);
19723 vector short vec_vpopcnt (vector short);
19724 vector unsigned short vec_vpopcnt (vector unsigned short);
19725 vector signed char vec_vpopcnt (vector signed char);
19726 vector unsigned char vec_vpopcnt (vector unsigned char);
19728 vector signed char vec_vpopcntb (vector signed char);
19729 vector unsigned char vec_vpopcntb (vector unsigned char);
19731 vector long long vec_vpopcntd (vector long long);
19732 vector unsigned long long vec_vpopcntd (vector unsigned long long);
19734 vector short vec_vpopcnth (vector short);
19735 vector unsigned short vec_vpopcnth (vector unsigned short);
19737 vector int vec_vpopcntw (vector int);
19738 vector unsigned int vec_vpopcntw (vector int);
19740 vector long long vec_vrld (vector long long, vector unsigned long long);
19741 vector unsigned long long vec_vrld (vector unsigned long long,
19742 vector unsigned long long);
19744 vector long long vec_vsld (vector long long, vector unsigned long long);
19745 vector long long vec_vsld (vector unsigned long long,
19746 vector unsigned long long);
19748 vector long long vec_vsrad (vector long long, vector unsigned long long);
19749 vector unsigned long long vec_vsrad (vector unsigned long long,
19750 vector unsigned long long);
19752 vector long long vec_vsrd (vector long long, vector unsigned long long);
19753 vector unsigned long long char vec_vsrd (vector unsigned long long,
19754 vector unsigned long long);
19756 vector long long vec_vsubudm (vector long long, vector long long);
19757 vector long long vec_vsubudm (vector bool long long, vector long long);
19758 vector long long vec_vsubudm (vector long long, vector bool long long);
19759 vector unsigned long long vec_vsubudm (vector unsigned long long,
19760 vector unsigned long long);
19761 vector unsigned long long vec_vsubudm (vector bool long long,
19762 vector unsigned long long);
19763 vector unsigned long long vec_vsubudm (vector unsigned long long,
19764 vector bool long long);
19766 vector long long vec_vupkhsw (vector int);
19767 vector unsigned long long vec_vupkhsw (vector unsigned int);
19769 vector long long vec_vupklsw (vector int);
19770 vector unsigned long long vec_vupklsw (vector int);
19773 If the ISA 2.07 additions to the vector/scalar (power8-vector)
19774 instruction set are available, the following additional functions are
19775 available for 64-bit targets. New vector types
19776 (@var{vector __int128} and @var{vector __uint128}) are available
19777 to hold the @var{__int128} and @var{__uint128} types to use these
19780 The normal vector extract, and set operations work on
19781 @var{vector __int128} and @var{vector __uint128} types,
19782 but the index value must be 0.
19785 vector __int128 vec_vaddcuq (vector __int128, vector __int128);
19786 vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128);
19788 vector __int128 vec_vadduqm (vector __int128, vector __int128);
19789 vector __uint128 vec_vadduqm (vector __uint128, vector __uint128);
19791 vector __int128 vec_vaddecuq (vector __int128, vector __int128,
19793 vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128,
19796 vector __int128 vec_vaddeuqm (vector __int128, vector __int128,
19798 vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128,
19801 vector __int128 vec_vsubecuq (vector __int128, vector __int128,
19803 vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128,
19806 vector __int128 vec_vsubeuqm (vector __int128, vector __int128,
19808 vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128,
19811 vector __int128 vec_vsubcuq (vector __int128, vector __int128);
19812 vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128);
19814 __int128 vec_vsubuqm (__int128, __int128);
19815 __uint128 vec_vsubuqm (__uint128, __uint128);
19817 vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int);
19818 int __builtin_bcdadd_lt (vector __int128, vector __int128, const int);
19819 int __builtin_bcdadd_eq (vector __int128, vector __int128, const int);
19820 int __builtin_bcdadd_gt (vector __int128, vector __int128, const int);
19821 int __builtin_bcdadd_ov (vector __int128, vector __int128, const int);
19822 vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int);
19823 int __builtin_bcdsub_lt (vector __int128, vector __int128, const int);
19824 int __builtin_bcdsub_eq (vector __int128, vector __int128, const int);
19825 int __builtin_bcdsub_gt (vector __int128, vector __int128, const int);
19826 int __builtin_bcdsub_ov (vector __int128, vector __int128, const int);
19829 @node PowerPC AltiVec Built-in Functions Available on ISA 3.0
19830 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0
19832 The following additional built-in functions are also available for the
19833 PowerPC family of processors, starting with ISA 3.0
19834 (@option{-mcpu=power9}) or later:
19836 unsigned int scalar_extract_exp (double source);
19837 unsigned long long int scalar_extract_exp (__ieee128 source);
19839 unsigned long long int scalar_extract_sig (double source);
19840 unsigned __int128 scalar_extract_sig (__ieee128 source);
19842 double scalar_insert_exp (unsigned long long int significand,
19843 unsigned long long int exponent);
19844 double scalar_insert_exp (double significand, unsigned long long int exponent);
19846 ieee_128 scalar_insert_exp (unsigned __int128 significand,
19847 unsigned long long int exponent);
19848 ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent);
19850 int scalar_cmp_exp_gt (double arg1, double arg2);
19851 int scalar_cmp_exp_lt (double arg1, double arg2);
19852 int scalar_cmp_exp_eq (double arg1, double arg2);
19853 int scalar_cmp_exp_unordered (double arg1, double arg2);
19855 bool scalar_test_data_class (float source, const int condition);
19856 bool scalar_test_data_class (double source, const int condition);
19857 bool scalar_test_data_class (__ieee128 source, const int condition);
19859 bool scalar_test_neg (float source);
19860 bool scalar_test_neg (double source);
19861 bool scalar_test_neg (__ieee128 source);
19864 The @code{scalar_extract_exp} and @code{scalar_extract_sig}
19865 functions require a 64-bit environment supporting ISA 3.0 or later.
19866 The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in
19867 functions return the significand and the biased exponent value
19868 respectively of their @code{source} arguments.
19869 When supplied with a 64-bit @code{source} argument, the
19870 result returned by @code{scalar_extract_sig} has
19871 the @code{0x0010000000000000} bit set if the
19872 function's @code{source} argument is in normalized form.
19873 Otherwise, this bit is set to 0.
19874 When supplied with a 128-bit @code{source} argument, the
19875 @code{0x00010000000000000000000000000000} bit of the result is
19877 Note that the sign of the significand is not represented in the result
19878 returned from the @code{scalar_extract_sig} function. Use the
19879 @code{scalar_test_neg} function to test the sign of its @code{double}
19882 The @code{scalar_insert_exp}
19883 functions require a 64-bit environment supporting ISA 3.0 or later.
19884 When supplied with a 64-bit first argument, the
19885 @code{scalar_insert_exp} built-in function returns a double-precision
19886 floating point value that is constructed by assembling the values of its
19887 @code{significand} and @code{exponent} arguments. The sign of the
19888 result is copied from the most significant bit of the
19889 @code{significand} argument. The significand and exponent components
19890 of the result are composed of the least significant 11 bits of the
19891 @code{exponent} argument and the least significant 52 bits of the
19892 @code{significand} argument respectively.
19894 When supplied with a 128-bit first argument, the
19895 @code{scalar_insert_exp} built-in function returns a quad-precision
19896 ieee floating point value. The sign bit of the result is copied from
19897 the most significant bit of the @code{significand} argument.
19898 The significand and exponent components of the result are composed of
19899 the least significant 15 bits of the @code{exponent} argument and the
19900 least significant 112 bits of the @code{significand} argument respectively.
19902 The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt},
19903 @code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in
19904 functions return a non-zero value if @code{arg1} is greater than, less
19905 than, equal to, or not comparable to @code{arg2} respectively. The
19906 arguments are not comparable if one or the other equals NaN (not a
19909 The @code{scalar_test_data_class} built-in function returns 1
19910 if any of the condition tests enabled by the value of the
19911 @code{condition} variable are true, and 0 otherwise. The
19912 @code{condition} argument must be a compile-time constant integer with
19913 value not exceeding 127. The
19914 @code{condition} argument is encoded as a bitmask with each bit
19915 enabling the testing of a different condition, as characterized by the
19919 0x20 Test for +Infinity
19920 0x10 Test for -Infinity
19921 0x08 Test for +Zero
19922 0x04 Test for -Zero
19923 0x02 Test for +Denormal
19924 0x01 Test for -Denormal
19927 The @code{scalar_test_neg} built-in function returns 1 if its
19928 @code{source} argument holds a negative value, 0 otherwise.
19930 The following built-in functions are also available for the PowerPC family
19931 of processors, starting with ISA 3.0 or later
19932 (@option{-mcpu=power9}). These string functions are described
19933 separately in order to group the descriptions closer to the function
19936 int vec_all_nez (vector signed char, vector signed char);
19937 int vec_all_nez (vector unsigned char, vector unsigned char);
19938 int vec_all_nez (vector signed short, vector signed short);
19939 int vec_all_nez (vector unsigned short, vector unsigned short);
19940 int vec_all_nez (vector signed int, vector signed int);
19941 int vec_all_nez (vector unsigned int, vector unsigned int);
19943 int vec_any_eqz (vector signed char, vector signed char);
19944 int vec_any_eqz (vector unsigned char, vector unsigned char);
19945 int vec_any_eqz (vector signed short, vector signed short);
19946 int vec_any_eqz (vector unsigned short, vector unsigned short);
19947 int vec_any_eqz (vector signed int, vector signed int);
19948 int vec_any_eqz (vector unsigned int, vector unsigned int);
19950 vector bool char vec_cmpnez (vector signed char arg1, vector signed char arg2);
19951 vector bool char vec_cmpnez (vector unsigned char arg1, vector unsigned char arg2);
19952 vector bool short vec_cmpnez (vector signed short arg1, vector signed short arg2);
19953 vector bool short vec_cmpnez (vector unsigned short arg1, vector unsigned short arg2);
19954 vector bool int vec_cmpnez (vector signed int arg1, vector signed int arg2);
19955 vector bool int vec_cmpnez (vector unsigned int, vector unsigned int);
19957 vector signed char vec_cnttz (vector signed char);
19958 vector unsigned char vec_cnttz (vector unsigned char);
19959 vector signed short vec_cnttz (vector signed short);
19960 vector unsigned short vec_cnttz (vector unsigned short);
19961 vector signed int vec_cnttz (vector signed int);
19962 vector unsigned int vec_cnttz (vector unsigned int);
19963 vector signed long long vec_cnttz (vector signed long long);
19964 vector unsigned long long vec_cnttz (vector unsigned long long);
19966 signed int vec_cntlz_lsbb (vector signed char);
19967 signed int vec_cntlz_lsbb (vector unsigned char);
19969 signed int vec_cnttz_lsbb (vector signed char);
19970 signed int vec_cnttz_lsbb (vector unsigned char);
19972 unsigned int vec_first_match_index (vector signed char, vector signed char);
19973 unsigned int vec_first_match_index (vector unsigned char, vector unsigned char);
19974 unsigned int vec_first_match_index (vector signed int, vector signed int);
19975 unsigned int vec_first_match_index (vector unsigned int, vector unsigned int);
19976 unsigned int vec_first_match_index (vector signed short, vector signed short);
19977 unsigned int vec_first_match_index (vector unsigned short, vector unsigned short);
19978 unsigned int vec_first_match_or_eos_index (vector signed char, vector signed char);
19979 unsigned int vec_first_match_or_eos_index (vector unsigned char, vector unsigned char);
19980 unsigned int vec_first_match_or_eos_index (vector signed int, vector signed int);
19981 unsigned int vec_first_match_or_eos_index (vector unsigned int, vector unsigned int);
19982 unsigned int vec_first_match_or_eos_index (vector signed short, vector signed short);
19983 unsigned int vec_first_match_or_eos_index (vector unsigned short,
19984 vector unsigned short);
19985 unsigned int vec_first_mismatch_index (vector signed char, vector signed char);
19986 unsigned int vec_first_mismatch_index (vector unsigned char, vector unsigned char);
19987 unsigned int vec_first_mismatch_index (vector signed int, vector signed int);
19988 unsigned int vec_first_mismatch_index (vector unsigned int, vector unsigned int);
19989 unsigned int vec_first_mismatch_index (vector signed short, vector signed short);
19990 unsigned int vec_first_mismatch_index (vector unsigned short, vector unsigned short);
19991 unsigned int vec_first_mismatch_or_eos_index (vector signed char, vector signed char);
19992 unsigned int vec_first_mismatch_or_eos_index (vector unsigned char,
19993 vector unsigned char);
19994 unsigned int vec_first_mismatch_or_eos_index (vector signed int, vector signed int);
19995 unsigned int vec_first_mismatch_or_eos_index (vector unsigned int, vector unsigned int);
19996 unsigned int vec_first_mismatch_or_eos_index (vector signed short, vector signed short);
19997 unsigned int vec_first_mismatch_or_eos_index (vector unsigned short,
19998 vector unsigned short);
20000 vector unsigned short vec_pack_to_short_fp32 (vector float, vector float);
20002 vector signed char vec_xl_be (signed long long, signed char *);
20003 vector unsigned char vec_xl_be (signed long long, unsigned char *);
20004 vector signed int vec_xl_be (signed long long, signed int *);
20005 vector unsigned int vec_xl_be (signed long long, unsigned int *);
20006 vector signed __int128 vec_xl_be (signed long long, signed __int128 *);
20007 vector unsigned __int128 vec_xl_be (signed long long, unsigned __int128 *);
20008 vector signed long long vec_xl_be (signed long long, signed long long *);
20009 vector unsigned long long vec_xl_be (signed long long, unsigned long long *);
20010 vector signed short vec_xl_be (signed long long, signed short *);
20011 vector unsigned short vec_xl_be (signed long long, unsigned short *);
20012 vector double vec_xl_be (signed long long, double *);
20013 vector float vec_xl_be (signed long long, float *);
20015 vector signed char vec_xl_len (signed char *addr, size_t len);
20016 vector unsigned char vec_xl_len (unsigned char *addr, size_t len);
20017 vector signed int vec_xl_len (signed int *addr, size_t len);
20018 vector unsigned int vec_xl_len (unsigned int *addr, size_t len);
20019 vector signed __int128 vec_xl_len (signed __int128 *addr, size_t len);
20020 vector unsigned __int128 vec_xl_len (unsigned __int128 *addr, size_t len);
20021 vector signed long long vec_xl_len (signed long long *addr, size_t len);
20022 vector unsigned long long vec_xl_len (unsigned long long *addr, size_t len);
20023 vector signed short vec_xl_len (signed short *addr, size_t len);
20024 vector unsigned short vec_xl_len (unsigned short *addr, size_t len);
20025 vector double vec_xl_len (double *addr, size_t len);
20026 vector float vec_xl_len (float *addr, size_t len);
20028 vector unsigned char vec_xl_len_r (unsigned char *addr, size_t len);
20030 void vec_xst_len (vector signed char data, signed char *addr, size_t len);
20031 void vec_xst_len (vector unsigned char data, unsigned char *addr, size_t len);
20032 void vec_xst_len (vector signed int data, signed int *addr, size_t len);
20033 void vec_xst_len (vector unsigned int data, unsigned int *addr, size_t len);
20034 void vec_xst_len (vector unsigned __int128 data, unsigned __int128 *addr, size_t len);
20035 void vec_xst_len (vector signed long long data, signed long long *addr, size_t len);
20036 void vec_xst_len (vector unsigned long long data, unsigned long long *addr, size_t len);
20037 void vec_xst_len (vector signed short data, signed short *addr, size_t len);
20038 void vec_xst_len (vector unsigned short data, unsigned short *addr, size_t len);
20039 void vec_xst_len (vector signed __int128 data, signed __int128 *addr, size_t len);
20040 void vec_xst_len (vector double data, double *addr, size_t len);
20041 void vec_xst_len (vector float data, float *addr, size_t len);
20043 void vec_xst_len_r (vector unsigned char data, unsigned char *addr, size_t len);
20045 signed char vec_xlx (unsigned int index, vector signed char data);
20046 unsigned char vec_xlx (unsigned int index, vector unsigned char data);
20047 signed short vec_xlx (unsigned int index, vector signed short data);
20048 unsigned short vec_xlx (unsigned int index, vector unsigned short data);
20049 signed int vec_xlx (unsigned int index, vector signed int data);
20050 unsigned int vec_xlx (unsigned int index, vector unsigned int data);
20051 float vec_xlx (unsigned int index, vector float data);
20053 signed char vec_xrx (unsigned int index, vector signed char data);
20054 unsigned char vec_xrx (unsigned int index, vector unsigned char data);
20055 signed short vec_xrx (unsigned int index, vector signed short data);
20056 unsigned short vec_xrx (unsigned int index, vector unsigned short data);
20057 signed int vec_xrx (unsigned int index, vector signed int data);
20058 unsigned int vec_xrx (unsigned int index, vector unsigned int data);
20059 float vec_xrx (unsigned int index, vector float data);
20062 The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez}
20063 perform pairwise comparisons between the elements at the same
20064 positions within their two vector arguments.
20065 The @code{vec_all_nez} function returns a
20066 non-zero value if and only if all pairwise comparisons are not
20067 equal and no element of either vector argument contains a zero.
20068 The @code{vec_any_eqz} function returns a
20069 non-zero value if and only if at least one pairwise comparison is equal
20070 or if at least one element of either vector argument contains a zero.
20071 The @code{vec_cmpnez} function returns a vector of the same type as
20072 its two arguments, within which each element consists of all ones to
20073 denote that either the corresponding elements of the incoming arguments are
20074 not equal or that at least one of the corresponding elements contains
20075 zero. Otherwise, the element of the returned vector contains all zeros.
20077 The @code{vec_cntlz_lsbb} function returns the count of the number of
20078 consecutive leading byte elements (starting from position 0 within the
20079 supplied vector argument) for which the least-significant bit
20080 equals zero. The @code{vec_cnttz_lsbb} function returns the count of
20081 the number of consecutive trailing byte elements (starting from
20082 position 15 and counting backwards within the supplied vector
20083 argument) for which the least-significant bit equals zero.
20085 The @code{vec_xl_len} and @code{vec_xst_len} functions require a
20086 64-bit environment supporting ISA 3.0 or later. The @code{vec_xl_len}
20087 function loads a variable length vector from memory. The
20088 @code{vec_xst_len} function stores a variable length vector to memory.
20089 With both the @code{vec_xl_len} and @code{vec_xst_len} functions, the
20090 @code{addr} argument represents the memory address to or from which
20091 data will be transferred, and the
20092 @code{len} argument represents the number of bytes to be
20093 transferred, as computed by the C expression @code{min((len & 0xff), 16)}.
20094 If this expression's value is not a multiple of the vector element's
20095 size, the behavior of this function is undefined.
20096 In the case that the underlying computer is configured to run in
20097 big-endian mode, the data transfer moves bytes 0 to @code{(len - 1)} of
20098 the corresponding vector. In little-endian mode, the data transfer
20099 moves bytes @code{(16 - len)} to @code{15} of the corresponding
20100 vector. For the load function, any bytes of the result vector that
20101 are not loaded from memory are set to zero.
20102 The value of the @code{addr} argument need not be aligned on a
20103 multiple of the vector's element size.
20105 The @code{vec_xlx} and @code{vec_xrx} functions extract the single
20106 element selected by the @code{index} argument from the vector
20107 represented by the @code{data} argument. The @code{index} argument
20108 always specifies a byte offset, regardless of the size of the vector
20109 element. With @code{vec_xlx}, @code{index} is the offset of the first
20110 byte of the element to be extracted. With @code{vec_xrx}, @code{index}
20111 represents the last byte of the element to be extracted, measured
20112 from the right end of the vector. In other words, the last byte of
20113 the element to be extracted is found at position @code{(15 - index)}.
20114 There is no requirement that @code{index} be a multiple of the vector
20115 element size. However, if the size of the vector element added to
20116 @code{index} is greater than 15, the content of the returned value is
20119 If the ISA 3.0 instruction set additions (@option{-mcpu=power9})
20123 vector unsigned long long vec_bperm (vector unsigned long long, vector unsigned char);
20125 vector bool char vec_cmpne (vector bool char, vector bool char);
20126 vector bool char vec_cmpne (vector signed char, vector signed char);
20127 vector bool char vec_cmpne (vector unsigned char, vector unsigned char);
20128 vector bool int vec_cmpne (vector bool int, vector bool int);
20129 vector bool int vec_cmpne (vector signed int, vector signed int);
20130 vector bool int vec_cmpne (vector unsigned int, vector unsigned int);
20131 vector bool long long vec_cmpne (vector bool long long, vector bool long long);
20132 vector bool long long vec_cmpne (vector signed long long, vector signed long long);
20133 vector bool long long vec_cmpne (vector unsigned long long, vector unsigned long long);
20134 vector bool short vec_cmpne (vector bool short, vector bool short);
20135 vector bool short vec_cmpne (vector signed short, vector signed short);
20136 vector bool short vec_cmpne (vector unsigned short, vector unsigned short);
20137 vector bool long long vec_cmpne (vector double, vector double);
20138 vector bool int vec_cmpne (vector float, vector float);
20140 vector float vec_extract_fp32_from_shorth (vector unsigned short);
20141 vector float vec_extract_fp32_from_shortl (vector unsigned short);
20143 vector long long vec_vctz (vector long long);
20144 vector unsigned long long vec_vctz (vector unsigned long long);
20145 vector int vec_vctz (vector int);
20146 vector unsigned int vec_vctz (vector int);
20147 vector short vec_vctz (vector short);
20148 vector unsigned short vec_vctz (vector unsigned short);
20149 vector signed char vec_vctz (vector signed char);
20150 vector unsigned char vec_vctz (vector unsigned char);
20152 vector signed char vec_vctzb (vector signed char);
20153 vector unsigned char vec_vctzb (vector unsigned char);
20155 vector long long vec_vctzd (vector long long);
20156 vector unsigned long long vec_vctzd (vector unsigned long long);
20158 vector short vec_vctzh (vector short);
20159 vector unsigned short vec_vctzh (vector unsigned short);
20161 vector int vec_vctzw (vector int);
20162 vector unsigned int vec_vctzw (vector int);
20164 vector unsigned long long vec_extract4b (vector unsigned char, const int);
20166 vector unsigned char vec_insert4b (vector signed int, vector unsigned char,
20168 vector unsigned char vec_insert4b (vector unsigned int, vector unsigned char,
20171 vector unsigned int vec_parity_lsbb (vector signed int);
20172 vector unsigned int vec_parity_lsbb (vector unsigned int);
20173 vector unsigned __int128 vec_parity_lsbb (vector signed __int128);
20174 vector unsigned __int128 vec_parity_lsbb (vector unsigned __int128);
20175 vector unsigned long long vec_parity_lsbb (vector signed long long);
20176 vector unsigned long long vec_parity_lsbb (vector unsigned long long);
20178 vector int vec_vprtyb (vector int);
20179 vector unsigned int vec_vprtyb (vector unsigned int);
20180 vector long long vec_vprtyb (vector long long);
20181 vector unsigned long long vec_vprtyb (vector unsigned long long);
20183 vector int vec_vprtybw (vector int);
20184 vector unsigned int vec_vprtybw (vector unsigned int);
20186 vector long long vec_vprtybd (vector long long);
20187 vector unsigned long long vec_vprtybd (vector unsigned long long);
20190 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
20194 vector long vec_vprtyb (vector long);
20195 vector unsigned long vec_vprtyb (vector unsigned long);
20196 vector __int128 vec_vprtyb (vector __int128);
20197 vector __uint128 vec_vprtyb (vector __uint128);
20199 vector long vec_vprtybd (vector long);
20200 vector unsigned long vec_vprtybd (vector unsigned long);
20202 vector __int128 vec_vprtybq (vector __int128);
20203 vector __uint128 vec_vprtybd (vector __uint128);
20206 The following built-in vector functions are available for the PowerPC family
20207 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20209 __vector unsigned char
20210 vec_slv (__vector unsigned char src, __vector unsigned char shift_distance);
20211 __vector unsigned char
20212 vec_srv (__vector unsigned char src, __vector unsigned char shift_distance);
20215 The @code{vec_slv} and @code{vec_srv} functions operate on
20216 all of the bytes of their @code{src} and @code{shift_distance}
20217 arguments in parallel. The behavior of the @code{vec_slv} is as if
20218 there existed a temporary array of 17 unsigned characters
20219 @code{slv_array} within which elements 0 through 15 are the same as
20220 the entries in the @code{src} array and element 16 equals 0. The
20221 result returned from the @code{vec_slv} function is a
20222 @code{__vector} of 16 unsigned characters within which element
20223 @code{i} is computed using the C expression
20224 @code{0xff & (*((unsigned short *)(slv_array + i)) << (0x07 &
20225 shift_distance[i]))},
20226 with this resulting value coerced to the @code{unsigned char} type.
20227 The behavior of the @code{vec_srv} is as if
20228 there existed a temporary array of 17 unsigned characters
20229 @code{srv_array} within which element 0 equals zero and
20230 elements 1 through 16 equal the elements 0 through 15 of
20231 the @code{src} array. The
20232 result returned from the @code{vec_srv} function is a
20233 @code{__vector} of 16 unsigned characters within which element
20234 @code{i} is computed using the C expression
20235 @code{0xff & (*((unsigned short *)(srv_array + i)) >>
20236 (0x07 & shift_distance[i]))},
20237 with this resulting value coerced to the @code{unsigned char} type.
20239 The following built-in functions are available for the PowerPC family
20240 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20242 __vector unsigned char
20243 vec_absd (__vector unsigned char arg1, __vector unsigned char arg2);
20244 __vector unsigned short
20245 vec_absd (__vector unsigned short arg1, __vector unsigned short arg2);
20246 __vector unsigned int
20247 vec_absd (__vector unsigned int arg1, __vector unsigned int arg2);
20249 __vector unsigned char
20250 vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2);
20251 __vector unsigned short
20252 vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2);
20253 __vector unsigned int
20254 vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2);
20257 The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and
20258 @code{vec_absdw} built-in functions each computes the absolute
20259 differences of the pairs of vector elements supplied in its two vector
20260 arguments, placing the absolute differences into the corresponding
20261 elements of the vector result.
20263 The following built-in functions are available for the PowerPC family
20264 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20266 __vector unsigned int vec_extract_exp (__vector float source);
20267 __vector unsigned long long int vec_extract_exp (__vector double source);
20269 __vector unsigned int vec_extract_sig (__vector float source);
20270 __vector unsigned long long int vec_extract_sig (__vector double source);
20272 __vector float vec_insert_exp (__vector unsigned int significands,
20273 __vector unsigned int exponents);
20274 __vector float vec_insert_exp (__vector unsigned float significands,
20275 __vector unsigned int exponents);
20276 __vector double vec_insert_exp (__vector unsigned long long int significands,
20277 __vector unsigned long long int exponents);
20278 __vector double vec_insert_exp (__vector unsigned double significands,
20279 __vector unsigned long long int exponents);
20281 __vector bool int vec_test_data_class (__vector float source, const int condition);
20282 __vector bool long long int vec_test_data_class (__vector double source,
20283 const int condition);
20286 The @code{vec_extract_sig} and @code{vec_extract_exp} built-in
20287 functions return vectors representing the significands and biased
20288 exponent values of their @code{source} arguments respectively.
20289 Within the result vector returned by @code{vec_extract_sig}, the
20290 @code{0x800000} bit of each vector element returned when the
20291 function's @code{source} argument is of type @code{float} is set to 1
20292 if the corresponding floating point value is in normalized form.
20293 Otherwise, this bit is set to 0. When the @code{source} argument is
20294 of type @code{double}, the @code{0x10000000000000} bit within each of
20295 the result vector's elements is set according to the same rules.
20296 Note that the sign of the significand is not represented in the result
20297 returned from the @code{vec_extract_sig} function. To extract the
20299 @code{vec_cpsgn} function, which returns a new vector within which all
20300 of the sign bits of its second argument vector are overwritten with the
20301 sign bits copied from the coresponding elements of its first argument
20302 vector, and all other (non-sign) bits of the second argument vector
20303 are copied unchanged into the result vector.
20305 The @code{vec_insert_exp} built-in functions return a vector of
20306 single- or double-precision floating
20307 point values constructed by assembling the values of their
20308 @code{significands} and @code{exponents} arguments into the
20309 corresponding elements of the returned vector.
20311 element of the result is copied from the most significant bit of the
20312 corresponding entry within the @code{significands} argument.
20313 Note that the relevant
20314 bits of the @code{significands} argument are the same, for both integer
20315 and floating point types.
20317 significand and exponent components of each element of the result are
20318 composed of the least significant bits of the corresponding
20319 @code{significands} element and the least significant bits of the
20320 corresponding @code{exponents} element.
20322 The @code{vec_test_data_class} built-in function returns a vector
20323 representing the results of testing the @code{source} vector for the
20324 condition selected by the @code{condition} argument. The
20325 @code{condition} argument must be a compile-time constant integer with
20326 value not exceeding 127. The
20327 @code{condition} argument is encoded as a bitmask with each bit
20328 enabling the testing of a different condition, as characterized by the
20332 0x20 Test for +Infinity
20333 0x10 Test for -Infinity
20334 0x08 Test for +Zero
20335 0x04 Test for -Zero
20336 0x02 Test for +Denormal
20337 0x01 Test for -Denormal
20340 If any of the enabled test conditions is true, the corresponding entry
20341 in the result vector is -1. Otherwise (all of the enabled test
20342 conditions are false), the corresponding entry of the result vector is 0.
20344 The following built-in functions are available for the PowerPC family
20345 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20347 vector unsigned int vec_rlmi (vector unsigned int, vector unsigned int,
20348 vector unsigned int);
20349 vector unsigned long long vec_rlmi (vector unsigned long long,
20350 vector unsigned long long,
20351 vector unsigned long long);
20352 vector unsigned int vec_rlnm (vector unsigned int, vector unsigned int,
20353 vector unsigned int);
20354 vector unsigned long long vec_rlnm (vector unsigned long long,
20355 vector unsigned long long,
20356 vector unsigned long long);
20357 vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int);
20358 vector unsigned long long vec_vrlnm (vector unsigned long long,
20359 vector unsigned long long);
20362 The result of @code{vec_rlmi} is obtained by rotating each element of
20363 the first argument vector left and inserting it under mask into the
20364 second argument vector. The third argument vector contains the mask
20365 beginning in bits 11:15, the mask end in bits 19:23, and the shift
20366 count in bits 27:31, of each element.
20368 The result of @code{vec_rlnm} is obtained by rotating each element of
20369 the first argument vector left and ANDing it with a mask specified by
20370 the second and third argument vectors. The second argument vector
20371 contains the shift count for each element in the low-order byte. The
20372 third argument vector contains the mask end for each element in the
20373 low-order byte, with the mask begin in the next higher byte.
20375 The result of @code{vec_vrlnm} is obtained by rotating each element
20376 of the first argument vector left and ANDing it with a mask. The
20377 second argument vector contains the mask beginning in bits 11:15,
20378 the mask end in bits 19:23, and the shift count in bits 27:31,
20381 If the ISA 3.0 instruction set additions (@option{-mcpu=power9})
20384 vector signed bool char vec_revb (vector signed char);
20385 vector signed char vec_revb (vector signed char);
20386 vector unsigned char vec_revb (vector unsigned char);
20387 vector bool short vec_revb (vector bool short);
20388 vector short vec_revb (vector short);
20389 vector unsigned short vec_revb (vector unsigned short);
20390 vector bool int vec_revb (vector bool int);
20391 vector int vec_revb (vector int);
20392 vector unsigned int vec_revb (vector unsigned int);
20393 vector float vec_revb (vector float);
20394 vector bool long long vec_revb (vector bool long long);
20395 vector long long vec_revb (vector long long);
20396 vector unsigned long long vec_revb (vector unsigned long long);
20397 vector double vec_revb (vector double);
20400 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
20403 vector long vec_revb (vector long);
20404 vector unsigned long vec_revb (vector unsigned long);
20405 vector __int128 vec_revb (vector __int128);
20406 vector __uint128 vec_revb (vector __uint128);
20409 The @code{vec_revb} built-in function reverses the bytes on an element
20410 by element basis. A vector of @code{vector unsigned char} or
20411 @code{vector signed char} reverses the bytes in the whole word.
20413 If the cryptographic instructions are enabled (@option{-mcrypto} or
20414 @option{-mcpu=power8}), the following builtins are enabled.
20417 vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long);
20419 vector unsigned char vec_sbox_be (vector unsigned char);
20421 vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long,
20422 vector unsigned long long);
20424 vector unsigned char vec_cipher_be (vector unsigned char, vector unsigned char);
20426 vector unsigned long long __builtin_crypto_vcipherlast
20427 (vector unsigned long long,
20428 vector unsigned long long);
20430 vector unsigned char vec_cipherlast_be (vector unsigned char,
20431 vector unsigned char);
20433 vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long,
20434 vector unsigned long long);
20436 vector unsigned char vec_ncipher_be (vector unsigned char,
20437 vector unsigned char);
20439 vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long,
20440 vector unsigned long long);
20442 vector unsigned char vec_ncipherlast_be (vector unsigned char,
20443 vector unsigned char);
20445 vector unsigned char __builtin_crypto_vpermxor (vector unsigned char,
20446 vector unsigned char,
20447 vector unsigned char);
20449 vector unsigned short __builtin_crypto_vpermxor (vector unsigned short,
20450 vector unsigned short,
20451 vector unsigned short);
20453 vector unsigned int __builtin_crypto_vpermxor (vector unsigned int,
20454 vector unsigned int,
20455 vector unsigned int);
20457 vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long,
20458 vector unsigned long long,
20459 vector unsigned long long);
20461 vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char,
20462 vector unsigned char);
20464 vector unsigned short __builtin_crypto_vpmsumb (vector unsigned short,
20465 vector unsigned short);
20467 vector unsigned int __builtin_crypto_vpmsumb (vector unsigned int,
20468 vector unsigned int);
20470 vector unsigned long long __builtin_crypto_vpmsumb (vector unsigned long long,
20471 vector unsigned long long);
20473 vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long,
20476 vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int);
20479 The second argument to @var{__builtin_crypto_vshasigmad} and
20480 @var{__builtin_crypto_vshasigmaw} must be a constant
20481 integer that is 0 or 1. The third argument to these built-in functions
20482 must be a constant integer in the range of 0 to 15.
20484 If the ISA 3.0 instruction set additions
20485 are enabled (@option{-mcpu=power9}), the following additional
20486 functions are available for both 32-bit and 64-bit targets.
20488 vector short vec_xl (int, vector short *);
20489 vector short vec_xl (int, short *);
20490 vector unsigned short vec_xl (int, vector unsigned short *);
20491 vector unsigned short vec_xl (int, unsigned short *);
20492 vector char vec_xl (int, vector char *);
20493 vector char vec_xl (int, char *);
20494 vector unsigned char vec_xl (int, vector unsigned char *);
20495 vector unsigned char vec_xl (int, unsigned char *);
20497 void vec_xst (vector short, int, vector short *);
20498 void vec_xst (vector short, int, short *);
20499 void vec_xst (vector unsigned short, int, vector unsigned short *);
20500 void vec_xst (vector unsigned short, int, unsigned short *);
20501 void vec_xst (vector char, int, vector char *);
20502 void vec_xst (vector char, int, char *);
20503 void vec_xst (vector unsigned char, int, vector unsigned char *);
20504 void vec_xst (vector unsigned char, int, unsigned char *);
20506 @node PowerPC Hardware Transactional Memory Built-in Functions
20507 @subsection PowerPC Hardware Transactional Memory Built-in Functions
20508 GCC provides two interfaces for accessing the Hardware Transactional
20509 Memory (HTM) instructions available on some of the PowerPC family
20510 of processors (eg, POWER8). The two interfaces come in a low level
20511 interface, consisting of built-in functions specific to PowerPC and a
20512 higher level interface consisting of inline functions that are common
20513 between PowerPC and S/390.
20515 @subsubsection PowerPC HTM Low Level Built-in Functions
20517 The following low level built-in functions are available with
20518 @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later.
20519 They all generate the machine instruction that is part of the name.
20521 The HTM builtins (with the exception of @code{__builtin_tbegin}) return
20522 the full 4-bit condition register value set by their associated hardware
20523 instruction. The header file @code{htmintrin.h} defines some macros that can
20524 be used to decipher the return value. The @code{__builtin_tbegin} builtin
20525 returns a simple @code{true} or @code{false} value depending on whether a transaction was
20526 successfully started or not. The arguments of the builtins match exactly the
20527 type and order of the associated hardware instruction's operands, except for
20528 the @code{__builtin_tcheck} builtin, which does not take any input arguments.
20529 Refer to the ISA manual for a description of each instruction's operands.
20532 unsigned int __builtin_tbegin (unsigned int)
20533 unsigned int __builtin_tend (unsigned int)
20535 unsigned int __builtin_tabort (unsigned int)
20536 unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int)
20537 unsigned int __builtin_tabortdci (unsigned int, unsigned int, int)
20538 unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int)
20539 unsigned int __builtin_tabortwci (unsigned int, unsigned int, int)
20541 unsigned int __builtin_tcheck (void)
20542 unsigned int __builtin_treclaim (unsigned int)
20543 unsigned int __builtin_trechkpt (void)
20544 unsigned int __builtin_tsr (unsigned int)
20547 In addition to the above HTM built-ins, we have added built-ins for
20548 some common extended mnemonics of the HTM instructions:
20551 unsigned int __builtin_tendall (void)
20552 unsigned int __builtin_tresume (void)
20553 unsigned int __builtin_tsuspend (void)
20556 Note that the semantics of the above HTM builtins are required to mimic
20557 the locking semantics used for critical sections. Builtins that are used
20558 to create a new transaction or restart a suspended transaction must have
20559 lock acquisition like semantics while those builtins that end or suspend a
20560 transaction must have lock release like semantics. Specifically, this must
20561 mimic lock semantics as specified by C++11, for example: Lock acquisition is
20562 as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE)
20563 that returns 0, and lock release is as-if an execution of
20564 __atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an
20565 implicit implementation-defined lock used for all transactions. The HTM
20566 instructions associated with with the builtins inherently provide the
20567 correct acquisition and release hardware barriers required. However,
20568 the compiler must also be prohibited from moving loads and stores across
20569 the builtins in a way that would violate their semantics. This has been
20570 accomplished by adding memory barriers to the associated HTM instructions
20571 (which is a conservative approach to provide acquire and release semantics).
20572 Earlier versions of the compiler did not treat the HTM instructions as
20573 memory barriers. A @code{__TM_FENCE__} macro has been added, which can
20574 be used to determine whether the current compiler treats HTM instructions
20575 as memory barriers or not. This allows the user to explicitly add memory
20576 barriers to their code when using an older version of the compiler.
20578 The following set of built-in functions are available to gain access
20579 to the HTM specific special purpose registers.
20582 unsigned long __builtin_get_texasr (void)
20583 unsigned long __builtin_get_texasru (void)
20584 unsigned long __builtin_get_tfhar (void)
20585 unsigned long __builtin_get_tfiar (void)
20587 void __builtin_set_texasr (unsigned long);
20588 void __builtin_set_texasru (unsigned long);
20589 void __builtin_set_tfhar (unsigned long);
20590 void __builtin_set_tfiar (unsigned long);
20593 Example usage of these low level built-in functions may look like:
20596 #include <htmintrin.h>
20598 int num_retries = 10;
20602 if (__builtin_tbegin (0))
20604 /* Transaction State Initiated. */
20605 if (is_locked (lock))
20606 __builtin_tabort (0);
20607 ... transaction code...
20608 __builtin_tend (0);
20613 /* Transaction State Failed. Use locks if the transaction
20614 failure is "persistent" or we've tried too many times. */
20615 if (num_retries-- <= 0
20616 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ()))
20618 acquire_lock (lock);
20619 ... non transactional fallback path...
20620 release_lock (lock);
20627 One final built-in function has been added that returns the value of
20628 the 2-bit Transaction State field of the Machine Status Register (MSR)
20629 as stored in @code{CR0}.
20632 unsigned long __builtin_ttest (void)
20635 This built-in can be used to determine the current transaction state
20636 using the following code example:
20639 #include <htmintrin.h>
20641 unsigned char tx_state = _HTM_STATE (__builtin_ttest ());
20643 if (tx_state == _HTM_TRANSACTIONAL)
20645 /* Code to use in transactional state. */
20647 else if (tx_state == _HTM_NONTRANSACTIONAL)
20649 /* Code to use in non-transactional state. */
20651 else if (tx_state == _HTM_SUSPENDED)
20653 /* Code to use in transaction suspended state. */
20657 @subsubsection PowerPC HTM High Level Inline Functions
20659 The following high level HTM interface is made available by including
20660 @code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU}
20661 where CPU is `power8' or later. This interface is common between PowerPC
20662 and S/390, allowing users to write one HTM source implementation that
20663 can be compiled and executed on either system.
20666 long __TM_simple_begin (void)
20667 long __TM_begin (void* const TM_buff)
20668 long __TM_end (void)
20669 void __TM_abort (void)
20670 void __TM_named_abort (unsigned char const code)
20671 void __TM_resume (void)
20672 void __TM_suspend (void)
20674 long __TM_is_user_abort (void* const TM_buff)
20675 long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code)
20676 long __TM_is_illegal (void* const TM_buff)
20677 long __TM_is_footprint_exceeded (void* const TM_buff)
20678 long __TM_nesting_depth (void* const TM_buff)
20679 long __TM_is_nested_too_deep(void* const TM_buff)
20680 long __TM_is_conflict(void* const TM_buff)
20681 long __TM_is_failure_persistent(void* const TM_buff)
20682 long __TM_failure_address(void* const TM_buff)
20683 long long __TM_failure_code(void* const TM_buff)
20686 Using these common set of HTM inline functions, we can create
20687 a more portable version of the HTM example in the previous
20688 section that will work on either PowerPC or S/390:
20691 #include <htmxlintrin.h>
20693 int num_retries = 10;
20694 TM_buff_type TM_buff;
20698 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED)
20700 /* Transaction State Initiated. */
20701 if (is_locked (lock))
20703 ... transaction code...
20709 /* Transaction State Failed. Use locks if the transaction
20710 failure is "persistent" or we've tried too many times. */
20711 if (num_retries-- <= 0
20712 || __TM_is_failure_persistent (TM_buff))
20714 acquire_lock (lock);
20715 ... non transactional fallback path...
20716 release_lock (lock);
20723 @node PowerPC Atomic Memory Operation Functions
20724 @subsection PowerPC Atomic Memory Operation Functions
20725 ISA 3.0 of the PowerPC added new atomic memory operation (amo)
20726 instructions. GCC provides support for these instructions in 64-bit
20727 environments. All of the functions are declared in the include file
20730 The functions supported are:
20735 uint32_t amo_lwat_add (uint32_t *, uint32_t);
20736 uint32_t amo_lwat_xor (uint32_t *, uint32_t);
20737 uint32_t amo_lwat_ior (uint32_t *, uint32_t);
20738 uint32_t amo_lwat_and (uint32_t *, uint32_t);
20739 uint32_t amo_lwat_umax (uint32_t *, uint32_t);
20740 uint32_t amo_lwat_umin (uint32_t *, uint32_t);
20741 uint32_t amo_lwat_swap (uint32_t *, uint32_t);
20743 int32_t amo_lwat_sadd (int32_t *, int32_t);
20744 int32_t amo_lwat_smax (int32_t *, int32_t);
20745 int32_t amo_lwat_smin (int32_t *, int32_t);
20746 int32_t amo_lwat_sswap (int32_t *, int32_t);
20748 uint64_t amo_ldat_add (uint64_t *, uint64_t);
20749 uint64_t amo_ldat_xor (uint64_t *, uint64_t);
20750 uint64_t amo_ldat_ior (uint64_t *, uint64_t);
20751 uint64_t amo_ldat_and (uint64_t *, uint64_t);
20752 uint64_t amo_ldat_umax (uint64_t *, uint64_t);
20753 uint64_t amo_ldat_umin (uint64_t *, uint64_t);
20754 uint64_t amo_ldat_swap (uint64_t *, uint64_t);
20756 int64_t amo_ldat_sadd (int64_t *, int64_t);
20757 int64_t amo_ldat_smax (int64_t *, int64_t);
20758 int64_t amo_ldat_smin (int64_t *, int64_t);
20759 int64_t amo_ldat_sswap (int64_t *, int64_t);
20761 void amo_stwat_add (uint32_t *, uint32_t);
20762 void amo_stwat_xor (uint32_t *, uint32_t);
20763 void amo_stwat_ior (uint32_t *, uint32_t);
20764 void amo_stwat_and (uint32_t *, uint32_t);
20765 void amo_stwat_umax (uint32_t *, uint32_t);
20766 void amo_stwat_umin (uint32_t *, uint32_t);
20768 void amo_stwat_sadd (int32_t *, int32_t);
20769 void amo_stwat_smax (int32_t *, int32_t);
20770 void amo_stwat_smin (int32_t *, int32_t);
20772 void amo_stdat_add (uint64_t *, uint64_t);
20773 void amo_stdat_xor (uint64_t *, uint64_t);
20774 void amo_stdat_ior (uint64_t *, uint64_t);
20775 void amo_stdat_and (uint64_t *, uint64_t);
20776 void amo_stdat_umax (uint64_t *, uint64_t);
20777 void amo_stdat_umin (uint64_t *, uint64_t);
20779 void amo_stdat_sadd (int64_t *, int64_t);
20780 void amo_stdat_smax (int64_t *, int64_t);
20781 void amo_stdat_smin (int64_t *, int64_t);
20784 @node RX Built-in Functions
20785 @subsection RX Built-in Functions
20786 GCC supports some of the RX instructions which cannot be expressed in
20787 the C programming language via the use of built-in functions. The
20788 following functions are supported:
20790 @deftypefn {Built-in Function} void __builtin_rx_brk (void)
20791 Generates the @code{brk} machine instruction.
20794 @deftypefn {Built-in Function} void __builtin_rx_clrpsw (int)
20795 Generates the @code{clrpsw} machine instruction to clear the specified
20796 bit in the processor status word.
20799 @deftypefn {Built-in Function} void __builtin_rx_int (int)
20800 Generates the @code{int} machine instruction to generate an interrupt
20801 with the specified value.
20804 @deftypefn {Built-in Function} void __builtin_rx_machi (int, int)
20805 Generates the @code{machi} machine instruction to add the result of
20806 multiplying the top 16 bits of the two arguments into the
20810 @deftypefn {Built-in Function} void __builtin_rx_maclo (int, int)
20811 Generates the @code{maclo} machine instruction to add the result of
20812 multiplying the bottom 16 bits of the two arguments into the
20816 @deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int)
20817 Generates the @code{mulhi} machine instruction to place the result of
20818 multiplying the top 16 bits of the two arguments into the
20822 @deftypefn {Built-in Function} void __builtin_rx_mullo (int, int)
20823 Generates the @code{mullo} machine instruction to place the result of
20824 multiplying the bottom 16 bits of the two arguments into the
20828 @deftypefn {Built-in Function} int __builtin_rx_mvfachi (void)
20829 Generates the @code{mvfachi} machine instruction to read the top
20830 32 bits of the accumulator.
20833 @deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void)
20834 Generates the @code{mvfacmi} machine instruction to read the middle
20835 32 bits of the accumulator.
20838 @deftypefn {Built-in Function} int __builtin_rx_mvfc (int)
20839 Generates the @code{mvfc} machine instruction which reads the control
20840 register specified in its argument and returns its value.
20843 @deftypefn {Built-in Function} void __builtin_rx_mvtachi (int)
20844 Generates the @code{mvtachi} machine instruction to set the top
20845 32 bits of the accumulator.
20848 @deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int)
20849 Generates the @code{mvtaclo} machine instruction to set the bottom
20850 32 bits of the accumulator.
20853 @deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val)
20854 Generates the @code{mvtc} machine instruction which sets control
20855 register number @code{reg} to @code{val}.
20858 @deftypefn {Built-in Function} void __builtin_rx_mvtipl (int)
20859 Generates the @code{mvtipl} machine instruction set the interrupt
20863 @deftypefn {Built-in Function} void __builtin_rx_racw (int)
20864 Generates the @code{racw} machine instruction to round the accumulator
20865 according to the specified mode.
20868 @deftypefn {Built-in Function} int __builtin_rx_revw (int)
20869 Generates the @code{revw} machine instruction which swaps the bytes in
20870 the argument so that bits 0--7 now occupy bits 8--15 and vice versa,
20871 and also bits 16--23 occupy bits 24--31 and vice versa.
20874 @deftypefn {Built-in Function} void __builtin_rx_rmpa (void)
20875 Generates the @code{rmpa} machine instruction which initiates a
20876 repeated multiply and accumulate sequence.
20879 @deftypefn {Built-in Function} void __builtin_rx_round (float)
20880 Generates the @code{round} machine instruction which returns the
20881 floating-point argument rounded according to the current rounding mode
20882 set in the floating-point status word register.
20885 @deftypefn {Built-in Function} int __builtin_rx_sat (int)
20886 Generates the @code{sat} machine instruction which returns the
20887 saturated value of the argument.
20890 @deftypefn {Built-in Function} void __builtin_rx_setpsw (int)
20891 Generates the @code{setpsw} machine instruction to set the specified
20892 bit in the processor status word.
20895 @deftypefn {Built-in Function} void __builtin_rx_wait (void)
20896 Generates the @code{wait} machine instruction.
20899 @node S/390 System z Built-in Functions
20900 @subsection S/390 System z Built-in Functions
20901 @deftypefn {Built-in Function} int __builtin_tbegin (void*)
20902 Generates the @code{tbegin} machine instruction starting a
20903 non-constrained hardware transaction. If the parameter is non-NULL the
20904 memory area is used to store the transaction diagnostic buffer and
20905 will be passed as first operand to @code{tbegin}. This buffer can be
20906 defined using the @code{struct __htm_tdb} C struct defined in
20907 @code{htmintrin.h} and must reside on a double-word boundary. The
20908 second tbegin operand is set to @code{0xff0c}. This enables
20909 save/restore of all GPRs and disables aborts for FPR and AR
20910 manipulations inside the transaction body. The condition code set by
20911 the tbegin instruction is returned as integer value. The tbegin
20912 instruction by definition overwrites the content of all FPRs. The
20913 compiler will generate code which saves and restores the FPRs. For
20914 soft-float code it is recommended to used the @code{*_nofloat}
20915 variant. In order to prevent a TDB from being written it is required
20916 to pass a constant zero value as parameter. Passing a zero value
20917 through a variable is not sufficient. Although modifications of
20918 access registers inside the transaction will not trigger an
20919 transaction abort it is not supported to actually modify them. Access
20920 registers do not get saved when entering a transaction. They will have
20921 undefined state when reaching the abort code.
20924 Macros for the possible return codes of tbegin are defined in the
20925 @code{htmintrin.h} header file:
20928 @item _HTM_TBEGIN_STARTED
20929 @code{tbegin} has been executed as part of normal processing. The
20930 transaction body is supposed to be executed.
20931 @item _HTM_TBEGIN_INDETERMINATE
20932 The transaction was aborted due to an indeterminate condition which
20933 might be persistent.
20934 @item _HTM_TBEGIN_TRANSIENT
20935 The transaction aborted due to a transient failure. The transaction
20936 should be re-executed in that case.
20937 @item _HTM_TBEGIN_PERSISTENT
20938 The transaction aborted due to a persistent failure. Re-execution
20939 under same circumstances will not be productive.
20942 @defmac _HTM_FIRST_USER_ABORT_CODE
20943 The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h}
20944 specifies the first abort code which can be used for
20945 @code{__builtin_tabort}. Values below this threshold are reserved for
20949 @deftp {Data type} {struct __htm_tdb}
20950 The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes
20951 the structure of the transaction diagnostic block as specified in the
20952 Principles of Operation manual chapter 5-91.
20955 @deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*)
20956 Same as @code{__builtin_tbegin} but without FPR saves and restores.
20957 Using this variant in code making use of FPRs will leave the FPRs in
20958 undefined state when entering the transaction abort handler code.
20961 @deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int)
20962 In addition to @code{__builtin_tbegin} a loop for transient failures
20963 is generated. If tbegin returns a condition code of 2 the transaction
20964 will be retried as often as specified in the second argument. The
20965 perform processor assist instruction is used to tell the CPU about the
20966 number of fails so far.
20969 @deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int)
20970 Same as @code{__builtin_tbegin_retry} but without FPR saves and
20971 restores. Using this variant in code making use of FPRs will leave
20972 the FPRs in undefined state when entering the transaction abort
20976 @deftypefn {Built-in Function} void __builtin_tbeginc (void)
20977 Generates the @code{tbeginc} machine instruction starting a constrained
20978 hardware transaction. The second operand is set to @code{0xff08}.
20981 @deftypefn {Built-in Function} int __builtin_tend (void)
20982 Generates the @code{tend} machine instruction finishing a transaction
20983 and making the changes visible to other threads. The condition code
20984 generated by tend is returned as integer value.
20987 @deftypefn {Built-in Function} void __builtin_tabort (int)
20988 Generates the @code{tabort} machine instruction with the specified
20989 abort code. Abort codes from 0 through 255 are reserved and will
20990 result in an error message.
20993 @deftypefn {Built-in Function} void __builtin_tx_assist (int)
20994 Generates the @code{ppa rX,rY,1} machine instruction. Where the
20995 integer parameter is loaded into rX and a value of zero is loaded into
20996 rY. The integer parameter specifies the number of times the
20997 transaction repeatedly aborted.
21000 @deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void)
21001 Generates the @code{etnd} machine instruction. The current nesting
21002 depth is returned as integer value. For a nesting depth of 0 the code
21003 is not executed as part of an transaction.
21006 @deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t)
21008 Generates the @code{ntstg} machine instruction. The second argument
21009 is written to the first arguments location. The store operation will
21010 not be rolled-back in case of an transaction abort.
21013 @node SH Built-in Functions
21014 @subsection SH Built-in Functions
21015 The following built-in functions are supported on the SH1, SH2, SH3 and SH4
21016 families of processors:
21018 @deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr})
21019 Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually
21020 used by system code that manages threads and execution contexts. The compiler
21021 normally does not generate code that modifies the contents of @samp{GBR} and
21022 thus the value is preserved across function calls. Changing the @samp{GBR}
21023 value in user code must be done with caution, since the compiler might use
21024 @samp{GBR} in order to access thread local variables.
21028 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
21029 Returns the value that is currently set in the @samp{GBR} register.
21030 Memory loads and stores that use the thread pointer as a base address are
21031 turned into @samp{GBR} based displacement loads and stores, if possible.
21039 int get_tcb_value (void)
21041 // Generate @samp{mov.l @@(8,gbr),r0} instruction
21042 return ((my_tcb*)__builtin_thread_pointer ())->c;
21048 @deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void)
21049 Returns the value that is currently set in the @samp{FPSCR} register.
21052 @deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val})
21053 Sets the @samp{FPSCR} register to the specified value @var{val}, while
21054 preserving the current values of the FR, SZ and PR bits.
21057 @node SPARC VIS Built-in Functions
21058 @subsection SPARC VIS Built-in Functions
21060 GCC supports SIMD operations on the SPARC using both the generic vector
21061 extensions (@pxref{Vector Extensions}) as well as built-in functions for
21062 the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis}
21063 switch, the VIS extension is exposed as the following built-in functions:
21066 typedef int v1si __attribute__ ((vector_size (4)));
21067 typedef int v2si __attribute__ ((vector_size (8)));
21068 typedef short v4hi __attribute__ ((vector_size (8)));
21069 typedef short v2hi __attribute__ ((vector_size (4)));
21070 typedef unsigned char v8qi __attribute__ ((vector_size (8)));
21071 typedef unsigned char v4qi __attribute__ ((vector_size (4)));
21073 void __builtin_vis_write_gsr (int64_t);
21074 int64_t __builtin_vis_read_gsr (void);
21076 void * __builtin_vis_alignaddr (void *, long);
21077 void * __builtin_vis_alignaddrl (void *, long);
21078 int64_t __builtin_vis_faligndatadi (int64_t, int64_t);
21079 v2si __builtin_vis_faligndatav2si (v2si, v2si);
21080 v4hi __builtin_vis_faligndatav4hi (v4si, v4si);
21081 v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi);
21083 v4hi __builtin_vis_fexpand (v4qi);
21085 v4hi __builtin_vis_fmul8x16 (v4qi, v4hi);
21086 v4hi __builtin_vis_fmul8x16au (v4qi, v2hi);
21087 v4hi __builtin_vis_fmul8x16al (v4qi, v2hi);
21088 v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi);
21089 v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi);
21090 v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi);
21091 v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi);
21093 v4qi __builtin_vis_fpack16 (v4hi);
21094 v8qi __builtin_vis_fpack32 (v2si, v8qi);
21095 v2hi __builtin_vis_fpackfix (v2si);
21096 v8qi __builtin_vis_fpmerge (v4qi, v4qi);
21098 int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t);
21100 long __builtin_vis_edge8 (void *, void *);
21101 long __builtin_vis_edge8l (void *, void *);
21102 long __builtin_vis_edge16 (void *, void *);
21103 long __builtin_vis_edge16l (void *, void *);
21104 long __builtin_vis_edge32 (void *, void *);
21105 long __builtin_vis_edge32l (void *, void *);
21107 long __builtin_vis_fcmple16 (v4hi, v4hi);
21108 long __builtin_vis_fcmple32 (v2si, v2si);
21109 long __builtin_vis_fcmpne16 (v4hi, v4hi);
21110 long __builtin_vis_fcmpne32 (v2si, v2si);
21111 long __builtin_vis_fcmpgt16 (v4hi, v4hi);
21112 long __builtin_vis_fcmpgt32 (v2si, v2si);
21113 long __builtin_vis_fcmpeq16 (v4hi, v4hi);
21114 long __builtin_vis_fcmpeq32 (v2si, v2si);
21116 v4hi __builtin_vis_fpadd16 (v4hi, v4hi);
21117 v2hi __builtin_vis_fpadd16s (v2hi, v2hi);
21118 v2si __builtin_vis_fpadd32 (v2si, v2si);
21119 v1si __builtin_vis_fpadd32s (v1si, v1si);
21120 v4hi __builtin_vis_fpsub16 (v4hi, v4hi);
21121 v2hi __builtin_vis_fpsub16s (v2hi, v2hi);
21122 v2si __builtin_vis_fpsub32 (v2si, v2si);
21123 v1si __builtin_vis_fpsub32s (v1si, v1si);
21125 long __builtin_vis_array8 (long, long);
21126 long __builtin_vis_array16 (long, long);
21127 long __builtin_vis_array32 (long, long);
21130 When you use the @option{-mvis2} switch, the VIS version 2.0 built-in
21131 functions also become available:
21134 long __builtin_vis_bmask (long, long);
21135 int64_t __builtin_vis_bshuffledi (int64_t, int64_t);
21136 v2si __builtin_vis_bshufflev2si (v2si, v2si);
21137 v4hi __builtin_vis_bshufflev2si (v4hi, v4hi);
21138 v8qi __builtin_vis_bshufflev2si (v8qi, v8qi);
21140 long __builtin_vis_edge8n (void *, void *);
21141 long __builtin_vis_edge8ln (void *, void *);
21142 long __builtin_vis_edge16n (void *, void *);
21143 long __builtin_vis_edge16ln (void *, void *);
21144 long __builtin_vis_edge32n (void *, void *);
21145 long __builtin_vis_edge32ln (void *, void *);
21148 When you use the @option{-mvis3} switch, the VIS version 3.0 built-in
21149 functions also become available:
21152 void __builtin_vis_cmask8 (long);
21153 void __builtin_vis_cmask16 (long);
21154 void __builtin_vis_cmask32 (long);
21156 v4hi __builtin_vis_fchksm16 (v4hi, v4hi);
21158 v4hi __builtin_vis_fsll16 (v4hi, v4hi);
21159 v4hi __builtin_vis_fslas16 (v4hi, v4hi);
21160 v4hi __builtin_vis_fsrl16 (v4hi, v4hi);
21161 v4hi __builtin_vis_fsra16 (v4hi, v4hi);
21162 v2si __builtin_vis_fsll16 (v2si, v2si);
21163 v2si __builtin_vis_fslas16 (v2si, v2si);
21164 v2si __builtin_vis_fsrl16 (v2si, v2si);
21165 v2si __builtin_vis_fsra16 (v2si, v2si);
21167 long __builtin_vis_pdistn (v8qi, v8qi);
21169 v4hi __builtin_vis_fmean16 (v4hi, v4hi);
21171 int64_t __builtin_vis_fpadd64 (int64_t, int64_t);
21172 int64_t __builtin_vis_fpsub64 (int64_t, int64_t);
21174 v4hi __builtin_vis_fpadds16 (v4hi, v4hi);
21175 v2hi __builtin_vis_fpadds16s (v2hi, v2hi);
21176 v4hi __builtin_vis_fpsubs16 (v4hi, v4hi);
21177 v2hi __builtin_vis_fpsubs16s (v2hi, v2hi);
21178 v2si __builtin_vis_fpadds32 (v2si, v2si);
21179 v1si __builtin_vis_fpadds32s (v1si, v1si);
21180 v2si __builtin_vis_fpsubs32 (v2si, v2si);
21181 v1si __builtin_vis_fpsubs32s (v1si, v1si);
21183 long __builtin_vis_fucmple8 (v8qi, v8qi);
21184 long __builtin_vis_fucmpne8 (v8qi, v8qi);
21185 long __builtin_vis_fucmpgt8 (v8qi, v8qi);
21186 long __builtin_vis_fucmpeq8 (v8qi, v8qi);
21188 float __builtin_vis_fhadds (float, float);
21189 double __builtin_vis_fhaddd (double, double);
21190 float __builtin_vis_fhsubs (float, float);
21191 double __builtin_vis_fhsubd (double, double);
21192 float __builtin_vis_fnhadds (float, float);
21193 double __builtin_vis_fnhaddd (double, double);
21195 int64_t __builtin_vis_umulxhi (int64_t, int64_t);
21196 int64_t __builtin_vis_xmulx (int64_t, int64_t);
21197 int64_t __builtin_vis_xmulxhi (int64_t, int64_t);
21200 When you use the @option{-mvis4} switch, the VIS version 4.0 built-in
21201 functions also become available:
21204 v8qi __builtin_vis_fpadd8 (v8qi, v8qi);
21205 v8qi __builtin_vis_fpadds8 (v8qi, v8qi);
21206 v8qi __builtin_vis_fpaddus8 (v8qi, v8qi);
21207 v4hi __builtin_vis_fpaddus16 (v4hi, v4hi);
21209 v8qi __builtin_vis_fpsub8 (v8qi, v8qi);
21210 v8qi __builtin_vis_fpsubs8 (v8qi, v8qi);
21211 v8qi __builtin_vis_fpsubus8 (v8qi, v8qi);
21212 v4hi __builtin_vis_fpsubus16 (v4hi, v4hi);
21214 long __builtin_vis_fpcmple8 (v8qi, v8qi);
21215 long __builtin_vis_fpcmpgt8 (v8qi, v8qi);
21216 long __builtin_vis_fpcmpule16 (v4hi, v4hi);
21217 long __builtin_vis_fpcmpugt16 (v4hi, v4hi);
21218 long __builtin_vis_fpcmpule32 (v2si, v2si);
21219 long __builtin_vis_fpcmpugt32 (v2si, v2si);
21221 v8qi __builtin_vis_fpmax8 (v8qi, v8qi);
21222 v4hi __builtin_vis_fpmax16 (v4hi, v4hi);
21223 v2si __builtin_vis_fpmax32 (v2si, v2si);
21225 v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi);
21226 v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi);
21227 v2si __builtin_vis_fpmaxu32 (v2si, v2si);
21230 v8qi __builtin_vis_fpmin8 (v8qi, v8qi);
21231 v4hi __builtin_vis_fpmin16 (v4hi, v4hi);
21232 v2si __builtin_vis_fpmin32 (v2si, v2si);
21234 v8qi __builtin_vis_fpminu8 (v8qi, v8qi);
21235 v4hi __builtin_vis_fpminu16 (v4hi, v4hi);
21236 v2si __builtin_vis_fpminu32 (v2si, v2si);
21239 When you use the @option{-mvis4b} switch, the VIS version 4.0B
21240 built-in functions also become available:
21243 v8qi __builtin_vis_dictunpack8 (double, int);
21244 v4hi __builtin_vis_dictunpack16 (double, int);
21245 v2si __builtin_vis_dictunpack32 (double, int);
21247 long __builtin_vis_fpcmple8shl (v8qi, v8qi, int);
21248 long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int);
21249 long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int);
21250 long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int);
21252 long __builtin_vis_fpcmple16shl (v4hi, v4hi, int);
21253 long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int);
21254 long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int);
21255 long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int);
21257 long __builtin_vis_fpcmple32shl (v2si, v2si, int);
21258 long __builtin_vis_fpcmpgt32shl (v2si, v2si, int);
21259 long __builtin_vis_fpcmpeq32shl (v2si, v2si, int);
21260 long __builtin_vis_fpcmpne32shl (v2si, v2si, int);
21262 long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int);
21263 long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int);
21264 long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int);
21265 long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int);
21266 long __builtin_vis_fpcmpule32shl (v2si, v2si, int);
21267 long __builtin_vis_fpcmpugt32shl (v2si, v2si, int);
21269 long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int);
21270 long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int);
21271 long __builtin_vis_fpcmpde32shl (v2si, v2si, int);
21273 long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int);
21274 long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int);
21275 long __builtin_vis_fpcmpur32shl (v2si, v2si, int);
21278 @node TI C6X Built-in Functions
21279 @subsection TI C6X Built-in Functions
21281 GCC provides intrinsics to access certain instructions of the TI C6X
21282 processors. These intrinsics, listed below, are available after
21283 inclusion of the @code{c6x_intrinsics.h} header file. They map directly
21284 to C6X instructions.
21288 int _sadd (int, int)
21289 int _ssub (int, int)
21290 int _sadd2 (int, int)
21291 int _ssub2 (int, int)
21292 long long _mpy2 (int, int)
21293 long long _smpy2 (int, int)
21294 int _add4 (int, int)
21295 int _sub4 (int, int)
21296 int _saddu4 (int, int)
21298 int _smpy (int, int)
21299 int _smpyh (int, int)
21300 int _smpyhl (int, int)
21301 int _smpylh (int, int)
21303 int _sshl (int, int)
21304 int _subc (int, int)
21306 int _avg2 (int, int)
21307 int _avgu4 (int, int)
21309 int _clrr (int, int)
21310 int _extr (int, int)
21311 int _extru (int, int)
21317 @node TILE-Gx Built-in Functions
21318 @subsection TILE-Gx Built-in Functions
21320 GCC provides intrinsics to access every instruction of the TILE-Gx
21321 processor. The intrinsics are of the form:
21325 unsigned long long __insn_@var{op} (...)
21329 Where @var{op} is the name of the instruction. Refer to the ISA manual
21330 for the complete list of instructions.
21332 GCC also provides intrinsics to directly access the network registers.
21333 The intrinsics are:
21337 unsigned long long __tile_idn0_receive (void)
21338 unsigned long long __tile_idn1_receive (void)
21339 unsigned long long __tile_udn0_receive (void)
21340 unsigned long long __tile_udn1_receive (void)
21341 unsigned long long __tile_udn2_receive (void)
21342 unsigned long long __tile_udn3_receive (void)
21343 void __tile_idn_send (unsigned long long)
21344 void __tile_udn_send (unsigned long long)
21348 The intrinsic @code{void __tile_network_barrier (void)} is used to
21349 guarantee that no network operations before it are reordered with
21352 @node TILEPro Built-in Functions
21353 @subsection TILEPro Built-in Functions
21355 GCC provides intrinsics to access every instruction of the TILEPro
21356 processor. The intrinsics are of the form:
21360 unsigned __insn_@var{op} (...)
21365 where @var{op} is the name of the instruction. Refer to the ISA manual
21366 for the complete list of instructions.
21368 GCC also provides intrinsics to directly access the network registers.
21369 The intrinsics are:
21373 unsigned __tile_idn0_receive (void)
21374 unsigned __tile_idn1_receive (void)
21375 unsigned __tile_sn_receive (void)
21376 unsigned __tile_udn0_receive (void)
21377 unsigned __tile_udn1_receive (void)
21378 unsigned __tile_udn2_receive (void)
21379 unsigned __tile_udn3_receive (void)
21380 void __tile_idn_send (unsigned)
21381 void __tile_sn_send (unsigned)
21382 void __tile_udn_send (unsigned)
21386 The intrinsic @code{void __tile_network_barrier (void)} is used to
21387 guarantee that no network operations before it are reordered with
21390 @node x86 Built-in Functions
21391 @subsection x86 Built-in Functions
21393 These built-in functions are available for the x86-32 and x86-64 family
21394 of computers, depending on the command-line switches used.
21396 If you specify command-line switches such as @option{-msse},
21397 the compiler could use the extended instruction sets even if the built-ins
21398 are not used explicitly in the program. For this reason, applications
21399 that perform run-time CPU detection must compile separate files for each
21400 supported architecture, using the appropriate flags. In particular,
21401 the file containing the CPU detection code should be compiled without
21404 The following machine modes are available for use with MMX built-in functions
21405 (@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers,
21406 @code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a
21407 vector of eight 8-bit integers. Some of the built-in functions operate on
21408 MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode.
21410 If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector
21411 of two 32-bit floating-point values.
21413 If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit
21414 floating-point values. Some instructions use a vector of four 32-bit
21415 integers, these use @code{V4SI}. Finally, some instructions operate on an
21416 entire vector register, interpreting it as a 128-bit integer, these use mode
21419 The x86-32 and x86-64 family of processors use additional built-in
21420 functions for efficient use of @code{TF} (@code{__float128}) 128-bit
21421 floating point and @code{TC} 128-bit complex floating-point values.
21423 The following floating-point built-in functions are always available. All
21424 of them implement the function that is part of the name.
21427 __float128 __builtin_fabsq (__float128)
21428 __float128 __builtin_copysignq (__float128, __float128)
21431 The following built-in functions are always available.
21434 @item __float128 __builtin_infq (void)
21435 Similar to @code{__builtin_inf}, except the return type is @code{__float128}.
21436 @findex __builtin_infq
21438 @item __float128 __builtin_huge_valq (void)
21439 Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}.
21440 @findex __builtin_huge_valq
21442 @item __float128 __builtin_nanq (void)
21443 Similar to @code{__builtin_nan}, except the return type is @code{__float128}.
21444 @findex __builtin_nanq
21446 @item __float128 __builtin_nansq (void)
21447 Similar to @code{__builtin_nans}, except the return type is @code{__float128}.
21448 @findex __builtin_nansq
21451 The following built-in function is always available.
21454 @item void __builtin_ia32_pause (void)
21455 Generates the @code{pause} machine instruction with a compiler memory
21459 The following built-in functions are always available and can be used to
21460 check the target platform type.
21462 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
21463 This function runs the CPU detection code to check the type of CPU and the
21464 features supported. This built-in function needs to be invoked along with the built-in functions
21465 to check CPU type and features, @code{__builtin_cpu_is} and
21466 @code{__builtin_cpu_supports}, only when used in a function that is
21467 executed before any constructors are called. The CPU detection code is
21468 automatically executed in a very high priority constructor.
21470 For example, this function has to be used in @code{ifunc} resolvers that
21471 check for CPU type using the built-in functions @code{__builtin_cpu_is}
21472 and @code{__builtin_cpu_supports}, or in constructors on targets that
21473 don't support constructor priority.
21476 static void (*resolve_memcpy (void)) (void)
21478 // ifunc resolvers fire before constructors, explicitly call the init
21480 __builtin_cpu_init ();
21481 if (__builtin_cpu_supports ("ssse3"))
21482 return ssse3_memcpy; // super fast memcpy with ssse3 instructions.
21484 return default_memcpy;
21487 void *memcpy (void *, const void *, size_t)
21488 __attribute__ ((ifunc ("resolve_memcpy")));
21493 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
21494 This function returns a positive integer if the run-time CPU
21495 is of type @var{cpuname}
21496 and returns @code{0} otherwise. The following CPU names can be detected:
21509 Intel Silvermont CPU.
21518 Intel Core i7 Nehalem CPU.
21521 Intel Core i7 Westmere CPU.
21524 Intel Core i7 Sandy Bridge CPU.
21527 Intel Core i7 Ivy Bridge CPU.
21530 Intel Core i7 Haswell CPU.
21533 Intel Core i7 Broadwell CPU.
21536 Intel Core i7 Skylake CPU.
21538 @item skylake-avx512
21539 Intel Core i7 Skylake AVX512 CPU.
21542 Intel Core i7 Cannon Lake CPU.
21544 @item icelake-client
21545 Intel Core i7 Ice Lake Client CPU.
21547 @item icelake-server
21548 Intel Core i7 Ice Lake Server CPU.
21551 Intel Core i7 Cascadelake CPU.
21554 Intel Core i7 Tigerlake CPU.
21557 Intel Core i7 Cooperlake CPU.
21560 Intel Atom Bonnell CPU.
21563 Intel Atom Silvermont CPU.
21566 Intel Atom Goldmont CPU.
21568 @item goldmont-plus
21569 Intel Atom Goldmont Plus CPU.
21572 Intel Atom Tremont CPU.
21575 Intel Knights Landing CPU.
21578 Intel Knights Mill CPU.
21581 AMD Family 10h CPU.
21584 AMD Family 10h Barcelona CPU.
21587 AMD Family 10h Shanghai CPU.
21590 AMD Family 10h Istanbul CPU.
21593 AMD Family 14h CPU.
21596 AMD Family 15h CPU.
21599 AMD Family 15h Bulldozer version 1.
21602 AMD Family 15h Bulldozer version 2.
21605 AMD Family 15h Bulldozer version 3.
21608 AMD Family 15h Bulldozer version 4.
21611 AMD Family 16h CPU.
21614 AMD Family 17h CPU.
21617 AMD Family 17h Zen version 1.
21620 AMD Family 17h Zen version 2.
21623 Here is an example:
21625 if (__builtin_cpu_is ("corei7"))
21627 do_corei7 (); // Core i7 specific implementation.
21631 do_generic (); // Generic implementation.
21636 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
21637 This function returns a positive integer if the run-time CPU
21638 supports @var{feature}
21639 and returns @code{0} otherwise. The following features can be detected:
21647 POPCNT instruction.
21655 SSSE3 instructions.
21657 SSE4.1 instructions.
21659 SSE4.2 instructions.
21665 SSE4A instructions.
21673 AVX512F instructions.
21681 PCLMUL instructions.
21683 AVX512VL instructions.
21685 AVX512BW instructions.
21687 AVX512DQ instructions.
21689 AVX512CD instructions.
21691 AVX512ER instructions.
21693 AVX512PF instructions.
21695 AVX512VBMI instructions.
21697 AVX512IFMA instructions.
21699 AVX5124VNNIW instructions.
21701 AVX5124FMAPS instructions.
21702 @item avx512vpopcntdq
21703 AVX512VPOPCNTDQ instructions.
21705 AVX512VBMI2 instructions.
21709 VPCLMULQDQ instructions.
21711 AVX512VNNI instructions.
21713 AVX512BITALG instructions.
21716 Here is an example:
21718 if (__builtin_cpu_supports ("popcnt"))
21720 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc");
21724 count = generic_countbits (n); //generic implementation.
21730 The following built-in functions are made available by @option{-mmmx}.
21731 All of them generate the machine instruction that is part of the name.
21734 v8qi __builtin_ia32_paddb (v8qi, v8qi)
21735 v4hi __builtin_ia32_paddw (v4hi, v4hi)
21736 v2si __builtin_ia32_paddd (v2si, v2si)
21737 v8qi __builtin_ia32_psubb (v8qi, v8qi)
21738 v4hi __builtin_ia32_psubw (v4hi, v4hi)
21739 v2si __builtin_ia32_psubd (v2si, v2si)
21740 v8qi __builtin_ia32_paddsb (v8qi, v8qi)
21741 v4hi __builtin_ia32_paddsw (v4hi, v4hi)
21742 v8qi __builtin_ia32_psubsb (v8qi, v8qi)
21743 v4hi __builtin_ia32_psubsw (v4hi, v4hi)
21744 v8qi __builtin_ia32_paddusb (v8qi, v8qi)
21745 v4hi __builtin_ia32_paddusw (v4hi, v4hi)
21746 v8qi __builtin_ia32_psubusb (v8qi, v8qi)
21747 v4hi __builtin_ia32_psubusw (v4hi, v4hi)
21748 v4hi __builtin_ia32_pmullw (v4hi, v4hi)
21749 v4hi __builtin_ia32_pmulhw (v4hi, v4hi)
21750 di __builtin_ia32_pand (di, di)
21751 di __builtin_ia32_pandn (di,di)
21752 di __builtin_ia32_por (di, di)
21753 di __builtin_ia32_pxor (di, di)
21754 v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi)
21755 v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi)
21756 v2si __builtin_ia32_pcmpeqd (v2si, v2si)
21757 v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi)
21758 v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi)
21759 v2si __builtin_ia32_pcmpgtd (v2si, v2si)
21760 v8qi __builtin_ia32_punpckhbw (v8qi, v8qi)
21761 v4hi __builtin_ia32_punpckhwd (v4hi, v4hi)
21762 v2si __builtin_ia32_punpckhdq (v2si, v2si)
21763 v8qi __builtin_ia32_punpcklbw (v8qi, v8qi)
21764 v4hi __builtin_ia32_punpcklwd (v4hi, v4hi)
21765 v2si __builtin_ia32_punpckldq (v2si, v2si)
21766 v8qi __builtin_ia32_packsswb (v4hi, v4hi)
21767 v4hi __builtin_ia32_packssdw (v2si, v2si)
21768 v8qi __builtin_ia32_packuswb (v4hi, v4hi)
21770 v4hi __builtin_ia32_psllw (v4hi, v4hi)
21771 v2si __builtin_ia32_pslld (v2si, v2si)
21772 v1di __builtin_ia32_psllq (v1di, v1di)
21773 v4hi __builtin_ia32_psrlw (v4hi, v4hi)
21774 v2si __builtin_ia32_psrld (v2si, v2si)
21775 v1di __builtin_ia32_psrlq (v1di, v1di)
21776 v4hi __builtin_ia32_psraw (v4hi, v4hi)
21777 v2si __builtin_ia32_psrad (v2si, v2si)
21778 v4hi __builtin_ia32_psllwi (v4hi, int)
21779 v2si __builtin_ia32_pslldi (v2si, int)
21780 v1di __builtin_ia32_psllqi (v1di, int)
21781 v4hi __builtin_ia32_psrlwi (v4hi, int)
21782 v2si __builtin_ia32_psrldi (v2si, int)
21783 v1di __builtin_ia32_psrlqi (v1di, int)
21784 v4hi __builtin_ia32_psrawi (v4hi, int)
21785 v2si __builtin_ia32_psradi (v2si, int)
21789 The following built-in functions are made available either with
21790 @option{-msse}, or with @option{-m3dnowa}. All of them generate
21791 the machine instruction that is part of the name.
21794 v4hi __builtin_ia32_pmulhuw (v4hi, v4hi)
21795 v8qi __builtin_ia32_pavgb (v8qi, v8qi)
21796 v4hi __builtin_ia32_pavgw (v4hi, v4hi)
21797 v1di __builtin_ia32_psadbw (v8qi, v8qi)
21798 v8qi __builtin_ia32_pmaxub (v8qi, v8qi)
21799 v4hi __builtin_ia32_pmaxsw (v4hi, v4hi)
21800 v8qi __builtin_ia32_pminub (v8qi, v8qi)
21801 v4hi __builtin_ia32_pminsw (v4hi, v4hi)
21802 int __builtin_ia32_pmovmskb (v8qi)
21803 void __builtin_ia32_maskmovq (v8qi, v8qi, char *)
21804 void __builtin_ia32_movntq (di *, di)
21805 void __builtin_ia32_sfence (void)
21808 The following built-in functions are available when @option{-msse} is used.
21809 All of them generate the machine instruction that is part of the name.
21812 int __builtin_ia32_comieq (v4sf, v4sf)
21813 int __builtin_ia32_comineq (v4sf, v4sf)
21814 int __builtin_ia32_comilt (v4sf, v4sf)
21815 int __builtin_ia32_comile (v4sf, v4sf)
21816 int __builtin_ia32_comigt (v4sf, v4sf)
21817 int __builtin_ia32_comige (v4sf, v4sf)
21818 int __builtin_ia32_ucomieq (v4sf, v4sf)
21819 int __builtin_ia32_ucomineq (v4sf, v4sf)
21820 int __builtin_ia32_ucomilt (v4sf, v4sf)
21821 int __builtin_ia32_ucomile (v4sf, v4sf)
21822 int __builtin_ia32_ucomigt (v4sf, v4sf)
21823 int __builtin_ia32_ucomige (v4sf, v4sf)
21824 v4sf __builtin_ia32_addps (v4sf, v4sf)
21825 v4sf __builtin_ia32_subps (v4sf, v4sf)
21826 v4sf __builtin_ia32_mulps (v4sf, v4sf)
21827 v4sf __builtin_ia32_divps (v4sf, v4sf)
21828 v4sf __builtin_ia32_addss (v4sf, v4sf)
21829 v4sf __builtin_ia32_subss (v4sf, v4sf)
21830 v4sf __builtin_ia32_mulss (v4sf, v4sf)
21831 v4sf __builtin_ia32_divss (v4sf, v4sf)
21832 v4sf __builtin_ia32_cmpeqps (v4sf, v4sf)
21833 v4sf __builtin_ia32_cmpltps (v4sf, v4sf)
21834 v4sf __builtin_ia32_cmpleps (v4sf, v4sf)
21835 v4sf __builtin_ia32_cmpgtps (v4sf, v4sf)
21836 v4sf __builtin_ia32_cmpgeps (v4sf, v4sf)
21837 v4sf __builtin_ia32_cmpunordps (v4sf, v4sf)
21838 v4sf __builtin_ia32_cmpneqps (v4sf, v4sf)
21839 v4sf __builtin_ia32_cmpnltps (v4sf, v4sf)
21840 v4sf __builtin_ia32_cmpnleps (v4sf, v4sf)
21841 v4sf __builtin_ia32_cmpngtps (v4sf, v4sf)
21842 v4sf __builtin_ia32_cmpngeps (v4sf, v4sf)
21843 v4sf __builtin_ia32_cmpordps (v4sf, v4sf)
21844 v4sf __builtin_ia32_cmpeqss (v4sf, v4sf)
21845 v4sf __builtin_ia32_cmpltss (v4sf, v4sf)
21846 v4sf __builtin_ia32_cmpless (v4sf, v4sf)
21847 v4sf __builtin_ia32_cmpunordss (v4sf, v4sf)
21848 v4sf __builtin_ia32_cmpneqss (v4sf, v4sf)
21849 v4sf __builtin_ia32_cmpnltss (v4sf, v4sf)
21850 v4sf __builtin_ia32_cmpnless (v4sf, v4sf)
21851 v4sf __builtin_ia32_cmpordss (v4sf, v4sf)
21852 v4sf __builtin_ia32_maxps (v4sf, v4sf)
21853 v4sf __builtin_ia32_maxss (v4sf, v4sf)
21854 v4sf __builtin_ia32_minps (v4sf, v4sf)
21855 v4sf __builtin_ia32_minss (v4sf, v4sf)
21856 v4sf __builtin_ia32_andps (v4sf, v4sf)
21857 v4sf __builtin_ia32_andnps (v4sf, v4sf)
21858 v4sf __builtin_ia32_orps (v4sf, v4sf)
21859 v4sf __builtin_ia32_xorps (v4sf, v4sf)
21860 v4sf __builtin_ia32_movss (v4sf, v4sf)
21861 v4sf __builtin_ia32_movhlps (v4sf, v4sf)
21862 v4sf __builtin_ia32_movlhps (v4sf, v4sf)
21863 v4sf __builtin_ia32_unpckhps (v4sf, v4sf)
21864 v4sf __builtin_ia32_unpcklps (v4sf, v4sf)
21865 v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si)
21866 v4sf __builtin_ia32_cvtsi2ss (v4sf, int)
21867 v2si __builtin_ia32_cvtps2pi (v4sf)
21868 int __builtin_ia32_cvtss2si (v4sf)
21869 v2si __builtin_ia32_cvttps2pi (v4sf)
21870 int __builtin_ia32_cvttss2si (v4sf)
21871 v4sf __builtin_ia32_rcpps (v4sf)
21872 v4sf __builtin_ia32_rsqrtps (v4sf)
21873 v4sf __builtin_ia32_sqrtps (v4sf)
21874 v4sf __builtin_ia32_rcpss (v4sf)
21875 v4sf __builtin_ia32_rsqrtss (v4sf)
21876 v4sf __builtin_ia32_sqrtss (v4sf)
21877 v4sf __builtin_ia32_shufps (v4sf, v4sf, int)
21878 void __builtin_ia32_movntps (float *, v4sf)
21879 int __builtin_ia32_movmskps (v4sf)
21882 The following built-in functions are available when @option{-msse} is used.
21885 @item v4sf __builtin_ia32_loadups (float *)
21886 Generates the @code{movups} machine instruction as a load from memory.
21887 @item void __builtin_ia32_storeups (float *, v4sf)
21888 Generates the @code{movups} machine instruction as a store to memory.
21889 @item v4sf __builtin_ia32_loadss (float *)
21890 Generates the @code{movss} machine instruction as a load from memory.
21891 @item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)
21892 Generates the @code{movhps} machine instruction as a load from memory.
21893 @item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)
21894 Generates the @code{movlps} machine instruction as a load from memory
21895 @item void __builtin_ia32_storehps (v2sf *, v4sf)
21896 Generates the @code{movhps} machine instruction as a store to memory.
21897 @item void __builtin_ia32_storelps (v2sf *, v4sf)
21898 Generates the @code{movlps} machine instruction as a store to memory.
21901 The following built-in functions are available when @option{-msse2} is used.
21902 All of them generate the machine instruction that is part of the name.
21905 int __builtin_ia32_comisdeq (v2df, v2df)
21906 int __builtin_ia32_comisdlt (v2df, v2df)
21907 int __builtin_ia32_comisdle (v2df, v2df)
21908 int __builtin_ia32_comisdgt (v2df, v2df)
21909 int __builtin_ia32_comisdge (v2df, v2df)
21910 int __builtin_ia32_comisdneq (v2df, v2df)
21911 int __builtin_ia32_ucomisdeq (v2df, v2df)
21912 int __builtin_ia32_ucomisdlt (v2df, v2df)
21913 int __builtin_ia32_ucomisdle (v2df, v2df)
21914 int __builtin_ia32_ucomisdgt (v2df, v2df)
21915 int __builtin_ia32_ucomisdge (v2df, v2df)
21916 int __builtin_ia32_ucomisdneq (v2df, v2df)
21917 v2df __builtin_ia32_cmpeqpd (v2df, v2df)
21918 v2df __builtin_ia32_cmpltpd (v2df, v2df)
21919 v2df __builtin_ia32_cmplepd (v2df, v2df)
21920 v2df __builtin_ia32_cmpgtpd (v2df, v2df)
21921 v2df __builtin_ia32_cmpgepd (v2df, v2df)
21922 v2df __builtin_ia32_cmpunordpd (v2df, v2df)
21923 v2df __builtin_ia32_cmpneqpd (v2df, v2df)
21924 v2df __builtin_ia32_cmpnltpd (v2df, v2df)
21925 v2df __builtin_ia32_cmpnlepd (v2df, v2df)
21926 v2df __builtin_ia32_cmpngtpd (v2df, v2df)
21927 v2df __builtin_ia32_cmpngepd (v2df, v2df)
21928 v2df __builtin_ia32_cmpordpd (v2df, v2df)
21929 v2df __builtin_ia32_cmpeqsd (v2df, v2df)
21930 v2df __builtin_ia32_cmpltsd (v2df, v2df)
21931 v2df __builtin_ia32_cmplesd (v2df, v2df)
21932 v2df __builtin_ia32_cmpunordsd (v2df, v2df)
21933 v2df __builtin_ia32_cmpneqsd (v2df, v2df)
21934 v2df __builtin_ia32_cmpnltsd (v2df, v2df)
21935 v2df __builtin_ia32_cmpnlesd (v2df, v2df)
21936 v2df __builtin_ia32_cmpordsd (v2df, v2df)
21937 v2di __builtin_ia32_paddq (v2di, v2di)
21938 v2di __builtin_ia32_psubq (v2di, v2di)
21939 v2df __builtin_ia32_addpd (v2df, v2df)
21940 v2df __builtin_ia32_subpd (v2df, v2df)
21941 v2df __builtin_ia32_mulpd (v2df, v2df)
21942 v2df __builtin_ia32_divpd (v2df, v2df)
21943 v2df __builtin_ia32_addsd (v2df, v2df)
21944 v2df __builtin_ia32_subsd (v2df, v2df)
21945 v2df __builtin_ia32_mulsd (v2df, v2df)
21946 v2df __builtin_ia32_divsd (v2df, v2df)
21947 v2df __builtin_ia32_minpd (v2df, v2df)
21948 v2df __builtin_ia32_maxpd (v2df, v2df)
21949 v2df __builtin_ia32_minsd (v2df, v2df)
21950 v2df __builtin_ia32_maxsd (v2df, v2df)
21951 v2df __builtin_ia32_andpd (v2df, v2df)
21952 v2df __builtin_ia32_andnpd (v2df, v2df)
21953 v2df __builtin_ia32_orpd (v2df, v2df)
21954 v2df __builtin_ia32_xorpd (v2df, v2df)
21955 v2df __builtin_ia32_movsd (v2df, v2df)
21956 v2df __builtin_ia32_unpckhpd (v2df, v2df)
21957 v2df __builtin_ia32_unpcklpd (v2df, v2df)
21958 v16qi __builtin_ia32_paddb128 (v16qi, v16qi)
21959 v8hi __builtin_ia32_paddw128 (v8hi, v8hi)
21960 v4si __builtin_ia32_paddd128 (v4si, v4si)
21961 v2di __builtin_ia32_paddq128 (v2di, v2di)
21962 v16qi __builtin_ia32_psubb128 (v16qi, v16qi)
21963 v8hi __builtin_ia32_psubw128 (v8hi, v8hi)
21964 v4si __builtin_ia32_psubd128 (v4si, v4si)
21965 v2di __builtin_ia32_psubq128 (v2di, v2di)
21966 v8hi __builtin_ia32_pmullw128 (v8hi, v8hi)
21967 v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi)
21968 v2di __builtin_ia32_pand128 (v2di, v2di)
21969 v2di __builtin_ia32_pandn128 (v2di, v2di)
21970 v2di __builtin_ia32_por128 (v2di, v2di)
21971 v2di __builtin_ia32_pxor128 (v2di, v2di)
21972 v16qi __builtin_ia32_pavgb128 (v16qi, v16qi)
21973 v8hi __builtin_ia32_pavgw128 (v8hi, v8hi)
21974 v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi)
21975 v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi)
21976 v4si __builtin_ia32_pcmpeqd128 (v4si, v4si)
21977 v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi)
21978 v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi)
21979 v4si __builtin_ia32_pcmpgtd128 (v4si, v4si)
21980 v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi)
21981 v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi)
21982 v16qi __builtin_ia32_pminub128 (v16qi, v16qi)
21983 v8hi __builtin_ia32_pminsw128 (v8hi, v8hi)
21984 v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi)
21985 v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi)
21986 v4si __builtin_ia32_punpckhdq128 (v4si, v4si)
21987 v2di __builtin_ia32_punpckhqdq128 (v2di, v2di)
21988 v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi)
21989 v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi)
21990 v4si __builtin_ia32_punpckldq128 (v4si, v4si)
21991 v2di __builtin_ia32_punpcklqdq128 (v2di, v2di)
21992 v16qi __builtin_ia32_packsswb128 (v8hi, v8hi)
21993 v8hi __builtin_ia32_packssdw128 (v4si, v4si)
21994 v16qi __builtin_ia32_packuswb128 (v8hi, v8hi)
21995 v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi)
21996 void __builtin_ia32_maskmovdqu (v16qi, v16qi)
21997 v2df __builtin_ia32_loadupd (double *)
21998 void __builtin_ia32_storeupd (double *, v2df)
21999 v2df __builtin_ia32_loadhpd (v2df, double const *)
22000 v2df __builtin_ia32_loadlpd (v2df, double const *)
22001 int __builtin_ia32_movmskpd (v2df)
22002 int __builtin_ia32_pmovmskb128 (v16qi)
22003 void __builtin_ia32_movnti (int *, int)
22004 void __builtin_ia32_movnti64 (long long int *, long long int)
22005 void __builtin_ia32_movntpd (double *, v2df)
22006 void __builtin_ia32_movntdq (v2df *, v2df)
22007 v4si __builtin_ia32_pshufd (v4si, int)
22008 v8hi __builtin_ia32_pshuflw (v8hi, int)
22009 v8hi __builtin_ia32_pshufhw (v8hi, int)
22010 v2di __builtin_ia32_psadbw128 (v16qi, v16qi)
22011 v2df __builtin_ia32_sqrtpd (v2df)
22012 v2df __builtin_ia32_sqrtsd (v2df)
22013 v2df __builtin_ia32_shufpd (v2df, v2df, int)
22014 v2df __builtin_ia32_cvtdq2pd (v4si)
22015 v4sf __builtin_ia32_cvtdq2ps (v4si)
22016 v4si __builtin_ia32_cvtpd2dq (v2df)
22017 v2si __builtin_ia32_cvtpd2pi (v2df)
22018 v4sf __builtin_ia32_cvtpd2ps (v2df)
22019 v4si __builtin_ia32_cvttpd2dq (v2df)
22020 v2si __builtin_ia32_cvttpd2pi (v2df)
22021 v2df __builtin_ia32_cvtpi2pd (v2si)
22022 int __builtin_ia32_cvtsd2si (v2df)
22023 int __builtin_ia32_cvttsd2si (v2df)
22024 long long __builtin_ia32_cvtsd2si64 (v2df)
22025 long long __builtin_ia32_cvttsd2si64 (v2df)
22026 v4si __builtin_ia32_cvtps2dq (v4sf)
22027 v2df __builtin_ia32_cvtps2pd (v4sf)
22028 v4si __builtin_ia32_cvttps2dq (v4sf)
22029 v2df __builtin_ia32_cvtsi2sd (v2df, int)
22030 v2df __builtin_ia32_cvtsi642sd (v2df, long long)
22031 v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df)
22032 v2df __builtin_ia32_cvtss2sd (v2df, v4sf)
22033 void __builtin_ia32_clflush (const void *)
22034 void __builtin_ia32_lfence (void)
22035 void __builtin_ia32_mfence (void)
22036 v16qi __builtin_ia32_loaddqu (const char *)
22037 void __builtin_ia32_storedqu (char *, v16qi)
22038 v1di __builtin_ia32_pmuludq (v2si, v2si)
22039 v2di __builtin_ia32_pmuludq128 (v4si, v4si)
22040 v8hi __builtin_ia32_psllw128 (v8hi, v8hi)
22041 v4si __builtin_ia32_pslld128 (v4si, v4si)
22042 v2di __builtin_ia32_psllq128 (v2di, v2di)
22043 v8hi __builtin_ia32_psrlw128 (v8hi, v8hi)
22044 v4si __builtin_ia32_psrld128 (v4si, v4si)
22045 v2di __builtin_ia32_psrlq128 (v2di, v2di)
22046 v8hi __builtin_ia32_psraw128 (v8hi, v8hi)
22047 v4si __builtin_ia32_psrad128 (v4si, v4si)
22048 v2di __builtin_ia32_pslldqi128 (v2di, int)
22049 v8hi __builtin_ia32_psllwi128 (v8hi, int)
22050 v4si __builtin_ia32_pslldi128 (v4si, int)
22051 v2di __builtin_ia32_psllqi128 (v2di, int)
22052 v2di __builtin_ia32_psrldqi128 (v2di, int)
22053 v8hi __builtin_ia32_psrlwi128 (v8hi, int)
22054 v4si __builtin_ia32_psrldi128 (v4si, int)
22055 v2di __builtin_ia32_psrlqi128 (v2di, int)
22056 v8hi __builtin_ia32_psrawi128 (v8hi, int)
22057 v4si __builtin_ia32_psradi128 (v4si, int)
22058 v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi)
22059 v2di __builtin_ia32_movq128 (v2di)
22062 The following built-in functions are available when @option{-msse3} is used.
22063 All of them generate the machine instruction that is part of the name.
22066 v2df __builtin_ia32_addsubpd (v2df, v2df)
22067 v4sf __builtin_ia32_addsubps (v4sf, v4sf)
22068 v2df __builtin_ia32_haddpd (v2df, v2df)
22069 v4sf __builtin_ia32_haddps (v4sf, v4sf)
22070 v2df __builtin_ia32_hsubpd (v2df, v2df)
22071 v4sf __builtin_ia32_hsubps (v4sf, v4sf)
22072 v16qi __builtin_ia32_lddqu (char const *)
22073 void __builtin_ia32_monitor (void *, unsigned int, unsigned int)
22074 v4sf __builtin_ia32_movshdup (v4sf)
22075 v4sf __builtin_ia32_movsldup (v4sf)
22076 void __builtin_ia32_mwait (unsigned int, unsigned int)
22079 The following built-in functions are available when @option{-mssse3} is used.
22080 All of them generate the machine instruction that is part of the name.
22083 v2si __builtin_ia32_phaddd (v2si, v2si)
22084 v4hi __builtin_ia32_phaddw (v4hi, v4hi)
22085 v4hi __builtin_ia32_phaddsw (v4hi, v4hi)
22086 v2si __builtin_ia32_phsubd (v2si, v2si)
22087 v4hi __builtin_ia32_phsubw (v4hi, v4hi)
22088 v4hi __builtin_ia32_phsubsw (v4hi, v4hi)
22089 v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi)
22090 v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi)
22091 v8qi __builtin_ia32_pshufb (v8qi, v8qi)
22092 v8qi __builtin_ia32_psignb (v8qi, v8qi)
22093 v2si __builtin_ia32_psignd (v2si, v2si)
22094 v4hi __builtin_ia32_psignw (v4hi, v4hi)
22095 v1di __builtin_ia32_palignr (v1di, v1di, int)
22096 v8qi __builtin_ia32_pabsb (v8qi)
22097 v2si __builtin_ia32_pabsd (v2si)
22098 v4hi __builtin_ia32_pabsw (v4hi)
22101 The following built-in functions are available when @option{-mssse3} is used.
22102 All of them generate the machine instruction that is part of the name.
22105 v4si __builtin_ia32_phaddd128 (v4si, v4si)
22106 v8hi __builtin_ia32_phaddw128 (v8hi, v8hi)
22107 v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi)
22108 v4si __builtin_ia32_phsubd128 (v4si, v4si)
22109 v8hi __builtin_ia32_phsubw128 (v8hi, v8hi)
22110 v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi)
22111 v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi)
22112 v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi)
22113 v16qi __builtin_ia32_pshufb128 (v16qi, v16qi)
22114 v16qi __builtin_ia32_psignb128 (v16qi, v16qi)
22115 v4si __builtin_ia32_psignd128 (v4si, v4si)
22116 v8hi __builtin_ia32_psignw128 (v8hi, v8hi)
22117 v2di __builtin_ia32_palignr128 (v2di, v2di, int)
22118 v16qi __builtin_ia32_pabsb128 (v16qi)
22119 v4si __builtin_ia32_pabsd128 (v4si)
22120 v8hi __builtin_ia32_pabsw128 (v8hi)
22123 The following built-in functions are available when @option{-msse4.1} is
22124 used. All of them generate the machine instruction that is part of the
22128 v2df __builtin_ia32_blendpd (v2df, v2df, const int)
22129 v4sf __builtin_ia32_blendps (v4sf, v4sf, const int)
22130 v2df __builtin_ia32_blendvpd (v2df, v2df, v2df)
22131 v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf)
22132 v2df __builtin_ia32_dppd (v2df, v2df, const int)
22133 v4sf __builtin_ia32_dpps (v4sf, v4sf, const int)
22134 v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int)
22135 v2di __builtin_ia32_movntdqa (v2di *);
22136 v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int)
22137 v8hi __builtin_ia32_packusdw128 (v4si, v4si)
22138 v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi)
22139 v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int)
22140 v2di __builtin_ia32_pcmpeqq (v2di, v2di)
22141 v8hi __builtin_ia32_phminposuw128 (v8hi)
22142 v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi)
22143 v4si __builtin_ia32_pmaxsd128 (v4si, v4si)
22144 v4si __builtin_ia32_pmaxud128 (v4si, v4si)
22145 v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi)
22146 v16qi __builtin_ia32_pminsb128 (v16qi, v16qi)
22147 v4si __builtin_ia32_pminsd128 (v4si, v4si)
22148 v4si __builtin_ia32_pminud128 (v4si, v4si)
22149 v8hi __builtin_ia32_pminuw128 (v8hi, v8hi)
22150 v4si __builtin_ia32_pmovsxbd128 (v16qi)
22151 v2di __builtin_ia32_pmovsxbq128 (v16qi)
22152 v8hi __builtin_ia32_pmovsxbw128 (v16qi)
22153 v2di __builtin_ia32_pmovsxdq128 (v4si)
22154 v4si __builtin_ia32_pmovsxwd128 (v8hi)
22155 v2di __builtin_ia32_pmovsxwq128 (v8hi)
22156 v4si __builtin_ia32_pmovzxbd128 (v16qi)
22157 v2di __builtin_ia32_pmovzxbq128 (v16qi)
22158 v8hi __builtin_ia32_pmovzxbw128 (v16qi)
22159 v2di __builtin_ia32_pmovzxdq128 (v4si)
22160 v4si __builtin_ia32_pmovzxwd128 (v8hi)
22161 v2di __builtin_ia32_pmovzxwq128 (v8hi)
22162 v2di __builtin_ia32_pmuldq128 (v4si, v4si)
22163 v4si __builtin_ia32_pmulld128 (v4si, v4si)
22164 int __builtin_ia32_ptestc128 (v2di, v2di)
22165 int __builtin_ia32_ptestnzc128 (v2di, v2di)
22166 int __builtin_ia32_ptestz128 (v2di, v2di)
22167 v2df __builtin_ia32_roundpd (v2df, const int)
22168 v4sf __builtin_ia32_roundps (v4sf, const int)
22169 v2df __builtin_ia32_roundsd (v2df, v2df, const int)
22170 v4sf __builtin_ia32_roundss (v4sf, v4sf, const int)
22173 The following built-in functions are available when @option{-msse4.1} is
22177 @item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)
22178 Generates the @code{insertps} machine instruction.
22179 @item int __builtin_ia32_vec_ext_v16qi (v16qi, const int)
22180 Generates the @code{pextrb} machine instruction.
22181 @item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)
22182 Generates the @code{pinsrb} machine instruction.
22183 @item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)
22184 Generates the @code{pinsrd} machine instruction.
22185 @item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)
22186 Generates the @code{pinsrq} machine instruction in 64bit mode.
22189 The following built-in functions are changed to generate new SSE4.1
22190 instructions when @option{-msse4.1} is used.
22193 @item float __builtin_ia32_vec_ext_v4sf (v4sf, const int)
22194 Generates the @code{extractps} machine instruction.
22195 @item int __builtin_ia32_vec_ext_v4si (v4si, const int)
22196 Generates the @code{pextrd} machine instruction.
22197 @item long long __builtin_ia32_vec_ext_v2di (v2di, const int)
22198 Generates the @code{pextrq} machine instruction in 64bit mode.
22201 The following built-in functions are available when @option{-msse4.2} is
22202 used. All of them generate the machine instruction that is part of the
22206 v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int)
22207 int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int)
22208 int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int)
22209 int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int)
22210 int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int)
22211 int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int)
22212 int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int)
22213 v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int)
22214 int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int)
22215 int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int)
22216 int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int)
22217 int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int)
22218 int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int)
22219 int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int)
22220 v2di __builtin_ia32_pcmpgtq (v2di, v2di)
22223 The following built-in functions are available when @option{-msse4.2} is
22227 @item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char)
22228 Generates the @code{crc32b} machine instruction.
22229 @item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short)
22230 Generates the @code{crc32w} machine instruction.
22231 @item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int)
22232 Generates the @code{crc32l} machine instruction.
22233 @item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long)
22234 Generates the @code{crc32q} machine instruction.
22237 The following built-in functions are changed to generate new SSE4.2
22238 instructions when @option{-msse4.2} is used.
22241 @item int __builtin_popcount (unsigned int)
22242 Generates the @code{popcntl} machine instruction.
22243 @item int __builtin_popcountl (unsigned long)
22244 Generates the @code{popcntl} or @code{popcntq} machine instruction,
22245 depending on the size of @code{unsigned long}.
22246 @item int __builtin_popcountll (unsigned long long)
22247 Generates the @code{popcntq} machine instruction.
22250 The following built-in functions are available when @option{-mavx} is
22251 used. All of them generate the machine instruction that is part of the
22255 v4df __builtin_ia32_addpd256 (v4df,v4df)
22256 v8sf __builtin_ia32_addps256 (v8sf,v8sf)
22257 v4df __builtin_ia32_addsubpd256 (v4df,v4df)
22258 v8sf __builtin_ia32_addsubps256 (v8sf,v8sf)
22259 v4df __builtin_ia32_andnpd256 (v4df,v4df)
22260 v8sf __builtin_ia32_andnps256 (v8sf,v8sf)
22261 v4df __builtin_ia32_andpd256 (v4df,v4df)
22262 v8sf __builtin_ia32_andps256 (v8sf,v8sf)
22263 v4df __builtin_ia32_blendpd256 (v4df,v4df,int)
22264 v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int)
22265 v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df)
22266 v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf)
22267 v2df __builtin_ia32_cmppd (v2df,v2df,int)
22268 v4df __builtin_ia32_cmppd256 (v4df,v4df,int)
22269 v4sf __builtin_ia32_cmpps (v4sf,v4sf,int)
22270 v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int)
22271 v2df __builtin_ia32_cmpsd (v2df,v2df,int)
22272 v4sf __builtin_ia32_cmpss (v4sf,v4sf,int)
22273 v4df __builtin_ia32_cvtdq2pd256 (v4si)
22274 v8sf __builtin_ia32_cvtdq2ps256 (v8si)
22275 v4si __builtin_ia32_cvtpd2dq256 (v4df)
22276 v4sf __builtin_ia32_cvtpd2ps256 (v4df)
22277 v8si __builtin_ia32_cvtps2dq256 (v8sf)
22278 v4df __builtin_ia32_cvtps2pd256 (v4sf)
22279 v4si __builtin_ia32_cvttpd2dq256 (v4df)
22280 v8si __builtin_ia32_cvttps2dq256 (v8sf)
22281 v4df __builtin_ia32_divpd256 (v4df,v4df)
22282 v8sf __builtin_ia32_divps256 (v8sf,v8sf)
22283 v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int)
22284 v4df __builtin_ia32_haddpd256 (v4df,v4df)
22285 v8sf __builtin_ia32_haddps256 (v8sf,v8sf)
22286 v4df __builtin_ia32_hsubpd256 (v4df,v4df)
22287 v8sf __builtin_ia32_hsubps256 (v8sf,v8sf)
22288 v32qi __builtin_ia32_lddqu256 (pcchar)
22289 v32qi __builtin_ia32_loaddqu256 (pcchar)
22290 v4df __builtin_ia32_loadupd256 (pcdouble)
22291 v8sf __builtin_ia32_loadups256 (pcfloat)
22292 v2df __builtin_ia32_maskloadpd (pcv2df,v2df)
22293 v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df)
22294 v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf)
22295 v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf)
22296 void __builtin_ia32_maskstorepd (pv2df,v2df,v2df)
22297 void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df)
22298 void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf)
22299 void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf)
22300 v4df __builtin_ia32_maxpd256 (v4df,v4df)
22301 v8sf __builtin_ia32_maxps256 (v8sf,v8sf)
22302 v4df __builtin_ia32_minpd256 (v4df,v4df)
22303 v8sf __builtin_ia32_minps256 (v8sf,v8sf)
22304 v4df __builtin_ia32_movddup256 (v4df)
22305 int __builtin_ia32_movmskpd256 (v4df)
22306 int __builtin_ia32_movmskps256 (v8sf)
22307 v8sf __builtin_ia32_movshdup256 (v8sf)
22308 v8sf __builtin_ia32_movsldup256 (v8sf)
22309 v4df __builtin_ia32_mulpd256 (v4df,v4df)
22310 v8sf __builtin_ia32_mulps256 (v8sf,v8sf)
22311 v4df __builtin_ia32_orpd256 (v4df,v4df)
22312 v8sf __builtin_ia32_orps256 (v8sf,v8sf)
22313 v2df __builtin_ia32_pd_pd256 (v4df)
22314 v4df __builtin_ia32_pd256_pd (v2df)
22315 v4sf __builtin_ia32_ps_ps256 (v8sf)
22316 v8sf __builtin_ia32_ps256_ps (v4sf)
22317 int __builtin_ia32_ptestc256 (v4di,v4di,ptest)
22318 int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest)
22319 int __builtin_ia32_ptestz256 (v4di,v4di,ptest)
22320 v8sf __builtin_ia32_rcpps256 (v8sf)
22321 v4df __builtin_ia32_roundpd256 (v4df,int)
22322 v8sf __builtin_ia32_roundps256 (v8sf,int)
22323 v8sf __builtin_ia32_rsqrtps_nr256 (v8sf)
22324 v8sf __builtin_ia32_rsqrtps256 (v8sf)
22325 v4df __builtin_ia32_shufpd256 (v4df,v4df,int)
22326 v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int)
22327 v4si __builtin_ia32_si_si256 (v8si)
22328 v8si __builtin_ia32_si256_si (v4si)
22329 v4df __builtin_ia32_sqrtpd256 (v4df)
22330 v8sf __builtin_ia32_sqrtps_nr256 (v8sf)
22331 v8sf __builtin_ia32_sqrtps256 (v8sf)
22332 void __builtin_ia32_storedqu256 (pchar,v32qi)
22333 void __builtin_ia32_storeupd256 (pdouble,v4df)
22334 void __builtin_ia32_storeups256 (pfloat,v8sf)
22335 v4df __builtin_ia32_subpd256 (v4df,v4df)
22336 v8sf __builtin_ia32_subps256 (v8sf,v8sf)
22337 v4df __builtin_ia32_unpckhpd256 (v4df,v4df)
22338 v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf)
22339 v4df __builtin_ia32_unpcklpd256 (v4df,v4df)
22340 v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf)
22341 v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df)
22342 v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf)
22343 v4df __builtin_ia32_vbroadcastsd256 (pcdouble)
22344 v4sf __builtin_ia32_vbroadcastss (pcfloat)
22345 v8sf __builtin_ia32_vbroadcastss256 (pcfloat)
22346 v2df __builtin_ia32_vextractf128_pd256 (v4df,int)
22347 v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int)
22348 v4si __builtin_ia32_vextractf128_si256 (v8si,int)
22349 v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int)
22350 v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int)
22351 v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int)
22352 v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int)
22353 v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int)
22354 v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int)
22355 v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int)
22356 v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int)
22357 v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int)
22358 v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int)
22359 v2df __builtin_ia32_vpermilpd (v2df,int)
22360 v4df __builtin_ia32_vpermilpd256 (v4df,int)
22361 v4sf __builtin_ia32_vpermilps (v4sf,int)
22362 v8sf __builtin_ia32_vpermilps256 (v8sf,int)
22363 v2df __builtin_ia32_vpermilvarpd (v2df,v2di)
22364 v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di)
22365 v4sf __builtin_ia32_vpermilvarps (v4sf,v4si)
22366 v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si)
22367 int __builtin_ia32_vtestcpd (v2df,v2df,ptest)
22368 int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest)
22369 int __builtin_ia32_vtestcps (v4sf,v4sf,ptest)
22370 int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest)
22371 int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest)
22372 int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest)
22373 int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest)
22374 int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest)
22375 int __builtin_ia32_vtestzpd (v2df,v2df,ptest)
22376 int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest)
22377 int __builtin_ia32_vtestzps (v4sf,v4sf,ptest)
22378 int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest)
22379 void __builtin_ia32_vzeroall (void)
22380 void __builtin_ia32_vzeroupper (void)
22381 v4df __builtin_ia32_xorpd256 (v4df,v4df)
22382 v8sf __builtin_ia32_xorps256 (v8sf,v8sf)
22385 The following built-in functions are available when @option{-mavx2} is
22386 used. All of them generate the machine instruction that is part of the
22390 v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int)
22391 v32qi __builtin_ia32_pabsb256 (v32qi)
22392 v16hi __builtin_ia32_pabsw256 (v16hi)
22393 v8si __builtin_ia32_pabsd256 (v8si)
22394 v16hi __builtin_ia32_packssdw256 (v8si,v8si)
22395 v32qi __builtin_ia32_packsswb256 (v16hi,v16hi)
22396 v16hi __builtin_ia32_packusdw256 (v8si,v8si)
22397 v32qi __builtin_ia32_packuswb256 (v16hi,v16hi)
22398 v32qi __builtin_ia32_paddb256 (v32qi,v32qi)
22399 v16hi __builtin_ia32_paddw256 (v16hi,v16hi)
22400 v8si __builtin_ia32_paddd256 (v8si,v8si)
22401 v4di __builtin_ia32_paddq256 (v4di,v4di)
22402 v32qi __builtin_ia32_paddsb256 (v32qi,v32qi)
22403 v16hi __builtin_ia32_paddsw256 (v16hi,v16hi)
22404 v32qi __builtin_ia32_paddusb256 (v32qi,v32qi)
22405 v16hi __builtin_ia32_paddusw256 (v16hi,v16hi)
22406 v4di __builtin_ia32_palignr256 (v4di,v4di,int)
22407 v4di __builtin_ia32_andsi256 (v4di,v4di)
22408 v4di __builtin_ia32_andnotsi256 (v4di,v4di)
22409 v32qi __builtin_ia32_pavgb256 (v32qi,v32qi)
22410 v16hi __builtin_ia32_pavgw256 (v16hi,v16hi)
22411 v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi)
22412 v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int)
22413 v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi)
22414 v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi)
22415 v8si __builtin_ia32_pcmpeqd256 (c8si,v8si)
22416 v4di __builtin_ia32_pcmpeqq256 (v4di,v4di)
22417 v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi)
22418 v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi)
22419 v8si __builtin_ia32_pcmpgtd256 (v8si,v8si)
22420 v4di __builtin_ia32_pcmpgtq256 (v4di,v4di)
22421 v16hi __builtin_ia32_phaddw256 (v16hi,v16hi)
22422 v8si __builtin_ia32_phaddd256 (v8si,v8si)
22423 v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi)
22424 v16hi __builtin_ia32_phsubw256 (v16hi,v16hi)
22425 v8si __builtin_ia32_phsubd256 (v8si,v8si)
22426 v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi)
22427 v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi)
22428 v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi)
22429 v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi)
22430 v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi)
22431 v8si __builtin_ia32_pmaxsd256 (v8si,v8si)
22432 v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi)
22433 v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi)
22434 v8si __builtin_ia32_pmaxud256 (v8si,v8si)
22435 v32qi __builtin_ia32_pminsb256 (v32qi,v32qi)
22436 v16hi __builtin_ia32_pminsw256 (v16hi,v16hi)
22437 v8si __builtin_ia32_pminsd256 (v8si,v8si)
22438 v32qi __builtin_ia32_pminub256 (v32qi,v32qi)
22439 v16hi __builtin_ia32_pminuw256 (v16hi,v16hi)
22440 v8si __builtin_ia32_pminud256 (v8si,v8si)
22441 int __builtin_ia32_pmovmskb256 (v32qi)
22442 v16hi __builtin_ia32_pmovsxbw256 (v16qi)
22443 v8si __builtin_ia32_pmovsxbd256 (v16qi)
22444 v4di __builtin_ia32_pmovsxbq256 (v16qi)
22445 v8si __builtin_ia32_pmovsxwd256 (v8hi)
22446 v4di __builtin_ia32_pmovsxwq256 (v8hi)
22447 v4di __builtin_ia32_pmovsxdq256 (v4si)
22448 v16hi __builtin_ia32_pmovzxbw256 (v16qi)
22449 v8si __builtin_ia32_pmovzxbd256 (v16qi)
22450 v4di __builtin_ia32_pmovzxbq256 (v16qi)
22451 v8si __builtin_ia32_pmovzxwd256 (v8hi)
22452 v4di __builtin_ia32_pmovzxwq256 (v8hi)
22453 v4di __builtin_ia32_pmovzxdq256 (v4si)
22454 v4di __builtin_ia32_pmuldq256 (v8si,v8si)
22455 v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi)
22456 v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi)
22457 v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi)
22458 v16hi __builtin_ia32_pmullw256 (v16hi,v16hi)
22459 v8si __builtin_ia32_pmulld256 (v8si,v8si)
22460 v4di __builtin_ia32_pmuludq256 (v8si,v8si)
22461 v4di __builtin_ia32_por256 (v4di,v4di)
22462 v16hi __builtin_ia32_psadbw256 (v32qi,v32qi)
22463 v32qi __builtin_ia32_pshufb256 (v32qi,v32qi)
22464 v8si __builtin_ia32_pshufd256 (v8si,int)
22465 v16hi __builtin_ia32_pshufhw256 (v16hi,int)
22466 v16hi __builtin_ia32_pshuflw256 (v16hi,int)
22467 v32qi __builtin_ia32_psignb256 (v32qi,v32qi)
22468 v16hi __builtin_ia32_psignw256 (v16hi,v16hi)
22469 v8si __builtin_ia32_psignd256 (v8si,v8si)
22470 v4di __builtin_ia32_pslldqi256 (v4di,int)
22471 v16hi __builtin_ia32_psllwi256 (16hi,int)
22472 v16hi __builtin_ia32_psllw256(v16hi,v8hi)
22473 v8si __builtin_ia32_pslldi256 (v8si,int)
22474 v8si __builtin_ia32_pslld256(v8si,v4si)
22475 v4di __builtin_ia32_psllqi256 (v4di,int)
22476 v4di __builtin_ia32_psllq256(v4di,v2di)
22477 v16hi __builtin_ia32_psrawi256 (v16hi,int)
22478 v16hi __builtin_ia32_psraw256 (v16hi,v8hi)
22479 v8si __builtin_ia32_psradi256 (v8si,int)
22480 v8si __builtin_ia32_psrad256 (v8si,v4si)
22481 v4di __builtin_ia32_psrldqi256 (v4di, int)
22482 v16hi __builtin_ia32_psrlwi256 (v16hi,int)
22483 v16hi __builtin_ia32_psrlw256 (v16hi,v8hi)
22484 v8si __builtin_ia32_psrldi256 (v8si,int)
22485 v8si __builtin_ia32_psrld256 (v8si,v4si)
22486 v4di __builtin_ia32_psrlqi256 (v4di,int)
22487 v4di __builtin_ia32_psrlq256(v4di,v2di)
22488 v32qi __builtin_ia32_psubb256 (v32qi,v32qi)
22489 v32hi __builtin_ia32_psubw256 (v16hi,v16hi)
22490 v8si __builtin_ia32_psubd256 (v8si,v8si)
22491 v4di __builtin_ia32_psubq256 (v4di,v4di)
22492 v32qi __builtin_ia32_psubsb256 (v32qi,v32qi)
22493 v16hi __builtin_ia32_psubsw256 (v16hi,v16hi)
22494 v32qi __builtin_ia32_psubusb256 (v32qi,v32qi)
22495 v16hi __builtin_ia32_psubusw256 (v16hi,v16hi)
22496 v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi)
22497 v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi)
22498 v8si __builtin_ia32_punpckhdq256 (v8si,v8si)
22499 v4di __builtin_ia32_punpckhqdq256 (v4di,v4di)
22500 v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi)
22501 v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi)
22502 v8si __builtin_ia32_punpckldq256 (v8si,v8si)
22503 v4di __builtin_ia32_punpcklqdq256 (v4di,v4di)
22504 v4di __builtin_ia32_pxor256 (v4di,v4di)
22505 v4di __builtin_ia32_movntdqa256 (pv4di)
22506 v4sf __builtin_ia32_vbroadcastss_ps (v4sf)
22507 v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf)
22508 v4df __builtin_ia32_vbroadcastsd_pd256 (v2df)
22509 v4di __builtin_ia32_vbroadcastsi256 (v2di)
22510 v4si __builtin_ia32_pblendd128 (v4si,v4si)
22511 v8si __builtin_ia32_pblendd256 (v8si,v8si)
22512 v32qi __builtin_ia32_pbroadcastb256 (v16qi)
22513 v16hi __builtin_ia32_pbroadcastw256 (v8hi)
22514 v8si __builtin_ia32_pbroadcastd256 (v4si)
22515 v4di __builtin_ia32_pbroadcastq256 (v2di)
22516 v16qi __builtin_ia32_pbroadcastb128 (v16qi)
22517 v8hi __builtin_ia32_pbroadcastw128 (v8hi)
22518 v4si __builtin_ia32_pbroadcastd128 (v4si)
22519 v2di __builtin_ia32_pbroadcastq128 (v2di)
22520 v8si __builtin_ia32_permvarsi256 (v8si,v8si)
22521 v4df __builtin_ia32_permdf256 (v4df,int)
22522 v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf)
22523 v4di __builtin_ia32_permdi256 (v4di,int)
22524 v4di __builtin_ia32_permti256 (v4di,v4di,int)
22525 v4di __builtin_ia32_extract128i256 (v4di,int)
22526 v4di __builtin_ia32_insert128i256 (v4di,v2di,int)
22527 v8si __builtin_ia32_maskloadd256 (pcv8si,v8si)
22528 v4di __builtin_ia32_maskloadq256 (pcv4di,v4di)
22529 v4si __builtin_ia32_maskloadd (pcv4si,v4si)
22530 v2di __builtin_ia32_maskloadq (pcv2di,v2di)
22531 void __builtin_ia32_maskstored256 (pv8si,v8si,v8si)
22532 void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di)
22533 void __builtin_ia32_maskstored (pv4si,v4si,v4si)
22534 void __builtin_ia32_maskstoreq (pv2di,v2di,v2di)
22535 v8si __builtin_ia32_psllv8si (v8si,v8si)
22536 v4si __builtin_ia32_psllv4si (v4si,v4si)
22537 v4di __builtin_ia32_psllv4di (v4di,v4di)
22538 v2di __builtin_ia32_psllv2di (v2di,v2di)
22539 v8si __builtin_ia32_psrav8si (v8si,v8si)
22540 v4si __builtin_ia32_psrav4si (v4si,v4si)
22541 v8si __builtin_ia32_psrlv8si (v8si,v8si)
22542 v4si __builtin_ia32_psrlv4si (v4si,v4si)
22543 v4di __builtin_ia32_psrlv4di (v4di,v4di)
22544 v2di __builtin_ia32_psrlv2di (v2di,v2di)
22545 v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int)
22546 v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int)
22547 v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int)
22548 v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int)
22549 v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int)
22550 v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int)
22551 v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int)
22552 v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int)
22553 v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int)
22554 v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int)
22555 v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int)
22556 v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int)
22557 v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int)
22558 v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int)
22559 v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int)
22560 v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int)
22563 The following built-in functions are available when @option{-maes} is
22564 used. All of them generate the machine instruction that is part of the
22568 v2di __builtin_ia32_aesenc128 (v2di, v2di)
22569 v2di __builtin_ia32_aesenclast128 (v2di, v2di)
22570 v2di __builtin_ia32_aesdec128 (v2di, v2di)
22571 v2di __builtin_ia32_aesdeclast128 (v2di, v2di)
22572 v2di __builtin_ia32_aeskeygenassist128 (v2di, const int)
22573 v2di __builtin_ia32_aesimc128 (v2di)
22576 The following built-in function is available when @option{-mpclmul} is
22580 @item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)
22581 Generates the @code{pclmulqdq} machine instruction.
22584 The following built-in function is available when @option{-mfsgsbase} is
22585 used. All of them generate the machine instruction that is part of the
22589 unsigned int __builtin_ia32_rdfsbase32 (void)
22590 unsigned long long __builtin_ia32_rdfsbase64 (void)
22591 unsigned int __builtin_ia32_rdgsbase32 (void)
22592 unsigned long long __builtin_ia32_rdgsbase64 (void)
22593 void _writefsbase_u32 (unsigned int)
22594 void _writefsbase_u64 (unsigned long long)
22595 void _writegsbase_u32 (unsigned int)
22596 void _writegsbase_u64 (unsigned long long)
22599 The following built-in function is available when @option{-mrdrnd} is
22600 used. All of them generate the machine instruction that is part of the
22604 unsigned int __builtin_ia32_rdrand16_step (unsigned short *)
22605 unsigned int __builtin_ia32_rdrand32_step (unsigned int *)
22606 unsigned int __builtin_ia32_rdrand64_step (unsigned long long *)
22609 The following built-in function is available when @option{-mptwrite} is
22610 used. All of them generate the machine instruction that is part of the
22614 void __builtin_ia32_ptwrite32 (unsigned)
22615 void __builtin_ia32_ptwrite64 (unsigned long long)
22618 The following built-in functions are available when @option{-msse4a} is used.
22619 All of them generate the machine instruction that is part of the name.
22622 void __builtin_ia32_movntsd (double *, v2df)
22623 void __builtin_ia32_movntss (float *, v4sf)
22624 v2di __builtin_ia32_extrq (v2di, v16qi)
22625 v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int)
22626 v2di __builtin_ia32_insertq (v2di, v2di)
22627 v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int)
22630 The following built-in functions are available when @option{-mxop} is used.
22632 v2df __builtin_ia32_vfrczpd (v2df)
22633 v4sf __builtin_ia32_vfrczps (v4sf)
22634 v2df __builtin_ia32_vfrczsd (v2df)
22635 v4sf __builtin_ia32_vfrczss (v4sf)
22636 v4df __builtin_ia32_vfrczpd256 (v4df)
22637 v8sf __builtin_ia32_vfrczps256 (v8sf)
22638 v2di __builtin_ia32_vpcmov (v2di, v2di, v2di)
22639 v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di)
22640 v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si)
22641 v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi)
22642 v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi)
22643 v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df)
22644 v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf)
22645 v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di)
22646 v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si)
22647 v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi)
22648 v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi)
22649 v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df)
22650 v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf)
22651 v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi)
22652 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
22653 v4si __builtin_ia32_vpcomeqd (v4si, v4si)
22654 v2di __builtin_ia32_vpcomeqq (v2di, v2di)
22655 v16qi __builtin_ia32_vpcomequb (v16qi, v16qi)
22656 v4si __builtin_ia32_vpcomequd (v4si, v4si)
22657 v2di __builtin_ia32_vpcomequq (v2di, v2di)
22658 v8hi __builtin_ia32_vpcomequw (v8hi, v8hi)
22659 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
22660 v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi)
22661 v4si __builtin_ia32_vpcomfalsed (v4si, v4si)
22662 v2di __builtin_ia32_vpcomfalseq (v2di, v2di)
22663 v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi)
22664 v4si __builtin_ia32_vpcomfalseud (v4si, v4si)
22665 v2di __builtin_ia32_vpcomfalseuq (v2di, v2di)
22666 v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi)
22667 v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi)
22668 v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi)
22669 v4si __builtin_ia32_vpcomged (v4si, v4si)
22670 v2di __builtin_ia32_vpcomgeq (v2di, v2di)
22671 v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi)
22672 v4si __builtin_ia32_vpcomgeud (v4si, v4si)
22673 v2di __builtin_ia32_vpcomgeuq (v2di, v2di)
22674 v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi)
22675 v8hi __builtin_ia32_vpcomgew (v8hi, v8hi)
22676 v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi)
22677 v4si __builtin_ia32_vpcomgtd (v4si, v4si)
22678 v2di __builtin_ia32_vpcomgtq (v2di, v2di)
22679 v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi)
22680 v4si __builtin_ia32_vpcomgtud (v4si, v4si)
22681 v2di __builtin_ia32_vpcomgtuq (v2di, v2di)
22682 v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi)
22683 v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi)
22684 v16qi __builtin_ia32_vpcomleb (v16qi, v16qi)
22685 v4si __builtin_ia32_vpcomled (v4si, v4si)
22686 v2di __builtin_ia32_vpcomleq (v2di, v2di)
22687 v16qi __builtin_ia32_vpcomleub (v16qi, v16qi)
22688 v4si __builtin_ia32_vpcomleud (v4si, v4si)
22689 v2di __builtin_ia32_vpcomleuq (v2di, v2di)
22690 v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi)
22691 v8hi __builtin_ia32_vpcomlew (v8hi, v8hi)
22692 v16qi __builtin_ia32_vpcomltb (v16qi, v16qi)
22693 v4si __builtin_ia32_vpcomltd (v4si, v4si)
22694 v2di __builtin_ia32_vpcomltq (v2di, v2di)
22695 v16qi __builtin_ia32_vpcomltub (v16qi, v16qi)
22696 v4si __builtin_ia32_vpcomltud (v4si, v4si)
22697 v2di __builtin_ia32_vpcomltuq (v2di, v2di)
22698 v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi)
22699 v8hi __builtin_ia32_vpcomltw (v8hi, v8hi)
22700 v16qi __builtin_ia32_vpcomneb (v16qi, v16qi)
22701 v4si __builtin_ia32_vpcomned (v4si, v4si)
22702 v2di __builtin_ia32_vpcomneq (v2di, v2di)
22703 v16qi __builtin_ia32_vpcomneub (v16qi, v16qi)
22704 v4si __builtin_ia32_vpcomneud (v4si, v4si)
22705 v2di __builtin_ia32_vpcomneuq (v2di, v2di)
22706 v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi)
22707 v8hi __builtin_ia32_vpcomnew (v8hi, v8hi)
22708 v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi)
22709 v4si __builtin_ia32_vpcomtrued (v4si, v4si)
22710 v2di __builtin_ia32_vpcomtrueq (v2di, v2di)
22711 v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi)
22712 v4si __builtin_ia32_vpcomtrueud (v4si, v4si)
22713 v2di __builtin_ia32_vpcomtrueuq (v2di, v2di)
22714 v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi)
22715 v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi)
22716 v4si __builtin_ia32_vphaddbd (v16qi)
22717 v2di __builtin_ia32_vphaddbq (v16qi)
22718 v8hi __builtin_ia32_vphaddbw (v16qi)
22719 v2di __builtin_ia32_vphadddq (v4si)
22720 v4si __builtin_ia32_vphaddubd (v16qi)
22721 v2di __builtin_ia32_vphaddubq (v16qi)
22722 v8hi __builtin_ia32_vphaddubw (v16qi)
22723 v2di __builtin_ia32_vphaddudq (v4si)
22724 v4si __builtin_ia32_vphadduwd (v8hi)
22725 v2di __builtin_ia32_vphadduwq (v8hi)
22726 v4si __builtin_ia32_vphaddwd (v8hi)
22727 v2di __builtin_ia32_vphaddwq (v8hi)
22728 v8hi __builtin_ia32_vphsubbw (v16qi)
22729 v2di __builtin_ia32_vphsubdq (v4si)
22730 v4si __builtin_ia32_vphsubwd (v8hi)
22731 v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si)
22732 v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di)
22733 v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di)
22734 v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si)
22735 v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di)
22736 v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di)
22737 v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si)
22738 v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi)
22739 v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si)
22740 v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi)
22741 v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si)
22742 v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si)
22743 v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi)
22744 v16qi __builtin_ia32_vprotb (v16qi, v16qi)
22745 v4si __builtin_ia32_vprotd (v4si, v4si)
22746 v2di __builtin_ia32_vprotq (v2di, v2di)
22747 v8hi __builtin_ia32_vprotw (v8hi, v8hi)
22748 v16qi __builtin_ia32_vpshab (v16qi, v16qi)
22749 v4si __builtin_ia32_vpshad (v4si, v4si)
22750 v2di __builtin_ia32_vpshaq (v2di, v2di)
22751 v8hi __builtin_ia32_vpshaw (v8hi, v8hi)
22752 v16qi __builtin_ia32_vpshlb (v16qi, v16qi)
22753 v4si __builtin_ia32_vpshld (v4si, v4si)
22754 v2di __builtin_ia32_vpshlq (v2di, v2di)
22755 v8hi __builtin_ia32_vpshlw (v8hi, v8hi)
22758 The following built-in functions are available when @option{-mfma4} is used.
22759 All of them generate the machine instruction that is part of the name.
22762 v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df)
22763 v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf)
22764 v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df)
22765 v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf)
22766 v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df)
22767 v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf)
22768 v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df)
22769 v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf)
22770 v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df)
22771 v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf)
22772 v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df)
22773 v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf)
22774 v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df)
22775 v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf)
22776 v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df)
22777 v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf)
22778 v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df)
22779 v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf)
22780 v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df)
22781 v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf)
22782 v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df)
22783 v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf)
22784 v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df)
22785 v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf)
22786 v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df)
22787 v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf)
22788 v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df)
22789 v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf)
22790 v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df)
22791 v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf)
22792 v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df)
22793 v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf)
22797 The following built-in functions are available when @option{-mlwp} is used.
22800 void __builtin_ia32_llwpcb16 (void *);
22801 void __builtin_ia32_llwpcb32 (void *);
22802 void __builtin_ia32_llwpcb64 (void *);
22803 void * __builtin_ia32_llwpcb16 (void);
22804 void * __builtin_ia32_llwpcb32 (void);
22805 void * __builtin_ia32_llwpcb64 (void);
22806 void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short)
22807 void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int)
22808 void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int)
22809 unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short)
22810 unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int)
22811 unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int)
22814 The following built-in functions are available when @option{-mbmi} is used.
22815 All of them generate the machine instruction that is part of the name.
22817 unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int);
22818 unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long);
22821 The following built-in functions are available when @option{-mbmi2} is used.
22822 All of them generate the machine instruction that is part of the name.
22824 unsigned int _bzhi_u32 (unsigned int, unsigned int)
22825 unsigned int _pdep_u32 (unsigned int, unsigned int)
22826 unsigned int _pext_u32 (unsigned int, unsigned int)
22827 unsigned long long _bzhi_u64 (unsigned long long, unsigned long long)
22828 unsigned long long _pdep_u64 (unsigned long long, unsigned long long)
22829 unsigned long long _pext_u64 (unsigned long long, unsigned long long)
22832 The following built-in functions are available when @option{-mlzcnt} is used.
22833 All of them generate the machine instruction that is part of the name.
22835 unsigned short __builtin_ia32_lzcnt_u16(unsigned short);
22836 unsigned int __builtin_ia32_lzcnt_u32(unsigned int);
22837 unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long);
22840 The following built-in functions are available when @option{-mfxsr} is used.
22841 All of them generate the machine instruction that is part of the name.
22843 void __builtin_ia32_fxsave (void *)
22844 void __builtin_ia32_fxrstor (void *)
22845 void __builtin_ia32_fxsave64 (void *)
22846 void __builtin_ia32_fxrstor64 (void *)
22849 The following built-in functions are available when @option{-mxsave} is used.
22850 All of them generate the machine instruction that is part of the name.
22852 void __builtin_ia32_xsave (void *, long long)
22853 void __builtin_ia32_xrstor (void *, long long)
22854 void __builtin_ia32_xsave64 (void *, long long)
22855 void __builtin_ia32_xrstor64 (void *, long long)
22858 The following built-in functions are available when @option{-mxsaveopt} is used.
22859 All of them generate the machine instruction that is part of the name.
22861 void __builtin_ia32_xsaveopt (void *, long long)
22862 void __builtin_ia32_xsaveopt64 (void *, long long)
22865 The following built-in functions are available when @option{-mtbm} is used.
22866 Both of them generate the immediate form of the bextr machine instruction.
22868 unsigned int __builtin_ia32_bextri_u32 (unsigned int,
22869 const unsigned int);
22870 unsigned long long __builtin_ia32_bextri_u64 (unsigned long long,
22871 const unsigned long long);
22875 The following built-in functions are available when @option{-m3dnow} is used.
22876 All of them generate the machine instruction that is part of the name.
22879 void __builtin_ia32_femms (void)
22880 v8qi __builtin_ia32_pavgusb (v8qi, v8qi)
22881 v2si __builtin_ia32_pf2id (v2sf)
22882 v2sf __builtin_ia32_pfacc (v2sf, v2sf)
22883 v2sf __builtin_ia32_pfadd (v2sf, v2sf)
22884 v2si __builtin_ia32_pfcmpeq (v2sf, v2sf)
22885 v2si __builtin_ia32_pfcmpge (v2sf, v2sf)
22886 v2si __builtin_ia32_pfcmpgt (v2sf, v2sf)
22887 v2sf __builtin_ia32_pfmax (v2sf, v2sf)
22888 v2sf __builtin_ia32_pfmin (v2sf, v2sf)
22889 v2sf __builtin_ia32_pfmul (v2sf, v2sf)
22890 v2sf __builtin_ia32_pfrcp (v2sf)
22891 v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf)
22892 v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf)
22893 v2sf __builtin_ia32_pfrsqrt (v2sf)
22894 v2sf __builtin_ia32_pfsub (v2sf, v2sf)
22895 v2sf __builtin_ia32_pfsubr (v2sf, v2sf)
22896 v2sf __builtin_ia32_pi2fd (v2si)
22897 v4hi __builtin_ia32_pmulhrw (v4hi, v4hi)
22900 The following built-in functions are available when @option{-m3dnowa} is used.
22901 All of them generate the machine instruction that is part of the name.
22904 v2si __builtin_ia32_pf2iw (v2sf)
22905 v2sf __builtin_ia32_pfnacc (v2sf, v2sf)
22906 v2sf __builtin_ia32_pfpnacc (v2sf, v2sf)
22907 v2sf __builtin_ia32_pi2fw (v2si)
22908 v2sf __builtin_ia32_pswapdsf (v2sf)
22909 v2si __builtin_ia32_pswapdsi (v2si)
22912 The following built-in functions are available when @option{-mrtm} is used
22913 They are used for restricted transactional memory. These are the internal
22914 low level functions. Normally the functions in
22915 @ref{x86 transactional memory intrinsics} should be used instead.
22918 int __builtin_ia32_xbegin ()
22919 void __builtin_ia32_xend ()
22920 void __builtin_ia32_xabort (status)
22921 int __builtin_ia32_xtest ()
22924 The following built-in functions are available when @option{-mmwaitx} is used.
22925 All of them generate the machine instruction that is part of the name.
22927 void __builtin_ia32_monitorx (void *, unsigned int, unsigned int)
22928 void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int)
22931 The following built-in functions are available when @option{-mclzero} is used.
22932 All of them generate the machine instruction that is part of the name.
22934 void __builtin_i32_clzero (void *)
22937 The following built-in functions are available when @option{-mpku} is used.
22938 They generate reads and writes to PKRU.
22940 void __builtin_ia32_wrpkru (unsigned int)
22941 unsigned int __builtin_ia32_rdpkru ()
22944 The following built-in functions are available when @option{-mcet} or
22945 @option{-mshstk} option is used. They support shadow stack
22946 machine instructions from Intel Control-flow Enforcement Technology (CET).
22947 Each built-in function generates the machine instruction that is part
22948 of the function's name. These are the internal low-level functions.
22949 Normally the functions in @ref{x86 control-flow protection intrinsics}
22950 should be used instead.
22953 unsigned int __builtin_ia32_rdsspd (void)
22954 unsigned long long __builtin_ia32_rdsspq (void)
22955 void __builtin_ia32_incsspd (unsigned int)
22956 void __builtin_ia32_incsspq (unsigned long long)
22957 void __builtin_ia32_saveprevssp(void);
22958 void __builtin_ia32_rstorssp(void *);
22959 void __builtin_ia32_wrssd(unsigned int, void *);
22960 void __builtin_ia32_wrssq(unsigned long long, void *);
22961 void __builtin_ia32_wrussd(unsigned int, void *);
22962 void __builtin_ia32_wrussq(unsigned long long, void *);
22963 void __builtin_ia32_setssbsy(void);
22964 void __builtin_ia32_clrssbsy(void *);
22967 @node x86 transactional memory intrinsics
22968 @subsection x86 Transactional Memory Intrinsics
22970 These hardware transactional memory intrinsics for x86 allow you to use
22971 memory transactions with RTM (Restricted Transactional Memory).
22972 This support is enabled with the @option{-mrtm} option.
22973 For using HLE (Hardware Lock Elision) see
22974 @ref{x86 specific memory model extensions for transactional memory} instead.
22976 A memory transaction commits all changes to memory in an atomic way,
22977 as visible to other threads. If the transaction fails it is rolled back
22978 and all side effects discarded.
22980 Generally there is no guarantee that a memory transaction ever succeeds
22981 and suitable fallback code always needs to be supplied.
22983 @deftypefn {RTM Function} {unsigned} _xbegin ()
22984 Start a RTM (Restricted Transactional Memory) transaction.
22985 Returns @code{_XBEGIN_STARTED} when the transaction
22986 started successfully (note this is not 0, so the constant has to be
22987 explicitly tested).
22989 If the transaction aborts, all side effects
22990 are undone and an abort code encoded as a bit mask is returned.
22991 The following macros are defined:
22994 @item _XABORT_EXPLICIT
22995 Transaction was explicitly aborted with @code{_xabort}. The parameter passed
22996 to @code{_xabort} is available with @code{_XABORT_CODE(status)}.
22997 @item _XABORT_RETRY
22998 Transaction retry is possible.
22999 @item _XABORT_CONFLICT
23000 Transaction abort due to a memory conflict with another thread.
23001 @item _XABORT_CAPACITY
23002 Transaction abort due to the transaction using too much memory.
23003 @item _XABORT_DEBUG
23004 Transaction abort due to a debug trap.
23005 @item _XABORT_NESTED
23006 Transaction abort in an inner nested transaction.
23009 There is no guarantee
23010 any transaction ever succeeds, so there always needs to be a valid
23014 @deftypefn {RTM Function} {void} _xend ()
23015 Commit the current transaction. When no transaction is active this faults.
23016 All memory side effects of the transaction become visible
23017 to other threads in an atomic manner.
23020 @deftypefn {RTM Function} {int} _xtest ()
23021 Return a nonzero value if a transaction is currently active, otherwise 0.
23024 @deftypefn {RTM Function} {void} _xabort (status)
23025 Abort the current transaction. When no transaction is active this is a no-op.
23026 The @var{status} is an 8-bit constant; its value is encoded in the return
23027 value from @code{_xbegin}.
23030 Here is an example showing handling for @code{_XABORT_RETRY}
23031 and a fallback path for other failures:
23034 #include <immintrin.h>
23036 int n_tries, max_tries;
23037 unsigned status = _XABORT_EXPLICIT;
23040 for (n_tries = 0; n_tries < max_tries; n_tries++)
23042 status = _xbegin ();
23043 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY))
23046 if (status == _XBEGIN_STARTED)
23048 ... transaction code...
23053 ... non-transactional fallback path...
23058 Note that, in most cases, the transactional and non-transactional code
23059 must synchronize together to ensure consistency.
23061 @node x86 control-flow protection intrinsics
23062 @subsection x86 Control-Flow Protection Intrinsics
23064 @deftypefn {CET Function} {ret_type} _get_ssp (void)
23065 Get the current value of shadow stack pointer if shadow stack support
23066 from Intel CET is enabled in the hardware or @code{0} otherwise.
23067 The @code{ret_type} is @code{unsigned long long} for 64-bit targets
23068 and @code{unsigned int} for 32-bit targets.
23071 @deftypefn {CET Function} void _inc_ssp (unsigned int)
23072 Increment the current shadow stack pointer by the size specified by the
23073 function argument. The argument is masked to a byte value for security
23074 reasons, so to increment by more than 255 bytes you must call the function
23078 The shadow stack unwind code looks like:
23081 #include <immintrin.h>
23083 /* Unwind the shadow stack for EH. */
23084 #define _Unwind_Frames_Extra(x) \
23087 _Unwind_Word ssp = _get_ssp (); \
23090 _Unwind_Word tmp = (x); \
23091 while (tmp > 255) \
23103 This code runs unconditionally on all 64-bit processors. For 32-bit
23104 processors the code runs on those that support multi-byte NOP instructions.
23106 @node Target Format Checks
23107 @section Format Checks Specific to Particular Target Machines
23109 For some target machines, GCC supports additional options to the
23111 (@pxref{Function Attributes,,Declaring Attributes of Functions}).
23114 * Solaris Format Checks::
23115 * Darwin Format Checks::
23118 @node Solaris Format Checks
23119 @subsection Solaris Format Checks
23121 Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format
23122 check. @code{cmn_err} accepts a subset of the standard @code{printf}
23123 conversions, and the two-argument @code{%b} conversion for displaying
23124 bit-fields. See the Solaris man page for @code{cmn_err} for more information.
23126 @node Darwin Format Checks
23127 @subsection Darwin Format Checks
23129 In addition to the full set of format archetypes (attribute format style
23130 arguments such as @code{printf}, @code{scanf}, @code{strftime}, and
23131 @code{strfmon}), Darwin targets also support the @code{CFString} (or
23132 @code{__CFString__}) archetype in the @code{format} attribute.
23133 Declarations with this archetype are parsed for correct syntax
23134 and argument types. However, parsing of the format string itself and
23135 validating arguments against it in calls to such functions is currently
23138 Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may
23139 also be used as format arguments. Note that the relevant headers are only likely to be
23140 available on Darwin (OSX) installations. On such installations, the XCode and system
23141 documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and
23142 associated functions.
23145 @section Pragmas Accepted by GCC
23147 @cindex @code{#pragma}
23149 GCC supports several types of pragmas, primarily in order to compile
23150 code originally written for other compilers. Note that in general
23151 we do not recommend the use of pragmas; @xref{Function Attributes},
23152 for further explanation.
23154 The GNU C preprocessor recognizes several pragmas in addition to the
23155 compiler pragmas documented here. Refer to the CPP manual for more
23159 * AArch64 Pragmas::
23164 * RS/6000 and PowerPC Pragmas::
23167 * Solaris Pragmas::
23168 * Symbol-Renaming Pragmas::
23169 * Structure-Layout Pragmas::
23171 * Diagnostic Pragmas::
23172 * Visibility Pragmas::
23173 * Push/Pop Macro Pragmas::
23174 * Function Specific Option Pragmas::
23175 * Loop-Specific Pragmas::
23178 @node AArch64 Pragmas
23179 @subsection AArch64 Pragmas
23181 The pragmas defined by the AArch64 target correspond to the AArch64
23182 target function attributes. They can be specified as below:
23184 #pragma GCC target("string")
23187 where @code{@var{string}} can be any string accepted as an AArch64 target
23188 attribute. @xref{AArch64 Function Attributes}, for more details
23189 on the permissible values of @code{string}.
23192 @subsection ARM Pragmas
23194 The ARM target defines pragmas for controlling the default addition of
23195 @code{long_call} and @code{short_call} attributes to functions.
23196 @xref{Function Attributes}, for information about the effects of these
23201 @cindex pragma, long_calls
23202 Set all subsequent functions to have the @code{long_call} attribute.
23204 @item no_long_calls
23205 @cindex pragma, no_long_calls
23206 Set all subsequent functions to have the @code{short_call} attribute.
23208 @item long_calls_off
23209 @cindex pragma, long_calls_off
23210 Do not affect the @code{long_call} or @code{short_call} attributes of
23211 subsequent functions.
23215 @subsection M32C Pragmas
23218 @item GCC memregs @var{number}
23219 @cindex pragma, memregs
23220 Overrides the command-line option @code{-memregs=} for the current
23221 file. Use with care! This pragma must be before any function in the
23222 file, and mixing different memregs values in different objects may
23223 make them incompatible. This pragma is useful when a
23224 performance-critical function uses a memreg for temporary values,
23225 as it may allow you to reduce the number of memregs used.
23227 @item ADDRESS @var{name} @var{address}
23228 @cindex pragma, address
23229 For any declared symbols matching @var{name}, this does three things
23230 to that symbol: it forces the symbol to be located at the given
23231 address (a number), it forces the symbol to be volatile, and it
23232 changes the symbol's scope to be static. This pragma exists for
23233 compatibility with other compilers, but note that the common
23234 @code{1234H} numeric syntax is not supported (use @code{0x1234}
23238 #pragma ADDRESS port3 0x103
23245 @subsection MeP Pragmas
23249 @item custom io_volatile (on|off)
23250 @cindex pragma, custom io_volatile
23251 Overrides the command-line option @code{-mio-volatile} for the current
23252 file. Note that for compatibility with future GCC releases, this
23253 option should only be used once before any @code{io} variables in each
23256 @item GCC coprocessor available @var{registers}
23257 @cindex pragma, coprocessor available
23258 Specifies which coprocessor registers are available to the register
23259 allocator. @var{registers} may be a single register, register range
23260 separated by ellipses, or comma-separated list of those. Example:
23263 #pragma GCC coprocessor available $c0...$c10, $c28
23266 @item GCC coprocessor call_saved @var{registers}
23267 @cindex pragma, coprocessor call_saved
23268 Specifies which coprocessor registers are to be saved and restored by
23269 any function using them. @var{registers} may be a single register,
23270 register range separated by ellipses, or comma-separated list of
23274 #pragma GCC coprocessor call_saved $c4...$c6, $c31
23277 @item GCC coprocessor subclass '(A|B|C|D)' = @var{registers}
23278 @cindex pragma, coprocessor subclass
23279 Creates and defines a register class. These register classes can be
23280 used by inline @code{asm} constructs. @var{registers} may be a single
23281 register, register range separated by ellipses, or comma-separated
23282 list of those. Example:
23285 #pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6
23287 asm ("cpfoo %0" : "=B" (x));
23290 @item GCC disinterrupt @var{name} , @var{name} @dots{}
23291 @cindex pragma, disinterrupt
23292 For the named functions, the compiler adds code to disable interrupts
23293 for the duration of those functions. If any functions so named
23294 are not encountered in the source, a warning is emitted that the pragma is
23295 not used. Examples:
23298 #pragma disinterrupt foo
23299 #pragma disinterrupt bar, grill
23300 int foo () @{ @dots{} @}
23303 @item GCC call @var{name} , @var{name} @dots{}
23304 @cindex pragma, call
23305 For the named functions, the compiler always uses a register-indirect
23306 call model when calling the named functions. Examples:
23316 @subsection PRU Pragmas
23320 @item ctable_entry @var{index} @var{constant_address}
23321 @cindex pragma, ctable_entry
23322 Specifies that the PRU CTABLE entry given by @var{index} has the value
23323 @var{constant_address}. This enables GCC to emit LBCO/SBCO instructions
23324 when the load/store address is known and can be addressed with some CTABLE
23325 entry. For example:
23328 /* will compile to "sbco Rx, 2, 0x10, 4" */
23329 #pragma ctable_entry 2 0x4802a000
23330 *(unsigned int *)0x4802a010 = val;
23335 @node RS/6000 and PowerPC Pragmas
23336 @subsection RS/6000 and PowerPC Pragmas
23338 The RS/6000 and PowerPC targets define one pragma for controlling
23339 whether or not the @code{longcall} attribute is added to function
23340 declarations by default. This pragma overrides the @option{-mlongcall}
23341 option, but not the @code{longcall} and @code{shortcall} attributes.
23342 @xref{RS/6000 and PowerPC Options}, for more information about when long
23343 calls are and are not necessary.
23347 @cindex pragma, longcall
23348 Apply the @code{longcall} attribute to all subsequent function
23352 Do not apply the @code{longcall} attribute to subsequent function
23356 @c Describe h8300 pragmas here.
23357 @c Describe sh pragmas here.
23358 @c Describe v850 pragmas here.
23360 @node S/390 Pragmas
23361 @subsection S/390 Pragmas
23363 The pragmas defined by the S/390 target correspond to the S/390
23364 target function attributes and some the additional options:
23371 Note that options of the pragma, unlike options of the target
23372 attribute, do change the value of preprocessor macros like
23373 @code{__VEC__}. They can be specified as below:
23376 #pragma GCC target("string[,string]...")
23377 #pragma GCC target("string"[,"string"]...)
23380 @node Darwin Pragmas
23381 @subsection Darwin Pragmas
23383 The following pragmas are available for all architectures running the
23384 Darwin operating system. These are useful for compatibility with other
23388 @item mark @var{tokens}@dots{}
23389 @cindex pragma, mark
23390 This pragma is accepted, but has no effect.
23392 @item options align=@var{alignment}
23393 @cindex pragma, options align
23394 This pragma sets the alignment of fields in structures. The values of
23395 @var{alignment} may be @code{mac68k}, to emulate m68k alignment, or
23396 @code{power}, to emulate PowerPC alignment. Uses of this pragma nest
23397 properly; to restore the previous setting, use @code{reset} for the
23400 @item segment @var{tokens}@dots{}
23401 @cindex pragma, segment
23402 This pragma is accepted, but has no effect.
23404 @item unused (@var{var} [, @var{var}]@dots{})
23405 @cindex pragma, unused
23406 This pragma declares variables to be possibly unused. GCC does not
23407 produce warnings for the listed variables. The effect is similar to
23408 that of the @code{unused} attribute, except that this pragma may appear
23409 anywhere within the variables' scopes.
23412 @node Solaris Pragmas
23413 @subsection Solaris Pragmas
23415 The Solaris target supports @code{#pragma redefine_extname}
23416 (@pxref{Symbol-Renaming Pragmas}). It also supports additional
23417 @code{#pragma} directives for compatibility with the system compiler.
23420 @item align @var{alignment} (@var{variable} [, @var{variable}]...)
23421 @cindex pragma, align
23423 Increase the minimum alignment of each @var{variable} to @var{alignment}.
23424 This is the same as GCC's @code{aligned} attribute @pxref{Variable
23425 Attributes}). Macro expansion occurs on the arguments to this pragma
23426 when compiling C and Objective-C@. It does not currently occur when
23427 compiling C++, but this is a bug which may be fixed in a future
23430 @item fini (@var{function} [, @var{function}]...)
23431 @cindex pragma, fini
23433 This pragma causes each listed @var{function} to be called after
23434 main, or during shared module unloading, by adding a call to the
23435 @code{.fini} section.
23437 @item init (@var{function} [, @var{function}]...)
23438 @cindex pragma, init
23440 This pragma causes each listed @var{function} to be called during
23441 initialization (before @code{main}) or during shared module loading, by
23442 adding a call to the @code{.init} section.
23446 @node Symbol-Renaming Pragmas
23447 @subsection Symbol-Renaming Pragmas
23449 GCC supports a @code{#pragma} directive that changes the name used in
23450 assembly for a given declaration. While this pragma is supported on all
23451 platforms, it is intended primarily to provide compatibility with the
23452 Solaris system headers. This effect can also be achieved using the asm
23453 labels extension (@pxref{Asm Labels}).
23456 @item redefine_extname @var{oldname} @var{newname}
23457 @cindex pragma, redefine_extname
23459 This pragma gives the C function @var{oldname} the assembly symbol
23460 @var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME}
23461 is defined if this pragma is available (currently on all platforms).
23464 This pragma and the @code{asm} labels extension interact in a complicated
23465 manner. Here are some corner cases you may want to be aware of:
23468 @item This pragma silently applies only to declarations with external
23469 linkage. The @code{asm} label feature does not have this restriction.
23471 @item In C++, this pragma silently applies only to declarations with
23472 ``C'' linkage. Again, @code{asm} labels do not have this restriction.
23474 @item If either of the ways of changing the assembly name of a
23475 declaration are applied to a declaration whose assembly name has
23476 already been determined (either by a previous use of one of these
23477 features, or because the compiler needed the assembly name in order to
23478 generate code), and the new name is different, a warning issues and
23479 the name does not change.
23481 @item The @var{oldname} used by @code{#pragma redefine_extname} is
23482 always the C-language name.
23485 @node Structure-Layout Pragmas
23486 @subsection Structure-Layout Pragmas
23488 For compatibility with Microsoft Windows compilers, GCC supports a
23489 set of @code{#pragma} directives that change the maximum alignment of
23490 members of structures (other than zero-width bit-fields), unions, and
23491 classes subsequently defined. The @var{n} value below always is required
23492 to be a small power of two and specifies the new alignment in bytes.
23495 @item @code{#pragma pack(@var{n})} simply sets the new alignment.
23496 @item @code{#pragma pack()} sets the alignment to the one that was in
23497 effect when compilation started (see also command-line option
23498 @option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}).
23499 @item @code{#pragma pack(push[,@var{n}])} pushes the current alignment
23500 setting on an internal stack and then optionally sets the new alignment.
23501 @item @code{#pragma pack(pop)} restores the alignment setting to the one
23502 saved at the top of the internal stack (and removes that stack entry).
23503 Note that @code{#pragma pack([@var{n}])} does not influence this internal
23504 stack; thus it is possible to have @code{#pragma pack(push)} followed by
23505 multiple @code{#pragma pack(@var{n})} instances and finalized by a single
23506 @code{#pragma pack(pop)}.
23509 Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct}
23510 directive which lays out structures and unions subsequently defined as the
23511 documented @code{__attribute__ ((ms_struct))}.
23514 @item @code{#pragma ms_struct on} turns on the Microsoft layout.
23515 @item @code{#pragma ms_struct off} turns off the Microsoft layout.
23516 @item @code{#pragma ms_struct reset} goes back to the default layout.
23519 Most targets also support the @code{#pragma scalar_storage_order} directive
23520 which lays out structures and unions subsequently defined as the documented
23521 @code{__attribute__ ((scalar_storage_order))}.
23524 @item @code{#pragma scalar_storage_order big-endian} sets the storage order
23525 of the scalar fields to big-endian.
23526 @item @code{#pragma scalar_storage_order little-endian} sets the storage order
23527 of the scalar fields to little-endian.
23528 @item @code{#pragma scalar_storage_order default} goes back to the endianness
23529 that was in effect when compilation started (see also command-line option
23530 @option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}).
23534 @subsection Weak Pragmas
23536 For compatibility with SVR4, GCC supports a set of @code{#pragma}
23537 directives for declaring symbols to be weak, and defining weak
23541 @item #pragma weak @var{symbol}
23542 @cindex pragma, weak
23543 This pragma declares @var{symbol} to be weak, as if the declaration
23544 had the attribute of the same name. The pragma may appear before
23545 or after the declaration of @var{symbol}. It is not an error for
23546 @var{symbol} to never be defined at all.
23548 @item #pragma weak @var{symbol1} = @var{symbol2}
23549 This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}.
23550 It is an error if @var{symbol2} is not defined in the current
23554 @node Diagnostic Pragmas
23555 @subsection Diagnostic Pragmas
23557 GCC allows the user to selectively enable or disable certain types of
23558 diagnostics, and change the kind of the diagnostic. For example, a
23559 project's policy might require that all sources compile with
23560 @option{-Werror} but certain files might have exceptions allowing
23561 specific types of warnings. Or, a project might selectively enable
23562 diagnostics and treat them as errors depending on which preprocessor
23563 macros are defined.
23566 @item #pragma GCC diagnostic @var{kind} @var{option}
23567 @cindex pragma, diagnostic
23569 Modifies the disposition of a diagnostic. Note that not all
23570 diagnostics are modifiable; at the moment only warnings (normally
23571 controlled by @samp{-W@dots{}}) can be controlled, and not all of them.
23572 Use @option{-fdiagnostics-show-option} to determine which diagnostics
23573 are controllable and which option controls them.
23575 @var{kind} is @samp{error} to treat this diagnostic as an error,
23576 @samp{warning} to treat it like a warning (even if @option{-Werror} is
23577 in effect), or @samp{ignored} if the diagnostic is to be ignored.
23578 @var{option} is a double quoted string that matches the command-line
23582 #pragma GCC diagnostic warning "-Wformat"
23583 #pragma GCC diagnostic error "-Wformat"
23584 #pragma GCC diagnostic ignored "-Wformat"
23587 Note that these pragmas override any command-line options. GCC keeps
23588 track of the location of each pragma, and issues diagnostics according
23589 to the state as of that point in the source file. Thus, pragmas occurring
23590 after a line do not affect diagnostics caused by that line.
23592 @item #pragma GCC diagnostic push
23593 @itemx #pragma GCC diagnostic pop
23595 Causes GCC to remember the state of the diagnostics as of each
23596 @code{push}, and restore to that point at each @code{pop}. If a
23597 @code{pop} has no matching @code{push}, the command-line options are
23601 #pragma GCC diagnostic error "-Wuninitialized"
23602 foo(a); /* error is given for this one */
23603 #pragma GCC diagnostic push
23604 #pragma GCC diagnostic ignored "-Wuninitialized"
23605 foo(b); /* no diagnostic for this one */
23606 #pragma GCC diagnostic pop
23607 foo(c); /* error is given for this one */
23608 #pragma GCC diagnostic pop
23609 foo(d); /* depends on command-line options */
23614 GCC also offers a simple mechanism for printing messages during
23618 @item #pragma message @var{string}
23619 @cindex pragma, diagnostic
23621 Prints @var{string} as a compiler message on compilation. The message
23622 is informational only, and is neither a compilation warning nor an
23623 error. Newlines can be included in the string by using the @samp{\n}
23627 #pragma message "Compiling " __FILE__ "..."
23630 @var{string} may be parenthesized, and is printed with location
23631 information. For example,
23634 #define DO_PRAGMA(x) _Pragma (#x)
23635 #define TODO(x) DO_PRAGMA(message ("TODO - " #x))
23637 TODO(Remember to fix this)
23641 prints @samp{/tmp/file.c:4: note: #pragma message:
23642 TODO - Remember to fix this}.
23644 @item #pragma GCC error @var{message}
23645 @cindex pragma, diagnostic
23646 Generates an error message. This pragma @emph{is} considered to
23647 indicate an error in the compilation, and it will be treated as such.
23649 Newlines can be included in the string by using the @samp{\n}
23650 escape sequence. They will be displayed as newlines even if the
23651 @option{-fmessage-length} option is set to zero.
23653 The error is only generated if the pragma is present in the code after
23654 pre-processing has been completed. It does not matter however if the
23655 code containing the pragma is unreachable:
23659 #pragma GCC error "this error is not seen"
23664 #pragma GCC error "this error is seen"
23668 @item #pragma GCC warning @var{message}
23669 @cindex pragma, diagnostic
23670 This is just like @samp{pragma GCC error} except that a warning
23671 message is issued instead of an error message. Unless
23672 @option{-Werror} is in effect, in which case this pragma will generate
23677 @node Visibility Pragmas
23678 @subsection Visibility Pragmas
23681 @item #pragma GCC visibility push(@var{visibility})
23682 @itemx #pragma GCC visibility pop
23683 @cindex pragma, visibility
23685 This pragma allows the user to set the visibility for multiple
23686 declarations without having to give each a visibility attribute
23687 (@pxref{Function Attributes}).
23689 In C++, @samp{#pragma GCC visibility} affects only namespace-scope
23690 declarations. Class members and template specializations are not
23691 affected; if you want to override the visibility for a particular
23692 member or instantiation, you must use an attribute.
23697 @node Push/Pop Macro Pragmas
23698 @subsection Push/Pop Macro Pragmas
23700 For compatibility with Microsoft Windows compilers, GCC supports
23701 @samp{#pragma push_macro(@var{"macro_name"})}
23702 and @samp{#pragma pop_macro(@var{"macro_name"})}.
23705 @item #pragma push_macro(@var{"macro_name"})
23706 @cindex pragma, push_macro
23707 This pragma saves the value of the macro named as @var{macro_name} to
23708 the top of the stack for this macro.
23710 @item #pragma pop_macro(@var{"macro_name"})
23711 @cindex pragma, pop_macro
23712 This pragma sets the value of the macro named as @var{macro_name} to
23713 the value on top of the stack for this macro. If the stack for
23714 @var{macro_name} is empty, the value of the macro remains unchanged.
23721 #pragma push_macro("X")
23724 #pragma pop_macro("X")
23729 In this example, the definition of X as 1 is saved by @code{#pragma
23730 push_macro} and restored by @code{#pragma pop_macro}.
23732 @node Function Specific Option Pragmas
23733 @subsection Function Specific Option Pragmas
23736 @item #pragma GCC target (@var{string}, @dots{})
23737 @cindex pragma GCC target
23739 This pragma allows you to set target-specific options for functions
23740 defined later in the source file. One or more strings can be
23741 specified. Each function that is defined after this point is treated
23742 as if it had been declared with one @code{target(}@var{string}@code{)}
23743 attribute for each @var{string} argument. The parentheses around
23744 the strings in the pragma are optional. @xref{Function Attributes},
23745 for more information about the @code{target} attribute and the attribute
23748 The @code{#pragma GCC target} pragma is presently implemented for
23749 x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only.
23751 @item #pragma GCC optimize (@var{string}, @dots{})
23752 @cindex pragma GCC optimize
23754 This pragma allows you to set global optimization options for functions
23755 defined later in the source file. One or more strings can be
23756 specified. Each function that is defined after this point is treated
23757 as if it had been declared with one @code{optimize(}@var{string}@code{)}
23758 attribute for each @var{string} argument. The parentheses around
23759 the strings in the pragma are optional. @xref{Function Attributes},
23760 for more information about the @code{optimize} attribute and the attribute
23763 @item #pragma GCC push_options
23764 @itemx #pragma GCC pop_options
23765 @cindex pragma GCC push_options
23766 @cindex pragma GCC pop_options
23768 These pragmas maintain a stack of the current target and optimization
23769 options. It is intended for include files where you temporarily want
23770 to switch to using a different @samp{#pragma GCC target} or
23771 @samp{#pragma GCC optimize} and then to pop back to the previous
23774 @item #pragma GCC reset_options
23775 @cindex pragma GCC reset_options
23777 This pragma clears the current @code{#pragma GCC target} and
23778 @code{#pragma GCC optimize} to use the default switches as specified
23779 on the command line.
23783 @node Loop-Specific Pragmas
23784 @subsection Loop-Specific Pragmas
23787 @item #pragma GCC ivdep
23788 @cindex pragma GCC ivdep
23790 With this pragma, the programmer asserts that there are no loop-carried
23791 dependencies which would prevent consecutive iterations of
23792 the following loop from executing concurrently with SIMD
23793 (single instruction multiple data) instructions.
23795 For example, the compiler can only unconditionally vectorize the following
23796 loop with the pragma:
23799 void foo (int n, int *a, int *b, int *c)
23803 for (i = 0; i < n; ++i)
23804 a[i] = b[i] + c[i];
23809 In this example, using the @code{restrict} qualifier had the same
23810 effect. In the following example, that would not be possible. Assume
23811 @math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows
23812 that it can unconditionally vectorize the following loop:
23815 void ignore_vec_dep (int *a, int k, int c, int m)
23818 for (int i = 0; i < m; i++)
23819 a[i] = a[i + k] * c;
23823 @item #pragma GCC unroll @var{n}
23824 @cindex pragma GCC unroll @var{n}
23826 You can use this pragma to control how many times a loop should be unrolled.
23827 It must be placed immediately before a @code{for}, @code{while} or @code{do}
23828 loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows.
23829 @var{n} is an integer constant expression specifying the unrolling factor.
23830 The values of @math{0} and @math{1} block any unrolling of the loop.
23834 @node Unnamed Fields
23835 @section Unnamed Structure and Union Fields
23836 @cindex @code{struct}
23837 @cindex @code{union}
23839 As permitted by ISO C11 and for compatibility with other compilers,
23840 GCC allows you to define
23841 a structure or union that contains, as fields, structures and unions
23842 without names. For example:
23856 In this example, you are able to access members of the unnamed
23857 union with code like @samp{foo.b}. Note that only unnamed structs and
23858 unions are allowed, you may not have, for example, an unnamed
23861 You must never create such structures that cause ambiguous field definitions.
23862 For example, in this structure:
23874 it is ambiguous which @code{a} is being referred to with @samp{foo.a}.
23875 The compiler gives errors for such constructs.
23877 @opindex fms-extensions
23878 Unless @option{-fms-extensions} is used, the unnamed field must be a
23879 structure or union definition without a tag (for example, @samp{struct
23880 @{ int a; @};}). If @option{-fms-extensions} is used, the field may
23881 also be a definition with a tag such as @samp{struct foo @{ int a;
23882 @};}, a reference to a previously defined structure or union such as
23883 @samp{struct foo;}, or a reference to a @code{typedef} name for a
23884 previously defined structure or union type.
23886 @opindex fplan9-extensions
23887 The option @option{-fplan9-extensions} enables
23888 @option{-fms-extensions} as well as two other extensions. First, a
23889 pointer to a structure is automatically converted to a pointer to an
23890 anonymous field for assignments and function calls. For example:
23893 struct s1 @{ int a; @};
23894 struct s2 @{ struct s1; @};
23895 extern void f1 (struct s1 *);
23896 void f2 (struct s2 *p) @{ f1 (p); @}
23900 In the call to @code{f1} inside @code{f2}, the pointer @code{p} is
23901 converted into a pointer to the anonymous field.
23903 Second, when the type of an anonymous field is a @code{typedef} for a
23904 @code{struct} or @code{union}, code may refer to the field using the
23905 name of the @code{typedef}.
23908 typedef struct @{ int a; @} s1;
23909 struct s2 @{ s1; @};
23910 s1 f1 (struct s2 *p) @{ return p->s1; @}
23913 These usages are only permitted when they are not ambiguous.
23916 @section Thread-Local Storage
23917 @cindex Thread-Local Storage
23918 @cindex @acronym{TLS}
23919 @cindex @code{__thread}
23921 Thread-local storage (@acronym{TLS}) is a mechanism by which variables
23922 are allocated such that there is one instance of the variable per extant
23923 thread. The runtime model GCC uses to implement this originates
23924 in the IA-64 processor-specific ABI, but has since been migrated
23925 to other processors as well. It requires significant support from
23926 the linker (@command{ld}), dynamic linker (@command{ld.so}), and
23927 system libraries (@file{libc.so} and @file{libpthread.so}), so it
23928 is not available everywhere.
23930 At the user level, the extension is visible with a new storage
23931 class keyword: @code{__thread}. For example:
23935 extern __thread struct state s;
23936 static __thread char *p;
23939 The @code{__thread} specifier may be used alone, with the @code{extern}
23940 or @code{static} specifiers, but with no other storage class specifier.
23941 When used with @code{extern} or @code{static}, @code{__thread} must appear
23942 immediately after the other storage class specifier.
23944 The @code{__thread} specifier may be applied to any global, file-scoped
23945 static, function-scoped static, or static data member of a class. It may
23946 not be applied to block-scoped automatic or non-static data member.
23948 When the address-of operator is applied to a thread-local variable, it is
23949 evaluated at run time and returns the address of the current thread's
23950 instance of that variable. An address so obtained may be used by any
23951 thread. When a thread terminates, any pointers to thread-local variables
23952 in that thread become invalid.
23954 No static initialization may refer to the address of a thread-local variable.
23956 In C++, if an initializer is present for a thread-local variable, it must
23957 be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++
23960 See @uref{https://www.akkadia.org/drepper/tls.pdf,
23961 ELF Handling For Thread-Local Storage} for a detailed explanation of
23962 the four thread-local storage addressing models, and how the runtime
23963 is expected to function.
23966 * C99 Thread-Local Edits::
23967 * C++98 Thread-Local Edits::
23970 @node C99 Thread-Local Edits
23971 @subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage
23973 The following are a set of changes to ISO/IEC 9899:1999 (aka C99)
23974 that document the exact semantics of the language extension.
23978 @cite{5.1.2 Execution environments}
23980 Add new text after paragraph 1
23983 Within either execution environment, a @dfn{thread} is a flow of
23984 control within a program. It is implementation defined whether
23985 or not there may be more than one thread associated with a program.
23986 It is implementation defined how threads beyond the first are
23987 created, the name and type of the function called at thread
23988 startup, and how threads may be terminated. However, objects
23989 with thread storage duration shall be initialized before thread
23994 @cite{6.2.4 Storage durations of objects}
23996 Add new text before paragraph 3
23999 An object whose identifier is declared with the storage-class
24000 specifier @w{@code{__thread}} has @dfn{thread storage duration}.
24001 Its lifetime is the entire execution of the thread, and its
24002 stored value is initialized only once, prior to thread startup.
24006 @cite{6.4.1 Keywords}
24008 Add @code{__thread}.
24011 @cite{6.7.1 Storage-class specifiers}
24013 Add @code{__thread} to the list of storage class specifiers in
24016 Change paragraph 2 to
24019 With the exception of @code{__thread}, at most one storage-class
24020 specifier may be given [@dots{}]. The @code{__thread} specifier may
24021 be used alone, or immediately following @code{extern} or
24025 Add new text after paragraph 6
24028 The declaration of an identifier for a variable that has
24029 block scope that specifies @code{__thread} shall also
24030 specify either @code{extern} or @code{static}.
24032 The @code{__thread} specifier shall be used only with
24037 @node C++98 Thread-Local Edits
24038 @subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage
24040 The following are a set of changes to ISO/IEC 14882:1998 (aka C++98)
24041 that document the exact semantics of the language extension.
24045 @b{[intro.execution]}
24047 New text after paragraph 4
24050 A @dfn{thread} is a flow of control within the abstract machine.
24051 It is implementation defined whether or not there may be more than
24055 New text after paragraph 7
24058 It is unspecified whether additional action must be taken to
24059 ensure when and whether side effects are visible to other threads.
24065 Add @code{__thread}.
24068 @b{[basic.start.main]}
24070 Add after paragraph 5
24073 The thread that begins execution at the @code{main} function is called
24074 the @dfn{main thread}. It is implementation defined how functions
24075 beginning threads other than the main thread are designated or typed.
24076 A function so designated, as well as the @code{main} function, is called
24077 a @dfn{thread startup function}. It is implementation defined what
24078 happens if a thread startup function returns. It is implementation
24079 defined what happens to other threads when any thread calls @code{exit}.
24083 @b{[basic.start.init]}
24085 Add after paragraph 4
24088 The storage for an object of thread storage duration shall be
24089 statically initialized before the first statement of the thread startup
24090 function. An object of thread storage duration shall not require
24091 dynamic initialization.
24095 @b{[basic.start.term]}
24097 Add after paragraph 3
24100 The type of an object with thread storage duration shall not have a
24101 non-trivial destructor, nor shall it be an array type whose elements
24102 (directly or indirectly) have non-trivial destructors.
24108 Add ``thread storage duration'' to the list in paragraph 1.
24113 Thread, static, and automatic storage durations are associated with
24114 objects introduced by declarations [@dots{}].
24117 Add @code{__thread} to the list of specifiers in paragraph 3.
24120 @b{[basic.stc.thread]}
24122 New section before @b{[basic.stc.static]}
24125 The keyword @code{__thread} applied to a non-local object gives the
24126 object thread storage duration.
24128 A local variable or class data member declared both @code{static}
24129 and @code{__thread} gives the variable or member thread storage
24134 @b{[basic.stc.static]}
24139 All objects that have neither thread storage duration, dynamic
24140 storage duration nor are local [@dots{}].
24146 Add @code{__thread} to the list in paragraph 1.
24151 With the exception of @code{__thread}, at most one
24152 @var{storage-class-specifier} shall appear in a given
24153 @var{decl-specifier-seq}. The @code{__thread} specifier may
24154 be used alone, or immediately following the @code{extern} or
24155 @code{static} specifiers. [@dots{}]
24158 Add after paragraph 5
24161 The @code{__thread} specifier can be applied only to the names of objects
24162 and to anonymous unions.
24168 Add after paragraph 6
24171 Non-@code{static} members shall not be @code{__thread}.
24175 @node Binary constants
24176 @section Binary Constants using the @samp{0b} Prefix
24177 @cindex Binary constants using the @samp{0b} prefix
24179 Integer constants can be written as binary constants, consisting of a
24180 sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
24181 @samp{0B}. This is particularly useful in environments that operate a
24182 lot on the bit level (like microcontrollers).
24184 The following statements are identical:
24193 The type of these constants follows the same rules as for octal or
24194 hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
24197 @node C++ Extensions
24198 @chapter Extensions to the C++ Language
24199 @cindex extensions, C++ language
24200 @cindex C++ language extensions
24202 The GNU compiler provides these extensions to the C++ language (and you
24203 can also use most of the C language extensions in your C++ programs). If you
24204 want to write code that checks whether these features are available, you can
24205 test for the GNU compiler the same way as for C programs: check for a
24206 predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to
24207 test specifically for GNU C++ (@pxref{Common Predefined Macros,,
24208 Predefined Macros,cpp,The GNU C Preprocessor}).
24211 * C++ Volatiles:: What constitutes an access to a volatile object.
24212 * Restricted Pointers:: C99 restricted pointers and references.
24213 * Vague Linkage:: Where G++ puts inlines, vtables and such.
24214 * C++ Interface:: You can use a single C++ header file for both
24215 declarations and definitions.
24216 * Template Instantiation:: Methods for ensuring that exactly one copy of
24217 each needed template instantiation is emitted.
24218 * Bound member functions:: You can extract a function pointer to the
24219 method denoted by a @samp{->*} or @samp{.*} expression.
24220 * C++ Attributes:: Variable, function, and type attributes for C++ only.
24221 * Function Multiversioning:: Declaring multiple function versions.
24222 * Type Traits:: Compiler support for type traits.
24223 * C++ Concepts:: Improved support for generic programming.
24224 * Deprecated Features:: Things will disappear from G++.
24225 * Backwards Compatibility:: Compatibilities with earlier definitions of C++.
24228 @node C++ Volatiles
24229 @section When is a Volatile C++ Object Accessed?
24230 @cindex accessing volatiles
24231 @cindex volatile read
24232 @cindex volatile write
24233 @cindex volatile access
24235 The C++ standard differs from the C standard in its treatment of
24236 volatile objects. It fails to specify what constitutes a volatile
24237 access, except to say that C++ should behave in a similar manner to C
24238 with respect to volatiles, where possible. However, the different
24239 lvalueness of expressions between C and C++ complicate the behavior.
24240 G++ behaves the same as GCC for volatile access, @xref{C
24241 Extensions,,Volatiles}, for a description of GCC's behavior.
24243 The C and C++ language specifications differ when an object is
24244 accessed in a void context:
24247 volatile int *src = @var{somevalue};
24251 The C++ standard specifies that such expressions do not undergo lvalue
24252 to rvalue conversion, and that the type of the dereferenced object may
24253 be incomplete. The C++ standard does not specify explicitly that it
24254 is lvalue to rvalue conversion that is responsible for causing an
24255 access. There is reason to believe that it is, because otherwise
24256 certain simple expressions become undefined. However, because it
24257 would surprise most programmers, G++ treats dereferencing a pointer to
24258 volatile object of complete type as GCC would do for an equivalent
24259 type in C@. When the object has incomplete type, G++ issues a
24260 warning; if you wish to force an error, you must force a conversion to
24261 rvalue with, for instance, a static cast.
24263 When using a reference to volatile, G++ does not treat equivalent
24264 expressions as accesses to volatiles, but instead issues a warning that
24265 no volatile is accessed. The rationale for this is that otherwise it
24266 becomes difficult to determine where volatile access occur, and not
24267 possible to ignore the return value from functions returning volatile
24268 references. Again, if you wish to force a read, cast the reference to
24271 G++ implements the same behavior as GCC does when assigning to a
24272 volatile object---there is no reread of the assigned-to object, the
24273 assigned rvalue is reused. Note that in C++ assignment expressions
24274 are lvalues, and if used as an lvalue, the volatile object is
24275 referred to. For instance, @var{vref} refers to @var{vobj}, as
24276 expected, in the following example:
24280 volatile int &vref = vobj = @var{something};
24283 @node Restricted Pointers
24284 @section Restricting Pointer Aliasing
24285 @cindex restricted pointers
24286 @cindex restricted references
24287 @cindex restricted this pointer
24289 As with the C front end, G++ understands the C99 feature of restricted pointers,
24290 specified with the @code{__restrict__}, or @code{__restrict} type
24291 qualifier. Because you cannot compile C++ by specifying the @option{-std=c99}
24292 language flag, @code{restrict} is not a keyword in C++.
24294 In addition to allowing restricted pointers, you can specify restricted
24295 references, which indicate that the reference is not aliased in the local
24299 void fn (int *__restrict__ rptr, int &__restrict__ rref)
24306 In the body of @code{fn}, @var{rptr} points to an unaliased integer and
24307 @var{rref} refers to a (different) unaliased integer.
24309 You may also specify whether a member function's @var{this} pointer is
24310 unaliased by using @code{__restrict__} as a member function qualifier.
24313 void T::fn () __restrict__
24320 Within the body of @code{T::fn}, @var{this} has the effective
24321 definition @code{T *__restrict__ const this}. Notice that the
24322 interpretation of a @code{__restrict__} member function qualifier is
24323 different to that of @code{const} or @code{volatile} qualifier, in that it
24324 is applied to the pointer rather than the object. This is consistent with
24325 other compilers that implement restricted pointers.
24327 As with all outermost parameter qualifiers, @code{__restrict__} is
24328 ignored in function definition matching. This means you only need to
24329 specify @code{__restrict__} in a function definition, rather than
24330 in a function prototype as well.
24332 @node Vague Linkage
24333 @section Vague Linkage
24334 @cindex vague linkage
24336 There are several constructs in C++ that require space in the object
24337 file but are not clearly tied to a single translation unit. We say that
24338 these constructs have ``vague linkage''. Typically such constructs are
24339 emitted wherever they are needed, though sometimes we can be more
24343 @item Inline Functions
24344 Inline functions are typically defined in a header file which can be
24345 included in many different compilations. Hopefully they can usually be
24346 inlined, but sometimes an out-of-line copy is necessary, if the address
24347 of the function is taken or if inlining fails. In general, we emit an
24348 out-of-line copy in all translation units where one is needed. As an
24349 exception, we only emit inline virtual functions with the vtable, since
24350 it always requires a copy.
24352 Local static variables and string constants used in an inline function
24353 are also considered to have vague linkage, since they must be shared
24354 between all inlined and out-of-line instances of the function.
24358 C++ virtual functions are implemented in most compilers using a lookup
24359 table, known as a vtable. The vtable contains pointers to the virtual
24360 functions provided by a class, and each object of the class contains a
24361 pointer to its vtable (or vtables, in some multiple-inheritance
24362 situations). If the class declares any non-inline, non-pure virtual
24363 functions, the first one is chosen as the ``key method'' for the class,
24364 and the vtable is only emitted in the translation unit where the key
24367 @emph{Note:} If the chosen key method is later defined as inline, the
24368 vtable is still emitted in every translation unit that defines it.
24369 Make sure that any inline virtuals are declared inline in the class
24370 body, even if they are not defined there.
24372 @item @code{type_info} objects
24373 @cindex @code{type_info}
24375 C++ requires information about types to be written out in order to
24376 implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
24377 For polymorphic classes (classes with virtual functions), the @samp{type_info}
24378 object is written out along with the vtable so that @samp{dynamic_cast}
24379 can determine the dynamic type of a class object at run time. For all
24380 other types, we write out the @samp{type_info} object when it is used: when
24381 applying @samp{typeid} to an expression, throwing an object, or
24382 referring to a type in a catch clause or exception specification.
24384 @item Template Instantiations
24385 Most everything in this section also applies to template instantiations,
24386 but there are other options as well.
24387 @xref{Template Instantiation,,Where's the Template?}.
24391 When used with GNU ld version 2.8 or later on an ELF system such as
24392 GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of
24393 these constructs will be discarded at link time. This is known as
24396 On targets that don't support COMDAT, but do support weak symbols, GCC
24397 uses them. This way one copy overrides all the others, but
24398 the unused copies still take up space in the executable.
24400 For targets that do not support either COMDAT or weak symbols,
24401 most entities with vague linkage are emitted as local symbols to
24402 avoid duplicate definition errors from the linker. This does not happen
24403 for local statics in inlines, however, as having multiple copies
24404 almost certainly breaks things.
24406 @xref{C++ Interface,,Declarations and Definitions in One Header}, for
24407 another way to control placement of these constructs.
24409 @node C++ Interface
24410 @section C++ Interface and Implementation Pragmas
24412 @cindex interface and implementation headers, C++
24413 @cindex C++ interface and implementation headers
24414 @cindex pragmas, interface and implementation
24416 @code{#pragma interface} and @code{#pragma implementation} provide the
24417 user with a way of explicitly directing the compiler to emit entities
24418 with vague linkage (and debugging information) in a particular
24421 @emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2
24422 by COMDAT support and the ``key method'' heuristic
24423 mentioned in @ref{Vague Linkage}. Using them can actually cause your
24424 program to grow due to unnecessary out-of-line copies of inline
24428 @item #pragma interface
24429 @itemx #pragma interface "@var{subdir}/@var{objects}.h"
24430 @kindex #pragma interface
24431 Use this directive in @emph{header files} that define object classes, to save
24432 space in most of the object files that use those classes. Normally,
24433 local copies of certain information (backup copies of inline member
24434 functions, debugging information, and the internal tables that implement
24435 virtual functions) must be kept in each object file that includes class
24436 definitions. You can use this pragma to avoid such duplication. When a
24437 header file containing @samp{#pragma interface} is included in a
24438 compilation, this auxiliary information is not generated (unless
24439 the main input source file itself uses @samp{#pragma implementation}).
24440 Instead, the object files contain references to be resolved at link
24443 The second form of this directive is useful for the case where you have
24444 multiple headers with the same name in different directories. If you
24445 use this form, you must specify the same string to @samp{#pragma
24448 @item #pragma implementation
24449 @itemx #pragma implementation "@var{objects}.h"
24450 @kindex #pragma implementation
24451 Use this pragma in a @emph{main input file}, when you want full output from
24452 included header files to be generated (and made globally visible). The
24453 included header file, in turn, should use @samp{#pragma interface}.
24454 Backup copies of inline member functions, debugging information, and the
24455 internal tables used to implement virtual functions are all generated in
24456 implementation files.
24458 @cindex implied @code{#pragma implementation}
24459 @cindex @code{#pragma implementation}, implied
24460 @cindex naming convention, implementation headers
24461 If you use @samp{#pragma implementation} with no argument, it applies to
24462 an include file with the same basename@footnote{A file's @dfn{basename}
24463 is the name stripped of all leading path information and of trailing
24464 suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source
24465 file. For example, in @file{allclass.cc}, giving just
24466 @samp{#pragma implementation}
24467 by itself is equivalent to @samp{#pragma implementation "allclass.h"}.
24469 Use the string argument if you want a single implementation file to
24470 include code from multiple header files. (You must also use
24471 @samp{#include} to include the header file; @samp{#pragma
24472 implementation} only specifies how to use the file---it doesn't actually
24475 There is no way to split up the contents of a single header file into
24476 multiple implementation files.
24479 @cindex inlining and C++ pragmas
24480 @cindex C++ pragmas, effect on inlining
24481 @cindex pragmas in C++, effect on inlining
24482 @samp{#pragma implementation} and @samp{#pragma interface} also have an
24483 effect on function inlining.
24485 If you define a class in a header file marked with @samp{#pragma
24486 interface}, the effect on an inline function defined in that class is
24487 similar to an explicit @code{extern} declaration---the compiler emits
24488 no code at all to define an independent version of the function. Its
24489 definition is used only for inlining with its callers.
24491 @opindex fno-implement-inlines
24492 Conversely, when you include the same header file in a main source file
24493 that declares it as @samp{#pragma implementation}, the compiler emits
24494 code for the function itself; this defines a version of the function
24495 that can be found via pointers (or by callers compiled without
24496 inlining). If all calls to the function can be inlined, you can avoid
24497 emitting the function by compiling with @option{-fno-implement-inlines}.
24498 If any calls are not inlined, you will get linker errors.
24500 @node Template Instantiation
24501 @section Where's the Template?
24502 @cindex template instantiation
24504 C++ templates were the first language feature to require more
24505 intelligence from the environment than was traditionally found on a UNIX
24506 system. Somehow the compiler and linker have to make sure that each
24507 template instance occurs exactly once in the executable if it is needed,
24508 and not at all otherwise. There are two basic approaches to this
24509 problem, which are referred to as the Borland model and the Cfront model.
24512 @item Borland model
24513 Borland C++ solved the template instantiation problem by adding the code
24514 equivalent of common blocks to their linker; the compiler emits template
24515 instances in each translation unit that uses them, and the linker
24516 collapses them together. The advantage of this model is that the linker
24517 only has to consider the object files themselves; there is no external
24518 complexity to worry about. The disadvantage is that compilation time
24519 is increased because the template code is being compiled repeatedly.
24520 Code written for this model tends to include definitions of all
24521 templates in the header file, since they must be seen to be
24525 The AT&T C++ translator, Cfront, solved the template instantiation
24526 problem by creating the notion of a template repository, an
24527 automatically maintained place where template instances are stored. A
24528 more modern version of the repository works as follows: As individual
24529 object files are built, the compiler places any template definitions and
24530 instantiations encountered in the repository. At link time, the link
24531 wrapper adds in the objects in the repository and compiles any needed
24532 instances that were not previously emitted. The advantages of this
24533 model are more optimal compilation speed and the ability to use the
24534 system linker; to implement the Borland model a compiler vendor also
24535 needs to replace the linker. The disadvantages are vastly increased
24536 complexity, and thus potential for error; for some code this can be
24537 just as transparent, but in practice it can been very difficult to build
24538 multiple programs in one directory and one program in multiple
24539 directories. Code written for this model tends to separate definitions
24540 of non-inline member templates into a separate file, which should be
24541 compiled separately.
24544 G++ implements the Borland model on targets where the linker supports it,
24545 including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows.
24546 Otherwise G++ implements neither automatic model.
24548 You have the following options for dealing with template instantiations:
24552 Do nothing. Code written for the Borland model works fine, but
24553 each translation unit contains instances of each of the templates it
24554 uses. The duplicate instances will be discarded by the linker, but in
24555 a large program, this can lead to an unacceptable amount of code
24556 duplication in object files or shared libraries.
24558 Duplicate instances of a template can be avoided by defining an explicit
24559 instantiation in one object file, and preventing the compiler from doing
24560 implicit instantiations in any other object files by using an explicit
24561 instantiation declaration, using the @code{extern template} syntax:
24564 extern template int max (int, int);
24567 This syntax is defined in the C++ 2011 standard, but has been supported by
24568 G++ and other compilers since well before 2011.
24570 Explicit instantiations can be used for the largest or most frequently
24571 duplicated instances, without having to know exactly which other instances
24572 are used in the rest of the program. You can scatter the explicit
24573 instantiations throughout your program, perhaps putting them in the
24574 translation units where the instances are used or the translation units
24575 that define the templates themselves; you can put all of the explicit
24576 instantiations you need into one big file; or you can create small files
24583 template class Foo<int>;
24584 template ostream& operator <<
24585 (ostream&, const Foo<int>&);
24589 for each of the instances you need, and create a template instantiation
24590 library from those.
24592 This is the simplest option, but also offers flexibility and
24593 fine-grained control when necessary. It is also the most portable
24594 alternative and programs using this approach will work with most modern
24598 @opindex fno-implicit-templates
24599 Compile your code with @option{-fno-implicit-templates} to disable the
24600 implicit generation of template instances, and explicitly instantiate
24601 all the ones you use. This approach requires more knowledge of exactly
24602 which instances you need than do the others, but it's less
24603 mysterious and allows greater control if you want to ensure that only
24604 the intended instances are used.
24606 If you are using Cfront-model code, you can probably get away with not
24607 using @option{-fno-implicit-templates} when compiling files that don't
24608 @samp{#include} the member template definitions.
24610 If you use one big file to do the instantiations, you may want to
24611 compile it without @option{-fno-implicit-templates} so you get all of the
24612 instances required by your explicit instantiations (but not by any
24613 other files) without having to specify them as well.
24615 In addition to forward declaration of explicit instantiations
24616 (with @code{extern}), G++ has extended the template instantiation
24617 syntax to support instantiation of the compiler support data for a
24618 template class (i.e.@: the vtable) without instantiating any of its
24619 members (with @code{inline}), and instantiation of only the static data
24620 members of a template class, without the support data or member
24621 functions (with @code{static}):
24624 inline template class Foo<int>;
24625 static template class Foo<int>;
24629 @node Bound member functions
24630 @section Extracting the Function Pointer from a Bound Pointer to Member Function
24632 @cindex pointer to member function
24633 @cindex bound pointer to member function
24635 In C++, pointer to member functions (PMFs) are implemented using a wide
24636 pointer of sorts to handle all the possible call mechanisms; the PMF
24637 needs to store information about how to adjust the @samp{this} pointer,
24638 and if the function pointed to is virtual, where to find the vtable, and
24639 where in the vtable to look for the member function. If you are using
24640 PMFs in an inner loop, you should really reconsider that decision. If
24641 that is not an option, you can extract the pointer to the function that
24642 would be called for a given object/PMF pair and call it directly inside
24643 the inner loop, to save a bit of time.
24645 Note that you still pay the penalty for the call through a
24646 function pointer; on most modern architectures, such a call defeats the
24647 branch prediction features of the CPU@. This is also true of normal
24648 virtual function calls.
24650 The syntax for this extension is
24654 extern int (A::*fp)();
24655 typedef int (*fptr)(A *);
24657 fptr p = (fptr)(a.*fp);
24660 For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}),
24661 no object is needed to obtain the address of the function. They can be
24662 converted to function pointers directly:
24665 fptr p1 = (fptr)(&A::foo);
24668 @opindex Wno-pmf-conversions
24669 You must specify @option{-Wno-pmf-conversions} to use this extension.
24671 @node C++ Attributes
24672 @section C++-Specific Variable, Function, and Type Attributes
24674 Some attributes only make sense for C++ programs.
24677 @item abi_tag ("@var{tag}", ...)
24678 @cindex @code{abi_tag} function attribute
24679 @cindex @code{abi_tag} variable attribute
24680 @cindex @code{abi_tag} type attribute
24681 The @code{abi_tag} attribute can be applied to a function, variable, or class
24682 declaration. It modifies the mangled name of the entity to
24683 incorporate the tag name, in order to distinguish the function or
24684 class from an earlier version with a different ABI; perhaps the class
24685 has changed size, or the function has a different return type that is
24686 not encoded in the mangled name.
24688 The attribute can also be applied to an inline namespace, but does not
24689 affect the mangled name of the namespace; in this case it is only used
24690 for @option{-Wabi-tag} warnings and automatic tagging of functions and
24691 variables. Tagging inline namespaces is generally preferable to
24692 tagging individual declarations, but the latter is sometimes
24693 necessary, such as when only certain members of a class need to be
24696 The argument can be a list of strings of arbitrary length. The
24697 strings are sorted on output, so the order of the list is
24700 A redeclaration of an entity must not add new ABI tags,
24701 since doing so would change the mangled name.
24703 The ABI tags apply to a name, so all instantiations and
24704 specializations of a template have the same tags. The attribute will
24705 be ignored if applied to an explicit specialization or instantiation.
24707 The @option{-Wabi-tag} flag enables a warning about a class which does
24708 not have all the ABI tags used by its subobjects and virtual functions; for users with code
24709 that needs to coexist with an earlier ABI, using this option can help
24710 to find all affected types that need to be tagged.
24712 When a type involving an ABI tag is used as the type of a variable or
24713 return type of a function where that tag is not already present in the
24714 signature of the function, the tag is automatically applied to the
24715 variable or function. @option{-Wabi-tag} also warns about this
24716 situation; this warning can be avoided by explicitly tagging the
24717 variable or function or moving it into a tagged inline namespace.
24719 @item init_priority (@var{priority})
24720 @cindex @code{init_priority} variable attribute
24722 In Standard C++, objects defined at namespace scope are guaranteed to be
24723 initialized in an order in strict accordance with that of their definitions
24724 @emph{in a given translation unit}. No guarantee is made for initializations
24725 across translation units. However, GNU C++ allows users to control the
24726 order of initialization of objects defined at namespace scope with the
24727 @code{init_priority} attribute by specifying a relative @var{priority},
24728 a constant integral expression currently bounded between 101 and 65535
24729 inclusive. Lower numbers indicate a higher priority.
24731 In the following example, @code{A} would normally be created before
24732 @code{B}, but the @code{init_priority} attribute reverses that order:
24735 Some_Class A __attribute__ ((init_priority (2000)));
24736 Some_Class B __attribute__ ((init_priority (543)));
24740 Note that the particular values of @var{priority} do not matter; only their
24744 @cindex @code{warn_unused} type attribute
24746 For C++ types with non-trivial constructors and/or destructors it is
24747 impossible for the compiler to determine whether a variable of this
24748 type is truly unused if it is not referenced. This type attribute
24749 informs the compiler that variables of this type should be warned
24750 about if they appear to be unused, just like variables of fundamental
24753 This attribute is appropriate for types which just represent a value,
24754 such as @code{std::string}; it is not appropriate for types which
24755 control a resource, such as @code{std::lock_guard}.
24757 This attribute is also accepted in C, but it is unnecessary because C
24758 does not have constructors or destructors.
24762 @node Function Multiversioning
24763 @section Function Multiversioning
24764 @cindex function versions
24766 With the GNU C++ front end, for x86 targets, you may specify multiple
24767 versions of a function, where each function is specialized for a
24768 specific target feature. At runtime, the appropriate version of the
24769 function is automatically executed depending on the characteristics of
24770 the execution platform. Here is an example.
24773 __attribute__ ((target ("default")))
24776 // The default version of foo.
24780 __attribute__ ((target ("sse4.2")))
24783 // foo version for SSE4.2
24787 __attribute__ ((target ("arch=atom")))
24790 // foo version for the Intel ATOM processor
24794 __attribute__ ((target ("arch=amdfam10")))
24797 // foo version for the AMD Family 0x10 processors.
24804 assert ((*p) () == foo ());
24809 In the above example, four versions of function foo are created. The
24810 first version of foo with the target attribute "default" is the default
24811 version. This version gets executed when no other target specific
24812 version qualifies for execution on a particular platform. A new version
24813 of foo is created by using the same function signature but with a
24814 different target string. Function foo is called or a pointer to it is
24815 taken just like a regular function. GCC takes care of doing the
24816 dispatching to call the right version at runtime. Refer to the
24817 @uref{http://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
24818 Function Multiversioning} for more details.
24821 @section Type Traits
24823 The C++ front end implements syntactic extensions that allow
24824 compile-time determination of
24825 various characteristics of a type (or of a
24829 @item __has_nothrow_assign (type)
24830 If @code{type} is @code{const}-qualified or is a reference type then
24831 the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)}
24832 is @code{true} then the trait is @code{true}, else if @code{type} is
24833 a cv-qualified class or union type with copy assignment operators that are
24834 known not to throw an exception then the trait is @code{true}, else it is
24836 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24837 @code{void}, or an array of unknown bound.
24839 @item __has_nothrow_copy (type)
24840 If @code{__has_trivial_copy (type)} is @code{true} then the trait is
24841 @code{true}, else if @code{type} is a cv-qualified class or union type
24842 with copy constructors that are known not to throw an exception then
24843 the trait is @code{true}, else it is @code{false}.
24844 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24845 @code{void}, or an array of unknown bound.
24847 @item __has_nothrow_constructor (type)
24848 If @code{__has_trivial_constructor (type)} is @code{true} then the trait
24849 is @code{true}, else if @code{type} is a cv class or union type (or array
24850 thereof) with a default constructor that is known not to throw an
24851 exception then the trait is @code{true}, else it is @code{false}.
24852 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24853 @code{void}, or an array of unknown bound.
24855 @item __has_trivial_assign (type)
24856 If @code{type} is @code{const}- qualified or is a reference type then
24857 the trait is @code{false}. Otherwise if @code{__is_pod (type)} is
24858 @code{true} then the trait is @code{true}, else if @code{type} is
24859 a cv-qualified class or union type with a trivial copy assignment
24860 ([class.copy]) then the trait 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 __has_trivial_copy (type)
24865 If @code{__is_pod (type)} is @code{true} or @code{type} is a reference
24866 type then the trait is @code{true}, else if @code{type} is a cv class
24867 or union type with a trivial copy constructor ([class.copy]) then the trait
24868 is @code{true}, else it is @code{false}. Requires: @code{type} shall be
24869 a complete type, (possibly cv-qualified) @code{void}, or an array of unknown
24872 @item __has_trivial_constructor (type)
24873 If @code{__is_pod (type)} is @code{true} then the trait is @code{true},
24874 else if @code{type} is a cv-qualified class or union type (or array thereof)
24875 with a trivial default constructor ([class.ctor]) then the trait is @code{true},
24876 else it is @code{false}.
24877 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24878 @code{void}, or an array of unknown bound.
24880 @item __has_trivial_destructor (type)
24881 If @code{__is_pod (type)} is @code{true} or @code{type} is a reference type
24882 then the trait is @code{true}, else if @code{type} is a cv class or union
24883 type (or array thereof) with a trivial destructor ([class.dtor]) then
24884 the trait is @code{true}, else it is @code{false}.
24885 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24886 @code{void}, or an array of unknown bound.
24888 @item __has_virtual_destructor (type)
24889 If @code{type} is a class type with a virtual destructor
24890 ([class.dtor]) then the trait is @code{true}, else it is @code{false}.
24891 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24892 @code{void}, or an array of unknown bound.
24894 @item __is_abstract (type)
24895 If @code{type} is an abstract class ([class.abstract]) then the trait
24896 is @code{true}, else it is @code{false}.
24897 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24898 @code{void}, or an array of unknown bound.
24900 @item __is_base_of (base_type, derived_type)
24901 If @code{base_type} is a base class of @code{derived_type}
24902 ([class.derived]) then the trait is @code{true}, otherwise it is @code{false}.
24903 Top-level cv-qualifications of @code{base_type} and
24904 @code{derived_type} are ignored. For the purposes of this trait, a
24905 class type is considered is own base.
24906 Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)}
24907 are @code{true} and @code{base_type} and @code{derived_type} are not the same
24908 type (disregarding cv-qualifiers), @code{derived_type} shall be a complete
24909 type. A diagnostic is produced if this requirement is not met.
24911 @item __is_class (type)
24912 If @code{type} is a cv-qualified class type, and not a union type
24913 ([basic.compound]) the trait is @code{true}, else it is @code{false}.
24915 @item __is_empty (type)
24916 If @code{__is_class (type)} is @code{false} then the trait is @code{false}.
24917 Otherwise @code{type} is considered empty if and only if: @code{type}
24918 has no non-static data members, or all non-static data members, if
24919 any, are bit-fields of length 0, and @code{type} has no virtual
24920 members, and @code{type} has no virtual base classes, and @code{type}
24921 has no base classes @code{base_type} for which
24922 @code{__is_empty (base_type)} is @code{false}.
24923 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24924 @code{void}, or an array of unknown bound.
24926 @item __is_enum (type)
24927 If @code{type} is a cv enumeration type ([basic.compound]) the trait is
24928 @code{true}, else it is @code{false}.
24930 @item __is_literal_type (type)
24931 If @code{type} is a literal type ([basic.types]) the trait is
24932 @code{true}, else it is @code{false}.
24933 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24934 @code{void}, or an array of unknown bound.
24936 @item __is_pod (type)
24937 If @code{type} is a cv POD type ([basic.types]) then the trait is @code{true},
24938 else it is @code{false}.
24939 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24940 @code{void}, or an array of unknown bound.
24942 @item __is_polymorphic (type)
24943 If @code{type} is a polymorphic class ([class.virtual]) then the trait
24944 is @code{true}, else it is @code{false}.
24945 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24946 @code{void}, or an array of unknown bound.
24948 @item __is_standard_layout (type)
24949 If @code{type} is a standard-layout type ([basic.types]) the trait is
24950 @code{true}, else it is @code{false}.
24951 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24952 @code{void}, or an array of unknown bound.
24954 @item __is_trivial (type)
24955 If @code{type} is a trivial type ([basic.types]) the trait is
24956 @code{true}, else it is @code{false}.
24957 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24958 @code{void}, or an array of unknown bound.
24960 @item __is_union (type)
24961 If @code{type} is a cv union type ([basic.compound]) the trait is
24962 @code{true}, else it is @code{false}.
24964 @item __underlying_type (type)
24965 The underlying type of @code{type}.
24966 Requires: @code{type} shall be an enumeration type ([dcl.enum]).
24968 @item __integer_pack (length)
24969 When used as the pattern of a pack expansion within a template
24970 definition, expands to a template argument pack containing integers
24971 from @code{0} to @code{length-1}. This is provided for efficient
24972 implementation of @code{std::make_integer_sequence}.
24978 @section C++ Concepts
24980 C++ concepts provide much-improved support for generic programming. In
24981 particular, they allow the specification of constraints on template arguments.
24982 The constraints are used to extend the usual overloading and partial
24983 specialization capabilities of the language, allowing generic data structures
24984 and algorithms to be ``refined'' based on their properties rather than their
24987 The following keywords are reserved for concepts.
24991 States an expression as an assumption, and if possible, verifies that the
24992 assumption is valid. For example, @code{assume(n > 0)}.
24995 Introduces an axiom definition. Axioms introduce requirements on values.
24998 Introduces a universally quantified object in an axiom. For example,
24999 @code{forall (int n) n + 0 == n}).
25002 Introduces a concept definition. Concepts are sets of syntactic and semantic
25003 requirements on types and their values.
25006 Introduces constraints on template arguments or requirements for a member
25007 function of a class template.
25011 The front end also exposes a number of internal mechanism that can be used
25012 to simplify the writing of type traits. Note that some of these traits are
25013 likely to be removed in the future.
25016 @item __is_same (type1, type2)
25017 A binary type trait: @code{true} whenever the type arguments are the same.
25022 @node Deprecated Features
25023 @section Deprecated Features
25025 In the past, the GNU C++ compiler was extended to experiment with new
25026 features, at a time when the C++ language was still evolving. Now that
25027 the C++ standard is complete, some of those features are superseded by
25028 superior alternatives. Using the old features might cause a warning in
25029 some cases that the feature will be dropped in the future. In other
25030 cases, the feature might be gone already.
25032 G++ allows a virtual function returning @samp{void *} to be overridden
25033 by one returning a different pointer type. This extension to the
25034 covariant return type rules is now deprecated and will be removed from a
25037 The use of default arguments in function pointers, function typedefs
25038 and other places where they are not permitted by the standard is
25039 deprecated and will be removed from a future version of G++.
25041 G++ allows floating-point literals to appear in integral constant expressions,
25042 e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} }
25043 This extension is deprecated and will be removed from a future version.
25045 G++ allows static data members of const floating-point type to be declared
25046 with an initializer in a class definition. The standard only allows
25047 initializers for static members of const integral types and const
25048 enumeration types so this extension has been deprecated and will be removed
25049 from a future version.
25051 G++ allows attributes to follow a parenthesized direct initializer,
25052 e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension
25053 has been ignored since G++ 3.3 and is deprecated.
25055 G++ allows anonymous structs and unions to have members that are not
25056 public non-static data members (i.e.@: fields). These extensions are
25059 @node Backwards Compatibility
25060 @section Backwards Compatibility
25061 @cindex Backwards Compatibility
25062 @cindex ARM [Annotated C++ Reference Manual]
25064 Now that there is a definitive ISO standard C++, G++ has a specification
25065 to adhere to. The C++ language evolved over time, and features that
25066 used to be acceptable in previous drafts of the standard, such as the ARM
25067 [Annotated C++ Reference Manual], are no longer accepted. In order to allow
25068 compilation of C++ written to such drafts, G++ contains some backwards
25069 compatibilities. @emph{All such backwards compatibility features are
25070 liable to disappear in future versions of G++.} They should be considered
25071 deprecated. @xref{Deprecated Features}.
25075 @item Implicit C language
25076 Old C system header files did not contain an @code{extern "C" @{@dots{}@}}
25077 scope to set the language. On such systems, all system header files are
25078 implicitly scoped inside a C language scope. Such headers must
25079 correctly prototype function argument types, there is no leeway for
25080 @code{()} to indicate an unspecified set of arguments.
25084 @c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd
25085 @c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr