1 @c Copyright (C) 1988-2024 Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
7 @chapter Extensions to the C Language Family
8 @cindex extensions, C language
9 @cindex C language extensions
12 GNU C provides several language features not found in ISO standard C@.
13 (The @option{-pedantic} option directs GCC to print a warning message if
14 any of these features is used.) To test for the availability of these
15 features in conditional compilation, check for a predefined macro
16 @code{__GNUC__}, which is always defined under GCC@.
18 These extensions are available in C and Objective-C@. Most of them are
19 also available in C++. @xref{C++ Extensions,,Extensions to the
20 C++ Language}, for extensions that apply @emph{only} to C++.
22 Some features that are in ISO C99 but not C90 or C++ are also, as
23 extensions, accepted by GCC in C90 mode and in C++.
26 * Statement Exprs:: Putting statements and declarations inside expressions.
27 * Local Labels:: Labels local to a block.
28 * Labels as Values:: Getting pointers to labels, and computed gotos.
29 * Nested Functions:: Nested function in GNU C.
30 * Nonlocal Gotos:: Nonlocal gotos.
31 * Constructing Calls:: Dispatching a call to another function.
32 * Typeof:: @code{typeof}: referring to the type of an expression.
33 * Conditionals:: Omitting the middle operand of a @samp{?:} expression.
34 * __int128:: 128-bit integers---@code{__int128}.
35 * Long Long:: Double-word integers---@code{long long int}.
36 * Complex:: Data types for complex numbers.
37 * Floating Types:: Additional Floating Types.
38 * Half-Precision:: Half-Precision Floating Point.
39 * Decimal Float:: Decimal Floating Types.
40 * Hex Floats:: Hexadecimal floating-point constants.
41 * Fixed-Point:: Fixed-Point Types.
42 * Named Address Spaces::Named address spaces.
43 * Zero Length:: Zero-length arrays.
44 * Empty Structures:: Structures with no members.
45 * Variable Length:: Arrays whose length is computed at run time.
46 * Variadic Macros:: Macros with a variable number of arguments.
47 * Escaped Newlines:: Slightly looser rules for escaped newlines.
48 * Subscripting:: Any array can be subscripted, even if not an lvalue.
49 * Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
50 * Variadic Pointer Args:: Pointer arguments to variadic functions.
51 * Pointers to Arrays:: Pointers to arrays with qualifiers work as expected.
52 * Initializers:: Non-constant initializers.
53 * Compound Literals:: Compound literals give structures, unions
55 * Designated Inits:: Labeling elements of initializers.
56 * Case Ranges:: `case 1 ... 9' and such.
57 * Cast to Union:: Casting to union type from any member of the union.
58 * Mixed Labels and Declarations:: Mixing declarations, labels and code.
59 * Function Attributes:: Declaring that functions have no side effects,
60 or that they can never return.
61 * Variable Attributes:: Specifying attributes of variables.
62 * Type Attributes:: Specifying attributes of types.
63 * Label Attributes:: Specifying attributes on labels.
64 * Enumerator Attributes:: Specifying attributes on enumerators.
65 * Statement Attributes:: Specifying attributes on statements.
66 * Attribute Syntax:: Formal syntax for attributes.
67 * Function Prototypes:: Prototype declarations and old-style definitions.
68 * C++ Comments:: C++ comments are recognized.
69 * Dollar Signs:: Dollar sign is allowed in identifiers.
70 * Character Escapes:: @samp{\e} stands for the character @key{ESC}.
71 * Alignment:: Determining the alignment of a function, type or variable.
72 * Inline:: Defining inline functions (as fast as macros).
73 * Const and Volatile Functions :: GCC interprets these specially in C.
74 * Volatiles:: What constitutes an access to a volatile object.
75 * Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler.
76 * Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
77 * Incomplete Enums:: @code{enum foo;}, with details to follow.
78 * Function Names:: Printable strings which are the name of the current
80 * Return Address:: Getting the return or frame address of a function.
81 * Stack Scrubbing:: Stack scrubbing internal interfaces.
82 * Vector Extensions:: Using vector instructions through built-in functions.
83 * Offsetof:: Special syntax for implementing @code{offsetof}.
84 * __sync Builtins:: Legacy built-in functions for atomic memory access.
85 * __atomic Builtins:: Atomic built-in functions with memory model.
86 * Integer Overflow Builtins:: Built-in functions to perform arithmetics and
87 arithmetic overflow checking.
88 * x86 specific memory model extensions for transactional memory:: x86 memory models.
89 * Object Size Checking:: Built-in functions for limited buffer overflow
91 * Other Builtins:: Other built-in functions.
92 * Target Builtins:: Built-in functions specific to particular targets.
93 * Target Format Checks:: Format checks specific to particular targets.
94 * Pragmas:: Pragmas accepted by GCC.
95 * Unnamed Fields:: Unnamed struct/union fields within structs/unions.
96 * Thread-Local:: Per-thread variables.
97 * Binary constants:: Binary constants using the @samp{0b} prefix.
100 @node Statement Exprs
101 @section Statements and Declarations in Expressions
102 @cindex statements inside expressions
103 @cindex declarations inside expressions
104 @cindex expressions containing statements
105 @cindex macros, statements in expressions
107 @c the above section title wrapped and causes an underfull hbox.. i
108 @c changed it from "within" to "in". --mew 4feb93
109 A compound statement enclosed in parentheses may appear as an expression
110 in GNU C@. This allows you to use loops, switches, and local variables
111 within an expression.
113 Recall that a compound statement is a sequence of statements surrounded
114 by braces; in this construct, parentheses go around the braces. For
118 (@{ int y = foo (); int z;
125 is a valid (though slightly more complex than necessary) expression
126 for the absolute value of @code{foo ()}.
128 The last thing in the compound statement should be an expression
129 followed by a semicolon; the value of this subexpression serves as the
130 value of the entire construct. (If you use some other kind of statement
131 last within the braces, the construct has type @code{void}, and thus
132 effectively no value.)
134 This feature is especially useful in making macro definitions ``safe'' (so
135 that they evaluate each operand exactly once). For example, the
136 ``maximum'' function is commonly defined as a macro in standard C as
140 #define max(a,b) ((a) > (b) ? (a) : (b))
144 @cindex side effects, macro argument
145 But this definition computes either @var{a} or @var{b} twice, with bad
146 results if the operand has side effects. In GNU C, if you know the
147 type of the operands (here taken as @code{int}), you can avoid this
148 problem by defining the macro as follows:
151 #define maxint(a,b) \
152 (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
155 Note that introducing variable declarations (as we do in @code{maxint}) can
156 cause variable shadowing, so while this example using the @code{max} macro
157 produces correct results:
159 int _a = 1, _b = 2, c;
163 this example using maxint will not:
165 int _a = 1, _b = 2, c;
169 This problem may for instance occur when we use this pattern recursively, like
173 #define maxint3(a, b, c) \
174 (@{int _a = (a), _b = (b), _c = (c); maxint (maxint (_a, _b), _c); @})
177 Embedded statements are not allowed in constant expressions, such as
178 the value of an enumeration constant, the width of a bit-field, or
179 the initial value of a static variable.
181 If you don't know the type of the operand, you can still do this, but you
182 must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}).
184 In G++, the result value of a statement expression undergoes array and
185 function pointer decay, and is returned by value to the enclosing
186 expression. For instance, if @code{A} is a class, then
195 constructs a temporary @code{A} object to hold the result of the
196 statement expression, and that is used to invoke @code{Foo}.
197 Therefore the @code{this} pointer observed by @code{Foo} is not the
200 In a statement expression, any temporaries created within a statement
201 are destroyed at that statement's end. This makes statement
202 expressions inside macros slightly different from function calls. In
203 the latter case temporaries introduced during argument evaluation are
204 destroyed at the end of the statement that includes the function
205 call. In the statement expression case they are destroyed during
206 the statement expression. For instance,
209 #define macro(a) (@{__typeof__(a) b = (a); b + 3; @})
210 template<typename T> T function(T a) @{ T b = a; return b + 3; @}
220 has different places where temporaries are destroyed. For the
221 @code{macro} case, the temporary @code{X} is destroyed just after
222 the initialization of @code{b}. In the @code{function} case that
223 temporary is destroyed when the function returns.
225 These considerations mean that it is probably a bad idea to use
226 statement expressions of this form in header files that are designed to
227 work with C++. (Note that some versions of the GNU C Library contained
228 header files using statement expressions that lead to precisely this
231 Jumping into a statement expression with @code{goto} or using a
232 @code{switch} statement outside the statement expression with a
233 @code{case} or @code{default} label inside the statement expression is
234 not permitted. Jumping into a statement expression with a computed
235 @code{goto} (@pxref{Labels as Values}) has undefined behavior.
236 Jumping out of a statement expression is permitted, but if the
237 statement expression is part of a larger expression then it is
238 unspecified which other subexpressions of that expression have been
239 evaluated except where the language definition requires certain
240 subexpressions to be evaluated before or after the statement
241 expression. A @code{break} or @code{continue} statement inside of
242 a statement expression used in @code{while}, @code{do} or @code{for}
243 loop or @code{switch} statement condition
244 or @code{for} statement init or increment expressions jumps to an
245 outer loop or @code{switch} statement if any (otherwise it is an error),
246 rather than to the loop or @code{switch} statement in whose condition
247 or init or increment expression it appears.
248 In any case, as with a function call, the evaluation of a
249 statement expression is not interleaved with the evaluation of other
250 parts of the containing expression. For example,
253 foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz();
257 calls @code{foo} and @code{bar1} and does not call @code{baz} but
258 may or may not call @code{bar2}. If @code{bar2} is called, it is
259 called after @code{foo} and before @code{bar1}.
262 @section Locally Declared Labels
264 @cindex macros, local labels
266 GCC allows you to declare @dfn{local labels} in any nested block
267 scope. A local label is just like an ordinary label, but you can
268 only reference it (with a @code{goto} statement, or by taking its
269 address) within the block in which it is declared.
271 A local label declaration looks like this:
274 __label__ @var{label};
281 __label__ @var{label1}, @var{label2}, /* @r{@dots{}} */;
284 Local label declarations must come at the beginning of the block,
285 before any ordinary declarations or statements.
287 The label declaration defines the label @emph{name}, but does not define
288 the label itself. You must do this in the usual way, with
289 @code{@var{label}:}, within the statements of the statement expression.
291 The local label feature is useful for complex macros. If a macro
292 contains nested loops, a @code{goto} can be useful for breaking out of
293 them. However, an ordinary label whose scope is the whole function
294 cannot be used: if the macro can be expanded several times in one
295 function, the label is multiply defined in that function. A
296 local label avoids this problem. For example:
299 #define SEARCH(value, array, target) \
302 typeof (target) _SEARCH_target = (target); \
303 typeof (*(array)) *_SEARCH_array = (array); \
306 for (i = 0; i < max; i++) \
307 for (j = 0; j < max; j++) \
308 if (_SEARCH_array[i][j] == _SEARCH_target) \
309 @{ (value) = i; goto found; @} \
315 This could also be written using a statement expression:
318 #define SEARCH(array, target) \
321 typeof (target) _SEARCH_target = (target); \
322 typeof (*(array)) *_SEARCH_array = (array); \
325 for (i = 0; i < max; i++) \
326 for (j = 0; j < max; j++) \
327 if (_SEARCH_array[i][j] == _SEARCH_target) \
328 @{ value = i; goto found; @} \
335 Local label declarations also make the labels they declare visible to
336 nested functions, if there are any. @xref{Nested Functions}, for details.
338 @node Labels as Values
339 @section Labels as Values
340 @cindex labels as values
341 @cindex computed gotos
342 @cindex goto with computed label
343 @cindex address of a label
345 You can get the address of a label defined in the current function
346 (or a containing function) with the unary operator @samp{&&}. The
347 value has type @code{void *}. This value is a constant and can be used
348 wherever a constant of that type is valid. For example:
356 To use these values, you need to be able to jump to one. This is done
357 with the computed goto statement@footnote{The analogous feature in
358 Fortran is called an assigned goto, but that name seems inappropriate in
359 C, where one can do more than simply store label addresses in label
360 variables.}, @code{goto *@var{exp};}. For example,
367 Any expression of type @code{void *} is allowed.
369 One way of using these constants is in initializing a static array that
370 serves as a jump table:
373 static void *array[] = @{ &&foo, &&bar, &&hack @};
377 Then you can select a label with indexing, like this:
384 Note that this does not check whether the subscript is in bounds---array
385 indexing in C never does that.
387 Such an array of label values serves a purpose much like that of the
388 @code{switch} statement. The @code{switch} statement is cleaner, so
389 use that rather than an array unless the problem does not fit a
390 @code{switch} statement very well.
392 Another use of label values is in an interpreter for threaded code.
393 The labels within the interpreter function can be stored in the
394 threaded code for super-fast dispatching.
396 You may not use this mechanism to jump to code in a different function.
397 If you do that, totally unpredictable things happen. The best way to
398 avoid this is to store the label address only in automatic variables and
399 never pass it as an argument.
401 An alternate way to write the above example is
404 static const int array[] = @{ &&foo - &&foo, &&bar - &&foo,
406 goto *(&&foo + array[i]);
410 This is more friendly to code living in shared libraries, as it reduces
411 the number of dynamic relocations that are needed, and by consequence,
412 allows the data to be read-only.
413 This alternative with label differences is not supported for the AVR target,
414 please use the first approach for AVR programs.
416 The @code{&&foo} expressions for the same label might have different
417 values if the containing function is inlined or cloned. If a program
418 relies on them being always the same,
419 @code{__attribute__((__noinline__,__noclone__))} should be used to
420 prevent inlining and cloning. If @code{&&foo} is used in a static
421 variable initializer, inlining and cloning is forbidden.
423 Unlike a normal goto, in GNU C++ a computed goto will not call
424 destructors for objects that go out of scope.
426 @node Nested Functions
427 @section Nested Functions
428 @cindex nested functions
429 @cindex downward funargs
432 A @dfn{nested function} is a function defined inside another function.
433 Nested functions are supported as an extension in GNU C, but are not
434 supported by GNU C++.
436 The nested function's name is local to the block where it is defined.
437 For example, here we define a nested function named @code{square}, and
442 foo (double a, double b)
444 double square (double z) @{ return z * z; @}
446 return square (a) + square (b);
451 The nested function can access all the variables of the containing
452 function that are visible at the point of its definition. This is
453 called @dfn{lexical scoping}. For example, here we show a nested
454 function which uses an inherited variable named @code{offset}:
458 bar (int *array, int offset, int size)
460 int access (int *array, int index)
461 @{ return array[index + offset]; @}
464 for (i = 0; i < size; i++)
465 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
470 Nested function definitions are permitted within functions in the places
471 where variable definitions are allowed; that is, in any block, mixed
472 with the other declarations and statements in the block.
474 It is possible to call the nested function from outside the scope of its
475 name by storing its address or passing the address to another function:
478 hack (int *array, int size)
480 void store (int index, int value)
481 @{ array[index] = value; @}
483 intermediate (store, size);
487 Here, the function @code{intermediate} receives the address of
488 @code{store} as an argument. If @code{intermediate} calls @code{store},
489 the arguments given to @code{store} are used to store into @code{array}.
490 But this technique works only so long as the containing function
491 (@code{hack}, in this example) does not exit.
493 If you try to call the nested function through its address after the
494 containing function exits, all hell breaks loose. If you try
495 to call it after a containing scope level exits, and if it refers
496 to some of the variables that are no longer in scope, you may be lucky,
497 but it's not wise to take the risk. If, however, the nested function
498 does not refer to anything that has gone out of scope, you should be
501 GCC implements taking the address of a nested function using a technique
502 called @dfn{trampolines}. This technique was described in
503 @cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX
504 C++ Conference Proceedings, October 17-21, 1988).
506 A nested function can jump to a label inherited from a containing
507 function, provided the label is explicitly declared in the containing
508 function (@pxref{Local Labels}). Such a jump returns instantly to the
509 containing function, exiting the nested function that did the
510 @code{goto} and any intermediate functions as well. Here is an example:
514 bar (int *array, int offset, int size)
517 int access (int *array, int index)
521 return array[index + offset];
525 for (i = 0; i < size; i++)
526 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
530 /* @r{Control comes here from @code{access}
531 if it detects an error.} */
538 A nested function always has no linkage. Declaring one with
539 @code{extern} or @code{static} is erroneous. If you need to declare the nested function
540 before its definition, use @code{auto} (which is otherwise meaningless
541 for function declarations).
544 bar (int *array, int offset, int size)
547 auto int access (int *, int);
549 int access (int *array, int index)
553 return array[index + offset];
560 @section Nonlocal Gotos
561 @cindex nonlocal gotos
563 GCC provides the built-in functions @code{__builtin_setjmp} and
564 @code{__builtin_longjmp} which are similar to, but not interchangeable
565 with, the C library functions @code{setjmp} and @code{longjmp}.
566 The built-in versions are used internally by GCC's libraries
567 to implement exception handling on some targets. You should use the
568 standard C library functions declared in @code{<setjmp.h>} in user code
569 instead of the builtins.
571 The built-in versions of these functions use GCC's normal
572 mechanisms to save and restore registers using the stack on function
573 entry and exit. The jump buffer argument @var{buf} holds only the
574 information needed to restore the stack frame, rather than the entire
575 set of saved register values.
577 An important caveat is that GCC arranges to save and restore only
578 those registers known to the specific architecture variant being
579 compiled for. This can make @code{__builtin_setjmp} and
580 @code{__builtin_longjmp} more efficient than their library
581 counterparts in some cases, but it can also cause incorrect and
582 mysterious behavior when mixing with code that uses the full register
585 You should declare the jump buffer argument @var{buf} to the
586 built-in functions as:
590 intptr_t @var{buf}[5];
593 @defbuiltin{{int} __builtin_setjmp (intptr_t *@var{buf})}
594 This function saves the current stack context in @var{buf}.
595 @code{__builtin_setjmp} returns 0 when returning directly,
596 and 1 when returning from @code{__builtin_longjmp} using the same
600 @defbuiltin{{void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val})}
601 This function restores the stack context in @var{buf},
602 saved by a previous call to @code{__builtin_setjmp}. After
603 @code{__builtin_longjmp} is finished, the program resumes execution as
604 if the matching @code{__builtin_setjmp} returns the value @var{val},
607 Because @code{__builtin_longjmp} depends on the function return
608 mechanism to restore the stack context, it cannot be called
609 from the same function calling @code{__builtin_setjmp} to
610 initialize @var{buf}. It can only be called from a function called
611 (directly or indirectly) from the function calling @code{__builtin_setjmp}.
614 @node Constructing Calls
615 @section Constructing Function Calls
616 @cindex constructing calls
617 @cindex forwarding calls
619 Using the built-in functions described below, you can record
620 the arguments a function received, and call another function
621 with the same arguments, without knowing the number or types
624 You can also record the return value of that function call,
625 and later return that value, without knowing what data type
626 the function tried to return (as long as your caller expects
629 However, these built-in functions may interact badly with some
630 sophisticated features or other extensions of the language. It
631 is, therefore, not recommended to use them outside very simple
632 functions acting as mere forwarders for their arguments.
634 @defbuiltin{{void *} __builtin_apply_args ()}
635 This built-in function returns a pointer to data
636 describing how to perform a call with the same arguments as are passed
637 to the current function.
639 The function saves the arg pointer register, structure value address,
640 and all registers that might be used to pass arguments to a function
641 into a block of memory allocated on the stack. Then it returns the
642 address of that block.
645 @defbuiltin{{void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})}
646 This built-in function invokes @var{function}
647 with a copy of the parameters described by @var{arguments}
650 The value of @var{arguments} should be the value returned by
651 @code{__builtin_apply_args}. The argument @var{size} specifies the size
652 of the stack argument data, in bytes.
654 This function returns a pointer to data describing
655 how to return whatever value is returned by @var{function}. The data
656 is saved in a block of memory allocated on the stack.
658 It is not always simple to compute the proper value for @var{size}. The
659 value is used by @code{__builtin_apply} to compute the amount of data
660 that should be pushed on the stack and copied from the incoming argument
664 @defbuiltin{{void} __builtin_return (void *@var{result})}
665 This built-in function returns the value described by @var{result} from
666 the containing function. You should specify, for @var{result}, a value
667 returned by @code{__builtin_apply}.
670 @defbuiltin{{} __builtin_va_arg_pack ()}
671 This built-in function represents all anonymous arguments of an inline
672 function. It can be used only in inline functions that are always
673 inlined, never compiled as a separate function, such as those using
674 @code{__attribute__ ((__always_inline__))} or
675 @code{__attribute__ ((__gnu_inline__))} extern inline functions.
676 It must be only passed as last argument to some other function
677 with variable arguments. This is useful for writing small wrapper
678 inlines for variable argument functions, when using preprocessor
679 macros is undesirable. For example:
681 extern int myprintf (FILE *f, const char *format, ...);
682 extern inline __attribute__ ((__gnu_inline__)) int
683 myprintf (FILE *f, const char *format, ...)
685 int r = fprintf (f, "myprintf: ");
688 int s = fprintf (f, format, __builtin_va_arg_pack ());
696 @defbuiltin{int __builtin_va_arg_pack_len ()}
697 This built-in function returns the number of anonymous arguments of
698 an inline function. It can be used only in inline functions that
699 are always inlined, never compiled as a separate function, such
700 as those using @code{__attribute__ ((__always_inline__))} or
701 @code{__attribute__ ((__gnu_inline__))} extern inline functions.
702 For example following does link- or run-time checking of open
703 arguments for optimized code:
706 extern inline __attribute__((__gnu_inline__)) int
707 myopen (const char *path, int oflag, ...)
709 if (__builtin_va_arg_pack_len () > 1)
710 warn_open_too_many_arguments ();
712 if (__builtin_constant_p (oflag))
714 if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1)
716 warn_open_missing_mode ();
717 return __open_2 (path, oflag);
719 return open (path, oflag, __builtin_va_arg_pack ());
722 if (__builtin_va_arg_pack_len () < 1)
723 return __open_2 (path, oflag);
725 return open (path, oflag, __builtin_va_arg_pack ());
732 @section Referring to a Type with @code{typeof}
735 @cindex macros, types of arguments
737 Another way to refer to the type of an expression is with @code{typeof}.
738 The syntax of using of this keyword looks like @code{sizeof}, but the
739 construct acts semantically like a type name defined with @code{typedef}.
741 There are two ways of writing the argument to @code{typeof}: with an
742 expression or with a type. Here is an example with an expression:
749 This assumes that @code{x} is an array of pointers to functions;
750 the type described is that of the values of the functions.
752 Here is an example with a typename as the argument:
759 Here the type described is that of pointers to @code{int}.
761 If you are writing a header file that must work when included in ISO C
762 programs, write @code{__typeof__} instead of @code{typeof}.
763 @xref{Alternate Keywords}.
765 A @code{typeof} construct can be used anywhere a typedef name can be
766 used. For example, you can use it in a declaration, in a cast, or inside
767 of @code{sizeof} or @code{typeof}.
769 The operand of @code{typeof} is evaluated for its side effects if and
770 only if it is an expression of variably modified type or the name of
773 @code{typeof} is often useful in conjunction with
774 statement expressions (@pxref{Statement Exprs}).
775 Here is how the two together can
776 be used to define a safe ``maximum'' macro which operates on any
777 arithmetic type and evaluates each of its arguments exactly once:
781 (@{ typeof (a) _a = (a); \
782 typeof (b) _b = (b); \
783 _a > _b ? _a : _b; @})
786 @cindex underscores in variables in macros
787 @cindex @samp{_} in variables in macros
788 @cindex local variables in macros
789 @cindex variables, local, in macros
790 @cindex macros, local variables in
792 The reason for using names that start with underscores for the local
793 variables is to avoid conflicts with variable names that occur within the
794 expressions that are substituted for @code{a} and @code{b}. Eventually we
795 hope to design a new form of declaration syntax that allows you to declare
796 variables whose scopes start only after their initializers; this will be a
797 more reliable way to prevent such conflicts.
800 Some more examples of the use of @code{typeof}:
804 This declares @code{y} with the type of what @code{x} points to.
811 This declares @code{y} as an array of such values.
818 This declares @code{y} as an array of pointers to characters:
821 typeof (typeof (char *)[4]) y;
825 It is equivalent to the following traditional C declaration:
831 To see the meaning of the declaration using @code{typeof}, and why it
832 might be a useful way to write, rewrite it with these macros:
835 #define pointer(T) typeof(T *)
836 #define array(T, N) typeof(T [N])
840 Now the declaration can be rewritten this way:
843 array (pointer (char), 4) y;
847 Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
848 pointers to @code{char}.
851 The ISO C23 operator @code{typeof_unqual} is available in ISO C23 mode
852 and its result is the non-atomic unqualified version of what @code{typeof}
853 operator returns. Alternate spelling @code{__typeof_unqual__} is
854 available in all C modes and provides non-atomic unqualified version of
855 what @code{__typeof__} operator returns.
856 @xref{Alternate Keywords}.
858 @cindex @code{__auto_type} in GNU C
859 In GNU C, but not GNU C++, you may also declare the type of a variable
860 as @code{__auto_type}. In that case, the declaration must declare
861 only one variable, whose declarator must just be an identifier, the
862 declaration must be initialized, and the type of the variable is
863 determined by the initializer; the name of the variable is not in
864 scope until after the initializer. (In C++, you should use C++11
865 @code{auto} for this purpose.) Using @code{__auto_type}, the
866 ``maximum'' macro above could be written as:
870 (@{ __auto_type _a = (a); \
871 __auto_type _b = (b); \
872 _a > _b ? _a : _b; @})
875 Using @code{__auto_type} instead of @code{typeof} has two advantages:
878 @item Each argument to the macro appears only once in the expansion of
879 the macro. This prevents the size of the macro expansion growing
880 exponentially when calls to such macros are nested inside arguments of
883 @item If the argument to the macro has variably modified type, it is
884 evaluated only once when using @code{__auto_type}, but twice if
885 @code{typeof} is used.
889 @section Conditionals with Omitted Operands
890 @cindex conditional expressions, extensions
891 @cindex omitted middle-operands
892 @cindex middle-operands, omitted
893 @cindex extensions, @code{?:}
894 @cindex @code{?:} extensions
896 The middle operand in a conditional expression may be omitted. Then
897 if the first operand is nonzero, its value is the value of the conditional
900 Therefore, the expression
907 has the value of @code{x} if that is nonzero; otherwise, the value of
910 This example is perfectly equivalent to
916 @cindex side effect in @code{?:}
917 @cindex @code{?:} side effect
919 In this simple case, the ability to omit the middle operand is not
920 especially useful. When it becomes useful is when the first operand does,
921 or may (if it is a macro argument), contain a side effect. Then repeating
922 the operand in the middle would perform the side effect twice. Omitting
923 the middle operand uses the value already computed without the undesirable
924 effects of recomputing it.
927 @section 128-bit Integers
928 @cindex @code{__int128} data types
930 As an extension the integer scalar type @code{__int128} is supported for
931 targets which have an integer mode wide enough to hold 128 bits.
932 Simply write @code{__int128} for a signed 128-bit integer, or
933 @code{unsigned __int128} for an unsigned 128-bit integer. There is no
934 support in GCC for expressing an integer constant of type @code{__int128}
935 for targets with @code{long long} integer less than 128 bits wide.
938 @section Double-Word Integers
939 @cindex @code{long long} data types
940 @cindex double-word arithmetic
941 @cindex multiprecision arithmetic
942 @cindex @code{LL} integer suffix
943 @cindex @code{ULL} integer suffix
945 ISO C99 and ISO C++11 support data types for integers that are at least
946 64 bits wide, and as an extension GCC supports them in C90 and C++98 modes.
947 Simply write @code{long long int} for a signed integer, or
948 @code{unsigned long long int} for an unsigned integer. To make an
949 integer constant of type @code{long long int}, add the suffix @samp{LL}
950 to the integer. To make an integer constant of type @code{unsigned long
951 long int}, add the suffix @samp{ULL} to the integer.
953 You can use these types in arithmetic like any other integer types.
954 Addition, subtraction, and bitwise boolean operations on these types
955 are open-coded on all types of machines. Multiplication is open-coded
956 if the machine supports a fullword-to-doubleword widening multiply
957 instruction. Division and shifts are open-coded only on machines that
958 provide special support. The operations that are not open-coded use
959 special library routines that come with GCC@.
961 There may be pitfalls when you use @code{long long} types for function
962 arguments without function prototypes. If a function
963 expects type @code{int} for its argument, and you pass a value of type
964 @code{long long int}, confusion results because the caller and the
965 subroutine disagree about the number of bytes for the argument.
966 Likewise, if the function expects @code{long long int} and you pass
967 @code{int}. The best way to avoid such problems is to use prototypes.
970 @section Complex Numbers
971 @cindex complex numbers
972 @cindex @code{_Complex} keyword
973 @cindex @code{__complex__} keyword
975 ISO C99 supports complex floating data types, and as an extension GCC
976 supports them in C90 mode and in C++. GCC also supports complex integer data
977 types which are not part of ISO C99. You can declare complex types
978 using the keyword @code{_Complex}. As an extension, the older GNU
979 keyword @code{__complex__} is also supported.
981 For example, @samp{_Complex double x;} declares @code{x} as a
982 variable whose real part and imaginary part are both of type
983 @code{double}. @samp{_Complex short int y;} declares @code{y} to
984 have real and imaginary parts of type @code{short int}; this is not
985 likely to be useful, but it shows that the set of complex types is
988 To write a constant with a complex data type, use the suffix @samp{i} or
989 @samp{j} (either one; they are equivalent). For example, @code{2.5fi}
990 has type @code{_Complex float} and @code{3i} has type
991 @code{_Complex int}. Such a constant always has a pure imaginary
992 value, but you can form any complex value you like by adding one to a
993 real constant. This is a GNU extension; if you have an ISO C99
994 conforming C library (such as the GNU C Library), and want to construct complex
995 constants of floating type, you should include @code{<complex.h>} and
996 use the macros @code{I} or @code{_Complex_I} instead.
998 The ISO C++14 library also defines the @samp{i} suffix, so C++14 code
999 that includes the @samp{<complex>} header cannot use @samp{i} for the
1000 GNU extension. The @samp{j} suffix still has the GNU meaning.
1002 GCC can handle both implicit and explicit casts between the @code{_Complex}
1003 types and other @code{_Complex} types as casting both the real and imaginary
1004 parts to the scalar type.
1005 GCC can handle implicit and explicit casts from a scalar type to a @code{_Complex}
1006 type and where the imaginary part will be considered zero.
1007 The C front-end can handle implicit and explicit casts from a @code{_Complex} type
1008 to a scalar type where the imaginary part will be ignored. In C++ code, this cast
1009 is considered illformed and G++ will error out.
1011 GCC provides a built-in function @code{__builtin_complex} will can be used to
1012 construct a complex value.
1014 @cindex @code{__real__} keyword
1015 @cindex @code{__imag__} keyword
1017 GCC has a few extensions which can be used to extract the real
1018 and the imaginary part of the complex-valued expression. Note
1019 these expressions are lvalues if the @var{exp} is an lvalue.
1020 These expressions operands have the type of a complex type
1021 which might get prompoted to a complex type from a scalar type.
1022 E.g. @code{__real__ (int)@var{x}} is the same as casting to
1023 @code{_Complex int} before @code{__real__} is done.
1025 @multitable @columnfractions .4 .6
1026 @headitem Expression @tab Description
1027 @item @code{__real__ @var{exp}}
1028 @tab Extract the real part of @var{exp}.
1029 @item @code{__imag__ @var{exp}}
1030 @tab Extract the imaginary part of @var{exp}.
1033 For values of floating point, you should use the ISO C99
1034 functions, declared in @code{<complex.h>} and also provided as
1035 built-in functions by GCC@.
1037 @multitable @columnfractions .4 .2 .2 .2
1038 @headitem Expression @tab float @tab double @tab long double
1039 @item @code{__real__ @var{exp}}
1040 @tab @code{crealf} @tab @code{creal} @tab @code{creall}
1041 @item @code{__imag__ @var{exp}}
1042 @tab @code{cimagf} @tab @code{cimag} @tab @code{cimagl}
1045 @cindex complex conjugation
1046 The operator @samp{~} performs complex conjugation when used on a value
1047 with a complex type. This is a GNU extension; for values of
1048 floating type, you should use the ISO C99 functions @code{conjf},
1049 @code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
1050 provided as built-in functions by GCC@. Note unlike the @code{__real__}
1051 and @code{__imag__} operators, this operator will not do an implicit cast
1052 to the complex type because the @samp{~} is already a normal operator.
1054 GCC can allocate complex automatic variables in a noncontiguous
1055 fashion; it's even possible for the real part to be in a register while
1056 the imaginary part is on the stack (or vice versa). Only the DWARF
1057 debug info format can represent this, so use of DWARF is recommended.
1058 If you are using the stabs debug info format, GCC describes a noncontiguous
1059 complex variable as if it were two separate variables of noncomplex type.
1060 If the variable's actual name is @code{foo}, the two fictitious
1061 variables are named @code{foo$real} and @code{foo$imag}. You can
1062 examine and set these two fictitious variables with your debugger.
1064 @defbuiltin{@var{type} __builtin_complex (@var{real}, @var{imag})}
1066 The built-in function @code{__builtin_complex} is provided for use in
1067 implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
1068 @code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
1069 real binary floating-point type, and the result has the corresponding
1070 complex type with real and imaginary parts @var{real} and @var{imag}.
1071 Unlike @samp{@var{real} + I * @var{imag}}, this works even when
1072 infinities, NaNs and negative zeros are involved.
1076 @node Floating Types
1077 @section Additional Floating Types
1078 @cindex additional floating types
1079 @cindex @code{_Float@var{n}} data types
1080 @cindex @code{_Float@var{n}x} data types
1081 @cindex @code{__float80} data type
1082 @cindex @code{__float128} data type
1083 @cindex @code{__ibm128} data type
1084 @cindex @code{w} floating point suffix
1085 @cindex @code{q} floating point suffix
1086 @cindex @code{W} floating point suffix
1087 @cindex @code{Q} floating point suffix
1089 ISO/IEC TS 18661-3:2015 defines C support for additional floating
1090 types @code{_Float@var{n}} and @code{_Float@var{n}x}, and GCC supports
1091 these type names; the set of types supported depends on the target
1093 Constants with these types use suffixes @code{f@var{n}} or
1094 @code{F@var{n}} and @code{f@var{n}x} or @code{F@var{n}x}. These type
1095 names can be used together with @code{_Complex} to declare complex
1098 As an extension, GNU C and GNU C++ support additional floating
1099 types, which are not supported by all targets.
1101 @item @code{__float128} is available on i386, x86_64, IA-64, LoongArch
1102 and hppa HP-UX, as well as on PowerPC GNU/Linux targets that enable
1103 the vector scalar (VSX) instruction set. @code{__float128} supports
1104 the 128-bit floating type. On i386, x86_64, PowerPC, LoongArch and IA-64,
1105 other than HP-UX, @code{__float128} is an alias for @code{_Float128}.
1106 On hppa and IA-64 HP-UX, @code{__float128} is an alias for @code{long
1109 @item @code{__float80} is available on the i386, x86_64, and IA-64
1110 targets, and supports the 80-bit (@code{XFmode}) floating type. It is
1111 an alias for the type name @code{_Float64x} on these targets.
1113 @item @code{__ibm128} is available on PowerPC targets, and provides
1114 access to the IBM extended double format which is the current format
1115 used for @code{long double}. When @code{long double} transitions to
1116 @code{__float128} on PowerPC in the future, @code{__ibm128} will remain
1117 for use in conversions between the two types.
1120 Support for these additional types includes the arithmetic operators:
1121 add, subtract, multiply, divide; unary arithmetic operators;
1122 relational operators; equality operators; and conversions to and from
1123 integer and other floating types. Use a suffix @samp{w} or @samp{W}
1124 in a literal constant of type @code{__float80} or type
1125 @code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{__float128}.
1127 In order to use @code{_Float128}, @code{__float128}, and @code{__ibm128}
1128 on PowerPC Linux systems, you must use the @option{-mfloat128} option. It is
1129 expected in future versions of GCC that @code{_Float128} and @code{__float128}
1130 will be enabled automatically.
1132 The @code{_Float128} type is supported on all systems where
1133 @code{__float128} is supported or where @code{long double} has the
1134 IEEE binary128 format. The @code{_Float64x} type is supported on all
1135 systems where @code{__float128} is supported. The @code{_Float32}
1136 type is supported on all systems supporting IEEE binary32; the
1137 @code{_Float64} and @code{_Float32x} types are supported on all systems
1138 supporting IEEE binary64. The @code{_Float16} type is supported on AArch64
1139 systems by default, on ARM systems when the IEEE format for 16-bit
1140 floating-point types is selected with @option{-mfp16-format=ieee} and,
1141 for both C and C++, on x86 systems with SSE2 enabled. GCC does not currently
1142 support @code{_Float128x} on any systems.
1144 On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex
1145 types using the corresponding internal complex type, @code{XCmode} for
1146 @code{__float80} type and @code{TCmode} for @code{__float128} type:
1149 typedef _Complex float __attribute__((mode(TC))) _Complex128;
1150 typedef _Complex float __attribute__((mode(XC))) _Complex80;
1153 On the PowerPC Linux VSX targets, you can declare complex types using
1154 the corresponding internal complex type, @code{KCmode} for
1155 @code{__float128} type and @code{ICmode} for @code{__ibm128} type:
1158 typedef _Complex float __attribute__((mode(KC))) _Complex_float128;
1159 typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128;
1162 @node Half-Precision
1163 @section Half-Precision Floating Point
1164 @cindex half-precision floating point
1165 @cindex @code{__fp16} data type
1166 @cindex @code{__Float16} data type
1168 On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating
1169 point via the @code{__fp16} type defined in the ARM C Language Extensions.
1170 On ARM systems, you must enable this type explicitly with the
1171 @option{-mfp16-format} command-line option in order to use it.
1172 On x86 targets with SSE2 enabled, GCC supports half-precision (16-bit)
1173 floating point via the @code{_Float16} type. For C++, x86 provides a builtin
1174 type named @code{_Float16} which contains same data format as C.
1176 ARM targets support two incompatible representations for half-precision
1177 floating-point values. You must choose one of the representations and
1178 use it consistently in your program.
1180 Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format.
1181 This format can represent normalized values in the range of @math{2^{-14}} to 65504.
1182 There are 11 bits of significand precision, approximately 3
1185 Specifying @option{-mfp16-format=alternative} selects the ARM
1186 alternative format. This representation is similar to the IEEE
1187 format, but does not support infinities or NaNs. Instead, the range
1188 of exponents is extended, so that this format can represent normalized
1189 values in the range of @math{2^{-14}} to 131008.
1191 The GCC port for AArch64 only supports the IEEE 754-2008 format, and does
1192 not require use of the @option{-mfp16-format} command-line option.
1194 The @code{__fp16} type may only be used as an argument to intrinsics defined
1195 in @code{<arm_fp16.h>}, or as a storage format. For purposes of
1196 arithmetic and other operations, @code{__fp16} values in C or C++
1197 expressions are automatically promoted to @code{float}.
1199 The ARM target provides hardware support for conversions between
1200 @code{__fp16} and @code{float} values
1201 as an extension to VFP and NEON (Advanced SIMD), and from ARMv8-A provides
1202 hardware support for conversions between @code{__fp16} and @code{double}
1203 values. GCC generates code using these hardware instructions if you
1204 compile with options to select an FPU that provides them;
1205 for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp},
1206 in addition to the @option{-mfp16-format} option to select
1207 a half-precision format.
1209 Language-level support for the @code{__fp16} data type is
1210 independent of whether GCC generates code using hardware floating-point
1211 instructions. In cases where hardware support is not specified, GCC
1212 implements conversions between @code{__fp16} and other types as library
1215 It is recommended that portable code use the @code{_Float16} type defined
1216 by ISO/IEC TS 18661-3:2015. @xref{Floating Types}.
1218 On x86 targets with SSE2 enabled, without @option{-mavx512fp16},
1219 all operations will be emulated by software emulation and the @code{float}
1220 instructions. The default behavior for @code{FLT_EVAL_METHOD} is to keep the
1221 intermediate result of the operation as 32-bit precision. This may lead to
1222 inconsistent behavior between software emulation and AVX512-FP16 instructions.
1223 Using @option{-fexcess-precision=16} will force round back after each operation.
1225 Using @option{-mavx512fp16} will generate AVX512-FP16 instructions instead of
1226 software emulation. The default behavior of @code{FLT_EVAL_METHOD} is to round
1227 after each operation. The same is true with @option{-fexcess-precision=standard}
1228 and @option{-mfpmath=sse}. If there is no @option{-mfpmath=sse},
1229 @option{-fexcess-precision=standard} alone does the same thing as before,
1230 It is useful for code that does not have @code{_Float16} and runs on the x87
1234 @section Decimal Floating Types
1235 @cindex decimal floating types
1236 @cindex @code{_Decimal32} data type
1237 @cindex @code{_Decimal64} data type
1238 @cindex @code{_Decimal128} data type
1239 @cindex @code{df} integer suffix
1240 @cindex @code{dd} integer suffix
1241 @cindex @code{dl} integer suffix
1242 @cindex @code{DF} integer suffix
1243 @cindex @code{DD} integer suffix
1244 @cindex @code{DL} integer suffix
1246 As an extension, GNU C supports decimal floating types as
1247 defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal
1248 floating types in GCC will evolve as the draft technical report changes.
1249 Calling conventions for any target might also change. Not all targets
1250 support decimal floating types.
1252 The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and
1253 @code{_Decimal128}. They use a radix of ten, unlike the floating types
1254 @code{float}, @code{double}, and @code{long double} whose radix is not
1255 specified by the C standard but is usually two.
1257 Support for decimal floating types includes the arithmetic operators
1258 add, subtract, multiply, divide; unary arithmetic operators;
1259 relational operators; equality operators; and conversions to and from
1260 integer and other floating types. Use a suffix @samp{df} or
1261 @samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
1262 or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
1265 GCC support of decimal float as specified by the draft technical report
1270 When the value of a decimal floating type cannot be represented in the
1271 integer type to which it is being converted, the result is undefined
1272 rather than the result value specified by the draft technical report.
1275 GCC does not provide the C library functionality associated with
1276 @file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and
1277 @file{wchar.h}, which must come from a separate C library implementation.
1278 Because of this the GNU C compiler does not define macro
1279 @code{__STDC_DEC_FP__} to indicate that the implementation conforms to
1280 the technical report.
1283 Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
1284 are supported by the DWARF debug information format.
1290 ISO C99 and ISO C++17 support floating-point numbers written not only in
1291 the usual decimal notation, such as @code{1.55e1}, but also numbers such as
1292 @code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC
1293 supports this in C90 mode (except in some cases when strictly
1294 conforming) and in C++98, C++11 and C++14 modes. In that format the
1295 @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
1296 mandatory. The exponent is a decimal number that indicates the power of
1297 2 by which the significant part is multiplied. Thus @samp{0x1.f} is
1304 @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
1305 is the same as @code{1.55e1}.
1307 Unlike for floating-point numbers in the decimal notation the exponent
1308 is always required in the hexadecimal notation. Otherwise the compiler
1309 would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This
1310 could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
1311 extension for floating-point constants of type @code{float}.
1314 @section Fixed-Point Types
1315 @cindex fixed-point types
1316 @cindex @code{_Fract} data type
1317 @cindex @code{_Accum} data type
1318 @cindex @code{_Sat} data type
1319 @cindex @code{hr} fixed-suffix
1320 @cindex @code{r} fixed-suffix
1321 @cindex @code{lr} fixed-suffix
1322 @cindex @code{llr} fixed-suffix
1323 @cindex @code{uhr} fixed-suffix
1324 @cindex @code{ur} fixed-suffix
1325 @cindex @code{ulr} fixed-suffix
1326 @cindex @code{ullr} fixed-suffix
1327 @cindex @code{hk} fixed-suffix
1328 @cindex @code{k} fixed-suffix
1329 @cindex @code{lk} fixed-suffix
1330 @cindex @code{llk} fixed-suffix
1331 @cindex @code{uhk} fixed-suffix
1332 @cindex @code{uk} fixed-suffix
1333 @cindex @code{ulk} fixed-suffix
1334 @cindex @code{ullk} fixed-suffix
1335 @cindex @code{HR} fixed-suffix
1336 @cindex @code{R} fixed-suffix
1337 @cindex @code{LR} fixed-suffix
1338 @cindex @code{LLR} fixed-suffix
1339 @cindex @code{UHR} fixed-suffix
1340 @cindex @code{UR} fixed-suffix
1341 @cindex @code{ULR} fixed-suffix
1342 @cindex @code{ULLR} fixed-suffix
1343 @cindex @code{HK} fixed-suffix
1344 @cindex @code{K} fixed-suffix
1345 @cindex @code{LK} fixed-suffix
1346 @cindex @code{LLK} fixed-suffix
1347 @cindex @code{UHK} fixed-suffix
1348 @cindex @code{UK} fixed-suffix
1349 @cindex @code{ULK} fixed-suffix
1350 @cindex @code{ULLK} fixed-suffix
1352 As an extension, GNU C supports fixed-point types as
1353 defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point
1354 types in GCC will evolve as the draft technical report changes.
1355 Calling conventions for any target might also change. Not all targets
1356 support fixed-point types.
1358 The fixed-point types are
1359 @code{short _Fract},
1362 @code{long long _Fract},
1363 @code{unsigned short _Fract},
1364 @code{unsigned _Fract},
1365 @code{unsigned long _Fract},
1366 @code{unsigned long long _Fract},
1367 @code{_Sat short _Fract},
1369 @code{_Sat long _Fract},
1370 @code{_Sat long long _Fract},
1371 @code{_Sat unsigned short _Fract},
1372 @code{_Sat unsigned _Fract},
1373 @code{_Sat unsigned long _Fract},
1374 @code{_Sat unsigned long long _Fract},
1375 @code{short _Accum},
1378 @code{long long _Accum},
1379 @code{unsigned short _Accum},
1380 @code{unsigned _Accum},
1381 @code{unsigned long _Accum},
1382 @code{unsigned long long _Accum},
1383 @code{_Sat short _Accum},
1385 @code{_Sat long _Accum},
1386 @code{_Sat long long _Accum},
1387 @code{_Sat unsigned short _Accum},
1388 @code{_Sat unsigned _Accum},
1389 @code{_Sat unsigned long _Accum},
1390 @code{_Sat unsigned long long _Accum}.
1392 Fixed-point data values contain fractional and optional integral parts.
1393 The format of fixed-point data varies and depends on the target machine.
1395 Support for fixed-point types includes:
1398 prefix and postfix increment and decrement operators (@code{++}, @code{--})
1400 unary arithmetic operators (@code{+}, @code{-}, @code{!})
1402 binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/})
1404 binary shift operators (@code{<<}, @code{>>})
1406 relational operators (@code{<}, @code{<=}, @code{>=}, @code{>})
1408 equality operators (@code{==}, @code{!=})
1410 assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=},
1411 @code{<<=}, @code{>>=})
1413 conversions to and from integer, floating-point, or fixed-point types
1416 Use a suffix in a fixed-point literal constant:
1418 @item @samp{hr} or @samp{HR} for @code{short _Fract} and
1419 @code{_Sat short _Fract}
1420 @item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract}
1421 @item @samp{lr} or @samp{LR} for @code{long _Fract} and
1422 @code{_Sat long _Fract}
1423 @item @samp{llr} or @samp{LLR} for @code{long long _Fract} and
1424 @code{_Sat long long _Fract}
1425 @item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and
1426 @code{_Sat unsigned short _Fract}
1427 @item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and
1428 @code{_Sat unsigned _Fract}
1429 @item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and
1430 @code{_Sat unsigned long _Fract}
1431 @item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract}
1432 and @code{_Sat unsigned long long _Fract}
1433 @item @samp{hk} or @samp{HK} for @code{short _Accum} and
1434 @code{_Sat short _Accum}
1435 @item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum}
1436 @item @samp{lk} or @samp{LK} for @code{long _Accum} and
1437 @code{_Sat long _Accum}
1438 @item @samp{llk} or @samp{LLK} for @code{long long _Accum} and
1439 @code{_Sat long long _Accum}
1440 @item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and
1441 @code{_Sat unsigned short _Accum}
1442 @item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and
1443 @code{_Sat unsigned _Accum}
1444 @item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and
1445 @code{_Sat unsigned long _Accum}
1446 @item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum}
1447 and @code{_Sat unsigned long long _Accum}
1450 GCC support of fixed-point types as specified by the draft technical report
1455 Pragmas to control overflow and rounding behaviors are not implemented.
1458 Fixed-point types are supported by the DWARF debug information format.
1460 @node Named Address Spaces
1461 @section Named Address Spaces
1462 @cindex Named Address Spaces
1464 As an extension, GNU C supports named address spaces as
1465 defined in the N1275 draft of ISO/IEC DTR 18037. Support for named
1466 address spaces in GCC will evolve as the draft technical report
1467 changes. Calling conventions for any target might also change. At
1468 present, only the AVR, M32C, PRU, RL78, and x86 targets support
1469 address spaces other than the generic address space.
1471 Address space identifiers may be used exactly like any other C type
1472 qualifier (e.g., @code{const} or @code{volatile}). See the N1275
1473 document for more details.
1475 @anchor{AVR Named Address Spaces}
1476 @subsection AVR Named Address Spaces
1478 On the AVR target, there are several address spaces that can be used
1479 in order to put read-only data into the flash memory and access that
1480 data by means of the special instructions @code{LPM} or @code{ELPM}
1481 needed to read from flash.
1483 Devices belonging to @code{avrtiny} and @code{avrxmega3} can access
1484 flash memory by means of @code{LD*} instructions because the flash
1485 memory is mapped into the RAM address space. There is @emph{no need}
1486 for language extensions like @code{__flash} or attribute
1487 @ref{AVR Variable Attributes,,@code{progmem}}.
1488 The default linker description files for these devices cater for that
1489 feature and @code{.rodata} stays in flash: The compiler just generates
1490 @code{LD*} instructions, and the linker script adds core specific
1491 offsets to all @code{.rodata} symbols: @code{0x4000} in the case of
1492 @code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}.
1493 See @ref{AVR Options} for a list of respective devices.
1495 For devices not in @code{avrtiny} or @code{avrxmega3},
1496 any data including read-only data is located in RAM (the generic
1497 address space) because flash memory is not visible in the RAM address
1498 space. In order to locate read-only data in flash memory @emph{and}
1499 to generate the right instructions to access this data without
1500 using (inline) assembler code, special address spaces are needed.
1503 @cindex @code{__flash} AVR Named Address Spaces
1505 The @code{__flash} qualifier locates data in the
1506 @code{.progmem.data} section. Data is read using the @code{LPM}
1507 instruction. Pointers to this address space are 16 bits wide.
1509 @cindex @code{__flash1} AVR Named Address Spaces
1510 @cindex @code{__flash2} AVR Named Address Spaces
1511 @cindex @code{__flash3} AVR Named Address Spaces
1512 @cindex @code{__flash4} AVR Named Address Spaces
1513 @cindex @code{__flash5} AVR Named Address Spaces
1519 These are 16-bit address spaces locating data in section
1520 @code{.progmem@var{N}.data} where @var{N} refers to
1521 address space @code{__flash@var{N}}.
1522 The compiler sets the @code{RAMPZ} segment register appropriately
1523 before reading data by means of the @code{ELPM} instruction.
1525 @cindex @code{__memx} AVR Named Address Spaces
1527 This is a 24-bit address space that linearizes flash and RAM:
1528 If the high bit of the address is set, data is read from
1529 RAM using the lower two bytes as RAM address.
1530 If the high bit of the address is clear, data is read from flash
1531 with @code{RAMPZ} set according to the high byte of the address.
1532 @xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}.
1534 Objects in this address space are located in @code{.progmemx.data}.
1540 char my_read (const __flash char ** p)
1542 /* p is a pointer to RAM that points to a pointer to flash.
1543 The first indirection of p reads that flash pointer
1544 from RAM and the second indirection reads a char from this
1550 /* Locate array[] in flash memory */
1551 const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @};
1557 /* Return 17 by reading from flash memory */
1558 return array[array[i]];
1563 For each named address space supported by avr-gcc there is an equally
1564 named but uppercase built-in macro defined.
1565 The purpose is to facilitate testing if respective address space
1566 support is available or not:
1570 const __flash int var = 1;
1577 #include <avr/pgmspace.h> /* From AVR-LibC */
1579 const int var PROGMEM = 1;
1583 return (int) pgm_read_word (&var);
1585 #endif /* __FLASH */
1589 Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}}
1590 locates data in flash but
1591 accesses to these data read from generic address space, i.e.@:
1593 so that you need special accessors like @code{pgm_read_byte}
1594 from @w{@uref{https://www.nongnu.org/avr-libc/user-manual/,AVR-LibC}}
1595 together with attribute @code{progmem}.
1598 @b{Limitations and Caveats}
1602 Reading across the 64@tie{}KiB section boundary of
1603 the @code{__flash} or @code{__flash@var{N}} address spaces
1604 shows undefined behavior. The only address space that
1605 supports reading across the 64@tie{}KiB flash segment boundaries is
1609 If you use one of the @code{__flash@var{N}} address spaces
1610 you must arrange your linker script to locate the
1611 @code{.progmem@var{N}.data} sections according to your needs.
1612 For an example, see the
1613 @w{@uref{https://gcc.gnu.org/wiki/avr-gcc#Address_Spaces,avr-gcc wiki}}
1616 Any data or pointers to the non-generic address spaces must
1617 be qualified as @code{const}, i.e.@: as read-only data.
1618 This still applies if the data in one of these address
1619 spaces like software version number or calibration lookup table are intended to
1620 be changed after load time by, say, a boot loader. In this case
1621 the right qualification is @code{const} @code{volatile} so that the compiler
1622 must not optimize away known values or insert them
1623 as immediates into operands of instructions.
1626 The following code initializes a variable @code{pfoo}
1627 located in static storage with a 24-bit address:
1629 extern const __memx char foo;
1630 const __memx void *pfoo = &foo;
1634 On the reduced Tiny devices like ATtiny40, no address spaces are supported.
1635 Just use vanilla C / C++ code without overhead as outlined above.
1636 Attribute @code{progmem} is supported but works differently,
1637 see @ref{AVR Variable Attributes}.
1641 @subsection M32C Named Address Spaces
1642 @cindex @code{__far} M32C Named Address Spaces
1644 On the M32C target, with the R8C and M16C CPU variants, variables
1645 qualified with @code{__far} are accessed using 32-bit addresses in
1646 order to access memory beyond the first 64@tie{}Ki bytes. If
1647 @code{__far} is used with the M32CM or M32C CPU variants, it has no
1650 @subsection PRU Named Address Spaces
1651 @cindex @code{__regio_symbol} PRU Named Address Spaces
1653 On the PRU target, variables qualified with @code{__regio_symbol} are
1654 aliases used to access the special I/O CPU registers. They must be
1655 declared as @code{extern} because such variables will not be allocated in
1656 any data memory. They must also be marked as @code{volatile}, and can
1657 only be 32-bit integer types. The only names those variables can have
1658 are @code{__R30} and @code{__R31}, representing respectively the
1659 @code{R30} and @code{R31} special I/O CPU registers. Hence the following
1660 example is the only valid usage of @code{__regio_symbol}:
1663 extern volatile __regio_symbol uint32_t __R30;
1664 extern volatile __regio_symbol uint32_t __R31;
1667 @subsection RL78 Named Address Spaces
1668 @cindex @code{__far} RL78 Named Address Spaces
1670 On the RL78 target, variables qualified with @code{__far} are accessed
1671 with 32-bit pointers (20-bit addresses) rather than the default 16-bit
1672 addresses. Non-far variables are assumed to appear in the topmost
1673 64@tie{}KiB of the address space.
1675 @subsection x86 Named Address Spaces
1676 @cindex x86 named address spaces
1678 On the x86 target, variables may be declared as being relative
1679 to the @code{%fs} or @code{%gs} segments.
1682 @cindex @code{__seg_fs} x86 named address space
1683 @cindex @code{__seg_gs} x86 named address space
1686 The object is accessed with the respective segment override prefix.
1688 The respective segment base must be set via some method specific to
1689 the operating system. Rather than require an expensive system call
1690 to retrieve the segment base, these address spaces are not considered
1691 to be subspaces of the generic (flat) address space. This means that
1692 explicit casts are required to convert pointers between these address
1693 spaces and the generic address space. In practice the application
1694 should cast to @code{uintptr_t} and apply the segment base offset
1695 that it installed previously.
1697 The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are
1698 defined when these address spaces are supported.
1702 @section Arrays of Length Zero
1703 @cindex arrays of length zero
1704 @cindex zero-length arrays
1705 @cindex length-zero arrays
1706 @cindex flexible array members
1708 Declaring zero-length arrays is allowed in GNU C as an extension.
1709 A zero-length array can be useful as the last element of a structure
1710 that is really a header for a variable-length object:
1718 struct line *thisline = (struct line *)
1719 malloc (sizeof (struct line) + this_length);
1720 thisline->length = this_length;
1723 In this example, @code{thisline->contents} is an array of @code{char} that
1724 can hold up to @code{thisline->length} bytes.
1726 Although the size of a zero-length array is zero, an array member of
1727 this kind may increase the size of the enclosing type as a result of tail
1728 padding. The offset of a zero-length array member from the beginning
1729 of the enclosing structure is the same as the offset of an array with
1730 one or more elements of the same type. The alignment of a zero-length
1731 array is the same as the alignment of its elements.
1733 Declaring zero-length arrays in other contexts, including as interior
1734 members of structure objects or as non-member objects, is discouraged.
1735 Accessing elements of zero-length arrays declared in such contexts is
1736 undefined and may be diagnosed.
1738 In the absence of the zero-length array extension, in ISO C90
1739 the @code{contents} array in the example above would typically be declared
1740 to have a single element. Unlike a zero-length array which only contributes
1741 to the size of the enclosing structure for the purposes of alignment,
1742 a one-element array always occupies at least as much space as a single
1743 object of the type. Although using one-element arrays this way is
1744 discouraged, GCC handles accesses to trailing one-element array members
1745 analogously to zero-length arrays.
1747 The preferred mechanism to declare variable-length types like
1748 @code{struct line} above is the ISO C99 @dfn{flexible array member},
1749 with slightly different syntax and semantics:
1753 Flexible array members are written as @code{contents[]} without
1757 Flexible array members have incomplete type, and so the @code{sizeof}
1758 operator may not be applied. As a quirk of the original implementation
1759 of zero-length arrays, @code{sizeof} evaluates to zero.
1762 Flexible array members may only appear as the last member of a
1763 @code{struct} that is otherwise non-empty.
1766 A structure containing a flexible array member, or a union containing
1767 such a structure (possibly recursively), may not be a member of a
1768 structure or an element of an array. (However, these uses are
1769 permitted by GCC as extensions, see details below.)
1772 The GCC extension accepts a structure containing an ISO C99 @dfn{flexible array
1773 member}, or a union containing such a structure (possibly recursively)
1774 to be a member of a structure.
1776 There are two situations:
1780 A structure containing a C99 flexible array member, or a union containing
1781 such a structure, is the last field of another structure, for example:
1784 struct flex @{ int length; char data[]; @};
1785 union union_flex @{ int others; struct flex f; @};
1787 struct out_flex_struct @{ int m; struct flex flex_data; @};
1788 struct out_flex_union @{ int n; union union_flex flex_data; @};
1791 In the above, both @code{out_flex_struct.flex_data.data[]} and
1792 @code{out_flex_union.flex_data.f.data[]} are considered as flexible arrays too.
1795 A structure containing a C99 flexible array member, or a union containing
1796 such a structure, is not the last field of another structure, for example:
1799 struct flex @{ int length; char data[]; @};
1801 struct mid_flex @{ int m; struct flex flex_data; int n; @};
1804 In the above, accessing a member of the array @code{mid_flex.flex_data.data[]}
1805 might have undefined behavior. Compilers do not handle such a case
1806 consistently. Any code relying on this case should be modified to ensure
1807 that flexible array members only end up at the ends of structures.
1809 Please use the warning option @option{-Wflex-array-member-not-at-end} to
1810 identify all such cases in the source code and modify them. This extension
1814 Non-empty initialization of zero-length
1815 arrays is treated like any case where there are more initializer
1816 elements than the array holds, in that a suitable warning about ``excess
1817 elements in array'' is given, and the excess elements (all of them, in
1818 this case) are ignored.
1820 GCC allows static initialization of flexible array members.
1821 This is equivalent to defining a new structure containing the original
1822 structure followed by an array of sufficient size to contain the data.
1823 E.g.@: in the following, @code{f1} is constructed as if it were declared
1829 @} f1 = @{ 1, @{ 2, 3, 4 @} @};
1832 struct f1 f1; int data[3];
1833 @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
1837 The convenience of this extension is that @code{f1} has the desired
1838 type, eliminating the need to consistently refer to @code{f2.f1}.
1840 This has symmetry with normal static arrays, in that an array of
1841 unknown size is also written with @code{[]}.
1843 Of course, this extension only makes sense if the extra data comes at
1844 the end of a top-level object, as otherwise we would be overwriting
1845 data at subsequent offsets. To avoid undue complication and confusion
1846 with initialization of deeply nested arrays, we simply disallow any
1847 non-empty initialization except when the structure is the top-level
1848 object. For example:
1851 struct foo @{ int x; int y[]; @};
1852 struct bar @{ struct foo z; @};
1854 struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
1855 struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1856 struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
1857 struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1860 @node Empty Structures
1861 @section Structures with No Members
1862 @cindex empty structures
1863 @cindex zero-size structures
1865 GCC permits a C structure to have no members:
1872 The structure has size zero. In C++, empty structures are part
1873 of the language. G++ treats empty structures as if they had a single
1874 member of type @code{char}.
1876 @node Variable Length
1877 @section Arrays of Variable Length
1878 @cindex variable-length arrays
1879 @cindex arrays of variable length
1882 Variable-length automatic arrays are allowed in ISO C99, and as an
1883 extension GCC accepts them in C90 mode and in C++. These arrays are
1884 declared like any other automatic arrays, but with a length that is not
1885 a constant expression. The storage is allocated at the point of
1886 declaration and deallocated when the block scope containing the declaration
1892 concat_fopen (char *s1, char *s2, char *mode)
1894 char str[strlen (s1) + strlen (s2) + 1];
1897 return fopen (str, mode);
1901 @cindex scope of a variable length array
1902 @cindex variable-length array scope
1903 @cindex deallocating variable length arrays
1904 Jumping or breaking out of the scope of the array name deallocates the
1905 storage. Jumping into the scope is not allowed; you get an error
1908 @cindex variable-length array in a structure
1909 As an extension, GCC accepts variable-length arrays as a member of
1910 a structure or a union. For example:
1916 struct S @{ int x[n]; @};
1920 @cindex @code{alloca} vs variable-length arrays
1921 You can use the function @code{alloca} to get an effect much like
1922 variable-length arrays. The function @code{alloca} is available in
1923 many other C implementations (but not in all). On the other hand,
1924 variable-length arrays are more elegant.
1926 There are other differences between these two methods. Space allocated
1927 with @code{alloca} exists until the containing @emph{function} returns.
1928 The space for a variable-length array is deallocated as soon as the array
1929 name's scope ends, unless you also use @code{alloca} in this scope.
1931 You can also use variable-length arrays as arguments to functions:
1935 tester (int len, char data[len][len])
1941 The length of an array is computed once when the storage is allocated
1942 and is remembered for the scope of the array in case you access it with
1945 If you want to pass the array first and the length afterward, you can
1946 use a forward declaration in the parameter list---another GNU extension.
1950 tester (int len; char data[len][len], int len)
1956 @cindex parameter forward declaration
1957 The @samp{int len} before the semicolon is a @dfn{parameter forward
1958 declaration}, and it serves the purpose of making the name @code{len}
1959 known when the declaration of @code{data} is parsed.
1961 You can write any number of such parameter forward declarations in the
1962 parameter list. They can be separated by commas or semicolons, but the
1963 last one must end with a semicolon, which is followed by the ``real''
1964 parameter declarations. Each forward declaration must match a ``real''
1965 declaration in parameter name and data type. ISO C99 does not support
1966 parameter forward declarations.
1968 @node Variadic Macros
1969 @section Macros with a Variable Number of Arguments.
1970 @cindex variable number of arguments
1971 @cindex macro with variable arguments
1972 @cindex rest argument (in macro)
1973 @cindex variadic macros
1975 In the ISO C standard of 1999, a macro can be declared to accept a
1976 variable number of arguments much as a function can. The syntax for
1977 defining the macro is similar to that of a function. Here is an
1981 #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
1985 Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
1986 such a macro, it represents the zero or more tokens until the closing
1987 parenthesis that ends the invocation, including any commas. This set of
1988 tokens replaces the identifier @code{__VA_ARGS__} in the macro body
1989 wherever it appears. See the CPP manual for more information.
1991 GCC has long supported variadic macros, and used a different syntax that
1992 allowed you to give a name to the variable arguments just like any other
1993 argument. Here is an example:
1996 #define debug(format, args...) fprintf (stderr, format, args)
2000 This is in all ways equivalent to the ISO C example above, but arguably
2001 more readable and descriptive.
2003 GNU CPP has two further variadic macro extensions, and permits them to
2004 be used with either of the above forms of macro definition.
2006 In standard C, you are not allowed to leave the variable argument out
2007 entirely; but you are allowed to pass an empty argument. For example,
2008 this invocation is invalid in ISO C, because there is no comma after
2015 GNU CPP permits you to completely omit the variable arguments in this
2016 way. In the above examples, the compiler would complain, though since
2017 the expansion of the macro still has the extra comma after the format
2020 To help solve this problem, CPP behaves specially for variable arguments
2021 used with the token paste operator, @samp{##}. If instead you write
2024 #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
2028 and if the variable arguments are omitted or empty, the @samp{##}
2029 operator causes the preprocessor to remove the comma before it. If you
2030 do provide some variable arguments in your macro invocation, GNU CPP
2031 does not complain about the paste operation and instead places the
2032 variable arguments after the comma. Just like any other pasted macro
2033 argument, these arguments are not macro expanded.
2035 @node Escaped Newlines
2036 @section Slightly Looser Rules for Escaped Newlines
2037 @cindex escaped newlines
2038 @cindex newlines (escaped)
2040 The preprocessor treatment of escaped newlines is more relaxed
2041 than that specified by the C90 standard, which requires the newline
2042 to immediately follow a backslash.
2043 GCC's implementation allows whitespace in the form
2044 of spaces, horizontal and vertical tabs, and form feeds between the
2045 backslash and the subsequent newline. The preprocessor issues a
2046 warning, but treats it as a valid escaped newline and combines the two
2047 lines to form a single logical line. This works within comments and
2048 tokens, as well as between tokens. Comments are @emph{not} treated as
2049 whitespace for the purposes of this relaxation, since they have not
2050 yet been replaced with spaces.
2053 @section Non-Lvalue Arrays May Have Subscripts
2054 @cindex subscripting
2055 @cindex arrays, non-lvalue
2057 @cindex subscripting and function values
2058 In ISO C99, arrays that are not lvalues still decay to pointers, and
2059 may be subscripted, although they may not be modified or used after
2060 the next sequence point and the unary @samp{&} operator may not be
2061 applied to them. As an extension, GNU C allows such arrays to be
2062 subscripted in C90 mode, though otherwise they do not decay to
2063 pointers outside C99 mode. For example,
2064 this is valid in GNU C though not valid in C90:
2068 struct foo @{int a[4];@};
2074 return f().a[index];
2080 @section Arithmetic on @code{void}- and Function-Pointers
2081 @cindex void pointers, arithmetic
2082 @cindex void, size of pointer to
2083 @cindex function pointers, arithmetic
2084 @cindex function, size of pointer to
2086 In GNU C, addition and subtraction operations are supported on pointers to
2087 @code{void} and on pointers to functions. This is done by treating the
2088 size of a @code{void} or of a function as 1.
2090 A consequence of this is that @code{sizeof} is also allowed on @code{void}
2091 and on function types, and returns 1.
2093 @opindex Wpointer-arith
2094 The option @option{-Wpointer-arith} requests a warning if these extensions
2097 @node Variadic Pointer Args
2098 @section Pointer Arguments in Variadic Functions
2099 @cindex pointer arguments in variadic functions
2100 @cindex variadic functions, pointer arguments
2102 Standard C requires that pointer types used with @code{va_arg} in
2103 functions with variable argument lists either must be compatible with
2104 that of the actual argument, or that one type must be a pointer to
2105 @code{void} and the other a pointer to a character type. GNU C
2106 implements the POSIX XSI extension that additionally permits the use
2107 of @code{va_arg} with a pointer type to receive arguments of any other
2110 In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used
2111 to consume an argument of any pointer type.
2113 @node Pointers to Arrays
2114 @section Pointers to Arrays with Qualifiers Work as Expected
2115 @cindex pointers to arrays
2116 @cindex const qualifier
2118 In GNU C, pointers to arrays with qualifiers work similar to pointers
2119 to other qualified types. For example, a value of type @code{int (*)[5]}
2120 can be used to initialize a variable of type @code{const int (*)[5]}.
2121 These types are incompatible in ISO C because the @code{const} qualifier
2122 is formally attached to the element type of the array and not the
2127 transpose (int N, int M, double out[M][N], const double in[N][M]);
2131 transpose(3, 2, y, x);
2135 @section Non-Constant Initializers
2136 @cindex initializers, non-constant
2137 @cindex non-constant initializers
2139 As in standard C++ and ISO C99, the elements of an aggregate initializer for an
2140 automatic variable are not required to be constant expressions in GNU C@.
2141 Here is an example of an initializer with run-time varying elements:
2144 foo (float f, float g)
2146 float beat_freqs[2] = @{ f-g, f+g @};
2151 @node Compound Literals
2152 @section Compound Literals
2153 @cindex constructor expressions
2154 @cindex initializations in expressions
2155 @cindex structures, constructor expression
2156 @cindex expressions, constructor
2157 @cindex compound literals
2158 @c The GNU C name for what C99 calls compound literals was "constructor expressions".
2160 A compound literal looks like a cast of a brace-enclosed aggregate
2161 initializer list. Its value is an object of the type specified in
2162 the cast, containing the elements specified in the initializer.
2163 Unlike the result of a cast, a compound literal is an lvalue. ISO
2164 C99 and later support compound literals. As an extension, GCC
2165 supports compound literals also in C90 mode and in C++, although
2166 as explained below, the C++ semantics are somewhat different.
2168 Usually, the specified type of a compound literal is a structure. Assume
2169 that @code{struct foo} and @code{structure} are declared as shown:
2172 struct foo @{int a; char b[2];@} structure;
2176 Here is an example of constructing a @code{struct foo} with a compound literal:
2179 structure = ((struct foo) @{x + y, 'a', 0@});
2183 This is equivalent to writing the following:
2187 struct foo temp = @{x + y, 'a', 0@};
2192 You can also construct an array, though this is dangerous in C++, as
2193 explained below. If all the elements of the compound literal are
2194 (made up of) simple constant expressions suitable for use in
2195 initializers of objects of static storage duration, then the compound
2196 literal can be coerced to a pointer to its first element and used in
2197 such an initializer, as shown here:
2200 char **foo = (char *[]) @{ "x", "y", "z" @};
2203 Compound literals for scalar types and union types are also allowed. In
2204 the following example the variable @code{i} is initialized to the value
2205 @code{2}, the result of incrementing the unnamed object created by
2206 the compound literal.
2209 int i = ++(int) @{ 1 @};
2212 As a GNU extension, GCC allows initialization of objects with static storage
2213 duration by compound literals (which is not possible in ISO C99 because
2214 the initializer is not a constant).
2215 It is handled as if the object were initialized only with the brace-enclosed
2216 list if the types of the compound literal and the object match.
2217 The elements of the compound literal must be constant.
2218 If the object being initialized has array type of unknown size, the size is
2219 determined by the size of the compound literal.
2222 static struct foo x = (struct foo) @{1, 'a', 'b'@};
2223 static int y[] = (int []) @{1, 2, 3@};
2224 static int z[] = (int [3]) @{1@};
2228 The above lines are equivalent to the following:
2230 static struct foo x = @{1, 'a', 'b'@};
2231 static int y[] = @{1, 2, 3@};
2232 static int z[] = @{1, 0, 0@};
2235 In C, a compound literal designates an unnamed object with static or
2236 automatic storage duration. In C++, a compound literal designates a
2237 temporary object that only lives until the end of its full-expression.
2238 As a result, well-defined C code that takes the address of a subobject
2239 of a compound literal can be undefined in C++, so G++ rejects
2240 the conversion of a temporary array to a pointer. For instance, if
2241 the array compound literal example above appeared inside a function,
2242 any subsequent use of @code{foo} in C++ would have undefined behavior
2243 because the lifetime of the array ends after the declaration of @code{foo}.
2245 As an optimization, G++ sometimes gives array compound literals longer
2246 lifetimes: when the array either appears outside a function or has
2247 a @code{const}-qualified type. If @code{foo} and its initializer had
2248 elements of type @code{char *const} rather than @code{char *}, or if
2249 @code{foo} were a global variable, the array would have static storage
2250 duration. But it is probably safest just to avoid the use of array
2251 compound literals in C++ code.
2253 @node Designated Inits
2254 @section Designated Initializers
2255 @cindex initializers with labeled elements
2256 @cindex labeled elements in initializers
2257 @cindex case labels in initializers
2258 @cindex designated initializers
2260 Standard C90 requires the elements of an initializer to appear in a fixed
2261 order, the same as the order of the elements in the array or structure
2264 In ISO C99 you can give the elements in any order, specifying the array
2265 indices or structure field names they apply to, and GNU C allows this as
2266 an extension in C90 mode as well. This extension is not
2267 implemented in GNU C++.
2269 To specify an array index, write
2270 @samp{[@var{index}] =} before the element value. For example,
2273 int a[6] = @{ [4] = 29, [2] = 15 @};
2280 int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
2284 The index values must be constant expressions, even if the array being
2285 initialized is automatic.
2287 An alternative syntax for this that has been obsolete since GCC 2.5 but
2288 GCC still accepts is to write @samp{[@var{index}]} before the element
2289 value, with no @samp{=}.
2291 To initialize a range of elements to the same value, write
2292 @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
2293 extension. For example,
2296 int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
2300 If the value in it has side effects, the side effects happen only once,
2301 not for each initialized field by the range initializer.
2304 Note that the length of the array is the highest value specified
2307 In a structure initializer, specify the name of a field to initialize
2308 with @samp{.@var{fieldname} =} before the element value. For example,
2309 given the following structure,
2312 struct point @{ int x, y; @};
2316 the following initialization
2319 struct point p = @{ .y = yvalue, .x = xvalue @};
2326 struct point p = @{ xvalue, yvalue @};
2329 Another syntax that has the same meaning, obsolete since GCC 2.5, is
2330 @samp{@var{fieldname}:}, as shown here:
2333 struct point p = @{ y: yvalue, x: xvalue @};
2336 Omitted fields are implicitly initialized the same as for objects
2337 that have static storage duration.
2340 The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
2341 @dfn{designator}. You can also use a designator (or the obsolete colon
2342 syntax) when initializing a union, to specify which element of the union
2343 should be used. For example,
2346 union foo @{ int i; double d; @};
2348 union foo f = @{ .d = 4 @};
2352 converts 4 to a @code{double} to store it in the union using
2353 the second element. By contrast, casting 4 to type @code{union foo}
2354 stores it into the union as the integer @code{i}, since it is
2355 an integer. @xref{Cast to Union}.
2357 You can combine this technique of naming elements with ordinary C
2358 initialization of successive elements. Each initializer element that
2359 does not have a designator applies to the next consecutive element of the
2360 array or structure. For example,
2363 int a[6] = @{ [1] = v1, v2, [4] = v4 @};
2370 int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
2373 Labeling the elements of an array initializer is especially useful
2374 when the indices are characters or belong to an @code{enum} type.
2379 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
2380 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
2383 @cindex designator lists
2384 You can also write a series of @samp{.@var{fieldname}} and
2385 @samp{[@var{index}]} designators before an @samp{=} to specify a
2386 nested subobject to initialize; the list is taken relative to the
2387 subobject corresponding to the closest surrounding brace pair. For
2388 example, with the @samp{struct point} declaration above:
2391 struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
2394 If the same field is initialized multiple times, or overlapping
2395 fields of a union are initialized, the value from the last
2396 initialization is used. When a field of a union is itself a structure,
2397 the entire structure from the last field initialized is used. If any previous
2398 initializer has side effect, it is unspecified whether the side effect
2399 happens or not. Currently, GCC discards the side-effecting
2400 initializer expressions and issues a warning.
2403 @section Case Ranges
2405 @cindex ranges in case statements
2407 You can specify a range of consecutive values in a single @code{case} label,
2411 case @var{low} ... @var{high}:
2415 This has the same effect as the proper number of individual @code{case}
2416 labels, one for each integer value from @var{low} to @var{high}, inclusive.
2418 This feature is especially useful for ranges of ASCII character codes:
2424 @strong{Be careful:} Write spaces around the @code{...}, for otherwise
2425 it may be parsed wrong when you use it with integer values. For example,
2440 @section Cast to a Union Type
2441 @cindex cast to a union
2442 @cindex union, casting to a
2444 A cast to a union type is a C extension not available in C++. It looks
2445 just like ordinary casts with the constraint that the type specified is
2446 a union type. You can specify the type either with the @code{union}
2447 keyword or with a @code{typedef} name that refers to a union. The result
2448 of a cast to a union is a temporary rvalue of the union type with a member
2449 whose type matches that of the operand initialized to the value of
2450 the operand. The effect of a cast to a union is similar to a compound
2451 literal except that it yields an rvalue like standard casts do.
2452 @xref{Compound Literals}.
2454 Expressions that may be cast to the union type are those whose type matches
2455 at least one of the members of the union. Thus, given the following union
2459 union foo @{ int i; double d; @};
2466 both @code{x} and @code{y} can be cast to type @code{union foo} and
2467 the following assignments
2472 are shorthand equivalents of these
2474 z = (union foo) @{ .i = x @};
2475 z = (union foo) @{ .d = y @};
2478 However, @code{(union foo) FLT_MAX;} is not a valid cast because the union
2479 has no member of type @code{float}.
2481 Using the cast as the right-hand side of an assignment to a variable of
2482 union type is equivalent to storing in a member of the union with
2488 u = (union foo) x @equiv{} u.i = x
2489 u = (union foo) y @equiv{} u.d = y
2492 You can also use the union cast as a function argument:
2495 void hack (union foo);
2497 hack ((union foo) x);
2500 @node Mixed Labels and Declarations
2501 @section Mixed Declarations, Labels and Code
2502 @cindex mixed declarations and code
2503 @cindex declarations, mixed with code
2504 @cindex code, mixed with declarations
2506 ISO C99 and ISO C++ allow declarations and code to be freely mixed
2507 within compound statements. ISO C23 allows labels to be
2508 placed before declarations and at the end of a compound statement.
2509 As an extension, GNU C also allows all this in C90 mode. For example,
2519 Each identifier is visible from where it is declared until the end of
2520 the enclosing block.
2522 @node Function Attributes
2523 @section Declaring Attributes of Functions
2524 @cindex function attributes
2525 @cindex declaring attributes of functions
2527 In GNU C and C++, you can use function attributes to specify certain
2528 function properties that may help the compiler optimize calls or
2529 check code more carefully for correctness. For example, you
2530 can use attributes to specify that a function never returns
2531 (@code{noreturn}), returns a value depending only on the values of
2532 its arguments (@code{const}), or has @code{printf}-style arguments
2535 You can also use attributes to control memory placement, code
2536 generation options or call/return conventions within the function
2537 being annotated. Many of these attributes are target-specific. For
2538 example, many targets support attributes for defining interrupt
2539 handler functions, which typically must follow special register usage
2540 and return conventions. Such attributes are described in the subsection
2541 for each target. However, a considerable number of attributes are
2542 supported by most, if not all targets. Those are described in
2543 the @ref{Common Function Attributes} section.
2545 GCC provides two different ways to specify attributes: the traditional
2546 GNU syntax using @samp{__attribute__ ((...))} annotations, and the
2547 newer standard C and C++ syntax using @samp{[[...]]} with the
2548 @samp{gnu::} prefix on attribute names. Note that the exact rules for
2549 placement of attributes in your source code are different depending on
2550 which syntax you use. @xref{Attribute Syntax}, for details.
2552 Compatible attribute specifications on distinct declarations
2553 of the same function are merged. An attribute specification that is not
2554 compatible with attributes already applied to a declaration of the same
2555 function is ignored with a warning.
2557 Some function attributes take one or more arguments that refer to
2558 the function's parameters by their positions within the function parameter
2559 list. Such attribute arguments are referred to as @dfn{positional arguments}.
2560 Unless specified otherwise, positional arguments that specify properties
2561 of parameters with pointer types can also specify the same properties of
2562 the implicit C++ @code{this} argument in non-static member functions, and
2563 of parameters of reference to a pointer type. For ordinary functions,
2564 position one refers to the first parameter on the list. In C++ non-static
2565 member functions, position one refers to the implicit @code{this} pointer.
2566 The same restrictions and effects apply to function attributes used with
2567 ordinary functions or C++ member functions.
2569 GCC also supports attributes on
2570 variable declarations (@pxref{Variable Attributes}),
2571 labels (@pxref{Label Attributes}),
2572 enumerators (@pxref{Enumerator Attributes}),
2573 statements (@pxref{Statement Attributes}),
2574 types (@pxref{Type Attributes}),
2575 and on field declarations (for @code{tainted_args}).
2577 There is some overlap between the purposes of attributes and pragmas
2578 (@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been
2579 found convenient to use @code{__attribute__} to achieve a natural
2580 attachment of attributes to their corresponding declarations, whereas
2581 @code{#pragma} is of use for compatibility with other compilers
2582 or constructs that do not naturally form part of the grammar.
2584 In addition to the attributes documented here,
2585 GCC plugins may provide their own attributes.
2588 * Common Function Attributes::
2589 * AArch64 Function Attributes::
2590 * AMD GCN Function Attributes::
2591 * ARC Function Attributes::
2592 * ARM Function Attributes::
2593 * AVR Function Attributes::
2594 * Blackfin Function Attributes::
2595 * BPF Function Attributes::
2596 * C-SKY Function Attributes::
2597 * Epiphany Function Attributes::
2598 * H8/300 Function Attributes::
2599 * IA-64 Function Attributes::
2600 * M32C Function Attributes::
2601 * M32R/D Function Attributes::
2602 * m68k Function Attributes::
2603 * MCORE Function Attributes::
2604 * MicroBlaze Function Attributes::
2605 * Microsoft Windows Function Attributes::
2606 * MIPS Function Attributes::
2607 * MSP430 Function Attributes::
2608 * NDS32 Function Attributes::
2609 * Nios II Function Attributes::
2610 * Nvidia PTX Function Attributes::
2611 * PowerPC Function Attributes::
2612 * RISC-V Function Attributes::
2613 * RL78 Function Attributes::
2614 * RX Function Attributes::
2615 * S/390 Function Attributes::
2616 * SH Function Attributes::
2617 * Symbian OS Function Attributes::
2618 * V850 Function Attributes::
2619 * Visium Function Attributes::
2620 * x86 Function Attributes::
2621 * Xstormy16 Function Attributes::
2624 @node Common Function Attributes
2625 @subsection Common Function Attributes
2627 The following attributes are supported on most targets.
2630 @c Keep this table alphabetized by attribute name. Treat _ as space.
2632 @cindex @code{access} function attribute
2633 @item access (@var{access-mode}, @var{ref-index})
2634 @itemx access (@var{access-mode}, @var{ref-index}, @var{size-index})
2636 The @code{access} attribute enables the detection of invalid or unsafe
2637 accesses by functions to which they apply or their callers, as well as
2638 write-only accesses to objects that are never read from. Such accesses
2639 may be diagnosed by warnings such as @option{-Wstringop-overflow},
2640 @option{-Wuninitialized}, @option{-Wunused}, and others.
2642 The @code{access} attribute specifies that a function to whose by-reference
2643 arguments the attribute applies accesses the referenced object according to
2644 @var{access-mode}. The @var{access-mode} argument is required and must be
2645 one of four names: @code{read_only}, @code{read_write}, @code{write_only},
2646 or @code{none}. The remaining two are positional arguments.
2648 The required @var{ref-index} positional argument denotes a function
2649 argument of pointer (or in C++, reference) type that is subject to
2650 the access. The same pointer argument can be referenced by at most one
2651 distinct @code{access} attribute.
2653 The optional @var{size-index} positional argument denotes a function
2654 argument of integer type that specifies the maximum size of the access.
2655 The size is the number of elements of the type referenced by @var{ref-index},
2656 or the number of bytes when the pointer type is @code{void*}. When no
2657 @var{size-index} argument is specified, the pointer argument must be either
2658 null or point to a space that is suitably aligned and large for at least one
2659 object of the referenced type (this implies that a past-the-end pointer is
2660 not a valid argument). The actual size of the access may be less but it
2663 The @code{read_only} access mode specifies that the pointer to which it
2664 applies is used to read the referenced object but not write to it. Unless
2665 the argument specifying the size of the access denoted by @var{size-index}
2666 is zero, the referenced object must be initialized. The mode implies
2667 a stronger guarantee than the @code{const} qualifier which, when cast away
2668 from a pointer, does not prevent the pointed-to object from being modified.
2669 Examples of the use of the @code{read_only} access mode is the argument to
2670 the @code{puts} function, or the second and third arguments to
2671 the @code{memcpy} function.
2674 __attribute__ ((access (read_only, 1)))
2675 int puts (const char*);
2677 __attribute__ ((access (read_only, 2, 3)))
2678 void* memcpy (void*, const void*, size_t);
2681 The @code{read_write} access mode applies to arguments of pointer types
2682 without the @code{const} qualifier. It specifies that the pointer to which
2683 it applies is used to both read and write the referenced object. Unless
2684 the argument specifying the size of the access denoted by @var{size-index}
2685 is zero, the object referenced by the pointer must be initialized. An example
2686 of the use of the @code{read_write} access mode is the first argument to
2687 the @code{strcat} function.
2690 __attribute__ ((access (read_write, 1), access (read_only, 2)))
2691 char* strcat (char*, const char*);
2694 The @code{write_only} access mode applies to arguments of pointer types
2695 without the @code{const} qualifier. It specifies that the pointer to which
2696 it applies is used to write to the referenced object but not read from it.
2697 The object referenced by the pointer need not be initialized. An example
2698 of the use of the @code{write_only} access mode is the first argument to
2699 the @code{strcpy} function, or the first two arguments to the @code{fgets}
2703 __attribute__ ((access (write_only, 1), access (read_only, 2)))
2704 char* strcpy (char*, const char*);
2706 __attribute__ ((access (write_only, 1, 2), access (read_write, 3)))
2707 int fgets (char*, int, FILE*);
2710 The access mode @code{none} specifies that the pointer to which it applies
2711 is not used to access the referenced object at all. Unless the pointer is
2712 null the pointed-to object must exist and have at least the size as denoted
2713 by the @var{size-index} argument. When the optional @var{size-index}
2714 argument is omitted for an argument of @code{void*} type the actual pointer
2715 agument is ignored. The referenced object need not be initialized.
2716 The mode is intended to be used as a means to help validate the expected
2717 object size, for example in functions that call @code{__builtin_object_size}.
2718 @xref{Object Size Checking}.
2720 Note that the @code{access} attribute merely specifies how an object
2721 referenced by the pointer argument can be accessed; it does not imply that
2722 an access @strong{will} happen. Also, the @code{access} attribute does not
2723 imply the attribute @code{nonnull}; it may be appropriate to add both attributes
2724 at the declaration of a function that unconditionally manipulates a buffer via
2725 a pointer argument. See the @code{nonnull} attribute for more information and
2728 @cindex @code{alias} function attribute
2729 @item alias ("@var{target}")
2730 The @code{alias} attribute causes the declaration to be emitted as an alias
2731 for another symbol, which must have been previously declared with the same
2732 type, and for variables, also the same size and alignment. Declaring an alias
2733 with a different type than the target is undefined and may be diagnosed. As
2734 an example, the following declarations:
2737 void __f () @{ /* @r{Do something.} */; @}
2738 void f () __attribute__ ((weak, alias ("__f")));
2742 define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name
2743 for the target must be used. It is an error if @samp{__f} is not defined in
2744 the same translation unit.
2746 This attribute requires assembler and object file support,
2747 and may not be available on all targets.
2749 @cindex @code{aligned} function attribute
2751 @itemx aligned (@var{alignment})
2752 The @code{aligned} attribute specifies a minimum alignment for
2753 the first instruction of the function, measured in bytes. When specified,
2754 @var{alignment} must be an integer constant power of 2. Specifying no
2755 @var{alignment} argument implies the ideal alignment for the target.
2756 The @code{__alignof__} operator can be used to determine what that is
2757 (@pxref{Alignment}). The attribute has no effect when a definition for
2758 the function is not provided in the same translation unit.
2760 The attribute cannot be used to decrease the alignment of a function
2761 previously declared with a more restrictive alignment; only to increase
2762 it. Attempts to do otherwise are diagnosed. Some targets specify
2763 a minimum default alignment for functions that is greater than 1. On
2764 such targets, specifying a less restrictive alignment is silently ignored.
2765 Using the attribute overrides the effect of the @option{-falign-functions}
2766 (@pxref{Optimize Options}) option for this function.
2768 Note that the effectiveness of @code{aligned} attributes may be
2769 limited by inherent limitations in the system linker
2770 and/or object file format. On some systems, the
2771 linker is only able to arrange for functions to be aligned up to a
2772 certain maximum alignment. (For some linkers, the maximum supported
2773 alignment may be very very small.) See your linker documentation for
2774 further information.
2776 The @code{aligned} attribute can also be used for variables and fields
2777 (@pxref{Variable Attributes}.)
2779 @cindex @code{alloc_align} function attribute
2780 @item alloc_align (@var{position})
2781 The @code{alloc_align} attribute may be applied to a function that
2782 returns a pointer and takes at least one argument of an integer or
2784 It indicates that the returned pointer is aligned on a boundary given
2785 by the function argument at @var{position}. Meaningful alignments are
2786 powers of 2 greater than one. GCC uses this information to improve
2787 pointer alignment analysis.
2789 The function parameter denoting the allocated alignment is specified by
2790 one constant integer argument whose number is the argument of the attribute.
2791 Argument numbering starts at one.
2796 void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1)));
2800 declares that @code{my_memalign} returns memory with minimum alignment
2801 given by parameter 1.
2803 @cindex @code{alloc_size} function attribute
2804 @item alloc_size (@var{position})
2805 @itemx alloc_size (@var{position-1}, @var{position-2})
2806 The @code{alloc_size} attribute may be applied to a function that
2807 returns a pointer and takes at least one argument of an integer or
2809 It indicates that the returned pointer points to memory whose size is
2810 given by the function argument at @var{position-1}, or by the product
2811 of the arguments at @var{position-1} and @var{position-2}. Meaningful
2812 sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this
2813 information to improve the results of @code{__builtin_object_size}.
2815 The function parameter(s) denoting the allocated size are specified by
2816 one or two integer arguments supplied to the attribute. The allocated size
2817 is either the value of the single function argument specified or the product
2818 of the two function arguments specified. Argument numbering starts at
2819 one for ordinary functions, and at two for C++ non-static member functions.
2824 void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2)));
2825 void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2)));
2829 declares that @code{my_calloc} returns memory of the size given by
2830 the product of parameter 1 and 2 and that @code{my_realloc} returns memory
2831 of the size given by parameter 2.
2833 @cindex @code{always_inline} function attribute
2835 Generally, functions are not inlined unless optimization is specified.
2836 For functions declared inline, this attribute inlines the function
2837 independent of any restrictions that otherwise apply to inlining.
2838 Failure to inline such a function is diagnosed as an error.
2839 Note that if such a function is called indirectly the compiler may
2840 or may not inline it depending on optimization level and a failure
2841 to inline an indirect call may or may not be diagnosed.
2843 @cindex @code{artificial} function attribute
2845 This attribute is useful for small inline wrappers that if possible
2846 should appear during debugging as a unit. Depending on the debug
2847 info format it either means marking the function as artificial
2848 or using the caller location for all instructions within the inlined
2851 @cindex @code{assume_aligned} function attribute
2852 @item assume_aligned (@var{alignment})
2853 @itemx assume_aligned (@var{alignment}, @var{offset})
2854 The @code{assume_aligned} attribute may be applied to a function that
2855 returns a pointer. It indicates that the returned pointer is aligned
2856 on a boundary given by @var{alignment}. If the attribute has two
2857 arguments, the second argument is misalignment @var{offset}. Meaningful
2858 values of @var{alignment} are powers of 2 greater than one. Meaningful
2859 values of @var{offset} are greater than zero and less than @var{alignment}.
2864 void* my_alloc1 (size_t) __attribute__((assume_aligned (16)));
2865 void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8)));
2869 declares that @code{my_alloc1} returns 16-byte aligned pointers and
2870 that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
2873 @cindex @code{cold} function attribute
2875 The @code{cold} attribute on functions is used to inform the compiler that
2876 the function is unlikely to be executed. The function is optimized for
2877 size rather than speed and on many targets it is placed into a special
2878 subsection of the text section so all cold functions appear close together,
2879 improving code locality of non-cold parts of program. The paths leading
2880 to calls of cold functions within code are marked as unlikely by the branch
2881 prediction mechanism. It is thus useful to mark functions used to handle
2882 unlikely conditions, such as @code{perror}, as cold to improve optimization
2883 of hot functions that do call marked functions in rare occasions. In C++,
2884 the @code{cold} attribute can be applied to types with the effect of being
2885 propagated to member functions. See
2886 @ref{C++ Attributes}.
2888 When profile feedback is available, via @option{-fprofile-use}, cold functions
2889 are automatically detected and this attribute is ignored.
2891 @cindex @code{const} function attribute
2892 @cindex functions that have no side effects
2894 Calls to functions whose return value is not affected by changes to
2895 the observable state of the program and that have no observable effects
2896 on such state other than to return a value may lend themselves to
2897 optimizations such as common subexpression elimination. Declaring such
2898 functions with the @code{const} attribute allows GCC to avoid emitting
2899 some calls in repeated invocations of the function with the same argument
2905 int square (int) __attribute__ ((const));
2909 tells GCC that subsequent calls to function @code{square} with the same
2910 argument value can be replaced by the result of the first call regardless
2911 of the statements in between.
2913 The @code{const} attribute prohibits a function from reading objects
2914 that affect its return value between successive invocations. However,
2915 functions declared with the attribute can safely read objects that do
2916 not change their return value, such as non-volatile constants.
2918 The @code{const} attribute imposes greater restrictions on a function's
2919 definition than the similar @code{pure} attribute. Declaring the same
2920 function with both the @code{const} and the @code{pure} attribute is
2921 diagnosed. Because a const function cannot have any observable side
2922 effects it does not make sense for it to return @code{void}. Declaring
2923 such a function is diagnosed.
2925 @cindex pointer arguments
2926 Note that a function that has pointer arguments and examines the data
2927 pointed to must @emph{not} be declared @code{const} if the pointed-to
2928 data might change between successive invocations of the function. In
2929 general, since a function cannot distinguish data that might change
2930 from data that cannot, const functions should never take pointer or,
2931 in C++, reference arguments. Likewise, a function that calls a non-const
2932 function usually must not be const itself.
2934 @cindex @code{constructor} function attribute
2935 @cindex @code{destructor} function attribute
2938 @itemx constructor (@var{priority})
2939 @itemx destructor (@var{priority})
2940 The @code{constructor} attribute causes the function to be called
2941 automatically before execution enters @code{main ()}. Similarly, the
2942 @code{destructor} attribute causes the function to be called
2943 automatically after @code{main ()} completes or @code{exit ()} is
2944 called. Functions with these attributes are useful for
2945 initializing data that is used implicitly during the execution of
2948 On some targets the attributes also accept an integer argument to
2949 specify a priority to control the order in which constructor and
2950 destructor functions are run. A constructor
2951 with a smaller priority number runs before a constructor with a larger
2952 priority number; the opposite relationship holds for destructors. Note
2953 that priorities 0-100 are reserved. So, if you have a constructor that
2954 allocates a resource and a destructor that deallocates the same
2955 resource, both functions typically have the same priority. The
2956 priorities for constructor and destructor functions are the same as
2957 those specified for namespace-scope C++ objects (@pxref{C++ Attributes}).
2958 However, at present, the order in which constructors for C++ objects
2959 with static storage duration and functions decorated with attribute
2960 @code{constructor} are invoked is unspecified. In mixed declarations,
2961 attribute @code{init_priority} can be used to impose a specific ordering.
2963 Using the argument forms of the @code{constructor} and @code{destructor}
2964 attributes on targets where the feature is not supported is rejected with
2967 @cindex @code{copy} function attribute
2969 @itemx copy (@var{function})
2970 The @code{copy} attribute applies the set of attributes with which
2971 @var{function} has been declared to the declaration of the function
2972 to which the attribute is applied. The attribute is designed for
2973 libraries that define aliases or function resolvers that are expected
2974 to specify the same set of attributes as their targets. The @code{copy}
2975 attribute can be used with functions, variables, or types. However,
2976 the kind of symbol to which the attribute is applied (either function
2977 or variable) must match the kind of symbol to which the argument refers.
2978 The @code{copy} attribute copies only syntactic and semantic attributes
2979 but not attributes that affect a symbol's linkage or visibility such as
2980 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
2981 and @code{target_clones} attribute are also not copied.
2982 @xref{Common Type Attributes}.
2983 @xref{Common Variable Attributes}.
2985 For example, the @var{StrongAlias} macro below makes use of the @code{alias}
2986 and @code{copy} attributes to define an alias named @var{alloc} for function
2987 @var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and
2988 @var{nothrow}. Thanks to the @code{__typeof__} operator the alias has
2989 the same type as the target function. As a result of the @code{copy}
2990 attribute the alias also shares the same attributes as the target.
2993 #define StrongAlias(TargetFunc, AliasDecl) \
2994 extern __typeof__ (TargetFunc) AliasDecl \
2995 __attribute__ ((alias (#TargetFunc), copy (TargetFunc)));
2997 extern __attribute__ ((alloc_size (1), malloc, nothrow))
2998 void* allocate (size_t);
2999 StrongAlias (allocate, alloc);
3002 @cindex @code{deprecated} function attribute
3004 @itemx deprecated (@var{msg})
3005 The @code{deprecated} attribute results in a warning if the function
3006 is used anywhere in the source file. This is useful when identifying
3007 functions that are expected to be removed in a future version of a
3008 program. The warning also includes the location of the declaration
3009 of the deprecated function, to enable users to easily find further
3010 information about why the function is deprecated, or what they should
3011 do instead. Note that the warnings only occurs for uses:
3014 int old_fn () __attribute__ ((deprecated));
3016 int (*fn_ptr)() = old_fn;
3020 results in a warning on line 3 but not line 2. The optional @var{msg}
3021 argument, which must be a string, is printed in the warning if
3024 The @code{deprecated} attribute can also be used for variables and
3025 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
3027 The message attached to the attribute is affected by the setting of
3028 the @option{-fmessage-length} option.
3030 @cindex @code{error} function attribute
3031 @cindex @code{warning} function attribute
3032 @item error ("@var{message}")
3033 @itemx warning ("@var{message}")
3034 If the @code{error} or @code{warning} attribute
3035 is used on a function declaration and a call to such a function
3036 is not eliminated through dead code elimination or other optimizations,
3037 an error or warning (respectively) that includes @var{message} is diagnosed.
3039 for compile-time checking, especially together with @code{__builtin_constant_p}
3040 and inline functions where checking the inline function arguments is not
3041 possible through @code{extern char [(condition) ? 1 : -1];} tricks.
3043 While it is possible to leave the function undefined and thus invoke
3044 a link failure (to define the function with
3045 a message in @code{.gnu.warning*} section),
3046 when using these attributes the problem is diagnosed
3047 earlier and with exact location of the call even in presence of inline
3048 functions or when not emitting debugging information.
3050 @cindex @code{expected_throw} function attribute
3051 @item expected_throw
3052 This attribute, attached to a function, tells the compiler the function
3053 is more likely to raise or propagate an exception than to return, loop
3054 forever, or terminate the program.
3056 This hint is mostly ignored by the compiler. The only effect is when
3057 it's applied to @code{noreturn} functions and
3058 @samp{-fharden-control-flow-redundancy} is enabled, and
3059 @samp{-fhardcfr-check-noreturn-calls=not-always} is not overridden.
3061 @cindex @code{externally_visible} function attribute
3062 @item externally_visible
3063 This attribute, attached to a global variable or function, nullifies
3064 the effect of the @option{-fwhole-program} command-line option, so the
3065 object remains visible outside the current compilation unit.
3067 If @option{-fwhole-program} is used together with @option{-flto} and
3068 @command{gold} is used as the linker plugin,
3069 @code{externally_visible} attributes are automatically added to functions
3070 (not variable yet due to a current @command{gold} issue)
3071 that are accessed outside of LTO objects according to resolution file
3072 produced by @command{gold}.
3073 For other linkers that cannot generate resolution file,
3074 explicit @code{externally_visible} attributes are still necessary.
3076 @cindex @code{fd_arg} function attribute
3078 @itemx fd_arg (@var{N})
3079 The @code{fd_arg} attribute may be applied to a function that takes an open
3080 file descriptor at referenced argument @var{N}.
3082 It indicates that the passed filedescriptor must not have been closed.
3083 Therefore, when the analyzer is enabled with @option{-fanalyzer}, the
3084 analyzer may emit a @option{-Wanalyzer-fd-use-after-close} diagnostic
3085 if it detects a code path in which a function with this attribute is
3086 called with a closed file descriptor.
3088 The attribute also indicates that the file descriptor must have been checked for
3089 validity before usage. Therefore, analyzer may emit
3090 @option{-Wanalyzer-fd-use-without-check} diagnostic if it detects a code path in
3091 which a function with this attribute is called with a file descriptor that has
3092 not been checked for validity.
3094 @cindex @code{fd_arg_read} function attribute
3096 @itemx fd_arg_read (@var{N})
3097 The @code{fd_arg_read} is identical to @code{fd_arg}, but with the additional
3098 requirement that it might read from the file descriptor, and thus, the file
3099 descriptor must not have been opened as write-only.
3101 The analyzer may emit a @option{-Wanalyzer-access-mode-mismatch}
3102 diagnostic if it detects a code path in which a function with this
3103 attribute is called on a file descriptor opened with @code{O_WRONLY}.
3105 @cindex @code{fd_arg_write} function attribute
3107 @itemx fd_arg_write (@var{N})
3108 The @code{fd_arg_write} is identical to @code{fd_arg_read} except that the
3109 analyzer may emit a @option{-Wanalyzer-access-mode-mismatch} diagnostic if
3110 it detects a code path in which a function with this attribute is called on a
3111 file descriptor opened with @code{O_RDONLY}.
3113 @cindex @code{flatten} function attribute
3115 Generally, inlining into a function is limited. For a function marked with
3116 this attribute, every call inside this function is inlined including the
3117 calls such inlining introduces to the function (but not recursive calls
3118 to the function itself), if possible.
3119 Functions declared with attribute @code{noinline} and similar are not
3120 inlined. Whether the function itself is considered for inlining depends
3121 on its size and the current inlining parameters.
3123 @cindex @code{format} function attribute
3124 @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
3126 @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
3127 The @code{format} attribute specifies that a function takes @code{printf},
3128 @code{scanf}, @code{strftime} or @code{strfmon} style arguments that
3129 should be type-checked against a format string. For example, the
3134 my_printf (void *my_object, const char *my_format, ...)
3135 __attribute__ ((format (printf, 2, 3)));
3139 causes the compiler to check the arguments in calls to @code{my_printf}
3140 for consistency with the @code{printf} style format string argument
3143 The parameter @var{archetype} determines how the format string is
3144 interpreted, and should be @code{printf}, @code{scanf}, @code{strftime},
3145 @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or
3146 @code{strfmon}. (You can also use @code{__printf__},
3147 @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On
3148 MinGW targets, @code{ms_printf}, @code{ms_scanf}, and
3149 @code{ms_strftime} are also present.
3150 @var{archetype} values such as @code{printf} refer to the formats accepted
3151 by the system's C runtime library,
3152 while values prefixed with @samp{gnu_} always refer
3153 to the formats accepted by the GNU C Library. On Microsoft Windows
3154 targets, values prefixed with @samp{ms_} refer to the formats accepted by the
3155 @file{msvcrt.dll} library.
3156 The parameter @var{string-index}
3157 specifies which argument is the format string argument (starting
3158 from 1), while @var{first-to-check} is the number of the first
3159 argument to check against the format string. For functions
3160 where the arguments are not available to be checked (such as
3161 @code{vprintf}), specify the third parameter as zero. In this case the
3162 compiler only checks the format string for consistency. For
3163 @code{strftime} formats, the third parameter is required to be zero.
3164 Since non-static C++ methods have an implicit @code{this} argument, the
3165 arguments of such methods should be counted from two, not one, when
3166 giving values for @var{string-index} and @var{first-to-check}.
3168 In the example above, the format string (@code{my_format}) is the second
3169 argument of the function @code{my_print}, and the arguments to check
3170 start with the third argument, so the correct parameters for the format
3171 attribute are 2 and 3.
3173 @opindex ffreestanding
3174 @opindex fno-builtin
3175 The @code{format} attribute allows you to identify your own functions
3176 that take format strings as arguments, so that GCC can check the
3177 calls to these functions for errors. The compiler always (unless
3178 @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
3179 for the standard library functions @code{printf}, @code{fprintf},
3180 @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
3181 @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
3182 warnings are requested (using @option{-Wformat}), so there is no need to
3183 modify the header file @file{stdio.h}. In C99 mode, the functions
3184 @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
3185 @code{vsscanf} are also checked. Except in strictly conforming C
3186 standard modes, the X/Open function @code{strfmon} is also checked as
3187 are @code{printf_unlocked} and @code{fprintf_unlocked}.
3188 @xref{C Dialect Options,,Options Controlling C Dialect}.
3190 For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is
3191 recognized in the same context. Declarations including these format attributes
3192 are parsed for correct syntax, however the result of checking of such format
3193 strings is not yet defined, and is not carried out by this version of the
3196 The target may also provide additional types of format checks.
3197 @xref{Target Format Checks,,Format Checks Specific to Particular
3200 @cindex @code{format_arg} function attribute
3201 @opindex Wformat-nonliteral
3202 @item format_arg (@var{string-index})
3203 The @code{format_arg} attribute specifies that a function takes one or
3204 more format strings for a @code{printf}, @code{scanf}, @code{strftime} or
3205 @code{strfmon} style function and modifies it (for example, to translate
3206 it into another language), so the result can be passed to a
3207 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
3208 function (with the remaining arguments to the format function the same
3209 as they would have been for the unmodified string). Multiple
3210 @code{format_arg} attributes may be applied to the same function, each
3211 designating a distinct parameter as a format string. For example, the
3216 my_dgettext (char *my_domain, const char *my_format)
3217 __attribute__ ((format_arg (2)));
3221 causes the compiler to check the arguments in calls to a @code{printf},
3222 @code{scanf}, @code{strftime} or @code{strfmon} type function, whose
3223 format string argument is a call to the @code{my_dgettext} function, for
3224 consistency with the format string argument @code{my_format}. If the
3225 @code{format_arg} attribute had not been specified, all the compiler
3226 could tell in such calls to format functions would be that the format
3227 string argument is not constant; this would generate a warning when
3228 @option{-Wformat-nonliteral} is used, but the calls could not be checked
3229 without the attribute.
3231 In calls to a function declared with more than one @code{format_arg}
3232 attribute, each with a distinct argument value, the corresponding
3233 actual function arguments are checked against all format strings
3234 designated by the attributes. This capability is designed to support
3235 the GNU @code{ngettext} family of functions.
3237 The parameter @var{string-index} specifies which argument is the format
3238 string argument (starting from one). Since non-static C++ methods have
3239 an implicit @code{this} argument, the arguments of such methods should
3240 be counted from two.
3242 The @code{format_arg} attribute allows you to identify your own
3243 functions that modify format strings, so that GCC can check the
3244 calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
3245 type function whose operands are a call to one of your own function.
3246 The compiler always treats @code{gettext}, @code{dgettext}, and
3247 @code{dcgettext} in this manner except when strict ISO C support is
3248 requested by @option{-ansi} or an appropriate @option{-std} option, or
3249 @option{-ffreestanding} or @option{-fno-builtin}
3250 is used. @xref{C Dialect Options,,Options
3251 Controlling C Dialect}.
3253 For Objective-C dialects, the @code{format-arg} attribute may refer to an
3254 @code{NSString} reference for compatibility with the @code{format} attribute
3257 The target may also allow additional types in @code{format-arg} attributes.
3258 @xref{Target Format Checks,,Format Checks Specific to Particular
3261 @cindex @code{gnu_inline} function attribute
3263 This attribute should be used with a function that is also declared
3264 with the @code{inline} keyword. It directs GCC to treat the function
3265 as if it were defined in gnu90 mode even when compiling in C99 or
3268 If the function is declared @code{extern}, then this definition of the
3269 function is used only for inlining. In no case is the function
3270 compiled as a standalone function, not even if you take its address
3271 explicitly. Such an address becomes an external reference, as if you
3272 had only declared the function, and had not defined it. This has
3273 almost the effect of a macro. The way to use this is to put a
3274 function definition in a header file with this attribute, and put
3275 another copy of the function, without @code{extern}, in a library
3276 file. The definition in the header file causes most calls to the
3277 function to be inlined. If any uses of the function remain, they
3278 refer to the single copy in the library. Note that the two
3279 definitions of the functions need not be precisely the same, although
3280 if they do not have the same effect your program may behave oddly.
3282 In C, if the function is neither @code{extern} nor @code{static}, then
3283 the function is compiled as a standalone function, as well as being
3284 inlined where possible.
3286 This is how GCC traditionally handled functions declared
3287 @code{inline}. Since ISO C99 specifies a different semantics for
3288 @code{inline}, this function attribute is provided as a transition
3289 measure and as a useful feature in its own right. This attribute is
3290 available in GCC 4.1.3 and later. It is available if either of the
3291 preprocessor macros @code{__GNUC_GNU_INLINE__} or
3292 @code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
3293 Function is As Fast As a Macro}.
3295 In C++, this attribute does not depend on @code{extern} in any way,
3296 but it still requires the @code{inline} keyword to enable its special
3299 @cindex @code{hot} function attribute
3301 The @code{hot} attribute on a function is used to inform the compiler that
3302 the function is a hot spot of the compiled program. The function is
3303 optimized more aggressively and on many targets it is placed into a special
3304 subsection of the text section so all hot functions appear close together,
3305 improving locality. In C++, the @code{hot} attribute can be applied to types
3306 with the effect of being propagated to member functions. See
3307 @ref{C++ Attributes}.
3309 When profile feedback is available, via @option{-fprofile-use}, hot functions
3310 are automatically detected and this attribute is ignored.
3312 @cindex @code{ifunc} function attribute
3313 @cindex indirect functions
3314 @cindex functions that are dynamically resolved
3315 @item ifunc ("@var{resolver}")
3316 The @code{ifunc} attribute is used to mark a function as an indirect
3317 function using the STT_GNU_IFUNC symbol type extension to the ELF
3318 standard. This allows the resolution of the symbol value to be
3319 determined dynamically at load time, and an optimized version of the
3320 routine to be selected for the particular processor or other system
3321 characteristics determined then. To use this attribute, first define
3322 the implementation functions available, and a resolver function that
3323 returns a pointer to the selected implementation function. The
3324 implementation functions' declarations must match the API of the
3325 function being implemented. The resolver should be declared to
3326 be a function taking no arguments and returning a pointer to
3327 a function of the same type as the implementation. For example:
3330 void *my_memcpy (void *dst, const void *src, size_t len)
3336 static void * (*resolve_memcpy (void))(void *, const void *, size_t)
3338 return my_memcpy; // we will just always select this routine
3343 The exported header file declaring the function the user calls would
3347 extern void *memcpy (void *, const void *, size_t);
3351 allowing the user to call @code{memcpy} as a regular function, unaware of
3352 the actual implementation. Finally, the indirect function needs to be
3353 defined in the same translation unit as the resolver function:
3356 void *memcpy (void *, const void *, size_t)
3357 __attribute__ ((ifunc ("resolve_memcpy")));
3360 In C++, the @code{ifunc} attribute takes a string that is the mangled name
3361 of the resolver function. A C++ resolver for a non-static member function
3362 of class @code{C} should be declared to return a pointer to a non-member
3363 function taking pointer to @code{C} as the first argument, followed by
3364 the same arguments as of the implementation function. G++ checks
3365 the signatures of the two functions and issues
3366 a @option{-Wattribute-alias} warning for mismatches. To suppress a warning
3367 for the necessary cast from a pointer to the implementation member function
3368 to the type of the corresponding non-member function use
3369 the @option{-Wno-pmf-conversions} option. For example:
3375 int debug_impl (int);
3376 int optimized_impl (int);
3378 typedef int Func (S*, int);
3380 static Func* resolver ();
3383 int interface (int);
3386 int S::debug_impl (int) @{ /* @r{@dots{}} */ @}
3387 int S::optimized_impl (int) @{ /* @r{@dots{}} */ @}
3389 S::Func* S::resolver ()
3391 int (S::*pimpl) (int)
3392 = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl;
3394 // Cast triggers -Wno-pmf-conversions.
3395 return reinterpret_cast<Func*>(pimpl);
3398 int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv")));
3401 Indirect functions cannot be weak. Binutils version 2.20.1 or higher
3402 and GNU C Library version 2.11.1 are required to use this feature.
3404 @cindex @code{interrupt_handler} function attribute
3405 @cindex @code{interrupt} function attribute
3407 @itemx interrupt_handler
3408 Many GCC back ends support attributes to indicate that a function is
3409 an interrupt handler, which tells the compiler to generate function
3410 entry and exit sequences that differ from those from regular
3411 functions. The exact syntax and behavior are target-specific;
3412 refer to the following subsections for details.
3414 @cindex @code{leaf} function attribute
3416 Calls to external functions with this attribute must return to the
3417 current compilation unit only by return or by exception handling. In
3418 particular, a leaf function is not allowed to invoke callback functions
3419 passed to it from the current compilation unit, directly call functions
3420 exported by the unit, or @code{longjmp} into the unit. Leaf functions
3421 might still call functions from other compilation units and thus they
3422 are not necessarily leaf in the sense that they contain no function
3425 The attribute is intended for library functions to improve dataflow
3426 analysis. The compiler takes the hint that any data not escaping the
3427 current compilation unit cannot be used or modified by the leaf
3428 function. For example, the @code{sin} function is a leaf function, but
3429 @code{qsort} is not.
3431 Note that leaf functions might indirectly run a signal handler defined
3432 in the current compilation unit that uses static variables. Similarly,
3433 when lazy symbol resolution is in effect, leaf functions might invoke
3434 indirect functions whose resolver function or implementation function is
3435 defined in the current compilation unit and uses static variables. There
3436 is no standard-compliant way to write such a signal handler, resolver
3437 function, or implementation function, and the best that you can do is to
3438 remove the @code{leaf} attribute or mark all such static variables
3439 @code{volatile}. Lastly, for ELF-based systems that support symbol
3440 interposition, care should be taken that functions defined in the
3441 current compilation unit do not unexpectedly interpose other symbols
3442 based on the defined standards mode and defined feature test macros;
3443 otherwise an inadvertent callback would be added.
3445 The attribute has no effect on functions defined within the current
3446 compilation unit. This is to allow easy merging of multiple compilation
3447 units into one, for example, by using the link-time optimization. For
3448 this reason the attribute is not allowed on types to annotate indirect
3451 @cindex @code{malloc} function attribute
3452 @cindex functions that behave like malloc
3454 @item malloc (@var{deallocator})
3455 @item malloc (@var{deallocator}, @var{ptr-index})
3456 Attribute @code{malloc} indicates that a function is @code{malloc}-like,
3457 i.e., that the pointer @var{P} returned by the function cannot alias any
3458 other pointer valid when the function returns, and moreover no
3459 pointers to valid objects occur in any storage addressed by @var{P}. In
3460 addition, GCC predicts that a function with the attribute returns
3461 non-null in most cases.
3463 Independently, the form of the attribute with one or two arguments
3464 associates @code{deallocator} as a suitable deallocation function for
3465 pointers returned from the @code{malloc}-like function. @var{ptr-index}
3466 denotes the positional argument to which when the pointer is passed in
3467 calls to @code{deallocator} has the effect of deallocating it.
3469 Using the attribute with no arguments is designed to improve optimization
3470 by relying on the aliasing property it implies. Functions like @code{malloc}
3471 and @code{calloc} have this property because they return a pointer to
3472 uninitialized or zeroed-out, newly obtained storage. However, functions
3473 like @code{realloc} do not have this property, as they may return pointers
3474 to storage containing pointers to existing objects. Additionally, since
3475 all such functions are assumed to return null only infrequently, callers
3476 can be optimized based on that assumption.
3478 Associating a function with a @var{deallocator} helps detect calls to
3479 mismatched allocation and deallocation functions and diagnose them under
3480 the control of options such as @option{-Wmismatched-dealloc}. It also
3481 makes it possible to diagnose attempts to deallocate objects that were not
3482 allocated dynamically, by @option{-Wfree-nonheap-object}. To indicate
3483 that an allocation function both satisifies the nonaliasing property and
3484 has a deallocator associated with it, both the plain form of the attribute
3485 and the one with the @var{deallocator} argument must be used. The same
3486 function can be both an allocator and a deallocator. Since inlining one
3487 of the associated functions but not the other could result in apparent
3488 mismatches, this form of attribute @code{malloc} is not accepted on inline
3489 functions. For the same reason, using the attribute prevents both
3490 the allocation and deallocation functions from being expanded inline.
3492 For example, besides stating that the functions return pointers that do
3493 not alias any others, the following declarations make @code{fclose}
3494 a suitable deallocator for pointers returned from all functions except
3495 @code{popen}, and @code{pclose} as the only suitable deallocator for
3496 pointers returned from @code{popen}. The deallocator functions must
3497 be declared before they can be referenced in the attribute.
3503 __attribute__ ((malloc, malloc (fclose, 1)))
3504 FILE* fdopen (int, const char*);
3505 __attribute__ ((malloc, malloc (fclose, 1)))
3506 FILE* fopen (const char*, const char*);
3507 __attribute__ ((malloc, malloc (fclose, 1)))
3508 FILE* fmemopen(void *, size_t, const char *);
3509 __attribute__ ((malloc, malloc (pclose, 1)))
3510 FILE* popen (const char*, const char*);
3511 __attribute__ ((malloc, malloc (fclose, 1)))
3512 FILE* tmpfile (void);
3515 The warnings guarded by @option{-fanalyzer} respect allocation and
3516 deallocation pairs marked with the @code{malloc}. In particular:
3521 The analyzer emits a @option{-Wanalyzer-mismatching-deallocation}
3522 diagnostic if there is an execution path in which the result of an
3523 allocation call is passed to a different deallocator.
3526 The analyzer emits a @option{-Wanalyzer-double-free}
3527 diagnostic if there is an execution path in which a value is passed
3528 more than once to a deallocation call.
3531 The analyzer considers the possibility that an allocation function
3532 could fail and return null. If there are
3533 execution paths in which an unchecked result of an allocation call is
3534 dereferenced or passed to a function requiring a non-null argument,
3536 @option{-Wanalyzer-possible-null-dereference} and
3537 @option{-Wanalyzer-possible-null-argument} diagnostics.
3538 If the allocator always returns non-null, use
3539 @code{__attribute__ ((returns_nonnull))} to suppress these warnings.
3542 char *xstrdup (const char *)
3543 __attribute__((malloc (free), returns_nonnull));
3547 The analyzer emits a @option{-Wanalyzer-use-after-free}
3548 diagnostic if there is an execution path in which the memory passed
3549 by pointer to a deallocation call is used after the deallocation.
3552 The analyzer emits a @option{-Wanalyzer-malloc-leak} diagnostic if
3553 there is an execution path in which the result of an allocation call
3554 is leaked (without being passed to the deallocation function).
3557 The analyzer emits a @option{-Wanalyzer-free-of-non-heap} diagnostic
3558 if a deallocation function is used on a global or on-stack variable.
3562 The analyzer assumes that deallocators can gracefully handle the null
3563 pointer. If this is not the case, the deallocator can be marked with
3564 @code{__attribute__((nonnull))} so that @option{-fanalyzer} can emit
3565 a @option{-Wanalyzer-possible-null-argument} diagnostic for code paths
3566 in which the deallocator is called with null.
3568 @cindex @code{no_icf} function attribute
3570 This function attribute prevents a functions from being merged with another
3571 semantically equivalent function.
3573 @cindex @code{no_instrument_function} function attribute
3574 @opindex finstrument-functions
3577 @item no_instrument_function
3578 If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are
3579 given, profiling function calls are
3580 generated at entry and exit of most user-compiled functions.
3581 Functions with this attribute are not so instrumented.
3583 @cindex @code{no_profile_instrument_function} function attribute
3584 @item no_profile_instrument_function
3585 The @code{no_profile_instrument_function} attribute on functions is used
3586 to inform the compiler that it should not process any profile feedback based
3587 optimization code instrumentation.
3589 @cindex @code{no_reorder} function attribute
3591 Do not reorder functions or variables marked @code{no_reorder}
3592 against each other or top level assembler statements the executable.
3593 The actual order in the program will depend on the linker command
3594 line. Static variables marked like this are also not removed.
3595 This has a similar effect
3596 as the @option{-fno-toplevel-reorder} option, but only applies to the
3599 @cindex @code{no_sanitize} function attribute
3600 @item no_sanitize ("@var{sanitize_option}")
3601 The @code{no_sanitize} attribute on functions is used
3602 to inform the compiler that it should not do sanitization of any option
3603 mentioned in @var{sanitize_option}. A list of values acceptable by
3604 the @option{-fsanitize} option can be provided.
3607 void __attribute__ ((no_sanitize ("alignment", "object-size")))
3608 f () @{ /* @r{Do something.} */; @}
3609 void __attribute__ ((no_sanitize ("alignment,object-size")))
3610 g () @{ /* @r{Do something.} */; @}
3613 @cindex @code{no_sanitize_address} function attribute
3614 @item no_sanitize_address
3615 @itemx no_address_safety_analysis
3616 The @code{no_sanitize_address} attribute on functions is used
3617 to inform the compiler that it should not instrument memory accesses
3618 in the function when compiling with the @option{-fsanitize=address} option.
3619 The @code{no_address_safety_analysis} is a deprecated alias of the
3620 @code{no_sanitize_address} attribute, new code should use
3621 @code{no_sanitize_address}.
3623 @cindex @code{no_sanitize_thread} function attribute
3624 @item no_sanitize_thread
3625 The @code{no_sanitize_thread} attribute on functions is used
3626 to inform the compiler that it should not instrument memory accesses
3627 in the function when compiling with the @option{-fsanitize=thread} option.
3629 @cindex @code{no_sanitize_undefined} function attribute
3630 @item no_sanitize_undefined
3631 The @code{no_sanitize_undefined} attribute on functions is used
3632 to inform the compiler that it should not check for undefined behavior
3633 in the function when compiling with the @option{-fsanitize=undefined} option.
3635 @cindex @code{no_sanitize_coverage} function attribute
3636 @item no_sanitize_coverage
3637 The @code{no_sanitize_coverage} attribute on functions is used
3638 to inform the compiler that it should not do coverage-guided
3639 fuzzing code instrumentation (@option{-fsanitize-coverage}).
3641 @cindex @code{no_split_stack} function attribute
3642 @opindex fsplit-stack
3643 @item no_split_stack
3644 If @option{-fsplit-stack} is given, functions have a small
3645 prologue which decides whether to split the stack. Functions with the
3646 @code{no_split_stack} attribute do not have that prologue, and thus
3647 may run with only a small amount of stack space available.
3649 @cindex @code{no_stack_limit} function attribute
3650 @item no_stack_limit
3651 This attribute locally overrides the @option{-fstack-limit-register}
3652 and @option{-fstack-limit-symbol} command-line options; it has the effect
3653 of disabling stack limit checking in the function it applies to.
3655 @cindex @code{no_stack_protector} function attribute
3656 @item no_stack_protector
3657 This attribute prevents stack protection code for the function.
3659 @cindex @code{noclone} function attribute
3661 This function attribute prevents a function from being considered for
3662 cloning---a mechanism that produces specialized copies of functions
3663 and which is (currently) performed by interprocedural constant
3666 @cindex @code{noinline} function attribute
3668 This function attribute prevents a function from being considered for
3669 inlining. It also disables some other interprocedural optimizations; it's
3670 preferable to use the more comprehensive @code{noipa} attribute instead
3671 if that is your goal.
3673 @c Don't enumerate the optimizations by name here; we try to be
3674 @c future-compatible with this mechanism.
3675 Even if a function is declared with the @code{noinline} attribute,
3676 there are optimizations other than inlining that can cause calls to be
3677 optimized away if it does not have side effects, although the function
3678 call is live. To keep such calls from being optimized away, put
3685 (@pxref{Extended Asm}) in the called function, to serve as a special
3688 @cindex @code{noipa} function attribute
3690 Disable interprocedural optimizations between the function with this
3691 attribute and its callers, as if the body of the function is not available
3692 when optimizing callers and the callers are unavailable when optimizing
3693 the body. This attribute implies @code{noinline}, @code{noclone} and
3694 @code{no_icf} attributes. However, this attribute is not equivalent
3695 to a combination of other attributes, because its purpose is to suppress
3696 existing and future optimizations employing interprocedural analysis,
3697 including those that do not have an attribute suitable for disabling
3700 @cindex @code{nonnull} function attribute
3701 @cindex functions with non-null pointer arguments
3703 @itemx nonnull (@var{arg-index}, @dots{})
3704 The @code{nonnull} attribute may be applied to a function that takes at
3705 least one argument of a pointer type. It indicates that the referenced
3706 arguments must be non-null pointers. For instance, the declaration:
3710 my_memcpy (void *dest, const void *src, size_t len)
3711 __attribute__((nonnull (1, 2)));
3715 informs the compiler that, in calls to @code{my_memcpy}, arguments
3716 @var{dest} and @var{src} must be non-null.
3718 The attribute has an effect both on functions calls and function definitions.
3722 @item If the compiler determines that a null pointer is
3723 passed in an argument slot marked as non-null, and the
3724 @option{-Wnonnull} option is enabled, a warning is issued.
3725 @xref{Warning Options}.
3726 @item The @option{-fisolate-erroneous-paths-attribute} option can be
3727 specified to have GCC transform calls with null arguments to non-null
3728 functions into traps. @xref{Optimize Options}.
3729 @item The compiler may also perform optimizations based on the
3730 knowledge that certain function arguments cannot be null. These
3731 optimizations can be disabled by the
3732 @option{-fno-delete-null-pointer-checks} option. @xref{Optimize Options}.
3735 For function definitions:
3737 @item If the compiler determines that a function parameter that is
3738 marked with nonnull is compared with null, and
3739 @option{-Wnonnull-compare} option is enabled, a warning is issued.
3740 @xref{Warning Options}.
3741 @item The compiler may also perform optimizations based on the
3742 knowledge that @code{nonnull} parameters cannot be null. This can
3743 currently not be disabled other than by removing the nonnull
3747 If no @var{arg-index} is given to the @code{nonnull} attribute,
3748 all pointer arguments are marked as non-null. To illustrate, the
3749 following declaration is equivalent to the previous example:
3753 my_memcpy (void *dest, const void *src, size_t len)
3754 __attribute__((nonnull));
3757 @cindex @code{noplt} function attribute
3759 The @code{noplt} attribute is the counterpart to option @option{-fno-plt}.
3760 Calls to functions marked with this attribute in position-independent code
3765 /* Externally defined function foo. */
3766 int foo () __attribute__ ((noplt));
3769 main (/* @r{@dots{}} */)
3778 The @code{noplt} attribute on function @code{foo}
3779 tells the compiler to assume that
3780 the function @code{foo} is externally defined and that the call to
3781 @code{foo} must avoid the PLT
3782 in position-independent code.
3784 In position-dependent code, a few targets also convert calls to
3785 functions that are marked to not use the PLT to use the GOT instead.
3787 @cindex @code{noreturn} function attribute
3788 @cindex functions that never return
3790 A few standard library functions, such as @code{abort} and @code{exit},
3791 cannot return. GCC knows this automatically. Some programs define
3792 their own functions that never return. You can declare them
3793 @code{noreturn} to tell the compiler this fact. For example,
3797 void fatal () __attribute__ ((noreturn));
3800 fatal (/* @r{@dots{}} */)
3802 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
3808 The @code{noreturn} keyword tells the compiler to assume that
3809 @code{fatal} cannot return. It can then optimize without regard to what
3810 would happen if @code{fatal} ever did return. This makes slightly
3811 better code. More importantly, it helps avoid spurious warnings of
3812 uninitialized variables.
3814 The @code{noreturn} keyword does not affect the exceptional path when that
3815 applies: a @code{noreturn}-marked function may still return to the caller
3816 by throwing an exception or calling @code{longjmp}.
3818 In order to preserve backtraces, GCC will never turn calls to
3819 @code{noreturn} functions into tail calls.
3821 Do not assume that registers saved by the calling function are
3822 restored before calling the @code{noreturn} function.
3824 It does not make sense for a @code{noreturn} function to have a return
3825 type other than @code{void}.
3827 @cindex @code{nothrow} function attribute
3829 The @code{nothrow} attribute is used to inform the compiler that a
3830 function cannot throw an exception. For example, most functions in
3831 the standard C library can be guaranteed not to throw an exception
3832 with the notable exceptions of @code{qsort} and @code{bsearch} that
3833 take function pointer arguments.
3835 @cindex @code{null_terminated_string_arg} function attribute
3836 @item null_terminated_string_arg
3837 @itemx null_terminated_string_arg (@var{N})
3838 The @code{null_terminated_string_arg} attribute may be applied to a
3839 function that takes a @code{char *} or @code{const char *} at
3840 referenced argument @var{N}.
3842 It indicates that the passed argument must be a C-style null-terminated
3843 string. Specifically, the presence of the attribute implies that, if
3844 the pointer is non-null, the function may scan through the referenced
3845 buffer looking for the first zero byte.
3847 In particular, when the analyzer is enabled (via @option{-fanalyzer}),
3848 if the pointer is non-null, it will simulate scanning for the first
3849 zero byte in the referenced buffer, and potentially emit
3850 @option{-Wanalyzer-use-of-uninitialized-value}
3851 or @option{-Wanalyzer-out-of-bounds} on improperly terminated buffers.
3853 For example, given the following:
3856 char *example_1 (const char *p)
3857 __attribute__((null_terminated_string_arg (1)));
3860 the analyzer will check that any non-null pointers passed to the function
3861 are validly terminated.
3863 If the parameter must be non-null, it is appropriate to use both this
3864 attribute and the attribute @code{nonnull}, such as in:
3867 extern char *example_2 (const char *p)
3868 __attribute__((null_terminated_string_arg (1),
3872 See the @code{nonnull} attribute for more information and
3875 If the pointer argument is also referred to by an @code{access} attribute on the
3876 function with @var{access-mode} either @code{read_only} or @code{read_write}
3877 and the latter attribute has the optional @var{size-index} argument
3878 referring to a size argument, this expressses the maximum size of the access.
3882 extern char *example_fn (const char *p, size_t n)
3883 __attribute__((null_terminated_string_arg (1),
3884 access (read_only, 1, 2),
3888 the analyzer will require the first parameter to be non-null, and either
3889 be validly null-terminated, or validly readable up to the size specified by
3890 the second parameter.
3892 @cindex @code{optimize} function attribute
3893 @item optimize (@var{level}, @dots{})
3894 @item optimize (@var{string}, @dots{})
3895 The @code{optimize} attribute is used to specify that a function is to
3896 be compiled with different optimization options than specified on the
3897 command line. The optimize attribute arguments of a function behave
3898 as if appended to the command-line.
3900 Valid arguments are constant non-negative integers and
3901 strings. Each numeric argument specifies an optimization @var{level}.
3902 Each @var{string} argument consists of one or more comma-separated
3903 substrings. Each substring that begins with the letter @code{O} refers
3904 to an optimization option such as @option{-O0} or @option{-Os}. Other
3905 substrings are taken as suffixes to the @code{-f} prefix jointly
3906 forming the name of an optimization option. @xref{Optimize Options}.
3908 @samp{#pragma GCC optimize} can be used to set optimization options
3909 for more than one function. @xref{Function Specific Option Pragmas},
3910 for details about the pragma.
3912 Providing multiple strings as arguments separated by commas to specify
3913 multiple options is equivalent to separating the option suffixes with
3914 a comma (@samp{,}) within a single string. Spaces are not permitted
3917 Not every optimization option that starts with the @var{-f} prefix
3918 specified by the attribute necessarily has an effect on the function.
3919 The @code{optimize} attribute should be used for debugging purposes only.
3920 It is not suitable in production code.
3922 @cindex @code{patchable_function_entry} function attribute
3923 @cindex extra NOP instructions at the function entry point
3924 @item patchable_function_entry
3925 In case the target's text segment can be made writable at run time by
3926 any means, padding the function entry with a number of NOPs can be
3927 used to provide a universal tool for instrumentation.
3929 The @code{patchable_function_entry} function attribute can be used to
3930 change the number of NOPs to any desired value. The two-value syntax
3931 is the same as for the command-line switch
3932 @option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with
3933 the function entry point before the @var{M}th NOP instruction.
3934 @var{M} defaults to 0 if omitted e.g.@: function entry point is before
3937 If patchable function entries are enabled globally using the command-line
3938 option @option{-fpatchable-function-entry=N,M}, then you must disable
3939 instrumentation on all functions that are part of the instrumentation
3940 framework with the attribute @code{patchable_function_entry (0)}
3941 to prevent recursion.
3943 @cindex @code{pure} function attribute
3944 @cindex functions that have no side effects
3947 Calls to functions that have no observable effects on the state of
3948 the program other than to return a value may lend themselves to optimizations
3949 such as common subexpression elimination. Declaring such functions with
3950 the @code{pure} attribute allows GCC to avoid emitting some calls in repeated
3951 invocations of the function with the same argument values.
3953 The @code{pure} attribute prohibits a function from modifying the state
3954 of the program that is observable by means other than inspecting
3955 the function's return value. However, functions declared with the @code{pure}
3956 attribute can safely read any non-volatile objects, and modify the value of
3957 objects in a way that does not affect their return value or the observable
3958 state of the program.
3963 int hash (char *) __attribute__ ((pure));
3967 tells GCC that subsequent calls to the function @code{hash} with the same
3968 string can be replaced by the result of the first call provided the state
3969 of the program observable by @code{hash}, including the contents of the array
3970 itself, does not change in between. Even though @code{hash} takes a non-const
3971 pointer argument it must not modify the array it points to, or any other object
3972 whose value the rest of the program may depend on. However, the caller may
3973 safely change the contents of the array between successive calls to
3974 the function (doing so disables the optimization). The restriction also
3975 applies to member objects referenced by the @code{this} pointer in C++
3976 non-static member functions.
3978 Some common examples of pure functions are @code{strlen} or @code{memcmp}.
3979 Interesting non-pure functions are functions with infinite loops or those
3980 depending on volatile memory or other system resource, that may change between
3981 consecutive calls (such as the standard C @code{feof} function in
3982 a multithreading environment).
3984 The @code{pure} attribute imposes similar but looser restrictions on
3985 a function's definition than the @code{const} attribute: @code{pure}
3986 allows the function to read any non-volatile memory, even if it changes
3987 in between successive invocations of the function. Declaring the same
3988 function with both the @code{pure} and the @code{const} attribute is
3989 diagnosed. Because a pure function cannot have any observable side
3990 effects it does not make sense for such a function to return @code{void}.
3991 Declaring such a function is diagnosed.
3993 @cindex @code{retain} function attribute
3995 For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
3996 will save the function from linker garbage collection. To support
3997 this behavior, functions that have not been placed in specific sections
3998 (e.g. by the @code{section} attribute, or the @code{-ffunction-sections}
3999 option), will be placed in new, unique sections.
4001 This additional functionality requires Binutils version 2.36 or later.
4003 @cindex @code{returns_nonnull} function attribute
4004 @item returns_nonnull
4005 The @code{returns_nonnull} attribute specifies that the function
4006 return value should be a non-null pointer. For instance, the declaration:
4010 mymalloc (size_t len) __attribute__((returns_nonnull));
4014 lets the compiler optimize callers based on the knowledge
4015 that the return value will never be null.
4017 @cindex @code{returns_twice} function attribute
4018 @cindex functions that return more than once
4020 The @code{returns_twice} attribute tells the compiler that a function may
4021 return more than one time. The compiler ensures that all registers
4022 are dead before calling such a function and emits a warning about
4023 the variables that may be clobbered after the second return from the
4024 function. Examples of such functions are @code{setjmp} and @code{vfork}.
4025 The @code{longjmp}-like counterpart of such function, if any, might need
4026 to be marked with the @code{noreturn} attribute.
4028 @cindex @code{section} function attribute
4029 @cindex functions in arbitrary sections
4030 @item section ("@var{section-name}")
4031 Normally, the compiler places the code it generates in the @code{text} section.
4032 Sometimes, however, you need additional sections, or you need certain
4033 particular functions to appear in special sections. The @code{section}
4034 attribute specifies that a function lives in a particular section.
4035 For example, the declaration:
4038 extern void foobar (void) __attribute__ ((section ("bar")));
4042 puts the function @code{foobar} in the @code{bar} section.
4044 Some file formats do not support arbitrary sections so the @code{section}
4045 attribute is not available on all platforms.
4046 If you need to map the entire contents of a module to a particular
4047 section, consider using the facilities of the linker instead.
4049 @cindex @code{sentinel} function attribute
4051 @itemx sentinel (@var{position})
4052 This function attribute indicates that an argument in a call to the function
4053 is expected to be an explicit @code{NULL}. The attribute is only valid on
4054 variadic functions. By default, the sentinel is expected to be the last
4055 argument of the function call. If the optional @var{position} argument
4056 is specified to the attribute, the sentinel must be located at
4057 @var{position} counting backwards from the end of the argument list.
4060 __attribute__ ((sentinel))
4062 __attribute__ ((sentinel(0)))
4065 The attribute is automatically set with a position of 0 for the built-in
4066 functions @code{execl} and @code{execlp}. The built-in function
4067 @code{execle} has the attribute set with a position of 1.
4069 A valid @code{NULL} in this context is defined as zero with any object
4070 pointer type. If your system defines the @code{NULL} macro with
4071 an integer type then you need to add an explicit cast. During
4072 installation GCC replaces the system @code{<stddef.h>} header with
4073 a copy that redefines NULL appropriately.
4075 The warnings for missing or incorrect sentinels are enabled with
4078 @cindex @code{simd} function attribute
4080 @itemx simd("@var{mask}")
4081 This attribute enables creation of one or more function versions that
4082 can process multiple arguments using SIMD instructions from a
4083 single invocation. Specifying this attribute allows compiler to
4084 assume that such versions are available at link time (provided
4085 in the same or another translation unit). Generated versions are
4086 target-dependent and described in the corresponding Vector ABI document. For
4087 x86_64 target this document can be found
4088 @w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}.
4090 The optional argument @var{mask} may have the value
4091 @code{notinbranch} or @code{inbranch},
4092 and instructs the compiler to generate non-masked or masked
4093 clones correspondingly. By default, all clones are generated.
4095 If the attribute is specified and @code{#pragma omp declare simd} is
4096 present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd}
4097 switch is specified, then the attribute is ignored.
4099 @cindex @code{stack_protect} function attribute
4101 This attribute adds stack protection code to the function if
4102 flags @option{-fstack-protector}, @option{-fstack-protector-strong}
4103 or @option{-fstack-protector-explicit} are set.
4105 @cindex @code{symver} function attribute
4106 @item symver ("@var{name2}@@@var{nodename}")
4107 On ELF targets this attribute creates a symbol version. The @var{name2} part
4108 of the parameter is the actual name of the symbol by which it will be
4109 externally referenced. The @code{nodename} portion should be the name of a
4110 node specified in the version script supplied to the linker when building a
4111 shared library. Versioned symbol must be defined and must be exported with
4115 __attribute__ ((__symver__ ("foo@@VERS_1"))) int
4121 Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
4124 One can also define multiple version for a given symbol
4125 (starting from binutils 2.35).
4128 __attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
4129 int symver_foo_v1 (void)
4134 This example creates a symbol name @code{symver_foo_v1}
4135 which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
4137 If you have an older release of binutils, then symbol alias needs to
4141 __attribute__ ((__symver__ ("foo@@VERS_2")))
4147 __attribute__ ((__symver__ ("foo@@VERS_3")))
4148 __attribute__ ((alias ("foo_v1")))
4149 int symver_foo_v1 (void);
4152 Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
4153 addition to creating a symbol version (as if
4154 @code{"@var{name2}@@@var{nodename}"} was used) the version will be also used
4155 to resolve @var{name2} by the linker.
4157 @cindex @code{tainted_args} function attribute
4159 The @code{tainted_args} attribute is used to specify that a function is called
4160 in a way that requires sanitization of its arguments, such as a system
4161 call in an operating system kernel. Such a function can be considered part
4162 of the ``attack surface'' of the program. The attribute can be used both
4163 on function declarations, and on field declarations containing function
4164 pointers. In the latter case, any function used as an initializer of
4165 such a callback field will be treated as being called with tainted
4168 The analyzer will pay particular attention to such functions when
4169 @option{-fanalyzer} is supplied, potentially issuing warnings guarded by
4170 @option{-Wanalyzer-tainted-allocation-size},
4171 @option{-Wanalyzer-tainted-array-index},
4172 @option{-Wanalyzer-tainted-divisor},
4173 @option{-Wanalyzer-tainted-offset},
4174 and @option{-Wanalyzer-tainted-size}.
4176 @cindex @code{target} function attribute
4177 @item target (@var{string}, @dots{})
4178 Multiple target back ends implement the @code{target} attribute
4179 to specify that a function is to
4180 be compiled with different target options than specified on the
4181 command line. The original target command-line options are ignored.
4182 One or more strings can be provided as arguments.
4183 Each string consists of one or more comma-separated suffixes to
4184 the @code{-m} prefix jointly forming the name of a machine-dependent
4185 option. @xref{Submodel Options,,Machine-Dependent Options}.
4187 The @code{target} attribute can be used for instance to have a function
4188 compiled with a different ISA (instruction set architecture) than the
4189 default. @samp{#pragma GCC target} can be used to specify target-specific
4190 options for more than one function. @xref{Function Specific Option Pragmas},
4191 for details about the pragma.
4193 For instance, on an x86, you could declare one function with the
4194 @code{target("sse4.1,arch=core2")} attribute and another with
4195 @code{target("sse4a,arch=amdfam10")}. This is equivalent to
4196 compiling the first function with @option{-msse4.1} and
4197 @option{-march=core2} options, and the second function with
4198 @option{-msse4a} and @option{-march=amdfam10} options. It is up to you
4199 to make sure that a function is only invoked on a machine that
4200 supports the particular ISA it is compiled for (for example by using
4201 @code{cpuid} on x86 to determine what feature bits and architecture
4205 int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
4206 int sse3_func (void) __attribute__ ((__target__ ("sse3")));
4209 Providing multiple strings as arguments separated by commas to specify
4210 multiple options is equivalent to separating the option suffixes with
4211 a comma (@samp{,}) within a single string. Spaces are not permitted
4214 The options supported are specific to each target; refer to @ref{x86
4215 Function Attributes}, @ref{PowerPC Function Attributes},
4216 @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
4217 @ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes}
4220 @cindex @code{target_clones} function attribute
4221 @item target_clones (@var{options})
4222 The @code{target_clones} attribute is used to specify that a function
4223 be cloned into multiple versions compiled with different target options
4224 than specified on the command line. The supported options and restrictions
4225 are the same as for @code{target} attribute.
4227 For instance, on an x86, you could compile a function with
4228 @code{target_clones("sse4.1,avx")}. GCC creates two function clones,
4229 one compiled with @option{-msse4.1} and another with @option{-mavx}.
4231 On a PowerPC, you can compile a function with
4232 @code{target_clones("cpu=power9,default")}. GCC will create two
4233 function clones, one compiled with @option{-mcpu=power9} and another
4234 with the default options. GCC must be configured to use GLIBC 2.23 or
4235 newer in order to use the @code{target_clones} attribute.
4237 It also creates a resolver function (see
4238 the @code{ifunc} attribute above) that dynamically selects a clone
4239 suitable for current architecture. The resolver is created only if there
4240 is a usage of a function with @code{target_clones} attribute.
4242 Note that any subsequent call of a function without @code{target_clone}
4243 from a @code{target_clone} caller will not lead to copying
4244 (target clone) of the called function.
4245 If you want to enforce such behaviour,
4246 we recommend declaring the calling function with the @code{flatten} attribute?
4248 @cindex @code{unavailable} function attribute
4250 @itemx unavailable (@var{msg})
4251 The @code{unavailable} attribute results in an error if the function
4252 is used anywhere in the source file. This is useful when identifying
4253 functions that have been removed from a particular variation of an
4254 interface. Other than emitting an error rather than a warning, the
4255 @code{unavailable} attribute behaves in the same manner as
4258 The @code{unavailable} attribute can also be used for variables and
4259 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
4261 @cindex @code{unused} function attribute
4263 This attribute, attached to a function, means that the function is meant
4264 to be possibly unused. GCC does not produce a warning for this
4267 @cindex @code{used} function attribute
4269 This attribute, attached to a function, means that code must be emitted
4270 for the function even if it appears that the function is not referenced.
4271 This is useful, for example, when the function is referenced only in
4274 When applied to a member function of a C++ class template, the
4275 attribute also means that the function is instantiated if the
4276 class itself is instantiated.
4278 @cindex @code{visibility} function attribute
4279 @item visibility ("@var{visibility_type}")
4280 This attribute affects the linkage of the declaration to which it is attached.
4281 It can be applied to variables (@pxref{Common Variable Attributes}) and types
4282 (@pxref{Common Type Attributes}) as well as functions.
4284 There are four supported @var{visibility_type} values: default,
4285 hidden, protected or internal visibility.
4288 void __attribute__ ((visibility ("protected")))
4289 f () @{ /* @r{Do something.} */; @}
4290 int i __attribute__ ((visibility ("hidden")));
4293 The possible values of @var{visibility_type} correspond to the
4294 visibility settings in the ELF gABI.
4297 @c keep this list of visibilities in alphabetical order.
4300 Default visibility is the normal case for the object file format.
4301 This value is available for the visibility attribute to override other
4302 options that may change the assumed visibility of entities.
4304 On ELF, default visibility means that the declaration is visible to other
4305 modules and, in shared libraries, means that the declared entity may be
4308 On Darwin, default visibility means that the declaration is visible to
4311 Default visibility corresponds to ``external linkage'' in the language.
4314 Hidden visibility indicates that the entity declared has a new
4315 form of linkage, which we call ``hidden linkage''. Two
4316 declarations of an object with hidden linkage refer to the same object
4317 if they are in the same shared object.
4320 Internal visibility is like hidden visibility, but with additional
4321 processor specific semantics. Unless otherwise specified by the
4322 psABI, GCC defines internal visibility to mean that a function is
4323 @emph{never} called from another module. Compare this with hidden
4324 functions which, while they cannot be referenced directly by other
4325 modules, can be referenced indirectly via function pointers. By
4326 indicating that a function cannot be called from outside the module,
4327 GCC may for instance omit the load of a PIC register since it is known
4328 that the calling function loaded the correct value.
4331 Protected visibility is like default visibility except that it
4332 indicates that references within the defining module bind to the
4333 definition in that module. That is, the declared entity cannot be
4334 overridden by another module.
4338 All visibilities are supported on many, but not all, ELF targets
4339 (supported when the assembler supports the @samp{.visibility}
4340 pseudo-op). Default visibility is supported everywhere. Hidden
4341 visibility is supported on Darwin targets.
4343 The visibility attribute should be applied only to declarations that
4344 would otherwise have external linkage. The attribute should be applied
4345 consistently, so that the same entity should not be declared with
4346 different settings of the attribute.
4348 In C++, the visibility attribute applies to types as well as functions
4349 and objects, because in C++ types have linkage. A class must not have
4350 greater visibility than its non-static data member types and bases,
4351 and class members default to the visibility of their class. Also, a
4352 declaration without explicit visibility is limited to the visibility
4355 In C++, you can mark member functions and static member variables of a
4356 class with the visibility attribute. This is useful if you know a
4357 particular method or static member variable should only be used from
4358 one shared object; then you can mark it hidden while the rest of the
4359 class has default visibility. Care must be taken to avoid breaking
4360 the One Definition Rule; for example, it is usually not useful to mark
4361 an inline method as hidden without marking the whole class as hidden.
4363 A C++ namespace declaration can also have the visibility attribute.
4366 namespace nspace1 __attribute__ ((visibility ("protected")))
4367 @{ /* @r{Do something.} */; @}
4370 This attribute applies only to the particular namespace body, not to
4371 other definitions of the same namespace; it is equivalent to using
4372 @samp{#pragma GCC visibility} before and after the namespace
4373 definition (@pxref{Visibility Pragmas}).
4375 In C++, if a template argument has limited visibility, this
4376 restriction is implicitly propagated to the template instantiation.
4377 Otherwise, template instantiations and specializations default to the
4378 visibility of their template.
4380 If both the template and enclosing class have explicit visibility, the
4381 visibility from the template is used.
4383 @cindex @code{warn_unused_result} function attribute
4384 @item warn_unused_result
4385 The @code{warn_unused_result} attribute causes a warning to be emitted
4386 if a caller of the function with this attribute does not use its
4387 return value. This is useful for functions where not checking
4388 the result is either a security problem or always a bug, such as
4392 int fn () __attribute__ ((warn_unused_result));
4395 if (fn () < 0) return -1;
4402 results in warning on line 5.
4404 @cindex @code{weak} function attribute
4406 The @code{weak} attribute causes a declaration of an external symbol
4407 to be emitted as a weak symbol rather than a global. This is primarily
4408 useful in defining library functions that can be overridden in user code,
4409 though it can also be used with non-function declarations. The overriding
4410 symbol must have the same type as the weak symbol. In addition, if it
4411 designates a variable it must also have the same size and alignment as
4412 the weak symbol. Weak symbols are supported for ELF targets, and also
4413 for a.out targets when using the GNU assembler and linker.
4415 @cindex @code{weakref} function attribute
4417 @itemx weakref ("@var{target}")
4418 The @code{weakref} attribute marks a declaration as a weak reference.
4419 Without arguments, it should be accompanied by an @code{alias} attribute
4420 naming the target symbol. Alternatively, @var{target} may be given as
4421 an argument to @code{weakref} itself, naming the target definition of
4422 the alias. The @var{target} must have the same type as the declaration.
4423 In addition, if it designates a variable it must also have the same size
4424 and alignment as the declaration. In either form of the declaration
4425 @code{weakref} implicitly marks the declared symbol as @code{weak}. Without
4426 a @var{target} given as an argument to @code{weakref} or to @code{alias},
4427 @code{weakref} is equivalent to @code{weak} (in that case the declaration
4428 may be @code{extern}).
4431 /* Given the declaration: */
4432 extern int y (void);
4434 /* the following... */
4435 static int x (void) __attribute__ ((weakref ("y")));
4437 /* is equivalent to... */
4438 static int x (void) __attribute__ ((weakref, alias ("y")));
4440 /* or, alternatively, to... */
4441 static int x (void) __attribute__ ((weakref));
4442 static int x (void) __attribute__ ((alias ("y")));
4445 A weak reference is an alias that does not by itself require a
4446 definition to be given for the target symbol. If the target symbol is
4447 only referenced through weak references, then it becomes a @code{weak}
4448 undefined symbol. If it is directly referenced, however, then such
4449 strong references prevail, and a definition is required for the
4450 symbol, not necessarily in the same translation unit.
4452 The effect is equivalent to moving all references to the alias to a
4453 separate translation unit, renaming the alias to the aliased symbol,
4454 declaring it as weak, compiling the two separate translation units and
4455 performing a link with relocatable output (i.e.@: @code{ld -r}) on them.
4457 A declaration to which @code{weakref} is attached and that is associated
4458 with a named @code{target} must be @code{static}.
4460 @cindex @code{zero_call_used_regs} function attribute
4461 @item zero_call_used_regs ("@var{choice}")
4463 The @code{zero_call_used_regs} attribute causes the compiler to zero
4464 a subset of all call-used registers@footnote{A ``call-used'' register
4465 is a register whose contents can be changed by a function call;
4466 therefore, a caller cannot assume that the register has the same contents
4467 on return from the function as it had before calling the function. Such
4468 registers are also called ``call-clobbered'', ``caller-saved'', or
4469 ``volatile''.} at function return.
4470 This is used to increase program security by either mitigating
4471 Return-Oriented Programming (ROP) attacks or preventing information leakage
4474 In order to satisfy users with different security needs and control the
4475 run-time overhead at the same time, the @var{choice} parameter provides a
4476 flexible way to choose the subset of the call-used registers to be zeroed.
4477 The four basic values of @var{choice} are:
4481 @samp{skip} doesn't zero any call-used registers.
4484 @samp{used} only zeros call-used registers that are used in the function.
4485 A ``used'' register is one whose content has been set or referenced in
4489 @samp{all} zeros all call-used registers.
4492 @samp{leafy} behaves like @samp{used} in a leaf function, and like
4493 @samp{all} in a nonleaf function. This makes for leaner zeroing in leaf
4494 functions, where the set of used registers is known, and that may be
4495 enough for some purposes of register zeroing.
4498 In addition to these three basic choices, it is possible to modify
4499 @samp{used}, @samp{all}, and @samp{leafy} as follows:
4503 Adding @samp{-gpr} restricts the zeroing to general-purpose registers.
4506 Adding @samp{-arg} restricts the zeroing to registers that can sometimes
4507 be used to pass function arguments. This includes all argument registers
4508 defined by the platform's calling conversion, regardless of whether the
4509 function uses those registers for function arguments or not.
4512 The modifiers can be used individually or together. If they are used
4513 together, they must appear in the order above.
4515 The full list of @var{choice}s is therefore:
4519 doesn't zero any call-used register.
4522 only zeros call-used registers that are used in the function.
4525 only zeros call-used general purpose registers that are used in the function.
4528 only zeros call-used registers that are used in the function and pass arguments.
4531 only zeros call-used general purpose registers that are used in the function
4535 zeros all call-used registers.
4538 zeros all call-used general purpose registers.
4541 zeros all call-used registers that pass arguments.
4544 zeros all call-used general purpose registers that pass
4548 Same as @samp{used} in a leaf function, and same as @samp{all} in a
4552 Same as @samp{used-gpr} in a leaf function, and same as @samp{all-gpr}
4553 in a nonleaf function.
4556 Same as @samp{used-arg} in a leaf function, and same as @samp{all-arg}
4557 in a nonleaf function.
4560 Same as @samp{used-gpr-arg} in a leaf function, and same as
4561 @samp{all-gpr-arg} in a nonleaf function.
4565 Of this list, @samp{used-arg}, @samp{used-gpr-arg}, @samp{all-arg},
4566 @samp{all-gpr-arg}, @samp{leafy-arg}, and @samp{leafy-gpr-arg} are
4567 mainly used for ROP mitigation.
4569 The default for the attribute is controlled by @option{-fzero-call-used-regs}.
4572 @c This is the end of the target-independent attribute table
4574 @node AArch64 Function Attributes
4575 @subsection AArch64 Function Attributes
4577 The following target-specific function attributes are available for the
4578 AArch64 target. For the most part, these options mirror the behavior of
4579 similar command-line options (@pxref{AArch64 Options}), but on a
4583 @cindex @code{general-regs-only} function attribute, AArch64
4584 @item general-regs-only
4585 Indicates that no floating-point or Advanced SIMD registers should be
4586 used when generating code for this function. If the function explicitly
4587 uses floating-point code, then the compiler gives an error. This is
4588 the same behavior as that of the command-line option
4589 @option{-mgeneral-regs-only}.
4591 @cindex @code{fix-cortex-a53-835769} function attribute, AArch64
4592 @item fix-cortex-a53-835769
4593 Indicates that the workaround for the Cortex-A53 erratum 835769 should be
4594 applied to this function. To explicitly disable the workaround for this
4595 function specify the negated form: @code{no-fix-cortex-a53-835769}.
4596 This corresponds to the behavior of the command line options
4597 @option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
4599 @cindex @code{cmodel=} function attribute, AArch64
4601 Indicates that code should be generated for a particular code model for
4602 this function. The behavior and permissible arguments are the same as
4603 for the command line option @option{-mcmodel=}.
4605 @cindex @code{strict-align} function attribute, AArch64
4607 @itemx no-strict-align
4608 @code{strict-align} indicates that the compiler should not assume that unaligned
4609 memory references are handled by the system. To allow the compiler to assume
4610 that aligned memory references are handled by the system, the inverse attribute
4611 @code{no-strict-align} can be specified. The behavior is same as for the
4612 command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
4614 @cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
4615 @item omit-leaf-frame-pointer
4616 Indicates that the frame pointer should be omitted for a leaf function call.
4617 To keep the frame pointer, the inverse attribute
4618 @code{no-omit-leaf-frame-pointer} can be specified. These attributes have
4619 the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
4620 and @option{-mno-omit-leaf-frame-pointer}.
4622 @cindex @code{tls-dialect=} function attribute, AArch64
4624 Specifies the TLS dialect to use for this function. The behavior and
4625 permissible arguments are the same as for the command-line option
4626 @option{-mtls-dialect=}.
4628 @cindex @code{arch=} function attribute, AArch64
4630 Specifies the architecture version and architectural extensions to use
4631 for this function. The behavior and permissible arguments are the same as
4632 for the @option{-march=} command-line option.
4634 @cindex @code{tune=} function attribute, AArch64
4636 Specifies the core for which to tune the performance of this function.
4637 The behavior and permissible arguments are the same as for the @option{-mtune=}
4638 command-line option.
4640 @cindex @code{cpu=} function attribute, AArch64
4642 Specifies the core for which to tune the performance of this function and also
4643 whose architectural features to use. The behavior and valid arguments are the
4644 same as for the @option{-mcpu=} command-line option.
4646 @cindex @code{sign-return-address} function attribute, AArch64
4647 @item sign-return-address
4648 Select the function scope on which return address signing will be applied. The
4649 behavior and permissible arguments are the same as for the command-line option
4650 @option{-msign-return-address=}. The default value is @code{none}. This
4651 attribute is deprecated. The @code{branch-protection} attribute should
4654 @cindex @code{branch-protection} function attribute, AArch64
4655 @item branch-protection
4656 Select the function scope on which branch protection will be applied. The
4657 behavior and permissible arguments are the same as for the command-line option
4658 @option{-mbranch-protection=}. The default value is @code{none}.
4660 @cindex @code{outline-atomics} function attribute, AArch64
4661 @item outline-atomics
4662 Enable or disable calls to out-of-line helpers to implement atomic operations.
4663 This corresponds to the behavior of the command line options
4664 @option{-moutline-atomics} and @option{-mno-outline-atomics}.
4668 The above target attributes can be specified as follows:
4671 __attribute__((target("@var{attr-string}")))
4679 where @code{@var{attr-string}} is one of the attribute strings specified above.
4681 Additionally, the architectural extension string may be specified on its
4682 own. This can be used to turn on and off particular architectural extensions
4683 without having to specify a particular architecture version or core. Example:
4686 __attribute__((target("+crc+nocrypto")))
4694 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
4695 extension and disables the @code{crypto} extension for the function @code{foo}
4696 without modifying an existing @option{-march=} or @option{-mcpu} option.
4698 Multiple target function attributes can be specified by separating them with
4699 a comma. For example:
4701 __attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
4709 is valid and compiles function @code{foo} for ARMv8-A with @code{crc}
4710 and @code{crypto} extensions and tunes it for @code{cortex-a53}.
4712 @subsubsection Inlining rules
4713 Specifying target attributes on individual functions or performing link-time
4714 optimization across translation units compiled with different target options
4715 can affect function inlining rules:
4717 In particular, a caller function can inline a callee function only if the
4718 architectural features available to the callee are a subset of the features
4719 available to the caller.
4720 For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
4721 or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
4722 can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
4723 because the all the architectural features that function @code{bar} requires
4724 are available to function @code{foo}. Conversely, function @code{bar} cannot
4725 inline function @code{foo}.
4727 Additionally inlining a function compiled with @option{-mstrict-align} into a
4728 function compiled without @code{-mstrict-align} is not allowed.
4729 However, inlining a function compiled without @option{-mstrict-align} into a
4730 function compiled with @option{-mstrict-align} is allowed.
4732 Note that CPU tuning options and attributes such as the @option{-mcpu=},
4733 @option{-mtune=} do not inhibit inlining unless the CPU specified by the
4734 @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
4735 architectural feature rules specified above.
4737 @node AMD GCN Function Attributes
4738 @subsection AMD GCN Function Attributes
4740 These function attributes are supported by the AMD GCN back end:
4743 @cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN
4744 @item amdgpu_hsa_kernel
4745 This attribute indicates that the corresponding function should be compiled as
4746 a kernel function, that is an entry point that can be invoked from the host
4747 via the HSA runtime library. By default functions are only callable only from
4748 other GCN functions.
4750 This attribute is implicitly applied to any function named @code{main}, using
4753 Kernel functions may return an integer value, which will be written to a
4754 conventional place within the HSA "kernargs" region.
4756 The attribute parameters configure what values are passed into the kernel
4757 function by the GPU drivers, via the initial register state. Some values are
4758 used by the compiler, and therefore forced on. Enabling other options may
4759 break assumptions in the compiler and/or run-time libraries.
4762 @item private_segment_buffer
4763 Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to
4767 Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the
4771 Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address
4774 @item kernarg_segment_ptr
4775 Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to
4776 locate the kernel arguments, "kernargs").
4779 Set @code{enable_sgpr_dispatch_id} flag.
4781 @item flat_scratch_init
4782 Set @code{enable_sgpr_flat_scratch_init} flag.
4784 @item private_segment_size
4785 Set @code{enable_sgpr_private_segment_size} flag.
4787 @item grid_workgroup_count_X
4788 Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to
4789 use OpenACC/OpenMP).
4791 @item grid_workgroup_count_Y
4792 Set @code{enable_sgpr_grid_workgroup_count_y} flag.
4794 @item grid_workgroup_count_Z
4795 Set @code{enable_sgpr_grid_workgroup_count_z} flag.
4797 @item workgroup_id_X
4798 Set @code{enable_sgpr_workgroup_id_x} flag.
4800 @item workgroup_id_Y
4801 Set @code{enable_sgpr_workgroup_id_y} flag.
4803 @item workgroup_id_Z
4804 Set @code{enable_sgpr_workgroup_id_z} flag.
4806 @item workgroup_info
4807 Set @code{enable_sgpr_workgroup_info} flag.
4809 @item private_segment_wave_offset
4810 Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on
4811 (required to locate the stack).
4813 @item work_item_id_X
4814 Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled).
4816 @item work_item_id_Y
4817 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable
4820 @item work_item_id_Z
4821 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use
4827 @node ARC Function Attributes
4828 @subsection ARC Function Attributes
4830 These function attributes are supported by the ARC back end:
4833 @cindex @code{interrupt} function attribute, ARC
4835 Use this attribute to indicate
4836 that the specified function is an interrupt handler. The compiler generates
4837 function entry and exit sequences suitable for use in an interrupt handler
4838 when this attribute is present.
4840 On the ARC, you must specify the kind of interrupt to be handled
4841 in a parameter to the interrupt attribute like this:
4844 void f () __attribute__ ((interrupt ("ilink1")));
4847 Permissible values for this parameter are: @w{@code{ilink1}} and
4848 @w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and
4849 @w{@code{firq}} for ARCv2 architecture.
4851 @cindex @code{long_call} function attribute, ARC
4852 @cindex @code{medium_call} function attribute, ARC
4853 @cindex @code{short_call} function attribute, ARC
4854 @cindex indirect calls, ARC
4858 These attributes specify how a particular function is called.
4859 These attributes override the
4860 @option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
4861 command-line switches and @code{#pragma long_calls} settings.
4863 For ARC, a function marked with the @code{long_call} attribute is
4864 always called using register-indirect jump-and-link instructions,
4865 thereby enabling the called function to be placed anywhere within the
4866 32-bit address space. A function marked with the @code{medium_call}
4867 attribute will always be close enough to be called with an unconditional
4868 branch-and-link instruction, which has a 25-bit offset from
4869 the call site. A function marked with the @code{short_call}
4870 attribute will always be close enough to be called with a conditional
4871 branch-and-link instruction, which has a 21-bit offset from
4874 @cindex @code{jli_always} function attribute, ARC
4876 Forces a particular function to be called using @code{jli}
4877 instruction. The @code{jli} instruction makes use of a table stored
4878 into @code{.jlitab} section, which holds the location of the functions
4879 which are addressed using this instruction.
4881 @cindex @code{jli_fixed} function attribute, ARC
4883 Identical like the above one, but the location of the function in the
4884 @code{jli} table is known and given as an attribute parameter.
4886 @cindex @code{secure_call} function attribute, ARC
4888 This attribute allows one to mark secure-code functions that are
4889 callable from normal mode. The location of the secure call function
4890 into the @code{sjli} table needs to be passed as argument.
4892 @cindex @code{naked} function attribute, ARC
4894 This attribute allows the compiler to construct the requisite function
4895 declaration, while allowing the body of the function to be assembly
4896 code. The specified function will not have prologue/epilogue
4897 sequences generated by the compiler. Only basic @code{asm} statements
4898 can safely be included in naked functions (@pxref{Basic Asm}). While
4899 using extended @code{asm} or a mixture of basic @code{asm} and C code
4900 may appear to work, they cannot be depended upon to work reliably and
4905 @node ARM Function Attributes
4906 @subsection ARM Function Attributes
4908 These function attributes are supported for ARM targets:
4912 @cindex @code{general-regs-only} function attribute, ARM
4913 @item general-regs-only
4914 Indicates that no floating-point or Advanced SIMD registers should be
4915 used when generating code for this function. If the function explicitly
4916 uses floating-point code, then the compiler gives an error. This is
4917 the same behavior as that of the command-line option
4918 @option{-mgeneral-regs-only}.
4920 @cindex @code{interrupt} function attribute, ARM
4922 Use this attribute to indicate
4923 that the specified function is an interrupt handler. The compiler generates
4924 function entry and exit sequences suitable for use in an interrupt handler
4925 when this attribute is present.
4927 You can specify the kind of interrupt to be handled by
4928 adding an optional parameter to the interrupt attribute like this:
4931 void f () __attribute__ ((interrupt ("IRQ")));
4935 Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
4936 @code{SWI}, @code{ABORT} and @code{UNDEF}.
4938 On ARMv7-M the interrupt type is ignored, and the attribute means the function
4939 may be called with a word-aligned stack pointer.
4941 @cindex @code{isr} function attribute, ARM
4943 Use this attribute on ARM to write Interrupt Service Routines. This is an
4944 alias to the @code{interrupt} attribute above.
4946 @cindex @code{long_call} function attribute, ARM
4947 @cindex @code{short_call} function attribute, ARM
4948 @cindex indirect calls, ARM
4951 These attributes specify how a particular function is called.
4952 These attributes override the
4953 @option{-mlong-calls} (@pxref{ARM Options})
4954 command-line switch and @code{#pragma long_calls} settings. For ARM, the
4955 @code{long_call} attribute indicates that the function might be far
4956 away from the call site and require a different (more expensive)
4957 calling sequence. The @code{short_call} attribute always places
4958 the offset to the function from the call site into the @samp{BL}
4959 instruction directly.
4961 @cindex @code{naked} function attribute, ARM
4963 This attribute allows the compiler to construct the
4964 requisite function declaration, while allowing the body of the
4965 function to be assembly code. The specified function will not have
4966 prologue/epilogue sequences generated by the compiler. Only basic
4967 @code{asm} statements can safely be included in naked functions
4968 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4969 basic @code{asm} and C code may appear to work, they cannot be
4970 depended upon to work reliably and are not supported.
4972 @cindex @code{pcs} function attribute, ARM
4975 The @code{pcs} attribute can be used to control the calling convention
4976 used for a function on ARM. The attribute takes an argument that specifies
4977 the calling convention to use.
4979 When compiling using the AAPCS ABI (or a variant of it) then valid
4980 values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
4981 order to use a variant other than @code{"aapcs"} then the compiler must
4982 be permitted to use the appropriate co-processor registers (i.e., the
4983 VFP registers must be available in order to use @code{"aapcs-vfp"}).
4987 /* Argument passed in r0, and result returned in r0+r1. */
4988 double f2d (float) __attribute__((pcs("aapcs")));
4991 Variadic functions always use the @code{"aapcs"} calling convention and
4992 the compiler rejects attempts to specify an alternative.
4994 @cindex @code{target} function attribute
4995 @item target (@var{options})
4996 As discussed in @ref{Common Function Attributes}, this attribute
4997 allows specification of target-specific compilation options.
4999 On ARM, the following options are allowed:
5002 @cindex @code{target("thumb")} function attribute, ARM
5004 Force code generation in the Thumb (T16/T32) ISA, depending on the
5007 @cindex @code{target("arm")} function attribute, ARM
5009 Force code generation in the ARM (A32) ISA.
5011 Functions from different modes can be inlined in the caller's mode.
5013 @cindex @code{target("fpu=")} function attribute, ARM
5015 Specifies the fpu for which to tune the performance of this function.
5016 The behavior and permissible arguments are the same as for the @option{-mfpu=}
5017 command-line option.
5019 @cindex @code{arch=} function attribute, ARM
5021 Specifies the architecture version and architectural extensions to use
5022 for this function. The behavior and permissible arguments are the same as
5023 for the @option{-march=} command-line option.
5025 The above target attributes can be specified as follows:
5028 __attribute__((target("arch=armv8-a+crc")))
5036 Additionally, the architectural extension string may be specified on its
5037 own. This can be used to turn on and off particular architectural extensions
5038 without having to specify a particular architecture version or core. Example:
5041 __attribute__((target("+crc+nocrypto")))
5049 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
5050 extension and disables the @code{crypto} extension for the function @code{foo}
5051 without modifying an existing @option{-march=} or @option{-mcpu} option.
5057 @node AVR Function Attributes
5058 @subsection AVR Function Attributes
5060 These function attributes are supported by the AVR back end:
5063 @cindex @code{signal} function attribute, AVR
5064 @cindex @code{interrupt} function attribute, AVR
5067 The function is an interrupt service routine (ISR). The compiler generates
5068 function entry and exit sequences suitable for use in an interrupt handler
5069 when one of the attributes is present.
5071 The AVR hardware globally disables interrupts when an interrupt is executed.
5074 @item ISRs with the @code{signal} attribute do not re-enable interrupts.
5075 It is save to enable interrupts in a @code{signal} handler.
5076 This ``save'' only applies to the code
5077 generated by the compiler and not to the IRQ layout of the
5078 application which is responsibility of the application.
5080 @item ISRs with the @code{interrupt} attribute re-enable interrupts.
5081 The first instruction of the routine is a @code{SEI} instruction to
5082 globally enable interrupts.
5085 The recommended way to use these attributes is by means of the
5086 @code{ISR} macro provided by @code{avr/interrupt.h} from
5087 @w{@uref{https://www.nongnu.org/avr-libc/user-manual/group__avr__interrupts.html,,AVR-LibC}}:
5089 #include <avr/interrupt.h>
5091 ISR (INT0_vect) // Uses the "signal" attribute.
5096 ISR (ADC_vect, ISR_NOBLOCK) // Uses the "interrupt" attribute.
5102 When both @code{signal} and @code{interrupt} are specified for the same
5103 function, then @code{signal} is silently ignored.
5105 @cindex @code{naked} function attribute, AVR
5107 This attribute allows the compiler to construct the
5108 requisite function declaration, while allowing the body of the
5109 function to be assembly code. The specified function will not have
5110 prologue/epilogue sequences generated by the compiler. Only basic
5111 @code{asm} statements can safely be included in naked functions
5112 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5113 basic @code{asm} and C code may appear to work, they cannot be
5114 depended upon to work reliably and are not supported.
5116 @cindex @code{no_gccisr} function attribute, AVR
5118 Do not use the @code{__gcc_isr}
5119 @uref{https://sourceware.org/binutils/docs/as/AVR-Pseudo-Instructions.html,pseudo instruction}
5121 the @code{interrupt} or @code{signal} attribute aka. interrupt
5122 service routine (ISR).
5123 Use this attribute if the preamble of the ISR prologue should always read
5127 in __tmp_reg__, __SREG__
5131 and accordingly for the postamble of the epilogue --- no matter whether
5132 the mentioned registers are actually used in the ISR or not.
5133 Situations where you might want to use this attribute include:
5136 Code that (effectively) clobbers bits of @code{SREG} other than the
5137 @code{I}-flag by writing to the memory location of @code{SREG}.
5139 Code that uses inline assembler to jump to a different function which
5140 expects (parts of) the prologue code as outlined above to be present.
5142 To disable @code{__gcc_isr} generation for the whole compilation unit,
5143 there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}.
5145 @cindex @code{OS_main} function attribute, AVR
5146 @cindex @code{OS_task} function attribute, AVR
5149 On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
5150 do not save/restore any call-saved register in their prologue/epilogue.
5152 The @code{OS_main} attribute can be used when there @emph{is
5153 guarantee} that interrupts are disabled at the time when the function
5154 is entered. This saves resources when the stack pointer has to be
5155 changed to set up a frame for local variables.
5157 The @code{OS_task} attribute can be used when there is @emph{no
5158 guarantee} that interrupts are disabled at that time when the function
5159 is entered like for, e@.g@. task functions in a multi-threading operating
5160 system. In that case, changing the stack pointer register is
5161 guarded by save/clear/restore of the global interrupt enable flag.
5163 The differences to the @code{naked} function attribute are:
5165 @item @code{naked} functions do not have a return instruction whereas
5166 @code{OS_main} and @code{OS_task} functions have a @code{RET} or
5167 @code{RETI} return instruction.
5168 @item @code{naked} functions do not set up a frame for local variables
5169 or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
5175 @node Blackfin Function Attributes
5176 @subsection Blackfin Function Attributes
5178 These function attributes are supported by the Blackfin back end:
5182 @cindex @code{exception_handler} function attribute
5183 @cindex exception handler functions, Blackfin
5184 @item exception_handler
5185 Use this attribute on the Blackfin to indicate that the specified function
5186 is an exception handler. The compiler generates function entry and
5187 exit sequences suitable for use in an exception handler when this
5188 attribute is present.
5190 @cindex @code{interrupt_handler} function attribute, Blackfin
5191 @item interrupt_handler
5192 Use this attribute to
5193 indicate that the specified function is an interrupt handler. The compiler
5194 generates function entry and exit sequences suitable for use in an
5195 interrupt handler when this attribute is present.
5197 @cindex @code{kspisusp} function attribute, Blackfin
5198 @cindex User stack pointer in interrupts on the Blackfin
5200 When used together with @code{interrupt_handler}, @code{exception_handler}
5201 or @code{nmi_handler}, code is generated to load the stack pointer
5202 from the USP register in the function prologue.
5204 @cindex @code{l1_text} function attribute, Blackfin
5206 This attribute specifies a function to be placed into L1 Instruction
5207 SRAM@. The function is put into a specific section named @code{.l1.text}.
5208 With @option{-mfdpic}, function calls with a such function as the callee
5209 or caller uses inlined PLT.
5211 @cindex @code{l2} function attribute, Blackfin
5213 This attribute specifies a function to be placed into L2
5214 SRAM. The function is put into a specific section named
5215 @code{.l2.text}. With @option{-mfdpic}, callers of such functions use
5218 @cindex indirect calls, Blackfin
5219 @cindex @code{longcall} function attribute, Blackfin
5220 @cindex @code{shortcall} function attribute, Blackfin
5223 The @code{longcall} attribute
5224 indicates that the function might be far away from the call site and
5225 require a different (more expensive) calling sequence. The
5226 @code{shortcall} attribute indicates that the function is always close
5227 enough for the shorter calling sequence to be used. These attributes
5228 override the @option{-mlongcall} switch.
5230 @cindex @code{nesting} function attribute, Blackfin
5231 @cindex Allow nesting in an interrupt handler on the Blackfin processor
5233 Use this attribute together with @code{interrupt_handler},
5234 @code{exception_handler} or @code{nmi_handler} to indicate that the function
5235 entry code should enable nested interrupts or exceptions.
5237 @cindex @code{nmi_handler} function attribute, Blackfin
5238 @cindex NMI handler functions on the Blackfin processor
5240 Use this attribute on the Blackfin to indicate that the specified function
5241 is an NMI handler. The compiler generates function entry and
5242 exit sequences suitable for use in an NMI handler when this
5243 attribute is present.
5245 @cindex @code{saveall} function attribute, Blackfin
5246 @cindex save all registers on the Blackfin
5248 Use this attribute to indicate that
5249 all registers except the stack pointer should be saved in the prologue
5250 regardless of whether they are used or not.
5253 @node BPF Function Attributes
5254 @subsection BPF Function Attributes
5256 These function attributes are supported by the BPF back end:
5259 @cindex @code{kernel helper}, function attribute, BPF
5261 use this attribute to indicate the specified function declaration is a
5262 kernel helper. The helper function is passed as an argument to the
5266 int bpf_probe_read (void *dst, int size, const void *unsafe_ptr)
5267 __attribute__ ((kernel_helper (4)));
5270 @cindex @code{naked} function attribute, BPF
5272 This attribute allows the compiler to construct the requisite function
5273 declaration, while allowing the body of the function to be assembly
5274 code. The specified function will not have prologue/epilogue
5275 sequences generated by the compiler. Only basic @code{asm} statements
5276 can safely be included in naked functions (@pxref{Basic Asm}). While
5277 using extended @code{asm} or a mixture of basic @code{asm} and C code
5278 may appear to work, they cannot be depended upon to work reliably and
5282 @node C-SKY Function Attributes
5283 @subsection C-SKY Function Attributes
5285 These function attributes are supported by the C-SKY back end:
5288 @cindex @code{interrupt} function attribute, C-SKY
5289 @cindex @code{isr} function attribute, C-SKY
5292 Use these attributes to indicate that the specified function
5293 is an interrupt handler.
5294 The compiler generates function entry and exit sequences suitable for
5295 use in an interrupt handler when either of these attributes are present.
5297 Use of these options requires the @option{-mistack} command-line option
5298 to enable support for the necessary interrupt stack instructions. They
5299 are ignored with a warning otherwise. @xref{C-SKY Options}.
5301 @cindex @code{naked} function attribute, C-SKY
5303 This attribute allows the compiler to construct the
5304 requisite function declaration, while allowing the body of the
5305 function to be assembly code. The specified function will not have
5306 prologue/epilogue sequences generated by the compiler. Only basic
5307 @code{asm} statements can safely be included in naked functions
5308 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5309 basic @code{asm} and C code may appear to work, they cannot be
5310 depended upon to work reliably and are not supported.
5314 @node Epiphany Function Attributes
5315 @subsection Epiphany Function Attributes
5317 These function attributes are supported by the Epiphany back end:
5320 @cindex @code{disinterrupt} function attribute, Epiphany
5322 This attribute causes the compiler to emit
5323 instructions to disable interrupts for the duration of the given
5326 @cindex @code{forwarder_section} function attribute, Epiphany
5327 @item forwarder_section
5328 This attribute modifies the behavior of an interrupt handler.
5329 The interrupt handler may be in external memory which cannot be
5330 reached by a branch instruction, so generate a local memory trampoline
5331 to transfer control. The single parameter identifies the section where
5332 the trampoline is placed.
5334 @cindex @code{interrupt} function attribute, Epiphany
5336 Use this attribute to indicate
5337 that the specified function is an interrupt handler. The compiler generates
5338 function entry and exit sequences suitable for use in an interrupt handler
5339 when this attribute is present. It may also generate
5340 a special section with code to initialize the interrupt vector table.
5342 On Epiphany targets one or more optional parameters can be added like this:
5345 void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
5348 Permissible values for these parameters are: @w{@code{reset}},
5349 @w{@code{software_exception}}, @w{@code{page_miss}},
5350 @w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
5351 @w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
5352 Multiple parameters indicate that multiple entries in the interrupt
5353 vector table should be initialized for this function, i.e.@: for each
5354 parameter @w{@var{name}}, a jump to the function is emitted in
5355 the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
5356 entirely, in which case no interrupt vector table entry is provided.
5358 Note that interrupts are enabled inside the function
5359 unless the @code{disinterrupt} attribute is also specified.
5361 The following examples are all valid uses of these attributes on
5364 void __attribute__ ((interrupt)) universal_handler ();
5365 void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
5366 void __attribute__ ((interrupt ("dma0, dma1")))
5367 universal_dma_handler ();
5368 void __attribute__ ((interrupt ("timer0"), disinterrupt))
5369 fast_timer_handler ();
5370 void __attribute__ ((interrupt ("dma0, dma1"),
5371 forwarder_section ("tramp")))
5372 external_dma_handler ();
5375 @cindex @code{long_call} function attribute, Epiphany
5376 @cindex @code{short_call} function attribute, Epiphany
5377 @cindex indirect calls, Epiphany
5380 These attributes specify how a particular function is called.
5381 These attributes override the
5382 @option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
5383 command-line switch and @code{#pragma long_calls} settings.
5387 @node H8/300 Function Attributes
5388 @subsection H8/300 Function Attributes
5390 These function attributes are available for H8/300 targets:
5393 @cindex @code{function_vector} function attribute, H8/300
5394 @item function_vector
5395 Use this attribute on the H8/300, H8/300H, and H8S to indicate
5396 that the specified function should be called through the function vector.
5397 Calling a function through the function vector reduces code size; however,
5398 the function vector has a limited size (maximum 128 entries on the H8/300
5399 and 64 entries on the H8/300H and H8S)
5400 and shares space with the interrupt vector.
5402 @cindex @code{interrupt_handler} function attribute, H8/300
5403 @item interrupt_handler
5404 Use this attribute on the H8/300, H8/300H, and H8S to
5405 indicate that the specified function is an interrupt handler. The compiler
5406 generates function entry and exit sequences suitable for use in an
5407 interrupt handler when this attribute is present.
5409 @cindex @code{saveall} function attribute, H8/300
5410 @cindex save all registers on the H8/300, H8/300H, and H8S
5412 Use this attribute on the H8/300, H8/300H, and H8S to indicate that
5413 all registers except the stack pointer should be saved in the prologue
5414 regardless of whether they are used or not.
5417 @node IA-64 Function Attributes
5418 @subsection IA-64 Function Attributes
5420 These function attributes are supported on IA-64 targets:
5423 @cindex @code{syscall_linkage} function attribute, IA-64
5424 @item syscall_linkage
5425 This attribute is used to modify the IA-64 calling convention by marking
5426 all input registers as live at all function exits. This makes it possible
5427 to restart a system call after an interrupt without having to save/restore
5428 the input registers. This also prevents kernel data from leaking into
5431 @cindex @code{version_id} function attribute, IA-64
5433 This IA-64 HP-UX attribute, attached to a global variable or function, renames a
5434 symbol to contain a version string, thus allowing for function level
5435 versioning. HP-UX system header files may use function level versioning
5436 for some system calls.
5439 extern int foo () __attribute__((version_id ("20040821")));
5443 Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
5446 @node M32C Function Attributes
5447 @subsection M32C Function Attributes
5449 These function attributes are supported by the M32C back end:
5452 @cindex @code{bank_switch} function attribute, M32C
5454 When added to an interrupt handler with the M32C port, causes the
5455 prologue and epilogue to use bank switching to preserve the registers
5456 rather than saving them on the stack.
5458 @cindex @code{fast_interrupt} function attribute, M32C
5459 @item fast_interrupt
5460 Use this attribute on the M32C port to indicate that the specified
5461 function is a fast interrupt handler. This is just like the
5462 @code{interrupt} attribute, except that @code{freit} is used to return
5463 instead of @code{reit}.
5465 @cindex @code{function_vector} function attribute, M16C/M32C
5466 @item function_vector
5467 On M16C/M32C targets, the @code{function_vector} attribute declares a
5468 special page subroutine call function. Use of this attribute reduces
5469 the code size by 2 bytes for each call generated to the
5470 subroutine. The argument to the attribute is the vector number entry
5471 from the special page vector table which contains the 16 low-order
5472 bits of the subroutine's entry address. Each vector table has special
5473 page number (18 to 255) that is used in @code{jsrs} instructions.
5474 Jump addresses of the routines are generated by adding 0x0F0000 (in
5475 case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
5476 2-byte addresses set in the vector table. Therefore you need to ensure
5477 that all the special page vector routines should get mapped within the
5478 address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
5481 In the following example 2 bytes are saved for each call to
5482 function @code{foo}.
5485 void foo (void) __attribute__((function_vector(0x18)));
5496 If functions are defined in one file and are called in another file,
5497 then be sure to write this declaration in both files.
5499 This attribute is ignored for R8C target.
5501 @cindex @code{interrupt} function attribute, M32C
5503 Use this attribute to indicate
5504 that the specified function is an interrupt handler. The compiler generates
5505 function entry and exit sequences suitable for use in an interrupt handler
5506 when this attribute is present.
5509 @node M32R/D Function Attributes
5510 @subsection M32R/D Function Attributes
5512 These function attributes are supported by the M32R/D back end:
5515 @cindex @code{interrupt} function attribute, M32R/D
5517 Use this attribute to indicate
5518 that the specified function is an interrupt handler. The compiler generates
5519 function entry and exit sequences suitable for use in an interrupt handler
5520 when this attribute is present.
5522 @cindex @code{model} function attribute, M32R/D
5523 @cindex function addressability on the M32R/D
5524 @item model (@var{model-name})
5526 On the M32R/D, use this attribute to set the addressability of an
5527 object, and of the code generated for a function. The identifier
5528 @var{model-name} is one of @code{small}, @code{medium}, or
5529 @code{large}, representing each of the code models.
5531 Small model objects live in the lower 16MB of memory (so that their
5532 addresses can be loaded with the @code{ld24} instruction), and are
5533 callable with the @code{bl} instruction.
5535 Medium model objects may live anywhere in the 32-bit address space (the
5536 compiler generates @code{seth/add3} instructions to load their addresses),
5537 and are callable with the @code{bl} instruction.
5539 Large model objects may live anywhere in the 32-bit address space (the
5540 compiler generates @code{seth/add3} instructions to load their addresses),
5541 and may not be reachable with the @code{bl} instruction (the compiler
5542 generates the much slower @code{seth/add3/jl} instruction sequence).
5545 @node m68k Function Attributes
5546 @subsection m68k Function Attributes
5548 These function attributes are supported by the m68k back end:
5551 @cindex @code{interrupt} function attribute, m68k
5552 @cindex @code{interrupt_handler} function attribute, m68k
5554 @itemx interrupt_handler
5555 Use this attribute to
5556 indicate that the specified function is an interrupt handler. The compiler
5557 generates function entry and exit sequences suitable for use in an
5558 interrupt handler when this attribute is present. Either name may be used.
5560 @cindex @code{interrupt_thread} function attribute, fido
5561 @item interrupt_thread
5562 Use this attribute on fido, a subarchitecture of the m68k, to indicate
5563 that the specified function is an interrupt handler that is designed
5564 to run as a thread. The compiler omits generate prologue/epilogue
5565 sequences and replaces the return instruction with a @code{sleep}
5566 instruction. This attribute is available only on fido.
5569 @node MCORE Function Attributes
5570 @subsection MCORE Function Attributes
5572 These function attributes are supported by the MCORE back end:
5575 @cindex @code{naked} function attribute, MCORE
5577 This attribute allows the compiler to construct the
5578 requisite function declaration, while allowing the body of the
5579 function to be assembly code. The specified function will not have
5580 prologue/epilogue sequences generated by the compiler. Only basic
5581 @code{asm} statements can safely be included in naked functions
5582 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5583 basic @code{asm} and C code may appear to work, they cannot be
5584 depended upon to work reliably and are not supported.
5587 @node MicroBlaze Function Attributes
5588 @subsection MicroBlaze Function Attributes
5590 These function attributes are supported on MicroBlaze targets:
5593 @cindex @code{save_volatiles} function attribute, MicroBlaze
5594 @item save_volatiles
5595 Use this attribute to indicate that the function is
5596 an interrupt handler. All volatile registers (in addition to non-volatile
5597 registers) are saved in the function prologue. If the function is a leaf
5598 function, only volatiles used by the function are saved. A normal function
5599 return is generated instead of a return from interrupt.
5601 @cindex @code{break_handler} function attribute, MicroBlaze
5602 @cindex break handler functions
5604 Use this attribute to indicate that
5605 the specified function is a break handler. The compiler generates function
5606 entry and exit sequences suitable for use in an break handler when this
5607 attribute is present. The return from @code{break_handler} is done through
5608 the @code{rtbd} instead of @code{rtsd}.
5611 void f () __attribute__ ((break_handler));
5614 @cindex @code{interrupt_handler} function attribute, MicroBlaze
5615 @cindex @code{fast_interrupt} function attribute, MicroBlaze
5616 @item interrupt_handler
5617 @itemx fast_interrupt
5618 These attributes indicate that the specified function is an interrupt
5619 handler. Use the @code{fast_interrupt} attribute to indicate handlers
5620 used in low-latency interrupt mode, and @code{interrupt_handler} for
5621 interrupts that do not use low-latency handlers. In both cases, GCC
5622 emits appropriate prologue code and generates a return from the handler
5623 using @code{rtid} instead of @code{rtsd}.
5626 @node Microsoft Windows Function Attributes
5627 @subsection Microsoft Windows Function Attributes
5629 The following attributes are available on Microsoft Windows and Symbian OS
5633 @cindex @code{dllexport} function attribute
5634 @cindex @code{__declspec(dllexport)}
5636 On Microsoft Windows targets and Symbian OS targets the
5637 @code{dllexport} attribute causes the compiler to provide a global
5638 pointer to a pointer in a DLL, so that it can be referenced with the
5639 @code{dllimport} attribute. On Microsoft Windows targets, the pointer
5640 name is formed by combining @code{_imp__} and the function or variable
5643 You can use @code{__declspec(dllexport)} as a synonym for
5644 @code{__attribute__ ((dllexport))} for compatibility with other
5647 On systems that support the @code{visibility} attribute, this
5648 attribute also implies ``default'' visibility. It is an error to
5649 explicitly specify any other visibility.
5651 GCC's default behavior is to emit all inline functions with the
5652 @code{dllexport} attribute. Since this can cause object file-size bloat,
5653 you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
5654 ignore the attribute for inlined functions unless the
5655 @option{-fkeep-inline-functions} flag is used instead.
5657 The attribute is ignored for undefined symbols.
5659 When applied to C++ classes, the attribute marks defined non-inlined
5660 member functions and static data members as exports. Static consts
5661 initialized in-class are not marked unless they are also defined
5664 For Microsoft Windows targets there are alternative methods for
5665 including the symbol in the DLL's export table such as using a
5666 @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
5667 the @option{--export-all} linker flag.
5669 @cindex @code{dllimport} function attribute
5670 @cindex @code{__declspec(dllimport)}
5672 On Microsoft Windows and Symbian OS targets, the @code{dllimport}
5673 attribute causes the compiler to reference a function or variable via
5674 a global pointer to a pointer that is set up by the DLL exporting the
5675 symbol. The attribute implies @code{extern}. On Microsoft Windows
5676 targets, the pointer name is formed by combining @code{_imp__} and the
5677 function or variable name.
5679 You can use @code{__declspec(dllimport)} as a synonym for
5680 @code{__attribute__ ((dllimport))} for compatibility with other
5683 On systems that support the @code{visibility} attribute, this
5684 attribute also implies ``default'' visibility. It is an error to
5685 explicitly specify any other visibility.
5687 Currently, the attribute is ignored for inlined functions. If the
5688 attribute is applied to a symbol @emph{definition}, an error is reported.
5689 If a symbol previously declared @code{dllimport} is later defined, the
5690 attribute is ignored in subsequent references, and a warning is emitted.
5691 The attribute is also overridden by a subsequent declaration as
5694 When applied to C++ classes, the attribute marks non-inlined
5695 member functions and static data members as imports. However, the
5696 attribute is ignored for virtual methods to allow creation of vtables
5699 On the SH Symbian OS target the @code{dllimport} attribute also has
5700 another affect---it can cause the vtable and run-time type information
5701 for a class to be exported. This happens when the class has a
5702 dllimported constructor or a non-inline, non-pure virtual function
5703 and, for either of those two conditions, the class also has an inline
5704 constructor or destructor and has a key function that is defined in
5705 the current translation unit.
5707 For Microsoft Windows targets the use of the @code{dllimport}
5708 attribute on functions is not necessary, but provides a small
5709 performance benefit by eliminating a thunk in the DLL@. The use of the
5710 @code{dllimport} attribute on imported variables can be avoided by passing the
5711 @option{--enable-auto-import} switch to the GNU linker. As with
5712 functions, using the attribute for a variable eliminates a thunk in
5715 One drawback to using this attribute is that a pointer to a
5716 @emph{variable} marked as @code{dllimport} cannot be used as a constant
5717 address. However, a pointer to a @emph{function} with the
5718 @code{dllimport} attribute can be used as a constant initializer; in
5719 this case, the address of a stub function in the import lib is
5720 referenced. On Microsoft Windows targets, the attribute can be disabled
5721 for functions by setting the @option{-mnop-fun-dllimport} flag.
5724 @node MIPS Function Attributes
5725 @subsection MIPS Function Attributes
5727 These function attributes are supported by the MIPS back end:
5730 @cindex @code{interrupt} function attribute, MIPS
5732 Use this attribute to indicate that the specified function is an interrupt
5733 handler. The compiler generates function entry and exit sequences suitable
5734 for use in an interrupt handler when this attribute is present.
5735 An optional argument is supported for the interrupt attribute which allows
5736 the interrupt mode to be described. By default GCC assumes the external
5737 interrupt controller (EIC) mode is in use, this can be explicitly set using
5738 @code{eic}. When interrupts are non-masked then the requested Interrupt
5739 Priority Level (IPL) is copied to the current IPL which has the effect of only
5740 enabling higher priority interrupts. To use vectored interrupt mode use
5741 the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
5742 the behavior of the non-masked interrupt support and GCC will arrange to mask
5743 all interrupts from sw0 up to and including the specified interrupt vector.
5745 You can use the following attributes to modify the behavior
5746 of an interrupt handler:
5748 @cindex @code{use_shadow_register_set} function attribute, MIPS
5749 @item use_shadow_register_set
5750 Assume that the handler uses a shadow register set, instead of
5751 the main general-purpose registers. An optional argument @code{intstack} is
5752 supported to indicate that the shadow register set contains a valid stack
5755 @cindex @code{keep_interrupts_masked} function attribute, MIPS
5756 @item keep_interrupts_masked
5757 Keep interrupts masked for the whole function. Without this attribute,
5758 GCC tries to reenable interrupts for as much of the function as it can.
5760 @cindex @code{use_debug_exception_return} function attribute, MIPS
5761 @item use_debug_exception_return
5762 Return using the @code{deret} instruction. Interrupt handlers that don't
5763 have this attribute return using @code{eret} instead.
5766 You can use any combination of these attributes, as shown below:
5768 void __attribute__ ((interrupt)) v0 ();
5769 void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
5770 void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
5771 void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
5772 void __attribute__ ((interrupt, use_shadow_register_set,
5773 keep_interrupts_masked)) v4 ();
5774 void __attribute__ ((interrupt, use_shadow_register_set,
5775 use_debug_exception_return)) v5 ();
5776 void __attribute__ ((interrupt, keep_interrupts_masked,
5777 use_debug_exception_return)) v6 ();
5778 void __attribute__ ((interrupt, use_shadow_register_set,
5779 keep_interrupts_masked,
5780 use_debug_exception_return)) v7 ();
5781 void __attribute__ ((interrupt("eic"))) v8 ();
5782 void __attribute__ ((interrupt("vector=hw3"))) v9 ();
5785 @cindex indirect calls, MIPS
5786 @cindex @code{long_call} function attribute, MIPS
5787 @cindex @code{short_call} function attribute, MIPS
5788 @cindex @code{near} function attribute, MIPS
5789 @cindex @code{far} function attribute, MIPS
5794 These attributes specify how a particular function is called on MIPS@.
5795 The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
5796 command-line switch. The @code{long_call} and @code{far} attributes are
5797 synonyms, and cause the compiler to always call
5798 the function by first loading its address into a register, and then using
5799 the contents of that register. The @code{short_call} and @code{near}
5800 attributes are synonyms, and have the opposite
5801 effect; they specify that non-PIC calls should be made using the more
5802 efficient @code{jal} instruction.
5804 @cindex @code{mips16} function attribute, MIPS
5805 @cindex @code{nomips16} function attribute, MIPS
5809 On MIPS targets, you can use the @code{mips16} and @code{nomips16}
5810 function attributes to locally select or turn off MIPS16 code generation.
5811 A function with the @code{mips16} attribute is emitted as MIPS16 code,
5812 while MIPS16 code generation is disabled for functions with the
5813 @code{nomips16} attribute. These attributes override the
5814 @option{-mips16} and @option{-mno-mips16} options on the command line
5815 (@pxref{MIPS Options}).
5817 When compiling files containing mixed MIPS16 and non-MIPS16 code, the
5818 preprocessor symbol @code{__mips16} reflects the setting on the command line,
5819 not that within individual functions. Mixed MIPS16 and non-MIPS16 code
5820 may interact badly with some GCC extensions such as @code{__builtin_apply}
5821 (@pxref{Constructing Calls}).
5823 @cindex @code{micromips} function attribute
5824 @cindex @code{nomicromips} function attribute
5825 @item micromips, MIPS
5826 @itemx nomicromips, MIPS
5828 On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
5829 function attributes to locally select or turn off microMIPS code generation.
5830 A function with the @code{micromips} attribute is emitted as microMIPS code,
5831 while microMIPS code generation is disabled for functions with the
5832 @code{nomicromips} attribute. These attributes override the
5833 @option{-mmicromips} and @option{-mno-micromips} options on the command line
5834 (@pxref{MIPS Options}).
5836 When compiling files containing mixed microMIPS and non-microMIPS code, the
5837 preprocessor symbol @code{__mips_micromips} reflects the setting on the
5839 not that within individual functions. Mixed microMIPS and non-microMIPS code
5840 may interact badly with some GCC extensions such as @code{__builtin_apply}
5841 (@pxref{Constructing Calls}).
5843 @cindex @code{nocompression} function attribute, MIPS
5845 On MIPS targets, you can use the @code{nocompression} function attribute
5846 to locally turn off MIPS16 and microMIPS code generation. This attribute
5847 overrides the @option{-mips16} and @option{-mmicromips} options on the
5848 command line (@pxref{MIPS Options}).
5850 @cindex @code{use_hazard_barrier_return} function attribute, MIPS
5851 @item use_hazard_barrier_return
5852 This function attribute instructs the compiler to generate a hazard barrier
5853 return that clears all execution and instruction hazards while returning,
5854 instead of generating a normal return instruction.
5857 @cindex @code{code_readable} function attribute, MIPS
5858 For MIPS targets that support PC-relative addressing modes, this attribute
5859 can be used to control how an object is addressed. The attribute takes
5860 a single optional argument:
5864 The function should not read the instruction stream as data.
5866 The function can read the instruction stream as data.
5868 The function can read the instruction stream in a pc-relative mode.
5871 If there is no argument supplied, the default of @code{"yes"} applies.
5874 @node MSP430 Function Attributes
5875 @subsection MSP430 Function Attributes
5877 These function attributes are supported by the MSP430 back end:
5880 @cindex @code{critical} function attribute, MSP430
5882 Critical functions disable interrupts upon entry and restore the
5883 previous interrupt state upon exit. Critical functions cannot also
5884 have the @code{naked}, @code{reentrant} or @code{interrupt} attributes.
5886 The MSP430 hardware ensures that interrupts are disabled on entry to
5887 @code{interrupt} functions, and restores the previous interrupt state
5888 on exit. The @code{critical} attribute is therefore redundant on
5889 @code{interrupt} functions.
5891 @cindex @code{interrupt} function attribute, MSP430
5893 Use this attribute to indicate
5894 that the specified function is an interrupt handler. The compiler generates
5895 function entry and exit sequences suitable for use in an interrupt handler
5896 when this attribute is present.
5898 You can provide an argument to the interrupt
5899 attribute which specifies a name or number. If the argument is a
5900 number it indicates the slot in the interrupt vector table (0 - 31) to
5901 which this handler should be assigned. If the argument is a name it
5902 is treated as a symbolic name for the vector slot. These names should
5903 match up with appropriate entries in the linker script. By default
5904 the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
5905 @code{reset} for vector 31 are recognized.
5907 @cindex @code{naked} function attribute, MSP430
5909 This attribute allows the compiler to construct the
5910 requisite function declaration, while allowing the body of the
5911 function to be assembly code. The specified function will not have
5912 prologue/epilogue sequences generated by the compiler. Only basic
5913 @code{asm} statements can safely be included in naked functions
5914 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5915 basic @code{asm} and C code may appear to work, they cannot be
5916 depended upon to work reliably and are not supported.
5918 @cindex @code{reentrant} function attribute, MSP430
5920 Reentrant functions disable interrupts upon entry and enable them
5921 upon exit. Reentrant functions cannot also have the @code{naked}
5922 or @code{critical} attributes. They can have the @code{interrupt}
5925 @cindex @code{wakeup} function attribute, MSP430
5927 This attribute only applies to interrupt functions. It is silently
5928 ignored if applied to a non-interrupt function. A wakeup interrupt
5929 function will rouse the processor from any low-power state that it
5930 might be in when the function exits.
5932 @cindex @code{lower} function attribute, MSP430
5933 @cindex @code{upper} function attribute, MSP430
5934 @cindex @code{either} function attribute, MSP430
5938 On the MSP430 target these attributes can be used to specify whether
5939 the function or variable should be placed into low memory, high
5940 memory, or the placement should be left to the linker to decide. The
5941 attributes are only significant if compiling for the MSP430X
5942 architecture in the large memory model.
5944 The attributes work in conjunction with a linker script that has been
5945 augmented to specify where to place sections with a @code{.lower} and
5946 a @code{.upper} prefix. So, for example, as well as placing the
5947 @code{.data} section, the script also specifies the placement of a
5948 @code{.lower.data} and a @code{.upper.data} section. The intention
5949 is that @code{lower} sections are placed into a small but easier to
5950 access memory region and the upper sections are placed into a larger, but
5951 slower to access, region.
5953 The @code{either} attribute is special. It tells the linker to place
5954 the object into the corresponding @code{lower} section if there is
5955 room for it. If there is insufficient room then the object is placed
5956 into the corresponding @code{upper} section instead. Note that the
5957 placement algorithm is not very sophisticated. It does not attempt to
5958 find an optimal packing of the @code{lower} sections. It just makes
5959 one pass over the objects and does the best that it can. Using the
5960 @option{-ffunction-sections} and @option{-fdata-sections} command-line
5961 options can help the packing, however, since they produce smaller,
5962 easier to pack regions.
5965 @node NDS32 Function Attributes
5966 @subsection NDS32 Function Attributes
5968 These function attributes are supported by the NDS32 back end:
5971 @cindex @code{exception} function attribute
5972 @cindex exception handler functions, NDS32
5974 Use this attribute on the NDS32 target to indicate that the specified function
5975 is an exception handler. The compiler will generate corresponding sections
5976 for use in an exception handler.
5978 @cindex @code{interrupt} function attribute, NDS32
5980 On NDS32 target, this attribute indicates that the specified function
5981 is an interrupt handler. The compiler generates corresponding sections
5982 for use in an interrupt handler. You can use the following attributes
5983 to modify the behavior:
5985 @cindex @code{nested} function attribute, NDS32
5987 This interrupt service routine is interruptible.
5988 @cindex @code{not_nested} function attribute, NDS32
5990 This interrupt service routine is not interruptible.
5991 @cindex @code{nested_ready} function attribute, NDS32
5993 This interrupt service routine is interruptible after @code{PSW.GIE}
5994 (global interrupt enable) is set. This allows interrupt service routine to
5995 finish some short critical code before enabling interrupts.
5996 @cindex @code{save_all} function attribute, NDS32
5998 The system will help save all registers into stack before entering
6000 @cindex @code{partial_save} function attribute, NDS32
6002 The system will help save caller registers into stack before entering
6006 @cindex @code{naked} function attribute, NDS32
6008 This attribute allows the compiler to construct the
6009 requisite function declaration, while allowing the body of the
6010 function to be assembly code. The specified function will not have
6011 prologue/epilogue sequences generated by the compiler. Only basic
6012 @code{asm} statements can safely be included in naked functions
6013 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6014 basic @code{asm} and C code may appear to work, they cannot be
6015 depended upon to work reliably and are not supported.
6017 @cindex @code{reset} function attribute, NDS32
6018 @cindex reset handler functions
6020 Use this attribute on the NDS32 target to indicate that the specified function
6021 is a reset handler. The compiler will generate corresponding sections
6022 for use in a reset handler. You can use the following attributes
6023 to provide extra exception handling:
6025 @cindex @code{nmi} function attribute, NDS32
6027 Provide a user-defined function to handle NMI exception.
6028 @cindex @code{warm} function attribute, NDS32
6030 Provide a user-defined function to handle warm reset exception.
6034 @node Nios II Function Attributes
6035 @subsection Nios II Function Attributes
6037 These function attributes are supported by the Nios II back end:
6040 @cindex @code{target} function attribute
6041 @item target (@var{options})
6042 As discussed in @ref{Common Function Attributes}, this attribute
6043 allows specification of target-specific compilation options.
6045 When compiling for Nios II, the following options are allowed:
6048 @cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II
6049 @cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II
6050 @item custom-@var{insn}=@var{N}
6051 @itemx no-custom-@var{insn}
6052 Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a
6053 custom instruction with encoding @var{N} when generating code that uses
6054 @var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of
6055 the custom instruction @var{insn}.
6056 These target attributes correspond to the
6057 @option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}}
6058 command-line options, and support the same set of @var{insn} keywords.
6059 @xref{Nios II Options}, for more information.
6061 @cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II
6062 @item custom-fpu-cfg=@var{name}
6063 This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}}
6064 command-line option, to select a predefined set of custom instructions
6066 @xref{Nios II Options}, for more information.
6070 @node Nvidia PTX Function Attributes
6071 @subsection Nvidia PTX Function Attributes
6073 These function attributes are supported by the Nvidia PTX back end:
6076 @cindex @code{kernel} attribute, Nvidia PTX
6078 This attribute indicates that the corresponding function should be compiled
6079 as a kernel function, which can be invoked from the host via the CUDA RT
6081 By default functions are only callable only from other PTX functions.
6083 Kernel functions must have @code{void} return type.
6086 @node PowerPC Function Attributes
6087 @subsection PowerPC Function Attributes
6089 These function attributes are supported by the PowerPC back end:
6092 @cindex indirect calls, PowerPC
6093 @cindex @code{longcall} function attribute, PowerPC
6094 @cindex @code{shortcall} function attribute, PowerPC
6097 The @code{longcall} attribute
6098 indicates that the function might be far away from the call site and
6099 require a different (more expensive) calling sequence. The
6100 @code{shortcall} attribute indicates that the function is always close
6101 enough for the shorter calling sequence to be used. These attributes
6102 override both the @option{-mlongcall} switch and
6103 the @code{#pragma longcall} setting.
6105 @xref{RS/6000 and PowerPC Options}, for more information on whether long
6106 calls are necessary.
6108 @cindex @code{target} function attribute
6109 @item target (@var{options})
6110 As discussed in @ref{Common Function Attributes}, this attribute
6111 allows specification of target-specific compilation options.
6113 On the PowerPC, the following options are allowed:
6116 @cindex @code{target("altivec")} function attribute, PowerPC
6119 Generate code that uses (does not use) AltiVec instructions. In
6120 32-bit code, you cannot enable AltiVec instructions unless
6121 @option{-mabi=altivec} is used on the command line.
6123 @cindex @code{target("cmpb")} function attribute, PowerPC
6126 Generate code that uses (does not use) the compare bytes instruction
6127 implemented on the POWER6 processor and other processors that support
6128 the PowerPC V2.05 architecture.
6130 @cindex @code{target("dlmzb")} function attribute, PowerPC
6133 Generate code that uses (does not use) the string-search @samp{dlmzb}
6134 instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
6135 generated by default when targeting those processors.
6137 @cindex @code{target("fprnd")} function attribute, PowerPC
6140 Generate code that uses (does not use) the FP round to integer
6141 instructions implemented on the POWER5+ processor and other processors
6142 that support the PowerPC V2.03 architecture.
6144 @cindex @code{target("hard-dfp")} function attribute, PowerPC
6147 Generate code that uses (does not use) the decimal floating-point
6148 instructions implemented on some POWER processors.
6150 @cindex @code{target("isel")} function attribute, PowerPC
6153 Generate code that uses (does not use) ISEL instruction.
6155 @cindex @code{target("mfcrf")} function attribute, PowerPC
6158 Generate code that uses (does not use) the move from condition
6159 register field instruction implemented on the POWER4 processor and
6160 other processors that support the PowerPC V2.01 architecture.
6162 @cindex @code{target("mulhw")} function attribute, PowerPC
6165 Generate code that uses (does not use) the half-word multiply and
6166 multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
6167 These instructions are generated by default when targeting those
6170 @cindex @code{target("multiple")} function attribute, PowerPC
6173 Generate code that uses (does not use) the load multiple word
6174 instructions and the store multiple word instructions.
6176 @cindex @code{target("update")} function attribute, PowerPC
6179 Generate code that uses (does not use) the load or store instructions
6180 that update the base register to the address of the calculated memory
6183 @cindex @code{target("popcntb")} function attribute, PowerPC
6186 Generate code that uses (does not use) the popcount and double-precision
6187 FP reciprocal estimate instruction implemented on the POWER5
6188 processor and other processors that support the PowerPC V2.02
6191 @cindex @code{target("popcntd")} function attribute, PowerPC
6194 Generate code that uses (does not use) the popcount instruction
6195 implemented on the POWER7 processor and other processors that support
6196 the PowerPC V2.06 architecture.
6198 @cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
6199 @item powerpc-gfxopt
6200 @itemx no-powerpc-gfxopt
6201 Generate code that uses (does not use) the optional PowerPC
6202 architecture instructions in the Graphics group, including
6203 floating-point select.
6205 @cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
6207 @itemx no-powerpc-gpopt
6208 Generate code that uses (does not use) the optional PowerPC
6209 architecture instructions in the General Purpose group, including
6210 floating-point square root.
6212 @cindex @code{target("recip-precision")} function attribute, PowerPC
6213 @item recip-precision
6214 @itemx no-recip-precision
6215 Assume (do not assume) that the reciprocal estimate instructions
6216 provide higher-precision estimates than is mandated by the PowerPC
6219 @cindex @code{target("string")} function attribute, PowerPC
6222 Generate code that uses (does not use) the load string instructions
6223 and the store string word instructions to save multiple registers and
6224 do small block moves.
6226 @cindex @code{target("vsx")} function attribute, PowerPC
6229 Generate code that uses (does not use) vector/scalar (VSX)
6230 instructions, and also enable the use of built-in functions that allow
6231 more direct access to the VSX instruction set. In 32-bit code, you
6232 cannot enable VSX or AltiVec instructions unless
6233 @option{-mabi=altivec} is used on the command line.
6235 @cindex @code{target("friz")} function attribute, PowerPC
6238 Generate (do not generate) the @code{friz} instruction when the
6239 @option{-funsafe-math-optimizations} option is used to optimize
6240 rounding a floating-point value to 64-bit integer and back to floating
6241 point. The @code{friz} instruction does not return the same value if
6242 the floating-point number is too large to fit in an integer.
6244 @cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
6245 @item avoid-indexed-addresses
6246 @itemx no-avoid-indexed-addresses
6247 Generate code that tries to avoid (not avoid) the use of indexed load
6248 or store instructions.
6250 @cindex @code{target("paired")} function attribute, PowerPC
6253 Generate code that uses (does not use) the generation of PAIRED simd
6256 @cindex @code{target("longcall")} function attribute, PowerPC
6259 Generate code that assumes (does not assume) that all calls are far
6260 away so that a longer more expensive calling sequence is required.
6262 @cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
6264 Specify the architecture to generate code for when compiling the
6265 function. If you select the @code{target("cpu=power7")} attribute when
6266 generating 32-bit code, VSX and AltiVec instructions are not generated
6267 unless you use the @option{-mabi=altivec} option on the command line.
6269 @cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
6270 @item tune=@var{TUNE}
6271 Specify the architecture to tune for when compiling the function. If
6272 you do not specify the @code{target("tune=@var{TUNE}")} attribute and
6273 you do specify the @code{target("cpu=@var{CPU}")} attribute,
6274 compilation tunes for the @var{CPU} architecture, and not the
6275 default tuning specified on the command line.
6278 On the PowerPC, the inliner does not inline a
6279 function that has different target options than the caller, unless the
6280 callee has a subset of the target options of the caller.
6283 @node RISC-V Function Attributes
6284 @subsection RISC-V Function Attributes
6286 These function attributes are supported by the RISC-V back end:
6289 @cindex @code{naked} function attribute, RISC-V
6291 This attribute allows the compiler to construct the
6292 requisite function declaration, while allowing the body of the
6293 function to be assembly code. The specified function will not have
6294 prologue/epilogue sequences generated by the compiler. Only basic
6295 @code{asm} statements can safely be included in naked functions
6296 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6297 basic @code{asm} and C code may appear to work, they cannot be
6298 depended upon to work reliably and are not supported.
6300 @cindex @code{interrupt} function attribute, RISC-V
6302 Use this attribute to indicate that the specified function is an interrupt
6303 handler. The compiler generates function entry and exit sequences suitable
6304 for use in an interrupt handler when this attribute is present.
6306 You can specify the kind of interrupt to be handled by adding an optional
6307 parameter to the interrupt attribute like this:
6310 void f (void) __attribute__ ((interrupt ("user")));
6313 Permissible values for this parameter are @code{user}, @code{supervisor},
6314 and @code{machine}. If there is no parameter, then it defaults to
6317 @cindex @code{riscv_vector_cc} function attribute, RISC-V
6318 @item riscv_vector_cc
6319 Use this attribute to force the function to use the vector calling
6323 void foo() __attribute__((riscv_vector_cc));
6324 [[riscv::vector_cc]] void foo(); // For C++11 and C23
6329 The following target-specific function attributes are available for the
6330 RISC-V target. For the most part, these options mirror the behavior of
6331 similar command-line options (@pxref{RISC-V Options}), but on a
6335 @cindex @code{arch=} function attribute, RISC-V
6337 Specifies the architecture version and architectural extensions to use
6338 for this function. The behavior and permissible arguments are the same as
6339 for the @option{-march=} command-line option, in addtion, it also support
6340 extension enablement list, a list of extension name and prefixed with @code{+},
6341 like @code{arch=+zba} means enable @code{zba} extension.
6342 Multiple extension can be enabled by separating them with a comma. For example:
6343 @code{arch=+zba,+zbb}.
6345 @cindex @code{tune=} function attribute, RISC-V
6347 Specifies the core for which to tune the performance of this function.
6348 The behavior and permissible arguments are the same as for the @option{-mtune=}
6349 command-line option.
6351 @cindex @code{cpu=} function attribute, RISC-V
6353 Specifies the core for which to tune the performance of this function and also
6354 whose architectural features to use. The behavior and valid arguments are the
6355 same as for the @option{-mcpu=} command-line option.
6359 The above target attributes can be specified as follows:
6362 __attribute__((target("@var{attr-string}")))
6370 where @code{@var{attr-string}} is one of the attribute strings specified above.
6372 Multiple target function attributes can be specified by separating them with
6373 a semicolon. For example:
6375 __attribute__((target("arch=+zba,+zbb;tune=rocket")))
6383 is valid and compiles function @code{foo} with @code{zba}
6384 and @code{zbb} extensions and tunes it for @code{rocket}.
6386 @node RL78 Function Attributes
6387 @subsection RL78 Function Attributes
6389 These function attributes are supported by the RL78 back end:
6392 @cindex @code{interrupt} function attribute, RL78
6393 @cindex @code{brk_interrupt} function attribute, RL78
6395 @itemx brk_interrupt
6396 These attributes indicate
6397 that the specified function is an interrupt handler. The compiler generates
6398 function entry and exit sequences suitable for use in an interrupt handler
6399 when this attribute is present.
6401 Use @code{brk_interrupt} instead of @code{interrupt} for
6402 handlers intended to be used with the @code{BRK} opcode (i.e.@: those
6403 that must end with @code{RETB} instead of @code{RETI}).
6405 @cindex @code{naked} function attribute, RL78
6407 This attribute allows the compiler to construct the
6408 requisite function declaration, while allowing the body of the
6409 function to be assembly code. The specified function will not have
6410 prologue/epilogue sequences generated by the compiler. Only basic
6411 @code{asm} statements can safely be included in naked functions
6412 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6413 basic @code{asm} and C code may appear to work, they cannot be
6414 depended upon to work reliably and are not supported.
6417 @node RX Function Attributes
6418 @subsection RX Function Attributes
6420 These function attributes are supported by the RX back end:
6423 @cindex @code{fast_interrupt} function attribute, RX
6424 @item fast_interrupt
6425 Use this attribute on the RX port to indicate that the specified
6426 function is a fast interrupt handler. This is just like the
6427 @code{interrupt} attribute, except that @code{freit} is used to return
6428 instead of @code{reit}.
6430 @cindex @code{interrupt} function attribute, RX
6432 Use this attribute to indicate
6433 that the specified function is an interrupt handler. The compiler generates
6434 function entry and exit sequences suitable for use in an interrupt handler
6435 when this attribute is present.
6437 On RX and RL78 targets, you may specify one or more vector numbers as arguments
6438 to the attribute, as well as naming an alternate table name.
6439 Parameters are handled sequentially, so one handler can be assigned to
6440 multiple entries in multiple tables. One may also pass the magic
6441 string @code{"$default"} which causes the function to be used for any
6442 unfilled slots in the current table.
6444 This example shows a simple assignment of a function to one vector in
6445 the default table (note that preprocessor macros may be used for
6446 chip-specific symbolic vector names):
6448 void __attribute__ ((interrupt (5))) txd1_handler ();
6451 This example assigns a function to two slots in the default table
6452 (using preprocessor macros defined elsewhere) and makes it the default
6453 for the @code{dct} table:
6455 void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
6459 @cindex @code{naked} function attribute, RX
6461 This attribute allows the compiler to construct the
6462 requisite function declaration, while allowing the body of the
6463 function to be assembly code. The specified function will not have
6464 prologue/epilogue sequences generated by the compiler. Only basic
6465 @code{asm} statements can safely be included in naked functions
6466 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6467 basic @code{asm} and C code may appear to work, they cannot be
6468 depended upon to work reliably and are not supported.
6470 @cindex @code{vector} function attribute, RX
6472 This RX attribute is similar to the @code{interrupt} attribute, including its
6473 parameters, but does not make the function an interrupt-handler type
6474 function (i.e.@: it retains the normal C function calling ABI). See the
6475 @code{interrupt} attribute for a description of its arguments.
6478 @node S/390 Function Attributes
6479 @subsection S/390 Function Attributes
6481 These function attributes are supported on the S/390:
6484 @cindex @code{hotpatch} function attribute, S/390
6485 @item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
6487 On S/390 System z targets, you can use this function attribute to
6488 make GCC generate a ``hot-patching'' function prologue. If the
6489 @option{-mhotpatch=} command-line option is used at the same time,
6490 the @code{hotpatch} attribute takes precedence. The first of the
6491 two arguments specifies the number of halfwords to be added before
6492 the function label. A second argument can be used to specify the
6493 number of halfwords to be added after the function label. For
6494 both arguments the maximum allowed value is 1000000.
6496 If both arguments are zero, hotpatching is disabled.
6498 @cindex @code{target} function attribute
6499 @item target (@var{options})
6500 As discussed in @ref{Common Function Attributes}, this attribute
6501 allows specification of target-specific compilation options.
6503 On S/390, the following options are supported:
6511 @item warn-framesize=
6523 @itemx no-packed-stack
6525 @itemx no-small-exec
6528 @item warn-dynamicstack
6529 @itemx no-warn-dynamicstack
6532 The options work exactly like the S/390 specific command line
6533 options (without the prefix @option{-m}) except that they do not
6534 change any feature macros. For example,
6537 @code{target("no-vx")}
6540 does not undefine the @code{__VEC__} macro.
6543 @node SH Function Attributes
6544 @subsection SH Function Attributes
6546 These function attributes are supported on the SH family of processors:
6549 @cindex @code{function_vector} function attribute, SH
6550 @cindex calling functions through the function vector on SH2A
6551 @item function_vector
6552 On SH2A targets, this attribute declares a function to be called using the
6553 TBR relative addressing mode. The argument to this attribute is the entry
6554 number of the same function in a vector table containing all the TBR
6555 relative addressable functions. For correct operation the TBR must be setup
6556 accordingly to point to the start of the vector table before any functions with
6557 this attribute are invoked. Usually a good place to do the initialization is
6558 the startup routine. The TBR relative vector table can have at max 256 function
6559 entries. The jumps to these functions are generated using a SH2A specific,
6560 non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD
6561 from GNU binutils version 2.7 or later for this attribute to work correctly.
6563 In an application, for a function being called once, this attribute
6564 saves at least 8 bytes of code; and if other successive calls are being
6565 made to the same function, it saves 2 bytes of code per each of these
6568 @cindex @code{interrupt_handler} function attribute, SH
6569 @item interrupt_handler
6570 Use this attribute to
6571 indicate that the specified function is an interrupt handler. The compiler
6572 generates function entry and exit sequences suitable for use in an
6573 interrupt handler when this attribute is present.
6575 @cindex @code{nosave_low_regs} function attribute, SH
6576 @item nosave_low_regs
6577 Use this attribute on SH targets to indicate that an @code{interrupt_handler}
6578 function should not save and restore registers R0..R7. This can be used on SH3*
6579 and SH4* targets that have a second R0..R7 register bank for non-reentrant
6582 @cindex @code{renesas} function attribute, SH
6584 On SH targets this attribute specifies that the function or struct follows the
6587 @cindex @code{resbank} function attribute, SH
6589 On the SH2A target, this attribute enables the high-speed register
6590 saving and restoration using a register bank for @code{interrupt_handler}
6591 routines. Saving to the bank is performed automatically after the CPU
6592 accepts an interrupt that uses a register bank.
6594 The nineteen 32-bit registers comprising general register R0 to R14,
6595 control register GBR, and system registers MACH, MACL, and PR and the
6596 vector table address offset are saved into a register bank. Register
6597 banks are stacked in first-in last-out (FILO) sequence. Restoration
6598 from the bank is executed by issuing a RESBANK instruction.
6600 @cindex @code{sp_switch} function attribute, SH
6602 Use this attribute on the SH to indicate an @code{interrupt_handler}
6603 function should switch to an alternate stack. It expects a string
6604 argument that names a global variable holding the address of the
6609 void f () __attribute__ ((interrupt_handler,
6610 sp_switch ("alt_stack")));
6613 @cindex @code{trap_exit} function attribute, SH
6615 Use this attribute on the SH for an @code{interrupt_handler} to return using
6616 @code{trapa} instead of @code{rte}. This attribute expects an integer
6617 argument specifying the trap number to be used.
6619 @cindex @code{trapa_handler} function attribute, SH
6621 On SH targets this function attribute is similar to @code{interrupt_handler}
6622 but it does not save and restore all registers.
6625 @node Symbian OS Function Attributes
6626 @subsection Symbian OS Function Attributes
6628 @xref{Microsoft Windows Function Attributes}, for discussion of the
6629 @code{dllexport} and @code{dllimport} attributes.
6631 @node V850 Function Attributes
6632 @subsection V850 Function Attributes
6634 The V850 back end supports these function attributes:
6637 @cindex @code{interrupt} function attribute, V850
6638 @cindex @code{interrupt_handler} function attribute, V850
6640 @itemx interrupt_handler
6641 Use these attributes to indicate
6642 that the specified function is an interrupt handler. The compiler generates
6643 function entry and exit sequences suitable for use in an interrupt handler
6644 when either attribute is present.
6647 @node Visium Function Attributes
6648 @subsection Visium Function Attributes
6650 These function attributes are supported by the Visium back end:
6653 @cindex @code{interrupt} function attribute, Visium
6655 Use this attribute to indicate
6656 that the specified function is an interrupt handler. The compiler generates
6657 function entry and exit sequences suitable for use in an interrupt handler
6658 when this attribute is present.
6661 @node x86 Function Attributes
6662 @subsection x86 Function Attributes
6664 These function attributes are supported by the x86 back end:
6667 @cindex @code{cdecl} function attribute, x86-32
6668 @cindex functions that pop the argument stack on x86-32
6671 On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
6672 assume that the calling function pops off the stack space used to
6673 pass arguments. This is
6674 useful to override the effects of the @option{-mrtd} switch.
6676 @cindex @code{fastcall} function attribute, x86-32
6677 @cindex functions that pop the argument stack on x86-32
6679 On x86-32 targets, the @code{fastcall} attribute causes the compiler to
6680 pass the first argument (if of integral type) in the register ECX and
6681 the second argument (if of integral type) in the register EDX@. Subsequent
6682 and other typed arguments are passed on the stack. The called function
6683 pops the arguments off the stack. If the number of arguments is variable all
6684 arguments are pushed on the stack.
6686 @cindex @code{thiscall} function attribute, x86-32
6687 @cindex functions that pop the argument stack on x86-32
6689 On x86-32 targets, the @code{thiscall} attribute causes the compiler to
6690 pass the first argument (if of integral type) in the register ECX.
6691 Subsequent and other typed arguments are passed on the stack. The called
6692 function pops the arguments off the stack.
6693 If the number of arguments is variable all arguments are pushed on the
6695 The @code{thiscall} attribute is intended for C++ non-static member functions.
6696 As a GCC extension, this calling convention can be used for C functions
6697 and for static member methods.
6699 @cindex @code{ms_abi} function attribute, x86
6700 @cindex @code{sysv_abi} function attribute, x86
6704 On 32-bit and 64-bit x86 targets, you can use an ABI attribute
6705 to indicate which calling convention should be used for a function. The
6706 @code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
6707 while the @code{sysv_abi} attribute tells the compiler to use the System V
6708 ELF ABI, which is used on GNU/Linux and other systems. The default is to use
6709 the Microsoft ABI when targeting Windows. On all other systems, the default
6710 is the System V ELF ABI.
6712 Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
6713 requires the @option{-maccumulate-outgoing-args} option.
6715 @cindex @code{callee_pop_aggregate_return} function attribute, x86
6716 @item callee_pop_aggregate_return (@var{number})
6718 On x86-32 targets, you can use this attribute to control how
6719 aggregates are returned in memory. If the caller is responsible for
6720 popping the hidden pointer together with the rest of the arguments, specify
6721 @var{number} equal to zero. If callee is responsible for popping the
6722 hidden pointer, specify @var{number} equal to one.
6724 The default x86-32 ABI assumes that the callee pops the
6725 stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
6726 the compiler assumes that the
6727 caller pops the stack for hidden pointer.
6729 @cindex @code{ms_hook_prologue} function attribute, x86
6730 @item ms_hook_prologue
6732 On 32-bit and 64-bit x86 targets, you can use
6733 this function attribute to make GCC generate the ``hot-patching'' function
6734 prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
6737 @cindex @code{naked} function attribute, x86
6739 This attribute allows the compiler to construct the
6740 requisite function declaration, while allowing the body of the
6741 function to be assembly code. The specified function will not have
6742 prologue/epilogue sequences generated by the compiler. Only basic
6743 @code{asm} statements can safely be included in naked functions
6744 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
6745 basic @code{asm} and C code may appear to work, they cannot be
6746 depended upon to work reliably and are not supported.
6748 @cindex @code{regparm} function attribute, x86
6749 @cindex functions that are passed arguments in registers on x86-32
6750 @item regparm (@var{number})
6751 On x86-32 targets, the @code{regparm} attribute causes the compiler to
6752 pass arguments number one to @var{number} if they are of integral type
6753 in registers EAX, EDX, and ECX instead of on the stack. Functions that
6754 take a variable number of arguments continue to be passed all of their
6755 arguments on the stack.
6757 Beware that on some ELF systems this attribute is unsuitable for
6758 global functions in shared libraries with lazy binding (which is the
6759 default). Lazy binding sends the first call via resolving code in
6760 the loader, which might assume EAX, EDX and ECX can be clobbered, as
6761 per the standard calling conventions. Solaris 8 is affected by this.
6762 Systems with the GNU C Library version 2.1 or higher
6763 and FreeBSD are believed to be
6764 safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
6765 disabled with the linker or the loader if desired, to avoid the
6768 @cindex @code{sseregparm} function attribute, x86
6770 On x86-32 targets with SSE support, the @code{sseregparm} attribute
6771 causes the compiler to pass up to 3 floating-point arguments in
6772 SSE registers instead of on the stack. Functions that take a
6773 variable number of arguments continue to pass all of their
6774 floating-point arguments on the stack.
6776 @cindex @code{force_align_arg_pointer} function attribute, x86
6777 @item force_align_arg_pointer
6778 On x86 targets, the @code{force_align_arg_pointer} attribute may be
6779 applied to individual function definitions, generating an alternate
6780 prologue and epilogue that realigns the run-time stack if necessary.
6781 This supports mixing legacy codes that run with a 4-byte aligned stack
6782 with modern codes that keep a 16-byte stack for SSE compatibility.
6784 @cindex @code{stdcall} function attribute, x86-32
6785 @cindex functions that pop the argument stack on x86-32
6787 On x86-32 targets, the @code{stdcall} attribute causes the compiler to
6788 assume that the called function pops off the stack space used to
6789 pass arguments, unless it takes a variable number of arguments.
6791 @cindex @code{no_callee_saved_registers} function attribute, x86
6792 @item no_callee_saved_registers
6793 Use this attribute to indicate that the specified function has no
6794 callee-saved registers. That is, all registers can be used as scratch
6795 registers. For example, this attribute can be used for a function
6796 called from the interrupt handler assembly stub which will preserve
6797 all registers and return from interrupt.
6799 @cindex @code{no_caller_saved_registers} function attribute, x86
6800 @item no_caller_saved_registers
6801 Use this attribute to indicate that the specified function has no
6802 caller-saved registers. That is, all registers are callee-saved. For
6803 example, this attribute can be used for a function called from an
6804 interrupt handler. The compiler generates proper function entry and
6805 exit sequences to save and restore any modified registers, except for
6806 the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87
6807 states, the GCC option @option{-mgeneral-regs-only} should be used to
6808 compile functions with @code{no_caller_saved_registers} attribute.
6810 @cindex @code{interrupt} function attribute, x86
6812 Use this attribute to indicate that the specified function is an
6813 interrupt handler or an exception handler (depending on parameters passed
6814 to the function, explained further). The compiler generates function
6815 entry and exit sequences suitable for use in an interrupt handler when
6816 this attribute is present. The @code{IRET} instruction, instead of the
6817 @code{RET} instruction, is used to return from interrupt handlers. All
6818 registers, except for the EFLAGS register which is restored by the
6819 @code{IRET} instruction, are preserved by the compiler. Since GCC
6820 doesn't preserve SSE, MMX nor x87 states, the GCC option
6821 @option{-mgeneral-regs-only} should be used to compile interrupt and
6824 Any interruptible-without-stack-switch code must be compiled with
6825 @option{-mno-red-zone} since interrupt handlers can and will, because
6826 of the hardware design, touch the red zone.
6828 An interrupt handler must be declared with a mandatory pointer
6832 struct interrupt_frame;
6834 __attribute__ ((interrupt))
6836 f (struct interrupt_frame *frame)
6842 and you must define @code{struct interrupt_frame} as described in the
6845 Exception handlers differ from interrupt handlers because the system
6846 pushes an error code on the stack. An exception handler declaration is
6847 similar to that for an interrupt handler, but with a different mandatory
6848 function signature. The compiler arranges to pop the error code off the
6849 stack before the @code{IRET} instruction.
6853 typedef unsigned long long int uword_t;
6855 typedef unsigned int uword_t;
6858 struct interrupt_frame;
6860 __attribute__ ((interrupt))
6862 f (struct interrupt_frame *frame, uword_t error_code)
6868 Exception handlers should only be used for exceptions that push an error
6869 code; you should use an interrupt handler in other cases. The system
6870 will crash if the wrong kind of handler is used.
6872 @cindex @code{target} function attribute
6873 @item target (@var{options})
6874 As discussed in @ref{Common Function Attributes}, this attribute
6875 allows specification of target-specific compilation options.
6877 On the x86, the following options are allowed:
6879 @cindex @code{target("3dnow")} function attribute, x86
6882 Enable/disable the generation of the 3DNow!@: instructions.
6884 @cindex @code{target("3dnowa")} function attribute, x86
6887 Enable/disable the generation of the enhanced 3DNow!@: instructions.
6889 @cindex @code{target("abm")} function attribute, x86
6892 Enable/disable the generation of the advanced bit instructions.
6894 @cindex @code{target("adx")} function attribute, x86
6897 Enable/disable the generation of the ADX instructions.
6899 @cindex @code{target("aes")} function attribute, x86
6902 Enable/disable the generation of the AES instructions.
6904 @cindex @code{target("avx")} function attribute, x86
6907 Enable/disable the generation of the AVX instructions.
6909 @cindex @code{target("avx2")} function attribute, x86
6912 Enable/disable the generation of the AVX2 instructions.
6914 @cindex @code{target("avx5124fmaps")} function attribute, x86
6916 @itemx no-avx5124fmaps
6917 Enable/disable the generation of the AVX5124FMAPS instructions.
6919 @cindex @code{target("avx5124vnniw")} function attribute, x86
6921 @itemx no-avx5124vnniw
6922 Enable/disable the generation of the AVX5124VNNIW instructions.
6924 @cindex @code{target("avx512bitalg")} function attribute, x86
6926 @itemx no-avx512bitalg
6927 Enable/disable the generation of the AVX512BITALG instructions.
6929 @cindex @code{target("avx512bw")} function attribute, x86
6932 Enable/disable the generation of the AVX512BW instructions.
6934 @cindex @code{target("avx512cd")} function attribute, x86
6937 Enable/disable the generation of the AVX512CD instructions.
6939 @cindex @code{target("avx512dq")} function attribute, x86
6942 Enable/disable the generation of the AVX512DQ instructions.
6944 @cindex @code{target("avx512er")} function attribute, x86
6947 Enable/disable the generation of the AVX512ER instructions.
6949 @cindex @code{target("avx512f")} function attribute, x86
6952 Enable/disable the generation of the AVX512F instructions.
6954 @cindex @code{target("avx512ifma")} function attribute, x86
6956 @itemx no-avx512ifma
6957 Enable/disable the generation of the AVX512IFMA instructions.
6959 @cindex @code{target("avx512pf")} function attribute, x86
6962 Enable/disable the generation of the AVX512PF instructions.
6964 @cindex @code{target("avx512vbmi")} function attribute, x86
6966 @itemx no-avx512vbmi
6967 Enable/disable the generation of the AVX512VBMI instructions.
6969 @cindex @code{target("avx512vbmi2")} function attribute, x86
6971 @itemx no-avx512vbmi2
6972 Enable/disable the generation of the AVX512VBMI2 instructions.
6974 @cindex @code{target("avx512vl")} function attribute, x86
6977 Enable/disable the generation of the AVX512VL instructions.
6979 @cindex @code{target("avx512vnni")} function attribute, x86
6981 @itemx no-avx512vnni
6982 Enable/disable the generation of the AVX512VNNI instructions.
6984 @cindex @code{target("avx512vpopcntdq")} function attribute, x86
6985 @item avx512vpopcntdq
6986 @itemx no-avx512vpopcntdq
6987 Enable/disable the generation of the AVX512VPOPCNTDQ instructions.
6989 @cindex @code{target("bmi")} function attribute, x86
6992 Enable/disable the generation of the BMI instructions.
6994 @cindex @code{target("bmi2")} function attribute, x86
6997 Enable/disable the generation of the BMI2 instructions.
6999 @cindex @code{target("cldemote")} function attribute, x86
7002 Enable/disable the generation of the CLDEMOTE instructions.
7004 @cindex @code{target("clflushopt")} function attribute, x86
7006 @itemx no-clflushopt
7007 Enable/disable the generation of the CLFLUSHOPT instructions.
7009 @cindex @code{target("clwb")} function attribute, x86
7012 Enable/disable the generation of the CLWB instructions.
7014 @cindex @code{target("clzero")} function attribute, x86
7017 Enable/disable the generation of the CLZERO instructions.
7019 @cindex @code{target("crc32")} function attribute, x86
7022 Enable/disable the generation of the CRC32 instructions.
7024 @cindex @code{target("cx16")} function attribute, x86
7027 Enable/disable the generation of the CMPXCHG16B instructions.
7029 @cindex @code{target("default")} function attribute, x86
7031 @xref{Function Multiversioning}, where it is used to specify the
7032 default function version.
7034 @cindex @code{target("f16c")} function attribute, x86
7037 Enable/disable the generation of the F16C instructions.
7039 @cindex @code{target("fma")} function attribute, x86
7042 Enable/disable the generation of the FMA instructions.
7044 @cindex @code{target("fma4")} function attribute, x86
7047 Enable/disable the generation of the FMA4 instructions.
7049 @cindex @code{target("fsgsbase")} function attribute, x86
7052 Enable/disable the generation of the FSGSBASE instructions.
7054 @cindex @code{target("fxsr")} function attribute, x86
7057 Enable/disable the generation of the FXSR instructions.
7059 @cindex @code{target("gfni")} function attribute, x86
7062 Enable/disable the generation of the GFNI instructions.
7064 @cindex @code{target("hle")} function attribute, x86
7067 Enable/disable the generation of the HLE instruction prefixes.
7069 @cindex @code{target("lwp")} function attribute, x86
7072 Enable/disable the generation of the LWP instructions.
7074 @cindex @code{target("lzcnt")} function attribute, x86
7077 Enable/disable the generation of the LZCNT instructions.
7079 @cindex @code{target("mmx")} function attribute, x86
7082 Enable/disable the generation of the MMX instructions.
7084 @cindex @code{target("movbe")} function attribute, x86
7087 Enable/disable the generation of the MOVBE instructions.
7089 @cindex @code{target("movdir64b")} function attribute, x86
7092 Enable/disable the generation of the MOVDIR64B instructions.
7094 @cindex @code{target("movdiri")} function attribute, x86
7097 Enable/disable the generation of the MOVDIRI instructions.
7099 @cindex @code{target("mwait")} function attribute, x86
7102 Enable/disable the generation of the MWAIT and MONITOR instructions.
7104 @cindex @code{target("mwaitx")} function attribute, x86
7107 Enable/disable the generation of the MWAITX instructions.
7109 @cindex @code{target("pclmul")} function attribute, x86
7112 Enable/disable the generation of the PCLMUL instructions.
7114 @cindex @code{target("pconfig")} function attribute, x86
7117 Enable/disable the generation of the PCONFIG instructions.
7119 @cindex @code{target("pku")} function attribute, x86
7122 Enable/disable the generation of the PKU instructions.
7124 @cindex @code{target("popcnt")} function attribute, x86
7127 Enable/disable the generation of the POPCNT instruction.
7129 @cindex @code{target("prefetchwt1")} function attribute, x86
7131 @itemx no-prefetchwt1
7132 Enable/disable the generation of the PREFETCHWT1 instructions.
7134 @cindex @code{target("prfchw")} function attribute, x86
7137 Enable/disable the generation of the PREFETCHW instruction.
7139 @cindex @code{target("ptwrite")} function attribute, x86
7142 Enable/disable the generation of the PTWRITE instructions.
7144 @cindex @code{target("rdpid")} function attribute, x86
7147 Enable/disable the generation of the RDPID instructions.
7149 @cindex @code{target("rdrnd")} function attribute, x86
7152 Enable/disable the generation of the RDRND instructions.
7154 @cindex @code{target("rdseed")} function attribute, x86
7157 Enable/disable the generation of the RDSEED instructions.
7159 @cindex @code{target("rtm")} function attribute, x86
7162 Enable/disable the generation of the RTM instructions.
7164 @cindex @code{target("sahf")} function attribute, x86
7167 Enable/disable the generation of the SAHF instructions.
7169 @cindex @code{target("sgx")} function attribute, x86
7172 Enable/disable the generation of the SGX instructions.
7174 @cindex @code{target("sha")} function attribute, x86
7177 Enable/disable the generation of the SHA instructions.
7179 @cindex @code{target("shstk")} function attribute, x86
7182 Enable/disable the shadow stack built-in functions from CET.
7184 @cindex @code{target("sse")} function attribute, x86
7187 Enable/disable the generation of the SSE instructions.
7189 @cindex @code{target("sse2")} function attribute, x86
7192 Enable/disable the generation of the SSE2 instructions.
7194 @cindex @code{target("sse3")} function attribute, x86
7197 Enable/disable the generation of the SSE3 instructions.
7199 @cindex @code{target("sse4")} function attribute, x86
7202 Enable/disable the generation of the SSE4 instructions (both SSE4.1
7205 @cindex @code{target("sse4.1")} function attribute, x86
7208 Enable/disable the generation of the SSE4.1 instructions.
7210 @cindex @code{target("sse4.2")} function attribute, x86
7213 Enable/disable the generation of the SSE4.2 instructions.
7215 @cindex @code{target("sse4a")} function attribute, x86
7218 Enable/disable the generation of the SSE4A instructions.
7220 @cindex @code{target("ssse3")} function attribute, x86
7223 Enable/disable the generation of the SSSE3 instructions.
7225 @cindex @code{target("tbm")} function attribute, x86
7228 Enable/disable the generation of the TBM instructions.
7230 @cindex @code{target("vaes")} function attribute, x86
7233 Enable/disable the generation of the VAES instructions.
7235 @cindex @code{target("vpclmulqdq")} function attribute, x86
7237 @itemx no-vpclmulqdq
7238 Enable/disable the generation of the VPCLMULQDQ instructions.
7240 @cindex @code{target("waitpkg")} function attribute, x86
7243 Enable/disable the generation of the WAITPKG instructions.
7245 @cindex @code{target("wbnoinvd")} function attribute, x86
7248 Enable/disable the generation of the WBNOINVD instructions.
7250 @cindex @code{target("xop")} function attribute, x86
7253 Enable/disable the generation of the XOP instructions.
7255 @cindex @code{target("xsave")} function attribute, x86
7258 Enable/disable the generation of the XSAVE instructions.
7260 @cindex @code{target("xsavec")} function attribute, x86
7263 Enable/disable the generation of the XSAVEC instructions.
7265 @cindex @code{target("xsaveopt")} function attribute, x86
7268 Enable/disable the generation of the XSAVEOPT instructions.
7270 @cindex @code{target("xsaves")} function attribute, x86
7273 Enable/disable the generation of the XSAVES instructions.
7275 @cindex @code{target("amx-tile")} function attribute, x86
7278 Enable/disable the generation of the AMX-TILE instructions.
7280 @cindex @code{target("amx-int8")} function attribute, x86
7283 Enable/disable the generation of the AMX-INT8 instructions.
7285 @cindex @code{target("amx-bf16")} function attribute, x86
7288 Enable/disable the generation of the AMX-BF16 instructions.
7290 @cindex @code{target("uintr")} function attribute, x86
7293 Enable/disable the generation of the UINTR instructions.
7295 @cindex @code{target("hreset")} function attribute, x86
7298 Enable/disable the generation of the HRESET instruction.
7300 @cindex @code{target("kl")} function attribute, x86
7303 Enable/disable the generation of the KEYLOCKER instructions.
7305 @cindex @code{target("widekl")} function attribute, x86
7308 Enable/disable the generation of the WIDEKL instructions.
7310 @cindex @code{target("avxvnni")} function attribute, x86
7313 Enable/disable the generation of the AVXVNNI instructions.
7315 @cindex @code{target("avxifma")} function attribute, x86
7318 Enable/disable the generation of the AVXIFMA instructions.
7320 @cindex @code{target("avxvnniint8")} function attribute, x86
7322 @itemx no-avxvnniint8
7323 Enable/disable the generation of the AVXVNNIINT8 instructions.
7325 @cindex @code{target("avxneconvert")} function attribute, x86
7327 @itemx no-avxneconvert
7328 Enable/disable the generation of the AVXNECONVERT instructions.
7330 @cindex @code{target("cmpccxadd")} function attribute, x86
7333 Enable/disable the generation of the CMPccXADD instructions.
7335 @cindex @code{target("amx-fp16")} function attribute, x86
7338 Enable/disable the generation of the AMX-FP16 instructions.
7340 @cindex @code{target("prefetchi")} function attribute, x86
7343 Enable/disable the generation of the PREFETCHI instructions.
7345 @cindex @code{target("raoint")} function attribute, x86
7348 Enable/disable the generation of the RAOINT instructions.
7350 @cindex @code{target("amx-complex")} function attribute, x86
7352 @itemx no-amx-complex
7353 Enable/disable the generation of the AMX-COMPLEX instructions.
7355 @cindex @code{target("avxvnniint16")} function attribute, x86
7357 @itemx no-avxvnniint16
7358 Enable/disable the generation of the AVXVNNIINT16 instructions.
7360 @cindex @code{target("sm3")} function attribute, x86
7363 Enable/disable the generation of the SM3 instructions.
7365 @cindex @code{target("sha512")} function attribute, x86
7368 Enable/disable the generation of the SHA512 instructions.
7370 @cindex @code{target("sm4")} function attribute, x86
7373 Enable/disable the generation of the SM4 instructions.
7375 @cindex @code{target("usermsr")} function attribute, x86
7378 Enable/disable the generation of the USER_MSR instructions.
7380 @cindex @code{target("apxf")} function attribute, x86
7383 Enable/disable the generation of the APX features, including
7384 EGPR, PUSH2POP2, NDD and PPX.
7386 @cindex @code{target("avx10.1")} function attribute, x86
7389 Enable/disable the generation of the AVX10.1 instructions.
7391 @cindex @code{target("avx10.1-256")} function attribute, x86
7393 @itemx no-avx10.1-256
7394 Enable/disable the generation of the AVX10.1 instructions.
7396 @cindex @code{target("avx10.1-512")} function attribute, x86
7398 @itemx no-avx10.1-512
7399 Enable/disable the generation of the AVX10.1 512 bit instructions.
7401 @cindex @code{target("cld")} function attribute, x86
7404 Enable/disable the generation of the CLD before string moves.
7406 @cindex @code{target("fancy-math-387")} function attribute, x86
7407 @item fancy-math-387
7408 @itemx no-fancy-math-387
7409 Enable/disable the generation of the @code{sin}, @code{cos}, and
7410 @code{sqrt} instructions on the 387 floating-point unit.
7412 @cindex @code{target("ieee-fp")} function attribute, x86
7415 Enable/disable the generation of floating point that depends on IEEE arithmetic.
7417 @cindex @code{target("inline-all-stringops")} function attribute, x86
7418 @item inline-all-stringops
7419 @itemx no-inline-all-stringops
7420 Enable/disable inlining of string operations.
7422 @cindex @code{target("inline-stringops-dynamically")} function attribute, x86
7423 @item inline-stringops-dynamically
7424 @itemx no-inline-stringops-dynamically
7425 Enable/disable the generation of the inline code to do small string
7426 operations and calling the library routines for large operations.
7428 @cindex @code{target("align-stringops")} function attribute, x86
7429 @item align-stringops
7430 @itemx no-align-stringops
7431 Do/do not align destination of inlined string operations.
7433 @cindex @code{target("recip")} function attribute, x86
7436 Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
7437 instructions followed an additional Newton-Raphson step instead of
7438 doing a floating-point division.
7440 @cindex @code{target("general-regs-only")} function attribute, x86
7441 @item general-regs-only
7442 Generate code which uses only the general registers.
7444 @cindex @code{target("arch=@var{ARCH}")} function attribute, x86
7445 @item arch=@var{ARCH}
7446 Specify the architecture to generate code for in compiling the function.
7448 @cindex @code{target("tune=@var{TUNE}")} function attribute, x86
7449 @item tune=@var{TUNE}
7450 Specify the architecture to tune for in compiling the function.
7452 @cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
7453 @item fpmath=@var{FPMATH}
7454 Specify which floating-point unit to use. You must specify the
7455 @code{target("fpmath=sse,387")} option as
7456 @code{target("fpmath=sse+387")} because the comma would separate
7459 @cindex @code{prefer-vector-width} function attribute, x86
7460 @item prefer-vector-width=@var{OPT}
7461 On x86 targets, the @code{prefer-vector-width} attribute informs the
7462 compiler to use @var{OPT}-bit vector width in instructions
7463 instead of the default on the selected platform.
7465 Valid @var{OPT} values are:
7469 No extra limitations applied to GCC other than defined by the selected platform.
7472 Prefer 128-bit vector width for instructions.
7475 Prefer 256-bit vector width for instructions.
7478 Prefer 512-bit vector width for instructions.
7483 @cindex @code{indirect_branch} function attribute, x86
7484 @item indirect_branch("@var{choice}")
7485 On x86 targets, the @code{indirect_branch} attribute causes the compiler
7486 to convert indirect call and jump with @var{choice}. @samp{keep}
7487 keeps indirect call and jump unmodified. @samp{thunk} converts indirect
7488 call and jump to call and return thunk. @samp{thunk-inline} converts
7489 indirect call and jump to inlined call and return thunk.
7490 @samp{thunk-extern} converts indirect call and jump to external call
7491 and return thunk provided in a separate object file.
7493 @cindex @code{function_return} function attribute, x86
7494 @item function_return("@var{choice}")
7495 On x86 targets, the @code{function_return} attribute causes the compiler
7496 to convert function return with @var{choice}. @samp{keep} keeps function
7497 return unmodified. @samp{thunk} converts function return to call and
7498 return thunk. @samp{thunk-inline} converts function return to inlined
7499 call and return thunk. @samp{thunk-extern} converts function return to
7500 external call and return thunk provided in a separate object file.
7502 @cindex @code{nocf_check} function attribute
7504 The @code{nocf_check} attribute on a function is used to inform the
7505 compiler that the function's prologue should not be instrumented when
7506 compiled with the @option{-fcf-protection=branch} option. The
7507 compiler assumes that the function's address is a valid target for a
7508 control-flow transfer.
7510 The @code{nocf_check} attribute on a type of pointer to function is
7511 used to inform the compiler that a call through the pointer should
7512 not be instrumented when compiled with the
7513 @option{-fcf-protection=branch} option. The compiler assumes
7514 that the function's address from the pointer is a valid target for
7515 a control-flow transfer. A direct function call through a function
7516 name is assumed to be a safe call thus direct calls are not
7517 instrumented by the compiler.
7519 The @code{nocf_check} attribute is applied to an object's type.
7520 In case of assignment of a function address or a function pointer to
7521 another pointer, the attribute is not carried over from the right-hand
7522 object's type; the type of left-hand object stays unchanged. The
7523 compiler checks for @code{nocf_check} attribute mismatch and reports
7524 a warning in case of mismatch.
7528 int foo (void) __attribute__(nocf_check);
7529 void (*foo1)(void) __attribute__(nocf_check);
7532 /* foo's address is assumed to be valid. */
7536 /* This call site is not checked for control-flow
7540 /* A warning is issued about attribute mismatch. */
7543 /* This call site is still not checked. */
7546 /* This call site is checked. */
7549 /* A warning is issued about attribute mismatch. */
7552 /* This call site is still checked. */
7559 @cindex @code{cf_check} function attribute, x86
7562 The @code{cf_check} attribute on a function is used to inform the
7563 compiler that ENDBR instruction should be placed at the function
7564 entry when @option{-fcf-protection=branch} is enabled.
7566 @cindex @code{indirect_return} function attribute, x86
7567 @item indirect_return
7569 The @code{indirect_return} attribute can be applied to a function,
7570 as well as variable or type of function pointer to inform the
7571 compiler that the function may return via indirect branch.
7573 @cindex @code{fentry_name} function attribute, x86
7574 @item fentry_name("@var{name}")
7575 On x86 targets, the @code{fentry_name} attribute sets the function to
7576 call on function entry when function instrumentation is enabled
7577 with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte
7578 nop sequence is generated.
7580 @cindex @code{fentry_section} function attribute, x86
7581 @item fentry_section("@var{name}")
7582 On x86 targets, the @code{fentry_section} attribute sets the name
7583 of the section to record function entry instrumentation calls in when
7584 enabled with @option{-pg -mrecord-mcount}
7586 @cindex @code{nodirect_extern_access} function attribute
7587 @opindex mno-direct-extern-access
7588 @item nodirect_extern_access
7589 This attribute, attached to a global variable or function, is the
7590 counterpart to option @option{-mno-direct-extern-access}.
7594 @subsubsection Inlining rules
7595 On the x86, the inliner does not inline a
7596 function that has different target options than the caller, unless the
7597 callee has a subset of the target options of the caller. For example
7598 a function declared with @code{target("sse3")} can inline a function
7599 with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
7601 Besides the basic rule, when a function specifies
7602 @code{target("arch=@var{ARCH}")} or @code{target("tune=@var{TUNE}")}
7603 attribute, the inlining rule will be different. It allows inlining of
7604 a function with default @option{-march=x86-64} and
7605 @option{-mtune=generic} specified, or a function that has a subset
7606 of ISA features and marked with always_inline.
7608 @node Xstormy16 Function Attributes
7609 @subsection Xstormy16 Function Attributes
7611 These function attributes are supported by the Xstormy16 back end:
7614 @cindex @code{interrupt} function attribute, Xstormy16
7616 Use this attribute to indicate
7617 that the specified function is an interrupt handler. The compiler generates
7618 function entry and exit sequences suitable for use in an interrupt handler
7619 when this attribute is present.
7622 @node Variable Attributes
7623 @section Specifying Attributes of Variables
7624 @cindex attribute of variables
7625 @cindex variable attributes
7627 You can use attributes to specify special properties
7628 of variables, function parameters, or structure, union, and, in C++, class
7629 members. Some attributes are currently
7630 defined generically for variables. Other attributes are defined for
7631 variables on particular target systems. Other attributes are available
7632 for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
7633 enumerators (@pxref{Enumerator Attributes}), statements
7634 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
7635 Other front ends might define more attributes
7636 (@pxref{C++ Extensions,,Extensions to the C++ Language}).
7638 GCC provides two different ways to specify attributes: the traditional
7639 GNU syntax using @samp{__attribute__ ((...))} annotations, and the
7640 newer standard C and C++ syntax using @samp{[[...]]} with the
7641 @samp{gnu::} prefix on attribute names. Note that the exact rules for
7642 placement of attributes in your source code are different depending on
7643 which syntax you use. @xref{Attribute Syntax}, for details.
7646 * Common Variable Attributes::
7647 * ARC Variable Attributes::
7648 * AVR Variable Attributes::
7649 * Blackfin Variable Attributes::
7650 * H8/300 Variable Attributes::
7651 * IA-64 Variable Attributes::
7652 * LoongArch Variable Attributes::
7653 * M32R/D Variable Attributes::
7654 * Microsoft Windows Variable Attributes::
7655 * MSP430 Variable Attributes::
7656 * Nvidia PTX Variable Attributes::
7657 * PowerPC Variable Attributes::
7658 * RL78 Variable Attributes::
7659 * V850 Variable Attributes::
7660 * x86 Variable Attributes::
7661 * Xstormy16 Variable Attributes::
7664 @node Common Variable Attributes
7665 @subsection Common Variable Attributes
7667 The following attributes are supported on most targets.
7670 @c Keep this table alphabetized by attribute name. Treat _ as space.
7672 @cindex @code{alias} variable attribute
7673 @item alias ("@var{target}")
7674 The @code{alias} variable attribute causes the declaration to be emitted
7675 as an alias for another symbol known as an @dfn{alias target}. Except
7676 for top-level qualifiers the alias target must have the same type as
7677 the alias. For instance, the following
7681 extern int __attribute__ ((alias ("var_target"))) var_alias;
7685 defines @code{var_alias} to be an alias for the @code{var_target} variable.
7687 It is an error if the alias target is not defined in the same translation
7690 Note that in the absence of the attribute GCC assumes that distinct
7691 declarations with external linkage denote distinct objects. Using both
7692 the alias and the alias target to access the same object is undefined
7693 in a translation unit without a declaration of the alias with the attribute.
7695 This attribute requires assembler and object file support, and may not be
7696 available on all targets.
7698 @cindex @code{aligned} variable attribute
7700 @itemx aligned (@var{alignment})
7701 The @code{aligned} attribute specifies a minimum alignment for the variable
7702 or structure field, measured in bytes. When specified, @var{alignment} must
7703 be an integer constant power of 2. Specifying no @var{alignment} argument
7704 implies the maximum alignment for the target, which is often, but by no
7705 means always, 8 or 16 bytes.
7707 For example, the declaration:
7710 int x __attribute__ ((aligned (16))) = 0;
7714 causes the compiler to allocate the global variable @code{x} on a
7715 16-byte boundary. On a 68040, this could be used in conjunction with
7716 an @code{asm} expression to access the @code{move16} instruction which
7717 requires 16-byte aligned operands.
7719 You can also specify the alignment of structure fields. For example, to
7720 create a double-word aligned @code{int} pair, you could write:
7723 struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
7727 This is an alternative to creating a union with a @code{double} member,
7728 which forces the union to be double-word aligned.
7730 As in the preceding examples, you can explicitly specify the alignment
7731 (in bytes) that you wish the compiler to use for a given variable or
7732 structure field. Alternatively, you can leave out the alignment factor
7733 and just ask the compiler to align a variable or field to the
7734 default alignment for the target architecture you are compiling for.
7735 The default alignment is sufficient for all scalar types, but may not be
7736 enough for all vector types on a target that supports vector operations.
7737 The default alignment is fixed for a particular target ABI.
7739 GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
7740 which is the largest alignment ever used for any data type on the
7741 target machine you are compiling for. For example, you could write:
7744 short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
7747 The compiler automatically sets the alignment for the declared
7748 variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
7749 often make copy operations more efficient, because the compiler can
7750 use whatever instructions copy the biggest chunks of memory when
7751 performing copies to or from the variables or fields that you have
7752 aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
7753 may change depending on command-line options.
7755 When used on a struct, or struct member, the @code{aligned} attribute can
7756 only increase the alignment; in order to decrease it, the @code{packed}
7757 attribute must be specified as well. When used as part of a typedef, the
7758 @code{aligned} attribute can both increase and decrease alignment, and
7759 specifying the @code{packed} attribute generates a warning.
7761 Note that the effectiveness of @code{aligned} attributes for static
7762 variables may be limited by inherent limitations in the system linker
7763 and/or object file format. On some systems, the linker is
7764 only able to arrange for variables to be aligned up to a certain maximum
7765 alignment. (For some linkers, the maximum supported alignment may
7766 be very very small.) If your linker is only able to align variables
7767 up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
7768 in an @code{__attribute__} still only provides you with 8-byte
7769 alignment. See your linker documentation for further information.
7771 Stack variables are not affected by linker restrictions; GCC can properly
7772 align them on any target.
7774 The @code{aligned} attribute can also be used for functions
7775 (@pxref{Common Function Attributes}.)
7777 @cindex @code{alloc_size} variable attribute
7778 @item alloc_size (@var{position})
7779 @itemx alloc_size (@var{position-1}, @var{position-2})
7780 The @code{alloc_size} variable attribute may be applied to the declaration
7781 of a pointer to a function that returns a pointer and takes at least one
7782 argument of an integer type. It indicates that the returned pointer points
7783 to an object whose size is given by the function argument at @var{position},
7784 or by the product of the arguments at @var{position-1} and @var{position-2}.
7785 Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other
7786 sizes are diagnosed when detected. GCC uses this information to improve
7787 the results of @code{__builtin_object_size}.
7789 For instance, the following declarations
7792 typedef __attribute__ ((alloc_size (1, 2))) void*
7793 (*calloc_ptr) (size_t, size_t);
7794 typedef __attribute__ ((alloc_size (1))) void*
7795 (*malloc_ptr) (size_t);
7799 specify that @code{calloc_ptr} is a pointer of a function that, like
7800 the standard C function @code{calloc}, returns an object whose size
7801 is given by the product of arguments 1 and 2, and similarly, that
7802 @code{malloc_ptr}, like the standard C function @code{malloc},
7803 returns an object whose size is given by argument 1 to the function.
7805 @cindex @code{cleanup} variable attribute
7806 @item cleanup (@var{cleanup_function})
7807 The @code{cleanup} attribute runs a function when the variable goes
7808 out of scope. This attribute can only be applied to auto function
7809 scope variables; it may not be applied to parameters or variables
7810 with static storage duration. The function must take one parameter,
7811 a pointer to a type compatible with the variable. The return value
7812 of the function (if any) is ignored.
7814 When multiple variables in the same scope have @code{cleanup}
7815 attributes, at exit from the scope their associated cleanup functions
7816 are run in reverse order of definition (last defined, first
7819 If @option{-fexceptions} is enabled, then @var{cleanup_function}
7820 is run during the stack unwinding that happens during the
7821 processing of the exception. Note that the @code{cleanup} attribute
7822 does not allow the exception to be caught, only to perform an action.
7823 It is undefined what happens if @var{cleanup_function} does not
7826 @cindex @code{common} variable attribute
7827 @cindex @code{nocommon} variable attribute
7832 The @code{common} attribute requests GCC to place a variable in
7833 ``common'' storage. The @code{nocommon} attribute requests the
7834 opposite---to allocate space for it directly.
7836 These attributes override the default chosen by the
7837 @option{-fno-common} and @option{-fcommon} flags respectively.
7839 @cindex @code{copy} variable attribute
7841 @itemx copy (@var{variable})
7842 The @code{copy} attribute applies the set of attributes with which
7843 @var{variable} has been declared to the declaration of the variable
7844 to which the attribute is applied. The attribute is designed for
7845 libraries that define aliases that are expected to specify the same
7846 set of attributes as the aliased symbols. The @code{copy} attribute
7847 can be used with variables, functions or types. However, the kind
7848 of symbol to which the attribute is applied (either varible or
7849 function) must match the kind of symbol to which the argument refers.
7850 The @code{copy} attribute copies only syntactic and semantic attributes
7851 but not attributes that affect a symbol's linkage or visibility such as
7852 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
7853 attribute is also not copied. @xref{Common Function Attributes}.
7854 @xref{Common Type Attributes}.
7856 @cindex @code{deprecated} variable attribute
7858 @itemx deprecated (@var{msg})
7859 The @code{deprecated} attribute results in a warning if the variable
7860 is used anywhere in the source file. This is useful when identifying
7861 variables that are expected to be removed in a future version of a
7862 program. The warning also includes the location of the declaration
7863 of the deprecated variable, to enable users to easily find further
7864 information about why the variable is deprecated, or what they should
7865 do instead. Note that the warning only occurs for uses:
7868 extern int old_var __attribute__ ((deprecated));
7870 int new_fn () @{ return old_var; @}
7874 results in a warning on line 3 but not line 2. The optional @var{msg}
7875 argument, which must be a string, is printed in the warning if
7878 The @code{deprecated} attribute can also be used for functions and
7879 types (@pxref{Common Function Attributes},
7880 @pxref{Common Type Attributes}).
7882 The message attached to the attribute is affected by the setting of
7883 the @option{-fmessage-length} option.
7885 @cindex @code{mode} variable attribute
7886 @item mode (@var{mode})
7887 This attribute specifies the data type for the declaration---whichever
7888 type corresponds to the mode @var{mode}. This in effect lets you
7889 request an integer or floating-point type according to its width.
7891 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
7892 for a list of the possible keywords for @var{mode}.
7893 You may also specify a mode of @code{byte} or @code{__byte__} to
7894 indicate the mode corresponding to a one-byte integer, @code{word} or
7895 @code{__word__} for the mode of a one-word integer, and @code{pointer}
7896 or @code{__pointer__} for the mode used to represent pointers.
7898 @cindex @code{no_icf} variable attribute
7900 This variable attribute prevents a variable from being merged with another
7901 equivalent variable.
7903 @cindex @code{noinit} variable attribute
7905 Any data with the @code{noinit} attribute will not be initialized by
7906 the C runtime startup code, or the program loader. Not initializing
7907 data in this way can reduce program startup times.
7909 This attribute is specific to ELF targets and relies on the linker
7910 script to place sections with the @code{.noinit} prefix in the right
7913 @cindex @code{nonstring} variable attribute
7915 The @code{nonstring} variable attribute specifies that an object or member
7916 declaration with type array of @code{char}, @code{signed char}, or
7917 @code{unsigned char}, or pointer to such a type is intended to store
7918 character arrays that do not necessarily contain a terminating @code{NUL}.
7919 This is useful in detecting uses of such arrays or pointers with functions
7920 that expect @code{NUL}-terminated strings, and to avoid warnings when such
7921 an array or pointer is used as an argument to a bounded string manipulation
7922 function such as @code{strncpy}. For example, without the attribute, GCC
7923 will issue a warning for the @code{strncpy} call below because it may
7924 truncate the copy without appending the terminating @code{NUL} character.
7925 Using the attribute makes it possible to suppress the warning. However,
7926 when the array is declared with the attribute the call to @code{strlen} is
7927 diagnosed because when the array doesn't contain a @code{NUL}-terminated
7928 string the call is undefined. To copy, compare, of search non-string
7929 character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr},
7930 and other functions that operate on arrays of bytes. In addition,
7931 calling @code{strnlen} and @code{strndup} with such arrays is safe
7932 provided a suitable bound is specified, and not diagnosed.
7937 char name [32] __attribute__ ((nonstring));
7940 int f (struct Data *pd, const char *s)
7942 strncpy (pd->name, s, sizeof pd->name);
7944 return strlen (pd->name); // unsafe, gets a warning
7948 @cindex @code{objc_nullability} variable attribute
7949 @item objc_nullability (@var{nullability kind}) @r{(Objective-C and Objective-C++ only)}
7950 This attribute applies to pointer variables only. It allows marking the
7951 pointer with one of four possible values describing the conditions under
7952 which the pointer might have a @code{nil} value. In most cases, the
7953 attribute is intended to be an internal representation for property and
7954 method nullability (specified by language keywords); it is not recommended
7957 When @var{nullability kind} is @code{"unspecified"} or @code{0}, nothing is
7958 known about the conditions in which the pointer might be @code{nil}. Making
7959 this state specific serves to avoid false positives in diagnostics.
7961 When @var{nullability kind} is @code{"nonnull"} or @code{1}, the pointer has
7962 no meaning if it is @code{nil} and thus the compiler is free to emit
7963 diagnostics if it can be determined that the value will be @code{nil}.
7965 When @var{nullability kind} is @code{"nullable"} or @code{2}, the pointer might
7966 be @code{nil} and carry meaning as such.
7968 When @var{nullability kind} is @code{"resettable"} or @code{3} (used only in
7969 the context of property attribute lists) this describes the case in which a
7970 property setter may take the value @code{nil} (which perhaps causes the
7971 property to be reset in some manner to a default) but for which the property
7972 getter will never validly return @code{nil}.
7974 @cindex @code{packed} variable attribute
7976 The @code{packed} attribute specifies that a structure member should have
7977 the smallest possible alignment---one bit for a bit-field and one byte
7978 otherwise, unless a larger value is specified with the @code{aligned}
7979 attribute. The attribute does not apply to non-member objects.
7981 For example in the structure below, the member array @code{x} is packed
7982 so that it immediately follows @code{a} with no intervening padding:
7988 int x[2] __attribute__ ((packed));
7992 @emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
7993 @code{packed} attribute on bit-fields of type @code{char}. This has
7994 been fixed in GCC 4.4 but the change can lead to differences in the
7995 structure layout. See the documentation of
7996 @option{-Wpacked-bitfield-compat} for more information.
7998 @cindex @code{persistent} variable attribute
8000 Any data with the @code{persistent} attribute will not be initialized by
8001 the C runtime startup code, but will be initialized by the program
8002 loader. This enables the value of the variable to @samp{persist}
8003 between processor resets.
8005 This attribute is specific to ELF targets and relies on the linker
8006 script to place the sections with the @code{.persistent} prefix in the
8007 right location. Specifically, some type of non-volatile, writeable
8010 @cindex @code{section} variable attribute
8011 @item section ("@var{section-name}")
8012 Normally, the compiler places the objects it generates in sections like
8013 @code{data} and @code{bss}. Sometimes, however, you need additional sections,
8014 or you need certain particular variables to appear in special sections,
8015 for example to map to special hardware. The @code{section}
8016 attribute specifies that a variable (or function) lives in a particular
8017 section. For example, this small program uses several specific section names:
8020 struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
8021 struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
8022 char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
8023 int init_data __attribute__ ((section ("INITDATA")));
8027 /* @r{Initialize stack pointer} */
8028 init_sp (stack + sizeof (stack));
8030 /* @r{Initialize initialized data} */
8031 memcpy (&init_data, &data, &edata - &data);
8033 /* @r{Turn on the serial ports} */
8040 Use the @code{section} attribute with
8041 @emph{global} variables and not @emph{local} variables,
8042 as shown in the example.
8044 You may use the @code{section} attribute with initialized or
8045 uninitialized global variables but the linker requires
8046 each object be defined once, with the exception that uninitialized
8047 variables tentatively go in the @code{common} (or @code{bss}) section
8048 and can be multiply ``defined''. Using the @code{section} attribute
8049 changes what section the variable goes into and may cause the
8050 linker to issue an error if an uninitialized variable has multiple
8051 definitions. You can force a variable to be initialized with the
8052 @option{-fno-common} flag or the @code{nocommon} attribute.
8054 Some file formats do not support arbitrary sections so the @code{section}
8055 attribute is not available on all platforms.
8056 If you need to map the entire contents of a module to a particular
8057 section, consider using the facilities of the linker instead.
8059 @cindex @code{strict_flex_array} variable attribute
8060 @item strict_flex_array (@var{level})
8061 The @code{strict_flex_array} attribute should be attached to the trailing
8062 array field of a structure. It controls when to treat the trailing array
8063 field of a structure as a flexible array member for the purposes of accessing
8064 the elements of such an array.
8065 @var{level} must be an integer betwen 0 to 3.
8067 @var{level}=0 is the least strict level, all trailing arrays of structures
8068 are treated as flexible array members. @var{level}=3 is the strictest level,
8069 only when the trailing array is declared as a flexible array member per C99
8070 standard onwards (@samp{[]}), it is treated as a flexible array member.
8072 There are two more levels in between 0 and 3, which are provided to
8073 support older codes that use GCC zero-length array extension
8074 (@samp{[0]}) or one-element array as flexible array members
8075 (@samp{[1]}). When @var{level} is 1, the trailing array is treated as
8076 a flexible array member when it is declared as either @samp{[]},
8077 @samp{[0]}, or @samp{[1]}; When @var{level} is 2, the trailing array
8078 is treated as a flexible array member when it is declared as either
8079 @samp{[]}, or @samp{[0]}.
8081 This attribute can be used with or without the
8082 @option{-fstrict-flex-arrays} command-line option. When both the
8083 attribute and the option are present at the same time, the level of
8084 the strictness for the specific trailing array field is determined by
8087 The @code{strict_flex_array} attribute interacts with the
8088 @option{-Wstrict-flex-arrays} option. @xref{Warning Options}, for more
8091 @cindex @code{tls_model} variable attribute
8092 @item tls_model ("@var{tls_model}")
8093 The @code{tls_model} attribute sets thread-local storage model
8094 (@pxref{Thread-Local}) of a particular @code{__thread} variable,
8095 overriding @option{-ftls-model=} command-line switch on a per-variable
8097 The @var{tls_model} argument should be one of @code{global-dynamic},
8098 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
8100 Not all targets support this attribute.
8102 @cindex @code{unavailable} variable attribute
8104 @itemx unavailable (@var{msg})
8105 The @code{unavailable} attribute indicates that the variable so marked
8106 is not available, if it is used anywhere in the source file. It behaves
8107 in the same manner as the @code{deprecated} attribute except that the
8108 compiler will emit an error rather than a warning.
8110 It is expected that items marked as @code{deprecated} will eventually be
8111 withdrawn from interfaces, and then become unavailable. This attribute
8112 allows for marking them appropriately.
8114 The @code{unavailable} attribute can also be used for functions and
8115 types (@pxref{Common Function Attributes},
8116 @pxref{Common Type Attributes}).
8118 @cindex @code{unused} variable attribute
8120 This attribute, attached to a variable or structure field, means that
8121 the variable or field is meant to be possibly unused. GCC does not
8122 produce a warning for this variable or field.
8124 @cindex @code{used} variable attribute
8126 This attribute, attached to a variable with static storage, means that
8127 the variable must be emitted even if it appears that the variable is not
8130 When applied to a static data member of a C++ class template, the
8131 attribute also means that the member is instantiated if the
8132 class itself is instantiated.
8134 @cindex @code{retain} variable attribute
8136 For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
8137 will save the variable from linker garbage collection. To support
8138 this behavior, variables that have not been placed in specific sections
8139 (e.g. by the @code{section} attribute, or the @code{-fdata-sections} option),
8140 will be placed in new, unique sections.
8142 This additional functionality requires Binutils version 2.36 or later.
8144 @cindex @code{uninitialized} variable attribute
8146 This attribute, attached to a variable with automatic storage, means that
8147 the variable should not be automatically initialized by the compiler when
8148 the option @code{-ftrivial-auto-var-init} presents.
8150 With the option @code{-ftrivial-auto-var-init}, all the automatic variables
8151 that do not have explicit initializers will be initialized by the compiler.
8152 These additional compiler initializations might incur run-time overhead,
8153 sometimes dramatically. This attribute can be used to mark some variables
8154 to be excluded from such automatical initialization in order to reduce runtime
8157 This attribute has no effect when the option @code{-ftrivial-auto-var-init}
8160 @cindex @code{vector_size} variable attribute
8161 @item vector_size (@var{bytes})
8162 This attribute specifies the vector size for the type of the declared
8163 variable, measured in bytes. The type to which it applies is known as
8164 the @dfn{base type}. The @var{bytes} argument must be a positive
8165 power-of-two multiple of the base type size. For example, the declaration:
8168 int foo __attribute__ ((vector_size (16)));
8172 causes the compiler to set the mode for @code{foo}, to be 16 bytes,
8173 divided into @code{int} sized units. Assuming a 32-bit @code{int},
8174 @code{foo}'s type is a vector of four units of four bytes each, and
8175 the corresponding mode of @code{foo} is @code{V4SI}.
8176 @xref{Vector Extensions}, for details of manipulating vector variables.
8178 This attribute is only applicable to integral and floating scalars,
8179 although arrays, pointers, and function return values are allowed in
8180 conjunction with this construct.
8182 Aggregates with this attribute are invalid, even if they are of the same
8183 size as a corresponding scalar. For example, the declaration:
8186 struct S @{ int a; @};
8187 struct S __attribute__ ((vector_size (16))) foo;
8191 is invalid even if the size of the structure is the same as the size of
8194 @cindex @code{visibility} variable attribute
8195 @item visibility ("@var{visibility_type}")
8196 This attribute affects the linkage of the declaration to which it is attached.
8197 The @code{visibility} attribute is described in
8198 @ref{Common Function Attributes}.
8200 @cindex @code{warn_if_not_aligned} variable attribute
8201 @item warn_if_not_aligned (@var{alignment})
8202 This attribute specifies a threshold for the structure field, measured
8203 in bytes. If the structure field is aligned below the threshold, a
8204 warning will be issued. For example, the declaration:
8211 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
8216 causes the compiler to issue an warning on @code{struct foo}, like
8217 @samp{warning: alignment 8 of 'struct foo' is less than 16}.
8218 The compiler also issues a warning, like @samp{warning: 'x' offset
8219 8 in 'struct foo' isn't aligned to 16}, when the structure field has
8220 the misaligned offset:
8223 struct __attribute__ ((aligned (16))) foo
8227 unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
8231 This warning can be disabled by @option{-Wno-if-not-aligned}.
8232 The @code{warn_if_not_aligned} attribute can also be used for types
8233 (@pxref{Common Type Attributes}.)
8235 @cindex @code{weak} variable attribute
8237 The @code{weak} attribute is described in
8238 @ref{Common Function Attributes}.
8242 @node ARC Variable Attributes
8243 @subsection ARC Variable Attributes
8246 @cindex @code{aux} variable attribute, ARC
8248 The @code{aux} attribute is used to directly access the ARC's
8249 auxiliary register space from C. The auxilirary register number is
8250 given via attribute argument.
8254 @node AVR Variable Attributes
8255 @subsection AVR Variable Attributes
8258 @cindex @code{progmem} variable attribute, AVR
8260 The @code{progmem} attribute is used on the AVR to place read-only
8261 data in the non-volatile program memory (flash). The @code{progmem}
8262 attribute accomplishes this by putting respective variables into a
8263 section whose name starts with @code{.progmem}.
8265 This attribute works similar to the @code{section} attribute
8266 but adds additional checking.
8269 @item @bullet{} Ordinary AVR cores with 32 general purpose registers:
8270 @code{progmem} affects the location
8271 of the data but not how this data is accessed.
8272 In order to read data located with the @code{progmem} attribute
8273 (inline) assembler must be used.
8275 /* Use custom macros from AVR-LibC */
8276 #include <avr/pgmspace.h>
8278 /* Locate var in flash memory */
8279 const int var[2] PROGMEM = @{ 1, 2 @};
8281 int read_var (int i)
8283 /* Access var[] by accessor macro from avr/pgmspace.h */
8284 return (int) pgm_read_word (& var[i]);
8288 AVR is a Harvard architecture processor and data and read-only data
8289 normally resides in the data memory (RAM).
8291 See also the @ref{AVR Named Address Spaces} section for
8292 an alternate way to locate and access data in flash memory.
8294 @item @bullet{} AVR cores with flash memory visible in the RAM address range:
8295 On such devices, there is no need for attribute @code{progmem} or
8296 @ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all.
8297 Just use standard C / C++. The compiler will generate @code{LD*}
8298 instructions. As flash memory is visible in the RAM address range,
8299 and the default linker script does @emph{not} locate @code{.rodata} in
8300 RAM, no special features are needed in order not to waste RAM for
8301 read-only data or to read from flash. You might even get slightly better
8303 avoiding @code{progmem} and @code{__flash}. This applies to devices from
8304 families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for
8307 @item @bullet{} Reduced AVR Tiny cores like ATtiny40:
8308 The compiler adds @code{0x4000}
8309 to the addresses of objects and declarations in @code{progmem} and locates
8310 the objects in flash memory, namely in section @code{.progmem.data}.
8311 The offset is needed because the flash memory is visible in the RAM
8312 address space starting at address @code{0x4000}.
8314 Data in @code{progmem} can be accessed by means of ordinary C@tie{}code,
8315 no special functions or macros are needed.
8318 /* var is located in flash memory */
8319 extern const int var[2] __attribute__((progmem));
8321 int read_var (int i)
8327 Please notice that on these devices, there is no need for @code{progmem}
8332 @cindex @code{io} variable attribute, AVR
8334 @itemx io (@var{addr})
8335 Variables with the @code{io} attribute are used to address
8336 memory-mapped peripherals in the I/O address range.
8337 No memory is allocated.
8338 If an address is specified, the variable
8339 is assigned that address, and the value is interpreted as an
8340 address in the data address space.
8344 volatile int porta __attribute__((io (__AVR_SFR_OFFSET__ + 0x2)));
8347 Otherwise, the variable is not assigned an address, but the
8348 compiler will still use @code{in} and @code{out} instructions where applicable,
8349 assuming some other module assigns an address in the I/O address range.
8353 extern volatile int porta __attribute__((io));
8356 @cindex @code{io_low} variable attribute, AVR
8358 @itemx io_low (@var{addr})
8359 This is like the @code{io} attribute, but additionally it informs the
8360 compiler that the object lies in the lower half of the I/O area,
8361 allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis}
8364 @cindex @code{address} variable attribute, AVR
8365 @item address (@var{addr})
8366 Variables with the @code{address} attribute can be used to address
8367 memory-mapped peripherals that may lie outside the I/O address range.
8368 Just like with the @code{io} and @code{io_low} attributes, no memory is
8372 volatile int porta __attribute__((address (0x600)));
8375 This attribute can also be used to define symbols in C/C++
8376 code which otherwise would require assembly, a linker description file
8377 or command line options like @code{-Wl,--defsym,a_symbol=@var{value}}.
8380 int a_symbol __attribute__((weak, address (1234)));
8388 @cindex @code{absdata} variable attribute, AVR
8390 Variables in static storage and with the @code{absdata} attribute can
8391 be accessed by the @code{LDS} and @code{STS} instructions which take
8396 This attribute is only supported for the reduced AVR Tiny core
8400 You must make sure that respective data is located in the
8401 address range @code{0x40}@dots{}@code{0xbf} accessible by
8402 @code{LDS} and @code{STS}. One way to achieve this as an
8403 appropriate linker description file.
8406 If the location does not fit the address range of @code{LDS}
8407 and @code{STS}, there is currently (Binutils 2.26) just an unspecific
8410 @code{module.cc:(.text+0x1c): warning: internal error: out of range error}
8415 See also the @option{-mabsdata} @ref{AVR Options,command-line option}.
8419 @node Blackfin Variable Attributes
8420 @subsection Blackfin Variable Attributes
8422 Three attributes are currently defined for the Blackfin.
8425 @cindex @code{l1_data} variable attribute, Blackfin
8426 @cindex @code{l1_data_A} variable attribute, Blackfin
8427 @cindex @code{l1_data_B} variable attribute, Blackfin
8431 Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
8432 Variables with @code{l1_data} attribute are put into the specific section
8433 named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into
8434 the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
8435 attribute are put into the specific section named @code{.l1.data.B}.
8437 @cindex @code{l2} variable attribute, Blackfin
8439 Use this attribute on the Blackfin to place the variable into L2 SRAM.
8440 Variables with @code{l2} attribute are put into the specific section
8441 named @code{.l2.data}.
8444 @node H8/300 Variable Attributes
8445 @subsection H8/300 Variable Attributes
8447 These variable attributes are available for H8/300 targets:
8450 @cindex @code{eightbit_data} variable attribute, H8/300
8451 @cindex eight-bit data on the H8/300, H8/300H, and H8S
8453 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
8454 variable should be placed into the eight-bit data section.
8455 The compiler generates more efficient code for certain operations
8456 on data in the eight-bit data area. Note the eight-bit data area is limited to
8459 You must use GAS and GLD from GNU binutils version 2.7 or later for
8460 this attribute to work correctly.
8462 @cindex @code{tiny_data} variable attribute, H8/300
8463 @cindex tiny data section on the H8/300H and H8S
8465 Use this attribute on the H8/300H and H8S to indicate that the specified
8466 variable should be placed into the tiny data section.
8467 The compiler generates more efficient code for loads and stores
8468 on data in the tiny data section. Note the tiny data area is limited to
8469 slightly under 32KB of data.
8473 @node IA-64 Variable Attributes
8474 @subsection IA-64 Variable Attributes
8476 The IA-64 back end supports the following variable attribute:
8479 @cindex @code{model} variable attribute, IA-64
8480 @item model (@var{model-name})
8482 On IA-64, use this attribute to set the addressability of an object.
8483 At present, the only supported identifier for @var{model-name} is
8484 @code{small}, indicating addressability via ``small'' (22-bit)
8485 addresses (so that their addresses can be loaded with the @code{addl}
8486 instruction). Caveat: such addressing is by definition not position
8487 independent and hence this attribute must not be used for objects
8488 defined by shared libraries.
8492 @node LoongArch Variable Attributes
8493 @subsection LoongArch Variable Attributes
8495 One attribute is currently defined for the LoongArch.
8498 @cindex @code{model} variable attribute, LoongArch
8499 @item model("@var{name}")
8500 Use this attribute on the LoongArch to use a different code model for
8501 addressing this variable, than the code model specified by the global
8502 @option{-mcmodel} option. This attribute is mostly useful if a
8503 @code{section} attribute and/or a linker script will locate this object
8504 specially. Currently the only supported values of @var{name} are
8505 @code{normal} and @code{extreme}.
8508 @node M32R/D Variable Attributes
8509 @subsection M32R/D Variable Attributes
8511 One attribute is currently defined for the M32R/D@.
8514 @cindex @code{model-name} variable attribute, M32R/D
8515 @cindex variable addressability on the M32R/D
8516 @item model (@var{model-name})
8517 Use this attribute on the M32R/D to set the addressability of an object.
8518 The identifier @var{model-name} is one of @code{small}, @code{medium},
8519 or @code{large}, representing each of the code models.
8521 Small model objects live in the lower 16MB of memory (so that their
8522 addresses can be loaded with the @code{ld24} instruction).
8524 Medium and large model objects may live anywhere in the 32-bit address space
8525 (the compiler generates @code{seth/add3} instructions to load their
8529 @node Microsoft Windows Variable Attributes
8530 @subsection Microsoft Windows Variable Attributes
8532 You can use these attributes on Microsoft Windows targets.
8533 @ref{x86 Variable Attributes} for additional Windows compatibility
8534 attributes available on all x86 targets.
8537 @cindex @code{dllimport} variable attribute
8538 @cindex @code{dllexport} variable attribute
8541 The @code{dllimport} and @code{dllexport} attributes are described in
8542 @ref{Microsoft Windows Function Attributes}.
8544 @cindex @code{selectany} variable attribute
8546 The @code{selectany} attribute causes an initialized global variable to
8547 have link-once semantics. When multiple definitions of the variable are
8548 encountered by the linker, the first is selected and the remainder are
8549 discarded. Following usage by the Microsoft compiler, the linker is told
8550 @emph{not} to warn about size or content differences of the multiple
8553 Although the primary usage of this attribute is for POD types, the
8554 attribute can also be applied to global C++ objects that are initialized
8555 by a constructor. In this case, the static initialization and destruction
8556 code for the object is emitted in each translation defining the object,
8557 but the calls to the constructor and destructor are protected by a
8558 link-once guard variable.
8560 The @code{selectany} attribute is only available on Microsoft Windows
8561 targets. You can use @code{__declspec (selectany)} as a synonym for
8562 @code{__attribute__ ((selectany))} for compatibility with other
8565 @cindex @code{shared} variable attribute
8567 On Microsoft Windows, in addition to putting variable definitions in a named
8568 section, the section can also be shared among all running copies of an
8569 executable or DLL@. For example, this small program defines shared data
8570 by putting it in a named section @code{shared} and marking the section
8574 int foo __attribute__((section ("shared"), shared)) = 0;
8579 /* @r{Read and write foo. All running
8580 copies see the same value.} */
8586 You may only use the @code{shared} attribute along with @code{section}
8587 attribute with a fully-initialized global definition because of the way
8588 linkers work. See @code{section} attribute for more information.
8590 The @code{shared} attribute is only available on Microsoft Windows@.
8594 @node MSP430 Variable Attributes
8595 @subsection MSP430 Variable Attributes
8598 @cindex @code{upper} variable attribute, MSP430
8599 @cindex @code{either} variable attribute, MSP430
8602 These attributes are the same as the MSP430 function attributes of the
8603 same name (@pxref{MSP430 Function Attributes}).
8605 @cindex @code{lower} variable attribute, MSP430
8607 This option behaves mostly the same as the MSP430 function attribute of the
8608 same name (@pxref{MSP430 Function Attributes}), but it has some additional
8611 If @option{-mdata-region=}@{@code{upper,either,none}@} has been passed, or
8612 the @code{section} attribute is applied to a variable, the compiler will
8613 generate 430X instructions to handle it. This is because the compiler has
8614 to assume that the variable could get placed in the upper memory region
8615 (above address 0xFFFF). Marking the variable with the @code{lower} attribute
8616 informs the compiler that the variable will be placed in lower memory so it
8617 is safe to use 430 instructions to handle it.
8619 In the case of the @code{section} attribute, the section name given
8620 will be used, and the @code{.lower} prefix will not be added.
8624 @node Nvidia PTX Variable Attributes
8625 @subsection Nvidia PTX Variable Attributes
8627 These variable attributes are supported by the Nvidia PTX back end:
8630 @cindex @code{shared} attribute, Nvidia PTX
8632 Use this attribute to place a variable in the @code{.shared} memory space.
8633 This memory space is private to each cooperative thread array; only threads
8634 within one thread block refer to the same instance of the variable.
8635 The runtime does not initialize variables in this memory space.
8638 @node PowerPC Variable Attributes
8639 @subsection PowerPC Variable Attributes
8641 Three attributes currently are defined for PowerPC configurations:
8642 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
8644 @cindex @code{ms_struct} variable attribute, PowerPC
8645 @cindex @code{gcc_struct} variable attribute, PowerPC
8646 For full documentation of the struct attributes please see the
8647 documentation in @ref{x86 Variable Attributes}.
8649 @cindex @code{altivec} variable attribute, PowerPC
8650 For documentation of @code{altivec} attribute please see the
8651 documentation in @ref{PowerPC Type Attributes}.
8653 @node RL78 Variable Attributes
8654 @subsection RL78 Variable Attributes
8656 @cindex @code{saddr} variable attribute, RL78
8657 The RL78 back end supports the @code{saddr} variable attribute. This
8658 specifies placement of the corresponding variable in the SADDR area,
8659 which can be accessed more efficiently than the default memory region.
8661 @node V850 Variable Attributes
8662 @subsection V850 Variable Attributes
8664 These variable attributes are supported by the V850 back end:
8668 @cindex @code{sda} variable attribute, V850
8670 Use this attribute to explicitly place a variable in the small data area,
8671 which can hold up to 64 kilobytes.
8673 @cindex @code{tda} variable attribute, V850
8675 Use this attribute to explicitly place a variable in the tiny data area,
8676 which can hold up to 256 bytes in total.
8678 @cindex @code{zda} variable attribute, V850
8680 Use this attribute to explicitly place a variable in the first 32 kilobytes
8684 @node x86 Variable Attributes
8685 @subsection x86 Variable Attributes
8687 Two attributes are currently defined for x86 configurations:
8688 @code{ms_struct} and @code{gcc_struct}.
8691 @cindex @code{ms_struct} variable attribute, x86
8692 @cindex @code{gcc_struct} variable attribute, x86
8696 If @code{packed} is used on a structure, or if bit-fields are used,
8697 it may be that the Microsoft ABI lays out the structure differently
8698 than the way GCC normally does. Particularly when moving packed
8699 data between functions compiled with GCC and the native Microsoft compiler
8700 (either via function call or as data in a file), it may be necessary to access
8703 The @code{ms_struct} and @code{gcc_struct} attributes correspond
8704 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
8705 command-line options, respectively;
8706 see @ref{x86 Options}, for details of how structure layout is affected.
8707 @xref{x86 Type Attributes}, for information about the corresponding
8708 attributes on types.
8712 @node Xstormy16 Variable Attributes
8713 @subsection Xstormy16 Variable Attributes
8715 One attribute is currently defined for xstormy16 configurations:
8719 @cindex @code{below100} variable attribute, Xstormy16
8722 If a variable has the @code{below100} attribute (@code{BELOW100} is
8723 allowed also), GCC places the variable in the first 0x100 bytes of
8724 memory and use special opcodes to access it. Such variables are
8725 placed in either the @code{.bss_below100} section or the
8726 @code{.data_below100} section.
8730 @node Type Attributes
8731 @section Specifying Attributes of Types
8732 @cindex attribute of types
8733 @cindex type attributes
8735 You can use attributes to specify various special
8736 properties of types. Some type attributes apply only to structure and
8737 union types, and in C++, also class types, while others can apply to
8738 any type defined via a @code{typedef} declaration. Unless otherwise
8739 specified, the same restrictions and effects apply to attributes regardless
8740 of whether a type is a trivial structure or a C++ class with user-defined
8741 constructors, destructors, or a copy assignment.
8743 Other attributes are defined for functions (@pxref{Function Attributes}),
8744 labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator
8745 Attributes}), statements (@pxref{Statement Attributes}), and for variables
8746 (@pxref{Variable Attributes}).
8748 GCC provides two different ways to specify attributes: the traditional
8749 GNU syntax using @samp{__attribute__ ((...))} annotations, and the
8750 newer standard C and C++ syntax using @samp{[[...]]} with the
8751 @samp{gnu::} prefix on attribute names. Note that the exact rules for
8752 placement of attributes in your source code are different depending on
8753 which syntax you use. @xref{Attribute Syntax}, for details.
8755 You may specify type attributes in an enum, struct or union type
8756 declaration or definition by placing them immediately after the
8757 @code{struct}, @code{union} or @code{enum} keyword. You can also place
8758 them just past the closing curly brace of the definition, but this is less
8759 preferred because logically the type should be fully defined at
8760 the closing brace. You can also include type attributes in a
8761 @code{typedef} declaration.
8764 * Common Type Attributes::
8765 * ARC Type Attributes::
8766 * ARM Type Attributes::
8767 * BPF Type Attributes::
8768 * PowerPC Type Attributes::
8769 * x86 Type Attributes::
8772 @node Common Type Attributes
8773 @subsection Common Type Attributes
8775 The following type attributes are supported on most targets.
8778 @c Keep this table alphabetized by attribute name. Treat _ as space.
8780 @cindex @code{aligned} type attribute
8782 @itemx aligned (@var{alignment})
8783 The @code{aligned} attribute specifies a minimum alignment (in bytes) for
8784 variables of the specified type. When specified, @var{alignment} must be
8785 a power of 2. Specifying no @var{alignment} argument implies the maximum
8786 alignment for the target, which is often, but by no means always, 8 or 16
8787 bytes. For example, the declarations:
8790 struct __attribute__ ((aligned (8))) S @{ short f[3]; @};
8791 typedef int more_aligned_int __attribute__ ((aligned (8)));
8795 force the compiler to ensure (as far as it can) that each variable whose
8796 type is @code{struct S} or @code{more_aligned_int} is allocated and
8797 aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all
8798 variables of type @code{struct S} aligned to 8-byte boundaries allows
8799 the compiler to use the @code{ldd} and @code{std} (doubleword load and
8800 store) instructions when copying one variable of type @code{struct S} to
8801 another, thus improving run-time efficiency.
8803 Note that the alignment of any given @code{struct} or @code{union} type
8804 is required by the ISO C standard to be at least a perfect multiple of
8805 the lowest common multiple of the alignments of all of the members of
8806 the @code{struct} or @code{union} in question. This means that you @emph{can}
8807 effectively adjust the alignment of a @code{struct} or @code{union}
8808 type by attaching an @code{aligned} attribute to any one of the members
8809 of such a type, but the notation illustrated in the example above is a
8810 more obvious, intuitive, and readable way to request the compiler to
8811 adjust the alignment of an entire @code{struct} or @code{union} type.
8813 As in the preceding example, you can explicitly specify the alignment
8814 (in bytes) that you wish the compiler to use for a given @code{struct}
8815 or @code{union} type. Alternatively, you can leave out the alignment factor
8816 and just ask the compiler to align a type to the maximum
8817 useful alignment for the target machine you are compiling for. For
8818 example, you could write:
8821 struct __attribute__ ((aligned)) S @{ short f[3]; @};
8824 Whenever you leave out the alignment factor in an @code{aligned}
8825 attribute specification, the compiler automatically sets the alignment
8826 for the type to the largest alignment that is ever used for any data
8827 type on the target machine you are compiling for. Doing this can often
8828 make copy operations more efficient, because the compiler can use
8829 whatever instructions copy the biggest chunks of memory when performing
8830 copies to or from the variables that have types that you have aligned
8833 In the example above, if the size of each @code{short} is 2 bytes, then
8834 the size of the entire @code{struct S} type is 6 bytes. The smallest
8835 power of two that is greater than or equal to that is 8, so the
8836 compiler sets the alignment for the entire @code{struct S} type to 8
8839 Note that although you can ask the compiler to select a time-efficient
8840 alignment for a given type and then declare only individual stand-alone
8841 objects of that type, the compiler's ability to select a time-efficient
8842 alignment is primarily useful only when you plan to create arrays of
8843 variables having the relevant (efficiently aligned) type. If you
8844 declare or use arrays of variables of an efficiently-aligned type, then
8845 it is likely that your program also does pointer arithmetic (or
8846 subscripting, which amounts to the same thing) on pointers to the
8847 relevant type, and the code that the compiler generates for these
8848 pointer arithmetic operations is often more efficient for
8849 efficiently-aligned types than for other types.
8851 Note that the effectiveness of @code{aligned} attributes may be limited
8852 by inherent limitations in your linker. On many systems, the linker is
8853 only able to arrange for variables to be aligned up to a certain maximum
8854 alignment. (For some linkers, the maximum supported alignment may
8855 be very very small.) If your linker is only able to align variables
8856 up to a maximum of 8-byte alignment, then specifying @code{aligned (16)}
8857 in an @code{__attribute__} still only provides you with 8-byte
8858 alignment. See your linker documentation for further information.
8860 When used on a struct, or struct member, the @code{aligned} attribute can
8861 only increase the alignment; in order to decrease it, the @code{packed}
8862 attribute must be specified as well. When used as part of a typedef, the
8863 @code{aligned} attribute can both increase and decrease alignment, and
8864 specifying the @code{packed} attribute generates a warning.
8866 @cindex @code{alloc_size} type attribute
8867 @item alloc_size (@var{position})
8868 @itemx alloc_size (@var{position-1}, @var{position-2})
8869 The @code{alloc_size} type attribute may be applied to the definition
8870 of a type of a function that returns a pointer and takes at least one
8871 argument of an integer type. It indicates that the returned pointer
8872 points to an object whose size is given by the function argument at
8873 @var{position-1}, or by the product of the arguments at @var{position-1}
8874 and @var{position-2}. Meaningful sizes are positive values less than
8875 @code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses
8876 this information to improve the results of @code{__builtin_object_size}.
8878 For instance, the following declarations
8881 typedef __attribute__ ((alloc_size (1, 2))) void*
8882 calloc_type (size_t, size_t);
8883 typedef __attribute__ ((alloc_size (1))) void*
8884 malloc_type (size_t);
8888 specify that @code{calloc_type} is a type of a function that, like
8889 the standard C function @code{calloc}, returns an object whose size
8890 is given by the product of arguments 1 and 2, and that
8891 @code{malloc_type}, like the standard C function @code{malloc},
8892 returns an object whose size is given by argument 1 to the function.
8894 @cindex @code{copy} type attribute
8896 @itemx copy (@var{expression})
8897 The @code{copy} attribute applies the set of attributes with which
8898 the type of the @var{expression} has been declared to the declaration
8899 of the type to which the attribute is applied. The attribute is
8900 designed for libraries that define aliases that are expected to
8901 specify the same set of attributes as the aliased symbols.
8902 The @code{copy} attribute can be used with types, variables, or
8903 functions. However, the kind of symbol to which the attribute is
8904 applied (either varible or function) must match the kind of symbol
8905 to which the argument refers.
8906 The @code{copy} attribute copies only syntactic and semantic attributes
8907 but not attributes that affect a symbol's linkage or visibility such as
8908 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
8909 attribute is also not copied. @xref{Common Function Attributes}.
8910 @xref{Common Variable Attributes}.
8912 For example, suppose @code{struct A} below is defined in some third
8913 party library header to have the alignment requirement @code{N} and
8914 to force a warning whenever a variable of the type is not so aligned
8915 due to attribute @code{packed}. Specifying the @code{copy} attribute
8916 on the definition on the unrelated @code{struct B} has the effect of
8917 copying all relevant attributes from the type referenced by the pointer
8918 expression to @code{struct B}.
8921 struct __attribute__ ((aligned (N), warn_if_not_aligned (N)))
8922 A @{ /* @r{@dots{}} */ @};
8923 struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @};
8926 @cindex @code{deprecated} type attribute
8928 @itemx deprecated (@var{msg})
8929 The @code{deprecated} attribute results in a warning if the type
8930 is used anywhere in the source file. This is useful when identifying
8931 types that are expected to be removed in a future version of a program.
8932 If possible, the warning also includes the location of the declaration
8933 of the deprecated type, to enable users to easily find further
8934 information about why the type is deprecated, or what they should do
8935 instead. Note that the warnings only occur for uses and then only
8936 if the type is being applied to an identifier that itself is not being
8937 declared as deprecated.
8940 typedef int T1 __attribute__ ((deprecated));
8944 typedef T1 T3 __attribute__ ((deprecated));
8945 T3 z __attribute__ ((deprecated));
8949 results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
8950 warning is issued for line 4 because T2 is not explicitly
8951 deprecated. Line 5 has no warning because T3 is explicitly
8952 deprecated. Similarly for line 6. The optional @var{msg}
8953 argument, which must be a string, is printed in the warning if
8954 present. Control characters in the string will be replaced with
8955 escape sequences, and if the @option{-fmessage-length} option is set
8956 to 0 (its default value) then any newline characters will be ignored.
8958 The @code{deprecated} attribute can also be used for functions and
8959 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
8961 The message attached to the attribute is affected by the setting of
8962 the @option{-fmessage-length} option.
8964 @cindex @code{designated_init} type attribute
8965 @item designated_init
8966 This attribute may only be applied to structure types. It indicates
8967 that any initialization of an object of this type must use designated
8968 initializers rather than positional initializers. The intent of this
8969 attribute is to allow the programmer to indicate that a structure's
8970 layout may change, and that therefore relying on positional
8971 initialization will result in future breakage.
8973 GCC emits warnings based on this attribute by default; use
8974 @option{-Wno-designated-init} to suppress them.
8976 @cindex @code{hardbool} type attribute
8978 @itemx hardbool (@var{false_value})
8979 @itemx hardbool (@var{false_value}, @var{true_value})
8980 This attribute may only be applied to integral types in C, to introduce
8981 hardened boolean types. It turns the integral type into a boolean-like
8982 type with the same size and precision, that uses the specified values as
8983 representations for @code{false} and @code{true}. Underneath, it is
8984 actually an enumerated type, but its observable behavior is like that of
8985 @code{_Bool}, except for the strict internal representations, verified
8988 If @var{true_value} is omitted, the bitwise negation of
8989 @var{false_value} is used. If @var{false_value} is omitted, zero is
8990 used. The named representation values must be different when converted
8991 to the original integral type. Narrower bitfields are rejected if the
8992 representations become indistinguishable.
8994 Values of such types automatically decay to @code{_Bool}, at which
8995 point, the selected representation values are mapped to the
8996 corresponding @code{_Bool} values. When the represented value is not
8997 determined, at compile time, to be either @var{false_value} or
8998 @var{true_value}, runtime verification calls @code{__builtin_trap} if it
8999 is neither. This is what makes them hardened boolean types.
9001 When converting scalar types to such hardened boolean types, implicitly
9002 or explicitly, behavior corresponds to a conversion to @code{_Bool},
9003 followed by a mapping from @code{false} and @code{true} to
9004 @var{false_value} and @var{true_value}, respectively.
9007 typedef char __attribute__ ((__hardbool__ (0x5a))) hbool;
9008 hbool first = 0; /* False, stored as (char)0x5a. */
9009 hbool second = !first; /* True, stored as ~(char)0x5a. */
9011 static hbool zeroinit; /* False, stored as (char)0x5a. */
9012 auto hbool uninit; /* Undefined, may trap. */
9015 When zero-initializing a variable or field of hardened boolean type
9016 (presumably held in static storage) the implied zero initializer gets
9017 converted to @code{_Bool}, and then to the hardened boolean type, so
9018 that the initial value is the hardened representation for @code{false}.
9019 Using that value is well defined. This is @emph{not} the case when
9020 variables and fields of such types are uninitialized (presumably held in
9021 automatic or dynamic storage): their values are indeterminate, and using
9022 them invokes undefined behavior. Using them may trap or not, depending
9023 on the bits held in the storage (re)used for the variable, if any, and
9024 on optimizations the compiler may perform on the grounds that using
9025 uninitialized values invokes undefined behavior.
9027 Users of @option{-ftrivial-auto-var-init} should be aware that the bit
9028 patterns used as initializers are @emph{not} converted to
9029 @code{hardbool} types, so using a @code{hardbool} variable that is
9030 implicitly initialized by the @option{-ftrivial-auto-var-init} may trap
9031 if the representations values chosen for @code{false} and @code{true} do
9032 not match the initializer.
9034 Since this is a language extension only available in C, interoperation
9035 with other languages may pose difficulties. It should interoperate with
9036 Ada Booleans defined with the same size and equivalent representation
9037 clauses, and with enumerations or other languages' integral types that
9038 correspond to C's chosen integral type.
9041 @cindex @code{may_alias} type attribute
9043 Accesses through pointers to types with this attribute are not subject
9044 to type-based alias analysis, but are instead assumed to be able to alias
9045 any other type of objects.
9046 In the context of section 6.5 paragraph 7 of the C99 standard,
9047 an lvalue expression
9048 dereferencing such a pointer is treated like having a character type.
9049 See @option{-fstrict-aliasing} for more information on aliasing issues.
9050 This extension exists to support some vector APIs, in which pointers to
9051 one vector type are permitted to alias pointers to a different vector type.
9053 Note that an object of a type with this attribute does not have any
9059 typedef short __attribute__ ((__may_alias__)) short_a;
9065 short_a *b = (short_a *) &a;
9069 if (a == 0x12345678)
9077 If you replaced @code{short_a} with @code{short} in the variable
9078 declaration, the above program would abort when compiled with
9079 @option{-fstrict-aliasing}, which is on by default at @option{-O2} or
9082 @cindex @code{mode} type attribute
9083 @item mode (@var{mode})
9084 This attribute specifies the data type for the declaration---whichever
9085 type corresponds to the mode @var{mode}. This in effect lets you
9086 request an integer or floating-point type according to its width.
9088 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
9089 for a list of the possible keywords for @var{mode}.
9090 You may also specify a mode of @code{byte} or @code{__byte__} to
9091 indicate the mode corresponding to a one-byte integer, @code{word} or
9092 @code{__word__} for the mode of a one-word integer, and @code{pointer}
9093 or @code{__pointer__} for the mode used to represent pointers.
9095 @cindex @code{objc_root_class} type attribute
9096 @item objc_root_class @r{(Objective-C and Objective-C++ only)}
9097 This attribute marks a class as being a root class, and thus allows
9098 the compiler to elide any warnings about a missing superclass and to
9099 make additional checks for mandatory methods as needed.
9101 @cindex @code{packed} type attribute
9103 This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class}
9104 type definition, specifies that each of its members (other than zero-width
9105 bit-fields) is placed to minimize the memory required. This is equivalent
9106 to specifying the @code{packed} attribute on each of the members.
9108 @opindex fshort-enums
9109 When attached to an @code{enum} definition, the @code{packed} attribute
9110 indicates that the smallest integral type should be used.
9111 Specifying the @option{-fshort-enums} flag on the command line
9112 is equivalent to specifying the @code{packed}
9113 attribute on all @code{enum} definitions.
9115 In the following example @code{struct my_packed_struct}'s members are
9116 packed closely together, but the internal layout of its @code{s} member
9117 is not packed---to do that, @code{struct my_unpacked_struct} needs to
9121 struct my_unpacked_struct
9127 struct __attribute__ ((__packed__)) my_packed_struct
9131 struct my_unpacked_struct s;
9135 You may only specify the @code{packed} attribute on the definition
9136 of an @code{enum}, @code{struct}, @code{union}, or @code{class},
9137 not on a @code{typedef} that does not also define the enumerated type,
9138 structure, union, or class.
9140 @cindex @code{scalar_storage_order} type attribute
9141 @item scalar_storage_order ("@var{endianness}")
9142 When attached to a @code{union} or a @code{struct}, this attribute sets
9143 the storage order, aka endianness, of the scalar fields of the type, as
9144 well as the array fields whose component is scalar. The supported
9145 endiannesses are @code{big-endian} and @code{little-endian}. The attribute
9146 has no effects on fields which are themselves a @code{union}, a @code{struct}
9147 or an array whose component is a @code{union} or a @code{struct}, and it is
9148 possible for these fields to have a different scalar storage order than the
9151 Note that neither pointer nor vector fields are considered scalar fields in
9152 this context, so the attribute has no effects on these fields.
9154 This attribute is supported only for targets that use a uniform default
9155 scalar storage order (fortunately, most of them), i.e.@: targets that store
9156 the scalars either all in big-endian or all in little-endian.
9158 Additional restrictions are enforced for types with the reverse scalar
9159 storage order with regard to the scalar storage order of the target:
9162 @item Taking the address of a scalar field of a @code{union} or a
9163 @code{struct} with reverse scalar storage order is not permitted and yields
9165 @item Taking the address of an array field, whose component is scalar, of
9166 a @code{union} or a @code{struct} with reverse scalar storage order is
9167 permitted but yields a warning, unless @option{-Wno-scalar-storage-order}
9169 @item Taking the address of a @code{union} or a @code{struct} with reverse
9170 scalar storage order is permitted.
9173 These restrictions exist because the storage order attribute is lost when
9174 the address of a scalar or the address of an array with scalar component is
9175 taken, so storing indirectly through this address generally does not work.
9176 The second case is nevertheless allowed to be able to perform a block copy
9177 from or to the array.
9179 Moreover, the use of type punning or aliasing to toggle the storage order
9180 is not supported; that is to say, if a given scalar object can be accessed
9181 through distinct types that assign a different storage order to it, then the
9182 behavior is undefined.
9184 @cindex @code{strub} type attribute
9186 This attribute defines stack-scrubbing properties of functions and
9187 variables, so that functions that access sensitive data can have their
9188 stack frames zeroed-out upon returning or propagating exceptions. This
9189 may be enabled explicitly, by selecting certain @code{strub} modes for
9190 specific functions, or implicitly, by means of @code{strub} variables.
9192 Being a type attribute, it attaches to types, even when specified in
9193 function and variable declarations. When applied to function types, it
9194 takes an optional string argument. When applied to a
9195 pointer-to-function type, if the optional argument is given, it gets
9196 propagated to the function type.
9199 /* A strub variable. */
9200 int __attribute__ ((strub)) var;
9201 /* A strub variable that happens to be a pointer. */
9202 __attribute__ ((strub)) int *strub_ptr_to_int;
9203 /* A pointer type that may point to a strub variable. */
9204 typedef int __attribute__ ((strub)) *ptr_to_strub_int_type;
9206 /* A declaration of a strub function. */
9207 extern int __attribute__ ((strub)) foo (void);
9208 /* A pointer to that strub function. */
9209 int __attribute__ ((strub ("at-calls"))) (*ptr_to_strub_fn)(void) = foo;
9212 A function associated with @code{at-calls} @code{strub} mode
9213 (@code{strub("at-calls")}, or just @code{strub}) undergoes interface
9214 changes. Its callers are adjusted to match the changes, and to scrub
9215 (overwrite with zeros) the stack space used by the called function after
9216 it returns. The interface change makes the function type incompatible
9217 with an unadorned but otherwise equivalent type, so @emph{every}
9218 declaration and every type that may be used to call the function must be
9219 associated with this strub mode.
9221 A function associated with @code{internal} @code{strub} mode
9222 (@code{strub("internal")}) retains an unmodified, type-compatible
9223 interface, but it may be turned into a wrapper that calls the wrapped
9224 body using a custom interface. The wrapper then scrubs the stack space
9225 used by the wrapped body. Though the wrapped body has its stack space
9226 scrubbed, the wrapper does not, so arguments and return values may
9227 remain unscrubbed even when such a function is called by another
9228 function that enables @code{strub}. This is why, when compiling with
9229 @option{-fstrub=strict}, a @code{strub} context is not allowed to call
9230 @code{internal} @code{strub} functions.
9233 /* A declaration of an internal-strub function. */
9234 extern int __attribute__ ((strub ("internal"))) bar (void);
9236 int __attribute__ ((strub))
9239 /* Ok, foo was declared above as an at-calls strub function. */
9241 /* Not allowed in strict mode, otherwise allowed. */
9246 An automatically-allocated variable associated with the @code{strub}
9247 attribute causes the (immediately) enclosing function to have
9248 @code{strub} enabled.
9250 A statically-allocated variable associated with the @code{strub}
9251 attribute causes functions that @emph{read} it, through its @code{strub}
9252 data type, to have @code{strub} enabled. Reading data by dereferencing
9253 a pointer to a @code{strub} data type has the same effect. Note: The
9254 attribute does not carry over from a composite type to the types of its
9255 components, so the intended effect may not be obtained with non-scalar
9258 When selecting a @code{strub}-enabled mode for a function that is not
9259 explicitly associated with one, because of @code{strub} variables or
9260 data pointers, the function must satisfy @code{internal} mode viability
9261 requirements (see below), even when @code{at-calls} mode is also viable
9262 and, being more efficient, ends up selected as an optimization.
9265 /* zapme is implicitly strub-enabled because of strub variables.
9266 Optimization may change its strub mode, but not the requirements. */
9270 /* A local strub variable enables strub. */
9271 int __attribute__ ((strub)) lvar;
9272 /* Reading strub data through a pointer-to-strub enables strub. */
9273 lvar = * (ptr_to_strub_int_type) &i;
9274 /* Writing to a global strub variable does not enable strub. */
9276 /* Reading from a global strub variable enables strub. */
9281 A @code{strub} context is the body (as opposed to the interface) of a
9282 function that has @code{strub} enabled, be it explicitly, by
9283 @code{at-calls} or @code{internal} mode, or implicitly, due to
9284 @code{strub} variables or command-line options.
9286 A function of a type associated with the @code{disabled} @code{strub}
9287 mode (@code{strub("disabled")} will not have its own stack space
9288 scrubbed. Such functions @emph{cannot} be called from within
9289 @code{strub} contexts.
9291 In order to enable a function to be called from within @code{strub}
9292 contexts without having its stack space scrubbed, associate it with the
9293 @code{callable} @code{strub} mode (@code{strub("callable")}).
9295 When a function is not assigned a @code{strub} mode, explicitly or
9296 implicitly, the mode defaults to @code{callable}, except when compiling
9297 with @option{-fstrub=strict}, that causes @code{strub} mode to default
9301 extern int __attribute__ ((strub ("callable"))) bac (void);
9302 extern int __attribute__ ((strub ("disabled"))) bad (void);
9303 /* Implicitly disabled with -fstrub=strict, otherwise callable. */
9304 extern int bah (void);
9306 int __attribute__ ((strub))
9309 /* Not allowed, bad is not strub-callable. */
9311 /* Ok, bac is strub-callable. */
9313 /* Not allowed with -fstrub=strict, otherwise allowed. */
9318 Function types marked @code{callable} and @code{disabled} are not
9319 mutually compatible types, but the underlying interfaces are compatible,
9320 so it is safe to convert pointers between them, and to use such pointers
9321 or alternate declarations to call them. Interfaces are also
9322 interchangeable between them and @code{internal} (but not
9323 @code{at-calls}!), but adding @code{internal} to a pointer type will not
9324 cause the pointed-to function to perform stack scrubbing.
9327 void __attribute__ ((strub))
9330 /* Assign a callable function to pointer-to-disabled.
9331 Flagged as not quite compatible with -Wpedantic. */
9332 int __attribute__ ((strub ("disabled"))) (*d_p) (void) = bac;
9333 /* Not allowed: calls disabled type in a strub context. */
9336 /* Assign a disabled function to pointer-to-callable.
9337 Flagged as not quite compatible with -Wpedantic. */
9338 int __attribute__ ((strub ("callable"))) (*c_p) (void) = bad;
9342 /* Assign an internal function to pointer-to-callable.
9343 Flagged as not quite compatible with -Wpedantic. */
9348 /* Assign an at-calls function to pointer-to-callable.
9349 Flaggged as incompatible. */
9351 /* The call through an interface-incompatible type will not use the
9352 modified interface expected by the at-calls function, so it is
9353 likely to misbehave at runtime. */
9358 @code{Strub} contexts are never inlined into non-@code{strub} contexts.
9359 When an @code{internal}-strub function is split up, the wrapper can
9360 often be inlined, but the wrapped body @emph{never} is. A function
9361 marked as @code{always_inline}, even if explicitly assigned
9362 @code{internal} strub mode, will not undergo wrapping, so its body gets
9363 inlined as required.
9366 inline int __attribute__ ((strub ("at-calls")))
9369 /* This body may get inlined into strub contexts. */
9372 inline int __attribute__ ((strub ("internal")))
9375 /* This body NEVER gets inlined, though its wrapper may. */
9378 inline int __attribute__ ((strub ("internal"), always_inline))
9381 /* No internal wrapper, so this body ALWAYS gets inlined,
9382 but it cannot be called from non-strub contexts. */
9385 void __attribute__ ((strub ("disabled")))
9388 /* Not allowed, cannot inline into a non-strub context. */
9393 @cindex strub eligibility and viability
9394 Some @option{-fstrub=*} command line options enable @code{strub} modes
9395 implicitly where viable. A @code{strub} mode is only viable for a
9396 function if the function is eligible for that mode, and if other
9397 conditions, detailed below, are satisfied. If it's not eligible for a
9398 mode, attempts to explicitly associate it with that mode are rejected
9399 with an error message. If it is eligible, that mode may be assigned
9400 explicitly through this attribute, but implicit assignment through
9401 command-line options may involve additional viability requirements.
9403 A function is ineligible for @code{at-calls} @code{strub} mode if a
9404 different @code{strub} mode is explicitly requested, if attribute
9405 @code{noipa} is present, or if it calls @code{__builtin_apply_args}.
9406 @code{At-calls} @code{strub} mode, if not requested through the function
9407 type, is only viable for an eligible function if the function is not
9408 visible to other translation units, if it doesn't have its address
9409 taken, and if it is never called with a function type overrider.
9412 /* bar is eligible for at-calls strub mode,
9413 but not viable for that mode because it is visible to other units.
9414 It is eligible and viable for internal strub mode. */
9417 /* setp is eligible for at-calls strub mode,
9418 but not viable for that mode because its address is taken.
9419 It is eligible and viable for internal strub mode. */
9420 void setp (void) @{ static void (*p)(void); = setp; @}
9423 A function is ineligible for @code{internal} @code{strub} mode if a
9424 different @code{strub} mode is explicitly requested, or if attribute
9425 @code{noipa} is present. For an @code{always_inline} function, meeting
9426 these requirements is enough to make it eligible. Any function that has
9427 attribute @code{noclone}, that uses such extensions as non-local labels,
9428 computed gotos, alternate variable argument passing interfaces,
9429 @code{__builtin_next_arg}, or @code{__builtin_return_address}, or that
9430 takes too many (about 64Ki) arguments is ineligible, unless it is
9431 @code{always_inline}. For @code{internal} @code{strub} mode, all
9432 eligible functions are viable.
9435 /* flop is not eligible, thus not viable, for at-calls strub mode.
9436 Likewise for internal strub mode. */
9437 __attribute__ ((noipa)) void flop (void) @{@}
9439 /* flip is eligible and viable for at-calls strub mode.
9440 It would be ineligible for internal strub mode, because of noclone,
9441 if it weren't for always_inline. With always_inline, noclone is not
9442 an obstacle, so it is also eligible and viable for internal strub mode. */
9443 inline __attribute__ ((noclone, always_inline)) void flip (void) @{@}
9446 @cindex @code{transparent_union} type attribute
9447 @item transparent_union
9449 This attribute, attached to a @code{union} type definition, indicates
9450 that any function parameter having that union type causes calls to that
9451 function to be treated in a special way.
9453 First, the argument corresponding to a transparent union type can be of
9454 any type in the union; no cast is required. Also, if the union contains
9455 a pointer type, the corresponding argument can be a null pointer
9456 constant or a void pointer expression; and if the union contains a void
9457 pointer type, the corresponding argument can be any pointer expression.
9458 If the union member type is a pointer, qualifiers like @code{const} on
9459 the referenced type must be respected, just as with normal pointer
9462 Second, the argument is passed to the function using the calling
9463 conventions of the first member of the transparent union, not the calling
9464 conventions of the union itself. All members of the union must have the
9465 same machine representation; this is necessary for this argument passing
9468 Transparent unions are designed for library functions that have multiple
9469 interfaces for compatibility reasons. For example, suppose the
9470 @code{wait} function must accept either a value of type @code{int *} to
9471 comply with POSIX, or a value of type @code{union wait *} to comply with
9472 the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
9473 @code{wait} would accept both kinds of arguments, but it would also
9474 accept any other pointer type and this would make argument type checking
9475 less useful. Instead, @code{<sys/wait.h>} might define the interface
9479 typedef union __attribute__ ((__transparent_union__))
9483 @} wait_status_ptr_t;
9485 pid_t wait (wait_status_ptr_t);
9489 This interface allows either @code{int *} or @code{union wait *}
9490 arguments to be passed, using the @code{int *} calling convention.
9491 The program can call @code{wait} with arguments of either type:
9494 int w1 () @{ int w; return wait (&w); @}
9495 int w2 () @{ union wait w; return wait (&w); @}
9499 With this interface, @code{wait}'s implementation might look like this:
9502 pid_t wait (wait_status_ptr_t p)
9504 return waitpid (-1, p.__ip, 0);
9508 @cindex @code{unavailable} type attribute
9510 @itemx unavailable (@var{msg})
9511 The @code{unavailable} attribute behaves in the same manner as the
9512 @code{deprecated} one, but emits an error rather than a warning. It is
9513 used to indicate that a (perhaps previously @code{deprecated}) type is
9516 The @code{unavailable} attribute can also be used for functions and
9517 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
9519 @cindex @code{unused} type attribute
9521 When attached to a type (including a @code{union} or a @code{struct}),
9522 this attribute means that variables of that type are meant to appear
9523 possibly unused. GCC does not produce a warning for any variables of
9524 that type, even if the variable appears to do nothing. This is often
9525 the case with lock or thread classes, which are usually defined and then
9526 not referenced, but contain constructors and destructors that have
9527 nontrivial bookkeeping functions.
9529 @cindex @code{vector_size} type attribute
9530 @item vector_size (@var{bytes})
9531 This attribute specifies the vector size for the type, measured in bytes.
9532 The type to which it applies is known as the @dfn{base type}. The @var{bytes}
9533 argument must be a positive power-of-two multiple of the base type size. For
9534 example, the following declarations:
9537 typedef __attribute__ ((vector_size (32))) int int_vec32_t ;
9538 typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t;
9539 typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3];
9543 define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int}
9544 sized units. With @code{int} having a size of 4 bytes, the type defines
9545 a vector of eight units, four bytes each. The mode of variables of type
9546 @code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined
9547 to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be
9548 an array of three such vectors. @xref{Vector Extensions}, for details of
9549 manipulating objects of vector types.
9551 This attribute is only applicable to integral and floating scalar types.
9552 In function declarations the attribute applies to the function return
9555 For example, the following:
9557 __attribute__ ((vector_size (16))) float get_flt_vec16 (void);
9559 declares @code{get_flt_vec16} to be a function returning a 16-byte vector
9560 with the base type @code{float}.
9562 @cindex @code{visibility} type attribute
9564 In C++, attribute visibility (@pxref{Function Attributes}) can also be
9565 applied to class, struct, union and enum types. Unlike other type
9566 attributes, the attribute must appear between the initial keyword and
9567 the name of the type; it cannot appear after the body of the type.
9569 Note that the type visibility is applied to vague linkage entities
9570 associated with the class (vtable, typeinfo node, etc.). In
9571 particular, if a class is thrown as an exception in one shared object
9572 and caught in another, the class must have default visibility.
9573 Otherwise the two shared objects are unable to use the same
9574 typeinfo node and exception handling will break.
9576 @cindex @code{warn_if_not_aligned} type attribute
9577 @item warn_if_not_aligned (@var{alignment})
9578 This attribute specifies a threshold for the structure field, measured
9579 in bytes. If the structure field is aligned below the threshold, a
9580 warning will be issued. For example, the declaration:
9583 typedef unsigned long long __u64
9584 __attribute__((aligned (4), warn_if_not_aligned (8)));
9595 causes the compiler to issue an warning on @code{struct foo}, like
9596 @samp{warning: alignment 4 of 'struct foo' is less than 8}.
9597 It is used to define @code{struct foo} in such a way that
9598 @code{struct foo} has the same layout and the structure field @code{x}
9599 has the same alignment when @code{__u64} is aligned at either 4 or
9600 8 bytes. Align @code{struct foo} to 8 bytes:
9603 struct __attribute__ ((aligned (8))) foo
9612 silences the warning. The compiler also issues a warning, like
9613 @samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8},
9614 when the structure field has the misaligned offset:
9617 struct __attribute__ ((aligned (8))) foo
9626 This warning can be disabled by @option{-Wno-if-not-aligned}.
9630 To specify multiple attributes, separate them by commas within the
9631 double parentheses: for example, @samp{__attribute__ ((aligned (16),
9634 @node ARC Type Attributes
9635 @subsection ARC Type Attributes
9637 @cindex @code{uncached} type attribute, ARC
9638 Declaring objects with @code{uncached} allows you to exclude
9639 data-cache participation in load and store operations on those objects
9640 without involving the additional semantic implications of
9641 @code{volatile}. The @code{.di} instruction suffix is used for all
9642 loads and stores of data declared @code{uncached}.
9644 @node ARM Type Attributes
9645 @subsection ARM Type Attributes
9647 @cindex @code{notshared} type attribute, ARM
9648 On those ARM targets that support @code{dllimport} (such as Symbian
9649 OS), you can use the @code{notshared} attribute to indicate that the
9650 virtual table and other similar data for a class should not be
9651 exported from a DLL@. For example:
9654 class __declspec(notshared) C @{
9656 __declspec(dllimport) C();
9660 __declspec(dllexport)
9665 In this code, @code{C::C} is exported from the current DLL, but the
9666 virtual table for @code{C} is not exported. (You can use
9667 @code{__attribute__} instead of @code{__declspec} if you prefer, but
9668 most Symbian OS code uses @code{__declspec}.)
9670 @node BPF Type Attributes
9671 @subsection BPF Type Attributes
9673 @cindex @code{preserve_access_index} type attribute, BPF
9674 BPF Compile Once - Run Everywhere (CO-RE) support. When attached to a
9675 @code{struct} or @code{union} type definition, indicates that CO-RE
9676 relocation information should be generated for any access to a variable
9677 of that type. The behavior is equivalent to the programmer manually
9678 wrapping every such access with @code{__builtin_preserve_access_index}.
9681 @node PowerPC Type Attributes
9682 @subsection PowerPC Type Attributes
9684 Three attributes currently are defined for PowerPC configurations:
9685 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
9687 @cindex @code{ms_struct} type attribute, PowerPC
9688 @cindex @code{gcc_struct} type attribute, PowerPC
9689 For full documentation of the @code{ms_struct} and @code{gcc_struct}
9690 attributes please see the documentation in @ref{x86 Type Attributes}.
9692 @cindex @code{altivec} type attribute, PowerPC
9693 The @code{altivec} attribute allows one to declare AltiVec vector data
9694 types supported by the AltiVec Programming Interface Manual. The
9695 attribute requires an argument to specify one of three vector types:
9696 @code{vector__}, @code{pixel__} (always followed by unsigned short),
9697 and @code{bool__} (always followed by unsigned).
9700 __attribute__((altivec(vector__)))
9701 __attribute__((altivec(pixel__))) unsigned short
9702 __attribute__((altivec(bool__))) unsigned
9705 These attributes mainly are intended to support the @code{__vector},
9706 @code{__pixel}, and @code{__bool} AltiVec keywords.
9708 @node x86 Type Attributes
9709 @subsection x86 Type Attributes
9711 Two attributes are currently defined for x86 configurations:
9712 @code{ms_struct} and @code{gcc_struct}.
9716 @cindex @code{ms_struct} type attribute, x86
9717 @cindex @code{gcc_struct} type attribute, x86
9721 If @code{packed} is used on a structure, or if bit-fields are used
9722 it may be that the Microsoft ABI packs them differently
9723 than GCC normally packs them. Particularly when moving packed
9724 data between functions compiled with GCC and the native Microsoft compiler
9725 (either via function call or as data in a file), it may be necessary to access
9728 The @code{ms_struct} and @code{gcc_struct} attributes correspond
9729 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
9730 command-line options, respectively;
9731 see @ref{x86 Options}, for details of how structure layout is affected.
9732 @xref{x86 Variable Attributes}, for information about the corresponding
9733 attributes on variables.
9737 @node Label Attributes
9738 @section Label Attributes
9739 @cindex Label Attributes
9741 GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for
9742 details of the exact syntax for using attributes. Other attributes are
9743 available for functions (@pxref{Function Attributes}), variables
9744 (@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}),
9745 statements (@pxref{Statement Attributes}), and for types
9746 (@pxref{Type Attributes}). A label attribute followed
9747 by a declaration appertains to the label and not the declaration.
9749 This example uses the @code{cold} label attribute to indicate the
9750 @code{ErrorHandling} branch is unlikely to be taken and that the
9751 @code{ErrorHandling} label is unused:
9755 asm goto ("some asm" : : : : NoError);
9757 /* This branch (the fall-through from the asm) is less commonly used */
9759 __attribute__((cold, unused)); /* Semi-colon is required here */
9764 printf("no error\n");
9769 @cindex @code{unused} label attribute
9771 This feature is intended for program-generated code that may contain
9772 unused labels, but which is compiled with @option{-Wall}. It is
9773 not normally appropriate to use in it human-written code, though it
9774 could be useful in cases where the code that jumps to the label is
9775 contained within an @code{#ifdef} conditional.
9777 @cindex @code{hot} label attribute
9779 The @code{hot} attribute on a label is used to inform the compiler that
9780 the path following the label is more likely than paths that are not so
9781 annotated. This attribute is used in cases where @code{__builtin_expect}
9782 cannot be used, for instance with computed goto or @code{asm goto}.
9784 @cindex @code{cold} label attribute
9786 The @code{cold} attribute on labels is used to inform the compiler that
9787 the path following the label is unlikely to be executed. This attribute
9788 is used in cases where @code{__builtin_expect} cannot be used, for instance
9789 with computed goto or @code{asm goto}.
9793 @node Enumerator Attributes
9794 @section Enumerator Attributes
9795 @cindex Enumerator Attributes
9797 GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for
9798 details of the exact syntax for using attributes. Other attributes are
9799 available for functions (@pxref{Function Attributes}), variables
9800 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements
9801 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
9803 This example uses the @code{deprecated} enumerator attribute to indicate the
9804 @code{oldval} enumerator is deprecated:
9808 oldval __attribute__((deprecated)),
9820 @cindex @code{deprecated} enumerator attribute
9822 The @code{deprecated} attribute results in a warning if the enumerator
9823 is used anywhere in the source file. This is useful when identifying
9824 enumerators that are expected to be removed in a future version of a
9825 program. The warning also includes the location of the declaration
9826 of the deprecated enumerator, to enable users to easily find further
9827 information about why the enumerator is deprecated, or what they should
9828 do instead. Note that the warnings only occurs for uses.
9830 @cindex @code{unavailable} enumerator attribute
9832 The @code{unavailable} attribute results in an error if the enumerator
9833 is used anywhere in the source file. In other respects it behaves in the
9834 same manner as the @code{deprecated} attribute.
9838 @node Statement Attributes
9839 @section Statement Attributes
9840 @cindex Statement Attributes
9842 GCC allows attributes to be set on null statements. @xref{Attribute Syntax},
9843 for details of the exact syntax for using attributes. Other attributes are
9844 available for functions (@pxref{Function Attributes}), variables
9845 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators
9846 (@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}).
9849 @cindex @code{fallthrough} statement attribute
9851 The @code{fallthrough} attribute with a null statement serves as a
9852 fallthrough statement. It hints to the compiler that a statement
9853 that falls through to another case label, or user-defined label
9854 in a switch statement is intentional and thus the
9855 @option{-Wimplicit-fallthrough} warning must not trigger. The
9856 fallthrough attribute may appear at most once in each attribute
9857 list, and may not be mixed with other attributes. It can only
9858 be used in a switch statement (the compiler will issue an error
9859 otherwise), after a preceding statement and before a logically
9860 succeeding case label, or user-defined label.
9862 This example uses the @code{fallthrough} statement attribute to indicate that
9863 the @option{-Wimplicit-fallthrough} warning should not be emitted:
9870 __attribute__((fallthrough));
9876 @cindex @code{assume} statement attribute
9878 The @code{assume} attribute with a null statement serves as portable
9879 assumption. It should have a single argument, a conditional expression,
9880 which is not evaluated. If the argument would evaluate to true
9881 at the point where it appears, it has no effect, otherwise there
9882 is undefined behavior. This is a GNU variant of the ISO C++23
9883 standard @code{assume} attribute, but it can be used in any version of
9890 __attribute__((assume(x == 42)));
9891 __attribute__((assume(++y == 43)));
9896 @code{y} is not actually incremented and the compiler can but does not
9897 have to optimize it to just @code{return 42 + 42;}.
9901 @node Attribute Syntax
9902 @section Attribute Syntax
9903 @cindex attribute syntax
9904 @cindex C standard attributes
9905 @cindex C++ standard attributes
9906 @cindex standard attribute syntax
9907 @cindex GNU attribute syntax
9909 GCC provides two different ways to specify attributes: the standard C
9910 and C++ syntax using double square brackets, and the older GNU
9911 extension syntax using the @code{@w{__attribute__}} keyword, which predates
9912 the adoption of the standard syntax and is still widely used in older
9915 The standard @samp{[[]]} attribute syntax is recognized by GCC's
9916 default language dialect for both C and C++. More specifically, this
9917 syntax was first introduced in the C++11 language standard
9918 (@pxref{Standards}), and is supported by GCC in C++ code with
9919 @option{-std=c++11} or @option{-std=gnu++11} or later. It is also
9920 part of the C23 language standard and is supported when compiling C
9921 code with @option{-std=c23} or @option{-std=gnu17} or later.
9923 When using GNU-specific attributes in the standard syntax, you must
9924 prefix their names with @samp{gnu::}, such as @code{gnu::section}.
9925 Refer to the relevant language standards for exact details on the
9926 placement of @samp{[[]]} attributes within your code, as they differ
9927 in some details from the rules for the GNU attribute syntax.
9929 The remainder of this section describes the details of the GNU extension
9930 @code{__attribute__} syntax,
9931 and the constructs to which attribute specifiers bind, for the C
9932 language. Some details may vary for C++ and Objective-C@. Because of
9933 limitations in the grammar for attributes, some forms described here
9934 may not be successfully parsed in all cases.
9936 There are some problems with the semantics of attributes in C++. For
9937 example, there are no manglings for attributes, although they may affect
9938 code generation, so problems may arise when attributed types are used in
9939 conjunction with templates or overloading. Similarly, @code{typeid}
9940 does not distinguish between types with different attributes. Support
9941 for attributes in C++ may be restricted in future to attributes on
9942 declarations only, but not on nested declarators.
9944 @xref{Function Attributes}, for details of the semantics of attributes
9945 applying to functions. @xref{Variable Attributes}, for details of the
9946 semantics of attributes applying to variables. @xref{Type Attributes},
9947 for details of the semantics of attributes applying to structure, union
9948 and enumerated types.
9949 @xref{Label Attributes}, for details of the semantics of attributes
9951 @xref{Enumerator Attributes}, for details of the semantics of attributes
9952 applying to enumerators.
9953 @xref{Statement Attributes}, for details of the semantics of attributes
9954 applying to statements.
9956 An @dfn{attribute specifier} is of the form
9957 @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
9958 is a possibly empty comma-separated sequence of @dfn{attributes}, where
9959 each attribute is one of the following:
9963 Empty. Empty attributes are ignored.
9967 (which may be an identifier such as @code{unused}, or a reserved
9968 word such as @code{const}).
9971 An attribute name followed by a parenthesized list of
9972 parameters for the attribute.
9973 These parameters take one of the following forms:
9977 An identifier. For example, @code{mode} attributes use this form.
9980 An identifier followed by a comma and a non-empty comma-separated list
9981 of expressions. For example, @code{format} attributes use this form.
9984 A possibly empty comma-separated list of expressions. For example,
9985 @code{format_arg} attributes use this form with the list being a single
9986 integer constant expression, and @code{alias} attributes use this form
9987 with the list being a single string constant.
9991 An @dfn{attribute specifier list} is a sequence of one or more attribute
9992 specifiers, not separated by any other tokens.
9994 You may optionally specify attribute names with @samp{__}
9995 preceding and following the name.
9996 This allows you to use them in header files without
9997 being concerned about a possible macro of the same name. For example,
9998 you may use the attribute name @code{__noreturn__} instead of @code{noreturn}.
10001 @subsubheading Label Attributes
10003 In GNU C, an attribute specifier list may appear after the colon following a
10004 label, other than a @code{case} or @code{default} label. GNU C++ only permits
10005 attributes on labels if the attribute specifier is immediately
10006 followed by a semicolon (i.e., the label applies to an empty
10007 statement). If the semicolon is missing, C++ label attributes are
10008 ambiguous, as it is permissible for a declaration, which could begin
10009 with an attribute list, to be labelled in C++. Declarations cannot be
10010 labelled in C90 or C99, so the ambiguity does not arise there.
10012 @subsubheading Enumerator Attributes
10014 In GNU C, an attribute specifier list may appear as part of an enumerator.
10015 The attribute goes after the enumeration constant, before @code{=}, if
10016 present. The optional attribute in the enumerator appertains to the
10017 enumeration constant. It is not possible to place the attribute after
10018 the constant expression, if present.
10020 @subsubheading Statement Attributes
10021 In GNU C, an attribute specifier list may appear as part of a null
10022 statement. The attribute goes before the semicolon.
10024 @subsubheading Type Attributes
10026 An attribute specifier list may appear as part of a @code{struct},
10027 @code{union} or @code{enum} specifier. It may go either immediately
10028 after the @code{struct}, @code{union} or @code{enum} keyword, or after
10029 the closing brace. The former syntax is preferred.
10030 Where attribute specifiers follow the closing brace, they are considered
10031 to relate to the structure, union or enumerated type defined, not to any
10032 enclosing declaration the type specifier appears in, and the type
10033 defined is not complete until after the attribute specifiers.
10034 @c Otherwise, there would be the following problems: a shift/reduce
10035 @c conflict between attributes binding the struct/union/enum and
10036 @c binding to the list of specifiers/qualifiers; and "aligned"
10037 @c attributes could use sizeof for the structure, but the size could be
10038 @c changed later by "packed" attributes.
10041 @subsubheading All other attributes
10043 Otherwise, an attribute specifier appears as part of a declaration,
10044 counting declarations of unnamed parameters and type names, and relates
10045 to that declaration (which may be nested in another declaration, for
10046 example in the case of a parameter declaration), or to a particular declarator
10047 within a declaration. Where an
10048 attribute specifier is applied to a parameter declared as a function or
10049 an array, it should apply to the function or array rather than the
10050 pointer to which the parameter is implicitly converted, but this is not
10051 yet correctly implemented.
10053 Any list of specifiers and qualifiers at the start of a declaration may
10054 contain attribute specifiers, whether or not such a list may in that
10055 context contain storage class specifiers. (Some attributes, however,
10056 are essentially in the nature of storage class specifiers, and only make
10057 sense where storage class specifiers may be used; for example,
10058 @code{section}.) There is one necessary limitation to this syntax: the
10059 first old-style parameter declaration in a function definition cannot
10060 begin with an attribute specifier, because such an attribute applies to
10061 the function instead by syntax described below (which, however, is not
10062 yet implemented in this case). In some other cases, attribute
10063 specifiers are permitted by this grammar but not yet supported by the
10064 compiler. All attribute specifiers in this place relate to the
10065 declaration as a whole. In the obsolescent usage where a type of
10066 @code{int} is implied by the absence of type specifiers, such a list of
10067 specifiers and qualifiers may be an attribute specifier list with no
10068 other specifiers or qualifiers.
10070 At present, the first parameter in a function prototype must have some
10071 type specifier that is not an attribute specifier; this resolves an
10072 ambiguity in the interpretation of @code{void f(int
10073 (__attribute__((foo)) x))}, but is subject to change. At present, if
10074 the parentheses of a function declarator contain only attributes then
10075 those attributes are ignored, rather than yielding an error or warning
10076 or implying a single parameter of type int, but this is subject to
10079 An attribute specifier list may appear immediately before a declarator
10080 (other than the first) in a comma-separated list of declarators in a
10081 declaration of more than one identifier using a single list of
10082 specifiers and qualifiers. Such attribute specifiers apply
10083 only to the identifier before whose declarator they appear. For
10087 __attribute__((noreturn)) void d0 (void),
10088 __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
10093 the @code{noreturn} attribute applies to all the functions
10094 declared; the @code{format} attribute only applies to @code{d1}.
10096 An attribute specifier list may appear immediately before the comma,
10097 @code{=} or semicolon terminating the declaration of an identifier other
10098 than a function definition. Such attribute specifiers apply
10099 to the declared object or function. Where an
10100 assembler name for an object or function is specified (@pxref{Asm
10101 Labels}), the attribute must follow the @code{asm}
10104 An attribute specifier list may, in future, be permitted to appear after
10105 the declarator in a function definition (before any old-style parameter
10106 declarations or the function body).
10108 Attribute specifiers may be mixed with type qualifiers appearing inside
10109 the @code{[]} of a parameter array declarator, in the C99 construct by
10110 which such qualifiers are applied to the pointer to which the array is
10111 implicitly converted. Such attribute specifiers apply to the pointer,
10112 not to the array, but at present this is not implemented and they are
10115 An attribute specifier list may appear at the start of a nested
10116 declarator. At present, there are some limitations in this usage: the
10117 attributes correctly apply to the declarator, but for most individual
10118 attributes the semantics this implies are not implemented.
10119 When attribute specifiers follow the @code{*} of a pointer
10120 declarator, they may be mixed with any type qualifiers present.
10121 The following describes the formal semantics of this syntax. It makes the
10122 most sense if you are familiar with the formal specification of
10123 declarators in the ISO C standard.
10125 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
10126 D1}, where @code{T} contains declaration specifiers that specify a type
10127 @var{Type} (such as @code{int}) and @code{D1} is a declarator that
10128 contains an identifier @var{ident}. The type specified for @var{ident}
10129 for derived declarators whose type does not include an attribute
10130 specifier is as in the ISO C standard.
10132 If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
10133 and the declaration @code{T D} specifies the type
10134 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
10135 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
10136 @var{attribute-specifier-list} @var{Type}'' for @var{ident}.
10138 If @code{D1} has the form @code{*
10139 @var{type-qualifier-and-attribute-specifier-list} D}, and the
10140 declaration @code{T D} specifies the type
10141 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
10142 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
10143 @var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for
10149 void (__attribute__((noreturn)) ****f) (void);
10153 specifies the type ``pointer to pointer to pointer to pointer to
10154 non-returning function returning @code{void}''. As another example,
10157 char *__attribute__((aligned(8))) *f;
10161 specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
10162 Note again that this does not work with most attributes; for example,
10163 the usage of @samp{aligned} and @samp{noreturn} attributes given above
10164 is not yet supported.
10166 For compatibility with existing code written for compiler versions that
10167 did not implement attributes on nested declarators, some laxity is
10168 allowed in the placing of attributes. If an attribute that only applies
10169 to types is applied to a declaration, it is treated as applying to
10170 the type of that declaration. If an attribute that only applies to
10171 declarations is applied to the type of a declaration, it is treated
10172 as applying to that declaration; and, for compatibility with code
10173 placing the attributes immediately before the identifier declared, such
10174 an attribute applied to a function return type is treated as
10175 applying to the function type, and such an attribute applied to an array
10176 element type is treated as applying to the array type. If an
10177 attribute that only applies to function types is applied to a
10178 pointer-to-function type, it is treated as applying to the pointer
10179 target type; if such an attribute is applied to a function return type
10180 that is not a pointer-to-function type, it is treated as applying
10181 to the function type.
10183 @node Function Prototypes
10184 @section Prototypes and Old-Style Function Definitions
10185 @cindex function prototype declarations
10186 @cindex old-style function definitions
10187 @cindex promotion of formal parameters
10189 GNU C extends ISO C to allow a function prototype to override a later
10190 old-style non-prototype definition. Consider the following example:
10193 /* @r{Use prototypes unless the compiler is old-fashioned.} */
10200 /* @r{Prototype function declaration.} */
10201 int isroot P((uid_t));
10203 /* @r{Old-style function definition.} */
10205 isroot (x) /* @r{??? lossage here ???} */
10212 Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
10213 not allow this example, because subword arguments in old-style
10214 non-prototype definitions are promoted. Therefore in this example the
10215 function definition's argument is really an @code{int}, which does not
10216 match the prototype argument type of @code{short}.
10218 This restriction of ISO C makes it hard to write code that is portable
10219 to traditional C compilers, because the programmer does not know
10220 whether the @code{uid_t} type is @code{short}, @code{int}, or
10221 @code{long}. Therefore, in cases like these GNU C allows a prototype
10222 to override a later old-style definition. More precisely, in GNU C, a
10223 function prototype argument type overrides the argument type specified
10224 by a later old-style definition if the former type is the same as the
10225 latter type before promotion. Thus in GNU C the above example is
10226 equivalent to the following:
10229 int isroot (uid_t);
10239 GNU C++ does not support old-style function definitions, so this
10240 extension is irrelevant.
10243 @section C++ Style Comments
10245 @cindex C++ comments
10246 @cindex comments, C++ style
10248 In GNU C, you may use C++ style comments, which start with @samp{//} and
10249 continue until the end of the line. Many other C implementations allow
10250 such comments, and they are included in the 1999 C standard. However,
10251 C++ style comments are not recognized if you specify an @option{-std}
10252 option specifying a version of ISO C before C99, or @option{-ansi}
10253 (equivalent to @option{-std=c90}).
10256 @section Dollar Signs in Identifier Names
10258 @cindex dollar signs in identifier names
10259 @cindex identifier names, dollar signs in
10261 In GNU C, you may normally use dollar signs in identifier names.
10262 This is because many traditional C implementations allow such identifiers.
10263 However, dollar signs in identifiers are not supported on a few target
10264 machines, typically because the target assembler does not allow them.
10266 @node Character Escapes
10267 @section The Character @key{ESC} in Constants
10269 You can use the sequence @samp{\e} in a string or character constant to
10270 stand for the ASCII character @key{ESC}.
10273 @section Determining the Alignment of Functions, Types or Variables
10275 @cindex type alignment
10276 @cindex variable alignment
10278 The keyword @code{__alignof__} determines the alignment requirement of
10279 a function, object, or a type, or the minimum alignment usually required
10280 by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}.
10282 For example, if the target machine requires a @code{double} value to be
10283 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
10284 This is true on many RISC machines. On more traditional machine
10285 designs, @code{__alignof__ (double)} is 4 or even 2.
10287 Some machines never actually require alignment; they allow references to any
10288 data type even at an odd address. For these machines, @code{__alignof__}
10289 reports the smallest alignment that GCC gives the data type, usually as
10290 mandated by the target ABI.
10292 If the operand of @code{__alignof__} is an lvalue rather than a type,
10293 its value is the required alignment for its type, taking into account
10294 any minimum alignment specified by attribute @code{aligned}
10295 (@pxref{Common Variable Attributes}). For example, after this
10299 struct foo @{ int x; char y; @} foo1;
10303 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
10304 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
10305 It is an error to ask for the alignment of an incomplete type other
10308 If the operand of the @code{__alignof__} expression is a function,
10309 the expression evaluates to the alignment of the function which may
10310 be specified by attribute @code{aligned} (@pxref{Common Function Attributes}).
10313 @section An Inline Function is As Fast As a Macro
10314 @cindex inline functions
10315 @cindex integrating function code
10316 @cindex open coding
10317 @cindex macros, inline alternative
10319 By declaring a function inline, you can direct GCC to make
10320 calls to that function faster. One way GCC can achieve this is to
10321 integrate that function's code into the code for its callers. This
10322 makes execution faster by eliminating the function-call overhead; in
10323 addition, if any of the actual argument values are constant, their
10324 known values may permit simplifications at compile time so that not
10325 all of the inline function's code needs to be included. The effect on
10326 code size is less predictable; object code may be larger or smaller
10327 with function inlining, depending on the particular case. You can
10328 also direct GCC to try to integrate all ``simple enough'' functions
10329 into their callers with the option @option{-finline-functions}.
10331 GCC implements three different semantics of declaring a function
10332 inline. One is available with @option{-std=gnu89} or
10333 @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
10334 on all inline declarations, another when
10336 @option{-std=gnu99} or an option for a later C version is used
10337 (without @option{-fgnu89-inline}), and the third
10338 is used when compiling C++.
10340 To declare a function inline, use the @code{inline} keyword in its
10341 declaration, like this:
10351 If you are writing a header file to be included in ISO C90 programs, write
10352 @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
10354 The three types of inlining behave similarly in two important cases:
10355 when the @code{inline} keyword is used on a @code{static} function,
10356 like the example above, and when a function is first declared without
10357 using the @code{inline} keyword and then is defined with
10358 @code{inline}, like this:
10361 extern int inc (int *a);
10369 In both of these common cases, the program behaves the same as if you
10370 had not used the @code{inline} keyword, except for its speed.
10372 @cindex inline functions, omission of
10373 @opindex fkeep-inline-functions
10374 When a function is both inline and @code{static}, if all calls to the
10375 function are integrated into the caller, and the function's address is
10376 never used, then the function's own assembler code is never referenced.
10377 In this case, GCC does not actually output assembler code for the
10378 function, unless you specify the option @option{-fkeep-inline-functions}.
10379 If there is a nonintegrated call, then the function is compiled to
10380 assembler code as usual. The function must also be compiled as usual if
10381 the program refers to its address, because that cannot be inlined.
10384 Note that certain usages in a function definition can make it unsuitable
10385 for inline substitution. Among these usages are: variadic functions,
10386 use of @code{alloca}, use of computed goto (@pxref{Labels as Values}),
10387 use of nonlocal goto, use of nested functions, use of @code{setjmp}, use
10388 of @code{__builtin_longjmp} and use of @code{__builtin_return} or
10389 @code{__builtin_apply_args}. Using @option{-Winline} warns when a
10390 function marked @code{inline} could not be substituted, and gives the
10391 reason for the failure.
10393 @cindex automatic @code{inline} for C++ member fns
10394 @cindex @code{inline} automatic for C++ member fns
10395 @cindex member fns, automatically @code{inline}
10396 @cindex C++ member fns, automatically @code{inline}
10397 @opindex fno-default-inline
10398 As required by ISO C++, GCC considers member functions defined within
10399 the body of a class to be marked inline even if they are
10400 not explicitly declared with the @code{inline} keyword. You can
10401 override this with @option{-fno-default-inline}; @pxref{C++ Dialect
10402 Options,,Options Controlling C++ Dialect}.
10404 GCC does not inline any functions when not optimizing unless you specify
10405 the @samp{always_inline} attribute for the function, like this:
10408 /* @r{Prototype.} */
10409 inline void foo (const char) __attribute__((always_inline));
10412 The remainder of this section is specific to GNU C90 inlining.
10414 @cindex non-static inline function
10415 When an inline function is not @code{static}, then the compiler must assume
10416 that there may be calls from other source files; since a global symbol can
10417 be defined only once in any program, the function must not be defined in
10418 the other source files, so the calls therein cannot be integrated.
10419 Therefore, a non-@code{static} inline function is always compiled on its
10420 own in the usual fashion.
10422 If you specify both @code{inline} and @code{extern} in the function
10423 definition, then the definition is used only for inlining. In no case
10424 is the function compiled on its own, not even if you refer to its
10425 address explicitly. Such an address becomes an external reference, as
10426 if you had only declared the function, and had not defined it.
10428 This combination of @code{inline} and @code{extern} has almost the
10429 effect of a macro. The way to use it is to put a function definition in
10430 a header file with these keywords, and put another copy of the
10431 definition (lacking @code{inline} and @code{extern}) in a library file.
10432 The definition in the header file causes most calls to the function
10433 to be inlined. If any uses of the function remain, they refer to
10434 the single copy in the library.
10436 @node Const and Volatile Functions
10437 @section Const and Volatile Functions
10438 @cindex @code{const} applied to function
10439 @cindex @code{volatile} applied to function
10441 The C standard explicitly leaves the behavior of the @code{const} and
10442 @code{volatile} type qualifiers applied to functions undefined; these
10443 constructs can only arise through the use of @code{typedef}. As an extension,
10444 GCC defines this use of the @code{const} qualifier to have the same meaning
10445 as the GCC @code{const} function attribute, and the @code{volatile} qualifier
10446 to be equivalent to the @code{noreturn} attribute.
10447 @xref{Common Function Attributes}, for more information.
10449 As examples of this usage,
10453 /* @r{Equivalent to:}
10454 void fatal () __attribute__ ((noreturn)); */
10455 typedef void voidfn ();
10456 volatile voidfn fatal;
10458 /* @r{Equivalent to:}
10459 extern int square (int) __attribute__ ((const)); */
10460 typedef int intfn (int);
10461 extern const intfn square;
10464 In general, using function attributes instead is preferred, since the
10465 attributes make both the intent of the code and its reliance on a GNU
10466 extension explicit. Additionally, using @code{const} and
10467 @code{volatile} in this way is specific to GNU C and does not work in
10471 @section When is a Volatile Object Accessed?
10472 @cindex accessing volatiles
10473 @cindex volatile read
10474 @cindex volatile write
10475 @cindex volatile access
10477 C has the concept of volatile objects. These are normally accessed by
10478 pointers and used for accessing hardware or inter-thread
10479 communication. The standard encourages compilers to refrain from
10480 optimizations concerning accesses to volatile objects, but leaves it
10481 implementation defined as to what constitutes a volatile access. The
10482 minimum requirement is that at a sequence point all previous accesses
10483 to volatile objects have stabilized and no subsequent accesses have
10484 occurred. Thus an implementation is free to reorder and combine
10485 volatile accesses that occur between sequence points, but cannot do
10486 so for accesses across a sequence point. The use of volatile does
10487 not allow you to violate the restriction on updating objects multiple
10488 times between two sequence points.
10490 Accesses to non-volatile objects are not ordered with respect to
10491 volatile accesses. You cannot use a volatile object as a memory
10492 barrier to order a sequence of writes to non-volatile memory. For
10496 int *ptr = @var{something};
10498 *ptr = @var{something};
10503 Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed
10504 that the write to @var{*ptr} occurs by the time the update
10505 of @var{vobj} happens. If you need this guarantee, you must use
10506 a stronger memory barrier such as:
10509 int *ptr = @var{something};
10511 *ptr = @var{something};
10512 asm volatile ("" : : : "memory");
10516 A scalar volatile object is read when it is accessed in a void context:
10519 volatile int *src = @var{somevalue};
10523 Such expressions are rvalues, and GCC implements this as a
10524 read of the volatile object being pointed to.
10526 Assignments are also expressions and have an rvalue. However when
10527 assigning to a scalar volatile, the volatile object is not reread,
10528 regardless of whether the assignment expression's rvalue is used or
10529 not. If the assignment's rvalue is used, the value is that assigned
10530 to the volatile object. For instance, there is no read of @var{vobj}
10531 in all the following cases:
10536 vobj = @var{something};
10537 obj = vobj = @var{something};
10538 obj ? vobj = @var{onething} : vobj = @var{anotherthing};
10539 obj = (@var{something}, vobj = @var{anotherthing});
10542 If you need to read the volatile object after an assignment has
10543 occurred, you must use a separate expression with an intervening
10546 As bit-fields are not individually addressable, volatile bit-fields may
10547 be implicitly read when written to, or when adjacent bit-fields are
10548 accessed. Bit-field operations may be optimized such that adjacent
10549 bit-fields are only partially accessed, if they straddle a storage unit
10550 boundary. For these reasons it is unwise to use volatile bit-fields to
10553 @node Using Assembly Language with C
10554 @section How to Use Inline Assembly Language in C Code
10555 @cindex @code{asm} keyword
10556 @cindex assembly language in C
10557 @cindex inline assembly language
10558 @cindex mixing assembly language and C
10560 The @code{asm} keyword allows you to embed assembler instructions
10561 within C code. GCC provides two forms of inline @code{asm}
10562 statements. A @dfn{basic @code{asm}} statement is one with no
10563 operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}}
10564 statement (@pxref{Extended Asm}) includes one or more operands.
10565 The extended form is preferred for mixing C and assembly language
10566 within a function, but to include assembly language at
10567 top level you must use basic @code{asm}.
10569 You can also use the @code{asm} keyword to override the assembler name
10570 for a C symbol, or to place a C variable in a specific register.
10573 * Basic Asm:: Inline assembler without operands.
10574 * Extended Asm:: Inline assembler with operands.
10575 * Constraints:: Constraints for @code{asm} operands
10576 * Asm Labels:: Specifying the assembler name to use for a C symbol.
10577 * Explicit Register Variables:: Defining variables residing in specified
10579 * Size of an asm:: How GCC calculates the size of an @code{asm} block.
10583 @subsection Basic Asm --- Assembler Instructions Without Operands
10584 @cindex basic @code{asm}
10585 @cindex assembly language in C, basic
10587 A basic @code{asm} statement has the following syntax:
10590 asm @var{asm-qualifiers} ( @var{AssemblerInstructions} )
10593 For the C language, the @code{asm} keyword is a GNU extension.
10594 When writing C code that can be compiled with @option{-ansi} and the
10595 @option{-std} options that select C dialects without GNU extensions, use
10596 @code{__asm__} instead of @code{asm} (@pxref{Alternate Keywords}). For
10597 the C++ language, @code{asm} is a standard keyword, but @code{__asm__}
10598 can be used for code compiled with @option{-fno-asm}.
10600 @subsubheading Qualifiers
10603 The optional @code{volatile} qualifier has no effect.
10604 All basic @code{asm} blocks are implicitly volatile.
10607 If you use the @code{inline} qualifier, then for inlining purposes the size
10608 of the @code{asm} statement is taken as the smallest size possible (@pxref{Size
10612 @subsubheading Parameters
10615 @item AssemblerInstructions
10616 This is a literal string that specifies the assembler code. The string can
10617 contain any instructions recognized by the assembler, including directives.
10618 GCC does not parse the assembler instructions themselves and
10619 does not know what they mean or even whether they are valid assembler input.
10621 You may place multiple assembler instructions together in a single @code{asm}
10622 string, separated by the characters normally used in assembly code for the
10623 system. A combination that works in most places is a newline to break the
10624 line, plus a tab character (written as @samp{\n\t}).
10625 Some assemblers allow semicolons as a line separator. However,
10626 note that some assembler dialects use semicolons to start a comment.
10629 @subsubheading Remarks
10630 Using extended @code{asm} (@pxref{Extended Asm}) typically produces
10631 smaller, safer, and more efficient code, and in most cases it is a
10632 better solution than basic @code{asm}. However, there are two
10633 situations where only basic @code{asm} can be used:
10637 Extended @code{asm} statements have to be inside a C
10638 function, so to write inline assembly language at file scope (``top-level''),
10639 outside of C functions, you must use basic @code{asm}.
10640 You can use this technique to emit assembler directives,
10641 define assembly language macros that can be invoked elsewhere in the file,
10642 or write entire functions in assembly language.
10643 Basic @code{asm} statements outside of functions may not use any
10648 with the @code{naked} attribute also require basic @code{asm}
10649 (@pxref{Function Attributes}).
10652 Safely accessing C data and calling functions from basic @code{asm} is more
10653 complex than it may appear. To access C data, it is better to use extended
10656 Do not expect a sequence of @code{asm} statements to remain perfectly
10657 consecutive after compilation. If certain instructions need to remain
10658 consecutive in the output, put them in a single multi-instruction @code{asm}
10659 statement. Note that GCC's optimizers can move @code{asm} statements
10660 relative to other code, including across jumps.
10662 @code{asm} statements may not perform jumps into other @code{asm} statements.
10663 GCC does not know about these jumps, and therefore cannot take
10664 account of them when deciding how to optimize. Jumps from @code{asm} to C
10665 labels are only supported in extended @code{asm}.
10667 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
10668 assembly code when optimizing. This can lead to unexpected duplicate
10669 symbol errors during compilation if your assembly code defines symbols or
10672 @strong{Warning:} The C standards do not specify semantics for @code{asm},
10673 making it a potential source of incompatibilities between compilers. These
10674 incompatibilities may not produce compiler warnings/errors.
10676 GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which
10677 means there is no way to communicate to the compiler what is happening
10678 inside them. GCC has no visibility of symbols in the @code{asm} and may
10679 discard them as unreferenced. It also does not know about side effects of
10680 the assembler code, such as modifications to memory or registers. Unlike
10681 some compilers, GCC assumes that no changes to general purpose registers
10682 occur. This assumption may change in a future release.
10684 To avoid complications from future changes to the semantics and the
10685 compatibility issues between compilers, consider replacing basic @code{asm}
10686 with extended @code{asm}. See
10687 @uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert
10688 from basic asm to extended asm} for information about how to perform this
10691 The compiler copies the assembler instructions in a basic @code{asm}
10692 verbatim to the assembly language output file, without
10693 processing dialects or any of the @samp{%} operators that are available with
10694 extended @code{asm}. This results in minor differences between basic
10695 @code{asm} strings and extended @code{asm} templates. For example, to refer to
10696 registers you might use @samp{%eax} in basic @code{asm} and
10697 @samp{%%eax} in extended @code{asm}.
10699 On targets such as x86 that support multiple assembler dialects,
10700 all basic @code{asm} blocks use the assembler dialect specified by the
10701 @option{-masm} command-line option (@pxref{x86 Options}).
10702 Basic @code{asm} provides no
10703 mechanism to provide different assembler strings for different dialects.
10705 For basic @code{asm} with non-empty assembler string GCC assumes
10706 the assembler block does not change any general purpose registers,
10707 but it may read or write any globally accessible variable.
10709 Here is an example of basic @code{asm} for i386:
10712 /* Note that this code will not compile with -masm=intel */
10713 #define DebugBreak() asm("int $3")
10717 @subsection Extended Asm - Assembler Instructions with C Expression Operands
10718 @cindex extended @code{asm}
10719 @cindex assembly language in C, extended
10721 With extended @code{asm} you can read and write C variables from
10722 assembler and perform jumps from assembler code to C labels.
10723 Extended @code{asm} syntax uses colons (@samp{:}) to delimit
10724 the operand parameters after the assembler template:
10727 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
10728 : @var{OutputOperands}
10729 @r{[} : @var{InputOperands}
10730 @r{[} : @var{Clobbers} @r{]} @r{]})
10732 asm @var{asm-qualifiers} ( @var{AssemblerTemplate}
10733 : @var{OutputOperands}
10734 : @var{InputOperands}
10736 : @var{GotoLabels})
10738 where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the
10741 The @code{asm} keyword is a GNU extension.
10742 When writing code that can be compiled with @option{-ansi} and the
10743 various @option{-std} options, use @code{__asm__} instead of
10744 @code{asm} (@pxref{Alternate Keywords}).
10746 @subsubheading Qualifiers
10750 The typical use of extended @code{asm} statements is to manipulate input
10751 values to produce output values. However, your @code{asm} statements may
10752 also produce side effects. If so, you may need to use the @code{volatile}
10753 qualifier to disable certain optimizations. @xref{Volatile}.
10756 If you use the @code{inline} qualifier, then for inlining purposes the size
10757 of the @code{asm} statement is taken as the smallest size possible
10758 (@pxref{Size of an asm}).
10761 This qualifier informs the compiler that the @code{asm} statement may
10762 perform a jump to one of the labels listed in the @var{GotoLabels}.
10766 @subsubheading Parameters
10768 @item AssemblerTemplate
10769 This is a literal string that is the template for the assembler code. It is a
10770 combination of fixed text and tokens that refer to the input, output,
10771 and goto parameters. @xref{AssemblerTemplate}.
10773 @item OutputOperands
10774 A comma-separated list of the C variables modified by the instructions in the
10775 @var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}.
10777 @item InputOperands
10778 A comma-separated list of C expressions read by the instructions in the
10779 @var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}.
10782 A comma-separated list of registers or other values changed by the
10783 @var{AssemblerTemplate}, beyond those listed as outputs.
10784 An empty list is permitted. @xref{Clobbers and Scratch Registers}.
10787 When you are using the @code{goto} form of @code{asm}, this section contains
10788 the list of all C labels to which the code in the
10789 @var{AssemblerTemplate} may jump.
10792 @code{asm} statements may not perform jumps into other @code{asm} statements,
10793 only to the listed @var{GotoLabels}.
10794 GCC's optimizers do not know about other jumps; therefore they cannot take
10795 account of them when deciding how to optimize.
10798 The total number of input + output + goto operands is limited to 30.
10800 @subsubheading Remarks
10801 The @code{asm} statement allows you to include assembly instructions directly
10802 within C code. This may help you to maximize performance in time-sensitive
10803 code or to access assembly instructions that are not readily available to C
10806 Note that extended @code{asm} statements must be inside a function. Only
10807 basic @code{asm} may be outside functions (@pxref{Basic Asm}).
10808 Functions declared with the @code{naked} attribute also require basic
10809 @code{asm} (@pxref{Function Attributes}).
10811 While the uses of @code{asm} are many and varied, it may help to think of an
10812 @code{asm} statement as a series of low-level instructions that convert input
10813 parameters to output parameters. So a simple (if not particularly useful)
10814 example for i386 using @code{asm} might look like this:
10820 asm ("mov %1, %0\n\t"
10825 printf("%d\n", dst);
10828 This code copies @code{src} to @code{dst} and add 1 to @code{dst}.
10831 @subsubsection Volatile
10832 @cindex volatile @code{asm}
10833 @cindex @code{asm} volatile
10835 GCC's optimizers sometimes discard @code{asm} statements if they determine
10836 there is no need for the output variables. Also, the optimizers may move
10837 code out of loops if they believe that the code will always return the same
10838 result (i.e.@: none of its input values change between calls). Using the
10839 @code{volatile} qualifier disables these optimizations. @code{asm} statements
10840 that have no output operands and @code{asm goto} statements,
10841 are implicitly volatile.
10843 This i386 code demonstrates a case that does not use (or require) the
10844 @code{volatile} qualifier. If it is performing assertion checking, this code
10845 uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is
10846 unreferenced by any code. As a result, the optimizers can discard the
10847 @code{asm} statement, which in turn removes the need for the entire
10848 @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
10849 isn't needed you allow the optimizers to produce the most efficient code
10853 void DoCheck(uint32_t dwSomeValue)
10857 // Assumes dwSomeValue is not zero.
10860 : "r" (dwSomeValue)
10867 The next example shows a case where the optimizers can recognize that the input
10868 (@code{dwSomeValue}) never changes during the execution of the function and can
10869 therefore move the @code{asm} outside the loop to produce more efficient code.
10870 Again, using the @code{volatile} qualifier disables this type of optimization.
10873 void do_print(uint32_t dwSomeValue)
10877 for (uint32_t x=0; x < 5; x++)
10879 // Assumes dwSomeValue is not zero.
10882 : "r" (dwSomeValue)
10885 printf("%u: %u %u\n", x, dwSomeValue, dwRes);
10890 The following example demonstrates a case where you need to use the
10891 @code{volatile} qualifier.
10892 It uses the x86 @code{rdtsc} instruction, which reads
10893 the computer's time-stamp counter. Without the @code{volatile} qualifier,
10894 the optimizers might assume that the @code{asm} block will always return the
10895 same value and therefore optimize away the second call.
10900 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
10901 "shl $32, %%rdx\n\t" // Shift the upper bits left.
10902 "or %%rdx, %0" // 'Or' in the lower bits.
10907 printf("msr: %llx\n", msr);
10909 // Do other work...
10911 // Reprint the timestamp
10912 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
10913 "shl $32, %%rdx\n\t" // Shift the upper bits left.
10914 "or %%rdx, %0" // 'Or' in the lower bits.
10919 printf("msr: %llx\n", msr);
10922 GCC's optimizers do not treat this code like the non-volatile code in the
10923 earlier examples. They do not move it out of loops or omit it on the
10924 assumption that the result from a previous call is still valid.
10926 Note that the compiler can move even @code{volatile asm} instructions relative
10927 to other code, including across jump instructions. For example, on many
10928 targets there is a system register that controls the rounding mode of
10929 floating-point operations. Setting it with a @code{volatile asm} statement,
10930 as in the following PowerPC example, does not work reliably.
10933 asm volatile("mtfsf 255, %0" : : "f" (fpenv));
10937 The compiler may move the addition back before the @code{volatile asm}
10938 statement. To make it work as expected, add an artificial dependency to
10939 the @code{asm} by referencing a variable in the subsequent code, for
10943 asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
10947 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
10948 assembly code when optimizing. This can lead to unexpected duplicate symbol
10949 errors during compilation if your @code{asm} code defines symbols or labels.
10951 (@pxref{AssemblerTemplate}) may help resolve this problem.
10953 @anchor{AssemblerTemplate}
10954 @subsubsection Assembler Template
10955 @cindex @code{asm} assembler template
10957 An assembler template is a literal string containing assembler instructions.
10958 The compiler replaces tokens in the template that refer
10959 to inputs, outputs, and goto labels,
10960 and then outputs the resulting string to the assembler. The
10961 string can contain any instructions recognized by the assembler, including
10962 directives. GCC does not parse the assembler instructions
10963 themselves and does not know what they mean or even whether they are valid
10964 assembler input. However, it does count the statements
10965 (@pxref{Size of an asm}).
10967 You may place multiple assembler instructions together in a single @code{asm}
10968 string, separated by the characters normally used in assembly code for the
10969 system. A combination that works in most places is a newline to break the
10970 line, plus a tab character to move to the instruction field (written as
10972 Some assemblers allow semicolons as a line separator. However, note
10973 that some assembler dialects use semicolons to start a comment.
10975 Do not expect a sequence of @code{asm} statements to remain perfectly
10976 consecutive after compilation, even when you are using the @code{volatile}
10977 qualifier. If certain instructions need to remain consecutive in the output,
10978 put them in a single multi-instruction @code{asm} statement.
10980 Accessing data from C programs without using input/output operands (such as
10981 by using global symbols directly from the assembler template) may not work as
10982 expected. Similarly, calling functions directly from an assembler template
10983 requires a detailed understanding of the target assembler and ABI.
10985 Since GCC does not parse the assembler template,
10986 it has no visibility of any
10987 symbols it references. This may result in GCC discarding those symbols as
10988 unreferenced unless they are also listed as input, output, or goto operands.
10990 @subsubheading Special format strings
10992 In addition to the tokens described by the input, output, and goto operands,
10993 these tokens have special meanings in the assembler template:
10997 Outputs a single @samp{%} into the assembler code.
11000 Outputs a number that is unique to each instance of the @code{asm}
11001 statement in the entire compilation. This option is useful when creating local
11002 labels and referring to them multiple times in a single template that
11003 generates multiple assembler instructions.
11008 Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively)
11009 into the assembler code. When unescaped, these characters have special
11010 meaning to indicate multiple assembler dialects, as described below.
11013 @subsubheading Multiple assembler dialects in @code{asm} templates
11015 On targets such as x86, GCC supports multiple assembler dialects.
11016 The @option{-masm} option controls which dialect GCC uses as its
11017 default for inline assembler. The target-specific documentation for the
11018 @option{-masm} option contains the list of supported dialects, as well as the
11019 default dialect if the option is not specified. This information may be
11020 important to understand, since assembler code that works correctly when
11021 compiled using one dialect will likely fail if compiled using another.
11022 @xref{x86 Options}.
11024 If your code needs to support multiple assembler dialects (for example, if
11025 you are writing public headers that need to support a variety of compilation
11026 options), use constructs of this form:
11029 @{ dialect0 | dialect1 | dialect2... @}
11032 This construct outputs @code{dialect0}
11033 when using dialect #0 to compile the code,
11034 @code{dialect1} for dialect #1, etc. If there are fewer alternatives within the
11035 braces than the number of dialects the compiler supports, the construct
11038 For example, if an x86 compiler supports two dialects
11039 (@samp{att}, @samp{intel}), an
11040 assembler template such as this:
11043 "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
11047 is equivalent to one of
11050 "btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */}
11051 "bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */}
11054 Using that same compiler, this code:
11057 "xchg@{l@}\t@{%%@}ebx, %1"
11061 corresponds to either
11064 "xchgl\t%%ebx, %1" @r{/* att dialect */}
11065 "xchg\tebx, %1" @r{/* intel dialect */}
11068 There is no support for nesting dialect alternatives.
11070 @anchor{OutputOperands}
11071 @subsubsection Output Operands
11072 @cindex @code{asm} output operands
11074 An @code{asm} statement has zero or more output operands indicating the names
11075 of C variables modified by the assembler code.
11077 In this i386 example, @code{old} (referred to in the template string as
11078 @code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset}
11079 (@code{%2}) is an input:
11084 __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
11085 "sbb %0,%0" // Use the CF to calculate old.
11086 : "=r" (old), "+rm" (*Base)
11093 Operands are separated by commas. Each operand has this format:
11096 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename})
11100 @item asmSymbolicName
11101 Specifies a symbolic name for the operand.
11102 Reference the name in the assembler template
11103 by enclosing it in square brackets
11104 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
11105 that contains the definition. Any valid C variable name is acceptable,
11106 including names already defined in the surrounding code. No two operands
11107 within the same @code{asm} statement can use the same symbolic name.
11109 When not using an @var{asmSymbolicName}, use the (zero-based) position
11111 in the list of operands in the assembler template. For example if there are
11112 three output operands, use @samp{%0} in the template to refer to the first,
11113 @samp{%1} for the second, and @samp{%2} for the third.
11116 A string constant specifying constraints on the placement of the operand;
11117 @xref{Constraints}, for details.
11119 Output constraints must begin with either @samp{=} (a variable overwriting an
11120 existing value) or @samp{+} (when reading and writing). When using
11121 @samp{=}, do not assume the location contains the existing value
11122 on entry to the @code{asm}, except
11123 when the operand is tied to an input; @pxref{InputOperands,,Input Operands}.
11125 After the prefix, there must be one or more additional constraints
11126 (@pxref{Constraints}) that describe where the value resides. Common
11127 constraints include @samp{r} for register and @samp{m} for memory.
11128 When you list more than one possible location (for example, @code{"=rm"}),
11129 the compiler chooses the most efficient one based on the current context.
11130 If you list as many alternates as the @code{asm} statement allows, you permit
11131 the optimizers to produce the best possible code.
11132 If you must use a specific register, but your Machine Constraints do not
11133 provide sufficient control to select the specific register you want,
11134 local register variables may provide a solution (@pxref{Local Register
11137 @item cvariablename
11138 Specifies a C lvalue expression to hold the output, typically a variable name.
11139 The enclosing parentheses are a required part of the syntax.
11143 When the compiler selects the registers to use to
11144 represent the output operands, it does not use any of the clobbered registers
11145 (@pxref{Clobbers and Scratch Registers}).
11147 Output operand expressions must be lvalues. The compiler cannot check whether
11148 the operands have data types that are reasonable for the instruction being
11149 executed. For output expressions that are not directly addressable (for
11150 example a bit-field), the constraint must allow a register. In that case, GCC
11151 uses the register as the output of the @code{asm}, and then stores that
11152 register into the output.
11154 Operands using the @samp{+} constraint modifier count as two operands
11155 (that is, both as input and output) towards the total maximum of 30 operands
11156 per @code{asm} statement.
11158 Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output
11159 operands that must not overlap an input. Otherwise,
11160 GCC may allocate the output operand in the same register as an unrelated
11161 input operand, on the assumption that the assembler code consumes its
11162 inputs before producing outputs. This assumption may be false if the assembler
11163 code actually consists of more than one instruction.
11165 The same problem can occur if one output parameter (@var{a}) allows a register
11166 constraint and another output parameter (@var{b}) allows a memory constraint.
11167 The code generated by GCC to access the memory address in @var{b} can contain
11168 registers which @emph{might} be shared by @var{a}, and GCC considers those
11169 registers to be inputs to the asm. As above, GCC assumes that such input
11170 registers are consumed before any outputs are written. This assumption may
11171 result in incorrect behavior if the @code{asm} statement writes to @var{a}
11173 @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a}
11174 ensures that modifying @var{a} does not affect the address referenced by
11175 @var{b}. Otherwise, the location of @var{b}
11176 is undefined if @var{a} is modified before using @var{b}.
11178 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
11179 instead of simply @samp{%2}). @ref{GenericOperandmodifiers,
11180 Generic Operand modifiers} lists the modifiers that are available
11181 on all targets. Other modifiers are hardware dependent.
11182 For example, the list of supported modifiers for x86 is found at
11183 @ref{x86Operandmodifiers,x86 Operand modifiers}.
11185 If the C code that follows the @code{asm} makes no use of any of the output
11186 operands, use @code{volatile} for the @code{asm} statement to prevent the
11187 optimizers from discarding the @code{asm} statement as unneeded
11188 (see @ref{Volatile}).
11190 This code makes no use of the optional @var{asmSymbolicName}. Therefore it
11191 references the first output operand as @code{%0} (were there a second, it
11192 would be @code{%1}, etc). The number of the first input operand is one greater
11193 than that of the last output operand. In this i386 example, that makes
11194 @code{Mask} referenced as @code{%1}:
11197 uint32_t Mask = 1234;
11206 That code overwrites the variable @code{Index} (@samp{=}),
11207 placing the value in a register (@samp{r}).
11208 Using the generic @samp{r} constraint instead of a constraint for a specific
11209 register allows the compiler to pick the register to use, which can result
11210 in more efficient code. This may not be possible if an assembler instruction
11211 requires a specific register.
11213 The following i386 example uses the @var{asmSymbolicName} syntax.
11215 same result as the code above, but some may consider it more readable or more
11216 maintainable since reordering index numbers is not necessary when adding or
11217 removing operands. The names @code{aIndex} and @code{aMask}
11218 are only used in this example to emphasize which
11219 names get used where.
11220 It is acceptable to reuse the names @code{Index} and @code{Mask}.
11223 uint32_t Mask = 1234;
11226 asm ("bsfl %[aMask], %[aIndex]"
11227 : [aIndex] "=r" (Index)
11228 : [aMask] "r" (Mask)
11232 Here are some more examples of output operands.
11239 asm ("mov %[e], %[d]"
11244 Here, @code{d} may either be in a register or in memory. Since the compiler
11245 might already have the current value of the @code{uint32_t} location
11246 pointed to by @code{e}
11247 in a register, you can enable it to choose the best location
11248 for @code{d} by specifying both constraints.
11250 @anchor{FlagOutputOperands}
11251 @subsubsection Flag Output Operands
11252 @cindex @code{asm} flag output operands
11254 Some targets have a special register that holds the ``flags'' for the
11255 result of an operation or comparison. Normally, the contents of that
11256 register are either unmodifed by the asm, or the @code{asm} statement is
11257 considered to clobber the contents.
11259 On some targets, a special form of output operand exists by which
11260 conditions in the flags register may be outputs of the asm. The set of
11261 conditions supported are target specific, but the general rule is that
11262 the output variable must be a scalar integer, and the value is boolean.
11263 When supported, the target defines the preprocessor symbol
11264 @code{__GCC_ASM_FLAG_OUTPUTS__}.
11266 Because of the special nature of the flag output operands, the constraint
11267 may not include alternatives.
11269 Most often, the target has only one flags register, and thus is an implied
11270 operand of many instructions. In this case, the operand should not be
11271 referenced within the assembler template via @code{%0} etc, as there's
11272 no corresponding text in the assembly language.
11277 The flag output constraints for the ARM family are of the form
11278 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
11279 conditions defined in the ARM ARM for @code{ConditionHolds}.
11283 Z flag set, or equal
11285 Z flag clear or not equal
11288 C flag set or unsigned greater than equal
11291 C flag clear or unsigned less than
11293 N flag set or ``minus''
11295 N flag clear or ``plus''
11297 V flag set or signed overflow
11301 unsigned greater than
11303 unsigned less than equal
11305 signed greater than equal
11309 signed greater than
11311 signed less than equal
11314 The flag output constraints are not supported in thumb1 mode.
11317 The flag output constraints for the x86 family are of the form
11318 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
11319 conditions defined in the ISA manual for @code{j@var{cc}} or
11320 @code{set@var{cc}}.
11324 ``above'' or unsigned greater than
11326 ``above or equal'' or unsigned greater than or equal
11328 ``below'' or unsigned less than
11330 ``below or equal'' or unsigned less than or equal
11335 ``equal'' or zero flag set
11337 signed greater than
11339 signed greater than or equal
11343 signed less than or equal
11364 ``not'' @var{flag}, or inverted versions of those above
11368 The flag output constraint for s390 is @samp{=@@cc}. Only one such
11369 constraint is allowed. The variable has to be stored in a @samp{int}
11374 @anchor{InputOperands}
11375 @subsubsection Input Operands
11376 @cindex @code{asm} input operands
11377 @cindex @code{asm} expressions
11379 Input operands make values from C variables and expressions available to the
11382 Operands are separated by commas. Each operand has this format:
11385 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression})
11389 @item asmSymbolicName
11390 Specifies a symbolic name for the operand.
11391 Reference the name in the assembler template
11392 by enclosing it in square brackets
11393 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement
11394 that contains the definition. Any valid C variable name is acceptable,
11395 including names already defined in the surrounding code. No two operands
11396 within the same @code{asm} statement can use the same symbolic name.
11398 When not using an @var{asmSymbolicName}, use the (zero-based) position
11400 in the list of operands in the assembler template. For example if there are
11401 two output operands and three inputs,
11402 use @samp{%2} in the template to refer to the first input operand,
11403 @samp{%3} for the second, and @samp{%4} for the third.
11406 A string constant specifying constraints on the placement of the operand;
11407 @xref{Constraints}, for details.
11409 Input constraint strings may not begin with either @samp{=} or @samp{+}.
11410 When you list more than one possible location (for example, @samp{"irm"}),
11411 the compiler chooses the most efficient one based on the current context.
11412 If you must use a specific register, but your Machine Constraints do not
11413 provide sufficient control to select the specific register you want,
11414 local register variables may provide a solution (@pxref{Local Register
11417 Input constraints can also be digits (for example, @code{"0"}). This indicates
11418 that the specified input must be in the same place as the output constraint
11419 at the (zero-based) index in the output constraint list.
11420 When using @var{asmSymbolicName} syntax for the output operands,
11421 you may use these names (enclosed in brackets @samp{[]}) instead of digits.
11424 This is the C variable or expression being passed to the @code{asm} statement
11425 as input. The enclosing parentheses are a required part of the syntax.
11429 When the compiler selects the registers to use to represent the input
11430 operands, it does not use any of the clobbered registers
11431 (@pxref{Clobbers and Scratch Registers}).
11433 If there are no output operands but there are input operands, place two
11434 consecutive colons where the output operands would go:
11437 __asm__ ("some instructions"
11438 : /* No outputs. */
11439 : "r" (Offset / 8));
11442 @strong{Warning:} Do @emph{not} modify the contents of input-only operands
11443 (except for inputs tied to outputs). The compiler assumes that on exit from
11444 the @code{asm} statement these operands contain the same values as they
11445 had before executing the statement.
11446 It is @emph{not} possible to use clobbers
11447 to inform the compiler that the values in these inputs are changing. One
11448 common work-around is to tie the changing input variable to an output variable
11449 that never gets used. Note, however, that if the code that follows the
11450 @code{asm} statement makes no use of any of the output operands, the GCC
11451 optimizers may discard the @code{asm} statement as unneeded
11452 (see @ref{Volatile}).
11454 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
11455 instead of simply @samp{%2}). @ref{GenericOperandmodifiers,
11456 Generic Operand modifiers} lists the modifiers that are available
11457 on all targets. Other modifiers are hardware dependent.
11458 For example, the list of supported modifiers for x86 is found at
11459 @ref{x86Operandmodifiers,x86 Operand modifiers}.
11461 In this example using the fictitious @code{combine} instruction, the
11462 constraint @code{"0"} for input operand 1 says that it must occupy the same
11463 location as output operand 0. Only input operands may use numbers in
11464 constraints, and they must each refer to an output operand. Only a number (or
11465 the symbolic assembler name) in the constraint can guarantee that one operand
11466 is in the same place as another. The mere fact that @code{foo} is the value of
11467 both operands is not enough to guarantee that they are in the same place in
11468 the generated assembler code.
11471 asm ("combine %2, %0"
11473 : "0" (foo), "g" (bar));
11476 Here is an example using symbolic names.
11479 asm ("cmoveq %1, %2, %[result]"
11480 : [result] "=r"(result)
11481 : "r" (test), "r" (new), "[result]" (old));
11484 @anchor{Clobbers and Scratch Registers}
11485 @subsubsection Clobbers and Scratch Registers
11486 @cindex @code{asm} clobbers
11487 @cindex @code{asm} scratch registers
11489 While the compiler is aware of changes to entries listed in the output
11490 operands, the inline @code{asm} code may modify more than just the outputs. For
11491 example, calculations may require additional registers, or the processor may
11492 overwrite a register as a side effect of a particular assembler instruction.
11493 In order to inform the compiler of these changes, list them in the clobber
11494 list. Clobber list items are either register names or the special clobbers
11495 (listed below). Each clobber list item is a string constant
11496 enclosed in double quotes and separated by commas.
11498 Clobber descriptions may not in any way overlap with an input or output
11499 operand. For example, you may not have an operand describing a register class
11500 with one member when listing that register in the clobber list. Variables
11501 declared to live in specific registers (@pxref{Explicit Register
11502 Variables}) and used
11503 as @code{asm} input or output operands must have no part mentioned in the
11504 clobber description. In particular, there is no way to specify that input
11505 operands get modified without also specifying them as output operands.
11507 When the compiler selects which registers to use to represent input and output
11508 operands, it does not use any of the clobbered registers. As a result,
11509 clobbered registers are available for any use in the assembler code.
11511 Another restriction is that the clobber list should not contain the
11512 stack pointer register. This is because the compiler requires the
11513 value of the stack pointer to be the same after an @code{asm}
11514 statement as it was on entry to the statement. However, previous
11515 versions of GCC did not enforce this rule and allowed the stack
11516 pointer to appear in the list, with unclear semantics. This behavior
11517 is deprecated and listing the stack pointer may become an error in
11518 future versions of GCC@.
11520 Here is a realistic example for the VAX showing the use of clobbered
11524 asm volatile ("movc3 %0, %1, %2"
11525 : /* No outputs. */
11526 : "g" (from), "g" (to), "g" (count)
11527 : "r0", "r1", "r2", "r3", "r4", "r5", "memory");
11530 Also, there are two special clobber arguments:
11534 The @code{"cc"} clobber indicates that the assembler code modifies the flags
11535 register. On some machines, GCC represents the condition codes as a specific
11536 hardware register; @code{"cc"} serves to name this register.
11537 On other machines, condition code handling is different,
11538 and specifying @code{"cc"} has no effect. But
11539 it is valid no matter what the target.
11542 The @code{"memory"} clobber tells the compiler that the assembly code
11544 reads or writes to items other than those listed in the input and output
11545 operands (for example, accessing the memory pointed to by one of the input
11546 parameters). To ensure memory contains correct values, GCC may need to flush
11547 specific register values to memory before executing the @code{asm}. Further,
11548 the compiler does not assume that any values read from memory before an
11549 @code{asm} remain unchanged after that @code{asm}; it reloads them as
11551 Using the @code{"memory"} clobber effectively forms a read/write
11552 memory barrier for the compiler.
11554 Note that this clobber does not prevent the @emph{processor} from doing
11555 speculative reads past the @code{asm} statement. To prevent that, you need
11556 processor-specific fence instructions.
11560 Flushing registers to memory has performance implications and may be
11561 an issue for time-sensitive code. You can provide better information
11562 to GCC to avoid this, as shown in the following examples. At a
11563 minimum, aliasing rules allow GCC to know what memory @emph{doesn't}
11564 need to be flushed.
11566 Here is a fictitious sum of squares instruction, that takes two
11567 pointers to floating point values in memory and produces a floating
11568 point register output.
11569 Notice that @code{x}, and @code{y} both appear twice in the @code{asm}
11570 parameters, once to specify memory accessed, and once to specify a
11571 base register used by the @code{asm}. You won't normally be wasting a
11572 register by doing this as GCC can use the same register for both
11573 purposes. However, it would be foolish to use both @code{%1} and
11574 @code{%3} for @code{x} in this @code{asm} and expect them to be the
11575 same. In fact, @code{%3} may well not be a register. It might be a
11576 symbolic memory reference to the object pointed to by @code{x}.
11579 asm ("sumsq %0, %1, %2"
11581 : "r" (x), "r" (y), "m" (*x), "m" (*y));
11584 Here is a fictitious @code{*z++ = *x++ * *y++} instruction.
11585 Notice that the @code{x}, @code{y} and @code{z} pointer registers
11586 must be specified as input/output because the @code{asm} modifies
11590 asm ("vecmul %0, %1, %2"
11591 : "+r" (z), "+r" (x), "+r" (y), "=m" (*z)
11592 : "m" (*x), "m" (*y));
11595 An x86 example where the string memory argument is of unknown length.
11599 : "=c" (count), "+D" (p)
11600 : "m" (*(const char (*)[]) p), "0" (-1), "a" (0));
11603 If you know the above will only be reading a ten byte array then you
11604 could instead use a memory input like:
11605 @code{"m" (*(const char (*)[10]) p)}.
11607 Here is an example of a PowerPC vector scale implemented in assembly,
11608 complete with vector and condition code clobbers, and some initialized
11609 offset registers that are unchanged by the @code{asm}.
11613 dscal (size_t n, double *x, double alpha)
11615 asm ("/* lots of asm here */"
11616 : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x)
11617 : "d" (alpha), "b" (32), "b" (48), "b" (64),
11618 "b" (80), "b" (96), "b" (112)
11620 "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39",
11621 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47");
11625 Rather than allocating fixed registers via clobbers to provide scratch
11626 registers for an @code{asm} statement, an alternative is to define a
11627 variable and make it an early-clobber output as with @code{a2} and
11628 @code{a3} in the example below. This gives the compiler register
11629 allocator more freedom. You can also define a variable and make it an
11630 output tied to an input as with @code{a0} and @code{a1}, tied
11631 respectively to @code{ap} and @code{lda}. Of course, with tied
11632 outputs your @code{asm} can't use the input value after modifying the
11633 output register since they are one and the same register. What's
11634 more, if you omit the early-clobber on the output, it is possible that
11635 GCC might allocate the same register to another of the inputs if GCC
11636 could prove they had the same value on entry to the @code{asm}. This
11637 is why @code{a1} has an early-clobber. Its tied input, @code{lda}
11638 might conceivably be known to have the value 16 and without an
11639 early-clobber share the same register as @code{%11}. On the other
11640 hand, @code{ap} can't be the same as any of the other inputs, so an
11641 early-clobber on @code{a0} is not needed. It is also not desirable in
11642 this case. An early-clobber on @code{a0} would cause GCC to allocate
11643 a separate register for the @code{"m" (*(const double (*)[]) ap)}
11644 input. Note that tying an input to an output is the way to set up an
11645 initialized temporary register modified by an @code{asm} statement.
11646 An input not tied to an output is assumed by GCC to be unchanged, for
11647 example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might
11648 use that register in following code if the value 16 happened to be
11649 needed. You can even use a normal @code{asm} output for a scratch if
11650 all inputs that might share the same register are consumed before the
11651 scratch is used. The VSX registers clobbered by the @code{asm}
11652 statement could have used this technique except for GCC's limit on the
11653 number of @code{asm} parameters.
11657 dgemv_kernel_4x4 (long n, const double *ap, long lda,
11658 const double *x, double *y, double alpha)
11667 /* lots of asm here */
11668 "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n"
11669 "#a0=%3 a1=%4 a2=%5 a3=%6"
11671 "+m" (*(double (*)[n]) y),
11679 "m" (*(const double (*)[n]) x),
11680 "m" (*(const double (*)[]) ap),
11688 "vs32","vs33","vs34","vs35","vs36","vs37",
11689 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"
11694 @anchor{GotoLabels}
11695 @subsubsection Goto Labels
11696 @cindex @code{asm} goto labels
11698 @code{asm goto} allows assembly code to jump to one or more C labels. The
11699 @var{GotoLabels} section in an @code{asm goto} statement contains
11701 list of all C labels to which the assembler code may jump. GCC assumes that
11702 @code{asm} execution falls through to the next statement (if this is not the
11703 case, consider using the @code{__builtin_unreachable} intrinsic after the
11704 @code{asm} statement). Optimization of @code{asm goto} may be improved by
11705 using the @code{hot} and @code{cold} label attributes (@pxref{Label
11708 If the assembler code does modify anything, use the @code{"memory"} clobber
11710 optimizers to flush all register values to memory and reload them if
11711 necessary after the @code{asm} statement.
11713 Also note that an @code{asm goto} statement is always implicitly
11714 considered volatile.
11716 Be careful when you set output operands inside @code{asm goto} only on
11717 some possible control flow paths. If you don't set up the output on
11718 given path and never use it on this path, it is okay. Otherwise, you
11719 should use @samp{+} constraint modifier meaning that the operand is
11720 input and output one. With this modifier you will have the correct
11721 values on all possible paths from the @code{asm goto}.
11723 To reference a label in the assembler template, prefix it with
11724 @samp{%l} (lowercase @samp{L}) followed by its (zero-based) position
11725 in @var{GotoLabels} plus the number of input and output operands.
11726 Output operand with constraint modifier @samp{+} is counted as two
11727 operands because it is considered as one output and one input operand.
11728 For example, if the @code{asm} has three inputs, one output operand
11729 with constraint modifier @samp{+} and one output operand with
11730 constraint modifier @samp{=} and references two labels, refer to the
11731 first label as @samp{%l6} and the second as @samp{%l7}).
11733 Alternately, you can reference labels using the actual C label name
11734 enclosed in brackets. For example, to reference a label named
11735 @code{carry}, you can use @samp{%l[carry]}. The label must still be
11736 listed in the @var{GotoLabels} section when using this approach. It
11737 is better to use the named references for labels as in this case you
11738 can avoid counting input and output operands and special treatment of
11739 output operands with constraint modifier @samp{+}.
11741 Here is an example of @code{asm goto} for i386:
11747 : /* No outputs. */
11748 : "r" (p1), "r" (p2)
11758 The following example shows an @code{asm goto} that uses a memory clobber.
11764 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
11765 : /* No outputs. */
11775 The following example shows an @code{asm goto} that uses an output.
11780 asm goto ("dec %0; jb %l[stop]"
11791 The following artificial example shows an @code{asm goto} that sets
11792 up an output only on one path inside the @code{asm goto}. Usage of
11793 constraint modifier @code{=} instead of @code{+} would be wrong as
11794 @code{factor} is used on all paths from the @code{asm goto}.
11800 asm goto ("cmp %1, 10; jb %l[lab]; mov 2, %0"
11806 return inp * factor; /* return 2 * inp or 0 if inp < 10 */
11810 @anchor{GenericOperandmodifiers}
11811 @subsubsection Generic Operand Modifiers
11813 The following table shows the modifiers supported by all targets and their effects:
11815 @multitable @columnfractions 0.15 0.7 0.15
11816 @headitem Modifier @tab Description @tab Example
11818 @tab Require a constant operand and print the constant expression with no punctuation.
11821 @tab Like @samp{%c} except that the value of the constant is negated before printing.
11824 @tab Substitute a memory reference, with the actual operand treated as the address.
11825 This may be useful when outputting a ``load address'' instruction, because
11826 often the assembler syntax for such an instruction requires you to write the
11827 operand as if it were a memory reference.
11830 @tab Print the label name with no punctuation.
11834 @anchor{aarch64Operandmodifiers}
11835 @subsubsection AArch64 Operand Modifiers
11837 The following table shows the modifiers supported by AArch64 and their effects:
11839 @multitable @columnfractions .10 .90
11840 @headitem Modifier @tab Description
11841 @item @code{w} @tab Print a 32-bit general-purpose register name or, given a
11842 constant zero operand, the 32-bit zero register (@code{wzr}).
11843 @item @code{x} @tab Print a 64-bit general-purpose register name or, given a
11844 constant zero operand, the 64-bit zero register (@code{xzr}).
11845 @item @code{b} @tab Print an FP/SIMD register name with a @code{b} (byte, 8-bit)
11847 @item @code{h} @tab Print an FP/SIMD register name with an @code{h} (halfword,
11849 @item @code{s} @tab Print an FP/SIMD register name with an @code{s} (single
11850 word, 32-bit) prefix.
11851 @item @code{d} @tab Print an FP/SIMD register name with a @code{d} (doubleword,
11853 @item @code{q} @tab Print an FP/SIMD register name with a @code{q} (quadword,
11855 @item @code{Z} @tab Print an FP/SIMD register name as an SVE register (i.e. with
11856 a @code{z} prefix). This is a no-op for SVE register operands.
11859 @anchor{x86Operandmodifiers}
11860 @subsubsection x86 Operand Modifiers
11862 References to input, output, and goto operands in the assembler template
11863 of extended @code{asm} statements can use
11864 modifiers to affect the way the operands are formatted in
11865 the code output to the assembler. For example, the
11866 following code uses the @samp{h} and @samp{b} modifiers for x86:
11870 asm volatile ("xchg %h0, %b0" : "+a" (num) );
11874 These modifiers generate this assembler code:
11880 The rest of this discussion uses the following code for illustrative purposes.
11889 asm volatile goto ("some assembler instructions here"
11890 : /* No outputs. */
11891 : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42)
11892 : /* No clobbers. */
11897 With no modifiers, this is what the output from the operands would be
11898 for the @samp{att} and @samp{intel} dialects of assembler:
11900 @multitable {Operand} {$.L2} {OFFSET FLAT:.L2}
11901 @headitem Operand @tab @samp{att} @tab @samp{intel}
11910 @tab @code{OFFSET FLAT:.L3}
11922 The table below shows the list of supported modifiers and their effects.
11924 @multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}}
11925 @headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel}
11927 @tab Print an absolute memory reference.
11932 @tab Print the QImode name of the register.
11937 @tab print the opcode suffix of b.
11942 @tab Require a constant operand and print the constant expression with no punctuation.
11947 @tab print duplicated register operand for AVX instruction.
11949 @tab @code{%xmm0, %xmm0}
11950 @tab @code{xmm0, xmm0}
11952 @tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit.
11953 Otherwise mode is unspecified (VOIDmode).
11958 @tab Print the V16SFmode name of the register.
11963 @tab Print the QImode name for a ``high'' register.
11968 @tab Add 8 bytes to an offsettable memory reference. Useful when accessing the
11969 high 8 bytes of SSE values. For a memref in (%rax), it generates
11971 @tab @code{8(%rax)}
11974 @tab Print the SImode name of the register.
11979 @tab Print the label name with no punctuation.
11984 @tab print the opcode suffix of l.
11994 @tab Print raw symbol name (without syntax-specific prefixes).
11999 @tab If used for a function, print the PLT suffix and generate PIC code.
12000 For example, emit @code{foo@@PLT} instead of 'foo' for the function
12001 foo(). If used for a constant, drop all syntax-specific prefixes and
12002 issue the bare constant. See @code{p} above.
12004 @tab Print the DImode name of the register.
12009 @tab print the opcode suffix of q.
12014 @tab print embedded rounding and sae.
12016 @tab @code{@{rn-sae@}, }
12017 @tab @code{, @{rn-sae@}}
12019 @tab print only sae.
12021 @tab @code{@{sae@}, }
12022 @tab @code{, @{sae@}}
12024 @tab print a shift double count, followed by the assemblers argument
12025 delimiterprint the opcode suffix of s.
12030 @tab print the opcode suffix of s.
12035 @tab print the V8SFmode name of the register.
12040 @tab print the opcode suffix of t.
12045 @tab print naked full integer register name without %.
12050 @tab Print the HImode name of the register.
12055 @tab print the opcode suffix of w.
12060 @tab print the V4SFmode name of the register.
12065 @tab print "st(0)" instead of "st" as a register.
12070 @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}).
12075 @tab Like @code{z}, with special suffixes for x87 instructions.
12079 @anchor{x86floatingpointasmoperands}
12080 @subsubsection x86 Floating-Point @code{asm} Operands
12082 On x86 targets, there are several rules on the usage of stack-like registers
12083 in the operands of an @code{asm}. These rules apply only to the operands
12084 that are stack-like registers:
12088 Given a set of input registers that die in an @code{asm}, it is
12089 necessary to know which are implicitly popped by the @code{asm}, and
12090 which must be explicitly popped by GCC@.
12092 An input register that is implicitly popped by the @code{asm} must be
12093 explicitly clobbered, unless it is constrained to match an
12097 For any input register that is implicitly popped by an @code{asm}, it is
12098 necessary to know how to adjust the stack to compensate for the pop.
12099 If any non-popped input is closer to the top of the reg-stack than
12100 the implicitly popped register, it would not be possible to know what the
12101 stack looked like---it's not clear how the rest of the stack ``slides
12104 All implicitly popped input registers must be closer to the top of
12105 the reg-stack than any input that is not implicitly popped.
12107 It is possible that if an input dies in an @code{asm}, the compiler might
12108 use the input register for an output reload. Consider this example:
12111 asm ("foo" : "=t" (a) : "f" (b));
12115 This code says that input @code{b} is not popped by the @code{asm}, and that
12116 the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one
12117 deeper after the @code{asm} than it was before. But, it is possible that
12118 reload may think that it can use the same register for both the input and
12121 To prevent this from happening,
12122 if any input operand uses the @samp{f} constraint, all output register
12123 constraints must use the @samp{&} early-clobber modifier.
12125 The example above is correctly written as:
12128 asm ("foo" : "=&t" (a) : "f" (b));
12132 Some operands need to be in particular places on the stack. All
12133 output operands fall in this category---GCC has no other way to
12134 know which registers the outputs appear in unless you indicate
12135 this in the constraints.
12137 Output operands must specifically indicate which register an output
12138 appears in after an @code{asm}. @samp{=f} is not allowed: the operand
12139 constraints must select a class with a single register.
12142 Output operands may not be ``inserted'' between existing stack registers.
12143 Since no 387 opcode uses a read/write operand, all output operands
12144 are dead before the @code{asm}, and are pushed by the @code{asm}.
12145 It makes no sense to push anywhere but the top of the reg-stack.
12147 Output operands must start at the top of the reg-stack: output
12148 operands may not ``skip'' a register.
12151 Some @code{asm} statements may need extra stack space for internal
12152 calculations. This can be guaranteed by clobbering stack registers
12153 unrelated to the inputs and outputs.
12158 takes one input, which is internally popped, and produces two outputs.
12161 asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
12165 This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode,
12166 and replaces them with one output. The @code{st(1)} clobber is necessary
12167 for the compiler to know that @code{fyl2xp1} pops both inputs.
12170 asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
12173 @anchor{msp430Operandmodifiers}
12174 @subsubsection MSP430 Operand Modifiers
12176 The list below describes the supported modifiers and their effects for MSP430.
12178 @multitable @columnfractions .10 .90
12179 @headitem Modifier @tab Description
12180 @item @code{A} @tab Select low 16-bits of the constant/register/memory operand.
12181 @item @code{B} @tab Select high 16-bits of the constant/register/memory
12183 @item @code{C} @tab Select bits 32-47 of the constant/register/memory operand.
12184 @item @code{D} @tab Select bits 48-63 of the constant/register/memory operand.
12185 @item @code{H} @tab Equivalent to @code{B} (for backwards compatibility).
12186 @item @code{I} @tab Print the inverse (logical @code{NOT}) of the constant
12188 @item @code{J} @tab Print an integer without a @code{#} prefix.
12189 @item @code{L} @tab Equivalent to @code{A} (for backwards compatibility).
12190 @item @code{O} @tab Offset of the current frame from the top of the stack.
12191 @item @code{Q} @tab Use the @code{A} instruction postfix.
12192 @item @code{R} @tab Inverse of condition code, for unsigned comparisons.
12193 @item @code{W} @tab Subtract 16 from the constant value.
12194 @item @code{X} @tab Use the @code{X} instruction postfix.
12195 @item @code{Y} @tab Subtract 4 from the constant value.
12196 @item @code{Z} @tab Subtract 1 from the constant value.
12197 @item @code{b} @tab Append @code{.B}, @code{.W} or @code{.A} to the
12198 instruction, depending on the mode.
12199 @item @code{d} @tab Offset 1 byte of a memory reference or constant value.
12200 @item @code{e} @tab Offset 3 bytes of a memory reference or constant value.
12201 @item @code{f} @tab Offset 5 bytes of a memory reference or constant value.
12202 @item @code{g} @tab Offset 7 bytes of a memory reference or constant value.
12203 @item @code{p} @tab Print the value of 2, raised to the power of the given
12204 constant. Used to select the specified bit position.
12205 @item @code{r} @tab Inverse of condition code, for signed comparisons.
12206 @item @code{x} @tab Equivialent to @code{X}, but only for pointers.
12209 @anchor{loongarchOperandmodifiers}
12210 @subsubsection LoongArch Operand Modifiers
12212 The list below describes the supported modifiers and their effects for LoongArch.
12214 @multitable @columnfractions .10 .90
12215 @headitem Modifier @tab Description
12216 @item @code{d} @tab Same as @code{c}.
12217 @item @code{i} @tab Print the character ''@code{i}'' if the operand is not a register.
12218 @item @code{m} @tab Same as @code{c}, but the printed value is @code{operand - 1}.
12219 @item @code{u} @tab Print a LASX register.
12220 @item @code{w} @tab Print a LSX register.
12221 @item @code{X} @tab Print a constant integer operand in hexadecimal.
12222 @item @code{z} @tab Print the operand in its unmodified form, followed by a comma.
12225 References to input and output operands in the assembler template of extended
12226 asm statements can use modifiers to affect the way the operands are formatted
12227 in the code output to the assembler. For example, the following code uses the
12228 'w' modifier for LoongArch:
12233 #include <lsxintrin.h>
12238 __asm__ ("vadd.d %w0,%w1,%w2\n\t"
12248 The compile command for the test case is as follows:
12251 gcc test-asm.c -mlsx -S -o test-asm.s
12255 The assembly statement produces the following assembly code:
12258 vadd.d $vr0,$vr0,$vr1
12261 This is a 128-bit vector addition instruction, @code{c} (referred to in the
12262 template string as %0) is the output, and @code{a} (%1) and @code{b} (%2) are
12263 the inputs. @code{__m128i} is a vector data type defined in the file
12264 @code{lsxintrin.h} (@xref{LoongArch SX Vector Intrinsics}). The symbol '=f'
12265 represents a constraint using a floating-point register as an output type, and
12266 the 'f' in the input operand represents a constraint using a floating-point
12267 register operand, which can refer to the definition of a constraint
12268 (@xref{Constraints}) in gcc.
12270 @anchor{riscvOperandmodifiers}
12271 @subsubsection RISC-V Operand Modifiers
12273 The list below describes the supported modifiers and their effects for RISC-V.
12275 @multitable @columnfractions .10 .90
12276 @headitem Modifier @tab Description
12277 @item @code{z} @tab Print ''@code{zero}'' instead of 0 if the operand is an immediate with a value of zero.
12278 @item @code{i} @tab Print the character ''@code{i}'' if the operand is an immediate.
12286 @subsection Controlling Names Used in Assembler Code
12287 @cindex assembler names for identifiers
12288 @cindex names used in assembler code
12289 @cindex identifiers, names in assembler code
12291 You can specify the name to be used in the assembler code for a C
12292 function or variable by writing the @code{asm} (or @code{__asm__})
12293 keyword after the declarator.
12294 It is up to you to make sure that the assembler names you choose do not
12295 conflict with any other assembler symbols, or reference registers.
12297 @subsubheading Assembler names for data
12299 This sample shows how to specify the assembler name for data:
12302 int foo asm ("myfoo") = 2;
12306 This specifies that the name to be used for the variable @code{foo} in
12307 the assembler code should be @samp{myfoo} rather than the usual
12310 On systems where an underscore is normally prepended to the name of a C
12311 variable, this feature allows you to define names for the
12312 linker that do not start with an underscore.
12314 GCC does not support using this feature with a non-static local variable
12315 since such variables do not have assembler names. If you are
12316 trying to put the variable in a particular register, see
12317 @ref{Explicit Register Variables}.
12319 @subsubheading Assembler names for functions
12321 To specify the assembler name for functions, write a declaration for the
12322 function before its definition and put @code{asm} there, like this:
12325 int func (int x, int y) asm ("MYFUNC");
12327 int func (int x, int y)
12333 This specifies that the name to be used for the function @code{func} in
12334 the assembler code should be @code{MYFUNC}.
12336 @node Explicit Register Variables
12337 @subsection Variables in Specified Registers
12338 @anchor{Explicit Reg Vars}
12339 @cindex explicit register variables
12340 @cindex variables in specified registers
12341 @cindex specified registers
12343 GNU C allows you to associate specific hardware registers with C
12344 variables. In almost all cases, allowing the compiler to assign
12345 registers produces the best code. However under certain unusual
12346 circumstances, more precise control over the variable storage is
12349 Both global and local variables can be associated with a register. The
12350 consequences of performing this association are very different between
12351 the two, as explained in the sections below.
12354 * Global Register Variables:: Variables declared at global scope.
12355 * Local Register Variables:: Variables declared within a function.
12358 @node Global Register Variables
12359 @subsubsection Defining Global Register Variables
12360 @anchor{Global Reg Vars}
12361 @cindex global register variables
12362 @cindex registers, global variables in
12363 @cindex registers, global allocation
12365 You can define a global register variable and associate it with a specified
12366 register like this:
12369 register int *foo asm ("r12");
12373 Here @code{r12} is the name of the register that should be used. Note that
12374 this is the same syntax used for defining local register variables, but for
12375 a global variable the declaration appears outside a function. The
12376 @code{register} keyword is required, and cannot be combined with
12377 @code{static}. The register name must be a valid register name for the
12380 Do not use type qualifiers such as @code{const} and @code{volatile}, as
12381 the outcome may be contrary to expectations. In particular, using the
12382 @code{volatile} qualifier does not fully prevent the compiler from
12383 optimizing accesses to the register.
12385 Registers are a scarce resource on most systems and allowing the
12386 compiler to manage their usage usually results in the best code. However,
12387 under special circumstances it can make sense to reserve some globally.
12388 For example this may be useful in programs such as programming language
12389 interpreters that have a couple of global variables that are accessed
12392 After defining a global register variable, for the current compilation
12396 @item If the register is a call-saved register, call ABI is affected:
12397 the register will not be restored in function epilogue sequences after
12398 the variable has been assigned. Therefore, functions cannot safely
12399 return to callers that assume standard ABI.
12400 @item Conversely, if the register is a call-clobbered register, making
12401 calls to functions that use standard ABI may lose contents of the variable.
12402 Such calls may be created by the compiler even if none are evident in
12403 the original program, for example when libgcc functions are used to
12404 make up for unavailable instructions.
12405 @item Accesses to the variable may be optimized as usual and the register
12406 remains available for allocation and use in any computations, provided that
12407 observable values of the variable are not affected.
12408 @item If the variable is referenced in inline assembly, the type of access
12409 must be provided to the compiler via constraints (@pxref{Constraints}).
12410 Accesses from basic asms are not supported.
12413 Note that these points @emph{only} apply to code that is compiled with the
12414 definition. The behavior of code that is merely linked in (for example
12415 code from libraries) is not affected.
12417 If you want to recompile source files that do not actually use your global
12418 register variable so they do not use the specified register for any other
12419 purpose, you need not actually add the global register declaration to
12420 their source code. It suffices to specify the compiler option
12421 @option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the
12424 @subsubheading Declaring the variable
12426 Global register variables cannot have initial values, because an
12427 executable file has no means to supply initial contents for a register.
12429 When selecting a register, choose one that is normally saved and
12430 restored by function calls on your machine. This ensures that code
12431 which is unaware of this reservation (such as library routines) will
12432 restore it before returning.
12434 On machines with register windows, be sure to choose a global
12435 register that is not affected magically by the function call mechanism.
12437 @subsubheading Using the variable
12439 @cindex @code{qsort}, and global register variables
12440 When calling routines that are not aware of the reservation, be
12441 cautious if those routines call back into code which uses them. As an
12442 example, if you call the system library version of @code{qsort}, it may
12443 clobber your registers during execution, but (if you have selected
12444 appropriate registers) it will restore them before returning. However
12445 it will @emph{not} restore them before calling @code{qsort}'s comparison
12446 function. As a result, global values will not reliably be available to
12447 the comparison function unless the @code{qsort} function itself is rebuilt.
12449 Similarly, it is not safe to access the global register variables from signal
12450 handlers or from more than one thread of control. Unless you recompile
12451 them specially for the task at hand, the system library routines may
12452 temporarily use the register for other things. Furthermore, since the register
12453 is not reserved exclusively for the variable, accessing it from handlers of
12454 asynchronous signals may observe unrelated temporary values residing in the
12457 @cindex register variable after @code{longjmp}
12458 @cindex global register after @code{longjmp}
12459 @cindex value after @code{longjmp}
12462 On most machines, @code{longjmp} restores to each global register
12463 variable the value it had at the time of the @code{setjmp}. On some
12464 machines, however, @code{longjmp} does not change the value of global
12465 register variables. To be portable, the function that called @code{setjmp}
12466 should make other arrangements to save the values of the global register
12467 variables, and to restore them in a @code{longjmp}. This way, the same
12468 thing happens regardless of what @code{longjmp} does.
12470 @node Local Register Variables
12471 @subsubsection Specifying Registers for Local Variables
12472 @anchor{Local Reg Vars}
12473 @cindex local variables, specifying registers
12474 @cindex specifying registers for local variables
12475 @cindex registers for local variables
12477 You can define a local register variable and associate it with a specified
12478 register like this:
12481 register int *foo asm ("r12");
12485 Here @code{r12} is the name of the register that should be used. Note
12486 that this is the same syntax used for defining global register variables,
12487 but for a local variable the declaration appears within a function. The
12488 @code{register} keyword is required, and cannot be combined with
12489 @code{static}. The register name must be a valid register name for the
12492 Do not use type qualifiers such as @code{const} and @code{volatile}, as
12493 the outcome may be contrary to expectations. In particular, when the
12494 @code{const} qualifier is used, the compiler may substitute the
12495 variable with its initializer in @code{asm} statements, which may cause
12496 the corresponding operand to appear in a different register.
12498 As with global register variables, it is recommended that you choose
12499 a register that is normally saved and restored by function calls on your
12500 machine, so that calls to library routines will not clobber it.
12502 The only supported use for this feature is to specify registers
12503 for input and output operands when calling Extended @code{asm}
12504 (@pxref{Extended Asm}). This may be necessary if the constraints for a
12505 particular machine don't provide sufficient control to select the desired
12506 register. To force an operand into a register, create a local variable
12507 and specify the register name after the variable's declaration. Then use
12508 the local variable for the @code{asm} operand and specify any constraint
12509 letter that matches the register:
12512 register int *p1 asm ("r0") = @dots{};
12513 register int *p2 asm ("r1") = @dots{};
12514 register int *result asm ("r0");
12515 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
12518 @emph{Warning:} In the above example, be aware that a register (for example
12519 @code{r0}) can be call-clobbered by subsequent code, including function
12520 calls and library calls for arithmetic operators on other variables (for
12521 example the initialization of @code{p2}). In this case, use temporary
12522 variables for expressions between the register assignments:
12526 register int *p1 asm ("r0") = @dots{};
12527 register int *p2 asm ("r1") = t1;
12528 register int *result asm ("r0");
12529 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
12532 Defining a register variable does not reserve the register. Other than
12533 when invoking the Extended @code{asm}, the contents of the specified
12534 register are not guaranteed. For this reason, the following uses
12535 are explicitly @emph{not} supported. If they appear to work, it is only
12536 happenstance, and may stop working as intended due to (seemingly)
12537 unrelated changes in surrounding code, or even minor changes in the
12538 optimization of a future version of gcc:
12541 @item Passing parameters to or from Basic @code{asm}
12542 @item Passing parameters to or from Extended @code{asm} without using input
12543 or output operands.
12544 @item Passing parameters to or from routines written in assembler (or
12545 other languages) using non-standard calling conventions.
12548 Some developers use Local Register Variables in an attempt to improve
12549 gcc's allocation of registers, especially in large functions. In this
12550 case the register name is essentially a hint to the register allocator.
12551 While in some instances this can generate better code, improvements are
12552 subject to the whims of the allocator/optimizers. Since there are no
12553 guarantees that your improvements won't be lost, this usage of Local
12554 Register Variables is discouraged.
12556 On the MIPS platform, there is related use for local register variables
12557 with slightly different characteristics (@pxref{MIPS Coprocessors,,
12558 Defining coprocessor specifics for MIPS targets, gccint,
12559 GNU Compiler Collection (GCC) Internals}).
12561 @node Size of an asm
12562 @subsection Size of an @code{asm}
12564 Some targets require that GCC track the size of each instruction used
12565 in order to generate correct code. Because the final length of the
12566 code produced by an @code{asm} statement is only known by the
12567 assembler, GCC must make an estimate as to how big it will be. It
12568 does this by counting the number of instructions in the pattern of the
12569 @code{asm} and multiplying that by the length of the longest
12570 instruction supported by that processor. (When working out the number
12571 of instructions, it assumes that any occurrence of a newline or of
12572 whatever statement separator character is supported by the assembler ---
12573 typically @samp{;} --- indicates the end of an instruction.)
12575 Normally, GCC's estimate is adequate to ensure that correct
12576 code is generated, but it is possible to confuse the compiler if you use
12577 pseudo instructions or assembler macros that expand into multiple real
12578 instructions, or if you use assembler directives that expand to more
12579 space in the object file than is needed for a single instruction.
12580 If this happens then the assembler may produce a diagnostic saying that
12581 a label is unreachable.
12583 @cindex @code{asm inline}
12584 This size is also used for inlining decisions. If you use @code{asm inline}
12585 instead of just @code{asm}, then for inlining purposes the size of the asm
12586 is taken as the minimum size, ignoring how many instructions GCC thinks it is.
12588 @node Alternate Keywords
12589 @section Alternate Keywords
12590 @cindex alternate keywords
12591 @cindex keywords, alternate
12593 @option{-ansi} and the various @option{-std} options disable certain
12594 keywords. This causes trouble when you want to use GNU C extensions, or
12595 a general-purpose header file that should be usable by all programs,
12596 including ISO C programs. The keywords @code{asm}, @code{typeof} and
12597 @code{inline} are not available in programs compiled with
12598 @option{-ansi} or @option{-std} (although @code{inline} can be used in a
12599 program compiled with @option{-std=c99} or a later standard). The
12601 @code{restrict} is only available when @option{-std=gnu99} (which will
12602 eventually be the default) or @option{-std=c99} (or the equivalent
12603 @option{-std=iso9899:1999}), or an option for a later standard
12606 The way to solve these problems is to put @samp{__} at the beginning and
12607 end of each problematical keyword. For example, use @code{__asm__}
12608 instead of @code{asm}, and @code{__inline__} instead of @code{inline}.
12610 Other C compilers won't accept these alternative keywords; if you want to
12611 compile with another compiler, you can define the alternate keywords as
12612 macros to replace them with the customary keywords. It looks like this:
12616 #define __asm__ asm
12620 @findex __extension__
12622 @option{-pedantic} and other options cause warnings for many GNU C extensions.
12623 You can suppress such warnings using the keyword @code{__extension__}.
12628 Writing @code{__extension__} before an expression prevents warnings
12629 about extensions within that expression.
12635 [[__extension__ @dots{}]]
12638 suppresses warnings about using @samp{[[]]} attributes in C versions
12642 @code{__extension__} has no effect aside from this.
12644 @node Incomplete Enums
12645 @section Incomplete @code{enum} Types
12647 You can define an @code{enum} tag without specifying its possible values.
12648 This results in an incomplete type, much like what you get if you write
12649 @code{struct foo} without describing the elements. A later declaration
12650 that does specify the possible values completes the type.
12652 You cannot allocate variables or storage using the type while it is
12653 incomplete. However, you can work with pointers to that type.
12655 This extension may not be very useful, but it makes the handling of
12656 @code{enum} more consistent with the way @code{struct} and @code{union}
12659 This extension is not supported by GNU C++.
12661 @node Function Names
12662 @section Function Names as Strings
12663 @cindex @code{__func__} identifier
12664 @cindex @code{__FUNCTION__} identifier
12665 @cindex @code{__PRETTY_FUNCTION__} identifier
12667 GCC provides three magic constants that hold the name of the current
12668 function as a string. In C++11 and later modes, all three are treated
12669 as constant expressions and can be used in @code{constexpr} constexts.
12670 The first of these constants is @code{__func__}, which is part of
12673 The identifier @code{__func__} is implicitly declared by the translator
12674 as if, immediately following the opening brace of each function
12675 definition, the declaration
12678 static const char __func__[] = "function-name";
12682 appeared, where function-name is the name of the lexically-enclosing
12683 function. This name is the unadorned name of the function. As an
12684 extension, at file (or, in C++, namespace scope), @code{__func__}
12685 evaluates to the empty string.
12687 @code{__FUNCTION__} is another name for @code{__func__}, provided for
12688 backward compatibility with old versions of GCC.
12690 In C, @code{__PRETTY_FUNCTION__} is yet another name for
12691 @code{__func__}, except that at file scope (or, in C++, namespace scope),
12692 it evaluates to the string @code{"top level"}. In addition, in C++,
12693 @code{__PRETTY_FUNCTION__} contains the signature of the function as
12694 well as its bare name. For example, this program:
12697 extern "C" int printf (const char *, ...);
12703 printf ("__FUNCTION__ = %s\n", __FUNCTION__);
12704 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
12722 __PRETTY_FUNCTION__ = void a::sub(int)
12725 These identifiers are variables, not preprocessor macros, and may not
12726 be used to initialize @code{char} arrays or be concatenated with string
12729 @node Return Address
12730 @section Getting the Return or Frame Address of a Function
12732 These functions may be used to get information about the callers of a
12735 @defbuiltin{{void *} __builtin_return_address (unsigned int @var{level})}
12736 This function returns the return address of the current function, or of
12737 one of its callers. The @var{level} argument is number of frames to
12738 scan up the call stack. A value of @code{0} yields the return address
12739 of the current function, a value of @code{1} yields the return address
12740 of the caller of the current function, and so forth. When inlining
12741 the expected behavior is that the function returns the address of
12742 the function that is returned to. To work around this behavior use
12743 the @code{noinline} function attribute.
12745 The @var{level} argument must be a constant integer.
12747 On some machines it may be impossible to determine the return address of
12748 any function other than the current one; in such cases, or when the top
12749 of the stack has been reached, this function returns an unspecified
12750 value. In addition, @code{__builtin_frame_address} may be used
12751 to determine if the top of the stack has been reached.
12753 Additional post-processing of the returned value may be needed, see
12754 @code{__builtin_extract_return_addr}.
12756 The stored representation of the return address in memory may be different
12757 from the address returned by @code{__builtin_return_address}. For example,
12758 on AArch64 the stored address may be mangled with return address signing
12759 whereas the address returned by @code{__builtin_return_address} is not.
12761 Calling this function with a nonzero argument can have unpredictable
12762 effects, including crashing the calling program. As a result, calls
12763 that are considered unsafe are diagnosed when the @option{-Wframe-address}
12764 option is in effect. Such calls should only be made in debugging
12767 On targets where code addresses are representable as @code{void *},
12769 void *addr = __builtin_extract_return_addr (__builtin_return_address (0));
12771 gives the code address where the current function would return. For example,
12772 such an address may be used with @code{dladdr} or other interfaces that work
12773 with code addresses.
12776 @defbuiltin{{void *} __builtin_extract_return_addr (void *@var{addr})}
12777 The address as returned by @code{__builtin_return_address} may have to be fed
12778 through this function to get the actual encoded address. For example, on the
12779 31-bit S/390 platform the highest bit has to be masked out, or on SPARC
12780 platforms an offset has to be added for the true next instruction to be
12783 If no fixup is needed, this function simply passes through @var{addr}.
12786 @defbuiltin{{void *} __builtin_frob_return_addr (void *@var{addr})}
12787 This function does the reverse of @code{__builtin_extract_return_addr}.
12790 @defbuiltin{{void *} __builtin_frame_address (unsigned int @var{level})}
12791 This function is similar to @code{__builtin_return_address}, but it
12792 returns the address of the function frame rather than the return address
12793 of the function. Calling @code{__builtin_frame_address} with a value of
12794 @code{0} yields the frame address of the current function, a value of
12795 @code{1} yields the frame address of the caller of the current function,
12798 The frame is the area on the stack that holds local variables and saved
12799 registers. The frame address is normally the address of the first word
12800 pushed on to the stack by the function. However, the exact definition
12801 depends upon the processor and the calling convention. If the processor
12802 has a dedicated frame pointer register, and the function has a frame,
12803 then @code{__builtin_frame_address} returns the value of the frame
12806 On some machines it may be impossible to determine the frame address of
12807 any function other than the current one; in such cases, or when the top
12808 of the stack has been reached, this function returns @code{0} if
12809 the first frame pointer is properly initialized by the startup code.
12811 Calling this function with a nonzero argument can have unpredictable
12812 effects, including crashing the calling program. As a result, calls
12813 that are considered unsafe are diagnosed when the @option{-Wframe-address}
12814 option is in effect. Such calls should only be made in debugging
12818 @deftypefn {Built-in Function} {void *} __builtin_stack_address ()
12819 This function returns the stack pointer register, offset by
12820 @code{STACK_ADDRESS_OFFSET} if that's defined.
12822 Conceptually, the returned address returned by this built-in function is
12823 the boundary between the stack area allocated for use by its caller, and
12824 the area that could be modified by a function call, that the caller
12825 could safely zero-out before or after (but not during) the call
12828 Arguments for a callee may be preallocated as part of the caller's stack
12829 frame, or allocated on a per-call basis, depending on the target, so
12830 they may be on either side of this boundary.
12832 Even if the stack pointer is biased, the result is not. The register
12833 save area on SPARC is regarded as modifiable by calls, rather than as
12834 allocated for use by the caller function, since it is never in use while
12835 the caller function itself is running.
12837 Red zones that only leaf functions could use are also regarded as
12838 modifiable by calls, rather than as allocated for use by the caller.
12839 This is only theoretical, since leaf functions do not issue calls, but a
12840 constant offset makes this built-in function more predictable.
12843 @node Stack Scrubbing
12844 @section Stack scrubbing internal interfaces
12846 Stack scrubbing involves cooperation between a @code{strub} context,
12847 i.e., a function whose stack frame is to be zeroed-out, and its callers.
12848 The caller initializes a stack watermark, the @code{strub} context
12849 updates the watermark according to its stack use, and the caller zeroes
12850 it out once it regains control, whether by the callee's returning or by
12853 Each of these steps is performed by a different builtin function call.
12854 Calls to these builtins are introduced automatically, in response to
12855 @code{strub} attributes and command-line options; they are not expected
12856 to be explicitly called by source code.
12858 The functions that implement the builtins are available in libgcc but,
12859 depending on optimization levels, they are expanded internally, adjusted
12860 to account for inlining, and sometimes combined/deferred (e.g. passing
12861 the caller-supplied watermark on to callees, refraining from erasing
12862 stack areas that the caller will) to enable tail calls and to optimize
12865 @deftypefn {Built-in Function} {void} __builtin___strub_enter (void **@var{wmptr})
12866 This function initializes a stack @var{watermark} variable with the
12867 current top of the stack. A call to this builtin function is introduced
12868 before entering a @code{strub} context. It remains as a function call
12869 if optimization is not enabled.
12872 @deftypefn {Built-in Function} {void} __builtin___strub_update (void **@var{wmptr})
12873 This function updates a stack @var{watermark} variable with the current
12874 top of the stack, if it tops the previous watermark. A call to this
12875 builtin function is inserted within @code{strub} contexts, whenever
12876 additional stack space may have been used. It remains as a function
12877 call at optimization levels lower than 2.
12880 @deftypefn {Built-in Function} {void} __builtin___strub_leave (void **@var{wmptr})
12881 This function overwrites the memory area between the current top of the
12882 stack, and the @var{watermark}ed address. A call to this builtin
12883 function is inserted after leaving a @code{strub} context. It remains
12884 as a function call at optimization levels lower than 3, and it is guarded by
12885 a condition at level 2.
12888 @node Vector Extensions
12889 @section Using Vector Instructions through Built-in Functions
12891 On some targets, the instruction set contains SIMD vector instructions which
12892 operate on multiple values contained in one large register at the same time.
12893 For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used
12896 The first step in using these extensions is to provide the necessary data
12897 types. This should be done using an appropriate @code{typedef}:
12900 typedef int v4si __attribute__ ((vector_size (16)));
12904 The @code{int} type specifies the @dfn{base type} (which can be a
12905 @code{typedef}), while the attribute specifies the vector size for the
12906 variable, measured in bytes. For example, the declaration above causes
12907 the compiler to set the mode for the @code{v4si} type to be 16 bytes wide
12908 and divided into @code{int} sized units. For a 32-bit @code{int} this
12909 means a vector of 4 units of 4 bytes, and the corresponding mode of
12910 @code{foo} is @acronym{V4SI}.
12912 The @code{vector_size} attribute is only applicable to integral and
12913 floating scalars, although arrays, pointers, and function return values
12914 are allowed in conjunction with this construct. Only sizes that are
12915 positive power-of-two multiples of the base type size are currently allowed.
12917 All the basic integer types can be used as base types, both as signed
12918 and as unsigned: @code{char}, @code{short}, @code{int}, @code{long},
12919 @code{long long}. In addition, @code{float} and @code{double} can be
12920 used to build floating-point vector types.
12922 Specifying a combination that is not valid for the current architecture
12923 causes GCC to synthesize the instructions using a narrower mode.
12924 For example, if you specify a variable of type @code{V4SI} and your
12925 architecture does not allow for this specific SIMD type, GCC
12926 produces code that uses 4 @code{SIs}.
12928 The types defined in this manner can be used with a subset of normal C
12929 operations. Currently, GCC allows using the following operators
12930 on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@.
12932 The operations behave like C++ @code{valarrays}. Addition is defined as
12933 the addition of the corresponding elements of the operands. For
12934 example, in the code below, each of the 4 elements in @var{a} is
12935 added to the corresponding 4 elements in @var{b} and the resulting
12936 vector is stored in @var{c}.
12939 typedef int v4si __attribute__ ((vector_size (16)));
12946 Subtraction, multiplication, division, and the logical operations
12947 operate in a similar manner. Likewise, the result of using the unary
12948 minus or complement operators on a vector type is a vector whose
12949 elements are the negative or complemented values of the corresponding
12950 elements in the operand.
12952 It is possible to use shifting operators @code{<<}, @code{>>} on
12953 integer-type vectors. The operation is defined as following: @code{@{a0,
12954 a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1,
12955 @dots{}, an >> bn@}}@. Unlike OpenCL, values of @code{b} are not
12956 implicitly taken modulo bit width of the base type @code{B}, and the behavior
12957 is undefined if any @code{bi} is greater than or equal to @code{B}.
12959 In contrast to scalar operations in C and C++, operands of integer vector
12960 operations do not undergo integer promotions.
12962 Operands of binary vector operations must have the same number of
12965 For convenience, it is allowed to use a binary vector operation
12966 where one operand is a scalar. In that case the compiler transforms
12967 the scalar operand into a vector where each element is the scalar from
12968 the operation. The transformation happens only if the scalar could be
12969 safely converted to the vector-element type.
12970 Consider the following code.
12973 typedef int v4si __attribute__ ((vector_size (16)));
12978 a = b + 1; /* a = b + @{1,1,1,1@}; */
12979 a = 2 * b; /* a = @{2,2,2,2@} * b; */
12981 a = l + a; /* Error, cannot convert long to int. */
12984 Vectors can be subscripted as if the vector were an array with
12985 the same number of elements and base type. Out of bound accesses
12986 invoke undefined behavior at run time. Warnings for out of bound
12987 accesses for vector subscription can be enabled with
12988 @option{-Warray-bounds}.
12990 Vector comparison is supported with standard comparison
12991 operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be
12992 vector expressions of integer-type or real-type. Comparison between
12993 integer-type vectors and real-type vectors are not supported. The
12994 result of the comparison is a vector of the same width and number of
12995 elements as the comparison operands with a signed integral element
12998 Vectors are compared element-wise producing 0 when comparison is false
12999 and -1 (constant of the appropriate type where all bits are set)
13000 otherwise. Consider the following example.
13003 typedef int v4si __attribute__ ((vector_size (16)));
13005 v4si a = @{1,2,3,4@};
13006 v4si b = @{3,2,1,4@};
13009 c = a > b; /* The result would be @{0, 0,-1, 0@} */
13010 c = a == b; /* The result would be @{0,-1, 0,-1@} */
13013 In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where
13014 @code{b} and @code{c} are vectors of the same type and @code{a} is an
13015 integer vector with the same number of elements of the same size as @code{b}
13016 and @code{c}, computes all three arguments and creates a vector
13017 @code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in
13018 OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}.
13019 As in the case of binary operations, this syntax is also accepted when
13020 one of @code{b} or @code{c} is a scalar that is then transformed into a
13021 vector. If both @code{b} and @code{c} are scalars and the type of
13022 @code{true?b:c} has the same size as the element type of @code{a}, then
13023 @code{b} and @code{c} are converted to a vector type whose elements have
13024 this type and with the same number of elements as @code{a}.
13026 In C++, the logic operators @code{!, &&, ||} are available for vectors.
13027 @code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to
13028 @code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}.
13029 For mixed operations between a scalar @code{s} and a vector @code{v},
13030 @code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is
13031 short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}.
13033 @findex __builtin_shuffle
13034 Vector shuffling is available using functions
13035 @code{__builtin_shuffle (vec, mask)} and
13036 @code{__builtin_shuffle (vec0, vec1, mask)}.
13037 Both functions construct a permutation of elements from one or two
13038 vectors and return a vector of the same type as the input vector(s).
13039 The @var{mask} is an integral vector with the same width (@var{W})
13040 and element count (@var{N}) as the output vector.
13042 The elements of the input vectors are numbered in memory ordering of
13043 @var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The
13044 elements of @var{mask} are considered modulo @var{N} in the single-operand
13045 case and modulo @math{2*@var{N}} in the two-operand case.
13047 Consider the following example,
13050 typedef int v4si __attribute__ ((vector_size (16)));
13052 v4si a = @{1,2,3,4@};
13053 v4si b = @{5,6,7,8@};
13054 v4si mask1 = @{0,1,1,3@};
13055 v4si mask2 = @{0,4,2,5@};
13058 res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */
13059 res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */
13062 Note that @code{__builtin_shuffle} is intentionally semantically
13063 compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions.
13065 You can declare variables and use them in function calls and returns, as
13066 well as in assignments and some casts. You can specify a vector type as
13067 a return type for a function. Vector types can also be used as function
13068 arguments. It is possible to cast from one vector type to another,
13069 provided they are of the same size (in fact, you can also cast vectors
13070 to and from other datatypes of the same size).
13072 You cannot operate between vectors of different lengths or different
13073 signedness without a cast.
13075 @findex __builtin_shufflevector
13076 Vector shuffling is available using the
13077 @code{__builtin_shufflevector (vec1, vec2, index...)}
13078 function. @var{vec1} and @var{vec2} must be expressions with
13079 vector type with a compatible element type. The result of
13080 @code{__builtin_shufflevector} is a vector with the same element type
13081 as @var{vec1} and @var{vec2} but that has an element count equal to
13082 the number of indices specified.
13084 The @var{index} arguments are a list of integers that specify the
13085 elements indices of the first two vectors that should be extracted and
13086 returned in a new vector. These element indices are numbered sequentially
13087 starting with the first vector, continuing into the second vector.
13088 An index of -1 can be used to indicate that the corresponding element in
13089 the returned vector is a don't care and can be freely chosen to optimized
13090 the generated code sequence performing the shuffle operation.
13092 Consider the following example,
13094 typedef int v4si __attribute__ ((vector_size (16)));
13095 typedef int v8si __attribute__ ((vector_size (32)));
13097 v8si a = @{1,-2,3,-4,5,-6,7,-8@};
13098 v4si b = __builtin_shufflevector (a, a, 0, 2, 4, 6); /* b is @{1,3,5,7@} */
13099 v4si c = @{-2,-4,-6,-8@};
13100 v8si d = __builtin_shufflevector (c, b, 4, 0, 5, 1, 6, 2, 7, 3); /* d is a */
13103 @findex __builtin_convertvector
13104 Vector conversion is available using the
13105 @code{__builtin_convertvector (vec, vectype)}
13106 function. @var{vec} must be an expression with integral or floating
13107 vector type and @var{vectype} an integral or floating vector type with the
13108 same number of elements. The result has @var{vectype} type and value of
13109 a C cast of every element of @var{vec} to the element type of @var{vectype}.
13111 Consider the following example,
13113 typedef int v4si __attribute__ ((vector_size (16)));
13114 typedef float v4sf __attribute__ ((vector_size (16)));
13115 typedef double v4df __attribute__ ((vector_size (32)));
13116 typedef unsigned long long v4di __attribute__ ((vector_size (32)));
13118 v4si a = @{1,-2,3,-4@};
13119 v4sf b = @{1.5f,-2.5f,3.f,7.f@};
13120 v4di c = @{1ULL,5ULL,0ULL,10ULL@};
13121 v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */
13123 v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */
13124 v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */
13125 v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */
13126 v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */
13127 v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */
13130 @cindex vector types, using with x86 intrinsics
13131 Sometimes it is desirable to write code using a mix of generic vector
13132 operations (for clarity) and machine-specific vector intrinsics (to
13133 access vector instructions that are not exposed via generic built-ins).
13134 On x86, intrinsic functions for integer vectors typically use the same
13135 vector type @code{__m128i} irrespective of how they interpret the vector,
13136 making it necessary to cast their arguments and return values from/to
13137 other vector types. In C, you can make use of a @code{union} type:
13138 @c In C++ such type punning via a union is not allowed by the language
13140 #include <immintrin.h>
13142 typedef unsigned char u8x16 __attribute__ ((vector_size (16)));
13143 typedef unsigned int u32x4 __attribute__ ((vector_size (16)));
13153 for variables that can be used with both built-in operators and x86
13157 v128 x, y = @{ 0 @};
13158 memcpy (&x, ptr, sizeof x);
13160 x.mm = _mm_adds_epu8 (x.mm, y.mm);
13163 /* Instead of a variable, a compound literal may be used to pass the
13164 return value of an intrinsic call to a function expecting the union: */
13166 x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@});
13167 @c This could be done implicitly with __attribute__((transparent_union)),
13168 @c but GCC does not accept it for unions of vector types (PR 88955).
13172 @section Support for @code{offsetof}
13173 @findex __builtin_offsetof
13175 GCC implements for both C and C++ a syntactic extension to implement
13176 the @code{offsetof} macro.
13180 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
13182 offsetof_member_designator:
13184 | offsetof_member_designator "." @code{identifier}
13185 | offsetof_member_designator "[" @code{expr} "]"
13188 This extension is sufficient such that
13191 #define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member})
13195 is a suitable definition of the @code{offsetof} macro. In C++, @var{type}
13196 may be dependent. In either case, @var{member} may consist of a single
13197 identifier, or a sequence of member accesses and array references.
13199 @node __sync Builtins
13200 @section Legacy @code{__sync} Built-in Functions for Atomic Memory Access
13202 The following built-in functions
13203 are intended to be compatible with those described
13204 in the @cite{Intel Itanium Processor-specific Application Binary Interface},
13205 section 7.4. As such, they depart from normal GCC practice by not using
13206 the @samp{__builtin_} prefix and also by being overloaded so that they
13207 work on multiple types.
13209 The definition given in the Intel documentation allows only for the use of
13210 the types @code{int}, @code{long}, @code{long long} or their unsigned
13211 counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in
13212 size other than the C type @code{_Bool} or the C++ type @code{bool}.
13213 Operations on pointer arguments are performed as if the operands were
13214 of the @code{uintptr_t} type. That is, they are not scaled by the size
13215 of the type to which the pointer points.
13217 These functions are implemented in terms of the @samp{__atomic}
13218 builtins (@pxref{__atomic Builtins}). They should not be used for new
13219 code which should use the @samp{__atomic} builtins instead.
13221 Not all operations are supported by all target processors. If a particular
13222 operation cannot be implemented on the target processor, a warning is
13223 generated and a call to an external function is generated. The external
13224 function carries the same name as the built-in version,
13225 with an additional suffix
13226 @samp{_@var{n}} where @var{n} is the size of the data type.
13228 @c ??? Should we have a mechanism to suppress this warning? This is almost
13229 @c useful for implementing the operation under the control of an external
13232 In most cases, these built-in functions are considered a @dfn{full barrier}.
13234 no memory operand is moved across the operation, either forward or
13235 backward. Further, instructions are issued as necessary to prevent the
13236 processor from speculating loads across the operation and from queuing stores
13237 after the operation.
13239 All of the routines are described in the Intel documentation to take
13240 ``an optional list of variables protected by the memory barrier''. It's
13241 not clear what is meant by that; it could mean that @emph{only} the
13242 listed variables are protected, or it could mean a list of additional
13243 variables to be protected. The list is ignored by GCC which treats it as
13244 empty. GCC interprets an empty list as meaning that all globally
13245 accessible variables should be protected.
13247 @defbuiltin{@var{type} __sync_fetch_and_add (@var{type} *@var{ptr}, @var{type} @var{value}, ...)}
13248 @defbuiltinx{@var{type} __sync_fetch_and_sub (@var{type} *@var{ptr}, @var{type} @var{value}, ...)}
13249 @defbuiltinx{@var{type} __sync_fetch_and_or (@var{type} *@var{ptr}, @var{type} @var{value}, ...)}
13250 @defbuiltinx{@var{type} __sync_fetch_and_and (@var{type} *@var{ptr}, @var{type} @var{value}, ...)}
13251 @defbuiltinx{@var{type} __sync_fetch_and_xor (@var{type} *@var{ptr}, @var{type} @var{value}, ...)}
13252 @defbuiltinx{@var{type} __sync_fetch_and_nand (@var{type} *@var{ptr}, @var{type} @var{value}, ...)}
13253 These built-in functions perform the operation suggested by the name, and
13254 returns the value that had previously been in memory. That is, operations
13255 on integer operands have the following semantics. Operations on pointer
13256 arguments are performed as if the operands were of the @code{uintptr_t}
13257 type. That is, they are not scaled by the size of the type to which
13258 the pointer points.
13261 @{ tmp = *ptr; *ptr @var{op}= value; return tmp; @}
13262 @{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand
13265 The object pointed to by the first argument must be of integer or pointer
13266 type. It must not be a boolean type.
13268 @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand}
13269 as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}.
13272 @defbuiltin{@var{type} __sync_add_and_fetch (@var{type} *@var{ptr}, @
13273 @var{type} @var{value}, ...)}
13274 @defbuiltinx{@var{type} __sync_sub_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)}
13275 @defbuiltinx{@var{type} __sync_or_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)}
13276 @defbuiltinx{@var{type} __sync_and_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)}
13277 @defbuiltinx{@var{type} __sync_xor_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)}
13278 @defbuiltinx{@var{type} __sync_nand_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)}
13279 These built-in functions perform the operation suggested by the name, and
13280 return the new value. That is, operations on integer operands have
13281 the following semantics. Operations on pointer operands are performed as
13282 if the operand's type were @code{uintptr_t}.
13285 @{ *ptr @var{op}= value; return *ptr; @}
13286 @{ *ptr = ~(*ptr & value); return *ptr; @} // nand
13289 The same constraints on arguments apply as for the corresponding
13290 @code{__sync_op_and_fetch} built-in functions.
13292 @emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch}
13293 as @code{*ptr = ~(*ptr & value)} instead of
13294 @code{*ptr = ~*ptr & value}.
13297 @defbuiltin{bool __sync_bool_compare_and_swap (@var{type} *@var{ptr}, @var{type} @var{oldval}, @var{type} @var{newval}, ...)}
13298 @defbuiltinx{@var{type} __sync_val_compare_and_swap (@var{type} *@var{ptr}, @var{type} @var{oldval}, @var{type} @var{newval}, ...)}
13299 These built-in functions perform an atomic compare and swap.
13300 That is, if the current
13301 value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into
13304 The ``bool'' version returns @code{true} if the comparison is successful and
13305 @var{newval} is written. The ``val'' version returns the contents
13306 of @code{*@var{ptr}} before the operation.
13309 @defbuiltin{void __sync_synchronize (...)}
13310 This built-in function issues a full memory barrier.
13313 @defbuiltin{@var{type} __sync_lock_test_and_set (@var{type} *@var{ptr}, @var{type} @var{value}, ...)}
13314 This built-in function, as described by Intel, is not a traditional test-and-set
13315 operation, but rather an atomic exchange operation. It writes @var{value}
13316 into @code{*@var{ptr}}, and returns the previous contents of
13319 Many targets have only minimal support for such locks, and do not support
13320 a full exchange operation. In this case, a target may support reduced
13321 functionality here by which the @emph{only} valid value to store is the
13322 immediate constant 1. The exact value actually stored in @code{*@var{ptr}}
13323 is implementation defined.
13325 This built-in function is not a full barrier,
13326 but rather an @dfn{acquire barrier}.
13327 This means that references after the operation cannot move to (or be
13328 speculated to) before the operation, but previous memory stores may not
13329 be globally visible yet, and previous memory loads may not yet be
13333 @defbuiltin{void __sync_lock_release (@var{type} *@var{ptr}, ...)}
13334 This built-in function releases the lock acquired by
13335 @code{__sync_lock_test_and_set}.
13336 Normally this means writing the constant 0 to @code{*@var{ptr}}.
13338 This built-in function is not a full barrier,
13339 but rather a @dfn{release barrier}.
13340 This means that all previous memory stores are globally visible, and all
13341 previous memory loads have been satisfied, but following memory reads
13342 are not prevented from being speculated to before the barrier.
13345 @node __atomic Builtins
13346 @section Built-in Functions for Memory Model Aware Atomic Operations
13348 The following built-in functions approximately match the requirements
13349 for the C++11 memory model. They are all
13350 identified by being prefixed with @samp{__atomic} and most are
13351 overloaded so that they work with multiple types.
13353 These functions are intended to replace the legacy @samp{__sync}
13354 builtins. The main difference is that the memory order that is requested
13355 is a parameter to the functions. New code should always use the
13356 @samp{__atomic} builtins rather than the @samp{__sync} builtins.
13358 Note that the @samp{__atomic} builtins assume that programs will
13359 conform to the C++11 memory model. In particular, they assume
13360 that programs are free of data races. See the C++11 standard for
13361 detailed requirements.
13363 The @samp{__atomic} builtins can be used with any integral scalar or
13364 pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral
13365 types are also allowed if @samp{__int128} (@pxref{__int128}) is
13366 supported by the architecture.
13368 The four non-arithmetic functions (load, store, exchange, and
13369 compare_exchange) all have a generic version as well. This generic
13370 version works on any data type. It uses the lock-free built-in function
13371 if the specific data type size makes that possible; otherwise, an
13372 external call is left to be resolved at run time. This external call is
13373 the same format with the addition of a @samp{size_t} parameter inserted
13374 as the first parameter indicating the size of the object being pointed to.
13375 All objects must be the same size.
13377 There are 6 different memory orders that can be specified. These map
13378 to the C++11 memory orders with the same names, see the C++11 standard
13379 or the @uref{https://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki
13380 on atomic synchronization} for detailed definitions. Individual
13381 targets may also support additional memory orders for use on specific
13382 architectures. Refer to the target documentation for details of
13385 An atomic operation can both constrain code motion and
13386 be mapped to hardware instructions for synchronization between threads
13387 (e.g., a fence). To which extent this happens is controlled by the
13388 memory orders, which are listed here in approximately ascending order of
13389 strength. The description of each memory order is only meant to roughly
13390 illustrate the effects and is not a specification; see the C++11
13391 memory model for precise semantics.
13394 @item __ATOMIC_RELAXED
13395 Implies no inter-thread ordering constraints.
13396 @item __ATOMIC_CONSUME
13397 This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE}
13398 memory order because of a deficiency in C++11's semantics for
13399 @code{memory_order_consume}.
13400 @item __ATOMIC_ACQUIRE
13401 Creates an inter-thread happens-before constraint from the release (or
13402 stronger) semantic store to this acquire load. Can prevent hoisting
13403 of code to before the operation.
13404 @item __ATOMIC_RELEASE
13405 Creates an inter-thread happens-before constraint to acquire (or stronger)
13406 semantic loads that read from this release store. Can prevent sinking
13407 of code to after the operation.
13408 @item __ATOMIC_ACQ_REL
13409 Combines the effects of both @code{__ATOMIC_ACQUIRE} and
13410 @code{__ATOMIC_RELEASE}.
13411 @item __ATOMIC_SEQ_CST
13412 Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations.
13415 Note that in the C++11 memory model, @emph{fences} (e.g.,
13416 @samp{__atomic_thread_fence}) take effect in combination with other
13417 atomic operations on specific memory locations (e.g., atomic loads);
13418 operations on specific memory locations do not necessarily affect other
13419 operations in the same way.
13421 Target architectures are encouraged to provide their own patterns for
13422 each of the atomic built-in functions. If no target is provided, the original
13423 non-memory model set of @samp{__sync} atomic built-in functions are
13424 used, along with any required synchronization fences surrounding it in
13425 order to achieve the proper behavior. Execution in this case is subject
13426 to the same restrictions as those built-in functions.
13428 If there is no pattern or mechanism to provide a lock-free instruction
13429 sequence, a call is made to an external routine with the same parameters
13430 to be resolved at run time.
13432 When implementing patterns for these built-in functions, the memory order
13433 parameter can be ignored as long as the pattern implements the most
13434 restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory
13435 orders execute correctly with this memory order but they may not execute as
13436 efficiently as they could with a more appropriate implementation of the
13437 relaxed requirements.
13439 Note that the C++11 standard allows for the memory order parameter to be
13440 determined at run time rather than at compile time. These built-in
13441 functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather
13442 than invoke a runtime library call or inline a switch statement. This is
13443 standard compliant, safe, and the simplest approach for now.
13445 The memory order parameter is a signed int, but only the lower 16 bits are
13446 reserved for the memory order. The remainder of the signed int is reserved
13447 for target use and should be 0. Use of the predefined atomic values
13448 ensures proper usage.
13450 @defbuiltin{@var{type} __atomic_load_n (@var{type} *@var{ptr}, int @var{memorder})}
13451 This built-in function implements an atomic load operation. It returns the
13452 contents of @code{*@var{ptr}}.
13454 The valid memory order variants are
13455 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
13456 and @code{__ATOMIC_CONSUME}.
13460 @defbuiltin{void __atomic_load (@var{type} *@var{ptr}, @var{type} *@var{ret}, int @var{memorder})}
13461 This is the generic version of an atomic load. It returns the
13462 contents of @code{*@var{ptr}} in @code{*@var{ret}}.
13466 @defbuiltin{void __atomic_store_n (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})}
13467 This built-in function implements an atomic store operation. It writes
13468 @code{@var{val}} into @code{*@var{ptr}}.
13470 The valid memory order variants are
13471 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}.
13475 @defbuiltin{void __atomic_store (@var{type} *@var{ptr}, @var{type} *@var{val}, int @var{memorder})}
13476 This is the generic version of an atomic store. It stores the value
13477 of @code{*@var{val}} into @code{*@var{ptr}}.
13481 @defbuiltin{@var{type} __atomic_exchange_n (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})}
13482 This built-in function implements an atomic exchange operation. It writes
13483 @var{val} into @code{*@var{ptr}}, and returns the previous contents of
13486 All memory order variants are valid.
13490 @defbuiltin{void __atomic_exchange (@var{type} *@var{ptr}, @var{type} *@var{val}, @var{type} *@var{ret}, int @var{memorder})}
13491 This is the generic version of an atomic exchange. It stores the
13492 contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value
13493 of @code{*@var{ptr}} is copied into @code{*@var{ret}}.
13497 @defbuiltin{bool __atomic_compare_exchange_n (@var{type} *@var{ptr}, @var{type} *@var{expected}, @var{type} @var{desired}, bool @var{weak}, int @var{success_memorder}, int @var{failure_memorder})}
13498 This built-in function implements an atomic compare and exchange operation.
13499 This compares the contents of @code{*@var{ptr}} with the contents of
13500 @code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write}
13501 operation that writes @var{desired} into @code{*@var{ptr}}. If they are not
13502 equal, the operation is a @emph{read} and the current contents of
13503 @code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true}
13504 for weak compare_exchange, which may fail spuriously, and @code{false} for
13505 the strong variation, which never fails spuriously. Many targets
13506 only offer the strong variation and ignore the parameter. When in doubt, use
13507 the strong variation.
13509 If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned
13510 and memory is affected according to the
13511 memory order specified by @var{success_memorder}. There are no
13512 restrictions on what memory order can be used here.
13514 Otherwise, @code{false} is returned and memory is affected according
13515 to @var{failure_memorder}. This memory order cannot be
13516 @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a
13517 stronger order than that specified by @var{success_memorder}.
13521 @defbuiltin{bool __atomic_compare_exchange (@var{type} *@var{ptr}, @var{type} *@var{expected}, @var{type} *@var{desired}, bool @var{weak}, int @var{success_memorder}, int @var{failure_memorder})}
13522 This built-in function implements the generic version of
13523 @code{__atomic_compare_exchange}. The function is virtually identical to
13524 @code{__atomic_compare_exchange_n}, except the desired value is also a
13529 @defbuiltin{@var{type} __atomic_add_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})}
13530 @defbuiltinx{@var{type} __atomic_sub_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})}
13531 @defbuiltinx{@var{type} __atomic_and_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})}
13532 @defbuiltinx{@var{type} __atomic_xor_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})}
13533 @defbuiltinx{@var{type} __atomic_or_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})}
13534 @defbuiltinx{@var{type} __atomic_nand_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})}
13535 These built-in functions perform the operation suggested by the name, and
13536 return the result of the operation. Operations on pointer arguments are
13537 performed as if the operands were of the @code{uintptr_t} type. That is,
13538 they are not scaled by the size of the type to which the pointer points.
13541 @{ *ptr @var{op}= val; return *ptr; @}
13542 @{ *ptr = ~(*ptr & val); return *ptr; @} // nand
13545 The object pointed to by the first argument must be of integer or pointer
13546 type. It must not be a boolean type. All memory orders are valid.
13550 @defbuiltin{@var{type} __atomic_fetch_add (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})}
13551 @defbuiltinx{@var{type} __atomic_fetch_sub (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})}
13552 @defbuiltinx{@var{type} __atomic_fetch_and (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})}
13553 @defbuiltinx{@var{type} __atomic_fetch_xor (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})}
13554 @defbuiltinx{@var{type} __atomic_fetch_or (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})}
13555 @defbuiltinx{@var{type} __atomic_fetch_nand (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})}
13556 These built-in functions perform the operation suggested by the name, and
13557 return the value that had previously been in @code{*@var{ptr}}. Operations
13558 on pointer arguments are performed as if the operands were of
13559 the @code{uintptr_t} type. That is, they are not scaled by the size of
13560 the type to which the pointer points.
13563 @{ tmp = *ptr; *ptr @var{op}= val; return tmp; @}
13564 @{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand
13567 The same constraints on arguments apply as for the corresponding
13568 @code{__atomic_op_fetch} built-in functions. All memory orders are valid.
13572 @defbuiltin{bool __atomic_test_and_set (void *@var{ptr}, int @var{memorder})}
13574 This built-in function performs an atomic test-and-set operation on
13575 the byte at @code{*@var{ptr}}. The byte is set to some implementation
13576 defined nonzero ``set'' value and the return value is @code{true} if and only
13577 if the previous contents were ``set''.
13578 It should be only used for operands of type @code{bool} or @code{char}. For
13579 other types only part of the value may be set.
13581 All memory orders are valid.
13585 @defbuiltin{void __atomic_clear (bool *@var{ptr}, int @var{memorder})}
13587 This built-in function performs an atomic clear operation on
13588 @code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0.
13589 It should be only used for operands of type @code{bool} or @code{char} and
13590 in conjunction with @code{__atomic_test_and_set}.
13591 For other types it may only clear partially. If the type is not @code{bool}
13592 prefer using @code{__atomic_store}.
13594 The valid memory order variants are
13595 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and
13596 @code{__ATOMIC_RELEASE}.
13600 @defbuiltin{void __atomic_thread_fence (int @var{memorder})}
13602 This built-in function acts as a synchronization fence between threads
13603 based on the specified memory order.
13605 All memory orders are valid.
13609 @defbuiltin{void __atomic_signal_fence (int @var{memorder})}
13611 This built-in function acts as a synchronization fence between a thread
13612 and signal handlers based in the same thread.
13614 All memory orders are valid.
13618 @defbuiltin{bool __atomic_always_lock_free (size_t @var{size}, void *@var{ptr})}
13620 This built-in function returns @code{true} if objects of @var{size} bytes always
13621 generate lock-free atomic instructions for the target architecture.
13622 @var{size} must resolve to a compile-time constant and the result also
13623 resolves to a compile-time constant.
13625 @var{ptr} is an optional pointer to the object that may be used to determine
13626 alignment. A value of 0 indicates typical alignment should be used. The
13627 compiler may also ignore this parameter.
13630 if (__atomic_always_lock_free (sizeof (long long), 0))
13635 @defbuiltin{bool __atomic_is_lock_free (size_t @var{size}, void *@var{ptr})}
13637 This built-in function returns @code{true} if objects of @var{size} bytes always
13638 generate lock-free atomic instructions for the target architecture. If
13639 the built-in function is not known to be lock-free, a call is made to a
13640 runtime routine named @code{__atomic_is_lock_free}.
13642 @var{ptr} is an optional pointer to the object that may be used to determine
13643 alignment. A value of 0 indicates typical alignment should be used. The
13644 compiler may also ignore this parameter.
13647 @node Integer Overflow Builtins
13648 @section Built-in Functions to Perform Arithmetic with Overflow Checking
13650 The following built-in functions allow performing simple arithmetic operations
13651 together with checking whether the operations overflowed.
13653 @defbuiltin{bool __builtin_add_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})}
13654 @defbuiltinx{bool __builtin_sadd_overflow (int @var{a}, int @var{b}, int *@var{res})}
13655 @defbuiltinx{bool __builtin_saddl_overflow (long int @var{a}, long int @var{b}, long int *@var{res})}
13656 @defbuiltinx{bool __builtin_saddll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})}
13657 @defbuiltinx{bool __builtin_uadd_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})}
13658 @defbuiltinx{bool __builtin_uaddl_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})}
13659 @defbuiltinx{bool __builtin_uaddll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})}
13661 These built-in functions promote the first two operands into infinite precision signed
13662 type and perform addition on those promoted operands. The result is then
13663 cast to the type the third pointer argument points to and stored there.
13664 If the stored result is equal to the infinite precision result, the built-in
13665 functions return @code{false}, otherwise they return @code{true}. As the addition is
13666 performed in infinite signed precision, these built-in functions have fully defined
13667 behavior for all argument values.
13669 The first built-in function allows arbitrary integral types for operands and
13670 the result type must be pointer to some integral type other than enumerated or
13671 boolean type, the rest of the built-in functions have explicit integer types.
13673 The compiler will attempt to use hardware instructions to implement
13674 these built-in functions where possible, like conditional jump on overflow
13675 after addition, conditional jump on carry etc.
13679 @defbuiltin{bool __builtin_sub_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})}
13680 @defbuiltinx{bool __builtin_ssub_overflow (int @var{a}, int @var{b}, int *@var{res})}
13681 @defbuiltinx{bool __builtin_ssubl_overflow (long int @var{a}, long int @var{b}, long int *@var{res})}
13682 @defbuiltinx{bool __builtin_ssubll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})}
13683 @defbuiltinx{bool __builtin_usub_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})}
13684 @defbuiltinx{bool __builtin_usubl_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})}
13685 @defbuiltinx{bool __builtin_usubll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})}
13687 These built-in functions are similar to the add overflow checking built-in
13688 functions above, except they perform subtraction, subtract the second argument
13689 from the first one, instead of addition.
13693 @defbuiltin{bool __builtin_mul_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})}
13694 @defbuiltinx{bool __builtin_smul_overflow (int @var{a}, int @var{b}, int *@var{res})}
13695 @defbuiltinx{bool __builtin_smull_overflow (long int @var{a}, long int @var{b}, long int *@var{res})}
13696 @defbuiltinx{bool __builtin_smulll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})}
13697 @defbuiltinx{bool __builtin_umul_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})}
13698 @defbuiltinx{bool __builtin_umull_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})}
13699 @defbuiltinx{bool __builtin_umulll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})}
13701 These built-in functions are similar to the add overflow checking built-in
13702 functions above, except they perform multiplication, instead of addition.
13706 The following built-in functions allow checking if simple arithmetic operation
13709 @defbuiltin{bool __builtin_add_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})}
13710 @defbuiltinx{bool __builtin_sub_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})}
13711 @defbuiltinx{bool __builtin_mul_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})}
13713 These built-in functions are similar to @code{__builtin_add_overflow},
13714 @code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that
13715 they don't store the result of the arithmetic operation anywhere and the
13716 last argument is not a pointer, but some expression with integral type other
13717 than enumerated or boolean type.
13719 The built-in functions promote the first two operands into infinite precision signed type
13720 and perform addition on those promoted operands. The result is then
13721 cast to the type of the third argument. If the cast result is equal to the infinite
13722 precision result, the built-in functions return @code{false}, otherwise they return @code{true}.
13723 The value of the third argument is ignored, just the side effects in the third argument
13724 are evaluated, and no integral argument promotions are performed on the last argument.
13725 If the third argument is a bit-field, the type used for the result cast has the
13726 precision and signedness of the given bit-field, rather than precision and signedness
13727 of the underlying type.
13729 For example, the following macro can be used to portably check, at
13730 compile-time, whether or not adding two constant integers will overflow,
13731 and perform the addition only when it is known to be safe and not to trigger
13732 a @option{-Woverflow} warning.
13735 #define INT_ADD_OVERFLOW_P(a, b) \
13736 __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0)
13739 A = INT_MAX, B = 3,
13740 C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B,
13741 D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0)
13745 The compiler will attempt to use hardware instructions to implement
13746 these built-in functions where possible, like conditional jump on overflow
13747 after addition, conditional jump on carry etc.
13751 @defbuiltin{{unsigned int} __builtin_addc (unsigned int @var{a}, unsigned int @var{b}, unsigned int @var{carry_in}, unsigned int *@var{carry_out})}
13752 @defbuiltinx{{unsigned long int} __builtin_addcl (unsigned long int @var{a}, unsigned long int @var{b}, unsigned int @var{carry_in}, unsigned long int *@var{carry_out})}
13753 @defbuiltinx{{unsigned long long int} __builtin_addcll (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int @var{carry_in}, unsigned long long int *@var{carry_out})}
13755 These built-in functions are equivalent to:
13757 (@{ __typeof__ (@var{a}) s; \
13758 __typeof__ (@var{a}) c1 = __builtin_add_overflow (@var{a}, @var{b}, &s); \
13759 __typeof__ (@var{a}) c2 = __builtin_add_overflow (s, @var{carry_in}, &s); \
13760 *(@var{carry_out}) = c1 | c2; \
13764 i.e.@: they add 3 unsigned values, set what the last argument
13765 points to to 1 if any of the two additions overflowed (otherwise 0)
13766 and return the sum of those 3 unsigned values. Note, while all
13767 the first 3 arguments can have arbitrary values, better code will be
13768 emitted if one of them (preferrably the third one) has only values
13769 0 or 1 (i.e.@: carry-in).
13773 @defbuiltin{{unsigned int} __builtin_subc (unsigned int @var{a}, unsigned int @var{b}, unsigned int @var{carry_in}, unsigned int *@var{carry_out})}
13774 @defbuiltinx{{unsigned long int} __builtin_subcl (unsigned long int @var{a}, unsigned long int @var{b}, unsigned int @var{carry_in}, unsigned long int *@var{carry_out})}
13775 @defbuiltinx{{unsigned long long int} __builtin_subcll (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int @var{carry_in}, unsigned long long int *@var{carry_out})}
13777 These built-in functions are equivalent to:
13779 (@{ __typeof__ (@var{a}) s; \
13780 __typeof__ (@var{a}) c1 = __builtin_sub_overflow (@var{a}, @var{b}, &s); \
13781 __typeof__ (@var{a}) c2 = __builtin_sub_overflow (s, @var{carry_in}, &s); \
13782 *(@var{carry_out}) = c1 | c2; \
13786 i.e.@: they subtract 2 unsigned values from the first unsigned value,
13787 set what the last argument points to to 1 if any of the two subtractions
13788 overflowed (otherwise 0) and return the result of the subtractions.
13789 Note, while all the first 3 arguments can have arbitrary values, better code
13790 will be emitted if one of them (preferrably the third one) has only values
13791 0 or 1 (i.e.@: carry-in).
13795 @node x86 specific memory model extensions for transactional memory
13796 @section x86-Specific Memory Model Extensions for Transactional Memory
13798 The x86 architecture supports additional memory ordering flags
13799 to mark critical sections for hardware lock elision.
13800 These must be specified in addition to an existing memory order to
13804 @item __ATOMIC_HLE_ACQUIRE
13805 Start lock elision on a lock variable.
13806 Memory order must be @code{__ATOMIC_ACQUIRE} or stronger.
13807 @item __ATOMIC_HLE_RELEASE
13808 End lock elision on a lock variable.
13809 Memory order must be @code{__ATOMIC_RELEASE} or stronger.
13812 When a lock acquire fails, it is required for good performance to abort
13813 the transaction quickly. This can be done with a @code{_mm_pause}.
13816 #include <immintrin.h> // For _mm_pause
13820 /* Acquire lock with lock elision */
13821 while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE))
13822 _mm_pause(); /* Abort failed transaction */
13824 /* Free lock with lock elision */
13825 __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE);
13828 @node Object Size Checking
13829 @section Object Size Checking
13831 @subsection Object Size Checking Built-in Functions
13832 @findex __builtin___memcpy_chk
13833 @findex __builtin___mempcpy_chk
13834 @findex __builtin___memmove_chk
13835 @findex __builtin___memset_chk
13836 @findex __builtin___strcpy_chk
13837 @findex __builtin___stpcpy_chk
13838 @findex __builtin___strncpy_chk
13839 @findex __builtin___strcat_chk
13840 @findex __builtin___strncat_chk
13842 GCC implements a limited buffer overflow protection mechanism that can
13843 prevent some buffer overflow attacks by determining the sizes of objects
13844 into which data is about to be written and preventing the writes when
13845 the size isn't sufficient. The built-in functions described below yield
13846 the best results when used together and when optimization is enabled.
13847 For example, to detect object sizes across function boundaries or to
13848 follow pointer assignments through non-trivial control flow they rely
13849 on various optimization passes enabled with @option{-O2}. However, to
13850 a limited extent, they can be used without optimization as well.
13852 @defbuiltin{size_t __builtin_object_size (const void * @var{ptr}, int @var{type})}
13853 is a built-in construct that returns a constant number of bytes from
13854 @var{ptr} to the end of the object @var{ptr} pointer points to
13855 (if known at compile time). To determine the sizes of dynamically allocated
13856 objects the function relies on the allocation functions called to obtain
13857 the storage to be declared with the @code{alloc_size} attribute (@pxref{Common
13858 Function Attributes}). @code{__builtin_object_size} never evaluates
13859 its arguments for side effects. If there are any side effects in them, it
13860 returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
13861 for @var{type} 2 or 3. If there are multiple objects @var{ptr} can
13862 point to and all of them are known at compile time, the returned number
13863 is the maximum of remaining byte counts in those objects if @var{type} & 2 is
13864 0 and minimum if nonzero. If it is not possible to determine which objects
13865 @var{ptr} points to at compile time, @code{__builtin_object_size} should
13866 return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
13867 for @var{type} 2 or 3.
13869 @var{type} is an integer constant from 0 to 3. If the least significant
13870 bit is clear, objects are whole variables, if it is set, a closest
13871 surrounding subobject is considered the object a pointer points to.
13872 The second bit determines if maximum or minimum of remaining bytes
13876 struct V @{ char buf1[10]; int b; char buf2[10]; @} var;
13877 char *p = &var.buf1[1], *q = &var.b;
13879 /* Here the object p points to is var. */
13880 assert (__builtin_object_size (p, 0) == sizeof (var) - 1);
13881 /* The subobject p points to is var.buf1. */
13882 assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1);
13883 /* The object q points to is var. */
13884 assert (__builtin_object_size (q, 0)
13885 == (char *) (&var + 1) - (char *) &var.b);
13886 /* The subobject q points to is var.b. */
13887 assert (__builtin_object_size (q, 1) == sizeof (var.b));
13891 @defbuiltin{{size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type})}
13892 is similar to @code{__builtin_object_size} in that it returns a number of bytes
13893 from @var{ptr} to the end of the object @var{ptr} pointer points to, except
13894 that the size returned may not be a constant. This results in successful
13895 evaluation of object size estimates in a wider range of use cases and can be
13896 more precise than @code{__builtin_object_size}, but it incurs a performance
13897 penalty since it may add a runtime overhead on size computation. Semantics of
13898 @var{type} as well as return values in case it is not possible to determine
13899 which objects @var{ptr} points to at compile time are the same as in the case
13900 of @code{__builtin_object_size}.
13903 @subsection Object Size Checking and Source Fortification
13905 Hardening of function calls using the @code{_FORTIFY_SOURCE} macro is
13906 one of the key uses of the object size checking built-in functions. To
13907 make implementation of these features more convenient and improve
13908 optimization and diagnostics, there are built-in functions added for
13909 many common string operation functions, e.g., for @code{memcpy}
13910 @code{__builtin___memcpy_chk} built-in is provided. This built-in has
13911 an additional last argument, which is the number of bytes remaining in
13912 the object the @var{dest} argument points to or @code{(size_t) -1} if
13913 the size is not known.
13915 The built-in functions are optimized into the normal string functions
13916 like @code{memcpy} if the last argument is @code{(size_t) -1} or if
13917 it is known at compile time that the destination object will not
13918 be overflowed. If the compiler can determine at compile time that the
13919 object will always be overflowed, it issues a warning.
13921 The intended use can be e.g.@:
13925 #define bos0(dest) __builtin_object_size (dest, 0)
13926 #define memcpy(dest, src, n) \
13927 __builtin___memcpy_chk (dest, src, n, bos0 (dest))
13931 /* It is unknown what object p points to, so this is optimized
13932 into plain memcpy - no checking is possible. */
13933 memcpy (p, "abcde", n);
13934 /* Destination is known and length too. It is known at compile
13935 time there will be no overflow. */
13936 memcpy (&buf[5], "abcde", 5);
13937 /* Destination is known, but the length is not known at compile time.
13938 This will result in __memcpy_chk call that can check for overflow
13940 memcpy (&buf[5], "abcde", n);
13941 /* Destination is known and it is known at compile time there will
13942 be overflow. There will be a warning and __memcpy_chk call that
13943 will abort the program at run time. */
13944 memcpy (&buf[6], "abcde", 5);
13947 Such built-in functions are provided for @code{memcpy}, @code{mempcpy},
13948 @code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy},
13949 @code{strcat} and @code{strncat}.
13951 @subsubsection Formatted Output Function Checking
13952 @defbuiltin{int __builtin___sprintf_chk @
13953 (char *@var{s}, int @var{flag}, size_t @var{os}, @
13954 const char *@var{fmt}, ...)}
13955 @defbuiltinx{int __builtin___snprintf_chk @
13956 (char *@var{s}, size_t @var{maxlen}, int @var{flag}, @
13957 size_t @var{os}, const char *@var{fmt}, ...)}
13958 @defbuiltinx{int __builtin___vsprintf_chk @
13959 (char *@var{s}, int @var{flag}, size_t @var{os}, @
13960 const char *@var{fmt}, va_list @var{ap})}
13961 @defbuiltinx{int __builtin___vsnprintf_chk @
13962 (char *@var{s}, size_t @var{maxlen}, int @var{flag}, @
13963 size_t @var{os}, const char *@var{fmt}, @
13966 The added @var{flag} argument is passed unchanged to @code{__sprintf_chk}
13967 etc.@: functions and can contain implementation specific flags on what
13968 additional security measures the checking function might take, such as
13969 handling @code{%n} differently.
13971 The @var{os} argument is the object size @var{s} points to, like in the
13972 other built-in functions. There is a small difference in the behavior
13973 though, if @var{os} is @code{(size_t) -1}, the built-in functions are
13974 optimized into the non-checking functions only if @var{flag} is 0, otherwise
13975 the checking function is called with @var{os} argument set to
13976 @code{(size_t) -1}.
13978 In addition to this, there are checking built-in functions
13979 @code{__builtin___printf_chk}, @code{__builtin___vprintf_chk},
13980 @code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}.
13981 These have just one additional argument, @var{flag}, right before
13982 format string @var{fmt}. If the compiler is able to optimize them to
13983 @code{fputc} etc.@: functions, it does, otherwise the checking function
13984 is called and the @var{flag} argument passed to it.
13987 @node Other Builtins
13988 @section Other Built-in Functions Provided by GCC
13989 @cindex built-in functions
13990 @findex __builtin_iseqsig
13991 @findex __builtin_isfinite
13992 @findex __builtin_isnormal
13993 @findex __builtin_isgreater
13994 @findex __builtin_isgreaterequal
13995 @findex __builtin_isunordered
13996 @findex __builtin_speculation_safe_value
14157 @findex fprintf_unlocked
14159 @findex fputs_unlocked
14268 @findex nexttowardf
14269 @findex nexttowardl
14277 @findex printf_unlocked
14308 @findex signbitd128
14309 @findex significand
14310 @findex significandf
14311 @findex significandl
14339 @findex strncasecmp
14383 GCC provides a large number of built-in functions other than the ones
14384 mentioned above. Some of these are for internal use in the processing
14385 of exceptions or variable-length argument lists and are not
14386 documented here because they may change from time to time; we do not
14387 recommend general use of these functions.
14389 The remaining functions are provided for optimization purposes.
14391 With the exception of built-ins that have library equivalents such as
14392 the standard C library functions discussed below, or that expand to
14393 library calls, GCC built-in functions are always expanded inline and
14394 thus do not have corresponding entry points and their address cannot
14395 be obtained. Attempting to use them in an expression other than
14396 a function call results in a compile-time error.
14398 @opindex fno-builtin
14399 GCC includes built-in versions of many of the functions in the standard
14400 C library. These functions come in two forms: one whose names start with
14401 the @code{__builtin_} prefix, and the other without. Both forms have the
14402 same type (including prototype), the same address (when their address is
14403 taken), and the same meaning as the C library functions even if you specify
14404 the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these
14405 functions are only optimized in certain cases; if they are not optimized in
14406 a particular case, a call to the library function is emitted.
14410 Outside strict ISO C mode (@option{-ansi}, @option{-std=c90},
14411 @option{-std=c99} or @option{-std=c11}), the functions
14412 @code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero},
14413 @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml},
14414 @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll},
14415 @code{ffsl}, @code{ffs}, @code{fprintf_unlocked},
14416 @code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma},
14417 @code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext},
14418 @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0},
14419 @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn},
14420 @code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy},
14421 @code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked},
14422 @code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roundevenl},
14423 @code{scalbf}, @code{scalbl}, @code{scalb},
14424 @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32},
14425 @code{signbitd64}, @code{signbitd128}, @code{significandf},
14426 @code{significandl}, @code{significand}, @code{sincosf},
14427 @code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy},
14428 @code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp},
14429 @code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l},
14430 @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and
14432 may be handled as built-in functions.
14433 All these functions have corresponding versions
14434 prefixed with @code{__builtin_}, which may be used even in strict C90
14437 The ISO C99 functions
14438 @code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf},
14439 @code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh},
14440 @code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf},
14441 @code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos},
14442 @code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf},
14443 @code{casinhl}, @code{casinh}, @code{casinl}, @code{casin},
14444 @code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh},
14445 @code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt},
14446 @code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl},
14447 @code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf},
14448 @code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog},
14449 @code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl},
14450 @code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf},
14451 @code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal},
14452 @code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl},
14453 @code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf},
14454 @code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan},
14455 @code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl},
14456 @code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f},
14457 @code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim},
14458 @code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax},
14459 @code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf},
14460 @code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb},
14461 @code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf},
14462 @code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl},
14463 @code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround},
14464 @code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l},
14465 @code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf},
14466 @code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl},
14467 @code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint},
14468 @code{nextafterf}, @code{nextafterl}, @code{nextafter},
14469 @code{nexttowardf}, @code{nexttowardl}, @code{nexttoward},
14470 @code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof},
14471 @code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint},
14472 @code{roundf}, @code{roundl}, @code{round}, @code{scalblnf},
14473 @code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl},
14474 @code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal},
14475 @code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc},
14476 @code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf}
14477 are handled as built-in functions
14478 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
14480 There are also built-in versions of the ISO C99 functions
14481 @code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f},
14482 @code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill},
14483 @code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf},
14484 @code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl},
14485 @code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf},
14486 @code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl},
14487 @code{modfl}, @code{modff}, @code{powf}, @code{powl}, @code{sinf},
14488 @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl},
14489 @code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl}
14490 that are recognized in any mode since ISO C90 reserves these names for
14491 the purpose to which ISO C99 puts them. All these functions have
14492 corresponding versions prefixed with @code{__builtin_}.
14494 There are also built-in functions @code{__builtin_fabsf@var{n}},
14495 @code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and
14496 @code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3
14497 functions @code{fabsf@var{n}}, @code{fabsf@var{n}x},
14498 @code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported
14499 types @code{_Float@var{n}} and @code{_Float@var{n}x}.
14501 There are also GNU extension functions @code{clog10}, @code{clog10f} and
14502 @code{clog10l} which names are reserved by ISO C99 for future use.
14503 All these functions have versions prefixed with @code{__builtin_}.
14505 The ISO C94 functions
14506 @code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit},
14507 @code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct},
14508 @code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and
14510 are handled as built-in functions
14511 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
14513 The ISO C90 functions
14514 @code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2},
14515 @code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos},
14516 @code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod},
14517 @code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf},
14518 @code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit},
14519 @code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct},
14520 @code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower},
14521 @code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log},
14522 @code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy},
14523 @code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar},
14524 @code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin},
14525 @code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat},
14526 @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn},
14527 @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy},
14528 @code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr},
14529 @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf}
14530 are all recognized as built-in functions unless
14531 @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}}
14532 is specified for an individual function). All of these functions have
14533 corresponding versions prefixed with @code{__builtin_}.
14535 GCC provides built-in versions of the ISO C99 floating-point comparison
14536 macros that avoid raising exceptions for unordered operands. They have
14537 the same names as the standard macros ( @code{isgreater},
14538 @code{isgreaterequal}, @code{isless}, @code{islessequal},
14539 @code{islessgreater}, and @code{isunordered}) , with @code{__builtin_}
14540 prefixed. We intend for a library implementor to be able to simply
14541 @code{#define} each standard macro to its built-in equivalent.
14542 In the same fashion, GCC provides @code{fpclassify}, @code{iseqsig},
14543 @code{isfinite}, @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins
14544 used with @code{__builtin_} prefixed. The @code{isinf} and @code{isnan}
14545 built-in functions appear both with and without the @code{__builtin_} prefix.
14546 With @code{-ffinite-math-only} option the @code{isinf} and @code{isnan}
14547 built-in functions will always return 0.
14549 GCC provides built-in versions of the ISO C99 floating-point rounding and
14550 exceptions handling functions @code{fegetround}, @code{feclearexcept} and
14551 @code{feraiseexcept}. They may not be available for all targets, and because
14552 they need close interaction with libc internal values, they may not be available
14553 for all target libcs, but in all cases they will gracefully fallback to libc
14554 calls. These built-in functions appear both with and without the
14555 @code{__builtin_} prefix.
14557 @defbuiltin{{void *} __builtin_alloca (size_t @var{size})}
14558 The @code{__builtin_alloca} function must be called at block scope.
14559 The function allocates an object @var{size} bytes large on the stack
14560 of the calling function. The object is aligned on the default stack
14561 alignment boundary for the target determined by the
14562 @code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca}
14563 function returns a pointer to the first byte of the allocated object.
14564 The lifetime of the allocated object ends just before the calling
14565 function returns to its caller. This is so even when
14566 @code{__builtin_alloca} is called within a nested block.
14568 For example, the following function allocates eight objects of @code{n}
14569 bytes each on the stack, storing a pointer to each in consecutive elements
14570 of the array @code{a}. It then passes the array to function @code{g}
14571 which can safely use the storage pointed to by each of the array elements.
14574 void f (unsigned n)
14577 for (int i = 0; i != 8; ++i)
14578 a [i] = __builtin_alloca (n);
14580 g (a, n); // @r{safe}
14584 Since the @code{__builtin_alloca} function doesn't validate its argument
14585 it is the responsibility of its caller to make sure the argument doesn't
14586 cause it to exceed the stack size limit.
14587 The @code{__builtin_alloca} function is provided to make it possible to
14588 allocate on the stack arrays of bytes with an upper bound that may be
14589 computed at run time. Since C99 Variable Length Arrays offer
14590 similar functionality under a portable, more convenient, and safer
14591 interface they are recommended instead, in both C99 and C++ programs
14592 where GCC provides them as an extension.
14593 @xref{Variable Length}, for details.
14597 @defbuiltin{{void *} __builtin_alloca_with_align (size_t @var{size}, size_t @var{alignment})}
14598 The @code{__builtin_alloca_with_align} function must be called at block
14599 scope. The function allocates an object @var{size} bytes large on
14600 the stack of the calling function. The allocated object is aligned on
14601 the boundary specified by the argument @var{alignment} whose unit is given
14602 in bits (not bytes). The @var{size} argument must be positive and not
14603 exceed the stack size limit. The @var{alignment} argument must be a constant
14604 integer expression that evaluates to a power of 2 greater than or equal to
14605 @code{CHAR_BIT} and less than some unspecified maximum. Invocations
14606 with other values are rejected with an error indicating the valid bounds.
14607 The function returns a pointer to the first byte of the allocated object.
14608 The lifetime of the allocated object ends at the end of the block in which
14609 the function was called. The allocated storage is released no later than
14610 just before the calling function returns to its caller, but may be released
14611 at the end of the block in which the function was called.
14613 For example, in the following function the call to @code{g} is unsafe
14614 because when @code{overalign} is non-zero, the space allocated by
14615 @code{__builtin_alloca_with_align} may have been released at the end
14616 of the @code{if} statement in which it was called.
14619 void f (unsigned n, bool overalign)
14623 p = __builtin_alloca_with_align (n, 64 /* bits */);
14625 p = __builtin_alloc (n);
14627 g (p, n); // @r{unsafe}
14631 Since the @code{__builtin_alloca_with_align} function doesn't validate its
14632 @var{size} argument it is the responsibility of its caller to make sure
14633 the argument doesn't cause it to exceed the stack size limit.
14634 The @code{__builtin_alloca_with_align} function is provided to make
14635 it possible to allocate on the stack overaligned arrays of bytes with
14636 an upper bound that may be computed at run time. Since C99
14637 Variable Length Arrays offer the same functionality under
14638 a portable, more convenient, and safer interface they are recommended
14639 instead, in both C99 and C++ programs where GCC provides them as
14640 an extension. @xref{Variable Length}, for details.
14644 @defbuiltin{{void *} __builtin_alloca_with_align_and_max (size_t @var{size}, size_t @var{alignment}, size_t @var{max_size})}
14645 Similar to @code{__builtin_alloca_with_align} but takes an extra argument
14646 specifying an upper bound for @var{size} in case its value cannot be computed
14647 at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage}
14648 and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer
14649 expression, it has no effect on code generation and no attempt is made to
14650 check its compatibility with @var{size}.
14654 @defbuiltin{bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})}
14655 The @code{__builtin_has_attribute} function evaluates to an integer constant
14656 expression equal to @code{true} if the symbol or type referenced by
14657 the @var{type-or-expression} argument has been declared with
14658 the @var{attribute} referenced by the second argument. For
14659 an @var{type-or-expression} argument that does not reference a symbol,
14660 since attributes do not apply to expressions the built-in consider
14661 the type of the argument. Neither argument is evaluated.
14662 The @var{type-or-expression} argument is subject to the same
14663 restrictions as the argument to @code{typeof} (@pxref{Typeof}). The
14664 @var{attribute} argument is an attribute name optionally followed by
14665 a comma-separated list of arguments enclosed in parentheses. Both forms
14666 of attribute names---with and without double leading and trailing
14667 underscores---are recognized. @xref{Attribute Syntax}, for details.
14668 When no attribute arguments are specified for an attribute that expects
14669 one or more arguments the function returns @code{true} if
14670 @var{type-or-expression} has been declared with the attribute regardless
14671 of the attribute argument values. Arguments provided for an attribute
14672 that expects some are validated and matched up to the provided number.
14673 The function returns @code{true} if all provided arguments match. For
14674 example, the first call to the function below evaluates to @code{true}
14675 because @code{x} is declared with the @code{aligned} attribute but
14676 the second call evaluates to @code{false} because @code{x} is declared
14677 @code{aligned (8)} and not @code{aligned (4)}.
14680 __attribute__ ((aligned (8))) int x;
14681 _Static_assert (__builtin_has_attribute (x, aligned), "aligned");
14682 _Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)");
14685 Due to a limitation the @code{__builtin_has_attribute} function returns
14686 @code{false} for the @code{mode} attribute even if the type or variable
14687 referenced by the @var{type-or-expression} argument was declared with one.
14688 The function is also not supported with labels, and in C with enumerators.
14690 Note that unlike the @code{__has_attribute} preprocessor operator which
14691 is suitable for use in @code{#if} preprocessing directives
14692 @code{__builtin_has_attribute} is an intrinsic function that is not
14693 recognized in such contexts.
14697 @defbuiltin{@var{type} __builtin_speculation_safe_value (@var{type} @var{val}, @var{type} @var{failval})}
14699 This built-in function can be used to help mitigate against unsafe
14700 speculative execution. @var{type} may be any integral type or any
14705 If the CPU is not speculatively executing the code, then @var{val}
14708 If the CPU is executing speculatively then either:
14711 The function may cause execution to pause until it is known that the
14712 code is no-longer being executed speculatively (in which case
14713 @var{val} can be returned, as above); or
14715 The function may use target-dependent speculation tracking state to cause
14716 @var{failval} to be returned when it is known that speculative
14717 execution has incorrectly predicted a conditional branch operation.
14721 The second argument, @var{failval}, is optional and defaults to zero
14724 GCC defines the preprocessor macro
14725 @code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been
14726 updated to support this builtin.
14728 The built-in function can be used where a variable appears to be used in a
14729 safe way, but the CPU, due to speculative execution may temporarily ignore
14730 the bounds checks. Consider, for example, the following function:
14734 int f (unsigned untrusted_index)
14736 if (untrusted_index < 500)
14737 return array[untrusted_index];
14742 If the function is called repeatedly with @code{untrusted_index} less
14743 than the limit of 500, then a branch predictor will learn that the
14744 block of code that returns a value stored in @code{array} will be
14745 executed. If the function is subsequently called with an
14746 out-of-range value it will still try to execute that block of code
14747 first until the CPU determines that the prediction was incorrect
14748 (the CPU will unwind any incorrect operations at that point).
14749 However, depending on how the result of the function is used, it might be
14750 possible to leave traces in the cache that can reveal what was stored
14751 at the out-of-bounds location. The built-in function can be used to
14752 provide some protection against leaking data in this way by changing
14757 int f (unsigned untrusted_index)
14759 if (untrusted_index < 500)
14760 return array[__builtin_speculation_safe_value (untrusted_index)];
14765 The built-in function will either cause execution to stall until the
14766 conditional branch has been fully resolved, or it may permit
14767 speculative execution to continue, but using 0 instead of
14768 @code{untrusted_value} if that exceeds the limit.
14770 If accessing any memory location is potentially unsafe when speculative
14771 execution is incorrect, then the code can be rewritten as
14775 int f (unsigned untrusted_index)
14777 if (untrusted_index < 500)
14778 return *__builtin_speculation_safe_value (&array[untrusted_index], NULL);
14783 which will cause a @code{NULL} pointer to be used for the unsafe case.
14787 @defbuiltin{int __builtin_types_compatible_p (@var{type1}, @var{type2})}
14789 You can use the built-in function @code{__builtin_types_compatible_p} to
14790 determine whether two types are the same.
14792 This built-in function returns 1 if the unqualified versions of the
14793 types @var{type1} and @var{type2} (which are types, not expressions) are
14794 compatible, 0 otherwise. The result of this built-in function can be
14795 used in integer constant expressions.
14797 This built-in function ignores top level qualifiers (e.g., @code{const},
14798 @code{volatile}). For example, @code{int} is equivalent to @code{const
14801 The type @code{int[]} and @code{int[5]} are compatible. On the other
14802 hand, @code{int} and @code{char *} are not compatible, even if the size
14803 of their types, on the particular architecture are the same. Also, the
14804 amount of pointer indirection is taken into account when determining
14805 similarity. Consequently, @code{short *} is not similar to
14806 @code{short **}. Furthermore, two types that are typedefed are
14807 considered compatible if their underlying types are compatible.
14809 An @code{enum} type is not considered to be compatible with another
14810 @code{enum} type even if both are compatible with the same integer
14811 type; this is what the C standard specifies.
14812 For example, @code{enum @{foo, bar@}} is not similar to
14813 @code{enum @{hot, dog@}}.
14815 You typically use this function in code whose execution varies
14816 depending on the arguments' types. For example:
14821 typeof (x) tmp = (x); \
14822 if (__builtin_types_compatible_p (typeof (x), long double)) \
14823 tmp = foo_long_double (tmp); \
14824 else if (__builtin_types_compatible_p (typeof (x), double)) \
14825 tmp = foo_double (tmp); \
14826 else if (__builtin_types_compatible_p (typeof (x), float)) \
14827 tmp = foo_float (tmp); \
14834 @emph{Note:} This construct is only available for C@.
14838 @defbuiltin{@var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})}
14840 The @var{call_exp} expression must be a function call, and the
14841 @var{pointer_exp} expression must be a pointer. The @var{pointer_exp}
14842 is passed to the function call in the target's static chain location.
14843 The result of builtin is the result of the function call.
14845 @emph{Note:} This builtin is only available for C@.
14846 This builtin can be used to call Go closures from C.
14850 @defbuiltin{@var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})}
14852 You can use the built-in function @code{__builtin_choose_expr} to
14853 evaluate code depending on the value of a constant expression. This
14854 built-in function returns @var{exp1} if @var{const_exp}, which is an
14855 integer constant expression, is nonzero. Otherwise it returns @var{exp2}.
14857 This built-in function is analogous to the @samp{? :} operator in C,
14858 except that the expression returned has its type unaltered by promotion
14859 rules. Also, the built-in function does not evaluate the expression
14860 that is not chosen. For example, if @var{const_exp} evaluates to @code{true},
14861 @var{exp2} is not evaluated even if it has side effects.
14863 This built-in function can return an lvalue if the chosen argument is an
14866 If @var{exp1} is returned, the return type is the same as @var{exp1}'s
14867 type. Similarly, if @var{exp2} is returned, its return type is the same
14874 __builtin_choose_expr ( \
14875 __builtin_types_compatible_p (typeof (x), double), \
14877 __builtin_choose_expr ( \
14878 __builtin_types_compatible_p (typeof (x), float), \
14880 /* @r{The void expression results in a compile-time error} \
14881 @r{when assigning the result to something.} */ \
14885 @emph{Note:} This construct is only available for C@. Furthermore, the
14886 unused expression (@var{exp1} or @var{exp2} depending on the value of
14887 @var{const_exp}) may still generate syntax errors. This may change in
14892 @defbuiltin{@var{type} __builtin_tgmath (@var{functions}, @var{arguments})}
14894 The built-in function @code{__builtin_tgmath}, available only for C
14895 and Objective-C, calls a function determined according to the rules of
14896 @code{<tgmath.h>} macros. It is intended to be used in
14897 implementations of that header, so that expansions of macros from that
14898 header only expand each of their arguments once, to avoid problems
14899 when calls to such macros are nested inside the arguments of other
14900 calls to such macros; in addition, it results in better diagnostics
14901 for invalid calls to @code{<tgmath.h>} macros than implementations
14902 using other GNU C language features. For example, the @code{pow}
14903 type-generic macro might be defined as:
14906 #define pow(a, b) __builtin_tgmath (powf, pow, powl, \
14907 cpowf, cpow, cpowl, a, b)
14910 The arguments to @code{__builtin_tgmath} are at least two pointers to
14911 functions, followed by the arguments to the type-generic macro (which
14912 will be passed as arguments to the selected function). All the
14913 pointers to functions must be pointers to prototyped functions, none
14914 of which may have variable arguments, and all of which must have the
14915 same number of parameters; the number of parameters of the first
14916 function determines how many arguments to @code{__builtin_tgmath} are
14917 interpreted as function pointers, and how many as the arguments to the
14920 The types of the specified functions must all be different, but
14921 related to each other in the same way as a set of functions that may
14922 be selected between by a macro in @code{<tgmath.h>}. This means that
14923 the functions are parameterized by a floating-point type @var{t},
14924 different for each such function. The function return types may all
14925 be the same type, or they may be @var{t} for each function, or they
14926 may be the real type corresponding to @var{t} for each function (if
14927 some of the types @var{t} are complex). Likewise, for each parameter
14928 position, the type of the parameter in that position may always be the
14929 same type, or may be @var{t} for each function (this case must apply
14930 for at least one parameter position), or may be the real type
14931 corresponding to @var{t} for each function.
14933 The standard rules for @code{<tgmath.h>} macros are used to find a
14934 common type @var{u} from the types of the arguments for parameters
14935 whose types vary between the functions; complex integer types (a GNU
14936 extension) are treated like the complex type corresponding to the real
14937 floating type that would be chosen for the corresponding real integer type.
14938 If the function return types vary, or are all the same integer type,
14939 the function called is the one for which @var{t} is @var{u}, and it is
14940 an error if there is no such function. If the function return types
14941 are all the same floating-point type, the type-generic macro is taken
14942 to be one of those from TS 18661 that rounds the result to a narrower
14943 type; if there is a function for which @var{t} is @var{u}, it is
14944 called, and otherwise the first function, if any, for which @var{t}
14945 has at least the range and precision of @var{u} is called, and it is
14946 an error if there is no such function.
14950 @defbuiltin{int __builtin_constant_p (@var{exp})}
14951 You can use the built-in function @code{__builtin_constant_p} to
14952 determine if the expression @var{exp} is known to be constant at
14953 compile time and hence that GCC can perform constant-folding on expressions
14954 involving that value. The argument of the function is the expression to test.
14955 The expression is not evaluated, side-effects are discarded. The function
14956 returns the integer 1 if the argument is known to be a compile-time
14957 constant and 0 if it is not known to be a compile-time constant.
14958 Any expression that has side-effects makes the function return 0.
14959 A return of 0 does not indicate that the expression is @emph{not} a constant,
14960 but merely that GCC cannot prove it is a constant within the constraints
14961 of the active set of optimization options.
14963 You typically use this function in an embedded application where
14964 memory is a critical resource. If you have some complex calculation,
14965 you may want it to be folded if it involves constants, but need to call
14966 a function if it does not. For example:
14969 #define Scale_Value(X) \
14970 (__builtin_constant_p (X) \
14971 ? ((X) * SCALE + OFFSET) : Scale (X))
14974 You may use this built-in function in either a macro or an inline
14975 function. However, if you use it in an inlined function and pass an
14976 argument of the function as the argument to the built-in, GCC
14977 never returns 1 when you call the inline function with a string constant
14978 or compound literal (@pxref{Compound Literals}) and does not return 1
14979 when you pass a constant numeric value to the inline function unless you
14980 specify the @option{-O} option.
14982 You may also use @code{__builtin_constant_p} in initializers for static
14983 data. For instance, you can write
14986 static const int table[] = @{
14987 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
14993 This is an acceptable initializer even if @var{EXPRESSION} is not a
14994 constant expression, including the case where
14995 @code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be
14996 folded to a constant but @var{EXPRESSION} contains operands that are
14997 not otherwise permitted in a static initializer (for example,
14998 @code{0 && foo ()}). GCC must be more conservative about evaluating the
14999 built-in in this case, because it has no opportunity to perform
15003 @defbuiltin{bool __builtin_is_constant_evaluated (void)}
15004 The @code{__builtin_is_constant_evaluated} function is available only
15005 in C++. The built-in is intended to be used by implementations of
15006 the @code{std::is_constant_evaluated} C++ function. Programs should make
15007 use of the latter function rather than invoking the built-in directly.
15009 The main use case of the built-in is to determine whether a @code{constexpr}
15010 function is being called in a @code{constexpr} context. A call to
15011 the function evaluates to a core constant expression with the value
15012 @code{true} if and only if it occurs within the evaluation of an expression
15013 or conversion that is manifestly constant-evaluated as defined in the C++
15014 standard. Manifestly constant-evaluated contexts include constant-expressions,
15015 the conditions of @code{constexpr if} statements, constraint-expressions, and
15016 initializers of variables usable in constant expressions. For more details
15017 refer to the latest revision of the C++ standard.
15020 @defbuiltin{void __builtin_clear_padding (@var{ptr})}
15021 The built-in function @code{__builtin_clear_padding} function clears
15022 padding bits inside of the object representation of object pointed by
15023 @var{ptr}, which has to be a pointer. The value representation of the
15024 object is not affected. The type of the object is assumed to be the type
15025 the pointer points to. Inside of a union, the only cleared bits are
15026 bits that are padding bits for all the union members.
15028 This built-in-function is useful if the padding bits of an object might
15029 have intederminate values and the object representation needs to be
15030 bitwise compared to some other object, for example for atomic operations.
15032 For C++, @var{ptr} argument type should be pointer to trivially-copyable
15033 type, unless the argument is address of a variable or parameter, because
15034 otherwise it isn't known if the type isn't just a base class whose padding
15035 bits are reused or laid out differently in a derived class.
15038 @defbuiltin{@var{type} __builtin_bit_cast (@var{type}, @var{arg})}
15039 The @code{__builtin_bit_cast} function is available only
15040 in C++. The built-in is intended to be used by implementations of
15041 the @code{std::bit_cast} C++ template function. Programs should make
15042 use of the latter function rather than invoking the built-in directly.
15044 This built-in function allows reinterpreting the bits of the @var{arg}
15045 argument as if it had type @var{type}. @var{type} and the type of the
15046 @var{arg} argument need to be trivially copyable types with the same size.
15047 When manifestly constant-evaluated, it performs extra diagnostics required
15048 for @code{std::bit_cast} and returns a constant expression if @var{arg}
15049 is a constant expression. For more details
15050 refer to the latest revision of the C++ standard.
15053 @defbuiltin{long __builtin_expect (long @var{exp}, long @var{c})}
15054 @opindex fprofile-arcs
15055 You may use @code{__builtin_expect} to provide the compiler with
15056 branch prediction information. In general, you should prefer to
15057 use actual profile feedback for this (@option{-fprofile-arcs}), as
15058 programmers are notoriously bad at predicting how their programs
15059 actually perform. However, there are applications in which this
15060 data is hard to collect.
15062 The return value is the value of @var{exp}, which should be an integral
15063 expression. The semantics of the built-in are that it is expected that
15064 @var{exp} == @var{c}. For example:
15067 if (__builtin_expect (x, 0))
15072 indicates that we do not expect to call @code{foo}, since
15073 we expect @code{x} to be zero. Since you are limited to integral
15074 expressions for @var{exp}, you should use constructions such as
15077 if (__builtin_expect (ptr != NULL, 1))
15082 when testing pointer or floating-point values.
15084 For the purposes of branch prediction optimizations, the probability that
15085 a @code{__builtin_expect} expression is @code{true} is controlled by GCC's
15086 @code{builtin-expect-probability} parameter, which defaults to 90%.
15088 You can also use @code{__builtin_expect_with_probability} to explicitly
15089 assign a probability value to individual expressions. If the built-in
15090 is used in a loop construct, the provided probability will influence
15091 the expected number of iterations made by loop optimizations.
15094 @defbuiltin{long __builtin_expect_with_probability}
15095 (long @var{exp}, long @var{c}, double @var{probability})
15097 This function has the same semantics as @code{__builtin_expect},
15098 but the caller provides the expected probability that @var{exp} == @var{c}.
15099 The last argument, @var{probability}, is a floating-point value in the
15100 range 0.0 to 1.0, inclusive. The @var{probability} argument must be
15101 constant floating-point expression.
15104 @defbuiltin{void __builtin_trap (void)}
15105 This function causes the program to exit abnormally. GCC implements
15106 this function by using a target-dependent mechanism (such as
15107 intentionally executing an illegal instruction) or by calling
15108 @code{abort}. The mechanism used may vary from release to release so
15109 you should not rely on any particular implementation.
15112 @defbuiltin{void __builtin_unreachable (void)}
15113 If control flow reaches the point of the @code{__builtin_unreachable},
15114 the program is undefined. It is useful in situations where the
15115 compiler cannot deduce the unreachability of the code.
15117 One such case is immediately following an @code{asm} statement that
15118 either never terminates, or one that transfers control elsewhere
15119 and never returns. In this example, without the
15120 @code{__builtin_unreachable}, GCC issues a warning that control
15121 reaches the end of a non-void function. It also generates code
15122 to return after the @code{asm}.
15125 int f (int c, int v)
15133 asm("jmp error_handler");
15134 __builtin_unreachable ();
15140 Because the @code{asm} statement unconditionally transfers control out
15141 of the function, control never reaches the end of the function
15142 body. The @code{__builtin_unreachable} is in fact unreachable and
15143 communicates this fact to the compiler.
15145 Another use for @code{__builtin_unreachable} is following a call a
15146 function that never returns but that is not declared
15147 @code{__attribute__((noreturn))}, as in this example:
15150 void function_that_never_returns (void);
15160 function_that_never_returns ();
15161 __builtin_unreachable ();
15168 @defbuiltin{@var{type} __builtin_assoc_barrier (@var{type} @var{expr})}
15169 This built-in inhibits re-association of the floating-point expression
15170 @var{expr} with expressions consuming the return value of the built-in. The
15171 expression @var{expr} itself can be reordered, and the whole expression
15172 @var{expr} can be reordered with operands after the barrier. The barrier is
15173 only relevant when @code{-fassociative-math} is active, since otherwise
15174 floating-point is not treated as associative.
15177 float x0 = a + b - b;
15178 float x1 = __builtin_assoc_barrier(a + b) - b;
15182 means that, with @code{-fassociative-math}, @code{x0} can be optimized to
15183 @code{x0 = a} but @code{x1} cannot.
15186 @defbuiltin{{void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)}
15187 This function returns its first argument, and allows the compiler
15188 to assume that the returned pointer is at least @var{align} bytes
15189 aligned. This built-in can have either two or three arguments,
15190 if it has three, the third argument should have integer type, and
15191 if it is nonzero means misalignment offset. For example:
15194 void *x = __builtin_assume_aligned (arg, 16);
15198 means that the compiler can assume @code{x}, set to @code{arg}, is at least
15199 16-byte aligned, while:
15202 void *x = __builtin_assume_aligned (arg, 32, 8);
15206 means that the compiler can assume for @code{x}, set to @code{arg}, that
15207 @code{(char *) x - 8} is 32-byte aligned.
15210 @defbuiltin{int __builtin_LINE ()}
15211 This function is the equivalent of the preprocessor @code{__LINE__}
15212 macro and returns a constant integer expression that evaluates to
15213 the line number of the invocation of the built-in. When used as a C++
15214 default argument for a function @var{F}, it returns the line number
15215 of the call to @var{F}.
15218 @defbuiltin{{const char *} __builtin_FUNCTION ()}
15219 This function is the equivalent of the @code{__FUNCTION__} symbol
15220 and returns an address constant pointing to the name of the function
15221 from which the built-in was invoked, or the empty string if
15222 the invocation is not at function scope. When used as a C++ default
15223 argument for a function @var{F}, it returns the name of @var{F}'s
15224 caller or the empty string if the call was not made at function
15228 @defbuiltin{{const char *} __builtin_FILE ()}
15229 This function is the equivalent of the preprocessor @code{__FILE__}
15230 macro and returns an address constant pointing to the file name
15231 containing the invocation of the built-in, or the empty string if
15232 the invocation is not at function scope. When used as a C++ default
15233 argument for a function @var{F}, it returns the file name of the call
15234 to @var{F} or the empty string if the call was not made at function
15237 For example, in the following, each call to function @code{foo} will
15238 print a line similar to @code{"file.c:123: foo: message"} with the name
15239 of the file and the line number of the @code{printf} call, the name of
15240 the function @code{foo}, followed by the word @code{message}.
15244 function (const char *func = __builtin_FUNCTION ())
15251 printf ("%s:%i: %s: message\n", file (), line (), function ());
15257 @defbuiltin{void __builtin___clear_cache (void *@var{begin}, void *@var{end})}
15258 This function is used to flush the processor's instruction cache for
15259 the region of memory between @var{begin} inclusive and @var{end}
15260 exclusive. Some targets require that the instruction cache be
15261 flushed, after modifying memory containing code, in order to obtain
15262 deterministic behavior.
15264 If the target does not require instruction cache flushes,
15265 @code{__builtin___clear_cache} has no effect. Otherwise either
15266 instructions are emitted in-line to clear the instruction cache or a
15267 call to the @code{__clear_cache} function in libgcc is made.
15270 @defbuiltin{void __builtin_prefetch (const void *@var{addr}, ...)}
15271 This function is used to minimize cache-miss latency by moving data into
15272 a cache before it is accessed.
15273 You can insert calls to @code{__builtin_prefetch} into code for which
15274 you know addresses of data in memory that is likely to be accessed soon.
15275 If the target supports them, data prefetch instructions are generated.
15276 If the prefetch is done early enough before the access then the data will
15277 be in the cache by the time it is accessed.
15279 The value of @var{addr} is the address of the memory to prefetch.
15280 There are two optional arguments, @var{rw} and @var{locality}.
15281 The value of @var{rw} is a compile-time constant one or zero; one
15282 means that the prefetch is preparing for a write to the memory address
15283 and zero, the default, means that the prefetch is preparing for a read.
15284 The value @var{locality} must be a compile-time constant integer between
15285 zero and three. A value of zero means that the data has no temporal
15286 locality, so it need not be left in the cache after the access. A value
15287 of three means that the data has a high degree of temporal locality and
15288 should be left in all levels of cache possible. Values of one and two
15289 mean, respectively, a low or moderate degree of temporal locality. The
15293 for (i = 0; i < n; i++)
15295 a[i] = a[i] + b[i];
15296 __builtin_prefetch (&a[i+j], 1, 1);
15297 __builtin_prefetch (&b[i+j], 0, 1);
15302 Data prefetch does not generate faults if @var{addr} is invalid, but
15303 the address expression itself must be valid. For example, a prefetch
15304 of @code{p->next} does not fault if @code{p->next} is not a valid
15305 address, but evaluation faults if @code{p} is not a valid address.
15307 If the target does not support data prefetch, the address expression
15308 is evaluated if it includes side effects but no other code is generated
15309 and GCC does not issue a warning.
15312 @defbuiltin{{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})}
15313 Returns a constant size estimate of an object pointed to by @var{ptr}.
15314 @xref{Object Size Checking}, for a detailed description of the function.
15317 @defbuiltin{{size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type})}
15318 Similar to @code{__builtin_object_size} except that the return value
15319 need not be a constant. @xref{Object Size Checking}, for a detailed
15320 description of the function.
15323 @defbuiltin{int __builtin_classify_type (@var{arg})}
15324 @defbuiltinx{int __builtin_classify_type (@var{type})}
15325 The @code{__builtin_classify_type} returns a small integer with a category
15326 of @var{arg} argument's type, like void type, integer type, enumeral type,
15327 boolean type, pointer type, reference type, offset type, real type, complex
15328 type, function type, method type, record type, union type, array type,
15329 string type, bit-precise integer type, vector type, etc. When the argument
15330 is an expression, for backwards compatibility reason the argument is promoted
15331 like arguments passed to @code{...} in varargs function, so some classes are
15332 never returned in certain languages. Alternatively, the argument of the
15333 built-in function can be a typename, such as the @code{typeof} specifier.
15337 __builtin_classify_type (a) == __builtin_classify_type (int[5]);
15338 __builtin_classify_type (a) == __builtin_classify_type (void*);
15339 __builtin_classify_type (typeof (a)) == __builtin_classify_type (int[5]);
15342 The first comparison will never be true, as @var{a} is implicitly converted
15343 to pointer. The last two comparisons will be true as they classify
15344 pointers in the second case and arrays in the last case.
15347 @defbuiltin{double __builtin_huge_val (void)}
15348 Returns a positive infinity, if supported by the floating-point format,
15349 else @code{DBL_MAX}. This function is suitable for implementing the
15350 ISO C macro @code{HUGE_VAL}.
15353 @defbuiltin{float __builtin_huge_valf (void)}
15354 Similar to @code{__builtin_huge_val}, except the return type is @code{float}.
15357 @defbuiltin{{long double} __builtin_huge_vall (void)}
15358 Similar to @code{__builtin_huge_val}, except the return
15359 type is @code{long double}.
15362 @defbuiltin{_Float@var{n} __builtin_huge_valf@var{n} (void)}
15363 Similar to @code{__builtin_huge_val}, except the return type is
15364 @code{_Float@var{n}}.
15367 @defbuiltin{_Float@var{n}x __builtin_huge_valf@var{n}x (void)}
15368 Similar to @code{__builtin_huge_val}, except the return type is
15369 @code{_Float@var{n}x}.
15372 @defbuiltin{int __builtin_fpclassify (int, int, int, int, int, ...)}
15373 This built-in implements the C99 fpclassify functionality. The first
15374 five int arguments should be the target library's notion of the
15375 possible FP classes and are used for return values. They must be
15376 constant values and they must appear in this order: @code{FP_NAN},
15377 @code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and
15378 @code{FP_ZERO}. The ellipsis is for exactly one floating-point value
15379 to classify. GCC treats the last argument as type-generic, which
15380 means it does not do default promotion from float to double.
15383 @defbuiltin{double __builtin_inf (void)}
15384 Similar to @code{__builtin_huge_val}, except a warning is generated
15385 if the target floating-point format does not support infinities.
15388 @defbuiltin{_Decimal32 __builtin_infd32 (void)}
15389 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}.
15392 @defbuiltin{_Decimal64 __builtin_infd64 (void)}
15393 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}.
15396 @defbuiltin{_Decimal128 __builtin_infd128 (void)}
15397 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}.
15400 @defbuiltin{float __builtin_inff (void)}
15401 Similar to @code{__builtin_inf}, except the return type is @code{float}.
15402 This function is suitable for implementing the ISO C99 macro @code{INFINITY}.
15405 @defbuiltin{{long double} __builtin_infl (void)}
15406 Similar to @code{__builtin_inf}, except the return
15407 type is @code{long double}.
15410 @defbuiltin{_Float@var{n} __builtin_inff@var{n} (void)}
15411 Similar to @code{__builtin_inf}, except the return
15412 type is @code{_Float@var{n}}.
15415 @defbuiltin{_Float@var{n} __builtin_inff@var{n}x (void)}
15416 Similar to @code{__builtin_inf}, except the return
15417 type is @code{_Float@var{n}x}.
15420 @defbuiltin{int __builtin_isinf_sign (...)}
15421 Similar to @code{isinf}, except the return value is -1 for
15422 an argument of @code{-Inf} and 1 for an argument of @code{+Inf}.
15423 Note while the parameter list is an
15424 ellipsis, this function only accepts exactly one floating-point
15425 argument. GCC treats this parameter as type-generic, which means it
15426 does not do default promotion from float to double.
15429 @defbuiltin{double __builtin_nan (const char *@var{str})}
15430 This is an implementation of the ISO C99 function @code{nan}.
15432 Since ISO C99 defines this function in terms of @code{strtod}, which we
15433 do not implement, a description of the parsing is in order. The string
15434 is parsed as by @code{strtol}; that is, the base is recognized by
15435 leading @samp{0} or @samp{0x} prefixes. The number parsed is placed
15436 in the significand such that the least significant bit of the number
15437 is at the least significant bit of the significand. The number is
15438 truncated to fit the significand field provided. The significand is
15439 forced to be a quiet NaN@.
15441 This function, if given a string literal all of which would have been
15442 consumed by @code{strtol}, is evaluated early enough that it is considered a
15443 compile-time constant.
15446 @defbuiltin{_Decimal32 __builtin_nand32 (const char *@var{str})}
15447 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}.
15450 @defbuiltin{_Decimal64 __builtin_nand64 (const char *@var{str})}
15451 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}.
15454 @defbuiltin{_Decimal128 __builtin_nand128 (const char *@var{str})}
15455 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}.
15458 @defbuiltin{float __builtin_nanf (const char *@var{str})}
15459 Similar to @code{__builtin_nan}, except the return type is @code{float}.
15462 @defbuiltin{{long double} __builtin_nanl (const char *@var{str})}
15463 Similar to @code{__builtin_nan}, except the return type is @code{long double}.
15466 @defbuiltin{_Float@var{n} __builtin_nanf@var{n} (const char *@var{str})}
15467 Similar to @code{__builtin_nan}, except the return type is
15468 @code{_Float@var{n}}.
15471 @defbuiltin{_Float@var{n}x __builtin_nanf@var{n}x (const char *@var{str})}
15472 Similar to @code{__builtin_nan}, except the return type is
15473 @code{_Float@var{n}x}.
15476 @defbuiltin{double __builtin_nans (const char *@var{str})}
15477 Similar to @code{__builtin_nan}, except the significand is forced
15478 to be a signaling NaN@. The @code{nans} function is proposed by
15479 @uref{https://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}.
15482 @defbuiltin{_Decimal32 __builtin_nansd32 (const char *@var{str})}
15483 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal32}.
15486 @defbuiltin{_Decimal64 __builtin_nansd64 (const char *@var{str})}
15487 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal64}.
15490 @defbuiltin{_Decimal128 __builtin_nansd128 (const char *@var{str})}
15491 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal128}.
15494 @defbuiltin{float __builtin_nansf (const char *@var{str})}
15495 Similar to @code{__builtin_nans}, except the return type is @code{float}.
15498 @defbuiltin{{long double} __builtin_nansl (const char *@var{str})}
15499 Similar to @code{__builtin_nans}, except the return type is @code{long double}.
15502 @defbuiltin{_Float@var{n} __builtin_nansf@var{n} (const char *@var{str})}
15503 Similar to @code{__builtin_nans}, except the return type is
15504 @code{_Float@var{n}}.
15507 @defbuiltin{_Float@var{n}x __builtin_nansf@var{n}x (const char *@var{str})}
15508 Similar to @code{__builtin_nans}, except the return type is
15509 @code{_Float@var{n}x}.
15512 @defbuiltin{int __builtin_issignaling (...)}
15513 Return non-zero if the argument is a signaling NaN and zero otherwise.
15514 Note while the parameter list is an
15515 ellipsis, this function only accepts exactly one floating-point
15516 argument. GCC treats this parameter as type-generic, which means it
15517 does not do default promotion from float to double.
15518 This built-in function can work even without the non-default
15519 @code{-fsignaling-nans} option, although if a signaling NaN is computed,
15520 stored or passed as argument to some function other than this built-in
15521 in the current translation unit, it is safer to use @code{-fsignaling-nans}.
15522 With @code{-ffinite-math-only} option this built-in function will always
15526 @defbuiltin{int __builtin_ffs (int @var{x})}
15527 Returns one plus the index of the least significant 1-bit of @var{x}, or
15528 if @var{x} is zero, returns zero.
15531 @defbuiltin{int __builtin_clz (unsigned int @var{x})}
15532 Returns the number of leading 0-bits in @var{x}, starting at the most
15533 significant bit position. If @var{x} is 0, the result is undefined.
15536 @defbuiltin{int __builtin_ctz (unsigned int @var{x})}
15537 Returns the number of trailing 0-bits in @var{x}, starting at the least
15538 significant bit position. If @var{x} is 0, the result is undefined.
15541 @defbuiltin{int __builtin_clrsb (int @var{x})}
15542 Returns the number of leading redundant sign bits in @var{x}, i.e.@: the
15543 number of bits following the most significant bit that are identical
15544 to it. There are no special cases for 0 or other values.
15547 @defbuiltin{int __builtin_popcount (unsigned int @var{x})}
15548 Returns the number of 1-bits in @var{x}.
15551 @defbuiltin{int __builtin_parity (unsigned int @var{x})}
15552 Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x}
15556 @defbuiltin{int __builtin_ffsl (long)}
15557 Similar to @code{__builtin_ffs}, except the argument type is
15561 @defbuiltin{int __builtin_clzl (unsigned long)}
15562 Similar to @code{__builtin_clz}, except the argument type is
15563 @code{unsigned long}.
15566 @defbuiltin{int __builtin_ctzl (unsigned long)}
15567 Similar to @code{__builtin_ctz}, except the argument type is
15568 @code{unsigned long}.
15571 @defbuiltin{int __builtin_clrsbl (long)}
15572 Similar to @code{__builtin_clrsb}, except the argument type is
15576 @defbuiltin{int __builtin_popcountl (unsigned long)}
15577 Similar to @code{__builtin_popcount}, except the argument type is
15578 @code{unsigned long}.
15581 @defbuiltin{int __builtin_parityl (unsigned long)}
15582 Similar to @code{__builtin_parity}, except the argument type is
15583 @code{unsigned long}.
15586 @defbuiltin{int __builtin_ffsll (long long)}
15587 Similar to @code{__builtin_ffs}, except the argument type is
15591 @defbuiltin{int __builtin_clzll (unsigned long long)}
15592 Similar to @code{__builtin_clz}, except the argument type is
15593 @code{unsigned long long}.
15596 @defbuiltin{int __builtin_ctzll (unsigned long long)}
15597 Similar to @code{__builtin_ctz}, except the argument type is
15598 @code{unsigned long long}.
15601 @defbuiltin{int __builtin_clrsbll (long long)}
15602 Similar to @code{__builtin_clrsb}, except the argument type is
15606 @defbuiltin{int __builtin_popcountll (unsigned long long)}
15607 Similar to @code{__builtin_popcount}, except the argument type is
15608 @code{unsigned long long}.
15611 @defbuiltin{int __builtin_parityll (unsigned long long)}
15612 Similar to @code{__builtin_parity}, except the argument type is
15613 @code{unsigned long long}.
15616 @defbuiltin{int __builtin_ffsg (...)}
15617 Similar to @code{__builtin_ffs}, except the argument is type-generic
15618 signed integer (standard, extended or bit-precise). No integral argument
15619 promotions are performed on the argument.
15622 @defbuiltin{int __builtin_clzg (...)}
15623 Similar to @code{__builtin_clz}, except the argument is type-generic
15624 unsigned integer (standard, extended or bit-precise) and there is
15625 optional second argument with int type. No integral argument promotions
15626 are performed on the first argument. If two arguments are specified,
15627 and first argument is 0, the result is the second argument. If only
15628 one argument is specified and it is 0, the result is undefined.
15631 @defbuiltin{int __builtin_ctzg (...)}
15632 Similar to @code{__builtin_ctz}, except the argument is type-generic
15633 unsigned integer (standard, extended or bit-precise) and there is
15634 optional second argument with int type. No integral argument promotions
15635 are performed on the first argument. If two arguments are specified,
15636 and first argument is 0, the result is the second argument. If only
15637 one argument is specified and it is 0, the result is undefined.
15640 @defbuiltin{int __builtin_clrsbg (...)}
15641 Similar to @code{__builtin_clrsb}, except the argument is type-generic
15642 signed integer (standard, extended or bit-precise). No integral argument
15643 promotions are performed on the argument.
15646 @defbuiltin{int __builtin_popcountg (...)}
15647 Similar to @code{__builtin_popcount}, except the argument is type-generic
15648 unsigned integer (standard, extended or bit-precise). No integral argument
15649 promotions are performed on the argument.
15652 @defbuiltin{int __builtin_parityg (...)}
15653 Similar to @code{__builtin_parity}, except the argument is type-generic
15654 unsigned integer (standard, extended or bit-precise). No integral argument
15655 promotions are performed on the argument.
15658 @defbuiltin{@var{type} __builtin_stdc_bit_ceil (@var{type} @var{arg})}
15659 The @code{__builtin_stdc_bit_ceil} function is available only
15660 in C. It is type-generic, the argument can be any unsigned integer
15661 (standard, extended or bit-precise). No integral argument promotions are
15662 performed on the argument. It is equivalent to
15663 @code{@var{arg} <= 1 ? (@var{type}) 1
15664 : (@var{type}) 2 << (@var{prec} - 1 - __builtin_clzg ((@var{type}) (@var{arg} - 1)))}
15665 where @var{prec} is bit width of @var{type}, except that side-effects
15666 in @var{arg} are evaluated just once.
15669 @defbuiltin{@var{type} __builtin_stdc_bit_floor (@var{type} @var{arg})}
15670 The @code{__builtin_stdc_bit_floor} function is available only
15671 in C. It is type-generic, the argument can be any unsigned integer
15672 (standard, extended or bit-precise). No integral argument promotions are
15673 performed on the argument. It is equivalent to
15674 @code{@var{arg} == 0 ? (@var{type}) 0
15675 : (@var{type}) 1 << (@var{prec} - 1 - __builtin_clzg (@var{arg}))}
15676 where @var{prec} is bit width of @var{type}, except that side-effects
15677 in @var{arg} are evaluated just once.
15680 @defbuiltin{{unsigned int} __builtin_stdc_bit_width (@var{type} @var{arg})}
15681 The @code{__builtin_stdc_bit_width} function is available only
15682 in C. It is type-generic, the argument can be any unsigned integer
15683 (standard, extended or bit-precise). No integral argument promotions are
15684 performed on the argument. It is equivalent to
15685 @code{(unsigned int) (@var{prec} - __builtin_clzg (@var{arg}, @var{prec}))}
15686 where @var{prec} is bit width of @var{type}.
15689 @defbuiltin{{unsigned int} __builtin_stdc_count_ones (@var{type} @var{arg})}
15690 The @code{__builtin_stdc_count_ones} function is available only
15691 in C. It is type-generic, the argument can be any unsigned integer
15692 (standard, extended or bit-precise). No integral argument promotions are
15693 performed on the argument. It is equivalent to
15694 @code{(unsigned int) __builtin_popcountg (@var{arg})}
15697 @defbuiltin{{unsigned int} __builtin_stdc_count_zeros (@var{type} @var{arg})}
15698 The @code{__builtin_stdc_count_zeros} function is available only
15699 in C. It is type-generic, the argument can be any unsigned integer
15700 (standard, extended or bit-precise). No integral argument promotions are
15701 performed on the argument. It is equivalent to
15702 @code{(unsigned int) __builtin_popcountg ((@var{type}) ~@var{arg})}
15705 @defbuiltin{{unsigned int} __builtin_stdc_first_leading_one (@var{type} @var{arg})}
15706 The @code{__builtin_stdc_first_leading_one} function is available only
15707 in C. It is type-generic, the argument can be any unsigned integer
15708 (standard, extended or bit-precise). No integral argument promotions are
15709 performed on the argument. It is equivalent to
15710 @code{__builtin_clzg (@var{arg}, -1) + 1U}
15713 @defbuiltin{{unsigned int} __builtin_stdc_first_leading_zero (@var{type} @var{arg})}
15714 The @code{__builtin_stdc_first_leading_zero} function is available only
15715 in C. It is type-generic, the argument can be any unsigned integer
15716 (standard, extended or bit-precise). No integral argument promotions are
15717 performed on the argument. It is equivalent to
15718 @code{__builtin_clzg ((@var{type}) ~@var{arg}, -1) + 1U}
15721 @defbuiltin{{unsigned int} __builtin_stdc_first_trailing_one (@var{type} @var{arg})}
15722 The @code{__builtin_stdc_first_trailing_one} function is available only
15723 in C. It is type-generic, the argument can be any unsigned integer
15724 (standard, extended or bit-precise). No integral argument promotions are
15725 performed on the argument. It is equivalent to
15726 @code{__builtin_ctzg (@var{arg}, -1) + 1U}
15729 @defbuiltin{{unsigned int} __builtin_stdc_first_trailing_zero (@var{type} @var{arg})}
15730 The @code{__builtin_stdc_first_trailing_zero} function is available only
15731 in C. It is type-generic, the argument can be any unsigned integer
15732 (standard, extended or bit-precise). No integral argument promotions are
15733 performed on the argument. It is equivalent to
15734 @code{__builtin_ctzg ((@var{type}) ~@var{arg}, -1) + 1U}
15737 @defbuiltin{{unsigned int} __builtin_stdc_has_single_bit (@var{type} @var{arg})}
15738 The @code{__builtin_stdc_has_single_bit} function is available only
15739 in C. It is type-generic, the argument can be any unsigned integer
15740 (standard, extended or bit-precise). No integral argument promotions are
15741 performed on the argument. It is equivalent to
15742 @code{(_Bool) (__builtin_popcountg (@var{arg}) == 1)}
15745 @defbuiltin{{unsigned int} __builtin_stdc_leading_ones (@var{type} @var{arg})}
15746 The @code{__builtin_stdc_leading_ones} function is available only
15747 in C. It is type-generic, the argument can be any unsigned integer
15748 (standard, extended or bit-precise). No integral argument promotions are
15749 performed on the argument. It is equivalent to
15750 @code{(unsigned int) __builtin_clzg ((@var{type}) ~@var{arg}, @var{prec})}
15753 @defbuiltin{{unsigned int} __builtin_stdc_leading_zeros (@var{type} @var{arg})}
15754 The @code{__builtin_stdc_leading_zeros} function is available only
15755 in C. It is type-generic, the argument can be any unsigned integer
15756 (standard, extended or bit-precise). No integral argument promotions are
15757 performed on the argument. It is equivalent to
15758 @code{(unsigned int) __builtin_clzg (@var{arg}, @var{prec})}
15761 @defbuiltin{{unsigned int} __builtin_stdc_trailing_ones (@var{type} @var{arg})}
15762 The @code{__builtin_stdc_trailing_ones} function is available only
15763 in C. It is type-generic, the argument can be any unsigned integer
15764 (standard, extended or bit-precise). No integral argument promotions are
15765 performed on the argument. It is equivalent to
15766 @code{(unsigned int) __builtin_ctzg ((@var{type}) ~@var{arg}, @var{prec})}
15769 @defbuiltin{{unsigned int} __builtin_stdc_trailing_zeros (@var{type} @var{arg})}
15770 The @code{__builtin_stdc_trailing_zeros} function is available only
15771 in C. It is type-generic, the argument can be any unsigned integer
15772 (standard, extended or bit-precise). No integral argument promotions are
15773 performed on the argument. It is equivalent to
15774 @code{(unsigned int) __builtin_ctzg (@var{arg}, @var{prec})}
15777 @defbuiltin{double __builtin_powi (double, int)}
15778 @defbuiltinx{float __builtin_powif (float, int)}
15779 @defbuiltinx{{long double} __builtin_powil (long double, int)}
15780 Returns the first argument raised to the power of the second. Unlike the
15781 @code{pow} function no guarantees about precision and rounding are made.
15784 @defbuiltin{uint16_t __builtin_bswap16 (uint16_t @var{x})}
15785 Returns @var{x} with the order of the bytes reversed; for example,
15786 @code{0xaabb} becomes @code{0xbbaa}. Byte here always means
15790 @defbuiltin{uint32_t __builtin_bswap32 (uint32_t @var{x})}
15791 Similar to @code{__builtin_bswap16}, except the argument and return types
15795 @defbuiltin{uint64_t __builtin_bswap64 (uint64_t @var{x})}
15796 Similar to @code{__builtin_bswap32}, except the argument and return types
15800 @defbuiltin{uint128_t __builtin_bswap128 (uint128_t @var{x})}
15801 Similar to @code{__builtin_bswap64}, except the argument and return types
15802 are 128-bit. Only supported on targets when 128-bit types are supported.
15806 @defbuiltin{Pmode __builtin_extend_pointer (void * @var{x})}
15807 On targets where the user visible pointer size is smaller than the size
15808 of an actual hardware address this function returns the extended user
15809 pointer. Targets where this is true included ILP32 mode on x86_64 or
15810 Aarch64. This function is mainly useful when writing inline assembly
15814 @defbuiltin{int __builtin_goacc_parlevel_id (int @var{x})}
15815 Returns the openacc gang, worker or vector id depending on whether @var{x} is
15819 @defbuiltin{int __builtin_goacc_parlevel_size (int @var{x})}
15820 Returns the openacc gang, worker or vector size depending on whether @var{x} is
15824 @node Target Builtins
15825 @section Built-in Functions Specific to Particular Target Machines
15827 On some target machines, GCC supports many built-in functions specific
15828 to those machines. Generally these generate calls to specific machine
15829 instructions, but allow the compiler to schedule those calls.
15832 * AArch64 Built-in Functions::
15833 * Alpha Built-in Functions::
15834 * Altera Nios II Built-in Functions::
15835 * ARC Built-in Functions::
15836 * ARC SIMD Built-in Functions::
15837 * ARM iWMMXt Built-in Functions::
15838 * ARM C Language Extensions (ACLE)::
15839 * ARM Floating Point Status and Control Intrinsics::
15840 * ARM ARMv8-M Security Extensions::
15841 * AVR Built-in Functions::
15842 * Blackfin Built-in Functions::
15843 * BPF Built-in Functions::
15844 * FR-V Built-in Functions::
15845 * LoongArch Base Built-in Functions::
15846 * LoongArch SX Vector Intrinsics::
15847 * LoongArch ASX Vector Intrinsics::
15848 * MIPS DSP Built-in Functions::
15849 * MIPS Paired-Single Support::
15850 * MIPS Loongson Built-in Functions::
15851 * MIPS SIMD Architecture (MSA) Support::
15852 * Other MIPS Built-in Functions::
15853 * MSP430 Built-in Functions::
15854 * NDS32 Built-in Functions::
15855 * Nvidia PTX Built-in Functions::
15856 * Basic PowerPC Built-in Functions::
15857 * PowerPC AltiVec/VSX Built-in Functions::
15858 * PowerPC Hardware Transactional Memory Built-in Functions::
15859 * PowerPC Atomic Memory Operation Functions::
15860 * PowerPC Matrix-Multiply Assist Built-in Functions::
15861 * PRU Built-in Functions::
15862 * RISC-V Built-in Functions::
15863 * RISC-V Vector Intrinsics::
15864 * CORE-V Built-in Functions::
15865 * RX Built-in Functions::
15866 * S/390 System z Built-in Functions::
15867 * SH Built-in Functions::
15868 * SPARC VIS Built-in Functions::
15869 * TI C6X Built-in Functions::
15870 * x86 Built-in Functions::
15871 * x86 transactional memory intrinsics::
15872 * x86 control-flow protection intrinsics::
15875 @node AArch64 Built-in Functions
15876 @subsection AArch64 Built-in Functions
15878 These built-in functions are available for the AArch64 family of
15881 unsigned int __builtin_aarch64_get_fpcr ();
15882 void __builtin_aarch64_set_fpcr (unsigned int);
15883 unsigned int __builtin_aarch64_get_fpsr ();
15884 void __builtin_aarch64_set_fpsr (unsigned int);
15886 unsigned long long __builtin_aarch64_get_fpcr64 ();
15887 void __builtin_aarch64_set_fpcr64 (unsigned long long);
15888 unsigned long long __builtin_aarch64_get_fpsr64 ();
15889 void __builtin_aarch64_set_fpsr64 (unsigned long long);
15892 @node Alpha Built-in Functions
15893 @subsection Alpha Built-in Functions
15895 These built-in functions are available for the Alpha family of
15896 processors, depending on the command-line switches used.
15898 The following built-in functions are always available. They
15899 all generate the machine instruction that is part of the name.
15902 long __builtin_alpha_implver (void);
15903 long __builtin_alpha_rpcc (void);
15904 long __builtin_alpha_amask (long);
15905 long __builtin_alpha_cmpbge (long, long);
15906 long __builtin_alpha_extbl (long, long);
15907 long __builtin_alpha_extwl (long, long);
15908 long __builtin_alpha_extll (long, long);
15909 long __builtin_alpha_extql (long, long);
15910 long __builtin_alpha_extwh (long, long);
15911 long __builtin_alpha_extlh (long, long);
15912 long __builtin_alpha_extqh (long, long);
15913 long __builtin_alpha_insbl (long, long);
15914 long __builtin_alpha_inswl (long, long);
15915 long __builtin_alpha_insll (long, long);
15916 long __builtin_alpha_insql (long, long);
15917 long __builtin_alpha_inswh (long, long);
15918 long __builtin_alpha_inslh (long, long);
15919 long __builtin_alpha_insqh (long, long);
15920 long __builtin_alpha_mskbl (long, long);
15921 long __builtin_alpha_mskwl (long, long);
15922 long __builtin_alpha_mskll (long, long);
15923 long __builtin_alpha_mskql (long, long);
15924 long __builtin_alpha_mskwh (long, long);
15925 long __builtin_alpha_msklh (long, long);
15926 long __builtin_alpha_mskqh (long, long);
15927 long __builtin_alpha_umulh (long, long);
15928 long __builtin_alpha_zap (long, long);
15929 long __builtin_alpha_zapnot (long, long);
15932 The following built-in functions are always with @option{-mmax}
15933 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
15934 later. They all generate the machine instruction that is part
15938 long __builtin_alpha_pklb (long);
15939 long __builtin_alpha_pkwb (long);
15940 long __builtin_alpha_unpkbl (long);
15941 long __builtin_alpha_unpkbw (long);
15942 long __builtin_alpha_minub8 (long, long);
15943 long __builtin_alpha_minsb8 (long, long);
15944 long __builtin_alpha_minuw4 (long, long);
15945 long __builtin_alpha_minsw4 (long, long);
15946 long __builtin_alpha_maxub8 (long, long);
15947 long __builtin_alpha_maxsb8 (long, long);
15948 long __builtin_alpha_maxuw4 (long, long);
15949 long __builtin_alpha_maxsw4 (long, long);
15950 long __builtin_alpha_perr (long, long);
15953 The following built-in functions are always with @option{-mcix}
15954 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
15955 later. They all generate the machine instruction that is part
15959 long __builtin_alpha_cttz (long);
15960 long __builtin_alpha_ctlz (long);
15961 long __builtin_alpha_ctpop (long);
15964 The following built-in functions are available on systems that use the OSF/1
15965 PALcode. Normally they invoke the @code{rduniq} and @code{wruniq}
15966 PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
15967 @code{rdval} and @code{wrval}.
15970 void *__builtin_thread_pointer (void);
15971 void __builtin_set_thread_pointer (void *);
15974 @node Altera Nios II Built-in Functions
15975 @subsection Altera Nios II Built-in Functions
15977 These built-in functions are available for the Altera Nios II
15978 family of processors.
15980 The following built-in functions are always available. They
15981 all generate the machine instruction that is part of the name.
15984 int __builtin_ldbio (volatile const void *);
15985 int __builtin_ldbuio (volatile const void *);
15986 int __builtin_ldhio (volatile const void *);
15987 int __builtin_ldhuio (volatile const void *);
15988 int __builtin_ldwio (volatile const void *);
15989 void __builtin_stbio (volatile void *, int);
15990 void __builtin_sthio (volatile void *, int);
15991 void __builtin_stwio (volatile void *, int);
15992 void __builtin_sync (void);
15993 int __builtin_rdctl (int);
15994 int __builtin_rdprs (int, int);
15995 void __builtin_wrctl (int, int);
15996 void __builtin_flushd (volatile void *);
15997 void __builtin_flushda (volatile void *);
15998 int __builtin_wrpie (int);
15999 void __builtin_eni (int);
16000 int __builtin_ldex (volatile const void *);
16001 int __builtin_stex (volatile void *, int);
16002 int __builtin_ldsex (volatile const void *);
16003 int __builtin_stsex (volatile void *, int);
16006 The following built-in functions are always available. They
16007 all generate a Nios II Custom Instruction. The name of the
16008 function represents the types that the function takes and
16009 returns. The letter before the @code{n} is the return type
16010 or void if absent. The @code{n} represents the first parameter
16011 to all the custom instructions, the custom instruction number.
16012 The two letters after the @code{n} represent the up to two
16013 parameters to the function.
16015 The letters represent the following data types:
16018 @code{void} for return type and no parameter for parameter types.
16021 @code{int} for return type and parameter type
16024 @code{float} for return type and parameter type
16027 @code{void *} for return type and parameter type
16031 And the function names are:
16033 void __builtin_custom_n (void);
16034 void __builtin_custom_ni (int);
16035 void __builtin_custom_nf (float);
16036 void __builtin_custom_np (void *);
16037 void __builtin_custom_nii (int, int);
16038 void __builtin_custom_nif (int, float);
16039 void __builtin_custom_nip (int, void *);
16040 void __builtin_custom_nfi (float, int);
16041 void __builtin_custom_nff (float, float);
16042 void __builtin_custom_nfp (float, void *);
16043 void __builtin_custom_npi (void *, int);
16044 void __builtin_custom_npf (void *, float);
16045 void __builtin_custom_npp (void *, void *);
16046 int __builtin_custom_in (void);
16047 int __builtin_custom_ini (int);
16048 int __builtin_custom_inf (float);
16049 int __builtin_custom_inp (void *);
16050 int __builtin_custom_inii (int, int);
16051 int __builtin_custom_inif (int, float);
16052 int __builtin_custom_inip (int, void *);
16053 int __builtin_custom_infi (float, int);
16054 int __builtin_custom_inff (float, float);
16055 int __builtin_custom_infp (float, void *);
16056 int __builtin_custom_inpi (void *, int);
16057 int __builtin_custom_inpf (void *, float);
16058 int __builtin_custom_inpp (void *, void *);
16059 float __builtin_custom_fn (void);
16060 float __builtin_custom_fni (int);
16061 float __builtin_custom_fnf (float);
16062 float __builtin_custom_fnp (void *);
16063 float __builtin_custom_fnii (int, int);
16064 float __builtin_custom_fnif (int, float);
16065 float __builtin_custom_fnip (int, void *);
16066 float __builtin_custom_fnfi (float, int);
16067 float __builtin_custom_fnff (float, float);
16068 float __builtin_custom_fnfp (float, void *);
16069 float __builtin_custom_fnpi (void *, int);
16070 float __builtin_custom_fnpf (void *, float);
16071 float __builtin_custom_fnpp (void *, void *);
16072 void * __builtin_custom_pn (void);
16073 void * __builtin_custom_pni (int);
16074 void * __builtin_custom_pnf (float);
16075 void * __builtin_custom_pnp (void *);
16076 void * __builtin_custom_pnii (int, int);
16077 void * __builtin_custom_pnif (int, float);
16078 void * __builtin_custom_pnip (int, void *);
16079 void * __builtin_custom_pnfi (float, int);
16080 void * __builtin_custom_pnff (float, float);
16081 void * __builtin_custom_pnfp (float, void *);
16082 void * __builtin_custom_pnpi (void *, int);
16083 void * __builtin_custom_pnpf (void *, float);
16084 void * __builtin_custom_pnpp (void *, void *);
16087 @node ARC Built-in Functions
16088 @subsection ARC Built-in Functions
16090 The following built-in functions are provided for ARC targets. The
16091 built-ins generate the corresponding assembly instructions. In the
16092 examples given below, the generated code often requires an operand or
16093 result to be in a register. Where necessary further code will be
16094 generated to ensure this is true, but for brevity this is not
16095 described in each case.
16097 @emph{Note:} Using a built-in to generate an instruction not supported
16098 by a target may cause problems. At present the compiler is not
16099 guaranteed to detect such misuse, and as a result an internal compiler
16100 error may be generated.
16102 @defbuiltin{int __builtin_arc_aligned (void *@var{val}, int @var{alignval})}
16103 Return 1 if @var{val} is known to have the byte alignment given
16104 by @var{alignval}, otherwise return 0.
16105 Note that this is different from
16107 __alignof__(*(char *)@var{val}) >= alignval
16109 because __alignof__ sees only the type of the dereference, whereas
16110 __builtin_arc_align uses alignment information from the pointer
16111 as well as from the pointed-to type.
16112 The information available will depend on optimization level.
16115 @defbuiltin{void __builtin_arc_brk (void)}
16122 @defbuiltin{{unsigned int} __builtin_arc_core_read (unsigned int @var{regno})}
16123 The operand is the number of a register to be read. Generates:
16125 mov @var{dest}, r@var{regno}
16127 where the value in @var{dest} will be the result returned from the
16131 @defbuiltin{void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val})}
16132 The first operand is the number of a register to be written, the
16133 second operand is a compile time constant to write into that
16134 register. Generates:
16136 mov r@var{regno}, @var{val}
16140 @defbuiltin{int __builtin_arc_divaw (int @var{a}, int @var{b})}
16141 Only available if either @option{-mcpu=ARC700} or @option{-meA} is set.
16144 divaw @var{dest}, @var{a}, @var{b}
16146 where the value in @var{dest} will be the result returned from the
16150 @defbuiltin{void __builtin_arc_flag (unsigned int @var{a})}
16157 @defbuiltin{{unsigned int} __builtin_arc_lr (unsigned int @var{auxr})}
16158 The operand, @var{auxv}, is the address of an auxiliary register and
16159 must be a compile time constant. Generates:
16161 lr @var{dest}, [@var{auxr}]
16163 Where the value in @var{dest} will be the result returned from the
16167 @defbuiltin{void __builtin_arc_mul64 (int @var{a}, int @var{b})}
16168 Only available with @option{-mmul64}. Generates:
16170 mul64 @var{a}, @var{b}
16174 @defbuiltin{void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b})}
16175 Only available with @option{-mmul64}. Generates:
16177 mulu64 @var{a}, @var{b}
16181 @defbuiltin{void __builtin_arc_nop (void)}
16188 @defbuiltin{int __builtin_arc_norm (int @var{src})}
16189 Only valid if the @samp{norm} instruction is available through the
16190 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
16193 norm @var{dest}, @var{src}
16195 Where the value in @var{dest} will be the result returned from the
16199 @defbuiltin{{short int} __builtin_arc_normw (short int @var{src})}
16200 Only valid if the @samp{normw} instruction is available through the
16201 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
16204 normw @var{dest}, @var{src}
16206 Where the value in @var{dest} will be the result returned from the
16210 @defbuiltin{void __builtin_arc_rtie (void)}
16217 @defbuiltin{void __builtin_arc_sleep (int @var{a}}
16224 @defbuiltin{void __builtin_arc_sr (unsigned int @var{val}, unsigned int @var{auxr})}
16225 The first argument, @var{val}, is a compile time constant to be
16226 written to the register, the second argument, @var{auxr}, is the
16227 address of an auxiliary register. Generates:
16229 sr @var{val}, [@var{auxr}]
16233 @defbuiltin{int __builtin_arc_swap (int @var{src})}
16234 Only valid with @option{-mswap}. Generates:
16236 swap @var{dest}, @var{src}
16238 Where the value in @var{dest} will be the result returned from the
16242 @defbuiltin{void __builtin_arc_swi (void)}
16249 @defbuiltin{void __builtin_arc_sync (void)}
16250 Only available with @option{-mcpu=ARC700}. Generates:
16256 @defbuiltin{void __builtin_arc_trap_s (unsigned int @var{c})}
16257 Only available with @option{-mcpu=ARC700}. Generates:
16263 @defbuiltin{void __builtin_arc_unimp_s (void)}
16264 Only available with @option{-mcpu=ARC700}. Generates:
16270 The instructions generated by the following builtins are not
16271 considered as candidates for scheduling. They are not moved around by
16272 the compiler during scheduling, and thus can be expected to appear
16273 where they are put in the C code:
16275 __builtin_arc_brk()
16276 __builtin_arc_core_read()
16277 __builtin_arc_core_write()
16278 __builtin_arc_flag()
16280 __builtin_arc_sleep()
16282 __builtin_arc_swi()
16285 The following built-in functions are available for the ARCv2 family of
16289 int __builtin_arc_clri ();
16290 void __builtin_arc_kflag (unsigned);
16291 void __builtin_arc_seti (int);
16294 The following built-in functions are available for the ARCv2 family
16295 and uses @option{-mnorm}.
16298 int __builtin_arc_ffs (int);
16299 int __builtin_arc_fls (int);
16302 @node ARC SIMD Built-in Functions
16303 @subsection ARC SIMD Built-in Functions
16305 SIMD builtins provided by the compiler can be used to generate the
16306 vector instructions. This section describes the available builtins
16307 and their usage in programs. With the @option{-msimd} option, the
16308 compiler provides 128-bit vector types, which can be specified using
16309 the @code{vector_size} attribute. The header file @file{arc-simd.h}
16310 can be included to use the following predefined types:
16312 typedef int __v4si __attribute__((vector_size(16)));
16313 typedef short __v8hi __attribute__((vector_size(16)));
16316 These types can be used to define 128-bit variables. The built-in
16317 functions listed in the following section can be used on these
16318 variables to generate the vector operations.
16320 For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file
16321 @file{arc-simd.h} also provides equivalent macros called
16322 @code{_@var{someinsn}} that can be used for programming ease and
16323 improved readability. The following macros for DMA control are also
16326 #define _setup_dma_in_channel_reg _vdiwr
16327 #define _setup_dma_out_channel_reg _vdowr
16330 The following is a complete list of all the SIMD built-ins provided
16331 for ARC, grouped by calling signature.
16333 The following take two @code{__v8hi} arguments and return a
16334 @code{__v8hi} result:
16336 __v8hi __builtin_arc_vaddaw (__v8hi, __v8hi);
16337 __v8hi __builtin_arc_vaddw (__v8hi, __v8hi);
16338 __v8hi __builtin_arc_vand (__v8hi, __v8hi);
16339 __v8hi __builtin_arc_vandaw (__v8hi, __v8hi);
16340 __v8hi __builtin_arc_vavb (__v8hi, __v8hi);
16341 __v8hi __builtin_arc_vavrb (__v8hi, __v8hi);
16342 __v8hi __builtin_arc_vbic (__v8hi, __v8hi);
16343 __v8hi __builtin_arc_vbicaw (__v8hi, __v8hi);
16344 __v8hi __builtin_arc_vdifaw (__v8hi, __v8hi);
16345 __v8hi __builtin_arc_vdifw (__v8hi, __v8hi);
16346 __v8hi __builtin_arc_veqw (__v8hi, __v8hi);
16347 __v8hi __builtin_arc_vh264f (__v8hi, __v8hi);
16348 __v8hi __builtin_arc_vh264ft (__v8hi, __v8hi);
16349 __v8hi __builtin_arc_vh264fw (__v8hi, __v8hi);
16350 __v8hi __builtin_arc_vlew (__v8hi, __v8hi);
16351 __v8hi __builtin_arc_vltw (__v8hi, __v8hi);
16352 __v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi);
16353 __v8hi __builtin_arc_vmaxw (__v8hi, __v8hi);
16354 __v8hi __builtin_arc_vminaw (__v8hi, __v8hi);
16355 __v8hi __builtin_arc_vminw (__v8hi, __v8hi);
16356 __v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi);
16357 __v8hi __builtin_arc_vmr1w (__v8hi, __v8hi);
16358 __v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi);
16359 __v8hi __builtin_arc_vmr2w (__v8hi, __v8hi);
16360 __v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi);
16361 __v8hi __builtin_arc_vmr3w (__v8hi, __v8hi);
16362 __v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi);
16363 __v8hi __builtin_arc_vmr4w (__v8hi, __v8hi);
16364 __v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi);
16365 __v8hi __builtin_arc_vmr5w (__v8hi, __v8hi);
16366 __v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi);
16367 __v8hi __builtin_arc_vmr6w (__v8hi, __v8hi);
16368 __v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi);
16369 __v8hi __builtin_arc_vmr7w (__v8hi, __v8hi);
16370 __v8hi __builtin_arc_vmrb (__v8hi, __v8hi);
16371 __v8hi __builtin_arc_vmulaw (__v8hi, __v8hi);
16372 __v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi);
16373 __v8hi __builtin_arc_vmulfw (__v8hi, __v8hi);
16374 __v8hi __builtin_arc_vmulw (__v8hi, __v8hi);
16375 __v8hi __builtin_arc_vnew (__v8hi, __v8hi);
16376 __v8hi __builtin_arc_vor (__v8hi, __v8hi);
16377 __v8hi __builtin_arc_vsubaw (__v8hi, __v8hi);
16378 __v8hi __builtin_arc_vsubw (__v8hi, __v8hi);
16379 __v8hi __builtin_arc_vsummw (__v8hi, __v8hi);
16380 __v8hi __builtin_arc_vvc1f (__v8hi, __v8hi);
16381 __v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi);
16382 __v8hi __builtin_arc_vxor (__v8hi, __v8hi);
16383 __v8hi __builtin_arc_vxoraw (__v8hi, __v8hi);
16386 The following take one @code{__v8hi} and one @code{int} argument and return a
16387 @code{__v8hi} result:
16390 __v8hi __builtin_arc_vbaddw (__v8hi, int);
16391 __v8hi __builtin_arc_vbmaxw (__v8hi, int);
16392 __v8hi __builtin_arc_vbminw (__v8hi, int);
16393 __v8hi __builtin_arc_vbmulaw (__v8hi, int);
16394 __v8hi __builtin_arc_vbmulfw (__v8hi, int);
16395 __v8hi __builtin_arc_vbmulw (__v8hi, int);
16396 __v8hi __builtin_arc_vbrsubw (__v8hi, int);
16397 __v8hi __builtin_arc_vbsubw (__v8hi, int);
16400 The following take one @code{__v8hi} argument and one @code{int} argument which
16401 must be a 3-bit compile time constant indicating a register number
16402 I0-I7. They return a @code{__v8hi} result.
16404 __v8hi __builtin_arc_vasrw (__v8hi, const int);
16405 __v8hi __builtin_arc_vsr8 (__v8hi, const int);
16406 __v8hi __builtin_arc_vsr8aw (__v8hi, const int);
16409 The following take one @code{__v8hi} argument and one @code{int}
16410 argument which must be a 6-bit compile time constant. They return a
16411 @code{__v8hi} result.
16413 __v8hi __builtin_arc_vasrpwbi (__v8hi, const int);
16414 __v8hi __builtin_arc_vasrrpwbi (__v8hi, const int);
16415 __v8hi __builtin_arc_vasrrwi (__v8hi, const int);
16416 __v8hi __builtin_arc_vasrsrwi (__v8hi, const int);
16417 __v8hi __builtin_arc_vasrwi (__v8hi, const int);
16418 __v8hi __builtin_arc_vsr8awi (__v8hi, const int);
16419 __v8hi __builtin_arc_vsr8i (__v8hi, const int);
16422 The following take one @code{__v8hi} argument and one @code{int} argument which
16423 must be a 8-bit compile time constant. They return a @code{__v8hi}
16426 __v8hi __builtin_arc_vd6tapf (__v8hi, const int);
16427 __v8hi __builtin_arc_vmvaw (__v8hi, const int);
16428 __v8hi __builtin_arc_vmvw (__v8hi, const int);
16429 __v8hi __builtin_arc_vmvzw (__v8hi, const int);
16432 The following take two @code{int} arguments, the second of which which
16433 must be a 8-bit compile time constant. They return a @code{__v8hi}
16436 __v8hi __builtin_arc_vmovaw (int, const int);
16437 __v8hi __builtin_arc_vmovw (int, const int);
16438 __v8hi __builtin_arc_vmovzw (int, const int);
16441 The following take a single @code{__v8hi} argument and return a
16442 @code{__v8hi} result:
16444 __v8hi __builtin_arc_vabsaw (__v8hi);
16445 __v8hi __builtin_arc_vabsw (__v8hi);
16446 __v8hi __builtin_arc_vaddsuw (__v8hi);
16447 __v8hi __builtin_arc_vexch1 (__v8hi);
16448 __v8hi __builtin_arc_vexch2 (__v8hi);
16449 __v8hi __builtin_arc_vexch4 (__v8hi);
16450 __v8hi __builtin_arc_vsignw (__v8hi);
16451 __v8hi __builtin_arc_vupbaw (__v8hi);
16452 __v8hi __builtin_arc_vupbw (__v8hi);
16453 __v8hi __builtin_arc_vupsbaw (__v8hi);
16454 __v8hi __builtin_arc_vupsbw (__v8hi);
16457 The following take two @code{int} arguments and return no result:
16459 void __builtin_arc_vdirun (int, int);
16460 void __builtin_arc_vdorun (int, int);
16463 The following take two @code{int} arguments and return no result. The
16464 first argument must a 3-bit compile time constant indicating one of
16465 the DR0-DR7 DMA setup channels:
16467 void __builtin_arc_vdiwr (const int, int);
16468 void __builtin_arc_vdowr (const int, int);
16471 The following take an @code{int} argument and return no result:
16473 void __builtin_arc_vendrec (int);
16474 void __builtin_arc_vrec (int);
16475 void __builtin_arc_vrecrun (int);
16476 void __builtin_arc_vrun (int);
16479 The following take a @code{__v8hi} argument and two @code{int}
16480 arguments and return a @code{__v8hi} result. The second argument must
16481 be a 3-bit compile time constants, indicating one the registers I0-I7,
16482 and the third argument must be an 8-bit compile time constant.
16484 @emph{Note:} Although the equivalent hardware instructions do not take
16485 an SIMD register as an operand, these builtins overwrite the relevant
16486 bits of the @code{__v8hi} register provided as the first argument with
16487 the value loaded from the @code{[Ib, u8]} location in the SDM.
16490 __v8hi __builtin_arc_vld32 (__v8hi, const int, const int);
16491 __v8hi __builtin_arc_vld32wh (__v8hi, const int, const int);
16492 __v8hi __builtin_arc_vld32wl (__v8hi, const int, const int);
16493 __v8hi __builtin_arc_vld64 (__v8hi, const int, const int);
16496 The following take two @code{int} arguments and return a @code{__v8hi}
16497 result. The first argument must be a 3-bit compile time constants,
16498 indicating one the registers I0-I7, and the second argument must be an
16499 8-bit compile time constant.
16502 __v8hi __builtin_arc_vld128 (const int, const int);
16503 __v8hi __builtin_arc_vld64w (const int, const int);
16506 The following take a @code{__v8hi} argument and two @code{int}
16507 arguments and return no result. The second argument must be a 3-bit
16508 compile time constants, indicating one the registers I0-I7, and the
16509 third argument must be an 8-bit compile time constant.
16512 void __builtin_arc_vst128 (__v8hi, const int, const int);
16513 void __builtin_arc_vst64 (__v8hi, const int, const int);
16516 The following take a @code{__v8hi} argument and three @code{int}
16517 arguments and return no result. The second argument must be a 3-bit
16518 compile-time constant, identifying the 16-bit sub-register to be
16519 stored, the third argument must be a 3-bit compile time constants,
16520 indicating one the registers I0-I7, and the fourth argument must be an
16521 8-bit compile time constant.
16524 void __builtin_arc_vst16_n (__v8hi, const int, const int, const int);
16525 void __builtin_arc_vst32_n (__v8hi, const int, const int, const int);
16528 The following built-in functions are available on systems that uses
16529 @option{-mmpy-option=6} or higher.
16532 __v2hi __builtin_arc_dmach (__v2hi, __v2hi);
16533 __v2hi __builtin_arc_dmachu (__v2hi, __v2hi);
16534 __v2hi __builtin_arc_dmpyh (__v2hi, __v2hi);
16535 __v2hi __builtin_arc_dmpyhu (__v2hi, __v2hi);
16536 __v2hi __builtin_arc_vaddsub2h (__v2hi, __v2hi);
16537 __v2hi __builtin_arc_vsubadd2h (__v2hi, __v2hi);
16540 The following built-in functions are available on systems that uses
16541 @option{-mmpy-option=7} or higher.
16544 __v2si __builtin_arc_vmac2h (__v2hi, __v2hi);
16545 __v2si __builtin_arc_vmac2hu (__v2hi, __v2hi);
16546 __v2si __builtin_arc_vmpy2h (__v2hi, __v2hi);
16547 __v2si __builtin_arc_vmpy2hu (__v2hi, __v2hi);
16550 The following built-in functions are available on systems that uses
16551 @option{-mmpy-option=8} or higher.
16554 long long __builtin_arc_qmach (__v4hi, __v4hi);
16555 long long __builtin_arc_qmachu (__v4hi, __v4hi);
16556 long long __builtin_arc_qmpyh (__v4hi, __v4hi);
16557 long long __builtin_arc_qmpyhu (__v4hi, __v4hi);
16558 long long __builtin_arc_dmacwh (__v2si, __v2hi);
16559 long long __builtin_arc_dmacwhu (__v2si, __v2hi);
16560 _v2si __builtin_arc_vaddsub (__v2si, __v2si);
16561 _v2si __builtin_arc_vsubadd (__v2si, __v2si);
16562 _v4hi __builtin_arc_vaddsub4h (__v4hi, __v4hi);
16563 _v4hi __builtin_arc_vsubadd4h (__v4hi, __v4hi);
16566 @node ARM iWMMXt Built-in Functions
16567 @subsection ARM iWMMXt Built-in Functions
16569 These built-in functions are available for the ARM family of
16570 processors when the @option{-mcpu=iwmmxt} switch is used:
16573 typedef int v2si __attribute__ ((vector_size (8)));
16574 typedef short v4hi __attribute__ ((vector_size (8)));
16575 typedef char v8qi __attribute__ ((vector_size (8)));
16577 int __builtin_arm_getwcgr0 (void);
16578 void __builtin_arm_setwcgr0 (int);
16579 int __builtin_arm_getwcgr1 (void);
16580 void __builtin_arm_setwcgr1 (int);
16581 int __builtin_arm_getwcgr2 (void);
16582 void __builtin_arm_setwcgr2 (int);
16583 int __builtin_arm_getwcgr3 (void);
16584 void __builtin_arm_setwcgr3 (int);
16585 int __builtin_arm_textrmsb (v8qi, int);
16586 int __builtin_arm_textrmsh (v4hi, int);
16587 int __builtin_arm_textrmsw (v2si, int);
16588 int __builtin_arm_textrmub (v8qi, int);
16589 int __builtin_arm_textrmuh (v4hi, int);
16590 int __builtin_arm_textrmuw (v2si, int);
16591 v8qi __builtin_arm_tinsrb (v8qi, int, int);
16592 v4hi __builtin_arm_tinsrh (v4hi, int, int);
16593 v2si __builtin_arm_tinsrw (v2si, int, int);
16594 long long __builtin_arm_tmia (long long, int, int);
16595 long long __builtin_arm_tmiabb (long long, int, int);
16596 long long __builtin_arm_tmiabt (long long, int, int);
16597 long long __builtin_arm_tmiaph (long long, int, int);
16598 long long __builtin_arm_tmiatb (long long, int, int);
16599 long long __builtin_arm_tmiatt (long long, int, int);
16600 int __builtin_arm_tmovmskb (v8qi);
16601 int __builtin_arm_tmovmskh (v4hi);
16602 int __builtin_arm_tmovmskw (v2si);
16603 long long __builtin_arm_waccb (v8qi);
16604 long long __builtin_arm_wacch (v4hi);
16605 long long __builtin_arm_waccw (v2si);
16606 v8qi __builtin_arm_waddb (v8qi, v8qi);
16607 v8qi __builtin_arm_waddbss (v8qi, v8qi);
16608 v8qi __builtin_arm_waddbus (v8qi, v8qi);
16609 v4hi __builtin_arm_waddh (v4hi, v4hi);
16610 v4hi __builtin_arm_waddhss (v4hi, v4hi);
16611 v4hi __builtin_arm_waddhus (v4hi, v4hi);
16612 v2si __builtin_arm_waddw (v2si, v2si);
16613 v2si __builtin_arm_waddwss (v2si, v2si);
16614 v2si __builtin_arm_waddwus (v2si, v2si);
16615 v8qi __builtin_arm_walign (v8qi, v8qi, int);
16616 long long __builtin_arm_wand(long long, long long);
16617 long long __builtin_arm_wandn (long long, long long);
16618 v8qi __builtin_arm_wavg2b (v8qi, v8qi);
16619 v8qi __builtin_arm_wavg2br (v8qi, v8qi);
16620 v4hi __builtin_arm_wavg2h (v4hi, v4hi);
16621 v4hi __builtin_arm_wavg2hr (v4hi, v4hi);
16622 v8qi __builtin_arm_wcmpeqb (v8qi, v8qi);
16623 v4hi __builtin_arm_wcmpeqh (v4hi, v4hi);
16624 v2si __builtin_arm_wcmpeqw (v2si, v2si);
16625 v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi);
16626 v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi);
16627 v2si __builtin_arm_wcmpgtsw (v2si, v2si);
16628 v8qi __builtin_arm_wcmpgtub (v8qi, v8qi);
16629 v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi);
16630 v2si __builtin_arm_wcmpgtuw (v2si, v2si);
16631 long long __builtin_arm_wmacs (long long, v4hi, v4hi);
16632 long long __builtin_arm_wmacsz (v4hi, v4hi);
16633 long long __builtin_arm_wmacu (long long, v4hi, v4hi);
16634 long long __builtin_arm_wmacuz (v4hi, v4hi);
16635 v4hi __builtin_arm_wmadds (v4hi, v4hi);
16636 v4hi __builtin_arm_wmaddu (v4hi, v4hi);
16637 v8qi __builtin_arm_wmaxsb (v8qi, v8qi);
16638 v4hi __builtin_arm_wmaxsh (v4hi, v4hi);
16639 v2si __builtin_arm_wmaxsw (v2si, v2si);
16640 v8qi __builtin_arm_wmaxub (v8qi, v8qi);
16641 v4hi __builtin_arm_wmaxuh (v4hi, v4hi);
16642 v2si __builtin_arm_wmaxuw (v2si, v2si);
16643 v8qi __builtin_arm_wminsb (v8qi, v8qi);
16644 v4hi __builtin_arm_wminsh (v4hi, v4hi);
16645 v2si __builtin_arm_wminsw (v2si, v2si);
16646 v8qi __builtin_arm_wminub (v8qi, v8qi);
16647 v4hi __builtin_arm_wminuh (v4hi, v4hi);
16648 v2si __builtin_arm_wminuw (v2si, v2si);
16649 v4hi __builtin_arm_wmulsm (v4hi, v4hi);
16650 v4hi __builtin_arm_wmulul (v4hi, v4hi);
16651 v4hi __builtin_arm_wmulum (v4hi, v4hi);
16652 long long __builtin_arm_wor (long long, long long);
16653 v2si __builtin_arm_wpackdss (long long, long long);
16654 v2si __builtin_arm_wpackdus (long long, long long);
16655 v8qi __builtin_arm_wpackhss (v4hi, v4hi);
16656 v8qi __builtin_arm_wpackhus (v4hi, v4hi);
16657 v4hi __builtin_arm_wpackwss (v2si, v2si);
16658 v4hi __builtin_arm_wpackwus (v2si, v2si);
16659 long long __builtin_arm_wrord (long long, long long);
16660 long long __builtin_arm_wrordi (long long, int);
16661 v4hi __builtin_arm_wrorh (v4hi, long long);
16662 v4hi __builtin_arm_wrorhi (v4hi, int);
16663 v2si __builtin_arm_wrorw (v2si, long long);
16664 v2si __builtin_arm_wrorwi (v2si, int);
16665 v2si __builtin_arm_wsadb (v2si, v8qi, v8qi);
16666 v2si __builtin_arm_wsadbz (v8qi, v8qi);
16667 v2si __builtin_arm_wsadh (v2si, v4hi, v4hi);
16668 v2si __builtin_arm_wsadhz (v4hi, v4hi);
16669 v4hi __builtin_arm_wshufh (v4hi, int);
16670 long long __builtin_arm_wslld (long long, long long);
16671 long long __builtin_arm_wslldi (long long, int);
16672 v4hi __builtin_arm_wsllh (v4hi, long long);
16673 v4hi __builtin_arm_wsllhi (v4hi, int);
16674 v2si __builtin_arm_wsllw (v2si, long long);
16675 v2si __builtin_arm_wsllwi (v2si, int);
16676 long long __builtin_arm_wsrad (long long, long long);
16677 long long __builtin_arm_wsradi (long long, int);
16678 v4hi __builtin_arm_wsrah (v4hi, long long);
16679 v4hi __builtin_arm_wsrahi (v4hi, int);
16680 v2si __builtin_arm_wsraw (v2si, long long);
16681 v2si __builtin_arm_wsrawi (v2si, int);
16682 long long __builtin_arm_wsrld (long long, long long);
16683 long long __builtin_arm_wsrldi (long long, int);
16684 v4hi __builtin_arm_wsrlh (v4hi, long long);
16685 v4hi __builtin_arm_wsrlhi (v4hi, int);
16686 v2si __builtin_arm_wsrlw (v2si, long long);
16687 v2si __builtin_arm_wsrlwi (v2si, int);
16688 v8qi __builtin_arm_wsubb (v8qi, v8qi);
16689 v8qi __builtin_arm_wsubbss (v8qi, v8qi);
16690 v8qi __builtin_arm_wsubbus (v8qi, v8qi);
16691 v4hi __builtin_arm_wsubh (v4hi, v4hi);
16692 v4hi __builtin_arm_wsubhss (v4hi, v4hi);
16693 v4hi __builtin_arm_wsubhus (v4hi, v4hi);
16694 v2si __builtin_arm_wsubw (v2si, v2si);
16695 v2si __builtin_arm_wsubwss (v2si, v2si);
16696 v2si __builtin_arm_wsubwus (v2si, v2si);
16697 v4hi __builtin_arm_wunpckehsb (v8qi);
16698 v2si __builtin_arm_wunpckehsh (v4hi);
16699 long long __builtin_arm_wunpckehsw (v2si);
16700 v4hi __builtin_arm_wunpckehub (v8qi);
16701 v2si __builtin_arm_wunpckehuh (v4hi);
16702 long long __builtin_arm_wunpckehuw (v2si);
16703 v4hi __builtin_arm_wunpckelsb (v8qi);
16704 v2si __builtin_arm_wunpckelsh (v4hi);
16705 long long __builtin_arm_wunpckelsw (v2si);
16706 v4hi __builtin_arm_wunpckelub (v8qi);
16707 v2si __builtin_arm_wunpckeluh (v4hi);
16708 long long __builtin_arm_wunpckeluw (v2si);
16709 v8qi __builtin_arm_wunpckihb (v8qi, v8qi);
16710 v4hi __builtin_arm_wunpckihh (v4hi, v4hi);
16711 v2si __builtin_arm_wunpckihw (v2si, v2si);
16712 v8qi __builtin_arm_wunpckilb (v8qi, v8qi);
16713 v4hi __builtin_arm_wunpckilh (v4hi, v4hi);
16714 v2si __builtin_arm_wunpckilw (v2si, v2si);
16715 long long __builtin_arm_wxor (long long, long long);
16716 long long __builtin_arm_wzero ();
16720 @node ARM C Language Extensions (ACLE)
16721 @subsection ARM C Language Extensions (ACLE)
16723 GCC implements extensions for C as described in the ARM C Language
16724 Extensions (ACLE) specification, which can be found at
16725 @uref{https://developer.arm.com/documentation/ihi0053/latest/}.
16727 As a part of ACLE, GCC implements extensions for Advanced SIMD as described in
16728 the ARM C Language Extensions Specification. The complete list of Advanced SIMD
16729 intrinsics can be found at
16730 @uref{https://developer.arm.com/documentation/ihi0073/latest/}.
16731 The built-in intrinsics for the Advanced SIMD extension are available when
16734 Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both
16735 back ends support CRC32 intrinsics and the ARM back end supports the
16736 Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit
16737 floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1.
16738 AArch64's back end does not have support for 16-bit floating point Advanced SIMD
16741 See @ref{ARM Options} and @ref{AArch64 Options} for more information on the
16742 availability of extensions.
16744 @node ARM Floating Point Status and Control Intrinsics
16745 @subsection ARM Floating Point Status and Control Intrinsics
16747 These built-in functions are available for the ARM family of
16748 processors with floating-point unit.
16751 unsigned int __builtin_arm_get_fpscr ();
16752 void __builtin_arm_set_fpscr (unsigned int);
16755 @node ARM ARMv8-M Security Extensions
16756 @subsection ARM ARMv8-M Security Extensions
16758 GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M
16759 Security Extensions: Requirements on Development Tools Engineering
16760 Specification, which can be found at
16761 @uref{https://developer.arm.com/documentation/ecm0359818/latest/}.
16763 As part of the Security Extensions GCC implements two new function attributes:
16764 @code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}.
16766 As part of the Security Extensions GCC implements the intrinsics below. FPTR
16767 is used here to mean any function pointer type.
16770 cmse_address_info_t cmse_TT (void *);
16771 cmse_address_info_t cmse_TT_fptr (FPTR);
16772 cmse_address_info_t cmse_TTT (void *);
16773 cmse_address_info_t cmse_TTT_fptr (FPTR);
16774 cmse_address_info_t cmse_TTA (void *);
16775 cmse_address_info_t cmse_TTA_fptr (FPTR);
16776 cmse_address_info_t cmse_TTAT (void *);
16777 cmse_address_info_t cmse_TTAT_fptr (FPTR);
16778 void * cmse_check_address_range (void *, size_t, int);
16779 typeof(p) cmse_nsfptr_create (FPTR p);
16780 intptr_t cmse_is_nsfptr (FPTR);
16781 int cmse_nonsecure_caller (void);
16784 @node AVR Built-in Functions
16785 @subsection AVR Built-in Functions
16787 For each built-in function for AVR, there is an equally named,
16788 uppercase built-in macro defined. That way users can easily query if
16789 or if not a specific built-in is implemented or not. For example, if
16790 @code{__builtin_avr_nop} is available the macro
16791 @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise.
16793 @defbuiltin{void __builtin_avr_nop (void)}
16794 @defbuiltinx{void __builtin_avr_sei (void)}
16795 @defbuiltinx{void __builtin_avr_cli (void)}
16796 @defbuiltinx{void __builtin_avr_sleep (void)}
16797 @defbuiltinx{void __builtin_avr_wdr (void)}
16798 @defbuiltinx{uint8_t __builtin_avr_swap (uint8_t)}
16799 @defbuiltinx{uint16_t __builtin_avr_fmul (uint8_t, uint8_t)}
16800 @defbuiltinx{int16_t __builtin_avr_fmuls (int8_t, int8_t)}
16801 @defbuiltinx{int16_t __builtin_avr_fmulsu (int8_t, uint8_t)}
16803 These built-in functions map to the respective machine
16804 instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep},
16805 @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls}
16806 resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented
16807 as library call if no hardware multiplier is available.
16810 @defbuiltin{void __builtin_avr_delay_cycles (uint32_t @var{ticks})}
16811 Delay execution for @var{ticks} cycles. Note that this
16812 built-in does not take into account the effect of interrupts that
16813 might increase delay time. @var{ticks} must be a compile-time
16814 integer constant; delays with a variable number of cycles are not supported.
16817 @defbuiltin{int8_t __builtin_avr_flash_segment (const __memx void*)}
16818 This built-in takes a byte address to the 24-bit
16819 @ref{AVR Named Address Spaces,address space} @code{__memx} and returns
16820 the number of the flash segment (the 64 KiB chunk) where the address
16821 points to. Counting starts at @code{0}.
16822 If the address does not point to flash memory, return @code{-1}.
16825 @defbuiltin{uint8_t __builtin_avr_insert_bits (uint32_t @var{map}, uint8_t @var{bits}, uint8_t @var{val})}
16826 Insert bits from @var{bits} into @var{val} and return the resulting
16827 value. The nibbles of @var{map} determine how the insertion is
16828 performed: Let @var{X} be the @var{n}-th nibble of @var{map}
16830 @item If @var{X} is @code{0xf},
16831 then the @var{n}-th bit of @var{val} is returned unaltered.
16833 @item If X is in the range 0@dots{}7,
16834 then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits}
16836 @item If X is in the range 8@dots{}@code{0xe},
16837 then the @var{n}-th result bit is undefined.
16841 One typical use case for this built-in is adjusting input and
16842 output values to non-contiguous port layouts. Some examples:
16845 // same as val, bits is unused
16846 __builtin_avr_insert_bits (0xffffffff, bits, val);
16850 // same as bits, val is unused
16851 __builtin_avr_insert_bits (0x76543210, bits, val);
16855 // same as rotating bits by 4
16856 __builtin_avr_insert_bits (0x32107654, bits, 0);
16860 // high nibble of result is the high nibble of val
16861 // low nibble of result is the low nibble of bits
16862 __builtin_avr_insert_bits (0xffff3210, bits, val);
16866 // reverse the bit order of bits
16867 __builtin_avr_insert_bits (0x01234567, bits, 0);
16871 @defbuiltin{void __builtin_avr_nops (uint16_t @var{count})}
16872 Insert @var{count} @code{NOP} instructions.
16873 The number of instructions must be a compile-time integer constant.
16877 There are many more AVR-specific built-in functions that are used to
16878 implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of
16879 section 7.18a.6. You don't need to use these built-ins directly.
16880 Instead, use the declarations as supplied by the @code{stdfix.h} header
16884 #include <stdfix.h>
16886 // Re-interpret the bit representation of unsigned 16-bit
16887 // integer @var{uval} as Q-format 0.16 value.
16888 unsigned fract get_bits (uint_ur_t uval)
16890 return urbits (uval);
16894 @node Blackfin Built-in Functions
16895 @subsection Blackfin Built-in Functions
16897 Currently, there are two Blackfin-specific built-in functions. These are
16898 used for generating @code{CSYNC} and @code{SSYNC} machine insns without
16899 using inline assembly; by using these built-in functions the compiler can
16900 automatically add workarounds for hardware errata involving these
16901 instructions. These functions are named as follows:
16904 void __builtin_bfin_csync (void);
16905 void __builtin_bfin_ssync (void);
16908 @node BPF Built-in Functions
16909 @subsection BPF Built-in Functions
16911 The following built-in functions are available for eBPF targets.
16913 @defbuiltin{{unsigned long long} __builtin_bpf_load_byte (unsigned long long @var{offset})}
16914 Load a byte from the @code{struct sk_buff} packet data pointed to by the
16915 register @code{%r6}, and return it.
16918 @defbuiltin{{unsigned long long} __builtin_bpf_load_half (unsigned long long @var{offset})}
16919 Load 16 bits from the @code{struct sk_buff} packet data pointed to by the
16920 register @code{%r6}, and return it.
16923 @defbuiltin{{unsigned long long} __builtin_bpf_load_word (unsigned long long @var{offset})}
16924 Load 32 bits from the @code{struct sk_buff} packet data pointed to by the
16925 register @code{%r6}, and return it.
16928 @defbuiltin{@var{type} __builtin_preserve_access_index (@var{type} @var{expr})}
16929 BPF Compile Once-Run Everywhere (CO-RE) support. Instruct GCC to
16930 generate CO-RE relocation records for any accesses to aggregate
16931 data structures (struct, union, array types) in @var{expr}. This builtin
16932 is otherwise transparent; @var{expr} may have any type and its value is
16933 returned. This builtin has no effect if @code{-mco-re} is not in effect
16934 (either specified or implied).
16937 @defbuiltin{{unsigned int} __builtin_preserve_field_info (@var{expr}, unsigned int @var{kind})}
16938 BPF Compile Once-Run Everywhere (CO-RE) support. This builtin is used to
16939 extract information to aid in struct/union relocations. @var{expr} is
16940 an access to a field of a struct or union. Depending on @var{kind}, different
16941 information is returned to the program. A CO-RE relocation for the access in
16942 @var{expr} with kind @var{kind} is recorded if @code{-mco-re} is in effect.
16944 The following values are supported for @var{kind}:
16946 @item FIELD_BYTE_OFFSET = 0
16947 The returned value is the offset, in bytes, of the field from the
16948 beginning of the containing structure. For bit-fields, this is the byte offset
16949 of the containing word.
16951 @item FIELD_BYTE_SIZE = 1
16952 The returned value is the size, in bytes, of the field. For bit-fields,
16953 this is the size in bytes of the containing word.
16955 @item FIELD_EXISTENCE = 2
16956 The returned value is 1 if the field exists, 0 otherwise. Always 1 at
16959 @item FIELD_SIGNEDNESS = 3
16960 The returned value is 1 if the field is signed, 0 otherwise.
16962 @item FIELD_LSHIFT_U64 = 4
16963 @itemx FIELD_RSHIFT_U64 = 5
16964 The returned value is the number of bits of left- or right-shifting
16965 (respectively) needed in order to recover the original value of the field,
16966 after it has been loaded by a read of @code{FIELD_BYTE_SIZE} bytes into an
16967 unsigned 64-bit value. Primarily useful for reading bit-field values
16968 from structures that may change between kernel versions.
16972 Note that the return value is a constant which is known at
16973 compile time. If the field has a variable offset then
16974 @code{FIELD_BYTE_OFFSET}, @code{FIELD_LSHIFT_U64},
16975 and @code{FIELD_RSHIFT_U64} are not supported.
16976 Similarly, if the field has a variable size then
16977 @code{FIELD_BYTE_SIZE}, @code{FIELD_LSHIFT_U64},
16978 and @code{FIELD_RSHIFT_U64} are not supported.
16980 For example, @code{__builtin_preserve_field_info} can be used to reliably
16981 extract bit-field values from a structure that may change between
16993 read_y (struct S *arg)
16995 unsigned long long val;
16996 unsigned int offset
16997 = __builtin_preserve_field_info (arg->y, FIELD_BYTE_OFFSET);
16999 = __builtin_preserve_field_info (arg->y, FIELD_BYTE_SIZE);
17001 /* Read size bytes from arg + offset into val. */
17002 bpf_probe_read (&val, size, arg + offset);
17004 val <<= __builtin_preserve_field_info (arg->y, FIELD_LSHIFT_U64);
17006 if (__builtin_preserve_field_info (arg->y, FIELD_SIGNEDNESS))
17007 val = ((long long) val
17008 >> __builtin_preserve_field_info (arg->y, FIELD_RSHIFT_U64));
17010 val >>= __builtin_preserve_field_info (arg->y, FIELD_RSHIFT_U64);
17018 @defbuiltin{{unsigned int} __builtin_preserve_enum_value (@var{type}, @var{enum}, unsigned int @var{kind})}
17019 BPF Compile Once-Run Everywhere (CO-RE) support. This builtin collects enum
17020 information and creates a CO-RE relocation relative to @var{enum} that should
17021 be of @var{type}. The @var{kind} specifies the action performed.
17023 The following values are supported for @var{kind}:
17025 @item ENUM_VALUE_EXISTS = 0
17026 The return value is either 0 or 1 depending if the enum value exists in the
17029 @item ENUM_VALUE = 1
17030 The return value is the enum value in the target kernel.
17034 @defbuiltin{{unsigned int} __builtin_btf_type_id (@var{type}, unsigned int @var{kind})}
17035 BPF Compile Once-Run Everywhere (CO-RE) support. This builtin is used to get
17036 the BTF type ID of a specified @var{type}.
17037 Depending on the @var{kind} argument, it
17038 either returns the ID of the local BTF information, or the BTF type ID in
17041 The following values are supported for @var{kind}:
17043 @item BTF_TYPE_ID_LOCAL = 0
17044 Return the local BTF type ID. Always succeeds.
17046 @item BTF_TYPE_ID_TARGET = 1
17047 Return the target BTF type ID. If @var{type} does not exist in the target,
17052 @defbuiltin{{unsigned int} __builtin_preserve_type_info (@var{type}, unsigned int @var{kind})}
17053 BPF Compile Once-Run Everywhere (CO-RE) support. This builtin performs named
17054 type (struct/union/enum/typedef) verifications. The type of verification
17055 depends on the @var{kind} argument provided. This builtin always
17056 returns 0 if @var{type} does not exist in the target kernel.
17058 The following values are supported for @var{kind}:
17060 @item BTF_TYPE_EXISTS = 0
17061 Checks if @var{type} exists in the target.
17063 @item BTF_TYPE_MATCHES = 1
17064 Checks if @var{type} matches the local definition in the target kernel.
17066 @item BTF_TYPE_SIZE = 2
17067 Returns the size of the @var{type} within the target.
17071 @node FR-V Built-in Functions
17072 @subsection FR-V Built-in Functions
17074 GCC provides many FR-V-specific built-in functions. In general,
17075 these functions are intended to be compatible with those described
17076 by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu
17077 Semiconductor}. The two exceptions are @code{__MDUNPACKH} and
17078 @code{__MBTOHE}, the GCC forms of which pass 128-bit values by
17079 pointer rather than by value.
17081 Most of the functions are named after specific FR-V instructions.
17082 Such functions are said to be ``directly mapped'' and are summarized
17083 here in tabular form.
17087 * Directly-mapped Integer Functions::
17088 * Directly-mapped Media Functions::
17089 * Raw read/write Functions::
17090 * Other Built-in Functions::
17093 @node Argument Types
17094 @subsubsection Argument Types
17096 The arguments to the built-in functions can be divided into three groups:
17097 register numbers, compile-time constants and run-time values. In order
17098 to make this classification clear at a glance, the arguments and return
17099 values are given the following pseudo types:
17101 @multitable @columnfractions .20 .30 .15 .35
17102 @headitem Pseudo type @tab Real C type @tab Constant? @tab Description
17103 @item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword
17104 @item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word
17105 @item @code{sw1} @tab @code{int} @tab No @tab a signed word
17106 @item @code{uw2} @tab @code{unsigned long long} @tab No
17107 @tab an unsigned doubleword
17108 @item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword
17109 @item @code{const} @tab @code{int} @tab Yes @tab an integer constant
17110 @item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number
17111 @item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number
17114 These pseudo types are not defined by GCC, they are simply a notational
17115 convenience used in this manual.
17117 Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2}
17118 and @code{sw2} are evaluated at run time. They correspond to
17119 register operands in the underlying FR-V instructions.
17121 @code{const} arguments represent immediate operands in the underlying
17122 FR-V instructions. They must be compile-time constants.
17124 @code{acc} arguments are evaluated at compile time and specify the number
17125 of an accumulator register. For example, an @code{acc} argument of 2
17126 selects the ACC2 register.
17128 @code{iacc} arguments are similar to @code{acc} arguments but specify the
17129 number of an IACC register. See @pxref{Other Built-in Functions}
17132 @node Directly-mapped Integer Functions
17133 @subsubsection Directly-Mapped Integer Functions
17135 The functions listed below map directly to FR-V I-type instructions.
17137 @multitable @columnfractions .45 .32 .23
17138 @headitem Function prototype @tab Example usage @tab Assembly output
17139 @item @code{sw1 __ADDSS (sw1, sw1)}
17140 @tab @code{@var{c} = __ADDSS (@var{a}, @var{b})}
17141 @tab @code{ADDSS @var{a},@var{b},@var{c}}
17142 @item @code{sw1 __SCAN (sw1, sw1)}
17143 @tab @code{@var{c} = __SCAN (@var{a}, @var{b})}
17144 @tab @code{SCAN @var{a},@var{b},@var{c}}
17145 @item @code{sw1 __SCUTSS (sw1)}
17146 @tab @code{@var{b} = __SCUTSS (@var{a})}
17147 @tab @code{SCUTSS @var{a},@var{b}}
17148 @item @code{sw1 __SLASS (sw1, sw1)}
17149 @tab @code{@var{c} = __SLASS (@var{a}, @var{b})}
17150 @tab @code{SLASS @var{a},@var{b},@var{c}}
17151 @item @code{void __SMASS (sw1, sw1)}
17152 @tab @code{__SMASS (@var{a}, @var{b})}
17153 @tab @code{SMASS @var{a},@var{b}}
17154 @item @code{void __SMSSS (sw1, sw1)}
17155 @tab @code{__SMSSS (@var{a}, @var{b})}
17156 @tab @code{SMSSS @var{a},@var{b}}
17157 @item @code{void __SMU (sw1, sw1)}
17158 @tab @code{__SMU (@var{a}, @var{b})}
17159 @tab @code{SMU @var{a},@var{b}}
17160 @item @code{sw2 __SMUL (sw1, sw1)}
17161 @tab @code{@var{c} = __SMUL (@var{a}, @var{b})}
17162 @tab @code{SMUL @var{a},@var{b},@var{c}}
17163 @item @code{sw1 __SUBSS (sw1, sw1)}
17164 @tab @code{@var{c} = __SUBSS (@var{a}, @var{b})}
17165 @tab @code{SUBSS @var{a},@var{b},@var{c}}
17166 @item @code{uw2 __UMUL (uw1, uw1)}
17167 @tab @code{@var{c} = __UMUL (@var{a}, @var{b})}
17168 @tab @code{UMUL @var{a},@var{b},@var{c}}
17171 @node Directly-mapped Media Functions
17172 @subsubsection Directly-Mapped Media Functions
17174 The functions listed below map directly to FR-V M-type instructions.
17176 @multitable @columnfractions .45 .32 .23
17177 @headitem Function prototype @tab Example usage @tab Assembly output
17178 @item @code{uw1 __MABSHS (sw1)}
17179 @tab @code{@var{b} = __MABSHS (@var{a})}
17180 @tab @code{MABSHS @var{a},@var{b}}
17181 @item @code{void __MADDACCS (acc, acc)}
17182 @tab @code{__MADDACCS (@var{b}, @var{a})}
17183 @tab @code{MADDACCS @var{a},@var{b}}
17184 @item @code{sw1 __MADDHSS (sw1, sw1)}
17185 @tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})}
17186 @tab @code{MADDHSS @var{a},@var{b},@var{c}}
17187 @item @code{uw1 __MADDHUS (uw1, uw1)}
17188 @tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})}
17189 @tab @code{MADDHUS @var{a},@var{b},@var{c}}
17190 @item @code{uw1 __MAND (uw1, uw1)}
17191 @tab @code{@var{c} = __MAND (@var{a}, @var{b})}
17192 @tab @code{MAND @var{a},@var{b},@var{c}}
17193 @item @code{void __MASACCS (acc, acc)}
17194 @tab @code{__MASACCS (@var{b}, @var{a})}
17195 @tab @code{MASACCS @var{a},@var{b}}
17196 @item @code{uw1 __MAVEH (uw1, uw1)}
17197 @tab @code{@var{c} = __MAVEH (@var{a}, @var{b})}
17198 @tab @code{MAVEH @var{a},@var{b},@var{c}}
17199 @item @code{uw2 __MBTOH (uw1)}
17200 @tab @code{@var{b} = __MBTOH (@var{a})}
17201 @tab @code{MBTOH @var{a},@var{b}}
17202 @item @code{void __MBTOHE (uw1 *, uw1)}
17203 @tab @code{__MBTOHE (&@var{b}, @var{a})}
17204 @tab @code{MBTOHE @var{a},@var{b}}
17205 @item @code{void __MCLRACC (acc)}
17206 @tab @code{__MCLRACC (@var{a})}
17207 @tab @code{MCLRACC @var{a}}
17208 @item @code{void __MCLRACCA (void)}
17209 @tab @code{__MCLRACCA ()}
17210 @tab @code{MCLRACCA}
17211 @item @code{uw1 __Mcop1 (uw1, uw1)}
17212 @tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})}
17213 @tab @code{Mcop1 @var{a},@var{b},@var{c}}
17214 @item @code{uw1 __Mcop2 (uw1, uw1)}
17215 @tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})}
17216 @tab @code{Mcop2 @var{a},@var{b},@var{c}}
17217 @item @code{uw1 __MCPLHI (uw2, const)}
17218 @tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})}
17219 @tab @code{MCPLHI @var{a},#@var{b},@var{c}}
17220 @item @code{uw1 __MCPLI (uw2, const)}
17221 @tab @code{@var{c} = __MCPLI (@var{a}, @var{b})}
17222 @tab @code{MCPLI @var{a},#@var{b},@var{c}}
17223 @item @code{void __MCPXIS (acc, sw1, sw1)}
17224 @tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})}
17225 @tab @code{MCPXIS @var{a},@var{b},@var{c}}
17226 @item @code{void __MCPXIU (acc, uw1, uw1)}
17227 @tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})}
17228 @tab @code{MCPXIU @var{a},@var{b},@var{c}}
17229 @item @code{void __MCPXRS (acc, sw1, sw1)}
17230 @tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})}
17231 @tab @code{MCPXRS @var{a},@var{b},@var{c}}
17232 @item @code{void __MCPXRU (acc, uw1, uw1)}
17233 @tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})}
17234 @tab @code{MCPXRU @var{a},@var{b},@var{c}}
17235 @item @code{uw1 __MCUT (acc, uw1)}
17236 @tab @code{@var{c} = __MCUT (@var{a}, @var{b})}
17237 @tab @code{MCUT @var{a},@var{b},@var{c}}
17238 @item @code{uw1 __MCUTSS (acc, sw1)}
17239 @tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})}
17240 @tab @code{MCUTSS @var{a},@var{b},@var{c}}
17241 @item @code{void __MDADDACCS (acc, acc)}
17242 @tab @code{__MDADDACCS (@var{b}, @var{a})}
17243 @tab @code{MDADDACCS @var{a},@var{b}}
17244 @item @code{void __MDASACCS (acc, acc)}
17245 @tab @code{__MDASACCS (@var{b}, @var{a})}
17246 @tab @code{MDASACCS @var{a},@var{b}}
17247 @item @code{uw2 __MDCUTSSI (acc, const)}
17248 @tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})}
17249 @tab @code{MDCUTSSI @var{a},#@var{b},@var{c}}
17250 @item @code{uw2 __MDPACKH (uw2, uw2)}
17251 @tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})}
17252 @tab @code{MDPACKH @var{a},@var{b},@var{c}}
17253 @item @code{uw2 __MDROTLI (uw2, const)}
17254 @tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})}
17255 @tab @code{MDROTLI @var{a},#@var{b},@var{c}}
17256 @item @code{void __MDSUBACCS (acc, acc)}
17257 @tab @code{__MDSUBACCS (@var{b}, @var{a})}
17258 @tab @code{MDSUBACCS @var{a},@var{b}}
17259 @item @code{void __MDUNPACKH (uw1 *, uw2)}
17260 @tab @code{__MDUNPACKH (&@var{b}, @var{a})}
17261 @tab @code{MDUNPACKH @var{a},@var{b}}
17262 @item @code{uw2 __MEXPDHD (uw1, const)}
17263 @tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})}
17264 @tab @code{MEXPDHD @var{a},#@var{b},@var{c}}
17265 @item @code{uw1 __MEXPDHW (uw1, const)}
17266 @tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})}
17267 @tab @code{MEXPDHW @var{a},#@var{b},@var{c}}
17268 @item @code{uw1 __MHDSETH (uw1, const)}
17269 @tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})}
17270 @tab @code{MHDSETH @var{a},#@var{b},@var{c}}
17271 @item @code{sw1 __MHDSETS (const)}
17272 @tab @code{@var{b} = __MHDSETS (@var{a})}
17273 @tab @code{MHDSETS #@var{a},@var{b}}
17274 @item @code{uw1 __MHSETHIH (uw1, const)}
17275 @tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})}
17276 @tab @code{MHSETHIH #@var{a},@var{b}}
17277 @item @code{sw1 __MHSETHIS (sw1, const)}
17278 @tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})}
17279 @tab @code{MHSETHIS #@var{a},@var{b}}
17280 @item @code{uw1 __MHSETLOH (uw1, const)}
17281 @tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})}
17282 @tab @code{MHSETLOH #@var{a},@var{b}}
17283 @item @code{sw1 __MHSETLOS (sw1, const)}
17284 @tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})}
17285 @tab @code{MHSETLOS #@var{a},@var{b}}
17286 @item @code{uw1 __MHTOB (uw2)}
17287 @tab @code{@var{b} = __MHTOB (@var{a})}
17288 @tab @code{MHTOB @var{a},@var{b}}
17289 @item @code{void __MMACHS (acc, sw1, sw1)}
17290 @tab @code{__MMACHS (@var{c}, @var{a}, @var{b})}
17291 @tab @code{MMACHS @var{a},@var{b},@var{c}}
17292 @item @code{void __MMACHU (acc, uw1, uw1)}
17293 @tab @code{__MMACHU (@var{c}, @var{a}, @var{b})}
17294 @tab @code{MMACHU @var{a},@var{b},@var{c}}
17295 @item @code{void __MMRDHS (acc, sw1, sw1)}
17296 @tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})}
17297 @tab @code{MMRDHS @var{a},@var{b},@var{c}}
17298 @item @code{void __MMRDHU (acc, uw1, uw1)}
17299 @tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})}
17300 @tab @code{MMRDHU @var{a},@var{b},@var{c}}
17301 @item @code{void __MMULHS (acc, sw1, sw1)}
17302 @tab @code{__MMULHS (@var{c}, @var{a}, @var{b})}
17303 @tab @code{MMULHS @var{a},@var{b},@var{c}}
17304 @item @code{void __MMULHU (acc, uw1, uw1)}
17305 @tab @code{__MMULHU (@var{c}, @var{a}, @var{b})}
17306 @tab @code{MMULHU @var{a},@var{b},@var{c}}
17307 @item @code{void __MMULXHS (acc, sw1, sw1)}
17308 @tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})}
17309 @tab @code{MMULXHS @var{a},@var{b},@var{c}}
17310 @item @code{void __MMULXHU (acc, uw1, uw1)}
17311 @tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})}
17312 @tab @code{MMULXHU @var{a},@var{b},@var{c}}
17313 @item @code{uw1 __MNOT (uw1)}
17314 @tab @code{@var{b} = __MNOT (@var{a})}
17315 @tab @code{MNOT @var{a},@var{b}}
17316 @item @code{uw1 __MOR (uw1, uw1)}
17317 @tab @code{@var{c} = __MOR (@var{a}, @var{b})}
17318 @tab @code{MOR @var{a},@var{b},@var{c}}
17319 @item @code{uw1 __MPACKH (uh, uh)}
17320 @tab @code{@var{c} = __MPACKH (@var{a}, @var{b})}
17321 @tab @code{MPACKH @var{a},@var{b},@var{c}}
17322 @item @code{sw2 __MQADDHSS (sw2, sw2)}
17323 @tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})}
17324 @tab @code{MQADDHSS @var{a},@var{b},@var{c}}
17325 @item @code{uw2 __MQADDHUS (uw2, uw2)}
17326 @tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})}
17327 @tab @code{MQADDHUS @var{a},@var{b},@var{c}}
17328 @item @code{void __MQCPXIS (acc, sw2, sw2)}
17329 @tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})}
17330 @tab @code{MQCPXIS @var{a},@var{b},@var{c}}
17331 @item @code{void __MQCPXIU (acc, uw2, uw2)}
17332 @tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})}
17333 @tab @code{MQCPXIU @var{a},@var{b},@var{c}}
17334 @item @code{void __MQCPXRS (acc, sw2, sw2)}
17335 @tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})}
17336 @tab @code{MQCPXRS @var{a},@var{b},@var{c}}
17337 @item @code{void __MQCPXRU (acc, uw2, uw2)}
17338 @tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})}
17339 @tab @code{MQCPXRU @var{a},@var{b},@var{c}}
17340 @item @code{sw2 __MQLCLRHS (sw2, sw2)}
17341 @tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})}
17342 @tab @code{MQLCLRHS @var{a},@var{b},@var{c}}
17343 @item @code{sw2 __MQLMTHS (sw2, sw2)}
17344 @tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})}
17345 @tab @code{MQLMTHS @var{a},@var{b},@var{c}}
17346 @item @code{void __MQMACHS (acc, sw2, sw2)}
17347 @tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})}
17348 @tab @code{MQMACHS @var{a},@var{b},@var{c}}
17349 @item @code{void __MQMACHU (acc, uw2, uw2)}
17350 @tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})}
17351 @tab @code{MQMACHU @var{a},@var{b},@var{c}}
17352 @item @code{void __MQMACXHS (acc, sw2, sw2)}
17353 @tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})}
17354 @tab @code{MQMACXHS @var{a},@var{b},@var{c}}
17355 @item @code{void __MQMULHS (acc, sw2, sw2)}
17356 @tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})}
17357 @tab @code{MQMULHS @var{a},@var{b},@var{c}}
17358 @item @code{void __MQMULHU (acc, uw2, uw2)}
17359 @tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})}
17360 @tab @code{MQMULHU @var{a},@var{b},@var{c}}
17361 @item @code{void __MQMULXHS (acc, sw2, sw2)}
17362 @tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})}
17363 @tab @code{MQMULXHS @var{a},@var{b},@var{c}}
17364 @item @code{void __MQMULXHU (acc, uw2, uw2)}
17365 @tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})}
17366 @tab @code{MQMULXHU @var{a},@var{b},@var{c}}
17367 @item @code{sw2 __MQSATHS (sw2, sw2)}
17368 @tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})}
17369 @tab @code{MQSATHS @var{a},@var{b},@var{c}}
17370 @item @code{uw2 __MQSLLHI (uw2, int)}
17371 @tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})}
17372 @tab @code{MQSLLHI @var{a},@var{b},@var{c}}
17373 @item @code{sw2 __MQSRAHI (sw2, int)}
17374 @tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})}
17375 @tab @code{MQSRAHI @var{a},@var{b},@var{c}}
17376 @item @code{sw2 __MQSUBHSS (sw2, sw2)}
17377 @tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})}
17378 @tab @code{MQSUBHSS @var{a},@var{b},@var{c}}
17379 @item @code{uw2 __MQSUBHUS (uw2, uw2)}
17380 @tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})}
17381 @tab @code{MQSUBHUS @var{a},@var{b},@var{c}}
17382 @item @code{void __MQXMACHS (acc, sw2, sw2)}
17383 @tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})}
17384 @tab @code{MQXMACHS @var{a},@var{b},@var{c}}
17385 @item @code{void __MQXMACXHS (acc, sw2, sw2)}
17386 @tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})}
17387 @tab @code{MQXMACXHS @var{a},@var{b},@var{c}}
17388 @item @code{uw1 __MRDACC (acc)}
17389 @tab @code{@var{b} = __MRDACC (@var{a})}
17390 @tab @code{MRDACC @var{a},@var{b}}
17391 @item @code{uw1 __MRDACCG (acc)}
17392 @tab @code{@var{b} = __MRDACCG (@var{a})}
17393 @tab @code{MRDACCG @var{a},@var{b}}
17394 @item @code{uw1 __MROTLI (uw1, const)}
17395 @tab @code{@var{c} = __MROTLI (@var{a}, @var{b})}
17396 @tab @code{MROTLI @var{a},#@var{b},@var{c}}
17397 @item @code{uw1 __MROTRI (uw1, const)}
17398 @tab @code{@var{c} = __MROTRI (@var{a}, @var{b})}
17399 @tab @code{MROTRI @var{a},#@var{b},@var{c}}
17400 @item @code{sw1 __MSATHS (sw1, sw1)}
17401 @tab @code{@var{c} = __MSATHS (@var{a}, @var{b})}
17402 @tab @code{MSATHS @var{a},@var{b},@var{c}}
17403 @item @code{uw1 __MSATHU (uw1, uw1)}
17404 @tab @code{@var{c} = __MSATHU (@var{a}, @var{b})}
17405 @tab @code{MSATHU @var{a},@var{b},@var{c}}
17406 @item @code{uw1 __MSLLHI (uw1, const)}
17407 @tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})}
17408 @tab @code{MSLLHI @var{a},#@var{b},@var{c}}
17409 @item @code{sw1 __MSRAHI (sw1, const)}
17410 @tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})}
17411 @tab @code{MSRAHI @var{a},#@var{b},@var{c}}
17412 @item @code{uw1 __MSRLHI (uw1, const)}
17413 @tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})}
17414 @tab @code{MSRLHI @var{a},#@var{b},@var{c}}
17415 @item @code{void __MSUBACCS (acc, acc)}
17416 @tab @code{__MSUBACCS (@var{b}, @var{a})}
17417 @tab @code{MSUBACCS @var{a},@var{b}}
17418 @item @code{sw1 __MSUBHSS (sw1, sw1)}
17419 @tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})}
17420 @tab @code{MSUBHSS @var{a},@var{b},@var{c}}
17421 @item @code{uw1 __MSUBHUS (uw1, uw1)}
17422 @tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})}
17423 @tab @code{MSUBHUS @var{a},@var{b},@var{c}}
17424 @item @code{void __MTRAP (void)}
17425 @tab @code{__MTRAP ()}
17427 @item @code{uw2 __MUNPACKH (uw1)}
17428 @tab @code{@var{b} = __MUNPACKH (@var{a})}
17429 @tab @code{MUNPACKH @var{a},@var{b}}
17430 @item @code{uw1 __MWCUT (uw2, uw1)}
17431 @tab @code{@var{c} = __MWCUT (@var{a}, @var{b})}
17432 @tab @code{MWCUT @var{a},@var{b},@var{c}}
17433 @item @code{void __MWTACC (acc, uw1)}
17434 @tab @code{__MWTACC (@var{b}, @var{a})}
17435 @tab @code{MWTACC @var{a},@var{b}}
17436 @item @code{void __MWTACCG (acc, uw1)}
17437 @tab @code{__MWTACCG (@var{b}, @var{a})}
17438 @tab @code{MWTACCG @var{a},@var{b}}
17439 @item @code{uw1 __MXOR (uw1, uw1)}
17440 @tab @code{@var{c} = __MXOR (@var{a}, @var{b})}
17441 @tab @code{MXOR @var{a},@var{b},@var{c}}
17444 @node Raw read/write Functions
17445 @subsubsection Raw Read/Write Functions
17447 This sections describes built-in functions related to read and write
17448 instructions to access memory. These functions generate
17449 @code{membar} instructions to flush the I/O load and stores where
17450 appropriate, as described in Fujitsu's manual described above.
17454 @item unsigned char __builtin_read8 (void *@var{data})
17455 @item unsigned short __builtin_read16 (void *@var{data})
17456 @item unsigned long __builtin_read32 (void *@var{data})
17457 @item unsigned long long __builtin_read64 (void *@var{data})
17459 @item void __builtin_write8 (void *@var{data}, unsigned char @var{datum})
17460 @item void __builtin_write16 (void *@var{data}, unsigned short @var{datum})
17461 @item void __builtin_write32 (void *@var{data}, unsigned long @var{datum})
17462 @item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum})
17465 @node Other Built-in Functions
17466 @subsubsection Other Built-in Functions
17468 This section describes built-in functions that are not named after
17469 a specific FR-V instruction.
17472 @item sw2 __IACCreadll (iacc @var{reg})
17473 Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved
17474 for future expansion and must be 0.
17476 @item sw1 __IACCreadl (iacc @var{reg})
17477 Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1.
17478 Other values of @var{reg} are rejected as invalid.
17480 @item void __IACCsetll (iacc @var{reg}, sw2 @var{x})
17481 Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument
17482 is reserved for future expansion and must be 0.
17484 @item void __IACCsetl (iacc @var{reg}, sw1 @var{x})
17485 Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg}
17486 is 1. Other values of @var{reg} are rejected as invalid.
17488 @item void __data_prefetch0 (const void *@var{x})
17489 Use the @code{dcpl} instruction to load the contents of address @var{x}
17490 into the data cache.
17492 @item void __data_prefetch (const void *@var{x})
17493 Use the @code{nldub} instruction to load the contents of address @var{x}
17494 into the data cache. The instruction is issued in slot I1@.
17497 @node LoongArch Base Built-in Functions
17498 @subsection LoongArch Base Built-in Functions
17500 These built-in functions are available for LoongArch.
17502 Data Type Description:
17504 @item @code{imm0_31}, a compile-time constant in range 0 to 31;
17505 @item @code{imm0_16383}, a compile-time constant in range 0 to 16383;
17506 @item @code{imm0_32767}, a compile-time constant in range 0 to 32767;
17507 @item @code{imm_n2048_2047}, a compile-time constant in range -2048 to 2047;
17510 The intrinsics provided are listed below:
17512 unsigned int __builtin_loongarch_movfcsr2gr (imm0_31)
17513 void __builtin_loongarch_movgr2fcsr (imm0_31, unsigned int)
17514 void __builtin_loongarch_cacop_d (imm0_31, unsigned long int, imm_n2048_2047)
17515 unsigned int __builtin_loongarch_cpucfg (unsigned int)
17516 void __builtin_loongarch_asrtle_d (long int, long int)
17517 void __builtin_loongarch_asrtgt_d (long int, long int)
17518 long int __builtin_loongarch_lddir_d (long int, imm0_31)
17519 void __builtin_loongarch_ldpte_d (long int, imm0_31)
17521 int __builtin_loongarch_crc_w_b_w (char, int)
17522 int __builtin_loongarch_crc_w_h_w (short, int)
17523 int __builtin_loongarch_crc_w_w_w (int, int)
17524 int __builtin_loongarch_crc_w_d_w (long int, int)
17525 int __builtin_loongarch_crcc_w_b_w (char, int)
17526 int __builtin_loongarch_crcc_w_h_w (short, int)
17527 int __builtin_loongarch_crcc_w_w_w (int, int)
17528 int __builtin_loongarch_crcc_w_d_w (long int, int)
17530 unsigned int __builtin_loongarch_csrrd_w (imm0_16383)
17531 unsigned int __builtin_loongarch_csrwr_w (unsigned int, imm0_16383)
17532 unsigned int __builtin_loongarch_csrxchg_w (unsigned int, unsigned int, imm0_16383)
17533 unsigned long int __builtin_loongarch_csrrd_d (imm0_16383)
17534 unsigned long int __builtin_loongarch_csrwr_d (unsigned long int, imm0_16383)
17535 unsigned long int __builtin_loongarch_csrxchg_d (unsigned long int, unsigned long int, imm0_16383)
17537 unsigned char __builtin_loongarch_iocsrrd_b (unsigned int)
17538 unsigned short __builtin_loongarch_iocsrrd_h (unsigned int)
17539 unsigned int __builtin_loongarch_iocsrrd_w (unsigned int)
17540 unsigned long int __builtin_loongarch_iocsrrd_d (unsigned int)
17541 void __builtin_loongarch_iocsrwr_b (unsigned char, unsigned int)
17542 void __builtin_loongarch_iocsrwr_h (unsigned short, unsigned int)
17543 void __builtin_loongarch_iocsrwr_w (unsigned int, unsigned int)
17544 void __builtin_loongarch_iocsrwr_d (unsigned long int, unsigned int)
17546 void __builtin_loongarch_dbar (imm0_32767)
17547 void __builtin_loongarch_ibar (imm0_32767)
17549 void __builtin_loongarch_syscall (imm0_32767)
17550 void __builtin_loongarch_break (imm0_32767)
17553 These instrisic functions are available by using @option{-mfrecipe}.
17555 float __builtin_loongarch_frecipe_s (float);
17556 double __builtin_loongarch_frecipe_d (double);
17557 float __builtin_loongarch_frsqrte_s (float);
17558 double __builtin_loongarch_frsqrte_d (double);
17561 @emph{Note:}Since the control register is divided into 32-bit and 64-bit,
17562 but the access instruction is not distinguished. So GCC renames the control
17563 instructions when implementing intrinsics.
17565 Take the csrrd instruction as an example, built-in functions are implemented as follows:
17567 __builtin_loongarch_csrrd_w // When reading the 32-bit control register use.
17568 __builtin_loongarch_csrrd_d // When reading the 64-bit control register use.
17571 For the convenience of use, the built-in functions are encapsulated,
17572 the encapsulated functions and @code{__drdtime_t, __rdtime_t} are
17573 defined in the @code{larchintrin.h}. So if you call the following
17574 function you need to include @code{larchintrin.h}.
17577 typedef struct drdtime@{
17578 unsigned long dvalue;
17579 unsigned long dtimeid;
17582 typedef struct rdtime@{
17583 unsigned int value;
17584 unsigned int timeid;
17589 __drdtime_t __rdtime_d (void)
17590 __rdtime_t __rdtimel_w (void)
17591 __rdtime_t __rdtimeh_w (void)
17592 unsigned int __movfcsr2gr (imm0_31)
17593 void __movgr2fcsr (imm0_31, unsigned int)
17594 void __cacop_d (imm0_31, unsigned long, imm_n2048_2047)
17595 unsigned int __cpucfg (unsigned int)
17596 void __asrtle_d (long int, long int)
17597 void __asrtgt_d (long int, long int)
17598 long int __lddir_d (long int, imm0_31)
17599 void __ldpte_d (long int, imm0_31)
17601 int __crc_w_b_w (char, int)
17602 int __crc_w_h_w (short, int)
17603 int __crc_w_w_w (int, int)
17604 int __crc_w_d_w (long int, int)
17605 int __crcc_w_b_w (char, int)
17606 int __crcc_w_h_w (short, int)
17607 int __crcc_w_w_w (int, int)
17608 int __crcc_w_d_w (long int, int)
17610 unsigned int __csrrd_w (imm0_16383)
17611 unsigned int __csrwr_w (unsigned int, imm0_16383)
17612 unsigned int __csrxchg_w (unsigned int, unsigned int, imm0_16383)
17613 unsigned long __csrrd_d (imm0_16383)
17614 unsigned long __csrwr_d (unsigned long, imm0_16383)
17615 unsigned long __csrxchg_d (unsigned long, unsigned long, imm0_16383)
17617 unsigned char __iocsrrd_b (unsigned int)
17618 unsigned short __iocsrrd_h (unsigned int)
17619 unsigned int __iocsrrd_w (unsigned int)
17620 unsigned long __iocsrrd_d (unsigned int)
17621 void __iocsrwr_b (unsigned char, unsigned int)
17622 void __iocsrwr_h (unsigned short, unsigned int)
17623 void __iocsrwr_w (unsigned int, unsigned int)
17624 void __iocsrwr_d (unsigned long, unsigned int)
17626 void __dbar (imm0_32767)
17627 void __ibar (imm0_32767)
17629 void __syscall (imm0_32767)
17630 void __break (imm0_32767)
17633 These instrisic functions are available by including @code{larchintrin.h} and
17634 using @option{-mfrecipe}.
17636 float __frecipe_s (float);
17637 double __frecipe_d (double);
17638 float __frsqrte_s (float);
17639 double __frsqrte_d (double);
17642 Additional built-in functions are available for LoongArch family
17643 processors to efficiently use 128-bit floating-point (__float128)
17646 The following are the basic built-in functions supported.
17648 __float128 __builtin_fabsq (__float128);
17649 __float128 __builtin_copysignq (__float128, __float128);
17650 __float128 __builtin_infq (void);
17651 __float128 __builtin_huge_valq (void);
17652 __float128 __builtin_nanq (void);
17653 __float128 __builtin_nansq (void);
17656 Returns the value that is currently set in the @samp{tp} register.
17658 void * __builtin_thread_pointer (void)
17661 @node LoongArch SX Vector Intrinsics
17662 @subsection LoongArch SX Vector Intrinsics
17664 GCC provides intrinsics to access the LSX (Loongson SIMD Extension) instructions.
17665 The interface is made available by including @code{<lsxintrin.h>} and using
17668 The following vectors typedefs are included in @code{lsxintrin.h}:
17671 @item @code{__m128i}, a 128-bit vector of fixed point;
17672 @item @code{__m128}, a 128-bit vector of single precision floating point;
17673 @item @code{__m128d}, a 128-bit vector of double precision floating point.
17676 Instructions and corresponding built-ins may have additional restrictions and/or
17677 input/output values manipulated:
17679 @item @code{imm0_1}, an integer literal in range 0 to 1;
17680 @item @code{imm0_3}, an integer literal in range 0 to 3;
17681 @item @code{imm0_7}, an integer literal in range 0 to 7;
17682 @item @code{imm0_15}, an integer literal in range 0 to 15;
17683 @item @code{imm0_31}, an integer literal in range 0 to 31;
17684 @item @code{imm0_63}, an integer literal in range 0 to 63;
17685 @item @code{imm0_127}, an integer literal in range 0 to 127;
17686 @item @code{imm0_255}, an integer literal in range 0 to 255;
17687 @item @code{imm_n16_15}, an integer literal in range -16 to 15;
17688 @item @code{imm_n128_127}, an integer literal in range -128 to 127;
17689 @item @code{imm_n256_255}, an integer literal in range -256 to 255;
17690 @item @code{imm_n512_511}, an integer literal in range -512 to 511;
17691 @item @code{imm_n1024_1023}, an integer literal in range -1024 to 1023;
17692 @item @code{imm_n2048_2047}, an integer literal in range -2048 to 2047.
17695 For convenience, GCC defines functions @code{__lsx_vrepli_@{b/h/w/d@}} and
17696 @code{__lsx_b[n]z_@{v/b/h/w/d@}}, which are implemented as follows:
17699 a. @code{__lsx_vrepli_@{b/h/w/d@}}: Implemented the case where the highest
17700 bit of @code{vldi} instruction @code{i13} is 1.
17703 case i13[11:10] of :
17704 2'b00: __lsx_vrepli_b (imm_n512_511)
17705 2'b01: __lsx_vrepli_h (imm_n512_511)
17706 2'b10: __lsx_vrepli_w (imm_n512_511)
17707 2'b11: __lsx_vrepli_d (imm_n512_511)
17709 b. @code{__lsx_b[n]z_@{v/b/h/w/d@}}: Since the @code{vseteqz} class directive
17710 cannot be used on its own, this function is defined.
17712 _lsx_bz_v => vseteqz.v + bcnez
17713 _lsx_bnz_v => vsetnez.v + bcnez
17714 _lsx_bz_b => vsetanyeqz.b + bcnez
17715 _lsx_bz_h => vsetanyeqz.h + bcnez
17716 _lsx_bz_w => vsetanyeqz.w + bcnez
17717 _lsx_bz_d => vsetanyeqz.d + bcnez
17718 _lsx_bnz_b => vsetallnez.b + bcnez
17719 _lsx_bnz_h => vsetallnez.h + bcnez
17720 _lsx_bnz_w => vsetallnez.w + bcnez
17721 _lsx_bnz_d => vsetallnez.d + bcnez
17726 #include <lsxintrin.h>
17728 extern __m128i @var{a};
17733 if (__lsx_bz_v (@var{a}))
17740 @emph{Note:} For directives where the intent operand is also the source operand
17741 (modifying only part of the bitfield of the intent register), the first parameter
17742 in the builtin call function is used as the intent operand.
17746 #include <lsxintrin.h>
17748 extern __m128i @var{dst};
17749 extern int @var{src};
17754 @var{dst} = __lsx_vinsgr2vr_b (@var{dst}, @var{src}, 3);
17758 The intrinsics provided are listed below:
17760 int __lsx_bnz_b (__m128i);
17761 int __lsx_bnz_d (__m128i);
17762 int __lsx_bnz_h (__m128i);
17763 int __lsx_bnz_v (__m128i);
17764 int __lsx_bnz_w (__m128i);
17765 int __lsx_bz_b (__m128i);
17766 int __lsx_bz_d (__m128i);
17767 int __lsx_bz_h (__m128i);
17768 int __lsx_bz_v (__m128i);
17769 int __lsx_bz_w (__m128i);
17770 __m128i __lsx_vabsd_b (__m128i, __m128i);
17771 __m128i __lsx_vabsd_bu (__m128i, __m128i);
17772 __m128i __lsx_vabsd_d (__m128i, __m128i);
17773 __m128i __lsx_vabsd_du (__m128i, __m128i);
17774 __m128i __lsx_vabsd_h (__m128i, __m128i);
17775 __m128i __lsx_vabsd_hu (__m128i, __m128i);
17776 __m128i __lsx_vabsd_w (__m128i, __m128i);
17777 __m128i __lsx_vabsd_wu (__m128i, __m128i);
17778 __m128i __lsx_vadda_b (__m128i, __m128i);
17779 __m128i __lsx_vadda_d (__m128i, __m128i);
17780 __m128i __lsx_vadda_h (__m128i, __m128i);
17781 __m128i __lsx_vadda_w (__m128i, __m128i);
17782 __m128i __lsx_vadd_b (__m128i, __m128i);
17783 __m128i __lsx_vadd_d (__m128i, __m128i);
17784 __m128i __lsx_vadd_h (__m128i, __m128i);
17785 __m128i __lsx_vaddi_bu (__m128i, imm0_31);
17786 __m128i __lsx_vaddi_du (__m128i, imm0_31);
17787 __m128i __lsx_vaddi_hu (__m128i, imm0_31);
17788 __m128i __lsx_vaddi_wu (__m128i, imm0_31);
17789 __m128i __lsx_vadd_q (__m128i, __m128i);
17790 __m128i __lsx_vadd_w (__m128i, __m128i);
17791 __m128i __lsx_vaddwev_d_w (__m128i, __m128i);
17792 __m128i __lsx_vaddwev_d_wu (__m128i, __m128i);
17793 __m128i __lsx_vaddwev_d_wu_w (__m128i, __m128i);
17794 __m128i __lsx_vaddwev_h_b (__m128i, __m128i);
17795 __m128i __lsx_vaddwev_h_bu (__m128i, __m128i);
17796 __m128i __lsx_vaddwev_h_bu_b (__m128i, __m128i);
17797 __m128i __lsx_vaddwev_q_d (__m128i, __m128i);
17798 __m128i __lsx_vaddwev_q_du (__m128i, __m128i);
17799 __m128i __lsx_vaddwev_q_du_d (__m128i, __m128i);
17800 __m128i __lsx_vaddwev_w_h (__m128i, __m128i);
17801 __m128i __lsx_vaddwev_w_hu (__m128i, __m128i);
17802 __m128i __lsx_vaddwev_w_hu_h (__m128i, __m128i);
17803 __m128i __lsx_vaddwod_d_w (__m128i, __m128i);
17804 __m128i __lsx_vaddwod_d_wu (__m128i, __m128i);
17805 __m128i __lsx_vaddwod_d_wu_w (__m128i, __m128i);
17806 __m128i __lsx_vaddwod_h_b (__m128i, __m128i);
17807 __m128i __lsx_vaddwod_h_bu (__m128i, __m128i);
17808 __m128i __lsx_vaddwod_h_bu_b (__m128i, __m128i);
17809 __m128i __lsx_vaddwod_q_d (__m128i, __m128i);
17810 __m128i __lsx_vaddwod_q_du (__m128i, __m128i);
17811 __m128i __lsx_vaddwod_q_du_d (__m128i, __m128i);
17812 __m128i __lsx_vaddwod_w_h (__m128i, __m128i);
17813 __m128i __lsx_vaddwod_w_hu (__m128i, __m128i);
17814 __m128i __lsx_vaddwod_w_hu_h (__m128i, __m128i);
17815 __m128i __lsx_vandi_b (__m128i, imm0_255);
17816 __m128i __lsx_vandn_v (__m128i, __m128i);
17817 __m128i __lsx_vand_v (__m128i, __m128i);
17818 __m128i __lsx_vavg_b (__m128i, __m128i);
17819 __m128i __lsx_vavg_bu (__m128i, __m128i);
17820 __m128i __lsx_vavg_d (__m128i, __m128i);
17821 __m128i __lsx_vavg_du (__m128i, __m128i);
17822 __m128i __lsx_vavg_h (__m128i, __m128i);
17823 __m128i __lsx_vavg_hu (__m128i, __m128i);
17824 __m128i __lsx_vavgr_b (__m128i, __m128i);
17825 __m128i __lsx_vavgr_bu (__m128i, __m128i);
17826 __m128i __lsx_vavgr_d (__m128i, __m128i);
17827 __m128i __lsx_vavgr_du (__m128i, __m128i);
17828 __m128i __lsx_vavgr_h (__m128i, __m128i);
17829 __m128i __lsx_vavgr_hu (__m128i, __m128i);
17830 __m128i __lsx_vavgr_w (__m128i, __m128i);
17831 __m128i __lsx_vavgr_wu (__m128i, __m128i);
17832 __m128i __lsx_vavg_w (__m128i, __m128i);
17833 __m128i __lsx_vavg_wu (__m128i, __m128i);
17834 __m128i __lsx_vbitclr_b (__m128i, __m128i);
17835 __m128i __lsx_vbitclr_d (__m128i, __m128i);
17836 __m128i __lsx_vbitclr_h (__m128i, __m128i);
17837 __m128i __lsx_vbitclri_b (__m128i, imm0_7);
17838 __m128i __lsx_vbitclri_d (__m128i, imm0_63);
17839 __m128i __lsx_vbitclri_h (__m128i, imm0_15);
17840 __m128i __lsx_vbitclri_w (__m128i, imm0_31);
17841 __m128i __lsx_vbitclr_w (__m128i, __m128i);
17842 __m128i __lsx_vbitrev_b (__m128i, __m128i);
17843 __m128i __lsx_vbitrev_d (__m128i, __m128i);
17844 __m128i __lsx_vbitrev_h (__m128i, __m128i);
17845 __m128i __lsx_vbitrevi_b (__m128i, imm0_7);
17846 __m128i __lsx_vbitrevi_d (__m128i, imm0_63);
17847 __m128i __lsx_vbitrevi_h (__m128i, imm0_15);
17848 __m128i __lsx_vbitrevi_w (__m128i, imm0_31);
17849 __m128i __lsx_vbitrev_w (__m128i, __m128i);
17850 __m128i __lsx_vbitseli_b (__m128i, __m128i, imm0_255);
17851 __m128i __lsx_vbitsel_v (__m128i, __m128i, __m128i);
17852 __m128i __lsx_vbitset_b (__m128i, __m128i);
17853 __m128i __lsx_vbitset_d (__m128i, __m128i);
17854 __m128i __lsx_vbitset_h (__m128i, __m128i);
17855 __m128i __lsx_vbitseti_b (__m128i, imm0_7);
17856 __m128i __lsx_vbitseti_d (__m128i, imm0_63);
17857 __m128i __lsx_vbitseti_h (__m128i, imm0_15);
17858 __m128i __lsx_vbitseti_w (__m128i, imm0_31);
17859 __m128i __lsx_vbitset_w (__m128i, __m128i);
17860 __m128i __lsx_vbsll_v (__m128i, imm0_31);
17861 __m128i __lsx_vbsrl_v (__m128i, imm0_31);
17862 __m128i __lsx_vclo_b (__m128i);
17863 __m128i __lsx_vclo_d (__m128i);
17864 __m128i __lsx_vclo_h (__m128i);
17865 __m128i __lsx_vclo_w (__m128i);
17866 __m128i __lsx_vclz_b (__m128i);
17867 __m128i __lsx_vclz_d (__m128i);
17868 __m128i __lsx_vclz_h (__m128i);
17869 __m128i __lsx_vclz_w (__m128i);
17870 __m128i __lsx_vdiv_b (__m128i, __m128i);
17871 __m128i __lsx_vdiv_bu (__m128i, __m128i);
17872 __m128i __lsx_vdiv_d (__m128i, __m128i);
17873 __m128i __lsx_vdiv_du (__m128i, __m128i);
17874 __m128i __lsx_vdiv_h (__m128i, __m128i);
17875 __m128i __lsx_vdiv_hu (__m128i, __m128i);
17876 __m128i __lsx_vdiv_w (__m128i, __m128i);
17877 __m128i __lsx_vdiv_wu (__m128i, __m128i);
17878 __m128i __lsx_vexth_du_wu (__m128i);
17879 __m128i __lsx_vexth_d_w (__m128i);
17880 __m128i __lsx_vexth_h_b (__m128i);
17881 __m128i __lsx_vexth_hu_bu (__m128i);
17882 __m128i __lsx_vexth_q_d (__m128i);
17883 __m128i __lsx_vexth_qu_du (__m128i);
17884 __m128i __lsx_vexth_w_h (__m128i);
17885 __m128i __lsx_vexth_wu_hu (__m128i);
17886 __m128i __lsx_vextl_q_d (__m128i);
17887 __m128i __lsx_vextl_qu_du (__m128i);
17888 __m128i __lsx_vextrins_b (__m128i, __m128i, imm0_255);
17889 __m128i __lsx_vextrins_d (__m128i, __m128i, imm0_255);
17890 __m128i __lsx_vextrins_h (__m128i, __m128i, imm0_255);
17891 __m128i __lsx_vextrins_w (__m128i, __m128i, imm0_255);
17892 __m128d __lsx_vfadd_d (__m128d, __m128d);
17893 __m128 __lsx_vfadd_s (__m128, __m128);
17894 __m128i __lsx_vfclass_d (__m128d);
17895 __m128i __lsx_vfclass_s (__m128);
17896 __m128i __lsx_vfcmp_caf_d (__m128d, __m128d);
17897 __m128i __lsx_vfcmp_caf_s (__m128, __m128);
17898 __m128i __lsx_vfcmp_ceq_d (__m128d, __m128d);
17899 __m128i __lsx_vfcmp_ceq_s (__m128, __m128);
17900 __m128i __lsx_vfcmp_cle_d (__m128d, __m128d);
17901 __m128i __lsx_vfcmp_cle_s (__m128, __m128);
17902 __m128i __lsx_vfcmp_clt_d (__m128d, __m128d);
17903 __m128i __lsx_vfcmp_clt_s (__m128, __m128);
17904 __m128i __lsx_vfcmp_cne_d (__m128d, __m128d);
17905 __m128i __lsx_vfcmp_cne_s (__m128, __m128);
17906 __m128i __lsx_vfcmp_cor_d (__m128d, __m128d);
17907 __m128i __lsx_vfcmp_cor_s (__m128, __m128);
17908 __m128i __lsx_vfcmp_cueq_d (__m128d, __m128d);
17909 __m128i __lsx_vfcmp_cueq_s (__m128, __m128);
17910 __m128i __lsx_vfcmp_cule_d (__m128d, __m128d);
17911 __m128i __lsx_vfcmp_cule_s (__m128, __m128);
17912 __m128i __lsx_vfcmp_cult_d (__m128d, __m128d);
17913 __m128i __lsx_vfcmp_cult_s (__m128, __m128);
17914 __m128i __lsx_vfcmp_cun_d (__m128d, __m128d);
17915 __m128i __lsx_vfcmp_cune_d (__m128d, __m128d);
17916 __m128i __lsx_vfcmp_cune_s (__m128, __m128);
17917 __m128i __lsx_vfcmp_cun_s (__m128, __m128);
17918 __m128i __lsx_vfcmp_saf_d (__m128d, __m128d);
17919 __m128i __lsx_vfcmp_saf_s (__m128, __m128);
17920 __m128i __lsx_vfcmp_seq_d (__m128d, __m128d);
17921 __m128i __lsx_vfcmp_seq_s (__m128, __m128);
17922 __m128i __lsx_vfcmp_sle_d (__m128d, __m128d);
17923 __m128i __lsx_vfcmp_sle_s (__m128, __m128);
17924 __m128i __lsx_vfcmp_slt_d (__m128d, __m128d);
17925 __m128i __lsx_vfcmp_slt_s (__m128, __m128);
17926 __m128i __lsx_vfcmp_sne_d (__m128d, __m128d);
17927 __m128i __lsx_vfcmp_sne_s (__m128, __m128);
17928 __m128i __lsx_vfcmp_sor_d (__m128d, __m128d);
17929 __m128i __lsx_vfcmp_sor_s (__m128, __m128);
17930 __m128i __lsx_vfcmp_sueq_d (__m128d, __m128d);
17931 __m128i __lsx_vfcmp_sueq_s (__m128, __m128);
17932 __m128i __lsx_vfcmp_sule_d (__m128d, __m128d);
17933 __m128i __lsx_vfcmp_sule_s (__m128, __m128);
17934 __m128i __lsx_vfcmp_sult_d (__m128d, __m128d);
17935 __m128i __lsx_vfcmp_sult_s (__m128, __m128);
17936 __m128i __lsx_vfcmp_sun_d (__m128d, __m128d);
17937 __m128i __lsx_vfcmp_sune_d (__m128d, __m128d);
17938 __m128i __lsx_vfcmp_sune_s (__m128, __m128);
17939 __m128i __lsx_vfcmp_sun_s (__m128, __m128);
17940 __m128d __lsx_vfcvth_d_s (__m128);
17941 __m128i __lsx_vfcvt_h_s (__m128, __m128);
17942 __m128 __lsx_vfcvth_s_h (__m128i);
17943 __m128d __lsx_vfcvtl_d_s (__m128);
17944 __m128 __lsx_vfcvtl_s_h (__m128i);
17945 __m128 __lsx_vfcvt_s_d (__m128d, __m128d);
17946 __m128d __lsx_vfdiv_d (__m128d, __m128d);
17947 __m128 __lsx_vfdiv_s (__m128, __m128);
17948 __m128d __lsx_vffint_d_l (__m128i);
17949 __m128d __lsx_vffint_d_lu (__m128i);
17950 __m128d __lsx_vffinth_d_w (__m128i);
17951 __m128d __lsx_vffintl_d_w (__m128i);
17952 __m128 __lsx_vffint_s_l (__m128i, __m128i);
17953 __m128 __lsx_vffint_s_w (__m128i);
17954 __m128 __lsx_vffint_s_wu (__m128i);
17955 __m128d __lsx_vflogb_d (__m128d);
17956 __m128 __lsx_vflogb_s (__m128);
17957 __m128d __lsx_vfmadd_d (__m128d, __m128d, __m128d);
17958 __m128 __lsx_vfmadd_s (__m128, __m128, __m128);
17959 __m128d __lsx_vfmaxa_d (__m128d, __m128d);
17960 __m128 __lsx_vfmaxa_s (__m128, __m128);
17961 __m128d __lsx_vfmax_d (__m128d, __m128d);
17962 __m128 __lsx_vfmax_s (__m128, __m128);
17963 __m128d __lsx_vfmina_d (__m128d, __m128d);
17964 __m128 __lsx_vfmina_s (__m128, __m128);
17965 __m128d __lsx_vfmin_d (__m128d, __m128d);
17966 __m128 __lsx_vfmin_s (__m128, __m128);
17967 __m128d __lsx_vfmsub_d (__m128d, __m128d, __m128d);
17968 __m128 __lsx_vfmsub_s (__m128, __m128, __m128);
17969 __m128d __lsx_vfmul_d (__m128d, __m128d);
17970 __m128 __lsx_vfmul_s (__m128, __m128);
17971 __m128d __lsx_vfnmadd_d (__m128d, __m128d, __m128d);
17972 __m128 __lsx_vfnmadd_s (__m128, __m128, __m128);
17973 __m128d __lsx_vfnmsub_d (__m128d, __m128d, __m128d);
17974 __m128 __lsx_vfnmsub_s (__m128, __m128, __m128);
17975 __m128d __lsx_vfrecip_d (__m128d);
17976 __m128 __lsx_vfrecip_s (__m128);
17977 __m128d __lsx_vfrint_d (__m128d);
17978 __m128d __lsx_vfrintrm_d (__m128d);
17979 __m128 __lsx_vfrintrm_s (__m128);
17980 __m128d __lsx_vfrintrne_d (__m128d);
17981 __m128 __lsx_vfrintrne_s (__m128);
17982 __m128d __lsx_vfrintrp_d (__m128d);
17983 __m128 __lsx_vfrintrp_s (__m128);
17984 __m128d __lsx_vfrintrz_d (__m128d);
17985 __m128 __lsx_vfrintrz_s (__m128);
17986 __m128 __lsx_vfrint_s (__m128);
17987 __m128d __lsx_vfrsqrt_d (__m128d);
17988 __m128 __lsx_vfrsqrt_s (__m128);
17989 __m128i __lsx_vfrstp_b (__m128i, __m128i, __m128i);
17990 __m128i __lsx_vfrstp_h (__m128i, __m128i, __m128i);
17991 __m128i __lsx_vfrstpi_b (__m128i, __m128i, imm0_31);
17992 __m128i __lsx_vfrstpi_h (__m128i, __m128i, imm0_31);
17993 __m128d __lsx_vfsqrt_d (__m128d);
17994 __m128 __lsx_vfsqrt_s (__m128);
17995 __m128d __lsx_vfsub_d (__m128d, __m128d);
17996 __m128 __lsx_vfsub_s (__m128, __m128);
17997 __m128i __lsx_vftinth_l_s (__m128);
17998 __m128i __lsx_vftint_l_d (__m128d);
17999 __m128i __lsx_vftintl_l_s (__m128);
18000 __m128i __lsx_vftint_lu_d (__m128d);
18001 __m128i __lsx_vftintrmh_l_s (__m128);
18002 __m128i __lsx_vftintrm_l_d (__m128d);
18003 __m128i __lsx_vftintrml_l_s (__m128);
18004 __m128i __lsx_vftintrm_w_d (__m128d, __m128d);
18005 __m128i __lsx_vftintrm_w_s (__m128);
18006 __m128i __lsx_vftintrneh_l_s (__m128);
18007 __m128i __lsx_vftintrne_l_d (__m128d);
18008 __m128i __lsx_vftintrnel_l_s (__m128);
18009 __m128i __lsx_vftintrne_w_d (__m128d, __m128d);
18010 __m128i __lsx_vftintrne_w_s (__m128);
18011 __m128i __lsx_vftintrph_l_s (__m128);
18012 __m128i __lsx_vftintrp_l_d (__m128d);
18013 __m128i __lsx_vftintrpl_l_s (__m128);
18014 __m128i __lsx_vftintrp_w_d (__m128d, __m128d);
18015 __m128i __lsx_vftintrp_w_s (__m128);
18016 __m128i __lsx_vftintrzh_l_s (__m128);
18017 __m128i __lsx_vftintrz_l_d (__m128d);
18018 __m128i __lsx_vftintrzl_l_s (__m128);
18019 __m128i __lsx_vftintrz_lu_d (__m128d);
18020 __m128i __lsx_vftintrz_w_d (__m128d, __m128d);
18021 __m128i __lsx_vftintrz_w_s (__m128);
18022 __m128i __lsx_vftintrz_wu_s (__m128);
18023 __m128i __lsx_vftint_w_d (__m128d, __m128d);
18024 __m128i __lsx_vftint_w_s (__m128);
18025 __m128i __lsx_vftint_wu_s (__m128);
18026 __m128i __lsx_vhaddw_du_wu (__m128i, __m128i);
18027 __m128i __lsx_vhaddw_d_w (__m128i, __m128i);
18028 __m128i __lsx_vhaddw_h_b (__m128i, __m128i);
18029 __m128i __lsx_vhaddw_hu_bu (__m128i, __m128i);
18030 __m128i __lsx_vhaddw_q_d (__m128i, __m128i);
18031 __m128i __lsx_vhaddw_qu_du (__m128i, __m128i);
18032 __m128i __lsx_vhaddw_w_h (__m128i, __m128i);
18033 __m128i __lsx_vhaddw_wu_hu (__m128i, __m128i);
18034 __m128i __lsx_vhsubw_du_wu (__m128i, __m128i);
18035 __m128i __lsx_vhsubw_d_w (__m128i, __m128i);
18036 __m128i __lsx_vhsubw_h_b (__m128i, __m128i);
18037 __m128i __lsx_vhsubw_hu_bu (__m128i, __m128i);
18038 __m128i __lsx_vhsubw_q_d (__m128i, __m128i);
18039 __m128i __lsx_vhsubw_qu_du (__m128i, __m128i);
18040 __m128i __lsx_vhsubw_w_h (__m128i, __m128i);
18041 __m128i __lsx_vhsubw_wu_hu (__m128i, __m128i);
18042 __m128i __lsx_vilvh_b (__m128i, __m128i);
18043 __m128i __lsx_vilvh_d (__m128i, __m128i);
18044 __m128i __lsx_vilvh_h (__m128i, __m128i);
18045 __m128i __lsx_vilvh_w (__m128i, __m128i);
18046 __m128i __lsx_vilvl_b (__m128i, __m128i);
18047 __m128i __lsx_vilvl_d (__m128i, __m128i);
18048 __m128i __lsx_vilvl_h (__m128i, __m128i);
18049 __m128i __lsx_vilvl_w (__m128i, __m128i);
18050 __m128i __lsx_vinsgr2vr_b (__m128i, int, imm0_15);
18051 __m128i __lsx_vinsgr2vr_d (__m128i, long int, imm0_1);
18052 __m128i __lsx_vinsgr2vr_h (__m128i, int, imm0_7);
18053 __m128i __lsx_vinsgr2vr_w (__m128i, int, imm0_3);
18054 __m128i __lsx_vld (void *, imm_n2048_2047);
18055 __m128i __lsx_vldi (imm_n1024_1023);
18056 __m128i __lsx_vldrepl_b (void *, imm_n2048_2047);
18057 __m128i __lsx_vldrepl_d (void *, imm_n256_255);
18058 __m128i __lsx_vldrepl_h (void *, imm_n1024_1023);
18059 __m128i __lsx_vldrepl_w (void *, imm_n512_511);
18060 __m128i __lsx_vldx (void *, long int);
18061 __m128i __lsx_vmadd_b (__m128i, __m128i, __m128i);
18062 __m128i __lsx_vmadd_d (__m128i, __m128i, __m128i);
18063 __m128i __lsx_vmadd_h (__m128i, __m128i, __m128i);
18064 __m128i __lsx_vmadd_w (__m128i, __m128i, __m128i);
18065 __m128i __lsx_vmaddwev_d_w (__m128i, __m128i, __m128i);
18066 __m128i __lsx_vmaddwev_d_wu (__m128i, __m128i, __m128i);
18067 __m128i __lsx_vmaddwev_d_wu_w (__m128i, __m128i, __m128i);
18068 __m128i __lsx_vmaddwev_h_b (__m128i, __m128i, __m128i);
18069 __m128i __lsx_vmaddwev_h_bu (__m128i, __m128i, __m128i);
18070 __m128i __lsx_vmaddwev_h_bu_b (__m128i, __m128i, __m128i);
18071 __m128i __lsx_vmaddwev_q_d (__m128i, __m128i, __m128i);
18072 __m128i __lsx_vmaddwev_q_du (__m128i, __m128i, __m128i);
18073 __m128i __lsx_vmaddwev_q_du_d (__m128i, __m128i, __m128i);
18074 __m128i __lsx_vmaddwev_w_h (__m128i, __m128i, __m128i);
18075 __m128i __lsx_vmaddwev_w_hu (__m128i, __m128i, __m128i);
18076 __m128i __lsx_vmaddwev_w_hu_h (__m128i, __m128i, __m128i);
18077 __m128i __lsx_vmaddwod_d_w (__m128i, __m128i, __m128i);
18078 __m128i __lsx_vmaddwod_d_wu (__m128i, __m128i, __m128i);
18079 __m128i __lsx_vmaddwod_d_wu_w (__m128i, __m128i, __m128i);
18080 __m128i __lsx_vmaddwod_h_b (__m128i, __m128i, __m128i);
18081 __m128i __lsx_vmaddwod_h_bu (__m128i, __m128i, __m128i);
18082 __m128i __lsx_vmaddwod_h_bu_b (__m128i, __m128i, __m128i);
18083 __m128i __lsx_vmaddwod_q_d (__m128i, __m128i, __m128i);
18084 __m128i __lsx_vmaddwod_q_du (__m128i, __m128i, __m128i);
18085 __m128i __lsx_vmaddwod_q_du_d (__m128i, __m128i, __m128i);
18086 __m128i __lsx_vmaddwod_w_h (__m128i, __m128i, __m128i);
18087 __m128i __lsx_vmaddwod_w_hu (__m128i, __m128i, __m128i);
18088 __m128i __lsx_vmaddwod_w_hu_h (__m128i, __m128i, __m128i);
18089 __m128i __lsx_vmax_b (__m128i, __m128i);
18090 __m128i __lsx_vmax_bu (__m128i, __m128i);
18091 __m128i __lsx_vmax_d (__m128i, __m128i);
18092 __m128i __lsx_vmax_du (__m128i, __m128i);
18093 __m128i __lsx_vmax_h (__m128i, __m128i);
18094 __m128i __lsx_vmax_hu (__m128i, __m128i);
18095 __m128i __lsx_vmaxi_b (__m128i, imm_n16_15);
18096 __m128i __lsx_vmaxi_bu (__m128i, imm0_31);
18097 __m128i __lsx_vmaxi_d (__m128i, imm_n16_15);
18098 __m128i __lsx_vmaxi_du (__m128i, imm0_31);
18099 __m128i __lsx_vmaxi_h (__m128i, imm_n16_15);
18100 __m128i __lsx_vmaxi_hu (__m128i, imm0_31);
18101 __m128i __lsx_vmaxi_w (__m128i, imm_n16_15);
18102 __m128i __lsx_vmaxi_wu (__m128i, imm0_31);
18103 __m128i __lsx_vmax_w (__m128i, __m128i);
18104 __m128i __lsx_vmax_wu (__m128i, __m128i);
18105 __m128i __lsx_vmin_b (__m128i, __m128i);
18106 __m128i __lsx_vmin_bu (__m128i, __m128i);
18107 __m128i __lsx_vmin_d (__m128i, __m128i);
18108 __m128i __lsx_vmin_du (__m128i, __m128i);
18109 __m128i __lsx_vmin_h (__m128i, __m128i);
18110 __m128i __lsx_vmin_hu (__m128i, __m128i);
18111 __m128i __lsx_vmini_b (__m128i, imm_n16_15);
18112 __m128i __lsx_vmini_bu (__m128i, imm0_31);
18113 __m128i __lsx_vmini_d (__m128i, imm_n16_15);
18114 __m128i __lsx_vmini_du (__m128i, imm0_31);
18115 __m128i __lsx_vmini_h (__m128i, imm_n16_15);
18116 __m128i __lsx_vmini_hu (__m128i, imm0_31);
18117 __m128i __lsx_vmini_w (__m128i, imm_n16_15);
18118 __m128i __lsx_vmini_wu (__m128i, imm0_31);
18119 __m128i __lsx_vmin_w (__m128i, __m128i);
18120 __m128i __lsx_vmin_wu (__m128i, __m128i);
18121 __m128i __lsx_vmod_b (__m128i, __m128i);
18122 __m128i __lsx_vmod_bu (__m128i, __m128i);
18123 __m128i __lsx_vmod_d (__m128i, __m128i);
18124 __m128i __lsx_vmod_du (__m128i, __m128i);
18125 __m128i __lsx_vmod_h (__m128i, __m128i);
18126 __m128i __lsx_vmod_hu (__m128i, __m128i);
18127 __m128i __lsx_vmod_w (__m128i, __m128i);
18128 __m128i __lsx_vmod_wu (__m128i, __m128i);
18129 __m128i __lsx_vmskgez_b (__m128i);
18130 __m128i __lsx_vmskltz_b (__m128i);
18131 __m128i __lsx_vmskltz_d (__m128i);
18132 __m128i __lsx_vmskltz_h (__m128i);
18133 __m128i __lsx_vmskltz_w (__m128i);
18134 __m128i __lsx_vmsknz_b (__m128i);
18135 __m128i __lsx_vmsub_b (__m128i, __m128i, __m128i);
18136 __m128i __lsx_vmsub_d (__m128i, __m128i, __m128i);
18137 __m128i __lsx_vmsub_h (__m128i, __m128i, __m128i);
18138 __m128i __lsx_vmsub_w (__m128i, __m128i, __m128i);
18139 __m128i __lsx_vmuh_b (__m128i, __m128i);
18140 __m128i __lsx_vmuh_bu (__m128i, __m128i);
18141 __m128i __lsx_vmuh_d (__m128i, __m128i);
18142 __m128i __lsx_vmuh_du (__m128i, __m128i);
18143 __m128i __lsx_vmuh_h (__m128i, __m128i);
18144 __m128i __lsx_vmuh_hu (__m128i, __m128i);
18145 __m128i __lsx_vmuh_w (__m128i, __m128i);
18146 __m128i __lsx_vmuh_wu (__m128i, __m128i);
18147 __m128i __lsx_vmul_b (__m128i, __m128i);
18148 __m128i __lsx_vmul_d (__m128i, __m128i);
18149 __m128i __lsx_vmul_h (__m128i, __m128i);
18150 __m128i __lsx_vmul_w (__m128i, __m128i);
18151 __m128i __lsx_vmulwev_d_w (__m128i, __m128i);
18152 __m128i __lsx_vmulwev_d_wu (__m128i, __m128i);
18153 __m128i __lsx_vmulwev_d_wu_w (__m128i, __m128i);
18154 __m128i __lsx_vmulwev_h_b (__m128i, __m128i);
18155 __m128i __lsx_vmulwev_h_bu (__m128i, __m128i);
18156 __m128i __lsx_vmulwev_h_bu_b (__m128i, __m128i);
18157 __m128i __lsx_vmulwev_q_d (__m128i, __m128i);
18158 __m128i __lsx_vmulwev_q_du (__m128i, __m128i);
18159 __m128i __lsx_vmulwev_q_du_d (__m128i, __m128i);
18160 __m128i __lsx_vmulwev_w_h (__m128i, __m128i);
18161 __m128i __lsx_vmulwev_w_hu (__m128i, __m128i);
18162 __m128i __lsx_vmulwev_w_hu_h (__m128i, __m128i);
18163 __m128i __lsx_vmulwod_d_w (__m128i, __m128i);
18164 __m128i __lsx_vmulwod_d_wu (__m128i, __m128i);
18165 __m128i __lsx_vmulwod_d_wu_w (__m128i, __m128i);
18166 __m128i __lsx_vmulwod_h_b (__m128i, __m128i);
18167 __m128i __lsx_vmulwod_h_bu (__m128i, __m128i);
18168 __m128i __lsx_vmulwod_h_bu_b (__m128i, __m128i);
18169 __m128i __lsx_vmulwod_q_d (__m128i, __m128i);
18170 __m128i __lsx_vmulwod_q_du (__m128i, __m128i);
18171 __m128i __lsx_vmulwod_q_du_d (__m128i, __m128i);
18172 __m128i __lsx_vmulwod_w_h (__m128i, __m128i);
18173 __m128i __lsx_vmulwod_w_hu (__m128i, __m128i);
18174 __m128i __lsx_vmulwod_w_hu_h (__m128i, __m128i);
18175 __m128i __lsx_vneg_b (__m128i);
18176 __m128i __lsx_vneg_d (__m128i);
18177 __m128i __lsx_vneg_h (__m128i);
18178 __m128i __lsx_vneg_w (__m128i);
18179 __m128i __lsx_vnori_b (__m128i, imm0_255);
18180 __m128i __lsx_vnor_v (__m128i, __m128i);
18181 __m128i __lsx_vori_b (__m128i, imm0_255);
18182 __m128i __lsx_vorn_v (__m128i, __m128i);
18183 __m128i __lsx_vor_v (__m128i, __m128i);
18184 __m128i __lsx_vpackev_b (__m128i, __m128i);
18185 __m128i __lsx_vpackev_d (__m128i, __m128i);
18186 __m128i __lsx_vpackev_h (__m128i, __m128i);
18187 __m128i __lsx_vpackev_w (__m128i, __m128i);
18188 __m128i __lsx_vpackod_b (__m128i, __m128i);
18189 __m128i __lsx_vpackod_d (__m128i, __m128i);
18190 __m128i __lsx_vpackod_h (__m128i, __m128i);
18191 __m128i __lsx_vpackod_w (__m128i, __m128i);
18192 __m128i __lsx_vpcnt_b (__m128i);
18193 __m128i __lsx_vpcnt_d (__m128i);
18194 __m128i __lsx_vpcnt_h (__m128i);
18195 __m128i __lsx_vpcnt_w (__m128i);
18196 __m128i __lsx_vpermi_w (__m128i, __m128i, imm0_255);
18197 __m128i __lsx_vpickev_b (__m128i, __m128i);
18198 __m128i __lsx_vpickev_d (__m128i, __m128i);
18199 __m128i __lsx_vpickev_h (__m128i, __m128i);
18200 __m128i __lsx_vpickev_w (__m128i, __m128i);
18201 __m128i __lsx_vpickod_b (__m128i, __m128i);
18202 __m128i __lsx_vpickod_d (__m128i, __m128i);
18203 __m128i __lsx_vpickod_h (__m128i, __m128i);
18204 __m128i __lsx_vpickod_w (__m128i, __m128i);
18205 int __lsx_vpickve2gr_b (__m128i, imm0_15);
18206 unsigned int __lsx_vpickve2gr_bu (__m128i, imm0_15);
18207 long int __lsx_vpickve2gr_d (__m128i, imm0_1);
18208 unsigned long int __lsx_vpickve2gr_du (__m128i, imm0_1);
18209 int __lsx_vpickve2gr_h (__m128i, imm0_7);
18210 unsigned int __lsx_vpickve2gr_hu (__m128i, imm0_7);
18211 int __lsx_vpickve2gr_w (__m128i, imm0_3);
18212 unsigned int __lsx_vpickve2gr_wu (__m128i, imm0_3);
18213 __m128i __lsx_vreplgr2vr_b (int);
18214 __m128i __lsx_vreplgr2vr_d (long int);
18215 __m128i __lsx_vreplgr2vr_h (int);
18216 __m128i __lsx_vreplgr2vr_w (int);
18217 __m128i __lsx_vrepli_b (imm_n512_511);
18218 __m128i __lsx_vrepli_d (imm_n512_511);
18219 __m128i __lsx_vrepli_h (imm_n512_511);
18220 __m128i __lsx_vrepli_w (imm_n512_511);
18221 __m128i __lsx_vreplve_b (__m128i, int);
18222 __m128i __lsx_vreplve_d (__m128i, int);
18223 __m128i __lsx_vreplve_h (__m128i, int);
18224 __m128i __lsx_vreplvei_b (__m128i, imm0_15);
18225 __m128i __lsx_vreplvei_d (__m128i, imm0_1);
18226 __m128i __lsx_vreplvei_h (__m128i, imm0_7);
18227 __m128i __lsx_vreplvei_w (__m128i, imm0_3);
18228 __m128i __lsx_vreplve_w (__m128i, int);
18229 __m128i __lsx_vrotr_b (__m128i, __m128i);
18230 __m128i __lsx_vrotr_d (__m128i, __m128i);
18231 __m128i __lsx_vrotr_h (__m128i, __m128i);
18232 __m128i __lsx_vrotri_b (__m128i, imm0_7);
18233 __m128i __lsx_vrotri_d (__m128i, imm0_63);
18234 __m128i __lsx_vrotri_h (__m128i, imm0_15);
18235 __m128i __lsx_vrotri_w (__m128i, imm0_31);
18236 __m128i __lsx_vrotr_w (__m128i, __m128i);
18237 __m128i __lsx_vsadd_b (__m128i, __m128i);
18238 __m128i __lsx_vsadd_bu (__m128i, __m128i);
18239 __m128i __lsx_vsadd_d (__m128i, __m128i);
18240 __m128i __lsx_vsadd_du (__m128i, __m128i);
18241 __m128i __lsx_vsadd_h (__m128i, __m128i);
18242 __m128i __lsx_vsadd_hu (__m128i, __m128i);
18243 __m128i __lsx_vsadd_w (__m128i, __m128i);
18244 __m128i __lsx_vsadd_wu (__m128i, __m128i);
18245 __m128i __lsx_vsat_b (__m128i, imm0_7);
18246 __m128i __lsx_vsat_bu (__m128i, imm0_7);
18247 __m128i __lsx_vsat_d (__m128i, imm0_63);
18248 __m128i __lsx_vsat_du (__m128i, imm0_63);
18249 __m128i __lsx_vsat_h (__m128i, imm0_15);
18250 __m128i __lsx_vsat_hu (__m128i, imm0_15);
18251 __m128i __lsx_vsat_w (__m128i, imm0_31);
18252 __m128i __lsx_vsat_wu (__m128i, imm0_31);
18253 __m128i __lsx_vseq_b (__m128i, __m128i);
18254 __m128i __lsx_vseq_d (__m128i, __m128i);
18255 __m128i __lsx_vseq_h (__m128i, __m128i);
18256 __m128i __lsx_vseqi_b (__m128i, imm_n16_15);
18257 __m128i __lsx_vseqi_d (__m128i, imm_n16_15);
18258 __m128i __lsx_vseqi_h (__m128i, imm_n16_15);
18259 __m128i __lsx_vseqi_w (__m128i, imm_n16_15);
18260 __m128i __lsx_vseq_w (__m128i, __m128i);
18261 __m128i __lsx_vshuf4i_b (__m128i, imm0_255);
18262 __m128i __lsx_vshuf4i_d (__m128i, __m128i, imm0_255);
18263 __m128i __lsx_vshuf4i_h (__m128i, imm0_255);
18264 __m128i __lsx_vshuf4i_w (__m128i, imm0_255);
18265 __m128i __lsx_vshuf_b (__m128i, __m128i, __m128i);
18266 __m128i __lsx_vshuf_d (__m128i, __m128i, __m128i);
18267 __m128i __lsx_vshuf_h (__m128i, __m128i, __m128i);
18268 __m128i __lsx_vshuf_w (__m128i, __m128i, __m128i);
18269 __m128i __lsx_vsigncov_b (__m128i, __m128i);
18270 __m128i __lsx_vsigncov_d (__m128i, __m128i);
18271 __m128i __lsx_vsigncov_h (__m128i, __m128i);
18272 __m128i __lsx_vsigncov_w (__m128i, __m128i);
18273 __m128i __lsx_vsle_b (__m128i, __m128i);
18274 __m128i __lsx_vsle_bu (__m128i, __m128i);
18275 __m128i __lsx_vsle_d (__m128i, __m128i);
18276 __m128i __lsx_vsle_du (__m128i, __m128i);
18277 __m128i __lsx_vsle_h (__m128i, __m128i);
18278 __m128i __lsx_vsle_hu (__m128i, __m128i);
18279 __m128i __lsx_vslei_b (__m128i, imm_n16_15);
18280 __m128i __lsx_vslei_bu (__m128i, imm0_31);
18281 __m128i __lsx_vslei_d (__m128i, imm_n16_15);
18282 __m128i __lsx_vslei_du (__m128i, imm0_31);
18283 __m128i __lsx_vslei_h (__m128i, imm_n16_15);
18284 __m128i __lsx_vslei_hu (__m128i, imm0_31);
18285 __m128i __lsx_vslei_w (__m128i, imm_n16_15);
18286 __m128i __lsx_vslei_wu (__m128i, imm0_31);
18287 __m128i __lsx_vsle_w (__m128i, __m128i);
18288 __m128i __lsx_vsle_wu (__m128i, __m128i);
18289 __m128i __lsx_vsll_b (__m128i, __m128i);
18290 __m128i __lsx_vsll_d (__m128i, __m128i);
18291 __m128i __lsx_vsll_h (__m128i, __m128i);
18292 __m128i __lsx_vslli_b (__m128i, imm0_7);
18293 __m128i __lsx_vslli_d (__m128i, imm0_63);
18294 __m128i __lsx_vslli_h (__m128i, imm0_15);
18295 __m128i __lsx_vslli_w (__m128i, imm0_31);
18296 __m128i __lsx_vsll_w (__m128i, __m128i);
18297 __m128i __lsx_vsllwil_du_wu (__m128i, imm0_31);
18298 __m128i __lsx_vsllwil_d_w (__m128i, imm0_31);
18299 __m128i __lsx_vsllwil_h_b (__m128i, imm0_7);
18300 __m128i __lsx_vsllwil_hu_bu (__m128i, imm0_7);
18301 __m128i __lsx_vsllwil_w_h (__m128i, imm0_15);
18302 __m128i __lsx_vsllwil_wu_hu (__m128i, imm0_15);
18303 __m128i __lsx_vslt_b (__m128i, __m128i);
18304 __m128i __lsx_vslt_bu (__m128i, __m128i);
18305 __m128i __lsx_vslt_d (__m128i, __m128i);
18306 __m128i __lsx_vslt_du (__m128i, __m128i);
18307 __m128i __lsx_vslt_h (__m128i, __m128i);
18308 __m128i __lsx_vslt_hu (__m128i, __m128i);
18309 __m128i __lsx_vslti_b (__m128i, imm_n16_15);
18310 __m128i __lsx_vslti_bu (__m128i, imm0_31);
18311 __m128i __lsx_vslti_d (__m128i, imm_n16_15);
18312 __m128i __lsx_vslti_du (__m128i, imm0_31);
18313 __m128i __lsx_vslti_h (__m128i, imm_n16_15);
18314 __m128i __lsx_vslti_hu (__m128i, imm0_31);
18315 __m128i __lsx_vslti_w (__m128i, imm_n16_15);
18316 __m128i __lsx_vslti_wu (__m128i, imm0_31);
18317 __m128i __lsx_vslt_w (__m128i, __m128i);
18318 __m128i __lsx_vslt_wu (__m128i, __m128i);
18319 __m128i __lsx_vsra_b (__m128i, __m128i);
18320 __m128i __lsx_vsra_d (__m128i, __m128i);
18321 __m128i __lsx_vsra_h (__m128i, __m128i);
18322 __m128i __lsx_vsrai_b (__m128i, imm0_7);
18323 __m128i __lsx_vsrai_d (__m128i, imm0_63);
18324 __m128i __lsx_vsrai_h (__m128i, imm0_15);
18325 __m128i __lsx_vsrai_w (__m128i, imm0_31);
18326 __m128i __lsx_vsran_b_h (__m128i, __m128i);
18327 __m128i __lsx_vsran_h_w (__m128i, __m128i);
18328 __m128i __lsx_vsrani_b_h (__m128i, __m128i, imm0_15);
18329 __m128i __lsx_vsrani_d_q (__m128i, __m128i, imm0_127);
18330 __m128i __lsx_vsrani_h_w (__m128i, __m128i, imm0_31);
18331 __m128i __lsx_vsrani_w_d (__m128i, __m128i, imm0_63);
18332 __m128i __lsx_vsran_w_d (__m128i, __m128i);
18333 __m128i __lsx_vsrar_b (__m128i, __m128i);
18334 __m128i __lsx_vsrar_d (__m128i, __m128i);
18335 __m128i __lsx_vsrar_h (__m128i, __m128i);
18336 __m128i __lsx_vsrari_b (__m128i, imm0_7);
18337 __m128i __lsx_vsrari_d (__m128i, imm0_63);
18338 __m128i __lsx_vsrari_h (__m128i, imm0_15);
18339 __m128i __lsx_vsrari_w (__m128i, imm0_31);
18340 __m128i __lsx_vsrarn_b_h (__m128i, __m128i);
18341 __m128i __lsx_vsrarn_h_w (__m128i, __m128i);
18342 __m128i __lsx_vsrarni_b_h (__m128i, __m128i, imm0_15);
18343 __m128i __lsx_vsrarni_d_q (__m128i, __m128i, imm0_127);
18344 __m128i __lsx_vsrarni_h_w (__m128i, __m128i, imm0_31);
18345 __m128i __lsx_vsrarni_w_d (__m128i, __m128i, imm0_63);
18346 __m128i __lsx_vsrarn_w_d (__m128i, __m128i);
18347 __m128i __lsx_vsrar_w (__m128i, __m128i);
18348 __m128i __lsx_vsra_w (__m128i, __m128i);
18349 __m128i __lsx_vsrl_b (__m128i, __m128i);
18350 __m128i __lsx_vsrl_d (__m128i, __m128i);
18351 __m128i __lsx_vsrl_h (__m128i, __m128i);
18352 __m128i __lsx_vsrli_b (__m128i, imm0_7);
18353 __m128i __lsx_vsrli_d (__m128i, imm0_63);
18354 __m128i __lsx_vsrli_h (__m128i, imm0_15);
18355 __m128i __lsx_vsrli_w (__m128i, imm0_31);
18356 __m128i __lsx_vsrln_b_h (__m128i, __m128i);
18357 __m128i __lsx_vsrln_h_w (__m128i, __m128i);
18358 __m128i __lsx_vsrlni_b_h (__m128i, __m128i, imm0_15);
18359 __m128i __lsx_vsrlni_d_q (__m128i, __m128i, imm0_127);
18360 __m128i __lsx_vsrlni_h_w (__m128i, __m128i, imm0_31);
18361 __m128i __lsx_vsrlni_w_d (__m128i, __m128i, imm0_63);
18362 __m128i __lsx_vsrln_w_d (__m128i, __m128i);
18363 __m128i __lsx_vsrlr_b (__m128i, __m128i);
18364 __m128i __lsx_vsrlr_d (__m128i, __m128i);
18365 __m128i __lsx_vsrlr_h (__m128i, __m128i);
18366 __m128i __lsx_vsrlri_b (__m128i, imm0_7);
18367 __m128i __lsx_vsrlri_d (__m128i, imm0_63);
18368 __m128i __lsx_vsrlri_h (__m128i, imm0_15);
18369 __m128i __lsx_vsrlri_w (__m128i, imm0_31);
18370 __m128i __lsx_vsrlrn_b_h (__m128i, __m128i);
18371 __m128i __lsx_vsrlrn_h_w (__m128i, __m128i);
18372 __m128i __lsx_vsrlrni_b_h (__m128i, __m128i, imm0_15);
18373 __m128i __lsx_vsrlrni_d_q (__m128i, __m128i, imm0_127);
18374 __m128i __lsx_vsrlrni_h_w (__m128i, __m128i, imm0_31);
18375 __m128i __lsx_vsrlrni_w_d (__m128i, __m128i, imm0_63);
18376 __m128i __lsx_vsrlrn_w_d (__m128i, __m128i);
18377 __m128i __lsx_vsrlr_w (__m128i, __m128i);
18378 __m128i __lsx_vsrl_w (__m128i, __m128i);
18379 __m128i __lsx_vssran_b_h (__m128i, __m128i);
18380 __m128i __lsx_vssran_bu_h (__m128i, __m128i);
18381 __m128i __lsx_vssran_hu_w (__m128i, __m128i);
18382 __m128i __lsx_vssran_h_w (__m128i, __m128i);
18383 __m128i __lsx_vssrani_b_h (__m128i, __m128i, imm0_15);
18384 __m128i __lsx_vssrani_bu_h (__m128i, __m128i, imm0_15);
18385 __m128i __lsx_vssrani_d_q (__m128i, __m128i, imm0_127);
18386 __m128i __lsx_vssrani_du_q (__m128i, __m128i, imm0_127);
18387 __m128i __lsx_vssrani_hu_w (__m128i, __m128i, imm0_31);
18388 __m128i __lsx_vssrani_h_w (__m128i, __m128i, imm0_31);
18389 __m128i __lsx_vssrani_w_d (__m128i, __m128i, imm0_63);
18390 __m128i __lsx_vssrani_wu_d (__m128i, __m128i, imm0_63);
18391 __m128i __lsx_vssran_w_d (__m128i, __m128i);
18392 __m128i __lsx_vssran_wu_d (__m128i, __m128i);
18393 __m128i __lsx_vssrarn_b_h (__m128i, __m128i);
18394 __m128i __lsx_vssrarn_bu_h (__m128i, __m128i);
18395 __m128i __lsx_vssrarn_hu_w (__m128i, __m128i);
18396 __m128i __lsx_vssrarn_h_w (__m128i, __m128i);
18397 __m128i __lsx_vssrarni_b_h (__m128i, __m128i, imm0_15);
18398 __m128i __lsx_vssrarni_bu_h (__m128i, __m128i, imm0_15);
18399 __m128i __lsx_vssrarni_d_q (__m128i, __m128i, imm0_127);
18400 __m128i __lsx_vssrarni_du_q (__m128i, __m128i, imm0_127);
18401 __m128i __lsx_vssrarni_hu_w (__m128i, __m128i, imm0_31);
18402 __m128i __lsx_vssrarni_h_w (__m128i, __m128i, imm0_31);
18403 __m128i __lsx_vssrarni_w_d (__m128i, __m128i, imm0_63);
18404 __m128i __lsx_vssrarni_wu_d (__m128i, __m128i, imm0_63);
18405 __m128i __lsx_vssrarn_w_d (__m128i, __m128i);
18406 __m128i __lsx_vssrarn_wu_d (__m128i, __m128i);
18407 __m128i __lsx_vssrln_b_h (__m128i, __m128i);
18408 __m128i __lsx_vssrln_bu_h (__m128i, __m128i);
18409 __m128i __lsx_vssrln_hu_w (__m128i, __m128i);
18410 __m128i __lsx_vssrln_h_w (__m128i, __m128i);
18411 __m128i __lsx_vssrlni_b_h (__m128i, __m128i, imm0_15);
18412 __m128i __lsx_vssrlni_bu_h (__m128i, __m128i, imm0_15);
18413 __m128i __lsx_vssrlni_d_q (__m128i, __m128i, imm0_127);
18414 __m128i __lsx_vssrlni_du_q (__m128i, __m128i, imm0_127);
18415 __m128i __lsx_vssrlni_hu_w (__m128i, __m128i, imm0_31);
18416 __m128i __lsx_vssrlni_h_w (__m128i, __m128i, imm0_31);
18417 __m128i __lsx_vssrlni_w_d (__m128i, __m128i, imm0_63);
18418 __m128i __lsx_vssrlni_wu_d (__m128i, __m128i, imm0_63);
18419 __m128i __lsx_vssrln_w_d (__m128i, __m128i);
18420 __m128i __lsx_vssrln_wu_d (__m128i, __m128i);
18421 __m128i __lsx_vssrlrn_b_h (__m128i, __m128i);
18422 __m128i __lsx_vssrlrn_bu_h (__m128i, __m128i);
18423 __m128i __lsx_vssrlrn_hu_w (__m128i, __m128i);
18424 __m128i __lsx_vssrlrn_h_w (__m128i, __m128i);
18425 __m128i __lsx_vssrlrni_b_h (__m128i, __m128i, imm0_15);
18426 __m128i __lsx_vssrlrni_bu_h (__m128i, __m128i, imm0_15);
18427 __m128i __lsx_vssrlrni_d_q (__m128i, __m128i, imm0_127);
18428 __m128i __lsx_vssrlrni_du_q (__m128i, __m128i, imm0_127);
18429 __m128i __lsx_vssrlrni_hu_w (__m128i, __m128i, imm0_31);
18430 __m128i __lsx_vssrlrni_h_w (__m128i, __m128i, imm0_31);
18431 __m128i __lsx_vssrlrni_w_d (__m128i, __m128i, imm0_63);
18432 __m128i __lsx_vssrlrni_wu_d (__m128i, __m128i, imm0_63);
18433 __m128i __lsx_vssrlrn_w_d (__m128i, __m128i);
18434 __m128i __lsx_vssrlrn_wu_d (__m128i, __m128i);
18435 __m128i __lsx_vssub_b (__m128i, __m128i);
18436 __m128i __lsx_vssub_bu (__m128i, __m128i);
18437 __m128i __lsx_vssub_d (__m128i, __m128i);
18438 __m128i __lsx_vssub_du (__m128i, __m128i);
18439 __m128i __lsx_vssub_h (__m128i, __m128i);
18440 __m128i __lsx_vssub_hu (__m128i, __m128i);
18441 __m128i __lsx_vssub_w (__m128i, __m128i);
18442 __m128i __lsx_vssub_wu (__m128i, __m128i);
18443 void __lsx_vst (__m128i, void *, imm_n2048_2047);
18444 void __lsx_vstelm_b (__m128i, void *, imm_n128_127, imm0_15);
18445 void __lsx_vstelm_d (__m128i, void *, imm_n128_127, imm0_1);
18446 void __lsx_vstelm_h (__m128i, void *, imm_n128_127, imm0_7);
18447 void __lsx_vstelm_w (__m128i, void *, imm_n128_127, imm0_3);
18448 void __lsx_vstx (__m128i, void *, long int);
18449 __m128i __lsx_vsub_b (__m128i, __m128i);
18450 __m128i __lsx_vsub_d (__m128i, __m128i);
18451 __m128i __lsx_vsub_h (__m128i, __m128i);
18452 __m128i __lsx_vsubi_bu (__m128i, imm0_31);
18453 __m128i __lsx_vsubi_du (__m128i, imm0_31);
18454 __m128i __lsx_vsubi_hu (__m128i, imm0_31);
18455 __m128i __lsx_vsubi_wu (__m128i, imm0_31);
18456 __m128i __lsx_vsub_q (__m128i, __m128i);
18457 __m128i __lsx_vsub_w (__m128i, __m128i);
18458 __m128i __lsx_vsubwev_d_w (__m128i, __m128i);
18459 __m128i __lsx_vsubwev_d_wu (__m128i, __m128i);
18460 __m128i __lsx_vsubwev_h_b (__m128i, __m128i);
18461 __m128i __lsx_vsubwev_h_bu (__m128i, __m128i);
18462 __m128i __lsx_vsubwev_q_d (__m128i, __m128i);
18463 __m128i __lsx_vsubwev_q_du (__m128i, __m128i);
18464 __m128i __lsx_vsubwev_w_h (__m128i, __m128i);
18465 __m128i __lsx_vsubwev_w_hu (__m128i, __m128i);
18466 __m128i __lsx_vsubwod_d_w (__m128i, __m128i);
18467 __m128i __lsx_vsubwod_d_wu (__m128i, __m128i);
18468 __m128i __lsx_vsubwod_h_b (__m128i, __m128i);
18469 __m128i __lsx_vsubwod_h_bu (__m128i, __m128i);
18470 __m128i __lsx_vsubwod_q_d (__m128i, __m128i);
18471 __m128i __lsx_vsubwod_q_du (__m128i, __m128i);
18472 __m128i __lsx_vsubwod_w_h (__m128i, __m128i);
18473 __m128i __lsx_vsubwod_w_hu (__m128i, __m128i);
18474 __m128i __lsx_vxori_b (__m128i, imm0_255);
18475 __m128i __lsx_vxor_v (__m128i, __m128i);
18478 These instrisic functions are available by including @code{lsxintrin.h} and
18479 using @option{-mfrecipe} and @option{-mlsx}.
18481 __m128d __lsx_vfrecipe_d (__m128d);
18482 __m128 __lsx_vfrecipe_s (__m128);
18483 __m128d __lsx_vfrsqrte_d (__m128d);
18484 __m128 __lsx_vfrsqrte_s (__m128);
18487 @node LoongArch ASX Vector Intrinsics
18488 @subsection LoongArch ASX Vector Intrinsics
18490 GCC provides intrinsics to access the LASX (Loongson Advanced SIMD Extension)
18491 instructions. The interface is made available by including @code{<lasxintrin.h>}
18492 and using @option{-mlasx}.
18494 The following vectors typedefs are included in @code{lasxintrin.h}:
18497 @item @code{__m256i}, a 256-bit vector of fixed point;
18498 @item @code{__m256}, a 256-bit vector of single precision floating point;
18499 @item @code{__m256d}, a 256-bit vector of double precision floating point.
18502 Instructions and corresponding built-ins may have additional restrictions and/or
18503 input/output values manipulated:
18506 @item @code{imm0_1}, an integer literal in range 0 to 1.
18507 @item @code{imm0_3}, an integer literal in range 0 to 3.
18508 @item @code{imm0_7}, an integer literal in range 0 to 7.
18509 @item @code{imm0_15}, an integer literal in range 0 to 15.
18510 @item @code{imm0_31}, an integer literal in range 0 to 31.
18511 @item @code{imm0_63}, an integer literal in range 0 to 63.
18512 @item @code{imm0_127}, an integer literal in range 0 to 127.
18513 @item @code{imm0_255}, an integer literal in range 0 to 255.
18514 @item @code{imm_n16_15}, an integer literal in range -16 to 15.
18515 @item @code{imm_n128_127}, an integer literal in range -128 to 127.
18516 @item @code{imm_n256_255}, an integer literal in range -256 to 255.
18517 @item @code{imm_n512_511}, an integer literal in range -512 to 511.
18518 @item @code{imm_n1024_1023}, an integer literal in range -1024 to 1023.
18519 @item @code{imm_n2048_2047}, an integer literal in range -2048 to 2047.
18522 For convenience, GCC defines functions @code{__lasx_xvrepli_@{b/h/w/d@}} and
18523 @code{__lasx_b[n]z_@{v/b/h/w/d@}}, which are implemented as follows:
18526 a. @code{__lasx_xvrepli_@{b/h/w/d@}}: Implemented the case where the highest
18527 bit of @code{xvldi} instruction @code{i13} is 1.
18530 case i13[11:10] of :
18531 2'b00: __lasx_xvrepli_b (imm_n512_511)
18532 2'b01: __lasx_xvrepli_h (imm_n512_511)
18533 2'b10: __lasx_xvrepli_w (imm_n512_511)
18534 2'b11: __lasx_xvrepli_d (imm_n512_511)
18536 b. @code{__lasx_b[n]z_@{v/b/h/w/d@}}: Since the @code{xvseteqz} class directive
18537 cannot be used on its own, this function is defined.
18539 __lasx_xbz_v => xvseteqz.v + bcnez
18540 __lasx_xbnz_v => xvsetnez.v + bcnez
18541 __lasx_xbz_b => xvsetanyeqz.b + bcnez
18542 __lasx_xbz_h => xvsetanyeqz.h + bcnez
18543 __lasx_xbz_w => xvsetanyeqz.w + bcnez
18544 __lasx_xbz_d => xvsetanyeqz.d + bcnez
18545 __lasx_xbnz_b => xvsetallnez.b + bcnez
18546 __lasx_xbnz_h => xvsetallnez.h + bcnez
18547 __lasx_xbnz_w => xvsetallnez.w + bcnez
18548 __lasx_xbnz_d => xvsetallnez.d + bcnez
18553 #include <lasxintrin.h>
18555 extern __m256i @var{a};
18560 if (__lasx_xbz_v (@var{a}))
18567 @emph{Note:} For directives where the intent operand is also the source operand
18568 (modifying only part of the bitfield of the intent register), the first parameter
18569 in the builtin call function is used as the intent operand.
18573 #include <lasxintrin.h>
18574 extern __m256i @var{dst};
18580 @var{dst} = __lasx_xvinsgr2vr_w (@var{dst}, @var{src}, 3);
18585 The intrinsics provided are listed below:
18588 __m256i __lasx_vext2xv_d_b (__m256i);
18589 __m256i __lasx_vext2xv_d_h (__m256i);
18590 __m256i __lasx_vext2xv_du_bu (__m256i);
18591 __m256i __lasx_vext2xv_du_hu (__m256i);
18592 __m256i __lasx_vext2xv_du_wu (__m256i);
18593 __m256i __lasx_vext2xv_d_w (__m256i);
18594 __m256i __lasx_vext2xv_h_b (__m256i);
18595 __m256i __lasx_vext2xv_hu_bu (__m256i);
18596 __m256i __lasx_vext2xv_w_b (__m256i);
18597 __m256i __lasx_vext2xv_w_h (__m256i);
18598 __m256i __lasx_vext2xv_wu_bu (__m256i);
18599 __m256i __lasx_vext2xv_wu_hu (__m256i);
18600 int __lasx_xbnz_b (__m256i);
18601 int __lasx_xbnz_d (__m256i);
18602 int __lasx_xbnz_h (__m256i);
18603 int __lasx_xbnz_v (__m256i);
18604 int __lasx_xbnz_w (__m256i);
18605 int __lasx_xbz_b (__m256i);
18606 int __lasx_xbz_d (__m256i);
18607 int __lasx_xbz_h (__m256i);
18608 int __lasx_xbz_v (__m256i);
18609 int __lasx_xbz_w (__m256i);
18610 __m256i __lasx_xvabsd_b (__m256i, __m256i);
18611 __m256i __lasx_xvabsd_bu (__m256i, __m256i);
18612 __m256i __lasx_xvabsd_d (__m256i, __m256i);
18613 __m256i __lasx_xvabsd_du (__m256i, __m256i);
18614 __m256i __lasx_xvabsd_h (__m256i, __m256i);
18615 __m256i __lasx_xvabsd_hu (__m256i, __m256i);
18616 __m256i __lasx_xvabsd_w (__m256i, __m256i);
18617 __m256i __lasx_xvabsd_wu (__m256i, __m256i);
18618 __m256i __lasx_xvadda_b (__m256i, __m256i);
18619 __m256i __lasx_xvadda_d (__m256i, __m256i);
18620 __m256i __lasx_xvadda_h (__m256i, __m256i);
18621 __m256i __lasx_xvadda_w (__m256i, __m256i);
18622 __m256i __lasx_xvadd_b (__m256i, __m256i);
18623 __m256i __lasx_xvadd_d (__m256i, __m256i);
18624 __m256i __lasx_xvadd_h (__m256i, __m256i);
18625 __m256i __lasx_xvaddi_bu (__m256i, imm0_31);
18626 __m256i __lasx_xvaddi_du (__m256i, imm0_31);
18627 __m256i __lasx_xvaddi_hu (__m256i, imm0_31);
18628 __m256i __lasx_xvaddi_wu (__m256i, imm0_31);
18629 __m256i __lasx_xvadd_q (__m256i, __m256i);
18630 __m256i __lasx_xvadd_w (__m256i, __m256i);
18631 __m256i __lasx_xvaddwev_d_w (__m256i, __m256i);
18632 __m256i __lasx_xvaddwev_d_wu (__m256i, __m256i);
18633 __m256i __lasx_xvaddwev_d_wu_w (__m256i, __m256i);
18634 __m256i __lasx_xvaddwev_h_b (__m256i, __m256i);
18635 __m256i __lasx_xvaddwev_h_bu (__m256i, __m256i);
18636 __m256i __lasx_xvaddwev_h_bu_b (__m256i, __m256i);
18637 __m256i __lasx_xvaddwev_q_d (__m256i, __m256i);
18638 __m256i __lasx_xvaddwev_q_du (__m256i, __m256i);
18639 __m256i __lasx_xvaddwev_q_du_d (__m256i, __m256i);
18640 __m256i __lasx_xvaddwev_w_h (__m256i, __m256i);
18641 __m256i __lasx_xvaddwev_w_hu (__m256i, __m256i);
18642 __m256i __lasx_xvaddwev_w_hu_h (__m256i, __m256i);
18643 __m256i __lasx_xvaddwod_d_w (__m256i, __m256i);
18644 __m256i __lasx_xvaddwod_d_wu (__m256i, __m256i);
18645 __m256i __lasx_xvaddwod_d_wu_w (__m256i, __m256i);
18646 __m256i __lasx_xvaddwod_h_b (__m256i, __m256i);
18647 __m256i __lasx_xvaddwod_h_bu (__m256i, __m256i);
18648 __m256i __lasx_xvaddwod_h_bu_b (__m256i, __m256i);
18649 __m256i __lasx_xvaddwod_q_d (__m256i, __m256i);
18650 __m256i __lasx_xvaddwod_q_du (__m256i, __m256i);
18651 __m256i __lasx_xvaddwod_q_du_d (__m256i, __m256i);
18652 __m256i __lasx_xvaddwod_w_h (__m256i, __m256i);
18653 __m256i __lasx_xvaddwod_w_hu (__m256i, __m256i);
18654 __m256i __lasx_xvaddwod_w_hu_h (__m256i, __m256i);
18655 __m256i __lasx_xvandi_b (__m256i, imm0_255);
18656 __m256i __lasx_xvandn_v (__m256i, __m256i);
18657 __m256i __lasx_xvand_v (__m256i, __m256i);
18658 __m256i __lasx_xvavg_b (__m256i, __m256i);
18659 __m256i __lasx_xvavg_bu (__m256i, __m256i);
18660 __m256i __lasx_xvavg_d (__m256i, __m256i);
18661 __m256i __lasx_xvavg_du (__m256i, __m256i);
18662 __m256i __lasx_xvavg_h (__m256i, __m256i);
18663 __m256i __lasx_xvavg_hu (__m256i, __m256i);
18664 __m256i __lasx_xvavgr_b (__m256i, __m256i);
18665 __m256i __lasx_xvavgr_bu (__m256i, __m256i);
18666 __m256i __lasx_xvavgr_d (__m256i, __m256i);
18667 __m256i __lasx_xvavgr_du (__m256i, __m256i);
18668 __m256i __lasx_xvavgr_h (__m256i, __m256i);
18669 __m256i __lasx_xvavgr_hu (__m256i, __m256i);
18670 __m256i __lasx_xvavgr_w (__m256i, __m256i);
18671 __m256i __lasx_xvavgr_wu (__m256i, __m256i);
18672 __m256i __lasx_xvavg_w (__m256i, __m256i);
18673 __m256i __lasx_xvavg_wu (__m256i, __m256i);
18674 __m256i __lasx_xvbitclr_b (__m256i, __m256i);
18675 __m256i __lasx_xvbitclr_d (__m256i, __m256i);
18676 __m256i __lasx_xvbitclr_h (__m256i, __m256i);
18677 __m256i __lasx_xvbitclri_b (__m256i, imm0_7);
18678 __m256i __lasx_xvbitclri_d (__m256i, imm0_63);
18679 __m256i __lasx_xvbitclri_h (__m256i, imm0_15);
18680 __m256i __lasx_xvbitclri_w (__m256i, imm0_31);
18681 __m256i __lasx_xvbitclr_w (__m256i, __m256i);
18682 __m256i __lasx_xvbitrev_b (__m256i, __m256i);
18683 __m256i __lasx_xvbitrev_d (__m256i, __m256i);
18684 __m256i __lasx_xvbitrev_h (__m256i, __m256i);
18685 __m256i __lasx_xvbitrevi_b (__m256i, imm0_7);
18686 __m256i __lasx_xvbitrevi_d (__m256i, imm0_63);
18687 __m256i __lasx_xvbitrevi_h (__m256i, imm0_15);
18688 __m256i __lasx_xvbitrevi_w (__m256i, imm0_31);
18689 __m256i __lasx_xvbitrev_w (__m256i, __m256i);
18690 __m256i __lasx_xvbitseli_b (__m256i, __m256i, imm0_255);
18691 __m256i __lasx_xvbitsel_v (__m256i, __m256i, __m256i);
18692 __m256i __lasx_xvbitset_b (__m256i, __m256i);
18693 __m256i __lasx_xvbitset_d (__m256i, __m256i);
18694 __m256i __lasx_xvbitset_h (__m256i, __m256i);
18695 __m256i __lasx_xvbitseti_b (__m256i, imm0_7);
18696 __m256i __lasx_xvbitseti_d (__m256i, imm0_63);
18697 __m256i __lasx_xvbitseti_h (__m256i, imm0_15);
18698 __m256i __lasx_xvbitseti_w (__m256i, imm0_31);
18699 __m256i __lasx_xvbitset_w (__m256i, __m256i);
18700 __m256i __lasx_xvbsll_v (__m256i, imm0_31);
18701 __m256i __lasx_xvbsrl_v (__m256i, imm0_31);
18702 __m256i __lasx_xvclo_b (__m256i);
18703 __m256i __lasx_xvclo_d (__m256i);
18704 __m256i __lasx_xvclo_h (__m256i);
18705 __m256i __lasx_xvclo_w (__m256i);
18706 __m256i __lasx_xvclz_b (__m256i);
18707 __m256i __lasx_xvclz_d (__m256i);
18708 __m256i __lasx_xvclz_h (__m256i);
18709 __m256i __lasx_xvclz_w (__m256i);
18710 __m256i __lasx_xvdiv_b (__m256i, __m256i);
18711 __m256i __lasx_xvdiv_bu (__m256i, __m256i);
18712 __m256i __lasx_xvdiv_d (__m256i, __m256i);
18713 __m256i __lasx_xvdiv_du (__m256i, __m256i);
18714 __m256i __lasx_xvdiv_h (__m256i, __m256i);
18715 __m256i __lasx_xvdiv_hu (__m256i, __m256i);
18716 __m256i __lasx_xvdiv_w (__m256i, __m256i);
18717 __m256i __lasx_xvdiv_wu (__m256i, __m256i);
18718 __m256i __lasx_xvexth_du_wu (__m256i);
18719 __m256i __lasx_xvexth_d_w (__m256i);
18720 __m256i __lasx_xvexth_h_b (__m256i);
18721 __m256i __lasx_xvexth_hu_bu (__m256i);
18722 __m256i __lasx_xvexth_q_d (__m256i);
18723 __m256i __lasx_xvexth_qu_du (__m256i);
18724 __m256i __lasx_xvexth_w_h (__m256i);
18725 __m256i __lasx_xvexth_wu_hu (__m256i);
18726 __m256i __lasx_xvextl_q_d (__m256i);
18727 __m256i __lasx_xvextl_qu_du (__m256i);
18728 __m256i __lasx_xvextrins_b (__m256i, __m256i, imm0_255);
18729 __m256i __lasx_xvextrins_d (__m256i, __m256i, imm0_255);
18730 __m256i __lasx_xvextrins_h (__m256i, __m256i, imm0_255);
18731 __m256i __lasx_xvextrins_w (__m256i, __m256i, imm0_255);
18732 __m256d __lasx_xvfadd_d (__m256d, __m256d);
18733 __m256 __lasx_xvfadd_s (__m256, __m256);
18734 __m256i __lasx_xvfclass_d (__m256d);
18735 __m256i __lasx_xvfclass_s (__m256);
18736 __m256i __lasx_xvfcmp_caf_d (__m256d, __m256d);
18737 __m256i __lasx_xvfcmp_caf_s (__m256, __m256);
18738 __m256i __lasx_xvfcmp_ceq_d (__m256d, __m256d);
18739 __m256i __lasx_xvfcmp_ceq_s (__m256, __m256);
18740 __m256i __lasx_xvfcmp_cle_d (__m256d, __m256d);
18741 __m256i __lasx_xvfcmp_cle_s (__m256, __m256);
18742 __m256i __lasx_xvfcmp_clt_d (__m256d, __m256d);
18743 __m256i __lasx_xvfcmp_clt_s (__m256, __m256);
18744 __m256i __lasx_xvfcmp_cne_d (__m256d, __m256d);
18745 __m256i __lasx_xvfcmp_cne_s (__m256, __m256);
18746 __m256i __lasx_xvfcmp_cor_d (__m256d, __m256d);
18747 __m256i __lasx_xvfcmp_cor_s (__m256, __m256);
18748 __m256i __lasx_xvfcmp_cueq_d (__m256d, __m256d);
18749 __m256i __lasx_xvfcmp_cueq_s (__m256, __m256);
18750 __m256i __lasx_xvfcmp_cule_d (__m256d, __m256d);
18751 __m256i __lasx_xvfcmp_cule_s (__m256, __m256);
18752 __m256i __lasx_xvfcmp_cult_d (__m256d, __m256d);
18753 __m256i __lasx_xvfcmp_cult_s (__m256, __m256);
18754 __m256i __lasx_xvfcmp_cun_d (__m256d, __m256d);
18755 __m256i __lasx_xvfcmp_cune_d (__m256d, __m256d);
18756 __m256i __lasx_xvfcmp_cune_s (__m256, __m256);
18757 __m256i __lasx_xvfcmp_cun_s (__m256, __m256);
18758 __m256i __lasx_xvfcmp_saf_d (__m256d, __m256d);
18759 __m256i __lasx_xvfcmp_saf_s (__m256, __m256);
18760 __m256i __lasx_xvfcmp_seq_d (__m256d, __m256d);
18761 __m256i __lasx_xvfcmp_seq_s (__m256, __m256);
18762 __m256i __lasx_xvfcmp_sle_d (__m256d, __m256d);
18763 __m256i __lasx_xvfcmp_sle_s (__m256, __m256);
18764 __m256i __lasx_xvfcmp_slt_d (__m256d, __m256d);
18765 __m256i __lasx_xvfcmp_slt_s (__m256, __m256);
18766 __m256i __lasx_xvfcmp_sne_d (__m256d, __m256d);
18767 __m256i __lasx_xvfcmp_sne_s (__m256, __m256);
18768 __m256i __lasx_xvfcmp_sor_d (__m256d, __m256d);
18769 __m256i __lasx_xvfcmp_sor_s (__m256, __m256);
18770 __m256i __lasx_xvfcmp_sueq_d (__m256d, __m256d);
18771 __m256i __lasx_xvfcmp_sueq_s (__m256, __m256);
18772 __m256i __lasx_xvfcmp_sule_d (__m256d, __m256d);
18773 __m256i __lasx_xvfcmp_sule_s (__m256, __m256);
18774 __m256i __lasx_xvfcmp_sult_d (__m256d, __m256d);
18775 __m256i __lasx_xvfcmp_sult_s (__m256, __m256);
18776 __m256i __lasx_xvfcmp_sun_d (__m256d, __m256d);
18777 __m256i __lasx_xvfcmp_sune_d (__m256d, __m256d);
18778 __m256i __lasx_xvfcmp_sune_s (__m256, __m256);
18779 __m256i __lasx_xvfcmp_sun_s (__m256, __m256);
18780 __m256d __lasx_xvfcvth_d_s (__m256);
18781 __m256i __lasx_xvfcvt_h_s (__m256, __m256);
18782 __m256 __lasx_xvfcvth_s_h (__m256i);
18783 __m256d __lasx_xvfcvtl_d_s (__m256);
18784 __m256 __lasx_xvfcvtl_s_h (__m256i);
18785 __m256 __lasx_xvfcvt_s_d (__m256d, __m256d);
18786 __m256d __lasx_xvfdiv_d (__m256d, __m256d);
18787 __m256 __lasx_xvfdiv_s (__m256, __m256);
18788 __m256d __lasx_xvffint_d_l (__m256i);
18789 __m256d __lasx_xvffint_d_lu (__m256i);
18790 __m256d __lasx_xvffinth_d_w (__m256i);
18791 __m256d __lasx_xvffintl_d_w (__m256i);
18792 __m256 __lasx_xvffint_s_l (__m256i, __m256i);
18793 __m256 __lasx_xvffint_s_w (__m256i);
18794 __m256 __lasx_xvffint_s_wu (__m256i);
18795 __m256d __lasx_xvflogb_d (__m256d);
18796 __m256 __lasx_xvflogb_s (__m256);
18797 __m256d __lasx_xvfmadd_d (__m256d, __m256d, __m256d);
18798 __m256 __lasx_xvfmadd_s (__m256, __m256, __m256);
18799 __m256d __lasx_xvfmaxa_d (__m256d, __m256d);
18800 __m256 __lasx_xvfmaxa_s (__m256, __m256);
18801 __m256d __lasx_xvfmax_d (__m256d, __m256d);
18802 __m256 __lasx_xvfmax_s (__m256, __m256);
18803 __m256d __lasx_xvfmina_d (__m256d, __m256d);
18804 __m256 __lasx_xvfmina_s (__m256, __m256);
18805 __m256d __lasx_xvfmin_d (__m256d, __m256d);
18806 __m256 __lasx_xvfmin_s (__m256, __m256);
18807 __m256d __lasx_xvfmsub_d (__m256d, __m256d, __m256d);
18808 __m256 __lasx_xvfmsub_s (__m256, __m256, __m256);
18809 __m256d __lasx_xvfmul_d (__m256d, __m256d);
18810 __m256 __lasx_xvfmul_s (__m256, __m256);
18811 __m256d __lasx_xvfnmadd_d (__m256d, __m256d, __m256d);
18812 __m256 __lasx_xvfnmadd_s (__m256, __m256, __m256);
18813 __m256d __lasx_xvfnmsub_d (__m256d, __m256d, __m256d);
18814 __m256 __lasx_xvfnmsub_s (__m256, __m256, __m256);
18815 __m256d __lasx_xvfrecip_d (__m256d);
18816 __m256 __lasx_xvfrecip_s (__m256);
18817 __m256d __lasx_xvfrint_d (__m256d);
18818 __m256d __lasx_xvfrintrm_d (__m256d);
18819 __m256 __lasx_xvfrintrm_s (__m256);
18820 __m256d __lasx_xvfrintrne_d (__m256d);
18821 __m256 __lasx_xvfrintrne_s (__m256);
18822 __m256d __lasx_xvfrintrp_d (__m256d);
18823 __m256 __lasx_xvfrintrp_s (__m256);
18824 __m256d __lasx_xvfrintrz_d (__m256d);
18825 __m256 __lasx_xvfrintrz_s (__m256);
18826 __m256 __lasx_xvfrint_s (__m256);
18827 __m256d __lasx_xvfrsqrt_d (__m256d);
18828 __m256 __lasx_xvfrsqrt_s (__m256);
18829 __m256i __lasx_xvfrstp_b (__m256i, __m256i, __m256i);
18830 __m256i __lasx_xvfrstp_h (__m256i, __m256i, __m256i);
18831 __m256i __lasx_xvfrstpi_b (__m256i, __m256i, imm0_31);
18832 __m256i __lasx_xvfrstpi_h (__m256i, __m256i, imm0_31);
18833 __m256d __lasx_xvfsqrt_d (__m256d);
18834 __m256 __lasx_xvfsqrt_s (__m256);
18835 __m256d __lasx_xvfsub_d (__m256d, __m256d);
18836 __m256 __lasx_xvfsub_s (__m256, __m256);
18837 __m256i __lasx_xvftinth_l_s (__m256);
18838 __m256i __lasx_xvftint_l_d (__m256d);
18839 __m256i __lasx_xvftintl_l_s (__m256);
18840 __m256i __lasx_xvftint_lu_d (__m256d);
18841 __m256i __lasx_xvftintrmh_l_s (__m256);
18842 __m256i __lasx_xvftintrm_l_d (__m256d);
18843 __m256i __lasx_xvftintrml_l_s (__m256);
18844 __m256i __lasx_xvftintrm_w_d (__m256d, __m256d);
18845 __m256i __lasx_xvftintrm_w_s (__m256);
18846 __m256i __lasx_xvftintrneh_l_s (__m256);
18847 __m256i __lasx_xvftintrne_l_d (__m256d);
18848 __m256i __lasx_xvftintrnel_l_s (__m256);
18849 __m256i __lasx_xvftintrne_w_d (__m256d, __m256d);
18850 __m256i __lasx_xvftintrne_w_s (__m256);
18851 __m256i __lasx_xvftintrph_l_s (__m256);
18852 __m256i __lasx_xvftintrp_l_d (__m256d);
18853 __m256i __lasx_xvftintrpl_l_s (__m256);
18854 __m256i __lasx_xvftintrp_w_d (__m256d, __m256d);
18855 __m256i __lasx_xvftintrp_w_s (__m256);
18856 __m256i __lasx_xvftintrzh_l_s (__m256);
18857 __m256i __lasx_xvftintrz_l_d (__m256d);
18858 __m256i __lasx_xvftintrzl_l_s (__m256);
18859 __m256i __lasx_xvftintrz_lu_d (__m256d);
18860 __m256i __lasx_xvftintrz_w_d (__m256d, __m256d);
18861 __m256i __lasx_xvftintrz_w_s (__m256);
18862 __m256i __lasx_xvftintrz_wu_s (__m256);
18863 __m256i __lasx_xvftint_w_d (__m256d, __m256d);
18864 __m256i __lasx_xvftint_w_s (__m256);
18865 __m256i __lasx_xvftint_wu_s (__m256);
18866 __m256i __lasx_xvhaddw_du_wu (__m256i, __m256i);
18867 __m256i __lasx_xvhaddw_d_w (__m256i, __m256i);
18868 __m256i __lasx_xvhaddw_h_b (__m256i, __m256i);
18869 __m256i __lasx_xvhaddw_hu_bu (__m256i, __m256i);
18870 __m256i __lasx_xvhaddw_q_d (__m256i, __m256i);
18871 __m256i __lasx_xvhaddw_qu_du (__m256i, __m256i);
18872 __m256i __lasx_xvhaddw_w_h (__m256i, __m256i);
18873 __m256i __lasx_xvhaddw_wu_hu (__m256i, __m256i);
18874 __m256i __lasx_xvhsubw_du_wu (__m256i, __m256i);
18875 __m256i __lasx_xvhsubw_d_w (__m256i, __m256i);
18876 __m256i __lasx_xvhsubw_h_b (__m256i, __m256i);
18877 __m256i __lasx_xvhsubw_hu_bu (__m256i, __m256i);
18878 __m256i __lasx_xvhsubw_q_d (__m256i, __m256i);
18879 __m256i __lasx_xvhsubw_qu_du (__m256i, __m256i);
18880 __m256i __lasx_xvhsubw_w_h (__m256i, __m256i);
18881 __m256i __lasx_xvhsubw_wu_hu (__m256i, __m256i);
18882 __m256i __lasx_xvilvh_b (__m256i, __m256i);
18883 __m256i __lasx_xvilvh_d (__m256i, __m256i);
18884 __m256i __lasx_xvilvh_h (__m256i, __m256i);
18885 __m256i __lasx_xvilvh_w (__m256i, __m256i);
18886 __m256i __lasx_xvilvl_b (__m256i, __m256i);
18887 __m256i __lasx_xvilvl_d (__m256i, __m256i);
18888 __m256i __lasx_xvilvl_h (__m256i, __m256i);
18889 __m256i __lasx_xvilvl_w (__m256i, __m256i);
18890 __m256i __lasx_xvinsgr2vr_d (__m256i, long int, imm0_3);
18891 __m256i __lasx_xvinsgr2vr_w (__m256i, int, imm0_7);
18892 __m256i __lasx_xvinsve0_d (__m256i, __m256i, imm0_3);
18893 __m256i __lasx_xvinsve0_w (__m256i, __m256i, imm0_7);
18894 __m256i __lasx_xvld (void *, imm_n2048_2047);
18895 __m256i __lasx_xvldi (imm_n1024_1023);
18896 __m256i __lasx_xvldrepl_b (void *, imm_n2048_2047);
18897 __m256i __lasx_xvldrepl_d (void *, imm_n256_255);
18898 __m256i __lasx_xvldrepl_h (void *, imm_n1024_1023);
18899 __m256i __lasx_xvldrepl_w (void *, imm_n512_511);
18900 __m256i __lasx_xvldx (void *, long int);
18901 __m256i __lasx_xvmadd_b (__m256i, __m256i, __m256i);
18902 __m256i __lasx_xvmadd_d (__m256i, __m256i, __m256i);
18903 __m256i __lasx_xvmadd_h (__m256i, __m256i, __m256i);
18904 __m256i __lasx_xvmadd_w (__m256i, __m256i, __m256i);
18905 __m256i __lasx_xvmaddwev_d_w (__m256i, __m256i, __m256i);
18906 __m256i __lasx_xvmaddwev_d_wu (__m256i, __m256i, __m256i);
18907 __m256i __lasx_xvmaddwev_d_wu_w (__m256i, __m256i, __m256i);
18908 __m256i __lasx_xvmaddwev_h_b (__m256i, __m256i, __m256i);
18909 __m256i __lasx_xvmaddwev_h_bu (__m256i, __m256i, __m256i);
18910 __m256i __lasx_xvmaddwev_h_bu_b (__m256i, __m256i, __m256i);
18911 __m256i __lasx_xvmaddwev_q_d (__m256i, __m256i, __m256i);
18912 __m256i __lasx_xvmaddwev_q_du (__m256i, __m256i, __m256i);
18913 __m256i __lasx_xvmaddwev_q_du_d (__m256i, __m256i, __m256i);
18914 __m256i __lasx_xvmaddwev_w_h (__m256i, __m256i, __m256i);
18915 __m256i __lasx_xvmaddwev_w_hu (__m256i, __m256i, __m256i);
18916 __m256i __lasx_xvmaddwev_w_hu_h (__m256i, __m256i, __m256i);
18917 __m256i __lasx_xvmaddwod_d_w (__m256i, __m256i, __m256i);
18918 __m256i __lasx_xvmaddwod_d_wu (__m256i, __m256i, __m256i);
18919 __m256i __lasx_xvmaddwod_d_wu_w (__m256i, __m256i, __m256i);
18920 __m256i __lasx_xvmaddwod_h_b (__m256i, __m256i, __m256i);
18921 __m256i __lasx_xvmaddwod_h_bu (__m256i, __m256i, __m256i);
18922 __m256i __lasx_xvmaddwod_h_bu_b (__m256i, __m256i, __m256i);
18923 __m256i __lasx_xvmaddwod_q_d (__m256i, __m256i, __m256i);
18924 __m256i __lasx_xvmaddwod_q_du (__m256i, __m256i, __m256i);
18925 __m256i __lasx_xvmaddwod_q_du_d (__m256i, __m256i, __m256i);
18926 __m256i __lasx_xvmaddwod_w_h (__m256i, __m256i, __m256i);
18927 __m256i __lasx_xvmaddwod_w_hu (__m256i, __m256i, __m256i);
18928 __m256i __lasx_xvmaddwod_w_hu_h (__m256i, __m256i, __m256i);
18929 __m256i __lasx_xvmax_b (__m256i, __m256i);
18930 __m256i __lasx_xvmax_bu (__m256i, __m256i);
18931 __m256i __lasx_xvmax_d (__m256i, __m256i);
18932 __m256i __lasx_xvmax_du (__m256i, __m256i);
18933 __m256i __lasx_xvmax_h (__m256i, __m256i);
18934 __m256i __lasx_xvmax_hu (__m256i, __m256i);
18935 __m256i __lasx_xvmaxi_b (__m256i, imm_n16_15);
18936 __m256i __lasx_xvmaxi_bu (__m256i, imm0_31);
18937 __m256i __lasx_xvmaxi_d (__m256i, imm_n16_15);
18938 __m256i __lasx_xvmaxi_du (__m256i, imm0_31);
18939 __m256i __lasx_xvmaxi_h (__m256i, imm_n16_15);
18940 __m256i __lasx_xvmaxi_hu (__m256i, imm0_31);
18941 __m256i __lasx_xvmaxi_w (__m256i, imm_n16_15);
18942 __m256i __lasx_xvmaxi_wu (__m256i, imm0_31);
18943 __m256i __lasx_xvmax_w (__m256i, __m256i);
18944 __m256i __lasx_xvmax_wu (__m256i, __m256i);
18945 __m256i __lasx_xvmin_b (__m256i, __m256i);
18946 __m256i __lasx_xvmin_bu (__m256i, __m256i);
18947 __m256i __lasx_xvmin_d (__m256i, __m256i);
18948 __m256i __lasx_xvmin_du (__m256i, __m256i);
18949 __m256i __lasx_xvmin_h (__m256i, __m256i);
18950 __m256i __lasx_xvmin_hu (__m256i, __m256i);
18951 __m256i __lasx_xvmini_b (__m256i, imm_n16_15);
18952 __m256i __lasx_xvmini_bu (__m256i, imm0_31);
18953 __m256i __lasx_xvmini_d (__m256i, imm_n16_15);
18954 __m256i __lasx_xvmini_du (__m256i, imm0_31);
18955 __m256i __lasx_xvmini_h (__m256i, imm_n16_15);
18956 __m256i __lasx_xvmini_hu (__m256i, imm0_31);
18957 __m256i __lasx_xvmini_w (__m256i, imm_n16_15);
18958 __m256i __lasx_xvmini_wu (__m256i, imm0_31);
18959 __m256i __lasx_xvmin_w (__m256i, __m256i);
18960 __m256i __lasx_xvmin_wu (__m256i, __m256i);
18961 __m256i __lasx_xvmod_b (__m256i, __m256i);
18962 __m256i __lasx_xvmod_bu (__m256i, __m256i);
18963 __m256i __lasx_xvmod_d (__m256i, __m256i);
18964 __m256i __lasx_xvmod_du (__m256i, __m256i);
18965 __m256i __lasx_xvmod_h (__m256i, __m256i);
18966 __m256i __lasx_xvmod_hu (__m256i, __m256i);
18967 __m256i __lasx_xvmod_w (__m256i, __m256i);
18968 __m256i __lasx_xvmod_wu (__m256i, __m256i);
18969 __m256i __lasx_xvmskgez_b (__m256i);
18970 __m256i __lasx_xvmskltz_b (__m256i);
18971 __m256i __lasx_xvmskltz_d (__m256i);
18972 __m256i __lasx_xvmskltz_h (__m256i);
18973 __m256i __lasx_xvmskltz_w (__m256i);
18974 __m256i __lasx_xvmsknz_b (__m256i);
18975 __m256i __lasx_xvmsub_b (__m256i, __m256i, __m256i);
18976 __m256i __lasx_xvmsub_d (__m256i, __m256i, __m256i);
18977 __m256i __lasx_xvmsub_h (__m256i, __m256i, __m256i);
18978 __m256i __lasx_xvmsub_w (__m256i, __m256i, __m256i);
18979 __m256i __lasx_xvmuh_b (__m256i, __m256i);
18980 __m256i __lasx_xvmuh_bu (__m256i, __m256i);
18981 __m256i __lasx_xvmuh_d (__m256i, __m256i);
18982 __m256i __lasx_xvmuh_du (__m256i, __m256i);
18983 __m256i __lasx_xvmuh_h (__m256i, __m256i);
18984 __m256i __lasx_xvmuh_hu (__m256i, __m256i);
18985 __m256i __lasx_xvmuh_w (__m256i, __m256i);
18986 __m256i __lasx_xvmuh_wu (__m256i, __m256i);
18987 __m256i __lasx_xvmul_b (__m256i, __m256i);
18988 __m256i __lasx_xvmul_d (__m256i, __m256i);
18989 __m256i __lasx_xvmul_h (__m256i, __m256i);
18990 __m256i __lasx_xvmul_w (__m256i, __m256i);
18991 __m256i __lasx_xvmulwev_d_w (__m256i, __m256i);
18992 __m256i __lasx_xvmulwev_d_wu (__m256i, __m256i);
18993 __m256i __lasx_xvmulwev_d_wu_w (__m256i, __m256i);
18994 __m256i __lasx_xvmulwev_h_b (__m256i, __m256i);
18995 __m256i __lasx_xvmulwev_h_bu (__m256i, __m256i);
18996 __m256i __lasx_xvmulwev_h_bu_b (__m256i, __m256i);
18997 __m256i __lasx_xvmulwev_q_d (__m256i, __m256i);
18998 __m256i __lasx_xvmulwev_q_du (__m256i, __m256i);
18999 __m256i __lasx_xvmulwev_q_du_d (__m256i, __m256i);
19000 __m256i __lasx_xvmulwev_w_h (__m256i, __m256i);
19001 __m256i __lasx_xvmulwev_w_hu (__m256i, __m256i);
19002 __m256i __lasx_xvmulwev_w_hu_h (__m256i, __m256i);
19003 __m256i __lasx_xvmulwod_d_w (__m256i, __m256i);
19004 __m256i __lasx_xvmulwod_d_wu (__m256i, __m256i);
19005 __m256i __lasx_xvmulwod_d_wu_w (__m256i, __m256i);
19006 __m256i __lasx_xvmulwod_h_b (__m256i, __m256i);
19007 __m256i __lasx_xvmulwod_h_bu (__m256i, __m256i);
19008 __m256i __lasx_xvmulwod_h_bu_b (__m256i, __m256i);
19009 __m256i __lasx_xvmulwod_q_d (__m256i, __m256i);
19010 __m256i __lasx_xvmulwod_q_du (__m256i, __m256i);
19011 __m256i __lasx_xvmulwod_q_du_d (__m256i, __m256i);
19012 __m256i __lasx_xvmulwod_w_h (__m256i, __m256i);
19013 __m256i __lasx_xvmulwod_w_hu (__m256i, __m256i);
19014 __m256i __lasx_xvmulwod_w_hu_h (__m256i, __m256i);
19015 __m256i __lasx_xvneg_b (__m256i);
19016 __m256i __lasx_xvneg_d (__m256i);
19017 __m256i __lasx_xvneg_h (__m256i);
19018 __m256i __lasx_xvneg_w (__m256i);
19019 __m256i __lasx_xvnori_b (__m256i, imm0_255);
19020 __m256i __lasx_xvnor_v (__m256i, __m256i);
19021 __m256i __lasx_xvori_b (__m256i, imm0_255);
19022 __m256i __lasx_xvorn_v (__m256i, __m256i);
19023 __m256i __lasx_xvor_v (__m256i, __m256i);
19024 __m256i __lasx_xvpackev_b (__m256i, __m256i);
19025 __m256i __lasx_xvpackev_d (__m256i, __m256i);
19026 __m256i __lasx_xvpackev_h (__m256i, __m256i);
19027 __m256i __lasx_xvpackev_w (__m256i, __m256i);
19028 __m256i __lasx_xvpackod_b (__m256i, __m256i);
19029 __m256i __lasx_xvpackod_d (__m256i, __m256i);
19030 __m256i __lasx_xvpackod_h (__m256i, __m256i);
19031 __m256i __lasx_xvpackod_w (__m256i, __m256i);
19032 __m256i __lasx_xvpcnt_b (__m256i);
19033 __m256i __lasx_xvpcnt_d (__m256i);
19034 __m256i __lasx_xvpcnt_h (__m256i);
19035 __m256i __lasx_xvpcnt_w (__m256i);
19036 __m256i __lasx_xvpermi_d (__m256i, imm0_255);
19037 __m256i __lasx_xvpermi_q (__m256i, __m256i, imm0_255);
19038 __m256i __lasx_xvpermi_w (__m256i, __m256i, imm0_255);
19039 __m256i __lasx_xvperm_w (__m256i, __m256i);
19040 __m256i __lasx_xvpickev_b (__m256i, __m256i);
19041 __m256i __lasx_xvpickev_d (__m256i, __m256i);
19042 __m256i __lasx_xvpickev_h (__m256i, __m256i);
19043 __m256i __lasx_xvpickev_w (__m256i, __m256i);
19044 __m256i __lasx_xvpickod_b (__m256i, __m256i);
19045 __m256i __lasx_xvpickod_d (__m256i, __m256i);
19046 __m256i __lasx_xvpickod_h (__m256i, __m256i);
19047 __m256i __lasx_xvpickod_w (__m256i, __m256i);
19048 long int __lasx_xvpickve2gr_d (__m256i, imm0_3);
19049 unsigned long int __lasx_xvpickve2gr_du (__m256i, imm0_3);
19050 int __lasx_xvpickve2gr_w (__m256i, imm0_7);
19051 unsigned int __lasx_xvpickve2gr_wu (__m256i, imm0_7);
19052 __m256i __lasx_xvpickve_d (__m256i, imm0_3);
19053 __m256d __lasx_xvpickve_d_f (__m256d, imm0_3);
19054 __m256i __lasx_xvpickve_w (__m256i, imm0_7);
19055 __m256 __lasx_xvpickve_w_f (__m256, imm0_7);
19056 __m256i __lasx_xvrepl128vei_b (__m256i, imm0_15);
19057 __m256i __lasx_xvrepl128vei_d (__m256i, imm0_1);
19058 __m256i __lasx_xvrepl128vei_h (__m256i, imm0_7);
19059 __m256i __lasx_xvrepl128vei_w (__m256i, imm0_3);
19060 __m256i __lasx_xvreplgr2vr_b (int);
19061 __m256i __lasx_xvreplgr2vr_d (long int);
19062 __m256i __lasx_xvreplgr2vr_h (int);
19063 __m256i __lasx_xvreplgr2vr_w (int);
19064 __m256i __lasx_xvrepli_b (imm_n512_511);
19065 __m256i __lasx_xvrepli_d (imm_n512_511);
19066 __m256i __lasx_xvrepli_h (imm_n512_511);
19067 __m256i __lasx_xvrepli_w (imm_n512_511);
19068 __m256i __lasx_xvreplve0_b (__m256i);
19069 __m256i __lasx_xvreplve0_d (__m256i);
19070 __m256i __lasx_xvreplve0_h (__m256i);
19071 __m256i __lasx_xvreplve0_q (__m256i);
19072 __m256i __lasx_xvreplve0_w (__m256i);
19073 __m256i __lasx_xvreplve_b (__m256i, int);
19074 __m256i __lasx_xvreplve_d (__m256i, int);
19075 __m256i __lasx_xvreplve_h (__m256i, int);
19076 __m256i __lasx_xvreplve_w (__m256i, int);
19077 __m256i __lasx_xvrotr_b (__m256i, __m256i);
19078 __m256i __lasx_xvrotr_d (__m256i, __m256i);
19079 __m256i __lasx_xvrotr_h (__m256i, __m256i);
19080 __m256i __lasx_xvrotri_b (__m256i, imm0_7);
19081 __m256i __lasx_xvrotri_d (__m256i, imm0_63);
19082 __m256i __lasx_xvrotri_h (__m256i, imm0_15);
19083 __m256i __lasx_xvrotri_w (__m256i, imm0_31);
19084 __m256i __lasx_xvrotr_w (__m256i, __m256i);
19085 __m256i __lasx_xvsadd_b (__m256i, __m256i);
19086 __m256i __lasx_xvsadd_bu (__m256i, __m256i);
19087 __m256i __lasx_xvsadd_d (__m256i, __m256i);
19088 __m256i __lasx_xvsadd_du (__m256i, __m256i);
19089 __m256i __lasx_xvsadd_h (__m256i, __m256i);
19090 __m256i __lasx_xvsadd_hu (__m256i, __m256i);
19091 __m256i __lasx_xvsadd_w (__m256i, __m256i);
19092 __m256i __lasx_xvsadd_wu (__m256i, __m256i);
19093 __m256i __lasx_xvsat_b (__m256i, imm0_7);
19094 __m256i __lasx_xvsat_bu (__m256i, imm0_7);
19095 __m256i __lasx_xvsat_d (__m256i, imm0_63);
19096 __m256i __lasx_xvsat_du (__m256i, imm0_63);
19097 __m256i __lasx_xvsat_h (__m256i, imm0_15);
19098 __m256i __lasx_xvsat_hu (__m256i, imm0_15);
19099 __m256i __lasx_xvsat_w (__m256i, imm0_31);
19100 __m256i __lasx_xvsat_wu (__m256i, imm0_31);
19101 __m256i __lasx_xvseq_b (__m256i, __m256i);
19102 __m256i __lasx_xvseq_d (__m256i, __m256i);
19103 __m256i __lasx_xvseq_h (__m256i, __m256i);
19104 __m256i __lasx_xvseqi_b (__m256i, imm_n16_15);
19105 __m256i __lasx_xvseqi_d (__m256i, imm_n16_15);
19106 __m256i __lasx_xvseqi_h (__m256i, imm_n16_15);
19107 __m256i __lasx_xvseqi_w (__m256i, imm_n16_15);
19108 __m256i __lasx_xvseq_w (__m256i, __m256i);
19109 __m256i __lasx_xvshuf4i_b (__m256i, imm0_255);
19110 __m256i __lasx_xvshuf4i_d (__m256i, __m256i, imm0_255);
19111 __m256i __lasx_xvshuf4i_h (__m256i, imm0_255);
19112 __m256i __lasx_xvshuf4i_w (__m256i, imm0_255);
19113 __m256i __lasx_xvshuf_b (__m256i, __m256i, __m256i);
19114 __m256i __lasx_xvshuf_d (__m256i, __m256i, __m256i);
19115 __m256i __lasx_xvshuf_h (__m256i, __m256i, __m256i);
19116 __m256i __lasx_xvshuf_w (__m256i, __m256i, __m256i);
19117 __m256i __lasx_xvsigncov_b (__m256i, __m256i);
19118 __m256i __lasx_xvsigncov_d (__m256i, __m256i);
19119 __m256i __lasx_xvsigncov_h (__m256i, __m256i);
19120 __m256i __lasx_xvsigncov_w (__m256i, __m256i);
19121 __m256i __lasx_xvsle_b (__m256i, __m256i);
19122 __m256i __lasx_xvsle_bu (__m256i, __m256i);
19123 __m256i __lasx_xvsle_d (__m256i, __m256i);
19124 __m256i __lasx_xvsle_du (__m256i, __m256i);
19125 __m256i __lasx_xvsle_h (__m256i, __m256i);
19126 __m256i __lasx_xvsle_hu (__m256i, __m256i);
19127 __m256i __lasx_xvslei_b (__m256i, imm_n16_15);
19128 __m256i __lasx_xvslei_bu (__m256i, imm0_31);
19129 __m256i __lasx_xvslei_d (__m256i, imm_n16_15);
19130 __m256i __lasx_xvslei_du (__m256i, imm0_31);
19131 __m256i __lasx_xvslei_h (__m256i, imm_n16_15);
19132 __m256i __lasx_xvslei_hu (__m256i, imm0_31);
19133 __m256i __lasx_xvslei_w (__m256i, imm_n16_15);
19134 __m256i __lasx_xvslei_wu (__m256i, imm0_31);
19135 __m256i __lasx_xvsle_w (__m256i, __m256i);
19136 __m256i __lasx_xvsle_wu (__m256i, __m256i);
19137 __m256i __lasx_xvsll_b (__m256i, __m256i);
19138 __m256i __lasx_xvsll_d (__m256i, __m256i);
19139 __m256i __lasx_xvsll_h (__m256i, __m256i);
19140 __m256i __lasx_xvslli_b (__m256i, imm0_7);
19141 __m256i __lasx_xvslli_d (__m256i, imm0_63);
19142 __m256i __lasx_xvslli_h (__m256i, imm0_15);
19143 __m256i __lasx_xvslli_w (__m256i, imm0_31);
19144 __m256i __lasx_xvsll_w (__m256i, __m256i);
19145 __m256i __lasx_xvsllwil_du_wu (__m256i, imm0_31);
19146 __m256i __lasx_xvsllwil_d_w (__m256i, imm0_31);
19147 __m256i __lasx_xvsllwil_h_b (__m256i, imm0_7);
19148 __m256i __lasx_xvsllwil_hu_bu (__m256i, imm0_7);
19149 __m256i __lasx_xvsllwil_w_h (__m256i, imm0_15);
19150 __m256i __lasx_xvsllwil_wu_hu (__m256i, imm0_15);
19151 __m256i __lasx_xvslt_b (__m256i, __m256i);
19152 __m256i __lasx_xvslt_bu (__m256i, __m256i);
19153 __m256i __lasx_xvslt_d (__m256i, __m256i);
19154 __m256i __lasx_xvslt_du (__m256i, __m256i);
19155 __m256i __lasx_xvslt_h (__m256i, __m256i);
19156 __m256i __lasx_xvslt_hu (__m256i, __m256i);
19157 __m256i __lasx_xvslti_b (__m256i, imm_n16_15);
19158 __m256i __lasx_xvslti_bu (__m256i, imm0_31);
19159 __m256i __lasx_xvslti_d (__m256i, imm_n16_15);
19160 __m256i __lasx_xvslti_du (__m256i, imm0_31);
19161 __m256i __lasx_xvslti_h (__m256i, imm_n16_15);
19162 __m256i __lasx_xvslti_hu (__m256i, imm0_31);
19163 __m256i __lasx_xvslti_w (__m256i, imm_n16_15);
19164 __m256i __lasx_xvslti_wu (__m256i, imm0_31);
19165 __m256i __lasx_xvslt_w (__m256i, __m256i);
19166 __m256i __lasx_xvslt_wu (__m256i, __m256i);
19167 __m256i __lasx_xvsra_b (__m256i, __m256i);
19168 __m256i __lasx_xvsra_d (__m256i, __m256i);
19169 __m256i __lasx_xvsra_h (__m256i, __m256i);
19170 __m256i __lasx_xvsrai_b (__m256i, imm0_7);
19171 __m256i __lasx_xvsrai_d (__m256i, imm0_63);
19172 __m256i __lasx_xvsrai_h (__m256i, imm0_15);
19173 __m256i __lasx_xvsrai_w (__m256i, imm0_31);
19174 __m256i __lasx_xvsran_b_h (__m256i, __m256i);
19175 __m256i __lasx_xvsran_h_w (__m256i, __m256i);
19176 __m256i __lasx_xvsrani_b_h (__m256i, __m256i, imm0_15);
19177 __m256i __lasx_xvsrani_d_q (__m256i, __m256i, imm0_127);
19178 __m256i __lasx_xvsrani_h_w (__m256i, __m256i, imm0_31);
19179 __m256i __lasx_xvsrani_w_d (__m256i, __m256i, imm0_63);
19180 __m256i __lasx_xvsran_w_d (__m256i, __m256i);
19181 __m256i __lasx_xvsrar_b (__m256i, __m256i);
19182 __m256i __lasx_xvsrar_d (__m256i, __m256i);
19183 __m256i __lasx_xvsrar_h (__m256i, __m256i);
19184 __m256i __lasx_xvsrari_b (__m256i, imm0_7);
19185 __m256i __lasx_xvsrari_d (__m256i, imm0_63);
19186 __m256i __lasx_xvsrari_h (__m256i, imm0_15);
19187 __m256i __lasx_xvsrari_w (__m256i, imm0_31);
19188 __m256i __lasx_xvsrarn_b_h (__m256i, __m256i);
19189 __m256i __lasx_xvsrarn_h_w (__m256i, __m256i);
19190 __m256i __lasx_xvsrarni_b_h (__m256i, __m256i, imm0_15);
19191 __m256i __lasx_xvsrarni_d_q (__m256i, __m256i, imm0_127);
19192 __m256i __lasx_xvsrarni_h_w (__m256i, __m256i, imm0_31);
19193 __m256i __lasx_xvsrarni_w_d (__m256i, __m256i, imm0_63);
19194 __m256i __lasx_xvsrarn_w_d (__m256i, __m256i);
19195 __m256i __lasx_xvsrar_w (__m256i, __m256i);
19196 __m256i __lasx_xvsra_w (__m256i, __m256i);
19197 __m256i __lasx_xvsrl_b (__m256i, __m256i);
19198 __m256i __lasx_xvsrl_d (__m256i, __m256i);
19199 __m256i __lasx_xvsrl_h (__m256i, __m256i);
19200 __m256i __lasx_xvsrli_b (__m256i, imm0_7);
19201 __m256i __lasx_xvsrli_d (__m256i, imm0_63);
19202 __m256i __lasx_xvsrli_h (__m256i, imm0_15);
19203 __m256i __lasx_xvsrli_w (__m256i, imm0_31);
19204 __m256i __lasx_xvsrln_b_h (__m256i, __m256i);
19205 __m256i __lasx_xvsrln_h_w (__m256i, __m256i);
19206 __m256i __lasx_xvsrlni_b_h (__m256i, __m256i, imm0_15);
19207 __m256i __lasx_xvsrlni_d_q (__m256i, __m256i, imm0_127);
19208 __m256i __lasx_xvsrlni_h_w (__m256i, __m256i, imm0_31);
19209 __m256i __lasx_xvsrlni_w_d (__m256i, __m256i, imm0_63);
19210 __m256i __lasx_xvsrln_w_d (__m256i, __m256i);
19211 __m256i __lasx_xvsrlr_b (__m256i, __m256i);
19212 __m256i __lasx_xvsrlr_d (__m256i, __m256i);
19213 __m256i __lasx_xvsrlr_h (__m256i, __m256i);
19214 __m256i __lasx_xvsrlri_b (__m256i, imm0_7);
19215 __m256i __lasx_xvsrlri_d (__m256i, imm0_63);
19216 __m256i __lasx_xvsrlri_h (__m256i, imm0_15);
19217 __m256i __lasx_xvsrlri_w (__m256i, imm0_31);
19218 __m256i __lasx_xvsrlrn_b_h (__m256i, __m256i);
19219 __m256i __lasx_xvsrlrn_h_w (__m256i, __m256i);
19220 __m256i __lasx_xvsrlrni_b_h (__m256i, __m256i, imm0_15);
19221 __m256i __lasx_xvsrlrni_d_q (__m256i, __m256i, imm0_127);
19222 __m256i __lasx_xvsrlrni_h_w (__m256i, __m256i, imm0_31);
19223 __m256i __lasx_xvsrlrni_w_d (__m256i, __m256i, imm0_63);
19224 __m256i __lasx_xvsrlrn_w_d (__m256i, __m256i);
19225 __m256i __lasx_xvsrlr_w (__m256i, __m256i);
19226 __m256i __lasx_xvsrl_w (__m256i, __m256i);
19227 __m256i __lasx_xvssran_b_h (__m256i, __m256i);
19228 __m256i __lasx_xvssran_bu_h (__m256i, __m256i);
19229 __m256i __lasx_xvssran_hu_w (__m256i, __m256i);
19230 __m256i __lasx_xvssran_h_w (__m256i, __m256i);
19231 __m256i __lasx_xvssrani_b_h (__m256i, __m256i, imm0_15);
19232 __m256i __lasx_xvssrani_bu_h (__m256i, __m256i, imm0_15);
19233 __m256i __lasx_xvssrani_d_q (__m256i, __m256i, imm0_127);
19234 __m256i __lasx_xvssrani_du_q (__m256i, __m256i, imm0_127);
19235 __m256i __lasx_xvssrani_hu_w (__m256i, __m256i, imm0_31);
19236 __m256i __lasx_xvssrani_h_w (__m256i, __m256i, imm0_31);
19237 __m256i __lasx_xvssrani_w_d (__m256i, __m256i, imm0_63);
19238 __m256i __lasx_xvssrani_wu_d (__m256i, __m256i, imm0_63);
19239 __m256i __lasx_xvssran_w_d (__m256i, __m256i);
19240 __m256i __lasx_xvssran_wu_d (__m256i, __m256i);
19241 __m256i __lasx_xvssrarn_b_h (__m256i, __m256i);
19242 __m256i __lasx_xvssrarn_bu_h (__m256i, __m256i);
19243 __m256i __lasx_xvssrarn_hu_w (__m256i, __m256i);
19244 __m256i __lasx_xvssrarn_h_w (__m256i, __m256i);
19245 __m256i __lasx_xvssrarni_b_h (__m256i, __m256i, imm0_15);
19246 __m256i __lasx_xvssrarni_bu_h (__m256i, __m256i, imm0_15);
19247 __m256i __lasx_xvssrarni_d_q (__m256i, __m256i, imm0_127);
19248 __m256i __lasx_xvssrarni_du_q (__m256i, __m256i, imm0_127);
19249 __m256i __lasx_xvssrarni_hu_w (__m256i, __m256i, imm0_31);
19250 __m256i __lasx_xvssrarni_h_w (__m256i, __m256i, imm0_31);
19251 __m256i __lasx_xvssrarni_w_d (__m256i, __m256i, imm0_63);
19252 __m256i __lasx_xvssrarni_wu_d (__m256i, __m256i, imm0_63);
19253 __m256i __lasx_xvssrarn_w_d (__m256i, __m256i);
19254 __m256i __lasx_xvssrarn_wu_d (__m256i, __m256i);
19255 __m256i __lasx_xvssrln_b_h (__m256i, __m256i);
19256 __m256i __lasx_xvssrln_bu_h (__m256i, __m256i);
19257 __m256i __lasx_xvssrln_hu_w (__m256i, __m256i);
19258 __m256i __lasx_xvssrln_h_w (__m256i, __m256i);
19259 __m256i __lasx_xvssrlni_b_h (__m256i, __m256i, imm0_15);
19260 __m256i __lasx_xvssrlni_bu_h (__m256i, __m256i, imm0_15);
19261 __m256i __lasx_xvssrlni_d_q (__m256i, __m256i, imm0_127);
19262 __m256i __lasx_xvssrlni_du_q (__m256i, __m256i, imm0_127);
19263 __m256i __lasx_xvssrlni_hu_w (__m256i, __m256i, imm0_31);
19264 __m256i __lasx_xvssrlni_h_w (__m256i, __m256i, imm0_31);
19265 __m256i __lasx_xvssrlni_w_d (__m256i, __m256i, imm0_63);
19266 __m256i __lasx_xvssrlni_wu_d (__m256i, __m256i, imm0_63);
19267 __m256i __lasx_xvssrln_w_d (__m256i, __m256i);
19268 __m256i __lasx_xvssrln_wu_d (__m256i, __m256i);
19269 __m256i __lasx_xvssrlrn_b_h (__m256i, __m256i);
19270 __m256i __lasx_xvssrlrn_bu_h (__m256i, __m256i);
19271 __m256i __lasx_xvssrlrn_hu_w (__m256i, __m256i);
19272 __m256i __lasx_xvssrlrn_h_w (__m256i, __m256i);
19273 __m256i __lasx_xvssrlrni_b_h (__m256i, __m256i, imm0_15);
19274 __m256i __lasx_xvssrlrni_bu_h (__m256i, __m256i, imm0_15);
19275 __m256i __lasx_xvssrlrni_d_q (__m256i, __m256i, imm0_127);
19276 __m256i __lasx_xvssrlrni_du_q (__m256i, __m256i, imm0_127);
19277 __m256i __lasx_xvssrlrni_hu_w (__m256i, __m256i, imm0_31);
19278 __m256i __lasx_xvssrlrni_h_w (__m256i, __m256i, imm0_31);
19279 __m256i __lasx_xvssrlrni_w_d (__m256i, __m256i, imm0_63);
19280 __m256i __lasx_xvssrlrni_wu_d (__m256i, __m256i, imm0_63);
19281 __m256i __lasx_xvssrlrn_w_d (__m256i, __m256i);
19282 __m256i __lasx_xvssrlrn_wu_d (__m256i, __m256i);
19283 __m256i __lasx_xvssub_b (__m256i, __m256i);
19284 __m256i __lasx_xvssub_bu (__m256i, __m256i);
19285 __m256i __lasx_xvssub_d (__m256i, __m256i);
19286 __m256i __lasx_xvssub_du (__m256i, __m256i);
19287 __m256i __lasx_xvssub_h (__m256i, __m256i);
19288 __m256i __lasx_xvssub_hu (__m256i, __m256i);
19289 __m256i __lasx_xvssub_w (__m256i, __m256i);
19290 __m256i __lasx_xvssub_wu (__m256i, __m256i);
19291 void __lasx_xvst (__m256i, void *, imm_n2048_2047);
19292 void __lasx_xvstelm_b (__m256i, void *, imm_n128_127, imm0_31);
19293 void __lasx_xvstelm_d (__m256i, void *, imm_n128_127, imm0_3);
19294 void __lasx_xvstelm_h (__m256i, void *, imm_n128_127, imm0_15);
19295 void __lasx_xvstelm_w (__m256i, void *, imm_n128_127, imm0_7);
19296 void __lasx_xvstx (__m256i, void *, long int);
19297 __m256i __lasx_xvsub_b (__m256i, __m256i);
19298 __m256i __lasx_xvsub_d (__m256i, __m256i);
19299 __m256i __lasx_xvsub_h (__m256i, __m256i);
19300 __m256i __lasx_xvsubi_bu (__m256i, imm0_31);
19301 __m256i __lasx_xvsubi_du (__m256i, imm0_31);
19302 __m256i __lasx_xvsubi_hu (__m256i, imm0_31);
19303 __m256i __lasx_xvsubi_wu (__m256i, imm0_31);
19304 __m256i __lasx_xvsub_q (__m256i, __m256i);
19305 __m256i __lasx_xvsub_w (__m256i, __m256i);
19306 __m256i __lasx_xvsubwev_d_w (__m256i, __m256i);
19307 __m256i __lasx_xvsubwev_d_wu (__m256i, __m256i);
19308 __m256i __lasx_xvsubwev_h_b (__m256i, __m256i);
19309 __m256i __lasx_xvsubwev_h_bu (__m256i, __m256i);
19310 __m256i __lasx_xvsubwev_q_d (__m256i, __m256i);
19311 __m256i __lasx_xvsubwev_q_du (__m256i, __m256i);
19312 __m256i __lasx_xvsubwev_w_h (__m256i, __m256i);
19313 __m256i __lasx_xvsubwev_w_hu (__m256i, __m256i);
19314 __m256i __lasx_xvsubwod_d_w (__m256i, __m256i);
19315 __m256i __lasx_xvsubwod_d_wu (__m256i, __m256i);
19316 __m256i __lasx_xvsubwod_h_b (__m256i, __m256i);
19317 __m256i __lasx_xvsubwod_h_bu (__m256i, __m256i);
19318 __m256i __lasx_xvsubwod_q_d (__m256i, __m256i);
19319 __m256i __lasx_xvsubwod_q_du (__m256i, __m256i);
19320 __m256i __lasx_xvsubwod_w_h (__m256i, __m256i);
19321 __m256i __lasx_xvsubwod_w_hu (__m256i, __m256i);
19322 __m256i __lasx_xvxori_b (__m256i, imm0_255);
19323 __m256i __lasx_xvxor_v (__m256i, __m256i);
19326 These instrisic functions are available by including @code{lasxintrin.h} and
19327 using @option{-mfrecipe} and @option{-mlasx}.
19329 __m256d __lasx_xvfrecipe_d (__m256d);
19330 __m256 __lasx_xvfrecipe_s (__m256);
19331 __m256d __lasx_xvfrsqrte_d (__m256d);
19332 __m256 __lasx_xvfrsqrte_s (__m256);
19335 @node MIPS DSP Built-in Functions
19336 @subsection MIPS DSP Built-in Functions
19338 The MIPS DSP Application-Specific Extension (ASE) includes new
19339 instructions that are designed to improve the performance of DSP and
19340 media applications. It provides instructions that operate on packed
19341 8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data.
19343 GCC supports MIPS DSP operations using both the generic
19344 vector extensions (@pxref{Vector Extensions}) and a collection of
19345 MIPS-specific built-in functions. Both kinds of support are
19346 enabled by the @option{-mdsp} command-line option.
19348 Revision 2 of the ASE was introduced in the second half of 2006.
19349 This revision adds extra instructions to the original ASE, but is
19350 otherwise backwards-compatible with it. You can select revision 2
19351 using the command-line option @option{-mdspr2}; this option implies
19354 The SCOUNT and POS bits of the DSP control register are global. The
19355 WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and
19356 POS bits. During optimization, the compiler does not delete these
19357 instructions and it does not delete calls to functions containing
19358 these instructions.
19360 At present, GCC only provides support for operations on 32-bit
19361 vectors. The vector type associated with 8-bit integer data is
19362 usually called @code{v4i8}, the vector type associated with Q7
19363 is usually called @code{v4q7}, the vector type associated with 16-bit
19364 integer data is usually called @code{v2i16}, and the vector type
19365 associated with Q15 is usually called @code{v2q15}. They can be
19366 defined in C as follows:
19369 typedef signed char v4i8 __attribute__ ((vector_size(4)));
19370 typedef signed char v4q7 __attribute__ ((vector_size(4)));
19371 typedef short v2i16 __attribute__ ((vector_size(4)));
19372 typedef short v2q15 __attribute__ ((vector_size(4)));
19375 @code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are
19376 initialized in the same way as aggregates. For example:
19379 v4i8 a = @{1, 2, 3, 4@};
19381 b = (v4i8) @{5, 6, 7, 8@};
19383 v2q15 c = @{0x0fcb, 0x3a75@};
19385 d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@};
19388 @emph{Note:} The CPU's endianness determines the order in which values
19389 are packed. On little-endian targets, the first value is the least
19390 significant and the last value is the most significant. The opposite
19391 order applies to big-endian targets. For example, the code above
19392 sets the lowest byte of @code{a} to @code{1} on little-endian targets
19393 and @code{4} on big-endian targets.
19395 @emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer
19396 representation. As shown in this example, the integer representation
19397 of a Q7 value can be obtained by multiplying the fractional value by
19398 @code{0x1.0p7}. The equivalent for Q15 values is to multiply by
19399 @code{0x1.0p15}. The equivalent for Q31 values is to multiply by
19402 The table below lists the @code{v4i8} and @code{v2q15} operations for which
19403 hardware support exists. @code{a} and @code{b} are @code{v4i8} values,
19404 and @code{c} and @code{d} are @code{v2q15} values.
19406 @multitable @columnfractions .50 .50
19407 @headitem C code @tab MIPS instruction
19408 @item @code{a + b} @tab @code{addu.qb}
19409 @item @code{c + d} @tab @code{addq.ph}
19410 @item @code{a - b} @tab @code{subu.qb}
19411 @item @code{c - d} @tab @code{subq.ph}
19414 The table below lists the @code{v2i16} operation for which
19415 hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are
19416 @code{v2i16} values.
19418 @multitable @columnfractions .50 .50
19419 @headitem C code @tab MIPS instruction
19420 @item @code{e * f} @tab @code{mul.ph}
19423 It is easier to describe the DSP built-in functions if we first define
19424 the following types:
19429 typedef unsigned int ui32;
19430 typedef long long a64;
19433 @code{q31} and @code{i32} are actually the same as @code{int}, but we
19434 use @code{q31} to indicate a Q31 fractional value and @code{i32} to
19435 indicate a 32-bit integer value. Similarly, @code{a64} is the same as
19436 @code{long long}, but we use @code{a64} to indicate values that are
19437 placed in one of the four DSP accumulators (@code{$ac0},
19438 @code{$ac1}, @code{$ac2} or @code{$ac3}).
19440 Also, some built-in functions prefer or require immediate numbers as
19441 parameters, because the corresponding DSP instructions accept both immediate
19442 numbers and register operands, or accept immediate numbers only. The
19443 immediate parameters are listed as follows.
19451 imm0_255: 0 to 255.
19452 imm_n32_31: -32 to 31.
19453 imm_n512_511: -512 to 511.
19456 The following built-in functions map directly to a particular MIPS DSP
19457 instruction. Please refer to the architecture specification
19458 for details on what each instruction does.
19461 v2q15 __builtin_mips_addq_ph (v2q15, v2q15);
19462 v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15);
19463 q31 __builtin_mips_addq_s_w (q31, q31);
19464 v4i8 __builtin_mips_addu_qb (v4i8, v4i8);
19465 v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8);
19466 v2q15 __builtin_mips_subq_ph (v2q15, v2q15);
19467 v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15);
19468 q31 __builtin_mips_subq_s_w (q31, q31);
19469 v4i8 __builtin_mips_subu_qb (v4i8, v4i8);
19470 v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8);
19471 i32 __builtin_mips_addsc (i32, i32);
19472 i32 __builtin_mips_addwc (i32, i32);
19473 i32 __builtin_mips_modsub (i32, i32);
19474 i32 __builtin_mips_raddu_w_qb (v4i8);
19475 v2q15 __builtin_mips_absq_s_ph (v2q15);
19476 q31 __builtin_mips_absq_s_w (q31);
19477 v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15);
19478 v2q15 __builtin_mips_precrq_ph_w (q31, q31);
19479 v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31);
19480 v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15);
19481 q31 __builtin_mips_preceq_w_phl (v2q15);
19482 q31 __builtin_mips_preceq_w_phr (v2q15);
19483 v2q15 __builtin_mips_precequ_ph_qbl (v4i8);
19484 v2q15 __builtin_mips_precequ_ph_qbr (v4i8);
19485 v2q15 __builtin_mips_precequ_ph_qbla (v4i8);
19486 v2q15 __builtin_mips_precequ_ph_qbra (v4i8);
19487 v2q15 __builtin_mips_preceu_ph_qbl (v4i8);
19488 v2q15 __builtin_mips_preceu_ph_qbr (v4i8);
19489 v2q15 __builtin_mips_preceu_ph_qbla (v4i8);
19490 v2q15 __builtin_mips_preceu_ph_qbra (v4i8);
19491 v4i8 __builtin_mips_shll_qb (v4i8, imm0_7);
19492 v4i8 __builtin_mips_shll_qb (v4i8, i32);
19493 v2q15 __builtin_mips_shll_ph (v2q15, imm0_15);
19494 v2q15 __builtin_mips_shll_ph (v2q15, i32);
19495 v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15);
19496 v2q15 __builtin_mips_shll_s_ph (v2q15, i32);
19497 q31 __builtin_mips_shll_s_w (q31, imm0_31);
19498 q31 __builtin_mips_shll_s_w (q31, i32);
19499 v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7);
19500 v4i8 __builtin_mips_shrl_qb (v4i8, i32);
19501 v2q15 __builtin_mips_shra_ph (v2q15, imm0_15);
19502 v2q15 __builtin_mips_shra_ph (v2q15, i32);
19503 v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15);
19504 v2q15 __builtin_mips_shra_r_ph (v2q15, i32);
19505 q31 __builtin_mips_shra_r_w (q31, imm0_31);
19506 q31 __builtin_mips_shra_r_w (q31, i32);
19507 v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15);
19508 v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15);
19509 v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15);
19510 q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15);
19511 q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15);
19512 a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8);
19513 a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8);
19514 a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8);
19515 a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8);
19516 a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15);
19517 a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31);
19518 a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15);
19519 a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31);
19520 a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15);
19521 a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15);
19522 a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15);
19523 a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15);
19524 a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15);
19525 i32 __builtin_mips_bitrev (i32);
19526 i32 __builtin_mips_insv (i32, i32);
19527 v4i8 __builtin_mips_repl_qb (imm0_255);
19528 v4i8 __builtin_mips_repl_qb (i32);
19529 v2q15 __builtin_mips_repl_ph (imm_n512_511);
19530 v2q15 __builtin_mips_repl_ph (i32);
19531 void __builtin_mips_cmpu_eq_qb (v4i8, v4i8);
19532 void __builtin_mips_cmpu_lt_qb (v4i8, v4i8);
19533 void __builtin_mips_cmpu_le_qb (v4i8, v4i8);
19534 i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8);
19535 i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8);
19536 i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8);
19537 void __builtin_mips_cmp_eq_ph (v2q15, v2q15);
19538 void __builtin_mips_cmp_lt_ph (v2q15, v2q15);
19539 void __builtin_mips_cmp_le_ph (v2q15, v2q15);
19540 v4i8 __builtin_mips_pick_qb (v4i8, v4i8);
19541 v2q15 __builtin_mips_pick_ph (v2q15, v2q15);
19542 v2q15 __builtin_mips_packrl_ph (v2q15, v2q15);
19543 i32 __builtin_mips_extr_w (a64, imm0_31);
19544 i32 __builtin_mips_extr_w (a64, i32);
19545 i32 __builtin_mips_extr_r_w (a64, imm0_31);
19546 i32 __builtin_mips_extr_s_h (a64, i32);
19547 i32 __builtin_mips_extr_rs_w (a64, imm0_31);
19548 i32 __builtin_mips_extr_rs_w (a64, i32);
19549 i32 __builtin_mips_extr_s_h (a64, imm0_31);
19550 i32 __builtin_mips_extr_r_w (a64, i32);
19551 i32 __builtin_mips_extp (a64, imm0_31);
19552 i32 __builtin_mips_extp (a64, i32);
19553 i32 __builtin_mips_extpdp (a64, imm0_31);
19554 i32 __builtin_mips_extpdp (a64, i32);
19555 a64 __builtin_mips_shilo (a64, imm_n32_31);
19556 a64 __builtin_mips_shilo (a64, i32);
19557 a64 __builtin_mips_mthlip (a64, i32);
19558 void __builtin_mips_wrdsp (i32, imm0_63);
19559 i32 __builtin_mips_rddsp (imm0_63);
19560 i32 __builtin_mips_lbux (void *, i32);
19561 i32 __builtin_mips_lhx (void *, i32);
19562 i32 __builtin_mips_lwx (void *, i32);
19563 a64 __builtin_mips_ldx (void *, i32); /* MIPS64 only */
19564 i32 __builtin_mips_bposge32 (void);
19565 a64 __builtin_mips_madd (a64, i32, i32);
19566 a64 __builtin_mips_maddu (a64, ui32, ui32);
19567 a64 __builtin_mips_msub (a64, i32, i32);
19568 a64 __builtin_mips_msubu (a64, ui32, ui32);
19569 a64 __builtin_mips_mult (i32, i32);
19570 a64 __builtin_mips_multu (ui32, ui32);
19573 The following built-in functions map directly to a particular MIPS DSP REV 2
19574 instruction. Please refer to the architecture specification
19575 for details on what each instruction does.
19578 v4q7 __builtin_mips_absq_s_qb (v4q7);
19579 v2i16 __builtin_mips_addu_ph (v2i16, v2i16);
19580 v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16);
19581 v4i8 __builtin_mips_adduh_qb (v4i8, v4i8);
19582 v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8);
19583 i32 __builtin_mips_append (i32, i32, imm0_31);
19584 i32 __builtin_mips_balign (i32, i32, imm0_3);
19585 i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8);
19586 i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8);
19587 i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8);
19588 a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16);
19589 a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16);
19590 v2i16 __builtin_mips_mul_ph (v2i16, v2i16);
19591 v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16);
19592 q31 __builtin_mips_mulq_rs_w (q31, q31);
19593 v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15);
19594 q31 __builtin_mips_mulq_s_w (q31, q31);
19595 a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16);
19596 v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16);
19597 v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31);
19598 v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31);
19599 i32 __builtin_mips_prepend (i32, i32, imm0_31);
19600 v4i8 __builtin_mips_shra_qb (v4i8, imm0_7);
19601 v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7);
19602 v4i8 __builtin_mips_shra_qb (v4i8, i32);
19603 v4i8 __builtin_mips_shra_r_qb (v4i8, i32);
19604 v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15);
19605 v2i16 __builtin_mips_shrl_ph (v2i16, i32);
19606 v2i16 __builtin_mips_subu_ph (v2i16, v2i16);
19607 v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16);
19608 v4i8 __builtin_mips_subuh_qb (v4i8, v4i8);
19609 v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8);
19610 v2q15 __builtin_mips_addqh_ph (v2q15, v2q15);
19611 v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15);
19612 q31 __builtin_mips_addqh_w (q31, q31);
19613 q31 __builtin_mips_addqh_r_w (q31, q31);
19614 v2q15 __builtin_mips_subqh_ph (v2q15, v2q15);
19615 v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15);
19616 q31 __builtin_mips_subqh_w (q31, q31);
19617 q31 __builtin_mips_subqh_r_w (q31, q31);
19618 a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16);
19619 a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16);
19620 a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15);
19621 a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15);
19622 a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15);
19623 a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15);
19627 @node MIPS Paired-Single Support
19628 @subsection MIPS Paired-Single Support
19630 The MIPS64 architecture includes a number of instructions that
19631 operate on pairs of single-precision floating-point values.
19632 Each pair is packed into a 64-bit floating-point register,
19633 with one element being designated the ``upper half'' and
19634 the other being designated the ``lower half''.
19636 GCC supports paired-single operations using both the generic
19637 vector extensions (@pxref{Vector Extensions}) and a collection of
19638 MIPS-specific built-in functions. Both kinds of support are
19639 enabled by the @option{-mpaired-single} command-line option.
19641 The vector type associated with paired-single values is usually
19642 called @code{v2sf}. It can be defined in C as follows:
19645 typedef float v2sf __attribute__ ((vector_size (8)));
19648 @code{v2sf} values are initialized in the same way as aggregates.
19652 v2sf a = @{1.5, 9.1@};
19655 b = (v2sf) @{e, f@};
19658 @emph{Note:} The CPU's endianness determines which value is stored in
19659 the upper half of a register and which value is stored in the lower half.
19660 On little-endian targets, the first value is the lower one and the second
19661 value is the upper one. The opposite order applies to big-endian targets.
19662 For example, the code above sets the lower half of @code{a} to
19663 @code{1.5} on little-endian targets and @code{9.1} on big-endian targets.
19665 @node MIPS Loongson Built-in Functions
19666 @subsection MIPS Loongson Built-in Functions
19668 GCC provides intrinsics to access the SIMD instructions provided by the
19669 ST Microelectronics Loongson-2E and -2F processors. These intrinsics,
19670 available after inclusion of the @code{loongson.h} header file,
19671 operate on the following 64-bit vector types:
19674 @item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers;
19675 @item @code{uint16x4_t}, a vector of four unsigned 16-bit integers;
19676 @item @code{uint32x2_t}, a vector of two unsigned 32-bit integers;
19677 @item @code{int8x8_t}, a vector of eight signed 8-bit integers;
19678 @item @code{int16x4_t}, a vector of four signed 16-bit integers;
19679 @item @code{int32x2_t}, a vector of two signed 32-bit integers.
19682 The intrinsics provided are listed below; each is named after the
19683 machine instruction to which it corresponds, with suffixes added as
19684 appropriate to distinguish intrinsics that expand to the same machine
19685 instruction yet have different argument types. Refer to the architecture
19686 documentation for a description of the functionality of each
19690 int16x4_t packsswh (int32x2_t s, int32x2_t t);
19691 int8x8_t packsshb (int16x4_t s, int16x4_t t);
19692 uint8x8_t packushb (uint16x4_t s, uint16x4_t t);
19693 uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t);
19694 uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t);
19695 uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t);
19696 int32x2_t paddw_s (int32x2_t s, int32x2_t t);
19697 int16x4_t paddh_s (int16x4_t s, int16x4_t t);
19698 int8x8_t paddb_s (int8x8_t s, int8x8_t t);
19699 uint64_t paddd_u (uint64_t s, uint64_t t);
19700 int64_t paddd_s (int64_t s, int64_t t);
19701 int16x4_t paddsh (int16x4_t s, int16x4_t t);
19702 int8x8_t paddsb (int8x8_t s, int8x8_t t);
19703 uint16x4_t paddush (uint16x4_t s, uint16x4_t t);
19704 uint8x8_t paddusb (uint8x8_t s, uint8x8_t t);
19705 uint64_t pandn_ud (uint64_t s, uint64_t t);
19706 uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t);
19707 uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t);
19708 uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t);
19709 int64_t pandn_sd (int64_t s, int64_t t);
19710 int32x2_t pandn_sw (int32x2_t s, int32x2_t t);
19711 int16x4_t pandn_sh (int16x4_t s, int16x4_t t);
19712 int8x8_t pandn_sb (int8x8_t s, int8x8_t t);
19713 uint16x4_t pavgh (uint16x4_t s, uint16x4_t t);
19714 uint8x8_t pavgb (uint8x8_t s, uint8x8_t t);
19715 uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t);
19716 uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t);
19717 uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t);
19718 int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t);
19719 int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t);
19720 int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t);
19721 uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t);
19722 uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t);
19723 uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t);
19724 int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t);
19725 int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t);
19726 int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t);
19727 uint16x4_t pextrh_u (uint16x4_t s, int field);
19728 int16x4_t pextrh_s (int16x4_t s, int field);
19729 uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t);
19730 uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t);
19731 uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t);
19732 uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t);
19733 int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t);
19734 int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t);
19735 int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t);
19736 int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t);
19737 int32x2_t pmaddhw (int16x4_t s, int16x4_t t);
19738 int16x4_t pmaxsh (int16x4_t s, int16x4_t t);
19739 uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t);
19740 int16x4_t pminsh (int16x4_t s, int16x4_t t);
19741 uint8x8_t pminub (uint8x8_t s, uint8x8_t t);
19742 uint8x8_t pmovmskb_u (uint8x8_t s);
19743 int8x8_t pmovmskb_s (int8x8_t s);
19744 uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t);
19745 int16x4_t pmulhh (int16x4_t s, int16x4_t t);
19746 int16x4_t pmullh (int16x4_t s, int16x4_t t);
19747 int64_t pmuluw (uint32x2_t s, uint32x2_t t);
19748 uint8x8_t pasubub (uint8x8_t s, uint8x8_t t);
19749 uint16x4_t biadd (uint8x8_t s);
19750 uint16x4_t psadbh (uint8x8_t s, uint8x8_t t);
19751 uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order);
19752 int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order);
19753 uint16x4_t psllh_u (uint16x4_t s, uint8_t amount);
19754 int16x4_t psllh_s (int16x4_t s, uint8_t amount);
19755 uint32x2_t psllw_u (uint32x2_t s, uint8_t amount);
19756 int32x2_t psllw_s (int32x2_t s, uint8_t amount);
19757 uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount);
19758 int16x4_t psrlh_s (int16x4_t s, uint8_t amount);
19759 uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount);
19760 int32x2_t psrlw_s (int32x2_t s, uint8_t amount);
19761 uint16x4_t psrah_u (uint16x4_t s, uint8_t amount);
19762 int16x4_t psrah_s (int16x4_t s, uint8_t amount);
19763 uint32x2_t psraw_u (uint32x2_t s, uint8_t amount);
19764 int32x2_t psraw_s (int32x2_t s, uint8_t amount);
19765 uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t);
19766 uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t);
19767 uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t);
19768 int32x2_t psubw_s (int32x2_t s, int32x2_t t);
19769 int16x4_t psubh_s (int16x4_t s, int16x4_t t);
19770 int8x8_t psubb_s (int8x8_t s, int8x8_t t);
19771 uint64_t psubd_u (uint64_t s, uint64_t t);
19772 int64_t psubd_s (int64_t s, int64_t t);
19773 int16x4_t psubsh (int16x4_t s, int16x4_t t);
19774 int8x8_t psubsb (int8x8_t s, int8x8_t t);
19775 uint16x4_t psubush (uint16x4_t s, uint16x4_t t);
19776 uint8x8_t psubusb (uint8x8_t s, uint8x8_t t);
19777 uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t);
19778 uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t);
19779 uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t);
19780 int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t);
19781 int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t);
19782 int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t);
19783 uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t);
19784 uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t);
19785 uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t);
19786 int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t);
19787 int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t);
19788 int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t);
19792 * Paired-Single Arithmetic::
19793 * Paired-Single Built-in Functions::
19794 * MIPS-3D Built-in Functions::
19797 @node Paired-Single Arithmetic
19798 @subsubsection Paired-Single Arithmetic
19800 The table below lists the @code{v2sf} operations for which hardware
19801 support exists. @code{a}, @code{b} and @code{c} are @code{v2sf}
19802 values and @code{x} is an integral value.
19804 @multitable @columnfractions .50 .50
19805 @headitem C code @tab MIPS instruction
19806 @item @code{a + b} @tab @code{add.ps}
19807 @item @code{a - b} @tab @code{sub.ps}
19808 @item @code{-a} @tab @code{neg.ps}
19809 @item @code{a * b} @tab @code{mul.ps}
19810 @item @code{a * b + c} @tab @code{madd.ps}
19811 @item @code{a * b - c} @tab @code{msub.ps}
19812 @item @code{-(a * b + c)} @tab @code{nmadd.ps}
19813 @item @code{-(a * b - c)} @tab @code{nmsub.ps}
19814 @item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps}
19817 Note that the multiply-accumulate instructions can be disabled
19818 using the command-line option @code{-mno-fused-madd}.
19820 @node Paired-Single Built-in Functions
19821 @subsubsection Paired-Single Built-in Functions
19823 The following paired-single functions map directly to a particular
19824 MIPS instruction. Please refer to the architecture specification
19825 for details on what each instruction does.
19828 @item v2sf __builtin_mips_pll_ps (v2sf, v2sf)
19829 Pair lower lower (@code{pll.ps}).
19831 @item v2sf __builtin_mips_pul_ps (v2sf, v2sf)
19832 Pair upper lower (@code{pul.ps}).
19834 @item v2sf __builtin_mips_plu_ps (v2sf, v2sf)
19835 Pair lower upper (@code{plu.ps}).
19837 @item v2sf __builtin_mips_puu_ps (v2sf, v2sf)
19838 Pair upper upper (@code{puu.ps}).
19840 @item v2sf __builtin_mips_cvt_ps_s (float, float)
19841 Convert pair to paired single (@code{cvt.ps.s}).
19843 @item float __builtin_mips_cvt_s_pl (v2sf)
19844 Convert pair lower to single (@code{cvt.s.pl}).
19846 @item float __builtin_mips_cvt_s_pu (v2sf)
19847 Convert pair upper to single (@code{cvt.s.pu}).
19849 @item v2sf __builtin_mips_abs_ps (v2sf)
19850 Absolute value (@code{abs.ps}).
19852 @item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int)
19853 Align variable (@code{alnv.ps}).
19855 @emph{Note:} The value of the third parameter must be 0 or 4
19856 modulo 8, otherwise the result is unpredictable. Please read the
19857 instruction description for details.
19860 The following multi-instruction functions are also available.
19861 In each case, @var{cond} can be any of the 16 floating-point conditions:
19862 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
19863 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl},
19864 @code{lt}, @code{nge}, @code{le} or @code{ngt}.
19867 @item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
19868 @itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
19869 Conditional move based on floating-point comparison (@code{c.@var{cond}.ps},
19870 @code{movt.ps}/@code{movf.ps}).
19872 The @code{movt} functions return the value @var{x} computed by:
19875 c.@var{cond}.ps @var{cc},@var{a},@var{b}
19876 mov.ps @var{x},@var{c}
19877 movt.ps @var{x},@var{d},@var{cc}
19880 The @code{movf} functions are similar but use @code{movf.ps} instead
19883 @item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
19884 @itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
19885 Comparison of two paired-single values (@code{c.@var{cond}.ps},
19886 @code{bc1t}/@code{bc1f}).
19888 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
19889 and return either the upper or lower half of the result. For example:
19893 if (__builtin_mips_upper_c_eq_ps (a, b))
19894 upper_halves_are_equal ();
19896 upper_halves_are_unequal ();
19898 if (__builtin_mips_lower_c_eq_ps (a, b))
19899 lower_halves_are_equal ();
19901 lower_halves_are_unequal ();
19905 @node MIPS-3D Built-in Functions
19906 @subsubsection MIPS-3D Built-in Functions
19908 The MIPS-3D Application-Specific Extension (ASE) includes additional
19909 paired-single instructions that are designed to improve the performance
19910 of 3D graphics operations. Support for these instructions is controlled
19911 by the @option{-mips3d} command-line option.
19913 The functions listed below map directly to a particular MIPS-3D
19914 instruction. Please refer to the architecture specification for
19915 more details on what each instruction does.
19918 @item v2sf __builtin_mips_addr_ps (v2sf, v2sf)
19919 Reduction add (@code{addr.ps}).
19921 @item v2sf __builtin_mips_mulr_ps (v2sf, v2sf)
19922 Reduction multiply (@code{mulr.ps}).
19924 @item v2sf __builtin_mips_cvt_pw_ps (v2sf)
19925 Convert paired single to paired word (@code{cvt.pw.ps}).
19927 @item v2sf __builtin_mips_cvt_ps_pw (v2sf)
19928 Convert paired word to paired single (@code{cvt.ps.pw}).
19930 @item float __builtin_mips_recip1_s (float)
19931 @itemx double __builtin_mips_recip1_d (double)
19932 @itemx v2sf __builtin_mips_recip1_ps (v2sf)
19933 Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}).
19935 @item float __builtin_mips_recip2_s (float, float)
19936 @itemx double __builtin_mips_recip2_d (double, double)
19937 @itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf)
19938 Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}).
19940 @item float __builtin_mips_rsqrt1_s (float)
19941 @itemx double __builtin_mips_rsqrt1_d (double)
19942 @itemx v2sf __builtin_mips_rsqrt1_ps (v2sf)
19943 Reduced-precision reciprocal square root (sequence step 1)
19944 (@code{rsqrt1.@var{fmt}}).
19946 @item float __builtin_mips_rsqrt2_s (float, float)
19947 @itemx double __builtin_mips_rsqrt2_d (double, double)
19948 @itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf)
19949 Reduced-precision reciprocal square root (sequence step 2)
19950 (@code{rsqrt2.@var{fmt}}).
19953 The following multi-instruction functions are also available.
19954 In each case, @var{cond} can be any of the 16 floating-point conditions:
19955 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
19956 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq},
19957 @code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}.
19960 @item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b})
19961 @itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b})
19962 Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}},
19963 @code{bc1t}/@code{bc1f}).
19965 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s}
19966 or @code{cabs.@var{cond}.d} and return the result as a boolean value.
19971 if (__builtin_mips_cabs_eq_s (a, b))
19977 @item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
19978 @itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
19979 Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps},
19980 @code{bc1t}/@code{bc1f}).
19982 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps}
19983 and return either the upper or lower half of the result. For example:
19987 if (__builtin_mips_upper_cabs_eq_ps (a, b))
19988 upper_halves_are_equal ();
19990 upper_halves_are_unequal ();
19992 if (__builtin_mips_lower_cabs_eq_ps (a, b))
19993 lower_halves_are_equal ();
19995 lower_halves_are_unequal ();
19998 @item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
19999 @itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
20000 Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps},
20001 @code{movt.ps}/@code{movf.ps}).
20003 The @code{movt} functions return the value @var{x} computed by:
20006 cabs.@var{cond}.ps @var{cc},@var{a},@var{b}
20007 mov.ps @var{x},@var{c}
20008 movt.ps @var{x},@var{d},@var{cc}
20011 The @code{movf} functions are similar but use @code{movf.ps} instead
20014 @item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
20015 @itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
20016 @itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
20017 @itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
20018 Comparison of two paired-single values
20019 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
20020 @code{bc1any2t}/@code{bc1any2f}).
20022 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
20023 or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either
20024 result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}.
20029 if (__builtin_mips_any_c_eq_ps (a, b))
20034 if (__builtin_mips_all_c_eq_ps (a, b))
20040 @item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
20041 @itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
20042 @itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
20043 @itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
20044 Comparison of four paired-single values
20045 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
20046 @code{bc1any4t}/@code{bc1any4f}).
20048 These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps}
20049 to compare @var{a} with @var{b} and to compare @var{c} with @var{d}.
20050 The @code{any} forms return @code{true} if any of the four results are @code{true}
20051 and the @code{all} forms return @code{true} if all four results are @code{true}.
20056 if (__builtin_mips_any_c_eq_4s (a, b, c, d))
20061 if (__builtin_mips_all_c_eq_4s (a, b, c, d))
20068 @node MIPS SIMD Architecture (MSA) Support
20069 @subsection MIPS SIMD Architecture (MSA) Support
20072 * MIPS SIMD Architecture Built-in Functions::
20075 GCC provides intrinsics to access the SIMD instructions provided by the
20076 MSA MIPS SIMD Architecture. The interface is made available by including
20077 @code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}.
20078 For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic,
20081 MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and
20082 64-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point
20083 data elements. The following vectors typedefs are included in @code{msa.h}:
20085 @item @code{v16i8}, a vector of sixteen signed 8-bit integers;
20086 @item @code{v16u8}, a vector of sixteen unsigned 8-bit integers;
20087 @item @code{v8i16}, a vector of eight signed 16-bit integers;
20088 @item @code{v8u16}, a vector of eight unsigned 16-bit integers;
20089 @item @code{v4i32}, a vector of four signed 32-bit integers;
20090 @item @code{v4u32}, a vector of four unsigned 32-bit integers;
20091 @item @code{v2i64}, a vector of two signed 64-bit integers;
20092 @item @code{v2u64}, a vector of two unsigned 64-bit integers;
20093 @item @code{v4f32}, a vector of four 32-bit floats;
20094 @item @code{v2f64}, a vector of two 64-bit doubles.
20097 Instructions and corresponding built-ins may have additional restrictions and/or
20098 input/output values manipulated:
20100 @item @code{imm0_1}, an integer literal in range 0 to 1;
20101 @item @code{imm0_3}, an integer literal in range 0 to 3;
20102 @item @code{imm0_7}, an integer literal in range 0 to 7;
20103 @item @code{imm0_15}, an integer literal in range 0 to 15;
20104 @item @code{imm0_31}, an integer literal in range 0 to 31;
20105 @item @code{imm0_63}, an integer literal in range 0 to 63;
20106 @item @code{imm0_255}, an integer literal in range 0 to 255;
20107 @item @code{imm_n16_15}, an integer literal in range -16 to 15;
20108 @item @code{imm_n512_511}, an integer literal in range -512 to 511;
20109 @item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left
20110 shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022;
20111 @item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left
20112 shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044;
20113 @item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left
20114 shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088;
20115 @item @code{imm1_4}, an integer literal in range 1 to 4;
20116 @item @code{i32, i64, u32, u64, f32, f64}, defined as follows:
20122 #if __LONG_MAX__ == __LONG_LONG_MAX__
20125 typedef long long i64;
20128 typedef unsigned int u32;
20129 #if __LONG_MAX__ == __LONG_LONG_MAX__
20130 typedef unsigned long u64;
20132 typedef unsigned long long u64;
20135 typedef double f64;
20140 @node MIPS SIMD Architecture Built-in Functions
20141 @subsubsection MIPS SIMD Architecture Built-in Functions
20143 The intrinsics provided are listed below; each is named after the
20144 machine instruction.
20147 v16i8 __builtin_msa_add_a_b (v16i8, v16i8);
20148 v8i16 __builtin_msa_add_a_h (v8i16, v8i16);
20149 v4i32 __builtin_msa_add_a_w (v4i32, v4i32);
20150 v2i64 __builtin_msa_add_a_d (v2i64, v2i64);
20152 v16i8 __builtin_msa_adds_a_b (v16i8, v16i8);
20153 v8i16 __builtin_msa_adds_a_h (v8i16, v8i16);
20154 v4i32 __builtin_msa_adds_a_w (v4i32, v4i32);
20155 v2i64 __builtin_msa_adds_a_d (v2i64, v2i64);
20157 v16i8 __builtin_msa_adds_s_b (v16i8, v16i8);
20158 v8i16 __builtin_msa_adds_s_h (v8i16, v8i16);
20159 v4i32 __builtin_msa_adds_s_w (v4i32, v4i32);
20160 v2i64 __builtin_msa_adds_s_d (v2i64, v2i64);
20162 v16u8 __builtin_msa_adds_u_b (v16u8, v16u8);
20163 v8u16 __builtin_msa_adds_u_h (v8u16, v8u16);
20164 v4u32 __builtin_msa_adds_u_w (v4u32, v4u32);
20165 v2u64 __builtin_msa_adds_u_d (v2u64, v2u64);
20167 v16i8 __builtin_msa_addv_b (v16i8, v16i8);
20168 v8i16 __builtin_msa_addv_h (v8i16, v8i16);
20169 v4i32 __builtin_msa_addv_w (v4i32, v4i32);
20170 v2i64 __builtin_msa_addv_d (v2i64, v2i64);
20172 v16i8 __builtin_msa_addvi_b (v16i8, imm0_31);
20173 v8i16 __builtin_msa_addvi_h (v8i16, imm0_31);
20174 v4i32 __builtin_msa_addvi_w (v4i32, imm0_31);
20175 v2i64 __builtin_msa_addvi_d (v2i64, imm0_31);
20177 v16u8 __builtin_msa_and_v (v16u8, v16u8);
20179 v16u8 __builtin_msa_andi_b (v16u8, imm0_255);
20181 v16i8 __builtin_msa_asub_s_b (v16i8, v16i8);
20182 v8i16 __builtin_msa_asub_s_h (v8i16, v8i16);
20183 v4i32 __builtin_msa_asub_s_w (v4i32, v4i32);
20184 v2i64 __builtin_msa_asub_s_d (v2i64, v2i64);
20186 v16u8 __builtin_msa_asub_u_b (v16u8, v16u8);
20187 v8u16 __builtin_msa_asub_u_h (v8u16, v8u16);
20188 v4u32 __builtin_msa_asub_u_w (v4u32, v4u32);
20189 v2u64 __builtin_msa_asub_u_d (v2u64, v2u64);
20191 v16i8 __builtin_msa_ave_s_b (v16i8, v16i8);
20192 v8i16 __builtin_msa_ave_s_h (v8i16, v8i16);
20193 v4i32 __builtin_msa_ave_s_w (v4i32, v4i32);
20194 v2i64 __builtin_msa_ave_s_d (v2i64, v2i64);
20196 v16u8 __builtin_msa_ave_u_b (v16u8, v16u8);
20197 v8u16 __builtin_msa_ave_u_h (v8u16, v8u16);
20198 v4u32 __builtin_msa_ave_u_w (v4u32, v4u32);
20199 v2u64 __builtin_msa_ave_u_d (v2u64, v2u64);
20201 v16i8 __builtin_msa_aver_s_b (v16i8, v16i8);
20202 v8i16 __builtin_msa_aver_s_h (v8i16, v8i16);
20203 v4i32 __builtin_msa_aver_s_w (v4i32, v4i32);
20204 v2i64 __builtin_msa_aver_s_d (v2i64, v2i64);
20206 v16u8 __builtin_msa_aver_u_b (v16u8, v16u8);
20207 v8u16 __builtin_msa_aver_u_h (v8u16, v8u16);
20208 v4u32 __builtin_msa_aver_u_w (v4u32, v4u32);
20209 v2u64 __builtin_msa_aver_u_d (v2u64, v2u64);
20211 v16u8 __builtin_msa_bclr_b (v16u8, v16u8);
20212 v8u16 __builtin_msa_bclr_h (v8u16, v8u16);
20213 v4u32 __builtin_msa_bclr_w (v4u32, v4u32);
20214 v2u64 __builtin_msa_bclr_d (v2u64, v2u64);
20216 v16u8 __builtin_msa_bclri_b (v16u8, imm0_7);
20217 v8u16 __builtin_msa_bclri_h (v8u16, imm0_15);
20218 v4u32 __builtin_msa_bclri_w (v4u32, imm0_31);
20219 v2u64 __builtin_msa_bclri_d (v2u64, imm0_63);
20221 v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8);
20222 v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16);
20223 v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32);
20224 v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64);
20226 v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7);
20227 v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15);
20228 v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31);
20229 v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63);
20231 v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8);
20232 v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16);
20233 v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32);
20234 v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64);
20236 v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7);
20237 v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15);
20238 v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31);
20239 v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63);
20241 v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8);
20243 v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255);
20245 v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8);
20247 v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255);
20249 v16u8 __builtin_msa_bneg_b (v16u8, v16u8);
20250 v8u16 __builtin_msa_bneg_h (v8u16, v8u16);
20251 v4u32 __builtin_msa_bneg_w (v4u32, v4u32);
20252 v2u64 __builtin_msa_bneg_d (v2u64, v2u64);
20254 v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7);
20255 v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15);
20256 v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31);
20257 v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63);
20259 i32 __builtin_msa_bnz_b (v16u8);
20260 i32 __builtin_msa_bnz_h (v8u16);
20261 i32 __builtin_msa_bnz_w (v4u32);
20262 i32 __builtin_msa_bnz_d (v2u64);
20264 i32 __builtin_msa_bnz_v (v16u8);
20266 v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8);
20268 v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255);
20270 v16u8 __builtin_msa_bset_b (v16u8, v16u8);
20271 v8u16 __builtin_msa_bset_h (v8u16, v8u16);
20272 v4u32 __builtin_msa_bset_w (v4u32, v4u32);
20273 v2u64 __builtin_msa_bset_d (v2u64, v2u64);
20275 v16u8 __builtin_msa_bseti_b (v16u8, imm0_7);
20276 v8u16 __builtin_msa_bseti_h (v8u16, imm0_15);
20277 v4u32 __builtin_msa_bseti_w (v4u32, imm0_31);
20278 v2u64 __builtin_msa_bseti_d (v2u64, imm0_63);
20280 i32 __builtin_msa_bz_b (v16u8);
20281 i32 __builtin_msa_bz_h (v8u16);
20282 i32 __builtin_msa_bz_w (v4u32);
20283 i32 __builtin_msa_bz_d (v2u64);
20285 i32 __builtin_msa_bz_v (v16u8);
20287 v16i8 __builtin_msa_ceq_b (v16i8, v16i8);
20288 v8i16 __builtin_msa_ceq_h (v8i16, v8i16);
20289 v4i32 __builtin_msa_ceq_w (v4i32, v4i32);
20290 v2i64 __builtin_msa_ceq_d (v2i64, v2i64);
20292 v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15);
20293 v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15);
20294 v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15);
20295 v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15);
20297 i32 __builtin_msa_cfcmsa (imm0_31);
20299 v16i8 __builtin_msa_cle_s_b (v16i8, v16i8);
20300 v8i16 __builtin_msa_cle_s_h (v8i16, v8i16);
20301 v4i32 __builtin_msa_cle_s_w (v4i32, v4i32);
20302 v2i64 __builtin_msa_cle_s_d (v2i64, v2i64);
20304 v16i8 __builtin_msa_cle_u_b (v16u8, v16u8);
20305 v8i16 __builtin_msa_cle_u_h (v8u16, v8u16);
20306 v4i32 __builtin_msa_cle_u_w (v4u32, v4u32);
20307 v2i64 __builtin_msa_cle_u_d (v2u64, v2u64);
20309 v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15);
20310 v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15);
20311 v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15);
20312 v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15);
20314 v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31);
20315 v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31);
20316 v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31);
20317 v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31);
20319 v16i8 __builtin_msa_clt_s_b (v16i8, v16i8);
20320 v8i16 __builtin_msa_clt_s_h (v8i16, v8i16);
20321 v4i32 __builtin_msa_clt_s_w (v4i32, v4i32);
20322 v2i64 __builtin_msa_clt_s_d (v2i64, v2i64);
20324 v16i8 __builtin_msa_clt_u_b (v16u8, v16u8);
20325 v8i16 __builtin_msa_clt_u_h (v8u16, v8u16);
20326 v4i32 __builtin_msa_clt_u_w (v4u32, v4u32);
20327 v2i64 __builtin_msa_clt_u_d (v2u64, v2u64);
20329 v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15);
20330 v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15);
20331 v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15);
20332 v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15);
20334 v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31);
20335 v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31);
20336 v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31);
20337 v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31);
20339 i32 __builtin_msa_copy_s_b (v16i8, imm0_15);
20340 i32 __builtin_msa_copy_s_h (v8i16, imm0_7);
20341 i32 __builtin_msa_copy_s_w (v4i32, imm0_3);
20342 i64 __builtin_msa_copy_s_d (v2i64, imm0_1);
20344 u32 __builtin_msa_copy_u_b (v16i8, imm0_15);
20345 u32 __builtin_msa_copy_u_h (v8i16, imm0_7);
20346 u32 __builtin_msa_copy_u_w (v4i32, imm0_3);
20347 u64 __builtin_msa_copy_u_d (v2i64, imm0_1);
20349 void __builtin_msa_ctcmsa (imm0_31, i32);
20351 v16i8 __builtin_msa_div_s_b (v16i8, v16i8);
20352 v8i16 __builtin_msa_div_s_h (v8i16, v8i16);
20353 v4i32 __builtin_msa_div_s_w (v4i32, v4i32);
20354 v2i64 __builtin_msa_div_s_d (v2i64, v2i64);
20356 v16u8 __builtin_msa_div_u_b (v16u8, v16u8);
20357 v8u16 __builtin_msa_div_u_h (v8u16, v8u16);
20358 v4u32 __builtin_msa_div_u_w (v4u32, v4u32);
20359 v2u64 __builtin_msa_div_u_d (v2u64, v2u64);
20361 v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8);
20362 v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16);
20363 v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32);
20365 v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8);
20366 v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16);
20367 v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32);
20369 v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8);
20370 v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16);
20371 v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32);
20373 v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8);
20374 v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16);
20375 v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32);
20377 v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8);
20378 v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16);
20379 v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32);
20381 v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8);
20382 v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16);
20383 v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32);
20385 v4f32 __builtin_msa_fadd_w (v4f32, v4f32);
20386 v2f64 __builtin_msa_fadd_d (v2f64, v2f64);
20388 v4i32 __builtin_msa_fcaf_w (v4f32, v4f32);
20389 v2i64 __builtin_msa_fcaf_d (v2f64, v2f64);
20391 v4i32 __builtin_msa_fceq_w (v4f32, v4f32);
20392 v2i64 __builtin_msa_fceq_d (v2f64, v2f64);
20394 v4i32 __builtin_msa_fclass_w (v4f32);
20395 v2i64 __builtin_msa_fclass_d (v2f64);
20397 v4i32 __builtin_msa_fcle_w (v4f32, v4f32);
20398 v2i64 __builtin_msa_fcle_d (v2f64, v2f64);
20400 v4i32 __builtin_msa_fclt_w (v4f32, v4f32);
20401 v2i64 __builtin_msa_fclt_d (v2f64, v2f64);
20403 v4i32 __builtin_msa_fcne_w (v4f32, v4f32);
20404 v2i64 __builtin_msa_fcne_d (v2f64, v2f64);
20406 v4i32 __builtin_msa_fcor_w (v4f32, v4f32);
20407 v2i64 __builtin_msa_fcor_d (v2f64, v2f64);
20409 v4i32 __builtin_msa_fcueq_w (v4f32, v4f32);
20410 v2i64 __builtin_msa_fcueq_d (v2f64, v2f64);
20412 v4i32 __builtin_msa_fcule_w (v4f32, v4f32);
20413 v2i64 __builtin_msa_fcule_d (v2f64, v2f64);
20415 v4i32 __builtin_msa_fcult_w (v4f32, v4f32);
20416 v2i64 __builtin_msa_fcult_d (v2f64, v2f64);
20418 v4i32 __builtin_msa_fcun_w (v4f32, v4f32);
20419 v2i64 __builtin_msa_fcun_d (v2f64, v2f64);
20421 v4i32 __builtin_msa_fcune_w (v4f32, v4f32);
20422 v2i64 __builtin_msa_fcune_d (v2f64, v2f64);
20424 v4f32 __builtin_msa_fdiv_w (v4f32, v4f32);
20425 v2f64 __builtin_msa_fdiv_d (v2f64, v2f64);
20427 v8i16 __builtin_msa_fexdo_h (v4f32, v4f32);
20428 v4f32 __builtin_msa_fexdo_w (v2f64, v2f64);
20430 v4f32 __builtin_msa_fexp2_w (v4f32, v4i32);
20431 v2f64 __builtin_msa_fexp2_d (v2f64, v2i64);
20433 v4f32 __builtin_msa_fexupl_w (v8i16);
20434 v2f64 __builtin_msa_fexupl_d (v4f32);
20436 v4f32 __builtin_msa_fexupr_w (v8i16);
20437 v2f64 __builtin_msa_fexupr_d (v4f32);
20439 v4f32 __builtin_msa_ffint_s_w (v4i32);
20440 v2f64 __builtin_msa_ffint_s_d (v2i64);
20442 v4f32 __builtin_msa_ffint_u_w (v4u32);
20443 v2f64 __builtin_msa_ffint_u_d (v2u64);
20445 v4f32 __builtin_msa_ffql_w (v8i16);
20446 v2f64 __builtin_msa_ffql_d (v4i32);
20448 v4f32 __builtin_msa_ffqr_w (v8i16);
20449 v2f64 __builtin_msa_ffqr_d (v4i32);
20451 v16i8 __builtin_msa_fill_b (i32);
20452 v8i16 __builtin_msa_fill_h (i32);
20453 v4i32 __builtin_msa_fill_w (i32);
20454 v2i64 __builtin_msa_fill_d (i64);
20456 v4f32 __builtin_msa_flog2_w (v4f32);
20457 v2f64 __builtin_msa_flog2_d (v2f64);
20459 v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32);
20460 v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64);
20462 v4f32 __builtin_msa_fmax_w (v4f32, v4f32);
20463 v2f64 __builtin_msa_fmax_d (v2f64, v2f64);
20465 v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32);
20466 v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64);
20468 v4f32 __builtin_msa_fmin_w (v4f32, v4f32);
20469 v2f64 __builtin_msa_fmin_d (v2f64, v2f64);
20471 v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32);
20472 v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64);
20474 v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32);
20475 v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64);
20477 v4f32 __builtin_msa_fmul_w (v4f32, v4f32);
20478 v2f64 __builtin_msa_fmul_d (v2f64, v2f64);
20480 v4f32 __builtin_msa_frint_w (v4f32);
20481 v2f64 __builtin_msa_frint_d (v2f64);
20483 v4f32 __builtin_msa_frcp_w (v4f32);
20484 v2f64 __builtin_msa_frcp_d (v2f64);
20486 v4f32 __builtin_msa_frsqrt_w (v4f32);
20487 v2f64 __builtin_msa_frsqrt_d (v2f64);
20489 v4i32 __builtin_msa_fsaf_w (v4f32, v4f32);
20490 v2i64 __builtin_msa_fsaf_d (v2f64, v2f64);
20492 v4i32 __builtin_msa_fseq_w (v4f32, v4f32);
20493 v2i64 __builtin_msa_fseq_d (v2f64, v2f64);
20495 v4i32 __builtin_msa_fsle_w (v4f32, v4f32);
20496 v2i64 __builtin_msa_fsle_d (v2f64, v2f64);
20498 v4i32 __builtin_msa_fslt_w (v4f32, v4f32);
20499 v2i64 __builtin_msa_fslt_d (v2f64, v2f64);
20501 v4i32 __builtin_msa_fsne_w (v4f32, v4f32);
20502 v2i64 __builtin_msa_fsne_d (v2f64, v2f64);
20504 v4i32 __builtin_msa_fsor_w (v4f32, v4f32);
20505 v2i64 __builtin_msa_fsor_d (v2f64, v2f64);
20507 v4f32 __builtin_msa_fsqrt_w (v4f32);
20508 v2f64 __builtin_msa_fsqrt_d (v2f64);
20510 v4f32 __builtin_msa_fsub_w (v4f32, v4f32);
20511 v2f64 __builtin_msa_fsub_d (v2f64, v2f64);
20513 v4i32 __builtin_msa_fsueq_w (v4f32, v4f32);
20514 v2i64 __builtin_msa_fsueq_d (v2f64, v2f64);
20516 v4i32 __builtin_msa_fsule_w (v4f32, v4f32);
20517 v2i64 __builtin_msa_fsule_d (v2f64, v2f64);
20519 v4i32 __builtin_msa_fsult_w (v4f32, v4f32);
20520 v2i64 __builtin_msa_fsult_d (v2f64, v2f64);
20522 v4i32 __builtin_msa_fsun_w (v4f32, v4f32);
20523 v2i64 __builtin_msa_fsun_d (v2f64, v2f64);
20525 v4i32 __builtin_msa_fsune_w (v4f32, v4f32);
20526 v2i64 __builtin_msa_fsune_d (v2f64, v2f64);
20528 v4i32 __builtin_msa_ftint_s_w (v4f32);
20529 v2i64 __builtin_msa_ftint_s_d (v2f64);
20531 v4u32 __builtin_msa_ftint_u_w (v4f32);
20532 v2u64 __builtin_msa_ftint_u_d (v2f64);
20534 v8i16 __builtin_msa_ftq_h (v4f32, v4f32);
20535 v4i32 __builtin_msa_ftq_w (v2f64, v2f64);
20537 v4i32 __builtin_msa_ftrunc_s_w (v4f32);
20538 v2i64 __builtin_msa_ftrunc_s_d (v2f64);
20540 v4u32 __builtin_msa_ftrunc_u_w (v4f32);
20541 v2u64 __builtin_msa_ftrunc_u_d (v2f64);
20543 v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8);
20544 v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16);
20545 v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32);
20547 v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8);
20548 v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16);
20549 v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32);
20551 v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8);
20552 v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16);
20553 v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32);
20555 v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8);
20556 v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16);
20557 v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32);
20559 v16i8 __builtin_msa_ilvev_b (v16i8, v16i8);
20560 v8i16 __builtin_msa_ilvev_h (v8i16, v8i16);
20561 v4i32 __builtin_msa_ilvev_w (v4i32, v4i32);
20562 v2i64 __builtin_msa_ilvev_d (v2i64, v2i64);
20564 v16i8 __builtin_msa_ilvl_b (v16i8, v16i8);
20565 v8i16 __builtin_msa_ilvl_h (v8i16, v8i16);
20566 v4i32 __builtin_msa_ilvl_w (v4i32, v4i32);
20567 v2i64 __builtin_msa_ilvl_d (v2i64, v2i64);
20569 v16i8 __builtin_msa_ilvod_b (v16i8, v16i8);
20570 v8i16 __builtin_msa_ilvod_h (v8i16, v8i16);
20571 v4i32 __builtin_msa_ilvod_w (v4i32, v4i32);
20572 v2i64 __builtin_msa_ilvod_d (v2i64, v2i64);
20574 v16i8 __builtin_msa_ilvr_b (v16i8, v16i8);
20575 v8i16 __builtin_msa_ilvr_h (v8i16, v8i16);
20576 v4i32 __builtin_msa_ilvr_w (v4i32, v4i32);
20577 v2i64 __builtin_msa_ilvr_d (v2i64, v2i64);
20579 v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32);
20580 v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32);
20581 v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32);
20582 v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64);
20584 v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8);
20585 v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16);
20586 v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32);
20587 v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64);
20589 v16i8 __builtin_msa_ld_b (const void *, imm_n512_511);
20590 v8i16 __builtin_msa_ld_h (const void *, imm_n1024_1022);
20591 v4i32 __builtin_msa_ld_w (const void *, imm_n2048_2044);
20592 v2i64 __builtin_msa_ld_d (const void *, imm_n4096_4088);
20594 v16i8 __builtin_msa_ldi_b (imm_n512_511);
20595 v8i16 __builtin_msa_ldi_h (imm_n512_511);
20596 v4i32 __builtin_msa_ldi_w (imm_n512_511);
20597 v2i64 __builtin_msa_ldi_d (imm_n512_511);
20599 v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16);
20600 v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32);
20602 v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16);
20603 v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32);
20605 v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8);
20606 v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16);
20607 v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32);
20608 v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64);
20610 v16i8 __builtin_msa_max_a_b (v16i8, v16i8);
20611 v8i16 __builtin_msa_max_a_h (v8i16, v8i16);
20612 v4i32 __builtin_msa_max_a_w (v4i32, v4i32);
20613 v2i64 __builtin_msa_max_a_d (v2i64, v2i64);
20615 v16i8 __builtin_msa_max_s_b (v16i8, v16i8);
20616 v8i16 __builtin_msa_max_s_h (v8i16, v8i16);
20617 v4i32 __builtin_msa_max_s_w (v4i32, v4i32);
20618 v2i64 __builtin_msa_max_s_d (v2i64, v2i64);
20620 v16u8 __builtin_msa_max_u_b (v16u8, v16u8);
20621 v8u16 __builtin_msa_max_u_h (v8u16, v8u16);
20622 v4u32 __builtin_msa_max_u_w (v4u32, v4u32);
20623 v2u64 __builtin_msa_max_u_d (v2u64, v2u64);
20625 v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15);
20626 v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15);
20627 v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15);
20628 v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15);
20630 v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31);
20631 v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31);
20632 v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31);
20633 v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31);
20635 v16i8 __builtin_msa_min_a_b (v16i8, v16i8);
20636 v8i16 __builtin_msa_min_a_h (v8i16, v8i16);
20637 v4i32 __builtin_msa_min_a_w (v4i32, v4i32);
20638 v2i64 __builtin_msa_min_a_d (v2i64, v2i64);
20640 v16i8 __builtin_msa_min_s_b (v16i8, v16i8);
20641 v8i16 __builtin_msa_min_s_h (v8i16, v8i16);
20642 v4i32 __builtin_msa_min_s_w (v4i32, v4i32);
20643 v2i64 __builtin_msa_min_s_d (v2i64, v2i64);
20645 v16u8 __builtin_msa_min_u_b (v16u8, v16u8);
20646 v8u16 __builtin_msa_min_u_h (v8u16, v8u16);
20647 v4u32 __builtin_msa_min_u_w (v4u32, v4u32);
20648 v2u64 __builtin_msa_min_u_d (v2u64, v2u64);
20650 v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15);
20651 v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15);
20652 v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15);
20653 v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15);
20655 v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31);
20656 v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31);
20657 v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31);
20658 v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31);
20660 v16i8 __builtin_msa_mod_s_b (v16i8, v16i8);
20661 v8i16 __builtin_msa_mod_s_h (v8i16, v8i16);
20662 v4i32 __builtin_msa_mod_s_w (v4i32, v4i32);
20663 v2i64 __builtin_msa_mod_s_d (v2i64, v2i64);
20665 v16u8 __builtin_msa_mod_u_b (v16u8, v16u8);
20666 v8u16 __builtin_msa_mod_u_h (v8u16, v8u16);
20667 v4u32 __builtin_msa_mod_u_w (v4u32, v4u32);
20668 v2u64 __builtin_msa_mod_u_d (v2u64, v2u64);
20670 v16i8 __builtin_msa_move_v (v16i8);
20672 v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16);
20673 v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32);
20675 v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16);
20676 v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32);
20678 v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8);
20679 v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16);
20680 v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32);
20681 v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64);
20683 v8i16 __builtin_msa_mul_q_h (v8i16, v8i16);
20684 v4i32 __builtin_msa_mul_q_w (v4i32, v4i32);
20686 v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16);
20687 v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32);
20689 v16i8 __builtin_msa_mulv_b (v16i8, v16i8);
20690 v8i16 __builtin_msa_mulv_h (v8i16, v8i16);
20691 v4i32 __builtin_msa_mulv_w (v4i32, v4i32);
20692 v2i64 __builtin_msa_mulv_d (v2i64, v2i64);
20694 v16i8 __builtin_msa_nloc_b (v16i8);
20695 v8i16 __builtin_msa_nloc_h (v8i16);
20696 v4i32 __builtin_msa_nloc_w (v4i32);
20697 v2i64 __builtin_msa_nloc_d (v2i64);
20699 v16i8 __builtin_msa_nlzc_b (v16i8);
20700 v8i16 __builtin_msa_nlzc_h (v8i16);
20701 v4i32 __builtin_msa_nlzc_w (v4i32);
20702 v2i64 __builtin_msa_nlzc_d (v2i64);
20704 v16u8 __builtin_msa_nor_v (v16u8, v16u8);
20706 v16u8 __builtin_msa_nori_b (v16u8, imm0_255);
20708 v16u8 __builtin_msa_or_v (v16u8, v16u8);
20710 v16u8 __builtin_msa_ori_b (v16u8, imm0_255);
20712 v16i8 __builtin_msa_pckev_b (v16i8, v16i8);
20713 v8i16 __builtin_msa_pckev_h (v8i16, v8i16);
20714 v4i32 __builtin_msa_pckev_w (v4i32, v4i32);
20715 v2i64 __builtin_msa_pckev_d (v2i64, v2i64);
20717 v16i8 __builtin_msa_pckod_b (v16i8, v16i8);
20718 v8i16 __builtin_msa_pckod_h (v8i16, v8i16);
20719 v4i32 __builtin_msa_pckod_w (v4i32, v4i32);
20720 v2i64 __builtin_msa_pckod_d (v2i64, v2i64);
20722 v16i8 __builtin_msa_pcnt_b (v16i8);
20723 v8i16 __builtin_msa_pcnt_h (v8i16);
20724 v4i32 __builtin_msa_pcnt_w (v4i32);
20725 v2i64 __builtin_msa_pcnt_d (v2i64);
20727 v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7);
20728 v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15);
20729 v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31);
20730 v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63);
20732 v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7);
20733 v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15);
20734 v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31);
20735 v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63);
20737 v16i8 __builtin_msa_shf_b (v16i8, imm0_255);
20738 v8i16 __builtin_msa_shf_h (v8i16, imm0_255);
20739 v4i32 __builtin_msa_shf_w (v4i32, imm0_255);
20741 v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32);
20742 v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32);
20743 v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32);
20744 v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32);
20746 v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15);
20747 v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7);
20748 v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3);
20749 v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1);
20751 v16i8 __builtin_msa_sll_b (v16i8, v16i8);
20752 v8i16 __builtin_msa_sll_h (v8i16, v8i16);
20753 v4i32 __builtin_msa_sll_w (v4i32, v4i32);
20754 v2i64 __builtin_msa_sll_d (v2i64, v2i64);
20756 v16i8 __builtin_msa_slli_b (v16i8, imm0_7);
20757 v8i16 __builtin_msa_slli_h (v8i16, imm0_15);
20758 v4i32 __builtin_msa_slli_w (v4i32, imm0_31);
20759 v2i64 __builtin_msa_slli_d (v2i64, imm0_63);
20761 v16i8 __builtin_msa_splat_b (v16i8, i32);
20762 v8i16 __builtin_msa_splat_h (v8i16, i32);
20763 v4i32 __builtin_msa_splat_w (v4i32, i32);
20764 v2i64 __builtin_msa_splat_d (v2i64, i32);
20766 v16i8 __builtin_msa_splati_b (v16i8, imm0_15);
20767 v8i16 __builtin_msa_splati_h (v8i16, imm0_7);
20768 v4i32 __builtin_msa_splati_w (v4i32, imm0_3);
20769 v2i64 __builtin_msa_splati_d (v2i64, imm0_1);
20771 v16i8 __builtin_msa_sra_b (v16i8, v16i8);
20772 v8i16 __builtin_msa_sra_h (v8i16, v8i16);
20773 v4i32 __builtin_msa_sra_w (v4i32, v4i32);
20774 v2i64 __builtin_msa_sra_d (v2i64, v2i64);
20776 v16i8 __builtin_msa_srai_b (v16i8, imm0_7);
20777 v8i16 __builtin_msa_srai_h (v8i16, imm0_15);
20778 v4i32 __builtin_msa_srai_w (v4i32, imm0_31);
20779 v2i64 __builtin_msa_srai_d (v2i64, imm0_63);
20781 v16i8 __builtin_msa_srar_b (v16i8, v16i8);
20782 v8i16 __builtin_msa_srar_h (v8i16, v8i16);
20783 v4i32 __builtin_msa_srar_w (v4i32, v4i32);
20784 v2i64 __builtin_msa_srar_d (v2i64, v2i64);
20786 v16i8 __builtin_msa_srari_b (v16i8, imm0_7);
20787 v8i16 __builtin_msa_srari_h (v8i16, imm0_15);
20788 v4i32 __builtin_msa_srari_w (v4i32, imm0_31);
20789 v2i64 __builtin_msa_srari_d (v2i64, imm0_63);
20791 v16i8 __builtin_msa_srl_b (v16i8, v16i8);
20792 v8i16 __builtin_msa_srl_h (v8i16, v8i16);
20793 v4i32 __builtin_msa_srl_w (v4i32, v4i32);
20794 v2i64 __builtin_msa_srl_d (v2i64, v2i64);
20796 v16i8 __builtin_msa_srli_b (v16i8, imm0_7);
20797 v8i16 __builtin_msa_srli_h (v8i16, imm0_15);
20798 v4i32 __builtin_msa_srli_w (v4i32, imm0_31);
20799 v2i64 __builtin_msa_srli_d (v2i64, imm0_63);
20801 v16i8 __builtin_msa_srlr_b (v16i8, v16i8);
20802 v8i16 __builtin_msa_srlr_h (v8i16, v8i16);
20803 v4i32 __builtin_msa_srlr_w (v4i32, v4i32);
20804 v2i64 __builtin_msa_srlr_d (v2i64, v2i64);
20806 v16i8 __builtin_msa_srlri_b (v16i8, imm0_7);
20807 v8i16 __builtin_msa_srlri_h (v8i16, imm0_15);
20808 v4i32 __builtin_msa_srlri_w (v4i32, imm0_31);
20809 v2i64 __builtin_msa_srlri_d (v2i64, imm0_63);
20811 void __builtin_msa_st_b (v16i8, void *, imm_n512_511);
20812 void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022);
20813 void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044);
20814 void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088);
20816 v16i8 __builtin_msa_subs_s_b (v16i8, v16i8);
20817 v8i16 __builtin_msa_subs_s_h (v8i16, v8i16);
20818 v4i32 __builtin_msa_subs_s_w (v4i32, v4i32);
20819 v2i64 __builtin_msa_subs_s_d (v2i64, v2i64);
20821 v16u8 __builtin_msa_subs_u_b (v16u8, v16u8);
20822 v8u16 __builtin_msa_subs_u_h (v8u16, v8u16);
20823 v4u32 __builtin_msa_subs_u_w (v4u32, v4u32);
20824 v2u64 __builtin_msa_subs_u_d (v2u64, v2u64);
20826 v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8);
20827 v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16);
20828 v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32);
20829 v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64);
20831 v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8);
20832 v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16);
20833 v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32);
20834 v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64);
20836 v16i8 __builtin_msa_subv_b (v16i8, v16i8);
20837 v8i16 __builtin_msa_subv_h (v8i16, v8i16);
20838 v4i32 __builtin_msa_subv_w (v4i32, v4i32);
20839 v2i64 __builtin_msa_subv_d (v2i64, v2i64);
20841 v16i8 __builtin_msa_subvi_b (v16i8, imm0_31);
20842 v8i16 __builtin_msa_subvi_h (v8i16, imm0_31);
20843 v4i32 __builtin_msa_subvi_w (v4i32, imm0_31);
20844 v2i64 __builtin_msa_subvi_d (v2i64, imm0_31);
20846 v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8);
20847 v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16);
20848 v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32);
20849 v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64);
20851 v16u8 __builtin_msa_xor_v (v16u8, v16u8);
20853 v16u8 __builtin_msa_xori_b (v16u8, imm0_255);
20856 @node Other MIPS Built-in Functions
20857 @subsection Other MIPS Built-in Functions
20859 GCC provides other MIPS-specific built-in functions:
20862 @item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr})
20863 Insert a @samp{cache} instruction with operands @var{op} and @var{addr}.
20864 GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE}
20865 when this function is available.
20867 @item unsigned int __builtin_mips_get_fcsr (void)
20868 @itemx void __builtin_mips_set_fcsr (unsigned int @var{value})
20869 Get and set the contents of the floating-point control and status register
20870 (FPU control register 31). These functions are only available in hard-float
20871 code but can be called in both MIPS16 and non-MIPS16 contexts.
20873 @code{__builtin_mips_set_fcsr} can be used to change any bit of the
20874 register except the condition codes, which GCC assumes are preserved.
20877 @node MSP430 Built-in Functions
20878 @subsection MSP430 Built-in Functions
20880 GCC provides a couple of special builtin functions to aid in the
20881 writing of interrupt handlers in C.
20884 @item __bic_SR_register_on_exit (int @var{mask})
20885 This clears the indicated bits in the saved copy of the status register
20886 currently residing on the stack. This only works inside interrupt
20887 handlers and the changes to the status register will only take affect
20888 once the handler returns.
20890 @item __bis_SR_register_on_exit (int @var{mask})
20891 This sets the indicated bits in the saved copy of the status register
20892 currently residing on the stack. This only works inside interrupt
20893 handlers and the changes to the status register will only take affect
20894 once the handler returns.
20896 @item __delay_cycles (long long @var{cycles})
20897 This inserts an instruction sequence that takes exactly @var{cycles}
20898 cycles (between 0 and about 17E9) to complete. The inserted sequence
20899 may use jumps, loops, or no-ops, and does not interfere with any other
20900 instructions. Note that @var{cycles} must be a compile-time constant
20901 integer - that is, you must pass a number, not a variable that may be
20902 optimized to a constant later. The number of cycles delayed by this
20906 @node NDS32 Built-in Functions
20907 @subsection NDS32 Built-in Functions
20909 These built-in functions are available for the NDS32 target:
20911 @defbuiltin{void __builtin_nds32_isync (int *@var{addr})}
20912 Insert an ISYNC instruction into the instruction stream where
20913 @var{addr} is an instruction address for serialization.
20916 @defbuiltin{void __builtin_nds32_isb (void)}
20917 Insert an ISB instruction into the instruction stream.
20920 @defbuiltin{int __builtin_nds32_mfsr (int @var{sr})}
20921 Return the content of a system register which is mapped by @var{sr}.
20924 @defbuiltin{int __builtin_nds32_mfusr (int @var{usr})}
20925 Return the content of a user space register which is mapped by @var{usr}.
20928 @defbuiltin{void __builtin_nds32_mtsr (int @var{value}, int @var{sr})}
20929 Move the @var{value} to a system register which is mapped by @var{sr}.
20932 @defbuiltin{void __builtin_nds32_mtusr (int @var{value}, int @var{usr})}
20933 Move the @var{value} to a user space register which is mapped by @var{usr}.
20936 @defbuiltin{void __builtin_nds32_setgie_en (void)}
20937 Enable global interrupt.
20940 @defbuiltin{void __builtin_nds32_setgie_dis (void)}
20941 Disable global interrupt.
20944 @node Nvidia PTX Built-in Functions
20945 @subsection Nvidia PTX Built-in Functions
20947 These built-in functions are available for the Nvidia PTX target:
20949 @defbuiltin{{unsigned int} __builtin_nvptx_brev (unsigned int @var{x})}
20950 Reverse the bit order of a 32-bit unsigned integer.
20953 @defbuiltin{{unsigned long long} __builtin_nvptx_brevll (unsigned long long @var{x})}
20954 Reverse the bit order of a 64-bit unsigned integer.
20957 @node Basic PowerPC Built-in Functions
20958 @subsection Basic PowerPC Built-in Functions
20961 * Basic PowerPC Built-in Functions Available on all Configurations::
20962 * Basic PowerPC Built-in Functions Available on ISA 2.05::
20963 * Basic PowerPC Built-in Functions Available on ISA 2.06::
20964 * Basic PowerPC Built-in Functions Available on ISA 2.07::
20965 * Basic PowerPC Built-in Functions Available on ISA 3.0::
20966 * Basic PowerPC Built-in Functions Available on ISA 3.1::
20969 This section describes PowerPC built-in functions that do not require
20970 the inclusion of any special header files to declare prototypes or
20971 provide macro definitions. The sections that follow describe
20972 additional PowerPC built-in functions.
20974 @node Basic PowerPC Built-in Functions Available on all Configurations
20975 @subsubsection Basic PowerPC Built-in Functions Available on all Configurations
20977 @defbuiltin{void __builtin_cpu_init (void)}
20978 This function is a @code{nop} on the PowerPC platform and is included solely
20979 to maintain API compatibility with the x86 builtins.
20982 @defbuiltin{int __builtin_cpu_is (const char *@var{cpuname})}
20983 This function returns a value of @code{1} if the run-time CPU is of type
20984 @var{cpuname} and returns @code{0} otherwise
20986 The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer
20987 which exports the hardware capability bits. GCC defines the macro
20988 @code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports}
20989 built-in function is fully supported.
20991 If GCC was configured to use a GLIBC before 2.23, the built-in
20992 function @code{__builtin_cpu_is} always returns a 0 and the compiler
20995 The following CPU names can be detected:
20999 IBM POWER10 Server CPU.
21001 IBM POWER9 Server CPU.
21003 IBM POWER8 Server CPU.
21005 IBM POWER7 Server CPU.
21007 IBM POWER6 Server CPU (RAW mode).
21009 IBM POWER6 Server CPU (Architected mode).
21011 IBM POWER5+ Server CPU.
21013 IBM POWER5 Server CPU.
21015 IBM 970 Server CPU (ie, Apple G5).
21017 IBM POWER4 Server CPU.
21019 IBM A2 64-bit Embedded CPU
21021 IBM PowerPC 476FP 32-bit Embedded CPU.
21023 IBM PowerPC 464 32-bit Embedded CPU.
21025 PowerPC 440 32-bit Embedded CPU.
21027 PowerPC 405 32-bit Embedded CPU.
21029 IBM PowerPC Cell Broadband Engine Architecture CPU.
21032 Here is an example:
21034 #ifdef __BUILTIN_CPU_SUPPORTS__
21035 if (__builtin_cpu_is ("power8"))
21037 do_power8 (); // POWER8 specific implementation.
21042 do_generic (); // Generic implementation.
21047 @defbuiltin{int __builtin_cpu_supports (const char *@var{feature})}
21048 This function returns a value of @code{1} if the run-time CPU supports the HWCAP
21049 feature @var{feature} and returns @code{0} otherwise.
21051 The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or
21052 newer which exports the hardware capability bits. GCC defines the
21053 macro @code{__BUILTIN_CPU_SUPPORTS__} if the
21054 @code{__builtin_cpu_supports} built-in function is fully supported.
21056 If GCC was configured to use a GLIBC before 2.23, the built-in
21057 function @code{__builtin_cpu_supports} always returns a 0 and the
21058 compiler issues a warning.
21060 The following features can be
21065 4xx CPU has a Multiply Accumulator.
21067 CPU has a SIMD/Vector Unit.
21069 CPU supports ISA 2.05 (eg, POWER6)
21071 CPU supports ISA 2.06 (eg, POWER7)
21073 CPU supports ISA 2.07 (eg, POWER8)
21075 CPU supports ISA 3.0 (eg, POWER9)
21077 CPU supports ISA 3.1 (eg, POWER10)
21079 CPU supports the set of compatible performance monitoring events.
21081 CPU supports the Embedded ISA category.
21083 CPU has a CELL broadband engine.
21085 CPU supports the @code{darn} (deliver a random number) instruction.
21087 CPU has a decimal floating point unit.
21089 CPU supports the data stream control register.
21091 CPU supports event base branching.
21093 CPU has a SPE double precision floating point unit.
21095 CPU has a SPE single precision floating point unit.
21097 CPU has a floating point unit.
21099 CPU has hardware transaction memory instructions.
21101 Kernel aborts hardware transactions when a syscall is made.
21102 @item htm-no-suspend
21103 CPU supports hardware transaction memory but does not support the
21104 @code{tsuspend.} instruction.
21106 CPU supports icache snooping capabilities.
21108 CPU supports 128-bit IEEE binary floating point instructions.
21110 CPU supports the integer select instruction.
21112 CPU supports the matrix-multiply assist instructions.
21114 CPU has a memory management unit.
21116 CPU does not have a timebase (eg, 601 and 403gx).
21118 CPU supports the PA Semi 6T CORE ISA.
21120 CPU supports ISA 2.00 (eg, POWER4)
21122 CPU supports ISA 2.02 (eg, POWER5)
21124 CPU supports ISA 2.03 (eg, POWER5+)
21126 CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr.
21128 CPU supports 32-bit mode execution.
21130 CPU supports the old POWER ISA (eg, 601)
21132 CPU supports 64-bit mode execution.
21134 CPU supports a little-endian mode that uses address swizzling.
21136 Kernel supports system call vectored.
21138 CPU support simultaneous multi-threading.
21140 CPU has a signal processing extension unit.
21142 CPU supports the target address register.
21144 CPU supports true little-endian mode.
21146 CPU has unified I/D cache.
21148 CPU supports the vector cryptography instructions.
21150 CPU supports the vector-scalar extension.
21153 Here is an example:
21155 #ifdef __BUILTIN_CPU_SUPPORTS__
21156 if (__builtin_cpu_supports ("fpu"))
21158 asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2));
21163 dst = __fadd (src1, src2); // Software FP addition function.
21168 The following built-in functions are also available on all PowerPC
21171 uint64_t __builtin_ppc_get_timebase ();
21172 unsigned long __builtin_ppc_mftb ();
21173 double __builtin_unpack_ibm128 (__ibm128, int);
21174 __ibm128 __builtin_pack_ibm128 (double, double);
21175 double __builtin_mffs (void);
21176 void __builtin_mtfsf (const int, double);
21177 void __builtin_mtfsb0 (const int);
21178 void __builtin_mtfsb1 (const int);
21179 double __builtin_set_fpscr_rn (int);
21182 The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb}
21183 functions generate instructions to read the Time Base Register. The
21184 @code{__builtin_ppc_get_timebase} function may generate multiple
21185 instructions and always returns the 64 bits of the Time Base Register.
21186 The @code{__builtin_ppc_mftb} function always generates one instruction and
21187 returns the Time Base Register value as an unsigned long, throwing away
21188 the most significant word on 32-bit environments. The @code{__builtin_mffs}
21189 return the value of the FPSCR register. Note, ISA 3.0 supports the
21190 @code{__builtin_mffsl()} which permits software to read the control and
21191 non-sticky status bits in the FSPCR without the higher latency associated with
21192 accessing the sticky status bits. The @code{__builtin_mtfsf} takes a constant
21193 8-bit integer field mask and a double precision floating point argument
21194 and generates the @code{mtfsf} (extended mnemonic) instruction to write new
21195 values to selected fields of the FPSCR. The
21196 @code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change
21197 as an argument. The valid bit range is between 0 and 31. The builtins map to
21198 the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and
21199 add 32. Hence these instructions only modify the FPSCR[32:63] bits by
21200 changing the specified bit to a zero or one respectively.
21202 The @code{__builtin_set_fpscr_rn} built-in allows changing both of the floating
21203 point rounding mode bits and returning the various FPSCR fields before the RN
21204 field is updated. The built-in returns a double consisting of the initial
21205 value of the FPSCR fields DRN, VE, OE, UE, ZE, XE, NI, and RN bit positions
21206 with all other bits set to zero. The built-in argument is a 2-bit value for the
21207 new RN field value. The argument can either be an @code{const int} or stored
21208 in a variable. Earlier versions of @code{__builtin_set_fpscr_rn} returned
21209 void. A @code{__SET_FPSCR_RN_RETURNS_FPSCR__} macro has been added. If
21210 defined, then the @code{__builtin_set_fpscr_rn} built-in returns the FPSCR
21211 fields. If not defined, the @code{__builtin_set_fpscr_rn} does not return a
21212 value. If the @option{-msoft-float} option is used, the
21213 @code{__builtin_set_fpscr_rn} built-in will not return a value.
21215 @node Basic PowerPC Built-in Functions Available on ISA 2.05
21216 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05
21218 The basic built-in functions described in this section are
21219 available on the PowerPC family of processors starting with ISA 2.05
21220 or later. Unless specific options are explicitly disabled on the
21221 command line, specifying option @option{-mcpu=power6} has the effect of
21222 enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt},
21223 @option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb},
21224 @option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and
21225 @option{-mrecip-precision} options. Specify the
21226 @option{-maltivec} option explicitly in
21227 combination with the above options if desired.
21229 The following functions require option @option{-mcmpb}.
21231 unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int);
21232 unsigned int __builtin_cmpb (unsigned int, unsigned int);
21235 The @code{__builtin_cmpb} function
21236 performs a byte-wise compare on the contents of its two arguments,
21237 returning the result of the byte-wise comparison as the returned
21238 value. For each byte comparison, the corresponding byte of the return
21239 value holds 0xff if the input bytes are equal and 0 if the input bytes
21240 are not equal. If either of the arguments to this built-in function
21241 is wider than 32 bits, the function call expands into the form that
21242 expects @code{unsigned long long int} arguments
21243 which is only available on 64-bit targets.
21245 The following built-in functions are available
21246 when hardware decimal floating point
21247 (@option{-mhard-dfp}) is available:
21249 void __builtin_set_fpscr_drn(int);
21250 _Decimal64 __builtin_ddedpd (int, _Decimal64);
21251 _Decimal128 __builtin_ddedpdq (int, _Decimal128);
21252 _Decimal64 __builtin_denbcd (int, _Decimal64);
21253 _Decimal128 __builtin_denbcdq (int, _Decimal128);
21254 _Decimal64 __builtin_diex (long long, _Decimal64);
21255 _Decimal128 _builtin_diexq (long long, _Decimal128);
21256 _Decimal64 __builtin_dscli (_Decimal64, int);
21257 _Decimal128 __builtin_dscliq (_Decimal128, int);
21258 _Decimal64 __builtin_dscri (_Decimal64, int);
21259 _Decimal128 __builtin_dscriq (_Decimal128, int);
21260 long long __builtin_dxex (_Decimal64);
21261 long long __builtin_dxexq (_Decimal128);
21262 _Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long);
21263 unsigned long long __builtin_unpack_dec128 (_Decimal128, int);
21265 The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal
21266 floating point rounding mode bits. The argument is a 3-bit value. The
21267 argument can either be a @code{const int} or the value can be stored in
21269 The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available.
21270 Otherwise the builtin reads the FPSCR, masks the current decimal rounding
21271 mode bits out and OR's in the new value.
21273 _Decimal64 __builtin_dfp_quantize (_Decimal64, _Decimal64, const int);
21274 _Decimal64 __builtin_dfp_quantize (const int, _Decimal64, const int);
21275 _Decimal128 __builtin_dfp_quantize (_Decimal128, _Decimal128, const int);
21276 _Decimal128 __builtin_dfp_quantize (const int, _Decimal128, const int);
21278 The @code{__builtin_dfp_quantize} built-in, converts and rounds the second
21279 argument to the form with the exponent as specified by the first
21280 argument based on the rounding mode specified by the third argument.
21281 If the first argument is a decimal floating point value, its exponent is used
21282 for converting and rounding of the second argument. If the first argument is a
21283 5-bit constant integer value, then the value specifies the exponent to be used
21284 when rounding and converting the second argument. The third argument is a
21285 two bit constant integer that specifies the rounding mode. The possible modes
21286 are: 00 Round to nearest, ties to even; 01 Round toward 0; 10 Round to nearest,
21287 ties away from 0; 11 Round according to DRN where DRN is the Decimal Floating
21288 point field of the FPSCR.
21292 The following functions require @option{-mhard-float},
21293 @option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options.
21296 double __builtin_recipdiv (double, double);
21297 float __builtin_recipdivf (float, float);
21298 double __builtin_rsqrt (double);
21299 float __builtin_rsqrtf (float);
21302 The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and
21303 @code{__builtin_rsqrtf} functions generate multiple instructions to
21304 implement the reciprocal sqrt functionality using reciprocal sqrt
21305 estimate instructions.
21307 The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf}
21308 functions generate multiple instructions to implement division using
21309 the reciprocal estimate instructions.
21311 The following functions require @option{-mhard-float} and
21312 @option{-mmultiple} options.
21314 The @code{__builtin_unpack_longdouble} function takes a
21315 @code{long double} argument and a compile time constant of 0 or 1. If
21316 the constant is 0, the first @code{double} within the
21317 @code{long double} is returned, otherwise the second @code{double}
21318 is returned. The @code{__builtin_unpack_longdouble} function is only
21319 available if @code{long double} uses the IBM extended double
21322 The @code{__builtin_pack_longdouble} function takes two @code{double}
21323 arguments and returns a @code{long double} value that combines the two
21324 arguments. The @code{__builtin_pack_longdouble} function is only
21325 available if @code{long double} uses the IBM extended double
21328 The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128}
21329 argument and a compile time constant of 0 or 1. If the constant is 0,
21330 the first @code{double} within the @code{__ibm128} is returned,
21331 otherwise the second @code{double} is returned.
21333 The @code{__builtin_pack_ibm128} function takes two @code{double}
21334 arguments and returns a @code{__ibm128} value that combines the two
21337 Additional built-in functions are available for the 64-bit PowerPC
21338 family of processors, for efficient use of 128-bit floating point
21339 (@code{__float128}) values.
21341 @node Basic PowerPC Built-in Functions Available on ISA 2.06
21342 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06
21344 The basic built-in functions described in this section are
21345 available on the PowerPC family of processors starting with ISA 2.05
21346 or later. Unless specific options are explicitly disabled on the
21347 command line, specifying option @option{-mcpu=power7} has the effect of
21348 enabling all the same options as for @option{-mcpu=power6} in
21349 addition to the @option{-maltivec}, @option{-mpopcntd}, and
21350 @option{-mvsx} options.
21352 The following basic built-in functions require @option{-mpopcntd}:
21354 unsigned int __builtin_addg6s (unsigned int, unsigned int);
21355 long long __builtin_bpermd (long long, long long);
21356 unsigned int __builtin_cbcdtd (unsigned int);
21357 unsigned int __builtin_cdtbcd (unsigned int);
21358 long long __builtin_divde (long long, long long);
21359 unsigned long long __builtin_divdeu (unsigned long long, unsigned long long);
21360 int __builtin_divwe (int, int);
21361 unsigned int __builtin_divweu (unsigned int, unsigned int);
21362 vector __int128 __builtin_pack_vector_int128 (long long, long long);
21363 void __builtin_rs6000_speculation_barrier (void);
21364 long long __builtin_unpack_vector_int128 (vector __int128, signed char);
21367 Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions
21368 require a 64-bit environment.
21370 The following basic built-in functions, which are also supported on
21371 x86 targets, require @option{-mfloat128}.
21373 __float128 __builtin_fabsq (__float128);
21374 __float128 __builtin_copysignq (__float128, __float128);
21375 __float128 __builtin_infq (void);
21376 __float128 __builtin_huge_valq (void);
21377 __float128 __builtin_nanq (void);
21378 __float128 __builtin_nansq (void);
21380 __float128 __builtin_sqrtf128 (__float128);
21381 __float128 __builtin_fmaf128 (__float128, __float128, __float128);
21384 @node Basic PowerPC Built-in Functions Available on ISA 2.07
21385 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07
21387 The basic built-in functions described in this section are
21388 available on the PowerPC family of processors starting with ISA 2.07
21389 or later. Unless specific options are explicitly disabled on the
21390 command line, specifying option @option{-mcpu=power8} has the effect of
21391 enabling all the same options as for @option{-mcpu=power7} in
21392 addition to the @option{-mpower8-fusion}, @option{-mcrypto},
21393 @option{-mhtm}, @option{-mquad-memory}, and
21394 @option{-mquad-memory-atomic} options.
21396 This section intentionally empty.
21398 @node Basic PowerPC Built-in Functions Available on ISA 3.0
21399 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0
21401 The basic built-in functions described in this section are
21402 available on the PowerPC family of processors starting with ISA 3.0
21403 or later. Unless specific options are explicitly disabled on the
21404 command line, specifying option @option{-mcpu=power9} has the effect of
21405 enabling all the same options as for @option{-mcpu=power8} in
21406 addition to the @option{-misel} option.
21408 The following built-in functions are available on Linux 64-bit systems
21409 that use the ISA 3.0 instruction set (@option{-mcpu=power9}):
21411 @defbuiltin{__float128 __builtin_addf128_round_to_odd (__float128, __float128)}
21412 Perform a 128-bit IEEE floating point add using round to odd as the
21416 @defbuiltin{__float128 __builtin_subf128_round_to_odd (__float128, __float128)}
21417 Perform a 128-bit IEEE floating point subtract using round to odd as
21421 @defbuiltin{__float128 __builtin_mulf128_round_to_odd (__float128, __float128)}
21422 Perform a 128-bit IEEE floating point multiply using round to odd as
21426 @defbuiltin{__float128 __builtin_divf128_round_to_odd (__float128, __float128)}
21427 Perform a 128-bit IEEE floating point divide using round to odd as
21431 @defbuiltin{__float128 __builtin_sqrtf128_round_to_odd (__float128)}
21432 Perform a 128-bit IEEE floating point square root using round to odd
21433 as the rounding mode.
21436 @defbuiltin{__float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128)}
21437 Perform a 128-bit IEEE floating point fused multiply and add operation
21438 using round to odd as the rounding mode.
21441 @defbuiltin{double __builtin_truncf128_round_to_odd (__float128)}
21442 Convert a 128-bit IEEE floating point value to @code{double} using
21443 round to odd as the rounding mode.
21447 The following additional built-in functions are also available for the
21448 PowerPC family of processors, starting with ISA 3.0 or later:
21450 @defbuiltin{{long long} __builtin_darn (void)}
21451 @defbuiltinx{{long long} __builtin_darn_raw (void)}
21452 @defbuiltinx{int __builtin_darn_32 (void)}
21453 The @code{__builtin_darn} and @code{__builtin_darn_raw}
21454 functions require a
21455 64-bit environment supporting ISA 3.0 or later.
21456 The @code{__builtin_darn} function provides a 64-bit conditioned
21457 random number. The @code{__builtin_darn_raw} function provides a
21458 64-bit raw random number. The @code{__builtin_darn_32} function
21459 provides a 32-bit conditioned random number.
21462 The following additional built-in functions are also available for the
21463 PowerPC family of processors, starting with ISA 3.0 or later:
21466 int __builtin_byte_in_set (unsigned char u, unsigned long long set);
21467 int __builtin_byte_in_range (unsigned char u, unsigned int range);
21468 int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges);
21470 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value);
21471 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value);
21472 int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value);
21473 int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value);
21475 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value);
21476 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value);
21477 int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value);
21478 int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value);
21480 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value);
21481 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value);
21482 int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value);
21483 int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value);
21485 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value);
21486 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value);
21487 int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value);
21488 int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value);
21490 double __builtin_mffsl(void);
21493 The @code{__builtin_byte_in_set} function requires a
21494 64-bit environment supporting ISA 3.0 or later. This function returns
21495 a non-zero value if and only if its @code{u} argument exactly equals one of
21496 the eight bytes contained within its 64-bit @code{set} argument.
21498 The @code{__builtin_byte_in_range} and
21499 @code{__builtin_byte_in_either_range} require an environment
21500 supporting ISA 3.0 or later. For these two functions, the
21501 @code{range} argument is encoded as 4 bytes, organized as
21502 @code{hi_1:lo_1:hi_2:lo_2}.
21503 The @code{__builtin_byte_in_range} function returns a
21504 non-zero value if and only if its @code{u} argument is within the
21505 range bounded between @code{lo_2} and @code{hi_2} inclusive.
21506 The @code{__builtin_byte_in_either_range} function returns non-zero if
21507 and only if its @code{u} argument is within either the range bounded
21508 between @code{lo_1} and @code{hi_1} inclusive or the range bounded
21509 between @code{lo_2} and @code{hi_2} inclusive.
21511 The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value
21512 if and only if the number of signficant digits of its @code{value} argument
21513 is less than its @code{comparison} argument. The
21514 @code{__builtin_dfp_dtstsfi_lt_dd} and
21515 @code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but
21516 require that the type of the @code{value} argument be
21517 @code{__Decimal64} and @code{__Decimal128} respectively.
21519 The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value
21520 if and only if the number of signficant digits of its @code{value} argument
21521 is greater than its @code{comparison} argument. The
21522 @code{__builtin_dfp_dtstsfi_gt_dd} and
21523 @code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but
21524 require that the type of the @code{value} argument be
21525 @code{__Decimal64} and @code{__Decimal128} respectively.
21527 The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value
21528 if and only if the number of signficant digits of its @code{value} argument
21529 equals its @code{comparison} argument. The
21530 @code{__builtin_dfp_dtstsfi_eq_dd} and
21531 @code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but
21532 require that the type of the @code{value} argument be
21533 @code{__Decimal64} and @code{__Decimal128} respectively.
21535 The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value
21536 if and only if its @code{value} argument has an undefined number of
21537 significant digits, such as when @code{value} is an encoding of @code{NaN}.
21538 The @code{__builtin_dfp_dtstsfi_ov_dd} and
21539 @code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but
21540 require that the type of the @code{value} argument be
21541 @code{__Decimal64} and @code{__Decimal128} respectively.
21543 The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read
21544 the FPSCR. The instruction is a lower latency version of the @code{mffs}
21545 instruction. If the @code{mffsl} instruction is not available, then the
21546 builtin uses the older @code{mffs} instruction to read the FPSCR.
21548 @node Basic PowerPC Built-in Functions Available on ISA 3.1
21549 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.1
21551 The basic built-in functions described in this section are
21552 available on the PowerPC family of processors starting with ISA 3.1.
21553 Unless specific options are explicitly disabled on the
21554 command line, specifying option @option{-mcpu=power10} has the effect of
21555 enabling all the same options as for @option{-mcpu=power9}.
21557 The following built-in functions are available on Linux 64-bit systems
21558 that use a future architecture instruction set (@option{-mcpu=power10}):
21560 @defbuiltin{{unsigned long long} @
21561 __builtin_cfuged (unsigned long long, unsigned long long)}
21562 Perform a 64-bit centrifuge operation, as if implemented by the
21563 @code{cfuged} instruction.
21566 @defbuiltin{{unsigned long long} @
21567 __builtin_cntlzdm (unsigned long long, unsigned long long)}
21568 Perform a 64-bit count leading zeros operation under mask, as if
21569 implemented by the @code{cntlzdm} instruction.
21572 @defbuiltin{{unsigned long long} @
21573 __builtin_cnttzdm (unsigned long long, unsigned long long)}
21574 Perform a 64-bit count trailing zeros operation under mask, as if
21575 implemented by the @code{cnttzdm} instruction.
21578 @defbuiltin{{unsigned long long} @
21579 __builtin_pdepd (unsigned long long, unsigned long long)}
21580 Perform a 64-bit parallel bits deposit operation, as if implemented by the
21581 @code{pdepd} instruction.
21584 @defbuiltin{{unsigned long long} @
21585 __builtin_pextd (unsigned long long, unsigned long long)}
21586 Perform a 64-bit parallel bits extract operation, as if implemented by the
21587 @code{pextd} instruction.
21590 @defbuiltin{{vector signed __int128} vsx_xl_sext (signed long long, signed char *)}
21591 @defbuiltinx{{vector signed __int128} vsx_xl_sext (signed long long, signed short *)}
21592 @defbuiltinx{{vector signed __int128} vsx_xl_sext (signed long long, signed int *)}
21593 @defbuiltinx{{vector signed __int128} vsx_xl_sext (signed long long, signed long long *)}
21594 @defbuiltinx{{vector unsigned __int128} vsx_xl_zext (signed long long, unsigned char *)}
21595 @defbuiltinx{{vector unsigned __int128} vsx_xl_zext (signed long long, unsigned short *)}
21596 @defbuiltinx{{vector unsigned __int128} vsx_xl_zext (signed long long, unsigned int *)}
21597 @defbuiltinx{{vector unsigned __int128} vsx_xl_zext (signed long long, unsigned long long *)}
21599 Load (and sign extend) to an __int128 vector, as if implemented by the ISA 3.1
21600 @code{lxvrbx}, @code{lxvrhx}, @code{lxvrwx}, and @code{lxvrdx}
21604 @defbuiltin{{void} vec_xst_trunc (vector signed __int128, signed long long, signed char *)}
21605 @defbuiltinx{{void} vec_xst_trunc (vector signed __int128, signed long long, signed short *)}
21606 @defbuiltinx{{void} vec_xst_trunc (vector signed __int128, signed long long, signed int *)}
21607 @defbuiltinx{{void} vec_xst_trunc (vector signed __int128, signed long long, signed long long *)}
21608 @defbuiltinx{{void} vec_xst_trunc (vector unsigned __int128, signed long long, unsigned char *)}
21609 @defbuiltinx{{void} vec_xst_trunc (vector unsigned __int128, signed long long, unsigned short *)}
21610 @defbuiltinx{{void} vec_xst_trunc (vector unsigned __int128, signed long long, unsigned int *)}
21611 @defbuiltinx{{void} vec_xst_trunc (vector unsigned __int128, signed long long, unsigned long long *)}
21613 Truncate and store the rightmost element of a vector, as if implemented by the
21614 ISA 3.1 @code{stxvrbx}, @code{stxvrhx}, @code{stxvrwx}, and @code{stxvrdx}
21618 @node PowerPC AltiVec/VSX Built-in Functions
21619 @subsection PowerPC AltiVec/VSX Built-in Functions
21621 GCC provides an interface for the PowerPC family of processors to access
21622 the AltiVec operations described in Motorola's AltiVec Programming
21623 Interface Manual. The interface is made available by including
21624 @code{<altivec.h>} and using @option{-maltivec} and
21625 @option{-mabi=altivec}. The interface supports the following vector
21629 vector unsigned char
21633 vector unsigned short
21634 vector signed short
21638 vector unsigned int
21644 GCC's implementation of the high-level language interface available from
21645 C and C++ code differs from Motorola's documentation in several ways.
21650 A vector constant is a list of constant expressions within curly braces.
21653 A vector initializer requires no cast if the vector constant is of the
21654 same type as the variable it is initializing.
21657 If @code{signed} or @code{unsigned} is omitted, the signedness of the
21658 vector type is the default signedness of the base type. The default
21659 varies depending on the operating system, so a portable program should
21660 always specify the signedness.
21663 Compiling with @option{-maltivec} adds keywords @code{__vector},
21664 @code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and
21665 @code{bool}. When compiling ISO C, the context-sensitive substitution
21666 of the keywords @code{vector}, @code{pixel} and @code{bool} is
21667 disabled. To use them, you must include @code{<altivec.h>} instead.
21670 GCC allows using a @code{typedef} name as the type specifier for a
21671 vector type, but only under the following circumstances:
21676 When using @code{__vector} instead of @code{vector}; for example,
21679 typedef signed short int16;
21680 __vector int16 data;
21684 When using @code{vector} in keyword-and-predefine mode; for example,
21687 typedef signed short int16;
21691 Note that keyword-and-predefine mode is enabled by disabling GNU
21692 extensions (e.g., by using @code{-std=c11}) and including
21693 @code{<altivec.h>}.
21697 For C, overloaded functions are implemented with macros so the following
21701 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo);
21705 Since @code{vec_add} is a macro, the vector constant in the example
21706 is treated as four separate arguments. Wrap the entire argument in
21707 parentheses for this to work.
21710 @emph{Note:} Only the @code{<altivec.h>} interface is supported.
21711 Internally, GCC uses built-in functions to achieve the functionality in
21712 the aforementioned header file, but they are not supported and are
21713 subject to change without notice.
21715 GCC complies with the Power Vector Intrinsic Programming Reference (PVIPR),
21716 which may be found at
21717 @uref{https://openpowerfoundation.org/?resource_lib=power-vector-intrinsic-programming-reference}.
21718 Chapter 4 of this document fully documents the vector API interfaces
21720 provided by compliant compilers. Programmers should preferentially use
21721 the interfaces described therein. However, historically GCC has provided
21722 additional interfaces for access to vector instructions. These are
21723 briefly described below. Where the PVIPR provides a portable interface,
21724 other functions in GCC that provide the same capabilities should be
21725 considered deprecated.
21727 The PVIPR documents the following overloaded functions:
21729 @multitable @columnfractions 0.33 0.33 0.33
21731 @item @code{vec_abs}
21732 @tab @code{vec_absd}
21733 @tab @code{vec_abss}
21734 @item @code{vec_add}
21735 @tab @code{vec_addc}
21736 @tab @code{vec_adde}
21737 @item @code{vec_addec}
21738 @tab @code{vec_adds}
21739 @tab @code{vec_all_eq}
21740 @item @code{vec_all_ge}
21741 @tab @code{vec_all_gt}
21742 @tab @code{vec_all_in}
21743 @item @code{vec_all_le}
21744 @tab @code{vec_all_lt}
21745 @tab @code{vec_all_nan}
21746 @item @code{vec_all_ne}
21747 @tab @code{vec_all_nge}
21748 @tab @code{vec_all_ngt}
21749 @item @code{vec_all_nle}
21750 @tab @code{vec_all_nlt}
21751 @tab @code{vec_all_numeric}
21752 @item @code{vec_and}
21753 @tab @code{vec_andc}
21754 @tab @code{vec_any_eq}
21755 @item @code{vec_any_ge}
21756 @tab @code{vec_any_gt}
21757 @tab @code{vec_any_le}
21758 @item @code{vec_any_lt}
21759 @tab @code{vec_any_nan}
21760 @tab @code{vec_any_ne}
21761 @item @code{vec_any_nge}
21762 @tab @code{vec_any_ngt}
21763 @tab @code{vec_any_nle}
21764 @item @code{vec_any_nlt}
21765 @tab @code{vec_any_numeric}
21766 @tab @code{vec_any_out}
21767 @item @code{vec_avg}
21768 @tab @code{vec_bperm}
21769 @tab @code{vec_ceil}
21770 @item @code{vec_cipher_be}
21771 @tab @code{vec_cipherlast_be}
21772 @tab @code{vec_cmpb}
21773 @item @code{vec_cmpeq}
21774 @tab @code{vec_cmpge}
21775 @tab @code{vec_cmpgt}
21776 @item @code{vec_cmple}
21777 @tab @code{vec_cmplt}
21778 @tab @code{vec_cmpne}
21779 @item @code{vec_cmpnez}
21780 @tab @code{vec_cntlz}
21781 @tab @code{vec_cntlz_lsbb}
21782 @item @code{vec_cnttz}
21783 @tab @code{vec_cnttz_lsbb}
21784 @tab @code{vec_cpsgn}
21785 @item @code{vec_ctf}
21786 @tab @code{vec_cts}
21787 @tab @code{vec_ctu}
21788 @item @code{vec_div}
21789 @tab @code{vec_double}
21790 @tab @code{vec_doublee}
21791 @item @code{vec_doubleh}
21792 @tab @code{vec_doublel}
21793 @tab @code{vec_doubleo}
21794 @item @code{vec_eqv}
21795 @tab @code{vec_expte}
21796 @tab @code{vec_extract}
21797 @item @code{vec_extract_exp}
21798 @tab @code{vec_extract_fp32_from_shorth}
21799 @tab @code{vec_extract_fp32_from_shortl}
21800 @item @code{vec_extract_sig}
21801 @tab @code{vec_extract_4b}
21802 @tab @code{vec_first_match_index}
21803 @item @code{vec_first_match_or_eos_index}
21804 @tab @code{vec_first_mismatch_index}
21805 @tab @code{vec_first_mismatch_or_eos_index}
21806 @item @code{vec_float}
21807 @tab @code{vec_float2}
21808 @tab @code{vec_floate}
21809 @item @code{vec_floato}
21810 @tab @code{vec_floor}
21812 @item @code{vec_insert}
21813 @tab @code{vec_insert_exp}
21814 @tab @code{vec_insert4b}
21815 @item @code{vec_ld}
21816 @tab @code{vec_lde}
21817 @tab @code{vec_ldl}
21818 @item @code{vec_loge}
21819 @tab @code{vec_madd}
21820 @tab @code{vec_madds}
21821 @item @code{vec_max}
21822 @tab @code{vec_mergee}
21823 @tab @code{vec_mergeh}
21824 @item @code{vec_mergel}
21825 @tab @code{vec_mergeo}
21826 @tab @code{vec_mfvscr}
21827 @item @code{vec_min}
21828 @tab @code{vec_mradds}
21829 @tab @code{vec_msub}
21830 @item @code{vec_msum}
21831 @tab @code{vec_msums}
21832 @tab @code{vec_mtvscr}
21833 @item @code{vec_mul}
21834 @tab @code{vec_mule}
21835 @tab @code{vec_mulo}
21836 @item @code{vec_nabs}
21837 @tab @code{vec_nand}
21838 @tab @code{vec_ncipher_be}
21839 @item @code{vec_ncipherlast_be}
21840 @tab @code{vec_nearbyint}
21841 @tab @code{vec_neg}
21842 @item @code{vec_nmadd}
21843 @tab @code{vec_nmsub}
21844 @tab @code{vec_nor}
21845 @item @code{vec_or}
21846 @tab @code{vec_orc}
21847 @tab @code{vec_pack}
21848 @item @code{vec_pack_to_short_fp32}
21849 @tab @code{vec_packpx}
21850 @tab @code{vec_packs}
21851 @item @code{vec_packsu}
21852 @tab @code{vec_parity_lsbb}
21853 @tab @code{vec_perm}
21854 @item @code{vec_permxor}
21855 @tab @code{vec_pmsum_be}
21856 @tab @code{vec_popcnt}
21857 @item @code{vec_re}
21858 @tab @code{vec_recipdiv}
21859 @tab @code{vec_revb}
21860 @item @code{vec_reve}
21861 @tab @code{vec_rint}
21863 @item @code{vec_rlmi}
21864 @tab @code{vec_rlnm}
21865 @tab @code{vec_round}
21866 @item @code{vec_rsqrt}
21867 @tab @code{vec_rsqrte}
21868 @tab @code{vec_sbox_be}
21869 @item @code{vec_sel}
21870 @tab @code{vec_shasigma_be}
21871 @tab @code{vec_signed}
21872 @item @code{vec_signed2}
21873 @tab @code{vec_signede}
21874 @tab @code{vec_signedo}
21875 @item @code{vec_sl}
21876 @tab @code{vec_sld}
21877 @tab @code{vec_sldw}
21878 @item @code{vec_sll}
21879 @tab @code{vec_slo}
21880 @tab @code{vec_slv}
21881 @item @code{vec_splat}
21882 @tab @code{vec_splat_s8}
21883 @tab @code{vec_splat_s16}
21884 @item @code{vec_splat_s32}
21885 @tab @code{vec_splat_u8}
21886 @tab @code{vec_splat_u16}
21887 @item @code{vec_splat_u32}
21888 @tab @code{vec_splats}
21889 @tab @code{vec_sqrt}
21890 @item @code{vec_sr}
21891 @tab @code{vec_sra}
21892 @tab @code{vec_srl}
21893 @item @code{vec_sro}
21894 @tab @code{vec_srv}
21896 @item @code{vec_ste}
21897 @tab @code{vec_stl}
21898 @tab @code{vec_sub}
21899 @item @code{vec_subc}
21900 @tab @code{vec_sube}
21901 @tab @code{vec_subec}
21902 @item @code{vec_subs}
21903 @tab @code{vec_sum2s}
21904 @tab @code{vec_sum4s}
21905 @item @code{vec_sums}
21906 @tab @code{vec_test_data_class}
21907 @tab @code{vec_trunc}
21908 @item @code{vec_unpackh}
21909 @tab @code{vec_unpackl}
21910 @tab @code{vec_unsigned}
21911 @item @code{vec_unsigned2}
21912 @tab @code{vec_unsignede}
21913 @tab @code{vec_unsignedo}
21914 @item @code{vec_xl}
21915 @tab @code{vec_xl_be}
21916 @tab @code{vec_xl_len}
21917 @item @code{vec_xl_len_r}
21918 @tab @code{vec_xor}
21919 @tab @code{vec_xst}
21920 @item @code{vec_xst_be}
21921 @tab @code{vec_xst_len}
21922 @tab @code{vec_xst_len_r}
21927 * PowerPC AltiVec Built-in Functions on ISA 2.05::
21928 * PowerPC AltiVec Built-in Functions Available on ISA 2.06::
21929 * PowerPC AltiVec Built-in Functions Available on ISA 2.07::
21930 * PowerPC AltiVec Built-in Functions Available on ISA 3.0::
21931 * PowerPC AltiVec Built-in Functions Available on ISA 3.1::
21934 @node PowerPC AltiVec Built-in Functions on ISA 2.05
21935 @subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05
21937 The following interfaces are supported for the generic and specific
21938 AltiVec operations and the AltiVec predicates. In cases where there
21939 is a direct mapping between generic and specific operations, only the
21940 generic names are shown here, although the specific operations can also
21943 Arguments that are documented as @code{const int} require literal
21944 integral values within the range required for that operation.
21946 Only functions excluded from the PVIPR are listed here.
21949 void vec_dss (const int);
21951 void vec_dssall (void);
21953 void vec_dst (const vector unsigned char *, int, const int);
21954 void vec_dst (const vector signed char *, int, const int);
21955 void vec_dst (const vector bool char *, int, const int);
21956 void vec_dst (const vector unsigned short *, int, const int);
21957 void vec_dst (const vector signed short *, int, const int);
21958 void vec_dst (const vector bool short *, int, const int);
21959 void vec_dst (const vector pixel *, int, const int);
21960 void vec_dst (const vector unsigned int *, int, const int);
21961 void vec_dst (const vector signed int *, int, const int);
21962 void vec_dst (const vector bool int *, int, const int);
21963 void vec_dst (const vector float *, int, const int);
21964 void vec_dst (const unsigned char *, int, const int);
21965 void vec_dst (const signed char *, int, const int);
21966 void vec_dst (const unsigned short *, int, const int);
21967 void vec_dst (const short *, int, const int);
21968 void vec_dst (const unsigned int *, int, const int);
21969 void vec_dst (const int *, int, const int);
21970 void vec_dst (const float *, int, const int);
21972 void vec_dstst (const vector unsigned char *, int, const int);
21973 void vec_dstst (const vector signed char *, int, const int);
21974 void vec_dstst (const vector bool char *, int, const int);
21975 void vec_dstst (const vector unsigned short *, int, const int);
21976 void vec_dstst (const vector signed short *, int, const int);
21977 void vec_dstst (const vector bool short *, int, const int);
21978 void vec_dstst (const vector pixel *, int, const int);
21979 void vec_dstst (const vector unsigned int *, int, const int);
21980 void vec_dstst (const vector signed int *, int, const int);
21981 void vec_dstst (const vector bool int *, int, const int);
21982 void vec_dstst (const vector float *, int, const int);
21983 void vec_dstst (const unsigned char *, int, const int);
21984 void vec_dstst (const signed char *, int, const int);
21985 void vec_dstst (const unsigned short *, int, const int);
21986 void vec_dstst (const short *, int, const int);
21987 void vec_dstst (const unsigned int *, int, const int);
21988 void vec_dstst (const int *, int, const int);
21989 void vec_dstst (const unsigned long *, int, const int);
21990 void vec_dstst (const long *, int, const int);
21991 void vec_dstst (const float *, int, const int);
21993 void vec_dststt (const vector unsigned char *, int, const int);
21994 void vec_dststt (const vector signed char *, int, const int);
21995 void vec_dststt (const vector bool char *, int, const int);
21996 void vec_dststt (const vector unsigned short *, int, const int);
21997 void vec_dststt (const vector signed short *, int, const int);
21998 void vec_dststt (const vector bool short *, int, const int);
21999 void vec_dststt (const vector pixel *, int, const int);
22000 void vec_dststt (const vector unsigned int *, int, const int);
22001 void vec_dststt (const vector signed int *, int, const int);
22002 void vec_dststt (const vector bool int *, int, const int);
22003 void vec_dststt (const vector float *, int, const int);
22004 void vec_dststt (const unsigned char *, int, const int);
22005 void vec_dststt (const signed char *, int, const int);
22006 void vec_dststt (const unsigned short *, int, const int);
22007 void vec_dststt (const short *, int, const int);
22008 void vec_dststt (const unsigned int *, int, const int);
22009 void vec_dststt (const int *, int, const int);
22010 void vec_dststt (const float *, int, const int);
22012 void vec_dstt (const vector unsigned char *, int, const int);
22013 void vec_dstt (const vector signed char *, int, const int);
22014 void vec_dstt (const vector bool char *, int, const int);
22015 void vec_dstt (const vector unsigned short *, int, const int);
22016 void vec_dstt (const vector signed short *, int, const int);
22017 void vec_dstt (const vector bool short *, int, const int);
22018 void vec_dstt (const vector pixel *, int, const int);
22019 void vec_dstt (const vector unsigned int *, int, const int);
22020 void vec_dstt (const vector signed int *, int, const int);
22021 void vec_dstt (const vector bool int *, int, const int);
22022 void vec_dstt (const vector float *, int, const int);
22023 void vec_dstt (const unsigned char *, int, const int);
22024 void vec_dstt (const signed char *, int, const int);
22025 void vec_dstt (const unsigned short *, int, const int);
22026 void vec_dstt (const short *, int, const int);
22027 void vec_dstt (const unsigned int *, int, const int);
22028 void vec_dstt (const int *, int, const int);
22029 void vec_dstt (const float *, int, const int);
22031 vector signed char vec_lvebx (int, char *);
22032 vector unsigned char vec_lvebx (int, unsigned char *);
22034 vector signed short vec_lvehx (int, short *);
22035 vector unsigned short vec_lvehx (int, unsigned short *);
22037 vector float vec_lvewx (int, float *);
22038 vector signed int vec_lvewx (int, int *);
22039 vector unsigned int vec_lvewx (int, unsigned int *);
22041 vector unsigned char vec_lvsl (int, const unsigned char *);
22042 vector unsigned char vec_lvsl (int, const signed char *);
22043 vector unsigned char vec_lvsl (int, const unsigned short *);
22044 vector unsigned char vec_lvsl (int, const short *);
22045 vector unsigned char vec_lvsl (int, const unsigned int *);
22046 vector unsigned char vec_lvsl (int, const int *);
22047 vector unsigned char vec_lvsl (int, const float *);
22049 vector unsigned char vec_lvsr (int, const unsigned char *);
22050 vector unsigned char vec_lvsr (int, const signed char *);
22051 vector unsigned char vec_lvsr (int, const unsigned short *);
22052 vector unsigned char vec_lvsr (int, const short *);
22053 vector unsigned char vec_lvsr (int, const unsigned int *);
22054 vector unsigned char vec_lvsr (int, const int *);
22055 vector unsigned char vec_lvsr (int, const float *);
22057 void vec_stvebx (vector signed char, int, signed char *);
22058 void vec_stvebx (vector unsigned char, int, unsigned char *);
22059 void vec_stvebx (vector bool char, int, signed char *);
22060 void vec_stvebx (vector bool char, int, unsigned char *);
22062 void vec_stvehx (vector signed short, int, short *);
22063 void vec_stvehx (vector unsigned short, int, unsigned short *);
22064 void vec_stvehx (vector bool short, int, short *);
22065 void vec_stvehx (vector bool short, int, unsigned short *);
22067 void vec_stvewx (vector float, int, float *);
22068 void vec_stvewx (vector signed int, int, int *);
22069 void vec_stvewx (vector unsigned int, int, unsigned int *);
22070 void vec_stvewx (vector bool int, int, int *);
22071 void vec_stvewx (vector bool int, int, unsigned int *);
22073 vector float vec_vaddfp (vector float, vector float);
22075 vector signed char vec_vaddsbs (vector bool char, vector signed char);
22076 vector signed char vec_vaddsbs (vector signed char, vector bool char);
22077 vector signed char vec_vaddsbs (vector signed char, vector signed char);
22079 vector signed short vec_vaddshs (vector bool short, vector signed short);
22080 vector signed short vec_vaddshs (vector signed short, vector bool short);
22081 vector signed short vec_vaddshs (vector signed short, vector signed short);
22083 vector signed int vec_vaddsws (vector bool int, vector signed int);
22084 vector signed int vec_vaddsws (vector signed int, vector bool int);
22085 vector signed int vec_vaddsws (vector signed int, vector signed int);
22087 vector signed char vec_vaddubm (vector bool char, vector signed char);
22088 vector signed char vec_vaddubm (vector signed char, vector bool char);
22089 vector signed char vec_vaddubm (vector signed char, vector signed char);
22090 vector unsigned char vec_vaddubm (vector bool char, vector unsigned char);
22091 vector unsigned char vec_vaddubm (vector unsigned char, vector bool char);
22092 vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char);
22094 vector unsigned char vec_vaddubs (vector bool char, vector unsigned char);
22095 vector unsigned char vec_vaddubs (vector unsigned char, vector bool char);
22096 vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char);
22098 vector signed short vec_vadduhm (vector bool short, vector signed short);
22099 vector signed short vec_vadduhm (vector signed short, vector bool short);
22100 vector signed short vec_vadduhm (vector signed short, vector signed short);
22101 vector unsigned short vec_vadduhm (vector bool short, vector unsigned short);
22102 vector unsigned short vec_vadduhm (vector unsigned short, vector bool short);
22103 vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short);
22105 vector unsigned short vec_vadduhs (vector bool short, vector unsigned short);
22106 vector unsigned short vec_vadduhs (vector unsigned short, vector bool short);
22107 vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short);
22109 vector signed int vec_vadduwm (vector bool int, vector signed int);
22110 vector signed int vec_vadduwm (vector signed int, vector bool int);
22111 vector signed int vec_vadduwm (vector signed int, vector signed int);
22112 vector unsigned int vec_vadduwm (vector bool int, vector unsigned int);
22113 vector unsigned int vec_vadduwm (vector unsigned int, vector bool int);
22114 vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int);
22116 vector unsigned int vec_vadduws (vector bool int, vector unsigned int);
22117 vector unsigned int vec_vadduws (vector unsigned int, vector bool int);
22118 vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int);
22120 vector signed char vec_vavgsb (vector signed char, vector signed char);
22122 vector signed short vec_vavgsh (vector signed short, vector signed short);
22124 vector signed int vec_vavgsw (vector signed int, vector signed int);
22126 vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char);
22128 vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short);
22130 vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int);
22132 vector float vec_vcfsx (vector signed int, const int);
22134 vector float vec_vcfux (vector unsigned int, const int);
22136 vector bool int vec_vcmpeqfp (vector float, vector float);
22138 vector bool char vec_vcmpequb (vector signed char, vector signed char);
22139 vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char);
22141 vector bool short vec_vcmpequh (vector signed short, vector signed short);
22142 vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short);
22144 vector bool int vec_vcmpequw (vector signed int, vector signed int);
22145 vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int);
22147 vector bool int vec_vcmpgtfp (vector float, vector float);
22149 vector bool char vec_vcmpgtsb (vector signed char, vector signed char);
22151 vector bool short vec_vcmpgtsh (vector signed short, vector signed short);
22153 vector bool int vec_vcmpgtsw (vector signed int, vector signed int);
22155 vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char);
22157 vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short);
22159 vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int);
22161 vector float vec_vmaxfp (vector float, vector float);
22163 vector signed char vec_vmaxsb (vector bool char, vector signed char);
22164 vector signed char vec_vmaxsb (vector signed char, vector bool char);
22165 vector signed char vec_vmaxsb (vector signed char, vector signed char);
22167 vector signed short vec_vmaxsh (vector bool short, vector signed short);
22168 vector signed short vec_vmaxsh (vector signed short, vector bool short);
22169 vector signed short vec_vmaxsh (vector signed short, vector signed short);
22171 vector signed int vec_vmaxsw (vector bool int, vector signed int);
22172 vector signed int vec_vmaxsw (vector signed int, vector bool int);
22173 vector signed int vec_vmaxsw (vector signed int, vector signed int);
22175 vector unsigned char vec_vmaxub (vector bool char, vector unsigned char);
22176 vector unsigned char vec_vmaxub (vector unsigned char, vector bool char);
22177 vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char);
22179 vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short);
22180 vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short);
22181 vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short);
22183 vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int);
22184 vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int);
22185 vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int);
22187 vector float vec_vminfp (vector float, vector float);
22189 vector signed char vec_vminsb (vector bool char, vector signed char);
22190 vector signed char vec_vminsb (vector signed char, vector bool char);
22191 vector signed char vec_vminsb (vector signed char, vector signed char);
22193 vector signed short vec_vminsh (vector bool short, vector signed short);
22194 vector signed short vec_vminsh (vector signed short, vector bool short);
22195 vector signed short vec_vminsh (vector signed short, vector signed short);
22197 vector signed int vec_vminsw (vector bool int, vector signed int);
22198 vector signed int vec_vminsw (vector signed int, vector bool int);
22199 vector signed int vec_vminsw (vector signed int, vector signed int);
22201 vector unsigned char vec_vminub (vector bool char, vector unsigned char);
22202 vector unsigned char vec_vminub (vector unsigned char, vector bool char);
22203 vector unsigned char vec_vminub (vector unsigned char, vector unsigned char);
22205 vector unsigned short vec_vminuh (vector bool short, vector unsigned short);
22206 vector unsigned short vec_vminuh (vector unsigned short, vector bool short);
22207 vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short);
22209 vector unsigned int vec_vminuw (vector bool int, vector unsigned int);
22210 vector unsigned int vec_vminuw (vector unsigned int, vector bool int);
22211 vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int);
22213 vector bool char vec_vmrghb (vector bool char, vector bool char);
22214 vector signed char vec_vmrghb (vector signed char, vector signed char);
22215 vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char);
22217 vector bool short vec_vmrghh (vector bool short, vector bool short);
22218 vector signed short vec_vmrghh (vector signed short, vector signed short);
22219 vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short);
22220 vector pixel vec_vmrghh (vector pixel, vector pixel);
22222 vector float vec_vmrghw (vector float, vector float);
22223 vector bool int vec_vmrghw (vector bool int, vector bool int);
22224 vector signed int vec_vmrghw (vector signed int, vector signed int);
22225 vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int);
22227 vector bool char vec_vmrglb (vector bool char, vector bool char);
22228 vector signed char vec_vmrglb (vector signed char, vector signed char);
22229 vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char);
22231 vector bool short vec_vmrglh (vector bool short, vector bool short);
22232 vector signed short vec_vmrglh (vector signed short, vector signed short);
22233 vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short);
22234 vector pixel vec_vmrglh (vector pixel, vector pixel);
22236 vector float vec_vmrglw (vector float, vector float);
22237 vector signed int vec_vmrglw (vector signed int, vector signed int);
22238 vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int);
22239 vector bool int vec_vmrglw (vector bool int, vector bool int);
22241 vector signed int vec_vmsummbm (vector signed char, vector unsigned char,
22242 vector signed int);
22244 vector signed int vec_vmsumshm (vector signed short, vector signed short,
22245 vector signed int);
22247 vector signed int vec_vmsumshs (vector signed short, vector signed short,
22248 vector signed int);
22250 vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char,
22251 vector unsigned int);
22253 vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short,
22254 vector unsigned int);
22256 vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short,
22257 vector unsigned int);
22259 vector signed short vec_vmulesb (vector signed char, vector signed char);
22261 vector signed int vec_vmulesh (vector signed short, vector signed short);
22263 vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char);
22265 vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short);
22267 vector signed short vec_vmulosb (vector signed char, vector signed char);
22269 vector signed int vec_vmulosh (vector signed short, vector signed short);
22271 vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char);
22273 vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short);
22275 vector signed char vec_vpkshss (vector signed short, vector signed short);
22277 vector unsigned char vec_vpkshus (vector signed short, vector signed short);
22279 vector signed short vec_vpkswss (vector signed int, vector signed int);
22281 vector unsigned short vec_vpkswus (vector signed int, vector signed int);
22283 vector bool char vec_vpkuhum (vector bool short, vector bool short);
22284 vector signed char vec_vpkuhum (vector signed short, vector signed short);
22285 vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short);
22287 vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short);
22289 vector bool short vec_vpkuwum (vector bool int, vector bool int);
22290 vector signed short vec_vpkuwum (vector signed int, vector signed int);
22291 vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int);
22293 vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int);
22295 vector signed char vec_vrlb (vector signed char, vector unsigned char);
22296 vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char);
22298 vector signed short vec_vrlh (vector signed short, vector unsigned short);
22299 vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short);
22301 vector signed int vec_vrlw (vector signed int, vector unsigned int);
22302 vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int);
22304 vector signed char vec_vslb (vector signed char, vector unsigned char);
22305 vector unsigned char vec_vslb (vector unsigned char, vector unsigned char);
22307 vector signed short vec_vslh (vector signed short, vector unsigned short);
22308 vector unsigned short vec_vslh (vector unsigned short, vector unsigned short);
22310 vector signed int vec_vslw (vector signed int, vector unsigned int);
22311 vector unsigned int vec_vslw (vector unsigned int, vector unsigned int);
22313 vector signed char vec_vspltb (vector signed char, const int);
22314 vector unsigned char vec_vspltb (vector unsigned char, const int);
22315 vector bool char vec_vspltb (vector bool char, const int);
22317 vector bool short vec_vsplth (vector bool short, const int);
22318 vector signed short vec_vsplth (vector signed short, const int);
22319 vector unsigned short vec_vsplth (vector unsigned short, const int);
22320 vector pixel vec_vsplth (vector pixel, const int);
22322 vector float vec_vspltw (vector float, const int);
22323 vector signed int vec_vspltw (vector signed int, const int);
22324 vector unsigned int vec_vspltw (vector unsigned int, const int);
22325 vector bool int vec_vspltw (vector bool int, const int);
22327 vector signed char vec_vsrab (vector signed char, vector unsigned char);
22328 vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char);
22330 vector signed short vec_vsrah (vector signed short, vector unsigned short);
22331 vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short);
22333 vector signed int vec_vsraw (vector signed int, vector unsigned int);
22334 vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int);
22336 vector signed char vec_vsrb (vector signed char, vector unsigned char);
22337 vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char);
22339 vector signed short vec_vsrh (vector signed short, vector unsigned short);
22340 vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short);
22342 vector signed int vec_vsrw (vector signed int, vector unsigned int);
22343 vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int);
22345 vector float vec_vsubfp (vector float, vector float);
22347 vector signed char vec_vsubsbs (vector bool char, vector signed char);
22348 vector signed char vec_vsubsbs (vector signed char, vector bool char);
22349 vector signed char vec_vsubsbs (vector signed char, vector signed char);
22351 vector signed short vec_vsubshs (vector bool short, vector signed short);
22352 vector signed short vec_vsubshs (vector signed short, vector bool short);
22353 vector signed short vec_vsubshs (vector signed short, vector signed short);
22355 vector signed int vec_vsubsws (vector bool int, vector signed int);
22356 vector signed int vec_vsubsws (vector signed int, vector bool int);
22357 vector signed int vec_vsubsws (vector signed int, vector signed int);
22359 vector signed char vec_vsububm (vector bool char, vector signed char);
22360 vector signed char vec_vsububm (vector signed char, vector bool char);
22361 vector signed char vec_vsububm (vector signed char, vector signed char);
22362 vector unsigned char vec_vsububm (vector bool char, vector unsigned char);
22363 vector unsigned char vec_vsububm (vector unsigned char, vector bool char);
22364 vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char);
22366 vector unsigned char vec_vsububs (vector bool char, vector unsigned char);
22367 vector unsigned char vec_vsububs (vector unsigned char, vector bool char);
22368 vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char);
22370 vector signed short vec_vsubuhm (vector bool short, vector signed short);
22371 vector signed short vec_vsubuhm (vector signed short, vector bool short);
22372 vector signed short vec_vsubuhm (vector signed short, vector signed short);
22373 vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short);
22374 vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short);
22375 vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short);
22377 vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short);
22378 vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short);
22379 vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short);
22381 vector signed int vec_vsubuwm (vector bool int, vector signed int);
22382 vector signed int vec_vsubuwm (vector signed int, vector bool int);
22383 vector signed int vec_vsubuwm (vector signed int, vector signed int);
22384 vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int);
22385 vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int);
22386 vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int);
22388 vector unsigned int vec_vsubuws (vector bool int, vector unsigned int);
22389 vector unsigned int vec_vsubuws (vector unsigned int, vector bool int);
22390 vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int);
22392 vector signed int vec_vsum4sbs (vector signed char, vector signed int);
22394 vector signed int vec_vsum4shs (vector signed short, vector signed int);
22396 vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int);
22398 vector unsigned int vec_vupkhpx (vector pixel);
22400 vector bool short vec_vupkhsb (vector bool char);
22401 vector signed short vec_vupkhsb (vector signed char);
22403 vector bool int vec_vupkhsh (vector bool short);
22404 vector signed int vec_vupkhsh (vector signed short);
22406 vector unsigned int vec_vupklpx (vector pixel);
22408 vector bool short vec_vupklsb (vector bool char);
22409 vector signed short vec_vupklsb (vector signed char);
22411 vector bool int vec_vupklsh (vector bool short);
22412 vector signed int vec_vupklsh (vector signed short);
22415 @node PowerPC AltiVec Built-in Functions Available on ISA 2.06
22416 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06
22418 The AltiVec built-in functions described in this section are
22419 available on the PowerPC family of processors starting with ISA 2.06
22420 or later. These are normally enabled by adding @option{-mvsx} to the
22423 When @option{-mvsx} is used, the following additional vector types are
22427 vector unsigned __int128
22428 vector signed __int128
22429 vector unsigned long long int
22430 vector signed long long int
22434 The long long types are only implemented for 64-bit code generation.
22436 Only functions excluded from the PVIPR are listed here.
22439 void vec_dst (const unsigned long *, int, const int);
22440 void vec_dst (const long *, int, const int);
22442 void vec_dststt (const unsigned long *, int, const int);
22443 void vec_dststt (const long *, int, const int);
22445 void vec_dstt (const unsigned long *, int, const int);
22446 void vec_dstt (const long *, int, const int);
22448 vector unsigned char vec_lvsl (int, const unsigned long *);
22449 vector unsigned char vec_lvsl (int, const long *);
22451 vector unsigned char vec_lvsr (int, const unsigned long *);
22452 vector unsigned char vec_lvsr (int, const long *);
22454 vector unsigned char vec_lvsl (int, const double *);
22455 vector unsigned char vec_lvsr (int, const double *);
22457 vector double vec_vsx_ld (int, const vector double *);
22458 vector double vec_vsx_ld (int, const double *);
22459 vector float vec_vsx_ld (int, const vector float *);
22460 vector float vec_vsx_ld (int, const float *);
22461 vector bool int vec_vsx_ld (int, const vector bool int *);
22462 vector signed int vec_vsx_ld (int, const vector signed int *);
22463 vector signed int vec_vsx_ld (int, const int *);
22464 vector signed int vec_vsx_ld (int, const long *);
22465 vector unsigned int vec_vsx_ld (int, const vector unsigned int *);
22466 vector unsigned int vec_vsx_ld (int, const unsigned int *);
22467 vector unsigned int vec_vsx_ld (int, const unsigned long *);
22468 vector bool short vec_vsx_ld (int, const vector bool short *);
22469 vector pixel vec_vsx_ld (int, const vector pixel *);
22470 vector signed short vec_vsx_ld (int, const vector signed short *);
22471 vector signed short vec_vsx_ld (int, const short *);
22472 vector unsigned short vec_vsx_ld (int, const vector unsigned short *);
22473 vector unsigned short vec_vsx_ld (int, const unsigned short *);
22474 vector bool char vec_vsx_ld (int, const vector bool char *);
22475 vector signed char vec_vsx_ld (int, const vector signed char *);
22476 vector signed char vec_vsx_ld (int, const signed char *);
22477 vector unsigned char vec_vsx_ld (int, const vector unsigned char *);
22478 vector unsigned char vec_vsx_ld (int, const unsigned char *);
22480 void vec_vsx_st (vector double, int, vector double *);
22481 void vec_vsx_st (vector double, int, double *);
22482 void vec_vsx_st (vector float, int, vector float *);
22483 void vec_vsx_st (vector float, int, float *);
22484 void vec_vsx_st (vector signed int, int, vector signed int *);
22485 void vec_vsx_st (vector signed int, int, int *);
22486 void vec_vsx_st (vector unsigned int, int, vector unsigned int *);
22487 void vec_vsx_st (vector unsigned int, int, unsigned int *);
22488 void vec_vsx_st (vector bool int, int, vector bool int *);
22489 void vec_vsx_st (vector bool int, int, unsigned int *);
22490 void vec_vsx_st (vector bool int, int, int *);
22491 void vec_vsx_st (vector signed short, int, vector signed short *);
22492 void vec_vsx_st (vector signed short, int, short *);
22493 void vec_vsx_st (vector unsigned short, int, vector unsigned short *);
22494 void vec_vsx_st (vector unsigned short, int, unsigned short *);
22495 void vec_vsx_st (vector bool short, int, vector bool short *);
22496 void vec_vsx_st (vector bool short, int, unsigned short *);
22497 void vec_vsx_st (vector pixel, int, vector pixel *);
22498 void vec_vsx_st (vector pixel, int, unsigned short *);
22499 void vec_vsx_st (vector pixel, int, short *);
22500 void vec_vsx_st (vector bool short, int, short *);
22501 void vec_vsx_st (vector signed char, int, vector signed char *);
22502 void vec_vsx_st (vector signed char, int, signed char *);
22503 void vec_vsx_st (vector unsigned char, int, vector unsigned char *);
22504 void vec_vsx_st (vector unsigned char, int, unsigned char *);
22505 void vec_vsx_st (vector bool char, int, vector bool char *);
22506 void vec_vsx_st (vector bool char, int, unsigned char *);
22507 void vec_vsx_st (vector bool char, int, signed char *);
22509 vector double vec_xxpermdi (vector double, vector double, const int);
22510 vector float vec_xxpermdi (vector float, vector float, const int);
22511 vector long long vec_xxpermdi (vector long long, vector long long, const int);
22512 vector unsigned long long vec_xxpermdi (vector unsigned long long,
22513 vector unsigned long long, const int);
22514 vector int vec_xxpermdi (vector int, vector int, const int);
22515 vector unsigned int vec_xxpermdi (vector unsigned int,
22516 vector unsigned int, const int);
22517 vector short vec_xxpermdi (vector short, vector short, const int);
22518 vector unsigned short vec_xxpermdi (vector unsigned short,
22519 vector unsigned short, const int);
22520 vector signed char vec_xxpermdi (vector signed char, vector signed char,
22522 vector unsigned char vec_xxpermdi (vector unsigned char,
22523 vector unsigned char, const int);
22525 vector double vec_xxsldi (vector double, vector double, int);
22526 vector float vec_xxsldi (vector float, vector float, int);
22527 vector long long vec_xxsldi (vector long long, vector long long, int);
22528 vector unsigned long long vec_xxsldi (vector unsigned long long,
22529 vector unsigned long long, int);
22530 vector int vec_xxsldi (vector int, vector int, int);
22531 vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int);
22532 vector short vec_xxsldi (vector short, vector short, int);
22533 vector unsigned short vec_xxsldi (vector unsigned short,
22534 vector unsigned short, int);
22535 vector signed char vec_xxsldi (vector signed char, vector signed char, int);
22536 vector unsigned char vec_xxsldi (vector unsigned char,
22537 vector unsigned char, int);
22540 Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always
22541 generate the AltiVec @samp{LVX} and @samp{STVX} instructions even
22542 if the VSX instruction set is available. The @samp{vec_vsx_ld} and
22543 @samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X},
22544 @samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions.
22546 @node PowerPC AltiVec Built-in Functions Available on ISA 2.07
22547 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07
22549 If the ISA 2.07 additions to the vector/scalar (power8-vector)
22550 instruction set are available, the following additional functions are
22551 available for both 32-bit and 64-bit targets. For 64-bit targets, you
22552 can use @var{vector long} instead of @var{vector long long},
22553 @var{vector bool long} instead of @var{vector bool long long}, and
22554 @var{vector unsigned long} instead of @var{vector unsigned long long}.
22556 Only functions excluded from the PVIPR are listed here.
22559 vector long long vec_vaddudm (vector long long, vector long long);
22560 vector long long vec_vaddudm (vector bool long long, vector long long);
22561 vector long long vec_vaddudm (vector long long, vector bool long long);
22562 vector unsigned long long vec_vaddudm (vector unsigned long long,
22563 vector unsigned long long);
22564 vector unsigned long long vec_vaddudm (vector bool unsigned long long,
22565 vector unsigned long long);
22566 vector unsigned long long vec_vaddudm (vector unsigned long long,
22567 vector bool unsigned long long);
22569 vector long long vec_vclz (vector long long);
22570 vector unsigned long long vec_vclz (vector unsigned long long);
22571 vector int vec_vclz (vector int);
22572 vector unsigned int vec_vclz (vector int);
22573 vector short vec_vclz (vector short);
22574 vector unsigned short vec_vclz (vector unsigned short);
22575 vector signed char vec_vclz (vector signed char);
22576 vector unsigned char vec_vclz (vector unsigned char);
22578 vector signed char vec_vclzb (vector signed char);
22579 vector unsigned char vec_vclzb (vector unsigned char);
22581 vector long long vec_vclzd (vector long long);
22582 vector unsigned long long vec_vclzd (vector unsigned long long);
22584 vector short vec_vclzh (vector short);
22585 vector unsigned short vec_vclzh (vector unsigned short);
22587 vector int vec_vclzw (vector int);
22588 vector unsigned int vec_vclzw (vector int);
22590 vector signed char vec_vgbbd (vector signed char);
22591 vector unsigned char vec_vgbbd (vector unsigned char);
22593 vector long long vec_vmaxsd (vector long long, vector long long);
22595 vector unsigned long long vec_vmaxud (vector unsigned long long,
22596 unsigned vector long long);
22598 vector long long vec_vminsd (vector long long, vector long long);
22600 vector unsigned long long vec_vminud (vector long long, vector long long);
22602 vector int vec_vpksdss (vector long long, vector long long);
22603 vector unsigned int vec_vpksdss (vector long long, vector long long);
22605 vector unsigned int vec_vpkudus (vector unsigned long long,
22606 vector unsigned long long);
22608 vector int vec_vpkudum (vector long long, vector long long);
22609 vector unsigned int vec_vpkudum (vector unsigned long long,
22610 vector unsigned long long);
22611 vector bool int vec_vpkudum (vector bool long long, vector bool long long);
22613 vector long long vec_vpopcnt (vector long long);
22614 vector unsigned long long vec_vpopcnt (vector unsigned long long);
22615 vector int vec_vpopcnt (vector int);
22616 vector unsigned int vec_vpopcnt (vector int);
22617 vector short vec_vpopcnt (vector short);
22618 vector unsigned short vec_vpopcnt (vector unsigned short);
22619 vector signed char vec_vpopcnt (vector signed char);
22620 vector unsigned char vec_vpopcnt (vector unsigned char);
22622 vector signed char vec_vpopcntb (vector signed char);
22623 vector unsigned char vec_vpopcntb (vector unsigned char);
22625 vector long long vec_vpopcntd (vector long long);
22626 vector unsigned long long vec_vpopcntd (vector unsigned long long);
22628 vector short vec_vpopcnth (vector short);
22629 vector unsigned short vec_vpopcnth (vector unsigned short);
22631 vector int vec_vpopcntw (vector int);
22632 vector unsigned int vec_vpopcntw (vector int);
22634 vector long long vec_vrld (vector long long, vector unsigned long long);
22635 vector unsigned long long vec_vrld (vector unsigned long long,
22636 vector unsigned long long);
22638 vector long long vec_vsld (vector long long, vector unsigned long long);
22639 vector long long vec_vsld (vector unsigned long long,
22640 vector unsigned long long);
22642 vector long long vec_vsrad (vector long long, vector unsigned long long);
22643 vector unsigned long long vec_vsrad (vector unsigned long long,
22644 vector unsigned long long);
22646 vector long long vec_vsrd (vector long long, vector unsigned long long);
22647 vector unsigned long long char vec_vsrd (vector unsigned long long,
22648 vector unsigned long long);
22650 vector long long vec_vsubudm (vector long long, vector long long);
22651 vector long long vec_vsubudm (vector bool long long, vector long long);
22652 vector long long vec_vsubudm (vector long long, vector bool long long);
22653 vector unsigned long long vec_vsubudm (vector unsigned long long,
22654 vector unsigned long long);
22655 vector unsigned long long vec_vsubudm (vector bool long long,
22656 vector unsigned long long);
22657 vector unsigned long long vec_vsubudm (vector unsigned long long,
22658 vector bool long long);
22660 vector long long vec_vupkhsw (vector int);
22661 vector unsigned long long vec_vupkhsw (vector unsigned int);
22663 vector long long vec_vupklsw (vector int);
22664 vector unsigned long long vec_vupklsw (vector int);
22667 If the ISA 2.07 additions to the vector/scalar (power8-vector)
22668 instruction set are available, the following additional functions are
22669 available for 64-bit targets. New vector types
22670 (@var{vector __int128} and @var{vector __uint128}) are available
22671 to hold the @var{__int128} and @var{__uint128} types to use these
22674 The normal vector extract, and set operations work on
22675 @var{vector __int128} and @var{vector __uint128} types,
22676 but the index value must be 0.
22678 Only functions excluded from the PVIPR are listed here.
22681 vector __int128 vec_vaddcuq (vector __int128, vector __int128);
22682 vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128);
22684 vector __int128 vec_vadduqm (vector __int128, vector __int128);
22685 vector __uint128 vec_vadduqm (vector __uint128, vector __uint128);
22687 vector __int128 vec_vaddecuq (vector __int128, vector __int128,
22689 vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128,
22692 vector __int128 vec_vaddeuqm (vector __int128, vector __int128,
22694 vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128,
22697 vector __int128 vec_vsubecuq (vector __int128, vector __int128,
22699 vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128,
22702 vector __int128 vec_vsubeuqm (vector __int128, vector __int128,
22704 vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128,
22707 vector __int128 vec_vsubcuq (vector __int128, vector __int128);
22708 vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128);
22710 __int128 vec_vsubuqm (__int128, __int128);
22711 __uint128 vec_vsubuqm (__uint128, __uint128);
22713 vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int);
22714 vector unsigned char __builtin_bcdadd (vector unsigned char, vector unsigned char,
22716 int __builtin_bcdadd_lt (vector __int128, vector __int128, const int);
22717 int __builtin_bcdadd_lt (vector unsigned char, vector unsigned char, const int);
22718 int __builtin_bcdadd_eq (vector __int128, vector __int128, const int);
22719 int __builtin_bcdadd_eq (vector unsigned char, vector unsigned char, const int);
22720 int __builtin_bcdadd_gt (vector __int128, vector __int128, const int);
22721 int __builtin_bcdadd_gt (vector unsigned char, vector unsigned char, const int);
22722 int __builtin_bcdadd_ov (vector __int128, vector __int128, const int);
22723 int __builtin_bcdadd_ov (vector unsigned char, vector unsigned char, const int);
22725 vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int);
22726 vector unsigned char __builtin_bcdsub (vector unsigned char, vector unsigned char,
22728 int __builtin_bcdsub_le (vector __int128, vector __int128, const int);
22729 int __builtin_bcdsub_le (vector unsigned char, vector unsigned char, const int);
22730 int __builtin_bcdsub_lt (vector __int128, vector __int128, const int);
22731 int __builtin_bcdsub_lt (vector unsigned char, vector unsigned char, const int);
22732 int __builtin_bcdsub_eq (vector __int128, vector __int128, const int);
22733 int __builtin_bcdsub_eq (vector unsigned char, vector unsigned char, const int);
22734 int __builtin_bcdsub_gt (vector __int128, vector __int128, const int);
22735 int __builtin_bcdsub_gt (vector unsigned char, vector unsigned char, const int);
22736 int __builtin_bcdsub_ge (vector __int128, vector __int128, const int);
22737 int __builtin_bcdsub_ge (vector unsigned char, vector unsigned char, const int);
22738 int __builtin_bcdsub_ov (vector __int128, vector __int128, const int);
22739 int __builtin_bcdsub_ov (vector unsigned char, vector unsigned char, const int);
22742 @node PowerPC AltiVec Built-in Functions Available on ISA 3.0
22743 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0
22745 The following additional built-in functions are also available for the
22746 PowerPC family of processors, starting with ISA 3.0
22747 (@option{-mcpu=power9}) or later.
22749 Only instructions excluded from the PVIPR are listed here.
22752 unsigned int scalar_extract_exp (double source);
22753 unsigned long long int scalar_extract_exp (__ieee128 source);
22755 unsigned long long int scalar_extract_sig (double source);
22756 unsigned __int128 scalar_extract_sig (__ieee128 source);
22758 double scalar_insert_exp (unsigned long long int significand,
22759 unsigned long long int exponent);
22760 double scalar_insert_exp (double significand, unsigned long long int exponent);
22762 ieee_128 scalar_insert_exp (unsigned __int128 significand,
22763 unsigned long long int exponent);
22764 ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent);
22765 vector ieee_128 scalar_insert_exp (vector unsigned __int128 significand,
22766 vector unsigned long long exponent);
22767 vector unsigned long long scalar_extract_exp_to_vec (ieee_128);
22768 vector unsigned __int128 scalar_extract_sig_to_vec (ieee_128);
22770 int scalar_cmp_exp_gt (double arg1, double arg2);
22771 int scalar_cmp_exp_lt (double arg1, double arg2);
22772 int scalar_cmp_exp_eq (double arg1, double arg2);
22773 int scalar_cmp_exp_unordered (double arg1, double arg2);
22775 bool scalar_test_data_class (float source, const int condition);
22776 bool scalar_test_data_class (double source, const int condition);
22777 bool scalar_test_data_class (__ieee128 source, const int condition);
22779 bool scalar_test_neg (float source);
22780 bool scalar_test_neg (double source);
22781 bool scalar_test_neg (__ieee128 source);
22784 The @code{scalar_extract_exp} with a 64-bit source argument
22785 function requires an environment supporting ISA 3.0 or later.
22786 The @code{scalar_extract_exp} with a 128-bit source argument
22787 and @code{scalar_extract_sig}
22788 functions require a 64-bit environment supporting ISA 3.0 or later.
22789 The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in
22790 functions return the significand and the biased exponent value
22791 respectively of their @code{source} arguments.
22792 When supplied with a 64-bit @code{source} argument, the
22793 result returned by @code{scalar_extract_sig} has
22794 the @code{0x0010000000000000} bit set if the
22795 function's @code{source} argument is in normalized form.
22796 Otherwise, this bit is set to 0.
22797 When supplied with a 128-bit @code{source} argument, the
22798 @code{0x00010000000000000000000000000000} bit of the result is
22800 Note that the sign of the significand is not represented in the result
22801 returned from the @code{scalar_extract_sig} function. Use the
22802 @code{scalar_test_neg} function to test the sign of its @code{double}
22805 The @code{scalar_insert_exp}
22806 functions require a 64-bit environment supporting ISA 3.0 or later.
22807 When supplied with a 64-bit first argument, the
22808 @code{scalar_insert_exp} built-in function returns a double-precision
22809 floating point value that is constructed by assembling the values of its
22810 @code{significand} and @code{exponent} arguments. The sign of the
22811 result is copied from the most significant bit of the
22812 @code{significand} argument. The significand and exponent components
22813 of the result are composed of the least significant 11 bits of the
22814 @code{exponent} argument and the least significant 52 bits of the
22815 @code{significand} argument respectively.
22817 When supplied with a 128-bit first argument, the
22818 @code{scalar_insert_exp} built-in function returns a quad-precision
22819 IEEE floating point value if the two arguments were scalar. If the two
22820 arguments are vectors, the return value is a vector IEEE floating point value.
22821 The sign bit of the result is copied from the most significant bit of the
22822 @code{significand} argument. The significand and exponent components of the
22823 result are composed of the least significant 15 bits of the @code{exponent}
22824 argument (element 0 on big-endian and element 1 on little-endian) and the
22825 least significant 112 bits of the @code{significand} argument
22826 respectively. Note, the @code{significand} is the scalar argument or in the
22827 case of vector arguments, @code{significand} is element 0 for big-endian and
22828 element 1 for little-endian.
22830 The @code{scalar_extract_exp_to_vec},
22831 and @code{scalar_extract_sig_to_vec} are similar to
22832 @code{scalar_extract_exp}, @code{scalar_extract_sig} except they return
22833 a vector result of type unsigned long long and unsigned __int128 respectively.
22835 The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt},
22836 @code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in
22837 functions return a non-zero value if @code{arg1} is greater than, less
22838 than, equal to, or not comparable to @code{arg2} respectively. The
22839 arguments are not comparable if one or the other equals NaN (not a
22842 The @code{scalar_test_data_class} built-in function returns 1
22843 if any of the condition tests enabled by the value of the
22844 @code{condition} variable are true, and 0 otherwise. The
22845 @code{condition} argument must be a compile-time constant integer with
22846 value not exceeding 127. The
22847 @code{condition} argument is encoded as a bitmask with each bit
22848 enabling the testing of a different condition, as characterized by the
22852 0x20 Test for +Infinity
22853 0x10 Test for -Infinity
22854 0x08 Test for +Zero
22855 0x04 Test for -Zero
22856 0x02 Test for +Denormal
22857 0x01 Test for -Denormal
22860 The @code{scalar_test_neg} built-in function returns 1 if its
22861 @code{source} argument holds a negative value, 0 otherwise.
22863 The following built-in functions are also available for the PowerPC family
22864 of processors, starting with ISA 3.0 or later
22865 (@option{-mcpu=power9}). These string functions are described
22866 separately in order to group the descriptions closer to the function
22869 Only functions excluded from the PVIPR are listed here.
22872 int vec_all_nez (vector signed char, vector signed char);
22873 int vec_all_nez (vector unsigned char, vector unsigned char);
22874 int vec_all_nez (vector signed short, vector signed short);
22875 int vec_all_nez (vector unsigned short, vector unsigned short);
22876 int vec_all_nez (vector signed int, vector signed int);
22877 int vec_all_nez (vector unsigned int, vector unsigned int);
22879 int vec_any_eqz (vector signed char, vector signed char);
22880 int vec_any_eqz (vector unsigned char, vector unsigned char);
22881 int vec_any_eqz (vector signed short, vector signed short);
22882 int vec_any_eqz (vector unsigned short, vector unsigned short);
22883 int vec_any_eqz (vector signed int, vector signed int);
22884 int vec_any_eqz (vector unsigned int, vector unsigned int);
22886 signed char vec_xlx (unsigned int index, vector signed char data);
22887 unsigned char vec_xlx (unsigned int index, vector unsigned char data);
22888 signed short vec_xlx (unsigned int index, vector signed short data);
22889 unsigned short vec_xlx (unsigned int index, vector unsigned short data);
22890 signed int vec_xlx (unsigned int index, vector signed int data);
22891 unsigned int vec_xlx (unsigned int index, vector unsigned int data);
22892 float vec_xlx (unsigned int index, vector float data);
22894 signed char vec_xrx (unsigned int index, vector signed char data);
22895 unsigned char vec_xrx (unsigned int index, vector unsigned char data);
22896 signed short vec_xrx (unsigned int index, vector signed short data);
22897 unsigned short vec_xrx (unsigned int index, vector unsigned short data);
22898 signed int vec_xrx (unsigned int index, vector signed int data);
22899 unsigned int vec_xrx (unsigned int index, vector unsigned int data);
22900 float vec_xrx (unsigned int index, vector float data);
22903 The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez}
22904 perform pairwise comparisons between the elements at the same
22905 positions within their two vector arguments.
22906 The @code{vec_all_nez} function returns a
22907 non-zero value if and only if all pairwise comparisons are not
22908 equal and no element of either vector argument contains a zero.
22909 The @code{vec_any_eqz} function returns a
22910 non-zero value if and only if at least one pairwise comparison is equal
22911 or if at least one element of either vector argument contains a zero.
22912 The @code{vec_cmpnez} function returns a vector of the same type as
22913 its two arguments, within which each element consists of all ones to
22914 denote that either the corresponding elements of the incoming arguments are
22915 not equal or that at least one of the corresponding elements contains
22916 zero. Otherwise, the element of the returned vector contains all zeros.
22918 The @code{vec_xlx} and @code{vec_xrx} functions extract the single
22919 element selected by the @code{index} argument from the vector
22920 represented by the @code{data} argument. The @code{index} argument
22921 always specifies a byte offset, regardless of the size of the vector
22922 element. With @code{vec_xlx}, @code{index} is the offset of the first
22923 byte of the element to be extracted. With @code{vec_xrx}, @code{index}
22924 represents the last byte of the element to be extracted, measured
22925 from the right end of the vector. In other words, the last byte of
22926 the element to be extracted is found at position @code{(15 - index)}.
22927 There is no requirement that @code{index} be a multiple of the vector
22928 element size. However, if the size of the vector element added to
22929 @code{index} is greater than 15, the content of the returned value is
22932 The following functions are also available if the ISA 3.0 instruction
22933 set additions (@option{-mcpu=power9}) are available.
22935 Only functions excluded from the PVIPR are listed here.
22938 vector long long vec_vctz (vector long long);
22939 vector unsigned long long vec_vctz (vector unsigned long long);
22940 vector int vec_vctz (vector int);
22941 vector unsigned int vec_vctz (vector int);
22942 vector short vec_vctz (vector short);
22943 vector unsigned short vec_vctz (vector unsigned short);
22944 vector signed char vec_vctz (vector signed char);
22945 vector unsigned char vec_vctz (vector unsigned char);
22947 vector signed char vec_vctzb (vector signed char);
22948 vector unsigned char vec_vctzb (vector unsigned char);
22950 vector long long vec_vctzd (vector long long);
22951 vector unsigned long long vec_vctzd (vector unsigned long long);
22953 vector short vec_vctzh (vector short);
22954 vector unsigned short vec_vctzh (vector unsigned short);
22956 vector int vec_vctzw (vector int);
22957 vector unsigned int vec_vctzw (vector int);
22959 vector int vec_vprtyb (vector int);
22960 vector unsigned int vec_vprtyb (vector unsigned int);
22961 vector long long vec_vprtyb (vector long long);
22962 vector unsigned long long vec_vprtyb (vector unsigned long long);
22964 vector int vec_vprtybw (vector int);
22965 vector unsigned int vec_vprtybw (vector unsigned int);
22967 vector long long vec_vprtybd (vector long long);
22968 vector unsigned long long vec_vprtybd (vector unsigned long long);
22971 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9})
22975 vector long vec_vprtyb (vector long);
22976 vector unsigned long vec_vprtyb (vector unsigned long);
22977 vector __int128 vec_vprtyb (vector __int128);
22978 vector __uint128 vec_vprtyb (vector __uint128);
22980 vector long vec_vprtybd (vector long);
22981 vector unsigned long vec_vprtybd (vector unsigned long);
22983 vector __int128 vec_vprtybq (vector __int128);
22984 vector __uint128 vec_vprtybd (vector __uint128);
22987 The following built-in functions are available for the PowerPC family
22988 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}).
22990 Only functions excluded from the PVIPR are listed here.
22993 __vector unsigned char
22994 vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2);
22995 __vector unsigned short
22996 vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2);
22997 __vector unsigned int
22998 vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2);
23001 The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and
23002 @code{vec_absdw} built-in functions each computes the absolute
23003 differences of the pairs of vector elements supplied in its two vector
23004 arguments, placing the absolute differences into the corresponding
23005 elements of the vector result.
23007 The following built-in functions are available for the PowerPC family
23008 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}):
23010 vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int);
23011 vector unsigned long long vec_vrlnm (vector unsigned long long,
23012 vector unsigned long long);
23015 The result of @code{vec_vrlnm} is obtained by rotating each element
23016 of the first argument vector left and ANDing it with a mask. The
23017 second argument vector contains the mask beginning in bits 11:15,
23018 the mask end in bits 19:23, and the shift count in bits 27:31,
23021 If the cryptographic instructions are enabled (@option{-mcrypto} or
23022 @option{-mcpu=power8}), the following builtins are enabled.
23024 Only functions excluded from the PVIPR are listed here.
23027 vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long);
23029 vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long,
23030 vector unsigned long long);
23032 vector unsigned long long __builtin_crypto_vcipherlast
23033 (vector unsigned long long,
23034 vector unsigned long long);
23036 vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long,
23037 vector unsigned long long);
23039 vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long,
23040 vector unsigned long long);
23042 vector unsigned char __builtin_crypto_vpermxor (vector unsigned char,
23043 vector unsigned char,
23044 vector unsigned char);
23046 vector unsigned short __builtin_crypto_vpermxor (vector unsigned short,
23047 vector unsigned short,
23048 vector unsigned short);
23050 vector unsigned int __builtin_crypto_vpermxor (vector unsigned int,
23051 vector unsigned int,
23052 vector unsigned int);
23054 vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long,
23055 vector unsigned long long,
23056 vector unsigned long long);
23058 vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char,
23059 vector unsigned char);
23061 vector unsigned short __builtin_crypto_vpmsumh (vector unsigned short,
23062 vector unsigned short);
23064 vector unsigned int __builtin_crypto_vpmsumw (vector unsigned int,
23065 vector unsigned int);
23067 vector unsigned long long __builtin_crypto_vpmsumd (vector unsigned long long,
23068 vector unsigned long long);
23070 vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long,
23073 vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int);
23076 The second argument to @var{__builtin_crypto_vshasigmad} and
23077 @var{__builtin_crypto_vshasigmaw} must be a constant
23078 integer that is 0 or 1. The third argument to these built-in functions
23079 must be a constant integer in the range of 0 to 15.
23081 The following sign extension builtins are provided:
23084 vector signed int vec_signexti (vector signed char a);
23085 vector signed long long vec_signextll (vector signed char a);
23086 vector signed int vec_signexti (vector signed short a);
23087 vector signed long long vec_signextll (vector signed short a);
23088 vector signed long long vec_signextll (vector signed int a);
23089 vector signed long long vec_signextq (vector signed long long a);
23092 Each element of the result is produced by sign-extending the element of the
23093 input vector that would fall in the least significant portion of the result
23094 element. For example, a sign-extension of a vector signed char to a vector
23095 signed long long will sign extend the rightmost byte of each doubleword.
23097 @node PowerPC AltiVec Built-in Functions Available on ISA 3.1
23098 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.1
23100 The following additional built-in functions are also available for the
23101 PowerPC family of processors, starting with ISA 3.1 (@option{-mcpu=power10}):
23105 @exdent vector unsigned long long int
23106 @exdent vec_cfuge (vector unsigned long long int, vector unsigned long long int);
23108 Perform a vector centrifuge operation, as if implemented by the
23109 @code{vcfuged} instruction.
23113 @exdent vector unsigned long long int
23114 @exdent vec_cntlzm (vector unsigned long long int, vector unsigned long long int);
23116 Perform a vector count leading zeros under bit mask operation, as if
23117 implemented by the @code{vclzdm} instruction.
23121 @exdent vector unsigned long long int
23122 @exdent vec_cnttzm (vector unsigned long long int, vector unsigned long long int);
23124 Perform a vector count trailing zeros under bit mask operation, as if
23125 implemented by the @code{vctzdm} instruction.
23129 @exdent vector signed char
23130 @exdent vec_clrl (vector signed char @var{a}, unsigned int @var{n});
23131 @exdent vector unsigned char
23132 @exdent vec_clrl (vector unsigned char @var{a}, unsigned int @var{n});
23134 Clear the left-most @code{(16 - n)} bytes of vector argument @code{a}, as if
23135 implemented by the @code{vclrlb} instruction on a big-endian target
23136 and by the @code{vclrrb} instruction on a little-endian target. A
23137 value of @code{n} that is greater than 16 is treated as if it equaled 16.
23141 @exdent vector signed char
23142 @exdent vec_clrr (vector signed char @var{a}, unsigned int @var{n});
23143 @exdent vector unsigned char
23144 @exdent vec_clrr (vector unsigned char @var{a}, unsigned int @var{n});
23146 Clear the right-most @code{(16 - n)} bytes of vector argument @code{a}, as if
23147 implemented by the @code{vclrrb} instruction on a big-endian target
23148 and by the @code{vclrlb} instruction on a little-endian target. A
23149 value of @code{n} that is greater than 16 is treated as if it equaled 16.
23153 @exdent vector unsigned long long int
23154 @exdent vec_gnb (vector unsigned __int128, const unsigned char);
23156 Perform a 128-bit vector gather operation, as if implemented by the
23157 @code{vgnb} instruction. The second argument must be a literal
23158 integer value between 2 and 7 inclusive.
23165 @exdent vector unsigned long long int
23166 @exdent vec_extractl (vector unsigned char, vector unsigned char, unsigned int);
23167 @exdent vector unsigned long long int
23168 @exdent vec_extractl (vector unsigned short, vector unsigned short, unsigned int);
23169 @exdent vector unsigned long long int
23170 @exdent vec_extractl (vector unsigned int, vector unsigned int, unsigned int);
23171 @exdent vector unsigned long long int
23172 @exdent vec_extractl (vector unsigned long long, vector unsigned long long, unsigned int);
23174 Extract an element from two concatenated vectors starting at the given byte index
23175 in natural-endian order, and place it zero-extended in doubleword 1 of the result
23176 according to natural element order. If the byte index is out of range for the
23177 data type, the intrinsic will be rejected.
23178 For little-endian, this output will match the placement by the hardware
23179 instruction, i.e., dword[0] in RTL notation. For big-endian, an additional
23180 instruction is needed to move it from the "left" doubleword to the "right" one.
23181 For little-endian, semantics matching the @code{vextdubvrx},
23182 @code{vextduhvrx}, @code{vextduwvrx} instruction will be generated, while for
23183 big-endian, semantics matching the @code{vextdubvlx}, @code{vextduhvlx},
23184 @code{vextduwvlx} instructions
23185 will be generated. Note that some fairly anomalous results can be generated if
23186 the byte index is not aligned on an element boundary for the element being
23187 extracted. This is a limitation of the bi-endian vector programming model is
23188 consistent with the limitation on @code{vec_perm}.
23189 @findex vec_extractl
23192 @exdent vector unsigned long long int
23193 @exdent vec_extracth (vector unsigned char, vector unsigned char, unsigned int);
23194 @exdent vector unsigned long long int
23195 @exdent vec_extracth (vector unsigned short, vector unsigned short,
23197 @exdent vector unsigned long long int
23198 @exdent vec_extracth (vector unsigned int, vector unsigned int, unsigned int);
23199 @exdent vector unsigned long long int
23200 @exdent vec_extracth (vector unsigned long long, vector unsigned long long,
23203 Extract an element from two concatenated vectors starting at the given byte
23204 index. The index is based on big endian order for a little endian system.
23205 Similarly, the index is based on little endian order for a big endian system.
23206 The extraced elements are zero-extended and put in doubleword 1
23207 according to natural element order. If the byte index is out of range for the
23208 data type, the intrinsic will be rejected. For little-endian, this output
23209 will match the placement by the hardware instruction (vextdubvrx, vextduhvrx,
23210 vextduwvrx, vextddvrx) i.e., dword[0] in RTL
23211 notation. For big-endian, an additional instruction is needed to move it
23212 from the "left" doubleword to the "right" one. For little-endian, semantics
23213 matching the @code{vextdubvlx}, @code{vextduhvlx}, @code{vextduwvlx}
23214 instructions will be generated, while for big-endian, semantics matching the
23215 @code{vextdubvrx}, @code{vextduhvrx}, @code{vextduwvrx} instructions will
23216 be generated. Note that some fairly anomalous
23217 results can be generated if the byte index is not aligned on the
23218 element boundary for the element being extracted. This is a
23219 limitation of the bi-endian vector programming model consistent with the
23220 limitation on @code{vec_perm}.
23221 @findex vec_extracth
23223 @exdent vector unsigned long long int
23224 @exdent vec_pdep (vector unsigned long long int, vector unsigned long long int);
23226 Perform a vector parallel bits deposit operation, as if implemented by
23227 the @code{vpdepd} instruction.
23233 @exdent vector unsigned char
23234 @exdent vec_insertl (unsigned char, vector unsigned char, unsigned int);
23235 @exdent vector unsigned short
23236 @exdent vec_insertl (unsigned short, vector unsigned short, unsigned int);
23237 @exdent vector unsigned int
23238 @exdent vec_insertl (unsigned int, vector unsigned int, unsigned int);
23239 @exdent vector unsigned long long
23240 @exdent vec_insertl (unsigned long long, vector unsigned long long,
23242 @exdent vector unsigned char
23243 @exdent vec_insertl (vector unsigned char, vector unsigned char, unsigned int;
23244 @exdent vector unsigned short
23245 @exdent vec_insertl (vector unsigned short, vector unsigned short,
23247 @exdent vector unsigned int
23248 @exdent vec_insertl (vector unsigned int, vector unsigned int, unsigned int);
23251 Let src be the first argument, when the first argument is a scalar, or the
23252 rightmost element of the left doubleword of the first argument, when the first
23253 argument is a vector. Insert the source into the destination at the position
23254 given by the third argument, using natural element order in the second
23255 argument. The rest of the second argument is unchanged. If the byte
23256 index is greater than 14 for halfwords, greater than 12 for words, or
23257 greater than 8 for doublewords the result is undefined. For little-endian,
23258 the generated code will be semantically equivalent to @code{vins[bhwd]rx}
23259 instructions. Similarly for big-endian it will be semantically equivalent
23260 to @code{vins[bhwd]lx}. Note that some fairly anomalous results can be
23261 generated if the byte index is not aligned on an element boundary for the
23262 type of element being inserted.
23263 @findex vec_insertl
23266 @exdent vector unsigned char
23267 @exdent vec_inserth (unsigned char, vector unsigned char, unsigned int);
23268 @exdent vector unsigned short
23269 @exdent vec_inserth (unsigned short, vector unsigned short, unsigned int);
23270 @exdent vector unsigned int
23271 @exdent vec_inserth (unsigned int, vector unsigned int, unsigned int);
23272 @exdent vector unsigned long long
23273 @exdent vec_inserth (unsigned long long, vector unsigned long long,
23275 @exdent vector unsigned char
23276 @exdent vec_inserth (vector unsigned char, vector unsigned char, unsigned int);
23277 @exdent vector unsigned short
23278 @exdent vec_inserth (vector unsigned short, vector unsigned short,
23280 @exdent vector unsigned int
23281 @exdent vec_inserth (vector unsigned int, vector unsigned int, unsigned int);
23284 Let src be the first argument, when the first argument is a scalar, or the
23285 rightmost element of the first argument, when the first argument is a vector.
23286 Insert src into the second argument at the position identified by the third
23287 argument, using opposite element order in the second argument, and leaving the
23288 rest of the second argument unchanged. If the byte index is greater than 14
23289 for halfwords, 12 for words, or 8 for doublewords, the intrinsic will be
23290 rejected. Note that the underlying hardware instruction uses the same register
23291 for the second argument and the result.
23292 For little-endian, the code generation will be semantically equivalent to
23293 @code{vins[bhwd]lx}, while for big-endian it will be semantically equivalent to
23294 @code{vins[bhwd]rx}.
23295 Note that some fairly anomalous results can be generated if the byte index is
23296 not aligned on an element boundary for the sort of element being inserted.
23297 @findex vec_inserth
23299 Vector Replace Element
23301 @exdent vector signed int vec_replace_elt (vector signed int, signed int,
23303 @exdent vector unsigned int vec_replace_elt (vector unsigned int,
23304 unsigned int, const int);
23305 @exdent vector float vec_replace_elt (vector float, float, const int);
23306 @exdent vector signed long long vec_replace_elt (vector signed long long,
23307 signed long long, const int);
23308 @exdent vector unsigned long long vec_replace_elt (vector unsigned long long,
23309 unsigned long long, const int);
23310 @exdent vector double rec_replace_elt (vector double, double, const int);
23312 The third argument (constrained to [0,3]) identifies the natural-endian
23313 element number of the first argument that will be replaced by the second
23314 argument to produce the result. The other elements of the first argument will
23315 remain unchanged in the result.
23317 If it's desirable to insert a word at an unaligned position, use
23318 vec_replace_unaligned instead.
23320 @findex vec_replace_element
23322 Vector Replace Unaligned
23324 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
23325 signed int, const int);
23326 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
23327 unsigned int, const int);
23328 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
23330 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
23331 signed long long, const int);
23332 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
23333 unsigned long long, const int);
23334 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char,
23335 double, const int);
23338 The second argument replaces a portion of the first argument to produce the
23339 result, with the rest of the first argument unchanged in the result. The
23340 third argument identifies the byte index (using left-to-right, or big-endian
23341 order) where the high-order byte of the second argument will be placed, with
23342 the remaining bytes of the second argument placed naturally "to the right"
23343 of the high-order byte.
23345 The programmer is responsible for understanding the endianness issues involved
23346 with the first argument and the result.
23347 @findex vec_replace_unaligned
23349 Vector Shift Left Double Bit Immediate
23351 @exdent vector signed char vec_sldb (vector signed char, vector signed char,
23352 const unsigned int);
23353 @exdent vector unsigned char vec_sldb (vector unsigned char,
23354 vector unsigned char, const unsigned int);
23355 @exdent vector signed short vec_sldb (vector signed short, vector signed short,
23356 const unsigned int);
23357 @exdent vector unsigned short vec_sldb (vector unsigned short,
23358 vector unsigned short, const unsigned int);
23359 @exdent vector signed int vec_sldb (vector signed int, vector signed int,
23360 const unsigned int);
23361 @exdent vector unsigned int vec_sldb (vector unsigned int, vector unsigned int,
23362 const unsigned int);
23363 @exdent vector signed long long vec_sldb (vector signed long long,
23364 vector signed long long, const unsigned int);
23365 @exdent vector unsigned long long vec_sldb (vector unsigned long long,
23366 vector unsigned long long, const unsigned int);
23369 Shift the combined input vectors left by the amount specified by the low-order
23370 three bits of the third argument, and return the leftmost remaining 128 bits.
23371 Code using this instruction must be endian-aware.
23375 Vector Shift Right Double Bit Immediate
23378 @exdent vector signed char vec_srdb (vector signed char, vector signed char,
23379 const unsigned int);
23380 @exdent vector unsigned char vec_srdb (vector unsigned char, vector unsigned char,
23381 const unsigned int);
23382 @exdent vector signed short vec_srdb (vector signed short, vector signed short,
23383 const unsigned int);
23384 @exdent vector unsigned short vec_srdb (vector unsigned short, vector unsigned short,
23385 const unsigned int);
23386 @exdent vector signed int vec_srdb (vector signed int, vector signed int,
23387 const unsigned int);
23388 @exdent vector unsigned int vec_srdb (vector unsigned int, vector unsigned int,
23389 const unsigned int);
23390 @exdent vector signed long long vec_srdb (vector signed long long,
23391 vector signed long long, const unsigned int);
23392 @exdent vector unsigned long long vec_srdb (vector unsigned long long,
23393 vector unsigned long long, const unsigned int);
23396 Shift the combined input vectors right by the amount specified by the low-order
23397 three bits of the third argument, and return the remaining 128 bits. Code
23398 using this built-in must be endian-aware.
23405 @exdent vector signed int vec_splati (const signed int);
23406 @exdent vector float vec_splati (const float);
23409 Splat a 32-bit immediate into a vector of words.
23414 @exdent vector double vec_splatid (const float);
23417 Convert a single precision floating-point value to double-precision and splat
23418 the result to a vector of double-precision floats.
23420 @findex vec_splatid
23423 @exdent vector signed int vec_splati_ins (vector signed int,
23424 const unsigned int, const signed int);
23425 @exdent vector unsigned int vec_splati_ins (vector unsigned int,
23426 const unsigned int, const unsigned int);
23427 @exdent vector float vec_splati_ins (vector float, const unsigned int,
23431 Argument 2 must be either 0 or 1. Splat the value of argument 3 into the word
23432 identified by argument 2 of each doubleword of argument 1 and return the
23433 result. The other words of argument 1 are unchanged.
23435 @findex vec_splati_ins
23437 Vector Blend Variable
23440 @exdent vector signed char vec_blendv (vector signed char, vector signed char,
23441 vector unsigned char);
23442 @exdent vector unsigned char vec_blendv (vector unsigned char,
23443 vector unsigned char, vector unsigned char);
23444 @exdent vector signed short vec_blendv (vector signed short,
23445 vector signed short, vector unsigned short);
23446 @exdent vector unsigned short vec_blendv (vector unsigned short,
23447 vector unsigned short, vector unsigned short);
23448 @exdent vector signed int vec_blendv (vector signed int, vector signed int,
23449 vector unsigned int);
23450 @exdent vector unsigned int vec_blendv (vector unsigned int,
23451 vector unsigned int, vector unsigned int);
23452 @exdent vector signed long long vec_blendv (vector signed long long,
23453 vector signed long long, vector unsigned long long);
23454 @exdent vector unsigned long long vec_blendv (vector unsigned long long,
23455 vector unsigned long long, vector unsigned long long);
23456 @exdent vector float vec_blendv (vector float, vector float,
23457 vector unsigned int);
23458 @exdent vector double vec_blendv (vector double, vector double,
23459 vector unsigned long long);
23462 Blend the first and second argument vectors according to the sign bits of the
23463 corresponding elements of the third argument vector. This is similar to the
23464 @code{vsel} and @code{xxsel} instructions but for bigger elements.
23468 Vector Permute Extended
23471 @exdent vector signed char vec_permx (vector signed char, vector signed char,
23472 vector unsigned char, const int);
23473 @exdent vector unsigned char vec_permx (vector unsigned char,
23474 vector unsigned char, vector unsigned char, const int);
23475 @exdent vector signed short vec_permx (vector signed short,
23476 vector signed short, vector unsigned char, const int);
23477 @exdent vector unsigned short vec_permx (vector unsigned short,
23478 vector unsigned short, vector unsigned char, const int);
23479 @exdent vector signed int vec_permx (vector signed int, vector signed int,
23480 vector unsigned char, const int);
23481 @exdent vector unsigned int vec_permx (vector unsigned int,
23482 vector unsigned int, vector unsigned char, const int);
23483 @exdent vector signed long long vec_permx (vector signed long long,
23484 vector signed long long, vector unsigned char, const int);
23485 @exdent vector unsigned long long vec_permx (vector unsigned long long,
23486 vector unsigned long long, vector unsigned char, const int);
23487 @exdent vector float (vector float, vector float, vector unsigned char,
23489 @exdent vector double (vector double, vector double, vector unsigned char,
23493 Perform a partial permute of the first two arguments, which form a 32-byte
23494 section of an emulated vector up to 256 bytes wide, using the partial permute
23495 control vector in the third argument. The fourth argument (constrained to
23496 values of 0-7) identifies which 32-byte section of the emulated vector is
23497 contained in the first two arguments.
23501 @exdent vector unsigned long long int
23502 @exdent vec_pext (vector unsigned long long int, vector unsigned long long int);
23504 Perform a vector parallel bit extract operation, as if implemented by
23505 the @code{vpextd} instruction.
23509 @exdent vector unsigned char vec_stril (vector unsigned char);
23510 @exdent vector signed char vec_stril (vector signed char);
23511 @exdent vector unsigned short vec_stril (vector unsigned short);
23512 @exdent vector signed short vec_stril (vector signed short);
23514 Isolate the left-most non-zero elements of the incoming vector argument,
23515 replacing all elements to the right of the left-most zero element
23516 found within the argument with zero. The typical implementation uses
23517 the @code{vstribl} or @code{vstrihl} instruction on big-endian targets
23518 and uses the @code{vstribr} or @code{vstrihr} instruction on
23519 little-endian targets.
23523 @exdent int vec_stril_p (vector unsigned char);
23524 @exdent int vec_stril_p (vector signed char);
23525 @exdent int short vec_stril_p (vector unsigned short);
23526 @exdent int vec_stril_p (vector signed short);
23528 Return a non-zero value if and only if the argument contains a zero
23529 element. The typical implementation uses
23530 the @code{vstribl.} or @code{vstrihl.} instruction on big-endian targets
23531 and uses the @code{vstribr.} or @code{vstrihr.} instruction on
23532 little-endian targets. Choose this built-in to check for presence of
23533 zero element if the same argument is also passed to @code{vec_stril}.
23534 @findex vec_stril_p
23537 @exdent vector unsigned char vec_strir (vector unsigned char);
23538 @exdent vector signed char vec_strir (vector signed char);
23539 @exdent vector unsigned short vec_strir (vector unsigned short);
23540 @exdent vector signed short vec_strir (vector signed short);
23542 Isolate the right-most non-zero elements of the incoming vector argument,
23543 replacing all elements to the left of the right-most zero element
23544 found within the argument with zero. The typical implementation uses
23545 the @code{vstribr} or @code{vstrihr} instruction on big-endian targets
23546 and uses the @code{vstribl} or @code{vstrihl} instruction on
23547 little-endian targets.
23551 @exdent int vec_strir_p (vector unsigned char);
23552 @exdent int vec_strir_p (vector signed char);
23553 @exdent int short vec_strir_p (vector unsigned short);
23554 @exdent int vec_strir_p (vector signed short);
23556 Return a non-zero value if and only if the argument contains a zero
23557 element. The typical implementation uses
23558 the @code{vstribr.} or @code{vstrihr.} instruction on big-endian targets
23559 and uses the @code{vstribl.} or @code{vstrihl.} instruction on
23560 little-endian targets. Choose this built-in to check for presence of
23561 zero element if the same argument is also passed to @code{vec_strir}.
23562 @findex vec_strir_p
23565 @exdent vector unsigned char
23566 @exdent vec_ternarylogic (vector unsigned char, vector unsigned char,
23567 vector unsigned char, const unsigned int);
23568 @exdent vector unsigned short
23569 @exdent vec_ternarylogic (vector unsigned short, vector unsigned short,
23570 vector unsigned short, const unsigned int);
23571 @exdent vector unsigned int
23572 @exdent vec_ternarylogic (vector unsigned int, vector unsigned int,
23573 vector unsigned int, const unsigned int);
23574 @exdent vector unsigned long long int
23575 @exdent vec_ternarylogic (vector unsigned long long int, vector unsigned long long int,
23576 vector unsigned long long int, const unsigned int);
23577 @exdent vector unsigned __int128
23578 @exdent vec_ternarylogic (vector unsigned __int128, vector unsigned __int128,
23579 vector unsigned __int128, const unsigned int);
23581 Perform a 128-bit vector evaluate operation, as if implemented by the
23582 @code{xxeval} instruction. The fourth argument must be a literal
23583 integer value between 0 and 255 inclusive.
23584 @findex vec_ternarylogic
23587 @exdent vector unsigned char vec_genpcvm (vector unsigned char, const int);
23588 @exdent vector unsigned short vec_genpcvm (vector unsigned short, const int);
23589 @exdent vector unsigned int vec_genpcvm (vector unsigned int, const int);
23590 @exdent vector unsigned int vec_genpcvm (vector unsigned long long int,
23594 Vector Integer Multiply/Divide/Modulo
23597 @exdent vector signed int
23598 @exdent vec_mulh (vector signed int @var{a}, vector signed int @var{b});
23599 @exdent vector unsigned int
23600 @exdent vec_mulh (vector unsigned int @var{a}, vector unsigned int @var{b});
23603 For each integer value @code{i} from 0 to 3, do the following. The integer
23604 value in word element @code{i} of a is multiplied by the integer value in word
23605 element @code{i} of b. The high-order 32 bits of the 64-bit product are placed
23606 into word element @code{i} of the vector returned.
23609 @exdent vector signed long long
23610 @exdent vec_mulh (vector signed long long @var{a}, vector signed long long @var{b});
23611 @exdent vector unsigned long long
23612 @exdent vec_mulh (vector unsigned long long @var{a}, vector unsigned long long @var{b});
23615 For each integer value @code{i} from 0 to 1, do the following. The integer
23616 value in doubleword element @code{i} of a is multiplied by the integer value in
23617 doubleword element @code{i} of b. The high-order 64 bits of the 128-bit product
23618 are placed into doubleword element @code{i} of the vector returned.
23621 @exdent vector unsigned long long
23622 @exdent vec_mul (vector unsigned long long @var{a}, vector unsigned long long @var{b});
23623 @exdent vector signed long long
23624 @exdent vec_mul (vector signed long long @var{a}, vector signed long long @var{b});
23627 For each integer value @code{i} from 0 to 1, do the following. The integer
23628 value in doubleword element @code{i} of a is multiplied by the integer value in
23629 doubleword element @code{i} of b. The low-order 64 bits of the 128-bit product
23630 are placed into doubleword element @code{i} of the vector returned.
23633 @exdent vector signed int
23634 @exdent vec_div (vector signed int @var{a}, vector signed int @var{b});
23635 @exdent vector unsigned int
23636 @exdent vec_div (vector unsigned int @var{a}, vector unsigned int @var{b});
23639 For each integer value @code{i} from 0 to 3, do the following. The integer in
23640 word element @code{i} of a is divided by the integer in word element @code{i}
23641 of b. The unique integer quotient is placed into the word element @code{i} of
23642 the vector returned. If an attempt is made to perform any of the divisions
23643 <anything> ÷ 0 then the quotient is undefined.
23646 @exdent vector signed long long
23647 @exdent vec_div (vector signed long long @var{a}, vector signed long long @var{b});
23648 @exdent vector unsigned long long
23649 @exdent vec_div (vector unsigned long long @var{a}, vector unsigned long long @var{b});
23652 For each integer value @code{i} from 0 to 1, do the following. The integer in
23653 doubleword element @code{i} of a is divided by the integer in doubleword
23654 element @code{i} of b. The unique integer quotient is placed into the
23655 doubleword element @code{i} of the vector returned. If an attempt is made to
23656 perform any of the divisions 0x8000_0000_0000_0000 ÷ -1 or <anything> ÷ 0 then
23657 the quotient is undefined.
23660 @exdent vector signed int
23661 @exdent vec_dive (vector signed int @var{a}, vector signed int @var{b});
23662 @exdent vector unsigned int
23663 @exdent vec_dive (vector unsigned int @var{a}, vector unsigned int @var{b});
23666 For each integer value @code{i} from 0 to 3, do the following. The integer in
23667 word element @code{i} of a is shifted left by 32 bits, then divided by the
23668 integer in word element @code{i} of b. The unique integer quotient is placed
23669 into the word element @code{i} of the vector returned. If the quotient cannot
23670 be represented in 32 bits, or if an attempt is made to perform any of the
23671 divisions <anything> ÷ 0 then the quotient is undefined.
23674 @exdent vector signed long long
23675 @exdent vec_dive (vector signed long long @var{a}, vector signed long long @var{b});
23676 @exdent vector unsigned long long
23677 @exdent vec_dive (vector unsigned long long @var{a}, vector unsigned long long @var{b});
23680 For each integer value @code{i} from 0 to 1, do the following. The integer in
23681 doubleword element @code{i} of a is shifted left by 64 bits, then divided by
23682 the integer in doubleword element @code{i} of b. The unique integer quotient is
23683 placed into the doubleword element @code{i} of the vector returned. If the
23684 quotient cannot be represented in 64 bits, or if an attempt is made to perform
23685 <anything> ÷ 0 then the quotient is undefined.
23688 @exdent vector signed int
23689 @exdent vec_mod (vector signed int @var{a}, vector signed int @var{b});
23690 @exdent vector unsigned int
23691 @exdent vec_mod (vector unsigned int @var{a}, vector unsigned int @var{b});
23694 For each integer value @code{i} from 0 to 3, do the following. The integer in
23695 word element @code{i} of a is divided by the integer in word element @code{i}
23696 of b. The unique integer remainder is placed into the word element @code{i} of
23697 the vector returned. If an attempt is made to perform any of the divisions
23698 0x8000_0000 ÷ -1 or <anything> ÷ 0 then the remainder is undefined.
23701 @exdent vector signed long long
23702 @exdent vec_mod (vector signed long long @var{a}, vector signed long long @var{b});
23703 @exdent vector unsigned long long
23704 @exdent vec_mod (vector unsigned long long @var{a}, vector unsigned long long @var{b});
23707 For each integer value @code{i} from 0 to 1, do the following. The integer in
23708 doubleword element @code{i} of a is divided by the integer in doubleword
23709 element @code{i} of b. The unique integer remainder is placed into the
23710 doubleword element @code{i} of the vector returned. If an attempt is made to
23711 perform <anything> ÷ 0 then the remainder is undefined.
23713 Generate PCV from specified Mask size, as if implemented by the
23714 @code{xxgenpcvbm}, @code{xxgenpcvhm}, @code{xxgenpcvwm} instructions, where
23715 immediate value is either 0, 1, 2 or 3.
23716 @findex vec_genpcvm
23719 @exdent vector unsigned __int128 vec_rl (vector unsigned __int128 @var{A},
23720 vector unsigned __int128 @var{B});
23721 @exdent vector signed __int128 vec_rl (vector signed __int128 @var{A},
23722 vector unsigned __int128 @var{B});
23725 Result value: Each element of @var{R} is obtained by rotating the corresponding element
23726 of @var{A} left by the number of bits specified by the corresponding element of @var{B}.
23730 @exdent vector unsigned __int128 vec_rlmi (vector unsigned __int128,
23731 vector unsigned __int128,
23732 vector unsigned __int128);
23733 @exdent vector signed __int128 vec_rlmi (vector signed __int128,
23734 vector signed __int128,
23735 vector unsigned __int128);
23738 Returns the result of rotating the first input and inserting it under mask
23739 into the second input. The first bit in the mask, the last bit in the mask are
23740 obtained from the two 7-bit fields bits [108:115] and bits [117:123]
23741 respectively of the second input. The shift is obtained from the third input
23742 in the 7-bit field [125:131] where all bits counted from zero at the left.
23745 @exdent vector unsigned __int128 vec_rlnm (vector unsigned __int128,
23746 vector unsigned __int128,
23747 vector unsigned __int128);
23748 @exdent vector signed __int128 vec_rlnm (vector signed __int128,
23749 vector unsigned __int128,
23750 vector unsigned __int128);
23753 Returns the result of rotating the first input and ANDing it with a mask. The
23754 first bit in the mask and the last bit in the mask are obtained from the two
23755 7-bit fields bits [117:123] and bits [125:131] respectively of the second
23756 input. The shift is obtained from the third input in the 7-bit field bits
23757 [125:131] where all bits counted from zero at the left.
23760 @exdent vector unsigned __int128 vec_sl(vector unsigned __int128 @var{A}, vector unsigned __int128 @var{B});
23761 @exdent vector signed __int128 vec_sl(vector signed __int128 @var{A}, vector unsigned __int128 @var{B});
23764 Result value: Each element of @var{R} is obtained by shifting the corresponding element of
23765 @var{A} left by the number of bits specified by the corresponding element of @var{B}.
23768 @exdent vector unsigned __int128 vec_sr(vector unsigned __int128 @var{A}, vector unsigned __int128 @var{B});
23769 @exdent vector signed __int128 vec_sr(vector signed __int128 @var{A}, vector unsigned __int128 @var{B});
23772 Result value: Each element of @var{R} is obtained by shifting the corresponding element of
23773 @var{A} right by the number of bits specified by the corresponding element of @var{B}.
23776 @exdent vector unsigned __int128 vec_sra(vector unsigned __int128 @var{A}, vector unsigned __int128 @var{B});
23777 @exdent vector signed __int128 vec_sra(vector signed __int128 @var{A}, vector unsigned __int128 @var{B});
23780 Result value: Each element of @var{R} is obtained by arithmetic shifting the corresponding
23781 element of @var{A} right by the number of bits specified by the corresponding element of @var{B}.
23784 @exdent vector unsigned __int128 vec_mule (vector unsigned long long,
23785 vector unsigned long long);
23786 @exdent vector signed __int128 vec_mule (vector signed long long,
23787 vector signed long long);
23790 Returns a vector containing a 128-bit integer result of multiplying the even
23791 doubleword elements of the two inputs.
23794 @exdent vector unsigned __int128 vec_mulo (vector unsigned long long,
23795 vector unsigned long long);
23796 @exdent vector signed __int128 vec_mulo (vector signed long long,
23797 vector signed long long);
23800 Returns a vector containing a 128-bit integer result of multiplying the odd
23801 doubleword elements of the two inputs.
23804 @exdent vector unsigned __int128 vec_div (vector unsigned __int128,
23805 vector unsigned __int128);
23806 @exdent vector signed __int128 vec_div (vector signed __int128,
23807 vector signed __int128);
23810 Returns the result of dividing the first operand by the second operand. An
23811 attempt to divide any value by zero or to divide the most negative signed
23812 128-bit integer by negative one results in an undefined value.
23815 @exdent vector unsigned __int128 vec_dive (vector unsigned __int128,
23816 vector unsigned __int128);
23817 @exdent vector signed __int128 vec_dive (vector signed __int128,
23818 vector signed __int128);
23821 The result is produced by shifting the first input left by 128 bits and
23822 dividing by the second. If an attempt is made to divide by zero or the result
23823 is larger than 128 bits, the result is undefined.
23826 @exdent vector unsigned __int128 vec_mod (vector unsigned __int128,
23827 vector unsigned __int128);
23828 @exdent vector signed __int128 vec_mod (vector signed __int128,
23829 vector signed __int128);
23832 The result is the modulo result of dividing the first input by the second
23835 The following builtins perform 128-bit vector comparisons. The
23836 @code{vec_all_xx}, @code{vec_any_xx}, and @code{vec_cmpxx}, where @code{xx} is
23837 one of the operations @code{eq, ne, gt, lt, ge, le} perform pairwise
23838 comparisons between the elements at the same positions within their two vector
23839 arguments. The @code{vec_all_xx}function returns a non-zero value if and only
23840 if all pairwise comparisons are true. The @code{vec_any_xx} function returns
23841 a non-zero value if and only if at least one pairwise comparison is true. The
23842 @code{vec_cmpxx}function returns a vector of the same type as its two
23843 arguments, within which each element consists of all ones to denote that
23844 specified logical comparison of the corresponding elements was true.
23845 Otherwise, the element of the returned vector contains all zeros.
23848 vector bool __int128 vec_cmpeq (vector signed __int128, vector signed __int128);
23849 vector bool __int128 vec_cmpeq (vector unsigned __int128, vector unsigned __int128);
23850 vector bool __int128 vec_cmpne (vector signed __int128, vector signed __int128);
23851 vector bool __int128 vec_cmpne (vector unsigned __int128, vector unsigned __int128);
23852 vector bool __int128 vec_cmpgt (vector signed __int128, vector signed __int128);
23853 vector bool __int128 vec_cmpgt (vector unsigned __int128, vector unsigned __int128);
23854 vector bool __int128 vec_cmplt (vector signed __int128, vector signed __int128);
23855 vector bool __int128 vec_cmplt (vector unsigned __int128, vector unsigned __int128);
23856 vector bool __int128 vec_cmpge (vector signed __int128, vector signed __int128);
23857 vector bool __int128 vec_cmpge (vector unsigned __int128, vector unsigned __int128);
23858 vector bool __int128 vec_cmple (vector signed __int128, vector signed __int128);
23859 vector bool __int128 vec_cmple (vector unsigned __int128, vector unsigned __int128);
23861 int vec_all_eq (vector signed __int128, vector signed __int128);
23862 int vec_all_eq (vector unsigned __int128, vector unsigned __int128);
23863 int vec_all_ne (vector signed __int128, vector signed __int128);
23864 int vec_all_ne (vector unsigned __int128, vector unsigned __int128);
23865 int vec_all_gt (vector signed __int128, vector signed __int128);
23866 int vec_all_gt (vector unsigned __int128, vector unsigned __int128);
23867 int vec_all_lt (vector signed __int128, vector signed __int128);
23868 int vec_all_lt (vector unsigned __int128, vector unsigned __int128);
23869 int vec_all_ge (vector signed __int128, vector signed __int128);
23870 int vec_all_ge (vector unsigned __int128, vector unsigned __int128);
23871 int vec_all_le (vector signed __int128, vector signed __int128);
23872 int vec_all_le (vector unsigned __int128, vector unsigned __int128);
23874 int vec_any_eq (vector signed __int128, vector signed __int128);
23875 int vec_any_eq (vector unsigned __int128, vector unsigned __int128);
23876 int vec_any_ne (vector signed __int128, vector signed __int128);
23877 int vec_any_ne (vector unsigned __int128, vector unsigned __int128);
23878 int vec_any_gt (vector signed __int128, vector signed __int128);
23879 int vec_any_gt (vector unsigned __int128, vector unsigned __int128);
23880 int vec_any_lt (vector signed __int128, vector signed __int128);
23881 int vec_any_lt (vector unsigned __int128, vector unsigned __int128);
23882 int vec_any_ge (vector signed __int128, vector signed __int128);
23883 int vec_any_ge (vector unsigned __int128, vector unsigned __int128);
23884 int vec_any_le (vector signed __int128, vector signed __int128);
23885 int vec_any_le (vector unsigned __int128, vector unsigned __int128);
23889 @node PowerPC Hardware Transactional Memory Built-in Functions
23890 @subsection PowerPC Hardware Transactional Memory Built-in Functions
23891 GCC provides two interfaces for accessing the Hardware Transactional
23892 Memory (HTM) instructions available on some of the PowerPC family
23893 of processors (eg, POWER8). The two interfaces come in a low level
23894 interface, consisting of built-in functions specific to PowerPC and a
23895 higher level interface consisting of inline functions that are common
23896 between PowerPC and S/390.
23898 @subsubsection PowerPC HTM Low Level Built-in Functions
23900 The following low level built-in functions are available with
23901 @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later.
23902 They all generate the machine instruction that is part of the name.
23904 The HTM builtins (with the exception of @code{__builtin_tbegin}) return
23905 the full 4-bit condition register value set by their associated hardware
23906 instruction. The header file @code{htmintrin.h} defines some macros that can
23907 be used to decipher the return value. The @code{__builtin_tbegin} builtin
23908 returns a simple @code{true} or @code{false} value depending on whether a transaction was
23909 successfully started or not. The arguments of the builtins match exactly the
23910 type and order of the associated hardware instruction's operands, except for
23911 the @code{__builtin_tcheck} builtin, which does not take any input arguments.
23912 Refer to the ISA manual for a description of each instruction's operands.
23915 unsigned int __builtin_tbegin (unsigned int);
23916 unsigned int __builtin_tend (unsigned int);
23918 unsigned int __builtin_tabort (unsigned int);
23919 unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int);
23920 unsigned int __builtin_tabortdci (unsigned int, unsigned int, int);
23921 unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int);
23922 unsigned int __builtin_tabortwci (unsigned int, unsigned int, int);
23924 unsigned int __builtin_tcheck (void);
23925 unsigned int __builtin_treclaim (unsigned int);
23926 unsigned int __builtin_trechkpt (void);
23927 unsigned int __builtin_tsr (unsigned int);
23930 In addition to the above HTM built-ins, we have added built-ins for
23931 some common extended mnemonics of the HTM instructions:
23934 unsigned int __builtin_tendall (void);
23935 unsigned int __builtin_tresume (void);
23936 unsigned int __builtin_tsuspend (void);
23939 Note that the semantics of the above HTM builtins are required to mimic
23940 the locking semantics used for critical sections. Builtins that are used
23941 to create a new transaction or restart a suspended transaction must have
23942 lock acquisition like semantics while those builtins that end or suspend a
23943 transaction must have lock release like semantics. Specifically, this must
23944 mimic lock semantics as specified by C++11, for example: Lock acquisition is
23945 as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE)
23946 that returns 0, and lock release is as-if an execution of
23947 __atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an
23948 implicit implementation-defined lock used for all transactions. The HTM
23949 instructions associated with with the builtins inherently provide the
23950 correct acquisition and release hardware barriers required. However,
23951 the compiler must also be prohibited from moving loads and stores across
23952 the builtins in a way that would violate their semantics. This has been
23953 accomplished by adding memory barriers to the associated HTM instructions
23954 (which is a conservative approach to provide acquire and release semantics).
23955 Earlier versions of the compiler did not treat the HTM instructions as
23956 memory barriers. A @code{__TM_FENCE__} macro has been added, which can
23957 be used to determine whether the current compiler treats HTM instructions
23958 as memory barriers or not. This allows the user to explicitly add memory
23959 barriers to their code when using an older version of the compiler.
23961 The following set of built-in functions are available to gain access
23962 to the HTM specific special purpose registers.
23965 unsigned long __builtin_get_texasr (void);
23966 unsigned long __builtin_get_texasru (void);
23967 unsigned long __builtin_get_tfhar (void);
23968 unsigned long __builtin_get_tfiar (void);
23970 void __builtin_set_texasr (unsigned long);
23971 void __builtin_set_texasru (unsigned long);
23972 void __builtin_set_tfhar (unsigned long);
23973 void __builtin_set_tfiar (unsigned long);
23976 Example usage of these low level built-in functions may look like:
23979 #include <htmintrin.h>
23981 int num_retries = 10;
23985 if (__builtin_tbegin (0))
23987 /* Transaction State Initiated. */
23988 if (is_locked (lock))
23989 __builtin_tabort (0);
23990 ... transaction code...
23991 __builtin_tend (0);
23996 /* Transaction State Failed. Use locks if the transaction
23997 failure is "persistent" or we've tried too many times. */
23998 if (num_retries-- <= 0
23999 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ()))
24001 acquire_lock (lock);
24002 ... non transactional fallback path...
24003 release_lock (lock);
24010 One final built-in function has been added that returns the value of
24011 the 2-bit Transaction State field of the Machine Status Register (MSR)
24012 as stored in @code{CR0}.
24015 unsigned long __builtin_ttest (void)
24018 This built-in can be used to determine the current transaction state
24019 using the following code example:
24022 #include <htmintrin.h>
24024 unsigned char tx_state = _HTM_STATE (__builtin_ttest ());
24026 if (tx_state == _HTM_TRANSACTIONAL)
24028 /* Code to use in transactional state. */
24030 else if (tx_state == _HTM_NONTRANSACTIONAL)
24032 /* Code to use in non-transactional state. */
24034 else if (tx_state == _HTM_SUSPENDED)
24036 /* Code to use in transaction suspended state. */
24040 @subsubsection PowerPC HTM High Level Inline Functions
24042 The following high level HTM interface is made available by including
24043 @code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU}
24044 where CPU is `power8' or later. This interface is common between PowerPC
24045 and S/390, allowing users to write one HTM source implementation that
24046 can be compiled and executed on either system.
24049 long __TM_simple_begin (void);
24050 long __TM_begin (void* const TM_buff);
24051 long __TM_end (void);
24052 void __TM_abort (void);
24053 void __TM_named_abort (unsigned char const code);
24054 void __TM_resume (void);
24055 void __TM_suspend (void);
24057 long __TM_is_user_abort (void* const TM_buff);
24058 long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code);
24059 long __TM_is_illegal (void* const TM_buff);
24060 long __TM_is_footprint_exceeded (void* const TM_buff);
24061 long __TM_nesting_depth (void* const TM_buff);
24062 long __TM_is_nested_too_deep(void* const TM_buff);
24063 long __TM_is_conflict(void* const TM_buff);
24064 long __TM_is_failure_persistent(void* const TM_buff);
24065 long __TM_failure_address(void* const TM_buff);
24066 long long __TM_failure_code(void* const TM_buff);
24069 Using these common set of HTM inline functions, we can create
24070 a more portable version of the HTM example in the previous
24071 section that will work on either PowerPC or S/390:
24074 #include <htmxlintrin.h>
24076 int num_retries = 10;
24077 TM_buff_type TM_buff;
24081 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED)
24083 /* Transaction State Initiated. */
24084 if (is_locked (lock))
24086 ... transaction code...
24092 /* Transaction State Failed. Use locks if the transaction
24093 failure is "persistent" or we've tried too many times. */
24094 if (num_retries-- <= 0
24095 || __TM_is_failure_persistent (TM_buff))
24097 acquire_lock (lock);
24098 ... non transactional fallback path...
24099 release_lock (lock);
24106 @node PowerPC Atomic Memory Operation Functions
24107 @subsection PowerPC Atomic Memory Operation Functions
24108 ISA 3.0 of the PowerPC added new atomic memory operation (amo)
24109 instructions. GCC provides support for these instructions in 64-bit
24110 environments. All of the functions are declared in the include file
24113 The functions supported are:
24118 uint32_t amo_lwat_add (uint32_t *, uint32_t);
24119 uint32_t amo_lwat_xor (uint32_t *, uint32_t);
24120 uint32_t amo_lwat_ior (uint32_t *, uint32_t);
24121 uint32_t amo_lwat_and (uint32_t *, uint32_t);
24122 uint32_t amo_lwat_umax (uint32_t *, uint32_t);
24123 uint32_t amo_lwat_umin (uint32_t *, uint32_t);
24124 uint32_t amo_lwat_swap (uint32_t *, uint32_t);
24126 int32_t amo_lwat_sadd (int32_t *, int32_t);
24127 int32_t amo_lwat_smax (int32_t *, int32_t);
24128 int32_t amo_lwat_smin (int32_t *, int32_t);
24129 int32_t amo_lwat_sswap (int32_t *, int32_t);
24131 uint64_t amo_ldat_add (uint64_t *, uint64_t);
24132 uint64_t amo_ldat_xor (uint64_t *, uint64_t);
24133 uint64_t amo_ldat_ior (uint64_t *, uint64_t);
24134 uint64_t amo_ldat_and (uint64_t *, uint64_t);
24135 uint64_t amo_ldat_umax (uint64_t *, uint64_t);
24136 uint64_t amo_ldat_umin (uint64_t *, uint64_t);
24137 uint64_t amo_ldat_swap (uint64_t *, uint64_t);
24139 int64_t amo_ldat_sadd (int64_t *, int64_t);
24140 int64_t amo_ldat_smax (int64_t *, int64_t);
24141 int64_t amo_ldat_smin (int64_t *, int64_t);
24142 int64_t amo_ldat_sswap (int64_t *, int64_t);
24144 void amo_stwat_add (uint32_t *, uint32_t);
24145 void amo_stwat_xor (uint32_t *, uint32_t);
24146 void amo_stwat_ior (uint32_t *, uint32_t);
24147 void amo_stwat_and (uint32_t *, uint32_t);
24148 void amo_stwat_umax (uint32_t *, uint32_t);
24149 void amo_stwat_umin (uint32_t *, uint32_t);
24151 void amo_stwat_sadd (int32_t *, int32_t);
24152 void amo_stwat_smax (int32_t *, int32_t);
24153 void amo_stwat_smin (int32_t *, int32_t);
24155 void amo_stdat_add (uint64_t *, uint64_t);
24156 void amo_stdat_xor (uint64_t *, uint64_t);
24157 void amo_stdat_ior (uint64_t *, uint64_t);
24158 void amo_stdat_and (uint64_t *, uint64_t);
24159 void amo_stdat_umax (uint64_t *, uint64_t);
24160 void amo_stdat_umin (uint64_t *, uint64_t);
24162 void amo_stdat_sadd (int64_t *, int64_t);
24163 void amo_stdat_smax (int64_t *, int64_t);
24164 void amo_stdat_smin (int64_t *, int64_t);
24167 @node PowerPC Matrix-Multiply Assist Built-in Functions
24168 @subsection PowerPC Matrix-Multiply Assist Built-in Functions
24169 ISA 3.1 of the PowerPC added new Matrix-Multiply Assist (MMA) instructions.
24170 GCC provides support for these instructions through the following built-in
24171 functions which are enabled with the @code{-mmma} option. The vec_t type
24172 below is defined to be a normal vector unsigned char type. The uint2, uint4
24173 and uint8 parameters are 2-bit, 4-bit and 8-bit unsigned integer constants
24174 respectively. The compiler will verify that they are constants and that
24175 their values are within range.
24177 The built-in functions supported are:
24180 void __builtin_mma_xvi4ger8 (__vector_quad *, vec_t, vec_t);
24181 void __builtin_mma_xvi8ger4 (__vector_quad *, vec_t, vec_t);
24182 void __builtin_mma_xvi16ger2 (__vector_quad *, vec_t, vec_t);
24183 void __builtin_mma_xvi16ger2s (__vector_quad *, vec_t, vec_t);
24184 void __builtin_mma_xvf16ger2 (__vector_quad *, vec_t, vec_t);
24185 void __builtin_mma_xvbf16ger2 (__vector_quad *, vec_t, vec_t);
24186 void __builtin_mma_xvf32ger (__vector_quad *, vec_t, vec_t);
24188 void __builtin_mma_xvi4ger8pp (__vector_quad *, vec_t, vec_t);
24189 void __builtin_mma_xvi8ger4pp (__vector_quad *, vec_t, vec_t);
24190 void __builtin_mma_xvi8ger4spp(__vector_quad *, vec_t, vec_t);
24191 void __builtin_mma_xvi16ger2pp (__vector_quad *, vec_t, vec_t);
24192 void __builtin_mma_xvi16ger2spp (__vector_quad *, vec_t, vec_t);
24193 void __builtin_mma_xvf16ger2pp (__vector_quad *, vec_t, vec_t);
24194 void __builtin_mma_xvf16ger2pn (__vector_quad *, vec_t, vec_t);
24195 void __builtin_mma_xvf16ger2np (__vector_quad *, vec_t, vec_t);
24196 void __builtin_mma_xvf16ger2nn (__vector_quad *, vec_t, vec_t);
24197 void __builtin_mma_xvbf16ger2pp (__vector_quad *, vec_t, vec_t);
24198 void __builtin_mma_xvbf16ger2pn (__vector_quad *, vec_t, vec_t);
24199 void __builtin_mma_xvbf16ger2np (__vector_quad *, vec_t, vec_t);
24200 void __builtin_mma_xvbf16ger2nn (__vector_quad *, vec_t, vec_t);
24201 void __builtin_mma_xvf32gerpp (__vector_quad *, vec_t, vec_t);
24202 void __builtin_mma_xvf32gerpn (__vector_quad *, vec_t, vec_t);
24203 void __builtin_mma_xvf32gernp (__vector_quad *, vec_t, vec_t);
24204 void __builtin_mma_xvf32gernn (__vector_quad *, vec_t, vec_t);
24206 void __builtin_mma_pmxvi4ger8 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8);
24207 void __builtin_mma_pmxvi4ger8pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8);
24209 void __builtin_mma_pmxvi8ger4 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
24210 void __builtin_mma_pmxvi8ger4pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
24211 void __builtin_mma_pmxvi8ger4spp(__vector_quad *, vec_t, vec_t, uint4, uint4, uint4);
24213 void __builtin_mma_pmxvi16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
24214 void __builtin_mma_pmxvi16ger2s (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
24215 void __builtin_mma_pmxvf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
24216 void __builtin_mma_pmxvbf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
24218 void __builtin_mma_pmxvi16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
24219 void __builtin_mma_pmxvi16ger2spp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
24220 void __builtin_mma_pmxvf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
24221 void __builtin_mma_pmxvf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
24222 void __builtin_mma_pmxvf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
24223 void __builtin_mma_pmxvf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
24224 void __builtin_mma_pmxvbf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
24225 void __builtin_mma_pmxvbf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
24226 void __builtin_mma_pmxvbf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
24227 void __builtin_mma_pmxvbf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2);
24229 void __builtin_mma_pmxvf32ger (__vector_quad *, vec_t, vec_t, uint4, uint4);
24230 void __builtin_mma_pmxvf32gerpp (__vector_quad *, vec_t, vec_t, uint4, uint4);
24231 void __builtin_mma_pmxvf32gerpn (__vector_quad *, vec_t, vec_t, uint4, uint4);
24232 void __builtin_mma_pmxvf32gernp (__vector_quad *, vec_t, vec_t, uint4, uint4);
24233 void __builtin_mma_pmxvf32gernn (__vector_quad *, vec_t, vec_t, uint4, uint4);
24235 void __builtin_mma_xvf64ger (__vector_quad *, __vector_pair, vec_t);
24236 void __builtin_mma_xvf64gerpp (__vector_quad *, __vector_pair, vec_t);
24237 void __builtin_mma_xvf64gerpn (__vector_quad *, __vector_pair, vec_t);
24238 void __builtin_mma_xvf64gernp (__vector_quad *, __vector_pair, vec_t);
24239 void __builtin_mma_xvf64gernn (__vector_quad *, __vector_pair, vec_t);
24241 void __builtin_mma_pmxvf64ger (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
24242 void __builtin_mma_pmxvf64gerpp (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
24243 void __builtin_mma_pmxvf64gerpn (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
24244 void __builtin_mma_pmxvf64gernp (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
24245 void __builtin_mma_pmxvf64gernn (__vector_quad *, __vector_pair, vec_t, uint4, uint2);
24247 void __builtin_mma_xxmtacc (__vector_quad *);
24248 void __builtin_mma_xxmfacc (__vector_quad *);
24249 void __builtin_mma_xxsetaccz (__vector_quad *);
24251 void __builtin_mma_build_acc (__vector_quad *, vec_t, vec_t, vec_t, vec_t);
24252 void __builtin_mma_disassemble_acc (void *, __vector_quad *);
24254 void __builtin_vsx_build_pair (__vector_pair *, vec_t, vec_t);
24255 void __builtin_vsx_disassemble_pair (void *, __vector_pair *);
24257 vec_t __builtin_vsx_xvcvspbf16 (vec_t);
24258 vec_t __builtin_vsx_xvcvbf16spn (vec_t);
24260 __vector_pair __builtin_vsx_lxvp (size_t, __vector_pair *);
24261 void __builtin_vsx_stxvp (__vector_pair, size_t, __vector_pair *);
24264 @node PRU Built-in Functions
24265 @subsection PRU Built-in Functions
24267 GCC provides a couple of special builtin functions to aid in utilizing
24268 special PRU instructions.
24270 The built-in functions supported are:
24272 @defbuiltin{void __delay_cycles (constant long long @var{cycles})}
24273 This inserts an instruction sequence that takes exactly @var{cycles}
24274 cycles (between 0 and 0xffffffff) to complete. The inserted sequence
24275 may use jumps, loops, or no-ops, and does not interfere with any other
24276 instructions. Note that @var{cycles} must be a compile-time constant
24277 integer - that is, you must pass a number, not a variable that may be
24278 optimized to a constant later. The number of cycles delayed by this
24282 @defbuiltin{void __halt (void)}
24283 This inserts a HALT instruction to stop processor execution.
24286 @defbuiltin{{unsigned int} @
24287 __lmbd (unsigned int @var{wordval}, @
24288 unsigned int @var{bitval})}
24289 This inserts LMBD instruction to calculate the left-most bit with value
24290 @var{bitval} in value @var{wordval}. Only the least significant bit
24291 of @var{bitval} is taken into account.
24294 @node RISC-V Built-in Functions
24295 @subsection RISC-V Built-in Functions
24297 These built-in functions are available for the RISC-V family of
24300 @defbuiltin{{void *} __builtin_thread_pointer (void)}
24301 Returns the value that is currently set in the @samp{tp} register.
24304 @defbuiltin{void __builtin_riscv_pause (void)}
24305 Generates the @code{pause} (hint) machine instruction. If the target implements
24306 the Zihintpause extension, it indicates that the current hart should be
24307 temporarily paused or slowed down.
24310 @node RISC-V Vector Intrinsics
24311 @subsection RISC-V Vector Intrinsics
24313 GCC supports vector intrinsics as specified in version 0.11 of the RISC-V
24314 vector intrinsic specification, which is available at the following link:
24315 @uref{https://github.com/riscv-non-isa/rvv-intrinsic-doc/tree/v0.11.x}.
24316 All of these functions are declared in the include file @file{riscv_vector.h}.
24318 @node CORE-V Built-in Functions
24319 @subsection CORE-V Built-in Functions
24320 For more information on all CORE-V built-ins, please see
24321 @uref{https://github.com/openhwgroup/core-v-sw/blob/master/specifications/corev-builtin-spec.md}
24323 These built-in functions are available for the CORE-V MAC machine
24324 architecture. For more information on CORE-V built-ins, please see
24325 @uref{https://github.com/openhwgroup/core-v-sw/blob/master/specifications/corev-builtin-spec.md#listing-of-multiply-accumulate-builtins-xcvmac}.
24327 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_mac (int32_t, int32_t, int32_t)
24328 Generated assembler @code{cv.mac}
24331 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_msu (int32_t, int32_t, int32_t)
24332 Generates the @code{cv.msu} machine instruction.
24335 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_muluN (uint32_t, uint32_t, uint8_t)
24336 Generates the @code{cv.muluN} machine instruction.
24339 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_mulhhuN (uint32_t, uint32_t, uint8_t)
24340 Generates the @code{cv.mulhhuN} machine instruction.
24343 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_mulsN (int32_t, int32_t, uint8_t)
24344 Generates the @code{cv.mulsN} machine instruction.
24347 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_mulhhsN (int32_t, int32_t, uint8_t)
24348 Generates the @code{cv.mulhhsN} machine instruction.
24351 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_muluRN (uint32_t, uint32_t, uint8_t)
24352 Generates the @code{cv.muluRN} machine instruction.
24355 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_mulhhuRN (uint32_t, uint32_t, uint8_t)
24356 Generates the @code{cv.mulhhuRN} machine instruction.
24359 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_mulsRN (int32_t, int32_t, uint8_t)
24360 Generates the @code{cv.mulsRN} machine instruction.
24363 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_mulhhsRN (int32_t, int32_t, uint8_t)
24364 Generates the @code{cv.mulhhsRN} machine instruction.
24367 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_macuN (uint32_t, uint32_t, uint8_t)
24368 Generates the @code{cv.macuN} machine instruction.
24371 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_machhuN (uint32_t, uint32_t, uint8_t)
24372 Generates the @code{cv.machhuN} machine instruction.
24375 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_macsN (int32_t, int32_t, uint8_t)
24376 Generates the @code{cv.macsN} machine instruction.
24379 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_machhsN (int32_t, int32_t, uint8_t)
24380 Generates the @code{cv.machhsN} machine instruction.
24383 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_macuRN (uint32_t, uint32_t, uint8_t)
24384 Generates the @code{cv.macuRN} machine instruction.
24387 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_mac_machhuRN (uint32_t, uint32_t, uint8_t)
24388 Generates the @code{cv.machhuRN} machine instruction.
24391 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_macsRN (int32_t, int32_t, uint8_t)
24392 Generates the @code{cv.macsRN} machine instruction.
24395 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_mac_machhsRN (int32_t, int32_t, uint8_t)
24396 Generates the @code{cv.machhsRN} machine instruction.
24399 These built-in functions are available for the CORE-V ALU machine
24400 architecture. For more information on CORE-V built-ins, please see
24401 @uref{https://github.com/openhwgroup/core-v-sw/blob/master/specifications/corev-builtin-spec.md#listing-of-miscellaneous-alu-builtins-xcvalu}
24403 @deftypefn {Built-in Function} {int} __builtin_riscv_cv_alu_slet (int32_t, int32_t)
24404 Generated assembler @code{cv.slet}
24407 @deftypefn {Built-in Function} {int} __builtin_riscv_cv_alu_sletu (uint32_t, uint32_t)
24408 Generated assembler @code{cv.sletu}
24411 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_min (int32_t, int32_t)
24412 Generated assembler @code{cv.min}
24415 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_minu (uint32_t, uint32_t)
24416 Generated assembler @code{cv.minu}
24419 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_max (int32_t, int32_t)
24420 Generated assembler @code{cv.max}
24423 @deftypefn {Built-in Function} {uint32_tnt} __builtin_riscv_cv_alu_maxu (uint32_t, uint32_t)
24424 Generated assembler @code{cv.maxu}
24427 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_exths (int16_t)
24428 Generated assembler @code{cv.exths}
24431 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_exthz (uint16_t)
24432 Generated assembler @code{cv.exthz}
24435 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_extbs (int8_t)
24436 Generated assembler @code{cv.extbs}
24439 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_extbz (uint8_t)
24440 Generated assembler @code{cv.extbz}
24443 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_clip (int32_t, uint32_t)
24444 Generated assembler @code{cv.clip} if the uint32_t operand is a constant and an exact power of 2.
24445 Generated assembler @code{cv.clipr} if the it is a register.
24448 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_clipu (uint32_t, uint32_t)
24449 Generated assembler @code{cv.clipu} if the uint32_t operand is a constant and an exact power of 2.
24450 Generated assembler @code{cv.clipur} if the it is a register.
24453 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_addN (int32_t, int32_t, uint8_t)
24454 Generated assembler @code{cv.addN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31.
24455 Generated assembler @code{cv.addNr} if the it is a register.
24458 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_adduN (uint32_t, uint32_t, uint8_t)
24459 Generated assembler @code{cv.adduN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31.
24460 Generated assembler @code{cv.adduNr} if the it is a register.
24463 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_addRN (int32_t, int32_t, uint8_t)
24464 Generated assembler @code{cv.addRN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31.
24465 Generated assembler @code{cv.addRNr} if the it is a register.
24468 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_adduRN (uint32_t, uint32_t, uint8_t)
24469 Generated assembler @code{cv.adduRN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31.
24470 Generated assembler @code{cv.adduRNr} if the it is a register.
24473 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_subN (int32_t, int32_t, uint8_t)
24474 Generated assembler @code{cv.subN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31.
24475 Generated assembler @code{cv.subNr} if the it is a register.
24478 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_subuN (uint32_t, uint32_t, uint8_t)
24479 Generated assembler @code{cv.subuN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31.
24480 Generated assembler @code{cv.subuNr} if the it is a register.
24483 @deftypefn {Built-in Function} {int32_t} __builtin_riscv_cv_alu_subRN (int32_t, int32_t, uint8_t)
24484 Generated assembler @code{cv.subRN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31.
24485 Generated assembler @code{cv.subRNr} if the it is a register.
24488 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_alu_subuRN (uint32_t, uint32_t, uint8_t)
24489 Generated assembler @code{cv.subuRN} if the uint8_t operand is a constant and in the range 0 <= shft <= 31.
24490 Generated assembler @code{cv.subuRNr} if the it is a register.
24493 These built-in functions are available for the CORE-V Event Load machine
24494 architecture. For more information on CORE-V ELW builtins, please see
24495 @uref{https://github.com/openhwgroup/core-v-sw/blob/master/specifications/corev-builtin-spec.md#listing-of-event-load-word-builtins-xcvelw}
24497 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_elw_elw (uint32_t *)
24498 Generated assembler @code{cv.elw}
24501 These built-in functions are available for the CORE-V SIMD machine
24502 architecture. For more information on CORE-V SIMD built-ins, please see
24503 @uref{https://github.com/openhwgroup/core-v-sw/blob/master/specifications/corev-builtin-spec.md#listing-of-pulp-816-bit-simd-builtins-xcvsimd}
24505 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_add_h (uint32_t, uint32_t, uint4_t)
24506 Generated assembler @code{cv.add.h}
24509 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_add_b (uint32_t, uint32_t)
24510 Generated assembler @code{cv.add.b}
24513 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_add_sc_h (uint32_t, int16_t)
24514 Generated assembler @code{cv.add.sc.h}
24517 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_add_sc_h (uint32_t, int6_t)
24518 Generated assembler @code{cv.add.sci.h}
24521 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_add_sc_b (uint32_t, int8_t)
24522 Generated assembler @code{cv.add.sc.b}
24525 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_add_sc_b (uint32_t, int6_t)
24526 Generated assembler @code{cv.add.sci.b}
24529 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sub_h (uint32_t, uint32_t, uint4_t)
24530 Generated assembler @code{cv.sub.h}
24533 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sub_b (uint32_t, uint32_t)
24534 Generated assembler @code{cv.sub.b}
24537 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sub_sc_h (uint32_t, int16_t)
24538 Generated assembler @code{cv.sub.sc.h}
24541 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sub_sc_h (uint32_t, int6_t)
24542 Generated assembler @code{cv.sub.sci.h}
24545 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sub_sc_b (uint32_t, int8_t)
24546 Generated assembler @code{cv.sub.sc.b}
24549 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sub_sc_b (uint32_t, int6_t)
24550 Generated assembler @code{cv.sub.sci.b}
24553 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_avg_h (uint32_t, uint32_t)
24554 Generated assembler @code{cv.avg.h}
24557 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_avg_b (uint32_t, uint32_t)
24558 Generated assembler @code{cv.avg.b}
24561 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_avg_sc_h (uint32_t, int16_t)
24562 Generated assembler @code{cv.avg.sc.h}
24565 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_avg_sc_h (uint32_t, int6_t)
24566 Generated assembler @code{cv.avg.sci.h}
24569 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_avg_sc_b (uint32_t, int8_t)
24570 Generated assembler @code{cv.avg.sc.b}
24573 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_avg_sc_b (uint32_t, int6_t)
24574 Generated assembler @code{cv.avg.sci.b}
24577 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_avgu_h (uint32_t, uint32_t)
24578 Generated assembler @code{cv.avgu.h}
24581 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_avgu_b (uint32_t, uint32_t)
24582 Generated assembler @code{cv.avgu.b}
24585 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_avgu_sc_h (uint32_t, uint16_t)
24586 Generated assembler @code{cv.avgu.sc.h}
24589 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_avgu_sc_h (uint32_t, uint6_t)
24590 Generated assembler @code{cv.avgu.sci.h}
24593 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_avgu_sc_b (uint32_t, uint8_t)
24594 Generated assembler @code{cv.avgu.sc.b}
24597 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_avgu_sc_b (uint32_t, uint6_t)
24598 Generated assembler @code{cv.avgu.sci.b}
24601 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_min_h (uint32_t, uint32_t)
24602 Generated assembler @code{cv.min.h}
24605 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_min_b (uint32_t, uint32_t)
24606 Generated assembler @code{cv.min.b}
24609 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_min_sc_h (uint32_t, int16_t)
24610 Generated assembler @code{cv.min.sc.h}
24613 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_min_sc_h (uint32_t, int6_t)
24614 Generated assembler @code{cv.min.sci.h}
24617 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_min_sc_b (uint32_t, int8_t)
24618 Generated assembler @code{cv.min.sc.b}
24621 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_min_sc_b (uint32_t, int6_t)
24622 Generated assembler @code{cv.min.sci.b}
24625 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_minu_h (uint32_t, uint32_t)
24626 Generated assembler @code{cv.minu.h}
24629 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_minu_b (uint32_t, uint32_t)
24630 Generated assembler @code{cv.minu.b}
24633 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_minu_sc_h (uint32_t, uint16_t)
24634 Generated assembler @code{cv.minu.sc.h}
24637 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_minu_sc_h (uint32_t, uint6_t)
24638 Generated assembler @code{cv.minu.sci.h}
24641 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_minu_sc_b (uint32_t, uint8_t)
24642 Generated assembler @code{cv.minu.sc.b}
24645 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_minu_sc_b (uint32_t, uint6_t)
24646 Generated assembler @code{cv.minu.sci.b}
24649 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_max_h (uint32_t, uint32_t)
24650 Generated assembler @code{cv.max.h}
24653 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_max_b (uint32_t, uint32_t)
24654 Generated assembler @code{cv.max.b}
24657 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_max_sc_h (uint32_t, int16_t)
24658 Generated assembler @code{cv.max.sc.h}
24661 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_max_sc_h (uint32_t, int6_t)
24662 Generated assembler @code{cv.max.sci.h}
24665 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_max_sc_b (uint32_t, int8_t)
24666 Generated assembler @code{cv.max.sc.b}
24669 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_max_sc_b (uint32_t, int6_t)
24670 Generated assembler @code{cv.max.sci.b}
24673 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_maxu_h (uint32_t, uint32_t)
24674 Generated assembler @code{cv.maxu.h}
24677 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_maxu_b (uint32_t, uint32_t)
24678 Generated assembler @code{cv.maxu.b}
24681 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_maxu_sc_h (uint32_t, uint16_t)
24682 Generated assembler @code{cv.maxu.sc.h}
24685 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_maxu_sc_h (uint32_t, uint6_t)
24686 Generated assembler @code{cv.maxu.sci.h}
24689 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_maxu_sc_b (uint32_t, uint8_t)
24690 Generated assembler @code{cv.maxu.sc.b}
24693 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_maxu_sc_b (uint32_t, uint6_t)
24694 Generated assembler @code{cv.maxu.sci.b}
24697 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_srl_h (uint32_t, uint32_t)
24698 Generated assembler @code{cv.srl.h}
24701 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_srl_b (uint32_t, uint32_t)
24702 Generated assembler @code{cv.srl.b}
24705 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_srl_sc_h (uint32_t, int16_t)
24706 Generated assembler @code{cv.srl.sc.h}
24709 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_srl_sc_h (uint32_t, int6_t)
24710 Generated assembler @code{cv.srl.sci.h}
24713 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_srl_sc_b (uint32_t, int8_t)
24714 Generated assembler @code{cv.srl.sc.b}
24717 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_srl_sc_b (uint32_t, int6_t)
24718 Generated assembler @code{cv.srl.sci.b}
24721 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sra_h (uint32_t, uint32_t)
24722 Generated assembler @code{cv.sra.h}
24725 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sra_b (uint32_t, uint32_t)
24726 Generated assembler @code{cv.sra.b}
24729 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sra_sc_h (uint32_t, int16_t)
24730 Generated assembler @code{cv.sra.sc.h}
24733 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sra_sc_h (uint32_t, int6_t)
24734 Generated assembler @code{cv.sra.sci.h}
24737 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sra_sc_b (uint32_t, int8_t)
24738 Generated assembler @code{cv.sra.sc.b}
24741 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sra_sc_b (uint32_t, int6_t)
24742 Generated assembler @code{cv.sra.sci.b}
24745 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sll_h (uint32_t, uint32_t)
24746 Generated assembler @code{cv.sll.h}
24749 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sll_b (uint32_t, uint32_t)
24750 Generated assembler @code{cv.sll.b}
24753 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sll_sc_h (uint32_t, int16_t)
24754 Generated assembler @code{cv.sll.sc.h}
24757 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sll_sc_h (uint32_t, int6_t)
24758 Generated assembler @code{cv.sll.sci.h}
24761 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sll_sc_b (uint32_t, int8_t)
24762 Generated assembler @code{cv.sll.sc.b}
24765 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sll_sc_b (uint32_t, int6_t)
24766 Generated assembler @code{cv.sll.sci.b}
24769 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_or_h (uint32_t, uint32_t)
24770 Generated assembler @code{cv.or.h}
24773 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_or_b (uint32_t, uint32_t)
24774 Generated assembler @code{cv.or.b}
24777 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_or_sc_h (uint32_t, int16_t)
24778 Generated assembler @code{cv.or.sc.h}
24781 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_or_sc_h (uint32_t, int6_t)
24782 Generated assembler @code{cv.or.sci.h}
24785 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_or_sc_b (uint32_t, int8_t)
24786 Generated assembler @code{cv.or.sc.b}
24789 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_or_sc_b (uint32_t, int6_t)
24790 Generated assembler @code{cv.or.sci.b}
24793 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_xor_h (uint32_t, uint32_t)
24794 Generated assembler @code{cv.xor.h}
24797 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_xor_b (uint32_t, uint32_t)
24798 Generated assembler @code{cv.xor.b}
24801 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_xor_sc_h (uint32_t, int16_t)
24802 Generated assembler @code{cv.xor.sc.h}
24805 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_xor_sc_h (uint32_t, int6_t)
24806 Generated assembler @code{cv.xor.sci.h}
24809 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_xor_sc_b (uint32_t, int8_t)
24810 Generated assembler @code{cv.xor.sc.b}
24813 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_xor_sc_b (uint32_t, int6_t)
24814 Generated assembler @code{cv.xor.sci.b}
24817 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_and_h (uint32_t, uint32_t)
24818 Generated assembler @code{cv.and.h}
24821 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_and_b (uint32_t, uint32_t)
24822 Generated assembler @code{cv.and.b}
24825 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_and_sc_h (uint32_t, int16_t)
24826 Generated assembler @code{cv.and.sc.h}
24829 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_and_sc_h (uint32_t, int6_t)
24830 Generated assembler @code{cv.and.sci.h}
24833 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_and_sc_b (uint32_t, int8_t)
24834 Generated assembler @code{cv.and.sc.b}
24837 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_and_sc_b (uint32_t, int6_t)
24838 Generated assembler @code{cv.and.sci.b}
24841 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_abs_h (uint32_t)
24842 Generated assembler @code{cv.abs.h}
24845 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_abs_b (uint32_t)
24846 Generated assembler @code{cv.abs.b}
24849 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotup_h (uint32_t, uint32_t)
24850 Generated assembler @code{cv.dotup.h}
24853 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotup_b (uint32_t, uint32_t)
24854 Generated assembler @code{cv.dotup.b}
24857 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotup_sc_h (uint32_t, uint16_t)
24858 Generated assembler @code{cv.dotup.sc.h}
24861 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotup_sc_h (uint32_t, uint6_t)
24862 Generated assembler @code{cv.dotup.sci.h}
24865 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotup_sc_b (uint32_t, uint8_t)
24866 Generated assembler @code{cv.dotup.sc.b}
24869 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotup_sc_b (uint32_t, uint6_t)
24870 Generated assembler @code{cv.dotup.sci.b}
24873 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotusp_h (uint32_t, uint32_t)
24874 Generated assembler @code{cv.dotusp.h}
24877 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotusp_b (uint32_t, uint32_t)
24878 Generated assembler @code{cv.dotusp.b}
24881 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotusp_sc_h (uint32_t, int16_t)
24882 Generated assembler @code{cv.dotusp.sc.h}
24885 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotusp_sc_h (uint32_t, int6_t)
24886 Generated assembler @code{cv.dotusp.sci.h}
24889 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotusp_sc_b (uint32_t, int8_t)
24890 Generated assembler @code{cv.dotusp.sc.b}
24893 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotusp_sc_b (uint32_t, int6_t)
24894 Generated assembler @code{cv.dotusp.sci.b}
24897 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotsp_h (uint32_t, uint32_t)
24898 Generated assembler @code{cv.dotsp.h}
24901 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotsp_b (uint32_t, uint32_t)
24902 Generated assembler @code{cv.dotsp.b}
24905 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotsp_sc_h (uint32_t, int16_t)
24906 Generated assembler @code{cv.dotsp.sc.h}
24909 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotsp_sc_h (uint32_t, int6_t)
24910 Generated assembler @code{cv.dotsp.sci.h}
24913 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotsp_sc_b (uint32_t, int8_t)
24914 Generated assembler @code{cv.dotsp.sc.b}
24917 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_dotsp_sc_b (uint32_t, int6_t)
24918 Generated assembler @code{cv.dotsp.sci.b}
24921 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotup_h (uint32_t, uint32_t, uint32_t)
24922 Generated assembler @code{cv.sdotup.h}
24925 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotup_b (uint32_t, uint32_t, uint32_t)
24926 Generated assembler @code{cv.sdotup.b}
24929 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotup_sc_h (uint32_t, uint16_t, uint32_t)
24930 Generated assembler @code{cv.sdotup.sc.h}
24933 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotup_sc_h (uint32_t, uint6_t, uint32_t)
24934 Generated assembler @code{cv.sdotup.sci.h}
24937 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotup_sc_b (uint32_t, uint8_t, uint32_t)
24938 Generated assembler @code{cv.sdotup.sc.b}
24941 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotup_sc_b (uint32_t, uint6_t, uint32_t)
24942 Generated assembler @code{cv.sdotup.sci.b}
24945 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotusp_h (uint32_t, uint32_t, uint32_t)
24946 Generated assembler @code{cv.sdotusp.h}
24949 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotusp_b (uint32_t, uint32_t, uint32_t)
24950 Generated assembler @code{cv.sdotusp.b}
24953 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotusp_sc_h (uint32_t, int16_t, uint32_t)
24954 Generated assembler @code{cv.sdotusp.sc.h}
24957 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotusp_sc_h (uint32_t, int6_t, uint32_t)
24958 Generated assembler @code{cv.sdotusp.sci.h}
24961 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotusp_sc_b (uint32_t, int8_t, uint32_t)
24962 Generated assembler @code{cv.sdotusp.sc.b}
24965 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotusp_sc_b (uint32_t, int6_t, uint32_t)
24966 Generated assembler @code{cv.sdotusp.sci.b}
24969 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotsp_h (uint32_t, uint32_t, uint32_t)
24970 Generated assembler @code{cv.sdotsp.h}
24973 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotsp_b (uint32_t, uint32_t, uint32_t)
24974 Generated assembler @code{cv.sdotsp.b}
24977 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotsp_sc_h (uint32_t, int16_t, uint32_t)
24978 Generated assembler @code{cv.sdotsp.sc.h}
24981 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotsp_sc_h (uint32_t, int6_t, uint32_t)
24982 Generated assembler @code{cv.sdotsp.sci.h}
24985 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotsp_sc_b (uint32_t, int8_t, uint32_t)
24986 Generated assembler @code{cv.sdotsp.sc.b}
24989 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sdotsp_sc_b (uint32_t, int6_t, uint32_t)
24990 Generated assembler @code{cv.sdotsp.sci.b}
24993 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_extract_h (uint32_t, uint6_t)
24994 Generated assembler @code{cv.extract.h}
24997 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_extract_b (uint32_t, uint6_t)
24998 Generated assembler @code{cv.extract.b}
25001 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_extractu_h (uint32_t, uint6_t)
25002 Generated assembler @code{cv.extractu.h}
25005 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_extractu_b (uint32_t, uint6_t)
25006 Generated assembler @code{cv.extractu.b}
25009 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_insert_h (uint32_t, uint32_t)
25010 Generated assembler @code{cv.insert.h}
25013 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_insert_b (uint32_t, uint32_t)
25014 Generated assembler @code{cv.insert.b}
25017 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_shuffle_h (uint32_t, uint32_t)
25018 Generated assembler @code{cv.shuffle.h}
25021 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_shuffle_b (uint32_t, uint32_t)
25022 Generated assembler @code{cv.shuffle.b}
25025 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_shuffle_sci_h (uint32_t, uint4_t)
25026 Generated assembler @code{cv.shuffle.sci.h}
25029 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_shufflei0_sci_b (uint32_t, uint4_t)
25030 Generated assembler @code{cv.shufflei0.sci.b}
25033 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_shufflei1_sci_b (uint32_t, uint4_t)
25034 Generated assembler @code{cv.shufflei1.sci.b}
25037 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_shufflei2_sci_b (uint32_t, uint4_t)
25038 Generated assembler @code{cv.shufflei2.sci.b}
25041 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_shufflei3_sci_b (uint32_t, uint4_t)
25042 Generated assembler @code{cv.shufflei3.sci.b}
25045 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_shuffle2_h (uint32_t, uint32_t, uint32_t)
25046 Generated assembler @code{cv.shuffle2.h}
25049 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_shuffle2_b (uint32_t, uint32_t, uint32_t)
25050 Generated assembler @code{cv.shuffle2.b}
25053 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_packlo_h (uint32_t, uint32_t)
25054 Generated assembler @code{cv.pack}
25057 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_packhi_h (uint32_t, uint32_t)
25058 Generated assembler @code{cv.pack.h}
25061 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_packhi_b (uint32_t, uint32_t, uint32_t)
25062 Generated assembler @code{cv.packhi.b}
25065 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_packlo_b (uint32_t, uint32_t, uint32_t)
25066 Generated assembler @code{cv.packlo.b}
25069 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpeq_h (uint32_t, uint32_t)
25070 Generated assembler @code{cv.cmpeq.h}
25073 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpeq_b (uint32_t, uint32_t)
25074 Generated assembler @code{cv.cmpeq.b}
25077 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpeq_sc_h (uint32_t, int16_t)
25078 Generated assembler @code{cv.cmpeq.sc.h}
25081 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpeq_sc_h (uint32_t, int6_t)
25082 Generated assembler @code{cv.cmpeq.sci.h}
25085 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpeq_sc_b (uint32_t, int8_t)
25086 Generated assembler @code{cv.cmpeq.sc.b}
25089 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpeq_sc_b (uint32_t, int6_t)
25090 Generated assembler @code{cv.cmpeq.sci.b}
25093 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpne_h (uint32_t, uint32_t)
25094 Generated assembler @code{cv.cmpne.h}
25097 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpne_b (uint32_t, uint32_t)
25098 Generated assembler @code{cv.cmpne.b}
25101 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpne_sc_h (uint32_t, int16_t)
25102 Generated assembler @code{cv.cmpne.sc.h}
25105 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpne_sc_h (uint32_t, int6_t)
25106 Generated assembler @code{cv.cmpne.sci.h}
25109 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpne_sc_b (uint32_t, int8_t)
25110 Generated assembler @code{cv.cmpne.sc.b}
25113 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpne_sc_b (uint32_t, int6_t)
25114 Generated assembler @code{cv.cmpne.sci.b}
25117 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgt_h (uint32_t, uint32_t)
25118 Generated assembler @code{cv.cmpgt.h}
25121 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgt_b (uint32_t, uint32_t)
25122 Generated assembler @code{cv.cmpgt.b}
25125 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgt_sc_h (uint32_t, int16_t)
25126 Generated assembler @code{cv.cmpgt.sc.h}
25129 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgt_sc_h (uint32_t, int6_t)
25130 Generated assembler @code{cv.cmpgt.sci.h}
25133 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgt_sc_b (uint32_t, int8_t)
25134 Generated assembler @code{cv.cmpgt.sc.b}
25137 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgt_sc_b (uint32_t, int6_t)
25138 Generated assembler @code{cv.cmpgt.sci.b}
25141 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpge_h (uint32_t, uint32_t)
25142 Generated assembler @code{cv.cmpge.h}
25145 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpge_b (uint32_t, uint32_t)
25146 Generated assembler @code{cv.cmpge.b}
25149 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpge_sc_h (uint32_t, int16_t)
25150 Generated assembler @code{cv.cmpge.sc.h}
25153 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpge_sc_h (uint32_t, int6_t)
25154 Generated assembler @code{cv.cmpge.sci.h}
25157 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpge_sc_b (uint32_t, int8_t)
25158 Generated assembler @code{cv.cmpge.sc.b}
25161 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpge_sc_b (uint32_t, int6_t)
25162 Generated assembler @code{cv.cmpge.sci.b}
25165 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmplt_h (uint32_t, uint32_t)
25166 Generated assembler @code{cv.cmplt.h}
25169 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmplt_b (uint32_t, uint32_t)
25170 Generated assembler @code{cv.cmplt.b}
25173 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmplt_sc_h (uint32_t, int16_t)
25174 Generated assembler @code{cv.cmplt.sc.h}
25177 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmplt_sc_h (uint32_t, int6_t)
25178 Generated assembler @code{cv.cmplt.sci.h}
25181 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmplt_sc_b (uint32_t, int8_t)
25182 Generated assembler @code{cv.cmplt.sc.b}
25185 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmplt_sc_b (uint32_t, int6_t)
25186 Generated assembler @code{cv.cmplt.sci.b}
25189 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmple_h (uint32_t, uint32_t)
25190 Generated assembler @code{cv.cmple.h}
25193 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmple_b (uint32_t, uint32_t)
25194 Generated assembler @code{cv.cmple.b}
25197 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmple_sc_h (uint32_t, int16_t)
25198 Generated assembler @code{cv.cmple.sc.h}
25201 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmple_sc_h (uint32_t, int6_t)
25202 Generated assembler @code{cv.cmple.sci.h}
25205 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmple_sc_b (uint32_t, int8_t)
25206 Generated assembler @code{cv.cmple.sc.b}
25209 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmple_sc_b (uint32_t, int6_t)
25210 Generated assembler @code{cv.cmple.sci.b}
25213 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgtu_h (uint32_t, uint32_t)
25214 Generated assembler @code{cv.cmpgtu.h}
25217 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgtu_b (uint32_t, uint32_t)
25218 Generated assembler @code{cv.cmpgtu.b}
25221 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgtu_sc_h (uint32_t, uint16_t)
25222 Generated assembler @code{cv.cmpgtu.sc.h}
25225 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgtu_sc_h (uint32_t, uint6_t)
25226 Generated assembler @code{cv.cmpgtu.sci.h}
25229 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgtu_sc_b (uint32_t, uint8_t)
25230 Generated assembler @code{cv.cmpgtu.sc.b}
25233 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgtu_sc_b (uint32_t, uint6_t)
25234 Generated assembler @code{cv.cmpgtu.sci.b}
25237 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgeu_h (uint32_t, uint32_t)
25238 Generated assembler @code{cv.cmpgeu.h}
25241 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgeu_b (uint32_t, uint32_t)
25242 Generated assembler @code{cv.cmpgeu.b}
25245 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgeu_sc_h (uint32_t, uint16_t)
25246 Generated assembler @code{cv.cmpgeu.sc.h}
25249 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgeu_sc_h (uint32_t, uint6_t)
25250 Generated assembler @code{cv.cmpgeu.sci.h}
25253 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgeu_sc_b (uint32_t, uint8_t)
25254 Generated assembler @code{cv.cmpgeu.sc.b}
25257 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpgeu_sc_b (uint32_t, uint6_t)
25258 Generated assembler @code{cv.cmpgeu.sci.b}
25261 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpltu_h (uint32_t, uint32_t)
25262 Generated assembler @code{cv.cmpltu.h}
25265 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpltu_b (uint32_t, uint32_t)
25266 Generated assembler @code{cv.cmpltu.b}
25269 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpltu_sc_h (uint32_t, uint16_t)
25270 Generated assembler @code{cv.cmpltu.sc.h}
25273 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpltu_sc_h (uint32_t, uint6_t)
25274 Generated assembler @code{cv.cmpltu.sci.h}
25277 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpltu_sc_b (uint32_t, uint8_t)
25278 Generated assembler @code{cv.cmpltu.sc.b}
25281 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpltu_sc_b (uint32_t, uint6_t)
25282 Generated assembler @code{cv.cmpltu.sci.b}
25285 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpleu_h (uint32_t, uint32_t)
25286 Generated assembler @code{cv.cmpleu.h}
25289 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpleu_b (uint32_t, uint32_t)
25290 Generated assembler @code{cv.cmpleu.b}
25293 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpleu_sc_h (uint32_t, uint16_t)
25294 Generated assembler @code{cv.cmpleu.sc.h}
25297 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpleu_sc_h (uint32_t, uint6_t)
25298 Generated assembler @code{cv.cmpleu.sci.h}
25301 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpleu_sc_b (uint32_t, uint8_t)
25302 Generated assembler @code{cv.cmpleu.sc.b}
25305 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cmpleu_sc_b (uint32_t, uint6_t)
25306 Generated assembler @code{cv.cmpleu.sci.b}
25309 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cplxmul_r (uint32_t, uint32_t, uint32_t, uint4_t)
25310 Generated assembler @code{cv.cplxmul.r}
25313 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cplxmul_i (uint32_t, uint32_t, uint32_t, uint4_t)
25314 Generated assembler @code{cv.cplxmul.i}
25317 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cplxmul_r (uint32_t, uint32_t, uint32_t, uint4_t)
25318 Generated assembler @code{cv.cplxmul.r.div2}
25321 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cplxmul_i (uint32_t, uint32_t, uint32_t, uint4_t)
25322 Generated assembler @code{cv.cplxmul.i.div2}
25325 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cplxmul_r (uint32_t, uint32_t, uint32_t, uint4_t)
25326 Generated assembler @code{cv.cplxmul.r.div4}
25329 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cplxmul_i (uint32_t, uint32_t, uint32_t, uint4_t)
25330 Generated assembler @code{cv.cplxmul.i.div4}
25333 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cplxmul_r (uint32_t, uint32_t, uint32_t, uint4_t)
25334 Generated assembler @code{cv.cplxmul.r.div8}
25337 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cplxmul_i (uint32_t, uint32_t, uint32_t, uint4_t)
25338 Generated assembler @code{cv.cplxmul.i.div8}
25341 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_cplxconj (uint32_t)
25342 Generated assembler @code{cv.cplxconj}
25345 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_subrotmj (uint32_t, uint32_t, uint4_t)
25346 Generated assembler @code{cv.subrotmj}
25349 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_subrotmj (uint32_t, uint32_t, uint32_t, uint4_t)
25350 Generated assembler @code{cv.subrotmj.div2}
25353 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_subrotmj (uint32_t, uint32_t, uint32_t, uint4_t)
25354 Generated assembler @code{cv.subrotmj.div4}
25357 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_subrotmj (uint32_t, uint32_t, uint32_t, uint4_t)
25358 Generated assembler @code{cv.subrotmj.div8}
25361 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_add_h (uint32_t, uint32_t, uint32_t, uint4_t)
25362 Generated assembler @code{cv.add.div2}
25365 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_add_h (uint32_t, uint32_t, uint32_t, uint4_t)
25366 Generated assembler @code{cv.add.div4}
25369 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_add_h (uint32_t, uint32_t, uint32_t, uint4_t)
25370 Generated assembler @code{cv.add.div8}
25373 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sub_h (uint32_t, uint32_t, uint32_t, uint4_t)
25374 Generated assembler @code{cv.sub.div2}
25377 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sub_h (uint32_t, uint32_t, uint32_t, uint4_t)
25378 Generated assembler @code{cv.sub.div4}
25381 @deftypefn {Built-in Function} {uint32_t} __builtin_riscv_cv_simd_sub_h (uint32_t, uint32_t, uint32_t, uint4_t)
25382 Generated assembler @code{cv.sub.div8}
25385 @node RX Built-in Functions
25386 @subsection RX Built-in Functions
25387 GCC supports some of the RX instructions which cannot be expressed in
25388 the C programming language via the use of built-in functions. The
25389 following functions are supported:
25391 @defbuiltin{void __builtin_rx_brk (void)}
25392 Generates the @code{brk} machine instruction.
25395 @defbuiltin{void __builtin_rx_clrpsw (int)}
25396 Generates the @code{clrpsw} machine instruction to clear the specified
25397 bit in the processor status word.
25400 @defbuiltin{void __builtin_rx_int (int)}
25401 Generates the @code{int} machine instruction to generate an interrupt
25402 with the specified value.
25405 @defbuiltin{void __builtin_rx_machi (int, int)}
25406 Generates the @code{machi} machine instruction to add the result of
25407 multiplying the top 16 bits of the two arguments into the
25411 @defbuiltin{void __builtin_rx_maclo (int, int)}
25412 Generates the @code{maclo} machine instruction to add the result of
25413 multiplying the bottom 16 bits of the two arguments into the
25417 @defbuiltin{void __builtin_rx_mulhi (int, int)}
25418 Generates the @code{mulhi} machine instruction to place the result of
25419 multiplying the top 16 bits of the two arguments into the
25423 @defbuiltin{void __builtin_rx_mullo (int, int)}
25424 Generates the @code{mullo} machine instruction to place the result of
25425 multiplying the bottom 16 bits of the two arguments into the
25429 @defbuiltin{int __builtin_rx_mvfachi (void)}
25430 Generates the @code{mvfachi} machine instruction to read the top
25431 32 bits of the accumulator.
25434 @defbuiltin{int __builtin_rx_mvfacmi (void)}
25435 Generates the @code{mvfacmi} machine instruction to read the middle
25436 32 bits of the accumulator.
25439 @defbuiltin{int __builtin_rx_mvfc (int)}
25440 Generates the @code{mvfc} machine instruction which reads the control
25441 register specified in its argument and returns its value.
25444 @defbuiltin{void __builtin_rx_mvtachi (int)}
25445 Generates the @code{mvtachi} machine instruction to set the top
25446 32 bits of the accumulator.
25449 @defbuiltin{void __builtin_rx_mvtaclo (int)}
25450 Generates the @code{mvtaclo} machine instruction to set the bottom
25451 32 bits of the accumulator.
25454 @defbuiltin{void __builtin_rx_mvtc (int @var{reg}, int @var{val})}
25455 Generates the @code{mvtc} machine instruction which sets control
25456 register number @code{reg} to @code{val}.
25459 @defbuiltin{void __builtin_rx_mvtipl (int)}
25460 Generates the @code{mvtipl} machine instruction set the interrupt
25464 @defbuiltin{void __builtin_rx_racw (int)}
25465 Generates the @code{racw} machine instruction to round the accumulator
25466 according to the specified mode.
25469 @defbuiltin{int __builtin_rx_revw (int)}
25470 Generates the @code{revw} machine instruction which swaps the bytes in
25471 the argument so that bits 0--7 now occupy bits 8--15 and vice versa,
25472 and also bits 16--23 occupy bits 24--31 and vice versa.
25475 @defbuiltin{void __builtin_rx_rmpa (void)}
25476 Generates the @code{rmpa} machine instruction which initiates a
25477 repeated multiply and accumulate sequence.
25480 @defbuiltin{void __builtin_rx_round (float)}
25481 Generates the @code{round} machine instruction which returns the
25482 floating-point argument rounded according to the current rounding mode
25483 set in the floating-point status word register.
25486 @defbuiltin{int __builtin_rx_sat (int)}
25487 Generates the @code{sat} machine instruction which returns the
25488 saturated value of the argument.
25491 @defbuiltin{void __builtin_rx_setpsw (int)}
25492 Generates the @code{setpsw} machine instruction to set the specified
25493 bit in the processor status word.
25496 @defbuiltin{void __builtin_rx_wait (void)}
25497 Generates the @code{wait} machine instruction.
25500 @node S/390 System z Built-in Functions
25501 @subsection S/390 System z Built-in Functions
25502 @defbuiltin{int __builtin_tbegin (void*)}
25503 Generates the @code{tbegin} machine instruction starting a
25504 non-constrained hardware transaction. If the parameter is non-NULL the
25505 memory area is used to store the transaction diagnostic buffer and
25506 will be passed as first operand to @code{tbegin}. This buffer can be
25507 defined using the @code{struct __htm_tdb} C struct defined in
25508 @code{htmintrin.h} and must reside on a double-word boundary. The
25509 second tbegin operand is set to @code{0xff0c}. This enables
25510 save/restore of all GPRs and disables aborts for FPR and AR
25511 manipulations inside the transaction body. The condition code set by
25512 the tbegin instruction is returned as integer value. The tbegin
25513 instruction by definition overwrites the content of all FPRs. The
25514 compiler will generate code which saves and restores the FPRs. For
25515 soft-float code it is recommended to used the @code{*_nofloat}
25516 variant. In order to prevent a TDB from being written it is required
25517 to pass a constant zero value as parameter. Passing a zero value
25518 through a variable is not sufficient. Although modifications of
25519 access registers inside the transaction will not trigger an
25520 transaction abort it is not supported to actually modify them. Access
25521 registers do not get saved when entering a transaction. They will have
25522 undefined state when reaching the abort code.
25525 Macros for the possible return codes of tbegin are defined in the
25526 @code{htmintrin.h} header file:
25528 @defmac _HTM_TBEGIN_STARTED
25529 @code{tbegin} has been executed as part of normal processing. The
25530 transaction body is supposed to be executed.
25533 @defmac _HTM_TBEGIN_INDETERMINATE
25534 The transaction was aborted due to an indeterminate condition which
25535 might be persistent.
25538 @defmac _HTM_TBEGIN_TRANSIENT
25539 The transaction aborted due to a transient failure. The transaction
25540 should be re-executed in that case.
25543 @defmac _HTM_TBEGIN_PERSISTENT
25544 The transaction aborted due to a persistent failure. Re-execution
25545 under same circumstances will not be productive.
25548 @defmac _HTM_FIRST_USER_ABORT_CODE
25549 The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h}
25550 specifies the first abort code which can be used for
25551 @code{__builtin_tabort}. Values below this threshold are reserved for
25555 @deftp {Data type} {struct __htm_tdb}
25556 The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes
25557 the structure of the transaction diagnostic block as specified in the
25558 Principles of Operation manual chapter 5-91.
25561 @defbuiltin{int __builtin_tbegin_nofloat (void*)}
25562 Same as @code{__builtin_tbegin} but without FPR saves and restores.
25563 Using this variant in code making use of FPRs will leave the FPRs in
25564 undefined state when entering the transaction abort handler code.
25567 @defbuiltin{int __builtin_tbegin_retry (void*, int)}
25568 In addition to @code{__builtin_tbegin} a loop for transient failures
25569 is generated. If tbegin returns a condition code of 2 the transaction
25570 will be retried as often as specified in the second argument. The
25571 perform processor assist instruction is used to tell the CPU about the
25572 number of fails so far.
25575 @defbuiltin{int __builtin_tbegin_retry_nofloat (void*, int)}
25576 Same as @code{__builtin_tbegin_retry} but without FPR saves and
25577 restores. Using this variant in code making use of FPRs will leave
25578 the FPRs in undefined state when entering the transaction abort
25582 @defbuiltin{void __builtin_tbeginc (void)}
25583 Generates the @code{tbeginc} machine instruction starting a constrained
25584 hardware transaction. The second operand is set to @code{0xff08}.
25587 @defbuiltin{int __builtin_tend (void)}
25588 Generates the @code{tend} machine instruction finishing a transaction
25589 and making the changes visible to other threads. The condition code
25590 generated by tend is returned as integer value.
25593 @defbuiltin{void __builtin_tabort (int)}
25594 Generates the @code{tabort} machine instruction with the specified
25595 abort code. Abort codes from 0 through 255 are reserved and will
25596 result in an error message.
25599 @defbuiltin{void __builtin_tx_assist (int)}
25600 Generates the @code{ppa rX,rY,1} machine instruction. Where the
25601 integer parameter is loaded into rX and a value of zero is loaded into
25602 rY. The integer parameter specifies the number of times the
25603 transaction repeatedly aborted.
25606 @defbuiltin{int __builtin_tx_nesting_depth (void)}
25607 Generates the @code{etnd} machine instruction. The current nesting
25608 depth is returned as integer value. For a nesting depth of 0 the code
25609 is not executed as part of an transaction.
25612 @defbuiltin{void __builtin_non_tx_store (uint64_t *, uint64_t)}
25614 Generates the @code{ntstg} machine instruction. The second argument
25615 is written to the first arguments location. The store operation will
25616 not be rolled-back in case of an transaction abort.
25619 @node SH Built-in Functions
25620 @subsection SH Built-in Functions
25621 The following built-in functions are supported on the SH1, SH2, SH3 and SH4
25622 families of processors:
25624 @defbuiltin{{void} __builtin_set_thread_pointer (void *@var{ptr})}
25625 Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually
25626 used by system code that manages threads and execution contexts. The compiler
25627 normally does not generate code that modifies the contents of @samp{GBR} and
25628 thus the value is preserved across function calls. Changing the @samp{GBR}
25629 value in user code must be done with caution, since the compiler might use
25630 @samp{GBR} in order to access thread local variables.
25634 @defbuiltin{{void *} __builtin_thread_pointer (void)}
25635 Returns the value that is currently set in the @samp{GBR} register.
25636 Memory loads and stores that use the thread pointer as a base address are
25637 turned into @samp{GBR} based displacement loads and stores, if possible.
25645 int get_tcb_value (void)
25647 // Generate @samp{mov.l @@(8,gbr),r0} instruction
25648 return ((my_tcb*)__builtin_thread_pointer ())->c;
25654 @defbuiltin{{unsigned int} __builtin_sh_get_fpscr (void)}
25655 Returns the value that is currently set in the @samp{FPSCR} register.
25658 @defbuiltin{{void} __builtin_sh_set_fpscr (unsigned int @var{val})}
25659 Sets the @samp{FPSCR} register to the specified value @var{val}, while
25660 preserving the current values of the FR, SZ and PR bits.
25663 @node SPARC VIS Built-in Functions
25664 @subsection SPARC VIS Built-in Functions
25666 GCC supports SIMD operations on the SPARC using both the generic vector
25667 extensions (@pxref{Vector Extensions}) as well as built-in functions for
25668 the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis}
25669 switch, the VIS extension is exposed as the following built-in functions:
25672 typedef int v1si __attribute__ ((vector_size (4)));
25673 typedef int v2si __attribute__ ((vector_size (8)));
25674 typedef short v4hi __attribute__ ((vector_size (8)));
25675 typedef short v2hi __attribute__ ((vector_size (4)));
25676 typedef unsigned char v8qi __attribute__ ((vector_size (8)));
25677 typedef unsigned char v4qi __attribute__ ((vector_size (4)));
25679 void __builtin_vis_write_gsr (int64_t);
25680 int64_t __builtin_vis_read_gsr (void);
25682 void * __builtin_vis_alignaddr (void *, long);
25683 void * __builtin_vis_alignaddrl (void *, long);
25684 int64_t __builtin_vis_faligndatadi (int64_t, int64_t);
25685 v2si __builtin_vis_faligndatav2si (v2si, v2si);
25686 v4hi __builtin_vis_faligndatav4hi (v4si, v4si);
25687 v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi);
25689 v4hi __builtin_vis_fexpand (v4qi);
25691 v4hi __builtin_vis_fmul8x16 (v4qi, v4hi);
25692 v4hi __builtin_vis_fmul8x16au (v4qi, v2hi);
25693 v4hi __builtin_vis_fmul8x16al (v4qi, v2hi);
25694 v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi);
25695 v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi);
25696 v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi);
25697 v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi);
25699 v4qi __builtin_vis_fpack16 (v4hi);
25700 v8qi __builtin_vis_fpack32 (v2si, v8qi);
25701 v2hi __builtin_vis_fpackfix (v2si);
25702 v8qi __builtin_vis_fpmerge (v4qi, v4qi);
25704 int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t);
25706 long __builtin_vis_edge8 (void *, void *);
25707 long __builtin_vis_edge8l (void *, void *);
25708 long __builtin_vis_edge16 (void *, void *);
25709 long __builtin_vis_edge16l (void *, void *);
25710 long __builtin_vis_edge32 (void *, void *);
25711 long __builtin_vis_edge32l (void *, void *);
25713 long __builtin_vis_fcmple16 (v4hi, v4hi);
25714 long __builtin_vis_fcmple32 (v2si, v2si);
25715 long __builtin_vis_fcmpne16 (v4hi, v4hi);
25716 long __builtin_vis_fcmpne32 (v2si, v2si);
25717 long __builtin_vis_fcmpgt16 (v4hi, v4hi);
25718 long __builtin_vis_fcmpgt32 (v2si, v2si);
25719 long __builtin_vis_fcmpeq16 (v4hi, v4hi);
25720 long __builtin_vis_fcmpeq32 (v2si, v2si);
25722 v4hi __builtin_vis_fpadd16 (v4hi, v4hi);
25723 v2hi __builtin_vis_fpadd16s (v2hi, v2hi);
25724 v2si __builtin_vis_fpadd32 (v2si, v2si);
25725 v1si __builtin_vis_fpadd32s (v1si, v1si);
25726 v4hi __builtin_vis_fpsub16 (v4hi, v4hi);
25727 v2hi __builtin_vis_fpsub16s (v2hi, v2hi);
25728 v2si __builtin_vis_fpsub32 (v2si, v2si);
25729 v1si __builtin_vis_fpsub32s (v1si, v1si);
25731 long __builtin_vis_array8 (long, long);
25732 long __builtin_vis_array16 (long, long);
25733 long __builtin_vis_array32 (long, long);
25736 When you use the @option{-mvis2} switch, the VIS version 2.0 built-in
25737 functions also become available:
25740 long __builtin_vis_bmask (long, long);
25741 int64_t __builtin_vis_bshuffledi (int64_t, int64_t);
25742 v2si __builtin_vis_bshufflev2si (v2si, v2si);
25743 v4hi __builtin_vis_bshufflev2si (v4hi, v4hi);
25744 v8qi __builtin_vis_bshufflev2si (v8qi, v8qi);
25746 long __builtin_vis_edge8n (void *, void *);
25747 long __builtin_vis_edge8ln (void *, void *);
25748 long __builtin_vis_edge16n (void *, void *);
25749 long __builtin_vis_edge16ln (void *, void *);
25750 long __builtin_vis_edge32n (void *, void *);
25751 long __builtin_vis_edge32ln (void *, void *);
25754 When you use the @option{-mvis3} switch, the VIS version 3.0 built-in
25755 functions also become available:
25758 void __builtin_vis_cmask8 (long);
25759 void __builtin_vis_cmask16 (long);
25760 void __builtin_vis_cmask32 (long);
25762 v4hi __builtin_vis_fchksm16 (v4hi, v4hi);
25764 v4hi __builtin_vis_fsll16 (v4hi, v4hi);
25765 v4hi __builtin_vis_fslas16 (v4hi, v4hi);
25766 v4hi __builtin_vis_fsrl16 (v4hi, v4hi);
25767 v4hi __builtin_vis_fsra16 (v4hi, v4hi);
25768 v2si __builtin_vis_fsll16 (v2si, v2si);
25769 v2si __builtin_vis_fslas16 (v2si, v2si);
25770 v2si __builtin_vis_fsrl16 (v2si, v2si);
25771 v2si __builtin_vis_fsra16 (v2si, v2si);
25773 long __builtin_vis_pdistn (v8qi, v8qi);
25775 v4hi __builtin_vis_fmean16 (v4hi, v4hi);
25777 int64_t __builtin_vis_fpadd64 (int64_t, int64_t);
25778 int64_t __builtin_vis_fpsub64 (int64_t, int64_t);
25780 v4hi __builtin_vis_fpadds16 (v4hi, v4hi);
25781 v2hi __builtin_vis_fpadds16s (v2hi, v2hi);
25782 v4hi __builtin_vis_fpsubs16 (v4hi, v4hi);
25783 v2hi __builtin_vis_fpsubs16s (v2hi, v2hi);
25784 v2si __builtin_vis_fpadds32 (v2si, v2si);
25785 v1si __builtin_vis_fpadds32s (v1si, v1si);
25786 v2si __builtin_vis_fpsubs32 (v2si, v2si);
25787 v1si __builtin_vis_fpsubs32s (v1si, v1si);
25789 long __builtin_vis_fucmple8 (v8qi, v8qi);
25790 long __builtin_vis_fucmpne8 (v8qi, v8qi);
25791 long __builtin_vis_fucmpgt8 (v8qi, v8qi);
25792 long __builtin_vis_fucmpeq8 (v8qi, v8qi);
25794 float __builtin_vis_fhadds (float, float);
25795 double __builtin_vis_fhaddd (double, double);
25796 float __builtin_vis_fhsubs (float, float);
25797 double __builtin_vis_fhsubd (double, double);
25798 float __builtin_vis_fnhadds (float, float);
25799 double __builtin_vis_fnhaddd (double, double);
25801 int64_t __builtin_vis_umulxhi (int64_t, int64_t);
25802 int64_t __builtin_vis_xmulx (int64_t, int64_t);
25803 int64_t __builtin_vis_xmulxhi (int64_t, int64_t);
25806 When you use the @option{-mvis4} switch, the VIS version 4.0 built-in
25807 functions also become available:
25810 v8qi __builtin_vis_fpadd8 (v8qi, v8qi);
25811 v8qi __builtin_vis_fpadds8 (v8qi, v8qi);
25812 v8qi __builtin_vis_fpaddus8 (v8qi, v8qi);
25813 v4hi __builtin_vis_fpaddus16 (v4hi, v4hi);
25815 v8qi __builtin_vis_fpsub8 (v8qi, v8qi);
25816 v8qi __builtin_vis_fpsubs8 (v8qi, v8qi);
25817 v8qi __builtin_vis_fpsubus8 (v8qi, v8qi);
25818 v4hi __builtin_vis_fpsubus16 (v4hi, v4hi);
25820 long __builtin_vis_fpcmple8 (v8qi, v8qi);
25821 long __builtin_vis_fpcmpgt8 (v8qi, v8qi);
25822 long __builtin_vis_fpcmpule16 (v4hi, v4hi);
25823 long __builtin_vis_fpcmpugt16 (v4hi, v4hi);
25824 long __builtin_vis_fpcmpule32 (v2si, v2si);
25825 long __builtin_vis_fpcmpugt32 (v2si, v2si);
25827 v8qi __builtin_vis_fpmax8 (v8qi, v8qi);
25828 v4hi __builtin_vis_fpmax16 (v4hi, v4hi);
25829 v2si __builtin_vis_fpmax32 (v2si, v2si);
25831 v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi);
25832 v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi);
25833 v2si __builtin_vis_fpmaxu32 (v2si, v2si);
25835 v8qi __builtin_vis_fpmin8 (v8qi, v8qi);
25836 v4hi __builtin_vis_fpmin16 (v4hi, v4hi);
25837 v2si __builtin_vis_fpmin32 (v2si, v2si);
25839 v8qi __builtin_vis_fpminu8 (v8qi, v8qi);
25840 v4hi __builtin_vis_fpminu16 (v4hi, v4hi);
25841 v2si __builtin_vis_fpminu32 (v2si, v2si);
25844 When you use the @option{-mvis4b} switch, the VIS version 4.0B
25845 built-in functions also become available:
25848 v8qi __builtin_vis_dictunpack8 (double, int);
25849 v4hi __builtin_vis_dictunpack16 (double, int);
25850 v2si __builtin_vis_dictunpack32 (double, int);
25852 long __builtin_vis_fpcmple8shl (v8qi, v8qi, int);
25853 long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int);
25854 long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int);
25855 long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int);
25857 long __builtin_vis_fpcmple16shl (v4hi, v4hi, int);
25858 long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int);
25859 long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int);
25860 long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int);
25862 long __builtin_vis_fpcmple32shl (v2si, v2si, int);
25863 long __builtin_vis_fpcmpgt32shl (v2si, v2si, int);
25864 long __builtin_vis_fpcmpeq32shl (v2si, v2si, int);
25865 long __builtin_vis_fpcmpne32shl (v2si, v2si, int);
25867 long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int);
25868 long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int);
25869 long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int);
25870 long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int);
25871 long __builtin_vis_fpcmpule32shl (v2si, v2si, int);
25872 long __builtin_vis_fpcmpugt32shl (v2si, v2si, int);
25874 long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int);
25875 long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int);
25876 long __builtin_vis_fpcmpde32shl (v2si, v2si, int);
25878 long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int);
25879 long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int);
25880 long __builtin_vis_fpcmpur32shl (v2si, v2si, int);
25883 @node TI C6X Built-in Functions
25884 @subsection TI C6X Built-in Functions
25886 GCC provides intrinsics to access certain instructions of the TI C6X
25887 processors. These intrinsics, listed below, are available after
25888 inclusion of the @code{c6x_intrinsics.h} header file. They map directly
25889 to C6X instructions.
25892 int _sadd (int, int);
25893 int _ssub (int, int);
25894 int _sadd2 (int, int);
25895 int _ssub2 (int, int);
25896 long long _mpy2 (int, int);
25897 long long _smpy2 (int, int);
25898 int _add4 (int, int);
25899 int _sub4 (int, int);
25900 int _saddu4 (int, int);
25902 int _smpy (int, int);
25903 int _smpyh (int, int);
25904 int _smpyhl (int, int);
25905 int _smpylh (int, int);
25907 int _sshl (int, int);
25908 int _subc (int, int);
25910 int _avg2 (int, int);
25911 int _avgu4 (int, int);
25913 int _clrr (int, int);
25914 int _extr (int, int);
25915 int _extru (int, int);
25920 @node x86 Built-in Functions
25921 @subsection x86 Built-in Functions
25923 These built-in functions are available for the x86-32 and x86-64 family
25924 of computers, depending on the command-line switches used.
25926 If you specify command-line switches such as @option{-msse},
25927 the compiler could use the extended instruction sets even if the built-ins
25928 are not used explicitly in the program. For this reason, applications
25929 that perform run-time CPU detection must compile separate files for each
25930 supported architecture, using the appropriate flags. In particular,
25931 the file containing the CPU detection code should be compiled without
25934 The following machine modes are available for use with MMX built-in functions
25935 (@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers,
25936 @code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a
25937 vector of eight 8-bit integers. Some of the built-in functions operate on
25938 MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode.
25940 If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector
25941 of two 32-bit floating-point values.
25943 If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit
25944 floating-point values. Some instructions use a vector of four 32-bit
25945 integers, these use @code{V4SI}. Finally, some instructions operate on an
25946 entire vector register, interpreting it as a 128-bit integer, these use mode
25949 The x86-32 and x86-64 family of processors use additional built-in
25950 functions for efficient use of @code{TF} (@code{__float128}) 128-bit
25951 floating point and @code{TC} 128-bit complex floating-point values.
25953 The following floating-point built-in functions are always available:
25955 @defbuiltin{__float128 __builtin_fabsq (__float128 @var{x}))}
25956 Computes the absolute value of @var{x}.
25959 @defbuiltin{__float128 __builtin_copysignq (__float128 @var{x}, @
25960 __float128 @var{y})}
25961 Copies the sign of @var{y} into @var{x} and returns the new value of
25965 @defbuiltin{__float128 __builtin_infq (void)}
25966 Similar to @code{__builtin_inf}, except the return type is @code{__float128}.
25969 @defbuiltin{__float128 __builtin_huge_valq (void)}
25970 Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}.
25973 @defbuiltin{__float128 __builtin_nanq (void)}
25974 Similar to @code{__builtin_nan}, except the return type is @code{__float128}.
25977 @defbuiltin{__float128 __builtin_nansq (void)}
25978 Similar to @code{__builtin_nans}, except the return type is @code{__float128}.
25981 The following built-in function is always available.
25983 @defbuiltin{void __builtin_ia32_pause (void)}
25984 Generates the @code{pause} machine instruction with a compiler memory
25988 The following built-in functions are always available and can be used to
25989 check the target platform type.
25991 @defbuiltin{void __builtin_cpu_init (void)}
25992 This function runs the CPU detection code to check the type of CPU and the
25993 features supported. This built-in function needs to be invoked along with the built-in functions
25994 to check CPU type and features, @code{__builtin_cpu_is} and
25995 @code{__builtin_cpu_supports}, only when used in a function that is
25996 executed before any constructors are called. The CPU detection code is
25997 automatically executed in a very high priority constructor.
25999 For example, this function has to be used in @code{ifunc} resolvers that
26000 check for CPU type using the built-in functions @code{__builtin_cpu_is}
26001 and @code{__builtin_cpu_supports}, or in constructors on targets that
26002 don't support constructor priority.
26005 static void (*resolve_memcpy (void)) (void)
26007 // ifunc resolvers fire before constructors, explicitly call the init
26009 __builtin_cpu_init ();
26010 if (__builtin_cpu_supports ("ssse3"))
26011 return ssse3_memcpy; // super fast memcpy with ssse3 instructions.
26013 return default_memcpy;
26016 void *memcpy (void *, const void *, size_t)
26017 __attribute__ ((ifunc ("resolve_memcpy")));
26022 @defbuiltin{int __builtin_cpu_is (const char *@var{cpuname})}
26023 This function returns a positive integer if the run-time CPU
26024 is of type @var{cpuname}
26025 and returns @code{0} otherwise. The following CPU names can be detected:
26038 Intel Silvermont CPU.
26047 Intel Core i7 Nehalem CPU.
26050 Intel Core i7 Westmere CPU.
26053 Intel Core i7 Sandy Bridge CPU.
26056 Intel Core i7 Ivy Bridge CPU.
26059 Intel Core i7 Haswell CPU.
26062 Intel Core i7 Broadwell CPU.
26065 Intel Core i7 Skylake CPU.
26067 @item skylake-avx512
26068 Intel Core i7 Skylake AVX512 CPU.
26071 Intel Core i7 Cannon Lake CPU.
26073 @item icelake-client
26074 Intel Core i7 Ice Lake Client CPU.
26076 @item icelake-server
26077 Intel Core i7 Ice Lake Server CPU.
26080 Intel Core i7 Cascadelake CPU.
26083 Intel Core i7 Tigerlake CPU.
26086 Intel Core i7 Cooperlake CPU.
26088 @item sapphirerapids
26089 Intel Core i7 sapphirerapids CPU.
26092 Intel Core i7 Alderlake CPU.
26095 Intel Core i7 Rocketlake CPU.
26097 @item graniterapids
26098 Intel Core i7 graniterapids CPU.
26100 @item graniterapids-d
26101 Intel Core i7 graniterapids D CPU.
26104 Intel Core i7 Arrow Lake CPU.
26107 Intel Core i7 Arrow Lake S CPU.
26110 Intel Core i7 Panther Lake CPU.
26113 Intel Atom Bonnell CPU.
26116 Intel Atom Silvermont CPU.
26119 Intel Atom Goldmont CPU.
26121 @item goldmont-plus
26122 Intel Atom Goldmont Plus CPU.
26125 Intel Atom Tremont CPU.
26128 Intel Atom Sierra Forest CPU.
26131 Intel Atom Grand Ridge CPU.
26133 @item clearwaterforest
26134 Intel Atom Clearwater Forest CPU.
26137 Intel Knights Landing CPU.
26140 Intel Knights Mill CPU.
26143 ZHAOXIN lujiazui CPU.
26146 ZHAOXIN yongfeng CPU.
26149 AMD Family 10h CPU.
26152 AMD Family 10h Barcelona CPU.
26155 AMD Family 10h Shanghai CPU.
26158 AMD Family 10h Istanbul CPU.
26161 AMD Family 14h CPU.
26164 AMD Family 15h CPU.
26167 AMD Family 15h Bulldozer version 1.
26170 AMD Family 15h Bulldozer version 2.
26173 AMD Family 15h Bulldozer version 3.
26176 AMD Family 15h Bulldozer version 4.
26179 AMD Family 16h CPU.
26182 AMD Family 17h CPU.
26185 AMD Family 17h Zen version 1.
26188 AMD Family 17h Zen version 2.
26191 AMD Family 19h CPU.
26194 AMD Family 19h Zen version 3.
26197 AMD Family 19h Zen version 4.
26200 AMD Family 1ah Zen version 5.
26203 Here is an example:
26205 if (__builtin_cpu_is ("corei7"))
26207 do_corei7 (); // Core i7 specific implementation.
26211 do_generic (); // Generic implementation.
26216 @defbuiltin{int __builtin_cpu_supports (const char *@var{feature})}
26217 This function returns a positive integer if the run-time CPU
26218 supports @var{feature}
26219 and returns @code{0} otherwise. The following features can be detected:
26227 POPCNT instruction.
26235 SSSE3 instructions.
26237 SSE4.1 instructions.
26239 SSE4.2 instructions.
26245 SSE4A instructions.
26253 AVX512F instructions.
26261 PCLMUL instructions.
26263 AVX512VL instructions.
26265 AVX512BW instructions.
26267 AVX512DQ instructions.
26269 AVX512CD instructions.
26271 AVX512ER instructions.
26273 AVX512PF instructions.
26275 AVX512VBMI instructions.
26277 AVX512IFMA instructions.
26279 AVX5124VNNIW instructions.
26281 AVX5124FMAPS instructions.
26282 @item avx512vpopcntdq
26283 AVX512VPOPCNTDQ instructions.
26285 AVX512VBMI2 instructions.
26289 VPCLMULQDQ instructions.
26291 AVX512VNNI instructions.
26293 AVX512BITALG instructions.
26295 Baseline x86-64 microarchitecture level (as defined in x86-64 psABI).
26297 x86-64-v2 microarchitecture level.
26299 x86-64-v3 microarchitecture level.
26301 x86-64-v4 microarchitecture level.
26306 Here is an example:
26308 if (__builtin_cpu_supports ("popcnt"))
26310 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc");
26314 count = generic_countbits (n); //generic implementation.
26319 The following built-in functions are made available by @option{-mmmx}.
26320 All of them generate the machine instruction that is part of the name.
26323 v8qi __builtin_ia32_paddb (v8qi, v8qi);
26324 v4hi __builtin_ia32_paddw (v4hi, v4hi);
26325 v2si __builtin_ia32_paddd (v2si, v2si);
26326 v8qi __builtin_ia32_psubb (v8qi, v8qi);
26327 v4hi __builtin_ia32_psubw (v4hi, v4hi);
26328 v2si __builtin_ia32_psubd (v2si, v2si);
26329 v8qi __builtin_ia32_paddsb (v8qi, v8qi);
26330 v4hi __builtin_ia32_paddsw (v4hi, v4hi);
26331 v8qi __builtin_ia32_psubsb (v8qi, v8qi);
26332 v4hi __builtin_ia32_psubsw (v4hi, v4hi);
26333 v8qi __builtin_ia32_paddusb (v8qi, v8qi);
26334 v4hi __builtin_ia32_paddusw (v4hi, v4hi);
26335 v8qi __builtin_ia32_psubusb (v8qi, v8qi);
26336 v4hi __builtin_ia32_psubusw (v4hi, v4hi);
26337 v4hi __builtin_ia32_pmullw (v4hi, v4hi);
26338 v4hi __builtin_ia32_pmulhw (v4hi, v4hi);
26339 di __builtin_ia32_pand (di, di);
26340 di __builtin_ia32_pandn (di,di);
26341 di __builtin_ia32_por (di, di);
26342 di __builtin_ia32_pxor (di, di);
26343 v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi);
26344 v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi);
26345 v2si __builtin_ia32_pcmpeqd (v2si, v2si);
26346 v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi);
26347 v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi);
26348 v2si __builtin_ia32_pcmpgtd (v2si, v2si);
26349 v8qi __builtin_ia32_punpckhbw (v8qi, v8qi);
26350 v4hi __builtin_ia32_punpckhwd (v4hi, v4hi);
26351 v2si __builtin_ia32_punpckhdq (v2si, v2si);
26352 v8qi __builtin_ia32_punpcklbw (v8qi, v8qi);
26353 v4hi __builtin_ia32_punpcklwd (v4hi, v4hi);
26354 v2si __builtin_ia32_punpckldq (v2si, v2si);
26355 v8qi __builtin_ia32_packsswb (v4hi, v4hi);
26356 v4hi __builtin_ia32_packssdw (v2si, v2si);
26357 v8qi __builtin_ia32_packuswb (v4hi, v4hi);
26359 v4hi __builtin_ia32_psllw (v4hi, v4hi);
26360 v2si __builtin_ia32_pslld (v2si, v2si);
26361 v1di __builtin_ia32_psllq (v1di, v1di);
26362 v4hi __builtin_ia32_psrlw (v4hi, v4hi);
26363 v2si __builtin_ia32_psrld (v2si, v2si);
26364 v1di __builtin_ia32_psrlq (v1di, v1di);
26365 v4hi __builtin_ia32_psraw (v4hi, v4hi);
26366 v2si __builtin_ia32_psrad (v2si, v2si);
26367 v4hi __builtin_ia32_psllwi (v4hi, int);
26368 v2si __builtin_ia32_pslldi (v2si, int);
26369 v1di __builtin_ia32_psllqi (v1di, int);
26370 v4hi __builtin_ia32_psrlwi (v4hi, int);
26371 v2si __builtin_ia32_psrldi (v2si, int);
26372 v1di __builtin_ia32_psrlqi (v1di, int);
26373 v4hi __builtin_ia32_psrawi (v4hi, int);
26374 v2si __builtin_ia32_psradi (v2si, int);
26377 The following built-in functions are made available either with
26378 @option{-msse}, or with @option{-m3dnowa}. All of them generate
26379 the machine instruction that is part of the name.
26382 v4hi __builtin_ia32_pmulhuw (v4hi, v4hi);
26383 v8qi __builtin_ia32_pavgb (v8qi, v8qi);
26384 v4hi __builtin_ia32_pavgw (v4hi, v4hi);
26385 v1di __builtin_ia32_psadbw (v8qi, v8qi);
26386 v8qi __builtin_ia32_pmaxub (v8qi, v8qi);
26387 v4hi __builtin_ia32_pmaxsw (v4hi, v4hi);
26388 v8qi __builtin_ia32_pminub (v8qi, v8qi);
26389 v4hi __builtin_ia32_pminsw (v4hi, v4hi);
26390 int __builtin_ia32_pmovmskb (v8qi);
26391 void __builtin_ia32_maskmovq (v8qi, v8qi, char *);
26392 void __builtin_ia32_movntq (di *, di);
26393 void __builtin_ia32_sfence (void);
26396 The following built-in functions are available when @option{-msse} is used.
26397 All of them generate the machine instruction that is part of the name.
26400 int __builtin_ia32_comieq (v4sf, v4sf);
26401 int __builtin_ia32_comineq (v4sf, v4sf);
26402 int __builtin_ia32_comilt (v4sf, v4sf);
26403 int __builtin_ia32_comile (v4sf, v4sf);
26404 int __builtin_ia32_comigt (v4sf, v4sf);
26405 int __builtin_ia32_comige (v4sf, v4sf);
26406 int __builtin_ia32_ucomieq (v4sf, v4sf);
26407 int __builtin_ia32_ucomineq (v4sf, v4sf);
26408 int __builtin_ia32_ucomilt (v4sf, v4sf);
26409 int __builtin_ia32_ucomile (v4sf, v4sf);
26410 int __builtin_ia32_ucomigt (v4sf, v4sf);
26411 int __builtin_ia32_ucomige (v4sf, v4sf);
26412 v4sf __builtin_ia32_addps (v4sf, v4sf);
26413 v4sf __builtin_ia32_subps (v4sf, v4sf);
26414 v4sf __builtin_ia32_mulps (v4sf, v4sf);
26415 v4sf __builtin_ia32_divps (v4sf, v4sf);
26416 v4sf __builtin_ia32_addss (v4sf, v4sf);
26417 v4sf __builtin_ia32_subss (v4sf, v4sf);
26418 v4sf __builtin_ia32_mulss (v4sf, v4sf);
26419 v4sf __builtin_ia32_divss (v4sf, v4sf);
26420 v4sf __builtin_ia32_cmpeqps (v4sf, v4sf);
26421 v4sf __builtin_ia32_cmpltps (v4sf, v4sf);
26422 v4sf __builtin_ia32_cmpleps (v4sf, v4sf);
26423 v4sf __builtin_ia32_cmpgtps (v4sf, v4sf);
26424 v4sf __builtin_ia32_cmpgeps (v4sf, v4sf);
26425 v4sf __builtin_ia32_cmpunordps (v4sf, v4sf);
26426 v4sf __builtin_ia32_cmpneqps (v4sf, v4sf);
26427 v4sf __builtin_ia32_cmpnltps (v4sf, v4sf);
26428 v4sf __builtin_ia32_cmpnleps (v4sf, v4sf);
26429 v4sf __builtin_ia32_cmpngtps (v4sf, v4sf);
26430 v4sf __builtin_ia32_cmpngeps (v4sf, v4sf);
26431 v4sf __builtin_ia32_cmpordps (v4sf, v4sf);
26432 v4sf __builtin_ia32_cmpeqss (v4sf, v4sf);
26433 v4sf __builtin_ia32_cmpltss (v4sf, v4sf);
26434 v4sf __builtin_ia32_cmpless (v4sf, v4sf);
26435 v4sf __builtin_ia32_cmpunordss (v4sf, v4sf);
26436 v4sf __builtin_ia32_cmpneqss (v4sf, v4sf);
26437 v4sf __builtin_ia32_cmpnltss (v4sf, v4sf);
26438 v4sf __builtin_ia32_cmpnless (v4sf, v4sf);
26439 v4sf __builtin_ia32_cmpordss (v4sf, v4sf);
26440 v4sf __builtin_ia32_maxps (v4sf, v4sf);
26441 v4sf __builtin_ia32_maxss (v4sf, v4sf);
26442 v4sf __builtin_ia32_minps (v4sf, v4sf);
26443 v4sf __builtin_ia32_minss (v4sf, v4sf);
26444 v4sf __builtin_ia32_andps (v4sf, v4sf);
26445 v4sf __builtin_ia32_andnps (v4sf, v4sf);
26446 v4sf __builtin_ia32_orps (v4sf, v4sf);
26447 v4sf __builtin_ia32_xorps (v4sf, v4sf);
26448 v4sf __builtin_ia32_movss (v4sf, v4sf);
26449 v4sf __builtin_ia32_movhlps (v4sf, v4sf);
26450 v4sf __builtin_ia32_movlhps (v4sf, v4sf);
26451 v4sf __builtin_ia32_unpckhps (v4sf, v4sf);
26452 v4sf __builtin_ia32_unpcklps (v4sf, v4sf);
26453 v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si);
26454 v4sf __builtin_ia32_cvtsi2ss (v4sf, int);
26455 v2si __builtin_ia32_cvtps2pi (v4sf);
26456 int __builtin_ia32_cvtss2si (v4sf);
26457 v2si __builtin_ia32_cvttps2pi (v4sf);
26458 int __builtin_ia32_cvttss2si (v4sf);
26459 v4sf __builtin_ia32_rcpps (v4sf);
26460 v4sf __builtin_ia32_rsqrtps (v4sf);
26461 v4sf __builtin_ia32_sqrtps (v4sf);
26462 v4sf __builtin_ia32_rcpss (v4sf);
26463 v4sf __builtin_ia32_rsqrtss (v4sf);
26464 v4sf __builtin_ia32_sqrtss (v4sf);
26465 v4sf __builtin_ia32_shufps (v4sf, v4sf, int);
26466 void __builtin_ia32_movntps (float *, v4sf);
26467 int __builtin_ia32_movmskps (v4sf);
26470 The following built-in functions are available when @option{-msse} is used.
26472 @defbuiltin{v4sf __builtin_ia32_loadups (float *)}
26473 Generates the @code{movups} machine instruction as a load from memory.
26476 @defbuiltin{void __builtin_ia32_storeups (float *, v4sf)}
26477 Generates the @code{movups} machine instruction as a store to memory.
26480 @defbuiltin{v4sf __builtin_ia32_loadss (float *)}
26481 Generates the @code{movss} machine instruction as a load from memory.
26484 @defbuiltin{v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)}
26485 Generates the @code{movhps} machine instruction as a load from memory.
26488 @defbuiltin{v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)}
26489 Generates the @code{movlps} machine instruction as a load from memory
26492 @defbuiltin{void __builtin_ia32_storehps (v2sf *, v4sf)}
26493 Generates the @code{movhps} machine instruction as a store to memory.
26496 @defbuiltin{void __builtin_ia32_storelps (v2sf *, v4sf)}
26497 Generates the @code{movlps} machine instruction as a store to memory.
26500 The following built-in functions are available when @option{-msse2} is used.
26501 All of them generate the machine instruction that is part of the name.
26504 int __builtin_ia32_comisdeq (v2df, v2df);
26505 int __builtin_ia32_comisdlt (v2df, v2df);
26506 int __builtin_ia32_comisdle (v2df, v2df);
26507 int __builtin_ia32_comisdgt (v2df, v2df);
26508 int __builtin_ia32_comisdge (v2df, v2df);
26509 int __builtin_ia32_comisdneq (v2df, v2df);
26510 int __builtin_ia32_ucomisdeq (v2df, v2df);
26511 int __builtin_ia32_ucomisdlt (v2df, v2df);
26512 int __builtin_ia32_ucomisdle (v2df, v2df);
26513 int __builtin_ia32_ucomisdgt (v2df, v2df);
26514 int __builtin_ia32_ucomisdge (v2df, v2df);
26515 int __builtin_ia32_ucomisdneq (v2df, v2df);
26516 v2df __builtin_ia32_cmpeqpd (v2df, v2df);
26517 v2df __builtin_ia32_cmpltpd (v2df, v2df);
26518 v2df __builtin_ia32_cmplepd (v2df, v2df);
26519 v2df __builtin_ia32_cmpgtpd (v2df, v2df);
26520 v2df __builtin_ia32_cmpgepd (v2df, v2df);
26521 v2df __builtin_ia32_cmpunordpd (v2df, v2df);
26522 v2df __builtin_ia32_cmpneqpd (v2df, v2df);
26523 v2df __builtin_ia32_cmpnltpd (v2df, v2df);
26524 v2df __builtin_ia32_cmpnlepd (v2df, v2df);
26525 v2df __builtin_ia32_cmpngtpd (v2df, v2df);
26526 v2df __builtin_ia32_cmpngepd (v2df, v2df);
26527 v2df __builtin_ia32_cmpordpd (v2df, v2df);
26528 v2df __builtin_ia32_cmpeqsd (v2df, v2df);
26529 v2df __builtin_ia32_cmpltsd (v2df, v2df);
26530 v2df __builtin_ia32_cmplesd (v2df, v2df);
26531 v2df __builtin_ia32_cmpunordsd (v2df, v2df);
26532 v2df __builtin_ia32_cmpneqsd (v2df, v2df);
26533 v2df __builtin_ia32_cmpnltsd (v2df, v2df);
26534 v2df __builtin_ia32_cmpnlesd (v2df, v2df);
26535 v2df __builtin_ia32_cmpordsd (v2df, v2df);
26536 v2di __builtin_ia32_paddq (v2di, v2di);
26537 v2di __builtin_ia32_psubq (v2di, v2di);
26538 v2df __builtin_ia32_addpd (v2df, v2df);
26539 v2df __builtin_ia32_subpd (v2df, v2df);
26540 v2df __builtin_ia32_mulpd (v2df, v2df);
26541 v2df __builtin_ia32_divpd (v2df, v2df);
26542 v2df __builtin_ia32_addsd (v2df, v2df);
26543 v2df __builtin_ia32_subsd (v2df, v2df);
26544 v2df __builtin_ia32_mulsd (v2df, v2df);
26545 v2df __builtin_ia32_divsd (v2df, v2df);
26546 v2df __builtin_ia32_minpd (v2df, v2df);
26547 v2df __builtin_ia32_maxpd (v2df, v2df);
26548 v2df __builtin_ia32_minsd (v2df, v2df);
26549 v2df __builtin_ia32_maxsd (v2df, v2df);
26550 v2df __builtin_ia32_andpd (v2df, v2df);
26551 v2df __builtin_ia32_andnpd (v2df, v2df);
26552 v2df __builtin_ia32_orpd (v2df, v2df);
26553 v2df __builtin_ia32_xorpd (v2df, v2df);
26554 v2df __builtin_ia32_movsd (v2df, v2df);
26555 v2df __builtin_ia32_unpckhpd (v2df, v2df);
26556 v2df __builtin_ia32_unpcklpd (v2df, v2df);
26557 v16qi __builtin_ia32_paddb128 (v16qi, v16qi);
26558 v8hi __builtin_ia32_paddw128 (v8hi, v8hi);
26559 v4si __builtin_ia32_paddd128 (v4si, v4si);
26560 v2di __builtin_ia32_paddq128 (v2di, v2di);
26561 v16qi __builtin_ia32_psubb128 (v16qi, v16qi);
26562 v8hi __builtin_ia32_psubw128 (v8hi, v8hi);
26563 v4si __builtin_ia32_psubd128 (v4si, v4si);
26564 v2di __builtin_ia32_psubq128 (v2di, v2di);
26565 v8hi __builtin_ia32_pmullw128 (v8hi, v8hi);
26566 v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi);
26567 v2di __builtin_ia32_pand128 (v2di, v2di);
26568 v2di __builtin_ia32_pandn128 (v2di, v2di);
26569 v2di __builtin_ia32_por128 (v2di, v2di);
26570 v2di __builtin_ia32_pxor128 (v2di, v2di);
26571 v16qi __builtin_ia32_pavgb128 (v16qi, v16qi);
26572 v8hi __builtin_ia32_pavgw128 (v8hi, v8hi);
26573 v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi);
26574 v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi);
26575 v4si __builtin_ia32_pcmpeqd128 (v4si, v4si);
26576 v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi);
26577 v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi);
26578 v4si __builtin_ia32_pcmpgtd128 (v4si, v4si);
26579 v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi);
26580 v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi);
26581 v16qi __builtin_ia32_pminub128 (v16qi, v16qi);
26582 v8hi __builtin_ia32_pminsw128 (v8hi, v8hi);
26583 v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi);
26584 v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi);
26585 v4si __builtin_ia32_punpckhdq128 (v4si, v4si);
26586 v2di __builtin_ia32_punpckhqdq128 (v2di, v2di);
26587 v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi);
26588 v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi);
26589 v4si __builtin_ia32_punpckldq128 (v4si, v4si);
26590 v2di __builtin_ia32_punpcklqdq128 (v2di, v2di);
26591 v16qi __builtin_ia32_packsswb128 (v8hi, v8hi);
26592 v8hi __builtin_ia32_packssdw128 (v4si, v4si);
26593 v16qi __builtin_ia32_packuswb128 (v8hi, v8hi);
26594 v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi);
26595 void __builtin_ia32_maskmovdqu (v16qi, v16qi);
26596 v2df __builtin_ia32_loadupd (double *);
26597 void __builtin_ia32_storeupd (double *, v2df);
26598 v2df __builtin_ia32_loadhpd (v2df, double const *);
26599 v2df __builtin_ia32_loadlpd (v2df, double const *);
26600 int __builtin_ia32_movmskpd (v2df);
26601 int __builtin_ia32_pmovmskb128 (v16qi);
26602 void __builtin_ia32_movnti (int *, int);
26603 void __builtin_ia32_movnti64 (long long int *, long long int);
26604 void __builtin_ia32_movntpd (double *, v2df);
26605 void __builtin_ia32_movntdq (v2df *, v2df);
26606 v4si __builtin_ia32_pshufd (v4si, int);
26607 v8hi __builtin_ia32_pshuflw (v8hi, int);
26608 v8hi __builtin_ia32_pshufhw (v8hi, int);
26609 v2di __builtin_ia32_psadbw128 (v16qi, v16qi);
26610 v2df __builtin_ia32_sqrtpd (v2df);
26611 v2df __builtin_ia32_sqrtsd (v2df);
26612 v2df __builtin_ia32_shufpd (v2df, v2df, int);
26613 v2df __builtin_ia32_cvtdq2pd (v4si);
26614 v4sf __builtin_ia32_cvtdq2ps (v4si);
26615 v4si __builtin_ia32_cvtpd2dq (v2df);
26616 v2si __builtin_ia32_cvtpd2pi (v2df);
26617 v4sf __builtin_ia32_cvtpd2ps (v2df);
26618 v4si __builtin_ia32_cvttpd2dq (v2df);
26619 v2si __builtin_ia32_cvttpd2pi (v2df);
26620 v2df __builtin_ia32_cvtpi2pd (v2si);
26621 int __builtin_ia32_cvtsd2si (v2df);
26622 int __builtin_ia32_cvttsd2si (v2df);
26623 long long __builtin_ia32_cvtsd2si64 (v2df);
26624 long long __builtin_ia32_cvttsd2si64 (v2df);
26625 v4si __builtin_ia32_cvtps2dq (v4sf);
26626 v2df __builtin_ia32_cvtps2pd (v4sf);
26627 v4si __builtin_ia32_cvttps2dq (v4sf);
26628 v2df __builtin_ia32_cvtsi2sd (v2df, int);
26629 v2df __builtin_ia32_cvtsi642sd (v2df, long long);
26630 v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df);
26631 v2df __builtin_ia32_cvtss2sd (v2df, v4sf);
26632 void __builtin_ia32_clflush (const void *);
26633 void __builtin_ia32_lfence (void);
26634 void __builtin_ia32_mfence (void);
26635 v16qi __builtin_ia32_loaddqu (const char *);
26636 void __builtin_ia32_storedqu (char *, v16qi);
26637 v1di __builtin_ia32_pmuludq (v2si, v2si);
26638 v2di __builtin_ia32_pmuludq128 (v4si, v4si);
26639 v8hi __builtin_ia32_psllw128 (v8hi, v8hi);
26640 v4si __builtin_ia32_pslld128 (v4si, v4si);
26641 v2di __builtin_ia32_psllq128 (v2di, v2di);
26642 v8hi __builtin_ia32_psrlw128 (v8hi, v8hi);
26643 v4si __builtin_ia32_psrld128 (v4si, v4si);
26644 v2di __builtin_ia32_psrlq128 (v2di, v2di);
26645 v8hi __builtin_ia32_psraw128 (v8hi, v8hi);
26646 v4si __builtin_ia32_psrad128 (v4si, v4si);
26647 v2di __builtin_ia32_pslldqi128 (v2di, int);
26648 v8hi __builtin_ia32_psllwi128 (v8hi, int);
26649 v4si __builtin_ia32_pslldi128 (v4si, int);
26650 v2di __builtin_ia32_psllqi128 (v2di, int);
26651 v2di __builtin_ia32_psrldqi128 (v2di, int);
26652 v8hi __builtin_ia32_psrlwi128 (v8hi, int);
26653 v4si __builtin_ia32_psrldi128 (v4si, int);
26654 v2di __builtin_ia32_psrlqi128 (v2di, int);
26655 v8hi __builtin_ia32_psrawi128 (v8hi, int);
26656 v4si __builtin_ia32_psradi128 (v4si, int);
26657 v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi);
26658 v2di __builtin_ia32_movq128 (v2di);
26661 The following built-in functions are available when @option{-msse3} is used.
26662 All of them generate the machine instruction that is part of the name.
26665 v2df __builtin_ia32_addsubpd (v2df, v2df);
26666 v4sf __builtin_ia32_addsubps (v4sf, v4sf);
26667 v2df __builtin_ia32_haddpd (v2df, v2df);
26668 v4sf __builtin_ia32_haddps (v4sf, v4sf);
26669 v2df __builtin_ia32_hsubpd (v2df, v2df);
26670 v4sf __builtin_ia32_hsubps (v4sf, v4sf);
26671 v16qi __builtin_ia32_lddqu (char const *);
26672 void __builtin_ia32_monitor (void *, unsigned int, unsigned int);
26673 v4sf __builtin_ia32_movshdup (v4sf);
26674 v4sf __builtin_ia32_movsldup (v4sf);
26675 void __builtin_ia32_mwait (unsigned int, unsigned int);
26678 The following built-in functions are available when @option{-mssse3} is used.
26679 All of them generate the machine instruction that is part of the name.
26682 v2si __builtin_ia32_phaddd (v2si, v2si);
26683 v4hi __builtin_ia32_phaddw (v4hi, v4hi);
26684 v4hi __builtin_ia32_phaddsw (v4hi, v4hi);
26685 v2si __builtin_ia32_phsubd (v2si, v2si);
26686 v4hi __builtin_ia32_phsubw (v4hi, v4hi);
26687 v4hi __builtin_ia32_phsubsw (v4hi, v4hi);
26688 v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi);
26689 v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi);
26690 v8qi __builtin_ia32_pshufb (v8qi, v8qi);
26691 v8qi __builtin_ia32_psignb (v8qi, v8qi);
26692 v2si __builtin_ia32_psignd (v2si, v2si);
26693 v4hi __builtin_ia32_psignw (v4hi, v4hi);
26694 v1di __builtin_ia32_palignr (v1di, v1di, int);
26695 v8qi __builtin_ia32_pabsb (v8qi);
26696 v2si __builtin_ia32_pabsd (v2si);
26697 v4hi __builtin_ia32_pabsw (v4hi);
26700 The following built-in functions are available when @option{-mssse3} is used.
26701 All of them generate the machine instruction that is part of the name.
26704 v4si __builtin_ia32_phaddd128 (v4si, v4si);
26705 v8hi __builtin_ia32_phaddw128 (v8hi, v8hi);
26706 v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi);
26707 v4si __builtin_ia32_phsubd128 (v4si, v4si);
26708 v8hi __builtin_ia32_phsubw128 (v8hi, v8hi);
26709 v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi);
26710 v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi);
26711 v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi);
26712 v16qi __builtin_ia32_pshufb128 (v16qi, v16qi);
26713 v16qi __builtin_ia32_psignb128 (v16qi, v16qi);
26714 v4si __builtin_ia32_psignd128 (v4si, v4si);
26715 v8hi __builtin_ia32_psignw128 (v8hi, v8hi);
26716 v2di __builtin_ia32_palignr128 (v2di, v2di, int);
26717 v16qi __builtin_ia32_pabsb128 (v16qi);
26718 v4si __builtin_ia32_pabsd128 (v4si);
26719 v8hi __builtin_ia32_pabsw128 (v8hi);
26722 The following built-in functions are available when @option{-msse4.1} is
26723 used. All of them generate the machine instruction that is part of the
26727 v2df __builtin_ia32_blendpd (v2df, v2df, const int);
26728 v4sf __builtin_ia32_blendps (v4sf, v4sf, const int);
26729 v2df __builtin_ia32_blendvpd (v2df, v2df, v2df);
26730 v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf);
26731 v2df __builtin_ia32_dppd (v2df, v2df, const int);
26732 v4sf __builtin_ia32_dpps (v4sf, v4sf, const int);
26733 v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int);
26734 v2di __builtin_ia32_movntdqa (v2di *);
26735 v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int);
26736 v8hi __builtin_ia32_packusdw128 (v4si, v4si);
26737 v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi);
26738 v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int);
26739 v2di __builtin_ia32_pcmpeqq (v2di, v2di);
26740 v8hi __builtin_ia32_phminposuw128 (v8hi);
26741 v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi);
26742 v4si __builtin_ia32_pmaxsd128 (v4si, v4si);
26743 v4si __builtin_ia32_pmaxud128 (v4si, v4si);
26744 v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi);
26745 v16qi __builtin_ia32_pminsb128 (v16qi, v16qi);
26746 v4si __builtin_ia32_pminsd128 (v4si, v4si);
26747 v4si __builtin_ia32_pminud128 (v4si, v4si);
26748 v8hi __builtin_ia32_pminuw128 (v8hi, v8hi);
26749 v4si __builtin_ia32_pmovsxbd128 (v16qi);
26750 v2di __builtin_ia32_pmovsxbq128 (v16qi);
26751 v8hi __builtin_ia32_pmovsxbw128 (v16qi);
26752 v2di __builtin_ia32_pmovsxdq128 (v4si);
26753 v4si __builtin_ia32_pmovsxwd128 (v8hi);
26754 v2di __builtin_ia32_pmovsxwq128 (v8hi);
26755 v4si __builtin_ia32_pmovzxbd128 (v16qi);
26756 v2di __builtin_ia32_pmovzxbq128 (v16qi);
26757 v8hi __builtin_ia32_pmovzxbw128 (v16qi);
26758 v2di __builtin_ia32_pmovzxdq128 (v4si);
26759 v4si __builtin_ia32_pmovzxwd128 (v8hi);
26760 v2di __builtin_ia32_pmovzxwq128 (v8hi);
26761 v2di __builtin_ia32_pmuldq128 (v4si, v4si);
26762 v4si __builtin_ia32_pmulld128 (v4si, v4si);
26763 int __builtin_ia32_ptestc128 (v2di, v2di);
26764 int __builtin_ia32_ptestnzc128 (v2di, v2di);
26765 int __builtin_ia32_ptestz128 (v2di, v2di);
26766 v2df __builtin_ia32_roundpd (v2df, const int);
26767 v4sf __builtin_ia32_roundps (v4sf, const int);
26768 v2df __builtin_ia32_roundsd (v2df, v2df, const int);
26769 v4sf __builtin_ia32_roundss (v4sf, v4sf, const int);
26772 The following built-in functions are available when @option{-msse4.1} is
26775 @defbuiltin{v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)}
26776 Generates the @code{insertps} machine instruction.
26779 @defbuiltin{int __builtin_ia32_vec_ext_v16qi (v16qi, const int)}
26780 Generates the @code{pextrb} machine instruction.
26783 @defbuiltin{v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)}
26784 Generates the @code{pinsrb} machine instruction.
26787 @defbuiltin{v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)}
26788 Generates the @code{pinsrd} machine instruction.
26791 @defbuiltin{v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)}
26792 Generates the @code{pinsrq} machine instruction in 64bit mode.
26795 The following built-in functions are changed to generate new SSE4.1
26796 instructions when @option{-msse4.1} is used.
26798 @defbuiltin{float __builtin_ia32_vec_ext_v4sf (v4sf, const int)}
26799 Generates the @code{extractps} machine instruction.
26802 @defbuiltin{int __builtin_ia32_vec_ext_v4si (v4si, const int)}
26803 Generates the @code{pextrd} machine instruction.
26806 @defbuiltin{{long long} __builtin_ia32_vec_ext_v2di (v2di, const int)}
26807 Generates the @code{pextrq} machine instruction in 64bit mode.
26810 The following built-in functions are available when @option{-msse4.2} is
26811 used. All of them generate the machine instruction that is part of the
26815 v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int);
26816 int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int);
26817 int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int);
26818 int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int);
26819 int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int);
26820 int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int);
26821 int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int);
26822 v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int);
26823 int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int);
26824 int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int);
26825 int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int);
26826 int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int);
26827 int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int);
26828 int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int);
26829 v2di __builtin_ia32_pcmpgtq (v2di, v2di);
26832 The following built-in functions are available when @option{-msse4.2} is
26835 @defbuiltin{{unsigned int} __builtin_ia32_crc32qi (unsigned int, unsigned char)}
26836 Generates the @code{crc32b} machine instruction.
26839 @defbuiltin{{unsigned int} __builtin_ia32_crc32hi (unsigned int, unsigned short)}
26840 Generates the @code{crc32w} machine instruction.
26843 @defbuiltin{{unsigned int} __builtin_ia32_crc32si (unsigned int, unsigned int)}
26844 Generates the @code{crc32l} machine instruction.
26847 @defbuiltin{{unsigned long long} __builtin_ia32_crc32di (unsigned long long, unsigned long long)}
26848 Generates the @code{crc32q} machine instruction.
26851 The following built-in functions are changed to generate new SSE4.2
26852 instructions when @option{-msse4.2} is used.
26854 @defbuiltin{int __builtin_popcount (unsigned int)}
26855 Generates the @code{popcntl} machine instruction.
26858 @defbuiltin{int __builtin_popcountl (unsigned long)}
26859 Generates the @code{popcntl} or @code{popcntq} machine instruction,
26860 depending on the size of @code{unsigned long}.
26863 @defbuiltin{int __builtin_popcountll (unsigned long long)}
26864 Generates the @code{popcntq} machine instruction.
26867 The following built-in functions are available when @option{-mavx} is
26868 used. All of them generate the machine instruction that is part of the
26872 v4df __builtin_ia32_addpd256 (v4df,v4df);
26873 v8sf __builtin_ia32_addps256 (v8sf,v8sf);
26874 v4df __builtin_ia32_addsubpd256 (v4df,v4df);
26875 v8sf __builtin_ia32_addsubps256 (v8sf,v8sf);
26876 v4df __builtin_ia32_andnpd256 (v4df,v4df);
26877 v8sf __builtin_ia32_andnps256 (v8sf,v8sf);
26878 v4df __builtin_ia32_andpd256 (v4df,v4df);
26879 v8sf __builtin_ia32_andps256 (v8sf,v8sf);
26880 v4df __builtin_ia32_blendpd256 (v4df,v4df,int);
26881 v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int);
26882 v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df);
26883 v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf);
26884 v2df __builtin_ia32_cmppd (v2df,v2df,int);
26885 v4df __builtin_ia32_cmppd256 (v4df,v4df,int);
26886 v4sf __builtin_ia32_cmpps (v4sf,v4sf,int);
26887 v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int);
26888 v2df __builtin_ia32_cmpsd (v2df,v2df,int);
26889 v4sf __builtin_ia32_cmpss (v4sf,v4sf,int);
26890 v4df __builtin_ia32_cvtdq2pd256 (v4si);
26891 v8sf __builtin_ia32_cvtdq2ps256 (v8si);
26892 v4si __builtin_ia32_cvtpd2dq256 (v4df);
26893 v4sf __builtin_ia32_cvtpd2ps256 (v4df);
26894 v8si __builtin_ia32_cvtps2dq256 (v8sf);
26895 v4df __builtin_ia32_cvtps2pd256 (v4sf);
26896 v4si __builtin_ia32_cvttpd2dq256 (v4df);
26897 v8si __builtin_ia32_cvttps2dq256 (v8sf);
26898 v4df __builtin_ia32_divpd256 (v4df,v4df);
26899 v8sf __builtin_ia32_divps256 (v8sf,v8sf);
26900 v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int);
26901 v4df __builtin_ia32_haddpd256 (v4df,v4df);
26902 v8sf __builtin_ia32_haddps256 (v8sf,v8sf);
26903 v4df __builtin_ia32_hsubpd256 (v4df,v4df);
26904 v8sf __builtin_ia32_hsubps256 (v8sf,v8sf);
26905 v32qi __builtin_ia32_lddqu256 (pcchar);
26906 v32qi __builtin_ia32_loaddqu256 (pcchar);
26907 v4df __builtin_ia32_loadupd256 (pcdouble);
26908 v8sf __builtin_ia32_loadups256 (pcfloat);
26909 v2df __builtin_ia32_maskloadpd (pcv2df,v2df);
26910 v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df);
26911 v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf);
26912 v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf);
26913 void __builtin_ia32_maskstorepd (pv2df,v2df,v2df);
26914 void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df);
26915 void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf);
26916 void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf);
26917 v4df __builtin_ia32_maxpd256 (v4df,v4df);
26918 v8sf __builtin_ia32_maxps256 (v8sf,v8sf);
26919 v4df __builtin_ia32_minpd256 (v4df,v4df);
26920 v8sf __builtin_ia32_minps256 (v8sf,v8sf);
26921 v4df __builtin_ia32_movddup256 (v4df);
26922 int __builtin_ia32_movmskpd256 (v4df);
26923 int __builtin_ia32_movmskps256 (v8sf);
26924 v8sf __builtin_ia32_movshdup256 (v8sf);
26925 v8sf __builtin_ia32_movsldup256 (v8sf);
26926 v4df __builtin_ia32_mulpd256 (v4df,v4df);
26927 v8sf __builtin_ia32_mulps256 (v8sf,v8sf);
26928 v4df __builtin_ia32_orpd256 (v4df,v4df);
26929 v8sf __builtin_ia32_orps256 (v8sf,v8sf);
26930 v2df __builtin_ia32_pd_pd256 (v4df);
26931 v4df __builtin_ia32_pd256_pd (v2df);
26932 v4sf __builtin_ia32_ps_ps256 (v8sf);
26933 v8sf __builtin_ia32_ps256_ps (v4sf);
26934 int __builtin_ia32_ptestc256 (v4di,v4di,ptest);
26935 int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest);
26936 int __builtin_ia32_ptestz256 (v4di,v4di,ptest);
26937 v8sf __builtin_ia32_rcpps256 (v8sf);
26938 v4df __builtin_ia32_roundpd256 (v4df,int);
26939 v8sf __builtin_ia32_roundps256 (v8sf,int);
26940 v8sf __builtin_ia32_rsqrtps_nr256 (v8sf);
26941 v8sf __builtin_ia32_rsqrtps256 (v8sf);
26942 v4df __builtin_ia32_shufpd256 (v4df,v4df,int);
26943 v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int);
26944 v4si __builtin_ia32_si_si256 (v8si);
26945 v8si __builtin_ia32_si256_si (v4si);
26946 v4df __builtin_ia32_sqrtpd256 (v4df);
26947 v8sf __builtin_ia32_sqrtps_nr256 (v8sf);
26948 v8sf __builtin_ia32_sqrtps256 (v8sf);
26949 void __builtin_ia32_storedqu256 (pchar,v32qi);
26950 void __builtin_ia32_storeupd256 (pdouble,v4df);
26951 void __builtin_ia32_storeups256 (pfloat,v8sf);
26952 v4df __builtin_ia32_subpd256 (v4df,v4df);
26953 v8sf __builtin_ia32_subps256 (v8sf,v8sf);
26954 v4df __builtin_ia32_unpckhpd256 (v4df,v4df);
26955 v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf);
26956 v4df __builtin_ia32_unpcklpd256 (v4df,v4df);
26957 v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf);
26958 v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df);
26959 v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf);
26960 v4df __builtin_ia32_vbroadcastsd256 (pcdouble);
26961 v4sf __builtin_ia32_vbroadcastss (pcfloat);
26962 v8sf __builtin_ia32_vbroadcastss256 (pcfloat);
26963 v2df __builtin_ia32_vextractf128_pd256 (v4df,int);
26964 v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int);
26965 v4si __builtin_ia32_vextractf128_si256 (v8si,int);
26966 v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int);
26967 v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int);
26968 v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int);
26969 v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int);
26970 v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int);
26971 v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int);
26972 v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int);
26973 v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int);
26974 v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int);
26975 v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int);
26976 v2df __builtin_ia32_vpermilpd (v2df,int);
26977 v4df __builtin_ia32_vpermilpd256 (v4df,int);
26978 v4sf __builtin_ia32_vpermilps (v4sf,int);
26979 v8sf __builtin_ia32_vpermilps256 (v8sf,int);
26980 v2df __builtin_ia32_vpermilvarpd (v2df,v2di);
26981 v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di);
26982 v4sf __builtin_ia32_vpermilvarps (v4sf,v4si);
26983 v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si);
26984 int __builtin_ia32_vtestcpd (v2df,v2df,ptest);
26985 int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest);
26986 int __builtin_ia32_vtestcps (v4sf,v4sf,ptest);
26987 int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest);
26988 int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest);
26989 int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest);
26990 int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest);
26991 int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest);
26992 int __builtin_ia32_vtestzpd (v2df,v2df,ptest);
26993 int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest);
26994 int __builtin_ia32_vtestzps (v4sf,v4sf,ptest);
26995 int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest);
26996 void __builtin_ia32_vzeroall (void);
26997 void __builtin_ia32_vzeroupper (void);
26998 v4df __builtin_ia32_xorpd256 (v4df,v4df);
26999 v8sf __builtin_ia32_xorps256 (v8sf,v8sf);
27002 The following built-in functions are available when @option{-mavx2} is
27003 used. All of them generate the machine instruction that is part of the
27007 v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int);
27008 v32qi __builtin_ia32_pabsb256 (v32qi);
27009 v16hi __builtin_ia32_pabsw256 (v16hi);
27010 v8si __builtin_ia32_pabsd256 (v8si);
27011 v16hi __builtin_ia32_packssdw256 (v8si,v8si);
27012 v32qi __builtin_ia32_packsswb256 (v16hi,v16hi);
27013 v16hi __builtin_ia32_packusdw256 (v8si,v8si);
27014 v32qi __builtin_ia32_packuswb256 (v16hi,v16hi);
27015 v32qi __builtin_ia32_paddb256 (v32qi,v32qi);
27016 v16hi __builtin_ia32_paddw256 (v16hi,v16hi);
27017 v8si __builtin_ia32_paddd256 (v8si,v8si);
27018 v4di __builtin_ia32_paddq256 (v4di,v4di);
27019 v32qi __builtin_ia32_paddsb256 (v32qi,v32qi);
27020 v16hi __builtin_ia32_paddsw256 (v16hi,v16hi);
27021 v32qi __builtin_ia32_paddusb256 (v32qi,v32qi);
27022 v16hi __builtin_ia32_paddusw256 (v16hi,v16hi);
27023 v4di __builtin_ia32_palignr256 (v4di,v4di,int);
27024 v4di __builtin_ia32_andsi256 (v4di,v4di);
27025 v4di __builtin_ia32_andnotsi256 (v4di,v4di);
27026 v32qi __builtin_ia32_pavgb256 (v32qi,v32qi);
27027 v16hi __builtin_ia32_pavgw256 (v16hi,v16hi);
27028 v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi);
27029 v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int);
27030 v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi);
27031 v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi);
27032 v8si __builtin_ia32_pcmpeqd256 (c8si,v8si);
27033 v4di __builtin_ia32_pcmpeqq256 (v4di,v4di);
27034 v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi);
27035 v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi);
27036 v8si __builtin_ia32_pcmpgtd256 (v8si,v8si);
27037 v4di __builtin_ia32_pcmpgtq256 (v4di,v4di);
27038 v16hi __builtin_ia32_phaddw256 (v16hi,v16hi);
27039 v8si __builtin_ia32_phaddd256 (v8si,v8si);
27040 v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi);
27041 v16hi __builtin_ia32_phsubw256 (v16hi,v16hi);
27042 v8si __builtin_ia32_phsubd256 (v8si,v8si);
27043 v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi);
27044 v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi);
27045 v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi);
27046 v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi);
27047 v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi);
27048 v8si __builtin_ia32_pmaxsd256 (v8si,v8si);
27049 v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi);
27050 v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi);
27051 v8si __builtin_ia32_pmaxud256 (v8si,v8si);
27052 v32qi __builtin_ia32_pminsb256 (v32qi,v32qi);
27053 v16hi __builtin_ia32_pminsw256 (v16hi,v16hi);
27054 v8si __builtin_ia32_pminsd256 (v8si,v8si);
27055 v32qi __builtin_ia32_pminub256 (v32qi,v32qi);
27056 v16hi __builtin_ia32_pminuw256 (v16hi,v16hi);
27057 v8si __builtin_ia32_pminud256 (v8si,v8si);
27058 int __builtin_ia32_pmovmskb256 (v32qi);
27059 v16hi __builtin_ia32_pmovsxbw256 (v16qi);
27060 v8si __builtin_ia32_pmovsxbd256 (v16qi);
27061 v4di __builtin_ia32_pmovsxbq256 (v16qi);
27062 v8si __builtin_ia32_pmovsxwd256 (v8hi);
27063 v4di __builtin_ia32_pmovsxwq256 (v8hi);
27064 v4di __builtin_ia32_pmovsxdq256 (v4si);
27065 v16hi __builtin_ia32_pmovzxbw256 (v16qi);
27066 v8si __builtin_ia32_pmovzxbd256 (v16qi);
27067 v4di __builtin_ia32_pmovzxbq256 (v16qi);
27068 v8si __builtin_ia32_pmovzxwd256 (v8hi);
27069 v4di __builtin_ia32_pmovzxwq256 (v8hi);
27070 v4di __builtin_ia32_pmovzxdq256 (v4si);
27071 v4di __builtin_ia32_pmuldq256 (v8si,v8si);
27072 v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi);
27073 v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi);
27074 v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi);
27075 v16hi __builtin_ia32_pmullw256 (v16hi,v16hi);
27076 v8si __builtin_ia32_pmulld256 (v8si,v8si);
27077 v4di __builtin_ia32_pmuludq256 (v8si,v8si);
27078 v4di __builtin_ia32_por256 (v4di,v4di);
27079 v16hi __builtin_ia32_psadbw256 (v32qi,v32qi);
27080 v32qi __builtin_ia32_pshufb256 (v32qi,v32qi);
27081 v8si __builtin_ia32_pshufd256 (v8si,int);
27082 v16hi __builtin_ia32_pshufhw256 (v16hi,int);
27083 v16hi __builtin_ia32_pshuflw256 (v16hi,int);
27084 v32qi __builtin_ia32_psignb256 (v32qi,v32qi);
27085 v16hi __builtin_ia32_psignw256 (v16hi,v16hi);
27086 v8si __builtin_ia32_psignd256 (v8si,v8si);
27087 v4di __builtin_ia32_pslldqi256 (v4di,int);
27088 v16hi __builtin_ia32_psllwi256 (16hi,int);
27089 v16hi __builtin_ia32_psllw256(v16hi,v8hi);
27090 v8si __builtin_ia32_pslldi256 (v8si,int);
27091 v8si __builtin_ia32_pslld256(v8si,v4si);
27092 v4di __builtin_ia32_psllqi256 (v4di,int);
27093 v4di __builtin_ia32_psllq256(v4di,v2di);
27094 v16hi __builtin_ia32_psrawi256 (v16hi,int);
27095 v16hi __builtin_ia32_psraw256 (v16hi,v8hi);
27096 v8si __builtin_ia32_psradi256 (v8si,int);
27097 v8si __builtin_ia32_psrad256 (v8si,v4si);
27098 v4di __builtin_ia32_psrldqi256 (v4di, int);
27099 v16hi __builtin_ia32_psrlwi256 (v16hi,int);
27100 v16hi __builtin_ia32_psrlw256 (v16hi,v8hi);
27101 v8si __builtin_ia32_psrldi256 (v8si,int);
27102 v8si __builtin_ia32_psrld256 (v8si,v4si);
27103 v4di __builtin_ia32_psrlqi256 (v4di,int);
27104 v4di __builtin_ia32_psrlq256(v4di,v2di);
27105 v32qi __builtin_ia32_psubb256 (v32qi,v32qi);
27106 v32hi __builtin_ia32_psubw256 (v16hi,v16hi);
27107 v8si __builtin_ia32_psubd256 (v8si,v8si);
27108 v4di __builtin_ia32_psubq256 (v4di,v4di);
27109 v32qi __builtin_ia32_psubsb256 (v32qi,v32qi);
27110 v16hi __builtin_ia32_psubsw256 (v16hi,v16hi);
27111 v32qi __builtin_ia32_psubusb256 (v32qi,v32qi);
27112 v16hi __builtin_ia32_psubusw256 (v16hi,v16hi);
27113 v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi);
27114 v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi);
27115 v8si __builtin_ia32_punpckhdq256 (v8si,v8si);
27116 v4di __builtin_ia32_punpckhqdq256 (v4di,v4di);
27117 v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi);
27118 v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi);
27119 v8si __builtin_ia32_punpckldq256 (v8si,v8si);
27120 v4di __builtin_ia32_punpcklqdq256 (v4di,v4di);
27121 v4di __builtin_ia32_pxor256 (v4di,v4di);
27122 v4di __builtin_ia32_movntdqa256 (pv4di);
27123 v4sf __builtin_ia32_vbroadcastss_ps (v4sf);
27124 v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf);
27125 v4df __builtin_ia32_vbroadcastsd_pd256 (v2df);
27126 v4di __builtin_ia32_vbroadcastsi256 (v2di);
27127 v4si __builtin_ia32_pblendd128 (v4si,v4si);
27128 v8si __builtin_ia32_pblendd256 (v8si,v8si);
27129 v32qi __builtin_ia32_pbroadcastb256 (v16qi);
27130 v16hi __builtin_ia32_pbroadcastw256 (v8hi);
27131 v8si __builtin_ia32_pbroadcastd256 (v4si);
27132 v4di __builtin_ia32_pbroadcastq256 (v2di);
27133 v16qi __builtin_ia32_pbroadcastb128 (v16qi);
27134 v8hi __builtin_ia32_pbroadcastw128 (v8hi);
27135 v4si __builtin_ia32_pbroadcastd128 (v4si);
27136 v2di __builtin_ia32_pbroadcastq128 (v2di);
27137 v8si __builtin_ia32_permvarsi256 (v8si,v8si);
27138 v4df __builtin_ia32_permdf256 (v4df,int);
27139 v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf);
27140 v4di __builtin_ia32_permdi256 (v4di,int);
27141 v4di __builtin_ia32_permti256 (v4di,v4di,int);
27142 v4di __builtin_ia32_extract128i256 (v4di,int);
27143 v4di __builtin_ia32_insert128i256 (v4di,v2di,int);
27144 v8si __builtin_ia32_maskloadd256 (pcv8si,v8si);
27145 v4di __builtin_ia32_maskloadq256 (pcv4di,v4di);
27146 v4si __builtin_ia32_maskloadd (pcv4si,v4si);
27147 v2di __builtin_ia32_maskloadq (pcv2di,v2di);
27148 void __builtin_ia32_maskstored256 (pv8si,v8si,v8si);
27149 void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di);
27150 void __builtin_ia32_maskstored (pv4si,v4si,v4si);
27151 void __builtin_ia32_maskstoreq (pv2di,v2di,v2di);
27152 v8si __builtin_ia32_psllv8si (v8si,v8si);
27153 v4si __builtin_ia32_psllv4si (v4si,v4si);
27154 v4di __builtin_ia32_psllv4di (v4di,v4di);
27155 v2di __builtin_ia32_psllv2di (v2di,v2di);
27156 v8si __builtin_ia32_psrav8si (v8si,v8si);
27157 v4si __builtin_ia32_psrav4si (v4si,v4si);
27158 v8si __builtin_ia32_psrlv8si (v8si,v8si);
27159 v4si __builtin_ia32_psrlv4si (v4si,v4si);
27160 v4di __builtin_ia32_psrlv4di (v4di,v4di);
27161 v2di __builtin_ia32_psrlv2di (v2di,v2di);
27162 v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int);
27163 v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int);
27164 v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int);
27165 v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int);
27166 v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int);
27167 v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int);
27168 v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int);
27169 v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int);
27170 v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int);
27171 v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int);
27172 v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int);
27173 v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int);
27174 v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int);
27175 v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int);
27176 v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int);
27177 v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int);
27180 The following built-in functions are available when @option{-maes} is
27181 used. All of them generate the machine instruction that is part of the
27185 v2di __builtin_ia32_aesenc128 (v2di, v2di);
27186 v2di __builtin_ia32_aesenclast128 (v2di, v2di);
27187 v2di __builtin_ia32_aesdec128 (v2di, v2di);
27188 v2di __builtin_ia32_aesdeclast128 (v2di, v2di);
27189 v2di __builtin_ia32_aeskeygenassist128 (v2di, const int);
27190 v2di __builtin_ia32_aesimc128 (v2di);
27193 The following built-in function is available when @option{-mpclmul} is
27196 @defbuiltin{v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)}
27197 Generates the @code{pclmulqdq} machine instruction.
27200 The following built-in function is available when @option{-mfsgsbase} is
27201 used. All of them generate the machine instruction that is part of the
27205 unsigned int __builtin_ia32_rdfsbase32 (void);
27206 unsigned long long __builtin_ia32_rdfsbase64 (void);
27207 unsigned int __builtin_ia32_rdgsbase32 (void);
27208 unsigned long long __builtin_ia32_rdgsbase64 (void);
27209 void _writefsbase_u32 (unsigned int);
27210 void _writefsbase_u64 (unsigned long long);
27211 void _writegsbase_u32 (unsigned int);
27212 void _writegsbase_u64 (unsigned long long);
27215 The following built-in function is available when @option{-mrdrnd} is
27216 used. All of them generate the machine instruction that is part of the
27220 unsigned int __builtin_ia32_rdrand16_step (unsigned short *);
27221 unsigned int __builtin_ia32_rdrand32_step (unsigned int *);
27222 unsigned int __builtin_ia32_rdrand64_step (unsigned long long *);
27225 The following built-in function is available when @option{-mptwrite} is
27226 used. All of them generate the machine instruction that is part of the
27230 void __builtin_ia32_ptwrite32 (unsigned);
27231 void __builtin_ia32_ptwrite64 (unsigned long long);
27234 The following built-in functions are available when @option{-msse4a} is used.
27235 All of them generate the machine instruction that is part of the name.
27238 void __builtin_ia32_movntsd (double *, v2df);
27239 void __builtin_ia32_movntss (float *, v4sf);
27240 v2di __builtin_ia32_extrq (v2di, v16qi);
27241 v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int);
27242 v2di __builtin_ia32_insertq (v2di, v2di);
27243 v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int);
27246 The following built-in functions are available when @option{-mxop} is used.
27248 v2df __builtin_ia32_vfrczpd (v2df);
27249 v4sf __builtin_ia32_vfrczps (v4sf);
27250 v2df __builtin_ia32_vfrczsd (v2df);
27251 v4sf __builtin_ia32_vfrczss (v4sf);
27252 v4df __builtin_ia32_vfrczpd256 (v4df);
27253 v8sf __builtin_ia32_vfrczps256 (v8sf);
27254 v2di __builtin_ia32_vpcmov (v2di, v2di, v2di);
27255 v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di);
27256 v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si);
27257 v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi);
27258 v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi);
27259 v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df);
27260 v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf);
27261 v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di);
27262 v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si);
27263 v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi);
27264 v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi);
27265 v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df);
27266 v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf);
27267 v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi);
27268 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi);
27269 v4si __builtin_ia32_vpcomeqd (v4si, v4si);
27270 v2di __builtin_ia32_vpcomeqq (v2di, v2di);
27271 v16qi __builtin_ia32_vpcomequb (v16qi, v16qi);
27272 v4si __builtin_ia32_vpcomequd (v4si, v4si);
27273 v2di __builtin_ia32_vpcomequq (v2di, v2di);
27274 v8hi __builtin_ia32_vpcomequw (v8hi, v8hi);
27275 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi);
27276 v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi);
27277 v4si __builtin_ia32_vpcomfalsed (v4si, v4si);
27278 v2di __builtin_ia32_vpcomfalseq (v2di, v2di);
27279 v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi);
27280 v4si __builtin_ia32_vpcomfalseud (v4si, v4si);
27281 v2di __builtin_ia32_vpcomfalseuq (v2di, v2di);
27282 v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi);
27283 v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi);
27284 v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi);
27285 v4si __builtin_ia32_vpcomged (v4si, v4si);
27286 v2di __builtin_ia32_vpcomgeq (v2di, v2di);
27287 v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi);
27288 v4si __builtin_ia32_vpcomgeud (v4si, v4si);
27289 v2di __builtin_ia32_vpcomgeuq (v2di, v2di);
27290 v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi);
27291 v8hi __builtin_ia32_vpcomgew (v8hi, v8hi);
27292 v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi);
27293 v4si __builtin_ia32_vpcomgtd (v4si, v4si);
27294 v2di __builtin_ia32_vpcomgtq (v2di, v2di);
27295 v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi);
27296 v4si __builtin_ia32_vpcomgtud (v4si, v4si);
27297 v2di __builtin_ia32_vpcomgtuq (v2di, v2di);
27298 v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi);
27299 v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi);
27300 v16qi __builtin_ia32_vpcomleb (v16qi, v16qi);
27301 v4si __builtin_ia32_vpcomled (v4si, v4si);
27302 v2di __builtin_ia32_vpcomleq (v2di, v2di);
27303 v16qi __builtin_ia32_vpcomleub (v16qi, v16qi);
27304 v4si __builtin_ia32_vpcomleud (v4si, v4si);
27305 v2di __builtin_ia32_vpcomleuq (v2di, v2di);
27306 v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi);
27307 v8hi __builtin_ia32_vpcomlew (v8hi, v8hi);
27308 v16qi __builtin_ia32_vpcomltb (v16qi, v16qi);
27309 v4si __builtin_ia32_vpcomltd (v4si, v4si);
27310 v2di __builtin_ia32_vpcomltq (v2di, v2di);
27311 v16qi __builtin_ia32_vpcomltub (v16qi, v16qi);
27312 v4si __builtin_ia32_vpcomltud (v4si, v4si);
27313 v2di __builtin_ia32_vpcomltuq (v2di, v2di);
27314 v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi);
27315 v8hi __builtin_ia32_vpcomltw (v8hi, v8hi);
27316 v16qi __builtin_ia32_vpcomneb (v16qi, v16qi);
27317 v4si __builtin_ia32_vpcomned (v4si, v4si);
27318 v2di __builtin_ia32_vpcomneq (v2di, v2di);
27319 v16qi __builtin_ia32_vpcomneub (v16qi, v16qi);
27320 v4si __builtin_ia32_vpcomneud (v4si, v4si);
27321 v2di __builtin_ia32_vpcomneuq (v2di, v2di);
27322 v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi);
27323 v8hi __builtin_ia32_vpcomnew (v8hi, v8hi);
27324 v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi);
27325 v4si __builtin_ia32_vpcomtrued (v4si, v4si);
27326 v2di __builtin_ia32_vpcomtrueq (v2di, v2di);
27327 v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi);
27328 v4si __builtin_ia32_vpcomtrueud (v4si, v4si);
27329 v2di __builtin_ia32_vpcomtrueuq (v2di, v2di);
27330 v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi);
27331 v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi);
27332 v4si __builtin_ia32_vphaddbd (v16qi);
27333 v2di __builtin_ia32_vphaddbq (v16qi);
27334 v8hi __builtin_ia32_vphaddbw (v16qi);
27335 v2di __builtin_ia32_vphadddq (v4si);
27336 v4si __builtin_ia32_vphaddubd (v16qi);
27337 v2di __builtin_ia32_vphaddubq (v16qi);
27338 v8hi __builtin_ia32_vphaddubw (v16qi);
27339 v2di __builtin_ia32_vphaddudq (v4si);
27340 v4si __builtin_ia32_vphadduwd (v8hi);
27341 v2di __builtin_ia32_vphadduwq (v8hi);
27342 v4si __builtin_ia32_vphaddwd (v8hi);
27343 v2di __builtin_ia32_vphaddwq (v8hi);
27344 v8hi __builtin_ia32_vphsubbw (v16qi);
27345 v2di __builtin_ia32_vphsubdq (v4si);
27346 v4si __builtin_ia32_vphsubwd (v8hi);
27347 v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si);
27348 v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di);
27349 v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di);
27350 v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si);
27351 v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di);
27352 v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di);
27353 v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si);
27354 v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi);
27355 v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si);
27356 v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi);
27357 v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si);
27358 v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si);
27359 v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi);
27360 v16qi __builtin_ia32_vprotb (v16qi, v16qi);
27361 v4si __builtin_ia32_vprotd (v4si, v4si);
27362 v2di __builtin_ia32_vprotq (v2di, v2di);
27363 v8hi __builtin_ia32_vprotw (v8hi, v8hi);
27364 v16qi __builtin_ia32_vpshab (v16qi, v16qi);
27365 v4si __builtin_ia32_vpshad (v4si, v4si);
27366 v2di __builtin_ia32_vpshaq (v2di, v2di);
27367 v8hi __builtin_ia32_vpshaw (v8hi, v8hi);
27368 v16qi __builtin_ia32_vpshlb (v16qi, v16qi);
27369 v4si __builtin_ia32_vpshld (v4si, v4si);
27370 v2di __builtin_ia32_vpshlq (v2di, v2di);
27371 v8hi __builtin_ia32_vpshlw (v8hi, v8hi);
27374 The following built-in functions are available when @option{-mfma4} is used.
27375 All of them generate the machine instruction that is part of the name.
27378 v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df);
27379 v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf);
27380 v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df);
27381 v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf);
27382 v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df);
27383 v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf);
27384 v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df);
27385 v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf);
27386 v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df);
27387 v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf);
27388 v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df);
27389 v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf);
27390 v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df);
27391 v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf);
27392 v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df);
27393 v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf);
27394 v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df);
27395 v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf);
27396 v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df);
27397 v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf);
27398 v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df);
27399 v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf);
27400 v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df);
27401 v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf);
27402 v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df);
27403 v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf);
27404 v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df);
27405 v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf);
27406 v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df);
27407 v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf);
27408 v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df);
27409 v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf);
27413 The following built-in functions are available when @option{-mlwp} is used.
27416 void __builtin_ia32_llwpcb16 (void *);
27417 void __builtin_ia32_llwpcb32 (void *);
27418 void __builtin_ia32_llwpcb64 (void *);
27419 void * __builtin_ia32_llwpcb16 (void);
27420 void * __builtin_ia32_llwpcb32 (void);
27421 void * __builtin_ia32_llwpcb64 (void);
27422 void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short);
27423 void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int);
27424 void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int);
27425 unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short);
27426 unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int);
27427 unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int);
27430 The following built-in functions are available when @option{-mbmi} is used.
27431 All of them generate the machine instruction that is part of the name.
27433 unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int);
27434 unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long);
27437 The following built-in functions are available when @option{-mbmi2} is used.
27438 All of them generate the machine instruction that is part of the name.
27440 unsigned int _bzhi_u32 (unsigned int, unsigned int);
27441 unsigned int _pdep_u32 (unsigned int, unsigned int);
27442 unsigned int _pext_u32 (unsigned int, unsigned int);
27443 unsigned long long _bzhi_u64 (unsigned long long, unsigned long long);
27444 unsigned long long _pdep_u64 (unsigned long long, unsigned long long);
27445 unsigned long long _pext_u64 (unsigned long long, unsigned long long);
27448 The following built-in functions are available when @option{-mlzcnt} is used.
27449 All of them generate the machine instruction that is part of the name.
27451 unsigned short __builtin_ia32_lzcnt_u16(unsigned short);
27452 unsigned int __builtin_ia32_lzcnt_u32(unsigned int);
27453 unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long);
27456 The following built-in functions are available when @option{-mfxsr} is used.
27457 All of them generate the machine instruction that is part of the name.
27459 void __builtin_ia32_fxsave (void *);
27460 void __builtin_ia32_fxrstor (void *);
27461 void __builtin_ia32_fxsave64 (void *);
27462 void __builtin_ia32_fxrstor64 (void *);
27465 The following built-in functions are available when @option{-mxsave} is used.
27466 All of them generate the machine instruction that is part of the name.
27468 void __builtin_ia32_xsave (void *, long long);
27469 void __builtin_ia32_xrstor (void *, long long);
27470 void __builtin_ia32_xsave64 (void *, long long);
27471 void __builtin_ia32_xrstor64 (void *, long long);
27474 The following built-in functions are available when @option{-mxsaveopt} is used.
27475 All of them generate the machine instruction that is part of the name.
27477 void __builtin_ia32_xsaveopt (void *, long long);
27478 void __builtin_ia32_xsaveopt64 (void *, long long);
27481 The following built-in functions are available when @option{-mtbm} is used.
27482 Both of them generate the immediate form of the bextr machine instruction.
27484 unsigned int __builtin_ia32_bextri_u32 (unsigned int,
27485 const unsigned int);
27486 unsigned long long __builtin_ia32_bextri_u64 (unsigned long long,
27487 const unsigned long long);
27491 The following built-in functions are available when @option{-m3dnow} is used.
27492 All of them generate the machine instruction that is part of the name.
27495 void __builtin_ia32_femms (void);
27496 v8qi __builtin_ia32_pavgusb (v8qi, v8qi);
27497 v2si __builtin_ia32_pf2id (v2sf);
27498 v2sf __builtin_ia32_pfacc (v2sf, v2sf);
27499 v2sf __builtin_ia32_pfadd (v2sf, v2sf);
27500 v2si __builtin_ia32_pfcmpeq (v2sf, v2sf);
27501 v2si __builtin_ia32_pfcmpge (v2sf, v2sf);
27502 v2si __builtin_ia32_pfcmpgt (v2sf, v2sf);
27503 v2sf __builtin_ia32_pfmax (v2sf, v2sf);
27504 v2sf __builtin_ia32_pfmin (v2sf, v2sf);
27505 v2sf __builtin_ia32_pfmul (v2sf, v2sf);
27506 v2sf __builtin_ia32_pfrcp (v2sf);
27507 v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf);
27508 v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf);
27509 v2sf __builtin_ia32_pfrsqrt (v2sf);
27510 v2sf __builtin_ia32_pfsub (v2sf, v2sf);
27511 v2sf __builtin_ia32_pfsubr (v2sf, v2sf);
27512 v2sf __builtin_ia32_pi2fd (v2si);
27513 v4hi __builtin_ia32_pmulhrw (v4hi, v4hi);
27516 The following built-in functions are available when @option{-m3dnowa} is used.
27517 All of them generate the machine instruction that is part of the name.
27520 v2si __builtin_ia32_pf2iw (v2sf);
27521 v2sf __builtin_ia32_pfnacc (v2sf, v2sf);
27522 v2sf __builtin_ia32_pfpnacc (v2sf, v2sf);
27523 v2sf __builtin_ia32_pi2fw (v2si);
27524 v2sf __builtin_ia32_pswapdsf (v2sf);
27525 v2si __builtin_ia32_pswapdsi (v2si);
27528 The following built-in functions are available when @option{-mrtm} is used
27529 They are used for restricted transactional memory. These are the internal
27530 low level functions. Normally the functions in
27531 @ref{x86 transactional memory intrinsics} should be used instead.
27534 int __builtin_ia32_xbegin ();
27535 void __builtin_ia32_xend ();
27536 void __builtin_ia32_xabort (status);
27537 int __builtin_ia32_xtest ();
27540 The following built-in functions are available when @option{-mmwaitx} is used.
27541 All of them generate the machine instruction that is part of the name.
27543 void __builtin_ia32_monitorx (void *, unsigned int, unsigned int);
27544 void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int);
27547 The following built-in functions are available when @option{-mclzero} is used.
27548 All of them generate the machine instruction that is part of the name.
27550 void __builtin_i32_clzero (void *);
27553 The following built-in functions are available when @option{-mpku} is used.
27554 They generate reads and writes to PKRU.
27556 void __builtin_ia32_wrpkru (unsigned int);
27557 unsigned int __builtin_ia32_rdpkru ();
27560 The following built-in functions are available when
27561 @option{-mshstk} option is used. They support shadow stack
27562 machine instructions from Intel Control-flow Enforcement Technology (CET).
27563 Each built-in function generates the machine instruction that is part
27564 of the function's name. These are the internal low-level functions.
27565 Normally the functions in @ref{x86 control-flow protection intrinsics}
27566 should be used instead.
27569 unsigned int __builtin_ia32_rdsspd (void);
27570 unsigned long long __builtin_ia32_rdsspq (void);
27571 void __builtin_ia32_incsspd (unsigned int);
27572 void __builtin_ia32_incsspq (unsigned long long);
27573 void __builtin_ia32_saveprevssp(void);
27574 void __builtin_ia32_rstorssp(void *);
27575 void __builtin_ia32_wrssd(unsigned int, void *);
27576 void __builtin_ia32_wrssq(unsigned long long, void *);
27577 void __builtin_ia32_wrussd(unsigned int, void *);
27578 void __builtin_ia32_wrussq(unsigned long long, void *);
27579 void __builtin_ia32_setssbsy(void);
27580 void __builtin_ia32_clrssbsy(void *);
27583 @node x86 transactional memory intrinsics
27584 @subsection x86 Transactional Memory Intrinsics
27586 These hardware transactional memory intrinsics for x86 allow you to use
27587 memory transactions with RTM (Restricted Transactional Memory).
27588 This support is enabled with the @option{-mrtm} option.
27589 For using HLE (Hardware Lock Elision) see
27590 @ref{x86 specific memory model extensions for transactional memory} instead.
27592 A memory transaction commits all changes to memory in an atomic way,
27593 as visible to other threads. If the transaction fails it is rolled back
27594 and all side effects discarded.
27596 Generally there is no guarantee that a memory transaction ever succeeds
27597 and suitable fallback code always needs to be supplied.
27599 @deftypefn {RTM Function} {unsigned} _xbegin ()
27600 Start a RTM (Restricted Transactional Memory) transaction.
27601 Returns @code{_XBEGIN_STARTED} when the transaction
27602 started successfully (note this is not 0, so the constant has to be
27603 explicitly tested).
27605 If the transaction aborts, all side effects
27606 are undone and an abort code encoded as a bit mask is returned.
27607 The following macros are defined:
27609 @defmac{_XABORT_EXPLICIT}
27610 Transaction was explicitly aborted with @code{_xabort}. The parameter passed
27611 to @code{_xabort} is available with @code{_XABORT_CODE(status)}.
27614 @defmac{_XABORT_RETRY}
27615 Transaction retry is possible.
27618 @defmac{_XABORT_CONFLICT}
27619 Transaction abort due to a memory conflict with another thread.
27622 @defmac{_XABORT_CAPACITY}
27623 Transaction abort due to the transaction using too much memory.
27626 @defmac{_XABORT_DEBUG}
27627 Transaction abort due to a debug trap.
27630 @defmac{_XABORT_NESTED}
27631 Transaction abort in an inner nested transaction.
27634 There is no guarantee
27635 any transaction ever succeeds, so there always needs to be a valid
27639 @deftypefn {RTM Function} {void} _xend ()
27640 Commit the current transaction. When no transaction is active this faults.
27641 All memory side effects of the transaction become visible
27642 to other threads in an atomic manner.
27645 @deftypefn {RTM Function} {int} _xtest ()
27646 Return a nonzero value if a transaction is currently active, otherwise 0.
27649 @deftypefn {RTM Function} {void} _xabort (status)
27650 Abort the current transaction. When no transaction is active this is a no-op.
27651 The @var{status} is an 8-bit constant; its value is encoded in the return
27652 value from @code{_xbegin}.
27655 Here is an example showing handling for @code{_XABORT_RETRY}
27656 and a fallback path for other failures:
27659 #include <immintrin.h>
27661 int n_tries, max_tries;
27662 unsigned status = _XABORT_EXPLICIT;
27665 for (n_tries = 0; n_tries < max_tries; n_tries++)
27667 status = _xbegin ();
27668 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY))
27671 if (status == _XBEGIN_STARTED)
27673 ... transaction code...
27678 ... non-transactional fallback path...
27683 Note that, in most cases, the transactional and non-transactional code
27684 must synchronize together to ensure consistency.
27686 @node x86 control-flow protection intrinsics
27687 @subsection x86 Control-Flow Protection Intrinsics
27689 @deftypefn {CET Function} {ret_type} _get_ssp (void)
27690 Get the current value of shadow stack pointer if shadow stack support
27691 from Intel CET is enabled in the hardware or @code{0} otherwise.
27692 The @code{ret_type} is @code{unsigned long long} for 64-bit targets
27693 and @code{unsigned int} for 32-bit targets.
27696 @deftypefn {CET Function} void _inc_ssp (unsigned int)
27697 Increment the current shadow stack pointer by the size specified by the
27698 function argument. The argument is masked to a byte value for security
27699 reasons, so to increment by more than 255 bytes you must call the function
27703 The shadow stack unwind code looks like:
27706 #include <immintrin.h>
27708 /* Unwind the shadow stack for EH. */
27709 #define _Unwind_Frames_Extra(x) \
27712 _Unwind_Word ssp = _get_ssp (); \
27715 _Unwind_Word tmp = (x); \
27716 while (tmp > 255) \
27728 This code runs unconditionally on all 64-bit processors. For 32-bit
27729 processors the code runs on those that support multi-byte NOP instructions.
27731 @node Target Format Checks
27732 @section Format Checks Specific to Particular Target Machines
27734 For some target machines, GCC supports additional options to the
27736 (@pxref{Function Attributes,,Declaring Attributes of Functions}).
27739 * Solaris Format Checks::
27740 * Darwin Format Checks::
27743 @node Solaris Format Checks
27744 @subsection Solaris Format Checks
27746 Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format
27747 check. @code{cmn_err} accepts a subset of the standard @code{printf}
27748 conversions, and the two-argument @code{%b} conversion for displaying
27749 bit-fields. See the Solaris man page for @code{cmn_err} for more information.
27751 @node Darwin Format Checks
27752 @subsection Darwin Format Checks
27754 In addition to the full set of format archetypes (attribute format style
27755 arguments such as @code{printf}, @code{scanf}, @code{strftime}, and
27756 @code{strfmon}), Darwin targets also support the @code{CFString} (or
27757 @code{__CFString__}) archetype in the @code{format} attribute.
27758 Declarations with this archetype are parsed for correct syntax
27759 and argument types. However, parsing of the format string itself and
27760 validating arguments against it in calls to such functions is currently
27763 Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may
27764 also be used as format arguments. Note that the relevant headers are only likely to be
27765 available on Darwin (OSX) installations. On such installations, the XCode and system
27766 documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and
27767 associated functions.
27770 @section Pragmas Accepted by GCC
27772 @cindex @code{#pragma}
27774 GCC supports several types of pragmas, primarily in order to compile
27775 code originally written for other compilers. Note that in general
27776 we do not recommend the use of pragmas; @xref{Function Attributes},
27777 for further explanation.
27779 The GNU C preprocessor recognizes several pragmas in addition to the
27780 compiler pragmas documented here. Refer to the CPP manual for more
27784 * AArch64 Pragmas::
27788 * RS/6000 and PowerPC Pragmas::
27791 * Solaris Pragmas::
27792 * Symbol-Renaming Pragmas::
27793 * Structure-Layout Pragmas::
27795 * Diagnostic Pragmas::
27796 * Visibility Pragmas::
27797 * Push/Pop Macro Pragmas::
27798 * Function Specific Option Pragmas::
27799 * Loop-Specific Pragmas::
27802 @node AArch64 Pragmas
27803 @subsection AArch64 Pragmas
27805 The pragmas defined by the AArch64 target correspond to the AArch64
27806 target function attributes. They can be specified as below:
27808 #pragma GCC target("string")
27811 where @code{@var{string}} can be any string accepted as an AArch64 target
27812 attribute. @xref{AArch64 Function Attributes}, for more details
27813 on the permissible values of @code{string}.
27816 @subsection ARM Pragmas
27818 The ARM target defines pragmas for controlling the default addition of
27819 @code{long_call} and @code{short_call} attributes to functions.
27820 @xref{Function Attributes}, for information about the effects of these
27824 @cindex pragma, long_calls
27826 Set all subsequent functions to have the @code{long_call} attribute.
27828 @cindex pragma, no_long_calls
27829 @item no_long_calls
27830 Set all subsequent functions to have the @code{short_call} attribute.
27832 @cindex pragma, long_calls_off
27833 @item long_calls_off
27834 Do not affect the @code{long_call} or @code{short_call} attributes of
27835 subsequent functions.
27839 @subsection M32C Pragmas
27842 @cindex pragma, memregs
27843 @item GCC memregs @var{number}
27844 Overrides the command-line option @code{-memregs=} for the current
27845 file. Use with care! This pragma must be before any function in the
27846 file, and mixing different memregs values in different objects may
27847 make them incompatible. This pragma is useful when a
27848 performance-critical function uses a memreg for temporary values,
27849 as it may allow you to reduce the number of memregs used.
27851 @cindex pragma, address
27852 @item ADDRESS @var{name} @var{address}
27853 For any declared symbols matching @var{name}, this does three things
27854 to that symbol: it forces the symbol to be located at the given
27855 address (a number), it forces the symbol to be volatile, and it
27856 changes the symbol's scope to be static. This pragma exists for
27857 compatibility with other compilers, but note that the common
27858 @code{1234H} numeric syntax is not supported (use @code{0x1234}
27862 #pragma ADDRESS port3 0x103
27869 @subsection PRU Pragmas
27873 @cindex pragma, ctable_entry
27874 @item ctable_entry @var{index} @var{constant_address}
27875 Specifies that the PRU CTABLE entry given by @var{index} has the value
27876 @var{constant_address}. This enables GCC to emit LBCO/SBCO instructions
27877 when the load/store address is known and can be addressed with some CTABLE
27878 entry. For example:
27881 /* will compile to "sbco Rx, 2, 0x10, 4" */
27882 #pragma ctable_entry 2 0x4802a000
27883 *(unsigned int *)0x4802a010 = val;
27888 @node RS/6000 and PowerPC Pragmas
27889 @subsection RS/6000 and PowerPC Pragmas
27891 The RS/6000 and PowerPC targets define one pragma for controlling
27892 whether or not the @code{longcall} attribute is added to function
27893 declarations by default. This pragma overrides the @option{-mlongcall}
27894 option, but not the @code{longcall} and @code{shortcall} attributes.
27895 @xref{RS/6000 and PowerPC Options}, for more information about when long
27896 calls are and are not necessary.
27899 @cindex pragma, longcall
27901 Apply the @code{longcall} attribute to all subsequent function
27905 Do not apply the @code{longcall} attribute to subsequent function
27909 @c Describe h8300 pragmas here.
27910 @c Describe sh pragmas here.
27911 @c Describe v850 pragmas here.
27913 @node S/390 Pragmas
27914 @subsection S/390 Pragmas
27916 The pragmas defined by the S/390 target correspond to the S/390
27917 target function attributes and some the additional options:
27924 Note that options of the pragma, unlike options of the target
27925 attribute, do change the value of preprocessor macros like
27926 @code{__VEC__}. They can be specified as below:
27929 #pragma GCC target("string[,string]...")
27930 #pragma GCC target("string"[,"string"]...)
27933 @node Darwin Pragmas
27934 @subsection Darwin Pragmas
27936 The following pragmas are available for all architectures running the
27937 Darwin operating system. These are useful for compatibility with other
27941 @cindex pragma, mark
27942 @item mark @var{tokens}@dots{}
27943 This pragma is accepted, but has no effect.
27945 @cindex pragma, options align
27946 @item options align=@var{alignment}
27947 This pragma sets the alignment of fields in structures. The values of
27948 @var{alignment} may be @code{mac68k}, to emulate m68k alignment, or
27949 @code{power}, to emulate PowerPC alignment. Uses of this pragma nest
27950 properly; to restore the previous setting, use @code{reset} for the
27953 @cindex pragma, segment
27954 @item segment @var{tokens}@dots{}
27955 This pragma is accepted, but has no effect.
27957 @cindex pragma, unused
27958 @item unused (@var{var} [, @var{var}]@dots{})
27959 This pragma declares variables to be possibly unused. GCC does not
27960 produce warnings for the listed variables. The effect is similar to
27961 that of the @code{unused} attribute, except that this pragma may appear
27962 anywhere within the variables' scopes.
27965 @node Solaris Pragmas
27966 @subsection Solaris Pragmas
27968 The Solaris target supports @code{#pragma redefine_extname}
27969 (@pxref{Symbol-Renaming Pragmas}). It also supports additional
27970 @code{#pragma} directives for compatibility with the system compiler.
27973 @cindex pragma, align
27974 @item align @var{alignment} (@var{variable} [, @var{variable}]...)
27976 Increase the minimum alignment of each @var{variable} to @var{alignment}.
27977 This is the same as GCC's @code{aligned} attribute @pxref{Variable
27978 Attributes}). Macro expansion occurs on the arguments to this pragma
27979 when compiling C and Objective-C@. It does not currently occur when
27980 compiling C++, but this is a bug which may be fixed in a future
27983 @cindex pragma, fini
27984 @item fini (@var{function} [, @var{function}]...)
27986 This pragma causes each listed @var{function} to be called after
27987 main, or during shared module unloading, by adding a call to the
27988 @code{.fini} section.
27990 @cindex pragma, init
27991 @item init (@var{function} [, @var{function}]...)
27993 This pragma causes each listed @var{function} to be called during
27994 initialization (before @code{main}) or during shared module loading, by
27995 adding a call to the @code{.init} section.
27999 @node Symbol-Renaming Pragmas
28000 @subsection Symbol-Renaming Pragmas
28002 GCC supports a @code{#pragma} directive that changes the name used in
28003 assembly for a given declaration. While this pragma is supported on all
28004 platforms, it is intended primarily to provide compatibility with the
28005 Solaris system headers. This effect can also be achieved using the asm
28006 labels extension (@pxref{Asm Labels}).
28009 @cindex pragma, redefine_extname
28010 @item redefine_extname @var{oldname} @var{newname}
28012 This pragma gives the C function @var{oldname} the assembly symbol
28013 @var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME}
28014 is defined if this pragma is available (currently on all platforms).
28017 This pragma and the @code{asm} labels extension interact in a complicated
28018 manner. Here are some corner cases you may want to be aware of:
28021 @item This pragma silently applies only to declarations with external
28022 linkage. The @code{asm} label feature does not have this restriction.
28024 @item In C++, this pragma silently applies only to declarations with
28025 ``C'' linkage. Again, @code{asm} labels do not have this restriction.
28027 @item If either of the ways of changing the assembly name of a
28028 declaration are applied to a declaration whose assembly name has
28029 already been determined (either by a previous use of one of these
28030 features, or because the compiler needed the assembly name in order to
28031 generate code), and the new name is different, a warning issues and
28032 the name does not change.
28034 @item The @var{oldname} used by @code{#pragma redefine_extname} is
28035 always the C-language name.
28038 @node Structure-Layout Pragmas
28039 @subsection Structure-Layout Pragmas
28041 For compatibility with Microsoft Windows compilers, GCC supports a
28042 set of @code{#pragma} directives that change the maximum alignment of
28043 members of structures (other than zero-width bit-fields), unions, and
28044 classes subsequently defined. The @var{n} value below always is required
28045 to be a small power of two and specifies the new alignment in bytes.
28048 @item @code{#pragma pack(@var{n})} simply sets the new alignment.
28049 @item @code{#pragma pack()} sets the alignment to the one that was in
28050 effect when compilation started (see also command-line option
28051 @option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}).
28052 @item @code{#pragma pack(push[,@var{n}])} pushes the current alignment
28053 setting on an internal stack and then optionally sets the new alignment.
28054 @item @code{#pragma pack(pop)} restores the alignment setting to the one
28055 saved at the top of the internal stack (and removes that stack entry).
28056 Note that @code{#pragma pack([@var{n}])} does not influence this internal
28057 stack; thus it is possible to have @code{#pragma pack(push)} followed by
28058 multiple @code{#pragma pack(@var{n})} instances and finalized by a single
28059 @code{#pragma pack(pop)}.
28062 Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct}
28063 directive which lays out structures and unions subsequently defined as the
28064 documented @code{__attribute__ ((ms_struct))}.
28067 @item @code{#pragma ms_struct on} turns on the Microsoft layout.
28068 @item @code{#pragma ms_struct off} turns off the Microsoft layout.
28069 @item @code{#pragma ms_struct reset} goes back to the default layout.
28072 Most targets also support the @code{#pragma scalar_storage_order} directive
28073 which lays out structures and unions subsequently defined as the documented
28074 @code{__attribute__ ((scalar_storage_order))}.
28077 @item @code{#pragma scalar_storage_order big-endian} sets the storage order
28078 of the scalar fields to big-endian.
28079 @item @code{#pragma scalar_storage_order little-endian} sets the storage order
28080 of the scalar fields to little-endian.
28081 @item @code{#pragma scalar_storage_order default} goes back to the endianness
28082 that was in effect when compilation started (see also command-line option
28083 @option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}).
28087 @subsection Weak Pragmas
28089 For compatibility with SVR4, GCC supports a set of @code{#pragma}
28090 directives for declaring symbols to be weak, and defining weak
28094 @cindex pragma, weak
28095 @item #pragma weak @var{symbol}
28096 This pragma declares @var{symbol} to be weak, as if the declaration
28097 had the attribute of the same name. The pragma may appear before
28098 or after the declaration of @var{symbol}. It is not an error for
28099 @var{symbol} to never be defined at all.
28101 @item #pragma weak @var{symbol1} = @var{symbol2}
28102 This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}.
28103 It is an error if @var{symbol2} is not defined in the current
28107 @node Diagnostic Pragmas
28108 @subsection Diagnostic Pragmas
28110 GCC allows the user to selectively enable or disable certain types of
28111 diagnostics, and change the kind of the diagnostic. For example, a
28112 project's policy might require that all sources compile with
28113 @option{-Werror} but certain files might have exceptions allowing
28114 specific types of warnings. Or, a project might selectively enable
28115 diagnostics and treat them as errors depending on which preprocessor
28116 macros are defined.
28119 @cindex pragma, diagnostic
28120 @item #pragma GCC diagnostic @var{kind} @var{option}
28122 Modifies the disposition of a diagnostic. Note that not all
28123 diagnostics are modifiable; at the moment only warnings (normally
28124 controlled by @samp{-W@dots{}}) can be controlled, and not all of them.
28125 Use @option{-fdiagnostics-show-option} to determine which diagnostics
28126 are controllable and which option controls them.
28128 @var{kind} is @samp{error} to treat this diagnostic as an error,
28129 @samp{warning} to treat it like a warning (even if @option{-Werror} is
28130 in effect), or @samp{ignored} if the diagnostic is to be ignored.
28131 @var{option} is a double quoted string that matches the command-line
28135 #pragma GCC diagnostic warning "-Wformat"
28136 #pragma GCC diagnostic error "-Wformat"
28137 #pragma GCC diagnostic ignored "-Wformat"
28140 Note that these pragmas override any command-line options. GCC keeps
28141 track of the location of each pragma, and issues diagnostics according
28142 to the state as of that point in the source file. Thus, pragmas occurring
28143 after a line do not affect diagnostics caused by that line.
28145 @item #pragma GCC diagnostic push
28146 @itemx #pragma GCC diagnostic pop
28148 Causes GCC to remember the state of the diagnostics as of each
28149 @code{push}, and restore to that point at each @code{pop}. If a
28150 @code{pop} has no matching @code{push}, the command-line options are
28154 #pragma GCC diagnostic error "-Wuninitialized"
28155 foo(a); /* error is given for this one */
28156 #pragma GCC diagnostic push
28157 #pragma GCC diagnostic ignored "-Wuninitialized"
28158 foo(b); /* no diagnostic for this one */
28159 #pragma GCC diagnostic pop
28160 foo(c); /* error is given for this one */
28161 #pragma GCC diagnostic pop
28162 foo(d); /* depends on command-line options */
28165 @item #pragma GCC diagnostic ignored_attributes
28167 Similarly to @option{-Wno-attributes=}, this pragma allows users to suppress
28168 warnings about unknown scoped attributes (in C++11 and C23). For example,
28169 @code{#pragma GCC diagnostic ignored_attributes "vendor::attr"} disables
28170 warning about the following declaration:
28173 [[vendor::attr]] void f();
28176 whereas @code{#pragma GCC diagnostic ignored_attributes "vendor::"} prevents
28177 warning about both of these declarations:
28180 [[vendor::safe]] void f();
28181 [[vendor::unsafe]] void f2();
28186 GCC also offers a simple mechanism for printing messages during
28190 @cindex pragma, diagnostic
28191 @item #pragma message @var{string}
28193 Prints @var{string} as a compiler message on compilation. The message
28194 is informational only, and is neither a compilation warning nor an
28195 error. Newlines can be included in the string by using the @samp{\n}
28199 #pragma message "Compiling " __FILE__ "..."
28202 @var{string} may be parenthesized, and is printed with location
28203 information. For example,
28206 #define DO_PRAGMA(x) _Pragma (#x)
28207 #define TODO(x) DO_PRAGMA(message ("TODO - " #x))
28209 TODO(Remember to fix this)
28213 prints @samp{/tmp/file.c:4: note: #pragma message:
28214 TODO - Remember to fix this}.
28216 @cindex pragma, diagnostic
28217 @item #pragma GCC error @var{message}
28218 Generates an error message. This pragma @emph{is} considered to
28219 indicate an error in the compilation, and it will be treated as such.
28221 Newlines can be included in the string by using the @samp{\n}
28222 escape sequence. They will be displayed as newlines even if the
28223 @option{-fmessage-length} option is set to zero.
28225 The error is only generated if the pragma is present in the code after
28226 pre-processing has been completed. It does not matter however if the
28227 code containing the pragma is unreachable:
28231 #pragma GCC error "this error is not seen"
28236 #pragma GCC error "this error is seen"
28240 @cindex pragma, diagnostic
28241 @item #pragma GCC warning @var{message}
28242 This is just like @samp{pragma GCC error} except that a warning
28243 message is issued instead of an error message. Unless
28244 @option{-Werror} is in effect, in which case this pragma will generate
28249 @node Visibility Pragmas
28250 @subsection Visibility Pragmas
28253 @cindex pragma, visibility
28254 @item #pragma GCC visibility push(@var{visibility})
28255 @itemx #pragma GCC visibility pop
28257 This pragma allows the user to set the visibility for multiple
28258 declarations without having to give each a visibility attribute
28259 (@pxref{Function Attributes}).
28261 In C++, @samp{#pragma GCC visibility} affects only namespace-scope
28262 declarations. Class members and template specializations are not
28263 affected; if you want to override the visibility for a particular
28264 member or instantiation, you must use an attribute.
28269 @node Push/Pop Macro Pragmas
28270 @subsection Push/Pop Macro Pragmas
28272 For compatibility with Microsoft Windows compilers, GCC supports
28273 @samp{#pragma push_macro(@var{"macro_name"})}
28274 and @samp{#pragma pop_macro(@var{"macro_name"})}.
28277 @cindex pragma, push_macro
28278 @item #pragma push_macro(@var{"macro_name"})
28279 This pragma saves the value of the macro named as @var{macro_name} to
28280 the top of the stack for this macro.
28282 @cindex pragma, pop_macro
28283 @item #pragma pop_macro(@var{"macro_name"})
28284 This pragma sets the value of the macro named as @var{macro_name} to
28285 the value on top of the stack for this macro. If the stack for
28286 @var{macro_name} is empty, the value of the macro remains unchanged.
28293 #pragma push_macro("X")
28296 #pragma pop_macro("X")
28301 In this example, the definition of X as 1 is saved by @code{#pragma
28302 push_macro} and restored by @code{#pragma pop_macro}.
28304 @node Function Specific Option Pragmas
28305 @subsection Function Specific Option Pragmas
28308 @cindex pragma GCC target
28309 @item #pragma GCC target (@var{string}, @dots{})
28311 This pragma allows you to set target-specific options for functions
28312 defined later in the source file. One or more strings can be
28313 specified. Each function that is defined after this point is treated
28314 as if it had been declared with one @code{target(}@var{string}@code{)}
28315 attribute for each @var{string} argument. The parentheses around
28316 the strings in the pragma are optional. @xref{Function Attributes},
28317 for more information about the @code{target} attribute and the attribute
28320 The @code{#pragma GCC target} pragma is presently implemented for
28321 x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only.
28323 @cindex pragma GCC optimize
28324 @item #pragma GCC optimize (@var{string}, @dots{})
28326 This pragma allows you to set global optimization options for functions
28327 defined later in the source file. One or more strings can be
28328 specified. Each function that is defined after this point is treated
28329 as if it had been declared with one @code{optimize(}@var{string}@code{)}
28330 attribute for each @var{string} argument. The parentheses around
28331 the strings in the pragma are optional. @xref{Function Attributes},
28332 for more information about the @code{optimize} attribute and the attribute
28335 @cindex pragma GCC push_options
28336 @cindex pragma GCC pop_options
28337 @item #pragma GCC push_options
28338 @itemx #pragma GCC pop_options
28340 These pragmas maintain a stack of the current target and optimization
28341 options. It is intended for include files where you temporarily want
28342 to switch to using a different @samp{#pragma GCC target} or
28343 @samp{#pragma GCC optimize} and then to pop back to the previous
28346 @cindex pragma GCC reset_options
28347 @item #pragma GCC reset_options
28349 This pragma clears the current @code{#pragma GCC target} and
28350 @code{#pragma GCC optimize} to use the default switches as specified
28351 on the command line.
28355 @node Loop-Specific Pragmas
28356 @subsection Loop-Specific Pragmas
28359 @cindex pragma GCC ivdep
28360 @item #pragma GCC ivdep
28362 With this pragma, the programmer asserts that there are no loop-carried
28363 dependencies which would prevent consecutive iterations of
28364 the following loop from executing concurrently with SIMD
28365 (single instruction multiple data) instructions.
28367 For example, the compiler can only unconditionally vectorize the following
28368 loop with the pragma:
28371 void foo (int n, int *a, int *b, int *c)
28375 for (i = 0; i < n; ++i)
28376 a[i] = b[i] + c[i];
28381 In this example, using the @code{restrict} qualifier had the same
28382 effect. In the following example, that would not be possible. Assume
28383 @math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows
28384 that it can unconditionally vectorize the following loop:
28387 void ignore_vec_dep (int *a, int k, int c, int m)
28390 for (int i = 0; i < m; i++)
28391 a[i] = a[i + k] * c;
28395 @cindex pragma GCC novector
28396 @item #pragma GCC novector
28398 With this pragma, the programmer asserts that the following loop should be
28399 prevented from executing concurrently with SIMD (single instruction multiple
28400 data) instructions.
28402 For example, the compiler cannot vectorize the following loop with the pragma:
28405 void foo (int n, int *a, int *b, int *c)
28408 #pragma GCC novector
28409 for (i = 0; i < n; ++i)
28410 a[i] = b[i] + c[i];
28414 @cindex pragma GCC unroll @var{n}
28415 @item #pragma GCC unroll @var{n}
28417 You can use this pragma to control how many times a loop should be unrolled.
28418 It must be placed immediately before a @code{for}, @code{while} or @code{do}
28419 loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows.
28420 @var{n} is an integer constant expression specifying the unrolling factor.
28421 The values of @math{0} and @math{1} block any unrolling of the loop.
28425 @node Unnamed Fields
28426 @section Unnamed Structure and Union Fields
28427 @cindex @code{struct}
28428 @cindex @code{union}
28430 As permitted by ISO C11 and for compatibility with other compilers,
28431 GCC allows you to define
28432 a structure or union that contains, as fields, structures and unions
28433 without names. For example:
28447 In this example, you are able to access members of the unnamed
28448 union with code like @samp{foo.b}. Note that only unnamed structs and
28449 unions are allowed, you may not have, for example, an unnamed
28452 You must never create such structures that cause ambiguous field definitions.
28453 For example, in this structure:
28465 it is ambiguous which @code{a} is being referred to with @samp{foo.a}.
28466 The compiler gives errors for such constructs.
28468 @opindex fms-extensions
28469 Unless @option{-fms-extensions} is used, the unnamed field must be a
28470 structure or union definition without a tag (for example, @samp{struct
28471 @{ int a; @};}). If @option{-fms-extensions} is used, the field may
28472 also be a definition with a tag such as @samp{struct foo @{ int a;
28473 @};}, a reference to a previously defined structure or union such as
28474 @samp{struct foo;}, or a reference to a @code{typedef} name for a
28475 previously defined structure or union type.
28477 @opindex fplan9-extensions
28478 The option @option{-fplan9-extensions} enables
28479 @option{-fms-extensions} as well as two other extensions. First, a
28480 pointer to a structure is automatically converted to a pointer to an
28481 anonymous field for assignments and function calls. For example:
28484 struct s1 @{ int a; @};
28485 struct s2 @{ struct s1; @};
28486 extern void f1 (struct s1 *);
28487 void f2 (struct s2 *p) @{ f1 (p); @}
28491 In the call to @code{f1} inside @code{f2}, the pointer @code{p} is
28492 converted into a pointer to the anonymous field.
28494 Second, when the type of an anonymous field is a @code{typedef} for a
28495 @code{struct} or @code{union}, code may refer to the field using the
28496 name of the @code{typedef}.
28499 typedef struct @{ int a; @} s1;
28500 struct s2 @{ s1; @};
28501 s1 f1 (struct s2 *p) @{ return p->s1; @}
28504 These usages are only permitted when they are not ambiguous.
28507 @section Thread-Local Storage
28508 @cindex Thread-Local Storage
28509 @cindex @acronym{TLS}
28510 @cindex @code{__thread}
28512 Thread-local storage (@acronym{TLS}) is a mechanism by which variables
28513 are allocated such that there is one instance of the variable per extant
28514 thread. The runtime model GCC uses to implement this originates
28515 in the IA-64 processor-specific ABI, but has since been migrated
28516 to other processors as well. It requires significant support from
28517 the linker (@command{ld}), dynamic linker (@command{ld.so}), and
28518 system libraries (@file{libc.so} and @file{libpthread.so}), so it
28519 is not available everywhere.
28521 At the user level, the extension is visible with a new storage
28522 class keyword: @code{__thread}. For example:
28526 extern __thread struct state s;
28527 static __thread char *p;
28530 The @code{__thread} specifier may be used alone, with the @code{extern}
28531 or @code{static} specifiers, but with no other storage class specifier.
28532 When used with @code{extern} or @code{static}, @code{__thread} must appear
28533 immediately after the other storage class specifier.
28535 The @code{__thread} specifier may be applied to any global, file-scoped
28536 static, function-scoped static, or static data member of a class. It may
28537 not be applied to block-scoped automatic or non-static data member.
28539 When the address-of operator is applied to a thread-local variable, it is
28540 evaluated at run time and returns the address of the current thread's
28541 instance of that variable. An address so obtained may be used by any
28542 thread. When a thread terminates, any pointers to thread-local variables
28543 in that thread become invalid.
28545 No static initialization may refer to the address of a thread-local variable.
28547 In C++, if an initializer is present for a thread-local variable, it must
28548 be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++
28551 See @uref{https://www.akkadia.org/drepper/tls.pdf,
28552 ELF Handling For Thread-Local Storage} for a detailed explanation of
28553 the four thread-local storage addressing models, and how the runtime
28554 is expected to function.
28557 * C99 Thread-Local Edits::
28558 * C++98 Thread-Local Edits::
28561 @node C99 Thread-Local Edits
28562 @subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage
28564 The following are a set of changes to ISO/IEC 9899:1999 (aka C99)
28565 that document the exact semantics of the language extension.
28569 @cite{5.1.2 Execution environments}
28571 Add new text after paragraph 1
28574 Within either execution environment, a @dfn{thread} is a flow of
28575 control within a program. It is implementation defined whether
28576 or not there may be more than one thread associated with a program.
28577 It is implementation defined how threads beyond the first are
28578 created, the name and type of the function called at thread
28579 startup, and how threads may be terminated. However, objects
28580 with thread storage duration shall be initialized before thread
28585 @cite{6.2.4 Storage durations of objects}
28587 Add new text before paragraph 3
28590 An object whose identifier is declared with the storage-class
28591 specifier @w{@code{__thread}} has @dfn{thread storage duration}.
28592 Its lifetime is the entire execution of the thread, and its
28593 stored value is initialized only once, prior to thread startup.
28597 @cite{6.4.1 Keywords}
28599 Add @code{__thread}.
28602 @cite{6.7.1 Storage-class specifiers}
28604 Add @code{__thread} to the list of storage class specifiers in
28607 Change paragraph 2 to
28610 With the exception of @code{__thread}, at most one storage-class
28611 specifier may be given [@dots{}]. The @code{__thread} specifier may
28612 be used alone, or immediately following @code{extern} or
28616 Add new text after paragraph 6
28619 The declaration of an identifier for a variable that has
28620 block scope that specifies @code{__thread} shall also
28621 specify either @code{extern} or @code{static}.
28623 The @code{__thread} specifier shall be used only with
28628 @node C++98 Thread-Local Edits
28629 @subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage
28631 The following are a set of changes to ISO/IEC 14882:1998 (aka C++98)
28632 that document the exact semantics of the language extension.
28636 @b{[intro.execution]}
28638 New text after paragraph 4
28641 A @dfn{thread} is a flow of control within the abstract machine.
28642 It is implementation defined whether or not there may be more than
28646 New text after paragraph 7
28649 It is unspecified whether additional action must be taken to
28650 ensure when and whether side effects are visible to other threads.
28656 Add @code{__thread}.
28659 @b{[basic.start.main]}
28661 Add after paragraph 5
28664 The thread that begins execution at the @code{main} function is called
28665 the @dfn{main thread}. It is implementation defined how functions
28666 beginning threads other than the main thread are designated or typed.
28667 A function so designated, as well as the @code{main} function, is called
28668 a @dfn{thread startup function}. It is implementation defined what
28669 happens if a thread startup function returns. It is implementation
28670 defined what happens to other threads when any thread calls @code{exit}.
28674 @b{[basic.start.init]}
28676 Add after paragraph 4
28679 The storage for an object of thread storage duration shall be
28680 statically initialized before the first statement of the thread startup
28681 function. An object of thread storage duration shall not require
28682 dynamic initialization.
28686 @b{[basic.start.term]}
28688 Add after paragraph 3
28691 The type of an object with thread storage duration shall not have a
28692 non-trivial destructor, nor shall it be an array type whose elements
28693 (directly or indirectly) have non-trivial destructors.
28699 Add ``thread storage duration'' to the list in paragraph 1.
28704 Thread, static, and automatic storage durations are associated with
28705 objects introduced by declarations [@dots{}].
28708 Add @code{__thread} to the list of specifiers in paragraph 3.
28711 @b{[basic.stc.thread]}
28713 New section before @b{[basic.stc.static]}
28716 The keyword @code{__thread} applied to a non-local object gives the
28717 object thread storage duration.
28719 A local variable or class data member declared both @code{static}
28720 and @code{__thread} gives the variable or member thread storage
28725 @b{[basic.stc.static]}
28730 All objects that have neither thread storage duration, dynamic
28731 storage duration nor are local [@dots{}].
28737 Add @code{__thread} to the list in paragraph 1.
28742 With the exception of @code{__thread}, at most one
28743 @var{storage-class-specifier} shall appear in a given
28744 @var{decl-specifier-seq}. The @code{__thread} specifier may
28745 be used alone, or immediately following the @code{extern} or
28746 @code{static} specifiers. [@dots{}]
28749 Add after paragraph 5
28752 The @code{__thread} specifier can be applied only to the names of objects
28753 and to anonymous unions.
28759 Add after paragraph 6
28762 Non-@code{static} members shall not be @code{__thread}.
28766 @node Binary constants
28767 @section Binary Constants using the @samp{0b} Prefix
28768 @cindex Binary constants using the @samp{0b} prefix
28770 Integer constants can be written as binary constants, consisting of a
28771 sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
28772 @samp{0B}. This is particularly useful in environments that operate a
28773 lot on the bit level (like microcontrollers).
28775 The following statements are identical:
28784 The type of these constants follows the same rules as for octal or
28785 hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
28788 @node C++ Extensions
28789 @chapter Extensions to the C++ Language
28790 @cindex extensions, C++ language
28791 @cindex C++ language extensions
28793 The GNU compiler provides these extensions to the C++ language (and you
28794 can also use most of the C language extensions in your C++ programs). If you
28795 want to write code that checks whether these features are available, you can
28796 test for the GNU compiler the same way as for C programs: check for a
28797 predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to
28798 test specifically for GNU C++ (@pxref{Common Predefined Macros,,
28799 Predefined Macros,cpp,The GNU C Preprocessor}).
28802 * C++ Volatiles:: What constitutes an access to a volatile object.
28803 * Restricted Pointers:: C99 restricted pointers and references.
28804 * Vague Linkage:: Where G++ puts inlines, vtables and such.
28805 * C++ Interface:: You can use a single C++ header file for both
28806 declarations and definitions.
28807 * Template Instantiation:: Methods for ensuring that exactly one copy of
28808 each needed template instantiation is emitted.
28809 * Bound member functions:: You can extract a function pointer to the
28810 method denoted by a @samp{->*} or @samp{.*} expression.
28811 * C++ Attributes:: Variable, function, and type attributes for C++ only.
28812 * Function Multiversioning:: Declaring multiple function versions.
28813 * Type Traits:: Compiler support for type traits.
28814 * C++ Concepts:: Improved support for generic programming.
28815 * Deprecated Features:: Things will disappear from G++.
28816 * Backwards Compatibility:: Compatibilities with earlier definitions of C++.
28819 @node C++ Volatiles
28820 @section When is a Volatile C++ Object Accessed?
28821 @cindex accessing volatiles
28822 @cindex volatile read
28823 @cindex volatile write
28824 @cindex volatile access
28826 The C++ standard differs from the C standard in its treatment of
28827 volatile objects. It fails to specify what constitutes a volatile
28828 access, except to say that C++ should behave in a similar manner to C
28829 with respect to volatiles, where possible. However, the different
28830 lvalueness of expressions between C and C++ complicate the behavior.
28831 G++ behaves the same as GCC for volatile access, @xref{C
28832 Extensions,,Volatiles}, for a description of GCC's behavior.
28834 The C and C++ language specifications differ when an object is
28835 accessed in a void context:
28838 volatile int *src = @var{somevalue};
28842 The C++ standard specifies that such expressions do not undergo lvalue
28843 to rvalue conversion, and that the type of the dereferenced object may
28844 be incomplete. The C++ standard does not specify explicitly that it
28845 is lvalue to rvalue conversion that is responsible for causing an
28846 access. There is reason to believe that it is, because otherwise
28847 certain simple expressions become undefined. However, because it
28848 would surprise most programmers, G++ treats dereferencing a pointer to
28849 volatile object of complete type as GCC would do for an equivalent
28850 type in C@. When the object has incomplete type, G++ issues a
28851 warning; if you wish to force an error, you must force a conversion to
28852 rvalue with, for instance, a static cast.
28854 When using a reference to volatile, G++ does not treat equivalent
28855 expressions as accesses to volatiles, but instead issues a warning that
28856 no volatile is accessed. The rationale for this is that otherwise it
28857 becomes difficult to determine where volatile access occur, and not
28858 possible to ignore the return value from functions returning volatile
28859 references. Again, if you wish to force a read, cast the reference to
28862 G++ implements the same behavior as GCC does when assigning to a
28863 volatile object---there is no reread of the assigned-to object, the
28864 assigned rvalue is reused. Note that in C++ assignment expressions
28865 are lvalues, and if used as an lvalue, the volatile object is
28866 referred to. For instance, @var{vref} refers to @var{vobj}, as
28867 expected, in the following example:
28871 volatile int &vref = vobj = @var{something};
28874 @node Restricted Pointers
28875 @section Restricting Pointer Aliasing
28876 @cindex restricted pointers
28877 @cindex restricted references
28878 @cindex restricted this pointer
28880 As with the C front end, G++ understands the C99 feature of restricted pointers,
28881 specified with the @code{__restrict__}, or @code{__restrict} type
28882 qualifier. Because you cannot compile C++ by specifying the @option{-std=c99}
28883 language flag, @code{restrict} is not a keyword in C++.
28885 In addition to allowing restricted pointers, you can specify restricted
28886 references, which indicate that the reference is not aliased in the local
28890 void fn (int *__restrict__ rptr, int &__restrict__ rref)
28897 In the body of @code{fn}, @var{rptr} points to an unaliased integer and
28898 @var{rref} refers to a (different) unaliased integer.
28900 You may also specify whether a member function's @var{this} pointer is
28901 unaliased by using @code{__restrict__} as a member function qualifier.
28904 void T::fn () __restrict__
28911 Within the body of @code{T::fn}, @var{this} has the effective
28912 definition @code{T *__restrict__ const this}. Notice that the
28913 interpretation of a @code{__restrict__} member function qualifier is
28914 different to that of @code{const} or @code{volatile} qualifier, in that it
28915 is applied to the pointer rather than the object. This is consistent with
28916 other compilers that implement restricted pointers.
28918 As with all outermost parameter qualifiers, @code{__restrict__} is
28919 ignored in function definition matching. This means you only need to
28920 specify @code{__restrict__} in a function definition, rather than
28921 in a function prototype as well.
28923 @node Vague Linkage
28924 @section Vague Linkage
28925 @cindex vague linkage
28927 There are several constructs in C++ that require space in the object
28928 file but are not clearly tied to a single translation unit. We say that
28929 these constructs have ``vague linkage''. Typically such constructs are
28930 emitted wherever they are needed, though sometimes we can be more
28934 @item Inline Functions
28935 Inline functions are typically defined in a header file which can be
28936 included in many different compilations. Hopefully they can usually be
28937 inlined, but sometimes an out-of-line copy is necessary, if the address
28938 of the function is taken or if inlining fails. In general, we emit an
28939 out-of-line copy in all translation units where one is needed. As an
28940 exception, we only emit inline virtual functions with the vtable, since
28941 it always requires a copy.
28943 Local static variables and string constants used in an inline function
28944 are also considered to have vague linkage, since they must be shared
28945 between all inlined and out-of-line instances of the function.
28949 C++ virtual functions are implemented in most compilers using a lookup
28950 table, known as a vtable. The vtable contains pointers to the virtual
28951 functions provided by a class, and each object of the class contains a
28952 pointer to its vtable (or vtables, in some multiple-inheritance
28953 situations). If the class declares any non-inline, non-pure virtual
28954 functions, the first one is chosen as the ``key method'' for the class,
28955 and the vtable is only emitted in the translation unit where the key
28958 @emph{Note:} If the chosen key method is later defined as inline, the
28959 vtable is still emitted in every translation unit that defines it.
28960 Make sure that any inline virtuals are declared inline in the class
28961 body, even if they are not defined there.
28963 @cindex @code{type_info}
28965 @item @code{type_info} objects
28966 C++ requires information about types to be written out in order to
28967 implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
28968 For polymorphic classes (classes with virtual functions), the @samp{type_info}
28969 object is written out along with the vtable so that @samp{dynamic_cast}
28970 can determine the dynamic type of a class object at run time. For all
28971 other types, we write out the @samp{type_info} object when it is used: when
28972 applying @samp{typeid} to an expression, throwing an object, or
28973 referring to a type in a catch clause or exception specification.
28975 @item Template Instantiations
28976 Most everything in this section also applies to template instantiations,
28977 but there are other options as well.
28978 @xref{Template Instantiation,,Where's the Template?}.
28982 When used with GNU ld version 2.8 or later on an ELF system such as
28983 GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of
28984 these constructs will be discarded at link time. This is known as
28987 On targets that don't support COMDAT, but do support weak symbols, GCC
28988 uses them. This way one copy overrides all the others, but
28989 the unused copies still take up space in the executable.
28991 For targets that do not support either COMDAT or weak symbols,
28992 most entities with vague linkage are emitted as local symbols to
28993 avoid duplicate definition errors from the linker. This does not happen
28994 for local statics in inlines, however, as having multiple copies
28995 almost certainly breaks things.
28997 @xref{C++ Interface,,Declarations and Definitions in One Header}, for
28998 another way to control placement of these constructs.
29000 @node C++ Interface
29001 @section C++ Interface and Implementation Pragmas
29003 @cindex interface and implementation headers, C++
29004 @cindex C++ interface and implementation headers
29005 @cindex pragmas, interface and implementation
29007 @code{#pragma interface} and @code{#pragma implementation} provide the
29008 user with a way of explicitly directing the compiler to emit entities
29009 with vague linkage (and debugging information) in a particular
29012 @emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2
29013 by COMDAT support and the ``key method'' heuristic
29014 mentioned in @ref{Vague Linkage}. Using them can actually cause your
29015 program to grow due to unnecessary out-of-line copies of inline
29019 @kindex #pragma interface
29020 @item #pragma interface
29021 @itemx #pragma interface "@var{subdir}/@var{objects}.h"
29022 Use this directive in @emph{header files} that define object classes, to save
29023 space in most of the object files that use those classes. Normally,
29024 local copies of certain information (backup copies of inline member
29025 functions, debugging information, and the internal tables that implement
29026 virtual functions) must be kept in each object file that includes class
29027 definitions. You can use this pragma to avoid such duplication. When a
29028 header file containing @samp{#pragma interface} is included in a
29029 compilation, this auxiliary information is not generated (unless
29030 the main input source file itself uses @samp{#pragma implementation}).
29031 Instead, the object files contain references to be resolved at link
29034 The second form of this directive is useful for the case where you have
29035 multiple headers with the same name in different directories. If you
29036 use this form, you must specify the same string to @samp{#pragma
29039 @kindex #pragma implementation
29040 @item #pragma implementation
29041 @itemx #pragma implementation "@var{objects}.h"
29042 Use this pragma in a @emph{main input file}, when you want full output from
29043 included header files to be generated (and made globally visible). The
29044 included header file, in turn, should use @samp{#pragma interface}.
29045 Backup copies of inline member functions, debugging information, and the
29046 internal tables used to implement virtual functions are all generated in
29047 implementation files.
29049 @cindex implied @code{#pragma implementation}
29050 @cindex @code{#pragma implementation}, implied
29051 @cindex naming convention, implementation headers
29052 If you use @samp{#pragma implementation} with no argument, it applies to
29053 an include file with the same basename@footnote{A file's @dfn{basename}
29054 is the name stripped of all leading path information and of trailing
29055 suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source
29056 file. For example, in @file{allclass.cc}, giving just
29057 @samp{#pragma implementation}
29058 by itself is equivalent to @samp{#pragma implementation "allclass.h"}.
29060 Use the string argument if you want a single implementation file to
29061 include code from multiple header files. (You must also use
29062 @samp{#include} to include the header file; @samp{#pragma
29063 implementation} only specifies how to use the file---it doesn't actually
29066 There is no way to split up the contents of a single header file into
29067 multiple implementation files.
29070 @cindex inlining and C++ pragmas
29071 @cindex C++ pragmas, effect on inlining
29072 @cindex pragmas in C++, effect on inlining
29073 @samp{#pragma implementation} and @samp{#pragma interface} also have an
29074 effect on function inlining.
29076 If you define a class in a header file marked with @samp{#pragma
29077 interface}, the effect on an inline function defined in that class is
29078 similar to an explicit @code{extern} declaration---the compiler emits
29079 no code at all to define an independent version of the function. Its
29080 definition is used only for inlining with its callers.
29082 @opindex fno-implement-inlines
29083 Conversely, when you include the same header file in a main source file
29084 that declares it as @samp{#pragma implementation}, the compiler emits
29085 code for the function itself; this defines a version of the function
29086 that can be found via pointers (or by callers compiled without
29087 inlining). If all calls to the function can be inlined, you can avoid
29088 emitting the function by compiling with @option{-fno-implement-inlines}.
29089 If any calls are not inlined, you will get linker errors.
29091 @node Template Instantiation
29092 @section Where's the Template?
29093 @cindex template instantiation
29095 C++ templates were the first language feature to require more
29096 intelligence from the environment than was traditionally found on a UNIX
29097 system. Somehow the compiler and linker have to make sure that each
29098 template instance occurs exactly once in the executable if it is needed,
29099 and not at all otherwise. There are two basic approaches to this
29100 problem, which are referred to as the Borland model and the Cfront model.
29103 @item Borland model
29104 Borland C++ solved the template instantiation problem by adding the code
29105 equivalent of common blocks to their linker; the compiler emits template
29106 instances in each translation unit that uses them, and the linker
29107 collapses them together. The advantage of this model is that the linker
29108 only has to consider the object files themselves; there is no external
29109 complexity to worry about. The disadvantage is that compilation time
29110 is increased because the template code is being compiled repeatedly.
29111 Code written for this model tends to include definitions of all
29112 templates in the header file, since they must be seen to be
29116 The AT&T C++ translator, Cfront, solved the template instantiation
29117 problem by creating the notion of a template repository, an
29118 automatically maintained place where template instances are stored. A
29119 more modern version of the repository works as follows: As individual
29120 object files are built, the compiler places any template definitions and
29121 instantiations encountered in the repository. At link time, the link
29122 wrapper adds in the objects in the repository and compiles any needed
29123 instances that were not previously emitted. The advantages of this
29124 model are more optimal compilation speed and the ability to use the
29125 system linker; to implement the Borland model a compiler vendor also
29126 needs to replace the linker. The disadvantages are vastly increased
29127 complexity, and thus potential for error; for some code this can be
29128 just as transparent, but in practice it can been very difficult to build
29129 multiple programs in one directory and one program in multiple
29130 directories. Code written for this model tends to separate definitions
29131 of non-inline member templates into a separate file, which should be
29132 compiled separately.
29135 G++ implements the Borland model on targets where the linker supports it,
29136 including ELF targets (such as GNU/Linux), macOS and Microsoft Windows.
29137 Otherwise G++ implements neither automatic model.
29139 You have the following options for dealing with template instantiations:
29143 Do nothing. Code written for the Borland model works fine, but
29144 each translation unit contains instances of each of the templates it
29145 uses. The duplicate instances will be discarded by the linker, but in
29146 a large program, this can lead to an unacceptable amount of code
29147 duplication in object files or shared libraries.
29149 Duplicate instances of a template can be avoided by defining an explicit
29150 instantiation in one object file, and preventing the compiler from doing
29151 implicit instantiations in any other object files by using an explicit
29152 instantiation declaration, using the @code{extern template} syntax:
29155 extern template int max (int, int);
29158 This syntax is defined in the C++ 2011 standard, but has been supported by
29159 G++ and other compilers since well before 2011.
29161 Explicit instantiations can be used for the largest or most frequently
29162 duplicated instances, without having to know exactly which other instances
29163 are used in the rest of the program. You can scatter the explicit
29164 instantiations throughout your program, perhaps putting them in the
29165 translation units where the instances are used or the translation units
29166 that define the templates themselves; you can put all of the explicit
29167 instantiations you need into one big file; or you can create small files
29174 template class Foo<int>;
29175 template ostream& operator <<
29176 (ostream&, const Foo<int>&);
29180 for each of the instances you need, and create a template instantiation
29181 library from those.
29183 This is the simplest option, but also offers flexibility and
29184 fine-grained control when necessary. It is also the most portable
29185 alternative and programs using this approach will work with most modern
29188 @opindex fno-implicit-templates
29190 Compile your code with @option{-fno-implicit-templates} to disable the
29191 implicit generation of template instances, and explicitly instantiate
29192 all the ones you use. This approach requires more knowledge of exactly
29193 which instances you need than do the others, but it's less
29194 mysterious and allows greater control if you want to ensure that only
29195 the intended instances are used.
29197 If you are using Cfront-model code, you can probably get away with not
29198 using @option{-fno-implicit-templates} when compiling files that don't
29199 @samp{#include} the member template definitions.
29201 If you use one big file to do the instantiations, you may want to
29202 compile it without @option{-fno-implicit-templates} so you get all of the
29203 instances required by your explicit instantiations (but not by any
29204 other files) without having to specify them as well.
29206 In addition to forward declaration of explicit instantiations
29207 (with @code{extern}), G++ has extended the template instantiation
29208 syntax to support instantiation of the compiler support data for a
29209 template class (i.e.@: the vtable) without instantiating any of its
29210 members (with @code{inline}), and instantiation of only the static data
29211 members of a template class, without the support data or member
29212 functions (with @code{static}):
29215 inline template class Foo<int>;
29216 static template class Foo<int>;
29220 @node Bound member functions
29221 @section Extracting the Function Pointer from a Bound Pointer to Member Function
29223 @cindex pointer to member function
29224 @cindex bound pointer to member function
29226 In C++, pointer to member functions (PMFs) are implemented using a wide
29227 pointer of sorts to handle all the possible call mechanisms; the PMF
29228 needs to store information about how to adjust the @samp{this} pointer,
29229 and if the function pointed to is virtual, where to find the vtable, and
29230 where in the vtable to look for the member function. If you are using
29231 PMFs in an inner loop, you should really reconsider that decision. If
29232 that is not an option, you can extract the pointer to the function that
29233 would be called for a given object/PMF pair and call it directly inside
29234 the inner loop, to save a bit of time.
29236 Note that you still pay the penalty for the call through a
29237 function pointer; on most modern architectures, such a call defeats the
29238 branch prediction features of the CPU@. This is also true of normal
29239 virtual function calls.
29241 The syntax for this extension is
29245 extern int (A::*fp)();
29246 typedef int (*fptr)(A *);
29248 fptr p = (fptr)(a.*fp);
29251 For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}),
29252 no object is needed to obtain the address of the function. They can be
29253 converted to function pointers directly:
29256 fptr p1 = (fptr)(&A::foo);
29259 @opindex Wno-pmf-conversions
29260 You must specify @option{-Wno-pmf-conversions} to use this extension.
29262 @node C++ Attributes
29263 @section C++-Specific Variable, Function, and Type Attributes
29265 Some attributes only make sense for C++ programs.
29268 @cindex @code{abi_tag} function attribute
29269 @cindex @code{abi_tag} variable attribute
29270 @cindex @code{abi_tag} type attribute
29271 @item abi_tag ("@var{tag}", ...)
29272 The @code{abi_tag} attribute can be applied to a function, variable, or class
29273 declaration. It modifies the mangled name of the entity to
29274 incorporate the tag name, in order to distinguish the function or
29275 class from an earlier version with a different ABI; perhaps the class
29276 has changed size, or the function has a different return type that is
29277 not encoded in the mangled name.
29279 The attribute can also be applied to an inline namespace, but does not
29280 affect the mangled name of the namespace; in this case it is only used
29281 for @option{-Wabi-tag} warnings and automatic tagging of functions and
29282 variables. Tagging inline namespaces is generally preferable to
29283 tagging individual declarations, but the latter is sometimes
29284 necessary, such as when only certain members of a class need to be
29287 The argument can be a list of strings of arbitrary length. The
29288 strings are sorted on output, so the order of the list is
29291 A redeclaration of an entity must not add new ABI tags,
29292 since doing so would change the mangled name.
29294 The ABI tags apply to a name, so all instantiations and
29295 specializations of a template have the same tags. The attribute will
29296 be ignored if applied to an explicit specialization or instantiation.
29298 The @option{-Wabi-tag} flag enables a warning about a class which does
29299 not have all the ABI tags used by its subobjects and virtual functions; for users with code
29300 that needs to coexist with an earlier ABI, using this option can help
29301 to find all affected types that need to be tagged.
29303 When a type involving an ABI tag is used as the type of a variable or
29304 return type of a function where that tag is not already present in the
29305 signature of the function, the tag is automatically applied to the
29306 variable or function. @option{-Wabi-tag} also warns about this
29307 situation; this warning can be avoided by explicitly tagging the
29308 variable or function or moving it into a tagged inline namespace.
29310 @cindex @code{init_priority} variable attribute
29311 @item init_priority (@var{priority})
29313 In Standard C++, objects defined at namespace scope are guaranteed to be
29314 initialized in an order in strict accordance with that of their definitions
29315 @emph{in a given translation unit}. No guarantee is made for initializations
29316 across translation units. However, GNU C++ allows users to control the
29317 order of initialization of objects defined at namespace scope with the
29318 @code{init_priority} attribute by specifying a relative @var{priority},
29319 a constant integral expression currently bounded between 101 and 65535
29320 inclusive. Lower numbers indicate a higher priority.
29322 In the following example, @code{A} would normally be created before
29323 @code{B}, but the @code{init_priority} attribute reverses that order:
29326 Some_Class A __attribute__ ((init_priority (2000)));
29327 Some_Class B __attribute__ ((init_priority (543)));
29331 Note that the particular values of @var{priority} do not matter; only their
29334 @cindex @code{no_dangling} type attribute
29335 @cindex @code{no_dangling} function attribute
29338 This attribute can be applied on a class type, function, or member
29339 function. Dangling references to classes marked with this attribute
29340 will have the @option{-Wdangling-reference} diagnostic suppressed; so
29341 will references returned from the @code{gnu::no_dangling}-marked
29342 functions. For example:
29345 class [[gnu::no_dangling]] S @{ @dots{} @};
29353 [[gnu::no_dangling]] int &foo() @{ return *p; @}
29356 [[gnu::no_dangling]] const int &
29363 This attribute takes an optional argument, which must be an expression that
29364 evaluates to true or false:
29367 template <typename T>
29368 struct [[gnu::no_dangling(std::is_reference_v<T>)]] S @{
29376 template <typename T>
29377 [[gnu::no_dangling(std::is_lvalue_reference_v<T>)]]
29378 decltype(auto) foo(T&& t) @{
29383 @cindex @code{warn_unused} type attribute
29386 For C++ types with non-trivial constructors and/or destructors it is
29387 impossible for the compiler to determine whether a variable of this
29388 type is truly unused if it is not referenced. This type attribute
29389 informs the compiler that variables of this type should be warned
29390 about if they appear to be unused, just like variables of fundamental
29393 This attribute is appropriate for types which just represent a value,
29394 such as @code{std::string}; it is not appropriate for types which
29395 control a resource, such as @code{std::lock_guard}.
29397 This attribute is also accepted in C, but it is unnecessary because C
29398 does not have constructors or destructors.
29400 @cindex @code{cold} type attribute
29403 In addition to functions and labels, GNU C++ allows the @code{cold}
29404 attribute to be used on C++ classes, structs, or unions. Applying
29405 the @code{cold} attribute on a type has the effect of treating every
29406 member function of the type, including implicit special member
29407 functions, as cold. If a member function is marked with the
29408 @code{hot} function attribute, the @code{hot} attribute takes
29409 precedence and the @code{cold} attribute is not propagated.
29411 For the effects of the @code{cold} attribute on functions, see
29412 @ref{Common Function Attributes}.
29414 @cindex @code{hot} type attribute
29417 In addition to functions and labels, GNU C++ allows the @code{hot}
29418 attribute to be used on C++ classes, structs, or unions. Applying
29419 the @code{hot} attribute on a type has the effect of treating every
29420 member function of the type, including implicit special member
29421 functions, as hot. If a member function is marked with the
29422 @code{cold} function attribute, the @code{cold} attribute takes
29423 precedence and the @code{hot} attribute is not propagated.
29425 For the effects of the @code{hot} attribute on functions, see
29426 @ref{Common Function Attributes}.
29430 @node Function Multiversioning
29431 @section Function Multiversioning
29432 @cindex function versions
29434 With the GNU C++ front end, for x86 targets, you may specify multiple
29435 versions of a function, where each function is specialized for a
29436 specific target feature. At runtime, the appropriate version of the
29437 function is automatically executed depending on the characteristics of
29438 the execution platform. Here is an example.
29441 __attribute__ ((target ("default")))
29444 // The default version of foo.
29448 __attribute__ ((target ("sse4.2")))
29451 // foo version for SSE4.2
29455 __attribute__ ((target ("arch=atom")))
29458 // foo version for the Intel ATOM processor
29462 __attribute__ ((target ("arch=amdfam10")))
29465 // foo version for the AMD Family 0x10 processors.
29472 assert ((*p) () == foo ());
29477 In the above example, four versions of function foo are created. The
29478 first version of foo with the target attribute "default" is the default
29479 version. This version gets executed when no other target specific
29480 version qualifies for execution on a particular platform. A new version
29481 of foo is created by using the same function signature but with a
29482 different target string. Function foo is called or a pointer to it is
29483 taken just like a regular function. GCC takes care of doing the
29484 dispatching to call the right version at runtime. Refer to the
29485 @uref{https://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
29486 Function Multiversioning} for more details.
29489 @section Type Traits
29491 The C++ front end implements syntactic extensions that allow
29492 compile-time determination of
29493 various characteristics of a type (or of a
29496 @defbuiltin{bool __has_nothrow_assign (@var{type})}
29497 If @var{type} is @code{const}-qualified or is a reference type then
29498 the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)}
29499 is @code{true} then the trait is @code{true}, else if @var{type} is
29500 a cv-qualified class or union type with copy assignment operators that are
29501 known not to throw an exception then the trait is @code{true}, else it is
29503 Requires: @var{type} shall be a complete type, (possibly cv-qualified)
29504 @code{void}, or an array of unknown bound.
29507 @defbuiltin{bool __has_nothrow_copy (@var{type})}
29508 If @code{__has_trivial_copy (type)} is @code{true} then the trait is
29509 @code{true}, else if @var{type} is a cv-qualified class or union type
29510 with copy constructors that are known not to throw an exception then
29511 the trait is @code{true}, else it is @code{false}.
29512 Requires: @var{type} shall be a complete type, (possibly cv-qualified)
29513 @code{void}, or an array of unknown bound.
29516 @defbuiltin{bool __has_nothrow_constructor (@var{type})}
29517 If @code{__has_trivial_constructor (type)} is @code{true} then the trait
29518 is @code{true}, else if @var{type} is a cv class or union type (or array
29519 thereof) with a default constructor that is known not to throw an
29520 exception then the trait is @code{true}, else it is @code{false}.
29521 Requires: @var{type} shall be a complete type, (possibly cv-qualified)
29522 @code{void}, or an array of unknown bound.
29525 @defbuiltin{bool __has_trivial_assign (@var{type})}
29526 If @var{type} is @code{const}- qualified or is a reference type then
29527 the trait is @code{false}. Otherwise if @code{__is_trivial (type)} is
29528 @code{true} then the trait is @code{true}, else if @var{type} is
29529 a cv-qualified class or union type with a trivial copy assignment
29530 ([class.copy]) then the trait is @code{true}, else it is @code{false}.
29531 Requires: @var{type} shall be a complete type, (possibly cv-qualified)
29532 @code{void}, or an array of unknown bound.
29535 @defbuiltin{bool __has_trivial_copy (@var{type})}
29536 If @code{__is_trivial (type)} is @code{true} or @var{type} is a reference
29537 type then the trait is @code{true}, else if @var{type} is a cv class
29538 or union type with a trivial copy constructor ([class.copy]) then the trait
29539 is @code{true}, else it is @code{false}. Requires: @var{type} shall be
29540 a complete type, (possibly cv-qualified) @code{void}, or an array of unknown
29544 @defbuiltin{bool __has_trivial_constructor (@var{type})}
29545 If @code{__is_trivial (type)} is @code{true} then the trait is @code{true},
29546 else if @var{type} is a cv-qualified class or union type (or array thereof)
29547 with a trivial default constructor ([class.ctor]) then the trait is @code{true},
29548 else it is @code{false}.
29549 Requires: @var{type} shall be a complete type, (possibly cv-qualified)
29550 @code{void}, or an array of unknown bound.
29553 @defbuiltin{bool __has_trivial_destructor (@var{type})}
29554 If @code{__is_trivial (type)} is @code{true} or @var{type} is a reference type
29555 then the trait is @code{true}, else if @var{type} is a cv class or union
29556 type (or array thereof) with a trivial destructor ([class.dtor]) then
29557 the trait is @code{true}, else it is @code{false}.
29558 Requires: @var{type} shall be a complete type, (possibly cv-qualified)
29559 @code{void}, or an array of unknown bound.
29562 @defbuiltin{bool __has_virtual_destructor (@var{type})}
29563 If @var{type} is a class type with a virtual destructor
29564 ([class.dtor]) then the trait is @code{true}, else it is @code{false}.
29565 Requires: If @var{type} is a non-union class type, it shall be a complete type.
29568 @defbuiltin{bool __is_abstract (@var{type})}
29569 If @var{type} is an abstract class ([class.abstract]) then the trait
29570 is @code{true}, else it is @code{false}.
29571 Requires: If @var{type} is a non-union class type, it shall be a complete type.
29574 @defbuiltin{bool __is_aggregate (@var{type})}
29575 If @var{type} is an aggregate type ([dcl.init.aggr]) the trait is
29576 @code{true}, else it is @code{false}.
29577 Requires: If @var{type} is a class type, it shall be a complete type.
29580 @defbuiltin{bool __is_base_of (@var{base_type}, @var{derived_type})}
29581 If @var{base_type} is a base class of @var{derived_type}
29582 ([class.derived]) then the trait is @code{true}, otherwise it is @code{false}.
29583 Top-level cv-qualifications of @var{base_type} and
29584 @var{derived_type} are ignored. For the purposes of this trait, a
29585 class type is considered is own base.
29586 Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)}
29587 are @code{true} and @var{base_type} and @var{derived_type} are not the same
29588 type (disregarding cv-qualifiers), @var{derived_type} shall be a complete
29589 type. A diagnostic is produced if this requirement is not met.
29592 @defbuiltin{bool __is_class (@var{type})}
29593 If @var{type} is a cv-qualified class type, and not a union type
29594 ([basic.compound]) the trait is @code{true}, else it is @code{false}.
29597 @c FIXME Commented out for GCC 13, discuss user interface for GCC 14.
29598 @c @defbuiltin{bool __is_deducible (@var{template}, @var{type})}
29599 @c If template arguments for @code{template} can be deduced from
29600 @c @code{type} or obtained from default template arguments.
29603 @defbuiltin{bool __is_empty (@var{type})}
29604 If @code{__is_class (type)} is @code{false} then the trait is @code{false}.
29605 Otherwise @var{type} is considered empty if and only if: @var{type}
29606 has no non-static data members, or all non-static data members, if
29607 any, are bit-fields of length 0, and @var{type} has no virtual
29608 members, and @var{type} has no virtual base classes, and @var{type}
29609 has no base classes @var{base_type} for which
29610 @code{__is_empty (base_type)} is @code{false}.
29611 Requires: If @var{type} is a non-union class type, it shall be a complete type.
29614 @defbuiltin{bool __is_enum (@var{type})}
29615 If @var{type} is a cv enumeration type ([basic.compound]) the trait is
29616 @code{true}, else it is @code{false}.
29619 @defbuiltin{bool __is_final (@var{type})}
29620 If @var{type} is a class or union type marked @code{final}, then the trait
29621 is @code{true}, else it is @code{false}.
29622 Requires: If @var{type} is a class type, it shall be a complete type.
29625 @defbuiltin{bool __is_literal_type (@var{type})}
29626 If @var{type} is a literal type ([basic.types]) the trait is
29627 @code{true}, else it is @code{false}.
29628 Requires: @var{type} shall be a complete type, (possibly cv-qualified)
29629 @code{void}, or an array of unknown bound.
29632 @defbuiltin{bool __is_pod (@var{type})}
29633 If @var{type} is a cv POD type ([basic.types]) then the trait is @code{true},
29634 else it is @code{false}.
29635 Requires: @var{type} shall be a complete type, (possibly cv-qualified)
29636 @code{void}, or an array of unknown bound.
29639 @defbuiltin{bool __is_polymorphic (@var{type})}
29640 If @var{type} is a polymorphic class ([class.virtual]) then the trait
29641 is @code{true}, else it is @code{false}.
29642 Requires: If @var{type} is a non-union class type, it shall be a complete type.
29645 @defbuiltin{bool __is_standard_layout (@var{type})}
29646 If @var{type} is a standard-layout type ([basic.types]) the trait is
29647 @code{true}, else it is @code{false}.
29648 Requires: @var{type} shall be a complete type, an array of complete types,
29649 or (possibly cv-qualified) @code{void}.
29652 @defbuiltin{bool __is_trivial (@var{type})}
29653 If @var{type} is a trivial type ([basic.types]) the trait is
29654 @code{true}, else it is @code{false}.
29655 Requires: @var{type} shall be a complete type, an array of complete types,
29656 or (possibly cv-qualified) @code{void}.
29659 @defbuiltin{bool __is_union (@var{type})}
29660 If @var{type} is a cv union type ([basic.compound]) the trait is
29661 @code{true}, else it is @code{false}.
29664 @defbuiltin{bool __underlying_type (@var{type})}
29665 The underlying type of @var{type}.
29666 Requires: @var{type} shall be an enumeration type ([dcl.enum]).
29669 @defbuiltin{bool __integer_pack (@var{length})}
29670 When used as the pattern of a pack expansion within a template
29671 definition, expands to a template argument pack containing integers
29672 from @code{0} to @code{@var{length}-1}. This is provided for
29673 efficient implementation of @code{std::make_integer_sequence}.
29678 @section C++ Concepts
29680 C++ concepts provide much-improved support for generic programming. In
29681 particular, they allow the specification of constraints on template arguments.
29682 The constraints are used to extend the usual overloading and partial
29683 specialization capabilities of the language, allowing generic data structures
29684 and algorithms to be ``refined'' based on their properties rather than their
29687 The following keywords are reserved for concepts.
29692 States an expression as an assumption, and if possible, verifies that the
29693 assumption is valid. For example, @code{assume(n > 0)}.
29697 Introduces an axiom definition. Axioms introduce requirements on values.
29701 Introduces a universally quantified object in an axiom. For example,
29702 @code{forall (int n) n + 0 == n}.
29706 Introduces a concept definition. Concepts are sets of syntactic and semantic
29707 requirements on types and their values.
29711 Introduces constraints on template arguments or requirements for a member
29712 function of a class template.
29715 The front end also exposes a number of internal mechanism that can be used
29716 to simplify the writing of type traits. Note that some of these traits are
29717 likely to be removed in the future.
29719 @defbuiltin{bool __is_same (@var{type1}, @var{type2})}
29720 A binary type trait: @code{true} whenever the @var{type1} and
29721 @var{type2} refer to the same type.
29725 @node Deprecated Features
29726 @section Deprecated Features
29728 In the past, the GNU C++ compiler was extended to experiment with new
29729 features, at a time when the C++ language was still evolving. Now that
29730 the C++ standard is complete, some of those features are superseded by
29731 superior alternatives. Using the old features might cause a warning in
29732 some cases that the feature will be dropped in the future. In other
29733 cases, the feature might be gone already.
29735 G++ allows a virtual function returning @samp{void *} to be overridden
29736 by one returning a different pointer type. This extension to the
29737 covariant return type rules is now deprecated and will be removed from a
29740 The use of default arguments in function pointers, function typedefs
29741 and other places where they are not permitted by the standard is
29742 deprecated and will be removed from a future version of G++.
29744 G++ allows floating-point literals to appear in integral constant expressions,
29745 e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} }
29746 This extension is deprecated and will be removed from a future version.
29748 G++ allows static data members of const floating-point type to be declared
29749 with an initializer in a class definition. The standard only allows
29750 initializers for static members of const integral types and const
29751 enumeration types so this extension has been deprecated and will be removed
29752 from a future version.
29754 G++ allows attributes to follow a parenthesized direct initializer,
29755 e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension
29756 has been ignored since G++ 3.3 and is deprecated.
29758 G++ allows anonymous structs and unions to have members that are not
29759 public non-static data members (i.e.@: fields). These extensions are
29762 @node Backwards Compatibility
29763 @section Backwards Compatibility
29764 @cindex Backwards Compatibility
29765 @cindex ARM [Annotated C++ Reference Manual]
29767 Now that there is a definitive ISO standard C++, G++ has a specification
29768 to adhere to. The C++ language evolved over time, and features that
29769 used to be acceptable in previous drafts of the standard, such as the ARM
29770 [Annotated C++ Reference Manual], are no longer accepted. In order to allow
29771 compilation of C++ written to such drafts, G++ contains some backwards
29772 compatibilities. @emph{All such backwards compatibility features are
29773 liable to disappear in future versions of G++.} They should be considered
29774 deprecated. @xref{Deprecated Features}.
29778 @item Implicit C language
29779 Old C system header files did not contain an @code{extern "C" @{@dots{}@}}
29780 scope to set the language. On such systems, all system header files are
29781 implicitly scoped inside a C language scope. Such headers must
29782 correctly prototype function argument types, there is no leeway for
29783 @code{()} to indicate an unspecified set of arguments.
29787 @c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd
29788 @c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr