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 * Pointers to Arrays:: Pointers to arrays with qualifiers work as expected.
51 * Initializers:: Non-constant initializers.
52 * Compound Literals:: Compound literals give structures, unions
54 * Designated Inits:: Labeling elements of initializers.
55 * Case Ranges:: `case 1 ... 9' and such.
56 * Cast to Union:: Casting to union type from any member of the union.
57 * Mixed Declarations:: Mixing declarations and code.
58 * Function Attributes:: Declaring that functions have no side effects,
59 or that they can never return.
60 * Variable Attributes:: Specifying attributes of variables.
61 * Type Attributes:: Specifying attributes of types.
62 * Label Attributes:: Specifying attributes on labels.
63 * Enumerator Attributes:: Specifying attributes on enumerators.
64 * Statement Attributes:: Specifying attributes on statements.
65 * Attribute Syntax:: Formal syntax for attributes.
66 * Function Prototypes:: Prototype declarations and old-style definitions.
67 * C++ Comments:: C++ comments are recognized.
68 * Dollar Signs:: Dollar sign is allowed in identifiers.
69 * Character Escapes:: @samp{\e} stands for the character @key{ESC}.
70 * Alignment:: Determining the alignment of a function, type or variable.
71 * Inline:: Defining inline functions (as fast as macros).
72 * Volatiles:: What constitutes an access to a volatile object.
73 * Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler.
74 * Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
75 * Incomplete Enums:: @code{enum foo;}, with details to follow.
76 * Function Names:: Printable strings which are the name of the current
78 * Return Address:: Getting the return or frame address of a function.
79 * Vector Extensions:: Using vector instructions through built-in functions.
80 * Offsetof:: Special syntax for implementing @code{offsetof}.
81 * __sync Builtins:: Legacy built-in functions for atomic memory access.
82 * __atomic Builtins:: Atomic built-in functions with memory model.
83 * Integer Overflow Builtins:: Built-in functions to perform arithmetics and
84 arithmetic overflow checking.
85 * x86 specific memory model extensions for transactional memory:: x86 memory models.
86 * Object Size Checking:: Built-in functions for limited buffer overflow
88 * Other Builtins:: Other built-in functions.
89 * Target Builtins:: Built-in functions specific to particular targets.
90 * Target Format Checks:: Format checks specific to particular targets.
91 * Pragmas:: Pragmas accepted by GCC.
92 * Unnamed Fields:: Unnamed struct/union fields within structs/unions.
93 * Thread-Local:: Per-thread variables.
94 * Binary constants:: Binary constants using the @samp{0b} prefix.
98 @section Statements and Declarations in Expressions
99 @cindex statements inside expressions
100 @cindex declarations inside expressions
101 @cindex expressions containing statements
102 @cindex macros, statements in expressions
104 @c the above section title wrapped and causes an underfull hbox.. i
105 @c changed it from "within" to "in". --mew 4feb93
106 A compound statement enclosed in parentheses may appear as an expression
107 in GNU C@. This allows you to use loops, switches, and local variables
108 within an expression.
110 Recall that a compound statement is a sequence of statements surrounded
111 by braces; in this construct, parentheses go around the braces. For
115 (@{ int y = foo (); int z;
122 is a valid (though slightly more complex than necessary) expression
123 for the absolute value of @code{foo ()}.
125 The last thing in the compound statement should be an expression
126 followed by a semicolon; the value of this subexpression serves as the
127 value of the entire construct. (If you use some other kind of statement
128 last within the braces, the construct has type @code{void}, and thus
129 effectively no value.)
131 This feature is especially useful in making macro definitions ``safe'' (so
132 that they evaluate each operand exactly once). For example, the
133 ``maximum'' function is commonly defined as a macro in standard C as
137 #define max(a,b) ((a) > (b) ? (a) : (b))
141 @cindex side effects, macro argument
142 But this definition computes either @var{a} or @var{b} twice, with bad
143 results if the operand has side effects. In GNU C, if you know the
144 type of the operands (here taken as @code{int}), you can define
145 the macro safely as follows:
148 #define maxint(a,b) \
149 (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
152 Embedded statements are not allowed in constant expressions, such as
153 the value of an enumeration constant, the width of a bit-field, or
154 the initial value of a static variable.
156 If you don't know the type of the operand, you can still do this, but you
157 must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}).
159 In G++, the result value of a statement expression undergoes array and
160 function pointer decay, and is returned by value to the enclosing
161 expression. For instance, if @code{A} is a class, then
170 constructs a temporary @code{A} object to hold the result of the
171 statement expression, and that is used to invoke @code{Foo}.
172 Therefore the @code{this} pointer observed by @code{Foo} is not the
175 In a statement expression, any temporaries created within a statement
176 are destroyed at that statement's end. This makes statement
177 expressions inside macros slightly different from function calls. In
178 the latter case temporaries introduced during argument evaluation are
179 destroyed at the end of the statement that includes the function
180 call. In the statement expression case they are destroyed during
181 the statement expression. For instance,
184 #define macro(a) (@{__typeof__(a) b = (a); b + 3; @})
185 template<typename T> T function(T a) @{ T b = a; return b + 3; @}
195 has different places where temporaries are destroyed. For the
196 @code{macro} case, the temporary @code{X} is destroyed just after
197 the initialization of @code{b}. In the @code{function} case that
198 temporary is destroyed when the function returns.
200 These considerations mean that it is probably a bad idea to use
201 statement expressions of this form in header files that are designed to
202 work with C++. (Note that some versions of the GNU C Library contained
203 header files using statement expressions that lead to precisely this
206 Jumping into a statement expression with @code{goto} or using a
207 @code{switch} statement outside the statement expression with a
208 @code{case} or @code{default} label inside the statement expression is
209 not permitted. Jumping into a statement expression with a computed
210 @code{goto} (@pxref{Labels as Values}) has undefined behavior.
211 Jumping out of a statement expression is permitted, but if the
212 statement expression is part of a larger expression then it is
213 unspecified which other subexpressions of that expression have been
214 evaluated except where the language definition requires certain
215 subexpressions to be evaluated before or after the statement
216 expression. A @code{break} or @code{continue} statement inside of
217 a statement expression used in @code{while}, @code{do} or @code{for}
218 loop or @code{switch} statement condition
219 or @code{for} statement init or increment expressions jumps to an
220 outer loop or @code{switch} statement if any (otherwise it is an error),
221 rather than to the loop or @code{switch} statement in whose condition
222 or init or increment expression it appears.
223 In any case, as with a function call, the evaluation of a
224 statement expression is not interleaved with the evaluation of other
225 parts of the containing expression. For example,
228 foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz();
232 calls @code{foo} and @code{bar1} and does not call @code{baz} but
233 may or may not call @code{bar2}. If @code{bar2} is called, it is
234 called after @code{foo} and before @code{bar1}.
237 @section Locally Declared Labels
239 @cindex macros, local labels
241 GCC allows you to declare @dfn{local labels} in any nested block
242 scope. A local label is just like an ordinary label, but you can
243 only reference it (with a @code{goto} statement, or by taking its
244 address) within the block in which it is declared.
246 A local label declaration looks like this:
249 __label__ @var{label};
256 __label__ @var{label1}, @var{label2}, /* @r{@dots{}} */;
259 Local label declarations must come at the beginning of the block,
260 before any ordinary declarations or statements.
262 The label declaration defines the label @emph{name}, but does not define
263 the label itself. You must do this in the usual way, with
264 @code{@var{label}:}, within the statements of the statement expression.
266 The local label feature is useful for complex macros. If a macro
267 contains nested loops, a @code{goto} can be useful for breaking out of
268 them. However, an ordinary label whose scope is the whole function
269 cannot be used: if the macro can be expanded several times in one
270 function, the label is multiply defined in that function. A
271 local label avoids this problem. For example:
274 #define SEARCH(value, array, target) \
277 typeof (target) _SEARCH_target = (target); \
278 typeof (*(array)) *_SEARCH_array = (array); \
281 for (i = 0; i < max; i++) \
282 for (j = 0; j < max; j++) \
283 if (_SEARCH_array[i][j] == _SEARCH_target) \
284 @{ (value) = i; goto found; @} \
290 This could also be written using a statement expression:
293 #define SEARCH(array, target) \
296 typeof (target) _SEARCH_target = (target); \
297 typeof (*(array)) *_SEARCH_array = (array); \
300 for (i = 0; i < max; i++) \
301 for (j = 0; j < max; j++) \
302 if (_SEARCH_array[i][j] == _SEARCH_target) \
303 @{ value = i; goto found; @} \
310 Local label declarations also make the labels they declare visible to
311 nested functions, if there are any. @xref{Nested Functions}, for details.
313 @node Labels as Values
314 @section Labels as Values
315 @cindex labels as values
316 @cindex computed gotos
317 @cindex goto with computed label
318 @cindex address of a label
320 You can get the address of a label defined in the current function
321 (or a containing function) with the unary operator @samp{&&}. The
322 value has type @code{void *}. This value is a constant and can be used
323 wherever a constant of that type is valid. For example:
331 To use these values, you need to be able to jump to one. This is done
332 with the computed goto statement@footnote{The analogous feature in
333 Fortran is called an assigned goto, but that name seems inappropriate in
334 C, where one can do more than simply store label addresses in label
335 variables.}, @code{goto *@var{exp};}. For example,
342 Any expression of type @code{void *} is allowed.
344 One way of using these constants is in initializing a static array that
345 serves as a jump table:
348 static void *array[] = @{ &&foo, &&bar, &&hack @};
352 Then you can select a label with indexing, like this:
359 Note that this does not check whether the subscript is in bounds---array
360 indexing in C never does that.
362 Such an array of label values serves a purpose much like that of the
363 @code{switch} statement. The @code{switch} statement is cleaner, so
364 use that rather than an array unless the problem does not fit a
365 @code{switch} statement very well.
367 Another use of label values is in an interpreter for threaded code.
368 The labels within the interpreter function can be stored in the
369 threaded code for super-fast dispatching.
371 You may not use this mechanism to jump to code in a different function.
372 If you do that, totally unpredictable things happen. The best way to
373 avoid this is to store the label address only in automatic variables and
374 never pass it as an argument.
376 An alternate way to write the above example is
379 static const int array[] = @{ &&foo - &&foo, &&bar - &&foo,
381 goto *(&&foo + array[i]);
385 This is more friendly to code living in shared libraries, as it reduces
386 the number of dynamic relocations that are needed, and by consequence,
387 allows the data to be read-only.
388 This alternative with label differences is not supported for the AVR target,
389 please use the first approach for AVR programs.
391 The @code{&&foo} expressions for the same label might have different
392 values if the containing function is inlined or cloned. If a program
393 relies on them being always the same,
394 @code{__attribute__((__noinline__,__noclone__))} should be used to
395 prevent inlining and cloning. If @code{&&foo} is used in a static
396 variable initializer, inlining and cloning is forbidden.
398 @node Nested Functions
399 @section Nested Functions
400 @cindex nested functions
401 @cindex downward funargs
404 A @dfn{nested function} is a function defined inside another function.
405 Nested functions are supported as an extension in GNU C, but are not
406 supported by GNU C++.
408 The nested function's name is local to the block where it is defined.
409 For example, here we define a nested function named @code{square}, and
414 foo (double a, double b)
416 double square (double z) @{ return z * z; @}
418 return square (a) + square (b);
423 The nested function can access all the variables of the containing
424 function that are visible at the point of its definition. This is
425 called @dfn{lexical scoping}. For example, here we show a nested
426 function which uses an inherited variable named @code{offset}:
430 bar (int *array, int offset, int size)
432 int access (int *array, int index)
433 @{ return array[index + offset]; @}
436 for (i = 0; i < size; i++)
437 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
442 Nested function definitions are permitted within functions in the places
443 where variable definitions are allowed; that is, in any block, mixed
444 with the other declarations and statements in the block.
446 It is possible to call the nested function from outside the scope of its
447 name by storing its address or passing the address to another function:
450 hack (int *array, int size)
452 void store (int index, int value)
453 @{ array[index] = value; @}
455 intermediate (store, size);
459 Here, the function @code{intermediate} receives the address of
460 @code{store} as an argument. If @code{intermediate} calls @code{store},
461 the arguments given to @code{store} are used to store into @code{array}.
462 But this technique works only so long as the containing function
463 (@code{hack}, in this example) does not exit.
465 If you try to call the nested function through its address after the
466 containing function exits, all hell breaks loose. If you try
467 to call it after a containing scope level exits, and if it refers
468 to some of the variables that are no longer in scope, you may be lucky,
469 but it's not wise to take the risk. If, however, the nested function
470 does not refer to anything that has gone out of scope, you should be
473 GCC implements taking the address of a nested function using a technique
474 called @dfn{trampolines}. This technique was described in
475 @cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX
476 C++ Conference Proceedings, October 17-21, 1988).
478 A nested function can jump to a label inherited from a containing
479 function, provided the label is explicitly declared in the containing
480 function (@pxref{Local Labels}). Such a jump returns instantly to the
481 containing function, exiting the nested function that did the
482 @code{goto} and any intermediate functions as well. Here is an example:
486 bar (int *array, int offset, int size)
489 int access (int *array, int index)
493 return array[index + offset];
497 for (i = 0; i < size; i++)
498 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
502 /* @r{Control comes here from @code{access}
503 if it detects an error.} */
510 A nested function always has no linkage. Declaring one with
511 @code{extern} or @code{static} is erroneous. If you need to declare the nested function
512 before its definition, use @code{auto} (which is otherwise meaningless
513 for function declarations).
516 bar (int *array, int offset, int size)
519 auto int access (int *, int);
521 int access (int *array, int index)
525 return array[index + offset];
532 @section Nonlocal Gotos
533 @cindex nonlocal gotos
535 GCC provides the built-in functions @code{__builtin_setjmp} and
536 @code{__builtin_longjmp} which are similar to, but not interchangeable
537 with, the C library functions @code{setjmp} and @code{longjmp}.
538 The built-in versions are used internally by GCC's libraries
539 to implement exception handling on some targets. You should use the
540 standard C library functions declared in @code{<setjmp.h>} in user code
541 instead of the builtins.
543 The built-in versions of these functions use GCC's normal
544 mechanisms to save and restore registers using the stack on function
545 entry and exit. The jump buffer argument @var{buf} holds only the
546 information needed to restore the stack frame, rather than the entire
547 set of saved register values.
549 An important caveat is that GCC arranges to save and restore only
550 those registers known to the specific architecture variant being
551 compiled for. This can make @code{__builtin_setjmp} and
552 @code{__builtin_longjmp} more efficient than their library
553 counterparts in some cases, but it can also cause incorrect and
554 mysterious behavior when mixing with code that uses the full register
557 You should declare the jump buffer argument @var{buf} to the
558 built-in functions as:
562 intptr_t @var{buf}[5];
565 @deftypefn {Built-in Function} {int} __builtin_setjmp (intptr_t *@var{buf})
566 This function saves the current stack context in @var{buf}.
567 @code{__builtin_setjmp} returns 0 when returning directly,
568 and 1 when returning from @code{__builtin_longjmp} using the same
572 @deftypefn {Built-in Function} {void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val})
573 This function restores the stack context in @var{buf},
574 saved by a previous call to @code{__builtin_setjmp}. After
575 @code{__builtin_longjmp} is finished, the program resumes execution as
576 if the matching @code{__builtin_setjmp} returns the value @var{val},
579 Because @code{__builtin_longjmp} depends on the function return
580 mechanism to restore the stack context, it cannot be called
581 from the same function calling @code{__builtin_setjmp} to
582 initialize @var{buf}. It can only be called from a function called
583 (directly or indirectly) from the function calling @code{__builtin_setjmp}.
586 @node Constructing Calls
587 @section Constructing Function Calls
588 @cindex constructing calls
589 @cindex forwarding calls
591 Using the built-in functions described below, you can record
592 the arguments a function received, and call another function
593 with the same arguments, without knowing the number or types
596 You can also record the return value of that function call,
597 and later return that value, without knowing what data type
598 the function tried to return (as long as your caller expects
601 However, these built-in functions may interact badly with some
602 sophisticated features or other extensions of the language. It
603 is, therefore, not recommended to use them outside very simple
604 functions acting as mere forwarders for their arguments.
606 @deftypefn {Built-in Function} {void *} __builtin_apply_args ()
607 This built-in function returns a pointer to data
608 describing how to perform a call with the same arguments as are passed
609 to the current function.
611 The function saves the arg pointer register, structure value address,
612 and all registers that might be used to pass arguments to a function
613 into a block of memory allocated on the stack. Then it returns the
614 address of that block.
617 @deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})
618 This built-in function invokes @var{function}
619 with a copy of the parameters described by @var{arguments}
622 The value of @var{arguments} should be the value returned by
623 @code{__builtin_apply_args}. The argument @var{size} specifies the size
624 of the stack argument data, in bytes.
626 This function returns a pointer to data describing
627 how to return whatever value is returned by @var{function}. The data
628 is saved in a block of memory allocated on the stack.
630 It is not always simple to compute the proper value for @var{size}. The
631 value is used by @code{__builtin_apply} to compute the amount of data
632 that should be pushed on the stack and copied from the incoming argument
636 @deftypefn {Built-in Function} {void} __builtin_return (void *@var{result})
637 This built-in function returns the value described by @var{result} from
638 the containing function. You should specify, for @var{result}, a value
639 returned by @code{__builtin_apply}.
642 @deftypefn {Built-in Function} {} __builtin_va_arg_pack ()
643 This built-in function represents all anonymous arguments of an inline
644 function. It can be used only in inline functions that are always
645 inlined, never compiled as a separate function, such as those using
646 @code{__attribute__ ((__always_inline__))} or
647 @code{__attribute__ ((__gnu_inline__))} extern inline functions.
648 It must be only passed as last argument to some other function
649 with variable arguments. This is useful for writing small wrapper
650 inlines for variable argument functions, when using preprocessor
651 macros is undesirable. For example:
653 extern int myprintf (FILE *f, const char *format, ...);
654 extern inline __attribute__ ((__gnu_inline__)) int
655 myprintf (FILE *f, const char *format, ...)
657 int r = fprintf (f, "myprintf: ");
660 int s = fprintf (f, format, __builtin_va_arg_pack ());
668 @deftypefn {Built-in Function} {size_t} __builtin_va_arg_pack_len ()
669 This built-in function returns the number of anonymous arguments of
670 an inline function. It can be used only in inline functions that
671 are always inlined, never compiled as a separate function, such
672 as those using @code{__attribute__ ((__always_inline__))} or
673 @code{__attribute__ ((__gnu_inline__))} extern inline functions.
674 For example following does link- or run-time checking of open
675 arguments for optimized code:
678 extern inline __attribute__((__gnu_inline__)) int
679 myopen (const char *path, int oflag, ...)
681 if (__builtin_va_arg_pack_len () > 1)
682 warn_open_too_many_arguments ();
684 if (__builtin_constant_p (oflag))
686 if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1)
688 warn_open_missing_mode ();
689 return __open_2 (path, oflag);
691 return open (path, oflag, __builtin_va_arg_pack ());
694 if (__builtin_va_arg_pack_len () < 1)
695 return __open_2 (path, oflag);
697 return open (path, oflag, __builtin_va_arg_pack ());
704 @section Referring to a Type with @code{typeof}
707 @cindex macros, types of arguments
709 Another way to refer to the type of an expression is with @code{typeof}.
710 The syntax of using of this keyword looks like @code{sizeof}, but the
711 construct acts semantically like a type name defined with @code{typedef}.
713 There are two ways of writing the argument to @code{typeof}: with an
714 expression or with a type. Here is an example with an expression:
721 This assumes that @code{x} is an array of pointers to functions;
722 the type described is that of the values of the functions.
724 Here is an example with a typename as the argument:
731 Here the type described is that of pointers to @code{int}.
733 If you are writing a header file that must work when included in ISO C
734 programs, write @code{__typeof__} instead of @code{typeof}.
735 @xref{Alternate Keywords}.
737 A @code{typeof} construct can be used anywhere a typedef name can be
738 used. For example, you can use it in a declaration, in a cast, or inside
739 of @code{sizeof} or @code{typeof}.
741 The operand of @code{typeof} is evaluated for its side effects if and
742 only if it is an expression of variably modified type or the name of
745 @code{typeof} is often useful in conjunction with
746 statement expressions (@pxref{Statement Exprs}).
747 Here is how the two together can
748 be used to define a safe ``maximum'' macro which operates on any
749 arithmetic type and evaluates each of its arguments exactly once:
753 (@{ typeof (a) _a = (a); \
754 typeof (b) _b = (b); \
755 _a > _b ? _a : _b; @})
758 @cindex underscores in variables in macros
759 @cindex @samp{_} in variables in macros
760 @cindex local variables in macros
761 @cindex variables, local, in macros
762 @cindex macros, local variables in
764 The reason for using names that start with underscores for the local
765 variables is to avoid conflicts with variable names that occur within the
766 expressions that are substituted for @code{a} and @code{b}. Eventually we
767 hope to design a new form of declaration syntax that allows you to declare
768 variables whose scopes start only after their initializers; this will be a
769 more reliable way to prevent such conflicts.
772 Some more examples of the use of @code{typeof}:
776 This declares @code{y} with the type of what @code{x} points to.
783 This declares @code{y} as an array of such values.
790 This declares @code{y} as an array of pointers to characters:
793 typeof (typeof (char *)[4]) y;
797 It is equivalent to the following traditional C declaration:
803 To see the meaning of the declaration using @code{typeof}, and why it
804 might be a useful way to write, rewrite it with these macros:
807 #define pointer(T) typeof(T *)
808 #define array(T, N) typeof(T [N])
812 Now the declaration can be rewritten this way:
815 array (pointer (char), 4) y;
819 Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
820 pointers to @code{char}.
823 In GNU C, but not GNU C++, you may also declare the type of a variable
824 as @code{__auto_type}. In that case, the declaration must declare
825 only one variable, whose declarator must just be an identifier, the
826 declaration must be initialized, and the type of the variable is
827 determined by the initializer; the name of the variable is not in
828 scope until after the initializer. (In C++, you should use C++11
829 @code{auto} for this purpose.) Using @code{__auto_type}, the
830 ``maximum'' macro above could be written as:
834 (@{ __auto_type _a = (a); \
835 __auto_type _b = (b); \
836 _a > _b ? _a : _b; @})
839 Using @code{__auto_type} instead of @code{typeof} has two advantages:
842 @item Each argument to the macro appears only once in the expansion of
843 the macro. This prevents the size of the macro expansion growing
844 exponentially when calls to such macros are nested inside arguments of
847 @item If the argument to the macro has variably modified type, it is
848 evaluated only once when using @code{__auto_type}, but twice if
849 @code{typeof} is used.
853 @section Conditionals with Omitted Operands
854 @cindex conditional expressions, extensions
855 @cindex omitted middle-operands
856 @cindex middle-operands, omitted
857 @cindex extensions, @code{?:}
858 @cindex @code{?:} extensions
860 The middle operand in a conditional expression may be omitted. Then
861 if the first operand is nonzero, its value is the value of the conditional
864 Therefore, the expression
871 has the value of @code{x} if that is nonzero; otherwise, the value of
874 This example is perfectly equivalent to
880 @cindex side effect in @code{?:}
881 @cindex @code{?:} side effect
883 In this simple case, the ability to omit the middle operand is not
884 especially useful. When it becomes useful is when the first operand does,
885 or may (if it is a macro argument), contain a side effect. Then repeating
886 the operand in the middle would perform the side effect twice. Omitting
887 the middle operand uses the value already computed without the undesirable
888 effects of recomputing it.
891 @section 128-bit Integers
892 @cindex @code{__int128} data types
894 As an extension the integer scalar type @code{__int128} is supported for
895 targets which have an integer mode wide enough to hold 128 bits.
896 Simply write @code{__int128} for a signed 128-bit integer, or
897 @code{unsigned __int128} for an unsigned 128-bit integer. There is no
898 support in GCC for expressing an integer constant of type @code{__int128}
899 for targets with @code{long long} integer less than 128 bits wide.
902 @section Double-Word Integers
903 @cindex @code{long long} data types
904 @cindex double-word arithmetic
905 @cindex multiprecision arithmetic
906 @cindex @code{LL} integer suffix
907 @cindex @code{ULL} integer suffix
909 ISO C99 and ISO C++11 support data types for integers that are at least
910 64 bits wide, and as an extension GCC supports them in C90 and C++98 modes.
911 Simply write @code{long long int} for a signed integer, or
912 @code{unsigned long long int} for an unsigned integer. To make an
913 integer constant of type @code{long long int}, add the suffix @samp{LL}
914 to the integer. To make an integer constant of type @code{unsigned long
915 long int}, add the suffix @samp{ULL} to the integer.
917 You can use these types in arithmetic like any other integer types.
918 Addition, subtraction, and bitwise boolean operations on these types
919 are open-coded on all types of machines. Multiplication is open-coded
920 if the machine supports a fullword-to-doubleword widening multiply
921 instruction. Division and shifts are open-coded only on machines that
922 provide special support. The operations that are not open-coded use
923 special library routines that come with GCC@.
925 There may be pitfalls when you use @code{long long} types for function
926 arguments without function prototypes. If a function
927 expects type @code{int} for its argument, and you pass a value of type
928 @code{long long int}, confusion results because the caller and the
929 subroutine disagree about the number of bytes for the argument.
930 Likewise, if the function expects @code{long long int} and you pass
931 @code{int}. The best way to avoid such problems is to use prototypes.
934 @section Complex Numbers
935 @cindex complex numbers
936 @cindex @code{_Complex} keyword
937 @cindex @code{__complex__} keyword
939 ISO C99 supports complex floating data types, and as an extension GCC
940 supports them in C90 mode and in C++. GCC also supports complex integer data
941 types which are not part of ISO C99. You can declare complex types
942 using the keyword @code{_Complex}. As an extension, the older GNU
943 keyword @code{__complex__} is also supported.
945 For example, @samp{_Complex double x;} declares @code{x} as a
946 variable whose real part and imaginary part are both of type
947 @code{double}. @samp{_Complex short int y;} declares @code{y} to
948 have real and imaginary parts of type @code{short int}; this is not
949 likely to be useful, but it shows that the set of complex types is
952 To write a constant with a complex data type, use the suffix @samp{i} or
953 @samp{j} (either one; they are equivalent). For example, @code{2.5fi}
954 has type @code{_Complex float} and @code{3i} has type
955 @code{_Complex int}. Such a constant always has a pure imaginary
956 value, but you can form any complex value you like by adding one to a
957 real constant. This is a GNU extension; if you have an ISO C99
958 conforming C library (such as the GNU C Library), and want to construct complex
959 constants of floating type, you should include @code{<complex.h>} and
960 use the macros @code{I} or @code{_Complex_I} instead.
962 The ISO C++14 library also defines the @samp{i} suffix, so C++14 code
963 that includes the @samp{<complex>} header cannot use @samp{i} for the
964 GNU extension. The @samp{j} suffix still has the GNU meaning.
966 @cindex @code{__real__} keyword
967 @cindex @code{__imag__} keyword
968 To extract the real part of a complex-valued expression @var{exp}, write
969 @code{__real__ @var{exp}}. Likewise, use @code{__imag__} to
970 extract the imaginary part. This is a GNU extension; for values of
971 floating type, you should use the ISO C99 functions @code{crealf},
972 @code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and
973 @code{cimagl}, declared in @code{<complex.h>} and also provided as
974 built-in functions by GCC@.
976 @cindex complex conjugation
977 The operator @samp{~} performs complex conjugation when used on a value
978 with a complex type. This is a GNU extension; for values of
979 floating type, you should use the ISO C99 functions @code{conjf},
980 @code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
981 provided as built-in functions by GCC@.
983 GCC can allocate complex automatic variables in a noncontiguous
984 fashion; it's even possible for the real part to be in a register while
985 the imaginary part is on the stack (or vice versa). Only the DWARF
986 debug info format can represent this, so use of DWARF is recommended.
987 If you are using the stabs debug info format, GCC describes a noncontiguous
988 complex variable as if it were two separate variables of noncomplex type.
989 If the variable's actual name is @code{foo}, the two fictitious
990 variables are named @code{foo$real} and @code{foo$imag}. You can
991 examine and set these two fictitious variables with your debugger.
994 @section Additional Floating Types
995 @cindex additional floating types
996 @cindex @code{_Float@var{n}} data types
997 @cindex @code{_Float@var{n}x} data types
998 @cindex @code{__float80} data type
999 @cindex @code{__float128} data type
1000 @cindex @code{__ibm128} data type
1001 @cindex @code{w} floating point suffix
1002 @cindex @code{q} floating point suffix
1003 @cindex @code{W} floating point suffix
1004 @cindex @code{Q} floating point suffix
1006 ISO/IEC TS 18661-3:2015 defines C support for additional floating
1007 types @code{_Float@var{n}} and @code{_Float@var{n}x}, and GCC supports
1008 these type names; the set of types supported depends on the target
1009 architecture. These types are not supported when compiling C++.
1010 Constants with these types use suffixes @code{f@var{n}} or
1011 @code{F@var{n}} and @code{f@var{n}x} or @code{F@var{n}x}. These type
1012 names can be used together with @code{_Complex} to declare complex
1015 As an extension, GNU C and GNU C++ support additional floating
1016 types, which are not supported by all targets.
1018 @item @code{__float128} is available on i386, x86_64, IA-64, and
1019 hppa HP-UX, as well as on PowerPC GNU/Linux targets that enable
1020 the vector scalar (VSX) instruction set. @code{__float128} supports
1021 the 128-bit floating type. On i386, x86_64, PowerPC, and IA-64
1022 other than HP-UX, @code{__float128} is an alias for @code{_Float128}.
1023 On hppa and IA-64 HP-UX, @code{__float128} is an alias for @code{long
1026 @item @code{__float80} is available on the i386, x86_64, and IA-64
1027 targets, and supports the 80-bit (@code{XFmode}) floating type. It is
1028 an alias for the type name @code{_Float64x} on these targets.
1030 @item @code{__ibm128} is available on PowerPC targets, and provides
1031 access to the IBM extended double format which is the current format
1032 used for @code{long double}. When @code{long double} transitions to
1033 @code{__float128} on PowerPC in the future, @code{__ibm128} will remain
1034 for use in conversions between the two types.
1037 Support for these additional types includes the arithmetic operators:
1038 add, subtract, multiply, divide; unary arithmetic operators;
1039 relational operators; equality operators; and conversions to and from
1040 integer and other floating types. Use a suffix @samp{w} or @samp{W}
1041 in a literal constant of type @code{__float80} or type
1042 @code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{_float128}.
1044 In order to use @code{_Float128}, @code{__float128}, and @code{__ibm128}
1045 on PowerPC Linux systems, you must use the @option{-mfloat128} option. It is
1046 expected in future versions of GCC that @code{_Float128} and @code{__float128}
1047 will be enabled automatically.
1049 The @code{_Float128} type is supported on all systems where
1050 @code{__float128} is supported or where @code{long double} has the
1051 IEEE binary128 format. The @code{_Float64x} type is supported on all
1052 systems where @code{__float128} is supported. The @code{_Float32}
1053 type is supported on all systems supporting IEEE binary32; the
1054 @code{_Float64} and @code{_Float32x} types are supported on all systems
1055 supporting IEEE binary64. The @code{_Float16} type is supported on AArch64
1056 systems by default, and on ARM systems when the IEEE format for 16-bit
1057 floating-point types is selected with @option{-mfp16-format=ieee}.
1058 GCC does not currently support @code{_Float128x} on any systems.
1060 On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex
1061 types using the corresponding internal complex type, @code{XCmode} for
1062 @code{__float80} type and @code{TCmode} for @code{__float128} type:
1065 typedef _Complex float __attribute__((mode(TC))) _Complex128;
1066 typedef _Complex float __attribute__((mode(XC))) _Complex80;
1069 On the PowerPC Linux VSX targets, you can declare complex types using
1070 the corresponding internal complex type, @code{KCmode} for
1071 @code{__float128} type and @code{ICmode} for @code{__ibm128} type:
1074 typedef _Complex float __attribute__((mode(KC))) _Complex_float128;
1075 typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128;
1078 @node Half-Precision
1079 @section Half-Precision Floating Point
1080 @cindex half-precision floating point
1081 @cindex @code{__fp16} data type
1083 On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating
1084 point via the @code{__fp16} type defined in the ARM C Language Extensions.
1085 On ARM systems, you must enable this type explicitly with the
1086 @option{-mfp16-format} command-line option in order to use it.
1088 ARM targets support two incompatible representations for half-precision
1089 floating-point values. You must choose one of the representations and
1090 use it consistently in your program.
1092 Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format.
1093 This format can represent normalized values in the range of @math{2^{-14}} to 65504.
1094 There are 11 bits of significand precision, approximately 3
1097 Specifying @option{-mfp16-format=alternative} selects the ARM
1098 alternative format. This representation is similar to the IEEE
1099 format, but does not support infinities or NaNs. Instead, the range
1100 of exponents is extended, so that this format can represent normalized
1101 values in the range of @math{2^{-14}} to 131008.
1103 The GCC port for AArch64 only supports the IEEE 754-2008 format, and does
1104 not require use of the @option{-mfp16-format} command-line option.
1106 The @code{__fp16} type may only be used as an argument to intrinsics defined
1107 in @code{<arm_fp16.h>}, or as a storage format. For purposes of
1108 arithmetic and other operations, @code{__fp16} values in C or C++
1109 expressions are automatically promoted to @code{float}.
1111 The ARM target provides hardware support for conversions between
1112 @code{__fp16} and @code{float} values
1113 as an extension to VFP and NEON (Advanced SIMD), and from ARMv8-A provides
1114 hardware support for conversions between @code{__fp16} and @code{double}
1115 values. GCC generates code using these hardware instructions if you
1116 compile with options to select an FPU that provides them;
1117 for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp},
1118 in addition to the @option{-mfp16-format} option to select
1119 a half-precision format.
1121 Language-level support for the @code{__fp16} data type is
1122 independent of whether GCC generates code using hardware floating-point
1123 instructions. In cases where hardware support is not specified, GCC
1124 implements conversions between @code{__fp16} and other types as library
1127 It is recommended that portable code use the @code{_Float16} type defined
1128 by ISO/IEC TS 18661-3:2015. @xref{Floating Types}.
1131 @section Decimal Floating Types
1132 @cindex decimal floating types
1133 @cindex @code{_Decimal32} data type
1134 @cindex @code{_Decimal64} data type
1135 @cindex @code{_Decimal128} data type
1136 @cindex @code{df} integer suffix
1137 @cindex @code{dd} integer suffix
1138 @cindex @code{dl} integer suffix
1139 @cindex @code{DF} integer suffix
1140 @cindex @code{DD} integer suffix
1141 @cindex @code{DL} integer suffix
1143 As an extension, GNU C supports decimal floating types as
1144 defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal
1145 floating types in GCC will evolve as the draft technical report changes.
1146 Calling conventions for any target might also change. Not all targets
1147 support decimal floating types.
1149 The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and
1150 @code{_Decimal128}. They use a radix of ten, unlike the floating types
1151 @code{float}, @code{double}, and @code{long double} whose radix is not
1152 specified by the C standard but is usually two.
1154 Support for decimal floating types includes the arithmetic operators
1155 add, subtract, multiply, divide; unary arithmetic operators;
1156 relational operators; equality operators; and conversions to and from
1157 integer and other floating types. Use a suffix @samp{df} or
1158 @samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
1159 or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
1162 GCC support of decimal float as specified by the draft technical report
1167 When the value of a decimal floating type cannot be represented in the
1168 integer type to which it is being converted, the result is undefined
1169 rather than the result value specified by the draft technical report.
1172 GCC does not provide the C library functionality associated with
1173 @file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and
1174 @file{wchar.h}, which must come from a separate C library implementation.
1175 Because of this the GNU C compiler does not define macro
1176 @code{__STDC_DEC_FP__} to indicate that the implementation conforms to
1177 the technical report.
1180 Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
1181 are supported by the DWARF debug information format.
1187 ISO C99 and ISO C++17 support floating-point numbers written not only in
1188 the usual decimal notation, such as @code{1.55e1}, but also numbers such as
1189 @code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC
1190 supports this in C90 mode (except in some cases when strictly
1191 conforming) and in C++98, C++11 and C++14 modes. In that format the
1192 @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
1193 mandatory. The exponent is a decimal number that indicates the power of
1194 2 by which the significant part is multiplied. Thus @samp{0x1.f} is
1201 @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
1202 is the same as @code{1.55e1}.
1204 Unlike for floating-point numbers in the decimal notation the exponent
1205 is always required in the hexadecimal notation. Otherwise the compiler
1206 would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This
1207 could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
1208 extension for floating-point constants of type @code{float}.
1211 @section Fixed-Point Types
1212 @cindex fixed-point types
1213 @cindex @code{_Fract} data type
1214 @cindex @code{_Accum} data type
1215 @cindex @code{_Sat} data type
1216 @cindex @code{hr} fixed-suffix
1217 @cindex @code{r} fixed-suffix
1218 @cindex @code{lr} fixed-suffix
1219 @cindex @code{llr} fixed-suffix
1220 @cindex @code{uhr} fixed-suffix
1221 @cindex @code{ur} fixed-suffix
1222 @cindex @code{ulr} fixed-suffix
1223 @cindex @code{ullr} fixed-suffix
1224 @cindex @code{hk} fixed-suffix
1225 @cindex @code{k} fixed-suffix
1226 @cindex @code{lk} fixed-suffix
1227 @cindex @code{llk} fixed-suffix
1228 @cindex @code{uhk} fixed-suffix
1229 @cindex @code{uk} fixed-suffix
1230 @cindex @code{ulk} fixed-suffix
1231 @cindex @code{ullk} fixed-suffix
1232 @cindex @code{HR} fixed-suffix
1233 @cindex @code{R} fixed-suffix
1234 @cindex @code{LR} fixed-suffix
1235 @cindex @code{LLR} fixed-suffix
1236 @cindex @code{UHR} fixed-suffix
1237 @cindex @code{UR} fixed-suffix
1238 @cindex @code{ULR} fixed-suffix
1239 @cindex @code{ULLR} fixed-suffix
1240 @cindex @code{HK} fixed-suffix
1241 @cindex @code{K} fixed-suffix
1242 @cindex @code{LK} fixed-suffix
1243 @cindex @code{LLK} fixed-suffix
1244 @cindex @code{UHK} fixed-suffix
1245 @cindex @code{UK} fixed-suffix
1246 @cindex @code{ULK} fixed-suffix
1247 @cindex @code{ULLK} fixed-suffix
1249 As an extension, GNU C supports fixed-point types as
1250 defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point
1251 types in GCC will evolve as the draft technical report changes.
1252 Calling conventions for any target might also change. Not all targets
1253 support fixed-point types.
1255 The fixed-point types are
1256 @code{short _Fract},
1259 @code{long long _Fract},
1260 @code{unsigned short _Fract},
1261 @code{unsigned _Fract},
1262 @code{unsigned long _Fract},
1263 @code{unsigned long long _Fract},
1264 @code{_Sat short _Fract},
1266 @code{_Sat long _Fract},
1267 @code{_Sat long long _Fract},
1268 @code{_Sat unsigned short _Fract},
1269 @code{_Sat unsigned _Fract},
1270 @code{_Sat unsigned long _Fract},
1271 @code{_Sat unsigned long long _Fract},
1272 @code{short _Accum},
1275 @code{long long _Accum},
1276 @code{unsigned short _Accum},
1277 @code{unsigned _Accum},
1278 @code{unsigned long _Accum},
1279 @code{unsigned long long _Accum},
1280 @code{_Sat short _Accum},
1282 @code{_Sat long _Accum},
1283 @code{_Sat long long _Accum},
1284 @code{_Sat unsigned short _Accum},
1285 @code{_Sat unsigned _Accum},
1286 @code{_Sat unsigned long _Accum},
1287 @code{_Sat unsigned long long _Accum}.
1289 Fixed-point data values contain fractional and optional integral parts.
1290 The format of fixed-point data varies and depends on the target machine.
1292 Support for fixed-point types includes:
1295 prefix and postfix increment and decrement operators (@code{++}, @code{--})
1297 unary arithmetic operators (@code{+}, @code{-}, @code{!})
1299 binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/})
1301 binary shift operators (@code{<<}, @code{>>})
1303 relational operators (@code{<}, @code{<=}, @code{>=}, @code{>})
1305 equality operators (@code{==}, @code{!=})
1307 assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=},
1308 @code{<<=}, @code{>>=})
1310 conversions to and from integer, floating-point, or fixed-point types
1313 Use a suffix in a fixed-point literal constant:
1315 @item @samp{hr} or @samp{HR} for @code{short _Fract} and
1316 @code{_Sat short _Fract}
1317 @item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract}
1318 @item @samp{lr} or @samp{LR} for @code{long _Fract} and
1319 @code{_Sat long _Fract}
1320 @item @samp{llr} or @samp{LLR} for @code{long long _Fract} and
1321 @code{_Sat long long _Fract}
1322 @item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and
1323 @code{_Sat unsigned short _Fract}
1324 @item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and
1325 @code{_Sat unsigned _Fract}
1326 @item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and
1327 @code{_Sat unsigned long _Fract}
1328 @item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract}
1329 and @code{_Sat unsigned long long _Fract}
1330 @item @samp{hk} or @samp{HK} for @code{short _Accum} and
1331 @code{_Sat short _Accum}
1332 @item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum}
1333 @item @samp{lk} or @samp{LK} for @code{long _Accum} and
1334 @code{_Sat long _Accum}
1335 @item @samp{llk} or @samp{LLK} for @code{long long _Accum} and
1336 @code{_Sat long long _Accum}
1337 @item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and
1338 @code{_Sat unsigned short _Accum}
1339 @item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and
1340 @code{_Sat unsigned _Accum}
1341 @item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and
1342 @code{_Sat unsigned long _Accum}
1343 @item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum}
1344 and @code{_Sat unsigned long long _Accum}
1347 GCC support of fixed-point types as specified by the draft technical report
1352 Pragmas to control overflow and rounding behaviors are not implemented.
1355 Fixed-point types are supported by the DWARF debug information format.
1357 @node Named Address Spaces
1358 @section Named Address Spaces
1359 @cindex Named Address Spaces
1361 As an extension, GNU C supports named address spaces as
1362 defined in the N1275 draft of ISO/IEC DTR 18037. Support for named
1363 address spaces in GCC will evolve as the draft technical report
1364 changes. Calling conventions for any target might also change. At
1365 present, only the AVR, SPU, M32C, RL78, and x86 targets support
1366 address spaces other than the generic address space.
1368 Address space identifiers may be used exactly like any other C type
1369 qualifier (e.g., @code{const} or @code{volatile}). See the N1275
1370 document for more details.
1372 @anchor{AVR Named Address Spaces}
1373 @subsection AVR Named Address Spaces
1375 On the AVR target, there are several address spaces that can be used
1376 in order to put read-only data into the flash memory and access that
1377 data by means of the special instructions @code{LPM} or @code{ELPM}
1378 needed to read from flash.
1380 Devices belonging to @code{avrtiny} and @code{avrxmega3} can access
1381 flash memory by means of @code{LD*} instructions because the flash
1382 memory is mapped into the RAM address space. There is @emph{no need}
1383 for language extensions like @code{__flash} or attribute
1384 @ref{AVR Variable Attributes,,@code{progmem}}.
1385 The default linker description files for these devices cater for that
1386 feature and @code{.rodata} stays in flash: The compiler just generates
1387 @code{LD*} instructions, and the linker script adds core specific
1388 offsets to all @code{.rodata} symbols: @code{0x4000} in the case of
1389 @code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}.
1390 See @ref{AVR Options} for a list of respective devices.
1392 For devices not in @code{avrtiny} or @code{avrxmega3},
1393 any data including read-only data is located in RAM (the generic
1394 address space) because flash memory is not visible in the RAM address
1395 space. In order to locate read-only data in flash memory @emph{and}
1396 to generate the right instructions to access this data without
1397 using (inline) assembler code, special address spaces are needed.
1401 @cindex @code{__flash} AVR Named Address Spaces
1402 The @code{__flash} qualifier locates data in the
1403 @code{.progmem.data} section. Data is read using the @code{LPM}
1404 instruction. Pointers to this address space are 16 bits wide.
1411 @cindex @code{__flash1} AVR Named Address Spaces
1412 @cindex @code{__flash2} AVR Named Address Spaces
1413 @cindex @code{__flash3} AVR Named Address Spaces
1414 @cindex @code{__flash4} AVR Named Address Spaces
1415 @cindex @code{__flash5} AVR Named Address Spaces
1416 These are 16-bit address spaces locating data in section
1417 @code{.progmem@var{N}.data} where @var{N} refers to
1418 address space @code{__flash@var{N}}.
1419 The compiler sets the @code{RAMPZ} segment register appropriately
1420 before reading data by means of the @code{ELPM} instruction.
1423 @cindex @code{__memx} AVR Named Address Spaces
1424 This is a 24-bit address space that linearizes flash and RAM:
1425 If the high bit of the address is set, data is read from
1426 RAM using the lower two bytes as RAM address.
1427 If the high bit of the address is clear, data is read from flash
1428 with @code{RAMPZ} set according to the high byte of the address.
1429 @xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}.
1431 Objects in this address space are located in @code{.progmemx.data}.
1437 char my_read (const __flash char ** p)
1439 /* p is a pointer to RAM that points to a pointer to flash.
1440 The first indirection of p reads that flash pointer
1441 from RAM and the second indirection reads a char from this
1447 /* Locate array[] in flash memory */
1448 const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @};
1454 /* Return 17 by reading from flash memory */
1455 return array[array[i]];
1460 For each named address space supported by avr-gcc there is an equally
1461 named but uppercase built-in macro defined.
1462 The purpose is to facilitate testing if respective address space
1463 support is available or not:
1467 const __flash int var = 1;
1474 #include <avr/pgmspace.h> /* From AVR-LibC */
1476 const int var PROGMEM = 1;
1480 return (int) pgm_read_word (&var);
1482 #endif /* __FLASH */
1486 Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}}
1487 locates data in flash but
1488 accesses to these data read from generic address space, i.e.@:
1490 so that you need special accessors like @code{pgm_read_byte}
1491 from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}}
1492 together with attribute @code{progmem}.
1495 @b{Limitations and caveats}
1499 Reading across the 64@tie{}KiB section boundary of
1500 the @code{__flash} or @code{__flash@var{N}} address spaces
1501 shows undefined behavior. The only address space that
1502 supports reading across the 64@tie{}KiB flash segment boundaries is
1506 If you use one of the @code{__flash@var{N}} address spaces
1507 you must arrange your linker script to locate the
1508 @code{.progmem@var{N}.data} sections according to your needs.
1511 Any data or pointers to the non-generic address spaces must
1512 be qualified as @code{const}, i.e.@: as read-only data.
1513 This still applies if the data in one of these address
1514 spaces like software version number or calibration lookup table are intended to
1515 be changed after load time by, say, a boot loader. In this case
1516 the right qualification is @code{const} @code{volatile} so that the compiler
1517 must not optimize away known values or insert them
1518 as immediates into operands of instructions.
1521 The following code initializes a variable @code{pfoo}
1522 located in static storage with a 24-bit address:
1524 extern const __memx char foo;
1525 const __memx void *pfoo = &foo;
1529 On the reduced Tiny devices like ATtiny40, no address spaces are supported.
1530 Just use vanilla C / C++ code without overhead as outlined above.
1531 Attribute @code{progmem} is supported but works differently,
1532 see @ref{AVR Variable Attributes}.
1536 @subsection M32C Named Address Spaces
1537 @cindex @code{__far} M32C Named Address Spaces
1539 On the M32C target, with the R8C and M16C CPU variants, variables
1540 qualified with @code{__far} are accessed using 32-bit addresses in
1541 order to access memory beyond the first 64@tie{}Ki bytes. If
1542 @code{__far} is used with the M32CM or M32C CPU variants, it has no
1545 @subsection RL78 Named Address Spaces
1546 @cindex @code{__far} RL78 Named Address Spaces
1548 On the RL78 target, variables qualified with @code{__far} are accessed
1549 with 32-bit pointers (20-bit addresses) rather than the default 16-bit
1550 addresses. Non-far variables are assumed to appear in the topmost
1551 64@tie{}KiB of the address space.
1553 @subsection SPU Named Address Spaces
1554 @cindex @code{__ea} SPU Named Address Spaces
1556 On the SPU target variables may be declared as
1557 belonging to another address space by qualifying the type with the
1558 @code{__ea} address space identifier:
1565 The compiler generates special code to access the variable @code{i}.
1566 It may use runtime library
1567 support, or generate special machine instructions to access that address
1570 @subsection x86 Named Address Spaces
1571 @cindex x86 named address spaces
1573 On the x86 target, variables may be declared as being relative
1574 to the @code{%fs} or @code{%gs} segments.
1579 @cindex @code{__seg_fs} x86 named address space
1580 @cindex @code{__seg_gs} x86 named address space
1581 The object is accessed with the respective segment override prefix.
1583 The respective segment base must be set via some method specific to
1584 the operating system. Rather than require an expensive system call
1585 to retrieve the segment base, these address spaces are not considered
1586 to be subspaces of the generic (flat) address space. This means that
1587 explicit casts are required to convert pointers between these address
1588 spaces and the generic address space. In practice the application
1589 should cast to @code{uintptr_t} and apply the segment base offset
1590 that it installed previously.
1592 The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are
1593 defined when these address spaces are supported.
1597 @section Arrays of Length Zero
1598 @cindex arrays of length zero
1599 @cindex zero-length arrays
1600 @cindex length-zero arrays
1601 @cindex flexible array members
1603 Declaring zero-length arrays is allowed in GNU C as an extension.
1604 A zero-length array can be useful as the last element of a structure
1605 that is really a header for a variable-length object:
1613 struct line *thisline = (struct line *)
1614 malloc (sizeof (struct line) + this_length);
1615 thisline->length = this_length;
1618 Although the size of a zero-length array is zero, an array member of
1619 this kind may increase the size of the enclosing type as a result of tail
1620 padding. The offset of a zero-length array member from the beginning
1621 of the enclosing structure is the same as the offset of an array with
1622 one or more elements of the same type. The alignment of a zero-length
1623 array is the same as the alignment of its elements.
1625 Declaring zero-length arrays in other contexts, including as interior
1626 members of structure objects or as non-member objects, is discouraged.
1627 Accessing elements of zero-length arrays declared in such contexts is
1628 undefined and may be diagnosed.
1630 In the absence of the zero-length array extension, in ISO C90
1631 the @code{contents} array in the example above would typically be declared
1632 to have a single element. Unlike a zero-length array which only contributes
1633 to the size of the enclosing structure for the purposes of alignment,
1634 a one-element array always occupies at least as much space as a single
1635 object of the type. Although using one-element arrays this way is
1636 discouraged, GCC handles accesses to trailing one-element array members
1637 analogously to zero-length arrays.
1639 The preferred mechanism to declare variable-length types like
1640 @code{struct line} above is the ISO C99 @dfn{flexible array member},
1641 with slightly different syntax and semantics:
1645 Flexible array members are written as @code{contents[]} without
1649 Flexible array members have incomplete type, and so the @code{sizeof}
1650 operator may not be applied. As a quirk of the original implementation
1651 of zero-length arrays, @code{sizeof} evaluates to zero.
1654 Flexible array members may only appear as the last member of a
1655 @code{struct} that is otherwise non-empty.
1658 A structure containing a flexible array member, or a union containing
1659 such a structure (possibly recursively), may not be a member of a
1660 structure or an element of an array. (However, these uses are
1661 permitted by GCC as extensions.)
1664 Non-empty initialization of zero-length
1665 arrays is treated like any case where there are more initializer
1666 elements than the array holds, in that a suitable warning about ``excess
1667 elements in array'' is given, and the excess elements (all of them, in
1668 this case) are ignored.
1670 GCC allows static initialization of flexible array members.
1671 This is equivalent to defining a new structure containing the original
1672 structure followed by an array of sufficient size to contain the data.
1673 E.g.@: in the following, @code{f1} is constructed as if it were declared
1679 @} f1 = @{ 1, @{ 2, 3, 4 @} @};
1682 struct f1 f1; int data[3];
1683 @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
1687 The convenience of this extension is that @code{f1} has the desired
1688 type, eliminating the need to consistently refer to @code{f2.f1}.
1690 This has symmetry with normal static arrays, in that an array of
1691 unknown size is also written with @code{[]}.
1693 Of course, this extension only makes sense if the extra data comes at
1694 the end of a top-level object, as otherwise we would be overwriting
1695 data at subsequent offsets. To avoid undue complication and confusion
1696 with initialization of deeply nested arrays, we simply disallow any
1697 non-empty initialization except when the structure is the top-level
1698 object. For example:
1701 struct foo @{ int x; int y[]; @};
1702 struct bar @{ struct foo z; @};
1704 struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
1705 struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1706 struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
1707 struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1710 @node Empty Structures
1711 @section Structures with No Members
1712 @cindex empty structures
1713 @cindex zero-size structures
1715 GCC permits a C structure to have no members:
1722 The structure has size zero. In C++, empty structures are part
1723 of the language. G++ treats empty structures as if they had a single
1724 member of type @code{char}.
1726 @node Variable Length
1727 @section Arrays of Variable Length
1728 @cindex variable-length arrays
1729 @cindex arrays of variable length
1732 Variable-length automatic arrays are allowed in ISO C99, and as an
1733 extension GCC accepts them in C90 mode and in C++. These arrays are
1734 declared like any other automatic arrays, but with a length that is not
1735 a constant expression. The storage is allocated at the point of
1736 declaration and deallocated when the block scope containing the declaration
1742 concat_fopen (char *s1, char *s2, char *mode)
1744 char str[strlen (s1) + strlen (s2) + 1];
1747 return fopen (str, mode);
1751 @cindex scope of a variable length array
1752 @cindex variable-length array scope
1753 @cindex deallocating variable length arrays
1754 Jumping or breaking out of the scope of the array name deallocates the
1755 storage. Jumping into the scope is not allowed; you get an error
1758 @cindex variable-length array in a structure
1759 As an extension, GCC accepts variable-length arrays as a member of
1760 a structure or a union. For example:
1766 struct S @{ int x[n]; @};
1770 @cindex @code{alloca} vs variable-length arrays
1771 You can use the function @code{alloca} to get an effect much like
1772 variable-length arrays. The function @code{alloca} is available in
1773 many other C implementations (but not in all). On the other hand,
1774 variable-length arrays are more elegant.
1776 There are other differences between these two methods. Space allocated
1777 with @code{alloca} exists until the containing @emph{function} returns.
1778 The space for a variable-length array is deallocated as soon as the array
1779 name's scope ends, unless you also use @code{alloca} in this scope.
1781 You can also use variable-length arrays as arguments to functions:
1785 tester (int len, char data[len][len])
1791 The length of an array is computed once when the storage is allocated
1792 and is remembered for the scope of the array in case you access it with
1795 If you want to pass the array first and the length afterward, you can
1796 use a forward declaration in the parameter list---another GNU extension.
1800 tester (int len; char data[len][len], int len)
1806 @cindex parameter forward declaration
1807 The @samp{int len} before the semicolon is a @dfn{parameter forward
1808 declaration}, and it serves the purpose of making the name @code{len}
1809 known when the declaration of @code{data} is parsed.
1811 You can write any number of such parameter forward declarations in the
1812 parameter list. They can be separated by commas or semicolons, but the
1813 last one must end with a semicolon, which is followed by the ``real''
1814 parameter declarations. Each forward declaration must match a ``real''
1815 declaration in parameter name and data type. ISO C99 does not support
1816 parameter forward declarations.
1818 @node Variadic Macros
1819 @section Macros with a Variable Number of Arguments.
1820 @cindex variable number of arguments
1821 @cindex macro with variable arguments
1822 @cindex rest argument (in macro)
1823 @cindex variadic macros
1825 In the ISO C standard of 1999, a macro can be declared to accept a
1826 variable number of arguments much as a function can. The syntax for
1827 defining the macro is similar to that of a function. Here is an
1831 #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
1835 Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
1836 such a macro, it represents the zero or more tokens until the closing
1837 parenthesis that ends the invocation, including any commas. This set of
1838 tokens replaces the identifier @code{__VA_ARGS__} in the macro body
1839 wherever it appears. See the CPP manual for more information.
1841 GCC has long supported variadic macros, and used a different syntax that
1842 allowed you to give a name to the variable arguments just like any other
1843 argument. Here is an example:
1846 #define debug(format, args...) fprintf (stderr, format, args)
1850 This is in all ways equivalent to the ISO C example above, but arguably
1851 more readable and descriptive.
1853 GNU CPP has two further variadic macro extensions, and permits them to
1854 be used with either of the above forms of macro definition.
1856 In standard C, you are not allowed to leave the variable argument out
1857 entirely; but you are allowed to pass an empty argument. For example,
1858 this invocation is invalid in ISO C, because there is no comma after
1865 GNU CPP permits you to completely omit the variable arguments in this
1866 way. In the above examples, the compiler would complain, though since
1867 the expansion of the macro still has the extra comma after the format
1870 To help solve this problem, CPP behaves specially for variable arguments
1871 used with the token paste operator, @samp{##}. If instead you write
1874 #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
1878 and if the variable arguments are omitted or empty, the @samp{##}
1879 operator causes the preprocessor to remove the comma before it. If you
1880 do provide some variable arguments in your macro invocation, GNU CPP
1881 does not complain about the paste operation and instead places the
1882 variable arguments after the comma. Just like any other pasted macro
1883 argument, these arguments are not macro expanded.
1885 @node Escaped Newlines
1886 @section Slightly Looser Rules for Escaped Newlines
1887 @cindex escaped newlines
1888 @cindex newlines (escaped)
1890 The preprocessor treatment of escaped newlines is more relaxed
1891 than that specified by the C90 standard, which requires the newline
1892 to immediately follow a backslash.
1893 GCC's implementation allows whitespace in the form
1894 of spaces, horizontal and vertical tabs, and form feeds between the
1895 backslash and the subsequent newline. The preprocessor issues a
1896 warning, but treats it as a valid escaped newline and combines the two
1897 lines to form a single logical line. This works within comments and
1898 tokens, as well as between tokens. Comments are @emph{not} treated as
1899 whitespace for the purposes of this relaxation, since they have not
1900 yet been replaced with spaces.
1903 @section Non-Lvalue Arrays May Have Subscripts
1904 @cindex subscripting
1905 @cindex arrays, non-lvalue
1907 @cindex subscripting and function values
1908 In ISO C99, arrays that are not lvalues still decay to pointers, and
1909 may be subscripted, although they may not be modified or used after
1910 the next sequence point and the unary @samp{&} operator may not be
1911 applied to them. As an extension, GNU C allows such arrays to be
1912 subscripted in C90 mode, though otherwise they do not decay to
1913 pointers outside C99 mode. For example,
1914 this is valid in GNU C though not valid in C90:
1918 struct foo @{int a[4];@};
1924 return f().a[index];
1930 @section Arithmetic on @code{void}- and Function-Pointers
1931 @cindex void pointers, arithmetic
1932 @cindex void, size of pointer to
1933 @cindex function pointers, arithmetic
1934 @cindex function, size of pointer to
1936 In GNU C, addition and subtraction operations are supported on pointers to
1937 @code{void} and on pointers to functions. This is done by treating the
1938 size of a @code{void} or of a function as 1.
1940 A consequence of this is that @code{sizeof} is also allowed on @code{void}
1941 and on function types, and returns 1.
1943 @opindex Wpointer-arith
1944 The option @option{-Wpointer-arith} requests a warning if these extensions
1947 @node Pointers to Arrays
1948 @section Pointers to Arrays with Qualifiers Work as Expected
1949 @cindex pointers to arrays
1950 @cindex const qualifier
1952 In GNU C, pointers to arrays with qualifiers work similar to pointers
1953 to other qualified types. For example, a value of type @code{int (*)[5]}
1954 can be used to initialize a variable of type @code{const int (*)[5]}.
1955 These types are incompatible in ISO C because the @code{const} qualifier
1956 is formally attached to the element type of the array and not the
1961 transpose (int N, int M, double out[M][N], const double in[N][M]);
1965 transpose(3, 2, y, x);
1969 @section Non-Constant Initializers
1970 @cindex initializers, non-constant
1971 @cindex non-constant initializers
1973 As in standard C++ and ISO C99, the elements of an aggregate initializer for an
1974 automatic variable are not required to be constant expressions in GNU C@.
1975 Here is an example of an initializer with run-time varying elements:
1978 foo (float f, float g)
1980 float beat_freqs[2] = @{ f-g, f+g @};
1985 @node Compound Literals
1986 @section Compound Literals
1987 @cindex constructor expressions
1988 @cindex initializations in expressions
1989 @cindex structures, constructor expression
1990 @cindex expressions, constructor
1991 @cindex compound literals
1992 @c The GNU C name for what C99 calls compound literals was "constructor expressions".
1994 A compound literal looks like a cast of a brace-enclosed aggregate
1995 initializer list. Its value is an object of the type specified in
1996 the cast, containing the elements specified in the initializer.
1997 Unlike the result of a cast, a compound literal is an lvalue. ISO
1998 C99 and later support compound literals. As an extension, GCC
1999 supports compound literals also in C90 mode and in C++, although
2000 as explained below, the C++ semantics are somewhat different.
2002 Usually, the specified type of a compound literal is a structure. Assume
2003 that @code{struct foo} and @code{structure} are declared as shown:
2006 struct foo @{int a; char b[2];@} structure;
2010 Here is an example of constructing a @code{struct foo} with a compound literal:
2013 structure = ((struct foo) @{x + y, 'a', 0@});
2017 This is equivalent to writing the following:
2021 struct foo temp = @{x + y, 'a', 0@};
2026 You can also construct an array, though this is dangerous in C++, as
2027 explained below. If all the elements of the compound literal are
2028 (made up of) simple constant expressions suitable for use in
2029 initializers of objects of static storage duration, then the compound
2030 literal can be coerced to a pointer to its first element and used in
2031 such an initializer, as shown here:
2034 char **foo = (char *[]) @{ "x", "y", "z" @};
2037 Compound literals for scalar types and union types are also allowed. In
2038 the following example the variable @code{i} is initialized to the value
2039 @code{2}, the result of incrementing the unnamed object created by
2040 the compound literal.
2043 int i = ++(int) @{ 1 @};
2046 As a GNU extension, GCC allows initialization of objects with static storage
2047 duration by compound literals (which is not possible in ISO C99 because
2048 the initializer is not a constant).
2049 It is handled as if the object were initialized only with the brace-enclosed
2050 list if the types of the compound literal and the object match.
2051 The elements of the compound literal must be constant.
2052 If the object being initialized has array type of unknown size, the size is
2053 determined by the size of the compound literal.
2056 static struct foo x = (struct foo) @{1, 'a', 'b'@};
2057 static int y[] = (int []) @{1, 2, 3@};
2058 static int z[] = (int [3]) @{1@};
2062 The above lines are equivalent to the following:
2064 static struct foo x = @{1, 'a', 'b'@};
2065 static int y[] = @{1, 2, 3@};
2066 static int z[] = @{1, 0, 0@};
2069 In C, a compound literal designates an unnamed object with static or
2070 automatic storage duration. In C++, a compound literal designates a
2071 temporary object that only lives until the end of its full-expression.
2072 As a result, well-defined C code that takes the address of a subobject
2073 of a compound literal can be undefined in C++, so G++ rejects
2074 the conversion of a temporary array to a pointer. For instance, if
2075 the array compound literal example above appeared inside a function,
2076 any subsequent use of @code{foo} in C++ would have undefined behavior
2077 because the lifetime of the array ends after the declaration of @code{foo}.
2079 As an optimization, G++ sometimes gives array compound literals longer
2080 lifetimes: when the array either appears outside a function or has
2081 a @code{const}-qualified type. If @code{foo} and its initializer had
2082 elements of type @code{char *const} rather than @code{char *}, or if
2083 @code{foo} were a global variable, the array would have static storage
2084 duration. But it is probably safest just to avoid the use of array
2085 compound literals in C++ code.
2087 @node Designated Inits
2088 @section Designated Initializers
2089 @cindex initializers with labeled elements
2090 @cindex labeled elements in initializers
2091 @cindex case labels in initializers
2092 @cindex designated initializers
2094 Standard C90 requires the elements of an initializer to appear in a fixed
2095 order, the same as the order of the elements in the array or structure
2098 In ISO C99 you can give the elements in any order, specifying the array
2099 indices or structure field names they apply to, and GNU C allows this as
2100 an extension in C90 mode as well. This extension is not
2101 implemented in GNU C++.
2103 To specify an array index, write
2104 @samp{[@var{index}] =} before the element value. For example,
2107 int a[6] = @{ [4] = 29, [2] = 15 @};
2114 int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
2118 The index values must be constant expressions, even if the array being
2119 initialized is automatic.
2121 An alternative syntax for this that has been obsolete since GCC 2.5 but
2122 GCC still accepts is to write @samp{[@var{index}]} before the element
2123 value, with no @samp{=}.
2125 To initialize a range of elements to the same value, write
2126 @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
2127 extension. For example,
2130 int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
2134 If the value in it has side effects, the side effects happen only once,
2135 not for each initialized field by the range initializer.
2138 Note that the length of the array is the highest value specified
2141 In a structure initializer, specify the name of a field to initialize
2142 with @samp{.@var{fieldname} =} before the element value. For example,
2143 given the following structure,
2146 struct point @{ int x, y; @};
2150 the following initialization
2153 struct point p = @{ .y = yvalue, .x = xvalue @};
2160 struct point p = @{ xvalue, yvalue @};
2163 Another syntax that has the same meaning, obsolete since GCC 2.5, is
2164 @samp{@var{fieldname}:}, as shown here:
2167 struct point p = @{ y: yvalue, x: xvalue @};
2170 Omitted fields are implicitly initialized the same as for objects
2171 that have static storage duration.
2174 The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
2175 @dfn{designator}. You can also use a designator (or the obsolete colon
2176 syntax) when initializing a union, to specify which element of the union
2177 should be used. For example,
2180 union foo @{ int i; double d; @};
2182 union foo f = @{ .d = 4 @};
2186 converts 4 to a @code{double} to store it in the union using
2187 the second element. By contrast, casting 4 to type @code{union foo}
2188 stores it into the union as the integer @code{i}, since it is
2189 an integer. @xref{Cast to Union}.
2191 You can combine this technique of naming elements with ordinary C
2192 initialization of successive elements. Each initializer element that
2193 does not have a designator applies to the next consecutive element of the
2194 array or structure. For example,
2197 int a[6] = @{ [1] = v1, v2, [4] = v4 @};
2204 int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
2207 Labeling the elements of an array initializer is especially useful
2208 when the indices are characters or belong to an @code{enum} type.
2213 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
2214 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
2217 @cindex designator lists
2218 You can also write a series of @samp{.@var{fieldname}} and
2219 @samp{[@var{index}]} designators before an @samp{=} to specify a
2220 nested subobject to initialize; the list is taken relative to the
2221 subobject corresponding to the closest surrounding brace pair. For
2222 example, with the @samp{struct point} declaration above:
2225 struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
2228 If the same field is initialized multiple times, or overlapping
2229 fields of a union are initialized, the value from the last
2230 initialization is used. When a field of a union is itself a structure,
2231 the entire structure from the last field initialized is used. If any previous
2232 initializer has side effect, it is unspecified whether the side effect
2233 happens or not. Currently, GCC discards the side-effecting
2234 initializer expressions and issues a warning.
2237 @section Case Ranges
2239 @cindex ranges in case statements
2241 You can specify a range of consecutive values in a single @code{case} label,
2245 case @var{low} ... @var{high}:
2249 This has the same effect as the proper number of individual @code{case}
2250 labels, one for each integer value from @var{low} to @var{high}, inclusive.
2252 This feature is especially useful for ranges of ASCII character codes:
2258 @strong{Be careful:} Write spaces around the @code{...}, for otherwise
2259 it may be parsed wrong when you use it with integer values. For example,
2274 @section Cast to a Union Type
2275 @cindex cast to a union
2276 @cindex union, casting to a
2278 A cast to a union type is a C extension not available in C++. It looks
2279 just like ordinary casts with the constraint that the type specified is
2280 a union type. You can specify the type either with the @code{union}
2281 keyword or with a @code{typedef} name that refers to a union. The result
2282 of a cast to a union is a temporary rvalue of the union type with a member
2283 whose type matches that of the operand initialized to the value of
2284 the operand. The effect of a cast to a union is similar to a compound
2285 literal except that it yields an rvalue like standard casts do.
2286 @xref{Compound Literals}.
2288 Expressions that may be cast to the union type are those whose type matches
2289 at least one of the members of the union. Thus, given the following union
2293 union foo @{ int i; double d; @};
2300 both @code{x} and @code{y} can be cast to type @code{union foo} and
2301 the following assignments
2306 are shorthand equivalents of these
2308 z = (union foo) @{ .i = x @};
2309 z = (union foo) @{ .d = y @};
2312 However, @code{(union foo) FLT_MAX;} is not a valid cast because the union
2313 has no member of type @code{float}.
2315 Using the cast as the right-hand side of an assignment to a variable of
2316 union type is equivalent to storing in a member of the union with
2322 u = (union foo) x @equiv{} u.i = x
2323 u = (union foo) y @equiv{} u.d = y
2326 You can also use the union cast as a function argument:
2329 void hack (union foo);
2331 hack ((union foo) x);
2334 @node Mixed Declarations
2335 @section Mixed Declarations and Code
2336 @cindex mixed declarations and code
2337 @cindex declarations, mixed with code
2338 @cindex code, mixed with declarations
2340 ISO C99 and ISO C++ allow declarations and code to be freely mixed
2341 within compound statements. As an extension, GNU C also allows this in
2342 C90 mode. For example, you could do:
2351 Each identifier is visible from where it is declared until the end of
2352 the enclosing block.
2354 @node Function Attributes
2355 @section Declaring Attributes of Functions
2356 @cindex function attributes
2357 @cindex declaring attributes of functions
2358 @cindex @code{volatile} applied to function
2359 @cindex @code{const} applied to function
2361 In GNU C and C++, you can use function attributes to specify certain
2362 function properties that may help the compiler optimize calls or
2363 check code more carefully for correctness. For example, you
2364 can use attributes to specify that a function never returns
2365 (@code{noreturn}), returns a value depending only on the values of
2366 its arguments (@code{const}), or has @code{printf}-style arguments
2369 You can also use attributes to control memory placement, code
2370 generation options or call/return conventions within the function
2371 being annotated. Many of these attributes are target-specific. For
2372 example, many targets support attributes for defining interrupt
2373 handler functions, which typically must follow special register usage
2374 and return conventions. Such attributes are described in the subsection
2375 for each target. However, a considerable number of attributes are
2376 supported by most, if not all targets. Those are described in
2377 the @ref{Common Function Attributes} section.
2379 Function attributes are introduced by the @code{__attribute__} keyword
2380 in the declaration of a function, followed by an attribute specification
2381 enclosed in double parentheses. You can specify multiple attributes in
2382 a declaration by separating them by commas within the double parentheses
2383 or by immediately following one attribute specification with another.
2384 @xref{Attribute Syntax}, for the exact rules on attribute syntax and
2385 placement. Compatible attribute specifications on distinct declarations
2386 of the same function are merged. An attribute specification that is not
2387 compatible with attributes already applied to a declaration of the same
2388 function is ignored with a warning.
2390 Some function attributes take one or more arguments that refer to
2391 the function's parameters by their positions within the function parameter
2392 list. Such attribute arguments are referred to as @dfn{positional arguments}.
2393 Unless specified otherwise, positional arguments that specify properties
2394 of parameters with pointer types can also specify the same properties of
2395 the implicit C++ @code{this} argument in non-static member functions, and
2396 of parameters of reference to a pointer type. For ordinary functions,
2397 position one refers to the first parameter on the list. In C++ non-static
2398 member functions, position one refers to the implicit @code{this} pointer.
2399 The same restrictions and effects apply to function attributes used with
2400 ordinary functions or C++ member functions.
2402 GCC also supports attributes on
2403 variable declarations (@pxref{Variable Attributes}),
2404 labels (@pxref{Label Attributes}),
2405 enumerators (@pxref{Enumerator Attributes}),
2406 statements (@pxref{Statement Attributes}),
2407 and types (@pxref{Type Attributes}).
2409 There is some overlap between the purposes of attributes and pragmas
2410 (@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been
2411 found convenient to use @code{__attribute__} to achieve a natural
2412 attachment of attributes to their corresponding declarations, whereas
2413 @code{#pragma} is of use for compatibility with other compilers
2414 or constructs that do not naturally form part of the grammar.
2416 In addition to the attributes documented here,
2417 GCC plugins may provide their own attributes.
2420 * Common Function Attributes::
2421 * AArch64 Function Attributes::
2422 * AMD GCN Function Attributes::
2423 * ARC Function Attributes::
2424 * ARM Function Attributes::
2425 * AVR Function Attributes::
2426 * Blackfin Function Attributes::
2427 * CR16 Function Attributes::
2428 * C-SKY Function Attributes::
2429 * Epiphany Function Attributes::
2430 * H8/300 Function Attributes::
2431 * IA-64 Function Attributes::
2432 * M32C Function Attributes::
2433 * M32R/D Function Attributes::
2434 * m68k Function Attributes::
2435 * MCORE Function Attributes::
2436 * MeP Function Attributes::
2437 * MicroBlaze Function Attributes::
2438 * Microsoft Windows Function Attributes::
2439 * MIPS Function Attributes::
2440 * MSP430 Function Attributes::
2441 * NDS32 Function Attributes::
2442 * Nios II Function Attributes::
2443 * Nvidia PTX Function Attributes::
2444 * PowerPC Function Attributes::
2445 * RISC-V Function Attributes::
2446 * RL78 Function Attributes::
2447 * RX Function Attributes::
2448 * S/390 Function Attributes::
2449 * SH Function Attributes::
2450 * SPU Function Attributes::
2451 * Symbian OS Function Attributes::
2452 * V850 Function Attributes::
2453 * Visium Function Attributes::
2454 * x86 Function Attributes::
2455 * Xstormy16 Function Attributes::
2458 @node Common Function Attributes
2459 @subsection Common Function Attributes
2461 The following attributes are supported on most targets.
2464 @c Keep this table alphabetized by attribute name. Treat _ as space.
2466 @item alias ("@var{target}")
2467 @cindex @code{alias} function attribute
2468 The @code{alias} attribute causes the declaration to be emitted as an
2469 alias for another symbol, which must be specified. For instance,
2472 void __f () @{ /* @r{Do something.} */; @}
2473 void f () __attribute__ ((weak, alias ("__f")));
2477 defines @samp{f} to be a weak alias for @samp{__f}. In C++, the
2478 mangled name for the target must be used. It is an error if @samp{__f}
2479 is not defined in the same translation unit.
2481 This attribute requires assembler and object file support,
2482 and may not be available on all targets.
2485 @itemx aligned (@var{alignment})
2486 @cindex @code{aligned} function attribute
2487 The @code{aligned} attribute specifies a minimum alignment for
2488 the first instruction of the function, measured in bytes. When specified,
2489 @var{alignment} must be an integer constant power of 2. Specifying no
2490 @var{alignment} argument implies the ideal alignment for the target.
2491 The @code{__alignof__} operator can be used to determine what that is
2492 (@pxref{Alignment}). The attribute has no effect when a definition for
2493 the function is not provided in the same translation unit.
2495 The attribute cannot be used to decrease the alignment of a function
2496 previously declared with a more restrictive alignment; only to increase
2497 it. Attempts to do otherwise are diagnosed. Some targets specify
2498 a minimum default alignment for functions that is greater than 1. On
2499 such targets, specifying a less restrictive alignment is silently ignored.
2500 Using the attribute overrides the effect of the @option{-falign-functions}
2501 (@pxref{Optimize Options}) option for this function.
2503 Note that the effectiveness of @code{aligned} attributes may be
2504 limited by inherent limitations in the system linker
2505 and/or object file format. On some systems, the
2506 linker is only able to arrange for functions to be aligned up to a
2507 certain maximum alignment. (For some linkers, the maximum supported
2508 alignment may be very very small.) See your linker documentation for
2509 further information.
2511 The @code{aligned} attribute can also be used for variables and fields
2512 (@pxref{Variable Attributes}.)
2514 @item alloc_align (@var{position})
2515 @cindex @code{alloc_align} function attribute
2516 The @code{alloc_align} attribute may be applied to a function that
2517 returns a pointer and takes at least one argument of an integer or
2519 It indicates that the returned pointer is aligned on a boundary given
2520 by the function argument at @var{position}. Meaningful alignments are
2521 powers of 2 greater than one. GCC uses this information to improve
2522 pointer alignment analysis.
2524 The function parameter denoting the allocated alignment is specified by
2525 one constant integer argument whose number is the argument of the attribute.
2526 Argument numbering starts at one.
2531 void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1)));
2535 declares that @code{my_memalign} returns memory with minimum alignment
2536 given by parameter 1.
2538 @item alloc_size (@var{position})
2539 @itemx alloc_size (@var{position-1}, @var{position-2})
2540 @cindex @code{alloc_size} function attribute
2541 The @code{alloc_size} attribute may be applied to a function that
2542 returns a pointer and takes at least one argument of an integer or
2544 It indicates that the returned pointer points to memory whose size is
2545 given by the function argument at @var{position-1}, or by the product
2546 of the arguments at @var{position-1} and @var{position-2}. Meaningful
2547 sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this
2548 information to improve the results of @code{__builtin_object_size}.
2550 The function parameter(s) denoting the allocated size are specified by
2551 one or two integer arguments supplied to the attribute. The allocated size
2552 is either the value of the single function argument specified or the product
2553 of the two function arguments specified. Argument numbering starts at
2554 one for ordinary functions, and at two for C++ non-static member functions.
2559 void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2)));
2560 void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2)));
2564 declares that @code{my_calloc} returns memory of the size given by
2565 the product of parameter 1 and 2 and that @code{my_realloc} returns memory
2566 of the size given by parameter 2.
2569 @cindex @code{always_inline} function attribute
2570 Generally, functions are not inlined unless optimization is specified.
2571 For functions declared inline, this attribute inlines the function
2572 independent of any restrictions that otherwise apply to inlining.
2573 Failure to inline such a function is diagnosed as an error.
2574 Note that if such a function is called indirectly the compiler may
2575 or may not inline it depending on optimization level and a failure
2576 to inline an indirect call may or may not be diagnosed.
2579 @cindex @code{artificial} function attribute
2580 This attribute is useful for small inline wrappers that if possible
2581 should appear during debugging as a unit. Depending on the debug
2582 info format it either means marking the function as artificial
2583 or using the caller location for all instructions within the inlined
2586 @item assume_aligned (@var{alignment})
2587 @itemx assume_aligned (@var{alignment}, @var{offset})
2588 @cindex @code{assume_aligned} function attribute
2589 The @code{assume_aligned} attribute may be applied to a function that
2590 returns a pointer. It indicates that the returned pointer is aligned
2591 on a boundary given by @var{alignment}. If the attribute has two
2592 arguments, the second argument is misalignment @var{offset}. Meaningful
2593 values of @var{alignment} are powers of 2 greater than one. Meaningful
2594 values of @var{offset} are greater than zero and less than @var{alignment}.
2599 void* my_alloc1 (size_t) __attribute__((assume_aligned (16)));
2600 void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8)));
2604 declares that @code{my_alloc1} returns 16-byte aligned pointers and
2605 that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
2609 @cindex @code{cold} function attribute
2610 The @code{cold} attribute on functions is used to inform the compiler that
2611 the function is unlikely to be executed. The function is optimized for
2612 size rather than speed and on many targets it is placed into a special
2613 subsection of the text section so all cold functions appear close together,
2614 improving code locality of non-cold parts of program. The paths leading
2615 to calls of cold functions within code are marked as unlikely by the branch
2616 prediction mechanism. It is thus useful to mark functions used to handle
2617 unlikely conditions, such as @code{perror}, as cold to improve optimization
2618 of hot functions that do call marked functions in rare occasions.
2620 When profile feedback is available, via @option{-fprofile-use}, cold functions
2621 are automatically detected and this attribute is ignored.
2624 @cindex @code{const} function attribute
2625 @cindex functions that have no side effects
2626 Calls to functions whose return value is not affected by changes to
2627 the observable state of the program and that have no observable effects
2628 on such state other than to return a value may lend themselves to
2629 optimizations such as common subexpression elimination. Declaring such
2630 functions with the @code{const} attribute allows GCC to avoid emitting
2631 some calls in repeated invocations of the function with the same argument
2637 int square (int) __attribute__ ((const));
2641 tells GCC that subsequent calls to function @code{square} with the same
2642 argument value can be replaced by the result of the first call regardless
2643 of the statements in between.
2645 The @code{const} attribute prohibits a function from reading objects
2646 that affect its return value between successive invocations. However,
2647 functions declared with the attribute can safely read objects that do
2648 not change their return value, such as non-volatile constants.
2650 The @code{const} attribute imposes greater restrictions on a function's
2651 definition than the similar @code{pure} attribute. Declaring the same
2652 function with both the @code{const} and the @code{pure} attribute is
2653 diagnosed. Because a const function cannot have any observable side
2654 effects it does not make sense for it to return @code{void}. Declaring
2655 such a function is diagnosed.
2657 @cindex pointer arguments
2658 Note that a function that has pointer arguments and examines the data
2659 pointed to must @emph{not} be declared @code{const} if the pointed-to
2660 data might change between successive invocations of the function. In
2661 general, since a function cannot distinguish data that might change
2662 from data that cannot, const functions should never take pointer or,
2663 in C++, reference arguments. Likewise, a function that calls a non-const
2664 function usually must not be const itself.
2668 @itemx constructor (@var{priority})
2669 @itemx destructor (@var{priority})
2670 @cindex @code{constructor} function attribute
2671 @cindex @code{destructor} function attribute
2672 The @code{constructor} attribute causes the function to be called
2673 automatically before execution enters @code{main ()}. Similarly, the
2674 @code{destructor} attribute causes the function to be called
2675 automatically after @code{main ()} completes or @code{exit ()} is
2676 called. Functions with these attributes are useful for
2677 initializing data that is used implicitly during the execution of
2680 On some targets the attributes also accept an integer argument to
2681 specify a priority to control the order in which constructor and
2682 destructor functions are run. A constructor
2683 with a smaller priority number runs before a constructor with a larger
2684 priority number; the opposite relationship holds for destructors. So,
2685 if you have a constructor that allocates a resource and a destructor
2686 that deallocates the same resource, both functions typically have the
2687 same priority. The priorities for constructor and destructor
2688 functions are the same as those specified for namespace-scope C++
2689 objects (@pxref{C++ Attributes}). However, at present, the order in which
2690 constructors for C++ objects with static storage duration and functions
2691 decorated with attribute @code{constructor} are invoked is unspecified.
2692 In mixed declarations, attribute @code{init_priority} can be used to
2693 impose a specific ordering.
2695 Using the argument forms of the @code{constructor} and @code{destructor}
2696 attributes on targets where the feature is not supported is rejected with
2700 @itemx copy (@var{function})
2701 @cindex @code{copy} function attribute
2702 The @code{copy} attribute applies the set of attributes with which
2703 @var{function} has been declared to the declaration of the function
2704 to which the attribute is applied. The attribute is designed for
2705 libraries that define aliases or function resolvers that are expected
2706 to specify the same set of attributes as their targets. The @code{copy}
2707 attribute can be used with functions, variables, or types. However,
2708 the kind of symbol to which the attribute is applied (either function
2709 or variable) must match the kind of symbol to which the argument refers.
2710 The @code{copy} attribute copies only syntactic and semantic attributes
2711 but not attributes that affect a symbol's linkage or visibility such as
2712 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
2713 attribute is also not copied. @xref{Common Type Attributes}.
2714 @xref{Common Variable Attributes}.
2716 For example, the @var{StrongAlias} macro below makes use of the @code{alias}
2717 and @code{copy} attributes to define an alias named @var{alloc} for function
2718 @var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and
2719 @var{nothrow}. Thanks to the @code{__typeof__} operator the alias has
2720 the same type as the target function. As a result of the @code{copy}
2721 attribute the alias also shares the same attributes as the target.
2724 #define StrongAlias(TagetFunc, AliasDecl) \
2725 extern __typeof__ (TargetFunc) AliasDecl \
2726 __attribute__ ((alias (#TargetFunc), copy (TargetFunc)));
2728 extern __attribute__ ((alloc_size (1), malloc, nothrow))
2729 void* allocate (size_t);
2730 StrongAlias (allocate, alloc);
2734 @itemx deprecated (@var{msg})
2735 @cindex @code{deprecated} function attribute
2736 The @code{deprecated} attribute results in a warning if the function
2737 is used anywhere in the source file. This is useful when identifying
2738 functions that are expected to be removed in a future version of a
2739 program. The warning also includes the location of the declaration
2740 of the deprecated function, to enable users to easily find further
2741 information about why the function is deprecated, or what they should
2742 do instead. Note that the warnings only occurs for uses:
2745 int old_fn () __attribute__ ((deprecated));
2747 int (*fn_ptr)() = old_fn;
2751 results in a warning on line 3 but not line 2. The optional @var{msg}
2752 argument, which must be a string, is printed in the warning if
2755 The @code{deprecated} attribute can also be used for variables and
2756 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
2758 The message attached to the attribute is affected by the setting of
2759 the @option{-fmessage-length} option.
2761 @item error ("@var{message}")
2762 @itemx warning ("@var{message}")
2763 @cindex @code{error} function attribute
2764 @cindex @code{warning} function attribute
2765 If the @code{error} or @code{warning} attribute
2766 is used on a function declaration and a call to such a function
2767 is not eliminated through dead code elimination or other optimizations,
2768 an error or warning (respectively) that includes @var{message} is diagnosed.
2770 for compile-time checking, especially together with @code{__builtin_constant_p}
2771 and inline functions where checking the inline function arguments is not
2772 possible through @code{extern char [(condition) ? 1 : -1];} tricks.
2774 While it is possible to leave the function undefined and thus invoke
2775 a link failure (to define the function with
2776 a message in @code{.gnu.warning*} section),
2777 when using these attributes the problem is diagnosed
2778 earlier and with exact location of the call even in presence of inline
2779 functions or when not emitting debugging information.
2781 @item externally_visible
2782 @cindex @code{externally_visible} function attribute
2783 This attribute, attached to a global variable or function, nullifies
2784 the effect of the @option{-fwhole-program} command-line option, so the
2785 object remains visible outside the current compilation unit.
2787 If @option{-fwhole-program} is used together with @option{-flto} and
2788 @command{gold} is used as the linker plugin,
2789 @code{externally_visible} attributes are automatically added to functions
2790 (not variable yet due to a current @command{gold} issue)
2791 that are accessed outside of LTO objects according to resolution file
2792 produced by @command{gold}.
2793 For other linkers that cannot generate resolution file,
2794 explicit @code{externally_visible} attributes are still necessary.
2797 @cindex @code{flatten} function attribute
2798 Generally, inlining into a function is limited. For a function marked with
2799 this attribute, every call inside this function is inlined, if possible.
2800 Functions declared with attribute @code{noinline} and similar are not
2801 inlined. Whether the function itself is considered for inlining depends
2802 on its size and the current inlining parameters.
2804 @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
2805 @cindex @code{format} function attribute
2806 @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
2808 The @code{format} attribute specifies that a function takes @code{printf},
2809 @code{scanf}, @code{strftime} or @code{strfmon} style arguments that
2810 should be type-checked against a format string. For example, the
2815 my_printf (void *my_object, const char *my_format, ...)
2816 __attribute__ ((format (printf, 2, 3)));
2820 causes the compiler to check the arguments in calls to @code{my_printf}
2821 for consistency with the @code{printf} style format string argument
2824 The parameter @var{archetype} determines how the format string is
2825 interpreted, and should be @code{printf}, @code{scanf}, @code{strftime},
2826 @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or
2827 @code{strfmon}. (You can also use @code{__printf__},
2828 @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On
2829 MinGW targets, @code{ms_printf}, @code{ms_scanf}, and
2830 @code{ms_strftime} are also present.
2831 @var{archetype} values such as @code{printf} refer to the formats accepted
2832 by the system's C runtime library,
2833 while values prefixed with @samp{gnu_} always refer
2834 to the formats accepted by the GNU C Library. On Microsoft Windows
2835 targets, values prefixed with @samp{ms_} refer to the formats accepted by the
2836 @file{msvcrt.dll} library.
2837 The parameter @var{string-index}
2838 specifies which argument is the format string argument (starting
2839 from 1), while @var{first-to-check} is the number of the first
2840 argument to check against the format string. For functions
2841 where the arguments are not available to be checked (such as
2842 @code{vprintf}), specify the third parameter as zero. In this case the
2843 compiler only checks the format string for consistency. For
2844 @code{strftime} formats, the third parameter is required to be zero.
2845 Since non-static C++ methods have an implicit @code{this} argument, the
2846 arguments of such methods should be counted from two, not one, when
2847 giving values for @var{string-index} and @var{first-to-check}.
2849 In the example above, the format string (@code{my_format}) is the second
2850 argument of the function @code{my_print}, and the arguments to check
2851 start with the third argument, so the correct parameters for the format
2852 attribute are 2 and 3.
2854 @opindex ffreestanding
2855 @opindex fno-builtin
2856 The @code{format} attribute allows you to identify your own functions
2857 that take format strings as arguments, so that GCC can check the
2858 calls to these functions for errors. The compiler always (unless
2859 @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
2860 for the standard library functions @code{printf}, @code{fprintf},
2861 @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
2862 @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
2863 warnings are requested (using @option{-Wformat}), so there is no need to
2864 modify the header file @file{stdio.h}. In C99 mode, the functions
2865 @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
2866 @code{vsscanf} are also checked. Except in strictly conforming C
2867 standard modes, the X/Open function @code{strfmon} is also checked as
2868 are @code{printf_unlocked} and @code{fprintf_unlocked}.
2869 @xref{C Dialect Options,,Options Controlling C Dialect}.
2871 For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is
2872 recognized in the same context. Declarations including these format attributes
2873 are parsed for correct syntax, however the result of checking of such format
2874 strings is not yet defined, and is not carried out by this version of the
2877 The target may also provide additional types of format checks.
2878 @xref{Target Format Checks,,Format Checks Specific to Particular
2881 @item format_arg (@var{string-index})
2882 @cindex @code{format_arg} function attribute
2883 @opindex Wformat-nonliteral
2884 The @code{format_arg} attribute specifies that a function takes one or
2885 more format strings for a @code{printf}, @code{scanf}, @code{strftime} or
2886 @code{strfmon} style function and modifies it (for example, to translate
2887 it into another language), so the result can be passed to a
2888 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
2889 function (with the remaining arguments to the format function the same
2890 as they would have been for the unmodified string). Multiple
2891 @code{format_arg} attributes may be applied to the same function, each
2892 designating a distinct parameter as a format string. For example, the
2897 my_dgettext (char *my_domain, const char *my_format)
2898 __attribute__ ((format_arg (2)));
2902 causes the compiler to check the arguments in calls to a @code{printf},
2903 @code{scanf}, @code{strftime} or @code{strfmon} type function, whose
2904 format string argument is a call to the @code{my_dgettext} function, for
2905 consistency with the format string argument @code{my_format}. If the
2906 @code{format_arg} attribute had not been specified, all the compiler
2907 could tell in such calls to format functions would be that the format
2908 string argument is not constant; this would generate a warning when
2909 @option{-Wformat-nonliteral} is used, but the calls could not be checked
2910 without the attribute.
2912 In calls to a function declared with more than one @code{format_arg}
2913 attribute, each with a distinct argument value, the corresponding
2914 actual function arguments are checked against all format strings
2915 designated by the attributes. This capability is designed to support
2916 the GNU @code{ngettext} family of functions.
2918 The parameter @var{string-index} specifies which argument is the format
2919 string argument (starting from one). Since non-static C++ methods have
2920 an implicit @code{this} argument, the arguments of such methods should
2921 be counted from two.
2923 The @code{format_arg} attribute allows you to identify your own
2924 functions that modify format strings, so that GCC can check the
2925 calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
2926 type function whose operands are a call to one of your own function.
2927 The compiler always treats @code{gettext}, @code{dgettext}, and
2928 @code{dcgettext} in this manner except when strict ISO C support is
2929 requested by @option{-ansi} or an appropriate @option{-std} option, or
2930 @option{-ffreestanding} or @option{-fno-builtin}
2931 is used. @xref{C Dialect Options,,Options
2932 Controlling C Dialect}.
2934 For Objective-C dialects, the @code{format-arg} attribute may refer to an
2935 @code{NSString} reference for compatibility with the @code{format} attribute
2938 The target may also allow additional types in @code{format-arg} attributes.
2939 @xref{Target Format Checks,,Format Checks Specific to Particular
2943 @cindex @code{gnu_inline} function attribute
2944 This attribute should be used with a function that is also declared
2945 with the @code{inline} keyword. It directs GCC to treat the function
2946 as if it were defined in gnu90 mode even when compiling in C99 or
2949 If the function is declared @code{extern}, then this definition of the
2950 function is used only for inlining. In no case is the function
2951 compiled as a standalone function, not even if you take its address
2952 explicitly. Such an address becomes an external reference, as if you
2953 had only declared the function, and had not defined it. This has
2954 almost the effect of a macro. The way to use this is to put a
2955 function definition in a header file with this attribute, and put
2956 another copy of the function, without @code{extern}, in a library
2957 file. The definition in the header file causes most calls to the
2958 function to be inlined. If any uses of the function remain, they
2959 refer to the single copy in the library. Note that the two
2960 definitions of the functions need not be precisely the same, although
2961 if they do not have the same effect your program may behave oddly.
2963 In C, if the function is neither @code{extern} nor @code{static}, then
2964 the function is compiled as a standalone function, as well as being
2965 inlined where possible.
2967 This is how GCC traditionally handled functions declared
2968 @code{inline}. Since ISO C99 specifies a different semantics for
2969 @code{inline}, this function attribute is provided as a transition
2970 measure and as a useful feature in its own right. This attribute is
2971 available in GCC 4.1.3 and later. It is available if either of the
2972 preprocessor macros @code{__GNUC_GNU_INLINE__} or
2973 @code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
2974 Function is As Fast As a Macro}.
2976 In C++, this attribute does not depend on @code{extern} in any way,
2977 but it still requires the @code{inline} keyword to enable its special
2981 @cindex @code{hot} function attribute
2982 The @code{hot} attribute on a function is used to inform the compiler that
2983 the function is a hot spot of the compiled program. The function is
2984 optimized more aggressively and on many targets it is placed into a special
2985 subsection of the text section so all hot functions appear close together,
2988 When profile feedback is available, via @option{-fprofile-use}, hot functions
2989 are automatically detected and this attribute is ignored.
2991 @item ifunc ("@var{resolver}")
2992 @cindex @code{ifunc} function attribute
2993 @cindex indirect functions
2994 @cindex functions that are dynamically resolved
2995 The @code{ifunc} attribute is used to mark a function as an indirect
2996 function using the STT_GNU_IFUNC symbol type extension to the ELF
2997 standard. This allows the resolution of the symbol value to be
2998 determined dynamically at load time, and an optimized version of the
2999 routine to be selected for the particular processor or other system
3000 characteristics determined then. To use this attribute, first define
3001 the implementation functions available, and a resolver function that
3002 returns a pointer to the selected implementation function. The
3003 implementation functions' declarations must match the API of the
3004 function being implemented. The resolver should be declared to
3005 be a function taking no arguments and returning a pointer to
3006 a function of the same type as the implementation. For example:
3009 void *my_memcpy (void *dst, const void *src, size_t len)
3015 static void * (*resolve_memcpy (void))(void *, const void *, size_t)
3017 return my_memcpy; // we will just always select this routine
3022 The exported header file declaring the function the user calls would
3026 extern void *memcpy (void *, const void *, size_t);
3030 allowing the user to call @code{memcpy} as a regular function, unaware of
3031 the actual implementation. Finally, the indirect function needs to be
3032 defined in the same translation unit as the resolver function:
3035 void *memcpy (void *, const void *, size_t)
3036 __attribute__ ((ifunc ("resolve_memcpy")));
3039 In C++, the @code{ifunc} attribute takes a string that is the mangled name
3040 of the resolver function. A C++ resolver for a non-static member function
3041 of class @code{C} should be declared to return a pointer to a non-member
3042 function taking pointer to @code{C} as the first argument, followed by
3043 the same arguments as of the implementation function. G++ checks
3044 the signatures of the two functions and issues
3045 a @option{-Wattribute-alias} warning for mismatches. To suppress a warning
3046 for the necessary cast from a pointer to the implementation member function
3047 to the type of the corresponding non-member function use
3048 the @option{-Wno-pmf-conversions} option. For example:
3054 int debug_impl (int);
3055 int optimized_impl (int);
3057 typedef int Func (S*, int);
3059 static Func* resolver ();
3062 int interface (int);
3065 int S::debug_impl (int) @{ /* @r{@dots{}} */ @}
3066 int S::optimized_impl (int) @{ /* @r{@dots{}} */ @}
3068 S::Func* S::resolver ()
3070 int (S::*pimpl) (int)
3071 = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl;
3073 // Cast triggers -Wno-pmf-conversions.
3074 return reinterpret_cast<Func*>(pimpl);
3077 int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv")));
3080 Indirect functions cannot be weak. Binutils version 2.20.1 or higher
3081 and GNU C Library version 2.11.1 are required to use this feature.
3084 @itemx interrupt_handler
3085 Many GCC back ends support attributes to indicate that a function is
3086 an interrupt handler, which tells the compiler to generate function
3087 entry and exit sequences that differ from those from regular
3088 functions. The exact syntax and behavior are target-specific;
3089 refer to the following subsections for details.
3092 @cindex @code{leaf} function attribute
3093 Calls to external functions with this attribute must return to the
3094 current compilation unit only by return or by exception handling. In
3095 particular, a leaf function is not allowed to invoke callback functions
3096 passed to it from the current compilation unit, directly call functions
3097 exported by the unit, or @code{longjmp} into the unit. Leaf functions
3098 might still call functions from other compilation units and thus they
3099 are not necessarily leaf in the sense that they contain no function
3102 The attribute is intended for library functions to improve dataflow
3103 analysis. The compiler takes the hint that any data not escaping the
3104 current compilation unit cannot be used or modified by the leaf
3105 function. For example, the @code{sin} function is a leaf function, but
3106 @code{qsort} is not.
3108 Note that leaf functions might indirectly run a signal handler defined
3109 in the current compilation unit that uses static variables. Similarly,
3110 when lazy symbol resolution is in effect, leaf functions might invoke
3111 indirect functions whose resolver function or implementation function is
3112 defined in the current compilation unit and uses static variables. There
3113 is no standard-compliant way to write such a signal handler, resolver
3114 function, or implementation function, and the best that you can do is to
3115 remove the @code{leaf} attribute or mark all such static variables
3116 @code{volatile}. Lastly, for ELF-based systems that support symbol
3117 interposition, care should be taken that functions defined in the
3118 current compilation unit do not unexpectedly interpose other symbols
3119 based on the defined standards mode and defined feature test macros;
3120 otherwise an inadvertent callback would be added.
3122 The attribute has no effect on functions defined within the current
3123 compilation unit. This is to allow easy merging of multiple compilation
3124 units into one, for example, by using the link-time optimization. For
3125 this reason the attribute is not allowed on types to annotate indirect
3129 @cindex @code{malloc} function attribute
3130 @cindex functions that behave like malloc
3131 This tells the compiler that a function is @code{malloc}-like, i.e.,
3132 that the pointer @var{P} returned by the function cannot alias any
3133 other pointer valid when the function returns, and moreover no
3134 pointers to valid objects occur in any storage addressed by @var{P}.
3136 Using this attribute can improve optimization. Compiler predicts
3137 that a function with the attribute returns non-null in most cases.
3139 @code{malloc} and @code{calloc} have this property because they return
3140 a pointer to uninitialized or zeroed-out storage. However, functions
3141 like @code{realloc} do not have this property, as they can return a
3142 pointer to storage containing pointers.
3145 @cindex @code{no_icf} function attribute
3146 This function attribute prevents a functions from being merged with another
3147 semantically equivalent function.
3149 @item no_instrument_function
3150 @cindex @code{no_instrument_function} function attribute
3151 @opindex finstrument-functions
3154 If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are
3155 given, profiling function calls are
3156 generated at entry and exit of most user-compiled functions.
3157 Functions with this attribute are not so instrumented.
3159 @item no_profile_instrument_function
3160 @cindex @code{no_profile_instrument_function} function attribute
3161 The @code{no_profile_instrument_function} attribute on functions is used
3162 to inform the compiler that it should not process any profile feedback based
3163 optimization code instrumentation.
3166 @cindex @code{no_reorder} function attribute
3167 Do not reorder functions or variables marked @code{no_reorder}
3168 against each other or top level assembler statements the executable.
3169 The actual order in the program will depend on the linker command
3170 line. Static variables marked like this are also not removed.
3171 This has a similar effect
3172 as the @option{-fno-toplevel-reorder} option, but only applies to the
3175 @item no_sanitize ("@var{sanitize_option}")
3176 @cindex @code{no_sanitize} function attribute
3177 The @code{no_sanitize} attribute on functions is used
3178 to inform the compiler that it should not do sanitization of all options
3179 mentioned in @var{sanitize_option}. A list of values acceptable by
3180 @option{-fsanitize} option can be provided.
3183 void __attribute__ ((no_sanitize ("alignment", "object-size")))
3184 f () @{ /* @r{Do something.} */; @}
3185 void __attribute__ ((no_sanitize ("alignment,object-size")))
3186 g () @{ /* @r{Do something.} */; @}
3189 @item no_sanitize_address
3190 @itemx no_address_safety_analysis
3191 @cindex @code{no_sanitize_address} function attribute
3192 The @code{no_sanitize_address} attribute on functions is used
3193 to inform the compiler that it should not instrument memory accesses
3194 in the function when compiling with the @option{-fsanitize=address} option.
3195 The @code{no_address_safety_analysis} is a deprecated alias of the
3196 @code{no_sanitize_address} attribute, new code should use
3197 @code{no_sanitize_address}.
3199 @item no_sanitize_thread
3200 @cindex @code{no_sanitize_thread} function attribute
3201 The @code{no_sanitize_thread} attribute on functions is used
3202 to inform the compiler that it should not instrument memory accesses
3203 in the function when compiling with the @option{-fsanitize=thread} option.
3205 @item no_sanitize_undefined
3206 @cindex @code{no_sanitize_undefined} function attribute
3207 The @code{no_sanitize_undefined} attribute on functions is used
3208 to inform the compiler that it should not check for undefined behavior
3209 in the function when compiling with the @option{-fsanitize=undefined} option.
3211 @item no_split_stack
3212 @cindex @code{no_split_stack} function attribute
3213 @opindex fsplit-stack
3214 If @option{-fsplit-stack} is given, functions have a small
3215 prologue which decides whether to split the stack. Functions with the
3216 @code{no_split_stack} attribute do not have that prologue, and thus
3217 may run with only a small amount of stack space available.
3219 @item no_stack_limit
3220 @cindex @code{no_stack_limit} function attribute
3221 This attribute locally overrides the @option{-fstack-limit-register}
3222 and @option{-fstack-limit-symbol} command-line options; it has the effect
3223 of disabling stack limit checking in the function it applies to.
3226 @cindex @code{noclone} function attribute
3227 This function attribute prevents a function from being considered for
3228 cloning---a mechanism that produces specialized copies of functions
3229 and which is (currently) performed by interprocedural constant
3233 @cindex @code{noinline} function attribute
3234 This function attribute prevents a function from being considered for
3236 @c Don't enumerate the optimizations by name here; we try to be
3237 @c future-compatible with this mechanism.
3238 If the function does not have side effects, there are optimizations
3239 other than inlining that cause function calls to be optimized away,
3240 although the function call is live. To keep such calls from being
3247 (@pxref{Extended Asm}) in the called function, to serve as a special
3251 @cindex @code{noipa} function attribute
3252 Disable interprocedural optimizations between the function with this
3253 attribute and its callers, as if the body of the function is not available
3254 when optimizing callers and the callers are unavailable when optimizing
3255 the body. This attribute implies @code{noinline}, @code{noclone} and
3256 @code{no_icf} attributes. However, this attribute is not equivalent
3257 to a combination of other attributes, because its purpose is to suppress
3258 existing and future optimizations employing interprocedural analysis,
3259 including those that do not have an attribute suitable for disabling
3260 them individually. This attribute is supported mainly for the purpose
3261 of testing the compiler.
3264 @itemx nonnull (@var{arg-index}, @dots{})
3265 @cindex @code{nonnull} function attribute
3266 @cindex functions with non-null pointer arguments
3267 The @code{nonnull} attribute may be applied to a function that takes at
3268 least one argument of a pointer type. It indicates that the referenced
3269 arguments must be non-null pointers. For instance, the declaration:
3273 my_memcpy (void *dest, const void *src, size_t len)
3274 __attribute__((nonnull (1, 2)));
3278 causes the compiler to check that, in calls to @code{my_memcpy},
3279 arguments @var{dest} and @var{src} are non-null. If the compiler
3280 determines that a null pointer is passed in an argument slot marked
3281 as non-null, and the @option{-Wnonnull} option is enabled, a warning
3282 is issued. @xref{Warning Options}. Unless disabled by
3283 the @option{-fno-delete-null-pointer-checks} option the compiler may
3284 also perform optimizations based on the knowledge that certain function
3285 arguments cannot be null. In addition,
3286 the @option{-fisolate-erroneous-paths-attribute} option can be specified
3287 to have GCC transform calls with null arguments to non-null functions
3288 into traps. @xref{Optimize Options}.
3290 If no @var{arg-index} is given to the @code{nonnull} attribute,
3291 all pointer arguments are marked as non-null. To illustrate, the
3292 following declaration is equivalent to the previous example:
3296 my_memcpy (void *dest, const void *src, size_t len)
3297 __attribute__((nonnull));
3301 @cindex @code{noplt} function attribute
3302 The @code{noplt} attribute is the counterpart to option @option{-fno-plt}.
3303 Calls to functions marked with this attribute in position-independent code
3308 /* Externally defined function foo. */
3309 int foo () __attribute__ ((noplt));
3312 main (/* @r{@dots{}} */)
3321 The @code{noplt} attribute on function @code{foo}
3322 tells the compiler to assume that
3323 the function @code{foo} is externally defined and that the call to
3324 @code{foo} must avoid the PLT
3325 in position-independent code.
3327 In position-dependent code, a few targets also convert calls to
3328 functions that are marked to not use the PLT to use the GOT instead.
3331 @cindex @code{noreturn} function attribute
3332 @cindex functions that never return
3333 A few standard library functions, such as @code{abort} and @code{exit},
3334 cannot return. GCC knows this automatically. Some programs define
3335 their own functions that never return. You can declare them
3336 @code{noreturn} to tell the compiler this fact. For example,
3340 void fatal () __attribute__ ((noreturn));
3343 fatal (/* @r{@dots{}} */)
3345 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
3351 The @code{noreturn} keyword tells the compiler to assume that
3352 @code{fatal} cannot return. It can then optimize without regard to what
3353 would happen if @code{fatal} ever did return. This makes slightly
3354 better code. More importantly, it helps avoid spurious warnings of
3355 uninitialized variables.
3357 The @code{noreturn} keyword does not affect the exceptional path when that
3358 applies: a @code{noreturn}-marked function may still return to the caller
3359 by throwing an exception or calling @code{longjmp}.
3361 In order to preserve backtraces, GCC will never turn calls to
3362 @code{noreturn} functions into tail calls.
3364 Do not assume that registers saved by the calling function are
3365 restored before calling the @code{noreturn} function.
3367 It does not make sense for a @code{noreturn} function to have a return
3368 type other than @code{void}.
3371 @cindex @code{nothrow} function attribute
3372 The @code{nothrow} attribute is used to inform the compiler that a
3373 function cannot throw an exception. For example, most functions in
3374 the standard C library can be guaranteed not to throw an exception
3375 with the notable exceptions of @code{qsort} and @code{bsearch} that
3376 take function pointer arguments.
3378 @item optimize (@var{level}, @dots{})
3379 @item optimize (@var{string}, @dots{})
3380 @cindex @code{optimize} function attribute
3381 The @code{optimize} attribute is used to specify that a function is to
3382 be compiled with different optimization options than specified on the
3383 command line. Valid arguments are constant non-negative integers and
3384 strings. Each numeric argument specifies an optimization @var{level}.
3385 Each @var{string} argument consists of one or more comma-separated
3386 substrings. Each substring that begins with the letter @code{O} refers
3387 to an optimization option such as @option{-O0} or @option{-Os}. Other
3388 substrings are taken as suffixes to the @code{-f} prefix jointly
3389 forming the name of an optimization option. @xref{Optimize Options}.
3391 @samp{#pragma GCC optimize} can be used to set optimization options
3392 for more than one function. @xref{Function Specific Option Pragmas},
3393 for details about the pragma.
3395 Providing multiple strings as arguments separated by commas to specify
3396 multiple options is equivalent to separating the option suffixes with
3397 a comma (@samp{,}) within a single string. Spaces are not permitted
3400 Not every optimization option that starts with the @var{-f} prefix
3401 specified by the attribute necessarily has an effect on the function.
3402 The @code{optimize} attribute should be used for debugging purposes only.
3403 It is not suitable in production code.
3405 @item patchable_function_entry
3406 @cindex @code{patchable_function_entry} function attribute
3407 @cindex extra NOP instructions at the function entry point
3408 In case the target's text segment can be made writable at run time by
3409 any means, padding the function entry with a number of NOPs can be
3410 used to provide a universal tool for instrumentation.
3412 The @code{patchable_function_entry} function attribute can be used to
3413 change the number of NOPs to any desired value. The two-value syntax
3414 is the same as for the command-line switch
3415 @option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with
3416 the function entry point before the @var{M}th NOP instruction.
3417 @var{M} defaults to 0 if omitted e.g.@: function entry point is before
3420 If patchable function entries are enabled globally using the command-line
3421 option @option{-fpatchable-function-entry=N,M}, then you must disable
3422 instrumentation on all functions that are part of the instrumentation
3423 framework with the attribute @code{patchable_function_entry (0)}
3424 to prevent recursion.
3427 @cindex @code{pure} function attribute
3428 @cindex functions that have no side effects
3430 Calls to functions that have no observable effects on the state of
3431 the program other than to return a value may lend themselves to optimizations
3432 such as common subexpression elimination. Declaring such functions with
3433 the @code{pure} attribute allows GCC to avoid emitting some calls in repeated
3434 invocations of the function with the same argument values.
3436 The @code{pure} attribute prohibits a function from modifying the state
3437 of the program that is observable by means other than inspecting
3438 the function's return value. However, functions declared with the @code{pure}
3439 attribute can safely read any non-volatile objects, and modify the value of
3440 objects in a way that does not affect their return value or the observable
3441 state of the program.
3446 int hash (char *) __attribute__ ((pure));
3450 tells GCC that subsequent calls to the function @code{hash} with the same
3451 string can be replaced by the result of the first call provided the state
3452 of the program observable by @code{hash}, including the contents of the array
3453 itself, does not change in between. Even though @code{hash} takes a non-const
3454 pointer argument it must not modify the array it points to, or any other object
3455 whose value the rest of the program may depend on. However, the caller may
3456 safely change the contents of the array between successive calls to
3457 the function (doing so disables the optimization). The restriction also
3458 applies to member objects referenced by the @code{this} pointer in C++
3459 non-static member functions.
3461 Some common examples of pure functions are @code{strlen} or @code{memcmp}.
3462 Interesting non-pure functions are functions with infinite loops or those
3463 depending on volatile memory or other system resource, that may change between
3464 consecutive calls (such as the standard C @code{feof} function in
3465 a multithreading environment).
3467 The @code{pure} attribute imposes similar but looser restrictions on
3468 a function's definition than the @code{const} attribute: @code{pure}
3469 allows the function to read any non-volatile memory, even if it changes
3470 in between successive invocations of the function. Declaring the same
3471 function with both the @code{pure} and the @code{const} attribute is
3472 diagnosed. Because a pure function cannot have any observable side
3473 effects it does not make sense for such a function to return @code{void}.
3474 Declaring such a function is diagnosed.
3476 @item returns_nonnull
3477 @cindex @code{returns_nonnull} function attribute
3478 The @code{returns_nonnull} attribute specifies that the function
3479 return value should be a non-null pointer. For instance, the declaration:
3483 mymalloc (size_t len) __attribute__((returns_nonnull));
3487 lets the compiler optimize callers based on the knowledge
3488 that the return value will never be null.
3491 @cindex @code{returns_twice} function attribute
3492 @cindex functions that return more than once
3493 The @code{returns_twice} attribute tells the compiler that a function may
3494 return more than one time. The compiler ensures that all registers
3495 are dead before calling such a function and emits a warning about
3496 the variables that may be clobbered after the second return from the
3497 function. Examples of such functions are @code{setjmp} and @code{vfork}.
3498 The @code{longjmp}-like counterpart of such function, if any, might need
3499 to be marked with the @code{noreturn} attribute.
3501 @item section ("@var{section-name}")
3502 @cindex @code{section} function attribute
3503 @cindex functions in arbitrary sections
3504 Normally, the compiler places the code it generates in the @code{text} section.
3505 Sometimes, however, you need additional sections, or you need certain
3506 particular functions to appear in special sections. The @code{section}
3507 attribute specifies that a function lives in a particular section.
3508 For example, the declaration:
3511 extern void foobar (void) __attribute__ ((section ("bar")));
3515 puts the function @code{foobar} in the @code{bar} section.
3517 Some file formats do not support arbitrary sections so the @code{section}
3518 attribute is not available on all platforms.
3519 If you need to map the entire contents of a module to a particular
3520 section, consider using the facilities of the linker instead.
3523 @itemx sentinel (@var{position})
3524 @cindex @code{sentinel} function attribute
3525 This function attribute indicates that an argument in a call to the function
3526 is expected to be an explicit @code{NULL}. The attribute is only valid on
3527 variadic functions. By default, the sentinel is expected to be the last
3528 argument of the function call. If the optional @var{position} argument
3529 is specified to the attribute, the sentinel must be located at
3530 @var{position} counting backwards from the end of the argument list.
3533 __attribute__ ((sentinel))
3535 __attribute__ ((sentinel(0)))
3538 The attribute is automatically set with a position of 0 for the built-in
3539 functions @code{execl} and @code{execlp}. The built-in function
3540 @code{execle} has the attribute set with a position of 1.
3542 A valid @code{NULL} in this context is defined as zero with any object
3543 pointer type. If your system defines the @code{NULL} macro with
3544 an integer type then you need to add an explicit cast. During
3545 installation GCC replaces the system @code{<stddef.h>} header with
3546 a copy that redefines NULL appropriately.
3548 The warnings for missing or incorrect sentinels are enabled with
3552 @itemx simd("@var{mask}")
3553 @cindex @code{simd} function attribute
3554 This attribute enables creation of one or more function versions that
3555 can process multiple arguments using SIMD instructions from a
3556 single invocation. Specifying this attribute allows compiler to
3557 assume that such versions are available at link time (provided
3558 in the same or another translation unit). Generated versions are
3559 target-dependent and described in the corresponding Vector ABI document. For
3560 x86_64 target this document can be found
3561 @w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}.
3563 The optional argument @var{mask} may have the value
3564 @code{notinbranch} or @code{inbranch},
3565 and instructs the compiler to generate non-masked or masked
3566 clones correspondingly. By default, all clones are generated.
3568 If the attribute is specified and @code{#pragma omp declare simd} is
3569 present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd}
3570 switch is specified, then the attribute is ignored.
3573 @cindex @code{stack_protect} function attribute
3574 This attribute adds stack protection code to the function if
3575 flags @option{-fstack-protector}, @option{-fstack-protector-strong}
3576 or @option{-fstack-protector-explicit} are set.
3578 @item target (@var{string}, @dots{})
3579 @cindex @code{target} function attribute
3580 Multiple target back ends implement the @code{target} attribute
3581 to specify that a function is to
3582 be compiled with different target options than specified on the
3583 command line. One or more strings can be provided as arguments.
3584 Each string consists of one or more comma-separated suffixes to
3585 the @code{-m} prefix jointly forming the name of a machine-dependent
3586 option. @xref{Submodel Options,,Machine-Dependent Options}.
3588 The @code{target} attribute can be used for instance to have a function
3589 compiled with a different ISA (instruction set architecture) than the
3590 default. @samp{#pragma GCC target} can be used to specify target-specific
3591 options for more than one function. @xref{Function Specific Option Pragmas},
3592 for details about the pragma.
3594 For instance, on an x86, you could declare one function with the
3595 @code{target("sse4.1,arch=core2")} attribute and another with
3596 @code{target("sse4a,arch=amdfam10")}. This is equivalent to
3597 compiling the first function with @option{-msse4.1} and
3598 @option{-march=core2} options, and the second function with
3599 @option{-msse4a} and @option{-march=amdfam10} options. It is up to you
3600 to make sure that a function is only invoked on a machine that
3601 supports the particular ISA it is compiled for (for example by using
3602 @code{cpuid} on x86 to determine what feature bits and architecture
3606 int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
3607 int sse3_func (void) __attribute__ ((__target__ ("sse3")));
3610 Providing multiple strings as arguments separated by commas to specify
3611 multiple options is equivalent to separating the option suffixes with
3612 a comma (@samp{,}) within a single string. Spaces are not permitted
3615 The options supported are specific to each target; refer to @ref{x86
3616 Function Attributes}, @ref{PowerPC Function Attributes},
3617 @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
3618 @ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
3621 @item target_clones (@var{options})
3622 @cindex @code{target_clones} function attribute
3623 The @code{target_clones} attribute is used to specify that a function
3624 be cloned into multiple versions compiled with different target options
3625 than specified on the command line. The supported options and restrictions
3626 are the same as for @code{target} attribute.
3628 For instance, on an x86, you could compile a function with
3629 @code{target_clones("sse4.1,avx")}. GCC creates two function clones,
3630 one compiled with @option{-msse4.1} and another with @option{-mavx}.
3632 On a PowerPC, you can compile a function with
3633 @code{target_clones("cpu=power9,default")}. GCC will create two
3634 function clones, one compiled with @option{-mcpu=power9} and another
3635 with the default options. GCC must be configured to use GLIBC 2.23 or
3636 newer in order to use the @code{target_clones} attribute.
3638 It also creates a resolver function (see
3639 the @code{ifunc} attribute above) that dynamically selects a clone
3640 suitable for current architecture. The resolver is created only if there
3641 is a usage of a function with @code{target_clones} attribute.
3644 @cindex @code{unused} function attribute
3645 This attribute, attached to a function, means that the function is meant
3646 to be possibly unused. GCC does not produce a warning for this
3650 @cindex @code{used} function attribute
3651 This attribute, attached to a function, means that code must be emitted
3652 for the function even if it appears that the function is not referenced.
3653 This is useful, for example, when the function is referenced only in
3656 When applied to a member function of a C++ class template, the
3657 attribute also means that the function is instantiated if the
3658 class itself is instantiated.
3660 @item visibility ("@var{visibility_type}")
3661 @cindex @code{visibility} function attribute
3662 This attribute affects the linkage of the declaration to which it is attached.
3663 It can be applied to variables (@pxref{Common Variable Attributes}) and types
3664 (@pxref{Common Type Attributes}) as well as functions.
3666 There are four supported @var{visibility_type} values: default,
3667 hidden, protected or internal visibility.
3670 void __attribute__ ((visibility ("protected")))
3671 f () @{ /* @r{Do something.} */; @}
3672 int i __attribute__ ((visibility ("hidden")));
3675 The possible values of @var{visibility_type} correspond to the
3676 visibility settings in the ELF gABI.
3679 @c keep this list of visibilities in alphabetical order.
3682 Default visibility is the normal case for the object file format.
3683 This value is available for the visibility attribute to override other
3684 options that may change the assumed visibility of entities.
3686 On ELF, default visibility means that the declaration is visible to other
3687 modules and, in shared libraries, means that the declared entity may be
3690 On Darwin, default visibility means that the declaration is visible to
3693 Default visibility corresponds to ``external linkage'' in the language.
3696 Hidden visibility indicates that the entity declared has a new
3697 form of linkage, which we call ``hidden linkage''. Two
3698 declarations of an object with hidden linkage refer to the same object
3699 if they are in the same shared object.
3702 Internal visibility is like hidden visibility, but with additional
3703 processor specific semantics. Unless otherwise specified by the
3704 psABI, GCC defines internal visibility to mean that a function is
3705 @emph{never} called from another module. Compare this with hidden
3706 functions which, while they cannot be referenced directly by other
3707 modules, can be referenced indirectly via function pointers. By
3708 indicating that a function cannot be called from outside the module,
3709 GCC may for instance omit the load of a PIC register since it is known
3710 that the calling function loaded the correct value.
3713 Protected visibility is like default visibility except that it
3714 indicates that references within the defining module bind to the
3715 definition in that module. That is, the declared entity cannot be
3716 overridden by another module.
3720 All visibilities are supported on many, but not all, ELF targets
3721 (supported when the assembler supports the @samp{.visibility}
3722 pseudo-op). Default visibility is supported everywhere. Hidden
3723 visibility is supported on Darwin targets.
3725 The visibility attribute should be applied only to declarations that
3726 would otherwise have external linkage. The attribute should be applied
3727 consistently, so that the same entity should not be declared with
3728 different settings of the attribute.
3730 In C++, the visibility attribute applies to types as well as functions
3731 and objects, because in C++ types have linkage. A class must not have
3732 greater visibility than its non-static data member types and bases,
3733 and class members default to the visibility of their class. Also, a
3734 declaration without explicit visibility is limited to the visibility
3737 In C++, you can mark member functions and static member variables of a
3738 class with the visibility attribute. This is useful if you know a
3739 particular method or static member variable should only be used from
3740 one shared object; then you can mark it hidden while the rest of the
3741 class has default visibility. Care must be taken to avoid breaking
3742 the One Definition Rule; for example, it is usually not useful to mark
3743 an inline method as hidden without marking the whole class as hidden.
3745 A C++ namespace declaration can also have the visibility attribute.
3748 namespace nspace1 __attribute__ ((visibility ("protected")))
3749 @{ /* @r{Do something.} */; @}
3752 This attribute applies only to the particular namespace body, not to
3753 other definitions of the same namespace; it is equivalent to using
3754 @samp{#pragma GCC visibility} before and after the namespace
3755 definition (@pxref{Visibility Pragmas}).
3757 In C++, if a template argument has limited visibility, this
3758 restriction is implicitly propagated to the template instantiation.
3759 Otherwise, template instantiations and specializations default to the
3760 visibility of their template.
3762 If both the template and enclosing class have explicit visibility, the
3763 visibility from the template is used.
3765 @item warn_unused_result
3766 @cindex @code{warn_unused_result} function attribute
3767 The @code{warn_unused_result} attribute causes a warning to be emitted
3768 if a caller of the function with this attribute does not use its
3769 return value. This is useful for functions where not checking
3770 the result is either a security problem or always a bug, such as
3774 int fn () __attribute__ ((warn_unused_result));
3777 if (fn () < 0) return -1;
3784 results in warning on line 5.
3787 @cindex @code{weak} function attribute
3788 The @code{weak} attribute causes the declaration to be emitted as a weak
3789 symbol rather than a global. This is primarily useful in defining
3790 library functions that can be overridden in user code, though it can
3791 also be used with non-function declarations. Weak symbols are supported
3792 for ELF targets, and also for a.out targets when using the GNU assembler
3796 @itemx weakref ("@var{target}")
3797 @cindex @code{weakref} function attribute
3798 The @code{weakref} attribute marks a declaration as a weak reference.
3799 Without arguments, it should be accompanied by an @code{alias} attribute
3800 naming the target symbol. Optionally, the @var{target} may be given as
3801 an argument to @code{weakref} itself. In either case, @code{weakref}
3802 implicitly marks the declaration as @code{weak}. Without a
3803 @var{target}, given as an argument to @code{weakref} or to @code{alias},
3804 @code{weakref} is equivalent to @code{weak}.
3807 static int x() __attribute__ ((weakref ("y")));
3808 /* is equivalent to... */
3809 static int x() __attribute__ ((weak, weakref, alias ("y")));
3811 static int x() __attribute__ ((weakref));
3812 static int x() __attribute__ ((alias ("y")));
3815 A weak reference is an alias that does not by itself require a
3816 definition to be given for the target symbol. If the target symbol is
3817 only referenced through weak references, then it becomes a @code{weak}
3818 undefined symbol. If it is directly referenced, however, then such
3819 strong references prevail, and a definition is required for the
3820 symbol, not necessarily in the same translation unit.
3822 The effect is equivalent to moving all references to the alias to a
3823 separate translation unit, renaming the alias to the aliased symbol,
3824 declaring it as weak, compiling the two separate translation units and
3825 performing a link with relocatable output (ie: @code{ld -r}) on them.
3827 At present, a declaration to which @code{weakref} is attached can
3828 only be @code{static}.
3833 @c This is the end of the target-independent attribute table
3835 @node AArch64 Function Attributes
3836 @subsection AArch64 Function Attributes
3838 The following target-specific function attributes are available for the
3839 AArch64 target. For the most part, these options mirror the behavior of
3840 similar command-line options (@pxref{AArch64 Options}), but on a
3844 @item general-regs-only
3845 @cindex @code{general-regs-only} function attribute, AArch64
3846 Indicates that no floating-point or Advanced SIMD registers should be
3847 used when generating code for this function. If the function explicitly
3848 uses floating-point code, then the compiler gives an error. This is
3849 the same behavior as that of the command-line option
3850 @option{-mgeneral-regs-only}.
3852 @item fix-cortex-a53-835769
3853 @cindex @code{fix-cortex-a53-835769} function attribute, AArch64
3854 Indicates that the workaround for the Cortex-A53 erratum 835769 should be
3855 applied to this function. To explicitly disable the workaround for this
3856 function specify the negated form: @code{no-fix-cortex-a53-835769}.
3857 This corresponds to the behavior of the command line options
3858 @option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
3861 @cindex @code{cmodel=} function attribute, AArch64
3862 Indicates that code should be generated for a particular code model for
3863 this function. The behavior and permissible arguments are the same as
3864 for the command line option @option{-mcmodel=}.
3867 @itemx no-strict-align
3868 @cindex @code{strict-align} function attribute, AArch64
3869 @code{strict-align} indicates that the compiler should not assume that unaligned
3870 memory references are handled by the system. To allow the compiler to assume
3871 that aligned memory references are handled by the system, the inverse attribute
3872 @code{no-strict-align} can be specified. The behavior is same as for the
3873 command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
3875 @item omit-leaf-frame-pointer
3876 @cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
3877 Indicates that the frame pointer should be omitted for a leaf function call.
3878 To keep the frame pointer, the inverse attribute
3879 @code{no-omit-leaf-frame-pointer} can be specified. These attributes have
3880 the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
3881 and @option{-mno-omit-leaf-frame-pointer}.
3884 @cindex @code{tls-dialect=} function attribute, AArch64
3885 Specifies the TLS dialect to use for this function. The behavior and
3886 permissible arguments are the same as for the command-line option
3887 @option{-mtls-dialect=}.
3890 @cindex @code{arch=} function attribute, AArch64
3891 Specifies the architecture version and architectural extensions to use
3892 for this function. The behavior and permissible arguments are the same as
3893 for the @option{-march=} command-line option.
3896 @cindex @code{tune=} function attribute, AArch64
3897 Specifies the core for which to tune the performance of this function.
3898 The behavior and permissible arguments are the same as for the @option{-mtune=}
3899 command-line option.
3902 @cindex @code{cpu=} function attribute, AArch64
3903 Specifies the core for which to tune the performance of this function and also
3904 whose architectural features to use. The behavior and valid arguments are the
3905 same as for the @option{-mcpu=} command-line option.
3907 @item sign-return-address
3908 @cindex @code{sign-return-address} function attribute, AArch64
3909 Select the function scope on which return address signing will be applied. The
3910 behavior and permissible arguments are the same as for the command-line option
3911 @option{-msign-return-address=}. The default value is @code{none}.
3915 The above target attributes can be specified as follows:
3918 __attribute__((target("@var{attr-string}")))
3926 where @code{@var{attr-string}} is one of the attribute strings specified above.
3928 Additionally, the architectural extension string may be specified on its
3929 own. This can be used to turn on and off particular architectural extensions
3930 without having to specify a particular architecture version or core. Example:
3933 __attribute__((target("+crc+nocrypto")))
3941 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
3942 extension and disables the @code{crypto} extension for the function @code{foo}
3943 without modifying an existing @option{-march=} or @option{-mcpu} option.
3945 Multiple target function attributes can be specified by separating them with
3946 a comma. For example:
3948 __attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
3956 is valid and compiles function @code{foo} for ARMv8-A with @code{crc}
3957 and @code{crypto} extensions and tunes it for @code{cortex-a53}.
3959 @subsubsection Inlining rules
3960 Specifying target attributes on individual functions or performing link-time
3961 optimization across translation units compiled with different target options
3962 can affect function inlining rules:
3964 In particular, a caller function can inline a callee function only if the
3965 architectural features available to the callee are a subset of the features
3966 available to the caller.
3967 For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
3968 or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
3969 can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
3970 because the all the architectural features that function @code{bar} requires
3971 are available to function @code{foo}. Conversely, function @code{bar} cannot
3972 inline function @code{foo}.
3974 Additionally inlining a function compiled with @option{-mstrict-align} into a
3975 function compiled without @code{-mstrict-align} is not allowed.
3976 However, inlining a function compiled without @option{-mstrict-align} into a
3977 function compiled with @option{-mstrict-align} is allowed.
3979 Note that CPU tuning options and attributes such as the @option{-mcpu=},
3980 @option{-mtune=} do not inhibit inlining unless the CPU specified by the
3981 @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
3982 architectural feature rules specified above.
3984 @node AMD GCN Function Attributes
3985 @subsection AMD GCN Function Attributes
3987 These function attributes are supported by the AMD GCN back end:
3990 @item amdgpu_hsa_kernel
3991 @cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN
3992 This attribute indicates that the corresponding function should be compiled as
3993 a kernel function, that is an entry point that can be invoked from the host
3994 via the HSA runtime library. By default functions are only callable only from
3995 other GCN functions.
3997 This attribute is implicitly applied to any function named @code{main}, using
4000 Kernel functions may return an integer value, which will be written to a
4001 conventional place within the HSA "kernargs" region.
4003 The attribute parameters configure what values are passed into the kernel
4004 function by the GPU drivers, via the initial register state. Some values are
4005 used by the compiler, and therefore forced on. Enabling other options may
4006 break assumptions in the compiler and/or run-time libraries.
4009 @item private_segment_buffer
4010 Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to
4014 Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the
4018 Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address
4021 @item kernarg_segment_ptr
4022 Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to
4023 locate the kernel arguments, "kernargs").
4026 Set @code{enable_sgpr_dispatch_id} flag.
4028 @item flat_scratch_init
4029 Set @code{enable_sgpr_flat_scratch_init} flag.
4031 @item private_segment_size
4032 Set @code{enable_sgpr_private_segment_size} flag.
4034 @item grid_workgroup_count_X
4035 Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to
4036 use OpenACC/OpenMP).
4038 @item grid_workgroup_count_Y
4039 Set @code{enable_sgpr_grid_workgroup_count_y} flag.
4041 @item grid_workgroup_count_Z
4042 Set @code{enable_sgpr_grid_workgroup_count_z} flag.
4044 @item workgroup_id_X
4045 Set @code{enable_sgpr_workgroup_id_x} flag.
4047 @item workgroup_id_Y
4048 Set @code{enable_sgpr_workgroup_id_y} flag.
4050 @item workgroup_id_Z
4051 Set @code{enable_sgpr_workgroup_id_z} flag.
4053 @item workgroup_info
4054 Set @code{enable_sgpr_workgroup_info} flag.
4056 @item private_segment_wave_offset
4057 Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on
4058 (required to locate the stack).
4060 @item work_item_id_X
4061 Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled).
4063 @item work_item_id_Y
4064 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable
4067 @item work_item_id_Z
4068 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use
4074 @node ARC Function Attributes
4075 @subsection ARC Function Attributes
4077 These function attributes are supported by the ARC back end:
4081 @cindex @code{interrupt} function attribute, ARC
4082 Use this attribute to indicate
4083 that the specified function is an interrupt handler. The compiler generates
4084 function entry and exit sequences suitable for use in an interrupt handler
4085 when this attribute is present.
4087 On the ARC, you must specify the kind of interrupt to be handled
4088 in a parameter to the interrupt attribute like this:
4091 void f () __attribute__ ((interrupt ("ilink1")));
4094 Permissible values for this parameter are: @w{@code{ilink1}} and
4100 @cindex @code{long_call} function attribute, ARC
4101 @cindex @code{medium_call} function attribute, ARC
4102 @cindex @code{short_call} function attribute, ARC
4103 @cindex indirect calls, ARC
4104 These attributes specify how a particular function is called.
4105 These attributes override the
4106 @option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
4107 command-line switches and @code{#pragma long_calls} settings.
4109 For ARC, a function marked with the @code{long_call} attribute is
4110 always called using register-indirect jump-and-link instructions,
4111 thereby enabling the called function to be placed anywhere within the
4112 32-bit address space. A function marked with the @code{medium_call}
4113 attribute will always be close enough to be called with an unconditional
4114 branch-and-link instruction, which has a 25-bit offset from
4115 the call site. A function marked with the @code{short_call}
4116 attribute will always be close enough to be called with a conditional
4117 branch-and-link instruction, which has a 21-bit offset from
4121 @cindex @code{jli_always} function attribute, ARC
4122 Forces a particular function to be called using @code{jli}
4123 instruction. The @code{jli} instruction makes use of a table stored
4124 into @code{.jlitab} section, which holds the location of the functions
4125 which are addressed using this instruction.
4128 @cindex @code{jli_fixed} function attribute, ARC
4129 Identical like the above one, but the location of the function in the
4130 @code{jli} table is known and given as an attribute parameter.
4133 @cindex @code{secure_call} function attribute, ARC
4134 This attribute allows one to mark secure-code functions that are
4135 callable from normal mode. The location of the secure call function
4136 into the @code{sjli} table needs to be passed as argument.
4140 @node ARM Function Attributes
4141 @subsection ARM Function Attributes
4143 These function attributes are supported for ARM targets:
4147 @cindex @code{interrupt} function attribute, ARM
4148 Use this attribute to indicate
4149 that the specified function is an interrupt handler. The compiler generates
4150 function entry and exit sequences suitable for use in an interrupt handler
4151 when this attribute is present.
4153 You can specify the kind of interrupt to be handled by
4154 adding an optional parameter to the interrupt attribute like this:
4157 void f () __attribute__ ((interrupt ("IRQ")));
4161 Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
4162 @code{SWI}, @code{ABORT} and @code{UNDEF}.
4164 On ARMv7-M the interrupt type is ignored, and the attribute means the function
4165 may be called with a word-aligned stack pointer.
4168 @cindex @code{isr} function attribute, ARM
4169 Use this attribute on ARM to write Interrupt Service Routines. This is an
4170 alias to the @code{interrupt} attribute above.
4174 @cindex @code{long_call} function attribute, ARM
4175 @cindex @code{short_call} function attribute, ARM
4176 @cindex indirect calls, ARM
4177 These attributes specify how a particular function is called.
4178 These attributes override the
4179 @option{-mlong-calls} (@pxref{ARM Options})
4180 command-line switch and @code{#pragma long_calls} settings. For ARM, the
4181 @code{long_call} attribute indicates that the function might be far
4182 away from the call site and require a different (more expensive)
4183 calling sequence. The @code{short_call} attribute always places
4184 the offset to the function from the call site into the @samp{BL}
4185 instruction directly.
4188 @cindex @code{naked} function attribute, ARM
4189 This attribute allows the compiler to construct the
4190 requisite function declaration, while allowing the body of the
4191 function to be assembly code. The specified function will not have
4192 prologue/epilogue sequences generated by the compiler. Only basic
4193 @code{asm} statements can safely be included in naked functions
4194 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4195 basic @code{asm} and C code may appear to work, they cannot be
4196 depended upon to work reliably and are not supported.
4199 @cindex @code{pcs} function attribute, ARM
4201 The @code{pcs} attribute can be used to control the calling convention
4202 used for a function on ARM. The attribute takes an argument that specifies
4203 the calling convention to use.
4205 When compiling using the AAPCS ABI (or a variant of it) then valid
4206 values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
4207 order to use a variant other than @code{"aapcs"} then the compiler must
4208 be permitted to use the appropriate co-processor registers (i.e., the
4209 VFP registers must be available in order to use @code{"aapcs-vfp"}).
4213 /* Argument passed in r0, and result returned in r0+r1. */
4214 double f2d (float) __attribute__((pcs("aapcs")));
4217 Variadic functions always use the @code{"aapcs"} calling convention and
4218 the compiler rejects attempts to specify an alternative.
4220 @item target (@var{options})
4221 @cindex @code{target} function attribute
4222 As discussed in @ref{Common Function Attributes}, this attribute
4223 allows specification of target-specific compilation options.
4225 On ARM, the following options are allowed:
4229 @cindex @code{target("thumb")} function attribute, ARM
4230 Force code generation in the Thumb (T16/T32) ISA, depending on the
4234 @cindex @code{target("arm")} function attribute, ARM
4235 Force code generation in the ARM (A32) ISA.
4237 Functions from different modes can be inlined in the caller's mode.
4240 @cindex @code{target("fpu=")} function attribute, ARM
4241 Specifies the fpu for which to tune the performance of this function.
4242 The behavior and permissible arguments are the same as for the @option{-mfpu=}
4243 command-line option.
4246 @cindex @code{arch=} function attribute, ARM
4247 Specifies the architecture version and architectural extensions to use
4248 for this function. The behavior and permissible arguments are the same as
4249 for the @option{-march=} command-line option.
4251 The above target attributes can be specified as follows:
4254 __attribute__((target("arch=armv8-a+crc")))
4262 Additionally, the architectural extension string may be specified on its
4263 own. This can be used to turn on and off particular architectural extensions
4264 without having to specify a particular architecture version or core. Example:
4267 __attribute__((target("+crc+nocrypto")))
4275 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
4276 extension and disables the @code{crypto} extension for the function @code{foo}
4277 without modifying an existing @option{-march=} or @option{-mcpu} option.
4283 @node AVR Function Attributes
4284 @subsection AVR Function Attributes
4286 These function attributes are supported by the AVR back end:
4290 @cindex @code{interrupt} function attribute, AVR
4291 Use this attribute to indicate
4292 that the specified function is an interrupt handler. The compiler generates
4293 function entry and exit sequences suitable for use in an interrupt handler
4294 when this attribute is present.
4296 On the AVR, the hardware globally disables interrupts when an
4297 interrupt is executed. The first instruction of an interrupt handler
4298 declared with this attribute is a @code{SEI} instruction to
4299 re-enable interrupts. See also the @code{signal} function attribute
4300 that does not insert a @code{SEI} instruction. If both @code{signal} and
4301 @code{interrupt} are specified for the same function, @code{signal}
4302 is silently ignored.
4305 @cindex @code{naked} function attribute, AVR
4306 This attribute allows the compiler to construct the
4307 requisite function declaration, while allowing the body of the
4308 function to be assembly code. The specified function will not have
4309 prologue/epilogue sequences generated by the compiler. Only basic
4310 @code{asm} statements can safely be included in naked functions
4311 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4312 basic @code{asm} and C code may appear to work, they cannot be
4313 depended upon to work reliably and are not supported.
4316 @cindex @code{no_gccisr} function attribute, AVR
4317 Do not use @code{__gcc_isr} pseudo instructions in a function with
4318 the @code{interrupt} or @code{signal} attribute aka. interrupt
4319 service routine (ISR).
4320 Use this attribute if the preamble of the ISR prologue should always read
4324 in __tmp_reg__, __SREG__
4328 and accordingly for the postamble of the epilogue --- no matter whether
4329 the mentioned registers are actually used in the ISR or not.
4330 Situations where you might want to use this attribute include:
4333 Code that (effectively) clobbers bits of @code{SREG} other than the
4334 @code{I}-flag by writing to the memory location of @code{SREG}.
4336 Code that uses inline assembler to jump to a different function which
4337 expects (parts of) the prologue code as outlined above to be present.
4339 To disable @code{__gcc_isr} generation for the whole compilation unit,
4340 there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}.
4344 @cindex @code{OS_main} function attribute, AVR
4345 @cindex @code{OS_task} function attribute, AVR
4346 On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
4347 do not save/restore any call-saved register in their prologue/epilogue.
4349 The @code{OS_main} attribute can be used when there @emph{is
4350 guarantee} that interrupts are disabled at the time when the function
4351 is entered. This saves resources when the stack pointer has to be
4352 changed to set up a frame for local variables.
4354 The @code{OS_task} attribute can be used when there is @emph{no
4355 guarantee} that interrupts are disabled at that time when the function
4356 is entered like for, e@.g@. task functions in a multi-threading operating
4357 system. In that case, changing the stack pointer register is
4358 guarded by save/clear/restore of the global interrupt enable flag.
4360 The differences to the @code{naked} function attribute are:
4362 @item @code{naked} functions do not have a return instruction whereas
4363 @code{OS_main} and @code{OS_task} functions have a @code{RET} or
4364 @code{RETI} return instruction.
4365 @item @code{naked} functions do not set up a frame for local variables
4366 or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
4371 @cindex @code{signal} function attribute, AVR
4372 Use this attribute on the AVR to indicate that the specified
4373 function is an interrupt handler. The compiler generates function
4374 entry and exit sequences suitable for use in an interrupt handler when this
4375 attribute is present.
4377 See also the @code{interrupt} function attribute.
4379 The AVR hardware globally disables interrupts when an interrupt is executed.
4380 Interrupt handler functions defined with the @code{signal} attribute
4381 do not re-enable interrupts. It is save to enable interrupts in a
4382 @code{signal} handler. This ``save'' only applies to the code
4383 generated by the compiler and not to the IRQ layout of the
4384 application which is responsibility of the application.
4386 If both @code{signal} and @code{interrupt} are specified for the same
4387 function, @code{signal} is silently ignored.
4390 @node Blackfin Function Attributes
4391 @subsection Blackfin Function Attributes
4393 These function attributes are supported by the Blackfin back end:
4397 @item exception_handler
4398 @cindex @code{exception_handler} function attribute
4399 @cindex exception handler functions, Blackfin
4400 Use this attribute on the Blackfin to indicate that the specified function
4401 is an exception handler. The compiler generates function entry and
4402 exit sequences suitable for use in an exception handler when this
4403 attribute is present.
4405 @item interrupt_handler
4406 @cindex @code{interrupt_handler} function attribute, Blackfin
4407 Use this attribute to
4408 indicate that the specified function is an interrupt handler. The compiler
4409 generates function entry and exit sequences suitable for use in an
4410 interrupt handler when this attribute is present.
4413 @cindex @code{kspisusp} function attribute, Blackfin
4414 @cindex User stack pointer in interrupts on the Blackfin
4415 When used together with @code{interrupt_handler}, @code{exception_handler}
4416 or @code{nmi_handler}, code is generated to load the stack pointer
4417 from the USP register in the function prologue.
4420 @cindex @code{l1_text} function attribute, Blackfin
4421 This attribute specifies a function to be placed into L1 Instruction
4422 SRAM@. The function is put into a specific section named @code{.l1.text}.
4423 With @option{-mfdpic}, function calls with a such function as the callee
4424 or caller uses inlined PLT.
4427 @cindex @code{l2} function attribute, Blackfin
4428 This attribute specifies a function to be placed into L2
4429 SRAM. The function is put into a specific section named
4430 @code{.l2.text}. With @option{-mfdpic}, callers of such functions use
4435 @cindex indirect calls, Blackfin
4436 @cindex @code{longcall} function attribute, Blackfin
4437 @cindex @code{shortcall} function attribute, Blackfin
4438 The @code{longcall} attribute
4439 indicates that the function might be far away from the call site and
4440 require a different (more expensive) calling sequence. The
4441 @code{shortcall} attribute indicates that the function is always close
4442 enough for the shorter calling sequence to be used. These attributes
4443 override the @option{-mlongcall} switch.
4446 @cindex @code{nesting} function attribute, Blackfin
4447 @cindex Allow nesting in an interrupt handler on the Blackfin processor
4448 Use this attribute together with @code{interrupt_handler},
4449 @code{exception_handler} or @code{nmi_handler} to indicate that the function
4450 entry code should enable nested interrupts or exceptions.
4453 @cindex @code{nmi_handler} function attribute, Blackfin
4454 @cindex NMI handler functions on the Blackfin processor
4455 Use this attribute on the Blackfin to indicate that the specified function
4456 is an NMI handler. The compiler generates function entry and
4457 exit sequences suitable for use in an NMI handler when this
4458 attribute is present.
4461 @cindex @code{saveall} function attribute, Blackfin
4462 @cindex save all registers on the Blackfin
4463 Use this attribute to indicate that
4464 all registers except the stack pointer should be saved in the prologue
4465 regardless of whether they are used or not.
4468 @node CR16 Function Attributes
4469 @subsection CR16 Function Attributes
4471 These function attributes are supported by the CR16 back end:
4475 @cindex @code{interrupt} function attribute, CR16
4476 Use this attribute to indicate
4477 that the specified function is an interrupt handler. The compiler generates
4478 function entry and exit sequences suitable for use in an interrupt handler
4479 when this attribute is present.
4482 @node C-SKY Function Attributes
4483 @subsection C-SKY Function Attributes
4485 These function attributes are supported by the C-SKY back end:
4490 @cindex @code{interrupt} function attribute, C-SKY
4491 @cindex @code{isr} function attribute, C-SKY
4492 Use these attributes to indicate that the specified function
4493 is an interrupt handler.
4494 The compiler generates function entry and exit sequences suitable for
4495 use in an interrupt handler when either of these attributes are present.
4497 Use of these options requires the @option{-mistack} command-line option
4498 to enable support for the necessary interrupt stack instructions. They
4499 are ignored with a warning otherwise. @xref{C-SKY Options}.
4502 @cindex @code{naked} function attribute, C-SKY
4503 This attribute allows the compiler to construct the
4504 requisite function declaration, while allowing the body of the
4505 function to be assembly code. The specified function will not have
4506 prologue/epilogue sequences generated by the compiler. Only basic
4507 @code{asm} statements can safely be included in naked functions
4508 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4509 basic @code{asm} and C code may appear to work, they cannot be
4510 depended upon to work reliably and are not supported.
4514 @node Epiphany Function Attributes
4515 @subsection Epiphany Function Attributes
4517 These function attributes are supported by the Epiphany back end:
4521 @cindex @code{disinterrupt} function attribute, Epiphany
4522 This attribute causes the compiler to emit
4523 instructions to disable interrupts for the duration of the given
4526 @item forwarder_section
4527 @cindex @code{forwarder_section} function attribute, Epiphany
4528 This attribute modifies the behavior of an interrupt handler.
4529 The interrupt handler may be in external memory which cannot be
4530 reached by a branch instruction, so generate a local memory trampoline
4531 to transfer control. The single parameter identifies the section where
4532 the trampoline is placed.
4535 @cindex @code{interrupt} function attribute, Epiphany
4536 Use this attribute to indicate
4537 that the specified function is an interrupt handler. The compiler generates
4538 function entry and exit sequences suitable for use in an interrupt handler
4539 when this attribute is present. It may also generate
4540 a special section with code to initialize the interrupt vector table.
4542 On Epiphany targets one or more optional parameters can be added like this:
4545 void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
4548 Permissible values for these parameters are: @w{@code{reset}},
4549 @w{@code{software_exception}}, @w{@code{page_miss}},
4550 @w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
4551 @w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
4552 Multiple parameters indicate that multiple entries in the interrupt
4553 vector table should be initialized for this function, i.e.@: for each
4554 parameter @w{@var{name}}, a jump to the function is emitted in
4555 the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
4556 entirely, in which case no interrupt vector table entry is provided.
4558 Note that interrupts are enabled inside the function
4559 unless the @code{disinterrupt} attribute is also specified.
4561 The following examples are all valid uses of these attributes on
4564 void __attribute__ ((interrupt)) universal_handler ();
4565 void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
4566 void __attribute__ ((interrupt ("dma0, dma1")))
4567 universal_dma_handler ();
4568 void __attribute__ ((interrupt ("timer0"), disinterrupt))
4569 fast_timer_handler ();
4570 void __attribute__ ((interrupt ("dma0, dma1"),
4571 forwarder_section ("tramp")))
4572 external_dma_handler ();
4577 @cindex @code{long_call} function attribute, Epiphany
4578 @cindex @code{short_call} function attribute, Epiphany
4579 @cindex indirect calls, Epiphany
4580 These attributes specify how a particular function is called.
4581 These attributes override the
4582 @option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
4583 command-line switch and @code{#pragma long_calls} settings.
4587 @node H8/300 Function Attributes
4588 @subsection H8/300 Function Attributes
4590 These function attributes are available for H8/300 targets:
4593 @item function_vector
4594 @cindex @code{function_vector} function attribute, H8/300
4595 Use this attribute on the H8/300, H8/300H, and H8S to indicate
4596 that the specified function should be called through the function vector.
4597 Calling a function through the function vector reduces code size; however,
4598 the function vector has a limited size (maximum 128 entries on the H8/300
4599 and 64 entries on the H8/300H and H8S)
4600 and shares space with the interrupt vector.
4602 @item interrupt_handler
4603 @cindex @code{interrupt_handler} function attribute, H8/300
4604 Use this attribute on the H8/300, H8/300H, and H8S to
4605 indicate that the specified function is an interrupt handler. The compiler
4606 generates function entry and exit sequences suitable for use in an
4607 interrupt handler when this attribute is present.
4610 @cindex @code{saveall} function attribute, H8/300
4611 @cindex save all registers on the H8/300, H8/300H, and H8S
4612 Use this attribute on the H8/300, H8/300H, and H8S to indicate that
4613 all registers except the stack pointer should be saved in the prologue
4614 regardless of whether they are used or not.
4617 @node IA-64 Function Attributes
4618 @subsection IA-64 Function Attributes
4620 These function attributes are supported on IA-64 targets:
4623 @item syscall_linkage
4624 @cindex @code{syscall_linkage} function attribute, IA-64
4625 This attribute is used to modify the IA-64 calling convention by marking
4626 all input registers as live at all function exits. This makes it possible
4627 to restart a system call after an interrupt without having to save/restore
4628 the input registers. This also prevents kernel data from leaking into
4632 @cindex @code{version_id} function attribute, IA-64
4633 This IA-64 HP-UX attribute, attached to a global variable or function, renames a
4634 symbol to contain a version string, thus allowing for function level
4635 versioning. HP-UX system header files may use function level versioning
4636 for some system calls.
4639 extern int foo () __attribute__((version_id ("20040821")));
4643 Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
4646 @node M32C Function Attributes
4647 @subsection M32C Function Attributes
4649 These function attributes are supported by the M32C back end:
4653 @cindex @code{bank_switch} function attribute, M32C
4654 When added to an interrupt handler with the M32C port, causes the
4655 prologue and epilogue to use bank switching to preserve the registers
4656 rather than saving them on the stack.
4658 @item fast_interrupt
4659 @cindex @code{fast_interrupt} function attribute, M32C
4660 Use this attribute on the M32C port to indicate that the specified
4661 function is a fast interrupt handler. This is just like the
4662 @code{interrupt} attribute, except that @code{freit} is used to return
4663 instead of @code{reit}.
4665 @item function_vector
4666 @cindex @code{function_vector} function attribute, M16C/M32C
4667 On M16C/M32C targets, the @code{function_vector} attribute declares a
4668 special page subroutine call function. Use of this attribute reduces
4669 the code size by 2 bytes for each call generated to the
4670 subroutine. The argument to the attribute is the vector number entry
4671 from the special page vector table which contains the 16 low-order
4672 bits of the subroutine's entry address. Each vector table has special
4673 page number (18 to 255) that is used in @code{jsrs} instructions.
4674 Jump addresses of the routines are generated by adding 0x0F0000 (in
4675 case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
4676 2-byte addresses set in the vector table. Therefore you need to ensure
4677 that all the special page vector routines should get mapped within the
4678 address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
4681 In the following example 2 bytes are saved for each call to
4682 function @code{foo}.
4685 void foo (void) __attribute__((function_vector(0x18)));
4696 If functions are defined in one file and are called in another file,
4697 then be sure to write this declaration in both files.
4699 This attribute is ignored for R8C target.
4702 @cindex @code{interrupt} function attribute, M32C
4703 Use this attribute to indicate
4704 that the specified function is an interrupt handler. The compiler generates
4705 function entry and exit sequences suitable for use in an interrupt handler
4706 when this attribute is present.
4709 @node M32R/D Function Attributes
4710 @subsection M32R/D Function Attributes
4712 These function attributes are supported by the M32R/D back end:
4716 @cindex @code{interrupt} function attribute, M32R/D
4717 Use this attribute to indicate
4718 that the specified function is an interrupt handler. The compiler generates
4719 function entry and exit sequences suitable for use in an interrupt handler
4720 when this attribute is present.
4722 @item model (@var{model-name})
4723 @cindex @code{model} function attribute, M32R/D
4724 @cindex function addressability on the M32R/D
4726 On the M32R/D, use this attribute to set the addressability of an
4727 object, and of the code generated for a function. The identifier
4728 @var{model-name} is one of @code{small}, @code{medium}, or
4729 @code{large}, representing each of the code models.
4731 Small model objects live in the lower 16MB of memory (so that their
4732 addresses can be loaded with the @code{ld24} instruction), and are
4733 callable with the @code{bl} instruction.
4735 Medium model objects may live anywhere in the 32-bit address space (the
4736 compiler generates @code{seth/add3} instructions to load their addresses),
4737 and are callable with the @code{bl} instruction.
4739 Large model objects may live anywhere in the 32-bit address space (the
4740 compiler generates @code{seth/add3} instructions to load their addresses),
4741 and may not be reachable with the @code{bl} instruction (the compiler
4742 generates the much slower @code{seth/add3/jl} instruction sequence).
4745 @node m68k Function Attributes
4746 @subsection m68k Function Attributes
4748 These function attributes are supported by the m68k back end:
4752 @itemx interrupt_handler
4753 @cindex @code{interrupt} function attribute, m68k
4754 @cindex @code{interrupt_handler} function attribute, m68k
4755 Use this attribute to
4756 indicate that the specified function is an interrupt handler. The compiler
4757 generates function entry and exit sequences suitable for use in an
4758 interrupt handler when this attribute is present. Either name may be used.
4760 @item interrupt_thread
4761 @cindex @code{interrupt_thread} function attribute, fido
4762 Use this attribute on fido, a subarchitecture of the m68k, to indicate
4763 that the specified function is an interrupt handler that is designed
4764 to run as a thread. The compiler omits generate prologue/epilogue
4765 sequences and replaces the return instruction with a @code{sleep}
4766 instruction. This attribute is available only on fido.
4769 @node MCORE Function Attributes
4770 @subsection MCORE Function Attributes
4772 These function attributes are supported by the MCORE back end:
4776 @cindex @code{naked} function attribute, MCORE
4777 This attribute allows the compiler to construct the
4778 requisite function declaration, while allowing the body of the
4779 function to be assembly code. The specified function will not have
4780 prologue/epilogue sequences generated by the compiler. Only basic
4781 @code{asm} statements can safely be included in naked functions
4782 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4783 basic @code{asm} and C code may appear to work, they cannot be
4784 depended upon to work reliably and are not supported.
4787 @node MeP Function Attributes
4788 @subsection MeP Function Attributes
4790 These function attributes are supported by the MeP back end:
4794 @cindex @code{disinterrupt} function attribute, MeP
4795 On MeP targets, this attribute causes the compiler to emit
4796 instructions to disable interrupts for the duration of the given
4800 @cindex @code{interrupt} function attribute, MeP
4801 Use this attribute to indicate
4802 that the specified function is an interrupt handler. The compiler generates
4803 function entry and exit sequences suitable for use in an interrupt handler
4804 when this attribute is present.
4807 @cindex @code{near} function attribute, MeP
4808 This attribute causes the compiler to assume the called
4809 function is close enough to use the normal calling convention,
4810 overriding the @option{-mtf} command-line option.
4813 @cindex @code{far} function attribute, MeP
4814 On MeP targets this causes the compiler to use a calling convention
4815 that assumes the called function is too far away for the built-in
4819 @cindex @code{vliw} function attribute, MeP
4820 The @code{vliw} attribute tells the compiler to emit
4821 instructions in VLIW mode instead of core mode. Note that this
4822 attribute is not allowed unless a VLIW coprocessor has been configured
4823 and enabled through command-line options.
4826 @node MicroBlaze Function Attributes
4827 @subsection MicroBlaze Function Attributes
4829 These function attributes are supported on MicroBlaze targets:
4832 @item save_volatiles
4833 @cindex @code{save_volatiles} function attribute, MicroBlaze
4834 Use this attribute to indicate that the function is
4835 an interrupt handler. All volatile registers (in addition to non-volatile
4836 registers) are saved in the function prologue. If the function is a leaf
4837 function, only volatiles used by the function are saved. A normal function
4838 return is generated instead of a return from interrupt.
4841 @cindex @code{break_handler} function attribute, MicroBlaze
4842 @cindex break handler functions
4843 Use this attribute to indicate that
4844 the specified function is a break handler. The compiler generates function
4845 entry and exit sequences suitable for use in an break handler when this
4846 attribute is present. The return from @code{break_handler} is done through
4847 the @code{rtbd} instead of @code{rtsd}.
4850 void f () __attribute__ ((break_handler));
4853 @item interrupt_handler
4854 @itemx fast_interrupt
4855 @cindex @code{interrupt_handler} function attribute, MicroBlaze
4856 @cindex @code{fast_interrupt} function attribute, MicroBlaze
4857 These attributes indicate that the specified function is an interrupt
4858 handler. Use the @code{fast_interrupt} attribute to indicate handlers
4859 used in low-latency interrupt mode, and @code{interrupt_handler} for
4860 interrupts that do not use low-latency handlers. In both cases, GCC
4861 emits appropriate prologue code and generates a return from the handler
4862 using @code{rtid} instead of @code{rtsd}.
4865 @node Microsoft Windows Function Attributes
4866 @subsection Microsoft Windows Function Attributes
4868 The following attributes are available on Microsoft Windows and Symbian OS
4873 @cindex @code{dllexport} function attribute
4874 @cindex @code{__declspec(dllexport)}
4875 On Microsoft Windows targets and Symbian OS targets the
4876 @code{dllexport} attribute causes the compiler to provide a global
4877 pointer to a pointer in a DLL, so that it can be referenced with the
4878 @code{dllimport} attribute. On Microsoft Windows targets, the pointer
4879 name is formed by combining @code{_imp__} and the function or variable
4882 You can use @code{__declspec(dllexport)} as a synonym for
4883 @code{__attribute__ ((dllexport))} for compatibility with other
4886 On systems that support the @code{visibility} attribute, this
4887 attribute also implies ``default'' visibility. It is an error to
4888 explicitly specify any other visibility.
4890 GCC's default behavior is to emit all inline functions with the
4891 @code{dllexport} attribute. Since this can cause object file-size bloat,
4892 you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
4893 ignore the attribute for inlined functions unless the
4894 @option{-fkeep-inline-functions} flag is used instead.
4896 The attribute is ignored for undefined symbols.
4898 When applied to C++ classes, the attribute marks defined non-inlined
4899 member functions and static data members as exports. Static consts
4900 initialized in-class are not marked unless they are also defined
4903 For Microsoft Windows targets there are alternative methods for
4904 including the symbol in the DLL's export table such as using a
4905 @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
4906 the @option{--export-all} linker flag.
4909 @cindex @code{dllimport} function attribute
4910 @cindex @code{__declspec(dllimport)}
4911 On Microsoft Windows and Symbian OS targets, the @code{dllimport}
4912 attribute causes the compiler to reference a function or variable via
4913 a global pointer to a pointer that is set up by the DLL exporting the
4914 symbol. The attribute implies @code{extern}. On Microsoft Windows
4915 targets, the pointer name is formed by combining @code{_imp__} and the
4916 function or variable name.
4918 You can use @code{__declspec(dllimport)} as a synonym for
4919 @code{__attribute__ ((dllimport))} for compatibility with other
4922 On systems that support the @code{visibility} attribute, this
4923 attribute also implies ``default'' visibility. It is an error to
4924 explicitly specify any other visibility.
4926 Currently, the attribute is ignored for inlined functions. If the
4927 attribute is applied to a symbol @emph{definition}, an error is reported.
4928 If a symbol previously declared @code{dllimport} is later defined, the
4929 attribute is ignored in subsequent references, and a warning is emitted.
4930 The attribute is also overridden by a subsequent declaration as
4933 When applied to C++ classes, the attribute marks non-inlined
4934 member functions and static data members as imports. However, the
4935 attribute is ignored for virtual methods to allow creation of vtables
4938 On the SH Symbian OS target the @code{dllimport} attribute also has
4939 another affect---it can cause the vtable and run-time type information
4940 for a class to be exported. This happens when the class has a
4941 dllimported constructor or a non-inline, non-pure virtual function
4942 and, for either of those two conditions, the class also has an inline
4943 constructor or destructor and has a key function that is defined in
4944 the current translation unit.
4946 For Microsoft Windows targets the use of the @code{dllimport}
4947 attribute on functions is not necessary, but provides a small
4948 performance benefit by eliminating a thunk in the DLL@. The use of the
4949 @code{dllimport} attribute on imported variables can be avoided by passing the
4950 @option{--enable-auto-import} switch to the GNU linker. As with
4951 functions, using the attribute for a variable eliminates a thunk in
4954 One drawback to using this attribute is that a pointer to a
4955 @emph{variable} marked as @code{dllimport} cannot be used as a constant
4956 address. However, a pointer to a @emph{function} with the
4957 @code{dllimport} attribute can be used as a constant initializer; in
4958 this case, the address of a stub function in the import lib is
4959 referenced. On Microsoft Windows targets, the attribute can be disabled
4960 for functions by setting the @option{-mnop-fun-dllimport} flag.
4963 @node MIPS Function Attributes
4964 @subsection MIPS Function Attributes
4966 These function attributes are supported by the MIPS back end:
4970 @cindex @code{interrupt} function attribute, MIPS
4971 Use this attribute to indicate that the specified function is an interrupt
4972 handler. The compiler generates function entry and exit sequences suitable
4973 for use in an interrupt handler when this attribute is present.
4974 An optional argument is supported for the interrupt attribute which allows
4975 the interrupt mode to be described. By default GCC assumes the external
4976 interrupt controller (EIC) mode is in use, this can be explicitly set using
4977 @code{eic}. When interrupts are non-masked then the requested Interrupt
4978 Priority Level (IPL) is copied to the current IPL which has the effect of only
4979 enabling higher priority interrupts. To use vectored interrupt mode use
4980 the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
4981 the behavior of the non-masked interrupt support and GCC will arrange to mask
4982 all interrupts from sw0 up to and including the specified interrupt vector.
4984 You can use the following attributes to modify the behavior
4985 of an interrupt handler:
4987 @item use_shadow_register_set
4988 @cindex @code{use_shadow_register_set} function attribute, MIPS
4989 Assume that the handler uses a shadow register set, instead of
4990 the main general-purpose registers. An optional argument @code{intstack} is
4991 supported to indicate that the shadow register set contains a valid stack
4994 @item keep_interrupts_masked
4995 @cindex @code{keep_interrupts_masked} function attribute, MIPS
4996 Keep interrupts masked for the whole function. Without this attribute,
4997 GCC tries to reenable interrupts for as much of the function as it can.
4999 @item use_debug_exception_return
5000 @cindex @code{use_debug_exception_return} function attribute, MIPS
5001 Return using the @code{deret} instruction. Interrupt handlers that don't
5002 have this attribute return using @code{eret} instead.
5005 You can use any combination of these attributes, as shown below:
5007 void __attribute__ ((interrupt)) v0 ();
5008 void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
5009 void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
5010 void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
5011 void __attribute__ ((interrupt, use_shadow_register_set,
5012 keep_interrupts_masked)) v4 ();
5013 void __attribute__ ((interrupt, use_shadow_register_set,
5014 use_debug_exception_return)) v5 ();
5015 void __attribute__ ((interrupt, keep_interrupts_masked,
5016 use_debug_exception_return)) v6 ();
5017 void __attribute__ ((interrupt, use_shadow_register_set,
5018 keep_interrupts_masked,
5019 use_debug_exception_return)) v7 ();
5020 void __attribute__ ((interrupt("eic"))) v8 ();
5021 void __attribute__ ((interrupt("vector=hw3"))) v9 ();
5028 @cindex indirect calls, MIPS
5029 @cindex @code{long_call} function attribute, MIPS
5030 @cindex @code{short_call} function attribute, MIPS
5031 @cindex @code{near} function attribute, MIPS
5032 @cindex @code{far} function attribute, MIPS
5033 These attributes specify how a particular function is called on MIPS@.
5034 The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
5035 command-line switch. The @code{long_call} and @code{far} attributes are
5036 synonyms, and cause the compiler to always call
5037 the function by first loading its address into a register, and then using
5038 the contents of that register. The @code{short_call} and @code{near}
5039 attributes are synonyms, and have the opposite
5040 effect; they specify that non-PIC calls should be made using the more
5041 efficient @code{jal} instruction.
5045 @cindex @code{mips16} function attribute, MIPS
5046 @cindex @code{nomips16} function attribute, MIPS
5048 On MIPS targets, you can use the @code{mips16} and @code{nomips16}
5049 function attributes to locally select or turn off MIPS16 code generation.
5050 A function with the @code{mips16} attribute is emitted as MIPS16 code,
5051 while MIPS16 code generation is disabled for functions with the
5052 @code{nomips16} attribute. These attributes override the
5053 @option{-mips16} and @option{-mno-mips16} options on the command line
5054 (@pxref{MIPS Options}).
5056 When compiling files containing mixed MIPS16 and non-MIPS16 code, the
5057 preprocessor symbol @code{__mips16} reflects the setting on the command line,
5058 not that within individual functions. Mixed MIPS16 and non-MIPS16 code
5059 may interact badly with some GCC extensions such as @code{__builtin_apply}
5060 (@pxref{Constructing Calls}).
5062 @item micromips, MIPS
5063 @itemx nomicromips, MIPS
5064 @cindex @code{micromips} function attribute
5065 @cindex @code{nomicromips} function attribute
5067 On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
5068 function attributes to locally select or turn off microMIPS code generation.
5069 A function with the @code{micromips} attribute is emitted as microMIPS code,
5070 while microMIPS code generation is disabled for functions with the
5071 @code{nomicromips} attribute. These attributes override the
5072 @option{-mmicromips} and @option{-mno-micromips} options on the command line
5073 (@pxref{MIPS Options}).
5075 When compiling files containing mixed microMIPS and non-microMIPS code, the
5076 preprocessor symbol @code{__mips_micromips} reflects the setting on the
5078 not that within individual functions. Mixed microMIPS and non-microMIPS code
5079 may interact badly with some GCC extensions such as @code{__builtin_apply}
5080 (@pxref{Constructing Calls}).
5083 @cindex @code{nocompression} function attribute, MIPS
5084 On MIPS targets, you can use the @code{nocompression} function attribute
5085 to locally turn off MIPS16 and microMIPS code generation. This attribute
5086 overrides the @option{-mips16} and @option{-mmicromips} options on the
5087 command line (@pxref{MIPS Options}).
5090 @node MSP430 Function Attributes
5091 @subsection MSP430 Function Attributes
5093 These function attributes are supported by the MSP430 back end:
5097 @cindex @code{critical} function attribute, MSP430
5098 Critical functions disable interrupts upon entry and restore the
5099 previous interrupt state upon exit. Critical functions cannot also
5100 have the @code{naked}, @code{reentrant} or @code{interrupt} attributes.
5102 The MSP430 hardware ensures that interrupts are disabled on entry to
5103 @code{interrupt} functions, and restores the previous interrupt state
5104 on exit. The @code{critical} attribute is therefore redundant on
5105 @code{interrupt} functions.
5108 @cindex @code{interrupt} function attribute, MSP430
5109 Use this attribute to indicate
5110 that the specified function is an interrupt handler. The compiler generates
5111 function entry and exit sequences suitable for use in an interrupt handler
5112 when this attribute is present.
5114 You can provide an argument to the interrupt
5115 attribute which specifies a name or number. If the argument is a
5116 number it indicates the slot in the interrupt vector table (0 - 31) to
5117 which this handler should be assigned. If the argument is a name it
5118 is treated as a symbolic name for the vector slot. These names should
5119 match up with appropriate entries in the linker script. By default
5120 the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
5121 @code{reset} for vector 31 are recognized.
5124 @cindex @code{naked} function attribute, MSP430
5125 This attribute allows the compiler to construct the
5126 requisite function declaration, while allowing the body of the
5127 function to be assembly code. The specified function will not have
5128 prologue/epilogue sequences generated by the compiler. Only basic
5129 @code{asm} statements can safely be included in naked functions
5130 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5131 basic @code{asm} and C code may appear to work, they cannot be
5132 depended upon to work reliably and are not supported.
5135 @cindex @code{reentrant} function attribute, MSP430
5136 Reentrant functions disable interrupts upon entry and enable them
5137 upon exit. Reentrant functions cannot also have the @code{naked}
5138 or @code{critical} attributes. They can have the @code{interrupt}
5142 @cindex @code{wakeup} function attribute, MSP430
5143 This attribute only applies to interrupt functions. It is silently
5144 ignored if applied to a non-interrupt function. A wakeup interrupt
5145 function will rouse the processor from any low-power state that it
5146 might be in when the function exits.
5151 @cindex @code{lower} function attribute, MSP430
5152 @cindex @code{upper} function attribute, MSP430
5153 @cindex @code{either} function attribute, MSP430
5154 On the MSP430 target these attributes can be used to specify whether
5155 the function or variable should be placed into low memory, high
5156 memory, or the placement should be left to the linker to decide. The
5157 attributes are only significant if compiling for the MSP430X
5160 The attributes work in conjunction with a linker script that has been
5161 augmented to specify where to place sections with a @code{.lower} and
5162 a @code{.upper} prefix. So, for example, as well as placing the
5163 @code{.data} section, the script also specifies the placement of a
5164 @code{.lower.data} and a @code{.upper.data} section. The intention
5165 is that @code{lower} sections are placed into a small but easier to
5166 access memory region and the upper sections are placed into a larger, but
5167 slower to access, region.
5169 The @code{either} attribute is special. It tells the linker to place
5170 the object into the corresponding @code{lower} section if there is
5171 room for it. If there is insufficient room then the object is placed
5172 into the corresponding @code{upper} section instead. Note that the
5173 placement algorithm is not very sophisticated. It does not attempt to
5174 find an optimal packing of the @code{lower} sections. It just makes
5175 one pass over the objects and does the best that it can. Using the
5176 @option{-ffunction-sections} and @option{-fdata-sections} command-line
5177 options can help the packing, however, since they produce smaller,
5178 easier to pack regions.
5181 @node NDS32 Function Attributes
5182 @subsection NDS32 Function Attributes
5184 These function attributes are supported by the NDS32 back end:
5188 @cindex @code{exception} function attribute
5189 @cindex exception handler functions, NDS32
5190 Use this attribute on the NDS32 target to indicate that the specified function
5191 is an exception handler. The compiler will generate corresponding sections
5192 for use in an exception handler.
5195 @cindex @code{interrupt} function attribute, NDS32
5196 On NDS32 target, this attribute indicates that the specified function
5197 is an interrupt handler. The compiler generates corresponding sections
5198 for use in an interrupt handler. You can use the following attributes
5199 to modify the behavior:
5202 @cindex @code{nested} function attribute, NDS32
5203 This interrupt service routine is interruptible.
5205 @cindex @code{not_nested} function attribute, NDS32
5206 This interrupt service routine is not interruptible.
5208 @cindex @code{nested_ready} function attribute, NDS32
5209 This interrupt service routine is interruptible after @code{PSW.GIE}
5210 (global interrupt enable) is set. This allows interrupt service routine to
5211 finish some short critical code before enabling interrupts.
5213 @cindex @code{save_all} function attribute, NDS32
5214 The system will help save all registers into stack before entering
5217 @cindex @code{partial_save} function attribute, NDS32
5218 The system will help save caller registers into stack before entering
5223 @cindex @code{naked} function attribute, NDS32
5224 This attribute allows the compiler to construct the
5225 requisite function declaration, while allowing the body of the
5226 function to be assembly code. The specified function will not have
5227 prologue/epilogue sequences generated by the compiler. Only basic
5228 @code{asm} statements can safely be included in naked functions
5229 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5230 basic @code{asm} and C code may appear to work, they cannot be
5231 depended upon to work reliably and are not supported.
5234 @cindex @code{reset} function attribute, NDS32
5235 @cindex reset handler functions
5236 Use this attribute on the NDS32 target to indicate that the specified function
5237 is a reset handler. The compiler will generate corresponding sections
5238 for use in a reset handler. You can use the following attributes
5239 to provide extra exception handling:
5242 @cindex @code{nmi} function attribute, NDS32
5243 Provide a user-defined function to handle NMI exception.
5245 @cindex @code{warm} function attribute, NDS32
5246 Provide a user-defined function to handle warm reset exception.
5250 @node Nios II Function Attributes
5251 @subsection Nios II Function Attributes
5253 These function attributes are supported by the Nios II back end:
5256 @item target (@var{options})
5257 @cindex @code{target} function attribute
5258 As discussed in @ref{Common Function Attributes}, this attribute
5259 allows specification of target-specific compilation options.
5261 When compiling for Nios II, the following options are allowed:
5264 @item custom-@var{insn}=@var{N}
5265 @itemx no-custom-@var{insn}
5266 @cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II
5267 @cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II
5268 Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a
5269 custom instruction with encoding @var{N} when generating code that uses
5270 @var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of
5271 the custom instruction @var{insn}.
5272 These target attributes correspond to the
5273 @option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}}
5274 command-line options, and support the same set of @var{insn} keywords.
5275 @xref{Nios II Options}, for more information.
5277 @item custom-fpu-cfg=@var{name}
5278 @cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II
5279 This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}}
5280 command-line option, to select a predefined set of custom instructions
5282 @xref{Nios II Options}, for more information.
5286 @node Nvidia PTX Function Attributes
5287 @subsection Nvidia PTX Function Attributes
5289 These function attributes are supported by the Nvidia PTX back end:
5293 @cindex @code{kernel} attribute, Nvidia PTX
5294 This attribute indicates that the corresponding function should be compiled
5295 as a kernel function, which can be invoked from the host via the CUDA RT
5297 By default functions are only callable only from other PTX functions.
5299 Kernel functions must have @code{void} return type.
5302 @node PowerPC Function Attributes
5303 @subsection PowerPC Function Attributes
5305 These function attributes are supported by the PowerPC back end:
5310 @cindex indirect calls, PowerPC
5311 @cindex @code{longcall} function attribute, PowerPC
5312 @cindex @code{shortcall} function attribute, PowerPC
5313 The @code{longcall} attribute
5314 indicates that the function might be far away from the call site and
5315 require a different (more expensive) calling sequence. The
5316 @code{shortcall} attribute indicates that the function is always close
5317 enough for the shorter calling sequence to be used. These attributes
5318 override both the @option{-mlongcall} switch and
5319 the @code{#pragma longcall} setting.
5321 @xref{RS/6000 and PowerPC Options}, for more information on whether long
5322 calls are necessary.
5324 @item target (@var{options})
5325 @cindex @code{target} function attribute
5326 As discussed in @ref{Common Function Attributes}, this attribute
5327 allows specification of target-specific compilation options.
5329 On the PowerPC, the following options are allowed:
5334 @cindex @code{target("altivec")} function attribute, PowerPC
5335 Generate code that uses (does not use) AltiVec instructions. In
5336 32-bit code, you cannot enable AltiVec instructions unless
5337 @option{-mabi=altivec} is used on the command line.
5341 @cindex @code{target("cmpb")} function attribute, PowerPC
5342 Generate code that uses (does not use) the compare bytes instruction
5343 implemented on the POWER6 processor and other processors that support
5344 the PowerPC V2.05 architecture.
5348 @cindex @code{target("dlmzb")} function attribute, PowerPC
5349 Generate code that uses (does not use) the string-search @samp{dlmzb}
5350 instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
5351 generated by default when targeting those processors.
5355 @cindex @code{target("fprnd")} function attribute, PowerPC
5356 Generate code that uses (does not use) the FP round to integer
5357 instructions implemented on the POWER5+ processor and other processors
5358 that support the PowerPC V2.03 architecture.
5362 @cindex @code{target("hard-dfp")} function attribute, PowerPC
5363 Generate code that uses (does not use) the decimal floating-point
5364 instructions implemented on some POWER processors.
5368 @cindex @code{target("isel")} function attribute, PowerPC
5369 Generate code that uses (does not use) ISEL instruction.
5373 @cindex @code{target("mfcrf")} function attribute, PowerPC
5374 Generate code that uses (does not use) the move from condition
5375 register field instruction implemented on the POWER4 processor and
5376 other processors that support the PowerPC V2.01 architecture.
5380 @cindex @code{target("mfpgpr")} function attribute, PowerPC
5381 Generate code that uses (does not use) the FP move to/from general
5382 purpose register instructions implemented on the POWER6X processor and
5383 other processors that support the extended PowerPC V2.05 architecture.
5387 @cindex @code{target("mulhw")} function attribute, PowerPC
5388 Generate code that uses (does not use) the half-word multiply and
5389 multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
5390 These instructions are generated by default when targeting those
5395 @cindex @code{target("multiple")} function attribute, PowerPC
5396 Generate code that uses (does not use) the load multiple word
5397 instructions and the store multiple word instructions.
5401 @cindex @code{target("update")} function attribute, PowerPC
5402 Generate code that uses (does not use) the load or store instructions
5403 that update the base register to the address of the calculated memory
5408 @cindex @code{target("popcntb")} function attribute, PowerPC
5409 Generate code that uses (does not use) the popcount and double-precision
5410 FP reciprocal estimate instruction implemented on the POWER5
5411 processor and other processors that support the PowerPC V2.02
5416 @cindex @code{target("popcntd")} function attribute, PowerPC
5417 Generate code that uses (does not use) the popcount instruction
5418 implemented on the POWER7 processor and other processors that support
5419 the PowerPC V2.06 architecture.
5421 @item powerpc-gfxopt
5422 @itemx no-powerpc-gfxopt
5423 @cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
5424 Generate code that uses (does not use) the optional PowerPC
5425 architecture instructions in the Graphics group, including
5426 floating-point select.
5429 @itemx no-powerpc-gpopt
5430 @cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
5431 Generate code that uses (does not use) the optional PowerPC
5432 architecture instructions in the General Purpose group, including
5433 floating-point square root.
5435 @item recip-precision
5436 @itemx no-recip-precision
5437 @cindex @code{target("recip-precision")} function attribute, PowerPC
5438 Assume (do not assume) that the reciprocal estimate instructions
5439 provide higher-precision estimates than is mandated by the PowerPC
5444 @cindex @code{target("string")} function attribute, PowerPC
5445 Generate code that uses (does not use) the load string instructions
5446 and the store string word instructions to save multiple registers and
5447 do small block moves.
5451 @cindex @code{target("vsx")} function attribute, PowerPC
5452 Generate code that uses (does not use) vector/scalar (VSX)
5453 instructions, and also enable the use of built-in functions that allow
5454 more direct access to the VSX instruction set. In 32-bit code, you
5455 cannot enable VSX or AltiVec instructions unless
5456 @option{-mabi=altivec} is used on the command line.
5460 @cindex @code{target("friz")} function attribute, PowerPC
5461 Generate (do not generate) the @code{friz} instruction when the
5462 @option{-funsafe-math-optimizations} option is used to optimize
5463 rounding a floating-point value to 64-bit integer and back to floating
5464 point. The @code{friz} instruction does not return the same value if
5465 the floating-point number is too large to fit in an integer.
5467 @item avoid-indexed-addresses
5468 @itemx no-avoid-indexed-addresses
5469 @cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
5470 Generate code that tries to avoid (not avoid) the use of indexed load
5471 or store instructions.
5475 @cindex @code{target("paired")} function attribute, PowerPC
5476 Generate code that uses (does not use) the generation of PAIRED simd
5481 @cindex @code{target("longcall")} function attribute, PowerPC
5482 Generate code that assumes (does not assume) that all calls are far
5483 away so that a longer more expensive calling sequence is required.
5486 @cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
5487 Specify the architecture to generate code for when compiling the
5488 function. If you select the @code{target("cpu=power7")} attribute when
5489 generating 32-bit code, VSX and AltiVec instructions are not generated
5490 unless you use the @option{-mabi=altivec} option on the command line.
5492 @item tune=@var{TUNE}
5493 @cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
5494 Specify the architecture to tune for when compiling the function. If
5495 you do not specify the @code{target("tune=@var{TUNE}")} attribute and
5496 you do specify the @code{target("cpu=@var{CPU}")} attribute,
5497 compilation tunes for the @var{CPU} architecture, and not the
5498 default tuning specified on the command line.
5501 On the PowerPC, the inliner does not inline a
5502 function that has different target options than the caller, unless the
5503 callee has a subset of the target options of the caller.
5506 @node RISC-V Function Attributes
5507 @subsection RISC-V Function Attributes
5509 These function attributes are supported by the RISC-V back end:
5513 @cindex @code{naked} function attribute, RISC-V
5514 This attribute allows the compiler to construct the
5515 requisite function declaration, while allowing the body of the
5516 function to be assembly code. The specified function will not have
5517 prologue/epilogue sequences generated by the compiler. Only basic
5518 @code{asm} statements can safely be included in naked functions
5519 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5520 basic @code{asm} and C code may appear to work, they cannot be
5521 depended upon to work reliably and are not supported.
5524 @cindex @code{interrupt} function attribute, RISC-V
5525 Use this attribute to indicate that the specified function is an interrupt
5526 handler. The compiler generates function entry and exit sequences suitable
5527 for use in an interrupt handler when this attribute is present.
5529 You can specify the kind of interrupt to be handled by adding an optional
5530 parameter to the interrupt attribute like this:
5533 void f (void) __attribute__ ((interrupt ("user")));
5536 Permissible values for this parameter are @code{user}, @code{supervisor},
5537 and @code{machine}. If there is no parameter, then it defaults to
5541 @node RL78 Function Attributes
5542 @subsection RL78 Function Attributes
5544 These function attributes are supported by the RL78 back end:
5548 @itemx brk_interrupt
5549 @cindex @code{interrupt} function attribute, RL78
5550 @cindex @code{brk_interrupt} function attribute, RL78
5551 These attributes indicate
5552 that the specified function is an interrupt handler. The compiler generates
5553 function entry and exit sequences suitable for use in an interrupt handler
5554 when this attribute is present.
5556 Use @code{brk_interrupt} instead of @code{interrupt} for
5557 handlers intended to be used with the @code{BRK} opcode (i.e.@: those
5558 that must end with @code{RETB} instead of @code{RETI}).
5561 @cindex @code{naked} function attribute, RL78
5562 This attribute allows the compiler to construct the
5563 requisite function declaration, while allowing the body of the
5564 function to be assembly code. The specified function will not have
5565 prologue/epilogue sequences generated by the compiler. Only basic
5566 @code{asm} statements can safely be included in naked functions
5567 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5568 basic @code{asm} and C code may appear to work, they cannot be
5569 depended upon to work reliably and are not supported.
5572 @node RX Function Attributes
5573 @subsection RX Function Attributes
5575 These function attributes are supported by the RX back end:
5578 @item fast_interrupt
5579 @cindex @code{fast_interrupt} function attribute, RX
5580 Use this attribute on the RX port to indicate that the specified
5581 function is a fast interrupt handler. This is just like the
5582 @code{interrupt} attribute, except that @code{freit} is used to return
5583 instead of @code{reit}.
5586 @cindex @code{interrupt} function attribute, RX
5587 Use this attribute to indicate
5588 that the specified function is an interrupt handler. The compiler generates
5589 function entry and exit sequences suitable for use in an interrupt handler
5590 when this attribute is present.
5592 On RX and RL78 targets, you may specify one or more vector numbers as arguments
5593 to the attribute, as well as naming an alternate table name.
5594 Parameters are handled sequentially, so one handler can be assigned to
5595 multiple entries in multiple tables. One may also pass the magic
5596 string @code{"$default"} which causes the function to be used for any
5597 unfilled slots in the current table.
5599 This example shows a simple assignment of a function to one vector in
5600 the default table (note that preprocessor macros may be used for
5601 chip-specific symbolic vector names):
5603 void __attribute__ ((interrupt (5))) txd1_handler ();
5606 This example assigns a function to two slots in the default table
5607 (using preprocessor macros defined elsewhere) and makes it the default
5608 for the @code{dct} table:
5610 void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
5615 @cindex @code{naked} function attribute, RX
5616 This attribute allows the compiler to construct the
5617 requisite function declaration, while allowing the body of the
5618 function to be assembly code. The specified function will not have
5619 prologue/epilogue sequences generated by the compiler. Only basic
5620 @code{asm} statements can safely be included in naked functions
5621 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5622 basic @code{asm} and C code may appear to work, they cannot be
5623 depended upon to work reliably and are not supported.
5626 @cindex @code{vector} function attribute, RX
5627 This RX attribute is similar to the @code{interrupt} attribute, including its
5628 parameters, but does not make the function an interrupt-handler type
5629 function (i.e.@: it retains the normal C function calling ABI). See the
5630 @code{interrupt} attribute for a description of its arguments.
5633 @node S/390 Function Attributes
5634 @subsection S/390 Function Attributes
5636 These function attributes are supported on the S/390:
5639 @item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
5640 @cindex @code{hotpatch} function attribute, S/390
5642 On S/390 System z targets, you can use this function attribute to
5643 make GCC generate a ``hot-patching'' function prologue. If the
5644 @option{-mhotpatch=} command-line option is used at the same time,
5645 the @code{hotpatch} attribute takes precedence. The first of the
5646 two arguments specifies the number of halfwords to be added before
5647 the function label. A second argument can be used to specify the
5648 number of halfwords to be added after the function label. For
5649 both arguments the maximum allowed value is 1000000.
5651 If both arguments are zero, hotpatching is disabled.
5653 @item target (@var{options})
5654 @cindex @code{target} function attribute
5655 As discussed in @ref{Common Function Attributes}, this attribute
5656 allows specification of target-specific compilation options.
5658 On S/390, the following options are supported:
5666 @item warn-framesize=
5678 @itemx no-packed-stack
5680 @itemx no-small-exec
5683 @item warn-dynamicstack
5684 @itemx no-warn-dynamicstack
5687 The options work exactly like the S/390 specific command line
5688 options (without the prefix @option{-m}) except that they do not
5689 change any feature macros. For example,
5692 @code{target("no-vx")}
5695 does not undefine the @code{__VEC__} macro.
5698 @node SH Function Attributes
5699 @subsection SH Function Attributes
5701 These function attributes are supported on the SH family of processors:
5704 @item function_vector
5705 @cindex @code{function_vector} function attribute, SH
5706 @cindex calling functions through the function vector on SH2A
5707 On SH2A targets, this attribute declares a function to be called using the
5708 TBR relative addressing mode. The argument to this attribute is the entry
5709 number of the same function in a vector table containing all the TBR
5710 relative addressable functions. For correct operation the TBR must be setup
5711 accordingly to point to the start of the vector table before any functions with
5712 this attribute are invoked. Usually a good place to do the initialization is
5713 the startup routine. The TBR relative vector table can have at max 256 function
5714 entries. The jumps to these functions are generated using a SH2A specific,
5715 non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD
5716 from GNU binutils version 2.7 or later for this attribute to work correctly.
5718 In an application, for a function being called once, this attribute
5719 saves at least 8 bytes of code; and if other successive calls are being
5720 made to the same function, it saves 2 bytes of code per each of these
5723 @item interrupt_handler
5724 @cindex @code{interrupt_handler} function attribute, SH
5725 Use this attribute to
5726 indicate that the specified function is an interrupt handler. The compiler
5727 generates function entry and exit sequences suitable for use in an
5728 interrupt handler when this attribute is present.
5730 @item nosave_low_regs
5731 @cindex @code{nosave_low_regs} function attribute, SH
5732 Use this attribute on SH targets to indicate that an @code{interrupt_handler}
5733 function should not save and restore registers R0..R7. This can be used on SH3*
5734 and SH4* targets that have a second R0..R7 register bank for non-reentrant
5738 @cindex @code{renesas} function attribute, SH
5739 On SH targets this attribute specifies that the function or struct follows the
5743 @cindex @code{resbank} function attribute, SH
5744 On the SH2A target, this attribute enables the high-speed register
5745 saving and restoration using a register bank for @code{interrupt_handler}
5746 routines. Saving to the bank is performed automatically after the CPU
5747 accepts an interrupt that uses a register bank.
5749 The nineteen 32-bit registers comprising general register R0 to R14,
5750 control register GBR, and system registers MACH, MACL, and PR and the
5751 vector table address offset are saved into a register bank. Register
5752 banks are stacked in first-in last-out (FILO) sequence. Restoration
5753 from the bank is executed by issuing a RESBANK instruction.
5756 @cindex @code{sp_switch} function attribute, SH
5757 Use this attribute on the SH to indicate an @code{interrupt_handler}
5758 function should switch to an alternate stack. It expects a string
5759 argument that names a global variable holding the address of the
5764 void f () __attribute__ ((interrupt_handler,
5765 sp_switch ("alt_stack")));
5769 @cindex @code{trap_exit} function attribute, SH
5770 Use this attribute on the SH for an @code{interrupt_handler} to return using
5771 @code{trapa} instead of @code{rte}. This attribute expects an integer
5772 argument specifying the trap number to be used.
5775 @cindex @code{trapa_handler} function attribute, SH
5776 On SH targets this function attribute is similar to @code{interrupt_handler}
5777 but it does not save and restore all registers.
5780 @node SPU Function Attributes
5781 @subsection SPU Function Attributes
5783 These function attributes are supported by the SPU back end:
5787 @cindex @code{naked} function attribute, SPU
5788 This attribute allows the compiler to construct the
5789 requisite function declaration, while allowing the body of the
5790 function to be assembly code. The specified function will not have
5791 prologue/epilogue sequences generated by the compiler. Only basic
5792 @code{asm} statements can safely be included in naked functions
5793 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5794 basic @code{asm} and C code may appear to work, they cannot be
5795 depended upon to work reliably and are not supported.
5798 @node Symbian OS Function Attributes
5799 @subsection Symbian OS Function Attributes
5801 @xref{Microsoft Windows Function Attributes}, for discussion of the
5802 @code{dllexport} and @code{dllimport} attributes.
5804 @node V850 Function Attributes
5805 @subsection V850 Function Attributes
5807 The V850 back end supports these function attributes:
5811 @itemx interrupt_handler
5812 @cindex @code{interrupt} function attribute, V850
5813 @cindex @code{interrupt_handler} function attribute, V850
5814 Use these attributes to indicate
5815 that the specified function is an interrupt handler. The compiler generates
5816 function entry and exit sequences suitable for use in an interrupt handler
5817 when either attribute is present.
5820 @node Visium Function Attributes
5821 @subsection Visium Function Attributes
5823 These function attributes are supported by the Visium back end:
5827 @cindex @code{interrupt} function attribute, Visium
5828 Use this attribute to indicate
5829 that the specified function is an interrupt handler. The compiler generates
5830 function entry and exit sequences suitable for use in an interrupt handler
5831 when this attribute is present.
5834 @node x86 Function Attributes
5835 @subsection x86 Function Attributes
5837 These function attributes are supported by the x86 back end:
5841 @cindex @code{cdecl} function attribute, x86-32
5842 @cindex functions that pop the argument stack on x86-32
5844 On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
5845 assume that the calling function pops off the stack space used to
5846 pass arguments. This is
5847 useful to override the effects of the @option{-mrtd} switch.
5850 @cindex @code{fastcall} function attribute, x86-32
5851 @cindex functions that pop the argument stack on x86-32
5852 On x86-32 targets, the @code{fastcall} attribute causes the compiler to
5853 pass the first argument (if of integral type) in the register ECX and
5854 the second argument (if of integral type) in the register EDX@. Subsequent
5855 and other typed arguments are passed on the stack. The called function
5856 pops the arguments off the stack. If the number of arguments is variable all
5857 arguments are pushed on the stack.
5860 @cindex @code{thiscall} function attribute, x86-32
5861 @cindex functions that pop the argument stack on x86-32
5862 On x86-32 targets, the @code{thiscall} attribute causes the compiler to
5863 pass the first argument (if of integral type) in the register ECX.
5864 Subsequent and other typed arguments are passed on the stack. The called
5865 function pops the arguments off the stack.
5866 If the number of arguments is variable all arguments are pushed on the
5868 The @code{thiscall} attribute is intended for C++ non-static member functions.
5869 As a GCC extension, this calling convention can be used for C functions
5870 and for static member methods.
5874 @cindex @code{ms_abi} function attribute, x86
5875 @cindex @code{sysv_abi} function attribute, x86
5877 On 32-bit and 64-bit x86 targets, you can use an ABI attribute
5878 to indicate which calling convention should be used for a function. The
5879 @code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
5880 while the @code{sysv_abi} attribute tells the compiler to use the ABI
5881 used on GNU/Linux and other systems. The default is to use the Microsoft ABI
5882 when targeting Windows. On all other systems, the default is the x86/AMD ABI.
5884 Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
5885 requires the @option{-maccumulate-outgoing-args} option.
5887 @item callee_pop_aggregate_return (@var{number})
5888 @cindex @code{callee_pop_aggregate_return} function attribute, x86
5890 On x86-32 targets, you can use this attribute to control how
5891 aggregates are returned in memory. If the caller is responsible for
5892 popping the hidden pointer together with the rest of the arguments, specify
5893 @var{number} equal to zero. If callee is responsible for popping the
5894 hidden pointer, specify @var{number} equal to one.
5896 The default x86-32 ABI assumes that the callee pops the
5897 stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
5898 the compiler assumes that the
5899 caller pops the stack for hidden pointer.
5901 @item ms_hook_prologue
5902 @cindex @code{ms_hook_prologue} function attribute, x86
5904 On 32-bit and 64-bit x86 targets, you can use
5905 this function attribute to make GCC generate the ``hot-patching'' function
5906 prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
5910 @cindex @code{naked} function attribute, x86
5911 This attribute allows the compiler to construct the
5912 requisite function declaration, while allowing the body of the
5913 function to be assembly code. The specified function will not have
5914 prologue/epilogue sequences generated by the compiler. Only basic
5915 @code{asm} statements can safely be included in naked functions
5916 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5917 basic @code{asm} and C code may appear to work, they cannot be
5918 depended upon to work reliably and are not supported.
5920 @item regparm (@var{number})
5921 @cindex @code{regparm} function attribute, x86
5922 @cindex functions that are passed arguments in registers on x86-32
5923 On x86-32 targets, the @code{regparm} attribute causes the compiler to
5924 pass arguments number one to @var{number} if they are of integral type
5925 in registers EAX, EDX, and ECX instead of on the stack. Functions that
5926 take a variable number of arguments continue to be passed all of their
5927 arguments on the stack.
5929 Beware that on some ELF systems this attribute is unsuitable for
5930 global functions in shared libraries with lazy binding (which is the
5931 default). Lazy binding sends the first call via resolving code in
5932 the loader, which might assume EAX, EDX and ECX can be clobbered, as
5933 per the standard calling conventions. Solaris 8 is affected by this.
5934 Systems with the GNU C Library version 2.1 or higher
5935 and FreeBSD are believed to be
5936 safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
5937 disabled with the linker or the loader if desired, to avoid the
5941 @cindex @code{sseregparm} function attribute, x86
5942 On x86-32 targets with SSE support, the @code{sseregparm} attribute
5943 causes the compiler to pass up to 3 floating-point arguments in
5944 SSE registers instead of on the stack. Functions that take a
5945 variable number of arguments continue to pass all of their
5946 floating-point arguments on the stack.
5948 @item force_align_arg_pointer
5949 @cindex @code{force_align_arg_pointer} function attribute, x86
5950 On x86 targets, the @code{force_align_arg_pointer} attribute may be
5951 applied to individual function definitions, generating an alternate
5952 prologue and epilogue that realigns the run-time stack if necessary.
5953 This supports mixing legacy codes that run with a 4-byte aligned stack
5954 with modern codes that keep a 16-byte stack for SSE compatibility.
5957 @cindex @code{stdcall} function attribute, x86-32
5958 @cindex functions that pop the argument stack on x86-32
5959 On x86-32 targets, the @code{stdcall} attribute causes the compiler to
5960 assume that the called function pops off the stack space used to
5961 pass arguments, unless it takes a variable number of arguments.
5963 @item no_caller_saved_registers
5964 @cindex @code{no_caller_saved_registers} function attribute, x86
5965 Use this attribute to indicate that the specified function has no
5966 caller-saved registers. That is, all registers are callee-saved. For
5967 example, this attribute can be used for a function called from an
5968 interrupt handler. The compiler generates proper function entry and
5969 exit sequences to save and restore any modified registers, except for
5970 the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87
5971 states, the GCC option @option{-mgeneral-regs-only} should be used to
5972 compile functions with @code{no_caller_saved_registers} attribute.
5975 @cindex @code{interrupt} function attribute, x86
5976 Use this attribute to indicate that the specified function is an
5977 interrupt handler or an exception handler (depending on parameters passed
5978 to the function, explained further). The compiler generates function
5979 entry and exit sequences suitable for use in an interrupt handler when
5980 this attribute is present. The @code{IRET} instruction, instead of the
5981 @code{RET} instruction, is used to return from interrupt handlers. All
5982 registers, except for the EFLAGS register which is restored by the
5983 @code{IRET} instruction, are preserved by the compiler. Since GCC
5984 doesn't preserve SSE, MMX nor x87 states, the GCC option
5985 @option{-mgeneral-regs-only} should be used to compile interrupt and
5988 Any interruptible-without-stack-switch code must be compiled with
5989 @option{-mno-red-zone} since interrupt handlers can and will, because
5990 of the hardware design, touch the red zone.
5992 An interrupt handler must be declared with a mandatory pointer
5996 struct interrupt_frame;
5998 __attribute__ ((interrupt))
6000 f (struct interrupt_frame *frame)
6006 and you must define @code{struct interrupt_frame} as described in the
6009 Exception handlers differ from interrupt handlers because the system
6010 pushes an error code on the stack. An exception handler declaration is
6011 similar to that for an interrupt handler, but with a different mandatory
6012 function signature. The compiler arranges to pop the error code off the
6013 stack before the @code{IRET} instruction.
6017 typedef unsigned long long int uword_t;
6019 typedef unsigned int uword_t;
6022 struct interrupt_frame;
6024 __attribute__ ((interrupt))
6026 f (struct interrupt_frame *frame, uword_t error_code)
6032 Exception handlers should only be used for exceptions that push an error
6033 code; you should use an interrupt handler in other cases. The system
6034 will crash if the wrong kind of handler is used.
6036 @item target (@var{options})
6037 @cindex @code{target} function attribute
6038 As discussed in @ref{Common Function Attributes}, this attribute
6039 allows specification of target-specific compilation options.
6041 On the x86, the following options are allowed:
6045 @cindex @code{target("3dnow")} function attribute, x86
6046 Enable/disable the generation of the 3DNow!@: instructions.
6050 @cindex @code{target("3dnowa")} function attribute, x86
6051 Enable/disable the generation of the enhanced 3DNow!@: instructions.
6055 @cindex @code{target("abm")} function attribute, x86
6056 Enable/disable the generation of the advanced bit instructions.
6060 @cindex @code{target("adx")} function attribute, x86
6061 Enable/disable the generation of the ADX instructions.
6065 @cindex @code{target("aes")} function attribute, x86
6066 Enable/disable the generation of the AES instructions.
6070 @cindex @code{target("avx")} function attribute, x86
6071 Enable/disable the generation of the AVX instructions.
6075 @cindex @code{target("avx2")} function attribute, x86
6076 Enable/disable the generation of the AVX2 instructions.
6079 @itemx no-avx5124fmaps
6080 @cindex @code{target("avx5124fmaps")} function attribute, x86
6081 Enable/disable the generation of the AVX5124FMAPS instructions.
6084 @itemx no-avx5124vnniw
6085 @cindex @code{target("avx5124vnniw")} function attribute, x86
6086 Enable/disable the generation of the AVX5124VNNIW instructions.
6089 @itemx no-avx512bitalg
6090 @cindex @code{target("avx512bitalg")} function attribute, x86
6091 Enable/disable the generation of the AVX512BITALG instructions.
6095 @cindex @code{target("avx512bw")} function attribute, x86
6096 Enable/disable the generation of the AVX512BW instructions.
6100 @cindex @code{target("avx512cd")} function attribute, x86
6101 Enable/disable the generation of the AVX512CD instructions.
6105 @cindex @code{target("avx512dq")} function attribute, x86
6106 Enable/disable the generation of the AVX512DQ instructions.
6110 @cindex @code{target("avx512er")} function attribute, x86
6111 Enable/disable the generation of the AVX512ER instructions.
6115 @cindex @code{target("avx512f")} function attribute, x86
6116 Enable/disable the generation of the AVX512F instructions.
6119 @itemx no-avx512ifma
6120 @cindex @code{target("avx512ifma")} function attribute, x86
6121 Enable/disable the generation of the AVX512IFMA instructions.
6125 @cindex @code{target("avx512pf")} function attribute, x86
6126 Enable/disable the generation of the AVX512PF instructions.
6129 @itemx no-avx512vbmi
6130 @cindex @code{target("avx512vbmi")} function attribute, x86
6131 Enable/disable the generation of the AVX512VBMI instructions.
6134 @itemx no-avx512vbmi2
6135 @cindex @code{target("avx512vbmi2")} function attribute, x86
6136 Enable/disable the generation of the AVX512VBMI2 instructions.
6140 @cindex @code{target("avx512vl")} function attribute, x86
6141 Enable/disable the generation of the AVX512VL instructions.
6144 @itemx no-avx512vnni
6145 @cindex @code{target("avx512vnni")} function attribute, x86
6146 Enable/disable the generation of the AVX512VNNI instructions.
6148 @item avx512vpopcntdq
6149 @itemx no-avx512vpopcntdq
6150 @cindex @code{target("avx512vpopcntdq")} function attribute, x86
6151 Enable/disable the generation of the AVX512VPOPCNTDQ instructions.
6155 @cindex @code{target("bmi")} function attribute, x86
6156 Enable/disable the generation of the BMI instructions.
6160 @cindex @code{target("bmi2")} function attribute, x86
6161 Enable/disable the generation of the BMI2 instructions.
6165 @cindex @code{target("cldemote")} function attribute, x86
6166 Enable/disable the generation of the CLDEMOTE instructions.
6169 @itemx no-clflushopt
6170 @cindex @code{target("clflushopt")} function attribute, x86
6171 Enable/disable the generation of the CLFLUSHOPT instructions.
6175 @cindex @code{target("clwb")} function attribute, x86
6176 Enable/disable the generation of the CLWB instructions.
6180 @cindex @code{target("clzero")} function attribute, x86
6181 Enable/disable the generation of the CLZERO instructions.
6185 @cindex @code{target("crc32")} function attribute, x86
6186 Enable/disable the generation of the CRC32 instructions.
6190 @cindex @code{target("cx16")} function attribute, x86
6191 Enable/disable the generation of the CMPXCHG16B instructions.
6194 @cindex @code{target("default")} function attribute, x86
6195 @xref{Function Multiversioning}, where it is used to specify the
6196 default function version.
6200 @cindex @code{target("f16c")} function attribute, x86
6201 Enable/disable the generation of the F16C instructions.
6205 @cindex @code{target("fma")} function attribute, x86
6206 Enable/disable the generation of the FMA instructions.
6210 @cindex @code{target("fma4")} function attribute, x86
6211 Enable/disable the generation of the FMA4 instructions.
6215 @cindex @code{target("fsgsbase")} function attribute, x86
6216 Enable/disable the generation of the FSGSBASE instructions.
6220 @cindex @code{target("fxsr")} function attribute, x86
6221 Enable/disable the generation of the FXSR instructions.
6225 @cindex @code{target("gfni")} function attribute, x86
6226 Enable/disable the generation of the GFNI instructions.
6230 @cindex @code{target("hle")} function attribute, x86
6231 Enable/disable the generation of the HLE instruction prefixes.
6235 @cindex @code{target("lwp")} function attribute, x86
6236 Enable/disable the generation of the LWP instructions.
6240 @cindex @code{target("lzcnt")} function attribute, x86
6241 Enable/disable the generation of the LZCNT instructions.
6245 @cindex @code{target("mmx")} function attribute, x86
6246 Enable/disable the generation of the MMX instructions.
6250 @cindex @code{target("movbe")} function attribute, x86
6251 Enable/disable the generation of the MOVBE instructions.
6255 @cindex @code{target("movdir64b")} function attribute, x86
6256 Enable/disable the generation of the MOVDIR64B instructions.
6260 @cindex @code{target("movdiri")} function attribute, x86
6261 Enable/disable the generation of the MOVDIRI instructions.
6265 @cindex @code{target("mwaitx")} function attribute, x86
6266 Enable/disable the generation of the MWAITX instructions.
6270 @cindex @code{target("pclmul")} function attribute, x86
6271 Enable/disable the generation of the PCLMUL instructions.
6275 @cindex @code{target("pconfig")} function attribute, x86
6276 Enable/disable the generation of the PCONFIG instructions.
6280 @cindex @code{target("pku")} function attribute, x86
6281 Enable/disable the generation of the PKU instructions.
6285 @cindex @code{target("popcnt")} function attribute, x86
6286 Enable/disable the generation of the POPCNT instruction.
6289 @itemx no-prefetchwt1
6290 @cindex @code{target("prefetchwt1")} function attribute, x86
6291 Enable/disable the generation of the PREFETCHWT1 instructions.
6295 @cindex @code{target("prfchw")} function attribute, x86
6296 Enable/disable the generation of the PREFETCHW instruction.
6300 @cindex @code{target("ptwrite")} function attribute, x86
6301 Enable/disable the generation of the PTWRITE instructions.
6305 @cindex @code{target("rdpid")} function attribute, x86
6306 Enable/disable the generation of the RDPID instructions.
6310 @cindex @code{target("rdrnd")} function attribute, x86
6311 Enable/disable the generation of the RDRND instructions.
6315 @cindex @code{target("rdseed")} function attribute, x86
6316 Enable/disable the generation of the RDSEED instructions.
6320 @cindex @code{target("rtm")} function attribute, x86
6321 Enable/disable the generation of the RTM instructions.
6325 @cindex @code{target("sahf")} function attribute, x86
6326 Enable/disable the generation of the SAHF instructions.
6330 @cindex @code{target("sgx")} function attribute, x86
6331 Enable/disable the generation of the SGX instructions.
6335 @cindex @code{target("sha")} function attribute, x86
6336 Enable/disable the generation of the SHA instructions.
6340 @cindex @code{target("shstk")} function attribute, x86
6341 Enable/disable the shadow stack built-in functions from CET.
6345 @cindex @code{target("sse")} function attribute, x86
6346 Enable/disable the generation of the SSE instructions.
6350 @cindex @code{target("sse2")} function attribute, x86
6351 Enable/disable the generation of the SSE2 instructions.
6355 @cindex @code{target("sse3")} function attribute, x86
6356 Enable/disable the generation of the SSE3 instructions.
6360 @cindex @code{target("sse4")} function attribute, x86
6361 Enable/disable the generation of the SSE4 instructions (both SSE4.1
6366 @cindex @code{target("sse4.1")} function attribute, x86
6367 Enable/disable the generation of the sse4.1 instructions.
6371 @cindex @code{target("sse4.2")} function attribute, x86
6372 Enable/disable the generation of the sse4.2 instructions.
6376 @cindex @code{target("sse4a")} function attribute, x86
6377 Enable/disable the generation of the SSE4A instructions.
6381 @cindex @code{target("ssse3")} function attribute, x86
6382 Enable/disable the generation of the SSSE3 instructions.
6386 @cindex @code{target("tbm")} function attribute, x86
6387 Enable/disable the generation of the TBM instructions.
6391 @cindex @code{target("vaes")} function attribute, x86
6392 Enable/disable the generation of the VAES instructions.
6395 @itemx no-vpclmulqdq
6396 @cindex @code{target("vpclmulqdq")} function attribute, x86
6397 Enable/disable the generation of the VPCLMULQDQ instructions.
6401 @cindex @code{target("waitpkg")} function attribute, x86
6402 Enable/disable the generation of the WAITPKG instructions.
6406 @cindex @code{target("wbnoinvd")} function attribute, x86
6407 Enable/disable the generation of the WBNOINVD instructions.
6411 @cindex @code{target("xop")} function attribute, x86
6412 Enable/disable the generation of the XOP instructions.
6416 @cindex @code{target("xsave")} function attribute, x86
6417 Enable/disable the generation of the XSAVE instructions.
6421 @cindex @code{target("xsavec")} function attribute, x86
6422 Enable/disable the generation of the XSAVEC instructions.
6426 @cindex @code{target("xsaveopt")} function attribute, x86
6427 Enable/disable the generation of the XSAVEOPT instructions.
6431 @cindex @code{target("xsaves")} function attribute, x86
6432 Enable/disable the generation of the XSAVES instructions.
6436 @cindex @code{target("cld")} function attribute, x86
6437 Enable/disable the generation of the CLD before string moves.
6439 @item fancy-math-387
6440 @itemx no-fancy-math-387
6441 @cindex @code{target("fancy-math-387")} function attribute, x86
6442 Enable/disable the generation of the @code{sin}, @code{cos}, and
6443 @code{sqrt} instructions on the 387 floating-point unit.
6447 @cindex @code{target("ieee-fp")} function attribute, x86
6448 Enable/disable the generation of floating point that depends on IEEE arithmetic.
6450 @item inline-all-stringops
6451 @itemx no-inline-all-stringops
6452 @cindex @code{target("inline-all-stringops")} function attribute, x86
6453 Enable/disable inlining of string operations.
6455 @item inline-stringops-dynamically
6456 @itemx no-inline-stringops-dynamically
6457 @cindex @code{target("inline-stringops-dynamically")} function attribute, x86
6458 Enable/disable the generation of the inline code to do small string
6459 operations and calling the library routines for large operations.
6461 @item align-stringops
6462 @itemx no-align-stringops
6463 @cindex @code{target("align-stringops")} function attribute, x86
6464 Do/do not align destination of inlined string operations.
6468 @cindex @code{target("recip")} function attribute, x86
6469 Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
6470 instructions followed an additional Newton-Raphson step instead of
6471 doing a floating-point division.
6473 @item arch=@var{ARCH}
6474 @cindex @code{target("arch=@var{ARCH}")} function attribute, x86
6475 Specify the architecture to generate code for in compiling the function.
6477 @item tune=@var{TUNE}
6478 @cindex @code{target("tune=@var{TUNE}")} function attribute, x86
6479 Specify the architecture to tune for in compiling the function.
6481 @item fpmath=@var{FPMATH}
6482 @cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
6483 Specify which floating-point unit to use. You must specify the
6484 @code{target("fpmath=sse,387")} option as
6485 @code{target("fpmath=sse+387")} because the comma would separate
6488 @item indirect_branch("@var{choice}")
6489 @cindex @code{indirect_branch} function attribute, x86
6490 On x86 targets, the @code{indirect_branch} attribute causes the compiler
6491 to convert indirect call and jump with @var{choice}. @samp{keep}
6492 keeps indirect call and jump unmodified. @samp{thunk} converts indirect
6493 call and jump to call and return thunk. @samp{thunk-inline} converts
6494 indirect call and jump to inlined call and return thunk.
6495 @samp{thunk-extern} converts indirect call and jump to external call
6496 and return thunk provided in a separate object file.
6498 @item function_return("@var{choice}")
6499 @cindex @code{function_return} function attribute, x86
6500 On x86 targets, the @code{function_return} attribute causes the compiler
6501 to convert function return with @var{choice}. @samp{keep} keeps function
6502 return unmodified. @samp{thunk} converts function return to call and
6503 return thunk. @samp{thunk-inline} converts function return to inlined
6504 call and return thunk. @samp{thunk-extern} converts function return to
6505 external call and return thunk provided in a separate object file.
6508 @cindex @code{nocf_check} function attribute
6509 The @code{nocf_check} attribute on a function is used to inform the
6510 compiler that the function's prologue should not be instrumented when
6511 compiled with the @option{-fcf-protection=branch} option. The
6512 compiler assumes that the function's address is a valid target for a
6513 control-flow transfer.
6515 The @code{nocf_check} attribute on a type of pointer to function is
6516 used to inform the compiler that a call through the pointer should
6517 not be instrumented when compiled with the
6518 @option{-fcf-protection=branch} option. The compiler assumes
6519 that the function's address from the pointer is a valid target for
6520 a control-flow transfer. A direct function call through a function
6521 name is assumed to be a safe call thus direct calls are not
6522 instrumented by the compiler.
6524 The @code{nocf_check} attribute is applied to an object's type.
6525 In case of assignment of a function address or a function pointer to
6526 another pointer, the attribute is not carried over from the right-hand
6527 object's type; the type of left-hand object stays unchanged. The
6528 compiler checks for @code{nocf_check} attribute mismatch and reports
6529 a warning in case of mismatch.
6533 int foo (void) __attribute__(nocf_check);
6534 void (*foo1)(void) __attribute__(nocf_check);
6537 /* foo's address is assumed to be valid. */
6541 /* This call site is not checked for control-flow
6545 /* A warning is issued about attribute mismatch. */
6548 /* This call site is still not checked. */
6551 /* This call site is checked. */
6554 /* A warning is issued about attribute mismatch. */
6557 /* This call site is still checked. */
6565 @cindex @code{cf_check} function attribute, x86
6567 The @code{cf_check} attribute on a function is used to inform the
6568 compiler that ENDBR instruction should be placed at the function
6569 entry when @option{-fcf-protection=branch} is enabled.
6571 @item indirect_return
6572 @cindex @code{indirect_return} function attribute, x86
6574 The @code{indirect_return} attribute can be applied to a function,
6575 as well as variable or type of function pointer to inform the
6576 compiler that the function may return via indirect branch.
6578 @item fentry_name("@var{name}")
6579 @cindex @code{fentry_name} function attribute, x86
6580 On x86 targets, the @code{fentry_name} attribute sets the function to
6581 call on function entry when function instrumentation is enabled
6582 with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte
6583 nop sequence is generated.
6585 @item fentry_section("@var{name}")
6586 @cindex @code{fentry_section} function attribute, x86
6587 On x86 targets, the @code{fentry_section} attribute sets the name
6588 of the section to record function entry instrumentation calls in when
6589 enabled with @option{-pg -mrecord-mcount}
6593 On the x86, the inliner does not inline a
6594 function that has different target options than the caller, unless the
6595 callee has a subset of the target options of the caller. For example
6596 a function declared with @code{target("sse3")} can inline a function
6597 with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
6600 @node Xstormy16 Function Attributes
6601 @subsection Xstormy16 Function Attributes
6603 These function attributes are supported by the Xstormy16 back end:
6607 @cindex @code{interrupt} function attribute, Xstormy16
6608 Use this attribute to indicate
6609 that the specified function is an interrupt handler. The compiler generates
6610 function entry and exit sequences suitable for use in an interrupt handler
6611 when this attribute is present.
6614 @node Variable Attributes
6615 @section Specifying Attributes of Variables
6616 @cindex attribute of variables
6617 @cindex variable attributes
6619 The keyword @code{__attribute__} allows you to specify special properties
6620 of variables, function parameters, or structure, union, and, in C++, class
6621 members. This @code{__attribute__} keyword is followed by an attribute
6622 specification enclosed in double parentheses. Some attributes are currently
6623 defined generically for variables. Other attributes are defined for
6624 variables on particular target systems. Other attributes are available
6625 for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
6626 enumerators (@pxref{Enumerator Attributes}), statements
6627 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
6628 Other front ends might define more attributes
6629 (@pxref{C++ Extensions,,Extensions to the C++ Language}).
6631 @xref{Attribute Syntax}, for details of the exact syntax for using
6635 * Common Variable Attributes::
6636 * ARC Variable Attributes::
6637 * AVR Variable Attributes::
6638 * Blackfin Variable Attributes::
6639 * H8/300 Variable Attributes::
6640 * IA-64 Variable Attributes::
6641 * M32R/D Variable Attributes::
6642 * MeP Variable Attributes::
6643 * Microsoft Windows Variable Attributes::
6644 * MSP430 Variable Attributes::
6645 * Nvidia PTX Variable Attributes::
6646 * PowerPC Variable Attributes::
6647 * RL78 Variable Attributes::
6648 * SPU Variable Attributes::
6649 * V850 Variable Attributes::
6650 * x86 Variable Attributes::
6651 * Xstormy16 Variable Attributes::
6654 @node Common Variable Attributes
6655 @subsection Common Variable Attributes
6657 The following attributes are supported on most targets.
6660 @cindex @code{aligned} variable attribute
6662 @itemx aligned (@var{alignment})
6663 The @code{aligned} attribute specifies a minimum alignment for the variable
6664 or structure field, measured in bytes. When specified, @var{alignment} must
6665 be an integer constant power of 2. Specifying no @var{alignment} argument
6666 implies the maximum alignment for the target, which is often, but by no
6667 means always, 8 or 16 bytes.
6669 For example, the declaration:
6672 int x __attribute__ ((aligned (16))) = 0;
6676 causes the compiler to allocate the global variable @code{x} on a
6677 16-byte boundary. On a 68040, this could be used in conjunction with
6678 an @code{asm} expression to access the @code{move16} instruction which
6679 requires 16-byte aligned operands.
6681 You can also specify the alignment of structure fields. For example, to
6682 create a double-word aligned @code{int} pair, you could write:
6685 struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
6689 This is an alternative to creating a union with a @code{double} member,
6690 which forces the union to be double-word aligned.
6692 As in the preceding examples, you can explicitly specify the alignment
6693 (in bytes) that you wish the compiler to use for a given variable or
6694 structure field. Alternatively, you can leave out the alignment factor
6695 and just ask the compiler to align a variable or field to the
6696 default alignment for the target architecture you are compiling for.
6697 The default alignment is sufficient for all scalar types, but may not be
6698 enough for all vector types on a target that supports vector operations.
6699 The default alignment is fixed for a particular target ABI.
6701 GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
6702 which is the largest alignment ever used for any data type on the
6703 target machine you are compiling for. For example, you could write:
6706 short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
6709 The compiler automatically sets the alignment for the declared
6710 variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
6711 often make copy operations more efficient, because the compiler can
6712 use whatever instructions copy the biggest chunks of memory when
6713 performing copies to or from the variables or fields that you have
6714 aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
6715 may change depending on command-line options.
6717 When used on a struct, or struct member, the @code{aligned} attribute can
6718 only increase the alignment; in order to decrease it, the @code{packed}
6719 attribute must be specified as well. When used as part of a typedef, the
6720 @code{aligned} attribute can both increase and decrease alignment, and
6721 specifying the @code{packed} attribute generates a warning.
6723 Note that the effectiveness of @code{aligned} attributes for static
6724 variables may be limited by inherent limitations in the system linker
6725 and/or object file format. On some systems, the linker is
6726 only able to arrange for variables to be aligned up to a certain maximum
6727 alignment. (For some linkers, the maximum supported alignment may
6728 be very very small.) If your linker is only able to align variables
6729 up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
6730 in an @code{__attribute__} still only provides you with 8-byte
6731 alignment. See your linker documentation for further information.
6733 Stack variables are not affected by linker restrictions; GCC can properly
6734 align them on any target.
6736 The @code{aligned} attribute can also be used for functions
6737 (@pxref{Common Function Attributes}.)
6739 @cindex @code{warn_if_not_aligned} variable attribute
6740 @item warn_if_not_aligned (@var{alignment})
6741 This attribute specifies a threshold for the structure field, measured
6742 in bytes. If the structure field is aligned below the threshold, a
6743 warning will be issued. For example, the declaration:
6750 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
6755 causes the compiler to issue an warning on @code{struct foo}, like
6756 @samp{warning: alignment 8 of 'struct foo' is less than 16}.
6757 The compiler also issues a warning, like @samp{warning: 'x' offset
6758 8 in 'struct foo' isn't aligned to 16}, when the structure field has
6759 the misaligned offset:
6762 struct __attribute__ ((aligned (16))) foo
6766 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
6770 This warning can be disabled by @option{-Wno-if-not-aligned}.
6771 The @code{warn_if_not_aligned} attribute can also be used for types
6772 (@pxref{Common Type Attributes}.)
6774 @item alloc_size (@var{position})
6775 @itemx alloc_size (@var{position-1}, @var{position-2})
6776 @cindex @code{alloc_size} variable attribute
6777 The @code{alloc_size} variable attribute may be applied to the declaration
6778 of a pointer to a function that returns a pointer and takes at least one
6779 argument of an integer type. It indicates that the returned pointer points
6780 to an object whose size is given by the function argument at @var{position-1},
6781 or by the product of the arguments at @var{position-1} and @var{position-2}.
6782 Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other
6783 sizes are disagnosed when detected. GCC uses this information to improve
6784 the results of @code{__builtin_object_size}.
6786 For instance, the following declarations
6789 typedef __attribute__ ((alloc_size (1, 2))) void*
6790 (*calloc_ptr) (size_t, size_t);
6791 typedef __attribute__ ((alloc_size (1))) void*
6792 (*malloc_ptr) (size_t);
6796 specify that @code{calloc_ptr} is a pointer of a function that, like
6797 the standard C function @code{calloc}, returns an object whose size
6798 is given by the product of arguments 1 and 2, and similarly, that
6799 @code{malloc_ptr}, like the standard C function @code{malloc},
6800 returns an object whose size is given by argument 1 to the function.
6802 @item cleanup (@var{cleanup_function})
6803 @cindex @code{cleanup} variable attribute
6804 The @code{cleanup} attribute runs a function when the variable goes
6805 out of scope. This attribute can only be applied to auto function
6806 scope variables; it may not be applied to parameters or variables
6807 with static storage duration. The function must take one parameter,
6808 a pointer to a type compatible with the variable. The return value
6809 of the function (if any) is ignored.
6811 If @option{-fexceptions} is enabled, then @var{cleanup_function}
6812 is run during the stack unwinding that happens during the
6813 processing of the exception. Note that the @code{cleanup} attribute
6814 does not allow the exception to be caught, only to perform an action.
6815 It is undefined what happens if @var{cleanup_function} does not
6820 @cindex @code{common} variable attribute
6821 @cindex @code{nocommon} variable attribute
6824 The @code{common} attribute requests GCC to place a variable in
6825 ``common'' storage. The @code{nocommon} attribute requests the
6826 opposite---to allocate space for it directly.
6828 These attributes override the default chosen by the
6829 @option{-fno-common} and @option{-fcommon} flags respectively.
6832 @itemx copy (@var{variable})
6833 @cindex @code{copy} variable attribute
6834 The @code{copy} attribute applies the set of attributes with which
6835 @var{variable} has been declared to the declaration of the variable
6836 to which the attribute is applied. The attribute is designed for
6837 libraries that define aliases that are expected to specify the same
6838 set of attributes as the aliased symbols. The @code{copy} attribute
6839 can be used with variables, functions or types. However, the kind
6840 of symbol to which the attribute is applied (either varible or
6841 function) must match the kind of symbol to which the argument refers.
6842 The @code{copy} attribute copies only syntactic and semantic attributes
6843 but not attributes that affect a symbol's linkage or visibility such as
6844 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
6845 attribute is also not copied. @xref{Common Function Attributes}.
6846 @xref{Common Type Attributes}.
6849 @itemx deprecated (@var{msg})
6850 @cindex @code{deprecated} variable attribute
6851 The @code{deprecated} attribute results in a warning if the variable
6852 is used anywhere in the source file. This is useful when identifying
6853 variables that are expected to be removed in a future version of a
6854 program. The warning also includes the location of the declaration
6855 of the deprecated variable, to enable users to easily find further
6856 information about why the variable is deprecated, or what they should
6857 do instead. Note that the warning only occurs for uses:
6860 extern int old_var __attribute__ ((deprecated));
6862 int new_fn () @{ return old_var; @}
6866 results in a warning on line 3 but not line 2. The optional @var{msg}
6867 argument, which must be a string, is printed in the warning if
6870 The @code{deprecated} attribute can also be used for functions and
6871 types (@pxref{Common Function Attributes},
6872 @pxref{Common Type Attributes}).
6874 The message attached to the attribute is affected by the setting of
6875 the @option{-fmessage-length} option.
6877 @item mode (@var{mode})
6878 @cindex @code{mode} variable attribute
6879 This attribute specifies the data type for the declaration---whichever
6880 type corresponds to the mode @var{mode}. This in effect lets you
6881 request an integer or floating-point type according to its width.
6883 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
6884 for a list of the possible keywords for @var{mode}.
6885 You may also specify a mode of @code{byte} or @code{__byte__} to
6886 indicate the mode corresponding to a one-byte integer, @code{word} or
6887 @code{__word__} for the mode of a one-word integer, and @code{pointer}
6888 or @code{__pointer__} for the mode used to represent pointers.
6891 @cindex @code{nonstring} variable attribute
6892 The @code{nonstring} variable attribute specifies that an object or member
6893 declaration with type array of @code{char}, @code{signed char}, or
6894 @code{unsigned char}, or pointer to such a type is intended to store
6895 character arrays that do not necessarily contain a terminating @code{NUL}.
6896 This is useful in detecting uses of such arrays or pointers with functions
6897 that expect @code{NUL}-terminated strings, and to avoid warnings when such
6898 an array or pointer is used as an argument to a bounded string manipulation
6899 function such as @code{strncpy}. For example, without the attribute, GCC
6900 will issue a warning for the @code{strncpy} call below because it may
6901 truncate the copy without appending the terminating @code{NUL} character.
6902 Using the attribute makes it possible to suppress the warning. However,
6903 when the array is declared with the attribute the call to @code{strlen} is
6904 diagnosed because when the array doesn't contain a @code{NUL}-terminated
6905 string the call is undefined. To copy, compare, of search non-string
6906 character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr},
6907 and other functions that operate on arrays of bytes. In addition,
6908 calling @code{strnlen} and @code{strndup} with such arrays is safe
6909 provided a suitable bound is specified, and not diagnosed.
6914 char name [32] __attribute__ ((nonstring));
6917 int f (struct Data *pd, const char *s)
6919 strncpy (pd->name, s, sizeof pd->name);
6921 return strlen (pd->name); // unsafe, gets a warning
6926 @cindex @code{packed} variable attribute
6927 The @code{packed} attribute specifies that a structure member should have
6928 the smallest possible alignment---one bit for a bit-field and one byte
6929 otherwise, unless a larger value is specified with the @code{aligned}
6930 attribute. The attribute does not apply to non-member objects.
6932 For example in the structure below, the member array @code{x} is packed
6933 so that it immediately follows @code{a} with no intervening padding:
6939 int x[2] __attribute__ ((packed));
6943 @emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
6944 @code{packed} attribute on bit-fields of type @code{char}. This has
6945 been fixed in GCC 4.4 but the change can lead to differences in the
6946 structure layout. See the documentation of
6947 @option{-Wpacked-bitfield-compat} for more information.
6949 @item section ("@var{section-name}")
6950 @cindex @code{section} variable attribute
6951 Normally, the compiler places the objects it generates in sections like
6952 @code{data} and @code{bss}. Sometimes, however, you need additional sections,
6953 or you need certain particular variables to appear in special sections,
6954 for example to map to special hardware. The @code{section}
6955 attribute specifies that a variable (or function) lives in a particular
6956 section. For example, this small program uses several specific section names:
6959 struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
6960 struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
6961 char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
6962 int init_data __attribute__ ((section ("INITDATA")));
6966 /* @r{Initialize stack pointer} */
6967 init_sp (stack + sizeof (stack));
6969 /* @r{Initialize initialized data} */
6970 memcpy (&init_data, &data, &edata - &data);
6972 /* @r{Turn on the serial ports} */
6979 Use the @code{section} attribute with
6980 @emph{global} variables and not @emph{local} variables,
6981 as shown in the example.
6983 You may use the @code{section} attribute with initialized or
6984 uninitialized global variables but the linker requires
6985 each object be defined once, with the exception that uninitialized
6986 variables tentatively go in the @code{common} (or @code{bss}) section
6987 and can be multiply ``defined''. Using the @code{section} attribute
6988 changes what section the variable goes into and may cause the
6989 linker to issue an error if an uninitialized variable has multiple
6990 definitions. You can force a variable to be initialized with the
6991 @option{-fno-common} flag or the @code{nocommon} attribute.
6993 Some file formats do not support arbitrary sections so the @code{section}
6994 attribute is not available on all platforms.
6995 If you need to map the entire contents of a module to a particular
6996 section, consider using the facilities of the linker instead.
6998 @item tls_model ("@var{tls_model}")
6999 @cindex @code{tls_model} variable attribute
7000 The @code{tls_model} attribute sets thread-local storage model
7001 (@pxref{Thread-Local}) of a particular @code{__thread} variable,
7002 overriding @option{-ftls-model=} command-line switch on a per-variable
7004 The @var{tls_model} argument should be one of @code{global-dynamic},
7005 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
7007 Not all targets support this attribute.
7010 @cindex @code{unused} variable attribute
7011 This attribute, attached to a variable, means that the variable is meant
7012 to be possibly unused. GCC does not produce a warning for this
7016 @cindex @code{used} variable attribute
7017 This attribute, attached to a variable with static storage, means that
7018 the variable must be emitted even if it appears that the variable is not
7021 When applied to a static data member of a C++ class template, the
7022 attribute also means that the member is instantiated if the
7023 class itself is instantiated.
7025 @item vector_size (@var{bytes})
7026 @cindex @code{vector_size} variable attribute
7027 This attribute specifies the vector size for the variable, measured in
7028 bytes. For example, the declaration:
7031 int foo __attribute__ ((vector_size (16)));
7035 causes the compiler to set the mode for @code{foo}, to be 16 bytes,
7036 divided into @code{int} sized units. Assuming a 32-bit int (a vector of
7037 4 units of 4 bytes), the corresponding mode of @code{foo} is V4SI@.
7039 This attribute is only applicable to integral and float scalars,
7040 although arrays, pointers, and function return values are allowed in
7041 conjunction with this construct.
7043 Aggregates with this attribute are invalid, even if they are of the same
7044 size as a corresponding scalar. For example, the declaration:
7047 struct S @{ int a; @};
7048 struct S __attribute__ ((vector_size (16))) foo;
7052 is invalid even if the size of the structure is the same as the size of
7055 @item visibility ("@var{visibility_type}")
7056 @cindex @code{visibility} variable attribute
7057 This attribute affects the linkage of the declaration to which it is attached.
7058 The @code{visibility} attribute is described in
7059 @ref{Common Function Attributes}.
7062 @cindex @code{weak} variable attribute
7063 The @code{weak} attribute is described in
7064 @ref{Common Function Attributes}.
7068 @node ARC Variable Attributes
7069 @subsection ARC Variable Attributes
7073 @cindex @code{aux} variable attribute, ARC
7074 The @code{aux} attribute is used to directly access the ARC's
7075 auxiliary register space from C. The auxilirary register number is
7076 given via attribute argument.
7080 @node AVR Variable Attributes
7081 @subsection AVR Variable Attributes
7085 @cindex @code{progmem} variable attribute, AVR
7086 The @code{progmem} attribute is used on the AVR to place read-only
7087 data in the non-volatile program memory (flash). The @code{progmem}
7088 attribute accomplishes this by putting respective variables into a
7089 section whose name starts with @code{.progmem}.
7091 This attribute works similar to the @code{section} attribute
7092 but adds additional checking.
7095 @item @bullet{}@tie{} Ordinary AVR cores with 32 general purpose registers:
7096 @code{progmem} affects the location
7097 of the data but not how this data is accessed.
7098 In order to read data located with the @code{progmem} attribute
7099 (inline) assembler must be used.
7101 /* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */
7102 #include <avr/pgmspace.h>
7104 /* Locate var in flash memory */
7105 const int var[2] PROGMEM = @{ 1, 2 @};
7107 int read_var (int i)
7109 /* Access var[] by accessor macro from avr/pgmspace.h */
7110 return (int) pgm_read_word (& var[i]);
7114 AVR is a Harvard architecture processor and data and read-only data
7115 normally resides in the data memory (RAM).
7117 See also the @ref{AVR Named Address Spaces} section for
7118 an alternate way to locate and access data in flash memory.
7120 @item @bullet{}@tie{} AVR cores with flash memory visible in the RAM address range:
7121 On such devices, there is no need for attribute @code{progmem} or
7122 @ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all.
7123 Just use standard C / C++. The compiler will generate @code{LD*}
7124 instructions. As flash memory is visible in the RAM address range,
7125 and the default linker script does @emph{not} locate @code{.rodata} in
7126 RAM, no special features are needed in order not to waste RAM for
7127 read-only data or to read from flash. You might even get slightly better
7129 avoiding @code{progmem} and @code{__flash}. This applies to devices from
7130 families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for
7133 @item @bullet{}@tie{}Reduced AVR Tiny cores like ATtiny40:
7134 The compiler adds @code{0x4000}
7135 to the addresses of objects and declarations in @code{progmem} and locates
7136 the objects in flash memory, namely in section @code{.progmem.data}.
7137 The offset is needed because the flash memory is visible in the RAM
7138 address space starting at address @code{0x4000}.
7140 Data in @code{progmem} can be accessed by means of ordinary C@tie{}code,
7141 no special functions or macros are needed.
7144 /* var is located in flash memory */
7145 extern const int var[2] __attribute__((progmem));
7147 int read_var (int i)
7153 Please notice that on these devices, there is no need for @code{progmem}
7159 @itemx io (@var{addr})
7160 @cindex @code{io} variable attribute, AVR
7161 Variables with the @code{io} attribute are used to address
7162 memory-mapped peripherals in the io address range.
7163 If an address is specified, the variable
7164 is assigned that address, and the value is interpreted as an
7165 address in the data address space.
7169 volatile int porta __attribute__((io (0x22)));
7172 The address specified in the address in the data address range.
7174 Otherwise, the variable it is not assigned an address, but the
7175 compiler will still use in/out instructions where applicable,
7176 assuming some other module assigns an address in the io address range.
7180 extern volatile int porta __attribute__((io));
7184 @itemx io_low (@var{addr})
7185 @cindex @code{io_low} variable attribute, AVR
7186 This is like the @code{io} attribute, but additionally it informs the
7187 compiler that the object lies in the lower half of the I/O area,
7188 allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis}
7192 @itemx address (@var{addr})
7193 @cindex @code{address} variable attribute, AVR
7194 Variables with the @code{address} attribute are used to address
7195 memory-mapped peripherals that may lie outside the io address range.
7198 volatile int porta __attribute__((address (0x600)));
7202 @cindex @code{absdata} variable attribute, AVR
7203 Variables in static storage and with the @code{absdata} attribute can
7204 be accessed by the @code{LDS} and @code{STS} instructions which take
7209 This attribute is only supported for the reduced AVR Tiny core
7213 You must make sure that respective data is located in the
7214 address range @code{0x40}@dots{}@code{0xbf} accessible by
7215 @code{LDS} and @code{STS}. One way to achieve this as an
7216 appropriate linker description file.
7219 If the location does not fit the address range of @code{LDS}
7220 and @code{STS}, there is currently (Binutils 2.26) just an unspecific
7223 @code{module.c:(.text+0x1c): warning: internal error: out of range error}
7228 See also the @option{-mabsdata} @ref{AVR Options,command-line option}.
7232 @node Blackfin Variable Attributes
7233 @subsection Blackfin Variable Attributes
7235 Three attributes are currently defined for the Blackfin.
7241 @cindex @code{l1_data} variable attribute, Blackfin
7242 @cindex @code{l1_data_A} variable attribute, Blackfin
7243 @cindex @code{l1_data_B} variable attribute, Blackfin
7244 Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
7245 Variables with @code{l1_data} attribute are put into the specific section
7246 named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into
7247 the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
7248 attribute are put into the specific section named @code{.l1.data.B}.
7251 @cindex @code{l2} variable attribute, Blackfin
7252 Use this attribute on the Blackfin to place the variable into L2 SRAM.
7253 Variables with @code{l2} attribute are put into the specific section
7254 named @code{.l2.data}.
7257 @node H8/300 Variable Attributes
7258 @subsection H8/300 Variable Attributes
7260 These variable attributes are available for H8/300 targets:
7264 @cindex @code{eightbit_data} variable attribute, H8/300
7265 @cindex eight-bit data on the H8/300, H8/300H, and H8S
7266 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
7267 variable should be placed into the eight-bit data section.
7268 The compiler generates more efficient code for certain operations
7269 on data in the eight-bit data area. Note the eight-bit data area is limited to
7272 You must use GAS and GLD from GNU binutils version 2.7 or later for
7273 this attribute to work correctly.
7276 @cindex @code{tiny_data} variable attribute, H8/300
7277 @cindex tiny data section on the H8/300H and H8S
7278 Use this attribute on the H8/300H and H8S to indicate that the specified
7279 variable should be placed into the tiny data section.
7280 The compiler generates more efficient code for loads and stores
7281 on data in the tiny data section. Note the tiny data area is limited to
7282 slightly under 32KB of data.
7286 @node IA-64 Variable Attributes
7287 @subsection IA-64 Variable Attributes
7289 The IA-64 back end supports the following variable attribute:
7292 @item model (@var{model-name})
7293 @cindex @code{model} variable attribute, IA-64
7295 On IA-64, use this attribute to set the addressability of an object.
7296 At present, the only supported identifier for @var{model-name} is
7297 @code{small}, indicating addressability via ``small'' (22-bit)
7298 addresses (so that their addresses can be loaded with the @code{addl}
7299 instruction). Caveat: such addressing is by definition not position
7300 independent and hence this attribute must not be used for objects
7301 defined by shared libraries.
7305 @node M32R/D Variable Attributes
7306 @subsection M32R/D Variable Attributes
7308 One attribute is currently defined for the M32R/D@.
7311 @item model (@var{model-name})
7312 @cindex @code{model-name} variable attribute, M32R/D
7313 @cindex variable addressability on the M32R/D
7314 Use this attribute on the M32R/D to set the addressability of an object.
7315 The identifier @var{model-name} is one of @code{small}, @code{medium},
7316 or @code{large}, representing each of the code models.
7318 Small model objects live in the lower 16MB of memory (so that their
7319 addresses can be loaded with the @code{ld24} instruction).
7321 Medium and large model objects may live anywhere in the 32-bit address space
7322 (the compiler generates @code{seth/add3} instructions to load their
7326 @node MeP Variable Attributes
7327 @subsection MeP Variable Attributes
7329 The MeP target has a number of addressing modes and busses. The
7330 @code{near} space spans the standard memory space's first 16 megabytes
7331 (24 bits). The @code{far} space spans the entire 32-bit memory space.
7332 The @code{based} space is a 128-byte region in the memory space that
7333 is addressed relative to the @code{$tp} register. The @code{tiny}
7334 space is a 65536-byte region relative to the @code{$gp} register. In
7335 addition to these memory regions, the MeP target has a separate 16-bit
7336 control bus which is specified with @code{cb} attributes.
7341 @cindex @code{based} variable attribute, MeP
7342 Any variable with the @code{based} attribute is assigned to the
7343 @code{.based} section, and is accessed with relative to the
7344 @code{$tp} register.
7347 @cindex @code{tiny} variable attribute, MeP
7348 Likewise, the @code{tiny} attribute assigned variables to the
7349 @code{.tiny} section, relative to the @code{$gp} register.
7352 @cindex @code{near} variable attribute, MeP
7353 Variables with the @code{near} attribute are assumed to have addresses
7354 that fit in a 24-bit addressing mode. This is the default for large
7355 variables (@code{-mtiny=4} is the default) but this attribute can
7356 override @code{-mtiny=} for small variables, or override @code{-ml}.
7359 @cindex @code{far} variable attribute, MeP
7360 Variables with the @code{far} attribute are addressed using a full
7361 32-bit address. Since this covers the entire memory space, this
7362 allows modules to make no assumptions about where variables might be
7366 @cindex @code{io} variable attribute, MeP
7367 @itemx io (@var{addr})
7368 Variables with the @code{io} attribute are used to address
7369 memory-mapped peripherals. If an address is specified, the variable
7370 is assigned that address, else it is not assigned an address (it is
7371 assumed some other module assigns an address). Example:
7374 int timer_count __attribute__((io(0x123)));
7378 @itemx cb (@var{addr})
7379 @cindex @code{cb} variable attribute, MeP
7380 Variables with the @code{cb} attribute are used to access the control
7381 bus, using special instructions. @code{addr} indicates the control bus
7385 int cpu_clock __attribute__((cb(0x123)));
7390 @node Microsoft Windows Variable Attributes
7391 @subsection Microsoft Windows Variable Attributes
7393 You can use these attributes on Microsoft Windows targets.
7394 @ref{x86 Variable Attributes} for additional Windows compatibility
7395 attributes available on all x86 targets.
7400 @cindex @code{dllimport} variable attribute
7401 @cindex @code{dllexport} variable attribute
7402 The @code{dllimport} and @code{dllexport} attributes are described in
7403 @ref{Microsoft Windows Function Attributes}.
7406 @cindex @code{selectany} variable attribute
7407 The @code{selectany} attribute causes an initialized global variable to
7408 have link-once semantics. When multiple definitions of the variable are
7409 encountered by the linker, the first is selected and the remainder are
7410 discarded. Following usage by the Microsoft compiler, the linker is told
7411 @emph{not} to warn about size or content differences of the multiple
7414 Although the primary usage of this attribute is for POD types, the
7415 attribute can also be applied to global C++ objects that are initialized
7416 by a constructor. In this case, the static initialization and destruction
7417 code for the object is emitted in each translation defining the object,
7418 but the calls to the constructor and destructor are protected by a
7419 link-once guard variable.
7421 The @code{selectany} attribute is only available on Microsoft Windows
7422 targets. You can use @code{__declspec (selectany)} as a synonym for
7423 @code{__attribute__ ((selectany))} for compatibility with other
7427 @cindex @code{shared} variable attribute
7428 On Microsoft Windows, in addition to putting variable definitions in a named
7429 section, the section can also be shared among all running copies of an
7430 executable or DLL@. For example, this small program defines shared data
7431 by putting it in a named section @code{shared} and marking the section
7435 int foo __attribute__((section ("shared"), shared)) = 0;
7440 /* @r{Read and write foo. All running
7441 copies see the same value.} */
7447 You may only use the @code{shared} attribute along with @code{section}
7448 attribute with a fully-initialized global definition because of the way
7449 linkers work. See @code{section} attribute for more information.
7451 The @code{shared} attribute is only available on Microsoft Windows@.
7455 @node MSP430 Variable Attributes
7456 @subsection MSP430 Variable Attributes
7460 @cindex @code{noinit} variable attribute, MSP430
7461 Any data with the @code{noinit} attribute will not be initialised by
7462 the C runtime startup code, or the program loader. Not initialising
7463 data in this way can reduce program startup times.
7466 @cindex @code{persistent} variable attribute, MSP430
7467 Any variable with the @code{persistent} attribute will not be
7468 initialised by the C runtime startup code. Instead its value will be
7469 set once, when the application is loaded, and then never initialised
7470 again, even if the processor is reset or the program restarts.
7471 Persistent data is intended to be placed into FLASH RAM, where its
7472 value will be retained across resets. The linker script being used to
7473 create the application should ensure that persistent data is correctly
7479 @cindex @code{lower} variable attribute, MSP430
7480 @cindex @code{upper} variable attribute, MSP430
7481 @cindex @code{either} variable attribute, MSP430
7482 These attributes are the same as the MSP430 function attributes of the
7483 same name (@pxref{MSP430 Function Attributes}).
7484 These attributes can be applied to both functions and variables.
7487 @node Nvidia PTX Variable Attributes
7488 @subsection Nvidia PTX Variable Attributes
7490 These variable attributes are supported by the Nvidia PTX back end:
7494 @cindex @code{shared} attribute, Nvidia PTX
7495 Use this attribute to place a variable in the @code{.shared} memory space.
7496 This memory space is private to each cooperative thread array; only threads
7497 within one thread block refer to the same instance of the variable.
7498 The runtime does not initialize variables in this memory space.
7501 @node PowerPC Variable Attributes
7502 @subsection PowerPC Variable Attributes
7504 Three attributes currently are defined for PowerPC configurations:
7505 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
7507 @cindex @code{ms_struct} variable attribute, PowerPC
7508 @cindex @code{gcc_struct} variable attribute, PowerPC
7509 For full documentation of the struct attributes please see the
7510 documentation in @ref{x86 Variable Attributes}.
7512 @cindex @code{altivec} variable attribute, PowerPC
7513 For documentation of @code{altivec} attribute please see the
7514 documentation in @ref{PowerPC Type Attributes}.
7516 @node RL78 Variable Attributes
7517 @subsection RL78 Variable Attributes
7519 @cindex @code{saddr} variable attribute, RL78
7520 The RL78 back end supports the @code{saddr} variable attribute. This
7521 specifies placement of the corresponding variable in the SADDR area,
7522 which can be accessed more efficiently than the default memory region.
7524 @node SPU Variable Attributes
7525 @subsection SPU Variable Attributes
7527 @cindex @code{spu_vector} variable attribute, SPU
7528 The SPU supports the @code{spu_vector} attribute for variables. For
7529 documentation of this attribute please see the documentation in
7530 @ref{SPU Type Attributes}.
7532 @node V850 Variable Attributes
7533 @subsection V850 Variable Attributes
7535 These variable attributes are supported by the V850 back end:
7540 @cindex @code{sda} variable attribute, V850
7541 Use this attribute to explicitly place a variable in the small data area,
7542 which can hold up to 64 kilobytes.
7545 @cindex @code{tda} variable attribute, V850
7546 Use this attribute to explicitly place a variable in the tiny data area,
7547 which can hold up to 256 bytes in total.
7550 @cindex @code{zda} variable attribute, V850
7551 Use this attribute to explicitly place a variable in the first 32 kilobytes
7555 @node x86 Variable Attributes
7556 @subsection x86 Variable Attributes
7558 Two attributes are currently defined for x86 configurations:
7559 @code{ms_struct} and @code{gcc_struct}.
7564 @cindex @code{ms_struct} variable attribute, x86
7565 @cindex @code{gcc_struct} variable attribute, x86
7567 If @code{packed} is used on a structure, or if bit-fields are used,
7568 it may be that the Microsoft ABI lays out the structure differently
7569 than the way GCC normally does. Particularly when moving packed
7570 data between functions compiled with GCC and the native Microsoft compiler
7571 (either via function call or as data in a file), it may be necessary to access
7574 The @code{ms_struct} and @code{gcc_struct} attributes correspond
7575 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
7576 command-line options, respectively;
7577 see @ref{x86 Options}, for details of how structure layout is affected.
7578 @xref{x86 Type Attributes}, for information about the corresponding
7579 attributes on types.
7583 @node Xstormy16 Variable Attributes
7584 @subsection Xstormy16 Variable Attributes
7586 One attribute is currently defined for xstormy16 configurations:
7591 @cindex @code{below100} variable attribute, Xstormy16
7593 If a variable has the @code{below100} attribute (@code{BELOW100} is
7594 allowed also), GCC places the variable in the first 0x100 bytes of
7595 memory and use special opcodes to access it. Such variables are
7596 placed in either the @code{.bss_below100} section or the
7597 @code{.data_below100} section.
7601 @node Type Attributes
7602 @section Specifying Attributes of Types
7603 @cindex attribute of types
7604 @cindex type attributes
7606 The keyword @code{__attribute__} allows you to specify various special
7607 properties of types. Some type attributes apply only to structure and
7608 union types, and in C++, also class types, while others can apply to
7609 any type defined via a @code{typedef} declaration. Unless otherwise
7610 specified, the same restrictions and effects apply to attributes regardless
7611 of whether a type is a trivial structure or a C++ class with user-defined
7612 constructors, destructors, or a copy assignment.
7614 Other attributes are defined for functions (@pxref{Function Attributes}),
7615 labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator
7616 Attributes}), statements (@pxref{Statement Attributes}), and for variables
7617 (@pxref{Variable Attributes}).
7619 The @code{__attribute__} keyword is followed by an attribute specification
7620 enclosed in double parentheses.
7622 You may specify type attributes in an enum, struct or union type
7623 declaration or definition by placing them immediately after the
7624 @code{struct}, @code{union} or @code{enum} keyword. You can also place
7625 them just past the closing curly brace of the definition, but this is less
7626 preferred because logically the type should be fully defined at
7629 You can also include type attributes in a @code{typedef} declaration.
7630 @xref{Attribute Syntax}, for details of the exact syntax for using
7634 * Common Type Attributes::
7635 * ARC Type Attributes::
7636 * ARM Type Attributes::
7637 * MeP Type Attributes::
7638 * PowerPC Type Attributes::
7639 * SPU Type Attributes::
7640 * x86 Type Attributes::
7643 @node Common Type Attributes
7644 @subsection Common Type Attributes
7646 The following type attributes are supported on most targets.
7649 @cindex @code{aligned} type attribute
7651 @itemx aligned (@var{alignment})
7652 The @code{aligned} attribute specifies a minimum alignment (in bytes) for
7653 variables of the specified type. When specified, @var{alignment} must be
7654 a power of 2. Specifying no @var{alignment} argument implies the maximum
7655 alignment for the target, which is often, but by no means always, 8 or 16
7656 bytes. For example, the declarations:
7659 struct __attribute__ ((aligned (8))) S @{ short f[3]; @};
7660 typedef int more_aligned_int __attribute__ ((aligned (8)));
7664 force the compiler to ensure (as far as it can) that each variable whose
7665 type is @code{struct S} or @code{more_aligned_int} is allocated and
7666 aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all
7667 variables of type @code{struct S} aligned to 8-byte boundaries allows
7668 the compiler to use the @code{ldd} and @code{std} (doubleword load and
7669 store) instructions when copying one variable of type @code{struct S} to
7670 another, thus improving run-time efficiency.
7672 Note that the alignment of any given @code{struct} or @code{union} type
7673 is required by the ISO C standard to be at least a perfect multiple of
7674 the lowest common multiple of the alignments of all of the members of
7675 the @code{struct} or @code{union} in question. This means that you @emph{can}
7676 effectively adjust the alignment of a @code{struct} or @code{union}
7677 type by attaching an @code{aligned} attribute to any one of the members
7678 of such a type, but the notation illustrated in the example above is a
7679 more obvious, intuitive, and readable way to request the compiler to
7680 adjust the alignment of an entire @code{struct} or @code{union} type.
7682 As in the preceding example, you can explicitly specify the alignment
7683 (in bytes) that you wish the compiler to use for a given @code{struct}
7684 or @code{union} type. Alternatively, you can leave out the alignment factor
7685 and just ask the compiler to align a type to the maximum
7686 useful alignment for the target machine you are compiling for. For
7687 example, you could write:
7690 struct __attribute__ ((aligned)) S @{ short f[3]; @};
7693 Whenever you leave out the alignment factor in an @code{aligned}
7694 attribute specification, the compiler automatically sets the alignment
7695 for the type to the largest alignment that is ever used for any data
7696 type on the target machine you are compiling for. Doing this can often
7697 make copy operations more efficient, because the compiler can use
7698 whatever instructions copy the biggest chunks of memory when performing
7699 copies to or from the variables that have types that you have aligned
7702 In the example above, if the size of each @code{short} is 2 bytes, then
7703 the size of the entire @code{struct S} type is 6 bytes. The smallest
7704 power of two that is greater than or equal to that is 8, so the
7705 compiler sets the alignment for the entire @code{struct S} type to 8
7708 Note that although you can ask the compiler to select a time-efficient
7709 alignment for a given type and then declare only individual stand-alone
7710 objects of that type, the compiler's ability to select a time-efficient
7711 alignment is primarily useful only when you plan to create arrays of
7712 variables having the relevant (efficiently aligned) type. If you
7713 declare or use arrays of variables of an efficiently-aligned type, then
7714 it is likely that your program also does pointer arithmetic (or
7715 subscripting, which amounts to the same thing) on pointers to the
7716 relevant type, and the code that the compiler generates for these
7717 pointer arithmetic operations is often more efficient for
7718 efficiently-aligned types than for other types.
7720 Note that the effectiveness of @code{aligned} attributes may be limited
7721 by inherent limitations in your linker. On many systems, the linker is
7722 only able to arrange for variables to be aligned up to a certain maximum
7723 alignment. (For some linkers, the maximum supported alignment may
7724 be very very small.) If your linker is only able to align variables
7725 up to a maximum of 8-byte alignment, then specifying @code{aligned (16)}
7726 in an @code{__attribute__} still only provides you with 8-byte
7727 alignment. See your linker documentation for further information.
7729 When used on a struct, or struct member, the @code{aligned} attribute can
7730 only increase the alignment; in order to decrease it, the @code{packed}
7731 attribute must be specified as well. When used as part of a typedef, the
7732 @code{aligned} attribute can both increase and decrease alignment, and
7733 specifying the @code{packed} attribute generates a warning.
7735 @cindex @code{warn_if_not_aligned} type attribute
7736 @item warn_if_not_aligned (@var{alignment})
7737 This attribute specifies a threshold for the structure field, measured
7738 in bytes. If the structure field is aligned below the threshold, a
7739 warning will be issued. For example, the declaration:
7742 typedef unsigned long long __u64
7743 __attribute__((aligned (4), warn_if_not_aligned (8)));
7754 causes the compiler to issue an warning on @code{struct foo}, like
7755 @samp{warning: alignment 4 of 'struct foo' is less than 8}.
7756 It is used to define @code{struct foo} in such a way that
7757 @code{struct foo} has the same layout and the structure field @code{x}
7758 has the same alignment when @code{__u64} is aligned at either 4 or
7759 8 bytes. Align @code{struct foo} to 8 bytes:
7762 struct __attribute__ ((aligned (8))) foo
7771 silences the warning. The compiler also issues a warning, like
7772 @samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8},
7773 when the structure field has the misaligned offset:
7776 struct __attribute__ ((aligned (8))) foo
7785 This warning can be disabled by @option{-Wno-if-not-aligned}.
7787 @item alloc_size (@var{position})
7788 @itemx alloc_size (@var{position-1}, @var{position-2})
7789 @cindex @code{alloc_size} type attribute
7790 The @code{alloc_size} type attribute may be applied to the definition
7791 of a type of a function that returns a pointer and takes at least one
7792 argument of an integer type. It indicates that the returned pointer
7793 points to an object whose size is given by the function argument at
7794 @var{position-1}, or by the product of the arguments at @var{position-1}
7795 and @var{position-2}. Meaningful sizes are positive values less than
7796 @code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses
7797 this information to improve the results of @code{__builtin_object_size}.
7799 For instance, the following declarations
7802 typedef __attribute__ ((alloc_size (1, 2))) void*
7803 calloc_type (size_t, size_t);
7804 typedef __attribute__ ((alloc_size (1))) void*
7805 malloc_type (size_t);
7809 specify that @code{calloc_type} is a type of a function that, like
7810 the standard C function @code{calloc}, returns an object whose size
7811 is given by the product of arguments 1 and 2, and that
7812 @code{malloc_type}, like the standard C function @code{malloc},
7813 returns an object whose size is given by argument 1 to the function.
7816 @itemx copy (@var{expression})
7817 @cindex @code{copy} type attribute
7818 The @code{copy} attribute applies the set of attributes with which
7819 the type of the @var{expression} has been declared to the declaration
7820 of the type to which the attribute is applied. The attribute is
7821 designed for libraries that define aliases that are expected to
7822 specify the same set of attributes as the aliased symbols.
7823 The @code{copy} attribute can be used with types, variables, or
7824 functions. However, the kind of symbol to which the attribute is
7825 applied (either varible or function) must match the kind of symbol
7826 to which the argument refers.
7827 The @code{copy} attribute copies only syntactic and semantic attributes
7828 but not attributes that affect a symbol's linkage or visibility such as
7829 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
7830 attribute is also not copied. @xref{Common Function Attributes}.
7831 @xref{Common Variable Attributes}.
7833 For example, suppose @code{struct A} below is defined in some third
7834 party library header to have the alignment requirement @code{N} and
7835 to force a warning whenever a variable of the type is not so aligned
7836 due to attribute @code{packed}. Specifying the @code{copy} attribute
7837 on the definition on the unrelated @code{struct B} has the effect of
7838 copying all relevant attributes from the type referenced by the pointer
7839 expression to @code{struct B}.
7842 struct __attribute__ ((aligned (N), warn_if_not_aligned (N)))
7843 A @{ /* @r{@dots{}} */ @};
7844 struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @};
7848 @itemx deprecated (@var{msg})
7849 @cindex @code{deprecated} type attribute
7850 The @code{deprecated} attribute results in a warning if the type
7851 is used anywhere in the source file. This is useful when identifying
7852 types that are expected to be removed in a future version of a program.
7853 If possible, the warning also includes the location of the declaration
7854 of the deprecated type, to enable users to easily find further
7855 information about why the type is deprecated, or what they should do
7856 instead. Note that the warnings only occur for uses and then only
7857 if the type is being applied to an identifier that itself is not being
7858 declared as deprecated.
7861 typedef int T1 __attribute__ ((deprecated));
7865 typedef T1 T3 __attribute__ ((deprecated));
7866 T3 z __attribute__ ((deprecated));
7870 results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
7871 warning is issued for line 4 because T2 is not explicitly
7872 deprecated. Line 5 has no warning because T3 is explicitly
7873 deprecated. Similarly for line 6. The optional @var{msg}
7874 argument, which must be a string, is printed in the warning if
7875 present. Control characters in the string will be replaced with
7876 escape sequences, and if the @option{-fmessage-length} option is set
7877 to 0 (its default value) then any newline characters will be ignored.
7879 The @code{deprecated} attribute can also be used for functions and
7880 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
7882 The message attached to the attribute is affected by the setting of
7883 the @option{-fmessage-length} option.
7885 @item designated_init
7886 @cindex @code{designated_init} type attribute
7887 This attribute may only be applied to structure types. It indicates
7888 that any initialization of an object of this type must use designated
7889 initializers rather than positional initializers. The intent of this
7890 attribute is to allow the programmer to indicate that a structure's
7891 layout may change, and that therefore relying on positional
7892 initialization will result in future breakage.
7894 GCC emits warnings based on this attribute by default; use
7895 @option{-Wno-designated-init} to suppress them.
7898 @cindex @code{may_alias} type attribute
7899 Accesses through pointers to types with this attribute are not subject
7900 to type-based alias analysis, but are instead assumed to be able to alias
7901 any other type of objects.
7902 In the context of section 6.5 paragraph 7 of the C99 standard,
7903 an lvalue expression
7904 dereferencing such a pointer is treated like having a character type.
7905 See @option{-fstrict-aliasing} for more information on aliasing issues.
7906 This extension exists to support some vector APIs, in which pointers to
7907 one vector type are permitted to alias pointers to a different vector type.
7909 Note that an object of a type with this attribute does not have any
7915 typedef short __attribute__ ((__may_alias__)) short_a;
7921 short_a *b = (short_a *) &a;
7925 if (a == 0x12345678)
7933 If you replaced @code{short_a} with @code{short} in the variable
7934 declaration, the above program would abort when compiled with
7935 @option{-fstrict-aliasing}, which is on by default at @option{-O2} or
7938 @item mode (@var{mode})
7939 @cindex @code{mode} type attribute
7940 This attribute specifies the data type for the declaration---whichever
7941 type corresponds to the mode @var{mode}. This in effect lets you
7942 request an integer or floating-point type according to its width.
7944 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
7945 for a list of the possible keywords for @var{mode}.
7946 You may also specify a mode of @code{byte} or @code{__byte__} to
7947 indicate the mode corresponding to a one-byte integer, @code{word} or
7948 @code{__word__} for the mode of a one-word integer, and @code{pointer}
7949 or @code{__pointer__} for the mode used to represent pointers.
7952 @cindex @code{packed} type attribute
7953 This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class}
7954 type definition, specifies that each of its members (other than zero-width
7955 bit-fields) is placed to minimize the memory required. This is equivalent
7956 to specifying the @code{packed} attribute on each of the members.
7958 @opindex fshort-enums
7959 When attached to an @code{enum} definition, the @code{packed} attribute
7960 indicates that the smallest integral type should be used.
7961 Specifying the @option{-fshort-enums} flag on the command line
7962 is equivalent to specifying the @code{packed}
7963 attribute on all @code{enum} definitions.
7965 In the following example @code{struct my_packed_struct}'s members are
7966 packed closely together, but the internal layout of its @code{s} member
7967 is not packed---to do that, @code{struct my_unpacked_struct} needs to
7971 struct my_unpacked_struct
7977 struct __attribute__ ((__packed__)) my_packed_struct
7981 struct my_unpacked_struct s;
7985 You may only specify the @code{packed} attribute on the definition
7986 of an @code{enum}, @code{struct}, @code{union}, or @code{class},
7987 not on a @code{typedef} that does not also define the enumerated type,
7988 structure, union, or class.
7990 @item scalar_storage_order ("@var{endianness}")
7991 @cindex @code{scalar_storage_order} type attribute
7992 When attached to a @code{union} or a @code{struct}, this attribute sets
7993 the storage order, aka endianness, of the scalar fields of the type, as
7994 well as the array fields whose component is scalar. The supported
7995 endiannesses are @code{big-endian} and @code{little-endian}. The attribute
7996 has no effects on fields which are themselves a @code{union}, a @code{struct}
7997 or an array whose component is a @code{union} or a @code{struct}, and it is
7998 possible for these fields to have a different scalar storage order than the
8001 This attribute is supported only for targets that use a uniform default
8002 scalar storage order (fortunately, most of them), i.e.@: targets that store
8003 the scalars either all in big-endian or all in little-endian.
8005 Additional restrictions are enforced for types with the reverse scalar
8006 storage order with regard to the scalar storage order of the target:
8009 @item Taking the address of a scalar field of a @code{union} or a
8010 @code{struct} with reverse scalar storage order is not permitted and yields
8012 @item Taking the address of an array field, whose component is scalar, of
8013 a @code{union} or a @code{struct} with reverse scalar storage order is
8014 permitted but yields a warning, unless @option{-Wno-scalar-storage-order}
8016 @item Taking the address of a @code{union} or a @code{struct} with reverse
8017 scalar storage order is permitted.
8020 These restrictions exist because the storage order attribute is lost when
8021 the address of a scalar or the address of an array with scalar component is
8022 taken, so storing indirectly through this address generally does not work.
8023 The second case is nevertheless allowed to be able to perform a block copy
8024 from or to the array.
8026 Moreover, the use of type punning or aliasing to toggle the storage order
8027 is not supported; that is to say, a given scalar object cannot be accessed
8028 through distinct types that assign a different storage order to it.
8030 @item transparent_union
8031 @cindex @code{transparent_union} type attribute
8033 This attribute, attached to a @code{union} type definition, indicates
8034 that any function parameter having that union type causes calls to that
8035 function to be treated in a special way.
8037 First, the argument corresponding to a transparent union type can be of
8038 any type in the union; no cast is required. Also, if the union contains
8039 a pointer type, the corresponding argument can be a null pointer
8040 constant or a void pointer expression; and if the union contains a void
8041 pointer type, the corresponding argument can be any pointer expression.
8042 If the union member type is a pointer, qualifiers like @code{const} on
8043 the referenced type must be respected, just as with normal pointer
8046 Second, the argument is passed to the function using the calling
8047 conventions of the first member of the transparent union, not the calling
8048 conventions of the union itself. All members of the union must have the
8049 same machine representation; this is necessary for this argument passing
8052 Transparent unions are designed for library functions that have multiple
8053 interfaces for compatibility reasons. For example, suppose the
8054 @code{wait} function must accept either a value of type @code{int *} to
8055 comply with POSIX, or a value of type @code{union wait *} to comply with
8056 the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
8057 @code{wait} would accept both kinds of arguments, but it would also
8058 accept any other pointer type and this would make argument type checking
8059 less useful. Instead, @code{<sys/wait.h>} might define the interface
8063 typedef union __attribute__ ((__transparent_union__))
8067 @} wait_status_ptr_t;
8069 pid_t wait (wait_status_ptr_t);
8073 This interface allows either @code{int *} or @code{union wait *}
8074 arguments to be passed, using the @code{int *} calling convention.
8075 The program can call @code{wait} with arguments of either type:
8078 int w1 () @{ int w; return wait (&w); @}
8079 int w2 () @{ union wait w; return wait (&w); @}
8083 With this interface, @code{wait}'s implementation might look like this:
8086 pid_t wait (wait_status_ptr_t p)
8088 return waitpid (-1, p.__ip, 0);
8093 @cindex @code{unused} type attribute
8094 When attached to a type (including a @code{union} or a @code{struct}),
8095 this attribute means that variables of that type are meant to appear
8096 possibly unused. GCC does not produce a warning for any variables of
8097 that type, even if the variable appears to do nothing. This is often
8098 the case with lock or thread classes, which are usually defined and then
8099 not referenced, but contain constructors and destructors that have
8100 nontrivial bookkeeping functions.
8103 @cindex @code{visibility} type attribute
8104 In C++, attribute visibility (@pxref{Function Attributes}) can also be
8105 applied to class, struct, union and enum types. Unlike other type
8106 attributes, the attribute must appear between the initial keyword and
8107 the name of the type; it cannot appear after the body of the type.
8109 Note that the type visibility is applied to vague linkage entities
8110 associated with the class (vtable, typeinfo node, etc.). In
8111 particular, if a class is thrown as an exception in one shared object
8112 and caught in another, the class must have default visibility.
8113 Otherwise the two shared objects are unable to use the same
8114 typeinfo node and exception handling will break.
8118 To specify multiple attributes, separate them by commas within the
8119 double parentheses: for example, @samp{__attribute__ ((aligned (16),
8122 @node ARC Type Attributes
8123 @subsection ARC Type Attributes
8125 @cindex @code{uncached} type attribute, ARC
8126 Declaring objects with @code{uncached} allows you to exclude
8127 data-cache participation in load and store operations on those objects
8128 without involving the additional semantic implications of
8129 @code{volatile}. The @code{.di} instruction suffix is used for all
8130 loads and stores of data declared @code{uncached}.
8132 @node ARM Type Attributes
8133 @subsection ARM Type Attributes
8135 @cindex @code{notshared} type attribute, ARM
8136 On those ARM targets that support @code{dllimport} (such as Symbian
8137 OS), you can use the @code{notshared} attribute to indicate that the
8138 virtual table and other similar data for a class should not be
8139 exported from a DLL@. For example:
8142 class __declspec(notshared) C @{
8144 __declspec(dllimport) C();
8148 __declspec(dllexport)
8153 In this code, @code{C::C} is exported from the current DLL, but the
8154 virtual table for @code{C} is not exported. (You can use
8155 @code{__attribute__} instead of @code{__declspec} if you prefer, but
8156 most Symbian OS code uses @code{__declspec}.)
8158 @node MeP Type Attributes
8159 @subsection MeP Type Attributes
8161 @cindex @code{based} type attribute, MeP
8162 @cindex @code{tiny} type attribute, MeP
8163 @cindex @code{near} type attribute, MeP
8164 @cindex @code{far} type attribute, MeP
8165 Many of the MeP variable attributes may be applied to types as well.
8166 Specifically, the @code{based}, @code{tiny}, @code{near}, and
8167 @code{far} attributes may be applied to either. The @code{io} and
8168 @code{cb} attributes may not be applied to types.
8170 @node PowerPC Type Attributes
8171 @subsection PowerPC Type Attributes
8173 Three attributes currently are defined for PowerPC configurations:
8174 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
8176 @cindex @code{ms_struct} type attribute, PowerPC
8177 @cindex @code{gcc_struct} type attribute, PowerPC
8178 For full documentation of the @code{ms_struct} and @code{gcc_struct}
8179 attributes please see the documentation in @ref{x86 Type Attributes}.
8181 @cindex @code{altivec} type attribute, PowerPC
8182 The @code{altivec} attribute allows one to declare AltiVec vector data
8183 types supported by the AltiVec Programming Interface Manual. The
8184 attribute requires an argument to specify one of three vector types:
8185 @code{vector__}, @code{pixel__} (always followed by unsigned short),
8186 and @code{bool__} (always followed by unsigned).
8189 __attribute__((altivec(vector__)))
8190 __attribute__((altivec(pixel__))) unsigned short
8191 __attribute__((altivec(bool__))) unsigned
8194 These attributes mainly are intended to support the @code{__vector},
8195 @code{__pixel}, and @code{__bool} AltiVec keywords.
8197 @node SPU Type Attributes
8198 @subsection SPU Type Attributes
8200 @cindex @code{spu_vector} type attribute, SPU
8201 The SPU supports the @code{spu_vector} attribute for types. This attribute
8202 allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU
8203 Language Extensions Specification. It is intended to support the
8204 @code{__vector} keyword.
8206 @node x86 Type Attributes
8207 @subsection x86 Type Attributes
8209 Two attributes are currently defined for x86 configurations:
8210 @code{ms_struct} and @code{gcc_struct}.
8216 @cindex @code{ms_struct} type attribute, x86
8217 @cindex @code{gcc_struct} type attribute, x86
8219 If @code{packed} is used on a structure, or if bit-fields are used
8220 it may be that the Microsoft ABI packs them differently
8221 than GCC normally packs them. Particularly when moving packed
8222 data between functions compiled with GCC and the native Microsoft compiler
8223 (either via function call or as data in a file), it may be necessary to access
8226 The @code{ms_struct} and @code{gcc_struct} attributes correspond
8227 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
8228 command-line options, respectively;
8229 see @ref{x86 Options}, for details of how structure layout is affected.
8230 @xref{x86 Variable Attributes}, for information about the corresponding
8231 attributes on variables.
8235 @node Label Attributes
8236 @section Label Attributes
8237 @cindex Label Attributes
8239 GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for
8240 details of the exact syntax for using attributes. Other attributes are
8241 available for functions (@pxref{Function Attributes}), variables
8242 (@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}),
8243 statements (@pxref{Statement Attributes}), and for types
8244 (@pxref{Type Attributes}).
8246 This example uses the @code{cold} label attribute to indicate the
8247 @code{ErrorHandling} branch is unlikely to be taken and that the
8248 @code{ErrorHandling} label is unused:
8252 asm goto ("some asm" : : : : NoError);
8254 /* This branch (the fall-through from the asm) is less commonly used */
8256 __attribute__((cold, unused)); /* Semi-colon is required here */
8261 printf("no error\n");
8267 @cindex @code{unused} label attribute
8268 This feature is intended for program-generated code that may contain
8269 unused labels, but which is compiled with @option{-Wall}. It is
8270 not normally appropriate to use in it human-written code, though it
8271 could be useful in cases where the code that jumps to the label is
8272 contained within an @code{#ifdef} conditional.
8275 @cindex @code{hot} label attribute
8276 The @code{hot} attribute on a label is used to inform the compiler that
8277 the path following the label is more likely than paths that are not so
8278 annotated. This attribute is used in cases where @code{__builtin_expect}
8279 cannot be used, for instance with computed goto or @code{asm goto}.
8282 @cindex @code{cold} label attribute
8283 The @code{cold} attribute on labels is used to inform the compiler that
8284 the path following the label is unlikely to be executed. This attribute
8285 is used in cases where @code{__builtin_expect} cannot be used, for instance
8286 with computed goto or @code{asm goto}.
8290 @node Enumerator Attributes
8291 @section Enumerator Attributes
8292 @cindex Enumerator Attributes
8294 GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for
8295 details of the exact syntax for using attributes. Other attributes are
8296 available for functions (@pxref{Function Attributes}), variables
8297 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements
8298 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
8300 This example uses the @code{deprecated} enumerator attribute to indicate the
8301 @code{oldval} enumerator is deprecated:
8305 oldval __attribute__((deprecated)),
8318 @cindex @code{deprecated} enumerator attribute
8319 The @code{deprecated} attribute results in a warning if the enumerator
8320 is used anywhere in the source file. This is useful when identifying
8321 enumerators that are expected to be removed in a future version of a
8322 program. The warning also includes the location of the declaration
8323 of the deprecated enumerator, to enable users to easily find further
8324 information about why the enumerator is deprecated, or what they should
8325 do instead. Note that the warnings only occurs for uses.
8329 @node Statement Attributes
8330 @section Statement Attributes
8331 @cindex Statement Attributes
8333 GCC allows attributes to be set on null statements. @xref{Attribute Syntax},
8334 for details of the exact syntax for using attributes. Other attributes are
8335 available for functions (@pxref{Function Attributes}), variables
8336 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators
8337 (@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}).
8339 This example uses the @code{fallthrough} statement attribute to indicate that
8340 the @option{-Wimplicit-fallthrough} warning should not be emitted:
8347 __attribute__((fallthrough));
8355 @cindex @code{fallthrough} statement attribute
8356 The @code{fallthrough} attribute with a null statement serves as a
8357 fallthrough statement. It hints to the compiler that a statement
8358 that falls through to another case label, or user-defined label
8359 in a switch statement is intentional and thus the
8360 @option{-Wimplicit-fallthrough} warning must not trigger. The
8361 fallthrough attribute may appear at most once in each attribute
8362 list, and may not be mixed with other attributes. It can only
8363 be used in a switch statement (the compiler will issue an error
8364 otherwise), after a preceding statement and before a logically
8365 succeeding case label, or user-defined label.
8369 @node Attribute Syntax
8370 @section Attribute Syntax
8371 @cindex attribute syntax
8373 This section describes the syntax with which @code{__attribute__} may be
8374 used, and the constructs to which attribute specifiers bind, for the C
8375 language. Some details may vary for C++ and Objective-C@. Because of
8376 infelicities in the grammar for attributes, some forms described here
8377 may not be successfully parsed in all cases.
8379 There are some problems with the semantics of attributes in C++. For
8380 example, there are no manglings for attributes, although they may affect
8381 code generation, so problems may arise when attributed types are used in
8382 conjunction with templates or overloading. Similarly, @code{typeid}
8383 does not distinguish between types with different attributes. Support
8384 for attributes in C++ may be restricted in future to attributes on
8385 declarations only, but not on nested declarators.
8387 @xref{Function Attributes}, for details of the semantics of attributes
8388 applying to functions. @xref{Variable Attributes}, for details of the
8389 semantics of attributes applying to variables. @xref{Type Attributes},
8390 for details of the semantics of attributes applying to structure, union
8391 and enumerated types.
8392 @xref{Label Attributes}, for details of the semantics of attributes
8394 @xref{Enumerator Attributes}, for details of the semantics of attributes
8395 applying to enumerators.
8396 @xref{Statement Attributes}, for details of the semantics of attributes
8397 applying to statements.
8399 An @dfn{attribute specifier} is of the form
8400 @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
8401 is a possibly empty comma-separated sequence of @dfn{attributes}, where
8402 each attribute is one of the following:
8406 Empty. Empty attributes are ignored.
8410 (which may be an identifier such as @code{unused}, or a reserved
8411 word such as @code{const}).
8414 An attribute name followed by a parenthesized list of
8415 parameters for the attribute.
8416 These parameters take one of the following forms:
8420 An identifier. For example, @code{mode} attributes use this form.
8423 An identifier followed by a comma and a non-empty comma-separated list
8424 of expressions. For example, @code{format} attributes use this form.
8427 A possibly empty comma-separated list of expressions. For example,
8428 @code{format_arg} attributes use this form with the list being a single
8429 integer constant expression, and @code{alias} attributes use this form
8430 with the list being a single string constant.
8434 An @dfn{attribute specifier list} is a sequence of one or more attribute
8435 specifiers, not separated by any other tokens.
8437 You may optionally specify attribute names with @samp{__}
8438 preceding and following the name.
8439 This allows you to use them in header files without
8440 being concerned about a possible macro of the same name. For example,
8441 you may use the attribute name @code{__noreturn__} instead of @code{noreturn}.
8444 @subsubheading Label Attributes
8446 In GNU C, an attribute specifier list may appear after the colon following a
8447 label, other than a @code{case} or @code{default} label. GNU C++ only permits
8448 attributes on labels if the attribute specifier is immediately
8449 followed by a semicolon (i.e., the label applies to an empty
8450 statement). If the semicolon is missing, C++ label attributes are
8451 ambiguous, as it is permissible for a declaration, which could begin
8452 with an attribute list, to be labelled in C++. Declarations cannot be
8453 labelled in C90 or C99, so the ambiguity does not arise there.
8455 @subsubheading Enumerator Attributes
8457 In GNU C, an attribute specifier list may appear as part of an enumerator.
8458 The attribute goes after the enumeration constant, before @code{=}, if
8459 present. The optional attribute in the enumerator appertains to the
8460 enumeration constant. It is not possible to place the attribute after
8461 the constant expression, if present.
8463 @subsubheading Statement Attributes
8464 In GNU C, an attribute specifier list may appear as part of a null
8465 statement. The attribute goes before the semicolon.
8467 @subsubheading Type Attributes
8469 An attribute specifier list may appear as part of a @code{struct},
8470 @code{union} or @code{enum} specifier. It may go either immediately
8471 after the @code{struct}, @code{union} or @code{enum} keyword, or after
8472 the closing brace. The former syntax is preferred.
8473 Where attribute specifiers follow the closing brace, they are considered
8474 to relate to the structure, union or enumerated type defined, not to any
8475 enclosing declaration the type specifier appears in, and the type
8476 defined is not complete until after the attribute specifiers.
8477 @c Otherwise, there would be the following problems: a shift/reduce
8478 @c conflict between attributes binding the struct/union/enum and
8479 @c binding to the list of specifiers/qualifiers; and "aligned"
8480 @c attributes could use sizeof for the structure, but the size could be
8481 @c changed later by "packed" attributes.
8484 @subsubheading All other attributes
8486 Otherwise, an attribute specifier appears as part of a declaration,
8487 counting declarations of unnamed parameters and type names, and relates
8488 to that declaration (which may be nested in another declaration, for
8489 example in the case of a parameter declaration), or to a particular declarator
8490 within a declaration. Where an
8491 attribute specifier is applied to a parameter declared as a function or
8492 an array, it should apply to the function or array rather than the
8493 pointer to which the parameter is implicitly converted, but this is not
8494 yet correctly implemented.
8496 Any list of specifiers and qualifiers at the start of a declaration may
8497 contain attribute specifiers, whether or not such a list may in that
8498 context contain storage class specifiers. (Some attributes, however,
8499 are essentially in the nature of storage class specifiers, and only make
8500 sense where storage class specifiers may be used; for example,
8501 @code{section}.) There is one necessary limitation to this syntax: the
8502 first old-style parameter declaration in a function definition cannot
8503 begin with an attribute specifier, because such an attribute applies to
8504 the function instead by syntax described below (which, however, is not
8505 yet implemented in this case). In some other cases, attribute
8506 specifiers are permitted by this grammar but not yet supported by the
8507 compiler. All attribute specifiers in this place relate to the
8508 declaration as a whole. In the obsolescent usage where a type of
8509 @code{int} is implied by the absence of type specifiers, such a list of
8510 specifiers and qualifiers may be an attribute specifier list with no
8511 other specifiers or qualifiers.
8513 At present, the first parameter in a function prototype must have some
8514 type specifier that is not an attribute specifier; this resolves an
8515 ambiguity in the interpretation of @code{void f(int
8516 (__attribute__((foo)) x))}, but is subject to change. At present, if
8517 the parentheses of a function declarator contain only attributes then
8518 those attributes are ignored, rather than yielding an error or warning
8519 or implying a single parameter of type int, but this is subject to
8522 An attribute specifier list may appear immediately before a declarator
8523 (other than the first) in a comma-separated list of declarators in a
8524 declaration of more than one identifier using a single list of
8525 specifiers and qualifiers. Such attribute specifiers apply
8526 only to the identifier before whose declarator they appear. For
8530 __attribute__((noreturn)) void d0 (void),
8531 __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
8536 the @code{noreturn} attribute applies to all the functions
8537 declared; the @code{format} attribute only applies to @code{d1}.
8539 An attribute specifier list may appear immediately before the comma,
8540 @code{=} or semicolon terminating the declaration of an identifier other
8541 than a function definition. Such attribute specifiers apply
8542 to the declared object or function. Where an
8543 assembler name for an object or function is specified (@pxref{Asm
8544 Labels}), the attribute must follow the @code{asm}
8547 An attribute specifier list may, in future, be permitted to appear after
8548 the declarator in a function definition (before any old-style parameter
8549 declarations or the function body).
8551 Attribute specifiers may be mixed with type qualifiers appearing inside
8552 the @code{[]} of a parameter array declarator, in the C99 construct by
8553 which such qualifiers are applied to the pointer to which the array is
8554 implicitly converted. Such attribute specifiers apply to the pointer,
8555 not to the array, but at present this is not implemented and they are
8558 An attribute specifier list may appear at the start of a nested
8559 declarator. At present, there are some limitations in this usage: the
8560 attributes correctly apply to the declarator, but for most individual
8561 attributes the semantics this implies are not implemented.
8562 When attribute specifiers follow the @code{*} of a pointer
8563 declarator, they may be mixed with any type qualifiers present.
8564 The following describes the formal semantics of this syntax. It makes the
8565 most sense if you are familiar with the formal specification of
8566 declarators in the ISO C standard.
8568 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
8569 D1}, where @code{T} contains declaration specifiers that specify a type
8570 @var{Type} (such as @code{int}) and @code{D1} is a declarator that
8571 contains an identifier @var{ident}. The type specified for @var{ident}
8572 for derived declarators whose type does not include an attribute
8573 specifier is as in the ISO C standard.
8575 If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
8576 and the declaration @code{T D} specifies the type
8577 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
8578 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
8579 @var{attribute-specifier-list} @var{Type}'' for @var{ident}.
8581 If @code{D1} has the form @code{*
8582 @var{type-qualifier-and-attribute-specifier-list} D}, and the
8583 declaration @code{T D} specifies the type
8584 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
8585 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
8586 @var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for
8592 void (__attribute__((noreturn)) ****f) (void);
8596 specifies the type ``pointer to pointer to pointer to pointer to
8597 non-returning function returning @code{void}''. As another example,
8600 char *__attribute__((aligned(8))) *f;
8604 specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
8605 Note again that this does not work with most attributes; for example,
8606 the usage of @samp{aligned} and @samp{noreturn} attributes given above
8607 is not yet supported.
8609 For compatibility with existing code written for compiler versions that
8610 did not implement attributes on nested declarators, some laxity is
8611 allowed in the placing of attributes. If an attribute that only applies
8612 to types is applied to a declaration, it is treated as applying to
8613 the type of that declaration. If an attribute that only applies to
8614 declarations is applied to the type of a declaration, it is treated
8615 as applying to that declaration; and, for compatibility with code
8616 placing the attributes immediately before the identifier declared, such
8617 an attribute applied to a function return type is treated as
8618 applying to the function type, and such an attribute applied to an array
8619 element type is treated as applying to the array type. If an
8620 attribute that only applies to function types is applied to a
8621 pointer-to-function type, it is treated as applying to the pointer
8622 target type; if such an attribute is applied to a function return type
8623 that is not a pointer-to-function type, it is treated as applying
8624 to the function type.
8626 @node Function Prototypes
8627 @section Prototypes and Old-Style Function Definitions
8628 @cindex function prototype declarations
8629 @cindex old-style function definitions
8630 @cindex promotion of formal parameters
8632 GNU C extends ISO C to allow a function prototype to override a later
8633 old-style non-prototype definition. Consider the following example:
8636 /* @r{Use prototypes unless the compiler is old-fashioned.} */
8643 /* @r{Prototype function declaration.} */
8644 int isroot P((uid_t));
8646 /* @r{Old-style function definition.} */
8648 isroot (x) /* @r{??? lossage here ???} */
8655 Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
8656 not allow this example, because subword arguments in old-style
8657 non-prototype definitions are promoted. Therefore in this example the
8658 function definition's argument is really an @code{int}, which does not
8659 match the prototype argument type of @code{short}.
8661 This restriction of ISO C makes it hard to write code that is portable
8662 to traditional C compilers, because the programmer does not know
8663 whether the @code{uid_t} type is @code{short}, @code{int}, or
8664 @code{long}. Therefore, in cases like these GNU C allows a prototype
8665 to override a later old-style definition. More precisely, in GNU C, a
8666 function prototype argument type overrides the argument type specified
8667 by a later old-style definition if the former type is the same as the
8668 latter type before promotion. Thus in GNU C the above example is
8669 equivalent to the following:
8682 GNU C++ does not support old-style function definitions, so this
8683 extension is irrelevant.
8686 @section C++ Style Comments
8688 @cindex C++ comments
8689 @cindex comments, C++ style
8691 In GNU C, you may use C++ style comments, which start with @samp{//} and
8692 continue until the end of the line. Many other C implementations allow
8693 such comments, and they are included in the 1999 C standard. However,
8694 C++ style comments are not recognized if you specify an @option{-std}
8695 option specifying a version of ISO C before C99, or @option{-ansi}
8696 (equivalent to @option{-std=c90}).
8699 @section Dollar Signs in Identifier Names
8701 @cindex dollar signs in identifier names
8702 @cindex identifier names, dollar signs in
8704 In GNU C, you may normally use dollar signs in identifier names.
8705 This is because many traditional C implementations allow such identifiers.
8706 However, dollar signs in identifiers are not supported on a few target
8707 machines, typically because the target assembler does not allow them.
8709 @node Character Escapes
8710 @section The Character @key{ESC} in Constants
8712 You can use the sequence @samp{\e} in a string or character constant to
8713 stand for the ASCII character @key{ESC}.
8716 @section Determining the Alignment of Functions, Types or Variables
8718 @cindex type alignment
8719 @cindex variable alignment
8721 The keyword @code{__alignof__} determines the alignment requirement of
8722 a function, object, or a type, or the minimum alignment usually required
8723 by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}.
8725 For example, if the target machine requires a @code{double} value to be
8726 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
8727 This is true on many RISC machines. On more traditional machine
8728 designs, @code{__alignof__ (double)} is 4 or even 2.
8730 Some machines never actually require alignment; they allow references to any
8731 data type even at an odd address. For these machines, @code{__alignof__}
8732 reports the smallest alignment that GCC gives the data type, usually as
8733 mandated by the target ABI.
8735 If the operand of @code{__alignof__} is an lvalue rather than a type,
8736 its value is the required alignment for its type, taking into account
8737 any minimum alignment specified by attribute @code{aligned}
8738 (@pxref{Common Variable Attributes}). For example, after this
8742 struct foo @{ int x; char y; @} foo1;
8746 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
8747 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
8748 It is an error to ask for the alignment of an incomplete type other
8751 If the operand of the @code{__alignof__} expression is a function,
8752 the expression evaluates to the alignment of the function which may
8753 be specified by attribute @code{aligned} (@pxref{Common Function Attributes}).
8756 @section An Inline Function is As Fast As a Macro
8757 @cindex inline functions
8758 @cindex integrating function code
8760 @cindex macros, inline alternative
8762 By declaring a function inline, you can direct GCC to make
8763 calls to that function faster. One way GCC can achieve this is to
8764 integrate that function's code into the code for its callers. This
8765 makes execution faster by eliminating the function-call overhead; in
8766 addition, if any of the actual argument values are constant, their
8767 known values may permit simplifications at compile time so that not
8768 all of the inline function's code needs to be included. The effect on
8769 code size is less predictable; object code may be larger or smaller
8770 with function inlining, depending on the particular case. You can
8771 also direct GCC to try to integrate all ``simple enough'' functions
8772 into their callers with the option @option{-finline-functions}.
8774 GCC implements three different semantics of declaring a function
8775 inline. One is available with @option{-std=gnu89} or
8776 @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
8777 on all inline declarations, another when
8779 @option{-std=gnu99} or an option for a later C version is used
8780 (without @option{-fgnu89-inline}), and the third
8781 is used when compiling C++.
8783 To declare a function inline, use the @code{inline} keyword in its
8784 declaration, like this:
8794 If you are writing a header file to be included in ISO C90 programs, write
8795 @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
8797 The three types of inlining behave similarly in two important cases:
8798 when the @code{inline} keyword is used on a @code{static} function,
8799 like the example above, and when a function is first declared without
8800 using the @code{inline} keyword and then is defined with
8801 @code{inline}, like this:
8804 extern int inc (int *a);
8812 In both of these common cases, the program behaves the same as if you
8813 had not used the @code{inline} keyword, except for its speed.
8815 @cindex inline functions, omission of
8816 @opindex fkeep-inline-functions
8817 When a function is both inline and @code{static}, if all calls to the
8818 function are integrated into the caller, and the function's address is
8819 never used, then the function's own assembler code is never referenced.
8820 In this case, GCC does not actually output assembler code for the
8821 function, unless you specify the option @option{-fkeep-inline-functions}.
8822 If there is a nonintegrated call, then the function is compiled to
8823 assembler code as usual. The function must also be compiled as usual if
8824 the program refers to its address, because that cannot be inlined.
8827 Note that certain usages in a function definition can make it unsuitable
8828 for inline substitution. Among these usages are: variadic functions,
8829 use of @code{alloca}, use of computed goto (@pxref{Labels as Values}),
8830 use of nonlocal goto, use of nested functions, use of @code{setjmp}, use
8831 of @code{__builtin_longjmp} and use of @code{__builtin_return} or
8832 @code{__builtin_apply_args}. Using @option{-Winline} warns when a
8833 function marked @code{inline} could not be substituted, and gives the
8834 reason for the failure.
8836 @cindex automatic @code{inline} for C++ member fns
8837 @cindex @code{inline} automatic for C++ member fns
8838 @cindex member fns, automatically @code{inline}
8839 @cindex C++ member fns, automatically @code{inline}
8840 @opindex fno-default-inline
8841 As required by ISO C++, GCC considers member functions defined within
8842 the body of a class to be marked inline even if they are
8843 not explicitly declared with the @code{inline} keyword. You can
8844 override this with @option{-fno-default-inline}; @pxref{C++ Dialect
8845 Options,,Options Controlling C++ Dialect}.
8847 GCC does not inline any functions when not optimizing unless you specify
8848 the @samp{always_inline} attribute for the function, like this:
8851 /* @r{Prototype.} */
8852 inline void foo (const char) __attribute__((always_inline));
8855 The remainder of this section is specific to GNU C90 inlining.
8857 @cindex non-static inline function
8858 When an inline function is not @code{static}, then the compiler must assume
8859 that there may be calls from other source files; since a global symbol can
8860 be defined only once in any program, the function must not be defined in
8861 the other source files, so the calls therein cannot be integrated.
8862 Therefore, a non-@code{static} inline function is always compiled on its
8863 own in the usual fashion.
8865 If you specify both @code{inline} and @code{extern} in the function
8866 definition, then the definition is used only for inlining. In no case
8867 is the function compiled on its own, not even if you refer to its
8868 address explicitly. Such an address becomes an external reference, as
8869 if you had only declared the function, and had not defined it.
8871 This combination of @code{inline} and @code{extern} has almost the
8872 effect of a macro. The way to use it is to put a function definition in
8873 a header file with these keywords, and put another copy of the
8874 definition (lacking @code{inline} and @code{extern}) in a library file.
8875 The definition in the header file causes most calls to the function
8876 to be inlined. If any uses of the function remain, they refer to
8877 the single copy in the library.
8880 @section When is a Volatile Object Accessed?
8881 @cindex accessing volatiles
8882 @cindex volatile read
8883 @cindex volatile write
8884 @cindex volatile access
8886 C has the concept of volatile objects. These are normally accessed by
8887 pointers and used for accessing hardware or inter-thread
8888 communication. The standard encourages compilers to refrain from
8889 optimizations concerning accesses to volatile objects, but leaves it
8890 implementation defined as to what constitutes a volatile access. The
8891 minimum requirement is that at a sequence point all previous accesses
8892 to volatile objects have stabilized and no subsequent accesses have
8893 occurred. Thus an implementation is free to reorder and combine
8894 volatile accesses that occur between sequence points, but cannot do
8895 so for accesses across a sequence point. The use of volatile does
8896 not allow you to violate the restriction on updating objects multiple
8897 times between two sequence points.
8899 Accesses to non-volatile objects are not ordered with respect to
8900 volatile accesses. You cannot use a volatile object as a memory
8901 barrier to order a sequence of writes to non-volatile memory. For
8905 int *ptr = @var{something};
8907 *ptr = @var{something};
8912 Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed
8913 that the write to @var{*ptr} occurs by the time the update
8914 of @var{vobj} happens. If you need this guarantee, you must use
8915 a stronger memory barrier such as:
8918 int *ptr = @var{something};
8920 *ptr = @var{something};
8921 asm volatile ("" : : : "memory");
8925 A scalar volatile object is read when it is accessed in a void context:
8928 volatile int *src = @var{somevalue};
8932 Such expressions are rvalues, and GCC implements this as a
8933 read of the volatile object being pointed to.
8935 Assignments are also expressions and have an rvalue. However when
8936 assigning to a scalar volatile, the volatile object is not reread,
8937 regardless of whether the assignment expression's rvalue is used or
8938 not. If the assignment's rvalue is used, the value is that assigned
8939 to the volatile object. For instance, there is no read of @var{vobj}
8940 in all the following cases:
8945 vobj = @var{something};
8946 obj = vobj = @var{something};
8947 obj ? vobj = @var{onething} : vobj = @var{anotherthing};
8948 obj = (@var{something}, vobj = @var{anotherthing});
8951 If you need to read the volatile object after an assignment has
8952 occurred, you must use a separate expression with an intervening
8955 As bit-fields are not individually addressable, volatile bit-fields may
8956 be implicitly read when written to, or when adjacent bit-fields are
8957 accessed. Bit-field operations may be optimized such that adjacent
8958 bit-fields are only partially accessed, if they straddle a storage unit
8959 boundary. For these reasons it is unwise to use volatile bit-fields to
8962 @node Using Assembly Language with C
8963 @section How to Use Inline Assembly Language in C Code
8964 @cindex @code{asm} keyword
8965 @cindex assembly language in C
8966 @cindex inline assembly language
8967 @cindex mixing assembly language and C
8969 The @code{asm} keyword allows you to embed assembler instructions
8970 within C code. GCC provides two forms of inline @code{asm}
8971 statements. A @dfn{basic @code{asm}} statement is one with no
8972 operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}}
8973 statement (@pxref{Extended Asm}) includes one or more operands.
8974 The extended form is preferred for mixing C and assembly language
8975 within a function, but to include assembly language at
8976 top level you must use basic @code{asm}.
8978 You can also use the @code{asm} keyword to override the assembler name
8979 for a C symbol, or to place a C variable in a specific register.
8982 * Basic Asm:: Inline assembler without operands.
8983 * Extended Asm:: Inline assembler with operands.
8984 * Constraints:: Constraints for @code{asm} operands
8985 * Asm Labels:: Specifying the assembler name to use for a C symbol.
8986 * Explicit Register Variables:: Defining variables residing in specified
8988 * Size of an asm:: How GCC calculates the size of an @code{asm} block.
8992 @subsection Basic Asm --- Assembler Instructions Without Operands
8993 @cindex basic @code{asm}
8994 @cindex assembly language in C, basic
8996 A basic @code{asm} statement has the following syntax:
8999 asm @var{asm-qualifiers} ( @var{AssemblerInstructions} )
9002 The @code{asm} keyword is a GNU extension.
9003 When writing code that can be compiled with @option{-ansi} and the
9004 various @option{-std} options, use @code{__asm__} instead of
9005 @code{asm} (@pxref{Alternate Keywords}).
9007 @subsubheading Qualifiers
9010 The optional @code{volatile} qualifier has no effect.
9011 All basic @code{asm} blocks are implicitly volatile.
9014 If you use the @code{inline} qualifier, then for inlining purposes the size
9015 of the @code{asm} statement is taken as the smallest size possible (@pxref{Size
9019 @subsubheading Parameters
9022 @item AssemblerInstructions
9023 This is a literal string that specifies the assembler code. The string can
9024 contain any instructions recognized by the assembler, including directives.
9025 GCC does not parse the assembler instructions themselves and
9026 does not know what they mean or even whether they are valid assembler input.
9028 You may place multiple assembler instructions together in a single @code{asm}
9029 string, separated by the characters normally used in assembly code for the
9030 system. A combination that works in most places is a newline to break the
9031 line, plus a tab character (written as @samp{\n\t}).
9032 Some assemblers allow semicolons as a line separator. However,
9033 note that some assembler dialects use semicolons to start a comment.
9036 @subsubheading Remarks
9037 Using extended @code{asm} (@pxref{Extended Asm}) typically produces
9038 smaller, safer, and more efficient code, and in most cases it is a
9039 better solution than basic @code{asm}. However, there are two
9040 situations where only basic @code{asm} can be used:
9044 Extended @code{asm} statements have to be inside a C
9045 function, so to write inline assembly language at file scope (``top-level''),
9046 outside of C functions, you must use basic @code{asm}.
9047 You can use this technique to emit assembler directives,
9048 define assembly language macros that can be invoked elsewhere in the file,
9049 or write entire functions in assembly language.
9053 with the @code{naked} attribute also require basic @code{asm}
9054 (@pxref{Function Attributes}).
9057 Safely accessing C data and calling functions from basic @code{asm} is more
9058 complex than it may appear. To access C data, it is better to use extended
9061 Do not expect a sequence of @code{asm} statements to remain perfectly
9062 consecutive after compilation. If certain instructions need to remain
9063 consecutive in the output, put them in a single multi-instruction @code{asm}
9064 statement. Note that GCC's optimizers can move @code{asm} statements
9065 relative to other code, including across jumps.
9067 @code{asm} statements may not perform jumps into other @code{asm} statements.
9068 GCC does not know about these jumps, and therefore cannot take
9069 account of them when deciding how to optimize. Jumps from @code{asm} to C
9070 labels are only supported in extended @code{asm}.
9072 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
9073 assembly code when optimizing. This can lead to unexpected duplicate
9074 symbol errors during compilation if your assembly code defines symbols or
9077 @strong{Warning:} The C standards do not specify semantics for @code{asm},
9078 making it a potential source of incompatibilities between compilers. These
9079 incompatibilities may not produce compiler warnings/errors.
9081 GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which
9082 means there is no way to communicate to the compiler what is happening
9083 inside them. GCC has no visibility of symbols in the @code{asm} and may
9084 discard them as unreferenced. It also does not know about side effects of
9085 the assembler code, such as modifications to memory or registers. Unlike
9086 some compilers, GCC assumes that no changes to general purpose registers
9087 occur. This assumption may change in a future release.
9089 To avoid complications from future changes to the semantics and the
9090 compatibility issues between compilers, consider replacing basic @code{asm}
9091 with extended @code{asm}. See
9092 @uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert
9093 from basic asm to extended asm} for information about how to perform this
9096 The compiler copies the assembler instructions in a basic @code{asm}
9097 verbatim to the assembly language output file, without
9098 processing dialects or any of the @samp{%} operators that are available with
9099 extended @code{asm}. This results in minor differences between basic
9100 @code{asm} strings and extended @code{asm} templates. For example, to refer to
9101 registers you might use @samp{%eax} in basic @code{asm} and
9102 @samp{%%eax} in extended @code{asm}.
9104 On targets such as x86 that support multiple assembler dialects,
9105 all basic @code{asm} blocks use the assembler dialect specified by the
9106 @option{-masm} command-line option (@pxref{x86 Options}).
9107 Basic @code{asm} provides no
9108 mechanism to provide different assembler strings for different dialects.
9110 For basic @code{asm} with non-empty assembler string GCC assumes
9111 the assembler block does not change any general purpose registers,
9112 but it may read or write any globally accessible variable.
9114 Here is an example of basic @code{asm} for i386:
9117 /* Note that this code will not compile with -masm=intel */
9118 #define DebugBreak() asm("int $3")
9122 @subsection Extended Asm - Assembler Instructions with C Expression Operands
9123 @cindex extended @code{asm}
9124 @cindex assembly language in C, extended
9126 With extended @code{asm} you can read and write C variables from
9127 assembler and perform jumps from assembler code to C labels.
9128 Extended @code{asm} syntax uses colons (@samp{:}) to delimit
9129 the operand parameters after the assembler template:
9132 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9133 : @var{OutputOperands}
9134 @r{[} : @var{InputOperands}
9135 @r{[} : @var{Clobbers} @r{]} @r{]})
9137 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
9139 : @var{InputOperands}
9143 where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the
9146 The @code{asm} keyword is a GNU extension.
9147 When writing code that can be compiled with @option{-ansi} and the
9148 various @option{-std} options, use @code{__asm__} instead of
9149 @code{asm} (@pxref{Alternate Keywords}).
9151 @subsubheading Qualifiers
9155 The typical use of extended @code{asm} statements is to manipulate input
9156 values to produce output values. However, your @code{asm} statements may
9157 also produce side effects. If so, you may need to use the @code{volatile}
9158 qualifier to disable certain optimizations. @xref{Volatile}.
9161 If you use the @code{inline} qualifier, then for inlining purposes the size
9162 of the @code{asm} statement is taken as the smallest size possible
9163 (@pxref{Size of an asm}).
9166 This qualifier informs the compiler that the @code{asm} statement may
9167 perform a jump to one of the labels listed in the @var{GotoLabels}.
9171 @subsubheading Parameters
9173 @item AssemblerTemplate
9174 This is a literal string that is the template for the assembler code. It is a
9175 combination of fixed text and tokens that refer to the input, output,
9176 and goto parameters. @xref{AssemblerTemplate}.
9178 @item OutputOperands
9179 A comma-separated list of the C variables modified by the instructions in the
9180 @var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}.
9183 A comma-separated list of C expressions read by the instructions in the
9184 @var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}.
9187 A comma-separated list of registers or other values changed by the
9188 @var{AssemblerTemplate}, beyond those listed as outputs.
9189 An empty list is permitted. @xref{Clobbers and Scratch Registers}.
9192 When you are using the @code{goto} form of @code{asm}, this section contains
9193 the list of all C labels to which the code in the
9194 @var{AssemblerTemplate} may jump.
9197 @code{asm} statements may not perform jumps into other @code{asm} statements,
9198 only to the listed @var{GotoLabels}.
9199 GCC's optimizers do not know about other jumps; therefore they cannot take
9200 account of them when deciding how to optimize.
9203 The total number of input + output + goto operands is limited to 30.
9205 @subsubheading Remarks
9206 The @code{asm} statement allows you to include assembly instructions directly
9207 within C code. This may help you to maximize performance in time-sensitive
9208 code or to access assembly instructions that are not readily available to C
9211 Note that extended @code{asm} statements must be inside a function. Only
9212 basic @code{asm} may be outside functions (@pxref{Basic Asm}).
9213 Functions declared with the @code{naked} attribute also require basic
9214 @code{asm} (@pxref{Function Attributes}).
9216 While the uses of @code{asm} are many and varied, it may help to think of an
9217 @code{asm} statement as a series of low-level instructions that convert input
9218 parameters to output parameters. So a simple (if not particularly useful)
9219 example for i386 using @code{asm} might look like this:
9225 asm ("mov %1, %0\n\t"
9230 printf("%d\n", dst);
9233 This code copies @code{src} to @code{dst} and add 1 to @code{dst}.
9236 @subsubsection Volatile
9237 @cindex volatile @code{asm}
9238 @cindex @code{asm} volatile
9240 GCC's optimizers sometimes discard @code{asm} statements if they determine
9241 there is no need for the output variables. Also, the optimizers may move
9242 code out of loops if they believe that the code will always return the same
9243 result (i.e.@: none of its input values change between calls). Using the
9244 @code{volatile} qualifier disables these optimizations. @code{asm} statements
9245 that have no output operands, including @code{asm goto} statements,
9246 are implicitly volatile.
9248 This i386 code demonstrates a case that does not use (or require) the
9249 @code{volatile} qualifier. If it is performing assertion checking, this code
9250 uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is
9251 unreferenced by any code. As a result, the optimizers can discard the
9252 @code{asm} statement, which in turn removes the need for the entire
9253 @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
9254 isn't needed you allow the optimizers to produce the most efficient code
9258 void DoCheck(uint32_t dwSomeValue)
9262 // Assumes dwSomeValue is not zero.
9272 The next example shows a case where the optimizers can recognize that the input
9273 (@code{dwSomeValue}) never changes during the execution of the function and can
9274 therefore move the @code{asm} outside the loop to produce more efficient code.
9275 Again, using the @code{volatile} qualifier disables this type of optimization.
9278 void do_print(uint32_t dwSomeValue)
9282 for (uint32_t x=0; x < 5; x++)
9284 // Assumes dwSomeValue is not zero.
9290 printf("%u: %u %u\n", x, dwSomeValue, dwRes);
9295 The following example demonstrates a case where you need to use the
9296 @code{volatile} qualifier.
9297 It uses the x86 @code{rdtsc} instruction, which reads
9298 the computer's time-stamp counter. Without the @code{volatile} qualifier,
9299 the optimizers might assume that the @code{asm} block will always return the
9300 same value and therefore optimize away the second call.
9305 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
9306 "shl $32, %%rdx\n\t" // Shift the upper bits left.
9307 "or %%rdx, %0" // 'Or' in the lower bits.
9312 printf("msr: %llx\n", msr);
9316 // Reprint the timestamp
9317 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
9318 "shl $32, %%rdx\n\t" // Shift the upper bits left.
9319 "or %%rdx, %0" // 'Or' in the lower bits.
9324 printf("msr: %llx\n", msr);
9327 GCC's optimizers do not treat this code like the non-volatile code in the
9328 earlier examples. They do not move it out of loops or omit it on the
9329 assumption that the result from a previous call is still valid.
9331 Note that the compiler can move even @code{volatile asm} instructions relative
9332 to other code, including across jump instructions. For example, on many
9333 targets there is a system register that controls the rounding mode of
9334 floating-point operations. Setting it with a @code{volatile asm} statement,
9335 as in the following PowerPC example, does not work reliably.
9338 asm volatile("mtfsf 255, %0" : : "f" (fpenv));
9342 The compiler may move the addition back before the @code{volatile asm}
9343 statement. To make it work as expected, add an artificial dependency to
9344 the @code{asm} by referencing a variable in the subsequent code, for
9348 asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
9352 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
9353 assembly code when optimizing. This can lead to unexpected duplicate symbol
9354 errors during compilation if your @code{asm} code defines symbols or labels.
9356 (@pxref{AssemblerTemplate}) may help resolve this problem.
9358 @anchor{AssemblerTemplate}
9359 @subsubsection Assembler Template
9360 @cindex @code{asm} assembler template
9362 An assembler template is a literal string containing assembler instructions.
9363 The compiler replaces tokens in the template that refer
9364 to inputs, outputs, and goto labels,
9365 and then outputs the resulting string to the assembler. The
9366 string can contain any instructions recognized by the assembler, including
9367 directives. GCC does not parse the assembler instructions
9368 themselves and does not know what they mean or even whether they are valid
9369 assembler input. However, it does count the statements
9370 (@pxref{Size of an asm}).
9372 You may place multiple assembler instructions together in a single @code{asm}
9373 string, separated by the characters normally used in assembly code for the
9374 system. A combination that works in most places is a newline to break the
9375 line, plus a tab character to move to the instruction field (written as
9377 Some assemblers allow semicolons as a line separator. However, note
9378 that some assembler dialects use semicolons to start a comment.
9380 Do not expect a sequence of @code{asm} statements to remain perfectly
9381 consecutive after compilation, even when you are using the @code{volatile}
9382 qualifier. If certain instructions need to remain consecutive in the output,
9383 put them in a single multi-instruction @code{asm} statement.
9385 Accessing data from C programs without using input/output operands (such as
9386 by using global symbols directly from the assembler template) may not work as
9387 expected. Similarly, calling functions directly from an assembler template
9388 requires a detailed understanding of the target assembler and ABI.
9390 Since GCC does not parse the assembler template,
9391 it has no visibility of any
9392 symbols it references. This may result in GCC discarding those symbols as
9393 unreferenced unless they are also listed as input, output, or goto operands.
9395 @subsubheading Special format strings
9397 In addition to the tokens described by the input, output, and goto operands,
9398 these tokens have special meanings in the assembler template:
9402 Outputs a single @samp{%} into the assembler code.
9405 Outputs a number that is unique to each instance of the @code{asm}
9406 statement in the entire compilation. This option is useful when creating local
9407 labels and referring to them multiple times in a single template that
9408 generates multiple assembler instructions.
9413 Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively)
9414 into the assembler code. When unescaped, these characters have special
9415 meaning to indicate multiple assembler dialects, as described below.
9418 @subsubheading Multiple assembler dialects in @code{asm} templates
9420 On targets such as x86, GCC supports multiple assembler dialects.
9421 The @option{-masm} option controls which dialect GCC uses as its
9422 default for inline assembler. The target-specific documentation for the
9423 @option{-masm} option contains the list of supported dialects, as well as the
9424 default dialect if the option is not specified. This information may be
9425 important to understand, since assembler code that works correctly when
9426 compiled using one dialect will likely fail if compiled using another.
9429 If your code needs to support multiple assembler dialects (for example, if
9430 you are writing public headers that need to support a variety of compilation
9431 options), use constructs of this form:
9434 @{ dialect0 | dialect1 | dialect2... @}
9437 This construct outputs @code{dialect0}
9438 when using dialect #0 to compile the code,
9439 @code{dialect1} for dialect #1, etc. If there are fewer alternatives within the
9440 braces than the number of dialects the compiler supports, the construct
9443 For example, if an x86 compiler supports two dialects
9444 (@samp{att}, @samp{intel}), an
9445 assembler template such as this:
9448 "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
9452 is equivalent to one of
9455 "btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */}
9456 "bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */}
9459 Using that same compiler, this code:
9462 "xchg@{l@}\t@{%%@}ebx, %1"
9466 corresponds to either
9469 "xchgl\t%%ebx, %1" @r{/* att dialect */}
9470 "xchg\tebx, %1" @r{/* intel dialect */}
9473 There is no support for nesting dialect alternatives.
9475 @anchor{OutputOperands}
9476 @subsubsection Output Operands
9477 @cindex @code{asm} output operands
9479 An @code{asm} statement has zero or more output operands indicating the names
9480 of C variables modified by the assembler code.
9482 In this i386 example, @code{old} (referred to in the template string as
9483 @code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset}
9484 (@code{%2}) is an input:
9489 __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
9490 "sbb %0,%0" // Use the CF to calculate old.
9491 : "=r" (old), "+rm" (*Base)
9498 Operands are separated by commas. Each operand has this format:
9501 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename})
9505 @item asmSymbolicName
9506 Specifies a symbolic name for the operand.
9507 Reference the name in the assembler template
9508 by enclosing it in square brackets
9509 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
9510 that contains the definition. Any valid C variable name is acceptable,
9511 including names already defined in the surrounding code. No two operands
9512 within the same @code{asm} statement can use the same symbolic name.
9514 When not using an @var{asmSymbolicName}, use the (zero-based) position
9516 in the list of operands in the assembler template. For example if there are
9517 three output operands, use @samp{%0} in the template to refer to the first,
9518 @samp{%1} for the second, and @samp{%2} for the third.
9521 A string constant specifying constraints on the placement of the operand;
9522 @xref{Constraints}, for details.
9524 Output constraints must begin with either @samp{=} (a variable overwriting an
9525 existing value) or @samp{+} (when reading and writing). When using
9526 @samp{=}, do not assume the location contains the existing value
9527 on entry to the @code{asm}, except
9528 when the operand is tied to an input; @pxref{InputOperands,,Input Operands}.
9530 After the prefix, there must be one or more additional constraints
9531 (@pxref{Constraints}) that describe where the value resides. Common
9532 constraints include @samp{r} for register and @samp{m} for memory.
9533 When you list more than one possible location (for example, @code{"=rm"}),
9534 the compiler chooses the most efficient one based on the current context.
9535 If you list as many alternates as the @code{asm} statement allows, you permit
9536 the optimizers to produce the best possible code.
9537 If you must use a specific register, but your Machine Constraints do not
9538 provide sufficient control to select the specific register you want,
9539 local register variables may provide a solution (@pxref{Local Register
9543 Specifies a C lvalue expression to hold the output, typically a variable name.
9544 The enclosing parentheses are a required part of the syntax.
9548 When the compiler selects the registers to use to
9549 represent the output operands, it does not use any of the clobbered registers
9550 (@pxref{Clobbers and Scratch Registers}).
9552 Output operand expressions must be lvalues. The compiler cannot check whether
9553 the operands have data types that are reasonable for the instruction being
9554 executed. For output expressions that are not directly addressable (for
9555 example a bit-field), the constraint must allow a register. In that case, GCC
9556 uses the register as the output of the @code{asm}, and then stores that
9557 register into the output.
9559 Operands using the @samp{+} constraint modifier count as two operands
9560 (that is, both as input and output) towards the total maximum of 30 operands
9561 per @code{asm} statement.
9563 Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output
9564 operands that must not overlap an input. Otherwise,
9565 GCC may allocate the output operand in the same register as an unrelated
9566 input operand, on the assumption that the assembler code consumes its
9567 inputs before producing outputs. This assumption may be false if the assembler
9568 code actually consists of more than one instruction.
9570 The same problem can occur if one output parameter (@var{a}) allows a register
9571 constraint and another output parameter (@var{b}) allows a memory constraint.
9572 The code generated by GCC to access the memory address in @var{b} can contain
9573 registers which @emph{might} be shared by @var{a}, and GCC considers those
9574 registers to be inputs to the asm. As above, GCC assumes that such input
9575 registers are consumed before any outputs are written. This assumption may
9576 result in incorrect behavior if the @code{asm} statement writes to @var{a}
9578 @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a}
9579 ensures that modifying @var{a} does not affect the address referenced by
9580 @var{b}. Otherwise, the location of @var{b}
9581 is undefined if @var{a} is modified before using @var{b}.
9583 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
9584 instead of simply @samp{%2}). Typically these qualifiers are hardware
9585 dependent. The list of supported modifiers for x86 is found at
9586 @ref{x86Operandmodifiers,x86 Operand modifiers}.
9588 If the C code that follows the @code{asm} makes no use of any of the output
9589 operands, use @code{volatile} for the @code{asm} statement to prevent the
9590 optimizers from discarding the @code{asm} statement as unneeded
9591 (see @ref{Volatile}).
9593 This code makes no use of the optional @var{asmSymbolicName}. Therefore it
9594 references the first output operand as @code{%0} (were there a second, it
9595 would be @code{%1}, etc). The number of the first input operand is one greater
9596 than that of the last output operand. In this i386 example, that makes
9597 @code{Mask} referenced as @code{%1}:
9600 uint32_t Mask = 1234;
9609 That code overwrites the variable @code{Index} (@samp{=}),
9610 placing the value in a register (@samp{r}).
9611 Using the generic @samp{r} constraint instead of a constraint for a specific
9612 register allows the compiler to pick the register to use, which can result
9613 in more efficient code. This may not be possible if an assembler instruction
9614 requires a specific register.
9616 The following i386 example uses the @var{asmSymbolicName} syntax.
9618 same result as the code above, but some may consider it more readable or more
9619 maintainable since reordering index numbers is not necessary when adding or
9620 removing operands. The names @code{aIndex} and @code{aMask}
9621 are only used in this example to emphasize which
9622 names get used where.
9623 It is acceptable to reuse the names @code{Index} and @code{Mask}.
9626 uint32_t Mask = 1234;
9629 asm ("bsfl %[aMask], %[aIndex]"
9630 : [aIndex] "=r" (Index)
9631 : [aMask] "r" (Mask)
9635 Here are some more examples of output operands.
9642 asm ("mov %[e], %[d]"
9647 Here, @code{d} may either be in a register or in memory. Since the compiler
9648 might already have the current value of the @code{uint32_t} location
9649 pointed to by @code{e}
9650 in a register, you can enable it to choose the best location
9651 for @code{d} by specifying both constraints.
9653 @anchor{FlagOutputOperands}
9654 @subsubsection Flag Output Operands
9655 @cindex @code{asm} flag output operands
9657 Some targets have a special register that holds the ``flags'' for the
9658 result of an operation or comparison. Normally, the contents of that
9659 register are either unmodifed by the asm, or the @code{asm} statement is
9660 considered to clobber the contents.
9662 On some targets, a special form of output operand exists by which
9663 conditions in the flags register may be outputs of the asm. The set of
9664 conditions supported are target specific, but the general rule is that
9665 the output variable must be a scalar integer, and the value is boolean.
9666 When supported, the target defines the preprocessor symbol
9667 @code{__GCC_ASM_FLAG_OUTPUTS__}.
9669 Because of the special nature of the flag output operands, the constraint
9670 may not include alternatives.
9672 Most often, the target has only one flags register, and thus is an implied
9673 operand of many instructions. In this case, the operand should not be
9674 referenced within the assembler template via @code{%0} etc, as there's
9675 no corresponding text in the assembly language.
9679 The flag output constraints for the x86 family are of the form
9680 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
9681 conditions defined in the ISA manual for @code{j@var{cc}} or
9686 ``above'' or unsigned greater than
9688 ``above or equal'' or unsigned greater than or equal
9690 ``below'' or unsigned less than
9692 ``below or equal'' or unsigned less than or equal
9697 ``equal'' or zero flag set
9701 signed greater than or equal
9705 signed less than or equal
9726 ``not'' @var{flag}, or inverted versions of those above
9731 @anchor{InputOperands}
9732 @subsubsection Input Operands
9733 @cindex @code{asm} input operands
9734 @cindex @code{asm} expressions
9736 Input operands make values from C variables and expressions available to the
9739 Operands are separated by commas. Each operand has this format:
9742 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression})
9746 @item asmSymbolicName
9747 Specifies a symbolic name for the operand.
9748 Reference the name in the assembler template
9749 by enclosing it in square brackets
9750 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
9751 that contains the definition. Any valid C variable name is acceptable,
9752 including names already defined in the surrounding code. No two operands
9753 within the same @code{asm} statement can use the same symbolic name.
9755 When not using an @var{asmSymbolicName}, use the (zero-based) position
9757 in the list of operands in the assembler template. For example if there are
9758 two output operands and three inputs,
9759 use @samp{%2} in the template to refer to the first input operand,
9760 @samp{%3} for the second, and @samp{%4} for the third.
9763 A string constant specifying constraints on the placement of the operand;
9764 @xref{Constraints}, for details.
9766 Input constraint strings may not begin with either @samp{=} or @samp{+}.
9767 When you list more than one possible location (for example, @samp{"irm"}),
9768 the compiler chooses the most efficient one based on the current context.
9769 If you must use a specific register, but your Machine Constraints do not
9770 provide sufficient control to select the specific register you want,
9771 local register variables may provide a solution (@pxref{Local Register
9774 Input constraints can also be digits (for example, @code{"0"}). This indicates
9775 that the specified input must be in the same place as the output constraint
9776 at the (zero-based) index in the output constraint list.
9777 When using @var{asmSymbolicName} syntax for the output operands,
9778 you may use these names (enclosed in brackets @samp{[]}) instead of digits.
9781 This is the C variable or expression being passed to the @code{asm} statement
9782 as input. The enclosing parentheses are a required part of the syntax.
9786 When the compiler selects the registers to use to represent the input
9787 operands, it does not use any of the clobbered registers
9788 (@pxref{Clobbers and Scratch Registers}).
9790 If there are no output operands but there are input operands, place two
9791 consecutive colons where the output operands would go:
9794 __asm__ ("some instructions"
9796 : "r" (Offset / 8));
9799 @strong{Warning:} Do @emph{not} modify the contents of input-only operands
9800 (except for inputs tied to outputs). The compiler assumes that on exit from
9801 the @code{asm} statement these operands contain the same values as they
9802 had before executing the statement.
9803 It is @emph{not} possible to use clobbers
9804 to inform the compiler that the values in these inputs are changing. One
9805 common work-around is to tie the changing input variable to an output variable
9806 that never gets used. Note, however, that if the code that follows the
9807 @code{asm} statement makes no use of any of the output operands, the GCC
9808 optimizers may discard the @code{asm} statement as unneeded
9809 (see @ref{Volatile}).
9811 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
9812 instead of simply @samp{%2}). Typically these qualifiers are hardware
9813 dependent. The list of supported modifiers for x86 is found at
9814 @ref{x86Operandmodifiers,x86 Operand modifiers}.
9816 In this example using the fictitious @code{combine} instruction, the
9817 constraint @code{"0"} for input operand 1 says that it must occupy the same
9818 location as output operand 0. Only input operands may use numbers in
9819 constraints, and they must each refer to an output operand. Only a number (or
9820 the symbolic assembler name) in the constraint can guarantee that one operand
9821 is in the same place as another. The mere fact that @code{foo} is the value of
9822 both operands is not enough to guarantee that they are in the same place in
9823 the generated assembler code.
9826 asm ("combine %2, %0"
9828 : "0" (foo), "g" (bar));
9831 Here is an example using symbolic names.
9834 asm ("cmoveq %1, %2, %[result]"
9835 : [result] "=r"(result)
9836 : "r" (test), "r" (new), "[result]" (old));
9839 @anchor{Clobbers and Scratch Registers}
9840 @subsubsection Clobbers and Scratch Registers
9841 @cindex @code{asm} clobbers
9842 @cindex @code{asm} scratch registers
9844 While the compiler is aware of changes to entries listed in the output
9845 operands, the inline @code{asm} code may modify more than just the outputs. For
9846 example, calculations may require additional registers, or the processor may
9847 overwrite a register as a side effect of a particular assembler instruction.
9848 In order to inform the compiler of these changes, list them in the clobber
9849 list. Clobber list items are either register names or the special clobbers
9850 (listed below). Each clobber list item is a string constant
9851 enclosed in double quotes and separated by commas.
9853 Clobber descriptions may not in any way overlap with an input or output
9854 operand. For example, you may not have an operand describing a register class
9855 with one member when listing that register in the clobber list. Variables
9856 declared to live in specific registers (@pxref{Explicit Register
9857 Variables}) and used
9858 as @code{asm} input or output operands must have no part mentioned in the
9859 clobber description. In particular, there is no way to specify that input
9860 operands get modified without also specifying them as output operands.
9862 When the compiler selects which registers to use to represent input and output
9863 operands, it does not use any of the clobbered registers. As a result,
9864 clobbered registers are available for any use in the assembler code.
9866 Another restriction is that the clobber list should not contain the
9867 stack pointer register. This is because the compiler requires the
9868 value of the stack pointer to be the same after an @code{asm}
9869 statement as it was on entry to the statement. However, previous
9870 versions of GCC did not enforce this rule and allowed the stack
9871 pointer to appear in the list, with unclear semantics. This behavior
9872 is deprecated and listing the stack pointer may become an error in
9873 future versions of GCC@.
9875 Here is a realistic example for the VAX showing the use of clobbered
9879 asm volatile ("movc3 %0, %1, %2"
9881 : "g" (from), "g" (to), "g" (count)
9882 : "r0", "r1", "r2", "r3", "r4", "r5", "memory");
9885 Also, there are two special clobber arguments:
9889 The @code{"cc"} clobber indicates that the assembler code modifies the flags
9890 register. On some machines, GCC represents the condition codes as a specific
9891 hardware register; @code{"cc"} serves to name this register.
9892 On other machines, condition code handling is different,
9893 and specifying @code{"cc"} has no effect. But
9894 it is valid no matter what the target.
9897 The @code{"memory"} clobber tells the compiler that the assembly code
9899 reads or writes to items other than those listed in the input and output
9900 operands (for example, accessing the memory pointed to by one of the input
9901 parameters). To ensure memory contains correct values, GCC may need to flush
9902 specific register values to memory before executing the @code{asm}. Further,
9903 the compiler does not assume that any values read from memory before an
9904 @code{asm} remain unchanged after that @code{asm}; it reloads them as
9906 Using the @code{"memory"} clobber effectively forms a read/write
9907 memory barrier for the compiler.
9909 Note that this clobber does not prevent the @emph{processor} from doing
9910 speculative reads past the @code{asm} statement. To prevent that, you need
9911 processor-specific fence instructions.
9915 Flushing registers to memory has performance implications and may be
9916 an issue for time-sensitive code. You can provide better information
9917 to GCC to avoid this, as shown in the following examples. At a
9918 minimum, aliasing rules allow GCC to know what memory @emph{doesn't}
9921 Here is a fictitious sum of squares instruction, that takes two
9922 pointers to floating point values in memory and produces a floating
9923 point register output.
9924 Notice that @code{x}, and @code{y} both appear twice in the @code{asm}
9925 parameters, once to specify memory accessed, and once to specify a
9926 base register used by the @code{asm}. You won't normally be wasting a
9927 register by doing this as GCC can use the same register for both
9928 purposes. However, it would be foolish to use both @code{%1} and
9929 @code{%3} for @code{x} in this @code{asm} and expect them to be the
9930 same. In fact, @code{%3} may well not be a register. It might be a
9931 symbolic memory reference to the object pointed to by @code{x}.
9934 asm ("sumsq %0, %1, %2"
9936 : "r" (x), "r" (y), "m" (*x), "m" (*y));
9939 Here is a fictitious @code{*z++ = *x++ * *y++} instruction.
9940 Notice that the @code{x}, @code{y} and @code{z} pointer registers
9941 must be specified as input/output because the @code{asm} modifies
9945 asm ("vecmul %0, %1, %2"
9946 : "+r" (z), "+r" (x), "+r" (y), "=m" (*z)
9947 : "m" (*x), "m" (*y));
9950 An x86 example where the string memory argument is of unknown length.
9954 : "=c" (count), "+D" (p)
9955 : "m" (*(const char (*)[]) p), "0" (-1), "a" (0));
9958 If you know the above will only be reading a ten byte array then you
9959 could instead use a memory input like:
9960 @code{"m" (*(const char (*)[10]) p)}.
9962 Here is an example of a PowerPC vector scale implemented in assembly,
9963 complete with vector and condition code clobbers, and some initialized
9964 offset registers that are unchanged by the @code{asm}.
9968 dscal (size_t n, double *x, double alpha)
9970 asm ("/* lots of asm here */"
9971 : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x)
9972 : "d" (alpha), "b" (32), "b" (48), "b" (64),
9973 "b" (80), "b" (96), "b" (112)
9975 "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39",
9976 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47");
9980 Rather than allocating fixed registers via clobbers to provide scratch
9981 registers for an @code{asm} statement, an alternative is to define a
9982 variable and make it an early-clobber output as with @code{a2} and
9983 @code{a3} in the example below. This gives the compiler register
9984 allocator more freedom. You can also define a variable and make it an
9985 output tied to an input as with @code{a0} and @code{a1}, tied
9986 respectively to @code{ap} and @code{lda}. Of course, with tied
9987 outputs your @code{asm} can't use the input value after modifying the
9988 output register since they are one and the same register. What's
9989 more, if you omit the early-clobber on the output, it is possible that
9990 GCC might allocate the same register to another of the inputs if GCC
9991 could prove they had the same value on entry to the @code{asm}. This
9992 is why @code{a1} has an early-clobber. Its tied input, @code{lda}
9993 might conceivably be known to have the value 16 and without an
9994 early-clobber share the same register as @code{%11}. On the other
9995 hand, @code{ap} can't be the same as any of the other inputs, so an
9996 early-clobber on @code{a0} is not needed. It is also not desirable in
9997 this case. An early-clobber on @code{a0} would cause GCC to allocate
9998 a separate register for the @code{"m" (*(const double (*)[]) ap)}
9999 input. Note that tying an input to an output is the way to set up an
10000 initialized temporary register modified by an @code{asm} statement.
10001 An input not tied to an output is assumed by GCC to be unchanged, for
10002 example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might
10003 use that register in following code if the value 16 happened to be
10004 needed. You can even use a normal @code{asm} output for a scratch if
10005 all inputs that might share the same register are consumed before the
10006 scratch is used. The VSX registers clobbered by the @code{asm}
10007 statement could have used this technique except for GCC's limit on the
10008 number of @code{asm} parameters.
10012 dgemv_kernel_4x4 (long n, const double *ap, long lda,
10013 const double *x, double *y, double alpha)
10022 /* lots of asm here */
10023 "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n"
10024 "#a0=%3 a1=%4 a2=%5 a3=%6"
10026 "+m" (*(double (*)[n]) y),
10034 "m" (*(const double (*)[n]) x),
10035 "m" (*(const double (*)[]) ap),
10043 "vs32","vs33","vs34","vs35","vs36","vs37",
10044 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"
10049 @anchor{GotoLabels}
10050 @subsubsection Goto Labels
10051 @cindex @code{asm} goto labels
10053 @code{asm goto} allows assembly code to jump to one or more C labels. The
10054 @var{GotoLabels} section in an @code{asm goto} statement contains
10056 list of all C labels to which the assembler code may jump. GCC assumes that
10057 @code{asm} execution falls through to the next statement (if this is not the
10058 case, consider using the @code{__builtin_unreachable} intrinsic after the
10059 @code{asm} statement). Optimization of @code{asm goto} may be improved by
10060 using the @code{hot} and @code{cold} label attributes (@pxref{Label
10063 An @code{asm goto} statement cannot have outputs.
10064 This is due to an internal restriction of
10065 the compiler: control transfer instructions cannot have outputs.
10066 If the assembler code does modify anything, use the @code{"memory"} clobber
10068 optimizers to flush all register values to memory and reload them if
10069 necessary after the @code{asm} statement.
10071 Also note that an @code{asm goto} statement is always implicitly
10072 considered volatile.
10074 To reference a label in the assembler template,
10075 prefix it with @samp{%l} (lowercase @samp{L}) followed
10076 by its (zero-based) position in @var{GotoLabels} plus the number of input
10077 operands. For example, if the @code{asm} has three inputs and references two
10078 labels, refer to the first label as @samp{%l3} and the second as @samp{%l4}).
10080 Alternately, you can reference labels using the actual C label name enclosed
10081 in brackets. For example, to reference a label named @code{carry}, you can
10082 use @samp{%l[carry]}. The label must still be listed in the @var{GotoLabels}
10083 section when using this approach.
10085 Here is an example of @code{asm goto} for i386:
10091 : /* No outputs. */
10092 : "r" (p1), "r" (p2)
10102 The following example shows an @code{asm goto} that uses a memory clobber.
10108 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
10109 : /* No outputs. */
10119 @anchor{x86Operandmodifiers}
10120 @subsubsection x86 Operand Modifiers
10122 References to input, output, and goto operands in the assembler template
10123 of extended @code{asm} statements can use
10124 modifiers to affect the way the operands are formatted in
10125 the code output to the assembler. For example, the
10126 following code uses the @samp{h} and @samp{b} modifiers for x86:
10130 asm volatile ("xchg %h0, %b0" : "+a" (num) );
10134 These modifiers generate this assembler code:
10140 The rest of this discussion uses the following code for illustrative purposes.
10149 asm volatile goto ("some assembler instructions here"
10150 : /* No outputs. */
10151 : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42)
10152 : /* No clobbers. */
10157 With no modifiers, this is what the output from the operands would be
10158 for the @samp{att} and @samp{intel} dialects of assembler:
10160 @multitable {Operand} {$.L2} {OFFSET FLAT:.L2}
10161 @headitem Operand @tab @samp{att} @tab @samp{intel}
10170 @tab @code{OFFSET FLAT:.L3}
10173 The table below shows the list of supported modifiers and their effects.
10175 @multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}}
10176 @headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel}
10178 @tab Print an absolute memory reference.
10183 @tab Print the QImode name of the register.
10188 @tab Require a constant operand and print the constant expression with no punctuation.
10193 @tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit.
10194 Otherwise mode is unspecified (VOIDmode).
10199 @tab Print the QImode name for a ``high'' register.
10204 @tab Add 8 bytes to an offsettable memory reference. Useful when accessing the
10205 high 8 bytes of SSE values. For a memref in (%rax), it generates
10207 @tab @code{8(%rax)}
10210 @tab Print the SImode name of the register.
10215 @tab Print the label name with no punctuation.
10220 @tab Print raw symbol name (without syntax-specific prefixes).
10225 @tab If used for a function, print the PLT suffix and generate PIC code.
10226 For example, emit @code{foo@@PLT} instead of 'foo' for the function
10227 foo(). If used for a constant, drop all syntax-specific prefixes and
10228 issue the bare constant. See @code{p} above.
10230 @tab Print the DImode name of the register.
10235 @tab Print the HImode name of the register.
10240 @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}).
10246 @code{V} is a special modifier which prints the name of the full integer
10247 register without @code{%}.
10249 @anchor{x86floatingpointasmoperands}
10250 @subsubsection x86 Floating-Point @code{asm} Operands
10252 On x86 targets, there are several rules on the usage of stack-like registers
10253 in the operands of an @code{asm}. These rules apply only to the operands
10254 that are stack-like registers:
10258 Given a set of input registers that die in an @code{asm}, it is
10259 necessary to know which are implicitly popped by the @code{asm}, and
10260 which must be explicitly popped by GCC@.
10262 An input register that is implicitly popped by the @code{asm} must be
10263 explicitly clobbered, unless it is constrained to match an
10267 For any input register that is implicitly popped by an @code{asm}, it is
10268 necessary to know how to adjust the stack to compensate for the pop.
10269 If any non-popped input is closer to the top of the reg-stack than
10270 the implicitly popped register, it would not be possible to know what the
10271 stack looked like---it's not clear how the rest of the stack ``slides
10274 All implicitly popped input registers must be closer to the top of
10275 the reg-stack than any input that is not implicitly popped.
10277 It is possible that if an input dies in an @code{asm}, the compiler might
10278 use the input register for an output reload. Consider this example:
10281 asm ("foo" : "=t" (a) : "f" (b));
10285 This code says that input @code{b} is not popped by the @code{asm}, and that
10286 the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one
10287 deeper after the @code{asm} than it was before. But, it is possible that
10288 reload may think that it can use the same register for both the input and
10291 To prevent this from happening,
10292 if any input operand uses the @samp{f} constraint, all output register
10293 constraints must use the @samp{&} early-clobber modifier.
10295 The example above is correctly written as:
10298 asm ("foo" : "=&t" (a) : "f" (b));
10302 Some operands need to be in particular places on the stack. All
10303 output operands fall in this category---GCC has no other way to
10304 know which registers the outputs appear in unless you indicate
10305 this in the constraints.
10307 Output operands must specifically indicate which register an output
10308 appears in after an @code{asm}. @samp{=f} is not allowed: the operand
10309 constraints must select a class with a single register.
10312 Output operands may not be ``inserted'' between existing stack registers.
10313 Since no 387 opcode uses a read/write operand, all output operands
10314 are dead before the @code{asm}, and are pushed by the @code{asm}.
10315 It makes no sense to push anywhere but the top of the reg-stack.
10317 Output operands must start at the top of the reg-stack: output
10318 operands may not ``skip'' a register.
10321 Some @code{asm} statements may need extra stack space for internal
10322 calculations. This can be guaranteed by clobbering stack registers
10323 unrelated to the inputs and outputs.
10328 takes one input, which is internally popped, and produces two outputs.
10331 asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
10335 This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode,
10336 and replaces them with one output. The @code{st(1)} clobber is necessary
10337 for the compiler to know that @code{fyl2xp1} pops both inputs.
10340 asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
10348 @subsection Controlling Names Used in Assembler Code
10349 @cindex assembler names for identifiers
10350 @cindex names used in assembler code
10351 @cindex identifiers, names in assembler code
10353 You can specify the name to be used in the assembler code for a C
10354 function or variable by writing the @code{asm} (or @code{__asm__})
10355 keyword after the declarator.
10356 It is up to you to make sure that the assembler names you choose do not
10357 conflict with any other assembler symbols, or reference registers.
10359 @subsubheading Assembler names for data:
10361 This sample shows how to specify the assembler name for data:
10364 int foo asm ("myfoo") = 2;
10368 This specifies that the name to be used for the variable @code{foo} in
10369 the assembler code should be @samp{myfoo} rather than the usual
10372 On systems where an underscore is normally prepended to the name of a C
10373 variable, this feature allows you to define names for the
10374 linker that do not start with an underscore.
10376 GCC does not support using this feature with a non-static local variable
10377 since such variables do not have assembler names. If you are
10378 trying to put the variable in a particular register, see
10379 @ref{Explicit Register Variables}.
10381 @subsubheading Assembler names for functions:
10383 To specify the assembler name for functions, write a declaration for the
10384 function before its definition and put @code{asm} there, like this:
10387 int func (int x, int y) asm ("MYFUNC");
10389 int func (int x, int y)
10395 This specifies that the name to be used for the function @code{func} in
10396 the assembler code should be @code{MYFUNC}.
10398 @node Explicit Register Variables
10399 @subsection Variables in Specified Registers
10400 @anchor{Explicit Reg Vars}
10401 @cindex explicit register variables
10402 @cindex variables in specified registers
10403 @cindex specified registers
10405 GNU C allows you to associate specific hardware registers with C
10406 variables. In almost all cases, allowing the compiler to assign
10407 registers produces the best code. However under certain unusual
10408 circumstances, more precise control over the variable storage is
10411 Both global and local variables can be associated with a register. The
10412 consequences of performing this association are very different between
10413 the two, as explained in the sections below.
10416 * Global Register Variables:: Variables declared at global scope.
10417 * Local Register Variables:: Variables declared within a function.
10420 @node Global Register Variables
10421 @subsubsection Defining Global Register Variables
10422 @anchor{Global Reg Vars}
10423 @cindex global register variables
10424 @cindex registers, global variables in
10425 @cindex registers, global allocation
10427 You can define a global register variable and associate it with a specified
10428 register like this:
10431 register int *foo asm ("r12");
10435 Here @code{r12} is the name of the register that should be used. Note that
10436 this is the same syntax used for defining local register variables, but for
10437 a global variable the declaration appears outside a function. The
10438 @code{register} keyword is required, and cannot be combined with
10439 @code{static}. The register name must be a valid register name for the
10442 Do not use type qualifiers such as @code{const} and @code{volatile}, as
10443 the outcome may be contrary to expectations. In particular, using the
10444 @code{volatile} qualifier does not fully prevent the compiler from
10445 optimizing accesses to the register.
10447 Registers are a scarce resource on most systems and allowing the
10448 compiler to manage their usage usually results in the best code. However,
10449 under special circumstances it can make sense to reserve some globally.
10450 For example this may be useful in programs such as programming language
10451 interpreters that have a couple of global variables that are accessed
10454 After defining a global register variable, for the current compilation
10458 @item If the register is a call-saved register, call ABI is affected:
10459 the register will not be restored in function epilogue sequences after
10460 the variable has been assigned. Therefore, functions cannot safely
10461 return to callers that assume standard ABI.
10462 @item Conversely, if the register is a call-clobbered register, making
10463 calls to functions that use standard ABI may lose contents of the variable.
10464 Such calls may be created by the compiler even if none are evident in
10465 the original program, for example when libgcc functions are used to
10466 make up for unavailable instructions.
10467 @item Accesses to the variable may be optimized as usual and the register
10468 remains available for allocation and use in any computations, provided that
10469 observable values of the variable are not affected.
10470 @item If the variable is referenced in inline assembly, the type of access
10471 must be provided to the compiler via constraints (@pxref{Constraints}).
10472 Accesses from basic asms are not supported.
10475 Note that these points @emph{only} apply to code that is compiled with the
10476 definition. The behavior of code that is merely linked in (for example
10477 code from libraries) is not affected.
10479 If you want to recompile source files that do not actually use your global
10480 register variable so they do not use the specified register for any other
10481 purpose, you need not actually add the global register declaration to
10482 their source code. It suffices to specify the compiler option
10483 @option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the
10486 @subsubheading Declaring the variable
10488 Global register variables cannot have initial values, because an
10489 executable file has no means to supply initial contents for a register.
10491 When selecting a register, choose one that is normally saved and
10492 restored by function calls on your machine. This ensures that code
10493 which is unaware of this reservation (such as library routines) will
10494 restore it before returning.
10496 On machines with register windows, be sure to choose a global
10497 register that is not affected magically by the function call mechanism.
10499 @subsubheading Using the variable
10501 @cindex @code{qsort}, and global register variables
10502 When calling routines that are not aware of the reservation, be
10503 cautious if those routines call back into code which uses them. As an
10504 example, if you call the system library version of @code{qsort}, it may
10505 clobber your registers during execution, but (if you have selected
10506 appropriate registers) it will restore them before returning. However
10507 it will @emph{not} restore them before calling @code{qsort}'s comparison
10508 function. As a result, global values will not reliably be available to
10509 the comparison function unless the @code{qsort} function itself is rebuilt.
10511 Similarly, it is not safe to access the global register variables from signal
10512 handlers or from more than one thread of control. Unless you recompile
10513 them specially for the task at hand, the system library routines may
10514 temporarily use the register for other things. Furthermore, since the register
10515 is not reserved exclusively for the variable, accessing it from handlers of
10516 asynchronous signals may observe unrelated temporary values residing in the
10519 @cindex register variable after @code{longjmp}
10520 @cindex global register after @code{longjmp}
10521 @cindex value after @code{longjmp}
10524 On most machines, @code{longjmp} restores to each global register
10525 variable the value it had at the time of the @code{setjmp}. On some
10526 machines, however, @code{longjmp} does not change the value of global
10527 register variables. To be portable, the function that called @code{setjmp}
10528 should make other arrangements to save the values of the global register
10529 variables, and to restore them in a @code{longjmp}. This way, the same
10530 thing happens regardless of what @code{longjmp} does.
10532 @node Local Register Variables
10533 @subsubsection Specifying Registers for Local Variables
10534 @anchor{Local Reg Vars}
10535 @cindex local variables, specifying registers
10536 @cindex specifying registers for local variables
10537 @cindex registers for local variables
10539 You can define a local register variable and associate it with a specified
10540 register like this:
10543 register int *foo asm ("r12");
10547 Here @code{r12} is the name of the register that should be used. Note
10548 that this is the same syntax used for defining global register variables,
10549 but for a local variable the declaration appears within a function. The
10550 @code{register} keyword is required, and cannot be combined with
10551 @code{static}. The register name must be a valid register name for the
10554 Do not use type qualifiers such as @code{const} and @code{volatile}, as
10555 the outcome may be contrary to expectations. In particular, when the
10556 @code{const} qualifier is used, the compiler may substitute the
10557 variable with its initializer in @code{asm} statements, which may cause
10558 the corresponding operand to appear in a different register.
10560 As with global register variables, it is recommended that you choose
10561 a register that is normally saved and restored by function calls on your
10562 machine, so that calls to library routines will not clobber it.
10564 The only supported use for this feature is to specify registers
10565 for input and output operands when calling Extended @code{asm}
10566 (@pxref{Extended Asm}). This may be necessary if the constraints for a
10567 particular machine don't provide sufficient control to select the desired
10568 register. To force an operand into a register, create a local variable
10569 and specify the register name after the variable's declaration. Then use
10570 the local variable for the @code{asm} operand and specify any constraint
10571 letter that matches the register:
10574 register int *p1 asm ("r0") = @dots{};
10575 register int *p2 asm ("r1") = @dots{};
10576 register int *result asm ("r0");
10577 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
10580 @emph{Warning:} In the above example, be aware that a register (for example
10581 @code{r0}) can be call-clobbered by subsequent code, including function
10582 calls and library calls for arithmetic operators on other variables (for
10583 example the initialization of @code{p2}). In this case, use temporary
10584 variables for expressions between the register assignments:
10588 register int *p1 asm ("r0") = @dots{};
10589 register int *p2 asm ("r1") = t1;
10590 register int *result asm ("r0");
10591 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
10594 Defining a register variable does not reserve the register. Other than
10595 when invoking the Extended @code{asm}, the contents of the specified
10596 register are not guaranteed. For this reason, the following uses
10597 are explicitly @emph{not} supported. If they appear to work, it is only
10598 happenstance, and may stop working as intended due to (seemingly)
10599 unrelated changes in surrounding code, or even minor changes in the
10600 optimization of a future version of gcc:
10603 @item Passing parameters to or from Basic @code{asm}
10604 @item Passing parameters to or from Extended @code{asm} without using input
10605 or output operands.
10606 @item Passing parameters to or from routines written in assembler (or
10607 other languages) using non-standard calling conventions.
10610 Some developers use Local Register Variables in an attempt to improve
10611 gcc's allocation of registers, especially in large functions. In this
10612 case the register name is essentially a hint to the register allocator.
10613 While in some instances this can generate better code, improvements are
10614 subject to the whims of the allocator/optimizers. Since there are no
10615 guarantees that your improvements won't be lost, this usage of Local
10616 Register Variables is discouraged.
10618 On the MIPS platform, there is related use for local register variables
10619 with slightly different characteristics (@pxref{MIPS Coprocessors,,
10620 Defining coprocessor specifics for MIPS targets, gccint,
10621 GNU Compiler Collection (GCC) Internals}).
10623 @node Size of an asm
10624 @subsection Size of an @code{asm}
10626 Some targets require that GCC track the size of each instruction used
10627 in order to generate correct code. Because the final length of the
10628 code produced by an @code{asm} statement is only known by the
10629 assembler, GCC must make an estimate as to how big it will be. It
10630 does this by counting the number of instructions in the pattern of the
10631 @code{asm} and multiplying that by the length of the longest
10632 instruction supported by that processor. (When working out the number
10633 of instructions, it assumes that any occurrence of a newline or of
10634 whatever statement separator character is supported by the assembler ---
10635 typically @samp{;} --- indicates the end of an instruction.)
10637 Normally, GCC's estimate is adequate to ensure that correct
10638 code is generated, but it is possible to confuse the compiler if you use
10639 pseudo instructions or assembler macros that expand into multiple real
10640 instructions, or if you use assembler directives that expand to more
10641 space in the object file than is needed for a single instruction.
10642 If this happens then the assembler may produce a diagnostic saying that
10643 a label is unreachable.
10645 @cindex @code{asm inline}
10646 This size is also used for inlining decisions. If you use @code{asm inline}
10647 instead of just @code{asm}, then for inlining purposes the size of the asm
10648 is taken as the minimum size, ignoring how many instructions GCC thinks it is.
10650 @node Alternate Keywords
10651 @section Alternate Keywords
10652 @cindex alternate keywords
10653 @cindex keywords, alternate
10655 @option{-ansi} and the various @option{-std} options disable certain
10656 keywords. This causes trouble when you want to use GNU C extensions, or
10657 a general-purpose header file that should be usable by all programs,
10658 including ISO C programs. The keywords @code{asm}, @code{typeof} and
10659 @code{inline} are not available in programs compiled with
10660 @option{-ansi} or @option{-std} (although @code{inline} can be used in a
10661 program compiled with @option{-std=c99} or @option{-std=c11}). The
10663 @code{restrict} is only available when @option{-std=gnu99} (which will
10664 eventually be the default) or @option{-std=c99} (or the equivalent
10665 @option{-std=iso9899:1999}), or an option for a later standard
10668 The way to solve these problems is to put @samp{__} at the beginning and
10669 end of each problematical keyword. For example, use @code{__asm__}
10670 instead of @code{asm}, and @code{__inline__} instead of @code{inline}.
10672 Other C compilers won't accept these alternative keywords; if you want to
10673 compile with another compiler, you can define the alternate keywords as
10674 macros to replace them with the customary keywords. It looks like this:
10678 #define __asm__ asm
10682 @findex __extension__
10684 @option{-pedantic} and other options cause warnings for many GNU C extensions.
10686 prevent such warnings within one expression by writing
10687 @code{__extension__} before the expression. @code{__extension__} has no
10688 effect aside from this.
10690 @node Incomplete Enums
10691 @section Incomplete @code{enum} Types
10693 You can define an @code{enum} tag without specifying its possible values.
10694 This results in an incomplete type, much like what you get if you write
10695 @code{struct foo} without describing the elements. A later declaration
10696 that does specify the possible values completes the type.
10698 You cannot allocate variables or storage using the type while it is
10699 incomplete. However, you can work with pointers to that type.
10701 This extension may not be very useful, but it makes the handling of
10702 @code{enum} more consistent with the way @code{struct} and @code{union}
10705 This extension is not supported by GNU C++.
10707 @node Function Names
10708 @section Function Names as Strings
10709 @cindex @code{__func__} identifier
10710 @cindex @code{__FUNCTION__} identifier
10711 @cindex @code{__PRETTY_FUNCTION__} identifier
10713 GCC provides three magic constants that hold the name of the current
10714 function as a string. In C++11 and later modes, all three are treated
10715 as constant expressions and can be used in @code{constexpr} constexts.
10716 The first of these constants is @code{__func__}, which is part of
10719 The identifier @code{__func__} is implicitly declared by the translator
10720 as if, immediately following the opening brace of each function
10721 definition, the declaration
10724 static const char __func__[] = "function-name";
10728 appeared, where function-name is the name of the lexically-enclosing
10729 function. This name is the unadorned name of the function. As an
10730 extension, at file (or, in C++, namespace scope), @code{__func__}
10731 evaluates to the empty string.
10733 @code{__FUNCTION__} is another name for @code{__func__}, provided for
10734 backward compatibility with old versions of GCC.
10736 In C, @code{__PRETTY_FUNCTION__} is yet another name for
10737 @code{__func__}, except that at file (or, in C++, namespace scope),
10738 it evaluates to the string @code{"top level"}. In addition, in C++,
10739 @code{__PRETTY_FUNCTION__} contains the signature of the function as
10740 well as its bare name. For example, this program:
10743 extern "C" int printf (const char *, ...);
10749 printf ("__FUNCTION__ = %s\n", __FUNCTION__);
10750 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
10768 __PRETTY_FUNCTION__ = void a::sub(int)
10771 These identifiers are variables, not preprocessor macros, and may not
10772 be used to initialize @code{char} arrays or be concatenated with string
10775 @node Return Address
10776 @section Getting the Return or Frame Address of a Function
10778 These functions may be used to get information about the callers of a
10781 @deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level})
10782 This function returns the return address of the current function, or of
10783 one of its callers. The @var{level} argument is number of frames to
10784 scan up the call stack. A value of @code{0} yields the return address
10785 of the current function, a value of @code{1} yields the return address
10786 of the caller of the current function, and so forth. When inlining
10787 the expected behavior is that the function returns the address of
10788 the function that is returned to. To work around this behavior use
10789 the @code{noinline} function attribute.
10791 The @var{level} argument must be a constant integer.
10793 On some machines it may be impossible to determine the return address of
10794 any function other than the current one; in such cases, or when the top
10795 of the stack has been reached, this function returns @code{0} or a
10796 random value. In addition, @code{__builtin_frame_address} may be used
10797 to determine if the top of the stack has been reached.
10799 Additional post-processing of the returned value may be needed, see
10800 @code{__builtin_extract_return_addr}.
10802 Calling this function with a nonzero argument can have unpredictable
10803 effects, including crashing the calling program. As a result, calls
10804 that are considered unsafe are diagnosed when the @option{-Wframe-address}
10805 option is in effect. Such calls should only be made in debugging
10809 @deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr})
10810 The address as returned by @code{__builtin_return_address} may have to be fed
10811 through this function to get the actual encoded address. For example, on the
10812 31-bit S/390 platform the highest bit has to be masked out, or on SPARC
10813 platforms an offset has to be added for the true next instruction to be
10816 If no fixup is needed, this function simply passes through @var{addr}.
10819 @deftypefn {Built-in Function} {void *} __builtin_frob_return_address (void *@var{addr})
10820 This function does the reverse of @code{__builtin_extract_return_addr}.
10823 @deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level})
10824 This function is similar to @code{__builtin_return_address}, but it
10825 returns the address of the function frame rather than the return address
10826 of the function. Calling @code{__builtin_frame_address} with a value of
10827 @code{0} yields the frame address of the current function, a value of
10828 @code{1} yields the frame address of the caller of the current function,
10831 The frame is the area on the stack that holds local variables and saved
10832 registers. The frame address is normally the address of the first word
10833 pushed on to the stack by the function. However, the exact definition
10834 depends upon the processor and the calling convention. If the processor
10835 has a dedicated frame pointer register, and the function has a frame,
10836 then @code{__builtin_frame_address} returns the value of the frame
10839 On some machines it may be impossible to determine the frame address of
10840 any function other than the current one; in such cases, or when the top
10841 of the stack has been reached, this function returns @code{0} if
10842 the first frame pointer is properly initialized by the startup code.
10844 Calling this function with a nonzero argument can have unpredictable
10845 effects, including crashing the calling program. As a result, calls
10846 that are considered unsafe are diagnosed when the @option{-Wframe-address}
10847 option is in effect. Such calls should only be made in debugging
10851 @node Vector Extensions
10852 @section Using Vector Instructions through Built-in Functions
10854 On some targets, the instruction set contains SIMD vector instructions which
10855 operate on multiple values contained in one large register at the same time.
10856 For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used
10859 The first step in using these extensions is to provide the necessary data
10860 types. This should be done using an appropriate @code{typedef}:
10863 typedef int v4si __attribute__ ((vector_size (16)));
10867 The @code{int} type specifies the base type, while the attribute specifies
10868 the vector size for the variable, measured in bytes. For example, the
10869 declaration above causes the compiler to set the mode for the @code{v4si}
10870 type to be 16 bytes wide and divided into @code{int} sized units. For
10871 a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the
10872 corresponding mode of @code{foo} is @acronym{V4SI}.
10874 The @code{vector_size} attribute is only applicable to integral and
10875 float scalars, although arrays, pointers, and function return values
10876 are allowed in conjunction with this construct. Only sizes that are
10877 a power of two are currently allowed.
10879 All the basic integer types can be used as base types, both as signed
10880 and as unsigned: @code{char}, @code{short}, @code{int}, @code{long},
10881 @code{long long}. In addition, @code{float} and @code{double} can be
10882 used to build floating-point vector types.
10884 Specifying a combination that is not valid for the current architecture
10885 causes GCC to synthesize the instructions using a narrower mode.
10886 For example, if you specify a variable of type @code{V4SI} and your
10887 architecture does not allow for this specific SIMD type, GCC
10888 produces code that uses 4 @code{SIs}.
10890 The types defined in this manner can be used with a subset of normal C
10891 operations. Currently, GCC allows using the following operators
10892 on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@.
10894 The operations behave like C++ @code{valarrays}. Addition is defined as
10895 the addition of the corresponding elements of the operands. For
10896 example, in the code below, each of the 4 elements in @var{a} is
10897 added to the corresponding 4 elements in @var{b} and the resulting
10898 vector is stored in @var{c}.
10901 typedef int v4si __attribute__ ((vector_size (16)));
10908 Subtraction, multiplication, division, and the logical operations
10909 operate in a similar manner. Likewise, the result of using the unary
10910 minus or complement operators on a vector type is a vector whose
10911 elements are the negative or complemented values of the corresponding
10912 elements in the operand.
10914 It is possible to use shifting operators @code{<<}, @code{>>} on
10915 integer-type vectors. The operation is defined as following: @code{@{a0,
10916 a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1,
10917 @dots{}, an >> bn@}}@. Vector operands must have the same number of
10920 For convenience, it is allowed to use a binary vector operation
10921 where one operand is a scalar. In that case the compiler transforms
10922 the scalar operand into a vector where each element is the scalar from
10923 the operation. The transformation happens only if the scalar could be
10924 safely converted to the vector-element type.
10925 Consider the following code.
10928 typedef int v4si __attribute__ ((vector_size (16)));
10933 a = b + 1; /* a = b + @{1,1,1,1@}; */
10934 a = 2 * b; /* a = @{2,2,2,2@} * b; */
10936 a = l + a; /* Error, cannot convert long to int. */
10939 Vectors can be subscripted as if the vector were an array with
10940 the same number of elements and base type. Out of bound accesses
10941 invoke undefined behavior at run time. Warnings for out of bound
10942 accesses for vector subscription can be enabled with
10943 @option{-Warray-bounds}.
10945 Vector comparison is supported with standard comparison
10946 operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be
10947 vector expressions of integer-type or real-type. Comparison between
10948 integer-type vectors and real-type vectors are not supported. The
10949 result of the comparison is a vector of the same width and number of
10950 elements as the comparison operands with a signed integral element
10953 Vectors are compared element-wise producing 0 when comparison is false
10954 and -1 (constant of the appropriate type where all bits are set)
10955 otherwise. Consider the following example.
10958 typedef int v4si __attribute__ ((vector_size (16)));
10960 v4si a = @{1,2,3,4@};
10961 v4si b = @{3,2,1,4@};
10964 c = a > b; /* The result would be @{0, 0,-1, 0@} */
10965 c = a == b; /* The result would be @{0,-1, 0,-1@} */
10968 In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where
10969 @code{b} and @code{c} are vectors of the same type and @code{a} is an
10970 integer vector with the same number of elements of the same size as @code{b}
10971 and @code{c}, computes all three arguments and creates a vector
10972 @code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in
10973 OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}.
10974 As in the case of binary operations, this syntax is also accepted when
10975 one of @code{b} or @code{c} is a scalar that is then transformed into a
10976 vector. If both @code{b} and @code{c} are scalars and the type of
10977 @code{true?b:c} has the same size as the element type of @code{a}, then
10978 @code{b} and @code{c} are converted to a vector type whose elements have
10979 this type and with the same number of elements as @code{a}.
10981 In C++, the logic operators @code{!, &&, ||} are available for vectors.
10982 @code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to
10983 @code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}.
10984 For mixed operations between a scalar @code{s} and a vector @code{v},
10985 @code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is
10986 short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}.
10988 @findex __builtin_shuffle
10989 Vector shuffling is available using functions
10990 @code{__builtin_shuffle (vec, mask)} and
10991 @code{__builtin_shuffle (vec0, vec1, mask)}.
10992 Both functions construct a permutation of elements from one or two
10993 vectors and return a vector of the same type as the input vector(s).
10994 The @var{mask} is an integral vector with the same width (@var{W})
10995 and element count (@var{N}) as the output vector.
10997 The elements of the input vectors are numbered in memory ordering of
10998 @var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The
10999 elements of @var{mask} are considered modulo @var{N} in the single-operand
11000 case and modulo @math{2*@var{N}} in the two-operand case.
11002 Consider the following example,
11005 typedef int v4si __attribute__ ((vector_size (16)));
11007 v4si a = @{1,2,3,4@};
11008 v4si b = @{5,6,7,8@};
11009 v4si mask1 = @{0,1,1,3@};
11010 v4si mask2 = @{0,4,2,5@};
11013 res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */
11014 res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */
11017 Note that @code{__builtin_shuffle} is intentionally semantically
11018 compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions.
11020 You can declare variables and use them in function calls and returns, as
11021 well as in assignments and some casts. You can specify a vector type as
11022 a return type for a function. Vector types can also be used as function
11023 arguments. It is possible to cast from one vector type to another,
11024 provided they are of the same size (in fact, you can also cast vectors
11025 to and from other datatypes of the same size).
11027 You cannot operate between vectors of different lengths or different
11028 signedness without a cast.
11030 @findex __builtin_convertvector
11031 Vector conversion is available using the
11032 @code{__builtin_convertvector (vec, vectype)}
11033 function. @var{vec} must be an expression with integral or floating
11034 vector type and @var{vectype} an integral or floating vector type with the
11035 same number of elements. The result has @var{vectype} type and value of
11036 a C cast of every element of @var{vec} to the element type of @var{vectype}.
11038 Consider the following example,
11040 typedef int v4si __attribute__ ((vector_size (16)));
11041 typedef float v4sf __attribute__ ((vector_size (16)));
11042 typedef double v4df __attribute__ ((vector_size (32)));
11043 typedef unsigned long long v4di __attribute__ ((vector_size (32)));
11045 v4si a = @{1,-2,3,-4@};
11046 v4sf b = @{1.5f,-2.5f,3.f,7.f@};
11047 v4di c = @{1ULL,5ULL,0ULL,10ULL@};
11048 v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */
11050 v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */
11051 v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */
11052 v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */
11053 v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */
11054 v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */
11057 @cindex vector types, using with x86 intrinsics
11058 Sometimes it is desirable to write code using a mix of generic vector
11059 operations (for clarity) and machine-specific vector intrinsics (to
11060 access vector instructions that are not exposed via generic built-ins).
11061 On x86, intrinsic functions for integer vectors typically use the same
11062 vector type @code{__m128i} irrespective of how they interpret the vector,
11063 making it necessary to cast their arguments and return values from/to
11064 other vector types. In C, you can make use of a @code{union} type:
11065 @c In C++ such type punning via a union is not allowed by the language
11067 #include <immintrin.h>
11069 typedef unsigned char u8x16 __attribute__ ((vector_size (16)));
11070 typedef unsigned int u32x4 __attribute__ ((vector_size (16)));
11080 for variables that can be used with both built-in operators and x86
11084 v128 x, y = @{ 0 @};
11085 memcpy (&x, ptr, sizeof x);
11087 x.mm = _mm_adds_epu8 (x.mm, y.mm);
11090 /* Instead of a variable, a compound literal may be used to pass the
11091 return value of an intrinsic call to a function expecting the union: */
11093 x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@});
11094 @c This could be done implicitly with __attribute__((transparent_union)),
11095 @c but GCC does not accept it for unions of vector types (PR 88955).
11099 @section Support for @code{offsetof}
11100 @findex __builtin_offsetof
11102 GCC implements for both C and C++ a syntactic extension to implement
11103 the @code{offsetof} macro.
11107 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
11109 offsetof_member_designator:
11111 | offsetof_member_designator "." @code{identifier}
11112 | offsetof_member_designator "[" @code{expr} "]"
11115 This extension is sufficient such that
11118 #define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member})
11122 is a suitable definition of the @code{offsetof} macro. In C++, @var{type}
11123 may be dependent. In either case, @var{member} may consist of a single
11124 identifier, or a sequence of member accesses and array references.
11126 @node __sync Builtins
11127 @section Legacy @code{__sync} Built-in Functions for Atomic Memory Access
11129 The following built-in functions
11130 are intended to be compatible with those described
11131 in the @cite{Intel Itanium Processor-specific Application Binary Interface},
11132 section 7.4. As such, they depart from normal GCC practice by not using
11133 the @samp{__builtin_} prefix and also by being overloaded so that they
11134 work on multiple types.
11136 The definition given in the Intel documentation allows only for the use of
11137 the types @code{int}, @code{long}, @code{long long} or their unsigned
11138 counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in
11139 size other than the C type @code{_Bool} or the C++ type @code{bool}.
11140 Operations on pointer arguments are performed as if the operands were
11141 of the @code{uintptr_t} type. That is, they are not scaled by the size
11142 of the type to which the pointer points.
11144 These functions are implemented in terms of the @samp{__atomic}
11145 builtins (@pxref{__atomic Builtins}). They should not be used for new
11146 code which should use the @samp{__atomic} builtins instead.
11148 Not all operations are supported by all target processors. If a particular
11149 operation cannot be implemented on the target processor, a warning is
11150 generated and a call to an external function is generated. The external
11151 function carries the same name as the built-in version,
11152 with an additional suffix
11153 @samp{_@var{n}} where @var{n} is the size of the data type.
11155 @c ??? Should we have a mechanism to suppress this warning? This is almost
11156 @c useful for implementing the operation under the control of an external
11159 In most cases, these built-in functions are considered a @dfn{full barrier}.
11161 no memory operand is moved across the operation, either forward or
11162 backward. Further, instructions are issued as necessary to prevent the
11163 processor from speculating loads across the operation and from queuing stores
11164 after the operation.
11166 All of the routines are described in the Intel documentation to take
11167 ``an optional list of variables protected by the memory barrier''. It's
11168 not clear what is meant by that; it could mean that @emph{only} the
11169 listed variables are protected, or it could mean a list of additional
11170 variables to be protected. The list is ignored by GCC which treats it as
11171 empty. GCC interprets an empty list as meaning that all globally
11172 accessible variables should be protected.
11175 @item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...)
11176 @itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...)
11177 @itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...)
11178 @itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...)
11179 @itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...)
11180 @itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...)
11181 @findex __sync_fetch_and_add
11182 @findex __sync_fetch_and_sub
11183 @findex __sync_fetch_and_or
11184 @findex __sync_fetch_and_and
11185 @findex __sync_fetch_and_xor
11186 @findex __sync_fetch_and_nand
11187 These built-in functions perform the operation suggested by the name, and
11188 returns the value that had previously been in memory. That is, operations
11189 on integer operands have the following semantics. Operations on pointer
11190 arguments are performed as if the operands were of the @code{uintptr_t}
11191 type. That is, they are not scaled by the size of the type to which
11192 the pointer points.
11195 @{ tmp = *ptr; *ptr @var{op}= value; return tmp; @}
11196 @{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand
11199 The object pointed to by the first argument must be of integer or pointer
11200 type. It must not be a boolean type.
11202 @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand}
11203 as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}.
11205 @item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...)
11206 @itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...)
11207 @itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...)
11208 @itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...)
11209 @itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...)
11210 @itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...)
11211 @findex __sync_add_and_fetch
11212 @findex __sync_sub_and_fetch
11213 @findex __sync_or_and_fetch
11214 @findex __sync_and_and_fetch
11215 @findex __sync_xor_and_fetch
11216 @findex __sync_nand_and_fetch
11217 These built-in functions perform the operation suggested by the name, and
11218 return the new value. That is, operations on integer operands have
11219 the following semantics. Operations on pointer operands are performed as
11220 if the operand's type were @code{uintptr_t}.
11223 @{ *ptr @var{op}= value; return *ptr; @}
11224 @{ *ptr = ~(*ptr & value); return *ptr; @} // nand
11227 The same constraints on arguments apply as for the corresponding
11228 @code{__sync_op_and_fetch} built-in functions.
11230 @emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch}
11231 as @code{*ptr = ~(*ptr & value)} instead of
11232 @code{*ptr = ~*ptr & value}.
11234 @item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
11235 @itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
11236 @findex __sync_bool_compare_and_swap
11237 @findex __sync_val_compare_and_swap
11238 These built-in functions perform an atomic compare and swap.
11239 That is, if the current
11240 value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into
11243 The ``bool'' version returns @code{true} if the comparison is successful and
11244 @var{newval} is written. The ``val'' version returns the contents
11245 of @code{*@var{ptr}} before the operation.
11247 @item __sync_synchronize (...)
11248 @findex __sync_synchronize
11249 This built-in function issues a full memory barrier.
11251 @item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...)
11252 @findex __sync_lock_test_and_set
11253 This built-in function, as described by Intel, is not a traditional test-and-set
11254 operation, but rather an atomic exchange operation. It writes @var{value}
11255 into @code{*@var{ptr}}, and returns the previous contents of
11258 Many targets have only minimal support for such locks, and do not support
11259 a full exchange operation. In this case, a target may support reduced
11260 functionality here by which the @emph{only} valid value to store is the
11261 immediate constant 1. The exact value actually stored in @code{*@var{ptr}}
11262 is implementation defined.
11264 This built-in function is not a full barrier,
11265 but rather an @dfn{acquire barrier}.
11266 This means that references after the operation cannot move to (or be
11267 speculated to) before the operation, but previous memory stores may not
11268 be globally visible yet, and previous memory loads may not yet be
11271 @item void __sync_lock_release (@var{type} *ptr, ...)
11272 @findex __sync_lock_release
11273 This built-in function releases the lock acquired by
11274 @code{__sync_lock_test_and_set}.
11275 Normally this means writing the constant 0 to @code{*@var{ptr}}.
11277 This built-in function is not a full barrier,
11278 but rather a @dfn{release barrier}.
11279 This means that all previous memory stores are globally visible, and all
11280 previous memory loads have been satisfied, but following memory reads
11281 are not prevented from being speculated to before the barrier.
11284 @node __atomic Builtins
11285 @section Built-in Functions for Memory Model Aware Atomic Operations
11287 The following built-in functions approximately match the requirements
11288 for the C++11 memory model. They are all
11289 identified by being prefixed with @samp{__atomic} and most are
11290 overloaded so that they work with multiple types.
11292 These functions are intended to replace the legacy @samp{__sync}
11293 builtins. The main difference is that the memory order that is requested
11294 is a parameter to the functions. New code should always use the
11295 @samp{__atomic} builtins rather than the @samp{__sync} builtins.
11297 Note that the @samp{__atomic} builtins assume that programs will
11298 conform to the C++11 memory model. In particular, they assume
11299 that programs are free of data races. See the C++11 standard for
11300 detailed requirements.
11302 The @samp{__atomic} builtins can be used with any integral scalar or
11303 pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral
11304 types are also allowed if @samp{__int128} (@pxref{__int128}) is
11305 supported by the architecture.
11307 The four non-arithmetic functions (load, store, exchange, and
11308 compare_exchange) all have a generic version as well. This generic
11309 version works on any data type. It uses the lock-free built-in function
11310 if the specific data type size makes that possible; otherwise, an
11311 external call is left to be resolved at run time. This external call is
11312 the same format with the addition of a @samp{size_t} parameter inserted
11313 as the first parameter indicating the size of the object being pointed to.
11314 All objects must be the same size.
11316 There are 6 different memory orders that can be specified. These map
11317 to the C++11 memory orders with the same names, see the C++11 standard
11318 or the @uref{http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki
11319 on atomic synchronization} for detailed definitions. Individual
11320 targets may also support additional memory orders for use on specific
11321 architectures. Refer to the target documentation for details of
11324 An atomic operation can both constrain code motion and
11325 be mapped to hardware instructions for synchronization between threads
11326 (e.g., a fence). To which extent this happens is controlled by the
11327 memory orders, which are listed here in approximately ascending order of
11328 strength. The description of each memory order is only meant to roughly
11329 illustrate the effects and is not a specification; see the C++11
11330 memory model for precise semantics.
11333 @item __ATOMIC_RELAXED
11334 Implies no inter-thread ordering constraints.
11335 @item __ATOMIC_CONSUME
11336 This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE}
11337 memory order because of a deficiency in C++11's semantics for
11338 @code{memory_order_consume}.
11339 @item __ATOMIC_ACQUIRE
11340 Creates an inter-thread happens-before constraint from the release (or
11341 stronger) semantic store to this acquire load. Can prevent hoisting
11342 of code to before the operation.
11343 @item __ATOMIC_RELEASE
11344 Creates an inter-thread happens-before constraint to acquire (or stronger)
11345 semantic loads that read from this release store. Can prevent sinking
11346 of code to after the operation.
11347 @item __ATOMIC_ACQ_REL
11348 Combines the effects of both @code{__ATOMIC_ACQUIRE} and
11349 @code{__ATOMIC_RELEASE}.
11350 @item __ATOMIC_SEQ_CST
11351 Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations.
11354 Note that in the C++11 memory model, @emph{fences} (e.g.,
11355 @samp{__atomic_thread_fence}) take effect in combination with other
11356 atomic operations on specific memory locations (e.g., atomic loads);
11357 operations on specific memory locations do not necessarily affect other
11358 operations in the same way.
11360 Target architectures are encouraged to provide their own patterns for
11361 each of the atomic built-in functions. If no target is provided, the original
11362 non-memory model set of @samp{__sync} atomic built-in functions are
11363 used, along with any required synchronization fences surrounding it in
11364 order to achieve the proper behavior. Execution in this case is subject
11365 to the same restrictions as those built-in functions.
11367 If there is no pattern or mechanism to provide a lock-free instruction
11368 sequence, a call is made to an external routine with the same parameters
11369 to be resolved at run time.
11371 When implementing patterns for these built-in functions, the memory order
11372 parameter can be ignored as long as the pattern implements the most
11373 restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory
11374 orders execute correctly with this memory order but they may not execute as
11375 efficiently as they could with a more appropriate implementation of the
11376 relaxed requirements.
11378 Note that the C++11 standard allows for the memory order parameter to be
11379 determined at run time rather than at compile time. These built-in
11380 functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather
11381 than invoke a runtime library call or inline a switch statement. This is
11382 standard compliant, safe, and the simplest approach for now.
11384 The memory order parameter is a signed int, but only the lower 16 bits are
11385 reserved for the memory order. The remainder of the signed int is reserved
11386 for target use and should be 0. Use of the predefined atomic values
11387 ensures proper usage.
11389 @deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memorder)
11390 This built-in function implements an atomic load operation. It returns the
11391 contents of @code{*@var{ptr}}.
11393 The valid memory order variants are
11394 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
11395 and @code{__ATOMIC_CONSUME}.
11399 @deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder)
11400 This is the generic version of an atomic load. It returns the
11401 contents of @code{*@var{ptr}} in @code{*@var{ret}}.
11405 @deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder)
11406 This built-in function implements an atomic store operation. It writes
11407 @code{@var{val}} into @code{*@var{ptr}}.
11409 The valid memory order variants are
11410 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}.
11414 @deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder)
11415 This is the generic version of an atomic store. It stores the value
11416 of @code{*@var{val}} into @code{*@var{ptr}}.
11420 @deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder)
11421 This built-in function implements an atomic exchange operation. It writes
11422 @var{val} into @code{*@var{ptr}}, and returns the previous contents of
11425 The valid memory order variants are
11426 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
11427 @code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}.
11431 @deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder)
11432 This is the generic version of an atomic exchange. It stores the
11433 contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value
11434 of @code{*@var{ptr}} is copied into @code{*@var{ret}}.
11438 @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)
11439 This built-in function implements an atomic compare and exchange operation.
11440 This compares the contents of @code{*@var{ptr}} with the contents of
11441 @code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write}
11442 operation that writes @var{desired} into @code{*@var{ptr}}. If they are not
11443 equal, the operation is a @emph{read} and the current contents of
11444 @code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true}
11445 for weak compare_exchange, which may fail spuriously, and @code{false} for
11446 the strong variation, which never fails spuriously. Many targets
11447 only offer the strong variation and ignore the parameter. When in doubt, use
11448 the strong variation.
11450 If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned
11451 and memory is affected according to the
11452 memory order specified by @var{success_memorder}. There are no
11453 restrictions on what memory order can be used here.
11455 Otherwise, @code{false} is returned and memory is affected according
11456 to @var{failure_memorder}. This memory order cannot be
11457 @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a
11458 stronger order than that specified by @var{success_memorder}.
11462 @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)
11463 This built-in function implements the generic version of
11464 @code{__atomic_compare_exchange}. The function is virtually identical to
11465 @code{__atomic_compare_exchange_n}, except the desired value is also a
11470 @deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder)
11471 @deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder)
11472 @deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder)
11473 @deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder)
11474 @deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder)
11475 @deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder)
11476 These built-in functions perform the operation suggested by the name, and
11477 return the result of the operation. Operations on pointer arguments are
11478 performed as if the operands were of the @code{uintptr_t} type. That is,
11479 they are not scaled by the size of the type to which the pointer points.
11482 @{ *ptr @var{op}= val; return *ptr; @}
11483 @{ *ptr = ~(*ptr & val); return *ptr; @} // nand
11486 The object pointed to by the first argument must be of integer or pointer
11487 type. It must not be a boolean type. All memory orders are valid.
11491 @deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder)
11492 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder)
11493 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder)
11494 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder)
11495 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder)
11496 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder)
11497 These built-in functions perform the operation suggested by the name, and
11498 return the value that had previously been in @code{*@var{ptr}}. Operations
11499 on pointer arguments are performed as if the operands were of
11500 the @code{uintptr_t} type. That is, they are not scaled by the size of
11501 the type to which the pointer points.
11504 @{ tmp = *ptr; *ptr @var{op}= val; return tmp; @}
11505 @{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand
11508 The same constraints on arguments apply as for the corresponding
11509 @code{__atomic_op_fetch} built-in functions. All memory orders are valid.
11513 @deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memorder)
11515 This built-in function performs an atomic test-and-set operation on
11516 the byte at @code{*@var{ptr}}. The byte is set to some implementation
11517 defined nonzero ``set'' value and the return value is @code{true} if and only
11518 if the previous contents were ``set''.
11519 It should be only used for operands of type @code{bool} or @code{char}. For
11520 other types only part of the value may be set.
11522 All memory orders are valid.
11526 @deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memorder)
11528 This built-in function performs an atomic clear operation on
11529 @code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0.
11530 It should be only used for operands of type @code{bool} or @code{char} and
11531 in conjunction with @code{__atomic_test_and_set}.
11532 For other types it may only clear partially. If the type is not @code{bool}
11533 prefer using @code{__atomic_store}.
11535 The valid memory order variants are
11536 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and
11537 @code{__ATOMIC_RELEASE}.
11541 @deftypefn {Built-in Function} void __atomic_thread_fence (int memorder)
11543 This built-in function acts as a synchronization fence between threads
11544 based on the specified memory order.
11546 All memory orders are valid.
11550 @deftypefn {Built-in Function} void __atomic_signal_fence (int memorder)
11552 This built-in function acts as a synchronization fence between a thread
11553 and signal handlers based in the same thread.
11555 All memory orders are valid.
11559 @deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr)
11561 This built-in function returns @code{true} if objects of @var{size} bytes always
11562 generate lock-free atomic instructions for the target architecture.
11563 @var{size} must resolve to a compile-time constant and the result also
11564 resolves to a compile-time constant.
11566 @var{ptr} is an optional pointer to the object that may be used to determine
11567 alignment. A value of 0 indicates typical alignment should be used. The
11568 compiler may also ignore this parameter.
11571 if (__atomic_always_lock_free (sizeof (long long), 0))
11576 @deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr)
11578 This built-in function returns @code{true} if objects of @var{size} bytes always
11579 generate lock-free atomic instructions for the target architecture. If
11580 the built-in function is not known to be lock-free, a call is made to a
11581 runtime routine named @code{__atomic_is_lock_free}.
11583 @var{ptr} is an optional pointer to the object that may be used to determine
11584 alignment. A value of 0 indicates typical alignment should be used. The
11585 compiler may also ignore this parameter.
11588 @node Integer Overflow Builtins
11589 @section Built-in Functions to Perform Arithmetic with Overflow Checking
11591 The following built-in functions allow performing simple arithmetic operations
11592 together with checking whether the operations overflowed.
11594 @deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
11595 @deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res)
11596 @deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res)
11597 @deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res)
11598 @deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res)
11599 @deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
11600 @deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
11602 These built-in functions promote the first two operands into infinite precision signed
11603 type and perform addition on those promoted operands. The result is then
11604 cast to the type the third pointer argument points to and stored there.
11605 If the stored result is equal to the infinite precision result, the built-in
11606 functions return @code{false}, otherwise they return @code{true}. As the addition is
11607 performed in infinite signed precision, these built-in functions have fully defined
11608 behavior for all argument values.
11610 The first built-in function allows arbitrary integral types for operands and
11611 the result type must be pointer to some integral type other than enumerated or
11612 boolean type, the rest of the built-in functions have explicit integer types.
11614 The compiler will attempt to use hardware instructions to implement
11615 these built-in functions where possible, like conditional jump on overflow
11616 after addition, conditional jump on carry etc.
11620 @deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
11621 @deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res)
11622 @deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res)
11623 @deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res)
11624 @deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res)
11625 @deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
11626 @deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
11628 These built-in functions are similar to the add overflow checking built-in
11629 functions above, except they perform subtraction, subtract the second argument
11630 from the first one, instead of addition.
11634 @deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
11635 @deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res)
11636 @deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res)
11637 @deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res)
11638 @deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res)
11639 @deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
11640 @deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res)
11642 These built-in functions are similar to the add overflow checking built-in
11643 functions above, except they perform multiplication, instead of addition.
11647 The following built-in functions allow checking if simple arithmetic operation
11650 @deftypefn {Built-in Function} bool __builtin_add_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
11651 @deftypefnx {Built-in Function} bool __builtin_sub_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
11652 @deftypefnx {Built-in Function} bool __builtin_mul_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c)
11654 These built-in functions are similar to @code{__builtin_add_overflow},
11655 @code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that
11656 they don't store the result of the arithmetic operation anywhere and the
11657 last argument is not a pointer, but some expression with integral type other
11658 than enumerated or boolean type.
11660 The built-in functions promote the first two operands into infinite precision signed type
11661 and perform addition on those promoted operands. The result is then
11662 cast to the type of the third argument. If the cast result is equal to the infinite
11663 precision result, the built-in functions return @code{false}, otherwise they return @code{true}.
11664 The value of the third argument is ignored, just the side effects in the third argument
11665 are evaluated, and no integral argument promotions are performed on the last argument.
11666 If the third argument is a bit-field, the type used for the result cast has the
11667 precision and signedness of the given bit-field, rather than precision and signedness
11668 of the underlying type.
11670 For example, the following macro can be used to portably check, at
11671 compile-time, whether or not adding two constant integers will overflow,
11672 and perform the addition only when it is known to be safe and not to trigger
11673 a @option{-Woverflow} warning.
11676 #define INT_ADD_OVERFLOW_P(a, b) \
11677 __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0)
11680 A = INT_MAX, B = 3,
11681 C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B,
11682 D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0)
11686 The compiler will attempt to use hardware instructions to implement
11687 these built-in functions where possible, like conditional jump on overflow
11688 after addition, conditional jump on carry etc.
11692 @node x86 specific memory model extensions for transactional memory
11693 @section x86-Specific Memory Model Extensions for Transactional Memory
11695 The x86 architecture supports additional memory ordering flags
11696 to mark critical sections for hardware lock elision.
11697 These must be specified in addition to an existing memory order to
11701 @item __ATOMIC_HLE_ACQUIRE
11702 Start lock elision on a lock variable.
11703 Memory order must be @code{__ATOMIC_ACQUIRE} or stronger.
11704 @item __ATOMIC_HLE_RELEASE
11705 End lock elision on a lock variable.
11706 Memory order must be @code{__ATOMIC_RELEASE} or stronger.
11709 When a lock acquire fails, it is required for good performance to abort
11710 the transaction quickly. This can be done with a @code{_mm_pause}.
11713 #include <immintrin.h> // For _mm_pause
11717 /* Acquire lock with lock elision */
11718 while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE))
11719 _mm_pause(); /* Abort failed transaction */
11721 /* Free lock with lock elision */
11722 __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE);
11725 @node Object Size Checking
11726 @section Object Size Checking Built-in Functions
11727 @findex __builtin_object_size
11728 @findex __builtin___memcpy_chk
11729 @findex __builtin___mempcpy_chk
11730 @findex __builtin___memmove_chk
11731 @findex __builtin___memset_chk
11732 @findex __builtin___strcpy_chk
11733 @findex __builtin___stpcpy_chk
11734 @findex __builtin___strncpy_chk
11735 @findex __builtin___strcat_chk
11736 @findex __builtin___strncat_chk
11737 @findex __builtin___sprintf_chk
11738 @findex __builtin___snprintf_chk
11739 @findex __builtin___vsprintf_chk
11740 @findex __builtin___vsnprintf_chk
11741 @findex __builtin___printf_chk
11742 @findex __builtin___vprintf_chk
11743 @findex __builtin___fprintf_chk
11744 @findex __builtin___vfprintf_chk
11746 GCC implements a limited buffer overflow protection mechanism that can
11747 prevent some buffer overflow attacks by determining the sizes of objects
11748 into which data is about to be written and preventing the writes when
11749 the size isn't sufficient. The built-in functions described below yield
11750 the best results when used together and when optimization is enabled.
11751 For example, to detect object sizes across function boundaries or to
11752 follow pointer assignments through non-trivial control flow they rely
11753 on various optimization passes enabled with @option{-O2}. However, to
11754 a limited extent, they can be used without optimization as well.
11756 @deftypefn {Built-in Function} {size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
11757 is a built-in construct that returns a constant number of bytes from
11758 @var{ptr} to the end of the object @var{ptr} pointer points to
11759 (if known at compile time). To determine the sizes of dynamically allocated
11760 objects the function relies on the allocation functions called to obtain
11761 the storage to be declared with the @code{alloc_size} attribute (@xref{Common
11762 Function Attributes}). @code{__builtin_object_size} never evaluates
11763 its arguments for side effects. If there are any side effects in them, it
11764 returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
11765 for @var{type} 2 or 3. If there are multiple objects @var{ptr} can
11766 point to and all of them are known at compile time, the returned number
11767 is the maximum of remaining byte counts in those objects if @var{type} & 2 is
11768 0 and minimum if nonzero. If it is not possible to determine which objects
11769 @var{ptr} points to at compile time, @code{__builtin_object_size} should
11770 return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
11771 for @var{type} 2 or 3.
11773 @var{type} is an integer constant from 0 to 3. If the least significant
11774 bit is clear, objects are whole variables, if it is set, a closest
11775 surrounding subobject is considered the object a pointer points to.
11776 The second bit determines if maximum or minimum of remaining bytes
11780 struct V @{ char buf1[10]; int b; char buf2[10]; @} var;
11781 char *p = &var.buf1[1], *q = &var.b;
11783 /* Here the object p points to is var. */
11784 assert (__builtin_object_size (p, 0) == sizeof (var) - 1);
11785 /* The subobject p points to is var.buf1. */
11786 assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1);
11787 /* The object q points to is var. */
11788 assert (__builtin_object_size (q, 0)
11789 == (char *) (&var + 1) - (char *) &var.b);
11790 /* The subobject q points to is var.b. */
11791 assert (__builtin_object_size (q, 1) == sizeof (var.b));
11795 There are built-in functions added for many common string operation
11796 functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk}
11797 built-in is provided. This built-in has an additional last argument,
11798 which is the number of bytes remaining in the object the @var{dest}
11799 argument points to or @code{(size_t) -1} if the size is not known.
11801 The built-in functions are optimized into the normal string functions
11802 like @code{memcpy} if the last argument is @code{(size_t) -1} or if
11803 it is known at compile time that the destination object will not
11804 be overflowed. If the compiler can determine at compile time that the
11805 object will always be overflowed, it issues a warning.
11807 The intended use can be e.g.@:
11811 #define bos0(dest) __builtin_object_size (dest, 0)
11812 #define memcpy(dest, src, n) \
11813 __builtin___memcpy_chk (dest, src, n, bos0 (dest))
11817 /* It is unknown what object p points to, so this is optimized
11818 into plain memcpy - no checking is possible. */
11819 memcpy (p, "abcde", n);
11820 /* Destination is known and length too. It is known at compile
11821 time there will be no overflow. */
11822 memcpy (&buf[5], "abcde", 5);
11823 /* Destination is known, but the length is not known at compile time.
11824 This will result in __memcpy_chk call that can check for overflow
11826 memcpy (&buf[5], "abcde", n);
11827 /* Destination is known and it is known at compile time there will
11828 be overflow. There will be a warning and __memcpy_chk call that
11829 will abort the program at run time. */
11830 memcpy (&buf[6], "abcde", 5);
11833 Such built-in functions are provided for @code{memcpy}, @code{mempcpy},
11834 @code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy},
11835 @code{strcat} and @code{strncat}.
11837 There are also checking built-in functions for formatted output functions.
11839 int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...);
11840 int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os,
11841 const char *fmt, ...);
11842 int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt,
11844 int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os,
11845 const char *fmt, va_list ap);
11848 The added @var{flag} argument is passed unchanged to @code{__sprintf_chk}
11849 etc.@: functions and can contain implementation specific flags on what
11850 additional security measures the checking function might take, such as
11851 handling @code{%n} differently.
11853 The @var{os} argument is the object size @var{s} points to, like in the
11854 other built-in functions. There is a small difference in the behavior
11855 though, if @var{os} is @code{(size_t) -1}, the built-in functions are
11856 optimized into the non-checking functions only if @var{flag} is 0, otherwise
11857 the checking function is called with @var{os} argument set to
11858 @code{(size_t) -1}.
11860 In addition to this, there are checking built-in functions
11861 @code{__builtin___printf_chk}, @code{__builtin___vprintf_chk},
11862 @code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}.
11863 These have just one additional argument, @var{flag}, right before
11864 format string @var{fmt}. If the compiler is able to optimize them to
11865 @code{fputc} etc.@: functions, it does, otherwise the checking function
11866 is called and the @var{flag} argument passed to it.
11868 @node Other Builtins
11869 @section Other Built-in Functions Provided by GCC
11870 @cindex built-in functions
11871 @findex __builtin_alloca
11872 @findex __builtin_alloca_with_align
11873 @findex __builtin_alloca_with_align_and_max
11874 @findex __builtin_call_with_static_chain
11875 @findex __builtin_extend_pointer
11876 @findex __builtin_fpclassify
11877 @findex __builtin_has_attribute
11878 @findex __builtin_isfinite
11879 @findex __builtin_isnormal
11880 @findex __builtin_isgreater
11881 @findex __builtin_isgreaterequal
11882 @findex __builtin_isinf_sign
11883 @findex __builtin_isless
11884 @findex __builtin_islessequal
11885 @findex __builtin_islessgreater
11886 @findex __builtin_isunordered
11887 @findex __builtin_object_size
11888 @findex __builtin_powi
11889 @findex __builtin_powif
11890 @findex __builtin_powil
11891 @findex __builtin_speculation_safe_value
12052 @findex fprintf_unlocked
12054 @findex fputs_unlocked
12162 @findex nexttowardf
12163 @findex nexttowardl
12171 @findex printf_unlocked
12201 @findex signbitd128
12202 @findex significand
12203 @findex significandf
12204 @findex significandl
12232 @findex strncasecmp
12276 GCC provides a large number of built-in functions other than the ones
12277 mentioned above. Some of these are for internal use in the processing
12278 of exceptions or variable-length argument lists and are not
12279 documented here because they may change from time to time; we do not
12280 recommend general use of these functions.
12282 The remaining functions are provided for optimization purposes.
12284 With the exception of built-ins that have library equivalents such as
12285 the standard C library functions discussed below, or that expand to
12286 library calls, GCC built-in functions are always expanded inline and
12287 thus do not have corresponding entry points and their address cannot
12288 be obtained. Attempting to use them in an expression other than
12289 a function call results in a compile-time error.
12291 @opindex fno-builtin
12292 GCC includes built-in versions of many of the functions in the standard
12293 C library. These functions come in two forms: one whose names start with
12294 the @code{__builtin_} prefix, and the other without. Both forms have the
12295 same type (including prototype), the same address (when their address is
12296 taken), and the same meaning as the C library functions even if you specify
12297 the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these
12298 functions are only optimized in certain cases; if they are not optimized in
12299 a particular case, a call to the library function is emitted.
12303 Outside strict ISO C mode (@option{-ansi}, @option{-std=c90},
12304 @option{-std=c99} or @option{-std=c11}), the functions
12305 @code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero},
12306 @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml},
12307 @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll},
12308 @code{ffsl}, @code{ffs}, @code{fprintf_unlocked},
12309 @code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma},
12310 @code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext},
12311 @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0},
12312 @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn},
12313 @code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy},
12314 @code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked},
12315 @code{rindex}, @code{scalbf}, @code{scalbl}, @code{scalb},
12316 @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32},
12317 @code{signbitd64}, @code{signbitd128}, @code{significandf},
12318 @code{significandl}, @code{significand}, @code{sincosf},
12319 @code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy},
12320 @code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp},
12321 @code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l},
12322 @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and
12324 may be handled as built-in functions.
12325 All these functions have corresponding versions
12326 prefixed with @code{__builtin_}, which may be used even in strict C90
12329 The ISO C99 functions
12330 @code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf},
12331 @code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh},
12332 @code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf},
12333 @code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos},
12334 @code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf},
12335 @code{casinhl}, @code{casinh}, @code{casinl}, @code{casin},
12336 @code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh},
12337 @code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt},
12338 @code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl},
12339 @code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf},
12340 @code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog},
12341 @code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl},
12342 @code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf},
12343 @code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal},
12344 @code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl},
12345 @code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf},
12346 @code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan},
12347 @code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl},
12348 @code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f},
12349 @code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim},
12350 @code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax},
12351 @code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf},
12352 @code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb},
12353 @code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf},
12354 @code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl},
12355 @code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround},
12356 @code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l},
12357 @code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf},
12358 @code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl},
12359 @code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint},
12360 @code{nextafterf}, @code{nextafterl}, @code{nextafter},
12361 @code{nexttowardf}, @code{nexttowardl}, @code{nexttoward},
12362 @code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof},
12363 @code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint},
12364 @code{roundf}, @code{roundl}, @code{round}, @code{scalblnf},
12365 @code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl},
12366 @code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal},
12367 @code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc},
12368 @code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf}
12369 are handled as built-in functions
12370 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
12372 There are also built-in versions of the ISO C99 functions
12373 @code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f},
12374 @code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill},
12375 @code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf},
12376 @code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl},
12377 @code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf},
12378 @code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl},
12379 @code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf},
12380 @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl},
12381 @code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl}
12382 that are recognized in any mode since ISO C90 reserves these names for
12383 the purpose to which ISO C99 puts them. All these functions have
12384 corresponding versions prefixed with @code{__builtin_}.
12386 There are also built-in functions @code{__builtin_fabsf@var{n}},
12387 @code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and
12388 @code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3
12389 functions @code{fabsf@var{n}}, @code{fabsf@var{n}x},
12390 @code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported
12391 types @code{_Float@var{n}} and @code{_Float@var{n}x}.
12393 There are also GNU extension functions @code{clog10}, @code{clog10f} and
12394 @code{clog10l} which names are reserved by ISO C99 for future use.
12395 All these functions have versions prefixed with @code{__builtin_}.
12397 The ISO C94 functions
12398 @code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit},
12399 @code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct},
12400 @code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and
12402 are handled as built-in functions
12403 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
12405 The ISO C90 functions
12406 @code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2},
12407 @code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos},
12408 @code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod},
12409 @code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf},
12410 @code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit},
12411 @code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct},
12412 @code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower},
12413 @code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log},
12414 @code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy},
12415 @code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar},
12416 @code{puts}, @code{scanf}, @code{sinh}, @code{sin}, @code{snprintf},
12417 @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat},
12418 @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn},
12419 @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy},
12420 @code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr},
12421 @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf}
12422 are all recognized as built-in functions unless
12423 @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}}
12424 is specified for an individual function). All of these functions have
12425 corresponding versions prefixed with @code{__builtin_}.
12427 GCC provides built-in versions of the ISO C99 floating-point comparison
12428 macros that avoid raising exceptions for unordered operands. They have
12429 the same names as the standard macros ( @code{isgreater},
12430 @code{isgreaterequal}, @code{isless}, @code{islessequal},
12431 @code{islessgreater}, and @code{isunordered}) , with @code{__builtin_}
12432 prefixed. We intend for a library implementor to be able to simply
12433 @code{#define} each standard macro to its built-in equivalent.
12434 In the same fashion, GCC provides @code{fpclassify}, @code{isfinite},
12435 @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with
12436 @code{__builtin_} prefixed. The @code{isinf} and @code{isnan}
12437 built-in functions appear both with and without the @code{__builtin_} prefix.
12439 @deftypefn {Built-in Function} void *__builtin_alloca (size_t size)
12440 The @code{__builtin_alloca} function must be called at block scope.
12441 The function allocates an object @var{size} bytes large on the stack
12442 of the calling function. The object is aligned on the default stack
12443 alignment boundary for the target determined by the
12444 @code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca}
12445 function returns a pointer to the first byte of the allocated object.
12446 The lifetime of the allocated object ends just before the calling
12447 function returns to its caller. This is so even when
12448 @code{__builtin_alloca} is called within a nested block.
12450 For example, the following function allocates eight objects of @code{n}
12451 bytes each on the stack, storing a pointer to each in consecutive elements
12452 of the array @code{a}. It then passes the array to function @code{g}
12453 which can safely use the storage pointed to by each of the array elements.
12456 void f (unsigned n)
12459 for (int i = 0; i != 8; ++i)
12460 a [i] = __builtin_alloca (n);
12462 g (a, n); // @r{safe}
12466 Since the @code{__builtin_alloca} function doesn't validate its argument
12467 it is the responsibility of its caller to make sure the argument doesn't
12468 cause it to exceed the stack size limit.
12469 The @code{__builtin_alloca} function is provided to make it possible to
12470 allocate on the stack arrays of bytes with an upper bound that may be
12471 computed at run time. Since C99 Variable Length Arrays offer
12472 similar functionality under a portable, more convenient, and safer
12473 interface they are recommended instead, in both C99 and C++ programs
12474 where GCC provides them as an extension.
12475 @xref{Variable Length}, for details.
12479 @deftypefn {Built-in Function} void *__builtin_alloca_with_align (size_t size, size_t alignment)
12480 The @code{__builtin_alloca_with_align} function must be called at block
12481 scope. The function allocates an object @var{size} bytes large on
12482 the stack of the calling function. The allocated object is aligned on
12483 the boundary specified by the argument @var{alignment} whose unit is given
12484 in bits (not bytes). The @var{size} argument must be positive and not
12485 exceed the stack size limit. The @var{alignment} argument must be a constant
12486 integer expression that evaluates to a power of 2 greater than or equal to
12487 @code{CHAR_BIT} and less than some unspecified maximum. Invocations
12488 with other values are rejected with an error indicating the valid bounds.
12489 The function returns a pointer to the first byte of the allocated object.
12490 The lifetime of the allocated object ends at the end of the block in which
12491 the function was called. The allocated storage is released no later than
12492 just before the calling function returns to its caller, but may be released
12493 at the end of the block in which the function was called.
12495 For example, in the following function the call to @code{g} is unsafe
12496 because when @code{overalign} is non-zero, the space allocated by
12497 @code{__builtin_alloca_with_align} may have been released at the end
12498 of the @code{if} statement in which it was called.
12501 void f (unsigned n, bool overalign)
12505 p = __builtin_alloca_with_align (n, 64 /* bits */);
12507 p = __builtin_alloc (n);
12509 g (p, n); // @r{unsafe}
12513 Since the @code{__builtin_alloca_with_align} function doesn't validate its
12514 @var{size} argument it is the responsibility of its caller to make sure
12515 the argument doesn't cause it to exceed the stack size limit.
12516 The @code{__builtin_alloca_with_align} function is provided to make
12517 it possible to allocate on the stack overaligned arrays of bytes with
12518 an upper bound that may be computed at run time. Since C99
12519 Variable Length Arrays offer the same functionality under
12520 a portable, more convenient, and safer interface they are recommended
12521 instead, in both C99 and C++ programs where GCC provides them as
12522 an extension. @xref{Variable Length}, for details.
12526 @deftypefn {Built-in Function} void *__builtin_alloca_with_align_and_max (size_t size, size_t alignment, size_t max_size)
12527 Similar to @code{__builtin_alloca_with_align} but takes an extra argument
12528 specifying an upper bound for @var{size} in case its value cannot be computed
12529 at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage}
12530 and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer
12531 expression, it has no effect on code generation and no attempt is made to
12532 check its compatibility with @var{size}.
12536 @deftypefn {Built-in Function} bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})
12537 The @code{__builtin_has_attribute} function evaluates to an integer constant
12538 expression equal to @code{true} if the symbol or type referenced by
12539 the @var{type-or-expression} argument has been declared with
12540 the @var{attribute} referenced by the second argument. Neither argument
12541 is evaluated. The @var{type-or-expression} argument is subject to the same
12542 restrictions as the argument to @code{typeof} (@pxref{Typeof}). The
12543 @var{attribute} argument is an attribute name optionally followed by
12544 a comma-separated list of arguments enclosed in parentheses. Both forms
12545 of attribute names---with and without double leading and trailing
12546 underscores---are recognized. @xref{Attribute Syntax} for details.
12547 When no attribute arguments are specified for an attribute that expects
12548 one or more arguments the function returns @code{true} if
12549 @var{type-or-expression} has been declared with the attribute regardless
12550 of the attribute argument values. Arguments provided for an attribute
12551 that expects some are validated and matched up to the provided number.
12552 The function returns @code{true} if all provided arguments match. For
12553 example, the first call to the function below evaluates to @code{true}
12554 because @code{x} is declared with the @code{aligned} attribute but
12555 the second call evaluates to @code{false} because @code{x} is declared
12556 @code{aligned (8)} and not @code{aligned (4)}.
12559 __attribute__ ((aligned (8))) int x;
12560 _Static_assert (__builtin_has_attribute (x, aligned), "aligned");
12561 _Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)");
12564 Due to a limitation the @code{__builtin_has_attribute} function returns
12565 @code{false} for the @code{mode} attribute even if the type or variable
12566 referenced by the @var{type-or-expression} argument was declared with one.
12567 The function is also not supported with labels, and in C with enumerators.
12569 Note that unlike the @code{__has_attribute} preprocessor operator which
12570 is suitable for use in @code{#if} preprocessing directives
12571 @code{__builtin_has_attribute} is an intrinsic function that is not
12572 recognized in such contexts.
12576 @deftypefn {Built-in Function} @var{type} __builtin_speculation_safe_value (@var{type} val, @var{type} failval)
12578 This built-in function can be used to help mitigate against unsafe
12579 speculative execution. @var{type} may be any integral type or any
12584 If the CPU is not speculatively executing the code, then @var{val}
12587 If the CPU is executing speculatively then either:
12590 The function may cause execution to pause until it is known that the
12591 code is no-longer being executed speculatively (in which case
12592 @var{val} can be returned, as above); or
12594 The function may use target-dependent speculation tracking state to cause
12595 @var{failval} to be returned when it is known that speculative
12596 execution has incorrectly predicted a conditional branch operation.
12600 The second argument, @var{failval}, is optional and defaults to zero
12603 GCC defines the preprocessor macro
12604 @code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been
12605 updated to support this builtin.
12607 The built-in function can be used where a variable appears to be used in a
12608 safe way, but the CPU, due to speculative execution may temporarily ignore
12609 the bounds checks. Consider, for example, the following function:
12613 int f (unsigned untrusted_index)
12615 if (untrusted_index < 500)
12616 return array[untrusted_index];
12621 If the function is called repeatedly with @code{untrusted_index} less
12622 than the limit of 500, then a branch predictor will learn that the
12623 block of code that returns a value stored in @code{array} will be
12624 executed. If the function is subsequently called with an
12625 out-of-range value it will still try to execute that block of code
12626 first until the CPU determines that the prediction was incorrect
12627 (the CPU will unwind any incorrect operations at that point).
12628 However, depending on how the result of the function is used, it might be
12629 possible to leave traces in the cache that can reveal what was stored
12630 at the out-of-bounds location. The built-in function can be used to
12631 provide some protection against leaking data in this way by changing
12636 int f (unsigned untrusted_index)
12638 if (untrusted_index < 500)
12639 return array[__builtin_speculation_safe_value (untrusted_index)];
12644 The built-in function will either cause execution to stall until the
12645 conditional branch has been fully resolved, or it may permit
12646 speculative execution to continue, but using 0 instead of
12647 @code{untrusted_value} if that exceeds the limit.
12649 If accessing any memory location is potentially unsafe when speculative
12650 execution is incorrect, then the code can be rewritten as
12654 int f (unsigned untrusted_index)
12656 if (untrusted_index < 500)
12657 return *__builtin_speculation_safe_value (&array[untrusted_index], NULL);
12662 which will cause a @code{NULL} pointer to be used for the unsafe case.
12666 @deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2})
12668 You can use the built-in function @code{__builtin_types_compatible_p} to
12669 determine whether two types are the same.
12671 This built-in function returns 1 if the unqualified versions of the
12672 types @var{type1} and @var{type2} (which are types, not expressions) are
12673 compatible, 0 otherwise. The result of this built-in function can be
12674 used in integer constant expressions.
12676 This built-in function ignores top level qualifiers (e.g., @code{const},
12677 @code{volatile}). For example, @code{int} is equivalent to @code{const
12680 The type @code{int[]} and @code{int[5]} are compatible. On the other
12681 hand, @code{int} and @code{char *} are not compatible, even if the size
12682 of their types, on the particular architecture are the same. Also, the
12683 amount of pointer indirection is taken into account when determining
12684 similarity. Consequently, @code{short *} is not similar to
12685 @code{short **}. Furthermore, two types that are typedefed are
12686 considered compatible if their underlying types are compatible.
12688 An @code{enum} type is not considered to be compatible with another
12689 @code{enum} type even if both are compatible with the same integer
12690 type; this is what the C standard specifies.
12691 For example, @code{enum @{foo, bar@}} is not similar to
12692 @code{enum @{hot, dog@}}.
12694 You typically use this function in code whose execution varies
12695 depending on the arguments' types. For example:
12700 typeof (x) tmp = (x); \
12701 if (__builtin_types_compatible_p (typeof (x), long double)) \
12702 tmp = foo_long_double (tmp); \
12703 else if (__builtin_types_compatible_p (typeof (x), double)) \
12704 tmp = foo_double (tmp); \
12705 else if (__builtin_types_compatible_p (typeof (x), float)) \
12706 tmp = foo_float (tmp); \
12713 @emph{Note:} This construct is only available for C@.
12717 @deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})
12719 The @var{call_exp} expression must be a function call, and the
12720 @var{pointer_exp} expression must be a pointer. The @var{pointer_exp}
12721 is passed to the function call in the target's static chain location.
12722 The result of builtin is the result of the function call.
12724 @emph{Note:} This builtin is only available for C@.
12725 This builtin can be used to call Go closures from C.
12729 @deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})
12731 You can use the built-in function @code{__builtin_choose_expr} to
12732 evaluate code depending on the value of a constant expression. This
12733 built-in function returns @var{exp1} if @var{const_exp}, which is an
12734 integer constant expression, is nonzero. Otherwise it returns @var{exp2}.
12736 This built-in function is analogous to the @samp{? :} operator in C,
12737 except that the expression returned has its type unaltered by promotion
12738 rules. Also, the built-in function does not evaluate the expression
12739 that is not chosen. For example, if @var{const_exp} evaluates to @code{true},
12740 @var{exp2} is not evaluated even if it has side effects.
12742 This built-in function can return an lvalue if the chosen argument is an
12745 If @var{exp1} is returned, the return type is the same as @var{exp1}'s
12746 type. Similarly, if @var{exp2} is returned, its return type is the same
12753 __builtin_choose_expr ( \
12754 __builtin_types_compatible_p (typeof (x), double), \
12756 __builtin_choose_expr ( \
12757 __builtin_types_compatible_p (typeof (x), float), \
12759 /* @r{The void expression results in a compile-time error} \
12760 @r{when assigning the result to something.} */ \
12764 @emph{Note:} This construct is only available for C@. Furthermore, the
12765 unused expression (@var{exp1} or @var{exp2} depending on the value of
12766 @var{const_exp}) may still generate syntax errors. This may change in
12771 @deftypefn {Built-in Function} @var{type} __builtin_tgmath (@var{functions}, @var{arguments})
12773 The built-in function @code{__builtin_tgmath}, available only for C
12774 and Objective-C, calls a function determined according to the rules of
12775 @code{<tgmath.h>} macros. It is intended to be used in
12776 implementations of that header, so that expansions of macros from that
12777 header only expand each of their arguments once, to avoid problems
12778 when calls to such macros are nested inside the arguments of other
12779 calls to such macros; in addition, it results in better diagnostics
12780 for invalid calls to @code{<tgmath.h>} macros than implementations
12781 using other GNU C language features. For example, the @code{pow}
12782 type-generic macro might be defined as:
12785 #define pow(a, b) __builtin_tgmath (powf, pow, powl, \
12786 cpowf, cpow, cpowl, a, b)
12789 The arguments to @code{__builtin_tgmath} are at least two pointers to
12790 functions, followed by the arguments to the type-generic macro (which
12791 will be passed as arguments to the selected function). All the
12792 pointers to functions must be pointers to prototyped functions, none
12793 of which may have variable arguments, and all of which must have the
12794 same number of parameters; the number of parameters of the first
12795 function determines how many arguments to @code{__builtin_tgmath} are
12796 interpreted as function pointers, and how many as the arguments to the
12799 The types of the specified functions must all be different, but
12800 related to each other in the same way as a set of functions that may
12801 be selected between by a macro in @code{<tgmath.h>}. This means that
12802 the functions are parameterized by a floating-point type @var{t},
12803 different for each such function. The function return types may all
12804 be the same type, or they may be @var{t} for each function, or they
12805 may be the real type corresponding to @var{t} for each function (if
12806 some of the types @var{t} are complex). Likewise, for each parameter
12807 position, the type of the parameter in that position may always be the
12808 same type, or may be @var{t} for each function (this case must apply
12809 for at least one parameter position), or may be the real type
12810 corresponding to @var{t} for each function.
12812 The standard rules for @code{<tgmath.h>} macros are used to find a
12813 common type @var{u} from the types of the arguments for parameters
12814 whose types vary between the functions; complex integer types (a GNU
12815 extension) are treated like @code{_Complex double} for this purpose
12816 (or @code{_Complex _Float64} if all the function return types are the
12817 same @code{_Float@var{n}} or @code{_Float@var{n}x} type).
12818 If the function return types vary, or are all the same integer type,
12819 the function called is the one for which @var{t} is @var{u}, and it is
12820 an error if there is no such function. If the function return types
12821 are all the same floating-point type, the type-generic macro is taken
12822 to be one of those from TS 18661 that rounds the result to a narrower
12823 type; if there is a function for which @var{t} is @var{u}, it is
12824 called, and otherwise the first function, if any, for which @var{t}
12825 has at least the range and precision of @var{u} is called, and it is
12826 an error if there is no such function.
12830 @deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag})
12832 The built-in function @code{__builtin_complex} is provided for use in
12833 implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
12834 @code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
12835 real binary floating-point type, and the result has the corresponding
12836 complex type with real and imaginary parts @var{real} and @var{imag}.
12837 Unlike @samp{@var{real} + I * @var{imag}}, this works even when
12838 infinities, NaNs and negative zeros are involved.
12842 @deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
12843 You can use the built-in function @code{__builtin_constant_p} to
12844 determine if a value is known to be constant at compile time and hence
12845 that GCC can perform constant-folding on expressions involving that
12846 value. The argument of the function is the value to test. The function
12847 returns the integer 1 if the argument is known to be a compile-time
12848 constant and 0 if it is not known to be a compile-time constant. A
12849 return of 0 does not indicate that the value is @emph{not} a constant,
12850 but merely that GCC cannot prove it is a constant with the specified
12851 value of the @option{-O} option.
12853 You typically use this function in an embedded application where
12854 memory is a critical resource. If you have some complex calculation,
12855 you may want it to be folded if it involves constants, but need to call
12856 a function if it does not. For example:
12859 #define Scale_Value(X) \
12860 (__builtin_constant_p (X) \
12861 ? ((X) * SCALE + OFFSET) : Scale (X))
12864 You may use this built-in function in either a macro or an inline
12865 function. However, if you use it in an inlined function and pass an
12866 argument of the function as the argument to the built-in, GCC
12867 never returns 1 when you call the inline function with a string constant
12868 or compound literal (@pxref{Compound Literals}) and does not return 1
12869 when you pass a constant numeric value to the inline function unless you
12870 specify the @option{-O} option.
12872 You may also use @code{__builtin_constant_p} in initializers for static
12873 data. For instance, you can write
12876 static const int table[] = @{
12877 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
12883 This is an acceptable initializer even if @var{EXPRESSION} is not a
12884 constant expression, including the case where
12885 @code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be
12886 folded to a constant but @var{EXPRESSION} contains operands that are
12887 not otherwise permitted in a static initializer (for example,
12888 @code{0 && foo ()}). GCC must be more conservative about evaluating the
12889 built-in in this case, because it has no opportunity to perform
12893 @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
12894 @opindex fprofile-arcs
12895 You may use @code{__builtin_expect} to provide the compiler with
12896 branch prediction information. In general, you should prefer to
12897 use actual profile feedback for this (@option{-fprofile-arcs}), as
12898 programmers are notoriously bad at predicting how their programs
12899 actually perform. However, there are applications in which this
12900 data is hard to collect.
12902 The return value is the value of @var{exp}, which should be an integral
12903 expression. The semantics of the built-in are that it is expected that
12904 @var{exp} == @var{c}. For example:
12907 if (__builtin_expect (x, 0))
12912 indicates that we do not expect to call @code{foo}, since
12913 we expect @code{x} to be zero. Since you are limited to integral
12914 expressions for @var{exp}, you should use constructions such as
12917 if (__builtin_expect (ptr != NULL, 1))
12922 when testing pointer or floating-point values.
12924 For the purposes of branch prediction optimizations, the probability that
12925 a @code{__builtin_expect} expression is @code{true} is controlled by GCC's
12926 @code{builtin-expect-probability} parameter, which defaults to 90%.
12927 You can also use @code{__builtin_expect_with_probability} to explicitly
12928 assign a probability value to individual expressions.
12931 @deftypefn {Built-in Function} long __builtin_expect_with_probability
12932 (long @var{exp}, long @var{c}, double @var{probability})
12934 This function has the same semantics as @code{__builtin_expect},
12935 but the caller provides the expected probability that @var{exp} == @var{c}.
12936 The last argument, @var{probability}, is a floating-point value in the
12937 range 0.0 to 1.0, inclusive. The @var{probability} argument must be
12938 constant floating-point expression.
12941 @deftypefn {Built-in Function} void __builtin_trap (void)
12942 This function causes the program to exit abnormally. GCC implements
12943 this function by using a target-dependent mechanism (such as
12944 intentionally executing an illegal instruction) or by calling
12945 @code{abort}. The mechanism used may vary from release to release so
12946 you should not rely on any particular implementation.
12949 @deftypefn {Built-in Function} void __builtin_unreachable (void)
12950 If control flow reaches the point of the @code{__builtin_unreachable},
12951 the program is undefined. It is useful in situations where the
12952 compiler cannot deduce the unreachability of the code.
12954 One such case is immediately following an @code{asm} statement that
12955 either never terminates, or one that transfers control elsewhere
12956 and never returns. In this example, without the
12957 @code{__builtin_unreachable}, GCC issues a warning that control
12958 reaches the end of a non-void function. It also generates code
12959 to return after the @code{asm}.
12962 int f (int c, int v)
12970 asm("jmp error_handler");
12971 __builtin_unreachable ();
12977 Because the @code{asm} statement unconditionally transfers control out
12978 of the function, control never reaches the end of the function
12979 body. The @code{__builtin_unreachable} is in fact unreachable and
12980 communicates this fact to the compiler.
12982 Another use for @code{__builtin_unreachable} is following a call a
12983 function that never returns but that is not declared
12984 @code{__attribute__((noreturn))}, as in this example:
12987 void function_that_never_returns (void);
12997 function_that_never_returns ();
12998 __builtin_unreachable ();
13005 @deftypefn {Built-in Function} {void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)
13006 This function returns its first argument, and allows the compiler
13007 to assume that the returned pointer is at least @var{align} bytes
13008 aligned. This built-in can have either two or three arguments,
13009 if it has three, the third argument should have integer type, and
13010 if it is nonzero means misalignment offset. For example:
13013 void *x = __builtin_assume_aligned (arg, 16);
13017 means that the compiler can assume @code{x}, set to @code{arg}, is at least
13018 16-byte aligned, while:
13021 void *x = __builtin_assume_aligned (arg, 32, 8);
13025 means that the compiler can assume for @code{x}, set to @code{arg}, that
13026 @code{(char *) x - 8} is 32-byte aligned.
13029 @deftypefn {Built-in Function} int __builtin_LINE ()
13030 This function is the equivalent of the preprocessor @code{__LINE__}
13031 macro and returns a constant integer expression that evaluates to
13032 the line number of the invocation of the built-in. When used as a C++
13033 default argument for a function @var{F}, it returns the line number
13034 of the call to @var{F}.
13037 @deftypefn {Built-in Function} {const char *} __builtin_FUNCTION ()
13038 This function is the equivalent of the @code{__FUNCTION__} symbol
13039 and returns an address constant pointing to the name of the function
13040 from which the built-in was invoked, or the empty string if
13041 the invocation is not at function scope. When used as a C++ default
13042 argument for a function @var{F}, it returns the name of @var{F}'s
13043 caller or the empty string if the call was not made at function
13047 @deftypefn {Built-in Function} {const char *} __builtin_FILE ()
13048 This function is the equivalent of the preprocessor @code{__FILE__}
13049 macro and returns an address constant pointing to the file name
13050 containing the invocation of the built-in, or the empty string if
13051 the invocation is not at function scope. When used as a C++ default
13052 argument for a function @var{F}, it returns the file name of the call
13053 to @var{F} or the empty string if the call was not made at function
13056 For example, in the following, each call to function @code{foo} will
13057 print a line similar to @code{"file.c:123: foo: message"} with the name
13058 of the file and the line number of the @code{printf} call, the name of
13059 the function @code{foo}, followed by the word @code{message}.
13063 function (const char *func = __builtin_FUNCTION ())
13070 printf ("%s:%i: %s: message\n", file (), line (), function ());
13076 @deftypefn {Built-in Function} void __builtin___clear_cache (void *@var{begin}, void *@var{end})
13077 This function is used to flush the processor's instruction cache for
13078 the region of memory between @var{begin} inclusive and @var{end}
13079 exclusive. Some targets require that the instruction cache be
13080 flushed, after modifying memory containing code, in order to obtain
13081 deterministic behavior.
13083 If the target does not require instruction cache flushes,
13084 @code{__builtin___clear_cache} has no effect. Otherwise either
13085 instructions are emitted in-line to clear the instruction cache or a
13086 call to the @code{__clear_cache} function in libgcc is made.
13089 @deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...)
13090 This function is used to minimize cache-miss latency by moving data into
13091 a cache before it is accessed.
13092 You can insert calls to @code{__builtin_prefetch} into code for which
13093 you know addresses of data in memory that is likely to be accessed soon.
13094 If the target supports them, data prefetch instructions are generated.
13095 If the prefetch is done early enough before the access then the data will
13096 be in the cache by the time it is accessed.
13098 The value of @var{addr} is the address of the memory to prefetch.
13099 There are two optional arguments, @var{rw} and @var{locality}.
13100 The value of @var{rw} is a compile-time constant one or zero; one
13101 means that the prefetch is preparing for a write to the memory address
13102 and zero, the default, means that the prefetch is preparing for a read.
13103 The value @var{locality} must be a compile-time constant integer between
13104 zero and three. A value of zero means that the data has no temporal
13105 locality, so it need not be left in the cache after the access. A value
13106 of three means that the data has a high degree of temporal locality and
13107 should be left in all levels of cache possible. Values of one and two
13108 mean, respectively, a low or moderate degree of temporal locality. The
13112 for (i = 0; i < n; i++)
13114 a[i] = a[i] + b[i];
13115 __builtin_prefetch (&a[i+j], 1, 1);
13116 __builtin_prefetch (&b[i+j], 0, 1);
13121 Data prefetch does not generate faults if @var{addr} is invalid, but
13122 the address expression itself must be valid. For example, a prefetch
13123 of @code{p->next} does not fault if @code{p->next} is not a valid
13124 address, but evaluation faults if @code{p} is not a valid address.
13126 If the target does not support data prefetch, the address expression
13127 is evaluated if it includes side effects but no other code is generated
13128 and GCC does not issue a warning.
13131 @deftypefn {Built-in Function}{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})
13132 Returns the size of an object pointed to by @var{ptr}. @xref{Object Size Checking} for a detailed description of the function.
13135 @deftypefn {Built-in Function} double __builtin_huge_val (void)
13136 Returns a positive infinity, if supported by the floating-point format,
13137 else @code{DBL_MAX}. This function is suitable for implementing the
13138 ISO C macro @code{HUGE_VAL}.
13141 @deftypefn {Built-in Function} float __builtin_huge_valf (void)
13142 Similar to @code{__builtin_huge_val}, except the return type is @code{float}.
13145 @deftypefn {Built-in Function} {long double} __builtin_huge_vall (void)
13146 Similar to @code{__builtin_huge_val}, except the return
13147 type is @code{long double}.
13150 @deftypefn {Built-in Function} _Float@var{n} __builtin_huge_valf@var{n} (void)
13151 Similar to @code{__builtin_huge_val}, except the return type is
13152 @code{_Float@var{n}}.
13155 @deftypefn {Built-in Function} _Float@var{n}x __builtin_huge_valf@var{n}x (void)
13156 Similar to @code{__builtin_huge_val}, except the return type is
13157 @code{_Float@var{n}x}.
13160 @deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...)
13161 This built-in implements the C99 fpclassify functionality. The first
13162 five int arguments should be the target library's notion of the
13163 possible FP classes and are used for return values. They must be
13164 constant values and they must appear in this order: @code{FP_NAN},
13165 @code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and
13166 @code{FP_ZERO}. The ellipsis is for exactly one floating-point value
13167 to classify. GCC treats the last argument as type-generic, which
13168 means it does not do default promotion from float to double.
13171 @deftypefn {Built-in Function} double __builtin_inf (void)
13172 Similar to @code{__builtin_huge_val}, except a warning is generated
13173 if the target floating-point format does not support infinities.
13176 @deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void)
13177 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}.
13180 @deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void)
13181 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}.
13184 @deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void)
13185 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}.
13188 @deftypefn {Built-in Function} float __builtin_inff (void)
13189 Similar to @code{__builtin_inf}, except the return type is @code{float}.
13190 This function is suitable for implementing the ISO C99 macro @code{INFINITY}.
13193 @deftypefn {Built-in Function} {long double} __builtin_infl (void)
13194 Similar to @code{__builtin_inf}, except the return
13195 type is @code{long double}.
13198 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n} (void)
13199 Similar to @code{__builtin_inf}, except the return
13200 type is @code{_Float@var{n}}.
13203 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n}x (void)
13204 Similar to @code{__builtin_inf}, except the return
13205 type is @code{_Float@var{n}x}.
13208 @deftypefn {Built-in Function} int __builtin_isinf_sign (...)
13209 Similar to @code{isinf}, except the return value is -1 for
13210 an argument of @code{-Inf} and 1 for an argument of @code{+Inf}.
13211 Note while the parameter list is an
13212 ellipsis, this function only accepts exactly one floating-point
13213 argument. GCC treats this parameter as type-generic, which means it
13214 does not do default promotion from float to double.
13217 @deftypefn {Built-in Function} double __builtin_nan (const char *str)
13218 This is an implementation of the ISO C99 function @code{nan}.
13220 Since ISO C99 defines this function in terms of @code{strtod}, which we
13221 do not implement, a description of the parsing is in order. The string
13222 is parsed as by @code{strtol}; that is, the base is recognized by
13223 leading @samp{0} or @samp{0x} prefixes. The number parsed is placed
13224 in the significand such that the least significant bit of the number
13225 is at the least significant bit of the significand. The number is
13226 truncated to fit the significand field provided. The significand is
13227 forced to be a quiet NaN@.
13229 This function, if given a string literal all of which would have been
13230 consumed by @code{strtol}, is evaluated early enough that it is considered a
13231 compile-time constant.
13234 @deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str)
13235 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}.
13238 @deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str)
13239 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}.
13242 @deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str)
13243 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}.
13246 @deftypefn {Built-in Function} float __builtin_nanf (const char *str)
13247 Similar to @code{__builtin_nan}, except the return type is @code{float}.
13250 @deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str)
13251 Similar to @code{__builtin_nan}, except the return type is @code{long double}.
13254 @deftypefn {Built-in Function} _Float@var{n} __builtin_nanf@var{n} (const char *str)
13255 Similar to @code{__builtin_nan}, except the return type is
13256 @code{_Float@var{n}}.
13259 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nanf@var{n}x (const char *str)
13260 Similar to @code{__builtin_nan}, except the return type is
13261 @code{_Float@var{n}x}.
13264 @deftypefn {Built-in Function} double __builtin_nans (const char *str)
13265 Similar to @code{__builtin_nan}, except the significand is forced
13266 to be a signaling NaN@. The @code{nans} function is proposed by
13267 @uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}.
13270 @deftypefn {Built-in Function} float __builtin_nansf (const char *str)
13271 Similar to @code{__builtin_nans}, except the return type is @code{float}.
13274 @deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str)
13275 Similar to @code{__builtin_nans}, except the return type is @code{long double}.
13278 @deftypefn {Built-in Function} _Float@var{n} __builtin_nansf@var{n} (const char *str)
13279 Similar to @code{__builtin_nans}, except the return type is
13280 @code{_Float@var{n}}.
13283 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nansf@var{n}x (const char *str)
13284 Similar to @code{__builtin_nans}, except the return type is
13285 @code{_Float@var{n}x}.
13288 @deftypefn {Built-in Function} int __builtin_ffs (int x)
13289 Returns one plus the index of the least significant 1-bit of @var{x}, or
13290 if @var{x} is zero, returns zero.
13293 @deftypefn {Built-in Function} int __builtin_clz (unsigned int x)
13294 Returns the number of leading 0-bits in @var{x}, starting at the most
13295 significant bit position. If @var{x} is 0, the result is undefined.
13298 @deftypefn {Built-in Function} int __builtin_ctz (unsigned int x)
13299 Returns the number of trailing 0-bits in @var{x}, starting at the least
13300 significant bit position. If @var{x} is 0, the result is undefined.
13303 @deftypefn {Built-in Function} int __builtin_clrsb (int x)
13304 Returns the number of leading redundant sign bits in @var{x}, i.e.@: the
13305 number of bits following the most significant bit that are identical
13306 to it. There are no special cases for 0 or other values.
13309 @deftypefn {Built-in Function} int __builtin_popcount (unsigned int x)
13310 Returns the number of 1-bits in @var{x}.
13313 @deftypefn {Built-in Function} int __builtin_parity (unsigned int x)
13314 Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x}
13318 @deftypefn {Built-in Function} int __builtin_ffsl (long)
13319 Similar to @code{__builtin_ffs}, except the argument type is
13323 @deftypefn {Built-in Function} int __builtin_clzl (unsigned long)
13324 Similar to @code{__builtin_clz}, except the argument type is
13325 @code{unsigned long}.
13328 @deftypefn {Built-in Function} int __builtin_ctzl (unsigned long)
13329 Similar to @code{__builtin_ctz}, except the argument type is
13330 @code{unsigned long}.
13333 @deftypefn {Built-in Function} int __builtin_clrsbl (long)
13334 Similar to @code{__builtin_clrsb}, except the argument type is
13338 @deftypefn {Built-in Function} int __builtin_popcountl (unsigned long)
13339 Similar to @code{__builtin_popcount}, except the argument type is
13340 @code{unsigned long}.
13343 @deftypefn {Built-in Function} int __builtin_parityl (unsigned long)
13344 Similar to @code{__builtin_parity}, except the argument type is
13345 @code{unsigned long}.
13348 @deftypefn {Built-in Function} int __builtin_ffsll (long long)
13349 Similar to @code{__builtin_ffs}, except the argument type is
13353 @deftypefn {Built-in Function} int __builtin_clzll (unsigned long long)
13354 Similar to @code{__builtin_clz}, except the argument type is
13355 @code{unsigned long long}.
13358 @deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long)
13359 Similar to @code{__builtin_ctz}, except the argument type is
13360 @code{unsigned long long}.
13363 @deftypefn {Built-in Function} int __builtin_clrsbll (long long)
13364 Similar to @code{__builtin_clrsb}, except the argument type is
13368 @deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long)
13369 Similar to @code{__builtin_popcount}, except the argument type is
13370 @code{unsigned long long}.
13373 @deftypefn {Built-in Function} int __builtin_parityll (unsigned long long)
13374 Similar to @code{__builtin_parity}, except the argument type is
13375 @code{unsigned long long}.
13378 @deftypefn {Built-in Function} double __builtin_powi (double, int)
13379 Returns the first argument raised to the power of the second. Unlike the
13380 @code{pow} function no guarantees about precision and rounding are made.
13383 @deftypefn {Built-in Function} float __builtin_powif (float, int)
13384 Similar to @code{__builtin_powi}, except the argument and return types
13388 @deftypefn {Built-in Function} {long double} __builtin_powil (long double, int)
13389 Similar to @code{__builtin_powi}, except the argument and return types
13390 are @code{long double}.
13393 @deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x)
13394 Returns @var{x} with the order of the bytes reversed; for example,
13395 @code{0xaabb} becomes @code{0xbbaa}. Byte here always means
13399 @deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x)
13400 Similar to @code{__builtin_bswap16}, except the argument and return types
13404 @deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x)
13405 Similar to @code{__builtin_bswap32}, except the argument and return types
13409 @deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x)
13410 On targets where the user visible pointer size is smaller than the size
13411 of an actual hardware address this function returns the extended user
13412 pointer. Targets where this is true included ILP32 mode on x86_64 or
13413 Aarch64. This function is mainly useful when writing inline assembly
13417 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_id (int x)
13418 Returns the openacc gang, worker or vector id depending on whether @var{x} is
13422 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_size (int x)
13423 Returns the openacc gang, worker or vector size depending on whether @var{x} is
13427 @node Target Builtins
13428 @section Built-in Functions Specific to Particular Target Machines
13430 On some target machines, GCC supports many built-in functions specific
13431 to those machines. Generally these generate calls to specific machine
13432 instructions, but allow the compiler to schedule those calls.
13435 * AArch64 Built-in Functions::
13436 * Alpha Built-in Functions::
13437 * Altera Nios II Built-in Functions::
13438 * ARC Built-in Functions::
13439 * ARC SIMD Built-in Functions::
13440 * ARM iWMMXt Built-in Functions::
13441 * ARM C Language Extensions (ACLE)::
13442 * ARM Floating Point Status and Control Intrinsics::
13443 * ARM ARMv8-M Security Extensions::
13444 * AVR Built-in Functions::
13445 * Blackfin Built-in Functions::
13446 * FR-V Built-in Functions::
13447 * MIPS DSP Built-in Functions::
13448 * MIPS Paired-Single Support::
13449 * MIPS Loongson Built-in Functions::
13450 * MIPS SIMD Architecture (MSA) Support::
13451 * Other MIPS Built-in Functions::
13452 * MSP430 Built-in Functions::
13453 * NDS32 Built-in Functions::
13454 * picoChip Built-in Functions::
13455 * Basic PowerPC Built-in Functions::
13456 * PowerPC AltiVec/VSX Built-in Functions::
13457 * PowerPC Hardware Transactional Memory Built-in Functions::
13458 * PowerPC Atomic Memory Operation Functions::
13459 * RX Built-in Functions::
13460 * S/390 System z Built-in Functions::
13461 * SH Built-in Functions::
13462 * SPARC VIS Built-in Functions::
13463 * SPU Built-in Functions::
13464 * TI C6X Built-in Functions::
13465 * TILE-Gx Built-in Functions::
13466 * TILEPro Built-in Functions::
13467 * x86 Built-in Functions::
13468 * x86 transactional memory intrinsics::
13469 * x86 control-flow protection intrinsics::
13472 @node AArch64 Built-in Functions
13473 @subsection AArch64 Built-in Functions
13475 These built-in functions are available for the AArch64 family of
13478 unsigned int __builtin_aarch64_get_fpcr ()
13479 void __builtin_aarch64_set_fpcr (unsigned int)
13480 unsigned int __builtin_aarch64_get_fpsr ()
13481 void __builtin_aarch64_set_fpsr (unsigned int)
13484 @node Alpha Built-in Functions
13485 @subsection Alpha Built-in Functions
13487 These built-in functions are available for the Alpha family of
13488 processors, depending on the command-line switches used.
13490 The following built-in functions are always available. They
13491 all generate the machine instruction that is part of the name.
13494 long __builtin_alpha_implver (void)
13495 long __builtin_alpha_rpcc (void)
13496 long __builtin_alpha_amask (long)
13497 long __builtin_alpha_cmpbge (long, long)
13498 long __builtin_alpha_extbl (long, long)
13499 long __builtin_alpha_extwl (long, long)
13500 long __builtin_alpha_extll (long, long)
13501 long __builtin_alpha_extql (long, long)
13502 long __builtin_alpha_extwh (long, long)
13503 long __builtin_alpha_extlh (long, long)
13504 long __builtin_alpha_extqh (long, long)
13505 long __builtin_alpha_insbl (long, long)
13506 long __builtin_alpha_inswl (long, long)
13507 long __builtin_alpha_insll (long, long)
13508 long __builtin_alpha_insql (long, long)
13509 long __builtin_alpha_inswh (long, long)
13510 long __builtin_alpha_inslh (long, long)
13511 long __builtin_alpha_insqh (long, long)
13512 long __builtin_alpha_mskbl (long, long)
13513 long __builtin_alpha_mskwl (long, long)
13514 long __builtin_alpha_mskll (long, long)
13515 long __builtin_alpha_mskql (long, long)
13516 long __builtin_alpha_mskwh (long, long)
13517 long __builtin_alpha_msklh (long, long)
13518 long __builtin_alpha_mskqh (long, long)
13519 long __builtin_alpha_umulh (long, long)
13520 long __builtin_alpha_zap (long, long)
13521 long __builtin_alpha_zapnot (long, long)
13524 The following built-in functions are always with @option{-mmax}
13525 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
13526 later. They all generate the machine instruction that is part
13530 long __builtin_alpha_pklb (long)
13531 long __builtin_alpha_pkwb (long)
13532 long __builtin_alpha_unpkbl (long)
13533 long __builtin_alpha_unpkbw (long)
13534 long __builtin_alpha_minub8 (long, long)
13535 long __builtin_alpha_minsb8 (long, long)
13536 long __builtin_alpha_minuw4 (long, long)
13537 long __builtin_alpha_minsw4 (long, long)
13538 long __builtin_alpha_maxub8 (long, long)
13539 long __builtin_alpha_maxsb8 (long, long)
13540 long __builtin_alpha_maxuw4 (long, long)
13541 long __builtin_alpha_maxsw4 (long, long)
13542 long __builtin_alpha_perr (long, long)
13545 The following built-in functions are always with @option{-mcix}
13546 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
13547 later. They all generate the machine instruction that is part
13551 long __builtin_alpha_cttz (long)
13552 long __builtin_alpha_ctlz (long)
13553 long __builtin_alpha_ctpop (long)
13556 The following built-in functions are available on systems that use the OSF/1
13557 PALcode. Normally they invoke the @code{rduniq} and @code{wruniq}
13558 PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
13559 @code{rdval} and @code{wrval}.
13562 void *__builtin_thread_pointer (void)
13563 void __builtin_set_thread_pointer (void *)
13566 @node Altera Nios II Built-in Functions
13567 @subsection Altera Nios II Built-in Functions
13569 These built-in functions are available for the Altera Nios II
13570 family of processors.
13572 The following built-in functions are always available. They
13573 all generate the machine instruction that is part of the name.
13576 int __builtin_ldbio (volatile const void *)
13577 int __builtin_ldbuio (volatile const void *)
13578 int __builtin_ldhio (volatile const void *)
13579 int __builtin_ldhuio (volatile const void *)
13580 int __builtin_ldwio (volatile const void *)
13581 void __builtin_stbio (volatile void *, int)
13582 void __builtin_sthio (volatile void *, int)
13583 void __builtin_stwio (volatile void *, int)
13584 void __builtin_sync (void)
13585 int __builtin_rdctl (int)
13586 int __builtin_rdprs (int, int)
13587 void __builtin_wrctl (int, int)
13588 void __builtin_flushd (volatile void *)
13589 void __builtin_flushda (volatile void *)
13590 int __builtin_wrpie (int);
13591 void __builtin_eni (int);
13592 int __builtin_ldex (volatile const void *)
13593 int __builtin_stex (volatile void *, int)
13594 int __builtin_ldsex (volatile const void *)
13595 int __builtin_stsex (volatile void *, int)
13598 The following built-in functions are always available. They
13599 all generate a Nios II Custom Instruction. The name of the
13600 function represents the types that the function takes and
13601 returns. The letter before the @code{n} is the return type
13602 or void if absent. The @code{n} represents the first parameter
13603 to all the custom instructions, the custom instruction number.
13604 The two letters after the @code{n} represent the up to two
13605 parameters to the function.
13607 The letters represent the following data types:
13610 @code{void} for return type and no parameter for parameter types.
13613 @code{int} for return type and parameter type
13616 @code{float} for return type and parameter type
13619 @code{void *} for return type and parameter type
13623 And the function names are:
13625 void __builtin_custom_n (void)
13626 void __builtin_custom_ni (int)
13627 void __builtin_custom_nf (float)
13628 void __builtin_custom_np (void *)
13629 void __builtin_custom_nii (int, int)
13630 void __builtin_custom_nif (int, float)
13631 void __builtin_custom_nip (int, void *)
13632 void __builtin_custom_nfi (float, int)
13633 void __builtin_custom_nff (float, float)
13634 void __builtin_custom_nfp (float, void *)
13635 void __builtin_custom_npi (void *, int)
13636 void __builtin_custom_npf (void *, float)
13637 void __builtin_custom_npp (void *, void *)
13638 int __builtin_custom_in (void)
13639 int __builtin_custom_ini (int)
13640 int __builtin_custom_inf (float)
13641 int __builtin_custom_inp (void *)
13642 int __builtin_custom_inii (int, int)
13643 int __builtin_custom_inif (int, float)
13644 int __builtin_custom_inip (int, void *)
13645 int __builtin_custom_infi (float, int)
13646 int __builtin_custom_inff (float, float)
13647 int __builtin_custom_infp (float, void *)
13648 int __builtin_custom_inpi (void *, int)
13649 int __builtin_custom_inpf (void *, float)
13650 int __builtin_custom_inpp (void *, void *)
13651 float __builtin_custom_fn (void)
13652 float __builtin_custom_fni (int)
13653 float __builtin_custom_fnf (float)
13654 float __builtin_custom_fnp (void *)
13655 float __builtin_custom_fnii (int, int)
13656 float __builtin_custom_fnif (int, float)
13657 float __builtin_custom_fnip (int, void *)
13658 float __builtin_custom_fnfi (float, int)
13659 float __builtin_custom_fnff (float, float)
13660 float __builtin_custom_fnfp (float, void *)
13661 float __builtin_custom_fnpi (void *, int)
13662 float __builtin_custom_fnpf (void *, float)
13663 float __builtin_custom_fnpp (void *, void *)
13664 void * __builtin_custom_pn (void)
13665 void * __builtin_custom_pni (int)
13666 void * __builtin_custom_pnf (float)
13667 void * __builtin_custom_pnp (void *)
13668 void * __builtin_custom_pnii (int, int)
13669 void * __builtin_custom_pnif (int, float)
13670 void * __builtin_custom_pnip (int, void *)
13671 void * __builtin_custom_pnfi (float, int)
13672 void * __builtin_custom_pnff (float, float)
13673 void * __builtin_custom_pnfp (float, void *)
13674 void * __builtin_custom_pnpi (void *, int)
13675 void * __builtin_custom_pnpf (void *, float)
13676 void * __builtin_custom_pnpp (void *, void *)
13679 @node ARC Built-in Functions
13680 @subsection ARC Built-in Functions
13682 The following built-in functions are provided for ARC targets. The
13683 built-ins generate the corresponding assembly instructions. In the
13684 examples given below, the generated code often requires an operand or
13685 result to be in a register. Where necessary further code will be
13686 generated to ensure this is true, but for brevity this is not
13687 described in each case.
13689 @emph{Note:} Using a built-in to generate an instruction not supported
13690 by a target may cause problems. At present the compiler is not
13691 guaranteed to detect such misuse, and as a result an internal compiler
13692 error may be generated.
13694 @deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval})
13695 Return 1 if @var{val} is known to have the byte alignment given
13696 by @var{alignval}, otherwise return 0.
13697 Note that this is different from
13699 __alignof__(*(char *)@var{val}) >= alignval
13701 because __alignof__ sees only the type of the dereference, whereas
13702 __builtin_arc_align uses alignment information from the pointer
13703 as well as from the pointed-to type.
13704 The information available will depend on optimization level.
13707 @deftypefn {Built-in Function} void __builtin_arc_brk (void)
13714 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno})
13715 The operand is the number of a register to be read. Generates:
13717 mov @var{dest}, r@var{regno}
13719 where the value in @var{dest} will be the result returned from the
13723 @deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val})
13724 The first operand is the number of a register to be written, the
13725 second operand is a compile time constant to write into that
13726 register. Generates:
13728 mov r@var{regno}, @var{val}
13732 @deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b})
13733 Only available if either @option{-mcpu=ARC700} or @option{-meA} is set.
13736 divaw @var{dest}, @var{a}, @var{b}
13738 where the value in @var{dest} will be the result returned from the
13742 @deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a})
13749 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr})
13750 The operand, @var{auxv}, is the address of an auxiliary register and
13751 must be a compile time constant. Generates:
13753 lr @var{dest}, [@var{auxr}]
13755 Where the value in @var{dest} will be the result returned from the
13759 @deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b})
13760 Only available with @option{-mmul64}. Generates:
13762 mul64 @var{a}, @var{b}
13766 @deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b})
13767 Only available with @option{-mmul64}. Generates:
13769 mulu64 @var{a}, @var{b}
13773 @deftypefn {Built-in Function} void __builtin_arc_nop (void)
13780 @deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src})
13781 Only valid if the @samp{norm} instruction is available through the
13782 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
13785 norm @var{dest}, @var{src}
13787 Where the value in @var{dest} will be the result returned from the
13791 @deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src})
13792 Only valid if the @samp{normw} instruction is available through the
13793 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
13796 normw @var{dest}, @var{src}
13798 Where the value in @var{dest} will be the result returned from the
13802 @deftypefn {Built-in Function} void __builtin_arc_rtie (void)
13809 @deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a}
13816 @deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{auxr}, unsigned int @var{val})
13817 The first argument, @var{auxv}, is the address of an auxiliary
13818 register, the second argument, @var{val}, is a compile time constant
13819 to be written to the register. Generates:
13821 sr @var{auxr}, [@var{val}]
13825 @deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src})
13826 Only valid with @option{-mswap}. Generates:
13828 swap @var{dest}, @var{src}
13830 Where the value in @var{dest} will be the result returned from the
13834 @deftypefn {Built-in Function} void __builtin_arc_swi (void)
13841 @deftypefn {Built-in Function} void __builtin_arc_sync (void)
13842 Only available with @option{-mcpu=ARC700}. Generates:
13848 @deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c})
13849 Only available with @option{-mcpu=ARC700}. Generates:
13855 @deftypefn {Built-in Function} void __builtin_arc_unimp_s (void)
13856 Only available with @option{-mcpu=ARC700}. Generates:
13862 The instructions generated by the following builtins are not
13863 considered as candidates for scheduling. They are not moved around by
13864 the compiler during scheduling, and thus can be expected to appear
13865 where they are put in the C code:
13867 __builtin_arc_brk()
13868 __builtin_arc_core_read()
13869 __builtin_arc_core_write()
13870 __builtin_arc_flag()
13872 __builtin_arc_sleep()
13874 __builtin_arc_swi()
13877 @node ARC SIMD Built-in Functions
13878 @subsection ARC SIMD Built-in Functions
13880 SIMD builtins provided by the compiler can be used to generate the
13881 vector instructions. This section describes the available builtins
13882 and their usage in programs. With the @option{-msimd} option, the
13883 compiler provides 128-bit vector types, which can be specified using
13884 the @code{vector_size} attribute. The header file @file{arc-simd.h}
13885 can be included to use the following predefined types:
13887 typedef int __v4si __attribute__((vector_size(16)));
13888 typedef short __v8hi __attribute__((vector_size(16)));
13891 These types can be used to define 128-bit variables. The built-in
13892 functions listed in the following section can be used on these
13893 variables to generate the vector operations.
13895 For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file
13896 @file{arc-simd.h} also provides equivalent macros called
13897 @code{_@var{someinsn}} that can be used for programming ease and
13898 improved readability. The following macros for DMA control are also
13901 #define _setup_dma_in_channel_reg _vdiwr
13902 #define _setup_dma_out_channel_reg _vdowr
13905 The following is a complete list of all the SIMD built-ins provided
13906 for ARC, grouped by calling signature.
13908 The following take two @code{__v8hi} arguments and return a
13909 @code{__v8hi} result:
13911 __v8hi __builtin_arc_vaddaw (__v8hi, __v8hi)
13912 __v8hi __builtin_arc_vaddw (__v8hi, __v8hi)
13913 __v8hi __builtin_arc_vand (__v8hi, __v8hi)
13914 __v8hi __builtin_arc_vandaw (__v8hi, __v8hi)
13915 __v8hi __builtin_arc_vavb (__v8hi, __v8hi)
13916 __v8hi __builtin_arc_vavrb (__v8hi, __v8hi)
13917 __v8hi __builtin_arc_vbic (__v8hi, __v8hi)
13918 __v8hi __builtin_arc_vbicaw (__v8hi, __v8hi)
13919 __v8hi __builtin_arc_vdifaw (__v8hi, __v8hi)
13920 __v8hi __builtin_arc_vdifw (__v8hi, __v8hi)
13921 __v8hi __builtin_arc_veqw (__v8hi, __v8hi)
13922 __v8hi __builtin_arc_vh264f (__v8hi, __v8hi)
13923 __v8hi __builtin_arc_vh264ft (__v8hi, __v8hi)
13924 __v8hi __builtin_arc_vh264fw (__v8hi, __v8hi)
13925 __v8hi __builtin_arc_vlew (__v8hi, __v8hi)
13926 __v8hi __builtin_arc_vltw (__v8hi, __v8hi)
13927 __v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi)
13928 __v8hi __builtin_arc_vmaxw (__v8hi, __v8hi)
13929 __v8hi __builtin_arc_vminaw (__v8hi, __v8hi)
13930 __v8hi __builtin_arc_vminw (__v8hi, __v8hi)
13931 __v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi)
13932 __v8hi __builtin_arc_vmr1w (__v8hi, __v8hi)
13933 __v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi)
13934 __v8hi __builtin_arc_vmr2w (__v8hi, __v8hi)
13935 __v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi)
13936 __v8hi __builtin_arc_vmr3w (__v8hi, __v8hi)
13937 __v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi)
13938 __v8hi __builtin_arc_vmr4w (__v8hi, __v8hi)
13939 __v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi)
13940 __v8hi __builtin_arc_vmr5w (__v8hi, __v8hi)
13941 __v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi)
13942 __v8hi __builtin_arc_vmr6w (__v8hi, __v8hi)
13943 __v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi)
13944 __v8hi __builtin_arc_vmr7w (__v8hi, __v8hi)
13945 __v8hi __builtin_arc_vmrb (__v8hi, __v8hi)
13946 __v8hi __builtin_arc_vmulaw (__v8hi, __v8hi)
13947 __v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi)
13948 __v8hi __builtin_arc_vmulfw (__v8hi, __v8hi)
13949 __v8hi __builtin_arc_vmulw (__v8hi, __v8hi)
13950 __v8hi __builtin_arc_vnew (__v8hi, __v8hi)
13951 __v8hi __builtin_arc_vor (__v8hi, __v8hi)
13952 __v8hi __builtin_arc_vsubaw (__v8hi, __v8hi)
13953 __v8hi __builtin_arc_vsubw (__v8hi, __v8hi)
13954 __v8hi __builtin_arc_vsummw (__v8hi, __v8hi)
13955 __v8hi __builtin_arc_vvc1f (__v8hi, __v8hi)
13956 __v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi)
13957 __v8hi __builtin_arc_vxor (__v8hi, __v8hi)
13958 __v8hi __builtin_arc_vxoraw (__v8hi, __v8hi)
13961 The following take one @code{__v8hi} and one @code{int} argument and return a
13962 @code{__v8hi} result:
13965 __v8hi __builtin_arc_vbaddw (__v8hi, int)
13966 __v8hi __builtin_arc_vbmaxw (__v8hi, int)
13967 __v8hi __builtin_arc_vbminw (__v8hi, int)
13968 __v8hi __builtin_arc_vbmulaw (__v8hi, int)
13969 __v8hi __builtin_arc_vbmulfw (__v8hi, int)
13970 __v8hi __builtin_arc_vbmulw (__v8hi, int)
13971 __v8hi __builtin_arc_vbrsubw (__v8hi, int)
13972 __v8hi __builtin_arc_vbsubw (__v8hi, int)
13975 The following take one @code{__v8hi} argument and one @code{int} argument which
13976 must be a 3-bit compile time constant indicating a register number
13977 I0-I7. They return a @code{__v8hi} result.
13979 __v8hi __builtin_arc_vasrw (__v8hi, const int)
13980 __v8hi __builtin_arc_vsr8 (__v8hi, const int)
13981 __v8hi __builtin_arc_vsr8aw (__v8hi, const int)
13984 The following take one @code{__v8hi} argument and one @code{int}
13985 argument which must be a 6-bit compile time constant. They return a
13986 @code{__v8hi} result.
13988 __v8hi __builtin_arc_vasrpwbi (__v8hi, const int)
13989 __v8hi __builtin_arc_vasrrpwbi (__v8hi, const int)
13990 __v8hi __builtin_arc_vasrrwi (__v8hi, const int)
13991 __v8hi __builtin_arc_vasrsrwi (__v8hi, const int)
13992 __v8hi __builtin_arc_vasrwi (__v8hi, const int)
13993 __v8hi __builtin_arc_vsr8awi (__v8hi, const int)
13994 __v8hi __builtin_arc_vsr8i (__v8hi, const int)
13997 The following take one @code{__v8hi} argument and one @code{int} argument which
13998 must be a 8-bit compile time constant. They return a @code{__v8hi}
14001 __v8hi __builtin_arc_vd6tapf (__v8hi, const int)
14002 __v8hi __builtin_arc_vmvaw (__v8hi, const int)
14003 __v8hi __builtin_arc_vmvw (__v8hi, const int)
14004 __v8hi __builtin_arc_vmvzw (__v8hi, const int)
14007 The following take two @code{int} arguments, the second of which which
14008 must be a 8-bit compile time constant. They return a @code{__v8hi}
14011 __v8hi __builtin_arc_vmovaw (int, const int)
14012 __v8hi __builtin_arc_vmovw (int, const int)
14013 __v8hi __builtin_arc_vmovzw (int, const int)
14016 The following take a single @code{__v8hi} argument and return a
14017 @code{__v8hi} result:
14019 __v8hi __builtin_arc_vabsaw (__v8hi)
14020 __v8hi __builtin_arc_vabsw (__v8hi)
14021 __v8hi __builtin_arc_vaddsuw (__v8hi)
14022 __v8hi __builtin_arc_vexch1 (__v8hi)
14023 __v8hi __builtin_arc_vexch2 (__v8hi)
14024 __v8hi __builtin_arc_vexch4 (__v8hi)
14025 __v8hi __builtin_arc_vsignw (__v8hi)
14026 __v8hi __builtin_arc_vupbaw (__v8hi)
14027 __v8hi __builtin_arc_vupbw (__v8hi)
14028 __v8hi __builtin_arc_vupsbaw (__v8hi)
14029 __v8hi __builtin_arc_vupsbw (__v8hi)
14032 The following take two @code{int} arguments and return no result:
14034 void __builtin_arc_vdirun (int, int)
14035 void __builtin_arc_vdorun (int, int)
14038 The following take two @code{int} arguments and return no result. The
14039 first argument must a 3-bit compile time constant indicating one of
14040 the DR0-DR7 DMA setup channels:
14042 void __builtin_arc_vdiwr (const int, int)
14043 void __builtin_arc_vdowr (const int, int)
14046 The following take an @code{int} argument and return no result:
14048 void __builtin_arc_vendrec (int)
14049 void __builtin_arc_vrec (int)
14050 void __builtin_arc_vrecrun (int)
14051 void __builtin_arc_vrun (int)
14054 The following take a @code{__v8hi} argument and two @code{int}
14055 arguments and return a @code{__v8hi} result. The second argument must
14056 be a 3-bit compile time constants, indicating one the registers I0-I7,
14057 and the third argument must be an 8-bit compile time constant.
14059 @emph{Note:} Although the equivalent hardware instructions do not take
14060 an SIMD register as an operand, these builtins overwrite the relevant
14061 bits of the @code{__v8hi} register provided as the first argument with
14062 the value loaded from the @code{[Ib, u8]} location in the SDM.
14065 __v8hi __builtin_arc_vld32 (__v8hi, const int, const int)
14066 __v8hi __builtin_arc_vld32wh (__v8hi, const int, const int)
14067 __v8hi __builtin_arc_vld32wl (__v8hi, const int, const int)
14068 __v8hi __builtin_arc_vld64 (__v8hi, const int, const int)
14071 The following take two @code{int} arguments and return a @code{__v8hi}
14072 result. The first argument must be a 3-bit compile time constants,
14073 indicating one the registers I0-I7, and the second argument must be an
14074 8-bit compile time constant.
14077 __v8hi __builtin_arc_vld128 (const int, const int)
14078 __v8hi __builtin_arc_vld64w (const int, const int)
14081 The following take a @code{__v8hi} argument and two @code{int}
14082 arguments and return no result. The second argument must be a 3-bit
14083 compile time constants, indicating one the registers I0-I7, and the
14084 third argument must be an 8-bit compile time constant.
14087 void __builtin_arc_vst128 (__v8hi, const int, const int)
14088 void __builtin_arc_vst64 (__v8hi, const int, const int)
14091 The following take a @code{__v8hi} argument and three @code{int}
14092 arguments and return no result. The second argument must be a 3-bit
14093 compile-time constant, identifying the 16-bit sub-register to be
14094 stored, the third argument must be a 3-bit compile time constants,
14095 indicating one the registers I0-I7, and the fourth argument must be an
14096 8-bit compile time constant.
14099 void __builtin_arc_vst16_n (__v8hi, const int, const int, const int)
14100 void __builtin_arc_vst32_n (__v8hi, const int, const int, const int)
14103 @node ARM iWMMXt Built-in Functions
14104 @subsection ARM iWMMXt Built-in Functions
14106 These built-in functions are available for the ARM family of
14107 processors when the @option{-mcpu=iwmmxt} switch is used:
14110 typedef int v2si __attribute__ ((vector_size (8)));
14111 typedef short v4hi __attribute__ ((vector_size (8)));
14112 typedef char v8qi __attribute__ ((vector_size (8)));
14114 int __builtin_arm_getwcgr0 (void)
14115 void __builtin_arm_setwcgr0 (int)
14116 int __builtin_arm_getwcgr1 (void)
14117 void __builtin_arm_setwcgr1 (int)
14118 int __builtin_arm_getwcgr2 (void)
14119 void __builtin_arm_setwcgr2 (int)
14120 int __builtin_arm_getwcgr3 (void)
14121 void __builtin_arm_setwcgr3 (int)
14122 int __builtin_arm_textrmsb (v8qi, int)
14123 int __builtin_arm_textrmsh (v4hi, int)
14124 int __builtin_arm_textrmsw (v2si, int)
14125 int __builtin_arm_textrmub (v8qi, int)
14126 int __builtin_arm_textrmuh (v4hi, int)
14127 int __builtin_arm_textrmuw (v2si, int)
14128 v8qi __builtin_arm_tinsrb (v8qi, int, int)
14129 v4hi __builtin_arm_tinsrh (v4hi, int, int)
14130 v2si __builtin_arm_tinsrw (v2si, int, int)
14131 long long __builtin_arm_tmia (long long, int, int)
14132 long long __builtin_arm_tmiabb (long long, int, int)
14133 long long __builtin_arm_tmiabt (long long, int, int)
14134 long long __builtin_arm_tmiaph (long long, int, int)
14135 long long __builtin_arm_tmiatb (long long, int, int)
14136 long long __builtin_arm_tmiatt (long long, int, int)
14137 int __builtin_arm_tmovmskb (v8qi)
14138 int __builtin_arm_tmovmskh (v4hi)
14139 int __builtin_arm_tmovmskw (v2si)
14140 long long __builtin_arm_waccb (v8qi)
14141 long long __builtin_arm_wacch (v4hi)
14142 long long __builtin_arm_waccw (v2si)
14143 v8qi __builtin_arm_waddb (v8qi, v8qi)
14144 v8qi __builtin_arm_waddbss (v8qi, v8qi)
14145 v8qi __builtin_arm_waddbus (v8qi, v8qi)
14146 v4hi __builtin_arm_waddh (v4hi, v4hi)
14147 v4hi __builtin_arm_waddhss (v4hi, v4hi)
14148 v4hi __builtin_arm_waddhus (v4hi, v4hi)
14149 v2si __builtin_arm_waddw (v2si, v2si)
14150 v2si __builtin_arm_waddwss (v2si, v2si)
14151 v2si __builtin_arm_waddwus (v2si, v2si)
14152 v8qi __builtin_arm_walign (v8qi, v8qi, int)
14153 long long __builtin_arm_wand(long long, long long)
14154 long long __builtin_arm_wandn (long long, long long)
14155 v8qi __builtin_arm_wavg2b (v8qi, v8qi)
14156 v8qi __builtin_arm_wavg2br (v8qi, v8qi)
14157 v4hi __builtin_arm_wavg2h (v4hi, v4hi)
14158 v4hi __builtin_arm_wavg2hr (v4hi, v4hi)
14159 v8qi __builtin_arm_wcmpeqb (v8qi, v8qi)
14160 v4hi __builtin_arm_wcmpeqh (v4hi, v4hi)
14161 v2si __builtin_arm_wcmpeqw (v2si, v2si)
14162 v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi)
14163 v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi)
14164 v2si __builtin_arm_wcmpgtsw (v2si, v2si)
14165 v8qi __builtin_arm_wcmpgtub (v8qi, v8qi)
14166 v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi)
14167 v2si __builtin_arm_wcmpgtuw (v2si, v2si)
14168 long long __builtin_arm_wmacs (long long, v4hi, v4hi)
14169 long long __builtin_arm_wmacsz (v4hi, v4hi)
14170 long long __builtin_arm_wmacu (long long, v4hi, v4hi)
14171 long long __builtin_arm_wmacuz (v4hi, v4hi)
14172 v4hi __builtin_arm_wmadds (v4hi, v4hi)
14173 v4hi __builtin_arm_wmaddu (v4hi, v4hi)
14174 v8qi __builtin_arm_wmaxsb (v8qi, v8qi)
14175 v4hi __builtin_arm_wmaxsh (v4hi, v4hi)
14176 v2si __builtin_arm_wmaxsw (v2si, v2si)
14177 v8qi __builtin_arm_wmaxub (v8qi, v8qi)
14178 v4hi __builtin_arm_wmaxuh (v4hi, v4hi)
14179 v2si __builtin_arm_wmaxuw (v2si, v2si)
14180 v8qi __builtin_arm_wminsb (v8qi, v8qi)
14181 v4hi __builtin_arm_wminsh (v4hi, v4hi)
14182 v2si __builtin_arm_wminsw (v2si, v2si)
14183 v8qi __builtin_arm_wminub (v8qi, v8qi)
14184 v4hi __builtin_arm_wminuh (v4hi, v4hi)
14185 v2si __builtin_arm_wminuw (v2si, v2si)
14186 v4hi __builtin_arm_wmulsm (v4hi, v4hi)
14187 v4hi __builtin_arm_wmulul (v4hi, v4hi)
14188 v4hi __builtin_arm_wmulum (v4hi, v4hi)
14189 long long __builtin_arm_wor (long long, long long)
14190 v2si __builtin_arm_wpackdss (long long, long long)
14191 v2si __builtin_arm_wpackdus (long long, long long)
14192 v8qi __builtin_arm_wpackhss (v4hi, v4hi)
14193 v8qi __builtin_arm_wpackhus (v4hi, v4hi)
14194 v4hi __builtin_arm_wpackwss (v2si, v2si)
14195 v4hi __builtin_arm_wpackwus (v2si, v2si)
14196 long long __builtin_arm_wrord (long long, long long)
14197 long long __builtin_arm_wrordi (long long, int)
14198 v4hi __builtin_arm_wrorh (v4hi, long long)
14199 v4hi __builtin_arm_wrorhi (v4hi, int)
14200 v2si __builtin_arm_wrorw (v2si, long long)
14201 v2si __builtin_arm_wrorwi (v2si, int)
14202 v2si __builtin_arm_wsadb (v2si, v8qi, v8qi)
14203 v2si __builtin_arm_wsadbz (v8qi, v8qi)
14204 v2si __builtin_arm_wsadh (v2si, v4hi, v4hi)
14205 v2si __builtin_arm_wsadhz (v4hi, v4hi)
14206 v4hi __builtin_arm_wshufh (v4hi, int)
14207 long long __builtin_arm_wslld (long long, long long)
14208 long long __builtin_arm_wslldi (long long, int)
14209 v4hi __builtin_arm_wsllh (v4hi, long long)
14210 v4hi __builtin_arm_wsllhi (v4hi, int)
14211 v2si __builtin_arm_wsllw (v2si, long long)
14212 v2si __builtin_arm_wsllwi (v2si, int)
14213 long long __builtin_arm_wsrad (long long, long long)
14214 long long __builtin_arm_wsradi (long long, int)
14215 v4hi __builtin_arm_wsrah (v4hi, long long)
14216 v4hi __builtin_arm_wsrahi (v4hi, int)
14217 v2si __builtin_arm_wsraw (v2si, long long)
14218 v2si __builtin_arm_wsrawi (v2si, int)
14219 long long __builtin_arm_wsrld (long long, long long)
14220 long long __builtin_arm_wsrldi (long long, int)
14221 v4hi __builtin_arm_wsrlh (v4hi, long long)
14222 v4hi __builtin_arm_wsrlhi (v4hi, int)
14223 v2si __builtin_arm_wsrlw (v2si, long long)
14224 v2si __builtin_arm_wsrlwi (v2si, int)
14225 v8qi __builtin_arm_wsubb (v8qi, v8qi)
14226 v8qi __builtin_arm_wsubbss (v8qi, v8qi)
14227 v8qi __builtin_arm_wsubbus (v8qi, v8qi)
14228 v4hi __builtin_arm_wsubh (v4hi, v4hi)
14229 v4hi __builtin_arm_wsubhss (v4hi, v4hi)
14230 v4hi __builtin_arm_wsubhus (v4hi, v4hi)
14231 v2si __builtin_arm_wsubw (v2si, v2si)
14232 v2si __builtin_arm_wsubwss (v2si, v2si)
14233 v2si __builtin_arm_wsubwus (v2si, v2si)
14234 v4hi __builtin_arm_wunpckehsb (v8qi)
14235 v2si __builtin_arm_wunpckehsh (v4hi)
14236 long long __builtin_arm_wunpckehsw (v2si)
14237 v4hi __builtin_arm_wunpckehub (v8qi)
14238 v2si __builtin_arm_wunpckehuh (v4hi)
14239 long long __builtin_arm_wunpckehuw (v2si)
14240 v4hi __builtin_arm_wunpckelsb (v8qi)
14241 v2si __builtin_arm_wunpckelsh (v4hi)
14242 long long __builtin_arm_wunpckelsw (v2si)
14243 v4hi __builtin_arm_wunpckelub (v8qi)
14244 v2si __builtin_arm_wunpckeluh (v4hi)
14245 long long __builtin_arm_wunpckeluw (v2si)
14246 v8qi __builtin_arm_wunpckihb (v8qi, v8qi)
14247 v4hi __builtin_arm_wunpckihh (v4hi, v4hi)
14248 v2si __builtin_arm_wunpckihw (v2si, v2si)
14249 v8qi __builtin_arm_wunpckilb (v8qi, v8qi)
14250 v4hi __builtin_arm_wunpckilh (v4hi, v4hi)
14251 v2si __builtin_arm_wunpckilw (v2si, v2si)
14252 long long __builtin_arm_wxor (long long, long long)
14253 long long __builtin_arm_wzero ()
14257 @node ARM C Language Extensions (ACLE)
14258 @subsection ARM C Language Extensions (ACLE)
14260 GCC implements extensions for C as described in the ARM C Language
14261 Extensions (ACLE) specification, which can be found at
14262 @uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf}.
14264 As a part of ACLE, GCC implements extensions for Advanced SIMD as described in
14265 the ARM C Language Extensions Specification. The complete list of Advanced SIMD
14266 intrinsics can be found at
14267 @uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0073a/IHI0073A_arm_neon_intrinsics_ref.pdf}.
14268 The built-in intrinsics for the Advanced SIMD extension are available when
14271 Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both
14272 back ends support CRC32 intrinsics and the ARM back end supports the
14273 Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit
14274 floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1.
14275 AArch64's back end does not have support for 16-bit floating point Advanced SIMD
14278 See @ref{ARM Options} and @ref{AArch64 Options} for more information on the
14279 availability of extensions.
14281 @node ARM Floating Point Status and Control Intrinsics
14282 @subsection ARM Floating Point Status and Control Intrinsics
14284 These built-in functions are available for the ARM family of
14285 processors with floating-point unit.
14288 unsigned int __builtin_arm_get_fpscr ()
14289 void __builtin_arm_set_fpscr (unsigned int)
14292 @node ARM ARMv8-M Security Extensions
14293 @subsection ARM ARMv8-M Security Extensions
14295 GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M
14296 Security Extensions: Requirements on Development Tools Engineering
14297 Specification, which can be found at
14298 @uref{http://infocenter.arm.com/help/topic/com.arm.doc.ecm0359818/ECM0359818_armv8m_security_extensions_reqs_on_dev_tools_1_0.pdf}.
14300 As part of the Security Extensions GCC implements two new function attributes:
14301 @code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}.
14303 As part of the Security Extensions GCC implements the intrinsics below. FPTR
14304 is used here to mean any function pointer type.
14307 cmse_address_info_t cmse_TT (void *)
14308 cmse_address_info_t cmse_TT_fptr (FPTR)
14309 cmse_address_info_t cmse_TTT (void *)
14310 cmse_address_info_t cmse_TTT_fptr (FPTR)
14311 cmse_address_info_t cmse_TTA (void *)
14312 cmse_address_info_t cmse_TTA_fptr (FPTR)
14313 cmse_address_info_t cmse_TTAT (void *)
14314 cmse_address_info_t cmse_TTAT_fptr (FPTR)
14315 void * cmse_check_address_range (void *, size_t, int)
14316 typeof(p) cmse_nsfptr_create (FPTR p)
14317 intptr_t cmse_is_nsfptr (FPTR)
14318 int cmse_nonsecure_caller (void)
14321 @node AVR Built-in Functions
14322 @subsection AVR Built-in Functions
14324 For each built-in function for AVR, there is an equally named,
14325 uppercase built-in macro defined. That way users can easily query if
14326 or if not a specific built-in is implemented or not. For example, if
14327 @code{__builtin_avr_nop} is available the macro
14328 @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise.
14332 @item void __builtin_avr_nop (void)
14333 @itemx void __builtin_avr_sei (void)
14334 @itemx void __builtin_avr_cli (void)
14335 @itemx void __builtin_avr_sleep (void)
14336 @itemx void __builtin_avr_wdr (void)
14337 @itemx unsigned char __builtin_avr_swap (unsigned char)
14338 @itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char)
14339 @itemx int __builtin_avr_fmuls (char, char)
14340 @itemx int __builtin_avr_fmulsu (char, unsigned char)
14341 These built-in functions map to the respective machine
14342 instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep},
14343 @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls}
14344 resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented
14345 as library call if no hardware multiplier is available.
14347 @item void __builtin_avr_delay_cycles (unsigned long ticks)
14348 Delay execution for @var{ticks} cycles. Note that this
14349 built-in does not take into account the effect of interrupts that
14350 might increase delay time. @var{ticks} must be a compile-time
14351 integer constant; delays with a variable number of cycles are not supported.
14353 @item char __builtin_avr_flash_segment (const __memx void*)
14354 This built-in takes a byte address to the 24-bit
14355 @ref{AVR Named Address Spaces,address space} @code{__memx} and returns
14356 the number of the flash segment (the 64 KiB chunk) where the address
14357 points to. Counting starts at @code{0}.
14358 If the address does not point to flash memory, return @code{-1}.
14360 @item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val)
14361 Insert bits from @var{bits} into @var{val} and return the resulting
14362 value. The nibbles of @var{map} determine how the insertion is
14363 performed: Let @var{X} be the @var{n}-th nibble of @var{map}
14365 @item If @var{X} is @code{0xf},
14366 then the @var{n}-th bit of @var{val} is returned unaltered.
14368 @item If X is in the range 0@dots{}7,
14369 then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits}
14371 @item If X is in the range 8@dots{}@code{0xe},
14372 then the @var{n}-th result bit is undefined.
14376 One typical use case for this built-in is adjusting input and
14377 output values to non-contiguous port layouts. Some examples:
14380 // same as val, bits is unused
14381 __builtin_avr_insert_bits (0xffffffff, bits, val)
14385 // same as bits, val is unused
14386 __builtin_avr_insert_bits (0x76543210, bits, val)
14390 // same as rotating bits by 4
14391 __builtin_avr_insert_bits (0x32107654, bits, 0)
14395 // high nibble of result is the high nibble of val
14396 // low nibble of result is the low nibble of bits
14397 __builtin_avr_insert_bits (0xffff3210, bits, val)
14401 // reverse the bit order of bits
14402 __builtin_avr_insert_bits (0x01234567, bits, 0)
14405 @item void __builtin_avr_nops (unsigned count)
14406 Insert @var{count} @code{NOP} instructions.
14407 The number of instructions must be a compile-time integer constant.
14412 There are many more AVR-specific built-in functions that are used to
14413 implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of
14414 section 7.18a.6. You don't need to use these built-ins directly.
14415 Instead, use the declarations as supplied by the @code{stdfix.h} header
14419 #include <stdfix.h>
14421 // Re-interpret the bit representation of unsigned 16-bit
14422 // integer @var{uval} as Q-format 0.16 value.
14423 unsigned fract get_bits (uint_ur_t uval)
14425 return urbits (uval);
14429 @node Blackfin Built-in Functions
14430 @subsection Blackfin Built-in Functions
14432 Currently, there are two Blackfin-specific built-in functions. These are
14433 used for generating @code{CSYNC} and @code{SSYNC} machine insns without
14434 using inline assembly; by using these built-in functions the compiler can
14435 automatically add workarounds for hardware errata involving these
14436 instructions. These functions are named as follows:
14439 void __builtin_bfin_csync (void)
14440 void __builtin_bfin_ssync (void)
14443 @node FR-V Built-in Functions
14444 @subsection FR-V Built-in Functions
14446 GCC provides many FR-V-specific built-in functions. In general,
14447 these functions are intended to be compatible with those described
14448 by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu
14449 Semiconductor}. The two exceptions are @code{__MDUNPACKH} and
14450 @code{__MBTOHE}, the GCC forms of which pass 128-bit values by
14451 pointer rather than by value.
14453 Most of the functions are named after specific FR-V instructions.
14454 Such functions are said to be ``directly mapped'' and are summarized
14455 here in tabular form.
14459 * Directly-mapped Integer Functions::
14460 * Directly-mapped Media Functions::
14461 * Raw read/write Functions::
14462 * Other Built-in Functions::
14465 @node Argument Types
14466 @subsubsection Argument Types
14468 The arguments to the built-in functions can be divided into three groups:
14469 register numbers, compile-time constants and run-time values. In order
14470 to make this classification clear at a glance, the arguments and return
14471 values are given the following pseudo types:
14473 @multitable @columnfractions .20 .30 .15 .35
14474 @item Pseudo type @tab Real C type @tab Constant? @tab Description
14475 @item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword
14476 @item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word
14477 @item @code{sw1} @tab @code{int} @tab No @tab a signed word
14478 @item @code{uw2} @tab @code{unsigned long long} @tab No
14479 @tab an unsigned doubleword
14480 @item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword
14481 @item @code{const} @tab @code{int} @tab Yes @tab an integer constant
14482 @item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number
14483 @item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number
14486 These pseudo types are not defined by GCC, they are simply a notational
14487 convenience used in this manual.
14489 Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2}
14490 and @code{sw2} are evaluated at run time. They correspond to
14491 register operands in the underlying FR-V instructions.
14493 @code{const} arguments represent immediate operands in the underlying
14494 FR-V instructions. They must be compile-time constants.
14496 @code{acc} arguments are evaluated at compile time and specify the number
14497 of an accumulator register. For example, an @code{acc} argument of 2
14498 selects the ACC2 register.
14500 @code{iacc} arguments are similar to @code{acc} arguments but specify the
14501 number of an IACC register. See @pxref{Other Built-in Functions}
14504 @node Directly-mapped Integer Functions
14505 @subsubsection Directly-Mapped Integer Functions
14507 The functions listed below map directly to FR-V I-type instructions.
14509 @multitable @columnfractions .45 .32 .23
14510 @item Function prototype @tab Example usage @tab Assembly output
14511 @item @code{sw1 __ADDSS (sw1, sw1)}
14512 @tab @code{@var{c} = __ADDSS (@var{a}, @var{b})}
14513 @tab @code{ADDSS @var{a},@var{b},@var{c}}
14514 @item @code{sw1 __SCAN (sw1, sw1)}
14515 @tab @code{@var{c} = __SCAN (@var{a}, @var{b})}
14516 @tab @code{SCAN @var{a},@var{b},@var{c}}
14517 @item @code{sw1 __SCUTSS (sw1)}
14518 @tab @code{@var{b} = __SCUTSS (@var{a})}
14519 @tab @code{SCUTSS @var{a},@var{b}}
14520 @item @code{sw1 __SLASS (sw1, sw1)}
14521 @tab @code{@var{c} = __SLASS (@var{a}, @var{b})}
14522 @tab @code{SLASS @var{a},@var{b},@var{c}}
14523 @item @code{void __SMASS (sw1, sw1)}
14524 @tab @code{__SMASS (@var{a}, @var{b})}
14525 @tab @code{SMASS @var{a},@var{b}}
14526 @item @code{void __SMSSS (sw1, sw1)}
14527 @tab @code{__SMSSS (@var{a}, @var{b})}
14528 @tab @code{SMSSS @var{a},@var{b}}
14529 @item @code{void __SMU (sw1, sw1)}
14530 @tab @code{__SMU (@var{a}, @var{b})}
14531 @tab @code{SMU @var{a},@var{b}}
14532 @item @code{sw2 __SMUL (sw1, sw1)}
14533 @tab @code{@var{c} = __SMUL (@var{a}, @var{b})}
14534 @tab @code{SMUL @var{a},@var{b},@var{c}}
14535 @item @code{sw1 __SUBSS (sw1, sw1)}
14536 @tab @code{@var{c} = __SUBSS (@var{a}, @var{b})}
14537 @tab @code{SUBSS @var{a},@var{b},@var{c}}
14538 @item @code{uw2 __UMUL (uw1, uw1)}
14539 @tab @code{@var{c} = __UMUL (@var{a}, @var{b})}
14540 @tab @code{UMUL @var{a},@var{b},@var{c}}
14543 @node Directly-mapped Media Functions
14544 @subsubsection Directly-Mapped Media Functions
14546 The functions listed below map directly to FR-V M-type instructions.
14548 @multitable @columnfractions .45 .32 .23
14549 @item Function prototype @tab Example usage @tab Assembly output
14550 @item @code{uw1 __MABSHS (sw1)}
14551 @tab @code{@var{b} = __MABSHS (@var{a})}
14552 @tab @code{MABSHS @var{a},@var{b}}
14553 @item @code{void __MADDACCS (acc, acc)}
14554 @tab @code{__MADDACCS (@var{b}, @var{a})}
14555 @tab @code{MADDACCS @var{a},@var{b}}
14556 @item @code{sw1 __MADDHSS (sw1, sw1)}
14557 @tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})}
14558 @tab @code{MADDHSS @var{a},@var{b},@var{c}}
14559 @item @code{uw1 __MADDHUS (uw1, uw1)}
14560 @tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})}
14561 @tab @code{MADDHUS @var{a},@var{b},@var{c}}
14562 @item @code{uw1 __MAND (uw1, uw1)}
14563 @tab @code{@var{c} = __MAND (@var{a}, @var{b})}
14564 @tab @code{MAND @var{a},@var{b},@var{c}}
14565 @item @code{void __MASACCS (acc, acc)}
14566 @tab @code{__MASACCS (@var{b}, @var{a})}
14567 @tab @code{MASACCS @var{a},@var{b}}
14568 @item @code{uw1 __MAVEH (uw1, uw1)}
14569 @tab @code{@var{c} = __MAVEH (@var{a}, @var{b})}
14570 @tab @code{MAVEH @var{a},@var{b},@var{c}}
14571 @item @code{uw2 __MBTOH (uw1)}
14572 @tab @code{@var{b} = __MBTOH (@var{a})}
14573 @tab @code{MBTOH @var{a},@var{b}}
14574 @item @code{void __MBTOHE (uw1 *, uw1)}
14575 @tab @code{__MBTOHE (&@var{b}, @var{a})}
14576 @tab @code{MBTOHE @var{a},@var{b}}
14577 @item @code{void __MCLRACC (acc)}
14578 @tab @code{__MCLRACC (@var{a})}
14579 @tab @code{MCLRACC @var{a}}
14580 @item @code{void __MCLRACCA (void)}
14581 @tab @code{__MCLRACCA ()}
14582 @tab @code{MCLRACCA}
14583 @item @code{uw1 __Mcop1 (uw1, uw1)}
14584 @tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})}
14585 @tab @code{Mcop1 @var{a},@var{b},@var{c}}
14586 @item @code{uw1 __Mcop2 (uw1, uw1)}
14587 @tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})}
14588 @tab @code{Mcop2 @var{a},@var{b},@var{c}}
14589 @item @code{uw1 __MCPLHI (uw2, const)}
14590 @tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})}
14591 @tab @code{MCPLHI @var{a},#@var{b},@var{c}}
14592 @item @code{uw1 __MCPLI (uw2, const)}
14593 @tab @code{@var{c} = __MCPLI (@var{a}, @var{b})}
14594 @tab @code{MCPLI @var{a},#@var{b},@var{c}}
14595 @item @code{void __MCPXIS (acc, sw1, sw1)}
14596 @tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})}
14597 @tab @code{MCPXIS @var{a},@var{b},@var{c}}
14598 @item @code{void __MCPXIU (acc, uw1, uw1)}
14599 @tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})}
14600 @tab @code{MCPXIU @var{a},@var{b},@var{c}}
14601 @item @code{void __MCPXRS (acc, sw1, sw1)}
14602 @tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})}
14603 @tab @code{MCPXRS @var{a},@var{b},@var{c}}
14604 @item @code{void __MCPXRU (acc, uw1, uw1)}
14605 @tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})}
14606 @tab @code{MCPXRU @var{a},@var{b},@var{c}}
14607 @item @code{uw1 __MCUT (acc, uw1)}
14608 @tab @code{@var{c} = __MCUT (@var{a}, @var{b})}
14609 @tab @code{MCUT @var{a},@var{b},@var{c}}
14610 @item @code{uw1 __MCUTSS (acc, sw1)}
14611 @tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})}
14612 @tab @code{MCUTSS @var{a},@var{b},@var{c}}
14613 @item @code{void __MDADDACCS (acc, acc)}
14614 @tab @code{__MDADDACCS (@var{b}, @var{a})}
14615 @tab @code{MDADDACCS @var{a},@var{b}}
14616 @item @code{void __MDASACCS (acc, acc)}
14617 @tab @code{__MDASACCS (@var{b}, @var{a})}
14618 @tab @code{MDASACCS @var{a},@var{b}}
14619 @item @code{uw2 __MDCUTSSI (acc, const)}
14620 @tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})}
14621 @tab @code{MDCUTSSI @var{a},#@var{b},@var{c}}
14622 @item @code{uw2 __MDPACKH (uw2, uw2)}
14623 @tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})}
14624 @tab @code{MDPACKH @var{a},@var{b},@var{c}}
14625 @item @code{uw2 __MDROTLI (uw2, const)}
14626 @tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})}
14627 @tab @code{MDROTLI @var{a},#@var{b},@var{c}}
14628 @item @code{void __MDSUBACCS (acc, acc)}
14629 @tab @code{__MDSUBACCS (@var{b}, @var{a})}
14630 @tab @code{MDSUBACCS @var{a},@var{b}}
14631 @item @code{void __MDUNPACKH (uw1 *, uw2)}
14632 @tab @code{__MDUNPACKH (&@var{b}, @var{a})}
14633 @tab @code{MDUNPACKH @var{a},@var{b}}
14634 @item @code{uw2 __MEXPDHD (uw1, const)}
14635 @tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})}
14636 @tab @code{MEXPDHD @var{a},#@var{b},@var{c}}
14637 @item @code{uw1 __MEXPDHW (uw1, const)}
14638 @tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})}
14639 @tab @code{MEXPDHW @var{a},#@var{b},@var{c}}
14640 @item @code{uw1 __MHDSETH (uw1, const)}
14641 @tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})}
14642 @tab @code{MHDSETH @var{a},#@var{b},@var{c}}
14643 @item @code{sw1 __MHDSETS (const)}
14644 @tab @code{@var{b} = __MHDSETS (@var{a})}
14645 @tab @code{MHDSETS #@var{a},@var{b}}
14646 @item @code{uw1 __MHSETHIH (uw1, const)}
14647 @tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})}
14648 @tab @code{MHSETHIH #@var{a},@var{b}}
14649 @item @code{sw1 __MHSETHIS (sw1, const)}
14650 @tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})}
14651 @tab @code{MHSETHIS #@var{a},@var{b}}
14652 @item @code{uw1 __MHSETLOH (uw1, const)}
14653 @tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})}
14654 @tab @code{MHSETLOH #@var{a},@var{b}}
14655 @item @code{sw1 __MHSETLOS (sw1, const)}
14656 @tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})}
14657 @tab @code{MHSETLOS #@var{a},@var{b}}
14658 @item @code{uw1 __MHTOB (uw2)}
14659 @tab @code{@var{b} = __MHTOB (@var{a})}
14660 @tab @code{MHTOB @var{a},@var{b}}
14661 @item @code{void __MMACHS (acc, sw1, sw1)}
14662 @tab @code{__MMACHS (@var{c}, @var{a}, @var{b})}
14663 @tab @code{MMACHS @var{a},@var{b},@var{c}}
14664 @item @code{void __MMACHU (acc, uw1, uw1)}
14665 @tab @code{__MMACHU (@var{c}, @var{a}, @var{b})}
14666 @tab @code{MMACHU @var{a},@var{b},@var{c}}
14667 @item @code{void __MMRDHS (acc, sw1, sw1)}
14668 @tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})}
14669 @tab @code{MMRDHS @var{a},@var{b},@var{c}}
14670 @item @code{void __MMRDHU (acc, uw1, uw1)}
14671 @tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})}
14672 @tab @code{MMRDHU @var{a},@var{b},@var{c}}
14673 @item @code{void __MMULHS (acc, sw1, sw1)}
14674 @tab @code{__MMULHS (@var{c}, @var{a}, @var{b})}
14675 @tab @code{MMULHS @var{a},@var{b},@var{c}}
14676 @item @code{void __MMULHU (acc, uw1, uw1)}
14677 @tab @code{__MMULHU (@var{c}, @var{a}, @var{b})}
14678 @tab @code{MMULHU @var{a},@var{b},@var{c}}
14679 @item @code{void __MMULXHS (acc, sw1, sw1)}
14680 @tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})}
14681 @tab @code{MMULXHS @var{a},@var{b},@var{c}}
14682 @item @code{void __MMULXHU (acc, uw1, uw1)}
14683 @tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})}
14684 @tab @code{MMULXHU @var{a},@var{b},@var{c}}
14685 @item @code{uw1 __MNOT (uw1)}
14686 @tab @code{@var{b} = __MNOT (@var{a})}
14687 @tab @code{MNOT @var{a},@var{b}}
14688 @item @code{uw1 __MOR (uw1, uw1)}
14689 @tab @code{@var{c} = __MOR (@var{a}, @var{b})}
14690 @tab @code{MOR @var{a},@var{b},@var{c}}
14691 @item @code{uw1 __MPACKH (uh, uh)}
14692 @tab @code{@var{c} = __MPACKH (@var{a}, @var{b})}
14693 @tab @code{MPACKH @var{a},@var{b},@var{c}}
14694 @item @code{sw2 __MQADDHSS (sw2, sw2)}
14695 @tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})}
14696 @tab @code{MQADDHSS @var{a},@var{b},@var{c}}
14697 @item @code{uw2 __MQADDHUS (uw2, uw2)}
14698 @tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})}
14699 @tab @code{MQADDHUS @var{a},@var{b},@var{c}}
14700 @item @code{void __MQCPXIS (acc, sw2, sw2)}
14701 @tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})}
14702 @tab @code{MQCPXIS @var{a},@var{b},@var{c}}
14703 @item @code{void __MQCPXIU (acc, uw2, uw2)}
14704 @tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})}
14705 @tab @code{MQCPXIU @var{a},@var{b},@var{c}}
14706 @item @code{void __MQCPXRS (acc, sw2, sw2)}
14707 @tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})}
14708 @tab @code{MQCPXRS @var{a},@var{b},@var{c}}
14709 @item @code{void __MQCPXRU (acc, uw2, uw2)}
14710 @tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})}
14711 @tab @code{MQCPXRU @var{a},@var{b},@var{c}}
14712 @item @code{sw2 __MQLCLRHS (sw2, sw2)}
14713 @tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})}
14714 @tab @code{MQLCLRHS @var{a},@var{b},@var{c}}
14715 @item @code{sw2 __MQLMTHS (sw2, sw2)}
14716 @tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})}
14717 @tab @code{MQLMTHS @var{a},@var{b},@var{c}}
14718 @item @code{void __MQMACHS (acc, sw2, sw2)}
14719 @tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})}
14720 @tab @code{MQMACHS @var{a},@var{b},@var{c}}
14721 @item @code{void __MQMACHU (acc, uw2, uw2)}
14722 @tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})}
14723 @tab @code{MQMACHU @var{a},@var{b},@var{c}}
14724 @item @code{void __MQMACXHS (acc, sw2, sw2)}
14725 @tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})}
14726 @tab @code{MQMACXHS @var{a},@var{b},@var{c}}
14727 @item @code{void __MQMULHS (acc, sw2, sw2)}
14728 @tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})}
14729 @tab @code{MQMULHS @var{a},@var{b},@var{c}}
14730 @item @code{void __MQMULHU (acc, uw2, uw2)}
14731 @tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})}
14732 @tab @code{MQMULHU @var{a},@var{b},@var{c}}
14733 @item @code{void __MQMULXHS (acc, sw2, sw2)}
14734 @tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})}
14735 @tab @code{MQMULXHS @var{a},@var{b},@var{c}}
14736 @item @code{void __MQMULXHU (acc, uw2, uw2)}
14737 @tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})}
14738 @tab @code{MQMULXHU @var{a},@var{b},@var{c}}
14739 @item @code{sw2 __MQSATHS (sw2, sw2)}
14740 @tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})}
14741 @tab @code{MQSATHS @var{a},@var{b},@var{c}}
14742 @item @code{uw2 __MQSLLHI (uw2, int)}
14743 @tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})}
14744 @tab @code{MQSLLHI @var{a},@var{b},@var{c}}
14745 @item @code{sw2 __MQSRAHI (sw2, int)}
14746 @tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})}
14747 @tab @code{MQSRAHI @var{a},@var{b},@var{c}}
14748 @item @code{sw2 __MQSUBHSS (sw2, sw2)}
14749 @tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})}
14750 @tab @code{MQSUBHSS @var{a},@var{b},@var{c}}
14751 @item @code{uw2 __MQSUBHUS (uw2, uw2)}
14752 @tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})}
14753 @tab @code{MQSUBHUS @var{a},@var{b},@var{c}}
14754 @item @code{void __MQXMACHS (acc, sw2, sw2)}
14755 @tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})}
14756 @tab @code{MQXMACHS @var{a},@var{b},@var{c}}
14757 @item @code{void __MQXMACXHS (acc, sw2, sw2)}
14758 @tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})}
14759 @tab @code{MQXMACXHS @var{a},@var{b},@var{c}}
14760 @item @code{uw1 __MRDACC (acc)}
14761 @tab @code{@var{b} = __MRDACC (@var{a})}
14762 @tab @code{MRDACC @var{a},@var{b}}
14763 @item @code{uw1 __MRDACCG (acc)}
14764 @tab @code{@var{b} = __MRDACCG (@var{a})}
14765 @tab @code{MRDACCG @var{a},@var{b}}
14766 @item @code{uw1 __MROTLI (uw1, const)}
14767 @tab @code{@var{c} = __MROTLI (@var{a}, @var{b})}
14768 @tab @code{MROTLI @var{a},#@var{b},@var{c}}
14769 @item @code{uw1 __MROTRI (uw1, const)}
14770 @tab @code{@var{c} = __MROTRI (@var{a}, @var{b})}
14771 @tab @code{MROTRI @var{a},#@var{b},@var{c}}
14772 @item @code{sw1 __MSATHS (sw1, sw1)}
14773 @tab @code{@var{c} = __MSATHS (@var{a}, @var{b})}
14774 @tab @code{MSATHS @var{a},@var{b},@var{c}}
14775 @item @code{uw1 __MSATHU (uw1, uw1)}
14776 @tab @code{@var{c} = __MSATHU (@var{a}, @var{b})}
14777 @tab @code{MSATHU @var{a},@var{b},@var{c}}
14778 @item @code{uw1 __MSLLHI (uw1, const)}
14779 @tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})}
14780 @tab @code{MSLLHI @var{a},#@var{b},@var{c}}
14781 @item @code{sw1 __MSRAHI (sw1, const)}
14782 @tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})}
14783 @tab @code{MSRAHI @var{a},#@var{b},@var{c}}
14784 @item @code{uw1 __MSRLHI (uw1, const)}
14785 @tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})}
14786 @tab @code{MSRLHI @var{a},#@var{b},@var{c}}
14787 @item @code{void __MSUBACCS (acc, acc)}
14788 @tab @code{__MSUBACCS (@var{b}, @var{a})}
14789 @tab @code{MSUBACCS @var{a},@var{b}}
14790 @item @code{sw1 __MSUBHSS (sw1, sw1)}
14791 @tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})}
14792 @tab @code{MSUBHSS @var{a},@var{b},@var{c}}
14793 @item @code{uw1 __MSUBHUS (uw1, uw1)}
14794 @tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})}
14795 @tab @code{MSUBHUS @var{a},@var{b},@var{c}}
14796 @item @code{void __MTRAP (void)}
14797 @tab @code{__MTRAP ()}
14799 @item @code{uw2 __MUNPACKH (uw1)}
14800 @tab @code{@var{b} = __MUNPACKH (@var{a})}
14801 @tab @code{MUNPACKH @var{a},@var{b}}
14802 @item @code{uw1 __MWCUT (uw2, uw1)}
14803 @tab @code{@var{c} = __MWCUT (@var{a}, @var{b})}
14804 @tab @code{MWCUT @var{a},@var{b},@var{c}}
14805 @item @code{void __MWTACC (acc, uw1)}
14806 @tab @code{__MWTACC (@var{b}, @var{a})}
14807 @tab @code{MWTACC @var{a},@var{b}}
14808 @item @code{void __MWTACCG (acc, uw1)}
14809 @tab @code{__MWTACCG (@var{b}, @var{a})}
14810 @tab @code{MWTACCG @var{a},@var{b}}
14811 @item @code{uw1 __MXOR (uw1, uw1)}
14812 @tab @code{@var{c} = __MXOR (@var{a}, @var{b})}
14813 @tab @code{MXOR @var{a},@var{b},@var{c}}
14816 @node Raw read/write Functions
14817 @subsubsection Raw Read/Write Functions
14819 This sections describes built-in functions related to read and write
14820 instructions to access memory. These functions generate
14821 @code{membar} instructions to flush the I/O load and stores where
14822 appropriate, as described in Fujitsu's manual described above.
14826 @item unsigned char __builtin_read8 (void *@var{data})
14827 @item unsigned short __builtin_read16 (void *@var{data})
14828 @item unsigned long __builtin_read32 (void *@var{data})
14829 @item unsigned long long __builtin_read64 (void *@var{data})
14831 @item void __builtin_write8 (void *@var{data}, unsigned char @var{datum})
14832 @item void __builtin_write16 (void *@var{data}, unsigned short @var{datum})
14833 @item void __builtin_write32 (void *@var{data}, unsigned long @var{datum})
14834 @item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum})
14837 @node Other Built-in Functions
14838 @subsubsection Other Built-in Functions
14840 This section describes built-in functions that are not named after
14841 a specific FR-V instruction.
14844 @item sw2 __IACCreadll (iacc @var{reg})
14845 Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved
14846 for future expansion and must be 0.
14848 @item sw1 __IACCreadl (iacc @var{reg})
14849 Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1.
14850 Other values of @var{reg} are rejected as invalid.
14852 @item void __IACCsetll (iacc @var{reg}, sw2 @var{x})
14853 Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument
14854 is reserved for future expansion and must be 0.
14856 @item void __IACCsetl (iacc @var{reg}, sw1 @var{x})
14857 Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg}
14858 is 1. Other values of @var{reg} are rejected as invalid.
14860 @item void __data_prefetch0 (const void *@var{x})
14861 Use the @code{dcpl} instruction to load the contents of address @var{x}
14862 into the data cache.
14864 @item void __data_prefetch (const void *@var{x})
14865 Use the @code{nldub} instruction to load the contents of address @var{x}
14866 into the data cache. The instruction is issued in slot I1@.
14869 @node MIPS DSP Built-in Functions
14870 @subsection MIPS DSP Built-in Functions
14872 The MIPS DSP Application-Specific Extension (ASE) includes new
14873 instructions that are designed to improve the performance of DSP and
14874 media applications. It provides instructions that operate on packed
14875 8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data.
14877 GCC supports MIPS DSP operations using both the generic
14878 vector extensions (@pxref{Vector Extensions}) and a collection of
14879 MIPS-specific built-in functions. Both kinds of support are
14880 enabled by the @option{-mdsp} command-line option.
14882 Revision 2 of the ASE was introduced in the second half of 2006.
14883 This revision adds extra instructions to the original ASE, but is
14884 otherwise backwards-compatible with it. You can select revision 2
14885 using the command-line option @option{-mdspr2}; this option implies
14888 The SCOUNT and POS bits of the DSP control register are global. The
14889 WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and
14890 POS bits. During optimization, the compiler does not delete these
14891 instructions and it does not delete calls to functions containing
14892 these instructions.
14894 At present, GCC only provides support for operations on 32-bit
14895 vectors. The vector type associated with 8-bit integer data is
14896 usually called @code{v4i8}, the vector type associated with Q7
14897 is usually called @code{v4q7}, the vector type associated with 16-bit
14898 integer data is usually called @code{v2i16}, and the vector type
14899 associated with Q15 is usually called @code{v2q15}. They can be
14900 defined in C as follows:
14903 typedef signed char v4i8 __attribute__ ((vector_size(4)));
14904 typedef signed char v4q7 __attribute__ ((vector_size(4)));
14905 typedef short v2i16 __attribute__ ((vector_size(4)));
14906 typedef short v2q15 __attribute__ ((vector_size(4)));
14909 @code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are
14910 initialized in the same way as aggregates. For example:
14913 v4i8 a = @{1, 2, 3, 4@};
14915 b = (v4i8) @{5, 6, 7, 8@};
14917 v2q15 c = @{0x0fcb, 0x3a75@};
14919 d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@};
14922 @emph{Note:} The CPU's endianness determines the order in which values
14923 are packed. On little-endian targets, the first value is the least
14924 significant and the last value is the most significant. The opposite
14925 order applies to big-endian targets. For example, the code above
14926 sets the lowest byte of @code{a} to @code{1} on little-endian targets
14927 and @code{4} on big-endian targets.
14929 @emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer
14930 representation. As shown in this example, the integer representation
14931 of a Q7 value can be obtained by multiplying the fractional value by
14932 @code{0x1.0p7}. The equivalent for Q15 values is to multiply by
14933 @code{0x1.0p15}. The equivalent for Q31 values is to multiply by
14936 The table below lists the @code{v4i8} and @code{v2q15} operations for which
14937 hardware support exists. @code{a} and @code{b} are @code{v4i8} values,
14938 and @code{c} and @code{d} are @code{v2q15} values.
14940 @multitable @columnfractions .50 .50
14941 @item C code @tab MIPS instruction
14942 @item @code{a + b} @tab @code{addu.qb}
14943 @item @code{c + d} @tab @code{addq.ph}
14944 @item @code{a - b} @tab @code{subu.qb}
14945 @item @code{c - d} @tab @code{subq.ph}
14948 The table below lists the @code{v2i16} operation for which
14949 hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are
14950 @code{v2i16} values.
14952 @multitable @columnfractions .50 .50
14953 @item C code @tab MIPS instruction
14954 @item @code{e * f} @tab @code{mul.ph}
14957 It is easier to describe the DSP built-in functions if we first define
14958 the following types:
14963 typedef unsigned int ui32;
14964 typedef long long a64;
14967 @code{q31} and @code{i32} are actually the same as @code{int}, but we
14968 use @code{q31} to indicate a Q31 fractional value and @code{i32} to
14969 indicate a 32-bit integer value. Similarly, @code{a64} is the same as
14970 @code{long long}, but we use @code{a64} to indicate values that are
14971 placed in one of the four DSP accumulators (@code{$ac0},
14972 @code{$ac1}, @code{$ac2} or @code{$ac3}).
14974 Also, some built-in functions prefer or require immediate numbers as
14975 parameters, because the corresponding DSP instructions accept both immediate
14976 numbers and register operands, or accept immediate numbers only. The
14977 immediate parameters are listed as follows.
14985 imm0_255: 0 to 255.
14986 imm_n32_31: -32 to 31.
14987 imm_n512_511: -512 to 511.
14990 The following built-in functions map directly to a particular MIPS DSP
14991 instruction. Please refer to the architecture specification
14992 for details on what each instruction does.
14995 v2q15 __builtin_mips_addq_ph (v2q15, v2q15)
14996 v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15)
14997 q31 __builtin_mips_addq_s_w (q31, q31)
14998 v4i8 __builtin_mips_addu_qb (v4i8, v4i8)
14999 v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8)
15000 v2q15 __builtin_mips_subq_ph (v2q15, v2q15)
15001 v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15)
15002 q31 __builtin_mips_subq_s_w (q31, q31)
15003 v4i8 __builtin_mips_subu_qb (v4i8, v4i8)
15004 v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8)
15005 i32 __builtin_mips_addsc (i32, i32)
15006 i32 __builtin_mips_addwc (i32, i32)
15007 i32 __builtin_mips_modsub (i32, i32)
15008 i32 __builtin_mips_raddu_w_qb (v4i8)
15009 v2q15 __builtin_mips_absq_s_ph (v2q15)
15010 q31 __builtin_mips_absq_s_w (q31)
15011 v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15)
15012 v2q15 __builtin_mips_precrq_ph_w (q31, q31)
15013 v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31)
15014 v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15)
15015 q31 __builtin_mips_preceq_w_phl (v2q15)
15016 q31 __builtin_mips_preceq_w_phr (v2q15)
15017 v2q15 __builtin_mips_precequ_ph_qbl (v4i8)
15018 v2q15 __builtin_mips_precequ_ph_qbr (v4i8)
15019 v2q15 __builtin_mips_precequ_ph_qbla (v4i8)
15020 v2q15 __builtin_mips_precequ_ph_qbra (v4i8)
15021 v2q15 __builtin_mips_preceu_ph_qbl (v4i8)
15022 v2q15 __builtin_mips_preceu_ph_qbr (v4i8)
15023 v2q15 __builtin_mips_preceu_ph_qbla (v4i8)
15024 v2q15 __builtin_mips_preceu_ph_qbra (v4i8)
15025 v4i8 __builtin_mips_shll_qb (v4i8, imm0_7)
15026 v4i8 __builtin_mips_shll_qb (v4i8, i32)
15027 v2q15 __builtin_mips_shll_ph (v2q15, imm0_15)
15028 v2q15 __builtin_mips_shll_ph (v2q15, i32)
15029 v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15)
15030 v2q15 __builtin_mips_shll_s_ph (v2q15, i32)
15031 q31 __builtin_mips_shll_s_w (q31, imm0_31)
15032 q31 __builtin_mips_shll_s_w (q31, i32)
15033 v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7)
15034 v4i8 __builtin_mips_shrl_qb (v4i8, i32)
15035 v2q15 __builtin_mips_shra_ph (v2q15, imm0_15)
15036 v2q15 __builtin_mips_shra_ph (v2q15, i32)
15037 v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15)
15038 v2q15 __builtin_mips_shra_r_ph (v2q15, i32)
15039 q31 __builtin_mips_shra_r_w (q31, imm0_31)
15040 q31 __builtin_mips_shra_r_w (q31, i32)
15041 v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15)
15042 v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15)
15043 v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15)
15044 q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15)
15045 q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15)
15046 a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8)
15047 a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8)
15048 a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8)
15049 a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8)
15050 a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15)
15051 a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31)
15052 a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15)
15053 a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31)
15054 a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15)
15055 a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15)
15056 a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15)
15057 a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15)
15058 a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15)
15059 i32 __builtin_mips_bitrev (i32)
15060 i32 __builtin_mips_insv (i32, i32)
15061 v4i8 __builtin_mips_repl_qb (imm0_255)
15062 v4i8 __builtin_mips_repl_qb (i32)
15063 v2q15 __builtin_mips_repl_ph (imm_n512_511)
15064 v2q15 __builtin_mips_repl_ph (i32)
15065 void __builtin_mips_cmpu_eq_qb (v4i8, v4i8)
15066 void __builtin_mips_cmpu_lt_qb (v4i8, v4i8)
15067 void __builtin_mips_cmpu_le_qb (v4i8, v4i8)
15068 i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8)
15069 i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8)
15070 i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8)
15071 void __builtin_mips_cmp_eq_ph (v2q15, v2q15)
15072 void __builtin_mips_cmp_lt_ph (v2q15, v2q15)
15073 void __builtin_mips_cmp_le_ph (v2q15, v2q15)
15074 v4i8 __builtin_mips_pick_qb (v4i8, v4i8)
15075 v2q15 __builtin_mips_pick_ph (v2q15, v2q15)
15076 v2q15 __builtin_mips_packrl_ph (v2q15, v2q15)
15077 i32 __builtin_mips_extr_w (a64, imm0_31)
15078 i32 __builtin_mips_extr_w (a64, i32)
15079 i32 __builtin_mips_extr_r_w (a64, imm0_31)
15080 i32 __builtin_mips_extr_s_h (a64, i32)
15081 i32 __builtin_mips_extr_rs_w (a64, imm0_31)
15082 i32 __builtin_mips_extr_rs_w (a64, i32)
15083 i32 __builtin_mips_extr_s_h (a64, imm0_31)
15084 i32 __builtin_mips_extr_r_w (a64, i32)
15085 i32 __builtin_mips_extp (a64, imm0_31)
15086 i32 __builtin_mips_extp (a64, i32)
15087 i32 __builtin_mips_extpdp (a64, imm0_31)
15088 i32 __builtin_mips_extpdp (a64, i32)
15089 a64 __builtin_mips_shilo (a64, imm_n32_31)
15090 a64 __builtin_mips_shilo (a64, i32)
15091 a64 __builtin_mips_mthlip (a64, i32)
15092 void __builtin_mips_wrdsp (i32, imm0_63)
15093 i32 __builtin_mips_rddsp (imm0_63)
15094 i32 __builtin_mips_lbux (void *, i32)
15095 i32 __builtin_mips_lhx (void *, i32)
15096 i32 __builtin_mips_lwx (void *, i32)
15097 a64 __builtin_mips_ldx (void *, i32) [MIPS64 only]
15098 i32 __builtin_mips_bposge32 (void)
15099 a64 __builtin_mips_madd (a64, i32, i32);
15100 a64 __builtin_mips_maddu (a64, ui32, ui32);
15101 a64 __builtin_mips_msub (a64, i32, i32);
15102 a64 __builtin_mips_msubu (a64, ui32, ui32);
15103 a64 __builtin_mips_mult (i32, i32);
15104 a64 __builtin_mips_multu (ui32, ui32);
15107 The following built-in functions map directly to a particular MIPS DSP REV 2
15108 instruction. Please refer to the architecture specification
15109 for details on what each instruction does.
15112 v4q7 __builtin_mips_absq_s_qb (v4q7);
15113 v2i16 __builtin_mips_addu_ph (v2i16, v2i16);
15114 v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16);
15115 v4i8 __builtin_mips_adduh_qb (v4i8, v4i8);
15116 v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8);
15117 i32 __builtin_mips_append (i32, i32, imm0_31);
15118 i32 __builtin_mips_balign (i32, i32, imm0_3);
15119 i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8);
15120 i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8);
15121 i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8);
15122 a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16);
15123 a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16);
15124 v2i16 __builtin_mips_mul_ph (v2i16, v2i16);
15125 v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16);
15126 q31 __builtin_mips_mulq_rs_w (q31, q31);
15127 v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15);
15128 q31 __builtin_mips_mulq_s_w (q31, q31);
15129 a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16);
15130 v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16);
15131 v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31);
15132 v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31);
15133 i32 __builtin_mips_prepend (i32, i32, imm0_31);
15134 v4i8 __builtin_mips_shra_qb (v4i8, imm0_7);
15135 v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7);
15136 v4i8 __builtin_mips_shra_qb (v4i8, i32);
15137 v4i8 __builtin_mips_shra_r_qb (v4i8, i32);
15138 v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15);
15139 v2i16 __builtin_mips_shrl_ph (v2i16, i32);
15140 v2i16 __builtin_mips_subu_ph (v2i16, v2i16);
15141 v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16);
15142 v4i8 __builtin_mips_subuh_qb (v4i8, v4i8);
15143 v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8);
15144 v2q15 __builtin_mips_addqh_ph (v2q15, v2q15);
15145 v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15);
15146 q31 __builtin_mips_addqh_w (q31, q31);
15147 q31 __builtin_mips_addqh_r_w (q31, q31);
15148 v2q15 __builtin_mips_subqh_ph (v2q15, v2q15);
15149 v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15);
15150 q31 __builtin_mips_subqh_w (q31, q31);
15151 q31 __builtin_mips_subqh_r_w (q31, q31);
15152 a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16);
15153 a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16);
15154 a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15);
15155 a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15);
15156 a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15);
15157 a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15);
15161 @node MIPS Paired-Single Support
15162 @subsection MIPS Paired-Single Support
15164 The MIPS64 architecture includes a number of instructions that
15165 operate on pairs of single-precision floating-point values.
15166 Each pair is packed into a 64-bit floating-point register,
15167 with one element being designated the ``upper half'' and
15168 the other being designated the ``lower half''.
15170 GCC supports paired-single operations using both the generic
15171 vector extensions (@pxref{Vector Extensions}) and a collection of
15172 MIPS-specific built-in functions. Both kinds of support are
15173 enabled by the @option{-mpaired-single} command-line option.
15175 The vector type associated with paired-single values is usually
15176 called @code{v2sf}. It can be defined in C as follows:
15179 typedef float v2sf __attribute__ ((vector_size (8)));
15182 @code{v2sf} values are initialized in the same way as aggregates.
15186 v2sf a = @{1.5, 9.1@};
15189 b = (v2sf) @{e, f@};
15192 @emph{Note:} The CPU's endianness determines which value is stored in
15193 the upper half of a register and which value is stored in the lower half.
15194 On little-endian targets, the first value is the lower one and the second
15195 value is the upper one. The opposite order applies to big-endian targets.
15196 For example, the code above sets the lower half of @code{a} to
15197 @code{1.5} on little-endian targets and @code{9.1} on big-endian targets.
15199 @node MIPS Loongson Built-in Functions
15200 @subsection MIPS Loongson Built-in Functions
15202 GCC provides intrinsics to access the SIMD instructions provided by the
15203 ST Microelectronics Loongson-2E and -2F processors. These intrinsics,
15204 available after inclusion of the @code{loongson.h} header file,
15205 operate on the following 64-bit vector types:
15208 @item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers;
15209 @item @code{uint16x4_t}, a vector of four unsigned 16-bit integers;
15210 @item @code{uint32x2_t}, a vector of two unsigned 32-bit integers;
15211 @item @code{int8x8_t}, a vector of eight signed 8-bit integers;
15212 @item @code{int16x4_t}, a vector of four signed 16-bit integers;
15213 @item @code{int32x2_t}, a vector of two signed 32-bit integers.
15216 The intrinsics provided are listed below; each is named after the
15217 machine instruction to which it corresponds, with suffixes added as
15218 appropriate to distinguish intrinsics that expand to the same machine
15219 instruction yet have different argument types. Refer to the architecture
15220 documentation for a description of the functionality of each
15224 int16x4_t packsswh (int32x2_t s, int32x2_t t);
15225 int8x8_t packsshb (int16x4_t s, int16x4_t t);
15226 uint8x8_t packushb (uint16x4_t s, uint16x4_t t);
15227 uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t);
15228 uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t);
15229 uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t);
15230 int32x2_t paddw_s (int32x2_t s, int32x2_t t);
15231 int16x4_t paddh_s (int16x4_t s, int16x4_t t);
15232 int8x8_t paddb_s (int8x8_t s, int8x8_t t);
15233 uint64_t paddd_u (uint64_t s, uint64_t t);
15234 int64_t paddd_s (int64_t s, int64_t t);
15235 int16x4_t paddsh (int16x4_t s, int16x4_t t);
15236 int8x8_t paddsb (int8x8_t s, int8x8_t t);
15237 uint16x4_t paddush (uint16x4_t s, uint16x4_t t);
15238 uint8x8_t paddusb (uint8x8_t s, uint8x8_t t);
15239 uint64_t pandn_ud (uint64_t s, uint64_t t);
15240 uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t);
15241 uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t);
15242 uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t);
15243 int64_t pandn_sd (int64_t s, int64_t t);
15244 int32x2_t pandn_sw (int32x2_t s, int32x2_t t);
15245 int16x4_t pandn_sh (int16x4_t s, int16x4_t t);
15246 int8x8_t pandn_sb (int8x8_t s, int8x8_t t);
15247 uint16x4_t pavgh (uint16x4_t s, uint16x4_t t);
15248 uint8x8_t pavgb (uint8x8_t s, uint8x8_t t);
15249 uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t);
15250 uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t);
15251 uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t);
15252 int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t);
15253 int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t);
15254 int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t);
15255 uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t);
15256 uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t);
15257 uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t);
15258 int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t);
15259 int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t);
15260 int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t);
15261 uint16x4_t pextrh_u (uint16x4_t s, int field);
15262 int16x4_t pextrh_s (int16x4_t s, int field);
15263 uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t);
15264 uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t);
15265 uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t);
15266 uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t);
15267 int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t);
15268 int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t);
15269 int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t);
15270 int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t);
15271 int32x2_t pmaddhw (int16x4_t s, int16x4_t t);
15272 int16x4_t pmaxsh (int16x4_t s, int16x4_t t);
15273 uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t);
15274 int16x4_t pminsh (int16x4_t s, int16x4_t t);
15275 uint8x8_t pminub (uint8x8_t s, uint8x8_t t);
15276 uint8x8_t pmovmskb_u (uint8x8_t s);
15277 int8x8_t pmovmskb_s (int8x8_t s);
15278 uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t);
15279 int16x4_t pmulhh (int16x4_t s, int16x4_t t);
15280 int16x4_t pmullh (int16x4_t s, int16x4_t t);
15281 int64_t pmuluw (uint32x2_t s, uint32x2_t t);
15282 uint8x8_t pasubub (uint8x8_t s, uint8x8_t t);
15283 uint16x4_t biadd (uint8x8_t s);
15284 uint16x4_t psadbh (uint8x8_t s, uint8x8_t t);
15285 uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order);
15286 int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order);
15287 uint16x4_t psllh_u (uint16x4_t s, uint8_t amount);
15288 int16x4_t psllh_s (int16x4_t s, uint8_t amount);
15289 uint32x2_t psllw_u (uint32x2_t s, uint8_t amount);
15290 int32x2_t psllw_s (int32x2_t s, uint8_t amount);
15291 uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount);
15292 int16x4_t psrlh_s (int16x4_t s, uint8_t amount);
15293 uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount);
15294 int32x2_t psrlw_s (int32x2_t s, uint8_t amount);
15295 uint16x4_t psrah_u (uint16x4_t s, uint8_t amount);
15296 int16x4_t psrah_s (int16x4_t s, uint8_t amount);
15297 uint32x2_t psraw_u (uint32x2_t s, uint8_t amount);
15298 int32x2_t psraw_s (int32x2_t s, uint8_t amount);
15299 uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t);
15300 uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t);
15301 uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t);
15302 int32x2_t psubw_s (int32x2_t s, int32x2_t t);
15303 int16x4_t psubh_s (int16x4_t s, int16x4_t t);
15304 int8x8_t psubb_s (int8x8_t s, int8x8_t t);
15305 uint64_t psubd_u (uint64_t s, uint64_t t);
15306 int64_t psubd_s (int64_t s, int64_t t);
15307 int16x4_t psubsh (int16x4_t s, int16x4_t t);
15308 int8x8_t psubsb (int8x8_t s, int8x8_t t);
15309 uint16x4_t psubush (uint16x4_t s, uint16x4_t t);
15310 uint8x8_t psubusb (uint8x8_t s, uint8x8_t t);
15311 uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t);
15312 uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t);
15313 uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t);
15314 int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t);
15315 int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t);
15316 int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t);
15317 uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t);
15318 uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t);
15319 uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t);
15320 int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t);
15321 int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t);
15322 int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t);
15326 * Paired-Single Arithmetic::
15327 * Paired-Single Built-in Functions::
15328 * MIPS-3D Built-in Functions::
15331 @node Paired-Single Arithmetic
15332 @subsubsection Paired-Single Arithmetic
15334 The table below lists the @code{v2sf} operations for which hardware
15335 support exists. @code{a}, @code{b} and @code{c} are @code{v2sf}
15336 values and @code{x} is an integral value.
15338 @multitable @columnfractions .50 .50
15339 @item C code @tab MIPS instruction
15340 @item @code{a + b} @tab @code{add.ps}
15341 @item @code{a - b} @tab @code{sub.ps}
15342 @item @code{-a} @tab @code{neg.ps}
15343 @item @code{a * b} @tab @code{mul.ps}
15344 @item @code{a * b + c} @tab @code{madd.ps}
15345 @item @code{a * b - c} @tab @code{msub.ps}
15346 @item @code{-(a * b + c)} @tab @code{nmadd.ps}
15347 @item @code{-(a * b - c)} @tab @code{nmsub.ps}
15348 @item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps}
15351 Note that the multiply-accumulate instructions can be disabled
15352 using the command-line option @code{-mno-fused-madd}.
15354 @node Paired-Single Built-in Functions
15355 @subsubsection Paired-Single Built-in Functions
15357 The following paired-single functions map directly to a particular
15358 MIPS instruction. Please refer to the architecture specification
15359 for details on what each instruction does.
15362 @item v2sf __builtin_mips_pll_ps (v2sf, v2sf)
15363 Pair lower lower (@code{pll.ps}).
15365 @item v2sf __builtin_mips_pul_ps (v2sf, v2sf)
15366 Pair upper lower (@code{pul.ps}).
15368 @item v2sf __builtin_mips_plu_ps (v2sf, v2sf)
15369 Pair lower upper (@code{plu.ps}).
15371 @item v2sf __builtin_mips_puu_ps (v2sf, v2sf)
15372 Pair upper upper (@code{puu.ps}).
15374 @item v2sf __builtin_mips_cvt_ps_s (float, float)
15375 Convert pair to paired single (@code{cvt.ps.s}).
15377 @item float __builtin_mips_cvt_s_pl (v2sf)
15378 Convert pair lower to single (@code{cvt.s.pl}).
15380 @item float __builtin_mips_cvt_s_pu (v2sf)
15381 Convert pair upper to single (@code{cvt.s.pu}).
15383 @item v2sf __builtin_mips_abs_ps (v2sf)
15384 Absolute value (@code{abs.ps}).
15386 @item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int)
15387 Align variable (@code{alnv.ps}).
15389 @emph{Note:} The value of the third parameter must be 0 or 4
15390 modulo 8, otherwise the result is unpredictable. Please read the
15391 instruction description for details.
15394 The following multi-instruction functions are also available.
15395 In each case, @var{cond} can be any of the 16 floating-point conditions:
15396 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
15397 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl},
15398 @code{lt}, @code{nge}, @code{le} or @code{ngt}.
15401 @item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15402 @itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15403 Conditional move based on floating-point comparison (@code{c.@var{cond}.ps},
15404 @code{movt.ps}/@code{movf.ps}).
15406 The @code{movt} functions return the value @var{x} computed by:
15409 c.@var{cond}.ps @var{cc},@var{a},@var{b}
15410 mov.ps @var{x},@var{c}
15411 movt.ps @var{x},@var{d},@var{cc}
15414 The @code{movf} functions are similar but use @code{movf.ps} instead
15417 @item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15418 @itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15419 Comparison of two paired-single values (@code{c.@var{cond}.ps},
15420 @code{bc1t}/@code{bc1f}).
15422 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
15423 and return either the upper or lower half of the result. For example:
15427 if (__builtin_mips_upper_c_eq_ps (a, b))
15428 upper_halves_are_equal ();
15430 upper_halves_are_unequal ();
15432 if (__builtin_mips_lower_c_eq_ps (a, b))
15433 lower_halves_are_equal ();
15435 lower_halves_are_unequal ();
15439 @node MIPS-3D Built-in Functions
15440 @subsubsection MIPS-3D Built-in Functions
15442 The MIPS-3D Application-Specific Extension (ASE) includes additional
15443 paired-single instructions that are designed to improve the performance
15444 of 3D graphics operations. Support for these instructions is controlled
15445 by the @option{-mips3d} command-line option.
15447 The functions listed below map directly to a particular MIPS-3D
15448 instruction. Please refer to the architecture specification for
15449 more details on what each instruction does.
15452 @item v2sf __builtin_mips_addr_ps (v2sf, v2sf)
15453 Reduction add (@code{addr.ps}).
15455 @item v2sf __builtin_mips_mulr_ps (v2sf, v2sf)
15456 Reduction multiply (@code{mulr.ps}).
15458 @item v2sf __builtin_mips_cvt_pw_ps (v2sf)
15459 Convert paired single to paired word (@code{cvt.pw.ps}).
15461 @item v2sf __builtin_mips_cvt_ps_pw (v2sf)
15462 Convert paired word to paired single (@code{cvt.ps.pw}).
15464 @item float __builtin_mips_recip1_s (float)
15465 @itemx double __builtin_mips_recip1_d (double)
15466 @itemx v2sf __builtin_mips_recip1_ps (v2sf)
15467 Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}).
15469 @item float __builtin_mips_recip2_s (float, float)
15470 @itemx double __builtin_mips_recip2_d (double, double)
15471 @itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf)
15472 Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}).
15474 @item float __builtin_mips_rsqrt1_s (float)
15475 @itemx double __builtin_mips_rsqrt1_d (double)
15476 @itemx v2sf __builtin_mips_rsqrt1_ps (v2sf)
15477 Reduced-precision reciprocal square root (sequence step 1)
15478 (@code{rsqrt1.@var{fmt}}).
15480 @item float __builtin_mips_rsqrt2_s (float, float)
15481 @itemx double __builtin_mips_rsqrt2_d (double, double)
15482 @itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf)
15483 Reduced-precision reciprocal square root (sequence step 2)
15484 (@code{rsqrt2.@var{fmt}}).
15487 The following multi-instruction functions are also available.
15488 In each case, @var{cond} can be any of the 16 floating-point conditions:
15489 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
15490 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq},
15491 @code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}.
15494 @item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b})
15495 @itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b})
15496 Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}},
15497 @code{bc1t}/@code{bc1f}).
15499 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s}
15500 or @code{cabs.@var{cond}.d} and return the result as a boolean value.
15505 if (__builtin_mips_cabs_eq_s (a, b))
15511 @item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15512 @itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15513 Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps},
15514 @code{bc1t}/@code{bc1f}).
15516 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps}
15517 and return either the upper or lower half of the result. For example:
15521 if (__builtin_mips_upper_cabs_eq_ps (a, b))
15522 upper_halves_are_equal ();
15524 upper_halves_are_unequal ();
15526 if (__builtin_mips_lower_cabs_eq_ps (a, b))
15527 lower_halves_are_equal ();
15529 lower_halves_are_unequal ();
15532 @item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15533 @itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15534 Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps},
15535 @code{movt.ps}/@code{movf.ps}).
15537 The @code{movt} functions return the value @var{x} computed by:
15540 cabs.@var{cond}.ps @var{cc},@var{a},@var{b}
15541 mov.ps @var{x},@var{c}
15542 movt.ps @var{x},@var{d},@var{cc}
15545 The @code{movf} functions are similar but use @code{movf.ps} instead
15548 @item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15549 @itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15550 @itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15551 @itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
15552 Comparison of two paired-single values
15553 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
15554 @code{bc1any2t}/@code{bc1any2f}).
15556 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
15557 or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either
15558 result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}.
15563 if (__builtin_mips_any_c_eq_ps (a, b))
15568 if (__builtin_mips_all_c_eq_ps (a, b))
15574 @item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15575 @itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15576 @itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15577 @itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
15578 Comparison of four paired-single values
15579 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
15580 @code{bc1any4t}/@code{bc1any4f}).
15582 These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps}
15583 to compare @var{a} with @var{b} and to compare @var{c} with @var{d}.
15584 The @code{any} forms return @code{true} if any of the four results are @code{true}
15585 and the @code{all} forms return @code{true} if all four results are @code{true}.
15590 if (__builtin_mips_any_c_eq_4s (a, b, c, d))
15595 if (__builtin_mips_all_c_eq_4s (a, b, c, d))
15602 @node MIPS SIMD Architecture (MSA) Support
15603 @subsection MIPS SIMD Architecture (MSA) Support
15606 * MIPS SIMD Architecture Built-in Functions::
15609 GCC provides intrinsics to access the SIMD instructions provided by the
15610 MSA MIPS SIMD Architecture. The interface is made available by including
15611 @code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}.
15612 For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic,
15615 MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and
15616 64-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point
15617 data elements. The following vectors typedefs are included in @code{msa.h}:
15619 @item @code{v16i8}, a vector of sixteen signed 8-bit integers;
15620 @item @code{v16u8}, a vector of sixteen unsigned 8-bit integers;
15621 @item @code{v8i16}, a vector of eight signed 16-bit integers;
15622 @item @code{v8u16}, a vector of eight unsigned 16-bit integers;
15623 @item @code{v4i32}, a vector of four signed 32-bit integers;
15624 @item @code{v4u32}, a vector of four unsigned 32-bit integers;
15625 @item @code{v2i64}, a vector of two signed 64-bit integers;
15626 @item @code{v2u64}, a vector of two unsigned 64-bit integers;
15627 @item @code{v4f32}, a vector of four 32-bit floats;
15628 @item @code{v2f64}, a vector of two 64-bit doubles.
15631 Instructions and corresponding built-ins may have additional restrictions and/or
15632 input/output values manipulated:
15634 @item @code{imm0_1}, an integer literal in range 0 to 1;
15635 @item @code{imm0_3}, an integer literal in range 0 to 3;
15636 @item @code{imm0_7}, an integer literal in range 0 to 7;
15637 @item @code{imm0_15}, an integer literal in range 0 to 15;
15638 @item @code{imm0_31}, an integer literal in range 0 to 31;
15639 @item @code{imm0_63}, an integer literal in range 0 to 63;
15640 @item @code{imm0_255}, an integer literal in range 0 to 255;
15641 @item @code{imm_n16_15}, an integer literal in range -16 to 15;
15642 @item @code{imm_n512_511}, an integer literal in range -512 to 511;
15643 @item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left
15644 shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022;
15645 @item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left
15646 shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044;
15647 @item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left
15648 shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088;
15649 @item @code{imm1_4}, an integer literal in range 1 to 4;
15650 @item @code{i32, i64, u32, u64, f32, f64}, defined as follows:
15656 #if __LONG_MAX__ == __LONG_LONG_MAX__
15659 typedef long long i64;
15662 typedef unsigned int u32;
15663 #if __LONG_MAX__ == __LONG_LONG_MAX__
15664 typedef unsigned long u64;
15666 typedef unsigned long long u64;
15669 typedef double f64;
15674 @node MIPS SIMD Architecture Built-in Functions
15675 @subsubsection MIPS SIMD Architecture Built-in Functions
15677 The intrinsics provided are listed below; each is named after the
15678 machine instruction.
15681 v16i8 __builtin_msa_add_a_b (v16i8, v16i8);
15682 v8i16 __builtin_msa_add_a_h (v8i16, v8i16);
15683 v4i32 __builtin_msa_add_a_w (v4i32, v4i32);
15684 v2i64 __builtin_msa_add_a_d (v2i64, v2i64);
15686 v16i8 __builtin_msa_adds_a_b (v16i8, v16i8);
15687 v8i16 __builtin_msa_adds_a_h (v8i16, v8i16);
15688 v4i32 __builtin_msa_adds_a_w (v4i32, v4i32);
15689 v2i64 __builtin_msa_adds_a_d (v2i64, v2i64);
15691 v16i8 __builtin_msa_adds_s_b (v16i8, v16i8);
15692 v8i16 __builtin_msa_adds_s_h (v8i16, v8i16);
15693 v4i32 __builtin_msa_adds_s_w (v4i32, v4i32);
15694 v2i64 __builtin_msa_adds_s_d (v2i64, v2i64);
15696 v16u8 __builtin_msa_adds_u_b (v16u8, v16u8);
15697 v8u16 __builtin_msa_adds_u_h (v8u16, v8u16);
15698 v4u32 __builtin_msa_adds_u_w (v4u32, v4u32);
15699 v2u64 __builtin_msa_adds_u_d (v2u64, v2u64);
15701 v16i8 __builtin_msa_addv_b (v16i8, v16i8);
15702 v8i16 __builtin_msa_addv_h (v8i16, v8i16);
15703 v4i32 __builtin_msa_addv_w (v4i32, v4i32);
15704 v2i64 __builtin_msa_addv_d (v2i64, v2i64);
15706 v16i8 __builtin_msa_addvi_b (v16i8, imm0_31);
15707 v8i16 __builtin_msa_addvi_h (v8i16, imm0_31);
15708 v4i32 __builtin_msa_addvi_w (v4i32, imm0_31);
15709 v2i64 __builtin_msa_addvi_d (v2i64, imm0_31);
15711 v16u8 __builtin_msa_and_v (v16u8, v16u8);
15713 v16u8 __builtin_msa_andi_b (v16u8, imm0_255);
15715 v16i8 __builtin_msa_asub_s_b (v16i8, v16i8);
15716 v8i16 __builtin_msa_asub_s_h (v8i16, v8i16);
15717 v4i32 __builtin_msa_asub_s_w (v4i32, v4i32);
15718 v2i64 __builtin_msa_asub_s_d (v2i64, v2i64);
15720 v16u8 __builtin_msa_asub_u_b (v16u8, v16u8);
15721 v8u16 __builtin_msa_asub_u_h (v8u16, v8u16);
15722 v4u32 __builtin_msa_asub_u_w (v4u32, v4u32);
15723 v2u64 __builtin_msa_asub_u_d (v2u64, v2u64);
15725 v16i8 __builtin_msa_ave_s_b (v16i8, v16i8);
15726 v8i16 __builtin_msa_ave_s_h (v8i16, v8i16);
15727 v4i32 __builtin_msa_ave_s_w (v4i32, v4i32);
15728 v2i64 __builtin_msa_ave_s_d (v2i64, v2i64);
15730 v16u8 __builtin_msa_ave_u_b (v16u8, v16u8);
15731 v8u16 __builtin_msa_ave_u_h (v8u16, v8u16);
15732 v4u32 __builtin_msa_ave_u_w (v4u32, v4u32);
15733 v2u64 __builtin_msa_ave_u_d (v2u64, v2u64);
15735 v16i8 __builtin_msa_aver_s_b (v16i8, v16i8);
15736 v8i16 __builtin_msa_aver_s_h (v8i16, v8i16);
15737 v4i32 __builtin_msa_aver_s_w (v4i32, v4i32);
15738 v2i64 __builtin_msa_aver_s_d (v2i64, v2i64);
15740 v16u8 __builtin_msa_aver_u_b (v16u8, v16u8);
15741 v8u16 __builtin_msa_aver_u_h (v8u16, v8u16);
15742 v4u32 __builtin_msa_aver_u_w (v4u32, v4u32);
15743 v2u64 __builtin_msa_aver_u_d (v2u64, v2u64);
15745 v16u8 __builtin_msa_bclr_b (v16u8, v16u8);
15746 v8u16 __builtin_msa_bclr_h (v8u16, v8u16);
15747 v4u32 __builtin_msa_bclr_w (v4u32, v4u32);
15748 v2u64 __builtin_msa_bclr_d (v2u64, v2u64);
15750 v16u8 __builtin_msa_bclri_b (v16u8, imm0_7);
15751 v8u16 __builtin_msa_bclri_h (v8u16, imm0_15);
15752 v4u32 __builtin_msa_bclri_w (v4u32, imm0_31);
15753 v2u64 __builtin_msa_bclri_d (v2u64, imm0_63);
15755 v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8);
15756 v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16);
15757 v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32);
15758 v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64);
15760 v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7);
15761 v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15);
15762 v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31);
15763 v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63);
15765 v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8);
15766 v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16);
15767 v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32);
15768 v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64);
15770 v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7);
15771 v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15);
15772 v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31);
15773 v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63);
15775 v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8);
15777 v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255);
15779 v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8);
15781 v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255);
15783 v16u8 __builtin_msa_bneg_b (v16u8, v16u8);
15784 v8u16 __builtin_msa_bneg_h (v8u16, v8u16);
15785 v4u32 __builtin_msa_bneg_w (v4u32, v4u32);
15786 v2u64 __builtin_msa_bneg_d (v2u64, v2u64);
15788 v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7);
15789 v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15);
15790 v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31);
15791 v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63);
15793 i32 __builtin_msa_bnz_b (v16u8);
15794 i32 __builtin_msa_bnz_h (v8u16);
15795 i32 __builtin_msa_bnz_w (v4u32);
15796 i32 __builtin_msa_bnz_d (v2u64);
15798 i32 __builtin_msa_bnz_v (v16u8);
15800 v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8);
15802 v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255);
15804 v16u8 __builtin_msa_bset_b (v16u8, v16u8);
15805 v8u16 __builtin_msa_bset_h (v8u16, v8u16);
15806 v4u32 __builtin_msa_bset_w (v4u32, v4u32);
15807 v2u64 __builtin_msa_bset_d (v2u64, v2u64);
15809 v16u8 __builtin_msa_bseti_b (v16u8, imm0_7);
15810 v8u16 __builtin_msa_bseti_h (v8u16, imm0_15);
15811 v4u32 __builtin_msa_bseti_w (v4u32, imm0_31);
15812 v2u64 __builtin_msa_bseti_d (v2u64, imm0_63);
15814 i32 __builtin_msa_bz_b (v16u8);
15815 i32 __builtin_msa_bz_h (v8u16);
15816 i32 __builtin_msa_bz_w (v4u32);
15817 i32 __builtin_msa_bz_d (v2u64);
15819 i32 __builtin_msa_bz_v (v16u8);
15821 v16i8 __builtin_msa_ceq_b (v16i8, v16i8);
15822 v8i16 __builtin_msa_ceq_h (v8i16, v8i16);
15823 v4i32 __builtin_msa_ceq_w (v4i32, v4i32);
15824 v2i64 __builtin_msa_ceq_d (v2i64, v2i64);
15826 v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15);
15827 v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15);
15828 v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15);
15829 v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15);
15831 i32 __builtin_msa_cfcmsa (imm0_31);
15833 v16i8 __builtin_msa_cle_s_b (v16i8, v16i8);
15834 v8i16 __builtin_msa_cle_s_h (v8i16, v8i16);
15835 v4i32 __builtin_msa_cle_s_w (v4i32, v4i32);
15836 v2i64 __builtin_msa_cle_s_d (v2i64, v2i64);
15838 v16i8 __builtin_msa_cle_u_b (v16u8, v16u8);
15839 v8i16 __builtin_msa_cle_u_h (v8u16, v8u16);
15840 v4i32 __builtin_msa_cle_u_w (v4u32, v4u32);
15841 v2i64 __builtin_msa_cle_u_d (v2u64, v2u64);
15843 v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15);
15844 v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15);
15845 v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15);
15846 v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15);
15848 v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31);
15849 v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31);
15850 v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31);
15851 v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31);
15853 v16i8 __builtin_msa_clt_s_b (v16i8, v16i8);
15854 v8i16 __builtin_msa_clt_s_h (v8i16, v8i16);
15855 v4i32 __builtin_msa_clt_s_w (v4i32, v4i32);
15856 v2i64 __builtin_msa_clt_s_d (v2i64, v2i64);
15858 v16i8 __builtin_msa_clt_u_b (v16u8, v16u8);
15859 v8i16 __builtin_msa_clt_u_h (v8u16, v8u16);
15860 v4i32 __builtin_msa_clt_u_w (v4u32, v4u32);
15861 v2i64 __builtin_msa_clt_u_d (v2u64, v2u64);
15863 v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15);
15864 v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15);
15865 v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15);
15866 v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15);
15868 v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31);
15869 v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31);
15870 v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31);
15871 v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31);
15873 i32 __builtin_msa_copy_s_b (v16i8, imm0_15);
15874 i32 __builtin_msa_copy_s_h (v8i16, imm0_7);
15875 i32 __builtin_msa_copy_s_w (v4i32, imm0_3);
15876 i64 __builtin_msa_copy_s_d (v2i64, imm0_1);
15878 u32 __builtin_msa_copy_u_b (v16i8, imm0_15);
15879 u32 __builtin_msa_copy_u_h (v8i16, imm0_7);
15880 u32 __builtin_msa_copy_u_w (v4i32, imm0_3);
15881 u64 __builtin_msa_copy_u_d (v2i64, imm0_1);
15883 void __builtin_msa_ctcmsa (imm0_31, i32);
15885 v16i8 __builtin_msa_div_s_b (v16i8, v16i8);
15886 v8i16 __builtin_msa_div_s_h (v8i16, v8i16);
15887 v4i32 __builtin_msa_div_s_w (v4i32, v4i32);
15888 v2i64 __builtin_msa_div_s_d (v2i64, v2i64);
15890 v16u8 __builtin_msa_div_u_b (v16u8, v16u8);
15891 v8u16 __builtin_msa_div_u_h (v8u16, v8u16);
15892 v4u32 __builtin_msa_div_u_w (v4u32, v4u32);
15893 v2u64 __builtin_msa_div_u_d (v2u64, v2u64);
15895 v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8);
15896 v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16);
15897 v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32);
15899 v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8);
15900 v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16);
15901 v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32);
15903 v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8);
15904 v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16);
15905 v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32);
15907 v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8);
15908 v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16);
15909 v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32);
15911 v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8);
15912 v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16);
15913 v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32);
15915 v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8);
15916 v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16);
15917 v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32);
15919 v4f32 __builtin_msa_fadd_w (v4f32, v4f32);
15920 v2f64 __builtin_msa_fadd_d (v2f64, v2f64);
15922 v4i32 __builtin_msa_fcaf_w (v4f32, v4f32);
15923 v2i64 __builtin_msa_fcaf_d (v2f64, v2f64);
15925 v4i32 __builtin_msa_fceq_w (v4f32, v4f32);
15926 v2i64 __builtin_msa_fceq_d (v2f64, v2f64);
15928 v4i32 __builtin_msa_fclass_w (v4f32);
15929 v2i64 __builtin_msa_fclass_d (v2f64);
15931 v4i32 __builtin_msa_fcle_w (v4f32, v4f32);
15932 v2i64 __builtin_msa_fcle_d (v2f64, v2f64);
15934 v4i32 __builtin_msa_fclt_w (v4f32, v4f32);
15935 v2i64 __builtin_msa_fclt_d (v2f64, v2f64);
15937 v4i32 __builtin_msa_fcne_w (v4f32, v4f32);
15938 v2i64 __builtin_msa_fcne_d (v2f64, v2f64);
15940 v4i32 __builtin_msa_fcor_w (v4f32, v4f32);
15941 v2i64 __builtin_msa_fcor_d (v2f64, v2f64);
15943 v4i32 __builtin_msa_fcueq_w (v4f32, v4f32);
15944 v2i64 __builtin_msa_fcueq_d (v2f64, v2f64);
15946 v4i32 __builtin_msa_fcule_w (v4f32, v4f32);
15947 v2i64 __builtin_msa_fcule_d (v2f64, v2f64);
15949 v4i32 __builtin_msa_fcult_w (v4f32, v4f32);
15950 v2i64 __builtin_msa_fcult_d (v2f64, v2f64);
15952 v4i32 __builtin_msa_fcun_w (v4f32, v4f32);
15953 v2i64 __builtin_msa_fcun_d (v2f64, v2f64);
15955 v4i32 __builtin_msa_fcune_w (v4f32, v4f32);
15956 v2i64 __builtin_msa_fcune_d (v2f64, v2f64);
15958 v4f32 __builtin_msa_fdiv_w (v4f32, v4f32);
15959 v2f64 __builtin_msa_fdiv_d (v2f64, v2f64);
15961 v8i16 __builtin_msa_fexdo_h (v4f32, v4f32);
15962 v4f32 __builtin_msa_fexdo_w (v2f64, v2f64);
15964 v4f32 __builtin_msa_fexp2_w (v4f32, v4i32);
15965 v2f64 __builtin_msa_fexp2_d (v2f64, v2i64);
15967 v4f32 __builtin_msa_fexupl_w (v8i16);
15968 v2f64 __builtin_msa_fexupl_d (v4f32);
15970 v4f32 __builtin_msa_fexupr_w (v8i16);
15971 v2f64 __builtin_msa_fexupr_d (v4f32);
15973 v4f32 __builtin_msa_ffint_s_w (v4i32);
15974 v2f64 __builtin_msa_ffint_s_d (v2i64);
15976 v4f32 __builtin_msa_ffint_u_w (v4u32);
15977 v2f64 __builtin_msa_ffint_u_d (v2u64);
15979 v4f32 __builtin_msa_ffql_w (v8i16);
15980 v2f64 __builtin_msa_ffql_d (v4i32);
15982 v4f32 __builtin_msa_ffqr_w (v8i16);
15983 v2f64 __builtin_msa_ffqr_d (v4i32);
15985 v16i8 __builtin_msa_fill_b (i32);
15986 v8i16 __builtin_msa_fill_h (i32);
15987 v4i32 __builtin_msa_fill_w (i32);
15988 v2i64 __builtin_msa_fill_d (i64);
15990 v4f32 __builtin_msa_flog2_w (v4f32);
15991 v2f64 __builtin_msa_flog2_d (v2f64);
15993 v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32);
15994 v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64);
15996 v4f32 __builtin_msa_fmax_w (v4f32, v4f32);
15997 v2f64 __builtin_msa_fmax_d (v2f64, v2f64);
15999 v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32);
16000 v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64);
16002 v4f32 __builtin_msa_fmin_w (v4f32, v4f32);
16003 v2f64 __builtin_msa_fmin_d (v2f64, v2f64);
16005 v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32);
16006 v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64);
16008 v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32);
16009 v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64);
16011 v4f32 __builtin_msa_fmul_w (v4f32, v4f32);
16012 v2f64 __builtin_msa_fmul_d (v2f64, v2f64);
16014 v4f32 __builtin_msa_frint_w (v4f32);
16015 v2f64 __builtin_msa_frint_d (v2f64);
16017 v4f32 __builtin_msa_frcp_w (v4f32);
16018 v2f64 __builtin_msa_frcp_d (v2f64);
16020 v4f32 __builtin_msa_frsqrt_w (v4f32);
16021 v2f64 __builtin_msa_frsqrt_d (v2f64);
16023 v4i32 __builtin_msa_fsaf_w (v4f32, v4f32);
16024 v2i64 __builtin_msa_fsaf_d (v2f64, v2f64);
16026 v4i32 __builtin_msa_fseq_w (v4f32, v4f32);
16027 v2i64 __builtin_msa_fseq_d (v2f64, v2f64);
16029 v4i32 __builtin_msa_fsle_w (v4f32, v4f32);
16030 v2i64 __builtin_msa_fsle_d (v2f64, v2f64);
16032 v4i32 __builtin_msa_fslt_w (v4f32, v4f32);
16033 v2i64 __builtin_msa_fslt_d (v2f64, v2f64);
16035 v4i32 __builtin_msa_fsne_w (v4f32, v4f32);
16036 v2i64 __builtin_msa_fsne_d (v2f64, v2f64);
16038 v4i32 __builtin_msa_fsor_w (v4f32, v4f32);
16039 v2i64 __builtin_msa_fsor_d (v2f64, v2f64);
16041 v4f32 __builtin_msa_fsqrt_w (v4f32);
16042 v2f64 __builtin_msa_fsqrt_d (v2f64);
16044 v4f32 __builtin_msa_fsub_w (v4f32, v4f32);
16045 v2f64 __builtin_msa_fsub_d (v2f64, v2f64);
16047 v4i32 __builtin_msa_fsueq_w (v4f32, v4f32);
16048 v2i64 __builtin_msa_fsueq_d (v2f64, v2f64);
16050 v4i32 __builtin_msa_fsule_w (v4f32, v4f32);
16051 v2i64 __builtin_msa_fsule_d (v2f64, v2f64);
16053 v4i32 __builtin_msa_fsult_w (v4f32, v4f32);
16054 v2i64 __builtin_msa_fsult_d (v2f64, v2f64);
16056 v4i32 __builtin_msa_fsun_w (v4f32, v4f32);
16057 v2i64 __builtin_msa_fsun_d (v2f64, v2f64);
16059 v4i32 __builtin_msa_fsune_w (v4f32, v4f32);
16060 v2i64 __builtin_msa_fsune_d (v2f64, v2f64);
16062 v4i32 __builtin_msa_ftint_s_w (v4f32);
16063 v2i64 __builtin_msa_ftint_s_d (v2f64);
16065 v4u32 __builtin_msa_ftint_u_w (v4f32);
16066 v2u64 __builtin_msa_ftint_u_d (v2f64);
16068 v8i16 __builtin_msa_ftq_h (v4f32, v4f32);
16069 v4i32 __builtin_msa_ftq_w (v2f64, v2f64);
16071 v4i32 __builtin_msa_ftrunc_s_w (v4f32);
16072 v2i64 __builtin_msa_ftrunc_s_d (v2f64);
16074 v4u32 __builtin_msa_ftrunc_u_w (v4f32);
16075 v2u64 __builtin_msa_ftrunc_u_d (v2f64);
16077 v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8);
16078 v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16);
16079 v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32);
16081 v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8);
16082 v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16);
16083 v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32);
16085 v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8);
16086 v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16);
16087 v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32);
16089 v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8);
16090 v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16);
16091 v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32);
16093 v16i8 __builtin_msa_ilvev_b (v16i8, v16i8);
16094 v8i16 __builtin_msa_ilvev_h (v8i16, v8i16);
16095 v4i32 __builtin_msa_ilvev_w (v4i32, v4i32);
16096 v2i64 __builtin_msa_ilvev_d (v2i64, v2i64);
16098 v16i8 __builtin_msa_ilvl_b (v16i8, v16i8);
16099 v8i16 __builtin_msa_ilvl_h (v8i16, v8i16);
16100 v4i32 __builtin_msa_ilvl_w (v4i32, v4i32);
16101 v2i64 __builtin_msa_ilvl_d (v2i64, v2i64);
16103 v16i8 __builtin_msa_ilvod_b (v16i8, v16i8);
16104 v8i16 __builtin_msa_ilvod_h (v8i16, v8i16);
16105 v4i32 __builtin_msa_ilvod_w (v4i32, v4i32);
16106 v2i64 __builtin_msa_ilvod_d (v2i64, v2i64);
16108 v16i8 __builtin_msa_ilvr_b (v16i8, v16i8);
16109 v8i16 __builtin_msa_ilvr_h (v8i16, v8i16);
16110 v4i32 __builtin_msa_ilvr_w (v4i32, v4i32);
16111 v2i64 __builtin_msa_ilvr_d (v2i64, v2i64);
16113 v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32);
16114 v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32);
16115 v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32);
16116 v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64);
16118 v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8);
16119 v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16);
16120 v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32);
16121 v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64);
16123 v16i8 __builtin_msa_ld_b (void *, imm_n512_511);
16124 v8i16 __builtin_msa_ld_h (void *, imm_n1024_1022);
16125 v4i32 __builtin_msa_ld_w (void *, imm_n2048_2044);
16126 v2i64 __builtin_msa_ld_d (void *, imm_n4096_4088);
16128 v16i8 __builtin_msa_ldi_b (imm_n512_511);
16129 v8i16 __builtin_msa_ldi_h (imm_n512_511);
16130 v4i32 __builtin_msa_ldi_w (imm_n512_511);
16131 v2i64 __builtin_msa_ldi_d (imm_n512_511);
16133 v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16);
16134 v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32);
16136 v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16);
16137 v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32);
16139 v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8);
16140 v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16);
16141 v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32);
16142 v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64);
16144 v16i8 __builtin_msa_max_a_b (v16i8, v16i8);
16145 v8i16 __builtin_msa_max_a_h (v8i16, v8i16);
16146 v4i32 __builtin_msa_max_a_w (v4i32, v4i32);
16147 v2i64 __builtin_msa_max_a_d (v2i64, v2i64);
16149 v16i8 __builtin_msa_max_s_b (v16i8, v16i8);
16150 v8i16 __builtin_msa_max_s_h (v8i16, v8i16);
16151 v4i32 __builtin_msa_max_s_w (v4i32, v4i32);
16152 v2i64 __builtin_msa_max_s_d (v2i64, v2i64);
16154 v16u8 __builtin_msa_max_u_b (v16u8, v16u8);
16155 v8u16 __builtin_msa_max_u_h (v8u16, v8u16);
16156 v4u32 __builtin_msa_max_u_w (v4u32, v4u32);
16157 v2u64 __builtin_msa_max_u_d (v2u64, v2u64);
16159 v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15);
16160 v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15);
16161 v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15);
16162 v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15);
16164 v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31);
16165 v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31);
16166 v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31);
16167 v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31);
16169 v16i8 __builtin_msa_min_a_b (v16i8, v16i8);
16170 v8i16 __builtin_msa_min_a_h (v8i16, v8i16);
16171 v4i32 __builtin_msa_min_a_w (v4i32, v4i32);
16172 v2i64 __builtin_msa_min_a_d (v2i64, v2i64);
16174 v16i8 __builtin_msa_min_s_b (v16i8, v16i8);
16175 v8i16 __builtin_msa_min_s_h (v8i16, v8i16);
16176 v4i32 __builtin_msa_min_s_w (v4i32, v4i32);
16177 v2i64 __builtin_msa_min_s_d (v2i64, v2i64);
16179 v16u8 __builtin_msa_min_u_b (v16u8, v16u8);
16180 v8u16 __builtin_msa_min_u_h (v8u16, v8u16);
16181 v4u32 __builtin_msa_min_u_w (v4u32, v4u32);
16182 v2u64 __builtin_msa_min_u_d (v2u64, v2u64);
16184 v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15);
16185 v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15);
16186 v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15);
16187 v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15);
16189 v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31);
16190 v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31);
16191 v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31);
16192 v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31);
16194 v16i8 __builtin_msa_mod_s_b (v16i8, v16i8);
16195 v8i16 __builtin_msa_mod_s_h (v8i16, v8i16);
16196 v4i32 __builtin_msa_mod_s_w (v4i32, v4i32);
16197 v2i64 __builtin_msa_mod_s_d (v2i64, v2i64);
16199 v16u8 __builtin_msa_mod_u_b (v16u8, v16u8);
16200 v8u16 __builtin_msa_mod_u_h (v8u16, v8u16);
16201 v4u32 __builtin_msa_mod_u_w (v4u32, v4u32);
16202 v2u64 __builtin_msa_mod_u_d (v2u64, v2u64);
16204 v16i8 __builtin_msa_move_v (v16i8);
16206 v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16);
16207 v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32);
16209 v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16);
16210 v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32);
16212 v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8);
16213 v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16);
16214 v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32);
16215 v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64);
16217 v8i16 __builtin_msa_mul_q_h (v8i16, v8i16);
16218 v4i32 __builtin_msa_mul_q_w (v4i32, v4i32);
16220 v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16);
16221 v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32);
16223 v16i8 __builtin_msa_mulv_b (v16i8, v16i8);
16224 v8i16 __builtin_msa_mulv_h (v8i16, v8i16);
16225 v4i32 __builtin_msa_mulv_w (v4i32, v4i32);
16226 v2i64 __builtin_msa_mulv_d (v2i64, v2i64);
16228 v16i8 __builtin_msa_nloc_b (v16i8);
16229 v8i16 __builtin_msa_nloc_h (v8i16);
16230 v4i32 __builtin_msa_nloc_w (v4i32);
16231 v2i64 __builtin_msa_nloc_d (v2i64);
16233 v16i8 __builtin_msa_nlzc_b (v16i8);
16234 v8i16 __builtin_msa_nlzc_h (v8i16);
16235 v4i32 __builtin_msa_nlzc_w (v4i32);
16236 v2i64 __builtin_msa_nlzc_d (v2i64);
16238 v16u8 __builtin_msa_nor_v (v16u8, v16u8);
16240 v16u8 __builtin_msa_nori_b (v16u8, imm0_255);
16242 v16u8 __builtin_msa_or_v (v16u8, v16u8);
16244 v16u8 __builtin_msa_ori_b (v16u8, imm0_255);
16246 v16i8 __builtin_msa_pckev_b (v16i8, v16i8);
16247 v8i16 __builtin_msa_pckev_h (v8i16, v8i16);
16248 v4i32 __builtin_msa_pckev_w (v4i32, v4i32);
16249 v2i64 __builtin_msa_pckev_d (v2i64, v2i64);
16251 v16i8 __builtin_msa_pckod_b (v16i8, v16i8);
16252 v8i16 __builtin_msa_pckod_h (v8i16, v8i16);
16253 v4i32 __builtin_msa_pckod_w (v4i32, v4i32);
16254 v2i64 __builtin_msa_pckod_d (v2i64, v2i64);
16256 v16i8 __builtin_msa_pcnt_b (v16i8);
16257 v8i16 __builtin_msa_pcnt_h (v8i16);
16258 v4i32 __builtin_msa_pcnt_w (v4i32);
16259 v2i64 __builtin_msa_pcnt_d (v2i64);
16261 v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7);
16262 v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15);
16263 v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31);
16264 v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63);
16266 v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7);
16267 v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15);
16268 v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31);
16269 v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63);
16271 v16i8 __builtin_msa_shf_b (v16i8, imm0_255);
16272 v8i16 __builtin_msa_shf_h (v8i16, imm0_255);
16273 v4i32 __builtin_msa_shf_w (v4i32, imm0_255);
16275 v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32);
16276 v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32);
16277 v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32);
16278 v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32);
16280 v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15);
16281 v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7);
16282 v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3);
16283 v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1);
16285 v16i8 __builtin_msa_sll_b (v16i8, v16i8);
16286 v8i16 __builtin_msa_sll_h (v8i16, v8i16);
16287 v4i32 __builtin_msa_sll_w (v4i32, v4i32);
16288 v2i64 __builtin_msa_sll_d (v2i64, v2i64);
16290 v16i8 __builtin_msa_slli_b (v16i8, imm0_7);
16291 v8i16 __builtin_msa_slli_h (v8i16, imm0_15);
16292 v4i32 __builtin_msa_slli_w (v4i32, imm0_31);
16293 v2i64 __builtin_msa_slli_d (v2i64, imm0_63);
16295 v16i8 __builtin_msa_splat_b (v16i8, i32);
16296 v8i16 __builtin_msa_splat_h (v8i16, i32);
16297 v4i32 __builtin_msa_splat_w (v4i32, i32);
16298 v2i64 __builtin_msa_splat_d (v2i64, i32);
16300 v16i8 __builtin_msa_splati_b (v16i8, imm0_15);
16301 v8i16 __builtin_msa_splati_h (v8i16, imm0_7);
16302 v4i32 __builtin_msa_splati_w (v4i32, imm0_3);
16303 v2i64 __builtin_msa_splati_d (v2i64, imm0_1);
16305 v16i8 __builtin_msa_sra_b (v16i8, v16i8);
16306 v8i16 __builtin_msa_sra_h (v8i16, v8i16);
16307 v4i32 __builtin_msa_sra_w (v4i32, v4i32);
16308 v2i64 __builtin_msa_sra_d (v2i64, v2i64);
16310 v16i8 __builtin_msa_srai_b (v16i8, imm0_7);
16311 v8i16 __builtin_msa_srai_h (v8i16, imm0_15);
16312 v4i32 __builtin_msa_srai_w (v4i32, imm0_31);
16313 v2i64 __builtin_msa_srai_d (v2i64, imm0_63);
16315 v16i8 __builtin_msa_srar_b (v16i8, v16i8);
16316 v8i16 __builtin_msa_srar_h (v8i16, v8i16);
16317 v4i32 __builtin_msa_srar_w (v4i32, v4i32);
16318 v2i64 __builtin_msa_srar_d (v2i64, v2i64);
16320 v16i8 __builtin_msa_srari_b (v16i8, imm0_7);
16321 v8i16 __builtin_msa_srari_h (v8i16, imm0_15);
16322 v4i32 __builtin_msa_srari_w (v4i32, imm0_31);
16323 v2i64 __builtin_msa_srari_d (v2i64, imm0_63);
16325 v16i8 __builtin_msa_srl_b (v16i8, v16i8);
16326 v8i16 __builtin_msa_srl_h (v8i16, v8i16);
16327 v4i32 __builtin_msa_srl_w (v4i32, v4i32);
16328 v2i64 __builtin_msa_srl_d (v2i64, v2i64);
16330 v16i8 __builtin_msa_srli_b (v16i8, imm0_7);
16331 v8i16 __builtin_msa_srli_h (v8i16, imm0_15);
16332 v4i32 __builtin_msa_srli_w (v4i32, imm0_31);
16333 v2i64 __builtin_msa_srli_d (v2i64, imm0_63);
16335 v16i8 __builtin_msa_srlr_b (v16i8, v16i8);
16336 v8i16 __builtin_msa_srlr_h (v8i16, v8i16);
16337 v4i32 __builtin_msa_srlr_w (v4i32, v4i32);
16338 v2i64 __builtin_msa_srlr_d (v2i64, v2i64);
16340 v16i8 __builtin_msa_srlri_b (v16i8, imm0_7);
16341 v8i16 __builtin_msa_srlri_h (v8i16, imm0_15);
16342 v4i32 __builtin_msa_srlri_w (v4i32, imm0_31);
16343 v2i64 __builtin_msa_srlri_d (v2i64, imm0_63);
16345 void __builtin_msa_st_b (v16i8, void *, imm_n512_511);
16346 void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022);
16347 void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044);
16348 void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088);
16350 v16i8 __builtin_msa_subs_s_b (v16i8, v16i8);
16351 v8i16 __builtin_msa_subs_s_h (v8i16, v8i16);
16352 v4i32 __builtin_msa_subs_s_w (v4i32, v4i32);
16353 v2i64 __builtin_msa_subs_s_d (v2i64, v2i64);
16355 v16u8 __builtin_msa_subs_u_b (v16u8, v16u8);
16356 v8u16 __builtin_msa_subs_u_h (v8u16, v8u16);
16357 v4u32 __builtin_msa_subs_u_w (v4u32, v4u32);
16358 v2u64 __builtin_msa_subs_u_d (v2u64, v2u64);
16360 v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8);
16361 v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16);
16362 v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32);
16363 v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64);
16365 v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8);
16366 v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16);
16367 v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32);
16368 v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64);
16370 v16i8 __builtin_msa_subv_b (v16i8, v16i8);
16371 v8i16 __builtin_msa_subv_h (v8i16, v8i16);
16372 v4i32 __builtin_msa_subv_w (v4i32, v4i32);
16373 v2i64 __builtin_msa_subv_d (v2i64, v2i64);
16375 v16i8 __builtin_msa_subvi_b (v16i8, imm0_31);
16376 v8i16 __builtin_msa_subvi_h (v8i16, imm0_31);
16377 v4i32 __builtin_msa_subvi_w (v4i32, imm0_31);
16378 v2i64 __builtin_msa_subvi_d (v2i64, imm0_31);
16380 v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8);
16381 v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16);
16382 v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32);
16383 v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64);
16385 v16u8 __builtin_msa_xor_v (v16u8, v16u8);
16387 v16u8 __builtin_msa_xori_b (v16u8, imm0_255);
16390 @node Other MIPS Built-in Functions
16391 @subsection Other MIPS Built-in Functions
16393 GCC provides other MIPS-specific built-in functions:
16396 @item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr})
16397 Insert a @samp{cache} instruction with operands @var{op} and @var{addr}.
16398 GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE}
16399 when this function is available.
16401 @item unsigned int __builtin_mips_get_fcsr (void)
16402 @itemx void __builtin_mips_set_fcsr (unsigned int @var{value})
16403 Get and set the contents of the floating-point control and status register
16404 (FPU control register 31). These functions are only available in hard-float
16405 code but can be called in both MIPS16 and non-MIPS16 contexts.
16407 @code{__builtin_mips_set_fcsr} can be used to change any bit of the
16408 register except the condition codes, which GCC assumes are preserved.
16411 @node MSP430 Built-in Functions
16412 @subsection MSP430 Built-in Functions
16414 GCC provides a couple of special builtin functions to aid in the
16415 writing of interrupt handlers in C.
16418 @item __bic_SR_register_on_exit (int @var{mask})
16419 This clears the indicated bits in the saved copy of the status register
16420 currently residing on the stack. This only works inside interrupt
16421 handlers and the changes to the status register will only take affect
16422 once the handler returns.
16424 @item __bis_SR_register_on_exit (int @var{mask})
16425 This sets the indicated bits in the saved copy of the status register
16426 currently residing on the stack. This only works inside interrupt
16427 handlers and the changes to the status register will only take affect
16428 once the handler returns.
16430 @item __delay_cycles (long long @var{cycles})
16431 This inserts an instruction sequence that takes exactly @var{cycles}
16432 cycles (between 0 and about 17E9) to complete. The inserted sequence
16433 may use jumps, loops, or no-ops, and does not interfere with any other
16434 instructions. Note that @var{cycles} must be a compile-time constant
16435 integer - that is, you must pass a number, not a variable that may be
16436 optimized to a constant later. The number of cycles delayed by this
16440 @node NDS32 Built-in Functions
16441 @subsection NDS32 Built-in Functions
16443 These built-in functions are available for the NDS32 target:
16445 @deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr})
16446 Insert an ISYNC instruction into the instruction stream where
16447 @var{addr} is an instruction address for serialization.
16450 @deftypefn {Built-in Function} void __builtin_nds32_isb (void)
16451 Insert an ISB instruction into the instruction stream.
16454 @deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr})
16455 Return the content of a system register which is mapped by @var{sr}.
16458 @deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr})
16459 Return the content of a user space register which is mapped by @var{usr}.
16462 @deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr})
16463 Move the @var{value} to a system register which is mapped by @var{sr}.
16466 @deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr})
16467 Move the @var{value} to a user space register which is mapped by @var{usr}.
16470 @deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void)
16471 Enable global interrupt.
16474 @deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void)
16475 Disable global interrupt.
16478 @node picoChip Built-in Functions
16479 @subsection picoChip Built-in Functions
16481 GCC provides an interface to selected machine instructions from the
16482 picoChip instruction set.
16485 @item int __builtin_sbc (int @var{value})
16486 Sign bit count. Return the number of consecutive bits in @var{value}
16487 that have the same value as the sign bit. The result is the number of
16488 leading sign bits minus one, giving the number of redundant sign bits in
16491 @item int __builtin_byteswap (int @var{value})
16492 Byte swap. Return the result of swapping the upper and lower bytes of
16495 @item int __builtin_brev (int @var{value})
16496 Bit reversal. Return the result of reversing the bits in
16497 @var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1,
16500 @item int __builtin_adds (int @var{x}, int @var{y})
16501 Saturating addition. Return the result of adding @var{x} and @var{y},
16502 storing the value 32767 if the result overflows.
16504 @item int __builtin_subs (int @var{x}, int @var{y})
16505 Saturating subtraction. Return the result of subtracting @var{y} from
16506 @var{x}, storing the value @minus{}32768 if the result overflows.
16508 @item void __builtin_halt (void)
16509 Halt. The processor stops execution. This built-in is useful for
16510 implementing assertions.
16514 @node Basic PowerPC Built-in Functions
16515 @subsection Basic PowerPC Built-in Functions
16518 * Basic PowerPC Built-in Functions Available on all Configurations::
16519 * Basic PowerPC Built-in Functions Available on ISA 2.05::
16520 * Basic PowerPC Built-in Functions Available on ISA 2.06::
16521 * Basic PowerPC Built-in Functions Available on ISA 2.07::
16522 * Basic PowerPC Built-in Functions Available on ISA 3.0::
16525 This section describes PowerPC built-in functions that do not require
16526 the inclusion of any special header files to declare prototypes or
16527 provide macro definitions. The sections that follow describe
16528 additional PowerPC built-in functions.
16530 @node Basic PowerPC Built-in Functions Available on all Configurations
16531 @subsubsection Basic PowerPC Built-in Functions Available on all Configurations
16533 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
16534 This function is a @code{nop} on the PowerPC platform and is included solely
16535 to maintain API compatibility with the x86 builtins.
16538 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
16539 This function returns a value of @code{1} if the run-time CPU is of type
16540 @var{cpuname} and returns @code{0} otherwise
16542 The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer
16543 which exports the hardware capability bits. GCC defines the macro
16544 @code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports}
16545 built-in function is fully supported.
16547 If GCC was configured to use a GLIBC before 2.23, the built-in
16548 function @code{__builtin_cpu_is} always returns a 0 and the compiler
16551 The following CPU names can be detected:
16555 IBM POWER9 Server CPU.
16557 IBM POWER8 Server CPU.
16559 IBM POWER7 Server CPU.
16561 IBM POWER6 Server CPU (RAW mode).
16563 IBM POWER6 Server CPU (Architected mode).
16565 IBM POWER5+ Server CPU.
16567 IBM POWER5 Server CPU.
16569 IBM 970 Server CPU (ie, Apple G5).
16571 IBM POWER4 Server CPU.
16573 IBM A2 64-bit Embedded CPU
16575 IBM PowerPC 476FP 32-bit Embedded CPU.
16577 IBM PowerPC 464 32-bit Embedded CPU.
16579 PowerPC 440 32-bit Embedded CPU.
16581 PowerPC 405 32-bit Embedded CPU.
16583 IBM PowerPC Cell Broadband Engine Architecture CPU.
16586 Here is an example:
16588 #ifdef __BUILTIN_CPU_SUPPORTS__
16589 if (__builtin_cpu_is ("power8"))
16591 do_power8 (); // POWER8 specific implementation.
16596 do_generic (); // Generic implementation.
16601 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
16602 This function returns a value of @code{1} if the run-time CPU supports the HWCAP
16603 feature @var{feature} and returns @code{0} otherwise.
16605 The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or
16606 newer which exports the hardware capability bits. GCC defines the
16607 macro @code{__BUILTIN_CPU_SUPPORTS__} if the
16608 @code{__builtin_cpu_supports} built-in function is fully supported.
16610 If GCC was configured to use a GLIBC before 2.23, the built-in
16611 function @code{__builtin_cpu_suports} always returns a 0 and the
16612 compiler issues a warning.
16614 The following features can be
16619 4xx CPU has a Multiply Accumulator.
16621 CPU has a SIMD/Vector Unit.
16623 CPU supports ISA 2.05 (eg, POWER6)
16625 CPU supports ISA 2.06 (eg, POWER7)
16627 CPU supports ISA 2.07 (eg, POWER8)
16629 CPU supports ISA 3.0 (eg, POWER9)
16631 CPU supports the set of compatible performance monitoring events.
16633 CPU supports the Embedded ISA category.
16635 CPU has a CELL broadband engine.
16637 CPU supports the @code{darn} (deliver a random number) instruction.
16639 CPU has a decimal floating point unit.
16641 CPU supports the data stream control register.
16643 CPU supports event base branching.
16645 CPU has a SPE double precision floating point unit.
16647 CPU has a SPE single precision floating point unit.
16649 CPU has a floating point unit.
16651 CPU has hardware transaction memory instructions.
16653 Kernel aborts hardware transactions when a syscall is made.
16654 @item htm-no-suspend
16655 CPU supports hardware transaction memory but does not support the
16656 @code{tsuspend.} instruction.
16658 CPU supports icache snooping capabilities.
16660 CPU supports 128-bit IEEE binary floating point instructions.
16662 CPU supports the integer select instruction.
16664 CPU has a memory management unit.
16666 CPU does not have a timebase (eg, 601 and 403gx).
16668 CPU supports the PA Semi 6T CORE ISA.
16670 CPU supports ISA 2.00 (eg, POWER4)
16672 CPU supports ISA 2.02 (eg, POWER5)
16674 CPU supports ISA 2.03 (eg, POWER5+)
16676 CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr.
16678 CPU supports 32-bit mode execution.
16680 CPU supports the old POWER ISA (eg, 601)
16682 CPU supports 64-bit mode execution.
16684 CPU supports a little-endian mode that uses address swizzling.
16686 Kernel supports system call vectored.
16688 CPU support simultaneous multi-threading.
16690 CPU has a signal processing extension unit.
16692 CPU supports the target address register.
16694 CPU supports true little-endian mode.
16696 CPU has unified I/D cache.
16698 CPU supports the vector cryptography instructions.
16700 CPU supports the vector-scalar extension.
16703 Here is an example:
16705 #ifdef __BUILTIN_CPU_SUPPORTS__
16706 if (__builtin_cpu_supports ("fpu"))
16708 asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2));
16713 dst = __fadd (src1, src2); // Software FP addition function.
16718 The following built-in functions are also available on all PowerPC
16721 uint64_t __builtin_ppc_get_timebase ();
16722 unsigned long __builtin_ppc_mftb ();
16723 double __builtin_unpack_ibm128 (__ibm128, int);
16724 __ibm128 __builtin_pack_ibm128 (double, double);
16725 double __builtin_mffs (void);
16726 void __builtin_mtfsb0 (const int);
16727 void __builtin_mtfsb1 (const int);
16728 void __builtin_set_fpscr_rn (int);
16731 The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb}
16732 functions generate instructions to read the Time Base Register. The
16733 @code{__builtin_ppc_get_timebase} function may generate multiple
16734 instructions and always returns the 64 bits of the Time Base Register.
16735 The @code{__builtin_ppc_mftb} function always generates one instruction and
16736 returns the Time Base Register value as an unsigned long, throwing away
16737 the most significant word on 32-bit environments. The @code{__builtin_mffs}
16738 return the value of the FPSCR register. Note, ISA 3.0 supports the
16739 @code{__builtin_mffsl()} which permits software to read the control and
16740 non-sticky status bits in the FSPCR without the higher latency associated with
16741 accessing the sticky status bits. The
16742 @code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change
16743 as an argument. The valid bit range is between 0 and 31. The builtins map to
16744 the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and
16745 add 32. Hence these instructions only modify the FPSCR[32:63] bits by
16746 changing the specified bit to a zero or one respectively. The
16747 @code{__builtin_set_fpscr_rn} builtin allows changing both of the floating
16748 point rounding mode bits. The argument is a 2-bit value. The argument can
16749 either be a @code{const int} or stored in a variable. The builtin uses
16751 instruction @code{mffscrn} if available, otherwise it reads the FPSCR, masks
16752 the current rounding mode bits out and OR's in the new value.
16754 @node Basic PowerPC Built-in Functions Available on ISA 2.05
16755 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05
16757 The basic built-in functions described in this section are
16758 available on the PowerPC family of processors starting with ISA 2.05
16759 or later. Unless specific options are explicitly disabled on the
16760 command line, specifying option @option{-mcpu=power6} has the effect of
16761 enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
16762 @option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb},
16763 @option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and
16764 @option{-mrecip-precision} options. Specify the
16765 @option{-maltivec} and @option{-mfpgpr} options explicitly in
16766 combination with the above options if they are desired.
16768 The following functions require option @option{-mcmpb}.
16770 unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int);
16771 unsigned int __builtin_cmpb (unsigned int, unsigned int);
16774 The @code{__builtin_cmpb} function
16775 performs a byte-wise compare on the contents of its two arguments,
16776 returning the result of the byte-wise comparison as the returned
16777 value. For each byte comparison, the corresponding byte of the return
16778 value holds 0xff if the input bytes are equal and 0 if the input bytes
16779 are not equal. If either of the arguments to this built-in function
16780 is wider than 32 bits, the function call expands into the form that
16781 expects @code{unsigned long long int} arguments
16782 which is only available on 64-bit targets.
16784 The following built-in functions are available
16785 when hardware decimal floating point
16786 (@option{-mhard-dfp}) is available:
16788 void __builtin_set_fpscr_drn(int);
16789 _Decimal64 __builtin_ddedpd (int, _Decimal64);
16790 _Decimal128 __builtin_ddedpdq (int, _Decimal128);
16791 _Decimal64 __builtin_denbcd (int, _Decimal64);
16792 _Decimal128 __builtin_denbcdq (int, _Decimal128);
16793 _Decimal64 __builtin_diex (long long, _Decimal64);
16794 _Decimal128 _builtin_diexq (long long, _Decimal128);
16795 _Decimal64 __builtin_dscli (_Decimal64, int);
16796 _Decimal128 __builtin_dscliq (_Decimal128, int);
16797 _Decimal64 __builtin_dscri (_Decimal64, int);
16798 _Decimal128 __builtin_dscriq (_Decimal128, int);
16799 long long __builtin_dxex (_Decimal64);
16800 long long __builtin_dxexq (_Decimal128);
16801 _Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long);
16802 unsigned long long __builtin_unpack_dec128 (_Decimal128, int);
16804 The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal
16805 floating point rounding mode bits. The argument is a 3-bit value. The
16806 argument can either be a @code{const int} or the value can be stored in
16808 The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available.
16809 Otherwise the builtin reads the FPSCR, masks the current decimal rounding
16810 mode bits out and OR's in the new value.
16814 The following functions require @option{-mhard-float},
16815 @option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options.
16818 double __builtin_recipdiv (double, double);
16819 float __builtin_recipdivf (float, float);
16820 double __builtin_rsqrt (double);
16821 float __builtin_rsqrtf (float);
16824 The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and
16825 @code{__builtin_rsqrtf} functions generate multiple instructions to
16826 implement the reciprocal sqrt functionality using reciprocal sqrt
16827 estimate instructions.
16829 The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf}
16830 functions generate multiple instructions to implement division using
16831 the reciprocal estimate instructions.
16833 The following functions require @option{-mhard-float} and
16834 @option{-mmultiple} options.
16836 The @code{__builtin_unpack_longdouble} function takes a
16837 @code{long double} argument and a compile time constant of 0 or 1. If
16838 the constant is 0, the first @code{double} within the
16839 @code{long double} is returned, otherwise the second @code{double}
16840 is returned. The @code{__builtin_unpack_longdouble} function is only
16841 available if @code{long double} uses the IBM extended double
16844 The @code{__builtin_pack_longdouble} function takes two @code{double}
16845 arguments and returns a @code{long double} value that combines the two
16846 arguments. The @code{__builtin_pack_longdouble} function is only
16847 available if @code{long double} uses the IBM extended double
16850 The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128}
16851 argument and a compile time constant of 0 or 1. If the constant is 0,
16852 the first @code{double} within the @code{__ibm128} is returned,
16853 otherwise the second @code{double} is returned.
16855 The @code{__builtin_pack_ibm128} function takes two @code{double}
16856 arguments and returns a @code{__ibm128} value that combines the two
16859 Additional built-in functions are available for the 64-bit PowerPC
16860 family of processors, for efficient use of 128-bit floating point
16861 (@code{__float128}) values.
16863 @node Basic PowerPC Built-in Functions Available on ISA 2.06
16864 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06
16866 The basic built-in functions described in this section are
16867 available on the PowerPC family of processors starting with ISA 2.05
16868 or later. Unless specific options are explicitly disabled on the
16869 command line, specifying option @option{-mcpu=power7} has the effect of
16870 enabling all the same options as for @option{-mcpu=power6} in
16871 addition to the @option{-maltivec}, @option{-mpopcntd}, and
16872 @option{-mvsx} options.
16874 The following basic built-in functions require @option{-mpopcntd}:
16876 unsigned int __builtin_addg6s (unsigned int, unsigned int);
16877 long long __builtin_bpermd (long long, long long);
16878 unsigned int __builtin_cbcdtd (unsigned int);
16879 unsigned int __builtin_cdtbcd (unsigned int);
16880 long long __builtin_divde (long long, long long);
16881 unsigned long long __builtin_divdeu (unsigned long long, unsigned long long);
16882 int __builtin_divwe (int, int);
16883 unsigned int __builtin_divweu (unsigned int, unsigned int);
16884 vector __int128 __builtin_pack_vector_int128 (long long, long long);
16885 void __builtin_rs6000_speculation_barrier (void);
16886 long long __builtin_unpack_vector_int128 (vector __int128, signed char);
16889 Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions
16890 require a 64-bit environment.
16892 The following basic built-in functions, which are also supported on
16893 x86 targets, require @option{-mfloat128}.
16895 __float128 __builtin_fabsq (__float128);
16896 __float128 __builtin_copysignq (__float128, __float128);
16897 __float128 __builtin_infq (void);
16898 __float128 __builtin_huge_valq (void);
16899 __float128 __builtin_nanq (void);
16900 __float128 __builtin_nansq (void);
16902 __float128 __builtin_sqrtf128 (__float128);
16903 __float128 __builtin_fmaf128 (__float128, __float128, __float128);
16906 @node Basic PowerPC Built-in Functions Available on ISA 2.07
16907 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07
16909 The basic built-in functions described in this section are
16910 available on the PowerPC family of processors starting with ISA 2.07
16911 or later. Unless specific options are explicitly disabled on the
16912 command line, specifying option @option{-mcpu=power8} has the effect of
16913 enabling all the same options as for @option{-mcpu=power7} in
16914 addition to the @option{-mpower8-fusion}, @option{-mpower8-vector},
16915 @option{-mcrypto}, @option{-mhtm}, @option{-mquad-memory}, and
16916 @option{-mquad-memory-atomic} options.
16918 This section intentionally empty.
16920 @node Basic PowerPC Built-in Functions Available on ISA 3.0
16921 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0
16923 The basic built-in functions described in this section are
16924 available on the PowerPC family of processors starting with ISA 3.0
16925 or later. Unless specific options are explicitly disabled on the
16926 command line, specifying option @option{-mcpu=power9} has the effect of
16927 enabling all the same options as for @option{-mcpu=power8} in
16928 addition to the @option{-misel} option.
16930 The following built-in functions are available on Linux 64-bit systems
16931 that use the ISA 3.0 instruction set (@option{-mcpu=power9}):
16934 @item __float128 __builtin_addf128_round_to_odd (__float128, __float128)
16935 Perform a 128-bit IEEE floating point add using round to odd as the
16937 @findex __builtin_addf128_round_to_odd
16939 @item __float128 __builtin_subf128_round_to_odd (__float128, __float128)
16940 Perform a 128-bit IEEE floating point subtract using round to odd as
16942 @findex __builtin_subf128_round_to_odd
16944 @item __float128 __builtin_mulf128_round_to_odd (__float128, __float128)
16945 Perform a 128-bit IEEE floating point multiply using round to odd as
16947 @findex __builtin_mulf128_round_to_odd
16949 @item __float128 __builtin_divf128_round_to_odd (__float128, __float128)
16950 Perform a 128-bit IEEE floating point divide using round to odd as
16952 @findex __builtin_divf128_round_to_odd
16954 @item __float128 __builtin_sqrtf128_round_to_odd (__float128)
16955 Perform a 128-bit IEEE floating point square root using round to odd
16956 as the rounding mode.
16957 @findex __builtin_sqrtf128_round_to_odd
16959 @item __float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128)
16960 Perform a 128-bit IEEE floating point fused multiply and add operation
16961 using round to odd as the rounding mode.
16962 @findex __builtin_fmaf128_round_to_odd
16964 @item double __builtin_truncf128_round_to_odd (__float128)
16965 Convert a 128-bit IEEE floating point value to @code{double} using
16966 round to odd as the rounding mode.
16967 @findex __builtin_truncf128_round_to_odd
16970 The following additional built-in functions are also available for the
16971 PowerPC family of processors, starting with ISA 3.0 or later:
16973 long long __builtin_darn (void);
16974 long long __builtin_darn_raw (void);
16975 int __builtin_darn_32 (void);
16978 The @code{__builtin_darn} and @code{__builtin_darn_raw}
16979 functions require a
16980 64-bit environment supporting ISA 3.0 or later.
16981 The @code{__builtin_darn} function provides a 64-bit conditioned
16982 random number. The @code{__builtin_darn_raw} function provides a
16983 64-bit raw random number. The @code{__builtin_darn_32} function
16984 provides a 32-bit conditioned random number.
16986 The following additional built-in functions are also available for the
16987 PowerPC family of processors, starting with ISA 3.0 or later:
16990 int __builtin_byte_in_set (unsigned char u, unsigned long long set);
16991 int __builtin_byte_in_range (unsigned char u, unsigned int range);
16992 int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges);
16994 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value);
16995 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value);
16996 int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value);
16997 int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value);
16999 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value);
17000 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value);
17001 int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value);
17002 int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value);
17004 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value);
17005 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value);
17006 int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value);
17007 int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value);
17009 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value);
17010 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value);
17011 int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value);
17012 int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value);
17014 double __builtin_mffsl(void);
17017 The @code{__builtin_byte_in_set} function requires a
17018 64-bit environment supporting ISA 3.0 or later. This function returns
17019 a non-zero value if and only if its @code{u} argument exactly equals one of
17020 the eight bytes contained within its 64-bit @code{set} argument.
17022 The @code{__builtin_byte_in_range} and
17023 @code{__builtin_byte_in_either_range} require an environment
17024 supporting ISA 3.0 or later. For these two functions, the
17025 @code{range} argument is encoded as 4 bytes, organized as
17026 @code{hi_1:lo_1:hi_2:lo_2}.
17027 The @code{__builtin_byte_in_range} function returns a
17028 non-zero value if and only if its @code{u} argument is within the
17029 range bounded between @code{lo_2} and @code{hi_2} inclusive.
17030 The @code{__builtin_byte_in_either_range} function returns non-zero if
17031 and only if its @code{u} argument is within either the range bounded
17032 between @code{lo_1} and @code{hi_1} inclusive or the range bounded
17033 between @code{lo_2} and @code{hi_2} inclusive.
17035 The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value
17036 if and only if the number of signficant digits of its @code{value} argument
17037 is less than its @code{comparison} argument. The
17038 @code{__builtin_dfp_dtstsfi_lt_dd} and
17039 @code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but
17040 require that the type of the @code{value} argument be
17041 @code{__Decimal64} and @code{__Decimal128} respectively.
17043 The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value
17044 if and only if the number of signficant digits of its @code{value} argument
17045 is greater than its @code{comparison} argument. The
17046 @code{__builtin_dfp_dtstsfi_gt_dd} and
17047 @code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but
17048 require that the type of the @code{value} argument be
17049 @code{__Decimal64} and @code{__Decimal128} respectively.
17051 The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value
17052 if and only if the number of signficant digits of its @code{value} argument
17053 equals its @code{comparison} argument. The
17054 @code{__builtin_dfp_dtstsfi_eq_dd} and
17055 @code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but
17056 require that the type of the @code{value} argument be
17057 @code{__Decimal64} and @code{__Decimal128} respectively.
17059 The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value
17060 if and only if its @code{value} argument has an undefined number of
17061 significant digits, such as when @code{value} is an encoding of @code{NaN}.
17062 The @code{__builtin_dfp_dtstsfi_ov_dd} and
17063 @code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but
17064 require that the type of the @code{value} argument be
17065 @code{__Decimal64} and @code{__Decimal128} respectively.
17067 The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read
17068 the FPSCR. The instruction is a lower latency version of the @code{mffs}
17069 instruction. If the @code{mffsl} instruction is not available, then the
17070 builtin uses the older @code{mffs} instruction to read the FPSCR.
17073 @node PowerPC AltiVec/VSX Built-in Functions
17074 @subsection PowerPC AltiVec/VSX Built-in Functions
17076 GCC provides an interface for the PowerPC family of processors to access
17077 the AltiVec operations described in Motorola's AltiVec Programming
17078 Interface Manual. The interface is made available by including
17079 @code{<altivec.h>} and using @option{-maltivec} and
17080 @option{-mabi=altivec}. The interface supports the following vector
17084 vector unsigned char
17088 vector unsigned short
17089 vector signed short
17093 vector unsigned int
17099 GCC's implementation of the high-level language interface available from
17100 C and C++ code differs from Motorola's documentation in several ways.
17105 A vector constant is a list of constant expressions within curly braces.
17108 A vector initializer requires no cast if the vector constant is of the
17109 same type as the variable it is initializing.
17112 If @code{signed} or @code{unsigned} is omitted, the signedness of the
17113 vector type is the default signedness of the base type. The default
17114 varies depending on the operating system, so a portable program should
17115 always specify the signedness.
17118 Compiling with @option{-maltivec} adds keywords @code{__vector},
17119 @code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and
17120 @code{bool}. When compiling ISO C, the context-sensitive substitution
17121 of the keywords @code{vector}, @code{pixel} and @code{bool} is
17122 disabled. To use them, you must include @code{<altivec.h>} instead.
17125 GCC allows using a @code{typedef} name as the type specifier for a
17126 vector type, but only under the following circumstances:
17131 When using @code{__vector} instead of @code{vector}; for example,
17134 typedef signed short int16;
17135 __vector int16 data;
17139 When using @code{vector} in keyword-and-predefine mode; for example,
17142 typedef signed short int16;
17146 Note that keyword-and-predefine mode is enabled by disabling GNU
17147 extensions (e.g., by using @code{-std=c11}) and including
17148 @code{<altivec.h>}.
17152 For C, overloaded functions are implemented with macros so the following
17156 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo);
17160 Since @code{vec_add} is a macro, the vector constant in the example
17161 is treated as four separate arguments. Wrap the entire argument in
17162 parentheses for this to work.
17165 @emph{Note:} Only the @code{<altivec.h>} interface is supported.
17166 Internally, GCC uses built-in functions to achieve the functionality in
17167 the aforementioned header file, but they are not supported and are
17168 subject to change without notice.
17170 GCC complies with the OpenPOWER 64-Bit ELF V2 ABI Specification,
17171 which may be found at
17172 @uref{http://openpowerfoundation.org/wp-content/uploads/resources/leabi-prd/content/index.html}.
17173 Appendix A of this document lists the vector API interfaces that must be
17174 provided by compliant compilers. Programmers should preferentially use
17175 the interfaces described therein. However, historically GCC has provided
17176 additional interfaces for access to vector instructions. These are
17177 briefly described below.
17180 * PowerPC AltiVec Built-in Functions on ISA 2.05::
17181 * PowerPC AltiVec Built-in Functions Available on ISA 2.06::
17182 * PowerPC AltiVec Built-in Functions Available on ISA 2.07::
17183 * PowerPC AltiVec Built-in Functions Available on ISA 3.0::
17186 @node PowerPC AltiVec Built-in Functions on ISA 2.05
17187 @subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05
17189 The following interfaces are supported for the generic and specific
17190 AltiVec operations and the AltiVec predicates. In cases where there
17191 is a direct mapping between generic and specific operations, only the
17192 generic names are shown here, although the specific operations can also
17195 Arguments that are documented as @code{const int} require literal
17196 integral values within the range required for that operation.
17199 vector signed char vec_abs (vector signed char);
17200 vector signed short vec_abs (vector signed short);
17201 vector signed int vec_abs (vector signed int);
17202 vector float vec_abs (vector float);
17204 vector signed char vec_abss (vector signed char);
17205 vector signed short vec_abss (vector signed short);
17206 vector signed int vec_abss (vector signed int);
17208 vector signed char vec_add (vector bool char, vector signed char);
17209 vector signed char vec_add (vector signed char, vector bool char);
17210 vector signed char vec_add (vector signed char, vector signed char);
17211 vector unsigned char vec_add (vector bool char, vector unsigned char);
17212 vector unsigned char vec_add (vector unsigned char, vector bool char);
17213 vector unsigned char vec_add (vector unsigned char, vector unsigned char);
17214 vector signed short vec_add (vector bool short, vector signed short);
17215 vector signed short vec_add (vector signed short, vector bool short);
17216 vector signed short vec_add (vector signed short, vector signed short);
17217 vector unsigned short vec_add (vector bool short, vector unsigned short);
17218 vector unsigned short vec_add (vector unsigned short, vector bool short);
17219 vector unsigned short vec_add (vector unsigned short, vector unsigned short);
17220 vector signed int vec_add (vector bool int, vector signed int);
17221 vector signed int vec_add (vector signed int, vector bool int);
17222 vector signed int vec_add (vector signed int, vector signed int);
17223 vector unsigned int vec_add (vector bool int, vector unsigned int);
17224 vector unsigned int vec_add (vector unsigned int, vector bool int);
17225 vector unsigned int vec_add (vector unsigned int, vector unsigned int);
17226 vector float vec_add (vector float, vector float);
17228 vector unsigned int vec_addc (vector unsigned int, vector unsigned int);
17230 vector unsigned char vec_adds (vector bool char, vector unsigned char);
17231 vector unsigned char vec_adds (vector unsigned char, vector bool char);
17232 vector unsigned char vec_adds (vector unsigned char, vector unsigned char);
17233 vector signed char vec_adds (vector bool char, vector signed char);
17234 vector signed char vec_adds (vector signed char, vector bool char);
17235 vector signed char vec_adds (vector signed char, vector signed char);
17236 vector unsigned short vec_adds (vector bool short, vector unsigned short);
17237 vector unsigned short vec_adds (vector unsigned short, vector bool short);
17238 vector unsigned short vec_adds (vector unsigned short, vector unsigned short);
17239 vector signed short vec_adds (vector bool short, vector signed short);
17240 vector signed short vec_adds (vector signed short, vector bool short);
17241 vector signed short vec_adds (vector signed short, vector signed short);
17242 vector unsigned int vec_adds (vector bool int, vector unsigned int);
17243 vector unsigned int vec_adds (vector unsigned int, vector bool int);
17244 vector unsigned int vec_adds (vector unsigned int, vector unsigned int);
17245 vector signed int vec_adds (vector bool int, vector signed int);
17246 vector signed int vec_adds (vector signed int, vector bool int);
17247 vector signed int vec_adds (vector signed int, vector signed int);
17249 int vec_all_eq (vector signed char, vector bool char);
17250 int vec_all_eq (vector signed char, vector signed char);
17251 int vec_all_eq (vector unsigned char, vector bool char);
17252 int vec_all_eq (vector unsigned char, vector unsigned char);
17253 int vec_all_eq (vector bool char, vector bool char);
17254 int vec_all_eq (vector bool char, vector unsigned char);
17255 int vec_all_eq (vector bool char, vector signed char);
17256 int vec_all_eq (vector signed short, vector bool short);
17257 int vec_all_eq (vector signed short, vector signed short);
17258 int vec_all_eq (vector unsigned short, vector bool short);
17259 int vec_all_eq (vector unsigned short, vector unsigned short);
17260 int vec_all_eq (vector bool short, vector bool short);
17261 int vec_all_eq (vector bool short, vector unsigned short);
17262 int vec_all_eq (vector bool short, vector signed short);
17263 int vec_all_eq (vector pixel, vector pixel);
17264 int vec_all_eq (vector signed int, vector bool int);
17265 int vec_all_eq (vector signed int, vector signed int);
17266 int vec_all_eq (vector unsigned int, vector bool int);
17267 int vec_all_eq (vector unsigned int, vector unsigned int);
17268 int vec_all_eq (vector bool int, vector bool int);
17269 int vec_all_eq (vector bool int, vector unsigned int);
17270 int vec_all_eq (vector bool int, vector signed int);
17271 int vec_all_eq (vector float, vector float);
17273 int vec_all_ge (vector bool char, vector unsigned char);
17274 int vec_all_ge (vector unsigned char, vector bool char);
17275 int vec_all_ge (vector unsigned char, vector unsigned char);
17276 int vec_all_ge (vector bool char, vector signed char);
17277 int vec_all_ge (vector signed char, vector bool char);
17278 int vec_all_ge (vector signed char, vector signed char);
17279 int vec_all_ge (vector bool short, vector unsigned short);
17280 int vec_all_ge (vector unsigned short, vector bool short);
17281 int vec_all_ge (vector unsigned short, vector unsigned short);
17282 int vec_all_ge (vector signed short, vector signed short);
17283 int vec_all_ge (vector bool short, vector signed short);
17284 int vec_all_ge (vector signed short, vector bool short);
17285 int vec_all_ge (vector bool int, vector unsigned int);
17286 int vec_all_ge (vector unsigned int, vector bool int);
17287 int vec_all_ge (vector unsigned int, vector unsigned int);
17288 int vec_all_ge (vector bool int, vector signed int);
17289 int vec_all_ge (vector signed int, vector bool int);
17290 int vec_all_ge (vector signed int, vector signed int);
17291 int vec_all_ge (vector float, vector float);
17293 int vec_all_gt (vector bool char, vector unsigned char);
17294 int vec_all_gt (vector unsigned char, vector bool char);
17295 int vec_all_gt (vector unsigned char, vector unsigned char);
17296 int vec_all_gt (vector bool char, vector signed char);
17297 int vec_all_gt (vector signed char, vector bool char);
17298 int vec_all_gt (vector signed char, vector signed char);
17299 int vec_all_gt (vector bool short, vector unsigned short);
17300 int vec_all_gt (vector unsigned short, vector bool short);
17301 int vec_all_gt (vector unsigned short, vector unsigned short);
17302 int vec_all_gt (vector bool short, vector signed short);
17303 int vec_all_gt (vector signed short, vector bool short);
17304 int vec_all_gt (vector signed short, vector signed short);
17305 int vec_all_gt (vector bool int, vector unsigned int);
17306 int vec_all_gt (vector unsigned int, vector bool int);
17307 int vec_all_gt (vector unsigned int, vector unsigned int);
17308 int vec_all_gt (vector bool int, vector signed int);
17309 int vec_all_gt (vector signed int, vector bool int);
17310 int vec_all_gt (vector signed int, vector signed int);
17311 int vec_all_gt (vector float, vector float);
17313 int vec_all_in (vector float, vector float);
17315 int vec_all_le (vector bool char, vector unsigned char);
17316 int vec_all_le (vector unsigned char, vector bool char);
17317 int vec_all_le (vector unsigned char, vector unsigned char);
17318 int vec_all_le (vector bool char, vector signed char);
17319 int vec_all_le (vector signed char, vector bool char);
17320 int vec_all_le (vector signed char, vector signed char);
17321 int vec_all_le (vector bool short, vector unsigned short);
17322 int vec_all_le (vector unsigned short, vector bool short);
17323 int vec_all_le (vector unsigned short, vector unsigned short);
17324 int vec_all_le (vector bool short, vector signed short);
17325 int vec_all_le (vector signed short, vector bool short);
17326 int vec_all_le (vector signed short, vector signed short);
17327 int vec_all_le (vector bool int, vector unsigned int);
17328 int vec_all_le (vector unsigned int, vector bool int);
17329 int vec_all_le (vector unsigned int, vector unsigned int);
17330 int vec_all_le (vector bool int, vector signed int);
17331 int vec_all_le (vector signed int, vector bool int);
17332 int vec_all_le (vector signed int, vector signed int);
17333 int vec_all_le (vector float, vector float);
17335 int vec_all_lt (vector bool char, vector unsigned char);
17336 int vec_all_lt (vector unsigned char, vector bool char);
17337 int vec_all_lt (vector unsigned char, vector unsigned char);
17338 int vec_all_lt (vector bool char, vector signed char);
17339 int vec_all_lt (vector signed char, vector bool char);
17340 int vec_all_lt (vector signed char, vector signed char);
17341 int vec_all_lt (vector bool short, vector unsigned short);
17342 int vec_all_lt (vector unsigned short, vector bool short);
17343 int vec_all_lt (vector unsigned short, vector unsigned short);
17344 int vec_all_lt (vector bool short, vector signed short);
17345 int vec_all_lt (vector signed short, vector bool short);
17346 int vec_all_lt (vector signed short, vector signed short);
17347 int vec_all_lt (vector bool int, vector unsigned int);
17348 int vec_all_lt (vector unsigned int, vector bool int);
17349 int vec_all_lt (vector unsigned int, vector unsigned int);
17350 int vec_all_lt (vector bool int, vector signed int);
17351 int vec_all_lt (vector signed int, vector bool int);
17352 int vec_all_lt (vector signed int, vector signed int);
17353 int vec_all_lt (vector float, vector float);
17355 int vec_all_nan (vector float);
17357 int vec_all_ne (vector signed char, vector bool char);
17358 int vec_all_ne (vector signed char, vector signed char);
17359 int vec_all_ne (vector unsigned char, vector bool char);
17360 int vec_all_ne (vector unsigned char, vector unsigned char);
17361 int vec_all_ne (vector bool char, vector bool char);
17362 int vec_all_ne (vector bool char, vector unsigned char);
17363 int vec_all_ne (vector bool char, vector signed char);
17364 int vec_all_ne (vector signed short, vector bool short);
17365 int vec_all_ne (vector signed short, vector signed short);
17366 int vec_all_ne (vector unsigned short, vector bool short);
17367 int vec_all_ne (vector unsigned short, vector unsigned short);
17368 int vec_all_ne (vector bool short, vector bool short);
17369 int vec_all_ne (vector bool short, vector unsigned short);
17370 int vec_all_ne (vector bool short, vector signed short);
17371 int vec_all_ne (vector pixel, vector pixel);
17372 int vec_all_ne (vector signed int, vector bool int);
17373 int vec_all_ne (vector signed int, vector signed int);
17374 int vec_all_ne (vector unsigned int, vector bool int);
17375 int vec_all_ne (vector unsigned int, vector unsigned int);
17376 int vec_all_ne (vector bool int, vector bool int);
17377 int vec_all_ne (vector bool int, vector unsigned int);
17378 int vec_all_ne (vector bool int, vector signed int);
17379 int vec_all_ne (vector float, vector float);
17381 int vec_all_nge (vector float, vector float);
17383 int vec_all_ngt (vector float, vector float);
17385 int vec_all_nle (vector float, vector float);
17387 int vec_all_nlt (vector float, vector float);
17389 int vec_all_numeric (vector float);
17391 vector float vec_and (vector float, vector float);
17392 vector float vec_and (vector float, vector bool int);
17393 vector float vec_and (vector bool int, vector float);
17394 vector bool int vec_and (vector bool int, vector bool int);
17395 vector signed int vec_and (vector bool int, vector signed int);
17396 vector signed int vec_and (vector signed int, vector bool int);
17397 vector signed int vec_and (vector signed int, vector signed int);
17398 vector unsigned int vec_and (vector bool int, vector unsigned int);
17399 vector unsigned int vec_and (vector unsigned int, vector bool int);
17400 vector unsigned int vec_and (vector unsigned int, vector unsigned int);
17401 vector bool short vec_and (vector bool short, vector bool short);
17402 vector signed short vec_and (vector bool short, vector signed short);
17403 vector signed short vec_and (vector signed short, vector bool short);
17404 vector signed short vec_and (vector signed short, vector signed short);
17405 vector unsigned short vec_and (vector bool short, vector unsigned short);
17406 vector unsigned short vec_and (vector unsigned short, vector bool short);
17407 vector unsigned short vec_and (vector unsigned short, vector unsigned short);
17408 vector signed char vec_and (vector bool char, vector signed char);
17409 vector bool char vec_and (vector bool char, vector bool char);
17410 vector signed char vec_and (vector signed char, vector bool char);
17411 vector signed char vec_and (vector signed char, vector signed char);
17412 vector unsigned char vec_and (vector bool char, vector unsigned char);
17413 vector unsigned char vec_and (vector unsigned char, vector bool char);
17414 vector unsigned char vec_and (vector unsigned char, vector unsigned char);
17416 vector float vec_andc (vector float, vector float);
17417 vector float vec_andc (vector float, vector bool int);
17418 vector float vec_andc (vector bool int, vector float);
17419 vector bool int vec_andc (vector bool int, vector bool int);
17420 vector signed int vec_andc (vector bool int, vector signed int);
17421 vector signed int vec_andc (vector signed int, vector bool int);
17422 vector signed int vec_andc (vector signed int, vector signed int);
17423 vector unsigned int vec_andc (vector bool int, vector unsigned int);
17424 vector unsigned int vec_andc (vector unsigned int, vector bool int);
17425 vector unsigned int vec_andc (vector unsigned int, vector unsigned int);
17426 vector bool short vec_andc (vector bool short, vector bool short);
17427 vector signed short vec_andc (vector bool short, vector signed short);
17428 vector signed short vec_andc (vector signed short, vector bool short);
17429 vector signed short vec_andc (vector signed short, vector signed short);
17430 vector unsigned short vec_andc (vector bool short, vector unsigned short);
17431 vector unsigned short vec_andc (vector unsigned short, vector bool short);
17432 vector unsigned short vec_andc (vector unsigned short, vector unsigned short);
17433 vector signed char vec_andc (vector bool char, vector signed char);
17434 vector bool char vec_andc (vector bool char, vector bool char);
17435 vector signed char vec_andc (vector signed char, vector bool char);
17436 vector signed char vec_andc (vector signed char, vector signed char);
17437 vector unsigned char vec_andc (vector bool char, vector unsigned char);
17438 vector unsigned char vec_andc (vector unsigned char, vector bool char);
17439 vector unsigned char vec_andc (vector unsigned char, vector unsigned char);
17441 int vec_any_eq (vector signed char, vector bool char);
17442 int vec_any_eq (vector signed char, vector signed char);
17443 int vec_any_eq (vector unsigned char, vector bool char);
17444 int vec_any_eq (vector unsigned char, vector unsigned char);
17445 int vec_any_eq (vector bool char, vector bool char);
17446 int vec_any_eq (vector bool char, vector unsigned char);
17447 int vec_any_eq (vector bool char, vector signed char);
17448 int vec_any_eq (vector signed short, vector bool short);
17449 int vec_any_eq (vector signed short, vector signed short);
17450 int vec_any_eq (vector unsigned short, vector bool short);
17451 int vec_any_eq (vector unsigned short, vector unsigned short);
17452 int vec_any_eq (vector bool short, vector bool short);
17453 int vec_any_eq (vector bool short, vector unsigned short);
17454 int vec_any_eq (vector bool short, vector signed short);
17455 int vec_any_eq (vector pixel, vector pixel);
17456 int vec_any_eq (vector signed int, vector bool int);
17457 int vec_any_eq (vector signed int, vector signed int);
17458 int vec_any_eq (vector unsigned int, vector bool int);
17459 int vec_any_eq (vector unsigned int, vector unsigned int);
17460 int vec_any_eq (vector bool int, vector bool int);
17461 int vec_any_eq (vector bool int, vector unsigned int);
17462 int vec_any_eq (vector bool int, vector signed int);
17463 int vec_any_eq (vector float, vector float);
17465 int vec_any_ge (vector signed char, vector bool char);
17466 int vec_any_ge (vector unsigned char, vector bool char);
17467 int vec_any_ge (vector unsigned char, vector unsigned char);
17468 int vec_any_ge (vector signed char, vector signed char);
17469 int vec_any_ge (vector bool char, vector unsigned char);
17470 int vec_any_ge (vector bool char, vector signed char);
17471 int vec_any_ge (vector unsigned short, vector bool short);
17472 int vec_any_ge (vector unsigned short, vector unsigned short);
17473 int vec_any_ge (vector signed short, vector signed short);
17474 int vec_any_ge (vector signed short, vector bool short);
17475 int vec_any_ge (vector bool short, vector unsigned short);
17476 int vec_any_ge (vector bool short, vector signed short);
17477 int vec_any_ge (vector signed int, vector bool int);
17478 int vec_any_ge (vector unsigned int, vector bool int);
17479 int vec_any_ge (vector unsigned int, vector unsigned int);
17480 int vec_any_ge (vector signed int, vector signed int);
17481 int vec_any_ge (vector bool int, vector unsigned int);
17482 int vec_any_ge (vector bool int, vector signed int);
17483 int vec_any_ge (vector float, vector float);
17485 int vec_any_gt (vector bool char, vector unsigned char);
17486 int vec_any_gt (vector unsigned char, vector bool char);
17487 int vec_any_gt (vector unsigned char, vector unsigned char);
17488 int vec_any_gt (vector bool char, vector signed char);
17489 int vec_any_gt (vector signed char, vector bool char);
17490 int vec_any_gt (vector signed char, vector signed char);
17491 int vec_any_gt (vector bool short, vector unsigned short);
17492 int vec_any_gt (vector unsigned short, vector bool short);
17493 int vec_any_gt (vector unsigned short, vector unsigned short);
17494 int vec_any_gt (vector bool short, vector signed short);
17495 int vec_any_gt (vector signed short, vector bool short);
17496 int vec_any_gt (vector signed short, vector signed short);
17497 int vec_any_gt (vector bool int, vector unsigned int);
17498 int vec_any_gt (vector unsigned int, vector bool int);
17499 int vec_any_gt (vector unsigned int, vector unsigned int);
17500 int vec_any_gt (vector bool int, vector signed int);
17501 int vec_any_gt (vector signed int, vector bool int);
17502 int vec_any_gt (vector signed int, vector signed int);
17503 int vec_any_gt (vector float, vector float);
17505 int vec_any_le (vector bool char, vector unsigned char);
17506 int vec_any_le (vector unsigned char, vector bool char);
17507 int vec_any_le (vector unsigned char, vector unsigned char);
17508 int vec_any_le (vector bool char, vector signed char);
17509 int vec_any_le (vector signed char, vector bool char);
17510 int vec_any_le (vector signed char, vector signed char);
17511 int vec_any_le (vector bool short, vector unsigned short);
17512 int vec_any_le (vector unsigned short, vector bool short);
17513 int vec_any_le (vector unsigned short, vector unsigned short);
17514 int vec_any_le (vector bool short, vector signed short);
17515 int vec_any_le (vector signed short, vector bool short);
17516 int vec_any_le (vector signed short, vector signed short);
17517 int vec_any_le (vector bool int, vector unsigned int);
17518 int vec_any_le (vector unsigned int, vector bool int);
17519 int vec_any_le (vector unsigned int, vector unsigned int);
17520 int vec_any_le (vector bool int, vector signed int);
17521 int vec_any_le (vector signed int, vector bool int);
17522 int vec_any_le (vector signed int, vector signed int);
17523 int vec_any_le (vector float, vector float);
17525 int vec_any_lt (vector bool char, vector unsigned char);
17526 int vec_any_lt (vector unsigned char, vector bool char);
17527 int vec_any_lt (vector unsigned char, vector unsigned char);
17528 int vec_any_lt (vector bool char, vector signed char);
17529 int vec_any_lt (vector signed char, vector bool char);
17530 int vec_any_lt (vector signed char, vector signed char);
17531 int vec_any_lt (vector bool short, vector unsigned short);
17532 int vec_any_lt (vector unsigned short, vector bool short);
17533 int vec_any_lt (vector unsigned short, vector unsigned short);
17534 int vec_any_lt (vector bool short, vector signed short);
17535 int vec_any_lt (vector signed short, vector bool short);
17536 int vec_any_lt (vector signed short, vector signed short);
17537 int vec_any_lt (vector bool int, vector unsigned int);
17538 int vec_any_lt (vector unsigned int, vector bool int);
17539 int vec_any_lt (vector unsigned int, vector unsigned int);
17540 int vec_any_lt (vector bool int, vector signed int);
17541 int vec_any_lt (vector signed int, vector bool int);
17542 int vec_any_lt (vector signed int, vector signed int);
17543 int vec_any_lt (vector float, vector float);
17545 int vec_any_nan (vector float);
17547 int vec_any_ne (vector signed char, vector bool char);
17548 int vec_any_ne (vector signed char, vector signed char);
17549 int vec_any_ne (vector unsigned char, vector bool char);
17550 int vec_any_ne (vector unsigned char, vector unsigned char);
17551 int vec_any_ne (vector bool char, vector bool char);
17552 int vec_any_ne (vector bool char, vector unsigned char);
17553 int vec_any_ne (vector bool char, vector signed char);
17554 int vec_any_ne (vector signed short, vector bool short);
17555 int vec_any_ne (vector signed short, vector signed short);
17556 int vec_any_ne (vector unsigned short, vector bool short);
17557 int vec_any_ne (vector unsigned short, vector unsigned short);
17558 int vec_any_ne (vector bool short, vector bool short);
17559 int vec_any_ne (vector bool short, vector unsigned short);
17560 int vec_any_ne (vector bool short, vector signed short);
17561 int vec_any_ne (vector pixel, vector pixel);
17562 int vec_any_ne (vector signed int, vector bool int);
17563 int vec_any_ne (vector signed int, vector signed int);
17564 int vec_any_ne (vector unsigned int, vector bool int);
17565 int vec_any_ne (vector unsigned int, vector unsigned int);
17566 int vec_any_ne (vector bool int, vector bool int);
17567 int vec_any_ne (vector bool int, vector unsigned int);
17568 int vec_any_ne (vector bool int, vector signed int);
17569 int vec_any_ne (vector float, vector float);
17571 int vec_any_nge (vector float, vector float);
17573 int vec_any_ngt (vector float, vector float);
17575 int vec_any_nle (vector float, vector float);
17577 int vec_any_nlt (vector float, vector float);
17579 int vec_any_numeric (vector float);
17581 int vec_any_out (vector float, vector float);
17583 vector unsigned char vec_avg (vector unsigned char, vector unsigned char);
17584 vector signed char vec_avg (vector signed char, vector signed char);
17585 vector unsigned short vec_avg (vector unsigned short, vector unsigned short);
17586 vector signed short vec_avg (vector signed short, vector signed short);
17587 vector unsigned int vec_avg (vector unsigned int, vector unsigned int);
17588 vector signed int vec_avg (vector signed int, vector signed int);
17590 vector float vec_ceil (vector float);
17592 vector signed int vec_cmpb (vector float, vector float);
17594 vector bool char vec_cmpeq (vector bool char, vector bool char);
17595 vector bool short vec_cmpeq (vector bool short, vector bool short);
17596 vector bool int vec_cmpeq (vector bool int, vector bool int);
17597 vector bool char vec_cmpeq (vector signed char, vector signed char);
17598 vector bool char vec_cmpeq (vector unsigned char, vector unsigned char);
17599 vector bool short vec_cmpeq (vector signed short, vector signed short);
17600 vector bool short vec_cmpeq (vector unsigned short, vector unsigned short);
17601 vector bool int vec_cmpeq (vector signed int, vector signed int);
17602 vector bool int vec_cmpeq (vector unsigned int, vector unsigned int);
17603 vector bool int vec_cmpeq (vector float, vector float);
17605 vector bool int vec_cmpge (vector float, vector float);
17607 vector bool char vec_cmpgt (vector unsigned char, vector unsigned char);
17608 vector bool char vec_cmpgt (vector signed char, vector signed char);
17609 vector bool short vec_cmpgt (vector unsigned short, vector unsigned short);
17610 vector bool short vec_cmpgt (vector signed short, vector signed short);
17611 vector bool int vec_cmpgt (vector unsigned int, vector unsigned int);
17612 vector bool int vec_cmpgt (vector signed int, vector signed int);
17613 vector bool int vec_cmpgt (vector float, vector float);
17615 vector bool int vec_cmple (vector float, vector float);
17617 vector bool char vec_cmplt (vector unsigned char, vector unsigned char);
17618 vector bool char vec_cmplt (vector signed char, vector signed char);
17619 vector bool short vec_cmplt (vector unsigned short, vector unsigned short);
17620 vector bool short vec_cmplt (vector signed short, vector signed short);
17621 vector bool int vec_cmplt (vector unsigned int, vector unsigned int);
17622 vector bool int vec_cmplt (vector signed int, vector signed int);
17623 vector bool int vec_cmplt (vector float, vector float);
17625 vector float vec_cpsgn (vector float, vector float);
17627 vector float vec_ctf (vector unsigned int, const int);
17628 vector float vec_ctf (vector signed int, const int);
17630 vector signed int vec_cts (vector float, const int);
17632 vector unsigned int vec_ctu (vector float, const int);
17634 void vec_dss (const int);
17636 void vec_dssall (void);
17638 void vec_dst (const vector unsigned char *, int, const int);
17639 void vec_dst (const vector signed char *, int, const int);
17640 void vec_dst (const vector bool char *, int, const int);
17641 void vec_dst (const vector unsigned short *, int, const int);
17642 void vec_dst (const vector signed short *, int, const int);
17643 void vec_dst (const vector bool short *, int, const int);
17644 void vec_dst (const vector pixel *, int, const int);
17645 void vec_dst (const vector unsigned int *, int, const int);
17646 void vec_dst (const vector signed int *, int, const int);
17647 void vec_dst (const vector bool int *, int, const int);
17648 void vec_dst (const vector float *, int, const int);
17649 void vec_dst (const unsigned char *, int, const int);
17650 void vec_dst (const signed char *, int, const int);
17651 void vec_dst (const unsigned short *, int, const int);
17652 void vec_dst (const short *, int, const int);
17653 void vec_dst (const unsigned int *, int, const int);
17654 void vec_dst (const int *, int, const int);
17655 void vec_dst (const float *, int, const int);
17657 void vec_dstst (const vector unsigned char *, int, const int);
17658 void vec_dstst (const vector signed char *, int, const int);
17659 void vec_dstst (const vector bool char *, int, const int);
17660 void vec_dstst (const vector unsigned short *, int, const int);
17661 void vec_dstst (const vector signed short *, int, const int);
17662 void vec_dstst (const vector bool short *, int, const int);
17663 void vec_dstst (const vector pixel *, int, const int);
17664 void vec_dstst (const vector unsigned int *, int, const int);
17665 void vec_dstst (const vector signed int *, int, const int);
17666 void vec_dstst (const vector bool int *, int, const int);
17667 void vec_dstst (const vector float *, int, const int);
17668 void vec_dstst (const unsigned char *, int, const int);
17669 void vec_dstst (const signed char *, int, const int);
17670 void vec_dstst (const unsigned short *, int, const int);
17671 void vec_dstst (const short *, int, const int);
17672 void vec_dstst (const unsigned int *, int, const int);
17673 void vec_dstst (const int *, int, const int);
17674 void vec_dstst (const unsigned long *, int, const int);
17675 void vec_dstst (const long *, int, const int);
17676 void vec_dstst (const float *, int, const int);
17678 void vec_dststt (const vector unsigned char *, int, const int);
17679 void vec_dststt (const vector signed char *, int, const int);
17680 void vec_dststt (const vector bool char *, int, const int);
17681 void vec_dststt (const vector unsigned short *, int, const int);
17682 void vec_dststt (const vector signed short *, int, const int);
17683 void vec_dststt (const vector bool short *, int, const int);
17684 void vec_dststt (const vector pixel *, int, const int);
17685 void vec_dststt (const vector unsigned int *, int, const int);
17686 void vec_dststt (const vector signed int *, int, const int);
17687 void vec_dststt (const vector bool int *, int, const int);
17688 void vec_dststt (const vector float *, int, const int);
17689 void vec_dststt (const unsigned char *, int, const int);
17690 void vec_dststt (const signed char *, int, const int);
17691 void vec_dststt (const unsigned short *, int, const int);
17692 void vec_dststt (const short *, int, const int);
17693 void vec_dststt (const unsigned int *, int, const int);
17694 void vec_dststt (const int *, int, const int);
17695 void vec_dststt (const float *, int, const int);
17697 void vec_dstt (const vector unsigned char *, int, const int);
17698 void vec_dstt (const vector signed char *, int, const int);
17699 void vec_dstt (const vector bool char *, int, const int);
17700 void vec_dstt (const vector unsigned short *, int, const int);
17701 void vec_dstt (const vector signed short *, int, const int);
17702 void vec_dstt (const vector bool short *, int, const int);
17703 void vec_dstt (const vector pixel *, int, const int);
17704 void vec_dstt (const vector unsigned int *, int, const int);
17705 void vec_dstt (const vector signed int *, int, const int);
17706 void vec_dstt (const vector bool int *, int, const int);
17707 void vec_dstt (const vector float *, int, const int);
17708 void vec_dstt (const unsigned char *, int, const int);
17709 void vec_dstt (const signed char *, int, const int);
17710 void vec_dstt (const unsigned short *, int, const int);
17711 void vec_dstt (const short *, int, const int);
17712 void vec_dstt (const unsigned int *, int, const int);
17713 void vec_dstt (const int *, int, const int);
17714 void vec_dstt (const float *, int, const int);
17716 vector float vec_expte (vector float);
17718 vector float vec_floor (vector float);
17720 vector float vec_ld (int, const vector float *);
17721 vector float vec_ld (int, const float *);
17722 vector bool int vec_ld (int, const vector bool int *);
17723 vector signed int vec_ld (int, const vector signed int *);
17724 vector signed int vec_ld (int, const int *);
17725 vector unsigned int vec_ld (int, const vector unsigned int *);
17726 vector unsigned int vec_ld (int, const unsigned int *);
17727 vector bool short vec_ld (int, const vector bool short *);
17728 vector pixel vec_ld (int, const vector pixel *);
17729 vector signed short vec_ld (int, const vector signed short *);
17730 vector signed short vec_ld (int, const short *);
17731 vector unsigned short vec_ld (int, const vector unsigned short *);
17732 vector unsigned short vec_ld (int, const unsigned short *);
17733 vector bool char vec_ld (int, const vector bool char *);
17734 vector signed char vec_ld (int, const vector signed char *);
17735 vector signed char vec_ld (int, const signed char *);
17736 vector unsigned char vec_ld (int, const vector unsigned char *);
17737 vector unsigned char vec_ld (int, const unsigned char *);
17739 vector signed char vec_lde (int, const signed char *);
17740 vector unsigned char vec_lde (int, const unsigned char *);
17741 vector signed short vec_lde (int, const short *);
17742 vector unsigned short vec_lde (int, const unsigned short *);
17743 vector float vec_lde (int, const float *);
17744 vector signed int vec_lde (int, const int *);
17745 vector unsigned int vec_lde (int, const unsigned int *);
17747 vector float vec_ldl (int, const vector float *);
17748 vector float vec_ldl (int, const float *);
17749 vector bool int vec_ldl (int, const vector bool int *);
17750 vector signed int vec_ldl (int, const vector signed int *);
17751 vector signed int vec_ldl (int, const int *);
17752 vector unsigned int vec_ldl (int, const vector unsigned int *);
17753 vector unsigned int vec_ldl (int, const unsigned int *);
17754 vector bool short vec_ldl (int, const vector bool short *);
17755 vector pixel vec_ldl (int, const vector pixel *);
17756 vector signed short vec_ldl (int, const vector signed short *);
17757 vector signed short vec_ldl (int, const short *);
17758 vector unsigned short vec_ldl (int, const vector unsigned short *);
17759 vector unsigned short vec_ldl (int, const unsigned short *);
17760 vector bool char vec_ldl (int, const vector bool char *);
17761 vector signed char vec_ldl (int, const vector signed char *);
17762 vector signed char vec_ldl (int, const signed char *);
17763 vector unsigned char vec_ldl (int, const vector unsigned char *);
17764 vector unsigned char vec_ldl (int, const unsigned char *);
17766 vector float vec_loge (vector float);
17768 vector signed char vec_lvebx (int, char *);
17769 vector unsigned char vec_lvebx (int, unsigned char *);
17771 vector signed short vec_lvehx (int, short *);
17772 vector unsigned short vec_lvehx (int, unsigned short *);
17774 vector float vec_lvewx (int, float *);
17775 vector signed int vec_lvewx (int, int *);
17776 vector unsigned int vec_lvewx (int, unsigned int *);
17778 vector unsigned char vec_lvsl (int, const unsigned char *);
17779 vector unsigned char vec_lvsl (int, const signed char *);
17780 vector unsigned char vec_lvsl (int, const unsigned short *);
17781 vector unsigned char vec_lvsl (int, const short *);
17782 vector unsigned char vec_lvsl (int, const unsigned int *);
17783 vector unsigned char vec_lvsl (int, const int *);
17784 vector unsigned char vec_lvsl (int, const float *);
17786 vector unsigned char vec_lvsr (int, const unsigned char *);
17787 vector unsigned char vec_lvsr (int, const signed char *);
17788 vector unsigned char vec_lvsr (int, const unsigned short *);
17789 vector unsigned char vec_lvsr (int, const short *);
17790 vector unsigned char vec_lvsr (int, const unsigned int *);
17791 vector unsigned char vec_lvsr (int, const int *);
17792 vector unsigned char vec_lvsr (int, const float *);
17794 vector float vec_madd (vector float, vector float, vector float);
17796 vector signed short vec_madds (vector signed short, vector signed short,
17797 vector signed short);
17799 vector unsigned char vec_max (vector bool char, vector unsigned char);
17800 vector unsigned char vec_max (vector unsigned char, vector bool char);
17801 vector unsigned char vec_max (vector unsigned char, vector unsigned char);
17802 vector signed char vec_max (vector bool char, vector signed char);
17803 vector signed char vec_max (vector signed char, vector bool char);
17804 vector signed char vec_max (vector signed char, vector signed char);
17805 vector unsigned short vec_max (vector bool short, vector unsigned short);
17806 vector unsigned short vec_max (vector unsigned short, vector bool short);
17807 vector unsigned short vec_max (vector unsigned short, vector unsigned short);
17808 vector signed short vec_max (vector bool short, vector signed short);
17809 vector signed short vec_max (vector signed short, vector bool short);
17810 vector signed short vec_max (vector signed short, vector signed short);
17811 vector unsigned int vec_max (vector bool int, vector unsigned int);
17812 vector unsigned int vec_max (vector unsigned int, vector bool int);
17813 vector unsigned int vec_max (vector unsigned int, vector unsigned int);
17814 vector signed int vec_max (vector bool int, vector signed int);
17815 vector signed int vec_max (vector signed int, vector bool int);
17816 vector signed int vec_max (vector signed int, vector signed int);
17817 vector float vec_max (vector float, vector float);
17819 vector bool char vec_mergeh (vector bool char, vector bool char);
17820 vector signed char vec_mergeh (vector signed char, vector signed char);
17821 vector unsigned char vec_mergeh (vector unsigned char, vector unsigned char);
17822 vector bool short vec_mergeh (vector bool short, vector bool short);
17823 vector pixel vec_mergeh (vector pixel, vector pixel);
17824 vector signed short vec_mergeh (vector signed short, vector signed short);
17825 vector unsigned short vec_mergeh (vector unsigned short, vector unsigned short);
17826 vector float vec_mergeh (vector float, vector float);
17827 vector bool int vec_mergeh (vector bool int, vector bool int);
17828 vector signed int vec_mergeh (vector signed int, vector signed int);
17829 vector unsigned int vec_mergeh (vector unsigned int, vector unsigned int);
17831 vector bool char vec_mergel (vector bool char, vector bool char);
17832 vector signed char vec_mergel (vector signed char, vector signed char);
17833 vector unsigned char vec_mergel (vector unsigned char, vector unsigned char);
17834 vector bool short vec_mergel (vector bool short, vector bool short);
17835 vector pixel vec_mergel (vector pixel, vector pixel);
17836 vector signed short vec_mergel (vector signed short, vector signed short);
17837 vector unsigned short vec_mergel (vector unsigned short, vector unsigned short);
17838 vector float vec_mergel (vector float, vector float);
17839 vector bool int vec_mergel (vector bool int, vector bool int);
17840 vector signed int vec_mergel (vector signed int, vector signed int);
17841 vector unsigned int vec_mergel (vector unsigned int, vector unsigned int);
17843 vector unsigned short vec_mfvscr (void);
17845 vector unsigned char vec_min (vector bool char, vector unsigned char);
17846 vector unsigned char vec_min (vector unsigned char, vector bool char);
17847 vector unsigned char vec_min (vector unsigned char, vector unsigned char);
17848 vector signed char vec_min (vector bool char, vector signed char);
17849 vector signed char vec_min (vector signed char, vector bool char);
17850 vector signed char vec_min (vector signed char, vector signed char);
17851 vector unsigned short vec_min (vector bool short, vector unsigned short);
17852 vector unsigned short vec_min (vector unsigned short, vector bool short);
17853 vector unsigned short vec_min (vector unsigned short, vector unsigned short);
17854 vector signed short vec_min (vector bool short, vector signed short);
17855 vector signed short vec_min (vector signed short, vector bool short);
17856 vector signed short vec_min (vector signed short, vector signed short);
17857 vector unsigned int vec_min (vector bool int, vector unsigned int);
17858 vector unsigned int vec_min (vector unsigned int, vector bool int);
17859 vector unsigned int vec_min (vector unsigned int, vector unsigned int);
17860 vector signed int vec_min (vector bool int, vector signed int);
17861 vector signed int vec_min (vector signed int, vector bool int);
17862 vector signed int vec_min (vector signed int, vector signed int);
17863 vector float vec_min (vector float, vector float);
17865 vector signed short vec_mladd (vector signed short, vector signed short,
17866 vector signed short);
17867 vector signed short vec_mladd (vector signed short, vector unsigned short,
17868 vector unsigned short);
17869 vector signed short vec_mladd (vector unsigned short, vector signed short,
17870 vector signed short);
17871 vector unsigned short vec_mladd (vector unsigned short, vector unsigned short,
17872 vector unsigned short);
17874 vector signed short vec_mradds (vector signed short, vector signed short,
17875 vector signed short);
17877 vector unsigned int vec_msum (vector unsigned char, vector unsigned char,
17878 vector unsigned int);
17879 vector signed int vec_msum (vector signed char, vector unsigned char,
17880 vector signed int);
17881 vector unsigned int vec_msum (vector unsigned short, vector unsigned short,
17882 vector unsigned int);
17883 vector signed int vec_msum (vector signed short, vector signed short,
17884 vector signed int);
17886 vector unsigned int vec_msums (vector unsigned short, vector unsigned short,
17887 vector unsigned int);
17888 vector signed int vec_msums (vector signed short, vector signed short,
17889 vector signed int);
17891 void vec_mtvscr (vector signed int);
17892 void vec_mtvscr (vector unsigned int);
17893 void vec_mtvscr (vector bool int);
17894 void vec_mtvscr (vector signed short);
17895 void vec_mtvscr (vector unsigned short);
17896 void vec_mtvscr (vector bool short);
17897 void vec_mtvscr (vector pixel);
17898 void vec_mtvscr (vector signed char);
17899 void vec_mtvscr (vector unsigned char);
17900 void vec_mtvscr (vector bool char);
17902 vector float vec_mul (vector float, vector float);
17904 vector unsigned short vec_mule (vector unsigned char, vector unsigned char);
17905 vector signed short vec_mule (vector signed char, vector signed char);
17906 vector unsigned int vec_mule (vector unsigned short, vector unsigned short);
17907 vector signed int vec_mule (vector signed short, vector signed short);
17909 vector unsigned short vec_mulo (vector unsigned char, vector unsigned char);
17910 vector signed short vec_mulo (vector signed char, vector signed char);
17911 vector unsigned int vec_mulo (vector unsigned short, vector unsigned short);
17912 vector signed int vec_mulo (vector signed short, vector signed short);
17914 vector signed char vec_nabs (vector signed char);
17915 vector signed short vec_nabs (vector signed short);
17916 vector signed int vec_nabs (vector signed int);
17917 vector float vec_nabs (vector float);
17919 vector float vec_nmsub (vector float, vector float, vector float);
17921 vector float vec_nor (vector float, vector float);
17922 vector signed int vec_nor (vector signed int, vector signed int);
17923 vector unsigned int vec_nor (vector unsigned int, vector unsigned int);
17924 vector bool int vec_nor (vector bool int, vector bool int);
17925 vector signed short vec_nor (vector signed short, vector signed short);
17926 vector unsigned short vec_nor (vector unsigned short, vector unsigned short);
17927 vector bool short vec_nor (vector bool short, vector bool short);
17928 vector signed char vec_nor (vector signed char, vector signed char);
17929 vector unsigned char vec_nor (vector unsigned char, vector unsigned char);
17930 vector bool char vec_nor (vector bool char, vector bool char);
17932 vector float vec_or (vector float, vector float);
17933 vector float vec_or (vector float, vector bool int);
17934 vector float vec_or (vector bool int, vector float);
17935 vector bool int vec_or (vector bool int, vector bool int);
17936 vector signed int vec_or (vector bool int, vector signed int);
17937 vector signed int vec_or (vector signed int, vector bool int);
17938 vector signed int vec_or (vector signed int, vector signed int);
17939 vector unsigned int vec_or (vector bool int, vector unsigned int);
17940 vector unsigned int vec_or (vector unsigned int, vector bool int);
17941 vector unsigned int vec_or (vector unsigned int, vector unsigned int);
17942 vector bool short vec_or (vector bool short, vector bool short);
17943 vector signed short vec_or (vector bool short, vector signed short);
17944 vector signed short vec_or (vector signed short, vector bool short);
17945 vector signed short vec_or (vector signed short, vector signed short);
17946 vector unsigned short vec_or (vector bool short, vector unsigned short);
17947 vector unsigned short vec_or (vector unsigned short, vector bool short);
17948 vector unsigned short vec_or (vector unsigned short, vector unsigned short);
17949 vector signed char vec_or (vector bool char, vector signed char);
17950 vector bool char vec_or (vector bool char, vector bool char);
17951 vector signed char vec_or (vector signed char, vector bool char);
17952 vector signed char vec_or (vector signed char, vector signed char);
17953 vector unsigned char vec_or (vector bool char, vector unsigned char);
17954 vector unsigned char vec_or (vector unsigned char, vector bool char);
17955 vector unsigned char vec_or (vector unsigned char, vector unsigned char);
17957 vector signed char vec_pack (vector signed short, vector signed short);
17958 vector unsigned char vec_pack (vector unsigned short, vector unsigned short);
17959 vector bool char vec_pack (vector bool short, vector bool short);
17960 vector signed short vec_pack (vector signed int, vector signed int);
17961 vector unsigned short vec_pack (vector unsigned int, vector unsigned int);
17962 vector bool short vec_pack (vector bool int, vector bool int);
17964 vector pixel vec_packpx (vector unsigned int, vector unsigned int);
17966 vector unsigned char vec_packs (vector unsigned short, vector unsigned short);
17967 vector signed char vec_packs (vector signed short, vector signed short);
17968 vector unsigned short vec_packs (vector unsigned int, vector unsigned int);
17969 vector signed short vec_packs (vector signed int, vector signed int);
17971 vector unsigned char vec_packsu (vector unsigned short, vector unsigned short);
17972 vector unsigned char vec_packsu (vector signed short, vector signed short);
17973 vector unsigned short vec_packsu (vector unsigned int, vector unsigned int);
17974 vector unsigned short vec_packsu (vector signed int, vector signed int);
17976 vector float vec_perm (vector float, vector float, vector unsigned char);
17977 vector signed int vec_perm (vector signed int, vector signed int, vector unsigned char);
17978 vector unsigned int vec_perm (vector unsigned int, vector unsigned int,
17979 vector unsigned char);
17980 vector bool int vec_perm (vector bool int, vector bool int, vector unsigned char);
17981 vector signed short vec_perm (vector signed short, vector signed short,
17982 vector unsigned char);
17983 vector unsigned short vec_perm (vector unsigned short, vector unsigned short,
17984 vector unsigned char);
17985 vector bool short vec_perm (vector bool short, vector bool short, vector unsigned char);
17986 vector pixel vec_perm (vector pixel, vector pixel, vector unsigned char);
17987 vector signed char vec_perm (vector signed char, vector signed char,
17988 vector unsigned char);
17989 vector unsigned char vec_perm (vector unsigned char, vector unsigned char,
17990 vector unsigned char);
17991 vector bool char vec_perm (vector bool char, vector bool char, vector unsigned char);
17993 vector float vec_re (vector float);
17995 vector bool char vec_reve (vector bool char);
17996 vector signed char vec_reve (vector signed char);
17997 vector unsigned char vec_reve (vector unsigned char);
17998 vector bool int vec_reve (vector bool int);
17999 vector signed int vec_reve (vector signed int);
18000 vector unsigned int vec_reve (vector unsigned int);
18001 vector bool short vec_reve (vector bool short);
18002 vector signed short vec_reve (vector signed short);
18003 vector unsigned short vec_reve (vector unsigned short);
18005 vector signed char vec_rl (vector signed char, vector unsigned char);
18006 vector unsigned char vec_rl (vector unsigned char, vector unsigned char);
18007 vector signed short vec_rl (vector signed short, vector unsigned short);
18008 vector unsigned short vec_rl (vector unsigned short, vector unsigned short);
18009 vector signed int vec_rl (vector signed int, vector unsigned int);
18010 vector unsigned int vec_rl (vector unsigned int, vector unsigned int);
18012 vector float vec_round (vector float);
18014 vector float vec_rsqrt (vector float);
18016 vector float vec_rsqrte (vector float);
18018 vector float vec_sel (vector float, vector float, vector bool int);
18019 vector float vec_sel (vector float, vector float, vector unsigned int);
18020 vector signed int vec_sel (vector signed int, vector signed int, vector bool int);
18021 vector signed int vec_sel (vector signed int, vector signed int, vector unsigned int);
18022 vector unsigned int vec_sel (vector unsigned int, vector unsigned int, vector bool int);
18023 vector unsigned int vec_sel (vector unsigned int, vector unsigned int,
18024 vector unsigned int);
18025 vector bool int vec_sel (vector bool int, vector bool int, vector bool int);
18026 vector bool int vec_sel (vector bool int, vector bool int, vector unsigned int);
18027 vector signed short vec_sel (vector signed short, vector signed short,
18028 vector bool short);
18029 vector signed short vec_sel (vector signed short, vector signed short,
18030 vector unsigned short);
18031 vector unsigned short vec_sel (vector unsigned short, vector unsigned short,
18032 vector bool short);
18033 vector unsigned short vec_sel (vector unsigned short, vector unsigned short,
18034 vector unsigned short);
18035 vector bool short vec_sel (vector bool short, vector bool short, vector bool short);
18036 vector bool short vec_sel (vector bool short, vector bool short, vector unsigned short);
18037 vector signed char vec_sel (vector signed char, vector signed char, vector bool char);
18038 vector signed char vec_sel (vector signed char, vector signed char,
18039 vector unsigned char);
18040 vector unsigned char vec_sel (vector unsigned char, vector unsigned char,
18042 vector unsigned char vec_sel (vector unsigned char, vector unsigned char,
18043 vector unsigned char);
18044 vector bool char vec_sel (vector bool char, vector bool char, vector bool char);
18045 vector bool char vec_sel (vector bool char, vector bool char, vector unsigned char);
18047 vector signed char vec_sl (vector signed char, vector unsigned char);
18048 vector unsigned char vec_sl (vector unsigned char, vector unsigned char);
18049 vector signed short vec_sl (vector signed short, vector unsigned short);
18050 vector unsigned short vec_sl (vector unsigned short, vector unsigned short);
18051 vector signed int vec_sl (vector signed int, vector unsigned int);
18052 vector unsigned int vec_sl (vector unsigned int, vector unsigned int);
18054 vector float vec_sld (vector float, vector float, const int);
18055 vector signed int vec_sld (vector signed int, vector signed int, const int);
18056 vector unsigned int vec_sld (vector unsigned int, vector unsigned int, const int);
18057 vector bool int vec_sld (vector bool int, vector bool int, const int);
18058 vector signed short vec_sld (vector signed short, vector signed short, const int);
18059 vector unsigned short vec_sld (vector unsigned short, vector unsigned short, const int);
18060 vector bool short vec_sld (vector bool short, vector bool short, const int);
18061 vector pixel vec_sld (vector pixel, vector pixel, const int);
18062 vector signed char vec_sld (vector signed char, vector signed char, const int);
18063 vector unsigned char vec_sld (vector unsigned char, vector unsigned char, const int);
18064 vector bool char vec_sld (vector bool char, vector bool char, const int);
18066 vector signed int vec_sll (vector signed int, vector unsigned int);
18067 vector signed int vec_sll (vector signed int, vector unsigned short);
18068 vector signed int vec_sll (vector signed int, vector unsigned char);
18069 vector unsigned int vec_sll (vector unsigned int, vector unsigned int);
18070 vector unsigned int vec_sll (vector unsigned int, vector unsigned short);
18071 vector unsigned int vec_sll (vector unsigned int, vector unsigned char);
18072 vector bool int vec_sll (vector bool int, vector unsigned int);
18073 vector bool int vec_sll (vector bool int, vector unsigned short);
18074 vector bool int vec_sll (vector bool int, vector unsigned char);
18075 vector signed short vec_sll (vector signed short, vector unsigned int);
18076 vector signed short vec_sll (vector signed short, vector unsigned short);
18077 vector signed short vec_sll (vector signed short, vector unsigned char);
18078 vector unsigned short vec_sll (vector unsigned short, vector unsigned int);
18079 vector unsigned short vec_sll (vector unsigned short, vector unsigned short);
18080 vector unsigned short vec_sll (vector unsigned short, vector unsigned char);
18081 vector bool short vec_sll (vector bool short, vector unsigned int);
18082 vector bool short vec_sll (vector bool short, vector unsigned short);
18083 vector bool short vec_sll (vector bool short, vector unsigned char);
18084 vector pixel vec_sll (vector pixel, vector unsigned int);
18085 vector pixel vec_sll (vector pixel, vector unsigned short);
18086 vector pixel vec_sll (vector pixel, vector unsigned char);
18087 vector signed char vec_sll (vector signed char, vector unsigned int);
18088 vector signed char vec_sll (vector signed char, vector unsigned short);
18089 vector signed char vec_sll (vector signed char, vector unsigned char);
18090 vector unsigned char vec_sll (vector unsigned char, vector unsigned int);
18091 vector unsigned char vec_sll (vector unsigned char, vector unsigned short);
18092 vector unsigned char vec_sll (vector unsigned char, vector unsigned char);
18093 vector bool char vec_sll (vector bool char, vector unsigned int);
18094 vector bool char vec_sll (vector bool char, vector unsigned short);
18095 vector bool char vec_sll (vector bool char, vector unsigned char);
18097 vector float vec_slo (vector float, vector signed char);
18098 vector float vec_slo (vector float, vector unsigned char);
18099 vector signed int vec_slo (vector signed int, vector signed char);
18100 vector signed int vec_slo (vector signed int, vector unsigned char);
18101 vector unsigned int vec_slo (vector unsigned int, vector signed char);
18102 vector unsigned int vec_slo (vector unsigned int, vector unsigned char);
18103 vector signed short vec_slo (vector signed short, vector signed char);
18104 vector signed short vec_slo (vector signed short, vector unsigned char);
18105 vector unsigned short vec_slo (vector unsigned short, vector signed char);
18106 vector unsigned short vec_slo (vector unsigned short, vector unsigned char);
18107 vector pixel vec_slo (vector pixel, vector signed char);
18108 vector pixel vec_slo (vector pixel, vector unsigned char);
18109 vector signed char vec_slo (vector signed char, vector signed char);
18110 vector signed char vec_slo (vector signed char, vector unsigned char);
18111 vector unsigned char vec_slo (vector unsigned char, vector signed char);
18112 vector unsigned char vec_slo (vector unsigned char, vector unsigned char);
18114 vector signed char vec_splat (vector signed char, const int);
18115 vector unsigned char vec_splat (vector unsigned char, const int);
18116 vector bool char vec_splat (vector bool char, const int);
18117 vector signed short vec_splat (vector signed short, const int);
18118 vector unsigned short vec_splat (vector unsigned short, const int);
18119 vector bool short vec_splat (vector bool short, const int);
18120 vector pixel vec_splat (vector pixel, const int);
18121 vector float vec_splat (vector float, const int);
18122 vector signed int vec_splat (vector signed int, const int);
18123 vector unsigned int vec_splat (vector unsigned int, const int);
18124 vector bool int vec_splat (vector bool int, const int);
18126 vector signed short vec_splat_s16 (const int);
18128 vector signed int vec_splat_s32 (const int);
18130 vector signed char vec_splat_s8 (const int);
18132 vector unsigned short vec_splat_u16 (const int);
18134 vector unsigned int vec_splat_u32 (const int);
18136 vector unsigned char vec_splat_u8 (const int);
18138 vector signed char vec_splats (signed char);
18139 vector unsigned char vec_splats (unsigned char);
18140 vector signed short vec_splats (signed short);
18141 vector unsigned short vec_splats (unsigned short);
18142 vector signed int vec_splats (signed int);
18143 vector unsigned int vec_splats (unsigned int);
18144 vector float vec_splats (float);
18146 vector signed char vec_sr (vector signed char, vector unsigned char);
18147 vector unsigned char vec_sr (vector unsigned char, vector unsigned char);
18148 vector signed short vec_sr (vector signed short, vector unsigned short);
18149 vector unsigned short vec_sr (vector unsigned short, vector unsigned short);
18150 vector signed int vec_sr (vector signed int, vector unsigned int);
18151 vector unsigned int vec_sr (vector unsigned int, vector unsigned int);
18153 vector signed char vec_sra (vector signed char, vector unsigned char);
18154 vector unsigned char vec_sra (vector unsigned char, vector unsigned char);
18155 vector signed short vec_sra (vector signed short, vector unsigned short);
18156 vector unsigned short vec_sra (vector unsigned short, vector unsigned short);
18157 vector signed int vec_sra (vector signed int, vector unsigned int);
18158 vector unsigned int vec_sra (vector unsigned int, vector unsigned int);
18160 vector signed int vec_srl (vector signed int, vector unsigned int);
18161 vector signed int vec_srl (vector signed int, vector unsigned short);
18162 vector signed int vec_srl (vector signed int, vector unsigned char);
18163 vector unsigned int vec_srl (vector unsigned int, vector unsigned int);
18164 vector unsigned int vec_srl (vector unsigned int, vector unsigned short);
18165 vector unsigned int vec_srl (vector unsigned int, vector unsigned char);
18166 vector bool int vec_srl (vector bool int, vector unsigned int);
18167 vector bool int vec_srl (vector bool int, vector unsigned short);
18168 vector bool int vec_srl (vector bool int, vector unsigned char);
18169 vector signed short vec_srl (vector signed short, vector unsigned int);
18170 vector signed short vec_srl (vector signed short, vector unsigned short);
18171 vector signed short vec_srl (vector signed short, vector unsigned char);
18172 vector unsigned short vec_srl (vector unsigned short, vector unsigned int);
18173 vector unsigned short vec_srl (vector unsigned short, vector unsigned short);
18174 vector unsigned short vec_srl (vector unsigned short, vector unsigned char);
18175 vector bool short vec_srl (vector bool short, vector unsigned int);
18176 vector bool short vec_srl (vector bool short, vector unsigned short);
18177 vector bool short vec_srl (vector bool short, vector unsigned char);
18178 vector pixel vec_srl (vector pixel, vector unsigned int);
18179 vector pixel vec_srl (vector pixel, vector unsigned short);
18180 vector pixel vec_srl (vector pixel, vector unsigned char);
18181 vector signed char vec_srl (vector signed char, vector unsigned int);
18182 vector signed char vec_srl (vector signed char, vector unsigned short);
18183 vector signed char vec_srl (vector signed char, vector unsigned char);
18184 vector unsigned char vec_srl (vector unsigned char, vector unsigned int);
18185 vector unsigned char vec_srl (vector unsigned char, vector unsigned short);
18186 vector unsigned char vec_srl (vector unsigned char, vector unsigned char);
18187 vector bool char vec_srl (vector bool char, vector unsigned int);
18188 vector bool char vec_srl (vector bool char, vector unsigned short);
18189 vector bool char vec_srl (vector bool char, vector unsigned char);
18191 vector float vec_sro (vector float, vector signed char);
18192 vector float vec_sro (vector float, vector unsigned char);
18193 vector signed int vec_sro (vector signed int, vector signed char);
18194 vector signed int vec_sro (vector signed int, vector unsigned char);
18195 vector unsigned int vec_sro (vector unsigned int, vector signed char);
18196 vector unsigned int vec_sro (vector unsigned int, vector unsigned char);
18197 vector signed short vec_sro (vector signed short, vector signed char);
18198 vector signed short vec_sro (vector signed short, vector unsigned char);
18199 vector unsigned short vec_sro (vector unsigned short, vector signed char);
18200 vector unsigned short vec_sro (vector unsigned short, vector unsigned char);
18201 vector pixel vec_sro (vector pixel, vector signed char);
18202 vector pixel vec_sro (vector pixel, vector unsigned char);
18203 vector signed char vec_sro (vector signed char, vector signed char);
18204 vector signed char vec_sro (vector signed char, vector unsigned char);
18205 vector unsigned char vec_sro (vector unsigned char, vector signed char);
18206 vector unsigned char vec_sro (vector unsigned char, vector unsigned char);
18208 void vec_st (vector float, int, vector float *);
18209 void vec_st (vector float, int, float *);
18210 void vec_st (vector signed int, int, vector signed int *);
18211 void vec_st (vector signed int, int, int *);
18212 void vec_st (vector unsigned int, int, vector unsigned int *);
18213 void vec_st (vector unsigned int, int, unsigned int *);
18214 void vec_st (vector bool int, int, vector bool int *);
18215 void vec_st (vector bool int, int, unsigned int *);
18216 void vec_st (vector bool int, int, int *);
18217 void vec_st (vector signed short, int, vector signed short *);
18218 void vec_st (vector signed short, int, short *);
18219 void vec_st (vector unsigned short, int, vector unsigned short *);
18220 void vec_st (vector unsigned short, int, unsigned short *);
18221 void vec_st (vector bool short, int, vector bool short *);
18222 void vec_st (vector bool short, int, unsigned short *);
18223 void vec_st (vector pixel, int, vector pixel *);
18224 void vec_st (vector bool short, int, short *);
18225 void vec_st (vector signed char, int, vector signed char *);
18226 void vec_st (vector signed char, int, signed char *);
18227 void vec_st (vector unsigned char, int, vector unsigned char *);
18228 void vec_st (vector unsigned char, int, unsigned char *);
18229 void vec_st (vector bool char, int, vector bool char *);
18230 void vec_st (vector bool char, int, unsigned char *);
18231 void vec_st (vector bool char, int, signed char *);
18233 void vec_ste (vector signed char, int, signed char *);
18234 void vec_ste (vector unsigned char, int, unsigned char *);
18235 void vec_ste (vector bool char, int, signed char *);
18236 void vec_ste (vector bool char, int, unsigned char *);
18237 void vec_ste (vector signed short, int, short *);
18238 void vec_ste (vector unsigned short, int, unsigned short *);
18239 void vec_ste (vector bool short, int, short *);
18240 void vec_ste (vector bool short, int, unsigned short *);
18241 void vec_ste (vector pixel, int, short *);
18242 void vec_ste (vector pixel, int, unsigned short *);
18243 void vec_ste (vector float, int, float *);
18244 void vec_ste (vector signed int, int, int *);
18245 void vec_ste (vector unsigned int, int, unsigned int *);
18246 void vec_ste (vector bool int, int, int *);
18247 void vec_ste (vector bool int, int, unsigned int *);
18249 void vec_stl (vector float, int, vector float *);
18250 void vec_stl (vector float, int, float *);
18251 void vec_stl (vector signed int, int, vector signed int *);
18252 void vec_stl (vector signed int, int, int *);
18253 void vec_stl (vector unsigned int, int, vector unsigned int *);
18254 void vec_stl (vector unsigned int, int, unsigned int *);
18255 void vec_stl (vector bool int, int, vector bool int *);
18256 void vec_stl (vector bool int, int, unsigned int *);
18257 void vec_stl (vector bool int, int, int *);
18258 void vec_stl (vector signed short, int, vector signed short *);
18259 void vec_stl (vector signed short, int, short *);
18260 void vec_stl (vector unsigned short, int, vector unsigned short *);
18261 void vec_stl (vector unsigned short, int, unsigned short *);
18262 void vec_stl (vector bool short, int, vector bool short *);
18263 void vec_stl (vector bool short, int, unsigned short *);
18264 void vec_stl (vector bool short, int, short *);
18265 void vec_stl (vector pixel, int, vector pixel *);
18266 void vec_stl (vector signed char, int, vector signed char *);
18267 void vec_stl (vector signed char, int, signed char *);
18268 void vec_stl (vector unsigned char, int, vector unsigned char *);
18269 void vec_stl (vector unsigned char, int, unsigned char *);
18270 void vec_stl (vector bool char, int, vector bool char *);
18271 void vec_stl (vector bool char, int, unsigned char *);
18272 void vec_stl (vector bool char, int, signed char *);
18274 void vec_stvebx (vector signed char, int, signed char *);
18275 void vec_stvebx (vector unsigned char, int, unsigned char *);
18276 void vec_stvebx (vector bool char, int, signed char *);
18277 void vec_stvebx (vector bool char, int, unsigned char *);
18279 void vec_stvehx (vector signed short, int, short *);
18280 void vec_stvehx (vector unsigned short, int, unsigned short *);
18281 void vec_stvehx (vector bool short, int, short *);
18282 void vec_stvehx (vector bool short, int, unsigned short *);
18284 void vec_stvewx (vector float, int, float *);
18285 void vec_stvewx (vector signed int, int, int *);
18286 void vec_stvewx (vector unsigned int, int, unsigned int *);
18287 void vec_stvewx (vector bool int, int, int *);
18288 void vec_stvewx (vector bool int, int, unsigned int *);
18290 vector signed char vec_sub (vector bool char, vector signed char);
18291 vector signed char vec_sub (vector signed char, vector bool char);
18292 vector signed char vec_sub (vector signed char, vector signed char);
18293 vector unsigned char vec_sub (vector bool char, vector unsigned char);
18294 vector unsigned char vec_sub (vector unsigned char, vector bool char);
18295 vector unsigned char vec_sub (vector unsigned char, vector unsigned char);
18296 vector signed short vec_sub (vector bool short, vector signed short);
18297 vector signed short vec_sub (vector signed short, vector bool short);
18298 vector signed short vec_sub (vector signed short, vector signed short);
18299 vector unsigned short vec_sub (vector bool short, vector unsigned short);
18300 vector unsigned short vec_sub (vector unsigned short, vector bool short);
18301 vector unsigned short vec_sub (vector unsigned short, vector unsigned short);
18302 vector signed int vec_sub (vector bool int, vector signed int);
18303 vector signed int vec_sub (vector signed int, vector bool int);
18304 vector signed int vec_sub (vector signed int, vector signed int);
18305 vector unsigned int vec_sub (vector bool int, vector unsigned int);
18306 vector unsigned int vec_sub (vector unsigned int, vector bool int);
18307 vector unsigned int vec_sub (vector unsigned int, vector unsigned int);
18308 vector float vec_sub (vector float, vector float);
18310 vector signed int vec_subc (vector signed int, vector signed int);
18311 vector unsigned int vec_subc (vector unsigned int, vector unsigned int);
18313 vector signed int vec_sube (vector signed int, vector signed int,
18314 vector signed int);
18315 vector unsigned int vec_sube (vector unsigned int, vector unsigned int,
18316 vector unsigned int);
18318 vector signed int vec_subec (vector signed int, vector signed int,
18319 vector signed int);
18320 vector unsigned int vec_subec (vector unsigned int, vector unsigned int,
18321 vector unsigned int);
18323 vector unsigned char vec_subs (vector bool char, vector unsigned char);
18324 vector unsigned char vec_subs (vector unsigned char, vector bool char);
18325 vector unsigned char vec_subs (vector unsigned char, vector unsigned char);
18326 vector signed char vec_subs (vector bool char, vector signed char);
18327 vector signed char vec_subs (vector signed char, vector bool char);
18328 vector signed char vec_subs (vector signed char, vector signed char);
18329 vector unsigned short vec_subs (vector bool short, vector unsigned short);
18330 vector unsigned short vec_subs (vector unsigned short, vector bool short);
18331 vector unsigned short vec_subs (vector unsigned short, vector unsigned short);
18332 vector signed short vec_subs (vector bool short, vector signed short);
18333 vector signed short vec_subs (vector signed short, vector bool short);
18334 vector signed short vec_subs (vector signed short, vector signed short);
18335 vector unsigned int vec_subs (vector bool int, vector unsigned int);
18336 vector unsigned int vec_subs (vector unsigned int, vector bool int);
18337 vector unsigned int vec_subs (vector unsigned int, vector unsigned int);
18338 vector signed int vec_subs (vector bool int, vector signed int);
18339 vector signed int vec_subs (vector signed int, vector bool int);
18340 vector signed int vec_subs (vector signed int, vector signed int);
18342 vector signed int vec_sum2s (vector signed int, vector signed int);
18344 vector unsigned int vec_sum4s (vector unsigned char, vector unsigned int);
18345 vector signed int vec_sum4s (vector signed char, vector signed int);
18346 vector signed int vec_sum4s (vector signed short, vector signed int);
18348 vector signed int vec_sums (vector signed int, vector signed int);
18350 vector float vec_trunc (vector float);
18352 vector signed short vec_unpackh (vector signed char);
18353 vector bool short vec_unpackh (vector bool char);
18354 vector signed int vec_unpackh (vector signed short);
18355 vector bool int vec_unpackh (vector bool short);
18356 vector unsigned int vec_unpackh (vector pixel);
18358 vector signed short vec_unpackl (vector signed char);
18359 vector bool short vec_unpackl (vector bool char);
18360 vector unsigned int vec_unpackl (vector pixel);
18361 vector signed int vec_unpackl (vector signed short);
18362 vector bool int vec_unpackl (vector bool short);
18364 vector float vec_vaddfp (vector float, vector float);
18366 vector signed char vec_vaddsbs (vector bool char, vector signed char);
18367 vector signed char vec_vaddsbs (vector signed char, vector bool char);
18368 vector signed char vec_vaddsbs (vector signed char, vector signed char);
18370 vector signed short vec_vaddshs (vector bool short, vector signed short);
18371 vector signed short vec_vaddshs (vector signed short, vector bool short);
18372 vector signed short vec_vaddshs (vector signed short, vector signed short);
18374 vector signed int vec_vaddsws (vector bool int, vector signed int);
18375 vector signed int vec_vaddsws (vector signed int, vector bool int);
18376 vector signed int vec_vaddsws (vector signed int, vector signed int);
18378 vector signed char vec_vaddubm (vector bool char, vector signed char);
18379 vector signed char vec_vaddubm (vector signed char, vector bool char);
18380 vector signed char vec_vaddubm (vector signed char, vector signed char);
18381 vector unsigned char vec_vaddubm (vector bool char, vector unsigned char);
18382 vector unsigned char vec_vaddubm (vector unsigned char, vector bool char);
18383 vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char);
18385 vector unsigned char vec_vaddubs (vector bool char, vector unsigned char);
18386 vector unsigned char vec_vaddubs (vector unsigned char, vector bool char);
18387 vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char);
18389 vector signed short vec_vadduhm (vector bool short, vector signed short);
18390 vector signed short vec_vadduhm (vector signed short, vector bool short);
18391 vector signed short vec_vadduhm (vector signed short, vector signed short);
18392 vector unsigned short vec_vadduhm (vector bool short, vector unsigned short);
18393 vector unsigned short vec_vadduhm (vector unsigned short, vector bool short);
18394 vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short);
18396 vector unsigned short vec_vadduhs (vector bool short, vector unsigned short);
18397 vector unsigned short vec_vadduhs (vector unsigned short, vector bool short);
18398 vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short);
18400 vector signed int vec_vadduwm (vector bool int, vector signed int);
18401 vector signed int vec_vadduwm (vector signed int, vector bool int);
18402 vector signed int vec_vadduwm (vector signed int, vector signed int);
18403 vector unsigned int vec_vadduwm (vector bool int, vector unsigned int);
18404 vector unsigned int vec_vadduwm (vector unsigned int, vector bool int);
18405 vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int);
18407 vector unsigned int vec_vadduws (vector bool int, vector unsigned int);
18408 vector unsigned int vec_vadduws (vector unsigned int, vector bool int);
18409 vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int);
18411 vector signed char vec_vavgsb (vector signed char, vector signed char);
18413 vector signed short vec_vavgsh (vector signed short, vector signed short);
18415 vector signed int vec_vavgsw (vector signed int, vector signed int);
18417 vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char);
18419 vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short);
18421 vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int);
18423 vector float vec_vcfsx (vector signed int, const int);
18425 vector float vec_vcfux (vector unsigned int, const int);
18427 vector bool int vec_vcmpeqfp (vector float, vector float);
18429 vector bool char vec_vcmpequb (vector signed char, vector signed char);
18430 vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char);
18432 vector bool short vec_vcmpequh (vector signed short, vector signed short);
18433 vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short);
18435 vector bool int vec_vcmpequw (vector signed int, vector signed int);
18436 vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int);
18438 vector bool int vec_vcmpgtfp (vector float, vector float);
18440 vector bool char vec_vcmpgtsb (vector signed char, vector signed char);
18442 vector bool short vec_vcmpgtsh (vector signed short, vector signed short);
18444 vector bool int vec_vcmpgtsw (vector signed int, vector signed int);
18446 vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char);
18448 vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short);
18450 vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int);
18452 vector float vec_vmaxfp (vector float, vector float);
18454 vector signed char vec_vmaxsb (vector bool char, vector signed char);
18455 vector signed char vec_vmaxsb (vector signed char, vector bool char);
18456 vector signed char vec_vmaxsb (vector signed char, vector signed char);
18458 vector signed short vec_vmaxsh (vector bool short, vector signed short);
18459 vector signed short vec_vmaxsh (vector signed short, vector bool short);
18460 vector signed short vec_vmaxsh (vector signed short, vector signed short);
18462 vector signed int vec_vmaxsw (vector bool int, vector signed int);
18463 vector signed int vec_vmaxsw (vector signed int, vector bool int);
18464 vector signed int vec_vmaxsw (vector signed int, vector signed int);
18466 vector unsigned char vec_vmaxub (vector bool char, vector unsigned char);
18467 vector unsigned char vec_vmaxub (vector unsigned char, vector bool char);
18468 vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char);
18470 vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short);
18471 vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short);
18472 vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short);
18474 vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int);
18475 vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int);
18476 vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int);
18478 vector float vec_vminfp (vector float, vector float);
18480 vector signed char vec_vminsb (vector bool char, vector signed char);
18481 vector signed char vec_vminsb (vector signed char, vector bool char);
18482 vector signed char vec_vminsb (vector signed char, vector signed char);
18484 vector signed short vec_vminsh (vector bool short, vector signed short);
18485 vector signed short vec_vminsh (vector signed short, vector bool short);
18486 vector signed short vec_vminsh (vector signed short, vector signed short);
18488 vector signed int vec_vminsw (vector bool int, vector signed int);
18489 vector signed int vec_vminsw (vector signed int, vector bool int);
18490 vector signed int vec_vminsw (vector signed int, vector signed int);
18492 vector unsigned char vec_vminub (vector bool char, vector unsigned char);
18493 vector unsigned char vec_vminub (vector unsigned char, vector bool char);
18494 vector unsigned char vec_vminub (vector unsigned char, vector unsigned char);
18496 vector unsigned short vec_vminuh (vector bool short, vector unsigned short);
18497 vector unsigned short vec_vminuh (vector unsigned short, vector bool short);
18498 vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short);
18500 vector unsigned int vec_vminuw (vector bool int, vector unsigned int);
18501 vector unsigned int vec_vminuw (vector unsigned int, vector bool int);
18502 vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int);
18504 vector bool char vec_vmrghb (vector bool char, vector bool char);
18505 vector signed char vec_vmrghb (vector signed char, vector signed char);
18506 vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char);
18508 vector bool short vec_vmrghh (vector bool short, vector bool short);
18509 vector signed short vec_vmrghh (vector signed short, vector signed short);
18510 vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short);
18511 vector pixel vec_vmrghh (vector pixel, vector pixel);
18513 vector float vec_vmrghw (vector float, vector float);
18514 vector bool int vec_vmrghw (vector bool int, vector bool int);
18515 vector signed int vec_vmrghw (vector signed int, vector signed int);
18516 vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int);
18518 vector bool char vec_vmrglb (vector bool char, vector bool char);
18519 vector signed char vec_vmrglb (vector signed char, vector signed char);
18520 vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char);
18522 vector bool short vec_vmrglh (vector bool short, vector bool short);
18523 vector signed short vec_vmrglh (vector signed short, vector signed short);
18524 vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short);
18525 vector pixel vec_vmrglh (vector pixel, vector pixel);
18527 vector float vec_vmrglw (vector float, vector float);
18528 vector signed int vec_vmrglw (vector signed int, vector signed int);
18529 vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int);
18530 vector bool int vec_vmrglw (vector bool int, vector bool int);
18532 vector signed int vec_vmsummbm (vector signed char, vector unsigned char,
18533 vector signed int);
18535 vector signed int vec_vmsumshm (vector signed short, vector signed short,
18536 vector signed int);
18538 vector signed int vec_vmsumshs (vector signed short, vector signed short,
18539 vector signed int);
18541 vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char,
18542 vector unsigned int);
18544 vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short,
18545 vector unsigned int);
18547 vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short,
18548 vector unsigned int);
18550 vector signed short vec_vmulesb (vector signed char, vector signed char);
18552 vector signed int vec_vmulesh (vector signed short, vector signed short);
18554 vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char);
18556 vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short);
18558 vector signed short vec_vmulosb (vector signed char, vector signed char);
18560 vector signed int vec_vmulosh (vector signed short, vector signed short);
18562 vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char);
18564 vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short);
18566 vector signed char vec_vpkshss (vector signed short, vector signed short);
18568 vector unsigned char vec_vpkshus (vector signed short, vector signed short);
18570 vector signed short vec_vpkswss (vector signed int, vector signed int);
18572 vector unsigned short vec_vpkswus (vector signed int, vector signed int);
18574 vector bool char vec_vpkuhum (vector bool short, vector bool short);
18575 vector signed char vec_vpkuhum (vector signed short, vector signed short);
18576 vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short);
18578 vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short);
18580 vector bool short vec_vpkuwum (vector bool int, vector bool int);
18581 vector signed short vec_vpkuwum (vector signed int, vector signed int);
18582 vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int);
18584 vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int);
18586 vector signed char vec_vrlb (vector signed char, vector unsigned char);
18587 vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char);
18589 vector signed short vec_vrlh (vector signed short, vector unsigned short);
18590 vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short);
18592 vector signed int vec_vrlw (vector signed int, vector unsigned int);
18593 vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int);
18595 vector signed char vec_vslb (vector signed char, vector unsigned char);
18596 vector unsigned char vec_vslb (vector unsigned char, vector unsigned char);
18598 vector signed short vec_vslh (vector signed short, vector unsigned short);
18599 vector unsigned short vec_vslh (vector unsigned short, vector unsigned short);
18601 vector signed int vec_vslw (vector signed int, vector unsigned int);
18602 vector unsigned int vec_vslw (vector unsigned int, vector unsigned int);
18604 vector signed char vec_vspltb (vector signed char, const int);
18605 vector unsigned char vec_vspltb (vector unsigned char, const int);
18606 vector bool char vec_vspltb (vector bool char, const int);
18608 vector bool short vec_vsplth (vector bool short, const int);
18609 vector signed short vec_vsplth (vector signed short, const int);
18610 vector unsigned short vec_vsplth (vector unsigned short, const int);
18611 vector pixel vec_vsplth (vector pixel, const int);
18613 vector float vec_vspltw (vector float, const int);
18614 vector signed int vec_vspltw (vector signed int, const int);
18615 vector unsigned int vec_vspltw (vector unsigned int, const int);
18616 vector bool int vec_vspltw (vector bool int, const int);
18618 vector signed char vec_vsrab (vector signed char, vector unsigned char);
18619 vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char);
18621 vector signed short vec_vsrah (vector signed short, vector unsigned short);
18622 vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short);
18624 vector signed int vec_vsraw (vector signed int, vector unsigned int);
18625 vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int);
18627 vector signed char vec_vsrb (vector signed char, vector unsigned char);
18628 vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char);
18630 vector signed short vec_vsrh (vector signed short, vector unsigned short);
18631 vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short);
18633 vector signed int vec_vsrw (vector signed int, vector unsigned int);
18634 vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int);
18636 vector float vec_vsubfp (vector float, vector float);
18638 vector signed char vec_vsubsbs (vector bool char, vector signed char);
18639 vector signed char vec_vsubsbs (vector signed char, vector bool char);
18640 vector signed char vec_vsubsbs (vector signed char, vector signed char);
18642 vector signed short vec_vsubshs (vector bool short, vector signed short);
18643 vector signed short vec_vsubshs (vector signed short, vector bool short);
18644 vector signed short vec_vsubshs (vector signed short, vector signed short);
18646 vector signed int vec_vsubsws (vector bool int, vector signed int);
18647 vector signed int vec_vsubsws (vector signed int, vector bool int);
18648 vector signed int vec_vsubsws (vector signed int, vector signed int);
18650 vector signed char vec_vsububm (vector bool char, vector signed char);
18651 vector signed char vec_vsububm (vector signed char, vector bool char);
18652 vector signed char vec_vsububm (vector signed char, vector signed char);
18653 vector unsigned char vec_vsububm (vector bool char, vector unsigned char);
18654 vector unsigned char vec_vsububm (vector unsigned char, vector bool char);
18655 vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char);
18657 vector unsigned char vec_vsububs (vector bool char, vector unsigned char);
18658 vector unsigned char vec_vsububs (vector unsigned char, vector bool char);
18659 vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char);
18661 vector signed short vec_vsubuhm (vector bool short, vector signed short);
18662 vector signed short vec_vsubuhm (vector signed short, vector bool short);
18663 vector signed short vec_vsubuhm (vector signed short, vector signed short);
18664 vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short);
18665 vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short);
18666 vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short);
18668 vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short);
18669 vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short);
18670 vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short);
18672 vector signed int vec_vsubuwm (vector bool int, vector signed int);
18673 vector signed int vec_vsubuwm (vector signed int, vector bool int);
18674 vector signed int vec_vsubuwm (vector signed int, vector signed int);
18675 vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int);
18676 vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int);
18677 vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int);
18679 vector unsigned int vec_vsubuws (vector bool int, vector unsigned int);
18680 vector unsigned int vec_vsubuws (vector unsigned int, vector bool int);
18681 vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int);
18683 vector signed int vec_vsum4sbs (vector signed char, vector signed int);
18685 vector signed int vec_vsum4shs (vector signed short, vector signed int);
18687 vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int);
18689 vector unsigned int vec_vupkhpx (vector pixel);
18691 vector bool short vec_vupkhsb (vector bool char);
18692 vector signed short vec_vupkhsb (vector signed char);
18694 vector bool int vec_vupkhsh (vector bool short);
18695 vector signed int vec_vupkhsh (vector signed short);
18697 vector unsigned int vec_vupklpx (vector pixel);
18699 vector bool short vec_vupklsb (vector bool char);
18700 vector signed short vec_vupklsb (vector signed char);
18702 vector bool int vec_vupklsh (vector bool short);
18703 vector signed int vec_vupklsh (vector signed short);
18705 vector float vec_xor (vector float, vector float);
18706 vector float vec_xor (vector float, vector bool int);
18707 vector float vec_xor (vector bool int, vector float);
18708 vector bool int vec_xor (vector bool int, vector bool int);
18709 vector signed int vec_xor (vector bool int, vector signed int);
18710 vector signed int vec_xor (vector signed int, vector bool int);
18711 vector signed int vec_xor (vector signed int, vector signed int);
18712 vector unsigned int vec_xor (vector bool int, vector unsigned int);
18713 vector unsigned int vec_xor (vector unsigned int, vector bool int);
18714 vector unsigned int vec_xor (vector unsigned int, vector unsigned int);
18715 vector bool short vec_xor (vector bool short, vector bool short);
18716 vector signed short vec_xor (vector bool short, vector signed short);
18717 vector signed short vec_xor (vector signed short, vector bool short);
18718 vector signed short vec_xor (vector signed short, vector signed short);
18719 vector unsigned short vec_xor (vector bool short, vector unsigned short);
18720 vector unsigned short vec_xor (vector unsigned short, vector bool short);
18721 vector unsigned short vec_xor (vector unsigned short, vector unsigned short);
18722 vector signed char vec_xor (vector bool char, vector signed char);
18723 vector bool char vec_xor (vector bool char, vector bool char);
18724 vector signed char vec_xor (vector signed char, vector bool char);
18725 vector signed char vec_xor (vector signed char, vector signed char);
18726 vector unsigned char vec_xor (vector bool char, vector unsigned char);
18727 vector unsigned char vec_xor (vector unsigned char, vector bool char);
18728 vector unsigned char vec_xor (vector unsigned char, vector unsigned char);
18731 @node PowerPC AltiVec Built-in Functions Available on ISA 2.06
18732 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06
18734 The AltiVec built-in functions described in this section are
18735 available on the PowerPC family of processors starting with ISA 2.06
18736 or later. These are normally enabled by adding @option{-mvsx} to the
18739 When @option{-mvsx} is used, the following additional vector types are
18743 vector unsigned __int128
18744 vector signed __int128
18745 vector unsigned long long int
18746 vector signed long long int
18750 The long long types are only implemented for 64-bit code generation.
18754 vector bool long long vec_and (vector bool long long int, vector bool long long);
18756 vector double vec_ctf (vector unsigned long, const int);
18757 vector double vec_ctf (vector signed long, const int);
18759 vector signed long vec_cts (vector double, const int);
18761 vector unsigned long vec_ctu (vector double, const int);
18763 void vec_dst (const unsigned long *, int, const int);
18764 void vec_dst (const long *, int, const int);
18766 void vec_dststt (const unsigned long *, int, const int);
18767 void vec_dststt (const long *, int, const int);
18769 void vec_dstt (const unsigned long *, int, const int);
18770 void vec_dstt (const long *, int, const int);
18772 vector unsigned char vec_lvsl (int, const unsigned long *);
18773 vector unsigned char vec_lvsl (int, const long *);
18775 vector unsigned char vec_lvsr (int, const unsigned long *);
18776 vector unsigned char vec_lvsr (int, const long *);
18778 vector double vec_mul (vector double, vector double);
18779 vector long vec_mul (vector long, vector long);
18780 vector unsigned long vec_mul (vector unsigned long, vector unsigned long);
18782 vector unsigned long long vec_mule (vector unsigned int, vector unsigned int);
18783 vector signed long long vec_mule (vector signed int, vector signed int);
18785 vector unsigned long long vec_mulo (vector unsigned int, vector unsigned int);
18786 vector signed long long vec_mulo (vector signed int, vector signed int);
18788 vector double vec_nabs (vector double);
18790 vector bool long long vec_reve (vector bool long long);
18791 vector signed long long vec_reve (vector signed long long);
18792 vector unsigned long long vec_reve (vector unsigned long long);
18793 vector double vec_sld (vector double, vector double, const int);
18795 vector bool long long int vec_sld (vector bool long long int,
18796 vector bool long long int, const int);
18797 vector long long int vec_sld (vector long long int, vector long long int, const int);
18798 vector unsigned long long int vec_sld (vector unsigned long long int,
18799 vector unsigned long long int, const int);
18801 vector long long int vec_sll (vector long long int, vector unsigned char);
18802 vector unsigned long long int vec_sll (vector unsigned long long int,
18803 vector unsigned char);
18805 vector signed long long vec_slo (vector signed long long, vector signed char);
18806 vector signed long long vec_slo (vector signed long long, vector unsigned char);
18807 vector unsigned long long vec_slo (vector unsigned long long, vector signed char);
18808 vector unsigned long long vec_slo (vector unsigned long long, vector unsigned char);
18810 vector signed long vec_splat (vector signed long, const int);
18811 vector unsigned long vec_splat (vector unsigned long, const int);
18813 vector long long int vec_srl (vector long long int, vector unsigned char);
18814 vector unsigned long long int vec_srl (vector unsigned long long int,
18815 vector unsigned char);
18817 vector long long int vec_sro (vector long long int, vector char);
18818 vector long long int vec_sro (vector long long int, vector unsigned char);
18819 vector unsigned long long int vec_sro (vector unsigned long long int, vector char);
18820 vector unsigned long long int vec_sro (vector unsigned long long int,
18821 vector unsigned char);
18823 vector signed __int128 vec_subc (vector signed __int128, vector signed __int128);
18824 vector unsigned __int128 vec_subc (vector unsigned __int128, vector unsigned __int128);
18826 vector signed __int128 vec_sube (vector signed __int128, vector signed __int128,
18827 vector signed __int128);
18828 vector unsigned __int128 vec_sube (vector unsigned __int128, vector unsigned __int128,
18829 vector unsigned __int128);
18831 vector signed __int128 vec_subec (vector signed __int128, vector signed __int128,
18832 vector signed __int128);
18833 vector unsigned __int128 vec_subec (vector unsigned __int128, vector unsigned __int128,
18834 vector unsigned __int128);
18836 vector double vec_unpackh (vector float);
18838 vector double vec_unpackl (vector float);
18840 vector double vec_doublee (vector float);
18841 vector double vec_doublee (vector signed int);
18842 vector double vec_doublee (vector unsigned int);
18844 vector double vec_doubleo (vector float);
18845 vector double vec_doubleo (vector signed int);
18846 vector double vec_doubleo (vector unsigned int);
18848 vector double vec_doubleh (vector float);
18849 vector double vec_doubleh (vector signed int);
18850 vector double vec_doubleh (vector unsigned int);
18852 vector double vec_doublel (vector float);
18853 vector double vec_doublel (vector signed int);
18854 vector double vec_doublel (vector unsigned int);
18856 vector float vec_float (vector signed int);
18857 vector float vec_float (vector unsigned int);
18859 vector float vec_float2 (vector signed long long, vector signed long long);
18860 vector float vec_float2 (vector unsigned long long, vector signed long long);
18862 vector float vec_floate (vector double);
18863 vector float vec_floate (vector signed long long);
18864 vector float vec_floate (vector unsigned long long);
18866 vector float vec_floato (vector double);
18867 vector float vec_floato (vector signed long long);
18868 vector float vec_floato (vector unsigned long long);
18870 vector signed long long vec_signed (vector double);
18871 vector signed int vec_signed (vector float);
18873 vector signed int vec_signede (vector double);
18875 vector signed int vec_signedo (vector double);
18877 vector signed char vec_sldw (vector signed char, vector signed char, const int);
18878 vector unsigned char vec_sldw (vector unsigned char, vector unsigned char, const int);
18879 vector signed short vec_sldw (vector signed short, vector signed short, const int);
18880 vector unsigned short vec_sldw (vector unsigned short,
18881 vector unsigned short, const int);
18882 vector signed int vec_sldw (vector signed int, vector signed int, const int);
18883 vector unsigned int vec_sldw (vector unsigned int, vector unsigned int, const int);
18884 vector signed long long vec_sldw (vector signed long long,
18885 vector signed long long, const int);
18886 vector unsigned long long vec_sldw (vector unsigned long long,
18887 vector unsigned long long, const int);
18889 vector signed long long vec_unsigned (vector double);
18890 vector signed int vec_unsigned (vector float);
18892 vector signed int vec_unsignede (vector double);
18894 vector signed int vec_unsignedo (vector double);
18896 vector double vec_abs (vector double);
18897 vector double vec_add (vector double, vector double);
18898 vector double vec_and (vector double, vector double);
18899 vector double vec_and (vector double, vector bool long);
18900 vector double vec_and (vector bool long, vector double);
18901 vector long vec_and (vector long, vector long);
18902 vector long vec_and (vector long, vector bool long);
18903 vector long vec_and (vector bool long, vector long);
18904 vector unsigned long vec_and (vector unsigned long, vector unsigned long);
18905 vector unsigned long vec_and (vector unsigned long, vector bool long);
18906 vector unsigned long vec_and (vector bool long, vector unsigned long);
18907 vector double vec_andc (vector double, vector double);
18908 vector double vec_andc (vector double, vector bool long);
18909 vector double vec_andc (vector bool long, vector double);
18910 vector long vec_andc (vector long, vector long);
18911 vector long vec_andc (vector long, vector bool long);
18912 vector long vec_andc (vector bool long, vector long);
18913 vector unsigned long vec_andc (vector unsigned long, vector unsigned long);
18914 vector unsigned long vec_andc (vector unsigned long, vector bool long);
18915 vector unsigned long vec_andc (vector bool long, vector unsigned long);
18916 vector double vec_ceil (vector double);
18917 vector bool long vec_cmpeq (vector double, vector double);
18918 vector bool long vec_cmpge (vector double, vector double);
18919 vector bool long vec_cmpgt (vector double, vector double);
18920 vector bool long vec_cmple (vector double, vector double);
18921 vector bool long vec_cmplt (vector double, vector double);
18922 vector double vec_cpsgn (vector double, vector double);
18923 vector float vec_div (vector float, vector float);
18924 vector double vec_div (vector double, vector double);
18925 vector long vec_div (vector long, vector long);
18926 vector unsigned long vec_div (vector unsigned long, vector unsigned long);
18927 vector double vec_floor (vector double);
18928 vector signed long long vec_ld (int, const vector signed long long *);
18929 vector signed long long vec_ld (int, const signed long long *);
18930 vector unsigned long long vec_ld (int, const vector unsigned long long *);
18931 vector unsigned long long vec_ld (int, const unsigned long long *);
18932 vector __int128 vec_ld (int, const vector __int128 *);
18933 vector unsigned __int128 vec_ld (int, const vector unsigned __int128 *);
18934 vector __int128 vec_ld (int, const __int128 *);
18935 vector unsigned __int128 vec_ld (int, const unsigned __int128 *);
18936 vector double vec_ld (int, const vector double *);
18937 vector double vec_ld (int, const double *);
18938 vector double vec_ldl (int, const vector double *);
18939 vector double vec_ldl (int, const double *);
18940 vector unsigned char vec_lvsl (int, const double *);
18941 vector unsigned char vec_lvsr (int, const double *);
18942 vector double vec_madd (vector double, vector double, vector double);
18943 vector double vec_max (vector double, vector double);
18944 vector signed long vec_mergeh (vector signed long, vector signed long);
18945 vector signed long vec_mergeh (vector signed long, vector bool long);
18946 vector signed long vec_mergeh (vector bool long, vector signed long);
18947 vector unsigned long vec_mergeh (vector unsigned long, vector unsigned long);
18948 vector unsigned long vec_mergeh (vector unsigned long, vector bool long);
18949 vector unsigned long vec_mergeh (vector bool long, vector unsigned long);
18950 vector signed long vec_mergel (vector signed long, vector signed long);
18951 vector signed long vec_mergel (vector signed long, vector bool long);
18952 vector signed long vec_mergel (vector bool long, vector signed long);
18953 vector unsigned long vec_mergel (vector unsigned long, vector unsigned long);
18954 vector unsigned long vec_mergel (vector unsigned long, vector bool long);
18955 vector unsigned long vec_mergel (vector bool long, vector unsigned long);
18956 vector double vec_min (vector double, vector double);
18957 vector float vec_msub (vector float, vector float, vector float);
18958 vector double vec_msub (vector double, vector double, vector double);
18959 vector float vec_nearbyint (vector float);
18960 vector double vec_nearbyint (vector double);
18961 vector float vec_nmadd (vector float, vector float, vector float);
18962 vector double vec_nmadd (vector double, vector double, vector double);
18963 vector double vec_nmsub (vector double, vector double, vector double);
18964 vector double vec_nor (vector double, vector double);
18965 vector long vec_nor (vector long, vector long);
18966 vector long vec_nor (vector long, vector bool long);
18967 vector long vec_nor (vector bool long, vector long);
18968 vector unsigned long vec_nor (vector unsigned long, vector unsigned long);
18969 vector unsigned long vec_nor (vector unsigned long, vector bool long);
18970 vector unsigned long vec_nor (vector bool long, vector unsigned long);
18971 vector double vec_or (vector double, vector double);
18972 vector double vec_or (vector double, vector bool long);
18973 vector double vec_or (vector bool long, vector double);
18974 vector long vec_or (vector long, vector long);
18975 vector long vec_or (vector long, vector bool long);
18976 vector long vec_or (vector bool long, vector long);
18977 vector unsigned long vec_or (vector unsigned long, vector unsigned long);
18978 vector unsigned long vec_or (vector unsigned long, vector bool long);
18979 vector unsigned long vec_or (vector bool long, vector unsigned long);
18980 vector double vec_perm (vector double, vector double, vector unsigned char);
18981 vector long vec_perm (vector long, vector long, vector unsigned char);
18982 vector unsigned long vec_perm (vector unsigned long, vector unsigned long,
18983 vector unsigned char);
18984 vector bool char vec_permxor (vector bool char, vector bool char,
18986 vector unsigned char vec_permxor (vector signed char, vector signed char,
18987 vector signed char);
18988 vector unsigned char vec_permxor (vector unsigned char, vector unsigned char,
18989 vector unsigned char);
18990 vector double vec_rint (vector double);
18991 vector double vec_recip (vector double, vector double);
18992 vector double vec_rsqrt (vector double);
18993 vector double vec_rsqrte (vector double);
18994 vector double vec_sel (vector double, vector double, vector bool long);
18995 vector double vec_sel (vector double, vector double, vector unsigned long);
18996 vector long vec_sel (vector long, vector long, vector long);
18997 vector long vec_sel (vector long, vector long, vector unsigned long);
18998 vector long vec_sel (vector long, vector long, vector bool long);
18999 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19001 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19002 vector unsigned long);
19003 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
19005 vector double vec_splats (double);
19006 vector signed long vec_splats (signed long);
19007 vector unsigned long vec_splats (unsigned long);
19008 vector float vec_sqrt (vector float);
19009 vector double vec_sqrt (vector double);
19010 void vec_st (vector signed long long, int, vector signed long long *);
19011 void vec_st (vector signed long long, int, signed long long *);
19012 void vec_st (vector unsigned long long, int, vector unsigned long long *);
19013 void vec_st (vector unsigned long long, int, unsigned long long *);
19014 void vec_st (vector bool long long, int, vector bool long long *);
19015 void vec_st (vector bool long long, int, signed long long *);
19016 void vec_st (vector bool long long, int, unsigned long long *);
19017 void vec_st (vector double, int, vector double *);
19018 void vec_st (vector double, int, double *);
19019 vector double vec_sub (vector double, vector double);
19020 vector double vec_trunc (vector double);
19021 vector double vec_xl (int, vector double *);
19022 vector double vec_xl (int, double *);
19023 vector long long vec_xl (int, vector long long *);
19024 vector long long vec_xl (int, long long *);
19025 vector unsigned long long vec_xl (int, vector unsigned long long *);
19026 vector unsigned long long vec_xl (int, unsigned long long *);
19027 vector float vec_xl (int, vector float *);
19028 vector float vec_xl (int, float *);
19029 vector int vec_xl (int, vector int *);
19030 vector int vec_xl (int, int *);
19031 vector unsigned int vec_xl (int, vector unsigned int *);
19032 vector unsigned int vec_xl (int, unsigned int *);
19033 vector double vec_xor (vector double, vector double);
19034 vector double vec_xor (vector double, vector bool long);
19035 vector double vec_xor (vector bool long, vector double);
19036 vector long vec_xor (vector long, vector long);
19037 vector long vec_xor (vector long, vector bool long);
19038 vector long vec_xor (vector bool long, vector long);
19039 vector unsigned long vec_xor (vector unsigned long, vector unsigned long);
19040 vector unsigned long vec_xor (vector unsigned long, vector bool long);
19041 vector unsigned long vec_xor (vector bool long, vector unsigned long);
19042 void vec_xst (vector double, int, vector double *);
19043 void vec_xst (vector double, int, double *);
19044 void vec_xst (vector long long, int, vector long long *);
19045 void vec_xst (vector long long, int, long long *);
19046 void vec_xst (vector unsigned long long, int, vector unsigned long long *);
19047 void vec_xst (vector unsigned long long, int, unsigned long long *);
19048 void vec_xst (vector float, int, vector float *);
19049 void vec_xst (vector float, int, float *);
19050 void vec_xst (vector int, int, vector int *);
19051 void vec_xst (vector int, int, int *);
19052 void vec_xst (vector unsigned int, int, vector unsigned int *);
19053 void vec_xst (vector unsigned int, int, unsigned int *);
19054 int vec_all_eq (vector double, vector double);
19055 int vec_all_ge (vector double, vector double);
19056 int vec_all_gt (vector double, vector double);
19057 int vec_all_le (vector double, vector double);
19058 int vec_all_lt (vector double, vector double);
19059 int vec_all_nan (vector double);
19060 int vec_all_ne (vector double, vector double);
19061 int vec_all_nge (vector double, vector double);
19062 int vec_all_ngt (vector double, vector double);
19063 int vec_all_nle (vector double, vector double);
19064 int vec_all_nlt (vector double, vector double);
19065 int vec_all_numeric (vector double);
19066 int vec_any_eq (vector double, vector double);
19067 int vec_any_ge (vector double, vector double);
19068 int vec_any_gt (vector double, vector double);
19069 int vec_any_le (vector double, vector double);
19070 int vec_any_lt (vector double, vector double);
19071 int vec_any_nan (vector double);
19072 int vec_any_ne (vector double, vector double);
19073 int vec_any_nge (vector double, vector double);
19074 int vec_any_ngt (vector double, vector double);
19075 int vec_any_nle (vector double, vector double);
19076 int vec_any_nlt (vector double, vector double);
19077 int vec_any_numeric (vector double);
19079 vector double vec_vsx_ld (int, const vector double *);
19080 vector double vec_vsx_ld (int, const double *);
19081 vector float vec_vsx_ld (int, const vector float *);
19082 vector float vec_vsx_ld (int, const float *);
19083 vector bool int vec_vsx_ld (int, const vector bool int *);
19084 vector signed int vec_vsx_ld (int, const vector signed int *);
19085 vector signed int vec_vsx_ld (int, const int *);
19086 vector signed int vec_vsx_ld (int, const long *);
19087 vector unsigned int vec_vsx_ld (int, const vector unsigned int *);
19088 vector unsigned int vec_vsx_ld (int, const unsigned int *);
19089 vector unsigned int vec_vsx_ld (int, const unsigned long *);
19090 vector bool short vec_vsx_ld (int, const vector bool short *);
19091 vector pixel vec_vsx_ld (int, const vector pixel *);
19092 vector signed short vec_vsx_ld (int, const vector signed short *);
19093 vector signed short vec_vsx_ld (int, const short *);
19094 vector unsigned short vec_vsx_ld (int, const vector unsigned short *);
19095 vector unsigned short vec_vsx_ld (int, const unsigned short *);
19096 vector bool char vec_vsx_ld (int, const vector bool char *);
19097 vector signed char vec_vsx_ld (int, const vector signed char *);
19098 vector signed char vec_vsx_ld (int, const signed char *);
19099 vector unsigned char vec_vsx_ld (int, const vector unsigned char *);
19100 vector unsigned char vec_vsx_ld (int, const unsigned char *);
19102 void vec_vsx_st (vector double, int, vector double *);
19103 void vec_vsx_st (vector double, int, double *);
19104 void vec_vsx_st (vector float, int, vector float *);
19105 void vec_vsx_st (vector float, int, float *);
19106 void vec_vsx_st (vector signed int, int, vector signed int *);
19107 void vec_vsx_st (vector signed int, int, int *);
19108 void vec_vsx_st (vector unsigned int, int, vector unsigned int *);
19109 void vec_vsx_st (vector unsigned int, int, unsigned int *);
19110 void vec_vsx_st (vector bool int, int, vector bool int *);
19111 void vec_vsx_st (vector bool int, int, unsigned int *);
19112 void vec_vsx_st (vector bool int, int, int *);
19113 void vec_vsx_st (vector signed short, int, vector signed short *);
19114 void vec_vsx_st (vector signed short, int, short *);
19115 void vec_vsx_st (vector unsigned short, int, vector unsigned short *);
19116 void vec_vsx_st (vector unsigned short, int, unsigned short *);
19117 void vec_vsx_st (vector bool short, int, vector bool short *);
19118 void vec_vsx_st (vector bool short, int, unsigned short *);
19119 void vec_vsx_st (vector pixel, int, vector pixel *);
19120 void vec_vsx_st (vector pixel, int, unsigned short *);
19121 void vec_vsx_st (vector pixel, int, short *);
19122 void vec_vsx_st (vector bool short, int, short *);
19123 void vec_vsx_st (vector signed char, int, vector signed char *);
19124 void vec_vsx_st (vector signed char, int, signed char *);
19125 void vec_vsx_st (vector unsigned char, int, vector unsigned char *);
19126 void vec_vsx_st (vector unsigned char, int, unsigned char *);
19127 void vec_vsx_st (vector bool char, int, vector bool char *);
19128 void vec_vsx_st (vector bool char, int, unsigned char *);
19129 void vec_vsx_st (vector bool char, int, signed char *);
19131 vector double vec_xxpermdi (vector double, vector double, const int);
19132 vector float vec_xxpermdi (vector float, vector float, const int);
19133 vector long long vec_xxpermdi (vector long long, vector long long, const int);
19134 vector unsigned long long vec_xxpermdi (vector unsigned long long,
19135 vector unsigned long long, const int);
19136 vector int vec_xxpermdi (vector int, vector int, const int);
19137 vector unsigned int vec_xxpermdi (vector unsigned int,
19138 vector unsigned int, const int);
19139 vector short vec_xxpermdi (vector short, vector short, const int);
19140 vector unsigned short vec_xxpermdi (vector unsigned short,
19141 vector unsigned short, const int);
19142 vector signed char vec_xxpermdi (vector signed char, vector signed char,
19144 vector unsigned char vec_xxpermdi (vector unsigned char,
19145 vector unsigned char, const int);
19147 vector double vec_xxsldi (vector double, vector double, int);
19148 vector float vec_xxsldi (vector float, vector float, int);
19149 vector long long vec_xxsldi (vector long long, vector long long, int);
19150 vector unsigned long long vec_xxsldi (vector unsigned long long,
19151 vector unsigned long long, int);
19152 vector int vec_xxsldi (vector int, vector int, int);
19153 vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int);
19154 vector short vec_xxsldi (vector short, vector short, int);
19155 vector unsigned short vec_xxsldi (vector unsigned short,
19156 vector unsigned short, int);
19157 vector signed char vec_xxsldi (vector signed char, vector signed char, int);
19158 vector unsigned char vec_xxsldi (vector unsigned char,
19159 vector unsigned char, int);
19162 Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always
19163 generate the AltiVec @samp{LVX} and @samp{STVX} instructions even
19164 if the VSX instruction set is available. The @samp{vec_vsx_ld} and
19165 @samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X},
19166 @samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions.
19168 @node PowerPC AltiVec Built-in Functions Available on ISA 2.07
19169 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07
19171 If the ISA 2.07 additions to the vector/scalar (power8-vector)
19172 instruction set are available, the following additional functions are
19173 available for both 32-bit and 64-bit targets. For 64-bit targets, you
19174 can use @var{vector long} instead of @var{vector long long},
19175 @var{vector bool long} instead of @var{vector bool long long}, and
19176 @var{vector unsigned long} instead of @var{vector unsigned long long}.
19179 vector signed char vec_neg (vector signed char);
19180 vector signed short vec_neg (vector signed short);
19181 vector signed int vec_neg (vector signed int);
19182 vector signed long long vec_neg (vector signed long long);
19183 vector float char vec_neg (vector float);
19184 vector double vec_neg (vector double);
19186 vector signed int vec_signed2 (vector double, vector double);
19188 vector signed int vec_unsigned2 (vector double, vector double);
19190 vector long long vec_abs (vector long long);
19192 vector long long vec_add (vector long long, vector long long);
19193 vector unsigned long long vec_add (vector unsigned long long,
19194 vector unsigned long long);
19196 int vec_all_eq (vector long long, vector long long);
19197 int vec_all_eq (vector unsigned long long, vector unsigned long long);
19198 int vec_all_ge (vector long long, vector long long);
19199 int vec_all_ge (vector unsigned long long, vector unsigned long long);
19200 int vec_all_gt (vector long long, vector long long);
19201 int vec_all_gt (vector unsigned long long, vector unsigned long long);
19202 int vec_all_le (vector long long, vector long long);
19203 int vec_all_le (vector unsigned long long, vector unsigned long long);
19204 int vec_all_lt (vector long long, vector long long);
19205 int vec_all_lt (vector unsigned long long, vector unsigned long long);
19206 int vec_all_ne (vector long long, vector long long);
19207 int vec_all_ne (vector unsigned long long, vector unsigned long long);
19209 int vec_any_eq (vector long long, vector long long);
19210 int vec_any_eq (vector unsigned long long, vector unsigned long long);
19211 int vec_any_ge (vector long long, vector long long);
19212 int vec_any_ge (vector unsigned long long, vector unsigned long long);
19213 int vec_any_gt (vector long long, vector long long);
19214 int vec_any_gt (vector unsigned long long, vector unsigned long long);
19215 int vec_any_le (vector long long, vector long long);
19216 int vec_any_le (vector unsigned long long, vector unsigned long long);
19217 int vec_any_lt (vector long long, vector long long);
19218 int vec_any_lt (vector unsigned long long, vector unsigned long long);
19219 int vec_any_ne (vector long long, vector long long);
19220 int vec_any_ne (vector unsigned long long, vector unsigned long long);
19222 vector bool long long vec_cmpeq (vector bool long long, vector bool long long);
19224 vector long long vec_eqv (vector long long, vector long long);
19225 vector long long vec_eqv (vector bool long long, vector long long);
19226 vector long long vec_eqv (vector long long, vector bool long long);
19227 vector unsigned long long vec_eqv (vector unsigned long long, vector unsigned long long);
19228 vector unsigned long long vec_eqv (vector bool long long, vector unsigned long long);
19229 vector unsigned long long vec_eqv (vector unsigned long long,
19230 vector bool long long);
19231 vector int vec_eqv (vector int, vector int);
19232 vector int vec_eqv (vector bool int, vector int);
19233 vector int vec_eqv (vector int, vector bool int);
19234 vector unsigned int vec_eqv (vector unsigned int, vector unsigned int);
19235 vector unsigned int vec_eqv (vector bool unsigned int, vector unsigned int);
19236 vector unsigned int vec_eqv (vector unsigned int, vector bool unsigned int);
19237 vector short vec_eqv (vector short, vector short);
19238 vector short vec_eqv (vector bool short, vector short);
19239 vector short vec_eqv (vector short, vector bool short);
19240 vector unsigned short vec_eqv (vector unsigned short, vector unsigned short);
19241 vector unsigned short vec_eqv (vector bool unsigned short, vector unsigned short);
19242 vector unsigned short vec_eqv (vector unsigned short, vector bool unsigned short);
19243 vector signed char vec_eqv (vector signed char, vector signed char);
19244 vector signed char vec_eqv (vector bool signed char, vector signed char);
19245 vector signed char vec_eqv (vector signed char, vector bool signed char);
19246 vector unsigned char vec_eqv (vector unsigned char, vector unsigned char);
19247 vector unsigned char vec_eqv (vector bool unsigned char, vector unsigned char);
19248 vector unsigned char vec_eqv (vector unsigned char, vector bool unsigned char);
19250 vector long long vec_max (vector long long, vector long long);
19251 vector unsigned long long vec_max (vector unsigned long long,
19252 vector unsigned long long);
19254 vector signed int vec_mergee (vector signed int, vector signed int);
19255 vector unsigned int vec_mergee (vector unsigned int, vector unsigned int);
19256 vector bool int vec_mergee (vector bool int, vector bool int);
19258 vector signed int vec_mergeo (vector signed int, vector signed int);
19259 vector unsigned int vec_mergeo (vector unsigned int, vector unsigned int);
19260 vector bool int vec_mergeo (vector bool int, vector bool int);
19262 vector long long vec_min (vector long long, vector long long);
19263 vector unsigned long long vec_min (vector unsigned long long,
19264 vector unsigned long long);
19266 vector signed long long vec_nabs (vector signed long long);
19268 vector long long vec_nand (vector long long, vector long long);
19269 vector long long vec_nand (vector bool long long, vector long long);
19270 vector long long vec_nand (vector long long, vector bool long long);
19271 vector unsigned long long vec_nand (vector unsigned long long,
19272 vector unsigned long long);
19273 vector unsigned long long vec_nand (vector bool long long, vector unsigned long long);
19274 vector unsigned long long vec_nand (vector unsigned long long, vector bool long long);
19275 vector int vec_nand (vector int, vector int);
19276 vector int vec_nand (vector bool int, vector int);
19277 vector int vec_nand (vector int, vector bool int);
19278 vector unsigned int vec_nand (vector unsigned int, vector unsigned int);
19279 vector unsigned int vec_nand (vector bool unsigned int, vector unsigned int);
19280 vector unsigned int vec_nand (vector unsigned int, vector bool unsigned int);
19281 vector short vec_nand (vector short, vector short);
19282 vector short vec_nand (vector bool short, vector short);
19283 vector short vec_nand (vector short, vector bool short);
19284 vector unsigned short vec_nand (vector unsigned short, vector unsigned short);
19285 vector unsigned short vec_nand (vector bool unsigned short, vector unsigned short);
19286 vector unsigned short vec_nand (vector unsigned short, vector bool unsigned short);
19287 vector signed char vec_nand (vector signed char, vector signed char);
19288 vector signed char vec_nand (vector bool signed char, vector signed char);
19289 vector signed char vec_nand (vector signed char, vector bool signed char);
19290 vector unsigned char vec_nand (vector unsigned char, vector unsigned char);
19291 vector unsigned char vec_nand (vector bool unsigned char, vector unsigned char);
19292 vector unsigned char vec_nand (vector unsigned char, vector bool unsigned char);
19294 vector long long vec_orc (vector long long, vector long long);
19295 vector long long vec_orc (vector bool long long, vector long long);
19296 vector long long vec_orc (vector long long, vector bool long long);
19297 vector unsigned long long vec_orc (vector unsigned long long,
19298 vector unsigned long long);
19299 vector unsigned long long vec_orc (vector bool long long, vector unsigned long long);
19300 vector unsigned long long vec_orc (vector unsigned long long, vector bool long long);
19301 vector int vec_orc (vector int, vector int);
19302 vector int vec_orc (vector bool int, vector int);
19303 vector int vec_orc (vector int, vector bool int);
19304 vector unsigned int vec_orc (vector unsigned int, vector unsigned int);
19305 vector unsigned int vec_orc (vector bool unsigned int, vector unsigned int);
19306 vector unsigned int vec_orc (vector unsigned int, vector bool unsigned int);
19307 vector short vec_orc (vector short, vector short);
19308 vector short vec_orc (vector bool short, vector short);
19309 vector short vec_orc (vector short, vector bool short);
19310 vector unsigned short vec_orc (vector unsigned short, vector unsigned short);
19311 vector unsigned short vec_orc (vector bool unsigned short, vector unsigned short);
19312 vector unsigned short vec_orc (vector unsigned short, vector bool unsigned short);
19313 vector signed char vec_orc (vector signed char, vector signed char);
19314 vector signed char vec_orc (vector bool signed char, vector signed char);
19315 vector signed char vec_orc (vector signed char, vector bool signed char);
19316 vector unsigned char vec_orc (vector unsigned char, vector unsigned char);
19317 vector unsigned char vec_orc (vector bool unsigned char, vector unsigned char);
19318 vector unsigned char vec_orc (vector unsigned char, vector bool unsigned char);
19320 vector int vec_pack (vector long long, vector long long);
19321 vector unsigned int vec_pack (vector unsigned long long, vector unsigned long long);
19322 vector bool int vec_pack (vector bool long long, vector bool long long);
19323 vector float vec_pack (vector double, vector double);
19325 vector int vec_packs (vector long long, vector long long);
19326 vector unsigned int vec_packs (vector unsigned long long, vector unsigned long long);
19328 vector unsigned char vec_packsu (vector signed short, vector signed short)
19329 vector unsigned char vec_packsu (vector unsigned short, vector unsigned short)
19330 vector unsigned short int vec_packsu (vector signed int, vector signed int);
19331 vector unsigned short int vec_packsu (vector unsigned int, vector unsigned int);
19332 vector unsigned int vec_packsu (vector long long, vector long long);
19333 vector unsigned int vec_packsu (vector unsigned long long, vector unsigned long long);
19334 vector unsigned int vec_packsu (vector signed long long, vector signed long long);
19336 vector unsigned char vec_popcnt (vector signed char);
19337 vector unsigned char vec_popcnt (vector unsigned char);
19338 vector unsigned short vec_popcnt (vector signed short);
19339 vector unsigned short vec_popcnt (vector unsigned short);
19340 vector unsigned int vec_popcnt (vector signed int);
19341 vector unsigned int vec_popcnt (vector unsigned int);
19342 vector unsigned long long vec_popcnt (vector signed long long);
19343 vector unsigned long long vec_popcnt (vector unsigned long long);
19345 vector long long vec_rl (vector long long, vector unsigned long long);
19346 vector long long vec_rl (vector unsigned long long, vector unsigned long long);
19348 vector long long vec_sl (vector long long, vector unsigned long long);
19349 vector long long vec_sl (vector unsigned long long, vector unsigned long long);
19351 vector long long vec_sr (vector long long, vector unsigned long long);
19352 vector unsigned long long char vec_sr (vector unsigned long long,
19353 vector unsigned long long);
19355 vector long long vec_sra (vector long long, vector unsigned long long);
19356 vector unsigned long long vec_sra (vector unsigned long long,
19357 vector unsigned long long);
19359 vector long long vec_sub (vector long long, vector long long);
19360 vector unsigned long long vec_sub (vector unsigned long long,
19361 vector unsigned long long);
19363 vector long long vec_unpackh (vector int);
19364 vector unsigned long long vec_unpackh (vector unsigned int);
19366 vector long long vec_unpackl (vector int);
19367 vector unsigned long long vec_unpackl (vector unsigned int);
19369 vector long long vec_vaddudm (vector long long, vector long long);
19370 vector long long vec_vaddudm (vector bool long long, vector long long);
19371 vector long long vec_vaddudm (vector long long, vector bool long long);
19372 vector unsigned long long vec_vaddudm (vector unsigned long long,
19373 vector unsigned long long);
19374 vector unsigned long long vec_vaddudm (vector bool unsigned long long,
19375 vector unsigned long long);
19376 vector unsigned long long vec_vaddudm (vector unsigned long long,
19377 vector bool unsigned long long);
19379 vector long long vec_vbpermq (vector signed char, vector signed char);
19380 vector long long vec_vbpermq (vector unsigned char, vector unsigned char);
19382 vector unsigned char vec_bperm (vector unsigned char, vector unsigned char);
19383 vector unsigned char vec_bperm (vector unsigned long long, vector unsigned char);
19384 vector unsigned long long vec_bperm (vector unsigned __int128, vector unsigned char);
19386 vector long long vec_cntlz (vector long long);
19387 vector unsigned long long vec_cntlz (vector unsigned long long);
19388 vector int vec_cntlz (vector int);
19389 vector unsigned int vec_cntlz (vector int);
19390 vector short vec_cntlz (vector short);
19391 vector unsigned short vec_cntlz (vector unsigned short);
19392 vector signed char vec_cntlz (vector signed char);
19393 vector unsigned char vec_cntlz (vector unsigned char);
19395 vector long long vec_vclz (vector long long);
19396 vector unsigned long long vec_vclz (vector unsigned long long);
19397 vector int vec_vclz (vector int);
19398 vector unsigned int vec_vclz (vector int);
19399 vector short vec_vclz (vector short);
19400 vector unsigned short vec_vclz (vector unsigned short);
19401 vector signed char vec_vclz (vector signed char);
19402 vector unsigned char vec_vclz (vector unsigned char);
19404 vector signed char vec_vclzb (vector signed char);
19405 vector unsigned char vec_vclzb (vector unsigned char);
19407 vector long long vec_vclzd (vector long long);
19408 vector unsigned long long vec_vclzd (vector unsigned long long);
19410 vector short vec_vclzh (vector short);
19411 vector unsigned short vec_vclzh (vector unsigned short);
19413 vector int vec_vclzw (vector int);
19414 vector unsigned int vec_vclzw (vector int);
19416 vector signed char vec_vgbbd (vector signed char);
19417 vector unsigned char vec_vgbbd (vector unsigned char);
19419 vector long long vec_vmaxsd (vector long long, vector long long);
19421 vector unsigned long long vec_vmaxud (vector unsigned long long,
19422 unsigned vector long long);
19424 vector long long vec_vminsd (vector long long, vector long long);
19426 vector unsigned long long vec_vminud (vector long long, vector long long);
19428 vector int vec_vpksdss (vector long long, vector long long);
19429 vector unsigned int vec_vpksdss (vector long long, vector long long);
19431 vector unsigned int vec_vpkudus (vector unsigned long long,
19432 vector unsigned long long);
19434 vector int vec_vpkudum (vector long long, vector long long);
19435 vector unsigned int vec_vpkudum (vector unsigned long long,
19436 vector unsigned long long);
19437 vector bool int vec_vpkudum (vector bool long long, vector bool long long);
19439 vector long long vec_vpopcnt (vector long long);
19440 vector unsigned long long vec_vpopcnt (vector unsigned long long);
19441 vector int vec_vpopcnt (vector int);
19442 vector unsigned int vec_vpopcnt (vector int);
19443 vector short vec_vpopcnt (vector short);
19444 vector unsigned short vec_vpopcnt (vector unsigned short);
19445 vector signed char vec_vpopcnt (vector signed char);
19446 vector unsigned char vec_vpopcnt (vector unsigned char);
19448 vector signed char vec_vpopcntb (vector signed char);
19449 vector unsigned char vec_vpopcntb (vector unsigned char);
19451 vector long long vec_vpopcntd (vector long long);
19452 vector unsigned long long vec_vpopcntd (vector unsigned long long);
19454 vector short vec_vpopcnth (vector short);
19455 vector unsigned short vec_vpopcnth (vector unsigned short);
19457 vector int vec_vpopcntw (vector int);
19458 vector unsigned int vec_vpopcntw (vector int);
19460 vector long long vec_vrld (vector long long, vector unsigned long long);
19461 vector unsigned long long vec_vrld (vector unsigned long long,
19462 vector unsigned long long);
19464 vector long long vec_vsld (vector long long, vector unsigned long long);
19465 vector long long vec_vsld (vector unsigned long long,
19466 vector unsigned long long);
19468 vector long long vec_vsrad (vector long long, vector unsigned long long);
19469 vector unsigned long long vec_vsrad (vector unsigned long long,
19470 vector unsigned long long);
19472 vector long long vec_vsrd (vector long long, vector unsigned long long);
19473 vector unsigned long long char vec_vsrd (vector unsigned long long,
19474 vector unsigned long long);
19476 vector long long vec_vsubudm (vector long long, vector long long);
19477 vector long long vec_vsubudm (vector bool long long, vector long long);
19478 vector long long vec_vsubudm (vector long long, vector bool long long);
19479 vector unsigned long long vec_vsubudm (vector unsigned long long,
19480 vector unsigned long long);
19481 vector unsigned long long vec_vsubudm (vector bool long long,
19482 vector unsigned long long);
19483 vector unsigned long long vec_vsubudm (vector unsigned long long,
19484 vector bool long long);
19486 vector long long vec_vupkhsw (vector int);
19487 vector unsigned long long vec_vupkhsw (vector unsigned int);
19489 vector long long vec_vupklsw (vector int);
19490 vector unsigned long long vec_vupklsw (vector int);
19493 If the ISA 2.07 additions to the vector/scalar (power8-vector)
19494 instruction set are available, the following additional functions are
19495 available for 64-bit targets. New vector types
19496 (@var{vector __int128} and @var{vector __uint128}) are available
19497 to hold the @var{__int128} and @var{__uint128} types to use these
19500 The normal vector extract, and set operations work on
19501 @var{vector __int128} and @var{vector __uint128} types,
19502 but the index value must be 0.
19505 vector __int128 vec_vaddcuq (vector __int128, vector __int128);
19506 vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128);
19508 vector __int128 vec_vadduqm (vector __int128, vector __int128);
19509 vector __uint128 vec_vadduqm (vector __uint128, vector __uint128);
19511 vector __int128 vec_vaddecuq (vector __int128, vector __int128,
19513 vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128,
19516 vector __int128 vec_vaddeuqm (vector __int128, vector __int128,
19518 vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128,
19521 vector __int128 vec_vsubecuq (vector __int128, vector __int128,
19523 vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128,
19526 vector __int128 vec_vsubeuqm (vector __int128, vector __int128,
19528 vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128,
19531 vector __int128 vec_vsubcuq (vector __int128, vector __int128);
19532 vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128);
19534 __int128 vec_vsubuqm (__int128, __int128);
19535 __uint128 vec_vsubuqm (__uint128, __uint128);
19537 vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int);
19538 int __builtin_bcdadd_lt (vector __int128, vector __int128, const int);
19539 int __builtin_bcdadd_eq (vector __int128, vector __int128, const int);
19540 int __builtin_bcdadd_gt (vector __int128, vector __int128, const int);
19541 int __builtin_bcdadd_ov (vector __int128, vector __int128, const int);
19542 vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int);
19543 int __builtin_bcdsub_lt (vector __int128, vector __int128, const int);
19544 int __builtin_bcdsub_eq (vector __int128, vector __int128, const int);
19545 int __builtin_bcdsub_gt (vector __int128, vector __int128, const int);
19546 int __builtin_bcdsub_ov (vector __int128, vector __int128, const int);
19549 @node PowerPC AltiVec Built-in Functions Available on ISA 3.0
19550 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0
19552 The following additional built-in functions are also available for the
19553 PowerPC family of processors, starting with ISA 3.0
19554 (@option{-mcpu=power9}) or later:
19556 unsigned int scalar_extract_exp (double source);
19557 unsigned long long int scalar_extract_exp (__ieee128 source);
19559 unsigned long long int scalar_extract_sig (double source);
19560 unsigned __int128 scalar_extract_sig (__ieee128 source);
19562 double scalar_insert_exp (unsigned long long int significand,
19563 unsigned long long int exponent);
19564 double scalar_insert_exp (double significand, unsigned long long int exponent);
19566 ieee_128 scalar_insert_exp (unsigned __int128 significand,
19567 unsigned long long int exponent);
19568 ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent);
19570 int scalar_cmp_exp_gt (double arg1, double arg2);
19571 int scalar_cmp_exp_lt (double arg1, double arg2);
19572 int scalar_cmp_exp_eq (double arg1, double arg2);
19573 int scalar_cmp_exp_unordered (double arg1, double arg2);
19575 bool scalar_test_data_class (float source, const int condition);
19576 bool scalar_test_data_class (double source, const int condition);
19577 bool scalar_test_data_class (__ieee128 source, const int condition);
19579 bool scalar_test_neg (float source);
19580 bool scalar_test_neg (double source);
19581 bool scalar_test_neg (__ieee128 source);
19584 The @code{scalar_extract_exp} and @code{scalar_extract_sig}
19585 functions require a 64-bit environment supporting ISA 3.0 or later.
19586 The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in
19587 functions return the significand and the biased exponent value
19588 respectively of their @code{source} arguments.
19589 When supplied with a 64-bit @code{source} argument, the
19590 result returned by @code{scalar_extract_sig} has
19591 the @code{0x0010000000000000} bit set if the
19592 function's @code{source} argument is in normalized form.
19593 Otherwise, this bit is set to 0.
19594 When supplied with a 128-bit @code{source} argument, the
19595 @code{0x00010000000000000000000000000000} bit of the result is
19597 Note that the sign of the significand is not represented in the result
19598 returned from the @code{scalar_extract_sig} function. Use the
19599 @code{scalar_test_neg} function to test the sign of its @code{double}
19602 The @code{scalar_insert_exp}
19603 functions require a 64-bit environment supporting ISA 3.0 or later.
19604 When supplied with a 64-bit first argument, the
19605 @code{scalar_insert_exp} built-in function returns a double-precision
19606 floating point value that is constructed by assembling the values of its
19607 @code{significand} and @code{exponent} arguments. The sign of the
19608 result is copied from the most significant bit of the
19609 @code{significand} argument. The significand and exponent components
19610 of the result are composed of the least significant 11 bits of the
19611 @code{exponent} argument and the least significant 52 bits of the
19612 @code{significand} argument respectively.
19614 When supplied with a 128-bit first argument, the
19615 @code{scalar_insert_exp} built-in function returns a quad-precision
19616 ieee floating point value. The sign bit of the result is copied from
19617 the most significant bit of the @code{significand} argument.
19618 The significand and exponent components of the result are composed of
19619 the least significant 15 bits of the @code{exponent} argument and the
19620 least significant 112 bits of the @code{significand} argument respectively.
19622 The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt},
19623 @code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in
19624 functions return a non-zero value if @code{arg1} is greater than, less
19625 than, equal to, or not comparable to @code{arg2} respectively. The
19626 arguments are not comparable if one or the other equals NaN (not a
19629 The @code{scalar_test_data_class} built-in function returns 1
19630 if any of the condition tests enabled by the value of the
19631 @code{condition} variable are true, and 0 otherwise. The
19632 @code{condition} argument must be a compile-time constant integer with
19633 value not exceeding 127. The
19634 @code{condition} argument is encoded as a bitmask with each bit
19635 enabling the testing of a different condition, as characterized by the
19639 0x20 Test for +Infinity
19640 0x10 Test for -Infinity
19641 0x08 Test for +Zero
19642 0x04 Test for -Zero
19643 0x02 Test for +Denormal
19644 0x01 Test for -Denormal
19647 The @code{scalar_test_neg} built-in function returns 1 if its
19648 @code{source} argument holds a negative value, 0 otherwise.
19650 The following built-in functions are also available for the PowerPC family
19651 of processors, starting with ISA 3.0 or later
19652 (@option{-mcpu=power9}). These string functions are described
19653 separately in order to group the descriptions closer to the function
19656 int vec_all_nez (vector signed char, vector signed char);
19657 int vec_all_nez (vector unsigned char, vector unsigned char);
19658 int vec_all_nez (vector signed short, vector signed short);
19659 int vec_all_nez (vector unsigned short, vector unsigned short);
19660 int vec_all_nez (vector signed int, vector signed int);
19661 int vec_all_nez (vector unsigned int, vector unsigned int);
19663 int vec_any_eqz (vector signed char, vector signed char);
19664 int vec_any_eqz (vector unsigned char, vector unsigned char);
19665 int vec_any_eqz (vector signed short, vector signed short);
19666 int vec_any_eqz (vector unsigned short, vector unsigned short);
19667 int vec_any_eqz (vector signed int, vector signed int);
19668 int vec_any_eqz (vector unsigned int, vector unsigned int);
19670 vector bool char vec_cmpnez (vector signed char arg1, vector signed char arg2);
19671 vector bool char vec_cmpnez (vector unsigned char arg1, vector unsigned char arg2);
19672 vector bool short vec_cmpnez (vector signed short arg1, vector signed short arg2);
19673 vector bool short vec_cmpnez (vector unsigned short arg1, vector unsigned short arg2);
19674 vector bool int vec_cmpnez (vector signed int arg1, vector signed int arg2);
19675 vector bool int vec_cmpnez (vector unsigned int, vector unsigned int);
19677 vector signed char vec_cnttz (vector signed char);
19678 vector unsigned char vec_cnttz (vector unsigned char);
19679 vector signed short vec_cnttz (vector signed short);
19680 vector unsigned short vec_cnttz (vector unsigned short);
19681 vector signed int vec_cnttz (vector signed int);
19682 vector unsigned int vec_cnttz (vector unsigned int);
19683 vector signed long long vec_cnttz (vector signed long long);
19684 vector unsigned long long vec_cnttz (vector unsigned long long);
19686 signed int vec_cntlz_lsbb (vector signed char);
19687 signed int vec_cntlz_lsbb (vector unsigned char);
19689 signed int vec_cnttz_lsbb (vector signed char);
19690 signed int vec_cnttz_lsbb (vector unsigned char);
19692 unsigned int vec_first_match_index (vector signed char, vector signed char);
19693 unsigned int vec_first_match_index (vector unsigned char, vector unsigned char);
19694 unsigned int vec_first_match_index (vector signed int, vector signed int);
19695 unsigned int vec_first_match_index (vector unsigned int, vector unsigned int);
19696 unsigned int vec_first_match_index (vector signed short, vector signed short);
19697 unsigned int vec_first_match_index (vector unsigned short, vector unsigned short);
19698 unsigned int vec_first_match_or_eos_index (vector signed char, vector signed char);
19699 unsigned int vec_first_match_or_eos_index (vector unsigned char, vector unsigned char);
19700 unsigned int vec_first_match_or_eos_index (vector signed int, vector signed int);
19701 unsigned int vec_first_match_or_eos_index (vector unsigned int, vector unsigned int);
19702 unsigned int vec_first_match_or_eos_index (vector signed short, vector signed short);
19703 unsigned int vec_first_match_or_eos_index (vector unsigned short,
19704 vector unsigned short);
19705 unsigned int vec_first_mismatch_index (vector signed char, vector signed char);
19706 unsigned int vec_first_mismatch_index (vector unsigned char, vector unsigned char);
19707 unsigned int vec_first_mismatch_index (vector signed int, vector signed int);
19708 unsigned int vec_first_mismatch_index (vector unsigned int, vector unsigned int);
19709 unsigned int vec_first_mismatch_index (vector signed short, vector signed short);
19710 unsigned int vec_first_mismatch_index (vector unsigned short, vector unsigned short);
19711 unsigned int vec_first_mismatch_or_eos_index (vector signed char, vector signed char);
19712 unsigned int vec_first_mismatch_or_eos_index (vector unsigned char,
19713 vector unsigned char);
19714 unsigned int vec_first_mismatch_or_eos_index (vector signed int, vector signed int);
19715 unsigned int vec_first_mismatch_or_eos_index (vector unsigned int, vector unsigned int);
19716 unsigned int vec_first_mismatch_or_eos_index (vector signed short, vector signed short);
19717 unsigned int vec_first_mismatch_or_eos_index (vector unsigned short,
19718 vector unsigned short);
19720 vector unsigned short vec_pack_to_short_fp32 (vector float, vector float);
19722 vector signed char vec_xl_be (signed long long, signed char *);
19723 vector unsigned char vec_xl_be (signed long long, unsigned char *);
19724 vector signed int vec_xl_be (signed long long, signed int *);
19725 vector unsigned int vec_xl_be (signed long long, unsigned int *);
19726 vector signed __int128 vec_xl_be (signed long long, signed __int128 *);
19727 vector unsigned __int128 vec_xl_be (signed long long, unsigned __int128 *);
19728 vector signed long long vec_xl_be (signed long long, signed long long *);
19729 vector unsigned long long vec_xl_be (signed long long, unsigned long long *);
19730 vector signed short vec_xl_be (signed long long, signed short *);
19731 vector unsigned short vec_xl_be (signed long long, unsigned short *);
19732 vector double vec_xl_be (signed long long, double *);
19733 vector float vec_xl_be (signed long long, float *);
19735 vector signed char vec_xl_len (signed char *addr, size_t len);
19736 vector unsigned char vec_xl_len (unsigned char *addr, size_t len);
19737 vector signed int vec_xl_len (signed int *addr, size_t len);
19738 vector unsigned int vec_xl_len (unsigned int *addr, size_t len);
19739 vector signed __int128 vec_xl_len (signed __int128 *addr, size_t len);
19740 vector unsigned __int128 vec_xl_len (unsigned __int128 *addr, size_t len);
19741 vector signed long long vec_xl_len (signed long long *addr, size_t len);
19742 vector unsigned long long vec_xl_len (unsigned long long *addr, size_t len);
19743 vector signed short vec_xl_len (signed short *addr, size_t len);
19744 vector unsigned short vec_xl_len (unsigned short *addr, size_t len);
19745 vector double vec_xl_len (double *addr, size_t len);
19746 vector float vec_xl_len (float *addr, size_t len);
19748 vector unsigned char vec_xl_len_r (unsigned char *addr, size_t len);
19750 void vec_xst_len (vector signed char data, signed char *addr, size_t len);
19751 void vec_xst_len (vector unsigned char data, unsigned char *addr, size_t len);
19752 void vec_xst_len (vector signed int data, signed int *addr, size_t len);
19753 void vec_xst_len (vector unsigned int data, unsigned int *addr, size_t len);
19754 void vec_xst_len (vector unsigned __int128 data, unsigned __int128 *addr, size_t len);
19755 void vec_xst_len (vector signed long long data, signed long long *addr, size_t len);
19756 void vec_xst_len (vector unsigned long long data, unsigned long long *addr, size_t len);
19757 void vec_xst_len (vector signed short data, signed short *addr, size_t len);
19758 void vec_xst_len (vector unsigned short data, unsigned short *addr, size_t len);
19759 void vec_xst_len (vector signed __int128 data, signed __int128 *addr, size_t len);
19760 void vec_xst_len (vector double data, double *addr, size_t len);
19761 void vec_xst_len (vector float data, float *addr, size_t len);
19763 void vec_xst_len_r (vector unsigned char data, unsigned char *addr, size_t len);
19765 signed char vec_xlx (unsigned int index, vector signed char data);
19766 unsigned char vec_xlx (unsigned int index, vector unsigned char data);
19767 signed short vec_xlx (unsigned int index, vector signed short data);
19768 unsigned short vec_xlx (unsigned int index, vector unsigned short data);
19769 signed int vec_xlx (unsigned int index, vector signed int data);
19770 unsigned int vec_xlx (unsigned int index, vector unsigned int data);
19771 float vec_xlx (unsigned int index, vector float data);
19773 signed char vec_xrx (unsigned int index, vector signed char data);
19774 unsigned char vec_xrx (unsigned int index, vector unsigned char data);
19775 signed short vec_xrx (unsigned int index, vector signed short data);
19776 unsigned short vec_xrx (unsigned int index, vector unsigned short data);
19777 signed int vec_xrx (unsigned int index, vector signed int data);
19778 unsigned int vec_xrx (unsigned int index, vector unsigned int data);
19779 float vec_xrx (unsigned int index, vector float data);
19782 The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez}
19783 perform pairwise comparisons between the elements at the same
19784 positions within their two vector arguments.
19785 The @code{vec_all_nez} function returns a
19786 non-zero value if and only if all pairwise comparisons are not
19787 equal and no element of either vector argument contains a zero.
19788 The @code{vec_any_eqz} function returns a
19789 non-zero value if and only if at least one pairwise comparison is equal
19790 or if at least one element of either vector argument contains a zero.
19791 The @code{vec_cmpnez} function returns a vector of the same type as
19792 its two arguments, within which each element consists of all ones to
19793 denote that either the corresponding elements of the incoming arguments are
19794 not equal or that at least one of the corresponding elements contains
19795 zero. Otherwise, the element of the returned vector contains all zeros.
19797 The @code{vec_cntlz_lsbb} function returns the count of the number of
19798 consecutive leading byte elements (starting from position 0 within the
19799 supplied vector argument) for which the least-significant bit
19800 equals zero. The @code{vec_cnttz_lsbb} function returns the count of
19801 the number of consecutive trailing byte elements (starting from
19802 position 15 and counting backwards within the supplied vector
19803 argument) for which the least-significant bit equals zero.
19805 The @code{vec_xl_len} and @code{vec_xst_len} functions require a
19806 64-bit environment supporting ISA 3.0 or later. The @code{vec_xl_len}
19807 function loads a variable length vector from memory. The
19808 @code{vec_xst_len} function stores a variable length vector to memory.
19809 With both the @code{vec_xl_len} and @code{vec_xst_len} functions, the
19810 @code{addr} argument represents the memory address to or from which
19811 data will be transferred, and the
19812 @code{len} argument represents the number of bytes to be
19813 transferred, as computed by the C expression @code{min((len & 0xff), 16)}.
19814 If this expression's value is not a multiple of the vector element's
19815 size, the behavior of this function is undefined.
19816 In the case that the underlying computer is configured to run in
19817 big-endian mode, the data transfer moves bytes 0 to @code{(len - 1)} of
19818 the corresponding vector. In little-endian mode, the data transfer
19819 moves bytes @code{(16 - len)} to @code{15} of the corresponding
19820 vector. For the load function, any bytes of the result vector that
19821 are not loaded from memory are set to zero.
19822 The value of the @code{addr} argument need not be aligned on a
19823 multiple of the vector's element size.
19825 The @code{vec_xlx} and @code{vec_xrx} functions extract the single
19826 element selected by the @code{index} argument from the vector
19827 represented by the @code{data} argument. The @code{index} argument
19828 always specifies a byte offset, regardless of the size of the vector
19829 element. With @code{vec_xlx}, @code{index} is the offset of the first
19830 byte of the element to be extracted. With @code{vec_xrx}, @code{index}
19831 represents the last byte of the element to be extracted, measured
19832 from the right end of the vector. In other words, the last byte of
19833 the element to be extracted is found at position @code{(15 - index)}.
19834 There is no requirement that @code{index} be a multiple of the vector
19835 element size. However, if the size of the vector element added to
19836 @code{index} is greater than 15, the content of the returned value is
19839 If the ISA 3.0 instruction set additions (@option{-mcpu=power9})
19843 vector unsigned long long vec_bperm (vector unsigned long long, vector unsigned char);
19845 vector bool char vec_cmpne (vector bool char, vector bool char);
19846 vector bool char vec_cmpne (vector signed char, vector signed char);
19847 vector bool char vec_cmpne (vector unsigned char, vector unsigned char);
19848 vector bool int vec_cmpne (vector bool int, vector bool int);
19849 vector bool int vec_cmpne (vector signed int, vector signed int);
19850 vector bool int vec_cmpne (vector unsigned int, vector unsigned int);
19851 vector bool long long vec_cmpne (vector bool long long, vector bool long long);
19852 vector bool long long vec_cmpne (vector signed long long, vector signed long long);
19853 vector bool long long vec_cmpne (vector unsigned long long, vector unsigned long long);
19854 vector bool short vec_cmpne (vector bool short, vector bool short);
19855 vector bool short vec_cmpne (vector signed short, vector signed short);
19856 vector bool short vec_cmpne (vector unsigned short, vector unsigned short);
19857 vector bool long long vec_cmpne (vector double, vector double);
19858 vector bool int vec_cmpne (vector float, vector float);
19860 vector float vec_extract_fp32_from_shorth (vector unsigned short);
19861 vector float vec_extract_fp32_from_shortl (vector unsigned short);
19863 vector long long vec_vctz (vector long long);
19864 vector unsigned long long vec_vctz (vector unsigned long long);
19865 vector int vec_vctz (vector int);
19866 vector unsigned int vec_vctz (vector int);
19867 vector short vec_vctz (vector short);
19868 vector unsigned short vec_vctz (vector unsigned short);
19869 vector signed char vec_vctz (vector signed char);
19870 vector unsigned char vec_vctz (vector unsigned char);
19872 vector signed char vec_vctzb (vector signed char);
19873 vector unsigned char vec_vctzb (vector unsigned char);
19875 vector long long vec_vctzd (vector long long);
19876 vector unsigned long long vec_vctzd (vector unsigned long long);
19878 vector short vec_vctzh (vector short);
19879 vector unsigned short vec_vctzh (vector unsigned short);
19881 vector int vec_vctzw (vector int);
19882 vector unsigned int vec_vctzw (vector int);
19884 vector unsigned long long vec_extract4b (vector unsigned char, const int);
19886 vector unsigned char vec_insert4b (vector signed int, vector unsigned char,
19888 vector unsigned char vec_insert4b (vector unsigned int, vector unsigned char,
19891 vector unsigned int vec_parity_lsbb (vector signed int);
19892 vector unsigned int vec_parity_lsbb (vector unsigned int);
19893 vector unsigned __int128 vec_parity_lsbb (vector signed __int128);
19894 vector unsigned __int128 vec_parity_lsbb (vector unsigned __int128);
19895 vector unsigned long long vec_parity_lsbb (vector signed long long);
19896 vector unsigned long long vec_parity_lsbb (vector unsigned long long);
19898 vector int vec_vprtyb (vector int);
19899 vector unsigned int vec_vprtyb (vector unsigned int);
19900 vector long long vec_vprtyb (vector long long);
19901 vector unsigned long long vec_vprtyb (vector unsigned long long);
19903 vector int vec_vprtybw (vector int);
19904 vector unsigned int vec_vprtybw (vector unsigned int);
19906 vector long long vec_vprtybd (vector long long);
19907 vector unsigned long long vec_vprtybd (vector unsigned long long);
19910 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
19914 vector long vec_vprtyb (vector long);
19915 vector unsigned long vec_vprtyb (vector unsigned long);
19916 vector __int128 vec_vprtyb (vector __int128);
19917 vector __uint128 vec_vprtyb (vector __uint128);
19919 vector long vec_vprtybd (vector long);
19920 vector unsigned long vec_vprtybd (vector unsigned long);
19922 vector __int128 vec_vprtybq (vector __int128);
19923 vector __uint128 vec_vprtybd (vector __uint128);
19926 The following built-in vector functions are available for the PowerPC family
19927 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
19929 __vector unsigned char
19930 vec_slv (__vector unsigned char src, __vector unsigned char shift_distance);
19931 __vector unsigned char
19932 vec_srv (__vector unsigned char src, __vector unsigned char shift_distance);
19935 The @code{vec_slv} and @code{vec_srv} functions operate on
19936 all of the bytes of their @code{src} and @code{shift_distance}
19937 arguments in parallel. The behavior of the @code{vec_slv} is as if
19938 there existed a temporary array of 17 unsigned characters
19939 @code{slv_array} within which elements 0 through 15 are the same as
19940 the entries in the @code{src} array and element 16 equals 0. The
19941 result returned from the @code{vec_slv} function is a
19942 @code{__vector} of 16 unsigned characters within which element
19943 @code{i} is computed using the C expression
19944 @code{0xff & (*((unsigned short *)(slv_array + i)) << (0x07 &
19945 shift_distance[i]))},
19946 with this resulting value coerced to the @code{unsigned char} type.
19947 The behavior of the @code{vec_srv} is as if
19948 there existed a temporary array of 17 unsigned characters
19949 @code{srv_array} within which element 0 equals zero and
19950 elements 1 through 16 equal the elements 0 through 15 of
19951 the @code{src} array. The
19952 result returned from the @code{vec_srv} function is a
19953 @code{__vector} of 16 unsigned characters within which element
19954 @code{i} is computed using the C expression
19955 @code{0xff & (*((unsigned short *)(srv_array + i)) >>
19956 (0x07 & shift_distance[i]))},
19957 with this resulting value coerced to the @code{unsigned char} type.
19959 The following built-in functions are available for the PowerPC family
19960 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
19962 __vector unsigned char
19963 vec_absd (__vector unsigned char arg1, __vector unsigned char arg2);
19964 __vector unsigned short
19965 vec_absd (__vector unsigned short arg1, __vector unsigned short arg2);
19966 __vector unsigned int
19967 vec_absd (__vector unsigned int arg1, __vector unsigned int arg2);
19969 __vector unsigned char
19970 vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2);
19971 __vector unsigned short
19972 vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2);
19973 __vector unsigned int
19974 vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2);
19977 The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and
19978 @code{vec_absdw} built-in functions each computes the absolute
19979 differences of the pairs of vector elements supplied in its two vector
19980 arguments, placing the absolute differences into the corresponding
19981 elements of the vector result.
19983 The following built-in functions are available for the PowerPC family
19984 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
19986 __vector unsigned int vec_extract_exp (__vector float source);
19987 __vector unsigned long long int vec_extract_exp (__vector double source);
19989 __vector unsigned int vec_extract_sig (__vector float source);
19990 __vector unsigned long long int vec_extract_sig (__vector double source);
19992 __vector float vec_insert_exp (__vector unsigned int significands,
19993 __vector unsigned int exponents);
19994 __vector float vec_insert_exp (__vector unsigned float significands,
19995 __vector unsigned int exponents);
19996 __vector double vec_insert_exp (__vector unsigned long long int significands,
19997 __vector unsigned long long int exponents);
19998 __vector double vec_insert_exp (__vector unsigned double significands,
19999 __vector unsigned long long int exponents);
20001 __vector bool int vec_test_data_class (__vector float source, const int condition);
20002 __vector bool long long int vec_test_data_class (__vector double source,
20003 const int condition);
20006 The @code{vec_extract_sig} and @code{vec_extract_exp} built-in
20007 functions return vectors representing the significands and biased
20008 exponent values of their @code{source} arguments respectively.
20009 Within the result vector returned by @code{vec_extract_sig}, the
20010 @code{0x800000} bit of each vector element returned when the
20011 function's @code{source} argument is of type @code{float} is set to 1
20012 if the corresponding floating point value is in normalized form.
20013 Otherwise, this bit is set to 0. When the @code{source} argument is
20014 of type @code{double}, the @code{0x10000000000000} bit within each of
20015 the result vector's elements is set according to the same rules.
20016 Note that the sign of the significand is not represented in the result
20017 returned from the @code{vec_extract_sig} function. To extract the
20019 @code{vec_cpsgn} function, which returns a new vector within which all
20020 of the sign bits of its second argument vector are overwritten with the
20021 sign bits copied from the coresponding elements of its first argument
20022 vector, and all other (non-sign) bits of the second argument vector
20023 are copied unchanged into the result vector.
20025 The @code{vec_insert_exp} built-in functions return a vector of
20026 single- or double-precision floating
20027 point values constructed by assembling the values of their
20028 @code{significands} and @code{exponents} arguments into the
20029 corresponding elements of the returned vector.
20031 element of the result is copied from the most significant bit of the
20032 corresponding entry within the @code{significands} argument.
20033 Note that the relevant
20034 bits of the @code{significands} argument are the same, for both integer
20035 and floating point types.
20037 significand and exponent components of each element of the result are
20038 composed of the least significant bits of the corresponding
20039 @code{significands} element and the least significant bits of the
20040 corresponding @code{exponents} element.
20042 The @code{vec_test_data_class} built-in function returns a vector
20043 representing the results of testing the @code{source} vector for the
20044 condition selected by the @code{condition} argument. The
20045 @code{condition} argument must be a compile-time constant integer with
20046 value not exceeding 127. The
20047 @code{condition} argument is encoded as a bitmask with each bit
20048 enabling the testing of a different condition, as characterized by the
20052 0x20 Test for +Infinity
20053 0x10 Test for -Infinity
20054 0x08 Test for +Zero
20055 0x04 Test for -Zero
20056 0x02 Test for +Denormal
20057 0x01 Test for -Denormal
20060 If any of the enabled test conditions is true, the corresponding entry
20061 in the result vector is -1. Otherwise (all of the enabled test
20062 conditions are false), the corresponding entry of the result vector is 0.
20064 The following built-in functions are available for the PowerPC family
20065 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
20067 vector unsigned int vec_rlmi (vector unsigned int, vector unsigned int,
20068 vector unsigned int);
20069 vector unsigned long long vec_rlmi (vector unsigned long long,
20070 vector unsigned long long,
20071 vector unsigned long long);
20072 vector unsigned int vec_rlnm (vector unsigned int, vector unsigned int,
20073 vector unsigned int);
20074 vector unsigned long long vec_rlnm (vector unsigned long long,
20075 vector unsigned long long,
20076 vector unsigned long long);
20077 vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int);
20078 vector unsigned long long vec_vrlnm (vector unsigned long long,
20079 vector unsigned long long);
20082 The result of @code{vec_rlmi} is obtained by rotating each element of
20083 the first argument vector left and inserting it under mask into the
20084 second argument vector. The third argument vector contains the mask
20085 beginning in bits 11:15, the mask end in bits 19:23, and the shift
20086 count in bits 27:31, of each element.
20088 The result of @code{vec_rlnm} is obtained by rotating each element of
20089 the first argument vector left and ANDing it with a mask specified by
20090 the second and third argument vectors. The second argument vector
20091 contains the shift count for each element in the low-order byte. The
20092 third argument vector contains the mask end for each element in the
20093 low-order byte, with the mask begin in the next higher byte.
20095 The result of @code{vec_vrlnm} is obtained by rotating each element
20096 of the first argument vector left and ANDing it with a mask. The
20097 second argument vector contains the mask beginning in bits 11:15,
20098 the mask end in bits 19:23, and the shift count in bits 27:31,
20101 If the ISA 3.0 instruction set additions (@option{-mcpu=power9})
20104 vector signed bool char vec_revb (vector signed char);
20105 vector signed char vec_revb (vector signed char);
20106 vector unsigned char vec_revb (vector unsigned char);
20107 vector bool short vec_revb (vector bool short);
20108 vector short vec_revb (vector short);
20109 vector unsigned short vec_revb (vector unsigned short);
20110 vector bool int vec_revb (vector bool int);
20111 vector int vec_revb (vector int);
20112 vector unsigned int vec_revb (vector unsigned int);
20113 vector float vec_revb (vector float);
20114 vector bool long long vec_revb (vector bool long long);
20115 vector long long vec_revb (vector long long);
20116 vector unsigned long long vec_revb (vector unsigned long long);
20117 vector double vec_revb (vector double);
20120 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
20123 vector long vec_revb (vector long);
20124 vector unsigned long vec_revb (vector unsigned long);
20125 vector __int128 vec_revb (vector __int128);
20126 vector __uint128 vec_revb (vector __uint128);
20129 The @code{vec_revb} built-in function reverses the bytes on an element
20130 by element basis. A vector of @code{vector unsigned char} or
20131 @code{vector signed char} reverses the bytes in the whole word.
20133 If the cryptographic instructions are enabled (@option{-mcrypto} or
20134 @option{-mcpu=power8}), the following builtins are enabled.
20137 vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long);
20139 vector unsigned char vec_sbox_be (vector unsigned char);
20141 vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long,
20142 vector unsigned long long);
20144 vector unsigned char vec_cipher_be (vector unsigned char, vector unsigned char);
20146 vector unsigned long long __builtin_crypto_vcipherlast
20147 (vector unsigned long long,
20148 vector unsigned long long);
20150 vector unsigned char vec_cipherlast_be (vector unsigned char,
20151 vector unsigned char);
20153 vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long,
20154 vector unsigned long long);
20156 vector unsigned char vec_ncipher_be (vector unsigned char,
20157 vector unsigned char);
20159 vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long,
20160 vector unsigned long long);
20162 vector unsigned char vec_ncipherlast_be (vector unsigned char,
20163 vector unsigned char);
20165 vector unsigned char __builtin_crypto_vpermxor (vector unsigned char,
20166 vector unsigned char,
20167 vector unsigned char);
20169 vector unsigned short __builtin_crypto_vpermxor (vector unsigned short,
20170 vector unsigned short,
20171 vector unsigned short);
20173 vector unsigned int __builtin_crypto_vpermxor (vector unsigned int,
20174 vector unsigned int,
20175 vector unsigned int);
20177 vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long,
20178 vector unsigned long long,
20179 vector unsigned long long);
20181 vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char,
20182 vector unsigned char);
20184 vector unsigned short __builtin_crypto_vpmsumb (vector unsigned short,
20185 vector unsigned short);
20187 vector unsigned int __builtin_crypto_vpmsumb (vector unsigned int,
20188 vector unsigned int);
20190 vector unsigned long long __builtin_crypto_vpmsumb (vector unsigned long long,
20191 vector unsigned long long);
20193 vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long,
20196 vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int);
20199 The second argument to @var{__builtin_crypto_vshasigmad} and
20200 @var{__builtin_crypto_vshasigmaw} must be a constant
20201 integer that is 0 or 1. The third argument to these built-in functions
20202 must be a constant integer in the range of 0 to 15.
20204 If the ISA 3.0 instruction set additions
20205 are enabled (@option{-mcpu=power9}), the following additional
20206 functions are available for both 32-bit and 64-bit targets.
20208 vector short vec_xl (int, vector short *);
20209 vector short vec_xl (int, short *);
20210 vector unsigned short vec_xl (int, vector unsigned short *);
20211 vector unsigned short vec_xl (int, unsigned short *);
20212 vector char vec_xl (int, vector char *);
20213 vector char vec_xl (int, char *);
20214 vector unsigned char vec_xl (int, vector unsigned char *);
20215 vector unsigned char vec_xl (int, unsigned char *);
20217 void vec_xst (vector short, int, vector short *);
20218 void vec_xst (vector short, int, short *);
20219 void vec_xst (vector unsigned short, int, vector unsigned short *);
20220 void vec_xst (vector unsigned short, int, unsigned short *);
20221 void vec_xst (vector char, int, vector char *);
20222 void vec_xst (vector char, int, char *);
20223 void vec_xst (vector unsigned char, int, vector unsigned char *);
20224 void vec_xst (vector unsigned char, int, unsigned char *);
20226 @node PowerPC Hardware Transactional Memory Built-in Functions
20227 @subsection PowerPC Hardware Transactional Memory Built-in Functions
20228 GCC provides two interfaces for accessing the Hardware Transactional
20229 Memory (HTM) instructions available on some of the PowerPC family
20230 of processors (eg, POWER8). The two interfaces come in a low level
20231 interface, consisting of built-in functions specific to PowerPC and a
20232 higher level interface consisting of inline functions that are common
20233 between PowerPC and S/390.
20235 @subsubsection PowerPC HTM Low Level Built-in Functions
20237 The following low level built-in functions are available with
20238 @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later.
20239 They all generate the machine instruction that is part of the name.
20241 The HTM builtins (with the exception of @code{__builtin_tbegin}) return
20242 the full 4-bit condition register value set by their associated hardware
20243 instruction. The header file @code{htmintrin.h} defines some macros that can
20244 be used to decipher the return value. The @code{__builtin_tbegin} builtin
20245 returns a simple @code{true} or @code{false} value depending on whether a transaction was
20246 successfully started or not. The arguments of the builtins match exactly the
20247 type and order of the associated hardware instruction's operands, except for
20248 the @code{__builtin_tcheck} builtin, which does not take any input arguments.
20249 Refer to the ISA manual for a description of each instruction's operands.
20252 unsigned int __builtin_tbegin (unsigned int)
20253 unsigned int __builtin_tend (unsigned int)
20255 unsigned int __builtin_tabort (unsigned int)
20256 unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int)
20257 unsigned int __builtin_tabortdci (unsigned int, unsigned int, int)
20258 unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int)
20259 unsigned int __builtin_tabortwci (unsigned int, unsigned int, int)
20261 unsigned int __builtin_tcheck (void)
20262 unsigned int __builtin_treclaim (unsigned int)
20263 unsigned int __builtin_trechkpt (void)
20264 unsigned int __builtin_tsr (unsigned int)
20267 In addition to the above HTM built-ins, we have added built-ins for
20268 some common extended mnemonics of the HTM instructions:
20271 unsigned int __builtin_tendall (void)
20272 unsigned int __builtin_tresume (void)
20273 unsigned int __builtin_tsuspend (void)
20276 Note that the semantics of the above HTM builtins are required to mimic
20277 the locking semantics used for critical sections. Builtins that are used
20278 to create a new transaction or restart a suspended transaction must have
20279 lock acquisition like semantics while those builtins that end or suspend a
20280 transaction must have lock release like semantics. Specifically, this must
20281 mimic lock semantics as specified by C++11, for example: Lock acquisition is
20282 as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE)
20283 that returns 0, and lock release is as-if an execution of
20284 __atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an
20285 implicit implementation-defined lock used for all transactions. The HTM
20286 instructions associated with with the builtins inherently provide the
20287 correct acquisition and release hardware barriers required. However,
20288 the compiler must also be prohibited from moving loads and stores across
20289 the builtins in a way that would violate their semantics. This has been
20290 accomplished by adding memory barriers to the associated HTM instructions
20291 (which is a conservative approach to provide acquire and release semantics).
20292 Earlier versions of the compiler did not treat the HTM instructions as
20293 memory barriers. A @code{__TM_FENCE__} macro has been added, which can
20294 be used to determine whether the current compiler treats HTM instructions
20295 as memory barriers or not. This allows the user to explicitly add memory
20296 barriers to their code when using an older version of the compiler.
20298 The following set of built-in functions are available to gain access
20299 to the HTM specific special purpose registers.
20302 unsigned long __builtin_get_texasr (void)
20303 unsigned long __builtin_get_texasru (void)
20304 unsigned long __builtin_get_tfhar (void)
20305 unsigned long __builtin_get_tfiar (void)
20307 void __builtin_set_texasr (unsigned long);
20308 void __builtin_set_texasru (unsigned long);
20309 void __builtin_set_tfhar (unsigned long);
20310 void __builtin_set_tfiar (unsigned long);
20313 Example usage of these low level built-in functions may look like:
20316 #include <htmintrin.h>
20318 int num_retries = 10;
20322 if (__builtin_tbegin (0))
20324 /* Transaction State Initiated. */
20325 if (is_locked (lock))
20326 __builtin_tabort (0);
20327 ... transaction code...
20328 __builtin_tend (0);
20333 /* Transaction State Failed. Use locks if the transaction
20334 failure is "persistent" or we've tried too many times. */
20335 if (num_retries-- <= 0
20336 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ()))
20338 acquire_lock (lock);
20339 ... non transactional fallback path...
20340 release_lock (lock);
20347 One final built-in function has been added that returns the value of
20348 the 2-bit Transaction State field of the Machine Status Register (MSR)
20349 as stored in @code{CR0}.
20352 unsigned long __builtin_ttest (void)
20355 This built-in can be used to determine the current transaction state
20356 using the following code example:
20359 #include <htmintrin.h>
20361 unsigned char tx_state = _HTM_STATE (__builtin_ttest ());
20363 if (tx_state == _HTM_TRANSACTIONAL)
20365 /* Code to use in transactional state. */
20367 else if (tx_state == _HTM_NONTRANSACTIONAL)
20369 /* Code to use in non-transactional state. */
20371 else if (tx_state == _HTM_SUSPENDED)
20373 /* Code to use in transaction suspended state. */
20377 @subsubsection PowerPC HTM High Level Inline Functions
20379 The following high level HTM interface is made available by including
20380 @code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU}
20381 where CPU is `power8' or later. This interface is common between PowerPC
20382 and S/390, allowing users to write one HTM source implementation that
20383 can be compiled and executed on either system.
20386 long __TM_simple_begin (void)
20387 long __TM_begin (void* const TM_buff)
20388 long __TM_end (void)
20389 void __TM_abort (void)
20390 void __TM_named_abort (unsigned char const code)
20391 void __TM_resume (void)
20392 void __TM_suspend (void)
20394 long __TM_is_user_abort (void* const TM_buff)
20395 long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code)
20396 long __TM_is_illegal (void* const TM_buff)
20397 long __TM_is_footprint_exceeded (void* const TM_buff)
20398 long __TM_nesting_depth (void* const TM_buff)
20399 long __TM_is_nested_too_deep(void* const TM_buff)
20400 long __TM_is_conflict(void* const TM_buff)
20401 long __TM_is_failure_persistent(void* const TM_buff)
20402 long __TM_failure_address(void* const TM_buff)
20403 long long __TM_failure_code(void* const TM_buff)
20406 Using these common set of HTM inline functions, we can create
20407 a more portable version of the HTM example in the previous
20408 section that will work on either PowerPC or S/390:
20411 #include <htmxlintrin.h>
20413 int num_retries = 10;
20414 TM_buff_type TM_buff;
20418 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED)
20420 /* Transaction State Initiated. */
20421 if (is_locked (lock))
20423 ... transaction code...
20429 /* Transaction State Failed. Use locks if the transaction
20430 failure is "persistent" or we've tried too many times. */
20431 if (num_retries-- <= 0
20432 || __TM_is_failure_persistent (TM_buff))
20434 acquire_lock (lock);
20435 ... non transactional fallback path...
20436 release_lock (lock);
20443 @node PowerPC Atomic Memory Operation Functions
20444 @subsection PowerPC Atomic Memory Operation Functions
20445 ISA 3.0 of the PowerPC added new atomic memory operation (amo)
20446 instructions. GCC provides support for these instructions in 64-bit
20447 environments. All of the functions are declared in the include file
20450 The functions supported are:
20455 uint32_t amo_lwat_add (uint32_t *, uint32_t);
20456 uint32_t amo_lwat_xor (uint32_t *, uint32_t);
20457 uint32_t amo_lwat_ior (uint32_t *, uint32_t);
20458 uint32_t amo_lwat_and (uint32_t *, uint32_t);
20459 uint32_t amo_lwat_umax (uint32_t *, uint32_t);
20460 uint32_t amo_lwat_umin (uint32_t *, uint32_t);
20461 uint32_t amo_lwat_swap (uint32_t *, uint32_t);
20463 int32_t amo_lwat_sadd (int32_t *, int32_t);
20464 int32_t amo_lwat_smax (int32_t *, int32_t);
20465 int32_t amo_lwat_smin (int32_t *, int32_t);
20466 int32_t amo_lwat_sswap (int32_t *, int32_t);
20468 uint64_t amo_ldat_add (uint64_t *, uint64_t);
20469 uint64_t amo_ldat_xor (uint64_t *, uint64_t);
20470 uint64_t amo_ldat_ior (uint64_t *, uint64_t);
20471 uint64_t amo_ldat_and (uint64_t *, uint64_t);
20472 uint64_t amo_ldat_umax (uint64_t *, uint64_t);
20473 uint64_t amo_ldat_umin (uint64_t *, uint64_t);
20474 uint64_t amo_ldat_swap (uint64_t *, uint64_t);
20476 int64_t amo_ldat_sadd (int64_t *, int64_t);
20477 int64_t amo_ldat_smax (int64_t *, int64_t);
20478 int64_t amo_ldat_smin (int64_t *, int64_t);
20479 int64_t amo_ldat_sswap (int64_t *, int64_t);
20481 void amo_stwat_add (uint32_t *, uint32_t);
20482 void amo_stwat_xor (uint32_t *, uint32_t);
20483 void amo_stwat_ior (uint32_t *, uint32_t);
20484 void amo_stwat_and (uint32_t *, uint32_t);
20485 void amo_stwat_umax (uint32_t *, uint32_t);
20486 void amo_stwat_umin (uint32_t *, uint32_t);
20488 void amo_stwat_sadd (int32_t *, int32_t);
20489 void amo_stwat_smax (int32_t *, int32_t);
20490 void amo_stwat_smin (int32_t *, int32_t);
20492 void amo_stdat_add (uint64_t *, uint64_t);
20493 void amo_stdat_xor (uint64_t *, uint64_t);
20494 void amo_stdat_ior (uint64_t *, uint64_t);
20495 void amo_stdat_and (uint64_t *, uint64_t);
20496 void amo_stdat_umax (uint64_t *, uint64_t);
20497 void amo_stdat_umin (uint64_t *, uint64_t);
20499 void amo_stdat_sadd (int64_t *, int64_t);
20500 void amo_stdat_smax (int64_t *, int64_t);
20501 void amo_stdat_smin (int64_t *, int64_t);
20504 @node RX Built-in Functions
20505 @subsection RX Built-in Functions
20506 GCC supports some of the RX instructions which cannot be expressed in
20507 the C programming language via the use of built-in functions. The
20508 following functions are supported:
20510 @deftypefn {Built-in Function} void __builtin_rx_brk (void)
20511 Generates the @code{brk} machine instruction.
20514 @deftypefn {Built-in Function} void __builtin_rx_clrpsw (int)
20515 Generates the @code{clrpsw} machine instruction to clear the specified
20516 bit in the processor status word.
20519 @deftypefn {Built-in Function} void __builtin_rx_int (int)
20520 Generates the @code{int} machine instruction to generate an interrupt
20521 with the specified value.
20524 @deftypefn {Built-in Function} void __builtin_rx_machi (int, int)
20525 Generates the @code{machi} machine instruction to add the result of
20526 multiplying the top 16 bits of the two arguments into the
20530 @deftypefn {Built-in Function} void __builtin_rx_maclo (int, int)
20531 Generates the @code{maclo} machine instruction to add the result of
20532 multiplying the bottom 16 bits of the two arguments into the
20536 @deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int)
20537 Generates the @code{mulhi} machine instruction to place the result of
20538 multiplying the top 16 bits of the two arguments into the
20542 @deftypefn {Built-in Function} void __builtin_rx_mullo (int, int)
20543 Generates the @code{mullo} machine instruction to place the result of
20544 multiplying the bottom 16 bits of the two arguments into the
20548 @deftypefn {Built-in Function} int __builtin_rx_mvfachi (void)
20549 Generates the @code{mvfachi} machine instruction to read the top
20550 32 bits of the accumulator.
20553 @deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void)
20554 Generates the @code{mvfacmi} machine instruction to read the middle
20555 32 bits of the accumulator.
20558 @deftypefn {Built-in Function} int __builtin_rx_mvfc (int)
20559 Generates the @code{mvfc} machine instruction which reads the control
20560 register specified in its argument and returns its value.
20563 @deftypefn {Built-in Function} void __builtin_rx_mvtachi (int)
20564 Generates the @code{mvtachi} machine instruction to set the top
20565 32 bits of the accumulator.
20568 @deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int)
20569 Generates the @code{mvtaclo} machine instruction to set the bottom
20570 32 bits of the accumulator.
20573 @deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val)
20574 Generates the @code{mvtc} machine instruction which sets control
20575 register number @code{reg} to @code{val}.
20578 @deftypefn {Built-in Function} void __builtin_rx_mvtipl (int)
20579 Generates the @code{mvtipl} machine instruction set the interrupt
20583 @deftypefn {Built-in Function} void __builtin_rx_racw (int)
20584 Generates the @code{racw} machine instruction to round the accumulator
20585 according to the specified mode.
20588 @deftypefn {Built-in Function} int __builtin_rx_revw (int)
20589 Generates the @code{revw} machine instruction which swaps the bytes in
20590 the argument so that bits 0--7 now occupy bits 8--15 and vice versa,
20591 and also bits 16--23 occupy bits 24--31 and vice versa.
20594 @deftypefn {Built-in Function} void __builtin_rx_rmpa (void)
20595 Generates the @code{rmpa} machine instruction which initiates a
20596 repeated multiply and accumulate sequence.
20599 @deftypefn {Built-in Function} void __builtin_rx_round (float)
20600 Generates the @code{round} machine instruction which returns the
20601 floating-point argument rounded according to the current rounding mode
20602 set in the floating-point status word register.
20605 @deftypefn {Built-in Function} int __builtin_rx_sat (int)
20606 Generates the @code{sat} machine instruction which returns the
20607 saturated value of the argument.
20610 @deftypefn {Built-in Function} void __builtin_rx_setpsw (int)
20611 Generates the @code{setpsw} machine instruction to set the specified
20612 bit in the processor status word.
20615 @deftypefn {Built-in Function} void __builtin_rx_wait (void)
20616 Generates the @code{wait} machine instruction.
20619 @node S/390 System z Built-in Functions
20620 @subsection S/390 System z Built-in Functions
20621 @deftypefn {Built-in Function} int __builtin_tbegin (void*)
20622 Generates the @code{tbegin} machine instruction starting a
20623 non-constrained hardware transaction. If the parameter is non-NULL the
20624 memory area is used to store the transaction diagnostic buffer and
20625 will be passed as first operand to @code{tbegin}. This buffer can be
20626 defined using the @code{struct __htm_tdb} C struct defined in
20627 @code{htmintrin.h} and must reside on a double-word boundary. The
20628 second tbegin operand is set to @code{0xff0c}. This enables
20629 save/restore of all GPRs and disables aborts for FPR and AR
20630 manipulations inside the transaction body. The condition code set by
20631 the tbegin instruction is returned as integer value. The tbegin
20632 instruction by definition overwrites the content of all FPRs. The
20633 compiler will generate code which saves and restores the FPRs. For
20634 soft-float code it is recommended to used the @code{*_nofloat}
20635 variant. In order to prevent a TDB from being written it is required
20636 to pass a constant zero value as parameter. Passing a zero value
20637 through a variable is not sufficient. Although modifications of
20638 access registers inside the transaction will not trigger an
20639 transaction abort it is not supported to actually modify them. Access
20640 registers do not get saved when entering a transaction. They will have
20641 undefined state when reaching the abort code.
20644 Macros for the possible return codes of tbegin are defined in the
20645 @code{htmintrin.h} header file:
20648 @item _HTM_TBEGIN_STARTED
20649 @code{tbegin} has been executed as part of normal processing. The
20650 transaction body is supposed to be executed.
20651 @item _HTM_TBEGIN_INDETERMINATE
20652 The transaction was aborted due to an indeterminate condition which
20653 might be persistent.
20654 @item _HTM_TBEGIN_TRANSIENT
20655 The transaction aborted due to a transient failure. The transaction
20656 should be re-executed in that case.
20657 @item _HTM_TBEGIN_PERSISTENT
20658 The transaction aborted due to a persistent failure. Re-execution
20659 under same circumstances will not be productive.
20662 @defmac _HTM_FIRST_USER_ABORT_CODE
20663 The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h}
20664 specifies the first abort code which can be used for
20665 @code{__builtin_tabort}. Values below this threshold are reserved for
20669 @deftp {Data type} {struct __htm_tdb}
20670 The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes
20671 the structure of the transaction diagnostic block as specified in the
20672 Principles of Operation manual chapter 5-91.
20675 @deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*)
20676 Same as @code{__builtin_tbegin} but without FPR saves and restores.
20677 Using this variant in code making use of FPRs will leave the FPRs in
20678 undefined state when entering the transaction abort handler code.
20681 @deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int)
20682 In addition to @code{__builtin_tbegin} a loop for transient failures
20683 is generated. If tbegin returns a condition code of 2 the transaction
20684 will be retried as often as specified in the second argument. The
20685 perform processor assist instruction is used to tell the CPU about the
20686 number of fails so far.
20689 @deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int)
20690 Same as @code{__builtin_tbegin_retry} but without FPR saves and
20691 restores. Using this variant in code making use of FPRs will leave
20692 the FPRs in undefined state when entering the transaction abort
20696 @deftypefn {Built-in Function} void __builtin_tbeginc (void)
20697 Generates the @code{tbeginc} machine instruction starting a constrained
20698 hardware transaction. The second operand is set to @code{0xff08}.
20701 @deftypefn {Built-in Function} int __builtin_tend (void)
20702 Generates the @code{tend} machine instruction finishing a transaction
20703 and making the changes visible to other threads. The condition code
20704 generated by tend is returned as integer value.
20707 @deftypefn {Built-in Function} void __builtin_tabort (int)
20708 Generates the @code{tabort} machine instruction with the specified
20709 abort code. Abort codes from 0 through 255 are reserved and will
20710 result in an error message.
20713 @deftypefn {Built-in Function} void __builtin_tx_assist (int)
20714 Generates the @code{ppa rX,rY,1} machine instruction. Where the
20715 integer parameter is loaded into rX and a value of zero is loaded into
20716 rY. The integer parameter specifies the number of times the
20717 transaction repeatedly aborted.
20720 @deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void)
20721 Generates the @code{etnd} machine instruction. The current nesting
20722 depth is returned as integer value. For a nesting depth of 0 the code
20723 is not executed as part of an transaction.
20726 @deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t)
20728 Generates the @code{ntstg} machine instruction. The second argument
20729 is written to the first arguments location. The store operation will
20730 not be rolled-back in case of an transaction abort.
20733 @node SH Built-in Functions
20734 @subsection SH Built-in Functions
20735 The following built-in functions are supported on the SH1, SH2, SH3 and SH4
20736 families of processors:
20738 @deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr})
20739 Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually
20740 used by system code that manages threads and execution contexts. The compiler
20741 normally does not generate code that modifies the contents of @samp{GBR} and
20742 thus the value is preserved across function calls. Changing the @samp{GBR}
20743 value in user code must be done with caution, since the compiler might use
20744 @samp{GBR} in order to access thread local variables.
20748 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
20749 Returns the value that is currently set in the @samp{GBR} register.
20750 Memory loads and stores that use the thread pointer as a base address are
20751 turned into @samp{GBR} based displacement loads and stores, if possible.
20759 int get_tcb_value (void)
20761 // Generate @samp{mov.l @@(8,gbr),r0} instruction
20762 return ((my_tcb*)__builtin_thread_pointer ())->c;
20768 @deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void)
20769 Returns the value that is currently set in the @samp{FPSCR} register.
20772 @deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val})
20773 Sets the @samp{FPSCR} register to the specified value @var{val}, while
20774 preserving the current values of the FR, SZ and PR bits.
20777 @node SPARC VIS Built-in Functions
20778 @subsection SPARC VIS Built-in Functions
20780 GCC supports SIMD operations on the SPARC using both the generic vector
20781 extensions (@pxref{Vector Extensions}) as well as built-in functions for
20782 the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis}
20783 switch, the VIS extension is exposed as the following built-in functions:
20786 typedef int v1si __attribute__ ((vector_size (4)));
20787 typedef int v2si __attribute__ ((vector_size (8)));
20788 typedef short v4hi __attribute__ ((vector_size (8)));
20789 typedef short v2hi __attribute__ ((vector_size (4)));
20790 typedef unsigned char v8qi __attribute__ ((vector_size (8)));
20791 typedef unsigned char v4qi __attribute__ ((vector_size (4)));
20793 void __builtin_vis_write_gsr (int64_t);
20794 int64_t __builtin_vis_read_gsr (void);
20796 void * __builtin_vis_alignaddr (void *, long);
20797 void * __builtin_vis_alignaddrl (void *, long);
20798 int64_t __builtin_vis_faligndatadi (int64_t, int64_t);
20799 v2si __builtin_vis_faligndatav2si (v2si, v2si);
20800 v4hi __builtin_vis_faligndatav4hi (v4si, v4si);
20801 v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi);
20803 v4hi __builtin_vis_fexpand (v4qi);
20805 v4hi __builtin_vis_fmul8x16 (v4qi, v4hi);
20806 v4hi __builtin_vis_fmul8x16au (v4qi, v2hi);
20807 v4hi __builtin_vis_fmul8x16al (v4qi, v2hi);
20808 v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi);
20809 v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi);
20810 v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi);
20811 v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi);
20813 v4qi __builtin_vis_fpack16 (v4hi);
20814 v8qi __builtin_vis_fpack32 (v2si, v8qi);
20815 v2hi __builtin_vis_fpackfix (v2si);
20816 v8qi __builtin_vis_fpmerge (v4qi, v4qi);
20818 int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t);
20820 long __builtin_vis_edge8 (void *, void *);
20821 long __builtin_vis_edge8l (void *, void *);
20822 long __builtin_vis_edge16 (void *, void *);
20823 long __builtin_vis_edge16l (void *, void *);
20824 long __builtin_vis_edge32 (void *, void *);
20825 long __builtin_vis_edge32l (void *, void *);
20827 long __builtin_vis_fcmple16 (v4hi, v4hi);
20828 long __builtin_vis_fcmple32 (v2si, v2si);
20829 long __builtin_vis_fcmpne16 (v4hi, v4hi);
20830 long __builtin_vis_fcmpne32 (v2si, v2si);
20831 long __builtin_vis_fcmpgt16 (v4hi, v4hi);
20832 long __builtin_vis_fcmpgt32 (v2si, v2si);
20833 long __builtin_vis_fcmpeq16 (v4hi, v4hi);
20834 long __builtin_vis_fcmpeq32 (v2si, v2si);
20836 v4hi __builtin_vis_fpadd16 (v4hi, v4hi);
20837 v2hi __builtin_vis_fpadd16s (v2hi, v2hi);
20838 v2si __builtin_vis_fpadd32 (v2si, v2si);
20839 v1si __builtin_vis_fpadd32s (v1si, v1si);
20840 v4hi __builtin_vis_fpsub16 (v4hi, v4hi);
20841 v2hi __builtin_vis_fpsub16s (v2hi, v2hi);
20842 v2si __builtin_vis_fpsub32 (v2si, v2si);
20843 v1si __builtin_vis_fpsub32s (v1si, v1si);
20845 long __builtin_vis_array8 (long, long);
20846 long __builtin_vis_array16 (long, long);
20847 long __builtin_vis_array32 (long, long);
20850 When you use the @option{-mvis2} switch, the VIS version 2.0 built-in
20851 functions also become available:
20854 long __builtin_vis_bmask (long, long);
20855 int64_t __builtin_vis_bshuffledi (int64_t, int64_t);
20856 v2si __builtin_vis_bshufflev2si (v2si, v2si);
20857 v4hi __builtin_vis_bshufflev2si (v4hi, v4hi);
20858 v8qi __builtin_vis_bshufflev2si (v8qi, v8qi);
20860 long __builtin_vis_edge8n (void *, void *);
20861 long __builtin_vis_edge8ln (void *, void *);
20862 long __builtin_vis_edge16n (void *, void *);
20863 long __builtin_vis_edge16ln (void *, void *);
20864 long __builtin_vis_edge32n (void *, void *);
20865 long __builtin_vis_edge32ln (void *, void *);
20868 When you use the @option{-mvis3} switch, the VIS version 3.0 built-in
20869 functions also become available:
20872 void __builtin_vis_cmask8 (long);
20873 void __builtin_vis_cmask16 (long);
20874 void __builtin_vis_cmask32 (long);
20876 v4hi __builtin_vis_fchksm16 (v4hi, v4hi);
20878 v4hi __builtin_vis_fsll16 (v4hi, v4hi);
20879 v4hi __builtin_vis_fslas16 (v4hi, v4hi);
20880 v4hi __builtin_vis_fsrl16 (v4hi, v4hi);
20881 v4hi __builtin_vis_fsra16 (v4hi, v4hi);
20882 v2si __builtin_vis_fsll16 (v2si, v2si);
20883 v2si __builtin_vis_fslas16 (v2si, v2si);
20884 v2si __builtin_vis_fsrl16 (v2si, v2si);
20885 v2si __builtin_vis_fsra16 (v2si, v2si);
20887 long __builtin_vis_pdistn (v8qi, v8qi);
20889 v4hi __builtin_vis_fmean16 (v4hi, v4hi);
20891 int64_t __builtin_vis_fpadd64 (int64_t, int64_t);
20892 int64_t __builtin_vis_fpsub64 (int64_t, int64_t);
20894 v4hi __builtin_vis_fpadds16 (v4hi, v4hi);
20895 v2hi __builtin_vis_fpadds16s (v2hi, v2hi);
20896 v4hi __builtin_vis_fpsubs16 (v4hi, v4hi);
20897 v2hi __builtin_vis_fpsubs16s (v2hi, v2hi);
20898 v2si __builtin_vis_fpadds32 (v2si, v2si);
20899 v1si __builtin_vis_fpadds32s (v1si, v1si);
20900 v2si __builtin_vis_fpsubs32 (v2si, v2si);
20901 v1si __builtin_vis_fpsubs32s (v1si, v1si);
20903 long __builtin_vis_fucmple8 (v8qi, v8qi);
20904 long __builtin_vis_fucmpne8 (v8qi, v8qi);
20905 long __builtin_vis_fucmpgt8 (v8qi, v8qi);
20906 long __builtin_vis_fucmpeq8 (v8qi, v8qi);
20908 float __builtin_vis_fhadds (float, float);
20909 double __builtin_vis_fhaddd (double, double);
20910 float __builtin_vis_fhsubs (float, float);
20911 double __builtin_vis_fhsubd (double, double);
20912 float __builtin_vis_fnhadds (float, float);
20913 double __builtin_vis_fnhaddd (double, double);
20915 int64_t __builtin_vis_umulxhi (int64_t, int64_t);
20916 int64_t __builtin_vis_xmulx (int64_t, int64_t);
20917 int64_t __builtin_vis_xmulxhi (int64_t, int64_t);
20920 When you use the @option{-mvis4} switch, the VIS version 4.0 built-in
20921 functions also become available:
20924 v8qi __builtin_vis_fpadd8 (v8qi, v8qi);
20925 v8qi __builtin_vis_fpadds8 (v8qi, v8qi);
20926 v8qi __builtin_vis_fpaddus8 (v8qi, v8qi);
20927 v4hi __builtin_vis_fpaddus16 (v4hi, v4hi);
20929 v8qi __builtin_vis_fpsub8 (v8qi, v8qi);
20930 v8qi __builtin_vis_fpsubs8 (v8qi, v8qi);
20931 v8qi __builtin_vis_fpsubus8 (v8qi, v8qi);
20932 v4hi __builtin_vis_fpsubus16 (v4hi, v4hi);
20934 long __builtin_vis_fpcmple8 (v8qi, v8qi);
20935 long __builtin_vis_fpcmpgt8 (v8qi, v8qi);
20936 long __builtin_vis_fpcmpule16 (v4hi, v4hi);
20937 long __builtin_vis_fpcmpugt16 (v4hi, v4hi);
20938 long __builtin_vis_fpcmpule32 (v2si, v2si);
20939 long __builtin_vis_fpcmpugt32 (v2si, v2si);
20941 v8qi __builtin_vis_fpmax8 (v8qi, v8qi);
20942 v4hi __builtin_vis_fpmax16 (v4hi, v4hi);
20943 v2si __builtin_vis_fpmax32 (v2si, v2si);
20945 v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi);
20946 v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi);
20947 v2si __builtin_vis_fpmaxu32 (v2si, v2si);
20950 v8qi __builtin_vis_fpmin8 (v8qi, v8qi);
20951 v4hi __builtin_vis_fpmin16 (v4hi, v4hi);
20952 v2si __builtin_vis_fpmin32 (v2si, v2si);
20954 v8qi __builtin_vis_fpminu8 (v8qi, v8qi);
20955 v4hi __builtin_vis_fpminu16 (v4hi, v4hi);
20956 v2si __builtin_vis_fpminu32 (v2si, v2si);
20959 When you use the @option{-mvis4b} switch, the VIS version 4.0B
20960 built-in functions also become available:
20963 v8qi __builtin_vis_dictunpack8 (double, int);
20964 v4hi __builtin_vis_dictunpack16 (double, int);
20965 v2si __builtin_vis_dictunpack32 (double, int);
20967 long __builtin_vis_fpcmple8shl (v8qi, v8qi, int);
20968 long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int);
20969 long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int);
20970 long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int);
20972 long __builtin_vis_fpcmple16shl (v4hi, v4hi, int);
20973 long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int);
20974 long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int);
20975 long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int);
20977 long __builtin_vis_fpcmple32shl (v2si, v2si, int);
20978 long __builtin_vis_fpcmpgt32shl (v2si, v2si, int);
20979 long __builtin_vis_fpcmpeq32shl (v2si, v2si, int);
20980 long __builtin_vis_fpcmpne32shl (v2si, v2si, int);
20982 long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int);
20983 long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int);
20984 long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int);
20985 long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int);
20986 long __builtin_vis_fpcmpule32shl (v2si, v2si, int);
20987 long __builtin_vis_fpcmpugt32shl (v2si, v2si, int);
20989 long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int);
20990 long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int);
20991 long __builtin_vis_fpcmpde32shl (v2si, v2si, int);
20993 long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int);
20994 long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int);
20995 long __builtin_vis_fpcmpur32shl (v2si, v2si, int);
20998 @node SPU Built-in Functions
20999 @subsection SPU Built-in Functions
21001 GCC provides extensions for the SPU processor as described in the
21002 Sony/Toshiba/IBM SPU Language Extensions Specification. GCC's
21003 implementation differs in several ways.
21008 The optional extension of specifying vector constants in parentheses is
21012 A vector initializer requires no cast if the vector constant is of the
21013 same type as the variable it is initializing.
21016 If @code{signed} or @code{unsigned} is omitted, the signedness of the
21017 vector type is the default signedness of the base type. The default
21018 varies depending on the operating system, so a portable program should
21019 always specify the signedness.
21022 By default, the keyword @code{__vector} is added. The macro
21023 @code{vector} is defined in @code{<spu_intrinsics.h>} and can be
21027 GCC allows using a @code{typedef} name as the type specifier for a
21031 For C, overloaded functions are implemented with macros so the following
21035 spu_add ((vector signed int)@{1, 2, 3, 4@}, foo);
21039 Since @code{spu_add} is a macro, the vector constant in the example
21040 is treated as four separate arguments. Wrap the entire argument in
21041 parentheses for this to work.
21044 The extended version of @code{__builtin_expect} is not supported.
21048 @emph{Note:} Only the interface described in the aforementioned
21049 specification is supported. Internally, GCC uses built-in functions to
21050 implement the required functionality, but these are not supported and
21051 are subject to change without notice.
21053 @node TI C6X Built-in Functions
21054 @subsection TI C6X Built-in Functions
21056 GCC provides intrinsics to access certain instructions of the TI C6X
21057 processors. These intrinsics, listed below, are available after
21058 inclusion of the @code{c6x_intrinsics.h} header file. They map directly
21059 to C6X instructions.
21063 int _sadd (int, int)
21064 int _ssub (int, int)
21065 int _sadd2 (int, int)
21066 int _ssub2 (int, int)
21067 long long _mpy2 (int, int)
21068 long long _smpy2 (int, int)
21069 int _add4 (int, int)
21070 int _sub4 (int, int)
21071 int _saddu4 (int, int)
21073 int _smpy (int, int)
21074 int _smpyh (int, int)
21075 int _smpyhl (int, int)
21076 int _smpylh (int, int)
21078 int _sshl (int, int)
21079 int _subc (int, int)
21081 int _avg2 (int, int)
21082 int _avgu4 (int, int)
21084 int _clrr (int, int)
21085 int _extr (int, int)
21086 int _extru (int, int)
21092 @node TILE-Gx Built-in Functions
21093 @subsection TILE-Gx Built-in Functions
21095 GCC provides intrinsics to access every instruction of the TILE-Gx
21096 processor. The intrinsics are of the form:
21100 unsigned long long __insn_@var{op} (...)
21104 Where @var{op} is the name of the instruction. Refer to the ISA manual
21105 for the complete list of instructions.
21107 GCC also provides intrinsics to directly access the network registers.
21108 The intrinsics are:
21112 unsigned long long __tile_idn0_receive (void)
21113 unsigned long long __tile_idn1_receive (void)
21114 unsigned long long __tile_udn0_receive (void)
21115 unsigned long long __tile_udn1_receive (void)
21116 unsigned long long __tile_udn2_receive (void)
21117 unsigned long long __tile_udn3_receive (void)
21118 void __tile_idn_send (unsigned long long)
21119 void __tile_udn_send (unsigned long long)
21123 The intrinsic @code{void __tile_network_barrier (void)} is used to
21124 guarantee that no network operations before it are reordered with
21127 @node TILEPro Built-in Functions
21128 @subsection TILEPro Built-in Functions
21130 GCC provides intrinsics to access every instruction of the TILEPro
21131 processor. The intrinsics are of the form:
21135 unsigned __insn_@var{op} (...)
21140 where @var{op} is the name of the instruction. Refer to the ISA manual
21141 for the complete list of instructions.
21143 GCC also provides intrinsics to directly access the network registers.
21144 The intrinsics are:
21148 unsigned __tile_idn0_receive (void)
21149 unsigned __tile_idn1_receive (void)
21150 unsigned __tile_sn_receive (void)
21151 unsigned __tile_udn0_receive (void)
21152 unsigned __tile_udn1_receive (void)
21153 unsigned __tile_udn2_receive (void)
21154 unsigned __tile_udn3_receive (void)
21155 void __tile_idn_send (unsigned)
21156 void __tile_sn_send (unsigned)
21157 void __tile_udn_send (unsigned)
21161 The intrinsic @code{void __tile_network_barrier (void)} is used to
21162 guarantee that no network operations before it are reordered with
21165 @node x86 Built-in Functions
21166 @subsection x86 Built-in Functions
21168 These built-in functions are available for the x86-32 and x86-64 family
21169 of computers, depending on the command-line switches used.
21171 If you specify command-line switches such as @option{-msse},
21172 the compiler could use the extended instruction sets even if the built-ins
21173 are not used explicitly in the program. For this reason, applications
21174 that perform run-time CPU detection must compile separate files for each
21175 supported architecture, using the appropriate flags. In particular,
21176 the file containing the CPU detection code should be compiled without
21179 The following machine modes are available for use with MMX built-in functions
21180 (@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers,
21181 @code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a
21182 vector of eight 8-bit integers. Some of the built-in functions operate on
21183 MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode.
21185 If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector
21186 of two 32-bit floating-point values.
21188 If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit
21189 floating-point values. Some instructions use a vector of four 32-bit
21190 integers, these use @code{V4SI}. Finally, some instructions operate on an
21191 entire vector register, interpreting it as a 128-bit integer, these use mode
21194 The x86-32 and x86-64 family of processors use additional built-in
21195 functions for efficient use of @code{TF} (@code{__float128}) 128-bit
21196 floating point and @code{TC} 128-bit complex floating-point values.
21198 The following floating-point built-in functions are always available. All
21199 of them implement the function that is part of the name.
21202 __float128 __builtin_fabsq (__float128)
21203 __float128 __builtin_copysignq (__float128, __float128)
21206 The following built-in functions are always available.
21209 @item __float128 __builtin_infq (void)
21210 Similar to @code{__builtin_inf}, except the return type is @code{__float128}.
21211 @findex __builtin_infq
21213 @item __float128 __builtin_huge_valq (void)
21214 Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}.
21215 @findex __builtin_huge_valq
21217 @item __float128 __builtin_nanq (void)
21218 Similar to @code{__builtin_nan}, except the return type is @code{__float128}.
21219 @findex __builtin_nanq
21221 @item __float128 __builtin_nansq (void)
21222 Similar to @code{__builtin_nans}, except the return type is @code{__float128}.
21223 @findex __builtin_nansq
21226 The following built-in function is always available.
21229 @item void __builtin_ia32_pause (void)
21230 Generates the @code{pause} machine instruction with a compiler memory
21234 The following built-in functions are always available and can be used to
21235 check the target platform type.
21237 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
21238 This function runs the CPU detection code to check the type of CPU and the
21239 features supported. This built-in function needs to be invoked along with the built-in functions
21240 to check CPU type and features, @code{__builtin_cpu_is} and
21241 @code{__builtin_cpu_supports}, only when used in a function that is
21242 executed before any constructors are called. The CPU detection code is
21243 automatically executed in a very high priority constructor.
21245 For example, this function has to be used in @code{ifunc} resolvers that
21246 check for CPU type using the built-in functions @code{__builtin_cpu_is}
21247 and @code{__builtin_cpu_supports}, or in constructors on targets that
21248 don't support constructor priority.
21251 static void (*resolve_memcpy (void)) (void)
21253 // ifunc resolvers fire before constructors, explicitly call the init
21255 __builtin_cpu_init ();
21256 if (__builtin_cpu_supports ("ssse3"))
21257 return ssse3_memcpy; // super fast memcpy with ssse3 instructions.
21259 return default_memcpy;
21262 void *memcpy (void *, const void *, size_t)
21263 __attribute__ ((ifunc ("resolve_memcpy")));
21268 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
21269 This function returns a positive integer if the run-time CPU
21270 is of type @var{cpuname}
21271 and returns @code{0} otherwise. The following CPU names can be detected:
21284 Intel Silvermont CPU.
21293 Intel Core i7 Nehalem CPU.
21296 Intel Core i7 Westmere CPU.
21299 Intel Core i7 Sandy Bridge CPU.
21302 Intel Core i7 Ivy Bridge CPU.
21305 Intel Core i7 Haswell CPU.
21308 Intel Core i7 Broadwell CPU.
21311 Intel Core i7 Skylake CPU.
21313 @item skylake-avx512
21314 Intel Core i7 Skylake AVX512 CPU.
21317 Intel Core i7 Cannon Lake CPU.
21319 @item icelake-client
21320 Intel Core i7 Ice Lake Client CPU.
21322 @item icelake-server
21323 Intel Core i7 Ice Lake Server CPU.
21326 Intel Core i7 Cascadelake CPU.
21329 Intel Atom Bonnell CPU.
21332 Intel Atom Silvermont CPU.
21335 Intel Atom Goldmont CPU.
21337 @item goldmont-plus
21338 Intel Atom Goldmont Plus CPU.
21341 Intel Atom Tremont CPU.
21344 Intel Knights Landing CPU.
21347 Intel Knights Mill CPU.
21350 AMD Family 10h CPU.
21353 AMD Family 10h Barcelona CPU.
21356 AMD Family 10h Shanghai CPU.
21359 AMD Family 10h Istanbul CPU.
21362 AMD Family 14h CPU.
21365 AMD Family 15h CPU.
21368 AMD Family 15h Bulldozer version 1.
21371 AMD Family 15h Bulldozer version 2.
21374 AMD Family 15h Bulldozer version 3.
21377 AMD Family 15h Bulldozer version 4.
21380 AMD Family 16h CPU.
21383 AMD Family 17h CPU.
21386 AMD Family 17h Zen version 1.
21389 AMD Family 17h Zen version 2.
21392 Here is an example:
21394 if (__builtin_cpu_is ("corei7"))
21396 do_corei7 (); // Core i7 specific implementation.
21400 do_generic (); // Generic implementation.
21405 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
21406 This function returns a positive integer if the run-time CPU
21407 supports @var{feature}
21408 and returns @code{0} otherwise. The following features can be detected:
21416 POPCNT instruction.
21424 SSSE3 instructions.
21426 SSE4.1 instructions.
21428 SSE4.2 instructions.
21434 SSE4A instructions.
21442 AVX512F instructions.
21450 PCLMUL instructions.
21452 AVX512VL instructions.
21454 AVX512BW instructions.
21456 AVX512DQ instructions.
21458 AVX512CD instructions.
21460 AVX512ER instructions.
21462 AVX512PF instructions.
21464 AVX512VBMI instructions.
21466 AVX512IFMA instructions.
21468 AVX5124VNNIW instructions.
21470 AVX5124FMAPS instructions.
21471 @item avx512vpopcntdq
21472 AVX512VPOPCNTDQ instructions.
21474 AVX512VBMI2 instructions.
21478 VPCLMULQDQ instructions.
21480 AVX512VNNI instructions.
21482 AVX512BITALG instructions.
21485 Here is an example:
21487 if (__builtin_cpu_supports ("popcnt"))
21489 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc");
21493 count = generic_countbits (n); //generic implementation.
21499 The following built-in functions are made available by @option{-mmmx}.
21500 All of them generate the machine instruction that is part of the name.
21503 v8qi __builtin_ia32_paddb (v8qi, v8qi)
21504 v4hi __builtin_ia32_paddw (v4hi, v4hi)
21505 v2si __builtin_ia32_paddd (v2si, v2si)
21506 v8qi __builtin_ia32_psubb (v8qi, v8qi)
21507 v4hi __builtin_ia32_psubw (v4hi, v4hi)
21508 v2si __builtin_ia32_psubd (v2si, v2si)
21509 v8qi __builtin_ia32_paddsb (v8qi, v8qi)
21510 v4hi __builtin_ia32_paddsw (v4hi, v4hi)
21511 v8qi __builtin_ia32_psubsb (v8qi, v8qi)
21512 v4hi __builtin_ia32_psubsw (v4hi, v4hi)
21513 v8qi __builtin_ia32_paddusb (v8qi, v8qi)
21514 v4hi __builtin_ia32_paddusw (v4hi, v4hi)
21515 v8qi __builtin_ia32_psubusb (v8qi, v8qi)
21516 v4hi __builtin_ia32_psubusw (v4hi, v4hi)
21517 v4hi __builtin_ia32_pmullw (v4hi, v4hi)
21518 v4hi __builtin_ia32_pmulhw (v4hi, v4hi)
21519 di __builtin_ia32_pand (di, di)
21520 di __builtin_ia32_pandn (di,di)
21521 di __builtin_ia32_por (di, di)
21522 di __builtin_ia32_pxor (di, di)
21523 v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi)
21524 v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi)
21525 v2si __builtin_ia32_pcmpeqd (v2si, v2si)
21526 v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi)
21527 v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi)
21528 v2si __builtin_ia32_pcmpgtd (v2si, v2si)
21529 v8qi __builtin_ia32_punpckhbw (v8qi, v8qi)
21530 v4hi __builtin_ia32_punpckhwd (v4hi, v4hi)
21531 v2si __builtin_ia32_punpckhdq (v2si, v2si)
21532 v8qi __builtin_ia32_punpcklbw (v8qi, v8qi)
21533 v4hi __builtin_ia32_punpcklwd (v4hi, v4hi)
21534 v2si __builtin_ia32_punpckldq (v2si, v2si)
21535 v8qi __builtin_ia32_packsswb (v4hi, v4hi)
21536 v4hi __builtin_ia32_packssdw (v2si, v2si)
21537 v8qi __builtin_ia32_packuswb (v4hi, v4hi)
21539 v4hi __builtin_ia32_psllw (v4hi, v4hi)
21540 v2si __builtin_ia32_pslld (v2si, v2si)
21541 v1di __builtin_ia32_psllq (v1di, v1di)
21542 v4hi __builtin_ia32_psrlw (v4hi, v4hi)
21543 v2si __builtin_ia32_psrld (v2si, v2si)
21544 v1di __builtin_ia32_psrlq (v1di, v1di)
21545 v4hi __builtin_ia32_psraw (v4hi, v4hi)
21546 v2si __builtin_ia32_psrad (v2si, v2si)
21547 v4hi __builtin_ia32_psllwi (v4hi, int)
21548 v2si __builtin_ia32_pslldi (v2si, int)
21549 v1di __builtin_ia32_psllqi (v1di, int)
21550 v4hi __builtin_ia32_psrlwi (v4hi, int)
21551 v2si __builtin_ia32_psrldi (v2si, int)
21552 v1di __builtin_ia32_psrlqi (v1di, int)
21553 v4hi __builtin_ia32_psrawi (v4hi, int)
21554 v2si __builtin_ia32_psradi (v2si, int)
21558 The following built-in functions are made available either with
21559 @option{-msse}, or with @option{-m3dnowa}. All of them generate
21560 the machine instruction that is part of the name.
21563 v4hi __builtin_ia32_pmulhuw (v4hi, v4hi)
21564 v8qi __builtin_ia32_pavgb (v8qi, v8qi)
21565 v4hi __builtin_ia32_pavgw (v4hi, v4hi)
21566 v1di __builtin_ia32_psadbw (v8qi, v8qi)
21567 v8qi __builtin_ia32_pmaxub (v8qi, v8qi)
21568 v4hi __builtin_ia32_pmaxsw (v4hi, v4hi)
21569 v8qi __builtin_ia32_pminub (v8qi, v8qi)
21570 v4hi __builtin_ia32_pminsw (v4hi, v4hi)
21571 int __builtin_ia32_pmovmskb (v8qi)
21572 void __builtin_ia32_maskmovq (v8qi, v8qi, char *)
21573 void __builtin_ia32_movntq (di *, di)
21574 void __builtin_ia32_sfence (void)
21577 The following built-in functions are available when @option{-msse} is used.
21578 All of them generate the machine instruction that is part of the name.
21581 int __builtin_ia32_comieq (v4sf, v4sf)
21582 int __builtin_ia32_comineq (v4sf, v4sf)
21583 int __builtin_ia32_comilt (v4sf, v4sf)
21584 int __builtin_ia32_comile (v4sf, v4sf)
21585 int __builtin_ia32_comigt (v4sf, v4sf)
21586 int __builtin_ia32_comige (v4sf, v4sf)
21587 int __builtin_ia32_ucomieq (v4sf, v4sf)
21588 int __builtin_ia32_ucomineq (v4sf, v4sf)
21589 int __builtin_ia32_ucomilt (v4sf, v4sf)
21590 int __builtin_ia32_ucomile (v4sf, v4sf)
21591 int __builtin_ia32_ucomigt (v4sf, v4sf)
21592 int __builtin_ia32_ucomige (v4sf, v4sf)
21593 v4sf __builtin_ia32_addps (v4sf, v4sf)
21594 v4sf __builtin_ia32_subps (v4sf, v4sf)
21595 v4sf __builtin_ia32_mulps (v4sf, v4sf)
21596 v4sf __builtin_ia32_divps (v4sf, v4sf)
21597 v4sf __builtin_ia32_addss (v4sf, v4sf)
21598 v4sf __builtin_ia32_subss (v4sf, v4sf)
21599 v4sf __builtin_ia32_mulss (v4sf, v4sf)
21600 v4sf __builtin_ia32_divss (v4sf, v4sf)
21601 v4sf __builtin_ia32_cmpeqps (v4sf, v4sf)
21602 v4sf __builtin_ia32_cmpltps (v4sf, v4sf)
21603 v4sf __builtin_ia32_cmpleps (v4sf, v4sf)
21604 v4sf __builtin_ia32_cmpgtps (v4sf, v4sf)
21605 v4sf __builtin_ia32_cmpgeps (v4sf, v4sf)
21606 v4sf __builtin_ia32_cmpunordps (v4sf, v4sf)
21607 v4sf __builtin_ia32_cmpneqps (v4sf, v4sf)
21608 v4sf __builtin_ia32_cmpnltps (v4sf, v4sf)
21609 v4sf __builtin_ia32_cmpnleps (v4sf, v4sf)
21610 v4sf __builtin_ia32_cmpngtps (v4sf, v4sf)
21611 v4sf __builtin_ia32_cmpngeps (v4sf, v4sf)
21612 v4sf __builtin_ia32_cmpordps (v4sf, v4sf)
21613 v4sf __builtin_ia32_cmpeqss (v4sf, v4sf)
21614 v4sf __builtin_ia32_cmpltss (v4sf, v4sf)
21615 v4sf __builtin_ia32_cmpless (v4sf, v4sf)
21616 v4sf __builtin_ia32_cmpunordss (v4sf, v4sf)
21617 v4sf __builtin_ia32_cmpneqss (v4sf, v4sf)
21618 v4sf __builtin_ia32_cmpnltss (v4sf, v4sf)
21619 v4sf __builtin_ia32_cmpnless (v4sf, v4sf)
21620 v4sf __builtin_ia32_cmpordss (v4sf, v4sf)
21621 v4sf __builtin_ia32_maxps (v4sf, v4sf)
21622 v4sf __builtin_ia32_maxss (v4sf, v4sf)
21623 v4sf __builtin_ia32_minps (v4sf, v4sf)
21624 v4sf __builtin_ia32_minss (v4sf, v4sf)
21625 v4sf __builtin_ia32_andps (v4sf, v4sf)
21626 v4sf __builtin_ia32_andnps (v4sf, v4sf)
21627 v4sf __builtin_ia32_orps (v4sf, v4sf)
21628 v4sf __builtin_ia32_xorps (v4sf, v4sf)
21629 v4sf __builtin_ia32_movss (v4sf, v4sf)
21630 v4sf __builtin_ia32_movhlps (v4sf, v4sf)
21631 v4sf __builtin_ia32_movlhps (v4sf, v4sf)
21632 v4sf __builtin_ia32_unpckhps (v4sf, v4sf)
21633 v4sf __builtin_ia32_unpcklps (v4sf, v4sf)
21634 v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si)
21635 v4sf __builtin_ia32_cvtsi2ss (v4sf, int)
21636 v2si __builtin_ia32_cvtps2pi (v4sf)
21637 int __builtin_ia32_cvtss2si (v4sf)
21638 v2si __builtin_ia32_cvttps2pi (v4sf)
21639 int __builtin_ia32_cvttss2si (v4sf)
21640 v4sf __builtin_ia32_rcpps (v4sf)
21641 v4sf __builtin_ia32_rsqrtps (v4sf)
21642 v4sf __builtin_ia32_sqrtps (v4sf)
21643 v4sf __builtin_ia32_rcpss (v4sf)
21644 v4sf __builtin_ia32_rsqrtss (v4sf)
21645 v4sf __builtin_ia32_sqrtss (v4sf)
21646 v4sf __builtin_ia32_shufps (v4sf, v4sf, int)
21647 void __builtin_ia32_movntps (float *, v4sf)
21648 int __builtin_ia32_movmskps (v4sf)
21651 The following built-in functions are available when @option{-msse} is used.
21654 @item v4sf __builtin_ia32_loadups (float *)
21655 Generates the @code{movups} machine instruction as a load from memory.
21656 @item void __builtin_ia32_storeups (float *, v4sf)
21657 Generates the @code{movups} machine instruction as a store to memory.
21658 @item v4sf __builtin_ia32_loadss (float *)
21659 Generates the @code{movss} machine instruction as a load from memory.
21660 @item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)
21661 Generates the @code{movhps} machine instruction as a load from memory.
21662 @item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)
21663 Generates the @code{movlps} machine instruction as a load from memory
21664 @item void __builtin_ia32_storehps (v2sf *, v4sf)
21665 Generates the @code{movhps} machine instruction as a store to memory.
21666 @item void __builtin_ia32_storelps (v2sf *, v4sf)
21667 Generates the @code{movlps} machine instruction as a store to memory.
21670 The following built-in functions are available when @option{-msse2} is used.
21671 All of them generate the machine instruction that is part of the name.
21674 int __builtin_ia32_comisdeq (v2df, v2df)
21675 int __builtin_ia32_comisdlt (v2df, v2df)
21676 int __builtin_ia32_comisdle (v2df, v2df)
21677 int __builtin_ia32_comisdgt (v2df, v2df)
21678 int __builtin_ia32_comisdge (v2df, v2df)
21679 int __builtin_ia32_comisdneq (v2df, v2df)
21680 int __builtin_ia32_ucomisdeq (v2df, v2df)
21681 int __builtin_ia32_ucomisdlt (v2df, v2df)
21682 int __builtin_ia32_ucomisdle (v2df, v2df)
21683 int __builtin_ia32_ucomisdgt (v2df, v2df)
21684 int __builtin_ia32_ucomisdge (v2df, v2df)
21685 int __builtin_ia32_ucomisdneq (v2df, v2df)
21686 v2df __builtin_ia32_cmpeqpd (v2df, v2df)
21687 v2df __builtin_ia32_cmpltpd (v2df, v2df)
21688 v2df __builtin_ia32_cmplepd (v2df, v2df)
21689 v2df __builtin_ia32_cmpgtpd (v2df, v2df)
21690 v2df __builtin_ia32_cmpgepd (v2df, v2df)
21691 v2df __builtin_ia32_cmpunordpd (v2df, v2df)
21692 v2df __builtin_ia32_cmpneqpd (v2df, v2df)
21693 v2df __builtin_ia32_cmpnltpd (v2df, v2df)
21694 v2df __builtin_ia32_cmpnlepd (v2df, v2df)
21695 v2df __builtin_ia32_cmpngtpd (v2df, v2df)
21696 v2df __builtin_ia32_cmpngepd (v2df, v2df)
21697 v2df __builtin_ia32_cmpordpd (v2df, v2df)
21698 v2df __builtin_ia32_cmpeqsd (v2df, v2df)
21699 v2df __builtin_ia32_cmpltsd (v2df, v2df)
21700 v2df __builtin_ia32_cmplesd (v2df, v2df)
21701 v2df __builtin_ia32_cmpunordsd (v2df, v2df)
21702 v2df __builtin_ia32_cmpneqsd (v2df, v2df)
21703 v2df __builtin_ia32_cmpnltsd (v2df, v2df)
21704 v2df __builtin_ia32_cmpnlesd (v2df, v2df)
21705 v2df __builtin_ia32_cmpordsd (v2df, v2df)
21706 v2di __builtin_ia32_paddq (v2di, v2di)
21707 v2di __builtin_ia32_psubq (v2di, v2di)
21708 v2df __builtin_ia32_addpd (v2df, v2df)
21709 v2df __builtin_ia32_subpd (v2df, v2df)
21710 v2df __builtin_ia32_mulpd (v2df, v2df)
21711 v2df __builtin_ia32_divpd (v2df, v2df)
21712 v2df __builtin_ia32_addsd (v2df, v2df)
21713 v2df __builtin_ia32_subsd (v2df, v2df)
21714 v2df __builtin_ia32_mulsd (v2df, v2df)
21715 v2df __builtin_ia32_divsd (v2df, v2df)
21716 v2df __builtin_ia32_minpd (v2df, v2df)
21717 v2df __builtin_ia32_maxpd (v2df, v2df)
21718 v2df __builtin_ia32_minsd (v2df, v2df)
21719 v2df __builtin_ia32_maxsd (v2df, v2df)
21720 v2df __builtin_ia32_andpd (v2df, v2df)
21721 v2df __builtin_ia32_andnpd (v2df, v2df)
21722 v2df __builtin_ia32_orpd (v2df, v2df)
21723 v2df __builtin_ia32_xorpd (v2df, v2df)
21724 v2df __builtin_ia32_movsd (v2df, v2df)
21725 v2df __builtin_ia32_unpckhpd (v2df, v2df)
21726 v2df __builtin_ia32_unpcklpd (v2df, v2df)
21727 v16qi __builtin_ia32_paddb128 (v16qi, v16qi)
21728 v8hi __builtin_ia32_paddw128 (v8hi, v8hi)
21729 v4si __builtin_ia32_paddd128 (v4si, v4si)
21730 v2di __builtin_ia32_paddq128 (v2di, v2di)
21731 v16qi __builtin_ia32_psubb128 (v16qi, v16qi)
21732 v8hi __builtin_ia32_psubw128 (v8hi, v8hi)
21733 v4si __builtin_ia32_psubd128 (v4si, v4si)
21734 v2di __builtin_ia32_psubq128 (v2di, v2di)
21735 v8hi __builtin_ia32_pmullw128 (v8hi, v8hi)
21736 v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi)
21737 v2di __builtin_ia32_pand128 (v2di, v2di)
21738 v2di __builtin_ia32_pandn128 (v2di, v2di)
21739 v2di __builtin_ia32_por128 (v2di, v2di)
21740 v2di __builtin_ia32_pxor128 (v2di, v2di)
21741 v16qi __builtin_ia32_pavgb128 (v16qi, v16qi)
21742 v8hi __builtin_ia32_pavgw128 (v8hi, v8hi)
21743 v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi)
21744 v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi)
21745 v4si __builtin_ia32_pcmpeqd128 (v4si, v4si)
21746 v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi)
21747 v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi)
21748 v4si __builtin_ia32_pcmpgtd128 (v4si, v4si)
21749 v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi)
21750 v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi)
21751 v16qi __builtin_ia32_pminub128 (v16qi, v16qi)
21752 v8hi __builtin_ia32_pminsw128 (v8hi, v8hi)
21753 v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi)
21754 v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi)
21755 v4si __builtin_ia32_punpckhdq128 (v4si, v4si)
21756 v2di __builtin_ia32_punpckhqdq128 (v2di, v2di)
21757 v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi)
21758 v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi)
21759 v4si __builtin_ia32_punpckldq128 (v4si, v4si)
21760 v2di __builtin_ia32_punpcklqdq128 (v2di, v2di)
21761 v16qi __builtin_ia32_packsswb128 (v8hi, v8hi)
21762 v8hi __builtin_ia32_packssdw128 (v4si, v4si)
21763 v16qi __builtin_ia32_packuswb128 (v8hi, v8hi)
21764 v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi)
21765 void __builtin_ia32_maskmovdqu (v16qi, v16qi)
21766 v2df __builtin_ia32_loadupd (double *)
21767 void __builtin_ia32_storeupd (double *, v2df)
21768 v2df __builtin_ia32_loadhpd (v2df, double const *)
21769 v2df __builtin_ia32_loadlpd (v2df, double const *)
21770 int __builtin_ia32_movmskpd (v2df)
21771 int __builtin_ia32_pmovmskb128 (v16qi)
21772 void __builtin_ia32_movnti (int *, int)
21773 void __builtin_ia32_movnti64 (long long int *, long long int)
21774 void __builtin_ia32_movntpd (double *, v2df)
21775 void __builtin_ia32_movntdq (v2df *, v2df)
21776 v4si __builtin_ia32_pshufd (v4si, int)
21777 v8hi __builtin_ia32_pshuflw (v8hi, int)
21778 v8hi __builtin_ia32_pshufhw (v8hi, int)
21779 v2di __builtin_ia32_psadbw128 (v16qi, v16qi)
21780 v2df __builtin_ia32_sqrtpd (v2df)
21781 v2df __builtin_ia32_sqrtsd (v2df)
21782 v2df __builtin_ia32_shufpd (v2df, v2df, int)
21783 v2df __builtin_ia32_cvtdq2pd (v4si)
21784 v4sf __builtin_ia32_cvtdq2ps (v4si)
21785 v4si __builtin_ia32_cvtpd2dq (v2df)
21786 v2si __builtin_ia32_cvtpd2pi (v2df)
21787 v4sf __builtin_ia32_cvtpd2ps (v2df)
21788 v4si __builtin_ia32_cvttpd2dq (v2df)
21789 v2si __builtin_ia32_cvttpd2pi (v2df)
21790 v2df __builtin_ia32_cvtpi2pd (v2si)
21791 int __builtin_ia32_cvtsd2si (v2df)
21792 int __builtin_ia32_cvttsd2si (v2df)
21793 long long __builtin_ia32_cvtsd2si64 (v2df)
21794 long long __builtin_ia32_cvttsd2si64 (v2df)
21795 v4si __builtin_ia32_cvtps2dq (v4sf)
21796 v2df __builtin_ia32_cvtps2pd (v4sf)
21797 v4si __builtin_ia32_cvttps2dq (v4sf)
21798 v2df __builtin_ia32_cvtsi2sd (v2df, int)
21799 v2df __builtin_ia32_cvtsi642sd (v2df, long long)
21800 v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df)
21801 v2df __builtin_ia32_cvtss2sd (v2df, v4sf)
21802 void __builtin_ia32_clflush (const void *)
21803 void __builtin_ia32_lfence (void)
21804 void __builtin_ia32_mfence (void)
21805 v16qi __builtin_ia32_loaddqu (const char *)
21806 void __builtin_ia32_storedqu (char *, v16qi)
21807 v1di __builtin_ia32_pmuludq (v2si, v2si)
21808 v2di __builtin_ia32_pmuludq128 (v4si, v4si)
21809 v8hi __builtin_ia32_psllw128 (v8hi, v8hi)
21810 v4si __builtin_ia32_pslld128 (v4si, v4si)
21811 v2di __builtin_ia32_psllq128 (v2di, v2di)
21812 v8hi __builtin_ia32_psrlw128 (v8hi, v8hi)
21813 v4si __builtin_ia32_psrld128 (v4si, v4si)
21814 v2di __builtin_ia32_psrlq128 (v2di, v2di)
21815 v8hi __builtin_ia32_psraw128 (v8hi, v8hi)
21816 v4si __builtin_ia32_psrad128 (v4si, v4si)
21817 v2di __builtin_ia32_pslldqi128 (v2di, int)
21818 v8hi __builtin_ia32_psllwi128 (v8hi, int)
21819 v4si __builtin_ia32_pslldi128 (v4si, int)
21820 v2di __builtin_ia32_psllqi128 (v2di, int)
21821 v2di __builtin_ia32_psrldqi128 (v2di, int)
21822 v8hi __builtin_ia32_psrlwi128 (v8hi, int)
21823 v4si __builtin_ia32_psrldi128 (v4si, int)
21824 v2di __builtin_ia32_psrlqi128 (v2di, int)
21825 v8hi __builtin_ia32_psrawi128 (v8hi, int)
21826 v4si __builtin_ia32_psradi128 (v4si, int)
21827 v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi)
21828 v2di __builtin_ia32_movq128 (v2di)
21831 The following built-in functions are available when @option{-msse3} is used.
21832 All of them generate the machine instruction that is part of the name.
21835 v2df __builtin_ia32_addsubpd (v2df, v2df)
21836 v4sf __builtin_ia32_addsubps (v4sf, v4sf)
21837 v2df __builtin_ia32_haddpd (v2df, v2df)
21838 v4sf __builtin_ia32_haddps (v4sf, v4sf)
21839 v2df __builtin_ia32_hsubpd (v2df, v2df)
21840 v4sf __builtin_ia32_hsubps (v4sf, v4sf)
21841 v16qi __builtin_ia32_lddqu (char const *)
21842 void __builtin_ia32_monitor (void *, unsigned int, unsigned int)
21843 v4sf __builtin_ia32_movshdup (v4sf)
21844 v4sf __builtin_ia32_movsldup (v4sf)
21845 void __builtin_ia32_mwait (unsigned int, unsigned int)
21848 The following built-in functions are available when @option{-mssse3} is used.
21849 All of them generate the machine instruction that is part of the name.
21852 v2si __builtin_ia32_phaddd (v2si, v2si)
21853 v4hi __builtin_ia32_phaddw (v4hi, v4hi)
21854 v4hi __builtin_ia32_phaddsw (v4hi, v4hi)
21855 v2si __builtin_ia32_phsubd (v2si, v2si)
21856 v4hi __builtin_ia32_phsubw (v4hi, v4hi)
21857 v4hi __builtin_ia32_phsubsw (v4hi, v4hi)
21858 v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi)
21859 v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi)
21860 v8qi __builtin_ia32_pshufb (v8qi, v8qi)
21861 v8qi __builtin_ia32_psignb (v8qi, v8qi)
21862 v2si __builtin_ia32_psignd (v2si, v2si)
21863 v4hi __builtin_ia32_psignw (v4hi, v4hi)
21864 v1di __builtin_ia32_palignr (v1di, v1di, int)
21865 v8qi __builtin_ia32_pabsb (v8qi)
21866 v2si __builtin_ia32_pabsd (v2si)
21867 v4hi __builtin_ia32_pabsw (v4hi)
21870 The following built-in functions are available when @option{-mssse3} is used.
21871 All of them generate the machine instruction that is part of the name.
21874 v4si __builtin_ia32_phaddd128 (v4si, v4si)
21875 v8hi __builtin_ia32_phaddw128 (v8hi, v8hi)
21876 v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi)
21877 v4si __builtin_ia32_phsubd128 (v4si, v4si)
21878 v8hi __builtin_ia32_phsubw128 (v8hi, v8hi)
21879 v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi)
21880 v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi)
21881 v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi)
21882 v16qi __builtin_ia32_pshufb128 (v16qi, v16qi)
21883 v16qi __builtin_ia32_psignb128 (v16qi, v16qi)
21884 v4si __builtin_ia32_psignd128 (v4si, v4si)
21885 v8hi __builtin_ia32_psignw128 (v8hi, v8hi)
21886 v2di __builtin_ia32_palignr128 (v2di, v2di, int)
21887 v16qi __builtin_ia32_pabsb128 (v16qi)
21888 v4si __builtin_ia32_pabsd128 (v4si)
21889 v8hi __builtin_ia32_pabsw128 (v8hi)
21892 The following built-in functions are available when @option{-msse4.1} is
21893 used. All of them generate the machine instruction that is part of the
21897 v2df __builtin_ia32_blendpd (v2df, v2df, const int)
21898 v4sf __builtin_ia32_blendps (v4sf, v4sf, const int)
21899 v2df __builtin_ia32_blendvpd (v2df, v2df, v2df)
21900 v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf)
21901 v2df __builtin_ia32_dppd (v2df, v2df, const int)
21902 v4sf __builtin_ia32_dpps (v4sf, v4sf, const int)
21903 v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int)
21904 v2di __builtin_ia32_movntdqa (v2di *);
21905 v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int)
21906 v8hi __builtin_ia32_packusdw128 (v4si, v4si)
21907 v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi)
21908 v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int)
21909 v2di __builtin_ia32_pcmpeqq (v2di, v2di)
21910 v8hi __builtin_ia32_phminposuw128 (v8hi)
21911 v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi)
21912 v4si __builtin_ia32_pmaxsd128 (v4si, v4si)
21913 v4si __builtin_ia32_pmaxud128 (v4si, v4si)
21914 v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi)
21915 v16qi __builtin_ia32_pminsb128 (v16qi, v16qi)
21916 v4si __builtin_ia32_pminsd128 (v4si, v4si)
21917 v4si __builtin_ia32_pminud128 (v4si, v4si)
21918 v8hi __builtin_ia32_pminuw128 (v8hi, v8hi)
21919 v4si __builtin_ia32_pmovsxbd128 (v16qi)
21920 v2di __builtin_ia32_pmovsxbq128 (v16qi)
21921 v8hi __builtin_ia32_pmovsxbw128 (v16qi)
21922 v2di __builtin_ia32_pmovsxdq128 (v4si)
21923 v4si __builtin_ia32_pmovsxwd128 (v8hi)
21924 v2di __builtin_ia32_pmovsxwq128 (v8hi)
21925 v4si __builtin_ia32_pmovzxbd128 (v16qi)
21926 v2di __builtin_ia32_pmovzxbq128 (v16qi)
21927 v8hi __builtin_ia32_pmovzxbw128 (v16qi)
21928 v2di __builtin_ia32_pmovzxdq128 (v4si)
21929 v4si __builtin_ia32_pmovzxwd128 (v8hi)
21930 v2di __builtin_ia32_pmovzxwq128 (v8hi)
21931 v2di __builtin_ia32_pmuldq128 (v4si, v4si)
21932 v4si __builtin_ia32_pmulld128 (v4si, v4si)
21933 int __builtin_ia32_ptestc128 (v2di, v2di)
21934 int __builtin_ia32_ptestnzc128 (v2di, v2di)
21935 int __builtin_ia32_ptestz128 (v2di, v2di)
21936 v2df __builtin_ia32_roundpd (v2df, const int)
21937 v4sf __builtin_ia32_roundps (v4sf, const int)
21938 v2df __builtin_ia32_roundsd (v2df, v2df, const int)
21939 v4sf __builtin_ia32_roundss (v4sf, v4sf, const int)
21942 The following built-in functions are available when @option{-msse4.1} is
21946 @item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)
21947 Generates the @code{insertps} machine instruction.
21948 @item int __builtin_ia32_vec_ext_v16qi (v16qi, const int)
21949 Generates the @code{pextrb} machine instruction.
21950 @item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)
21951 Generates the @code{pinsrb} machine instruction.
21952 @item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)
21953 Generates the @code{pinsrd} machine instruction.
21954 @item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)
21955 Generates the @code{pinsrq} machine instruction in 64bit mode.
21958 The following built-in functions are changed to generate new SSE4.1
21959 instructions when @option{-msse4.1} is used.
21962 @item float __builtin_ia32_vec_ext_v4sf (v4sf, const int)
21963 Generates the @code{extractps} machine instruction.
21964 @item int __builtin_ia32_vec_ext_v4si (v4si, const int)
21965 Generates the @code{pextrd} machine instruction.
21966 @item long long __builtin_ia32_vec_ext_v2di (v2di, const int)
21967 Generates the @code{pextrq} machine instruction in 64bit mode.
21970 The following built-in functions are available when @option{-msse4.2} is
21971 used. All of them generate the machine instruction that is part of the
21975 v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int)
21976 int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int)
21977 int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int)
21978 int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int)
21979 int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int)
21980 int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int)
21981 int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int)
21982 v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int)
21983 int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int)
21984 int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int)
21985 int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int)
21986 int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int)
21987 int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int)
21988 int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int)
21989 v2di __builtin_ia32_pcmpgtq (v2di, v2di)
21992 The following built-in functions are available when @option{-msse4.2} is
21996 @item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char)
21997 Generates the @code{crc32b} machine instruction.
21998 @item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short)
21999 Generates the @code{crc32w} machine instruction.
22000 @item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int)
22001 Generates the @code{crc32l} machine instruction.
22002 @item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long)
22003 Generates the @code{crc32q} machine instruction.
22006 The following built-in functions are changed to generate new SSE4.2
22007 instructions when @option{-msse4.2} is used.
22010 @item int __builtin_popcount (unsigned int)
22011 Generates the @code{popcntl} machine instruction.
22012 @item int __builtin_popcountl (unsigned long)
22013 Generates the @code{popcntl} or @code{popcntq} machine instruction,
22014 depending on the size of @code{unsigned long}.
22015 @item int __builtin_popcountll (unsigned long long)
22016 Generates the @code{popcntq} machine instruction.
22019 The following built-in functions are available when @option{-mavx} is
22020 used. All of them generate the machine instruction that is part of the
22024 v4df __builtin_ia32_addpd256 (v4df,v4df)
22025 v8sf __builtin_ia32_addps256 (v8sf,v8sf)
22026 v4df __builtin_ia32_addsubpd256 (v4df,v4df)
22027 v8sf __builtin_ia32_addsubps256 (v8sf,v8sf)
22028 v4df __builtin_ia32_andnpd256 (v4df,v4df)
22029 v8sf __builtin_ia32_andnps256 (v8sf,v8sf)
22030 v4df __builtin_ia32_andpd256 (v4df,v4df)
22031 v8sf __builtin_ia32_andps256 (v8sf,v8sf)
22032 v4df __builtin_ia32_blendpd256 (v4df,v4df,int)
22033 v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int)
22034 v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df)
22035 v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf)
22036 v2df __builtin_ia32_cmppd (v2df,v2df,int)
22037 v4df __builtin_ia32_cmppd256 (v4df,v4df,int)
22038 v4sf __builtin_ia32_cmpps (v4sf,v4sf,int)
22039 v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int)
22040 v2df __builtin_ia32_cmpsd (v2df,v2df,int)
22041 v4sf __builtin_ia32_cmpss (v4sf,v4sf,int)
22042 v4df __builtin_ia32_cvtdq2pd256 (v4si)
22043 v8sf __builtin_ia32_cvtdq2ps256 (v8si)
22044 v4si __builtin_ia32_cvtpd2dq256 (v4df)
22045 v4sf __builtin_ia32_cvtpd2ps256 (v4df)
22046 v8si __builtin_ia32_cvtps2dq256 (v8sf)
22047 v4df __builtin_ia32_cvtps2pd256 (v4sf)
22048 v4si __builtin_ia32_cvttpd2dq256 (v4df)
22049 v8si __builtin_ia32_cvttps2dq256 (v8sf)
22050 v4df __builtin_ia32_divpd256 (v4df,v4df)
22051 v8sf __builtin_ia32_divps256 (v8sf,v8sf)
22052 v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int)
22053 v4df __builtin_ia32_haddpd256 (v4df,v4df)
22054 v8sf __builtin_ia32_haddps256 (v8sf,v8sf)
22055 v4df __builtin_ia32_hsubpd256 (v4df,v4df)
22056 v8sf __builtin_ia32_hsubps256 (v8sf,v8sf)
22057 v32qi __builtin_ia32_lddqu256 (pcchar)
22058 v32qi __builtin_ia32_loaddqu256 (pcchar)
22059 v4df __builtin_ia32_loadupd256 (pcdouble)
22060 v8sf __builtin_ia32_loadups256 (pcfloat)
22061 v2df __builtin_ia32_maskloadpd (pcv2df,v2df)
22062 v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df)
22063 v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf)
22064 v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf)
22065 void __builtin_ia32_maskstorepd (pv2df,v2df,v2df)
22066 void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df)
22067 void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf)
22068 void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf)
22069 v4df __builtin_ia32_maxpd256 (v4df,v4df)
22070 v8sf __builtin_ia32_maxps256 (v8sf,v8sf)
22071 v4df __builtin_ia32_minpd256 (v4df,v4df)
22072 v8sf __builtin_ia32_minps256 (v8sf,v8sf)
22073 v4df __builtin_ia32_movddup256 (v4df)
22074 int __builtin_ia32_movmskpd256 (v4df)
22075 int __builtin_ia32_movmskps256 (v8sf)
22076 v8sf __builtin_ia32_movshdup256 (v8sf)
22077 v8sf __builtin_ia32_movsldup256 (v8sf)
22078 v4df __builtin_ia32_mulpd256 (v4df,v4df)
22079 v8sf __builtin_ia32_mulps256 (v8sf,v8sf)
22080 v4df __builtin_ia32_orpd256 (v4df,v4df)
22081 v8sf __builtin_ia32_orps256 (v8sf,v8sf)
22082 v2df __builtin_ia32_pd_pd256 (v4df)
22083 v4df __builtin_ia32_pd256_pd (v2df)
22084 v4sf __builtin_ia32_ps_ps256 (v8sf)
22085 v8sf __builtin_ia32_ps256_ps (v4sf)
22086 int __builtin_ia32_ptestc256 (v4di,v4di,ptest)
22087 int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest)
22088 int __builtin_ia32_ptestz256 (v4di,v4di,ptest)
22089 v8sf __builtin_ia32_rcpps256 (v8sf)
22090 v4df __builtin_ia32_roundpd256 (v4df,int)
22091 v8sf __builtin_ia32_roundps256 (v8sf,int)
22092 v8sf __builtin_ia32_rsqrtps_nr256 (v8sf)
22093 v8sf __builtin_ia32_rsqrtps256 (v8sf)
22094 v4df __builtin_ia32_shufpd256 (v4df,v4df,int)
22095 v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int)
22096 v4si __builtin_ia32_si_si256 (v8si)
22097 v8si __builtin_ia32_si256_si (v4si)
22098 v4df __builtin_ia32_sqrtpd256 (v4df)
22099 v8sf __builtin_ia32_sqrtps_nr256 (v8sf)
22100 v8sf __builtin_ia32_sqrtps256 (v8sf)
22101 void __builtin_ia32_storedqu256 (pchar,v32qi)
22102 void __builtin_ia32_storeupd256 (pdouble,v4df)
22103 void __builtin_ia32_storeups256 (pfloat,v8sf)
22104 v4df __builtin_ia32_subpd256 (v4df,v4df)
22105 v8sf __builtin_ia32_subps256 (v8sf,v8sf)
22106 v4df __builtin_ia32_unpckhpd256 (v4df,v4df)
22107 v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf)
22108 v4df __builtin_ia32_unpcklpd256 (v4df,v4df)
22109 v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf)
22110 v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df)
22111 v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf)
22112 v4df __builtin_ia32_vbroadcastsd256 (pcdouble)
22113 v4sf __builtin_ia32_vbroadcastss (pcfloat)
22114 v8sf __builtin_ia32_vbroadcastss256 (pcfloat)
22115 v2df __builtin_ia32_vextractf128_pd256 (v4df,int)
22116 v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int)
22117 v4si __builtin_ia32_vextractf128_si256 (v8si,int)
22118 v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int)
22119 v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int)
22120 v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int)
22121 v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int)
22122 v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int)
22123 v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int)
22124 v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int)
22125 v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int)
22126 v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int)
22127 v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int)
22128 v2df __builtin_ia32_vpermilpd (v2df,int)
22129 v4df __builtin_ia32_vpermilpd256 (v4df,int)
22130 v4sf __builtin_ia32_vpermilps (v4sf,int)
22131 v8sf __builtin_ia32_vpermilps256 (v8sf,int)
22132 v2df __builtin_ia32_vpermilvarpd (v2df,v2di)
22133 v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di)
22134 v4sf __builtin_ia32_vpermilvarps (v4sf,v4si)
22135 v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si)
22136 int __builtin_ia32_vtestcpd (v2df,v2df,ptest)
22137 int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest)
22138 int __builtin_ia32_vtestcps (v4sf,v4sf,ptest)
22139 int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest)
22140 int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest)
22141 int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest)
22142 int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest)
22143 int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest)
22144 int __builtin_ia32_vtestzpd (v2df,v2df,ptest)
22145 int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest)
22146 int __builtin_ia32_vtestzps (v4sf,v4sf,ptest)
22147 int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest)
22148 void __builtin_ia32_vzeroall (void)
22149 void __builtin_ia32_vzeroupper (void)
22150 v4df __builtin_ia32_xorpd256 (v4df,v4df)
22151 v8sf __builtin_ia32_xorps256 (v8sf,v8sf)
22154 The following built-in functions are available when @option{-mavx2} is
22155 used. All of them generate the machine instruction that is part of the
22159 v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int)
22160 v32qi __builtin_ia32_pabsb256 (v32qi)
22161 v16hi __builtin_ia32_pabsw256 (v16hi)
22162 v8si __builtin_ia32_pabsd256 (v8si)
22163 v16hi __builtin_ia32_packssdw256 (v8si,v8si)
22164 v32qi __builtin_ia32_packsswb256 (v16hi,v16hi)
22165 v16hi __builtin_ia32_packusdw256 (v8si,v8si)
22166 v32qi __builtin_ia32_packuswb256 (v16hi,v16hi)
22167 v32qi __builtin_ia32_paddb256 (v32qi,v32qi)
22168 v16hi __builtin_ia32_paddw256 (v16hi,v16hi)
22169 v8si __builtin_ia32_paddd256 (v8si,v8si)
22170 v4di __builtin_ia32_paddq256 (v4di,v4di)
22171 v32qi __builtin_ia32_paddsb256 (v32qi,v32qi)
22172 v16hi __builtin_ia32_paddsw256 (v16hi,v16hi)
22173 v32qi __builtin_ia32_paddusb256 (v32qi,v32qi)
22174 v16hi __builtin_ia32_paddusw256 (v16hi,v16hi)
22175 v4di __builtin_ia32_palignr256 (v4di,v4di,int)
22176 v4di __builtin_ia32_andsi256 (v4di,v4di)
22177 v4di __builtin_ia32_andnotsi256 (v4di,v4di)
22178 v32qi __builtin_ia32_pavgb256 (v32qi,v32qi)
22179 v16hi __builtin_ia32_pavgw256 (v16hi,v16hi)
22180 v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi)
22181 v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int)
22182 v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi)
22183 v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi)
22184 v8si __builtin_ia32_pcmpeqd256 (c8si,v8si)
22185 v4di __builtin_ia32_pcmpeqq256 (v4di,v4di)
22186 v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi)
22187 v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi)
22188 v8si __builtin_ia32_pcmpgtd256 (v8si,v8si)
22189 v4di __builtin_ia32_pcmpgtq256 (v4di,v4di)
22190 v16hi __builtin_ia32_phaddw256 (v16hi,v16hi)
22191 v8si __builtin_ia32_phaddd256 (v8si,v8si)
22192 v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi)
22193 v16hi __builtin_ia32_phsubw256 (v16hi,v16hi)
22194 v8si __builtin_ia32_phsubd256 (v8si,v8si)
22195 v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi)
22196 v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi)
22197 v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi)
22198 v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi)
22199 v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi)
22200 v8si __builtin_ia32_pmaxsd256 (v8si,v8si)
22201 v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi)
22202 v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi)
22203 v8si __builtin_ia32_pmaxud256 (v8si,v8si)
22204 v32qi __builtin_ia32_pminsb256 (v32qi,v32qi)
22205 v16hi __builtin_ia32_pminsw256 (v16hi,v16hi)
22206 v8si __builtin_ia32_pminsd256 (v8si,v8si)
22207 v32qi __builtin_ia32_pminub256 (v32qi,v32qi)
22208 v16hi __builtin_ia32_pminuw256 (v16hi,v16hi)
22209 v8si __builtin_ia32_pminud256 (v8si,v8si)
22210 int __builtin_ia32_pmovmskb256 (v32qi)
22211 v16hi __builtin_ia32_pmovsxbw256 (v16qi)
22212 v8si __builtin_ia32_pmovsxbd256 (v16qi)
22213 v4di __builtin_ia32_pmovsxbq256 (v16qi)
22214 v8si __builtin_ia32_pmovsxwd256 (v8hi)
22215 v4di __builtin_ia32_pmovsxwq256 (v8hi)
22216 v4di __builtin_ia32_pmovsxdq256 (v4si)
22217 v16hi __builtin_ia32_pmovzxbw256 (v16qi)
22218 v8si __builtin_ia32_pmovzxbd256 (v16qi)
22219 v4di __builtin_ia32_pmovzxbq256 (v16qi)
22220 v8si __builtin_ia32_pmovzxwd256 (v8hi)
22221 v4di __builtin_ia32_pmovzxwq256 (v8hi)
22222 v4di __builtin_ia32_pmovzxdq256 (v4si)
22223 v4di __builtin_ia32_pmuldq256 (v8si,v8si)
22224 v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi)
22225 v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi)
22226 v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi)
22227 v16hi __builtin_ia32_pmullw256 (v16hi,v16hi)
22228 v8si __builtin_ia32_pmulld256 (v8si,v8si)
22229 v4di __builtin_ia32_pmuludq256 (v8si,v8si)
22230 v4di __builtin_ia32_por256 (v4di,v4di)
22231 v16hi __builtin_ia32_psadbw256 (v32qi,v32qi)
22232 v32qi __builtin_ia32_pshufb256 (v32qi,v32qi)
22233 v8si __builtin_ia32_pshufd256 (v8si,int)
22234 v16hi __builtin_ia32_pshufhw256 (v16hi,int)
22235 v16hi __builtin_ia32_pshuflw256 (v16hi,int)
22236 v32qi __builtin_ia32_psignb256 (v32qi,v32qi)
22237 v16hi __builtin_ia32_psignw256 (v16hi,v16hi)
22238 v8si __builtin_ia32_psignd256 (v8si,v8si)
22239 v4di __builtin_ia32_pslldqi256 (v4di,int)
22240 v16hi __builtin_ia32_psllwi256 (16hi,int)
22241 v16hi __builtin_ia32_psllw256(v16hi,v8hi)
22242 v8si __builtin_ia32_pslldi256 (v8si,int)
22243 v8si __builtin_ia32_pslld256(v8si,v4si)
22244 v4di __builtin_ia32_psllqi256 (v4di,int)
22245 v4di __builtin_ia32_psllq256(v4di,v2di)
22246 v16hi __builtin_ia32_psrawi256 (v16hi,int)
22247 v16hi __builtin_ia32_psraw256 (v16hi,v8hi)
22248 v8si __builtin_ia32_psradi256 (v8si,int)
22249 v8si __builtin_ia32_psrad256 (v8si,v4si)
22250 v4di __builtin_ia32_psrldqi256 (v4di, int)
22251 v16hi __builtin_ia32_psrlwi256 (v16hi,int)
22252 v16hi __builtin_ia32_psrlw256 (v16hi,v8hi)
22253 v8si __builtin_ia32_psrldi256 (v8si,int)
22254 v8si __builtin_ia32_psrld256 (v8si,v4si)
22255 v4di __builtin_ia32_psrlqi256 (v4di,int)
22256 v4di __builtin_ia32_psrlq256(v4di,v2di)
22257 v32qi __builtin_ia32_psubb256 (v32qi,v32qi)
22258 v32hi __builtin_ia32_psubw256 (v16hi,v16hi)
22259 v8si __builtin_ia32_psubd256 (v8si,v8si)
22260 v4di __builtin_ia32_psubq256 (v4di,v4di)
22261 v32qi __builtin_ia32_psubsb256 (v32qi,v32qi)
22262 v16hi __builtin_ia32_psubsw256 (v16hi,v16hi)
22263 v32qi __builtin_ia32_psubusb256 (v32qi,v32qi)
22264 v16hi __builtin_ia32_psubusw256 (v16hi,v16hi)
22265 v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi)
22266 v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi)
22267 v8si __builtin_ia32_punpckhdq256 (v8si,v8si)
22268 v4di __builtin_ia32_punpckhqdq256 (v4di,v4di)
22269 v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi)
22270 v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi)
22271 v8si __builtin_ia32_punpckldq256 (v8si,v8si)
22272 v4di __builtin_ia32_punpcklqdq256 (v4di,v4di)
22273 v4di __builtin_ia32_pxor256 (v4di,v4di)
22274 v4di __builtin_ia32_movntdqa256 (pv4di)
22275 v4sf __builtin_ia32_vbroadcastss_ps (v4sf)
22276 v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf)
22277 v4df __builtin_ia32_vbroadcastsd_pd256 (v2df)
22278 v4di __builtin_ia32_vbroadcastsi256 (v2di)
22279 v4si __builtin_ia32_pblendd128 (v4si,v4si)
22280 v8si __builtin_ia32_pblendd256 (v8si,v8si)
22281 v32qi __builtin_ia32_pbroadcastb256 (v16qi)
22282 v16hi __builtin_ia32_pbroadcastw256 (v8hi)
22283 v8si __builtin_ia32_pbroadcastd256 (v4si)
22284 v4di __builtin_ia32_pbroadcastq256 (v2di)
22285 v16qi __builtin_ia32_pbroadcastb128 (v16qi)
22286 v8hi __builtin_ia32_pbroadcastw128 (v8hi)
22287 v4si __builtin_ia32_pbroadcastd128 (v4si)
22288 v2di __builtin_ia32_pbroadcastq128 (v2di)
22289 v8si __builtin_ia32_permvarsi256 (v8si,v8si)
22290 v4df __builtin_ia32_permdf256 (v4df,int)
22291 v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf)
22292 v4di __builtin_ia32_permdi256 (v4di,int)
22293 v4di __builtin_ia32_permti256 (v4di,v4di,int)
22294 v4di __builtin_ia32_extract128i256 (v4di,int)
22295 v4di __builtin_ia32_insert128i256 (v4di,v2di,int)
22296 v8si __builtin_ia32_maskloadd256 (pcv8si,v8si)
22297 v4di __builtin_ia32_maskloadq256 (pcv4di,v4di)
22298 v4si __builtin_ia32_maskloadd (pcv4si,v4si)
22299 v2di __builtin_ia32_maskloadq (pcv2di,v2di)
22300 void __builtin_ia32_maskstored256 (pv8si,v8si,v8si)
22301 void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di)
22302 void __builtin_ia32_maskstored (pv4si,v4si,v4si)
22303 void __builtin_ia32_maskstoreq (pv2di,v2di,v2di)
22304 v8si __builtin_ia32_psllv8si (v8si,v8si)
22305 v4si __builtin_ia32_psllv4si (v4si,v4si)
22306 v4di __builtin_ia32_psllv4di (v4di,v4di)
22307 v2di __builtin_ia32_psllv2di (v2di,v2di)
22308 v8si __builtin_ia32_psrav8si (v8si,v8si)
22309 v4si __builtin_ia32_psrav4si (v4si,v4si)
22310 v8si __builtin_ia32_psrlv8si (v8si,v8si)
22311 v4si __builtin_ia32_psrlv4si (v4si,v4si)
22312 v4di __builtin_ia32_psrlv4di (v4di,v4di)
22313 v2di __builtin_ia32_psrlv2di (v2di,v2di)
22314 v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int)
22315 v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int)
22316 v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int)
22317 v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int)
22318 v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int)
22319 v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int)
22320 v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int)
22321 v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int)
22322 v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int)
22323 v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int)
22324 v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int)
22325 v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int)
22326 v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int)
22327 v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int)
22328 v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int)
22329 v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int)
22332 The following built-in functions are available when @option{-maes} is
22333 used. All of them generate the machine instruction that is part of the
22337 v2di __builtin_ia32_aesenc128 (v2di, v2di)
22338 v2di __builtin_ia32_aesenclast128 (v2di, v2di)
22339 v2di __builtin_ia32_aesdec128 (v2di, v2di)
22340 v2di __builtin_ia32_aesdeclast128 (v2di, v2di)
22341 v2di __builtin_ia32_aeskeygenassist128 (v2di, const int)
22342 v2di __builtin_ia32_aesimc128 (v2di)
22345 The following built-in function is available when @option{-mpclmul} is
22349 @item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)
22350 Generates the @code{pclmulqdq} machine instruction.
22353 The following built-in function is available when @option{-mfsgsbase} is
22354 used. All of them generate the machine instruction that is part of the
22358 unsigned int __builtin_ia32_rdfsbase32 (void)
22359 unsigned long long __builtin_ia32_rdfsbase64 (void)
22360 unsigned int __builtin_ia32_rdgsbase32 (void)
22361 unsigned long long __builtin_ia32_rdgsbase64 (void)
22362 void _writefsbase_u32 (unsigned int)
22363 void _writefsbase_u64 (unsigned long long)
22364 void _writegsbase_u32 (unsigned int)
22365 void _writegsbase_u64 (unsigned long long)
22368 The following built-in function is available when @option{-mrdrnd} is
22369 used. All of them generate the machine instruction that is part of the
22373 unsigned int __builtin_ia32_rdrand16_step (unsigned short *)
22374 unsigned int __builtin_ia32_rdrand32_step (unsigned int *)
22375 unsigned int __builtin_ia32_rdrand64_step (unsigned long long *)
22378 The following built-in function is available when @option{-mptwrite} is
22379 used. All of them generate the machine instruction that is part of the
22383 void __builtin_ia32_ptwrite32 (unsigned)
22384 void __builtin_ia32_ptwrite64 (unsigned long long)
22387 The following built-in functions are available when @option{-msse4a} is used.
22388 All of them generate the machine instruction that is part of the name.
22391 void __builtin_ia32_movntsd (double *, v2df)
22392 void __builtin_ia32_movntss (float *, v4sf)
22393 v2di __builtin_ia32_extrq (v2di, v16qi)
22394 v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int)
22395 v2di __builtin_ia32_insertq (v2di, v2di)
22396 v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int)
22399 The following built-in functions are available when @option{-mxop} is used.
22401 v2df __builtin_ia32_vfrczpd (v2df)
22402 v4sf __builtin_ia32_vfrczps (v4sf)
22403 v2df __builtin_ia32_vfrczsd (v2df)
22404 v4sf __builtin_ia32_vfrczss (v4sf)
22405 v4df __builtin_ia32_vfrczpd256 (v4df)
22406 v8sf __builtin_ia32_vfrczps256 (v8sf)
22407 v2di __builtin_ia32_vpcmov (v2di, v2di, v2di)
22408 v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di)
22409 v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si)
22410 v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi)
22411 v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi)
22412 v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df)
22413 v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf)
22414 v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di)
22415 v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si)
22416 v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi)
22417 v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi)
22418 v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df)
22419 v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf)
22420 v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi)
22421 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
22422 v4si __builtin_ia32_vpcomeqd (v4si, v4si)
22423 v2di __builtin_ia32_vpcomeqq (v2di, v2di)
22424 v16qi __builtin_ia32_vpcomequb (v16qi, v16qi)
22425 v4si __builtin_ia32_vpcomequd (v4si, v4si)
22426 v2di __builtin_ia32_vpcomequq (v2di, v2di)
22427 v8hi __builtin_ia32_vpcomequw (v8hi, v8hi)
22428 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
22429 v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi)
22430 v4si __builtin_ia32_vpcomfalsed (v4si, v4si)
22431 v2di __builtin_ia32_vpcomfalseq (v2di, v2di)
22432 v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi)
22433 v4si __builtin_ia32_vpcomfalseud (v4si, v4si)
22434 v2di __builtin_ia32_vpcomfalseuq (v2di, v2di)
22435 v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi)
22436 v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi)
22437 v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi)
22438 v4si __builtin_ia32_vpcomged (v4si, v4si)
22439 v2di __builtin_ia32_vpcomgeq (v2di, v2di)
22440 v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi)
22441 v4si __builtin_ia32_vpcomgeud (v4si, v4si)
22442 v2di __builtin_ia32_vpcomgeuq (v2di, v2di)
22443 v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi)
22444 v8hi __builtin_ia32_vpcomgew (v8hi, v8hi)
22445 v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi)
22446 v4si __builtin_ia32_vpcomgtd (v4si, v4si)
22447 v2di __builtin_ia32_vpcomgtq (v2di, v2di)
22448 v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi)
22449 v4si __builtin_ia32_vpcomgtud (v4si, v4si)
22450 v2di __builtin_ia32_vpcomgtuq (v2di, v2di)
22451 v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi)
22452 v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi)
22453 v16qi __builtin_ia32_vpcomleb (v16qi, v16qi)
22454 v4si __builtin_ia32_vpcomled (v4si, v4si)
22455 v2di __builtin_ia32_vpcomleq (v2di, v2di)
22456 v16qi __builtin_ia32_vpcomleub (v16qi, v16qi)
22457 v4si __builtin_ia32_vpcomleud (v4si, v4si)
22458 v2di __builtin_ia32_vpcomleuq (v2di, v2di)
22459 v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi)
22460 v8hi __builtin_ia32_vpcomlew (v8hi, v8hi)
22461 v16qi __builtin_ia32_vpcomltb (v16qi, v16qi)
22462 v4si __builtin_ia32_vpcomltd (v4si, v4si)
22463 v2di __builtin_ia32_vpcomltq (v2di, v2di)
22464 v16qi __builtin_ia32_vpcomltub (v16qi, v16qi)
22465 v4si __builtin_ia32_vpcomltud (v4si, v4si)
22466 v2di __builtin_ia32_vpcomltuq (v2di, v2di)
22467 v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi)
22468 v8hi __builtin_ia32_vpcomltw (v8hi, v8hi)
22469 v16qi __builtin_ia32_vpcomneb (v16qi, v16qi)
22470 v4si __builtin_ia32_vpcomned (v4si, v4si)
22471 v2di __builtin_ia32_vpcomneq (v2di, v2di)
22472 v16qi __builtin_ia32_vpcomneub (v16qi, v16qi)
22473 v4si __builtin_ia32_vpcomneud (v4si, v4si)
22474 v2di __builtin_ia32_vpcomneuq (v2di, v2di)
22475 v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi)
22476 v8hi __builtin_ia32_vpcomnew (v8hi, v8hi)
22477 v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi)
22478 v4si __builtin_ia32_vpcomtrued (v4si, v4si)
22479 v2di __builtin_ia32_vpcomtrueq (v2di, v2di)
22480 v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi)
22481 v4si __builtin_ia32_vpcomtrueud (v4si, v4si)
22482 v2di __builtin_ia32_vpcomtrueuq (v2di, v2di)
22483 v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi)
22484 v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi)
22485 v4si __builtin_ia32_vphaddbd (v16qi)
22486 v2di __builtin_ia32_vphaddbq (v16qi)
22487 v8hi __builtin_ia32_vphaddbw (v16qi)
22488 v2di __builtin_ia32_vphadddq (v4si)
22489 v4si __builtin_ia32_vphaddubd (v16qi)
22490 v2di __builtin_ia32_vphaddubq (v16qi)
22491 v8hi __builtin_ia32_vphaddubw (v16qi)
22492 v2di __builtin_ia32_vphaddudq (v4si)
22493 v4si __builtin_ia32_vphadduwd (v8hi)
22494 v2di __builtin_ia32_vphadduwq (v8hi)
22495 v4si __builtin_ia32_vphaddwd (v8hi)
22496 v2di __builtin_ia32_vphaddwq (v8hi)
22497 v8hi __builtin_ia32_vphsubbw (v16qi)
22498 v2di __builtin_ia32_vphsubdq (v4si)
22499 v4si __builtin_ia32_vphsubwd (v8hi)
22500 v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si)
22501 v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di)
22502 v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di)
22503 v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si)
22504 v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di)
22505 v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di)
22506 v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si)
22507 v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi)
22508 v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si)
22509 v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi)
22510 v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si)
22511 v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si)
22512 v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi)
22513 v16qi __builtin_ia32_vprotb (v16qi, v16qi)
22514 v4si __builtin_ia32_vprotd (v4si, v4si)
22515 v2di __builtin_ia32_vprotq (v2di, v2di)
22516 v8hi __builtin_ia32_vprotw (v8hi, v8hi)
22517 v16qi __builtin_ia32_vpshab (v16qi, v16qi)
22518 v4si __builtin_ia32_vpshad (v4si, v4si)
22519 v2di __builtin_ia32_vpshaq (v2di, v2di)
22520 v8hi __builtin_ia32_vpshaw (v8hi, v8hi)
22521 v16qi __builtin_ia32_vpshlb (v16qi, v16qi)
22522 v4si __builtin_ia32_vpshld (v4si, v4si)
22523 v2di __builtin_ia32_vpshlq (v2di, v2di)
22524 v8hi __builtin_ia32_vpshlw (v8hi, v8hi)
22527 The following built-in functions are available when @option{-mfma4} is used.
22528 All of them generate the machine instruction that is part of the name.
22531 v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df)
22532 v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf)
22533 v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df)
22534 v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf)
22535 v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df)
22536 v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf)
22537 v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df)
22538 v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf)
22539 v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df)
22540 v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf)
22541 v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df)
22542 v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf)
22543 v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df)
22544 v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf)
22545 v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df)
22546 v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf)
22547 v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df)
22548 v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf)
22549 v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df)
22550 v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf)
22551 v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df)
22552 v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf)
22553 v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df)
22554 v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf)
22555 v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df)
22556 v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf)
22557 v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df)
22558 v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf)
22559 v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df)
22560 v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf)
22561 v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df)
22562 v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf)
22566 The following built-in functions are available when @option{-mlwp} is used.
22569 void __builtin_ia32_llwpcb16 (void *);
22570 void __builtin_ia32_llwpcb32 (void *);
22571 void __builtin_ia32_llwpcb64 (void *);
22572 void * __builtin_ia32_llwpcb16 (void);
22573 void * __builtin_ia32_llwpcb32 (void);
22574 void * __builtin_ia32_llwpcb64 (void);
22575 void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short)
22576 void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int)
22577 void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int)
22578 unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short)
22579 unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int)
22580 unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int)
22583 The following built-in functions are available when @option{-mbmi} is used.
22584 All of them generate the machine instruction that is part of the name.
22586 unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int);
22587 unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long);
22590 The following built-in functions are available when @option{-mbmi2} is used.
22591 All of them generate the machine instruction that is part of the name.
22593 unsigned int _bzhi_u32 (unsigned int, unsigned int)
22594 unsigned int _pdep_u32 (unsigned int, unsigned int)
22595 unsigned int _pext_u32 (unsigned int, unsigned int)
22596 unsigned long long _bzhi_u64 (unsigned long long, unsigned long long)
22597 unsigned long long _pdep_u64 (unsigned long long, unsigned long long)
22598 unsigned long long _pext_u64 (unsigned long long, unsigned long long)
22601 The following built-in functions are available when @option{-mlzcnt} is used.
22602 All of them generate the machine instruction that is part of the name.
22604 unsigned short __builtin_ia32_lzcnt_u16(unsigned short);
22605 unsigned int __builtin_ia32_lzcnt_u32(unsigned int);
22606 unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long);
22609 The following built-in functions are available when @option{-mfxsr} is used.
22610 All of them generate the machine instruction that is part of the name.
22612 void __builtin_ia32_fxsave (void *)
22613 void __builtin_ia32_fxrstor (void *)
22614 void __builtin_ia32_fxsave64 (void *)
22615 void __builtin_ia32_fxrstor64 (void *)
22618 The following built-in functions are available when @option{-mxsave} is used.
22619 All of them generate the machine instruction that is part of the name.
22621 void __builtin_ia32_xsave (void *, long long)
22622 void __builtin_ia32_xrstor (void *, long long)
22623 void __builtin_ia32_xsave64 (void *, long long)
22624 void __builtin_ia32_xrstor64 (void *, long long)
22627 The following built-in functions are available when @option{-mxsaveopt} is used.
22628 All of them generate the machine instruction that is part of the name.
22630 void __builtin_ia32_xsaveopt (void *, long long)
22631 void __builtin_ia32_xsaveopt64 (void *, long long)
22634 The following built-in functions are available when @option{-mtbm} is used.
22635 Both of them generate the immediate form of the bextr machine instruction.
22637 unsigned int __builtin_ia32_bextri_u32 (unsigned int,
22638 const unsigned int);
22639 unsigned long long __builtin_ia32_bextri_u64 (unsigned long long,
22640 const unsigned long long);
22644 The following built-in functions are available when @option{-m3dnow} is used.
22645 All of them generate the machine instruction that is part of the name.
22648 void __builtin_ia32_femms (void)
22649 v8qi __builtin_ia32_pavgusb (v8qi, v8qi)
22650 v2si __builtin_ia32_pf2id (v2sf)
22651 v2sf __builtin_ia32_pfacc (v2sf, v2sf)
22652 v2sf __builtin_ia32_pfadd (v2sf, v2sf)
22653 v2si __builtin_ia32_pfcmpeq (v2sf, v2sf)
22654 v2si __builtin_ia32_pfcmpge (v2sf, v2sf)
22655 v2si __builtin_ia32_pfcmpgt (v2sf, v2sf)
22656 v2sf __builtin_ia32_pfmax (v2sf, v2sf)
22657 v2sf __builtin_ia32_pfmin (v2sf, v2sf)
22658 v2sf __builtin_ia32_pfmul (v2sf, v2sf)
22659 v2sf __builtin_ia32_pfrcp (v2sf)
22660 v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf)
22661 v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf)
22662 v2sf __builtin_ia32_pfrsqrt (v2sf)
22663 v2sf __builtin_ia32_pfsub (v2sf, v2sf)
22664 v2sf __builtin_ia32_pfsubr (v2sf, v2sf)
22665 v2sf __builtin_ia32_pi2fd (v2si)
22666 v4hi __builtin_ia32_pmulhrw (v4hi, v4hi)
22669 The following built-in functions are available when @option{-m3dnowa} is used.
22670 All of them generate the machine instruction that is part of the name.
22673 v2si __builtin_ia32_pf2iw (v2sf)
22674 v2sf __builtin_ia32_pfnacc (v2sf, v2sf)
22675 v2sf __builtin_ia32_pfpnacc (v2sf, v2sf)
22676 v2sf __builtin_ia32_pi2fw (v2si)
22677 v2sf __builtin_ia32_pswapdsf (v2sf)
22678 v2si __builtin_ia32_pswapdsi (v2si)
22681 The following built-in functions are available when @option{-mrtm} is used
22682 They are used for restricted transactional memory. These are the internal
22683 low level functions. Normally the functions in
22684 @ref{x86 transactional memory intrinsics} should be used instead.
22687 int __builtin_ia32_xbegin ()
22688 void __builtin_ia32_xend ()
22689 void __builtin_ia32_xabort (status)
22690 int __builtin_ia32_xtest ()
22693 The following built-in functions are available when @option{-mmwaitx} is used.
22694 All of them generate the machine instruction that is part of the name.
22696 void __builtin_ia32_monitorx (void *, unsigned int, unsigned int)
22697 void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int)
22700 The following built-in functions are available when @option{-mclzero} is used.
22701 All of them generate the machine instruction that is part of the name.
22703 void __builtin_i32_clzero (void *)
22706 The following built-in functions are available when @option{-mpku} is used.
22707 They generate reads and writes to PKRU.
22709 void __builtin_ia32_wrpkru (unsigned int)
22710 unsigned int __builtin_ia32_rdpkru ()
22713 The following built-in functions are available when @option{-mcet} or
22714 @option{-mshstk} option is used. They support shadow stack
22715 machine instructions from Intel Control-flow Enforcement Technology (CET).
22716 Each built-in function generates the machine instruction that is part
22717 of the function's name. These are the internal low-level functions.
22718 Normally the functions in @ref{x86 control-flow protection intrinsics}
22719 should be used instead.
22722 unsigned int __builtin_ia32_rdsspd (void)
22723 unsigned long long __builtin_ia32_rdsspq (void)
22724 void __builtin_ia32_incsspd (unsigned int)
22725 void __builtin_ia32_incsspq (unsigned long long)
22726 void __builtin_ia32_saveprevssp(void);
22727 void __builtin_ia32_rstorssp(void *);
22728 void __builtin_ia32_wrssd(unsigned int, void *);
22729 void __builtin_ia32_wrssq(unsigned long long, void *);
22730 void __builtin_ia32_wrussd(unsigned int, void *);
22731 void __builtin_ia32_wrussq(unsigned long long, void *);
22732 void __builtin_ia32_setssbsy(void);
22733 void __builtin_ia32_clrssbsy(void *);
22736 @node x86 transactional memory intrinsics
22737 @subsection x86 Transactional Memory Intrinsics
22739 These hardware transactional memory intrinsics for x86 allow you to use
22740 memory transactions with RTM (Restricted Transactional Memory).
22741 This support is enabled with the @option{-mrtm} option.
22742 For using HLE (Hardware Lock Elision) see
22743 @ref{x86 specific memory model extensions for transactional memory} instead.
22745 A memory transaction commits all changes to memory in an atomic way,
22746 as visible to other threads. If the transaction fails it is rolled back
22747 and all side effects discarded.
22749 Generally there is no guarantee that a memory transaction ever succeeds
22750 and suitable fallback code always needs to be supplied.
22752 @deftypefn {RTM Function} {unsigned} _xbegin ()
22753 Start a RTM (Restricted Transactional Memory) transaction.
22754 Returns @code{_XBEGIN_STARTED} when the transaction
22755 started successfully (note this is not 0, so the constant has to be
22756 explicitly tested).
22758 If the transaction aborts, all side effects
22759 are undone and an abort code encoded as a bit mask is returned.
22760 The following macros are defined:
22763 @item _XABORT_EXPLICIT
22764 Transaction was explicitly aborted with @code{_xabort}. The parameter passed
22765 to @code{_xabort} is available with @code{_XABORT_CODE(status)}.
22766 @item _XABORT_RETRY
22767 Transaction retry is possible.
22768 @item _XABORT_CONFLICT
22769 Transaction abort due to a memory conflict with another thread.
22770 @item _XABORT_CAPACITY
22771 Transaction abort due to the transaction using too much memory.
22772 @item _XABORT_DEBUG
22773 Transaction abort due to a debug trap.
22774 @item _XABORT_NESTED
22775 Transaction abort in an inner nested transaction.
22778 There is no guarantee
22779 any transaction ever succeeds, so there always needs to be a valid
22783 @deftypefn {RTM Function} {void} _xend ()
22784 Commit the current transaction. When no transaction is active this faults.
22785 All memory side effects of the transaction become visible
22786 to other threads in an atomic manner.
22789 @deftypefn {RTM Function} {int} _xtest ()
22790 Return a nonzero value if a transaction is currently active, otherwise 0.
22793 @deftypefn {RTM Function} {void} _xabort (status)
22794 Abort the current transaction. When no transaction is active this is a no-op.
22795 The @var{status} is an 8-bit constant; its value is encoded in the return
22796 value from @code{_xbegin}.
22799 Here is an example showing handling for @code{_XABORT_RETRY}
22800 and a fallback path for other failures:
22803 #include <immintrin.h>
22805 int n_tries, max_tries;
22806 unsigned status = _XABORT_EXPLICIT;
22809 for (n_tries = 0; n_tries < max_tries; n_tries++)
22811 status = _xbegin ();
22812 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY))
22815 if (status == _XBEGIN_STARTED)
22817 ... transaction code...
22822 ... non-transactional fallback path...
22827 Note that, in most cases, the transactional and non-transactional code
22828 must synchronize together to ensure consistency.
22830 @node x86 control-flow protection intrinsics
22831 @subsection x86 Control-Flow Protection Intrinsics
22833 @deftypefn {CET Function} {ret_type} _get_ssp (void)
22834 Get the current value of shadow stack pointer if shadow stack support
22835 from Intel CET is enabled in the hardware or @code{0} otherwise.
22836 The @code{ret_type} is @code{unsigned long long} for 64-bit targets
22837 and @code{unsigned int} for 32-bit targets.
22840 @deftypefn {CET Function} void _inc_ssp (unsigned int)
22841 Increment the current shadow stack pointer by the size specified by the
22842 function argument. The argument is masked to a byte value for security
22843 reasons, so to increment by more than 255 bytes you must call the function
22847 The shadow stack unwind code looks like:
22850 #include <immintrin.h>
22852 /* Unwind the shadow stack for EH. */
22853 #define _Unwind_Frames_Extra(x) \
22856 _Unwind_Word ssp = _get_ssp (); \
22859 _Unwind_Word tmp = (x); \
22860 while (tmp > 255) \
22872 This code runs unconditionally on all 64-bit processors. For 32-bit
22873 processors the code runs on those that support multi-byte NOP instructions.
22875 @node Target Format Checks
22876 @section Format Checks Specific to Particular Target Machines
22878 For some target machines, GCC supports additional options to the
22880 (@pxref{Function Attributes,,Declaring Attributes of Functions}).
22883 * Solaris Format Checks::
22884 * Darwin Format Checks::
22887 @node Solaris Format Checks
22888 @subsection Solaris Format Checks
22890 Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format
22891 check. @code{cmn_err} accepts a subset of the standard @code{printf}
22892 conversions, and the two-argument @code{%b} conversion for displaying
22893 bit-fields. See the Solaris man page for @code{cmn_err} for more information.
22895 @node Darwin Format Checks
22896 @subsection Darwin Format Checks
22898 In addition to the full set of format archetypes (attribute format style
22899 arguments such as @code{printf}, @code{scanf}, @code{strftime}, and
22900 @code{strfmon}), Darwin targets also support the @code{CFString} (or
22901 @code{__CFString__}) archetype in the @code{format} attribute.
22902 Declarations with this archetype are parsed for correct syntax
22903 and argument types. However, parsing of the format string itself and
22904 validating arguments against it in calls to such functions is currently
22907 Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may
22908 also be used as format arguments. Note that the relevant headers are only likely to be
22909 available on Darwin (OSX) installations. On such installations, the XCode and system
22910 documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and
22911 associated functions.
22914 @section Pragmas Accepted by GCC
22916 @cindex @code{#pragma}
22918 GCC supports several types of pragmas, primarily in order to compile
22919 code originally written for other compilers. Note that in general
22920 we do not recommend the use of pragmas; @xref{Function Attributes},
22921 for further explanation.
22923 The GNU C preprocessor recognizes several pragmas in addition to the
22924 compiler pragmas documented here. Refer to the CPP manual for more
22928 * AArch64 Pragmas::
22932 * RS/6000 and PowerPC Pragmas::
22935 * Solaris Pragmas::
22936 * Symbol-Renaming Pragmas::
22937 * Structure-Layout Pragmas::
22939 * Diagnostic Pragmas::
22940 * Visibility Pragmas::
22941 * Push/Pop Macro Pragmas::
22942 * Function Specific Option Pragmas::
22943 * Loop-Specific Pragmas::
22946 @node AArch64 Pragmas
22947 @subsection AArch64 Pragmas
22949 The pragmas defined by the AArch64 target correspond to the AArch64
22950 target function attributes. They can be specified as below:
22952 #pragma GCC target("string")
22955 where @code{@var{string}} can be any string accepted as an AArch64 target
22956 attribute. @xref{AArch64 Function Attributes}, for more details
22957 on the permissible values of @code{string}.
22960 @subsection ARM Pragmas
22962 The ARM target defines pragmas for controlling the default addition of
22963 @code{long_call} and @code{short_call} attributes to functions.
22964 @xref{Function Attributes}, for information about the effects of these
22969 @cindex pragma, long_calls
22970 Set all subsequent functions to have the @code{long_call} attribute.
22972 @item no_long_calls
22973 @cindex pragma, no_long_calls
22974 Set all subsequent functions to have the @code{short_call} attribute.
22976 @item long_calls_off
22977 @cindex pragma, long_calls_off
22978 Do not affect the @code{long_call} or @code{short_call} attributes of
22979 subsequent functions.
22983 @subsection M32C Pragmas
22986 @item GCC memregs @var{number}
22987 @cindex pragma, memregs
22988 Overrides the command-line option @code{-memregs=} for the current
22989 file. Use with care! This pragma must be before any function in the
22990 file, and mixing different memregs values in different objects may
22991 make them incompatible. This pragma is useful when a
22992 performance-critical function uses a memreg for temporary values,
22993 as it may allow you to reduce the number of memregs used.
22995 @item ADDRESS @var{name} @var{address}
22996 @cindex pragma, address
22997 For any declared symbols matching @var{name}, this does three things
22998 to that symbol: it forces the symbol to be located at the given
22999 address (a number), it forces the symbol to be volatile, and it
23000 changes the symbol's scope to be static. This pragma exists for
23001 compatibility with other compilers, but note that the common
23002 @code{1234H} numeric syntax is not supported (use @code{0x1234}
23006 #pragma ADDRESS port3 0x103
23013 @subsection MeP Pragmas
23017 @item custom io_volatile (on|off)
23018 @cindex pragma, custom io_volatile
23019 Overrides the command-line option @code{-mio-volatile} for the current
23020 file. Note that for compatibility with future GCC releases, this
23021 option should only be used once before any @code{io} variables in each
23024 @item GCC coprocessor available @var{registers}
23025 @cindex pragma, coprocessor available
23026 Specifies which coprocessor registers are available to the register
23027 allocator. @var{registers} may be a single register, register range
23028 separated by ellipses, or comma-separated list of those. Example:
23031 #pragma GCC coprocessor available $c0...$c10, $c28
23034 @item GCC coprocessor call_saved @var{registers}
23035 @cindex pragma, coprocessor call_saved
23036 Specifies which coprocessor registers are to be saved and restored by
23037 any function using them. @var{registers} may be a single register,
23038 register range separated by ellipses, or comma-separated list of
23042 #pragma GCC coprocessor call_saved $c4...$c6, $c31
23045 @item GCC coprocessor subclass '(A|B|C|D)' = @var{registers}
23046 @cindex pragma, coprocessor subclass
23047 Creates and defines a register class. These register classes can be
23048 used by inline @code{asm} constructs. @var{registers} may be a single
23049 register, register range separated by ellipses, or comma-separated
23050 list of those. Example:
23053 #pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6
23055 asm ("cpfoo %0" : "=B" (x));
23058 @item GCC disinterrupt @var{name} , @var{name} @dots{}
23059 @cindex pragma, disinterrupt
23060 For the named functions, the compiler adds code to disable interrupts
23061 for the duration of those functions. If any functions so named
23062 are not encountered in the source, a warning is emitted that the pragma is
23063 not used. Examples:
23066 #pragma disinterrupt foo
23067 #pragma disinterrupt bar, grill
23068 int foo () @{ @dots{} @}
23071 @item GCC call @var{name} , @var{name} @dots{}
23072 @cindex pragma, call
23073 For the named functions, the compiler always uses a register-indirect
23074 call model when calling the named functions. Examples:
23083 @node RS/6000 and PowerPC Pragmas
23084 @subsection RS/6000 and PowerPC Pragmas
23086 The RS/6000 and PowerPC targets define one pragma for controlling
23087 whether or not the @code{longcall} attribute is added to function
23088 declarations by default. This pragma overrides the @option{-mlongcall}
23089 option, but not the @code{longcall} and @code{shortcall} attributes.
23090 @xref{RS/6000 and PowerPC Options}, for more information about when long
23091 calls are and are not necessary.
23095 @cindex pragma, longcall
23096 Apply the @code{longcall} attribute to all subsequent function
23100 Do not apply the @code{longcall} attribute to subsequent function
23104 @c Describe h8300 pragmas here.
23105 @c Describe sh pragmas here.
23106 @c Describe v850 pragmas here.
23108 @node S/390 Pragmas
23109 @subsection S/390 Pragmas
23111 The pragmas defined by the S/390 target correspond to the S/390
23112 target function attributes and some the additional options:
23119 Note that options of the pragma, unlike options of the target
23120 attribute, do change the value of preprocessor macros like
23121 @code{__VEC__}. They can be specified as below:
23124 #pragma GCC target("string[,string]...")
23125 #pragma GCC target("string"[,"string"]...)
23128 @node Darwin Pragmas
23129 @subsection Darwin Pragmas
23131 The following pragmas are available for all architectures running the
23132 Darwin operating system. These are useful for compatibility with other
23136 @item mark @var{tokens}@dots{}
23137 @cindex pragma, mark
23138 This pragma is accepted, but has no effect.
23140 @item options align=@var{alignment}
23141 @cindex pragma, options align
23142 This pragma sets the alignment of fields in structures. The values of
23143 @var{alignment} may be @code{mac68k}, to emulate m68k alignment, or
23144 @code{power}, to emulate PowerPC alignment. Uses of this pragma nest
23145 properly; to restore the previous setting, use @code{reset} for the
23148 @item segment @var{tokens}@dots{}
23149 @cindex pragma, segment
23150 This pragma is accepted, but has no effect.
23152 @item unused (@var{var} [, @var{var}]@dots{})
23153 @cindex pragma, unused
23154 This pragma declares variables to be possibly unused. GCC does not
23155 produce warnings for the listed variables. The effect is similar to
23156 that of the @code{unused} attribute, except that this pragma may appear
23157 anywhere within the variables' scopes.
23160 @node Solaris Pragmas
23161 @subsection Solaris Pragmas
23163 The Solaris target supports @code{#pragma redefine_extname}
23164 (@pxref{Symbol-Renaming Pragmas}). It also supports additional
23165 @code{#pragma} directives for compatibility with the system compiler.
23168 @item align @var{alignment} (@var{variable} [, @var{variable}]...)
23169 @cindex pragma, align
23171 Increase the minimum alignment of each @var{variable} to @var{alignment}.
23172 This is the same as GCC's @code{aligned} attribute @pxref{Variable
23173 Attributes}). Macro expansion occurs on the arguments to this pragma
23174 when compiling C and Objective-C@. It does not currently occur when
23175 compiling C++, but this is a bug which may be fixed in a future
23178 @item fini (@var{function} [, @var{function}]...)
23179 @cindex pragma, fini
23181 This pragma causes each listed @var{function} to be called after
23182 main, or during shared module unloading, by adding a call to the
23183 @code{.fini} section.
23185 @item init (@var{function} [, @var{function}]...)
23186 @cindex pragma, init
23188 This pragma causes each listed @var{function} to be called during
23189 initialization (before @code{main}) or during shared module loading, by
23190 adding a call to the @code{.init} section.
23194 @node Symbol-Renaming Pragmas
23195 @subsection Symbol-Renaming Pragmas
23197 GCC supports a @code{#pragma} directive that changes the name used in
23198 assembly for a given declaration. While this pragma is supported on all
23199 platforms, it is intended primarily to provide compatibility with the
23200 Solaris system headers. This effect can also be achieved using the asm
23201 labels extension (@pxref{Asm Labels}).
23204 @item redefine_extname @var{oldname} @var{newname}
23205 @cindex pragma, redefine_extname
23207 This pragma gives the C function @var{oldname} the assembly symbol
23208 @var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME}
23209 is defined if this pragma is available (currently on all platforms).
23212 This pragma and the @code{asm} labels extension interact in a complicated
23213 manner. Here are some corner cases you may want to be aware of:
23216 @item This pragma silently applies only to declarations with external
23217 linkage. The @code{asm} label feature does not have this restriction.
23219 @item In C++, this pragma silently applies only to declarations with
23220 ``C'' linkage. Again, @code{asm} labels do not have this restriction.
23222 @item If either of the ways of changing the assembly name of a
23223 declaration are applied to a declaration whose assembly name has
23224 already been determined (either by a previous use of one of these
23225 features, or because the compiler needed the assembly name in order to
23226 generate code), and the new name is different, a warning issues and
23227 the name does not change.
23229 @item The @var{oldname} used by @code{#pragma redefine_extname} is
23230 always the C-language name.
23233 @node Structure-Layout Pragmas
23234 @subsection Structure-Layout Pragmas
23236 For compatibility with Microsoft Windows compilers, GCC supports a
23237 set of @code{#pragma} directives that change the maximum alignment of
23238 members of structures (other than zero-width bit-fields), unions, and
23239 classes subsequently defined. The @var{n} value below always is required
23240 to be a small power of two and specifies the new alignment in bytes.
23243 @item @code{#pragma pack(@var{n})} simply sets the new alignment.
23244 @item @code{#pragma pack()} sets the alignment to the one that was in
23245 effect when compilation started (see also command-line option
23246 @option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}).
23247 @item @code{#pragma pack(push[,@var{n}])} pushes the current alignment
23248 setting on an internal stack and then optionally sets the new alignment.
23249 @item @code{#pragma pack(pop)} restores the alignment setting to the one
23250 saved at the top of the internal stack (and removes that stack entry).
23251 Note that @code{#pragma pack([@var{n}])} does not influence this internal
23252 stack; thus it is possible to have @code{#pragma pack(push)} followed by
23253 multiple @code{#pragma pack(@var{n})} instances and finalized by a single
23254 @code{#pragma pack(pop)}.
23257 Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct}
23258 directive which lays out structures and unions subsequently defined as the
23259 documented @code{__attribute__ ((ms_struct))}.
23262 @item @code{#pragma ms_struct on} turns on the Microsoft layout.
23263 @item @code{#pragma ms_struct off} turns off the Microsoft layout.
23264 @item @code{#pragma ms_struct reset} goes back to the default layout.
23267 Most targets also support the @code{#pragma scalar_storage_order} directive
23268 which lays out structures and unions subsequently defined as the documented
23269 @code{__attribute__ ((scalar_storage_order))}.
23272 @item @code{#pragma scalar_storage_order big-endian} sets the storage order
23273 of the scalar fields to big-endian.
23274 @item @code{#pragma scalar_storage_order little-endian} sets the storage order
23275 of the scalar fields to little-endian.
23276 @item @code{#pragma scalar_storage_order default} goes back to the endianness
23277 that was in effect when compilation started (see also command-line option
23278 @option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}).
23282 @subsection Weak Pragmas
23284 For compatibility with SVR4, GCC supports a set of @code{#pragma}
23285 directives for declaring symbols to be weak, and defining weak
23289 @item #pragma weak @var{symbol}
23290 @cindex pragma, weak
23291 This pragma declares @var{symbol} to be weak, as if the declaration
23292 had the attribute of the same name. The pragma may appear before
23293 or after the declaration of @var{symbol}. It is not an error for
23294 @var{symbol} to never be defined at all.
23296 @item #pragma weak @var{symbol1} = @var{symbol2}
23297 This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}.
23298 It is an error if @var{symbol2} is not defined in the current
23302 @node Diagnostic Pragmas
23303 @subsection Diagnostic Pragmas
23305 GCC allows the user to selectively enable or disable certain types of
23306 diagnostics, and change the kind of the diagnostic. For example, a
23307 project's policy might require that all sources compile with
23308 @option{-Werror} but certain files might have exceptions allowing
23309 specific types of warnings. Or, a project might selectively enable
23310 diagnostics and treat them as errors depending on which preprocessor
23311 macros are defined.
23314 @item #pragma GCC diagnostic @var{kind} @var{option}
23315 @cindex pragma, diagnostic
23317 Modifies the disposition of a diagnostic. Note that not all
23318 diagnostics are modifiable; at the moment only warnings (normally
23319 controlled by @samp{-W@dots{}}) can be controlled, and not all of them.
23320 Use @option{-fdiagnostics-show-option} to determine which diagnostics
23321 are controllable and which option controls them.
23323 @var{kind} is @samp{error} to treat this diagnostic as an error,
23324 @samp{warning} to treat it like a warning (even if @option{-Werror} is
23325 in effect), or @samp{ignored} if the diagnostic is to be ignored.
23326 @var{option} is a double quoted string that matches the command-line
23330 #pragma GCC diagnostic warning "-Wformat"
23331 #pragma GCC diagnostic error "-Wformat"
23332 #pragma GCC diagnostic ignored "-Wformat"
23335 Note that these pragmas override any command-line options. GCC keeps
23336 track of the location of each pragma, and issues diagnostics according
23337 to the state as of that point in the source file. Thus, pragmas occurring
23338 after a line do not affect diagnostics caused by that line.
23340 @item #pragma GCC diagnostic push
23341 @itemx #pragma GCC diagnostic pop
23343 Causes GCC to remember the state of the diagnostics as of each
23344 @code{push}, and restore to that point at each @code{pop}. If a
23345 @code{pop} has no matching @code{push}, the command-line options are
23349 #pragma GCC diagnostic error "-Wuninitialized"
23350 foo(a); /* error is given for this one */
23351 #pragma GCC diagnostic push
23352 #pragma GCC diagnostic ignored "-Wuninitialized"
23353 foo(b); /* no diagnostic for this one */
23354 #pragma GCC diagnostic pop
23355 foo(c); /* error is given for this one */
23356 #pragma GCC diagnostic pop
23357 foo(d); /* depends on command-line options */
23362 GCC also offers a simple mechanism for printing messages during
23366 @item #pragma message @var{string}
23367 @cindex pragma, diagnostic
23369 Prints @var{string} as a compiler message on compilation. The message
23370 is informational only, and is neither a compilation warning nor an
23371 error. Newlines can be included in the string by using the @samp{\n}
23375 #pragma message "Compiling " __FILE__ "..."
23378 @var{string} may be parenthesized, and is printed with location
23379 information. For example,
23382 #define DO_PRAGMA(x) _Pragma (#x)
23383 #define TODO(x) DO_PRAGMA(message ("TODO - " #x))
23385 TODO(Remember to fix this)
23389 prints @samp{/tmp/file.c:4: note: #pragma message:
23390 TODO - Remember to fix this}.
23392 @item #pragma GCC error @var{message}
23393 @cindex pragma, diagnostic
23394 Generates an error message. This pragma @emph{is} considered to
23395 indicate an error in the compilation, and it will be treated as such.
23397 Newlines can be included in the string by using the @samp{\n}
23398 escape sequence. They will be displayed as newlines even if the
23399 @option{-fmessage-length} option is set to zero.
23401 The error is only generated if the pragma is present in the code after
23402 pre-processing has been completed. It does not matter however if the
23403 code containing the pragma is unreachable:
23407 #pragma GCC error "this error is not seen"
23412 #pragma GCC error "this error is seen"
23416 @item #pragma GCC warning @var{message}
23417 @cindex pragma, diagnostic
23418 This is just like @samp{pragma GCC error} except that a warning
23419 message is issued instead of an error message. Unless
23420 @option{-Werror} is in effect, in which case this pragma will generate
23425 @node Visibility Pragmas
23426 @subsection Visibility Pragmas
23429 @item #pragma GCC visibility push(@var{visibility})
23430 @itemx #pragma GCC visibility pop
23431 @cindex pragma, visibility
23433 This pragma allows the user to set the visibility for multiple
23434 declarations without having to give each a visibility attribute
23435 (@pxref{Function Attributes}).
23437 In C++, @samp{#pragma GCC visibility} affects only namespace-scope
23438 declarations. Class members and template specializations are not
23439 affected; if you want to override the visibility for a particular
23440 member or instantiation, you must use an attribute.
23445 @node Push/Pop Macro Pragmas
23446 @subsection Push/Pop Macro Pragmas
23448 For compatibility with Microsoft Windows compilers, GCC supports
23449 @samp{#pragma push_macro(@var{"macro_name"})}
23450 and @samp{#pragma pop_macro(@var{"macro_name"})}.
23453 @item #pragma push_macro(@var{"macro_name"})
23454 @cindex pragma, push_macro
23455 This pragma saves the value of the macro named as @var{macro_name} to
23456 the top of the stack for this macro.
23458 @item #pragma pop_macro(@var{"macro_name"})
23459 @cindex pragma, pop_macro
23460 This pragma sets the value of the macro named as @var{macro_name} to
23461 the value on top of the stack for this macro. If the stack for
23462 @var{macro_name} is empty, the value of the macro remains unchanged.
23469 #pragma push_macro("X")
23472 #pragma pop_macro("X")
23477 In this example, the definition of X as 1 is saved by @code{#pragma
23478 push_macro} and restored by @code{#pragma pop_macro}.
23480 @node Function Specific Option Pragmas
23481 @subsection Function Specific Option Pragmas
23484 @item #pragma GCC target (@var{string}, @dots{})
23485 @cindex pragma GCC target
23487 This pragma allows you to set target-specific options for functions
23488 defined later in the source file. One or more strings can be
23489 specified. Each function that is defined after this point is treated
23490 as if it had been declared with one @code{target(}@var{string}@code{)}
23491 attribute for each @var{string} argument. The parentheses around
23492 the strings in the pragma are optional. @xref{Function Attributes},
23493 for more information about the @code{target} attribute and the attribute
23496 The @code{#pragma GCC target} pragma is presently implemented for
23497 x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only.
23499 @item #pragma GCC optimize (@var{string}, @dots{})
23500 @cindex pragma GCC optimize
23502 This pragma allows you to set global optimization options for functions
23503 defined later in the source file. One or more strings can be
23504 specified. Each function that is defined after this point is treated
23505 as if it had been declared with one @code{optimize(}@var{string}@code{)}
23506 attribute for each @var{string} argument. The parentheses around
23507 the strings in the pragma are optional. @xref{Function Attributes},
23508 for more information about the @code{optimize} attribute and the attribute
23511 @item #pragma GCC push_options
23512 @itemx #pragma GCC pop_options
23513 @cindex pragma GCC push_options
23514 @cindex pragma GCC pop_options
23516 These pragmas maintain a stack of the current target and optimization
23517 options. It is intended for include files where you temporarily want
23518 to switch to using a different @samp{#pragma GCC target} or
23519 @samp{#pragma GCC optimize} and then to pop back to the previous
23522 @item #pragma GCC reset_options
23523 @cindex pragma GCC reset_options
23525 This pragma clears the current @code{#pragma GCC target} and
23526 @code{#pragma GCC optimize} to use the default switches as specified
23527 on the command line.
23531 @node Loop-Specific Pragmas
23532 @subsection Loop-Specific Pragmas
23535 @item #pragma GCC ivdep
23536 @cindex pragma GCC ivdep
23538 With this pragma, the programmer asserts that there are no loop-carried
23539 dependencies which would prevent consecutive iterations of
23540 the following loop from executing concurrently with SIMD
23541 (single instruction multiple data) instructions.
23543 For example, the compiler can only unconditionally vectorize the following
23544 loop with the pragma:
23547 void foo (int n, int *a, int *b, int *c)
23551 for (i = 0; i < n; ++i)
23552 a[i] = b[i] + c[i];
23557 In this example, using the @code{restrict} qualifier had the same
23558 effect. In the following example, that would not be possible. Assume
23559 @math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows
23560 that it can unconditionally vectorize the following loop:
23563 void ignore_vec_dep (int *a, int k, int c, int m)
23566 for (int i = 0; i < m; i++)
23567 a[i] = a[i + k] * c;
23571 @item #pragma GCC unroll @var{n}
23572 @cindex pragma GCC unroll @var{n}
23574 You can use this pragma to control how many times a loop should be unrolled.
23575 It must be placed immediately before a @code{for}, @code{while} or @code{do}
23576 loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows.
23577 @var{n} is an integer constant expression specifying the unrolling factor.
23578 The values of @math{0} and @math{1} block any unrolling of the loop.
23582 @node Unnamed Fields
23583 @section Unnamed Structure and Union Fields
23584 @cindex @code{struct}
23585 @cindex @code{union}
23587 As permitted by ISO C11 and for compatibility with other compilers,
23588 GCC allows you to define
23589 a structure or union that contains, as fields, structures and unions
23590 without names. For example:
23604 In this example, you are able to access members of the unnamed
23605 union with code like @samp{foo.b}. Note that only unnamed structs and
23606 unions are allowed, you may not have, for example, an unnamed
23609 You must never create such structures that cause ambiguous field definitions.
23610 For example, in this structure:
23622 it is ambiguous which @code{a} is being referred to with @samp{foo.a}.
23623 The compiler gives errors for such constructs.
23625 @opindex fms-extensions
23626 Unless @option{-fms-extensions} is used, the unnamed field must be a
23627 structure or union definition without a tag (for example, @samp{struct
23628 @{ int a; @};}). If @option{-fms-extensions} is used, the field may
23629 also be a definition with a tag such as @samp{struct foo @{ int a;
23630 @};}, a reference to a previously defined structure or union such as
23631 @samp{struct foo;}, or a reference to a @code{typedef} name for a
23632 previously defined structure or union type.
23634 @opindex fplan9-extensions
23635 The option @option{-fplan9-extensions} enables
23636 @option{-fms-extensions} as well as two other extensions. First, a
23637 pointer to a structure is automatically converted to a pointer to an
23638 anonymous field for assignments and function calls. For example:
23641 struct s1 @{ int a; @};
23642 struct s2 @{ struct s1; @};
23643 extern void f1 (struct s1 *);
23644 void f2 (struct s2 *p) @{ f1 (p); @}
23648 In the call to @code{f1} inside @code{f2}, the pointer @code{p} is
23649 converted into a pointer to the anonymous field.
23651 Second, when the type of an anonymous field is a @code{typedef} for a
23652 @code{struct} or @code{union}, code may refer to the field using the
23653 name of the @code{typedef}.
23656 typedef struct @{ int a; @} s1;
23657 struct s2 @{ s1; @};
23658 s1 f1 (struct s2 *p) @{ return p->s1; @}
23661 These usages are only permitted when they are not ambiguous.
23664 @section Thread-Local Storage
23665 @cindex Thread-Local Storage
23666 @cindex @acronym{TLS}
23667 @cindex @code{__thread}
23669 Thread-local storage (@acronym{TLS}) is a mechanism by which variables
23670 are allocated such that there is one instance of the variable per extant
23671 thread. The runtime model GCC uses to implement this originates
23672 in the IA-64 processor-specific ABI, but has since been migrated
23673 to other processors as well. It requires significant support from
23674 the linker (@command{ld}), dynamic linker (@command{ld.so}), and
23675 system libraries (@file{libc.so} and @file{libpthread.so}), so it
23676 is not available everywhere.
23678 At the user level, the extension is visible with a new storage
23679 class keyword: @code{__thread}. For example:
23683 extern __thread struct state s;
23684 static __thread char *p;
23687 The @code{__thread} specifier may be used alone, with the @code{extern}
23688 or @code{static} specifiers, but with no other storage class specifier.
23689 When used with @code{extern} or @code{static}, @code{__thread} must appear
23690 immediately after the other storage class specifier.
23692 The @code{__thread} specifier may be applied to any global, file-scoped
23693 static, function-scoped static, or static data member of a class. It may
23694 not be applied to block-scoped automatic or non-static data member.
23696 When the address-of operator is applied to a thread-local variable, it is
23697 evaluated at run time and returns the address of the current thread's
23698 instance of that variable. An address so obtained may be used by any
23699 thread. When a thread terminates, any pointers to thread-local variables
23700 in that thread become invalid.
23702 No static initialization may refer to the address of a thread-local variable.
23704 In C++, if an initializer is present for a thread-local variable, it must
23705 be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++
23708 See @uref{https://www.akkadia.org/drepper/tls.pdf,
23709 ELF Handling For Thread-Local Storage} for a detailed explanation of
23710 the four thread-local storage addressing models, and how the runtime
23711 is expected to function.
23714 * C99 Thread-Local Edits::
23715 * C++98 Thread-Local Edits::
23718 @node C99 Thread-Local Edits
23719 @subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage
23721 The following are a set of changes to ISO/IEC 9899:1999 (aka C99)
23722 that document the exact semantics of the language extension.
23726 @cite{5.1.2 Execution environments}
23728 Add new text after paragraph 1
23731 Within either execution environment, a @dfn{thread} is a flow of
23732 control within a program. It is implementation defined whether
23733 or not there may be more than one thread associated with a program.
23734 It is implementation defined how threads beyond the first are
23735 created, the name and type of the function called at thread
23736 startup, and how threads may be terminated. However, objects
23737 with thread storage duration shall be initialized before thread
23742 @cite{6.2.4 Storage durations of objects}
23744 Add new text before paragraph 3
23747 An object whose identifier is declared with the storage-class
23748 specifier @w{@code{__thread}} has @dfn{thread storage duration}.
23749 Its lifetime is the entire execution of the thread, and its
23750 stored value is initialized only once, prior to thread startup.
23754 @cite{6.4.1 Keywords}
23756 Add @code{__thread}.
23759 @cite{6.7.1 Storage-class specifiers}
23761 Add @code{__thread} to the list of storage class specifiers in
23764 Change paragraph 2 to
23767 With the exception of @code{__thread}, at most one storage-class
23768 specifier may be given [@dots{}]. The @code{__thread} specifier may
23769 be used alone, or immediately following @code{extern} or
23773 Add new text after paragraph 6
23776 The declaration of an identifier for a variable that has
23777 block scope that specifies @code{__thread} shall also
23778 specify either @code{extern} or @code{static}.
23780 The @code{__thread} specifier shall be used only with
23785 @node C++98 Thread-Local Edits
23786 @subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage
23788 The following are a set of changes to ISO/IEC 14882:1998 (aka C++98)
23789 that document the exact semantics of the language extension.
23793 @b{[intro.execution]}
23795 New text after paragraph 4
23798 A @dfn{thread} is a flow of control within the abstract machine.
23799 It is implementation defined whether or not there may be more than
23803 New text after paragraph 7
23806 It is unspecified whether additional action must be taken to
23807 ensure when and whether side effects are visible to other threads.
23813 Add @code{__thread}.
23816 @b{[basic.start.main]}
23818 Add after paragraph 5
23821 The thread that begins execution at the @code{main} function is called
23822 the @dfn{main thread}. It is implementation defined how functions
23823 beginning threads other than the main thread are designated or typed.
23824 A function so designated, as well as the @code{main} function, is called
23825 a @dfn{thread startup function}. It is implementation defined what
23826 happens if a thread startup function returns. It is implementation
23827 defined what happens to other threads when any thread calls @code{exit}.
23831 @b{[basic.start.init]}
23833 Add after paragraph 4
23836 The storage for an object of thread storage duration shall be
23837 statically initialized before the first statement of the thread startup
23838 function. An object of thread storage duration shall not require
23839 dynamic initialization.
23843 @b{[basic.start.term]}
23845 Add after paragraph 3
23848 The type of an object with thread storage duration shall not have a
23849 non-trivial destructor, nor shall it be an array type whose elements
23850 (directly or indirectly) have non-trivial destructors.
23856 Add ``thread storage duration'' to the list in paragraph 1.
23861 Thread, static, and automatic storage durations are associated with
23862 objects introduced by declarations [@dots{}].
23865 Add @code{__thread} to the list of specifiers in paragraph 3.
23868 @b{[basic.stc.thread]}
23870 New section before @b{[basic.stc.static]}
23873 The keyword @code{__thread} applied to a non-local object gives the
23874 object thread storage duration.
23876 A local variable or class data member declared both @code{static}
23877 and @code{__thread} gives the variable or member thread storage
23882 @b{[basic.stc.static]}
23887 All objects that have neither thread storage duration, dynamic
23888 storage duration nor are local [@dots{}].
23894 Add @code{__thread} to the list in paragraph 1.
23899 With the exception of @code{__thread}, at most one
23900 @var{storage-class-specifier} shall appear in a given
23901 @var{decl-specifier-seq}. The @code{__thread} specifier may
23902 be used alone, or immediately following the @code{extern} or
23903 @code{static} specifiers. [@dots{}]
23906 Add after paragraph 5
23909 The @code{__thread} specifier can be applied only to the names of objects
23910 and to anonymous unions.
23916 Add after paragraph 6
23919 Non-@code{static} members shall not be @code{__thread}.
23923 @node Binary constants
23924 @section Binary Constants using the @samp{0b} Prefix
23925 @cindex Binary constants using the @samp{0b} prefix
23927 Integer constants can be written as binary constants, consisting of a
23928 sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
23929 @samp{0B}. This is particularly useful in environments that operate a
23930 lot on the bit level (like microcontrollers).
23932 The following statements are identical:
23941 The type of these constants follows the same rules as for octal or
23942 hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
23945 @node C++ Extensions
23946 @chapter Extensions to the C++ Language
23947 @cindex extensions, C++ language
23948 @cindex C++ language extensions
23950 The GNU compiler provides these extensions to the C++ language (and you
23951 can also use most of the C language extensions in your C++ programs). If you
23952 want to write code that checks whether these features are available, you can
23953 test for the GNU compiler the same way as for C programs: check for a
23954 predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to
23955 test specifically for GNU C++ (@pxref{Common Predefined Macros,,
23956 Predefined Macros,cpp,The GNU C Preprocessor}).
23959 * C++ Volatiles:: What constitutes an access to a volatile object.
23960 * Restricted Pointers:: C99 restricted pointers and references.
23961 * Vague Linkage:: Where G++ puts inlines, vtables and such.
23962 * C++ Interface:: You can use a single C++ header file for both
23963 declarations and definitions.
23964 * Template Instantiation:: Methods for ensuring that exactly one copy of
23965 each needed template instantiation is emitted.
23966 * Bound member functions:: You can extract a function pointer to the
23967 method denoted by a @samp{->*} or @samp{.*} expression.
23968 * C++ Attributes:: Variable, function, and type attributes for C++ only.
23969 * Function Multiversioning:: Declaring multiple function versions.
23970 * Type Traits:: Compiler support for type traits.
23971 * C++ Concepts:: Improved support for generic programming.
23972 * Deprecated Features:: Things will disappear from G++.
23973 * Backwards Compatibility:: Compatibilities with earlier definitions of C++.
23976 @node C++ Volatiles
23977 @section When is a Volatile C++ Object Accessed?
23978 @cindex accessing volatiles
23979 @cindex volatile read
23980 @cindex volatile write
23981 @cindex volatile access
23983 The C++ standard differs from the C standard in its treatment of
23984 volatile objects. It fails to specify what constitutes a volatile
23985 access, except to say that C++ should behave in a similar manner to C
23986 with respect to volatiles, where possible. However, the different
23987 lvalueness of expressions between C and C++ complicate the behavior.
23988 G++ behaves the same as GCC for volatile access, @xref{C
23989 Extensions,,Volatiles}, for a description of GCC's behavior.
23991 The C and C++ language specifications differ when an object is
23992 accessed in a void context:
23995 volatile int *src = @var{somevalue};
23999 The C++ standard specifies that such expressions do not undergo lvalue
24000 to rvalue conversion, and that the type of the dereferenced object may
24001 be incomplete. The C++ standard does not specify explicitly that it
24002 is lvalue to rvalue conversion that is responsible for causing an
24003 access. There is reason to believe that it is, because otherwise
24004 certain simple expressions become undefined. However, because it
24005 would surprise most programmers, G++ treats dereferencing a pointer to
24006 volatile object of complete type as GCC would do for an equivalent
24007 type in C@. When the object has incomplete type, G++ issues a
24008 warning; if you wish to force an error, you must force a conversion to
24009 rvalue with, for instance, a static cast.
24011 When using a reference to volatile, G++ does not treat equivalent
24012 expressions as accesses to volatiles, but instead issues a warning that
24013 no volatile is accessed. The rationale for this is that otherwise it
24014 becomes difficult to determine where volatile access occur, and not
24015 possible to ignore the return value from functions returning volatile
24016 references. Again, if you wish to force a read, cast the reference to
24019 G++ implements the same behavior as GCC does when assigning to a
24020 volatile object---there is no reread of the assigned-to object, the
24021 assigned rvalue is reused. Note that in C++ assignment expressions
24022 are lvalues, and if used as an lvalue, the volatile object is
24023 referred to. For instance, @var{vref} refers to @var{vobj}, as
24024 expected, in the following example:
24028 volatile int &vref = vobj = @var{something};
24031 @node Restricted Pointers
24032 @section Restricting Pointer Aliasing
24033 @cindex restricted pointers
24034 @cindex restricted references
24035 @cindex restricted this pointer
24037 As with the C front end, G++ understands the C99 feature of restricted pointers,
24038 specified with the @code{__restrict__}, or @code{__restrict} type
24039 qualifier. Because you cannot compile C++ by specifying the @option{-std=c99}
24040 language flag, @code{restrict} is not a keyword in C++.
24042 In addition to allowing restricted pointers, you can specify restricted
24043 references, which indicate that the reference is not aliased in the local
24047 void fn (int *__restrict__ rptr, int &__restrict__ rref)
24054 In the body of @code{fn}, @var{rptr} points to an unaliased integer and
24055 @var{rref} refers to a (different) unaliased integer.
24057 You may also specify whether a member function's @var{this} pointer is
24058 unaliased by using @code{__restrict__} as a member function qualifier.
24061 void T::fn () __restrict__
24068 Within the body of @code{T::fn}, @var{this} has the effective
24069 definition @code{T *__restrict__ const this}. Notice that the
24070 interpretation of a @code{__restrict__} member function qualifier is
24071 different to that of @code{const} or @code{volatile} qualifier, in that it
24072 is applied to the pointer rather than the object. This is consistent with
24073 other compilers that implement restricted pointers.
24075 As with all outermost parameter qualifiers, @code{__restrict__} is
24076 ignored in function definition matching. This means you only need to
24077 specify @code{__restrict__} in a function definition, rather than
24078 in a function prototype as well.
24080 @node Vague Linkage
24081 @section Vague Linkage
24082 @cindex vague linkage
24084 There are several constructs in C++ that require space in the object
24085 file but are not clearly tied to a single translation unit. We say that
24086 these constructs have ``vague linkage''. Typically such constructs are
24087 emitted wherever they are needed, though sometimes we can be more
24091 @item Inline Functions
24092 Inline functions are typically defined in a header file which can be
24093 included in many different compilations. Hopefully they can usually be
24094 inlined, but sometimes an out-of-line copy is necessary, if the address
24095 of the function is taken or if inlining fails. In general, we emit an
24096 out-of-line copy in all translation units where one is needed. As an
24097 exception, we only emit inline virtual functions with the vtable, since
24098 it always requires a copy.
24100 Local static variables and string constants used in an inline function
24101 are also considered to have vague linkage, since they must be shared
24102 between all inlined and out-of-line instances of the function.
24106 C++ virtual functions are implemented in most compilers using a lookup
24107 table, known as a vtable. The vtable contains pointers to the virtual
24108 functions provided by a class, and each object of the class contains a
24109 pointer to its vtable (or vtables, in some multiple-inheritance
24110 situations). If the class declares any non-inline, non-pure virtual
24111 functions, the first one is chosen as the ``key method'' for the class,
24112 and the vtable is only emitted in the translation unit where the key
24115 @emph{Note:} If the chosen key method is later defined as inline, the
24116 vtable is still emitted in every translation unit that defines it.
24117 Make sure that any inline virtuals are declared inline in the class
24118 body, even if they are not defined there.
24120 @item @code{type_info} objects
24121 @cindex @code{type_info}
24123 C++ requires information about types to be written out in order to
24124 implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
24125 For polymorphic classes (classes with virtual functions), the @samp{type_info}
24126 object is written out along with the vtable so that @samp{dynamic_cast}
24127 can determine the dynamic type of a class object at run time. For all
24128 other types, we write out the @samp{type_info} object when it is used: when
24129 applying @samp{typeid} to an expression, throwing an object, or
24130 referring to a type in a catch clause or exception specification.
24132 @item Template Instantiations
24133 Most everything in this section also applies to template instantiations,
24134 but there are other options as well.
24135 @xref{Template Instantiation,,Where's the Template?}.
24139 When used with GNU ld version 2.8 or later on an ELF system such as
24140 GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of
24141 these constructs will be discarded at link time. This is known as
24144 On targets that don't support COMDAT, but do support weak symbols, GCC
24145 uses them. This way one copy overrides all the others, but
24146 the unused copies still take up space in the executable.
24148 For targets that do not support either COMDAT or weak symbols,
24149 most entities with vague linkage are emitted as local symbols to
24150 avoid duplicate definition errors from the linker. This does not happen
24151 for local statics in inlines, however, as having multiple copies
24152 almost certainly breaks things.
24154 @xref{C++ Interface,,Declarations and Definitions in One Header}, for
24155 another way to control placement of these constructs.
24157 @node C++ Interface
24158 @section C++ Interface and Implementation Pragmas
24160 @cindex interface and implementation headers, C++
24161 @cindex C++ interface and implementation headers
24162 @cindex pragmas, interface and implementation
24164 @code{#pragma interface} and @code{#pragma implementation} provide the
24165 user with a way of explicitly directing the compiler to emit entities
24166 with vague linkage (and debugging information) in a particular
24169 @emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2
24170 by COMDAT support and the ``key method'' heuristic
24171 mentioned in @ref{Vague Linkage}. Using them can actually cause your
24172 program to grow due to unnecessary out-of-line copies of inline
24176 @item #pragma interface
24177 @itemx #pragma interface "@var{subdir}/@var{objects}.h"
24178 @kindex #pragma interface
24179 Use this directive in @emph{header files} that define object classes, to save
24180 space in most of the object files that use those classes. Normally,
24181 local copies of certain information (backup copies of inline member
24182 functions, debugging information, and the internal tables that implement
24183 virtual functions) must be kept in each object file that includes class
24184 definitions. You can use this pragma to avoid such duplication. When a
24185 header file containing @samp{#pragma interface} is included in a
24186 compilation, this auxiliary information is not generated (unless
24187 the main input source file itself uses @samp{#pragma implementation}).
24188 Instead, the object files contain references to be resolved at link
24191 The second form of this directive is useful for the case where you have
24192 multiple headers with the same name in different directories. If you
24193 use this form, you must specify the same string to @samp{#pragma
24196 @item #pragma implementation
24197 @itemx #pragma implementation "@var{objects}.h"
24198 @kindex #pragma implementation
24199 Use this pragma in a @emph{main input file}, when you want full output from
24200 included header files to be generated (and made globally visible). The
24201 included header file, in turn, should use @samp{#pragma interface}.
24202 Backup copies of inline member functions, debugging information, and the
24203 internal tables used to implement virtual functions are all generated in
24204 implementation files.
24206 @cindex implied @code{#pragma implementation}
24207 @cindex @code{#pragma implementation}, implied
24208 @cindex naming convention, implementation headers
24209 If you use @samp{#pragma implementation} with no argument, it applies to
24210 an include file with the same basename@footnote{A file's @dfn{basename}
24211 is the name stripped of all leading path information and of trailing
24212 suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source
24213 file. For example, in @file{allclass.cc}, giving just
24214 @samp{#pragma implementation}
24215 by itself is equivalent to @samp{#pragma implementation "allclass.h"}.
24217 Use the string argument if you want a single implementation file to
24218 include code from multiple header files. (You must also use
24219 @samp{#include} to include the header file; @samp{#pragma
24220 implementation} only specifies how to use the file---it doesn't actually
24223 There is no way to split up the contents of a single header file into
24224 multiple implementation files.
24227 @cindex inlining and C++ pragmas
24228 @cindex C++ pragmas, effect on inlining
24229 @cindex pragmas in C++, effect on inlining
24230 @samp{#pragma implementation} and @samp{#pragma interface} also have an
24231 effect on function inlining.
24233 If you define a class in a header file marked with @samp{#pragma
24234 interface}, the effect on an inline function defined in that class is
24235 similar to an explicit @code{extern} declaration---the compiler emits
24236 no code at all to define an independent version of the function. Its
24237 definition is used only for inlining with its callers.
24239 @opindex fno-implement-inlines
24240 Conversely, when you include the same header file in a main source file
24241 that declares it as @samp{#pragma implementation}, the compiler emits
24242 code for the function itself; this defines a version of the function
24243 that can be found via pointers (or by callers compiled without
24244 inlining). If all calls to the function can be inlined, you can avoid
24245 emitting the function by compiling with @option{-fno-implement-inlines}.
24246 If any calls are not inlined, you will get linker errors.
24248 @node Template Instantiation
24249 @section Where's the Template?
24250 @cindex template instantiation
24252 C++ templates were the first language feature to require more
24253 intelligence from the environment than was traditionally found on a UNIX
24254 system. Somehow the compiler and linker have to make sure that each
24255 template instance occurs exactly once in the executable if it is needed,
24256 and not at all otherwise. There are two basic approaches to this
24257 problem, which are referred to as the Borland model and the Cfront model.
24260 @item Borland model
24261 Borland C++ solved the template instantiation problem by adding the code
24262 equivalent of common blocks to their linker; the compiler emits template
24263 instances in each translation unit that uses them, and the linker
24264 collapses them together. The advantage of this model is that the linker
24265 only has to consider the object files themselves; there is no external
24266 complexity to worry about. The disadvantage is that compilation time
24267 is increased because the template code is being compiled repeatedly.
24268 Code written for this model tends to include definitions of all
24269 templates in the header file, since they must be seen to be
24273 The AT&T C++ translator, Cfront, solved the template instantiation
24274 problem by creating the notion of a template repository, an
24275 automatically maintained place where template instances are stored. A
24276 more modern version of the repository works as follows: As individual
24277 object files are built, the compiler places any template definitions and
24278 instantiations encountered in the repository. At link time, the link
24279 wrapper adds in the objects in the repository and compiles any needed
24280 instances that were not previously emitted. The advantages of this
24281 model are more optimal compilation speed and the ability to use the
24282 system linker; to implement the Borland model a compiler vendor also
24283 needs to replace the linker. The disadvantages are vastly increased
24284 complexity, and thus potential for error; for some code this can be
24285 just as transparent, but in practice it can been very difficult to build
24286 multiple programs in one directory and one program in multiple
24287 directories. Code written for this model tends to separate definitions
24288 of non-inline member templates into a separate file, which should be
24289 compiled separately.
24292 G++ implements the Borland model on targets where the linker supports it,
24293 including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows.
24294 Otherwise G++ implements neither automatic model.
24296 You have the following options for dealing with template instantiations:
24300 Do nothing. Code written for the Borland model works fine, but
24301 each translation unit contains instances of each of the templates it
24302 uses. The duplicate instances will be discarded by the linker, but in
24303 a large program, this can lead to an unacceptable amount of code
24304 duplication in object files or shared libraries.
24306 Duplicate instances of a template can be avoided by defining an explicit
24307 instantiation in one object file, and preventing the compiler from doing
24308 implicit instantiations in any other object files by using an explicit
24309 instantiation declaration, using the @code{extern template} syntax:
24312 extern template int max (int, int);
24315 This syntax is defined in the C++ 2011 standard, but has been supported by
24316 G++ and other compilers since well before 2011.
24318 Explicit instantiations can be used for the largest or most frequently
24319 duplicated instances, without having to know exactly which other instances
24320 are used in the rest of the program. You can scatter the explicit
24321 instantiations throughout your program, perhaps putting them in the
24322 translation units where the instances are used or the translation units
24323 that define the templates themselves; you can put all of the explicit
24324 instantiations you need into one big file; or you can create small files
24331 template class Foo<int>;
24332 template ostream& operator <<
24333 (ostream&, const Foo<int>&);
24337 for each of the instances you need, and create a template instantiation
24338 library from those.
24340 This is the simplest option, but also offers flexibility and
24341 fine-grained control when necessary. It is also the most portable
24342 alternative and programs using this approach will work with most modern
24347 Compile your template-using code with @option{-frepo}. The compiler
24348 generates files with the extension @samp{.rpo} listing all of the
24349 template instantiations used in the corresponding object files that
24350 could be instantiated there; the link wrapper, @samp{collect2},
24351 then updates the @samp{.rpo} files to tell the compiler where to place
24352 those instantiations and rebuild any affected object files. The
24353 link-time overhead is negligible after the first pass, as the compiler
24354 continues to place the instantiations in the same files.
24356 This can be a suitable option for application code written for the Borland
24357 model, as it usually just works. Code written for the Cfront model
24358 needs to be modified so that the template definitions are available at
24359 one or more points of instantiation; usually this is as simple as adding
24360 @code{#include <tmethods.cc>} to the end of each template header.
24362 For library code, if you want the library to provide all of the template
24363 instantiations it needs, just try to link all of its object files
24364 together; the link will fail, but cause the instantiations to be
24365 generated as a side effect. Be warned, however, that this may cause
24366 conflicts if multiple libraries try to provide the same instantiations.
24367 For greater control, use explicit instantiation as described in the next
24371 @opindex fno-implicit-templates
24372 Compile your code with @option{-fno-implicit-templates} to disable the
24373 implicit generation of template instances, and explicitly instantiate
24374 all the ones you use. This approach requires more knowledge of exactly
24375 which instances you need than do the others, but it's less
24376 mysterious and allows greater control if you want to ensure that only
24377 the intended instances are used.
24379 If you are using Cfront-model code, you can probably get away with not
24380 using @option{-fno-implicit-templates} when compiling files that don't
24381 @samp{#include} the member template definitions.
24383 If you use one big file to do the instantiations, you may want to
24384 compile it without @option{-fno-implicit-templates} so you get all of the
24385 instances required by your explicit instantiations (but not by any
24386 other files) without having to specify them as well.
24388 In addition to forward declaration of explicit instantiations
24389 (with @code{extern}), G++ has extended the template instantiation
24390 syntax to support instantiation of the compiler support data for a
24391 template class (i.e.@: the vtable) without instantiating any of its
24392 members (with @code{inline}), and instantiation of only the static data
24393 members of a template class, without the support data or member
24394 functions (with @code{static}):
24397 inline template class Foo<int>;
24398 static template class Foo<int>;
24402 @node Bound member functions
24403 @section Extracting the Function Pointer from a Bound Pointer to Member Function
24405 @cindex pointer to member function
24406 @cindex bound pointer to member function
24408 In C++, pointer to member functions (PMFs) are implemented using a wide
24409 pointer of sorts to handle all the possible call mechanisms; the PMF
24410 needs to store information about how to adjust the @samp{this} pointer,
24411 and if the function pointed to is virtual, where to find the vtable, and
24412 where in the vtable to look for the member function. If you are using
24413 PMFs in an inner loop, you should really reconsider that decision. If
24414 that is not an option, you can extract the pointer to the function that
24415 would be called for a given object/PMF pair and call it directly inside
24416 the inner loop, to save a bit of time.
24418 Note that you still pay the penalty for the call through a
24419 function pointer; on most modern architectures, such a call defeats the
24420 branch prediction features of the CPU@. This is also true of normal
24421 virtual function calls.
24423 The syntax for this extension is
24427 extern int (A::*fp)();
24428 typedef int (*fptr)(A *);
24430 fptr p = (fptr)(a.*fp);
24433 For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}),
24434 no object is needed to obtain the address of the function. They can be
24435 converted to function pointers directly:
24438 fptr p1 = (fptr)(&A::foo);
24441 @opindex Wno-pmf-conversions
24442 You must specify @option{-Wno-pmf-conversions} to use this extension.
24444 @node C++ Attributes
24445 @section C++-Specific Variable, Function, and Type Attributes
24447 Some attributes only make sense for C++ programs.
24450 @item abi_tag ("@var{tag}", ...)
24451 @cindex @code{abi_tag} function attribute
24452 @cindex @code{abi_tag} variable attribute
24453 @cindex @code{abi_tag} type attribute
24454 The @code{abi_tag} attribute can be applied to a function, variable, or class
24455 declaration. It modifies the mangled name of the entity to
24456 incorporate the tag name, in order to distinguish the function or
24457 class from an earlier version with a different ABI; perhaps the class
24458 has changed size, or the function has a different return type that is
24459 not encoded in the mangled name.
24461 The attribute can also be applied to an inline namespace, but does not
24462 affect the mangled name of the namespace; in this case it is only used
24463 for @option{-Wabi-tag} warnings and automatic tagging of functions and
24464 variables. Tagging inline namespaces is generally preferable to
24465 tagging individual declarations, but the latter is sometimes
24466 necessary, such as when only certain members of a class need to be
24469 The argument can be a list of strings of arbitrary length. The
24470 strings are sorted on output, so the order of the list is
24473 A redeclaration of an entity must not add new ABI tags,
24474 since doing so would change the mangled name.
24476 The ABI tags apply to a name, so all instantiations and
24477 specializations of a template have the same tags. The attribute will
24478 be ignored if applied to an explicit specialization or instantiation.
24480 The @option{-Wabi-tag} flag enables a warning about a class which does
24481 not have all the ABI tags used by its subobjects and virtual functions; for users with code
24482 that needs to coexist with an earlier ABI, using this option can help
24483 to find all affected types that need to be tagged.
24485 When a type involving an ABI tag is used as the type of a variable or
24486 return type of a function where that tag is not already present in the
24487 signature of the function, the tag is automatically applied to the
24488 variable or function. @option{-Wabi-tag} also warns about this
24489 situation; this warning can be avoided by explicitly tagging the
24490 variable or function or moving it into a tagged inline namespace.
24492 @item init_priority (@var{priority})
24493 @cindex @code{init_priority} variable attribute
24495 In Standard C++, objects defined at namespace scope are guaranteed to be
24496 initialized in an order in strict accordance with that of their definitions
24497 @emph{in a given translation unit}. No guarantee is made for initializations
24498 across translation units. However, GNU C++ allows users to control the
24499 order of initialization of objects defined at namespace scope with the
24500 @code{init_priority} attribute by specifying a relative @var{priority},
24501 a constant integral expression currently bounded between 101 and 65535
24502 inclusive. Lower numbers indicate a higher priority.
24504 In the following example, @code{A} would normally be created before
24505 @code{B}, but the @code{init_priority} attribute reverses that order:
24508 Some_Class A __attribute__ ((init_priority (2000)));
24509 Some_Class B __attribute__ ((init_priority (543)));
24513 Note that the particular values of @var{priority} do not matter; only their
24517 @cindex @code{warn_unused} type attribute
24519 For C++ types with non-trivial constructors and/or destructors it is
24520 impossible for the compiler to determine whether a variable of this
24521 type is truly unused if it is not referenced. This type attribute
24522 informs the compiler that variables of this type should be warned
24523 about if they appear to be unused, just like variables of fundamental
24526 This attribute is appropriate for types which just represent a value,
24527 such as @code{std::string}; it is not appropriate for types which
24528 control a resource, such as @code{std::lock_guard}.
24530 This attribute is also accepted in C, but it is unnecessary because C
24531 does not have constructors or destructors.
24535 @node Function Multiversioning
24536 @section Function Multiversioning
24537 @cindex function versions
24539 With the GNU C++ front end, for x86 targets, you may specify multiple
24540 versions of a function, where each function is specialized for a
24541 specific target feature. At runtime, the appropriate version of the
24542 function is automatically executed depending on the characteristics of
24543 the execution platform. Here is an example.
24546 __attribute__ ((target ("default")))
24549 // The default version of foo.
24553 __attribute__ ((target ("sse4.2")))
24556 // foo version for SSE4.2
24560 __attribute__ ((target ("arch=atom")))
24563 // foo version for the Intel ATOM processor
24567 __attribute__ ((target ("arch=amdfam10")))
24570 // foo version for the AMD Family 0x10 processors.
24577 assert ((*p) () == foo ());
24582 In the above example, four versions of function foo are created. The
24583 first version of foo with the target attribute "default" is the default
24584 version. This version gets executed when no other target specific
24585 version qualifies for execution on a particular platform. A new version
24586 of foo is created by using the same function signature but with a
24587 different target string. Function foo is called or a pointer to it is
24588 taken just like a regular function. GCC takes care of doing the
24589 dispatching to call the right version at runtime. Refer to the
24590 @uref{http://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
24591 Function Multiversioning} for more details.
24594 @section Type Traits
24596 The C++ front end implements syntactic extensions that allow
24597 compile-time determination of
24598 various characteristics of a type (or of a
24602 @item __has_nothrow_assign (type)
24603 If @code{type} is @code{const}-qualified or is a reference type then
24604 the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)}
24605 is @code{true} then the trait is @code{true}, else if @code{type} is
24606 a cv-qualified class or union type with copy assignment operators that are
24607 known not to throw an exception then the trait is @code{true}, else it is
24609 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24610 @code{void}, or an array of unknown bound.
24612 @item __has_nothrow_copy (type)
24613 If @code{__has_trivial_copy (type)} is @code{true} then the trait is
24614 @code{true}, else if @code{type} is a cv-qualified class or union type
24615 with copy constructors that are known not to throw an exception then
24616 the trait is @code{true}, else it is @code{false}.
24617 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24618 @code{void}, or an array of unknown bound.
24620 @item __has_nothrow_constructor (type)
24621 If @code{__has_trivial_constructor (type)} is @code{true} then the trait
24622 is @code{true}, else if @code{type} is a cv class or union type (or array
24623 thereof) with a default constructor that is known not to throw an
24624 exception then the trait is @code{true}, else it is @code{false}.
24625 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24626 @code{void}, or an array of unknown bound.
24628 @item __has_trivial_assign (type)
24629 If @code{type} is @code{const}- qualified or is a reference type then
24630 the trait is @code{false}. Otherwise if @code{__is_pod (type)} is
24631 @code{true} then the trait is @code{true}, else if @code{type} is
24632 a cv-qualified class or union type with a trivial copy assignment
24633 ([class.copy]) then the trait is @code{true}, else it is @code{false}.
24634 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24635 @code{void}, or an array of unknown bound.
24637 @item __has_trivial_copy (type)
24638 If @code{__is_pod (type)} is @code{true} or @code{type} is a reference
24639 type then the trait is @code{true}, else if @code{type} is a cv class
24640 or union type with a trivial copy constructor ([class.copy]) then the trait
24641 is @code{true}, else it is @code{false}. Requires: @code{type} shall be
24642 a complete type, (possibly cv-qualified) @code{void}, or an array of unknown
24645 @item __has_trivial_constructor (type)
24646 If @code{__is_pod (type)} is @code{true} then the trait is @code{true},
24647 else if @code{type} is a cv-qualified class or union type (or array thereof)
24648 with a trivial default constructor ([class.ctor]) then the trait is @code{true},
24649 else it is @code{false}.
24650 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24651 @code{void}, or an array of unknown bound.
24653 @item __has_trivial_destructor (type)
24654 If @code{__is_pod (type)} is @code{true} or @code{type} is a reference type
24655 then the trait is @code{true}, else if @code{type} is a cv class or union
24656 type (or array thereof) with a trivial destructor ([class.dtor]) then
24657 the trait is @code{true}, else it is @code{false}.
24658 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24659 @code{void}, or an array of unknown bound.
24661 @item __has_virtual_destructor (type)
24662 If @code{type} is a class type with a virtual destructor
24663 ([class.dtor]) then the trait is @code{true}, else it is @code{false}.
24664 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24665 @code{void}, or an array of unknown bound.
24667 @item __is_abstract (type)
24668 If @code{type} is an abstract class ([class.abstract]) then the trait
24669 is @code{true}, else it is @code{false}.
24670 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24671 @code{void}, or an array of unknown bound.
24673 @item __is_base_of (base_type, derived_type)
24674 If @code{base_type} is a base class of @code{derived_type}
24675 ([class.derived]) then the trait is @code{true}, otherwise it is @code{false}.
24676 Top-level cv-qualifications of @code{base_type} and
24677 @code{derived_type} are ignored. For the purposes of this trait, a
24678 class type is considered is own base.
24679 Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)}
24680 are @code{true} and @code{base_type} and @code{derived_type} are not the same
24681 type (disregarding cv-qualifiers), @code{derived_type} shall be a complete
24682 type. A diagnostic is produced if this requirement is not met.
24684 @item __is_class (type)
24685 If @code{type} is a cv-qualified class type, and not a union type
24686 ([basic.compound]) the trait is @code{true}, else it is @code{false}.
24688 @item __is_empty (type)
24689 If @code{__is_class (type)} is @code{false} then the trait is @code{false}.
24690 Otherwise @code{type} is considered empty if and only if: @code{type}
24691 has no non-static data members, or all non-static data members, if
24692 any, are bit-fields of length 0, and @code{type} has no virtual
24693 members, and @code{type} has no virtual base classes, and @code{type}
24694 has no base classes @code{base_type} for which
24695 @code{__is_empty (base_type)} is @code{false}.
24696 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24697 @code{void}, or an array of unknown bound.
24699 @item __is_enum (type)
24700 If @code{type} is a cv enumeration type ([basic.compound]) the trait is
24701 @code{true}, else it is @code{false}.
24703 @item __is_literal_type (type)
24704 If @code{type} is a literal type ([basic.types]) the trait is
24705 @code{true}, else it is @code{false}.
24706 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24707 @code{void}, or an array of unknown bound.
24709 @item __is_pod (type)
24710 If @code{type} is a cv POD type ([basic.types]) then the trait is @code{true},
24711 else it is @code{false}.
24712 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24713 @code{void}, or an array of unknown bound.
24715 @item __is_polymorphic (type)
24716 If @code{type} is a polymorphic class ([class.virtual]) then the trait
24717 is @code{true}, else it is @code{false}.
24718 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24719 @code{void}, or an array of unknown bound.
24721 @item __is_standard_layout (type)
24722 If @code{type} is a standard-layout type ([basic.types]) the trait is
24723 @code{true}, else it is @code{false}.
24724 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24725 @code{void}, or an array of unknown bound.
24727 @item __is_trivial (type)
24728 If @code{type} is a trivial type ([basic.types]) the trait is
24729 @code{true}, else it is @code{false}.
24730 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
24731 @code{void}, or an array of unknown bound.
24733 @item __is_union (type)
24734 If @code{type} is a cv union type ([basic.compound]) the trait is
24735 @code{true}, else it is @code{false}.
24737 @item __underlying_type (type)
24738 The underlying type of @code{type}.
24739 Requires: @code{type} shall be an enumeration type ([dcl.enum]).
24741 @item __integer_pack (length)
24742 When used as the pattern of a pack expansion within a template
24743 definition, expands to a template argument pack containing integers
24744 from @code{0} to @code{length-1}. This is provided for efficient
24745 implementation of @code{std::make_integer_sequence}.
24751 @section C++ Concepts
24753 C++ concepts provide much-improved support for generic programming. In
24754 particular, they allow the specification of constraints on template arguments.
24755 The constraints are used to extend the usual overloading and partial
24756 specialization capabilities of the language, allowing generic data structures
24757 and algorithms to be ``refined'' based on their properties rather than their
24760 The following keywords are reserved for concepts.
24764 States an expression as an assumption, and if possible, verifies that the
24765 assumption is valid. For example, @code{assume(n > 0)}.
24768 Introduces an axiom definition. Axioms introduce requirements on values.
24771 Introduces a universally quantified object in an axiom. For example,
24772 @code{forall (int n) n + 0 == n}).
24775 Introduces a concept definition. Concepts are sets of syntactic and semantic
24776 requirements on types and their values.
24779 Introduces constraints on template arguments or requirements for a member
24780 function of a class template.
24784 The front end also exposes a number of internal mechanism that can be used
24785 to simplify the writing of type traits. Note that some of these traits are
24786 likely to be removed in the future.
24789 @item __is_same (type1, type2)
24790 A binary type trait: @code{true} whenever the type arguments are the same.
24795 @node Deprecated Features
24796 @section Deprecated Features
24798 In the past, the GNU C++ compiler was extended to experiment with new
24799 features, at a time when the C++ language was still evolving. Now that
24800 the C++ standard is complete, some of those features are superseded by
24801 superior alternatives. Using the old features might cause a warning in
24802 some cases that the feature will be dropped in the future. In other
24803 cases, the feature might be gone already.
24805 G++ allows a virtual function returning @samp{void *} to be overridden
24806 by one returning a different pointer type. This extension to the
24807 covariant return type rules is now deprecated and will be removed from a
24810 The use of default arguments in function pointers, function typedefs
24811 and other places where they are not permitted by the standard is
24812 deprecated and will be removed from a future version of G++.
24814 G++ allows floating-point literals to appear in integral constant expressions,
24815 e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} }
24816 This extension is deprecated and will be removed from a future version.
24818 G++ allows static data members of const floating-point type to be declared
24819 with an initializer in a class definition. The standard only allows
24820 initializers for static members of const integral types and const
24821 enumeration types so this extension has been deprecated and will be removed
24822 from a future version.
24824 G++ allows attributes to follow a parenthesized direct initializer,
24825 e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension
24826 has been ignored since G++ 3.3 and is deprecated.
24828 G++ allows anonymous structs and unions to have members that are not
24829 public non-static data members (i.e.@: fields). These extensions are
24832 @node Backwards Compatibility
24833 @section Backwards Compatibility
24834 @cindex Backwards Compatibility
24835 @cindex ARM [Annotated C++ Reference Manual]
24837 Now that there is a definitive ISO standard C++, G++ has a specification
24838 to adhere to. The C++ language evolved over time, and features that
24839 used to be acceptable in previous drafts of the standard, such as the ARM
24840 [Annotated C++ Reference Manual], are no longer accepted. In order to allow
24841 compilation of C++ written to such drafts, G++ contains some backwards
24842 compatibilities. @emph{All such backwards compatibility features are
24843 liable to disappear in future versions of G++.} They should be considered
24844 deprecated. @xref{Deprecated Features}.
24848 @item Implicit C language
24849 Old C system header files did not contain an @code{extern "C" @{@dots{}@}}
24850 scope to set the language. On such systems, all system header files are
24851 implicitly scoped inside a C language scope. Such headers must
24852 correctly prototype function argument types, there is no leeway for
24853 @code{()} to indicate an unspecified set of arguments.
24857 @c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd
24858 @c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr