1c Copyright (C) 1988-2020 Free Software Foundation, Inc. 2 3@c This is part of the GCC manual. 4@c For copying conditions, see the file gcc.texi. 5 6@node C Extensions 7@chapter Extensions to the C Language Family 8@cindex extensions, C language 9@cindex C language extensions 10 11@opindex pedantic 12GNU C provides several language features not found in ISO standard C@. 13(The @option{-pedantic} option directs GCC to print a warning message if 14any of these features is used.) To test for the availability of these 15features in conditional compilation, check for a predefined macro 16@code{__GNUC__}, which is always defined under GCC@. 17 18These extensions are available in C and Objective-C@. Most of them are 19also available in C++. @xref{C++ Extensions,,Extensions to the 20C++ Language}, for extensions that apply @emph{only} to C++. 21 22Some features that are in ISO C99 but not C90 or C++ are also, as 23extensions, accepted by GCC in C90 mode and in C++. 24 25@menu 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 54 or arrays as values. 55* Designated Inits:: Labeling elements of initializers. 56* Case Ranges:: `case 1 ... 9' and such. 57* Cast to Union:: Casting to union type from any member of the union. 58* Mixed Declarations:: Mixing declarations and code. 59* Function Attributes:: Declaring that functions have no side effects, 60 or that they can never return. 61* Variable Attributes:: Specifying attributes of variables. 62* Type Attributes:: Specifying attributes of types. 63* Label Attributes:: Specifying attributes on labels. 64* Enumerator Attributes:: Specifying attributes on enumerators. 65* Statement Attributes:: Specifying attributes on statements. 66* Attribute Syntax:: Formal syntax for attributes. 67* Function Prototypes:: Prototype declarations and old-style definitions. 68* C++ Comments:: C++ comments are recognized. 69* Dollar Signs:: Dollar sign is allowed in identifiers. 70* Character Escapes:: @samp{\e} stands for the character @key{ESC}. 71* Alignment:: Determining the alignment of a function, type or variable. 72* Inline:: Defining inline functions (as fast as macros). 73* Volatiles:: What constitutes an access to a volatile object. 74* Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler. 75* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. 76* Incomplete Enums:: @code{enum foo;}, with details to follow. 77* Function Names:: Printable strings which are the name of the current 78 function. 79* Return Address:: Getting the return or frame address of a function. 80* Vector Extensions:: Using vector instructions through built-in functions. 81* Offsetof:: Special syntax for implementing @code{offsetof}. 82* __sync Builtins:: Legacy built-in functions for atomic memory access. 83* __atomic Builtins:: Atomic built-in functions with memory model. 84* Integer Overflow Builtins:: Built-in functions to perform arithmetics and 85 arithmetic overflow checking. 86* x86 specific memory model extensions for transactional memory:: x86 memory models. 87* Object Size Checking:: Built-in functions for limited buffer overflow 88 checking. 89* Other Builtins:: Other built-in functions. 90* Target Builtins:: Built-in functions specific to particular targets. 91* Target Format Checks:: Format checks specific to particular targets. 92* Pragmas:: Pragmas accepted by GCC. 93* Unnamed Fields:: Unnamed struct/union fields within structs/unions. 94* Thread-Local:: Per-thread variables. 95* Binary constants:: Binary constants using the @samp{0b} prefix. 96@end menu 97 98@node Statement Exprs 99@section Statements and Declarations in Expressions 100@cindex statements inside expressions 101@cindex declarations inside expressions 102@cindex expressions containing statements 103@cindex macros, statements in expressions 104 105@c the above section title wrapped and causes an underfull hbox.. i 106@c changed it from "within" to "in". --mew 4feb93 107A compound statement enclosed in parentheses may appear as an expression 108in GNU C@. This allows you to use loops, switches, and local variables 109within an expression. 110 111Recall that a compound statement is a sequence of statements surrounded 112by braces; in this construct, parentheses go around the braces. For 113example: 114 115@smallexample 116(@{ int y = foo (); int z; 117 if (y > 0) z = y; 118 else z = - y; 119 z; @}) 120@end smallexample 121 122@noindent 123is a valid (though slightly more complex than necessary) expression 124for the absolute value of @code{foo ()}. 125 126The last thing in the compound statement should be an expression 127followed by a semicolon; the value of this subexpression serves as the 128value of the entire construct. (If you use some other kind of statement 129last within the braces, the construct has type @code{void}, and thus 130effectively no value.) 131 132This feature is especially useful in making macro definitions ``safe'' (so 133that they evaluate each operand exactly once). For example, the 134``maximum'' function is commonly defined as a macro in standard C as 135follows: 136 137@smallexample 138#define max(a,b) ((a) > (b) ? (a) : (b)) 139@end smallexample 140 141@noindent 142@cindex side effects, macro argument 143But this definition computes either @var{a} or @var{b} twice, with bad 144results if the operand has side effects. In GNU C, if you know the 145type of the operands (here taken as @code{int}), you can avoid this 146problem by defining the macro as follows: 147 148@smallexample 149#define maxint(a,b) \ 150 (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) 151@end smallexample 152 153Note that introducing variable declarations (as we do in @code{maxint}) can 154cause variable shadowing, so while this example using the @code{max} macro 155produces correct results: 156@smallexample 157int _a = 1, _b = 2, c; 158c = max (_a, _b); 159@end smallexample 160@noindent 161this example using maxint will not: 162@smallexample 163int _a = 1, _b = 2, c; 164c = maxint (_a, _b); 165@end smallexample 166 167This problem may for instance occur when we use this pattern recursively, like 168so: 169 170@smallexample 171#define maxint3(a, b, c) \ 172 (@{int _a = (a), _b = (b), _c = (c); maxint (maxint (_a, _b), _c); @}) 173@end smallexample 174 175Embedded statements are not allowed in constant expressions, such as 176the value of an enumeration constant, the width of a bit-field, or 177the initial value of a static variable. 178 179If you don't know the type of the operand, you can still do this, but you 180must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}). 181 182In G++, the result value of a statement expression undergoes array and 183function pointer decay, and is returned by value to the enclosing 184expression. For instance, if @code{A} is a class, then 185 186@smallexample 187 A a; 188 189 (@{a;@}).Foo () 190@end smallexample 191 192@noindent 193constructs a temporary @code{A} object to hold the result of the 194statement expression, and that is used to invoke @code{Foo}. 195Therefore the @code{this} pointer observed by @code{Foo} is not the 196address of @code{a}. 197 198In a statement expression, any temporaries created within a statement 199are destroyed at that statement's end. This makes statement 200expressions inside macros slightly different from function calls. In 201the latter case temporaries introduced during argument evaluation are 202destroyed at the end of the statement that includes the function 203call. In the statement expression case they are destroyed during 204the statement expression. For instance, 205 206@smallexample 207#define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) 208template<typename T> T function(T a) @{ T b = a; return b + 3; @} 209 210void foo () 211@{ 212 macro (X ()); 213 function (X ()); 214@} 215@end smallexample 216 217@noindent 218has different places where temporaries are destroyed. For the 219@code{macro} case, the temporary @code{X} is destroyed just after 220the initialization of @code{b}. In the @code{function} case that 221temporary is destroyed when the function returns. 222 223These considerations mean that it is probably a bad idea to use 224statement expressions of this form in header files that are designed to 225work with C++. (Note that some versions of the GNU C Library contained 226header files using statement expressions that lead to precisely this 227bug.) 228 229Jumping into a statement expression with @code{goto} or using a 230@code{switch} statement outside the statement expression with a 231@code{case} or @code{default} label inside the statement expression is 232not permitted. Jumping into a statement expression with a computed 233@code{goto} (@pxref{Labels as Values}) has undefined behavior. 234Jumping out of a statement expression is permitted, but if the 235statement expression is part of a larger expression then it is 236unspecified which other subexpressions of that expression have been 237evaluated except where the language definition requires certain 238subexpressions to be evaluated before or after the statement 239expression. A @code{break} or @code{continue} statement inside of 240a statement expression used in @code{while}, @code{do} or @code{for} 241loop or @code{switch} statement condition 242or @code{for} statement init or increment expressions jumps to an 243outer loop or @code{switch} statement if any (otherwise it is an error), 244rather than to the loop or @code{switch} statement in whose condition 245or init or increment expression it appears. 246In any case, as with a function call, the evaluation of a 247statement expression is not interleaved with the evaluation of other 248parts of the containing expression. For example, 249 250@smallexample 251 foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); 252@end smallexample 253 254@noindent 255calls @code{foo} and @code{bar1} and does not call @code{baz} but 256may or may not call @code{bar2}. If @code{bar2} is called, it is 257called after @code{foo} and before @code{bar1}. 258 259@node Local Labels 260@section Locally Declared Labels 261@cindex local labels 262@cindex macros, local labels 263 264GCC allows you to declare @dfn{local labels} in any nested block 265scope. A local label is just like an ordinary label, but you can 266only reference it (with a @code{goto} statement, or by taking its 267address) within the block in which it is declared. 268 269A local label declaration looks like this: 270 271@smallexample 272__label__ @var{label}; 273@end smallexample 274 275@noindent 276or 277 278@smallexample 279__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; 280@end smallexample 281 282Local label declarations must come at the beginning of the block, 283before any ordinary declarations or statements. 284 285The label declaration defines the label @emph{name}, but does not define 286the label itself. You must do this in the usual way, with 287@code{@var{label}:}, within the statements of the statement expression. 288 289The local label feature is useful for complex macros. If a macro 290contains nested loops, a @code{goto} can be useful for breaking out of 291them. However, an ordinary label whose scope is the whole function 292cannot be used: if the macro can be expanded several times in one 293function, the label is multiply defined in that function. A 294local label avoids this problem. For example: 295 296@smallexample 297#define SEARCH(value, array, target) \ 298do @{ \ 299 __label__ found; \ 300 typeof (target) _SEARCH_target = (target); \ 301 typeof (*(array)) *_SEARCH_array = (array); \ 302 int i, j; \ 303 int value; \ 304 for (i = 0; i < max; i++) \ 305 for (j = 0; j < max; j++) \ 306 if (_SEARCH_array[i][j] == _SEARCH_target) \ 307 @{ (value) = i; goto found; @} \ 308 (value) = -1; \ 309 found:; \ 310@} while (0) 311@end smallexample 312 313This could also be written using a statement expression: 314 315@smallexample 316#define SEARCH(array, target) \ 317(@{ \ 318 __label__ found; \ 319 typeof (target) _SEARCH_target = (target); \ 320 typeof (*(array)) *_SEARCH_array = (array); \ 321 int i, j; \ 322 int value; \ 323 for (i = 0; i < max; i++) \ 324 for (j = 0; j < max; j++) \ 325 if (_SEARCH_array[i][j] == _SEARCH_target) \ 326 @{ value = i; goto found; @} \ 327 value = -1; \ 328 found: \ 329 value; \ 330@}) 331@end smallexample 332 333Local label declarations also make the labels they declare visible to 334nested functions, if there are any. @xref{Nested Functions}, for details. 335 336@node Labels as Values 337@section Labels as Values 338@cindex labels as values 339@cindex computed gotos 340@cindex goto with computed label 341@cindex address of a label 342 343You can get the address of a label defined in the current function 344(or a containing function) with the unary operator @samp{&&}. The 345value has type @code{void *}. This value is a constant and can be used 346wherever a constant of that type is valid. For example: 347 348@smallexample 349void *ptr; 350/* @r{@dots{}} */ 351ptr = &&foo; 352@end smallexample 353 354To use these values, you need to be able to jump to one. This is done 355with the computed goto statement@footnote{The analogous feature in 356Fortran is called an assigned goto, but that name seems inappropriate in 357C, where one can do more than simply store label addresses in label 358variables.}, @code{goto *@var{exp};}. For example, 359 360@smallexample 361goto *ptr; 362@end smallexample 363 364@noindent 365Any expression of type @code{void *} is allowed. 366 367One way of using these constants is in initializing a static array that 368serves as a jump table: 369 370@smallexample 371static void *array[] = @{ &&foo, &&bar, &&hack @}; 372@end smallexample 373 374@noindent 375Then you can select a label with indexing, like this: 376 377@smallexample 378goto *array[i]; 379@end smallexample 380 381@noindent 382Note that this does not check whether the subscript is in bounds---array 383indexing in C never does that. 384 385Such an array of label values serves a purpose much like that of the 386@code{switch} statement. The @code{switch} statement is cleaner, so 387use that rather than an array unless the problem does not fit a 388@code{switch} statement very well. 389 390Another use of label values is in an interpreter for threaded code. 391The labels within the interpreter function can be stored in the 392threaded code for super-fast dispatching. 393 394You may not use this mechanism to jump to code in a different function. 395If you do that, totally unpredictable things happen. The best way to 396avoid this is to store the label address only in automatic variables and 397never pass it as an argument. 398 399An alternate way to write the above example is 400 401@smallexample 402static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, 403 &&hack - &&foo @}; 404goto *(&&foo + array[i]); 405@end smallexample 406 407@noindent 408This is more friendly to code living in shared libraries, as it reduces 409the number of dynamic relocations that are needed, and by consequence, 410allows the data to be read-only. 411This alternative with label differences is not supported for the AVR target, 412please use the first approach for AVR programs. 413 414The @code{&&foo} expressions for the same label might have different 415values if the containing function is inlined or cloned. If a program 416relies on them being always the same, 417@code{__attribute__((__noinline__,__noclone__))} should be used to 418prevent inlining and cloning. If @code{&&foo} is used in a static 419variable initializer, inlining and cloning is forbidden. 420 421@node Nested Functions 422@section Nested Functions 423@cindex nested functions 424@cindex downward funargs 425@cindex thunks 426 427A @dfn{nested function} is a function defined inside another function. 428Nested functions are supported as an extension in GNU C, but are not 429supported by GNU C++. 430 431The nested function's name is local to the block where it is defined. 432For example, here we define a nested function named @code{square}, and 433call it twice: 434 435@smallexample 436@group 437foo (double a, double b) 438@{ 439 double square (double z) @{ return z * z; @} 440 441 return square (a) + square (b); 442@} 443@end group 444@end smallexample 445 446The nested function can access all the variables of the containing 447function that are visible at the point of its definition. This is 448called @dfn{lexical scoping}. For example, here we show a nested 449function which uses an inherited variable named @code{offset}: 450 451@smallexample 452@group 453bar (int *array, int offset, int size) 454@{ 455 int access (int *array, int index) 456 @{ return array[index + offset]; @} 457 int i; 458 /* @r{@dots{}} */ 459 for (i = 0; i < size; i++) 460 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 461@} 462@end group 463@end smallexample 464 465Nested function definitions are permitted within functions in the places 466where variable definitions are allowed; that is, in any block, mixed 467with the other declarations and statements in the block. 468 469It is possible to call the nested function from outside the scope of its 470name by storing its address or passing the address to another function: 471 472@smallexample 473hack (int *array, int size) 474@{ 475 void store (int index, int value) 476 @{ array[index] = value; @} 477 478 intermediate (store, size); 479@} 480@end smallexample 481 482Here, the function @code{intermediate} receives the address of 483@code{store} as an argument. If @code{intermediate} calls @code{store}, 484the arguments given to @code{store} are used to store into @code{array}. 485But this technique works only so long as the containing function 486(@code{hack}, in this example) does not exit. 487 488If you try to call the nested function through its address after the 489containing function exits, all hell breaks loose. If you try 490to call it after a containing scope level exits, and if it refers 491to some of the variables that are no longer in scope, you may be lucky, 492but it's not wise to take the risk. If, however, the nested function 493does not refer to anything that has gone out of scope, you should be 494safe. 495 496GCC implements taking the address of a nested function using a technique 497called @dfn{trampolines}. This technique was described in 498@cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX 499C++ Conference Proceedings, October 17-21, 1988). 500 501A nested function can jump to a label inherited from a containing 502function, provided the label is explicitly declared in the containing 503function (@pxref{Local Labels}). Such a jump returns instantly to the 504containing function, exiting the nested function that did the 505@code{goto} and any intermediate functions as well. Here is an example: 506 507@smallexample 508@group 509bar (int *array, int offset, int size) 510@{ 511 __label__ failure; 512 int access (int *array, int index) 513 @{ 514 if (index > size) 515 goto failure; 516 return array[index + offset]; 517 @} 518 int i; 519 /* @r{@dots{}} */ 520 for (i = 0; i < size; i++) 521 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 522 /* @r{@dots{}} */ 523 return 0; 524 525 /* @r{Control comes here from @code{access} 526 if it detects an error.} */ 527 failure: 528 return -1; 529@} 530@end group 531@end smallexample 532 533A nested function always has no linkage. Declaring one with 534@code{extern} or @code{static} is erroneous. If you need to declare the nested function 535before its definition, use @code{auto} (which is otherwise meaningless 536for function declarations). 537 538@smallexample 539bar (int *array, int offset, int size) 540@{ 541 __label__ failure; 542 auto int access (int *, int); 543 /* @r{@dots{}} */ 544 int access (int *array, int index) 545 @{ 546 if (index > size) 547 goto failure; 548 return array[index + offset]; 549 @} 550 /* @r{@dots{}} */ 551@} 552@end smallexample 553 554@node Nonlocal Gotos 555@section Nonlocal Gotos 556@cindex nonlocal gotos 557 558GCC provides the built-in functions @code{__builtin_setjmp} and 559@code{__builtin_longjmp} which are similar to, but not interchangeable 560with, the C library functions @code{setjmp} and @code{longjmp}. 561The built-in versions are used internally by GCC's libraries 562to implement exception handling on some targets. You should use the 563standard C library functions declared in @code{<setjmp.h>} in user code 564instead of the builtins. 565 566The built-in versions of these functions use GCC's normal 567mechanisms to save and restore registers using the stack on function 568entry and exit. The jump buffer argument @var{buf} holds only the 569information needed to restore the stack frame, rather than the entire 570set of saved register values. 571 572An important caveat is that GCC arranges to save and restore only 573those registers known to the specific architecture variant being 574compiled for. This can make @code{__builtin_setjmp} and 575@code{__builtin_longjmp} more efficient than their library 576counterparts in some cases, but it can also cause incorrect and 577mysterious behavior when mixing with code that uses the full register 578set. 579 580You should declare the jump buffer argument @var{buf} to the 581built-in functions as: 582 583@smallexample 584#include <stdint.h> 585intptr_t @var{buf}[5]; 586@end smallexample 587 588@deftypefn {Built-in Function} {int} __builtin_setjmp (intptr_t *@var{buf}) 589This function saves the current stack context in @var{buf}. 590@code{__builtin_setjmp} returns 0 when returning directly, 591and 1 when returning from @code{__builtin_longjmp} using the same 592@var{buf}. 593@end deftypefn 594 595@deftypefn {Built-in Function} {void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val}) 596This function restores the stack context in @var{buf}, 597saved by a previous call to @code{__builtin_setjmp}. After 598@code{__builtin_longjmp} is finished, the program resumes execution as 599if the matching @code{__builtin_setjmp} returns the value @var{val}, 600which must be 1. 601 602Because @code{__builtin_longjmp} depends on the function return 603mechanism to restore the stack context, it cannot be called 604from the same function calling @code{__builtin_setjmp} to 605initialize @var{buf}. It can only be called from a function called 606(directly or indirectly) from the function calling @code{__builtin_setjmp}. 607@end deftypefn 608 609@node Constructing Calls 610@section Constructing Function Calls 611@cindex constructing calls 612@cindex forwarding calls 613 614Using the built-in functions described below, you can record 615the arguments a function received, and call another function 616with the same arguments, without knowing the number or types 617of the arguments. 618 619You can also record the return value of that function call, 620and later return that value, without knowing what data type 621the function tried to return (as long as your caller expects 622that data type). 623 624However, these built-in functions may interact badly with some 625sophisticated features or other extensions of the language. It 626is, therefore, not recommended to use them outside very simple 627functions acting as mere forwarders for their arguments. 628 629@deftypefn {Built-in Function} {void *} __builtin_apply_args () 630This built-in function returns a pointer to data 631describing how to perform a call with the same arguments as are passed 632to the current function. 633 634The function saves the arg pointer register, structure value address, 635and all registers that might be used to pass arguments to a function 636into a block of memory allocated on the stack. Then it returns the 637address of that block. 638@end deftypefn 639 640@deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size}) 641This built-in function invokes @var{function} 642with a copy of the parameters described by @var{arguments} 643and @var{size}. 644 645The value of @var{arguments} should be the value returned by 646@code{__builtin_apply_args}. The argument @var{size} specifies the size 647of the stack argument data, in bytes. 648 649This function returns a pointer to data describing 650how to return whatever value is returned by @var{function}. The data 651is saved in a block of memory allocated on the stack. 652 653It is not always simple to compute the proper value for @var{size}. The 654value is used by @code{__builtin_apply} to compute the amount of data 655that should be pushed on the stack and copied from the incoming argument 656area. 657@end deftypefn 658 659@deftypefn {Built-in Function} {void} __builtin_return (void *@var{result}) 660This built-in function returns the value described by @var{result} from 661the containing function. You should specify, for @var{result}, a value 662returned by @code{__builtin_apply}. 663@end deftypefn 664 665@deftypefn {Built-in Function} {} __builtin_va_arg_pack () 666This built-in function represents all anonymous arguments of an inline 667function. It can be used only in inline functions that are always 668inlined, never compiled as a separate function, such as those using 669@code{__attribute__ ((__always_inline__))} or 670@code{__attribute__ ((__gnu_inline__))} extern inline functions. 671It must be only passed as last argument to some other function 672with variable arguments. This is useful for writing small wrapper 673inlines for variable argument functions, when using preprocessor 674macros is undesirable. For example: 675@smallexample 676extern int myprintf (FILE *f, const char *format, ...); 677extern inline __attribute__ ((__gnu_inline__)) int 678myprintf (FILE *f, const char *format, ...) 679@{ 680 int r = fprintf (f, "myprintf: "); 681 if (r < 0) 682 return r; 683 int s = fprintf (f, format, __builtin_va_arg_pack ()); 684 if (s < 0) 685 return s; 686 return r + s; 687@} 688@end smallexample 689@end deftypefn 690 691@deftypefn {Built-in Function} {int} __builtin_va_arg_pack_len () 692This built-in function returns the number of anonymous arguments of 693an inline function. It can be used only in inline functions that 694are always inlined, never compiled as a separate function, such 695as those using @code{__attribute__ ((__always_inline__))} or 696@code{__attribute__ ((__gnu_inline__))} extern inline functions. 697For example following does link- or run-time checking of open 698arguments for optimized code: 699@smallexample 700#ifdef __OPTIMIZE__ 701extern inline __attribute__((__gnu_inline__)) int 702myopen (const char *path, int oflag, ...) 703@{ 704 if (__builtin_va_arg_pack_len () > 1) 705 warn_open_too_many_arguments (); 706 707 if (__builtin_constant_p (oflag)) 708 @{ 709 if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1) 710 @{ 711 warn_open_missing_mode (); 712 return __open_2 (path, oflag); 713 @} 714 return open (path, oflag, __builtin_va_arg_pack ()); 715 @} 716 717 if (__builtin_va_arg_pack_len () < 1) 718 return __open_2 (path, oflag); 719 720 return open (path, oflag, __builtin_va_arg_pack ()); 721@} 722#endif 723@end smallexample 724@end deftypefn 725 726@node Typeof 727@section Referring to a Type with @code{typeof} 728@findex typeof 729@findex sizeof 730@cindex macros, types of arguments 731 732Another way to refer to the type of an expression is with @code{typeof}. 733The syntax of using of this keyword looks like @code{sizeof}, but the 734construct acts semantically like a type name defined with @code{typedef}. 735 736There are two ways of writing the argument to @code{typeof}: with an 737expression or with a type. Here is an example with an expression: 738 739@smallexample 740typeof (x[0](1)) 741@end smallexample 742 743@noindent 744This assumes that @code{x} is an array of pointers to functions; 745the type described is that of the values of the functions. 746 747Here is an example with a typename as the argument: 748 749@smallexample 750typeof (int *) 751@end smallexample 752 753@noindent 754Here the type described is that of pointers to @code{int}. 755 756If you are writing a header file that must work when included in ISO C 757programs, write @code{__typeof__} instead of @code{typeof}. 758@xref{Alternate Keywords}. 759 760A @code{typeof} construct can be used anywhere a typedef name can be 761used. For example, you can use it in a declaration, in a cast, or inside 762of @code{sizeof} or @code{typeof}. 763 764The operand of @code{typeof} is evaluated for its side effects if and 765only if it is an expression of variably modified type or the name of 766such a type. 767 768@code{typeof} is often useful in conjunction with 769statement expressions (@pxref{Statement Exprs}). 770Here is how the two together can 771be used to define a safe ``maximum'' macro which operates on any 772arithmetic type and evaluates each of its arguments exactly once: 773 774@smallexample 775#define max(a,b) \ 776 (@{ typeof (a) _a = (a); \ 777 typeof (b) _b = (b); \ 778 _a > _b ? _a : _b; @}) 779@end smallexample 780 781@cindex underscores in variables in macros 782@cindex @samp{_} in variables in macros 783@cindex local variables in macros 784@cindex variables, local, in macros 785@cindex macros, local variables in 786 787The reason for using names that start with underscores for the local 788variables is to avoid conflicts with variable names that occur within the 789expressions that are substituted for @code{a} and @code{b}. Eventually we 790hope to design a new form of declaration syntax that allows you to declare 791variables whose scopes start only after their initializers; this will be a 792more reliable way to prevent such conflicts. 793 794@noindent 795Some more examples of the use of @code{typeof}: 796 797@itemize @bullet 798@item 799This declares @code{y} with the type of what @code{x} points to. 800 801@smallexample 802typeof (*x) y; 803@end smallexample 804 805@item 806This declares @code{y} as an array of such values. 807 808@smallexample 809typeof (*x) y[4]; 810@end smallexample 811 812@item 813This declares @code{y} as an array of pointers to characters: 814 815@smallexample 816typeof (typeof (char *)[4]) y; 817@end smallexample 818 819@noindent 820It is equivalent to the following traditional C declaration: 821 822@smallexample 823char *y[4]; 824@end smallexample 825 826To see the meaning of the declaration using @code{typeof}, and why it 827might be a useful way to write, rewrite it with these macros: 828 829@smallexample 830#define pointer(T) typeof(T *) 831#define array(T, N) typeof(T [N]) 832@end smallexample 833 834@noindent 835Now the declaration can be rewritten this way: 836 837@smallexample 838array (pointer (char), 4) y; 839@end smallexample 840 841@noindent 842Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 843pointers to @code{char}. 844@end itemize 845 846In GNU C, but not GNU C++, you may also declare the type of a variable 847as @code{__auto_type}. In that case, the declaration must declare 848only one variable, whose declarator must just be an identifier, the 849declaration must be initialized, and the type of the variable is 850determined by the initializer; the name of the variable is not in 851scope until after the initializer. (In C++, you should use C++11 852@code{auto} for this purpose.) Using @code{__auto_type}, the 853``maximum'' macro above could be written as: 854 855@smallexample 856#define max(a,b) \ 857 (@{ __auto_type _a = (a); \ 858 __auto_type _b = (b); \ 859 _a > _b ? _a : _b; @}) 860@end smallexample 861 862Using @code{__auto_type} instead of @code{typeof} has two advantages: 863 864@itemize @bullet 865@item Each argument to the macro appears only once in the expansion of 866the macro. This prevents the size of the macro expansion growing 867exponentially when calls to such macros are nested inside arguments of 868such macros. 869 870@item If the argument to the macro has variably modified type, it is 871evaluated only once when using @code{__auto_type}, but twice if 872@code{typeof} is used. 873@end itemize 874 875@node Conditionals 876@section Conditionals with Omitted Operands 877@cindex conditional expressions, extensions 878@cindex omitted middle-operands 879@cindex middle-operands, omitted 880@cindex extensions, @code{?:} 881@cindex @code{?:} extensions 882 883The middle operand in a conditional expression may be omitted. Then 884if the first operand is nonzero, its value is the value of the conditional 885expression. 886 887Therefore, the expression 888 889@smallexample 890x ? : y 891@end smallexample 892 893@noindent 894has the value of @code{x} if that is nonzero; otherwise, the value of 895@code{y}. 896 897This example is perfectly equivalent to 898 899@smallexample 900x ? x : y 901@end smallexample 902 903@cindex side effect in @code{?:} 904@cindex @code{?:} side effect 905@noindent 906In this simple case, the ability to omit the middle operand is not 907especially useful. When it becomes useful is when the first operand does, 908or may (if it is a macro argument), contain a side effect. Then repeating 909the operand in the middle would perform the side effect twice. Omitting 910the middle operand uses the value already computed without the undesirable 911effects of recomputing it. 912 913@node __int128 914@section 128-bit Integers 915@cindex @code{__int128} data types 916 917As an extension the integer scalar type @code{__int128} is supported for 918targets which have an integer mode wide enough to hold 128 bits. 919Simply write @code{__int128} for a signed 128-bit integer, or 920@code{unsigned __int128} for an unsigned 128-bit integer. There is no 921support in GCC for expressing an integer constant of type @code{__int128} 922for targets with @code{long long} integer less than 128 bits wide. 923 924@node Long Long 925@section Double-Word Integers 926@cindex @code{long long} data types 927@cindex double-word arithmetic 928@cindex multiprecision arithmetic 929@cindex @code{LL} integer suffix 930@cindex @code{ULL} integer suffix 931 932ISO C99 and ISO C++11 support data types for integers that are at least 93364 bits wide, and as an extension GCC supports them in C90 and C++98 modes. 934Simply write @code{long long int} for a signed integer, or 935@code{unsigned long long int} for an unsigned integer. To make an 936integer constant of type @code{long long int}, add the suffix @samp{LL} 937to the integer. To make an integer constant of type @code{unsigned long 938long int}, add the suffix @samp{ULL} to the integer. 939 940You can use these types in arithmetic like any other integer types. 941Addition, subtraction, and bitwise boolean operations on these types 942are open-coded on all types of machines. Multiplication is open-coded 943if the machine supports a fullword-to-doubleword widening multiply 944instruction. Division and shifts are open-coded only on machines that 945provide special support. The operations that are not open-coded use 946special library routines that come with GCC@. 947 948There may be pitfalls when you use @code{long long} types for function 949arguments without function prototypes. If a function 950expects type @code{int} for its argument, and you pass a value of type 951@code{long long int}, confusion results because the caller and the 952subroutine disagree about the number of bytes for the argument. 953Likewise, if the function expects @code{long long int} and you pass 954@code{int}. The best way to avoid such problems is to use prototypes. 955 956@node Complex 957@section Complex Numbers 958@cindex complex numbers 959@cindex @code{_Complex} keyword 960@cindex @code{__complex__} keyword 961 962ISO C99 supports complex floating data types, and as an extension GCC 963supports them in C90 mode and in C++. GCC also supports complex integer data 964types which are not part of ISO C99. You can declare complex types 965using the keyword @code{_Complex}. As an extension, the older GNU 966keyword @code{__complex__} is also supported. 967 968For example, @samp{_Complex double x;} declares @code{x} as a 969variable whose real part and imaginary part are both of type 970@code{double}. @samp{_Complex short int y;} declares @code{y} to 971have real and imaginary parts of type @code{short int}; this is not 972likely to be useful, but it shows that the set of complex types is 973complete. 974 975To write a constant with a complex data type, use the suffix @samp{i} or 976@samp{j} (either one; they are equivalent). For example, @code{2.5fi} 977has type @code{_Complex float} and @code{3i} has type 978@code{_Complex int}. Such a constant always has a pure imaginary 979value, but you can form any complex value you like by adding one to a 980real constant. This is a GNU extension; if you have an ISO C99 981conforming C library (such as the GNU C Library), and want to construct complex 982constants of floating type, you should include @code{<complex.h>} and 983use the macros @code{I} or @code{_Complex_I} instead. 984 985The ISO C++14 library also defines the @samp{i} suffix, so C++14 code 986that includes the @samp{<complex>} header cannot use @samp{i} for the 987GNU extension. The @samp{j} suffix still has the GNU meaning. 988 989@cindex @code{__real__} keyword 990@cindex @code{__imag__} keyword 991To extract the real part of a complex-valued expression @var{exp}, write 992@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to 993extract the imaginary part. This is a GNU extension; for values of 994floating type, you should use the ISO C99 functions @code{crealf}, 995@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and 996@code{cimagl}, declared in @code{<complex.h>} and also provided as 997built-in functions by GCC@. 998 999@cindex complex conjugation 1000The operator @samp{~} performs complex conjugation when used on a value 1001with a complex type. This is a GNU extension; for values of 1002floating type, you should use the ISO C99 functions @code{conjf}, 1003@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also 1004provided as built-in functions by GCC@. 1005 1006GCC can allocate complex automatic variables in a noncontiguous 1007fashion; it's even possible for the real part to be in a register while 1008the imaginary part is on the stack (or vice versa). Only the DWARF 1009debug info format can represent this, so use of DWARF is recommended. 1010If you are using the stabs debug info format, GCC describes a noncontiguous 1011complex variable as if it were two separate variables of noncomplex type. 1012If the variable's actual name is @code{foo}, the two fictitious 1013variables are named @code{foo$real} and @code{foo$imag}. You can 1014examine and set these two fictitious variables with your debugger. 1015 1016@node Floating Types 1017@section Additional Floating Types 1018@cindex additional floating types 1019@cindex @code{_Float@var{n}} data types 1020@cindex @code{_Float@var{n}x} data types 1021@cindex @code{__float80} data type 1022@cindex @code{__float128} data type 1023@cindex @code{__ibm128} data type 1024@cindex @code{w} floating point suffix 1025@cindex @code{q} floating point suffix 1026@cindex @code{W} floating point suffix 1027@cindex @code{Q} floating point suffix 1028 1029ISO/IEC TS 18661-3:2015 defines C support for additional floating 1030types @code{_Float@var{n}} and @code{_Float@var{n}x}, and GCC supports 1031these type names; the set of types supported depends on the target 1032architecture. These types are not supported when compiling C++. 1033Constants with these types use suffixes @code{f@var{n}} or 1034@code{F@var{n}} and @code{f@var{n}x} or @code{F@var{n}x}. These type 1035names can be used together with @code{_Complex} to declare complex 1036types. 1037 1038As an extension, GNU C and GNU C++ support additional floating 1039types, which are not supported by all targets. 1040@itemize @bullet 1041@item @code{__float128} is available on i386, x86_64, IA-64, and 1042hppa HP-UX, as well as on PowerPC GNU/Linux targets that enable 1043the vector scalar (VSX) instruction set. @code{__float128} supports 1044the 128-bit floating type. On i386, x86_64, PowerPC, and IA-64 1045other than HP-UX, @code{__float128} is an alias for @code{_Float128}. 1046On hppa and IA-64 HP-UX, @code{__float128} is an alias for @code{long 1047double}. 1048 1049@item @code{__float80} is available on the i386, x86_64, and IA-64 1050targets, and supports the 80-bit (@code{XFmode}) floating type. It is 1051an alias for the type name @code{_Float64x} on these targets. 1052 1053@item @code{__ibm128} is available on PowerPC targets, and provides 1054access to the IBM extended double format which is the current format 1055used for @code{long double}. When @code{long double} transitions to 1056@code{__float128} on PowerPC in the future, @code{__ibm128} will remain 1057for use in conversions between the two types. 1058@end itemize 1059 1060Support for these additional types includes the arithmetic operators: 1061add, subtract, multiply, divide; unary arithmetic operators; 1062relational operators; equality operators; and conversions to and from 1063integer and other floating types. Use a suffix @samp{w} or @samp{W} 1064in a literal constant of type @code{__float80} or type 1065@code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{_float128}. 1066 1067In order to use @code{_Float128}, @code{__float128}, and @code{__ibm128} 1068on PowerPC Linux systems, you must use the @option{-mfloat128} option. It is 1069expected in future versions of GCC that @code{_Float128} and @code{__float128} 1070will be enabled automatically. 1071 1072The @code{_Float128} type is supported on all systems where 1073@code{__float128} is supported or where @code{long double} has the 1074IEEE binary128 format. The @code{_Float64x} type is supported on all 1075systems where @code{__float128} is supported. The @code{_Float32} 1076type is supported on all systems supporting IEEE binary32; the 1077@code{_Float64} and @code{_Float32x} types are supported on all systems 1078supporting IEEE binary64. The @code{_Float16} type is supported on AArch64 1079systems by default, and on ARM systems when the IEEE format for 16-bit 1080floating-point types is selected with @option{-mfp16-format=ieee}. 1081GCC does not currently support @code{_Float128x} on any systems. 1082 1083On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex 1084types using the corresponding internal complex type, @code{XCmode} for 1085@code{__float80} type and @code{TCmode} for @code{__float128} type: 1086 1087@smallexample 1088typedef _Complex float __attribute__((mode(TC))) _Complex128; 1089typedef _Complex float __attribute__((mode(XC))) _Complex80; 1090@end smallexample 1091 1092On the PowerPC Linux VSX targets, you can declare complex types using 1093the corresponding internal complex type, @code{KCmode} for 1094@code{__float128} type and @code{ICmode} for @code{__ibm128} type: 1095 1096@smallexample 1097typedef _Complex float __attribute__((mode(KC))) _Complex_float128; 1098typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128; 1099@end smallexample 1100 1101@node Half-Precision 1102@section Half-Precision Floating Point 1103@cindex half-precision floating point 1104@cindex @code{__fp16} data type 1105 1106On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating 1107point via the @code{__fp16} type defined in the ARM C Language Extensions. 1108On ARM systems, you must enable this type explicitly with the 1109@option{-mfp16-format} command-line option in order to use it. 1110 1111ARM targets support two incompatible representations for half-precision 1112floating-point values. You must choose one of the representations and 1113use it consistently in your program. 1114 1115Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format. 1116This format can represent normalized values in the range of @math{2^{-14}} to 65504. 1117There are 11 bits of significand precision, approximately 3 1118decimal digits. 1119 1120Specifying @option{-mfp16-format=alternative} selects the ARM 1121alternative format. This representation is similar to the IEEE 1122format, but does not support infinities or NaNs. Instead, the range 1123of exponents is extended, so that this format can represent normalized 1124values in the range of @math{2^{-14}} to 131008. 1125 1126The GCC port for AArch64 only supports the IEEE 754-2008 format, and does 1127not require use of the @option{-mfp16-format} command-line option. 1128 1129The @code{__fp16} type may only be used as an argument to intrinsics defined 1130in @code{<arm_fp16.h>}, or as a storage format. For purposes of 1131arithmetic and other operations, @code{__fp16} values in C or C++ 1132expressions are automatically promoted to @code{float}. 1133 1134The ARM target provides hardware support for conversions between 1135@code{__fp16} and @code{float} values 1136as an extension to VFP and NEON (Advanced SIMD), and from ARMv8-A provides 1137hardware support for conversions between @code{__fp16} and @code{double} 1138values. GCC generates code using these hardware instructions if you 1139compile with options to select an FPU that provides them; 1140for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp}, 1141in addition to the @option{-mfp16-format} option to select 1142a half-precision format. 1143 1144Language-level support for the @code{__fp16} data type is 1145independent of whether GCC generates code using hardware floating-point 1146instructions. In cases where hardware support is not specified, GCC 1147implements conversions between @code{__fp16} and other types as library 1148calls. 1149 1150It is recommended that portable code use the @code{_Float16} type defined 1151by ISO/IEC TS 18661-3:2015. @xref{Floating Types}. 1152 1153@node Decimal Float 1154@section Decimal Floating Types 1155@cindex decimal floating types 1156@cindex @code{_Decimal32} data type 1157@cindex @code{_Decimal64} data type 1158@cindex @code{_Decimal128} data type 1159@cindex @code{df} integer suffix 1160@cindex @code{dd} integer suffix 1161@cindex @code{dl} integer suffix 1162@cindex @code{DF} integer suffix 1163@cindex @code{DD} integer suffix 1164@cindex @code{DL} integer suffix 1165 1166As an extension, GNU C supports decimal floating types as 1167defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal 1168floating types in GCC will evolve as the draft technical report changes. 1169Calling conventions for any target might also change. Not all targets 1170support decimal floating types. 1171 1172The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and 1173@code{_Decimal128}. They use a radix of ten, unlike the floating types 1174@code{float}, @code{double}, and @code{long double} whose radix is not 1175specified by the C standard but is usually two. 1176 1177Support for decimal floating types includes the arithmetic operators 1178add, subtract, multiply, divide; unary arithmetic operators; 1179relational operators; equality operators; and conversions to and from 1180integer and other floating types. Use a suffix @samp{df} or 1181@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd} 1182or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for 1183@code{_Decimal128}. 1184 1185GCC support of decimal float as specified by the draft technical report 1186is incomplete: 1187 1188@itemize @bullet 1189@item 1190When the value of a decimal floating type cannot be represented in the 1191integer type to which it is being converted, the result is undefined 1192rather than the result value specified by the draft technical report. 1193 1194@item 1195GCC does not provide the C library functionality associated with 1196@file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and 1197@file{wchar.h}, which must come from a separate C library implementation. 1198Because of this the GNU C compiler does not define macro 1199@code{__STDC_DEC_FP__} to indicate that the implementation conforms to 1200the technical report. 1201@end itemize 1202 1203Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} 1204are supported by the DWARF debug information format. 1205 1206@node Hex Floats 1207@section Hex Floats 1208@cindex hex floats 1209 1210ISO C99 and ISO C++17 support floating-point numbers written not only in 1211the usual decimal notation, such as @code{1.55e1}, but also numbers such as 1212@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC 1213supports this in C90 mode (except in some cases when strictly 1214conforming) and in C++98, C++11 and C++14 modes. In that format the 1215@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are 1216mandatory. The exponent is a decimal number that indicates the power of 12172 by which the significant part is multiplied. Thus @samp{0x1.f} is 1218@tex 1219$1 {15\over16}$, 1220@end tex 1221@ifnottex 12221 15/16, 1223@end ifnottex 1224@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} 1225is the same as @code{1.55e1}. 1226 1227Unlike for floating-point numbers in the decimal notation the exponent 1228is always required in the hexadecimal notation. Otherwise the compiler 1229would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This 1230could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the 1231extension for floating-point constants of type @code{float}. 1232 1233@node Fixed-Point 1234@section Fixed-Point Types 1235@cindex fixed-point types 1236@cindex @code{_Fract} data type 1237@cindex @code{_Accum} data type 1238@cindex @code{_Sat} data type 1239@cindex @code{hr} fixed-suffix 1240@cindex @code{r} fixed-suffix 1241@cindex @code{lr} fixed-suffix 1242@cindex @code{llr} fixed-suffix 1243@cindex @code{uhr} fixed-suffix 1244@cindex @code{ur} fixed-suffix 1245@cindex @code{ulr} fixed-suffix 1246@cindex @code{ullr} fixed-suffix 1247@cindex @code{hk} fixed-suffix 1248@cindex @code{k} fixed-suffix 1249@cindex @code{lk} fixed-suffix 1250@cindex @code{llk} fixed-suffix 1251@cindex @code{uhk} fixed-suffix 1252@cindex @code{uk} fixed-suffix 1253@cindex @code{ulk} fixed-suffix 1254@cindex @code{ullk} fixed-suffix 1255@cindex @code{HR} fixed-suffix 1256@cindex @code{R} fixed-suffix 1257@cindex @code{LR} fixed-suffix 1258@cindex @code{LLR} fixed-suffix 1259@cindex @code{UHR} fixed-suffix 1260@cindex @code{UR} fixed-suffix 1261@cindex @code{ULR} fixed-suffix 1262@cindex @code{ULLR} fixed-suffix 1263@cindex @code{HK} fixed-suffix 1264@cindex @code{K} fixed-suffix 1265@cindex @code{LK} fixed-suffix 1266@cindex @code{LLK} fixed-suffix 1267@cindex @code{UHK} fixed-suffix 1268@cindex @code{UK} fixed-suffix 1269@cindex @code{ULK} fixed-suffix 1270@cindex @code{ULLK} fixed-suffix 1271 1272As an extension, GNU C supports fixed-point types as 1273defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point 1274types in GCC will evolve as the draft technical report changes. 1275Calling conventions for any target might also change. Not all targets 1276support fixed-point types. 1277 1278The fixed-point types are 1279@code{short _Fract}, 1280@code{_Fract}, 1281@code{long _Fract}, 1282@code{long long _Fract}, 1283@code{unsigned short _Fract}, 1284@code{unsigned _Fract}, 1285@code{unsigned long _Fract}, 1286@code{unsigned long long _Fract}, 1287@code{_Sat short _Fract}, 1288@code{_Sat _Fract}, 1289@code{_Sat long _Fract}, 1290@code{_Sat long long _Fract}, 1291@code{_Sat unsigned short _Fract}, 1292@code{_Sat unsigned _Fract}, 1293@code{_Sat unsigned long _Fract}, 1294@code{_Sat unsigned long long _Fract}, 1295@code{short _Accum}, 1296@code{_Accum}, 1297@code{long _Accum}, 1298@code{long long _Accum}, 1299@code{unsigned short _Accum}, 1300@code{unsigned _Accum}, 1301@code{unsigned long _Accum}, 1302@code{unsigned long long _Accum}, 1303@code{_Sat short _Accum}, 1304@code{_Sat _Accum}, 1305@code{_Sat long _Accum}, 1306@code{_Sat long long _Accum}, 1307@code{_Sat unsigned short _Accum}, 1308@code{_Sat unsigned _Accum}, 1309@code{_Sat unsigned long _Accum}, 1310@code{_Sat unsigned long long _Accum}. 1311 1312Fixed-point data values contain fractional and optional integral parts. 1313The format of fixed-point data varies and depends on the target machine. 1314 1315Support for fixed-point types includes: 1316@itemize @bullet 1317@item 1318prefix and postfix increment and decrement operators (@code{++}, @code{--}) 1319@item 1320unary arithmetic operators (@code{+}, @code{-}, @code{!}) 1321@item 1322binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/}) 1323@item 1324binary shift operators (@code{<<}, @code{>>}) 1325@item 1326relational operators (@code{<}, @code{<=}, @code{>=}, @code{>}) 1327@item 1328equality operators (@code{==}, @code{!=}) 1329@item 1330assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=}, 1331@code{<<=}, @code{>>=}) 1332@item 1333conversions to and from integer, floating-point, or fixed-point types 1334@end itemize 1335 1336Use a suffix in a fixed-point literal constant: 1337@itemize 1338@item @samp{hr} or @samp{HR} for @code{short _Fract} and 1339@code{_Sat short _Fract} 1340@item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract} 1341@item @samp{lr} or @samp{LR} for @code{long _Fract} and 1342@code{_Sat long _Fract} 1343@item @samp{llr} or @samp{LLR} for @code{long long _Fract} and 1344@code{_Sat long long _Fract} 1345@item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and 1346@code{_Sat unsigned short _Fract} 1347@item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and 1348@code{_Sat unsigned _Fract} 1349@item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and 1350@code{_Sat unsigned long _Fract} 1351@item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract} 1352and @code{_Sat unsigned long long _Fract} 1353@item @samp{hk} or @samp{HK} for @code{short _Accum} and 1354@code{_Sat short _Accum} 1355@item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum} 1356@item @samp{lk} or @samp{LK} for @code{long _Accum} and 1357@code{_Sat long _Accum} 1358@item @samp{llk} or @samp{LLK} for @code{long long _Accum} and 1359@code{_Sat long long _Accum} 1360@item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and 1361@code{_Sat unsigned short _Accum} 1362@item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and 1363@code{_Sat unsigned _Accum} 1364@item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and 1365@code{_Sat unsigned long _Accum} 1366@item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum} 1367and @code{_Sat unsigned long long _Accum} 1368@end itemize 1369 1370GCC support of fixed-point types as specified by the draft technical report 1371is incomplete: 1372 1373@itemize @bullet 1374@item 1375Pragmas to control overflow and rounding behaviors are not implemented. 1376@end itemize 1377 1378Fixed-point types are supported by the DWARF debug information format. 1379 1380@node Named Address Spaces 1381@section Named Address Spaces 1382@cindex Named Address Spaces 1383 1384As an extension, GNU C supports named address spaces as 1385defined in the N1275 draft of ISO/IEC DTR 18037. Support for named 1386address spaces in GCC will evolve as the draft technical report 1387changes. Calling conventions for any target might also change. At 1388present, only the AVR, M32C, RL78, and x86 targets support 1389address spaces other than the generic address space. 1390 1391Address space identifiers may be used exactly like any other C type 1392qualifier (e.g., @code{const} or @code{volatile}). See the N1275 1393document for more details. 1394 1395@anchor{AVR Named Address Spaces} 1396@subsection AVR Named Address Spaces 1397 1398On the AVR target, there are several address spaces that can be used 1399in order to put read-only data into the flash memory and access that 1400data by means of the special instructions @code{LPM} or @code{ELPM} 1401needed to read from flash. 1402 1403Devices belonging to @code{avrtiny} and @code{avrxmega3} can access 1404flash memory by means of @code{LD*} instructions because the flash 1405memory is mapped into the RAM address space. There is @emph{no need} 1406for language extensions like @code{__flash} or attribute 1407@ref{AVR Variable Attributes,,@code{progmem}}. 1408The default linker description files for these devices cater for that 1409feature and @code{.rodata} stays in flash: The compiler just generates 1410@code{LD*} instructions, and the linker script adds core specific 1411offsets to all @code{.rodata} symbols: @code{0x4000} in the case of 1412@code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}. 1413See @ref{AVR Options} for a list of respective devices. 1414 1415For devices not in @code{avrtiny} or @code{avrxmega3}, 1416any data including read-only data is located in RAM (the generic 1417address space) because flash memory is not visible in the RAM address 1418space. In order to locate read-only data in flash memory @emph{and} 1419to generate the right instructions to access this data without 1420using (inline) assembler code, special address spaces are needed. 1421 1422@table @code 1423@item __flash 1424@cindex @code{__flash} AVR Named Address Spaces 1425The @code{__flash} qualifier locates data in the 1426@code{.progmem.data} section. Data is read using the @code{LPM} 1427instruction. Pointers to this address space are 16 bits wide. 1428 1429@item __flash1 1430@itemx __flash2 1431@itemx __flash3 1432@itemx __flash4 1433@itemx __flash5 1434@cindex @code{__flash1} AVR Named Address Spaces 1435@cindex @code{__flash2} AVR Named Address Spaces 1436@cindex @code{__flash3} AVR Named Address Spaces 1437@cindex @code{__flash4} AVR Named Address Spaces 1438@cindex @code{__flash5} AVR Named Address Spaces 1439These are 16-bit address spaces locating data in section 1440@code{.progmem@var{N}.data} where @var{N} refers to 1441address space @code{__flash@var{N}}. 1442The compiler sets the @code{RAMPZ} segment register appropriately 1443before reading data by means of the @code{ELPM} instruction. 1444 1445@item __memx 1446@cindex @code{__memx} AVR Named Address Spaces 1447This is a 24-bit address space that linearizes flash and RAM: 1448If the high bit of the address is set, data is read from 1449RAM using the lower two bytes as RAM address. 1450If the high bit of the address is clear, data is read from flash 1451with @code{RAMPZ} set according to the high byte of the address. 1452@xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}. 1453 1454Objects in this address space are located in @code{.progmemx.data}. 1455@end table 1456 1457@b{Example} 1458 1459@smallexample 1460char my_read (const __flash char ** p) 1461@{ 1462 /* p is a pointer to RAM that points to a pointer to flash. 1463 The first indirection of p reads that flash pointer 1464 from RAM and the second indirection reads a char from this 1465 flash address. */ 1466 1467 return **p; 1468@} 1469 1470/* Locate array[] in flash memory */ 1471const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @}; 1472 1473int i = 1; 1474 1475int main (void) 1476@{ 1477 /* Return 17 by reading from flash memory */ 1478 return array[array[i]]; 1479@} 1480@end smallexample 1481 1482@noindent 1483For each named address space supported by avr-gcc there is an equally 1484named but uppercase built-in macro defined. 1485The purpose is to facilitate testing if respective address space 1486support is available or not: 1487 1488@smallexample 1489#ifdef __FLASH 1490const __flash int var = 1; 1491 1492int read_var (void) 1493@{ 1494 return var; 1495@} 1496#else 1497#include <avr/pgmspace.h> /* From AVR-LibC */ 1498 1499const int var PROGMEM = 1; 1500 1501int read_var (void) 1502@{ 1503 return (int) pgm_read_word (&var); 1504@} 1505#endif /* __FLASH */ 1506@end smallexample 1507 1508@noindent 1509Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}} 1510locates data in flash but 1511accesses to these data read from generic address space, i.e.@: 1512from RAM, 1513so that you need special accessors like @code{pgm_read_byte} 1514from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} 1515together with attribute @code{progmem}. 1516 1517@noindent 1518@b{Limitations and caveats} 1519 1520@itemize 1521@item 1522Reading across the 64@tie{}KiB section boundary of 1523the @code{__flash} or @code{__flash@var{N}} address spaces 1524shows undefined behavior. The only address space that 1525supports reading across the 64@tie{}KiB flash segment boundaries is 1526@code{__memx}. 1527 1528@item 1529If you use one of the @code{__flash@var{N}} address spaces 1530you must arrange your linker script to locate the 1531@code{.progmem@var{N}.data} sections according to your needs. 1532 1533@item 1534Any data or pointers to the non-generic address spaces must 1535be qualified as @code{const}, i.e.@: as read-only data. 1536This still applies if the data in one of these address 1537spaces like software version number or calibration lookup table are intended to 1538be changed after load time by, say, a boot loader. In this case 1539the right qualification is @code{const} @code{volatile} so that the compiler 1540must not optimize away known values or insert them 1541as immediates into operands of instructions. 1542 1543@item 1544The following code initializes a variable @code{pfoo} 1545located in static storage with a 24-bit address: 1546@smallexample 1547extern const __memx char foo; 1548const __memx void *pfoo = &foo; 1549@end smallexample 1550 1551@item 1552On the reduced Tiny devices like ATtiny40, no address spaces are supported. 1553Just use vanilla C / C++ code without overhead as outlined above. 1554Attribute @code{progmem} is supported but works differently, 1555see @ref{AVR Variable Attributes}. 1556 1557@end itemize 1558 1559@subsection M32C Named Address Spaces 1560@cindex @code{__far} M32C Named Address Spaces 1561 1562On the M32C target, with the R8C and M16C CPU variants, variables 1563qualified with @code{__far} are accessed using 32-bit addresses in 1564order to access memory beyond the first 64@tie{}Ki bytes. If 1565@code{__far} is used with the M32CM or M32C CPU variants, it has no 1566effect. 1567 1568@subsection RL78 Named Address Spaces 1569@cindex @code{__far} RL78 Named Address Spaces 1570 1571On the RL78 target, variables qualified with @code{__far} are accessed 1572with 32-bit pointers (20-bit addresses) rather than the default 16-bit 1573addresses. Non-far variables are assumed to appear in the topmost 157464@tie{}KiB of the address space. 1575 1576@subsection x86 Named Address Spaces 1577@cindex x86 named address spaces 1578 1579On the x86 target, variables may be declared as being relative 1580to the @code{%fs} or @code{%gs} segments. 1581 1582@table @code 1583@item __seg_fs 1584@itemx __seg_gs 1585@cindex @code{__seg_fs} x86 named address space 1586@cindex @code{__seg_gs} x86 named address space 1587The object is accessed with the respective segment override prefix. 1588 1589The respective segment base must be set via some method specific to 1590the operating system. Rather than require an expensive system call 1591to retrieve the segment base, these address spaces are not considered 1592to be subspaces of the generic (flat) address space. This means that 1593explicit casts are required to convert pointers between these address 1594spaces and the generic address space. In practice the application 1595should cast to @code{uintptr_t} and apply the segment base offset 1596that it installed previously. 1597 1598The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are 1599defined when these address spaces are supported. 1600@end table 1601 1602@node Zero Length 1603@section Arrays of Length Zero 1604@cindex arrays of length zero 1605@cindex zero-length arrays 1606@cindex length-zero arrays 1607@cindex flexible array members 1608 1609Declaring zero-length arrays is allowed in GNU C as an extension. 1610A zero-length array can be useful as the last element of a structure 1611that is really a header for a variable-length object: 1612 1613@smallexample 1614struct line @{ 1615 int length; 1616 char contents[0]; 1617@}; 1618 1619struct line *thisline = (struct line *) 1620 malloc (sizeof (struct line) + this_length); 1621thisline->length = this_length; 1622@end smallexample 1623 1624Although the size of a zero-length array is zero, an array member of 1625this kind may increase the size of the enclosing type as a result of tail 1626padding. The offset of a zero-length array member from the beginning 1627of the enclosing structure is the same as the offset of an array with 1628one or more elements of the same type. The alignment of a zero-length 1629array is the same as the alignment of its elements. 1630 1631Declaring zero-length arrays in other contexts, including as interior 1632members of structure objects or as non-member objects, is discouraged. 1633Accessing elements of zero-length arrays declared in such contexts is 1634undefined and may be diagnosed. 1635 1636In the absence of the zero-length array extension, in ISO C90 1637the @code{contents} array in the example above would typically be declared 1638to have a single element. Unlike a zero-length array which only contributes 1639to the size of the enclosing structure for the purposes of alignment, 1640a one-element array always occupies at least as much space as a single 1641object of the type. Although using one-element arrays this way is 1642discouraged, GCC handles accesses to trailing one-element array members 1643analogously to zero-length arrays. 1644 1645The preferred mechanism to declare variable-length types like 1646@code{struct line} above is the ISO C99 @dfn{flexible array member}, 1647with slightly different syntax and semantics: 1648 1649@itemize @bullet 1650@item 1651Flexible array members are written as @code{contents[]} without 1652the @code{0}. 1653 1654@item 1655Flexible array members have incomplete type, and so the @code{sizeof} 1656operator may not be applied. As a quirk of the original implementation 1657of zero-length arrays, @code{sizeof} evaluates to zero. 1658 1659@item 1660Flexible array members may only appear as the last member of a 1661@code{struct} that is otherwise non-empty. 1662 1663@item 1664A structure containing a flexible array member, or a union containing 1665such a structure (possibly recursively), may not be a member of a 1666structure or an element of an array. (However, these uses are 1667permitted by GCC as extensions.) 1668@end itemize 1669 1670Non-empty initialization of zero-length 1671arrays is treated like any case where there are more initializer 1672elements than the array holds, in that a suitable warning about ``excess 1673elements in array'' is given, and the excess elements (all of them, in 1674this case) are ignored. 1675 1676GCC allows static initialization of flexible array members. 1677This is equivalent to defining a new structure containing the original 1678structure followed by an array of sufficient size to contain the data. 1679E.g.@: in the following, @code{f1} is constructed as if it were declared 1680like @code{f2}. 1681 1682@smallexample 1683struct f1 @{ 1684 int x; int y[]; 1685@} f1 = @{ 1, @{ 2, 3, 4 @} @}; 1686 1687struct f2 @{ 1688 struct f1 f1; int data[3]; 1689@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; 1690@end smallexample 1691 1692@noindent 1693The convenience of this extension is that @code{f1} has the desired 1694type, eliminating the need to consistently refer to @code{f2.f1}. 1695 1696This has symmetry with normal static arrays, in that an array of 1697unknown size is also written with @code{[]}. 1698 1699Of course, this extension only makes sense if the extra data comes at 1700the end of a top-level object, as otherwise we would be overwriting 1701data at subsequent offsets. To avoid undue complication and confusion 1702with initialization of deeply nested arrays, we simply disallow any 1703non-empty initialization except when the structure is the top-level 1704object. For example: 1705 1706@smallexample 1707struct foo @{ int x; int y[]; @}; 1708struct bar @{ struct foo z; @}; 1709 1710struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} 1711struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1712struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} 1713struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1714@end smallexample 1715 1716@node Empty Structures 1717@section Structures with No Members 1718@cindex empty structures 1719@cindex zero-size structures 1720 1721GCC permits a C structure to have no members: 1722 1723@smallexample 1724struct empty @{ 1725@}; 1726@end smallexample 1727 1728The structure has size zero. In C++, empty structures are part 1729of the language. G++ treats empty structures as if they had a single 1730member of type @code{char}. 1731 1732@node Variable Length 1733@section Arrays of Variable Length 1734@cindex variable-length arrays 1735@cindex arrays of variable length 1736@cindex VLAs 1737 1738Variable-length automatic arrays are allowed in ISO C99, and as an 1739extension GCC accepts them in C90 mode and in C++. These arrays are 1740declared like any other automatic arrays, but with a length that is not 1741a constant expression. The storage is allocated at the point of 1742declaration and deallocated when the block scope containing the declaration 1743exits. For 1744example: 1745 1746@smallexample 1747FILE * 1748concat_fopen (char *s1, char *s2, char *mode) 1749@{ 1750 char str[strlen (s1) + strlen (s2) + 1]; 1751 strcpy (str, s1); 1752 strcat (str, s2); 1753 return fopen (str, mode); 1754@} 1755@end smallexample 1756 1757@cindex scope of a variable length array 1758@cindex variable-length array scope 1759@cindex deallocating variable length arrays 1760Jumping or breaking out of the scope of the array name deallocates the 1761storage. Jumping into the scope is not allowed; you get an error 1762message for it. 1763 1764@cindex variable-length array in a structure 1765As an extension, GCC accepts variable-length arrays as a member of 1766a structure or a union. For example: 1767 1768@smallexample 1769void 1770foo (int n) 1771@{ 1772 struct S @{ int x[n]; @}; 1773@} 1774@end smallexample 1775 1776@cindex @code{alloca} vs variable-length arrays 1777You can use the function @code{alloca} to get an effect much like 1778variable-length arrays. The function @code{alloca} is available in 1779many other C implementations (but not in all). On the other hand, 1780variable-length arrays are more elegant. 1781 1782There are other differences between these two methods. Space allocated 1783with @code{alloca} exists until the containing @emph{function} returns. 1784The space for a variable-length array is deallocated as soon as the array 1785name's scope ends, unless you also use @code{alloca} in this scope. 1786 1787You can also use variable-length arrays as arguments to functions: 1788 1789@smallexample 1790struct entry 1791tester (int len, char data[len][len]) 1792@{ 1793 /* @r{@dots{}} */ 1794@} 1795@end smallexample 1796 1797The length of an array is computed once when the storage is allocated 1798and is remembered for the scope of the array in case you access it with 1799@code{sizeof}. 1800 1801If you want to pass the array first and the length afterward, you can 1802use a forward declaration in the parameter list---another GNU extension. 1803 1804@smallexample 1805struct entry 1806tester (int len; char data[len][len], int len) 1807@{ 1808 /* @r{@dots{}} */ 1809@} 1810@end smallexample 1811 1812@cindex parameter forward declaration 1813The @samp{int len} before the semicolon is a @dfn{parameter forward 1814declaration}, and it serves the purpose of making the name @code{len} 1815known when the declaration of @code{data} is parsed. 1816 1817You can write any number of such parameter forward declarations in the 1818parameter list. They can be separated by commas or semicolons, but the 1819last one must end with a semicolon, which is followed by the ``real'' 1820parameter declarations. Each forward declaration must match a ``real'' 1821declaration in parameter name and data type. ISO C99 does not support 1822parameter forward declarations. 1823 1824@node Variadic Macros 1825@section Macros with a Variable Number of Arguments. 1826@cindex variable number of arguments 1827@cindex macro with variable arguments 1828@cindex rest argument (in macro) 1829@cindex variadic macros 1830 1831In the ISO C standard of 1999, a macro can be declared to accept a 1832variable number of arguments much as a function can. The syntax for 1833defining the macro is similar to that of a function. Here is an 1834example: 1835 1836@smallexample 1837#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) 1838@end smallexample 1839 1840@noindent 1841Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of 1842such a macro, it represents the zero or more tokens until the closing 1843parenthesis that ends the invocation, including any commas. This set of 1844tokens replaces the identifier @code{__VA_ARGS__} in the macro body 1845wherever it appears. See the CPP manual for more information. 1846 1847GCC has long supported variadic macros, and used a different syntax that 1848allowed you to give a name to the variable arguments just like any other 1849argument. Here is an example: 1850 1851@smallexample 1852#define debug(format, args...) fprintf (stderr, format, args) 1853@end smallexample 1854 1855@noindent 1856This is in all ways equivalent to the ISO C example above, but arguably 1857more readable and descriptive. 1858 1859GNU CPP has two further variadic macro extensions, and permits them to 1860be used with either of the above forms of macro definition. 1861 1862In standard C, you are not allowed to leave the variable argument out 1863entirely; but you are allowed to pass an empty argument. For example, 1864this invocation is invalid in ISO C, because there is no comma after 1865the string: 1866 1867@smallexample 1868debug ("A message") 1869@end smallexample 1870 1871GNU CPP permits you to completely omit the variable arguments in this 1872way. In the above examples, the compiler would complain, though since 1873the expansion of the macro still has the extra comma after the format 1874string. 1875 1876To help solve this problem, CPP behaves specially for variable arguments 1877used with the token paste operator, @samp{##}. If instead you write 1878 1879@smallexample 1880#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) 1881@end smallexample 1882 1883@noindent 1884and if the variable arguments are omitted or empty, the @samp{##} 1885operator causes the preprocessor to remove the comma before it. If you 1886do provide some variable arguments in your macro invocation, GNU CPP 1887does not complain about the paste operation and instead places the 1888variable arguments after the comma. Just like any other pasted macro 1889argument, these arguments are not macro expanded. 1890 1891@node Escaped Newlines 1892@section Slightly Looser Rules for Escaped Newlines 1893@cindex escaped newlines 1894@cindex newlines (escaped) 1895 1896The preprocessor treatment of escaped newlines is more relaxed 1897than that specified by the C90 standard, which requires the newline 1898to immediately follow a backslash. 1899GCC's implementation allows whitespace in the form 1900of spaces, horizontal and vertical tabs, and form feeds between the 1901backslash and the subsequent newline. The preprocessor issues a 1902warning, but treats it as a valid escaped newline and combines the two 1903lines to form a single logical line. This works within comments and 1904tokens, as well as between tokens. Comments are @emph{not} treated as 1905whitespace for the purposes of this relaxation, since they have not 1906yet been replaced with spaces. 1907 1908@node Subscripting 1909@section Non-Lvalue Arrays May Have Subscripts 1910@cindex subscripting 1911@cindex arrays, non-lvalue 1912 1913@cindex subscripting and function values 1914In ISO C99, arrays that are not lvalues still decay to pointers, and 1915may be subscripted, although they may not be modified or used after 1916the next sequence point and the unary @samp{&} operator may not be 1917applied to them. As an extension, GNU C allows such arrays to be 1918subscripted in C90 mode, though otherwise they do not decay to 1919pointers outside C99 mode. For example, 1920this is valid in GNU C though not valid in C90: 1921 1922@smallexample 1923@group 1924struct foo @{int a[4];@}; 1925 1926struct foo f(); 1927 1928bar (int index) 1929@{ 1930 return f().a[index]; 1931@} 1932@end group 1933@end smallexample 1934 1935@node Pointer Arith 1936@section Arithmetic on @code{void}- and Function-Pointers 1937@cindex void pointers, arithmetic 1938@cindex void, size of pointer to 1939@cindex function pointers, arithmetic 1940@cindex function, size of pointer to 1941 1942In GNU C, addition and subtraction operations are supported on pointers to 1943@code{void} and on pointers to functions. This is done by treating the 1944size of a @code{void} or of a function as 1. 1945 1946A consequence of this is that @code{sizeof} is also allowed on @code{void} 1947and on function types, and returns 1. 1948 1949@opindex Wpointer-arith 1950The option @option{-Wpointer-arith} requests a warning if these extensions 1951are used. 1952 1953@node Variadic Pointer Args 1954@section Pointer Arguments in Variadic Functions 1955@cindex pointer arguments in variadic functions 1956@cindex variadic functions, pointer arguments 1957 1958Standard C requires that pointer types used with @code{va_arg} in 1959functions with variable argument lists either must be compatible with 1960that of the actual argument, or that one type must be a pointer to 1961@code{void} and the other a pointer to a character type. GNU C 1962implements the POSIX XSI extension that additionally permits the use 1963of @code{va_arg} with a pointer type to receive arguments of any other 1964pointer type. 1965 1966In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used 1967to consume an argument of any pointer type. 1968 1969@node Pointers to Arrays 1970@section Pointers to Arrays with Qualifiers Work as Expected 1971@cindex pointers to arrays 1972@cindex const qualifier 1973 1974In GNU C, pointers to arrays with qualifiers work similar to pointers 1975to other qualified types. For example, a value of type @code{int (*)[5]} 1976can be used to initialize a variable of type @code{const int (*)[5]}. 1977These types are incompatible in ISO C because the @code{const} qualifier 1978is formally attached to the element type of the array and not the 1979array itself. 1980 1981@smallexample 1982extern void 1983transpose (int N, int M, double out[M][N], const double in[N][M]); 1984double x[3][2]; 1985double y[2][3]; 1986@r{@dots{}} 1987transpose(3, 2, y, x); 1988@end smallexample 1989 1990@node Initializers 1991@section Non-Constant Initializers 1992@cindex initializers, non-constant 1993@cindex non-constant initializers 1994 1995As in standard C++ and ISO C99, the elements of an aggregate initializer for an 1996automatic variable are not required to be constant expressions in GNU C@. 1997Here is an example of an initializer with run-time varying elements: 1998 1999@smallexample 2000foo (float f, float g) 2001@{ 2002 float beat_freqs[2] = @{ f-g, f+g @}; 2003 /* @r{@dots{}} */ 2004@} 2005@end smallexample 2006 2007@node Compound Literals 2008@section Compound Literals 2009@cindex constructor expressions 2010@cindex initializations in expressions 2011@cindex structures, constructor expression 2012@cindex expressions, constructor 2013@cindex compound literals 2014@c The GNU C name for what C99 calls compound literals was "constructor expressions". 2015 2016A compound literal looks like a cast of a brace-enclosed aggregate 2017initializer list. Its value is an object of the type specified in 2018the cast, containing the elements specified in the initializer. 2019Unlike the result of a cast, a compound literal is an lvalue. ISO 2020C99 and later support compound literals. As an extension, GCC 2021supports compound literals also in C90 mode and in C++, although 2022as explained below, the C++ semantics are somewhat different. 2023 2024Usually, the specified type of a compound literal is a structure. Assume 2025that @code{struct foo} and @code{structure} are declared as shown: 2026 2027@smallexample 2028struct foo @{int a; char b[2];@} structure; 2029@end smallexample 2030 2031@noindent 2032Here is an example of constructing a @code{struct foo} with a compound literal: 2033 2034@smallexample 2035structure = ((struct foo) @{x + y, 'a', 0@}); 2036@end smallexample 2037 2038@noindent 2039This is equivalent to writing the following: 2040 2041@smallexample 2042@{ 2043 struct foo temp = @{x + y, 'a', 0@}; 2044 structure = temp; 2045@} 2046@end smallexample 2047 2048You can also construct an array, though this is dangerous in C++, as 2049explained below. If all the elements of the compound literal are 2050(made up of) simple constant expressions suitable for use in 2051initializers of objects of static storage duration, then the compound 2052literal can be coerced to a pointer to its first element and used in 2053such an initializer, as shown here: 2054 2055@smallexample 2056char **foo = (char *[]) @{ "x", "y", "z" @}; 2057@end smallexample 2058 2059Compound literals for scalar types and union types are also allowed. In 2060the following example the variable @code{i} is initialized to the value 2061@code{2}, the result of incrementing the unnamed object created by 2062the compound literal. 2063 2064@smallexample 2065int i = ++(int) @{ 1 @}; 2066@end smallexample 2067 2068As a GNU extension, GCC allows initialization of objects with static storage 2069duration by compound literals (which is not possible in ISO C99 because 2070the initializer is not a constant). 2071It is handled as if the object were initialized only with the brace-enclosed 2072list if the types of the compound literal and the object match. 2073The elements of the compound literal must be constant. 2074If the object being initialized has array type of unknown size, the size is 2075determined by the size of the compound literal. 2076 2077@smallexample 2078static struct foo x = (struct foo) @{1, 'a', 'b'@}; 2079static int y[] = (int []) @{1, 2, 3@}; 2080static int z[] = (int [3]) @{1@}; 2081@end smallexample 2082 2083@noindent 2084The above lines are equivalent to the following: 2085@smallexample 2086static struct foo x = @{1, 'a', 'b'@}; 2087static int y[] = @{1, 2, 3@}; 2088static int z[] = @{1, 0, 0@}; 2089@end smallexample 2090 2091In C, a compound literal designates an unnamed object with static or 2092automatic storage duration. In C++, a compound literal designates a 2093temporary object that only lives until the end of its full-expression. 2094As a result, well-defined C code that takes the address of a subobject 2095of a compound literal can be undefined in C++, so G++ rejects 2096the conversion of a temporary array to a pointer. For instance, if 2097the array compound literal example above appeared inside a function, 2098any subsequent use of @code{foo} in C++ would have undefined behavior 2099because the lifetime of the array ends after the declaration of @code{foo}. 2100 2101As an optimization, G++ sometimes gives array compound literals longer 2102lifetimes: when the array either appears outside a function or has 2103a @code{const}-qualified type. If @code{foo} and its initializer had 2104elements of type @code{char *const} rather than @code{char *}, or if 2105@code{foo} were a global variable, the array would have static storage 2106duration. But it is probably safest just to avoid the use of array 2107compound literals in C++ code. 2108 2109@node Designated Inits 2110@section Designated Initializers 2111@cindex initializers with labeled elements 2112@cindex labeled elements in initializers 2113@cindex case labels in initializers 2114@cindex designated initializers 2115 2116Standard C90 requires the elements of an initializer to appear in a fixed 2117order, the same as the order of the elements in the array or structure 2118being initialized. 2119 2120In ISO C99 you can give the elements in any order, specifying the array 2121indices or structure field names they apply to, and GNU C allows this as 2122an extension in C90 mode as well. This extension is not 2123implemented in GNU C++. 2124 2125To specify an array index, write 2126@samp{[@var{index}] =} before the element value. For example, 2127 2128@smallexample 2129int a[6] = @{ [4] = 29, [2] = 15 @}; 2130@end smallexample 2131 2132@noindent 2133is equivalent to 2134 2135@smallexample 2136int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; 2137@end smallexample 2138 2139@noindent 2140The index values must be constant expressions, even if the array being 2141initialized is automatic. 2142 2143An alternative syntax for this that has been obsolete since GCC 2.5 but 2144GCC still accepts is to write @samp{[@var{index}]} before the element 2145value, with no @samp{=}. 2146 2147To initialize a range of elements to the same value, write 2148@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU 2149extension. For example, 2150 2151@smallexample 2152int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; 2153@end smallexample 2154 2155@noindent 2156If the value in it has side effects, the side effects happen only once, 2157not for each initialized field by the range initializer. 2158 2159@noindent 2160Note that the length of the array is the highest value specified 2161plus one. 2162 2163In a structure initializer, specify the name of a field to initialize 2164with @samp{.@var{fieldname} =} before the element value. For example, 2165given the following structure, 2166 2167@smallexample 2168struct point @{ int x, y; @}; 2169@end smallexample 2170 2171@noindent 2172the following initialization 2173 2174@smallexample 2175struct point p = @{ .y = yvalue, .x = xvalue @}; 2176@end smallexample 2177 2178@noindent 2179is equivalent to 2180 2181@smallexample 2182struct point p = @{ xvalue, yvalue @}; 2183@end smallexample 2184 2185Another syntax that has the same meaning, obsolete since GCC 2.5, is 2186@samp{@var{fieldname}:}, as shown here: 2187 2188@smallexample 2189struct point p = @{ y: yvalue, x: xvalue @}; 2190@end smallexample 2191 2192Omitted fields are implicitly initialized the same as for objects 2193that have static storage duration. 2194 2195@cindex designators 2196The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a 2197@dfn{designator}. You can also use a designator (or the obsolete colon 2198syntax) when initializing a union, to specify which element of the union 2199should be used. For example, 2200 2201@smallexample 2202union foo @{ int i; double d; @}; 2203 2204union foo f = @{ .d = 4 @}; 2205@end smallexample 2206 2207@noindent 2208converts 4 to a @code{double} to store it in the union using 2209the second element. By contrast, casting 4 to type @code{union foo} 2210stores it into the union as the integer @code{i}, since it is 2211an integer. @xref{Cast to Union}. 2212 2213You can combine this technique of naming elements with ordinary C 2214initialization of successive elements. Each initializer element that 2215does not have a designator applies to the next consecutive element of the 2216array or structure. For example, 2217 2218@smallexample 2219int a[6] = @{ [1] = v1, v2, [4] = v4 @}; 2220@end smallexample 2221 2222@noindent 2223is equivalent to 2224 2225@smallexample 2226int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; 2227@end smallexample 2228 2229Labeling the elements of an array initializer is especially useful 2230when the indices are characters or belong to an @code{enum} type. 2231For example: 2232 2233@smallexample 2234int whitespace[256] 2235 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, 2236 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; 2237@end smallexample 2238 2239@cindex designator lists 2240You can also write a series of @samp{.@var{fieldname}} and 2241@samp{[@var{index}]} designators before an @samp{=} to specify a 2242nested subobject to initialize; the list is taken relative to the 2243subobject corresponding to the closest surrounding brace pair. For 2244example, with the @samp{struct point} declaration above: 2245 2246@smallexample 2247struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; 2248@end smallexample 2249 2250If the same field is initialized multiple times, or overlapping 2251fields of a union are initialized, the value from the last 2252initialization is used. When a field of a union is itself a structure, 2253the entire structure from the last field initialized is used. If any previous 2254initializer has side effect, it is unspecified whether the side effect 2255happens or not. Currently, GCC discards the side-effecting 2256initializer expressions and issues a warning. 2257 2258@node Case Ranges 2259@section Case Ranges 2260@cindex case ranges 2261@cindex ranges in case statements 2262 2263You can specify a range of consecutive values in a single @code{case} label, 2264like this: 2265 2266@smallexample 2267case @var{low} ... @var{high}: 2268@end smallexample 2269 2270@noindent 2271This has the same effect as the proper number of individual @code{case} 2272labels, one for each integer value from @var{low} to @var{high}, inclusive. 2273 2274This feature is especially useful for ranges of ASCII character codes: 2275 2276@smallexample 2277case 'A' ... 'Z': 2278@end smallexample 2279 2280@strong{Be careful:} Write spaces around the @code{...}, for otherwise 2281it may be parsed wrong when you use it with integer values. For example, 2282write this: 2283 2284@smallexample 2285case 1 ... 5: 2286@end smallexample 2287 2288@noindent 2289rather than this: 2290 2291@smallexample 2292case 1...5: 2293@end smallexample 2294 2295@node Cast to Union 2296@section Cast to a Union Type 2297@cindex cast to a union 2298@cindex union, casting to a 2299 2300A cast to a union type is a C extension not available in C++. It looks 2301just like ordinary casts with the constraint that the type specified is 2302a union type. You can specify the type either with the @code{union} 2303keyword or with a @code{typedef} name that refers to a union. The result 2304of a cast to a union is a temporary rvalue of the union type with a member 2305whose type matches that of the operand initialized to the value of 2306the operand. The effect of a cast to a union is similar to a compound 2307literal except that it yields an rvalue like standard casts do. 2308@xref{Compound Literals}. 2309 2310Expressions that may be cast to the union type are those whose type matches 2311at least one of the members of the union. Thus, given the following union 2312and variables: 2313 2314@smallexample 2315union foo @{ int i; double d; @}; 2316int x; 2317double y; 2318union foo z; 2319@end smallexample 2320 2321@noindent 2322both @code{x} and @code{y} can be cast to type @code{union foo} and 2323the following assignments 2324@smallexample 2325 z = (union foo) x; 2326 z = (union foo) y; 2327@end smallexample 2328are shorthand equivalents of these 2329@smallexample 2330 z = (union foo) @{ .i = x @}; 2331 z = (union foo) @{ .d = y @}; 2332@end smallexample 2333 2334However, @code{(union foo) FLT_MAX;} is not a valid cast because the union 2335has no member of type @code{float}. 2336 2337Using the cast as the right-hand side of an assignment to a variable of 2338union type is equivalent to storing in a member of the union with 2339the same type 2340 2341@smallexample 2342union foo u; 2343/* @r{@dots{}} */ 2344u = (union foo) x @equiv{} u.i = x 2345u = (union foo) y @equiv{} u.d = y 2346@end smallexample 2347 2348You can also use the union cast as a function argument: 2349 2350@smallexample 2351void hack (union foo); 2352/* @r{@dots{}} */ 2353hack ((union foo) x); 2354@end smallexample 2355 2356@node Mixed Declarations 2357@section Mixed Declarations and Code 2358@cindex mixed declarations and code 2359@cindex declarations, mixed with code 2360@cindex code, mixed with declarations 2361 2362ISO C99 and ISO C++ allow declarations and code to be freely mixed 2363within compound statements. As an extension, GNU C also allows this in 2364C90 mode. For example, you could do: 2365 2366@smallexample 2367int i; 2368/* @r{@dots{}} */ 2369i++; 2370int j = i + 2; 2371@end smallexample 2372 2373Each identifier is visible from where it is declared until the end of 2374the enclosing block. 2375 2376@node Function Attributes 2377@section Declaring Attributes of Functions 2378@cindex function attributes 2379@cindex declaring attributes of functions 2380@cindex @code{volatile} applied to function 2381@cindex @code{const} applied to function 2382 2383In GNU C and C++, you can use function attributes to specify certain 2384function properties that may help the compiler optimize calls or 2385check code more carefully for correctness. For example, you 2386can use attributes to specify that a function never returns 2387(@code{noreturn}), returns a value depending only on the values of 2388its arguments (@code{const}), or has @code{printf}-style arguments 2389(@code{format}). 2390 2391You can also use attributes to control memory placement, code 2392generation options or call/return conventions within the function 2393being annotated. Many of these attributes are target-specific. For 2394example, many targets support attributes for defining interrupt 2395handler functions, which typically must follow special register usage 2396and return conventions. Such attributes are described in the subsection 2397for each target. However, a considerable number of attributes are 2398supported by most, if not all targets. Those are described in 2399the @ref{Common Function Attributes} section. 2400 2401Function attributes are introduced by the @code{__attribute__} keyword 2402in the declaration of a function, followed by an attribute specification 2403enclosed in double parentheses. You can specify multiple attributes in 2404a declaration by separating them by commas within the double parentheses 2405or by immediately following one attribute specification with another. 2406@xref{Attribute Syntax}, for the exact rules on attribute syntax and 2407placement. Compatible attribute specifications on distinct declarations 2408of the same function are merged. An attribute specification that is not 2409compatible with attributes already applied to a declaration of the same 2410function is ignored with a warning. 2411 2412Some function attributes take one or more arguments that refer to 2413the function's parameters by their positions within the function parameter 2414list. Such attribute arguments are referred to as @dfn{positional arguments}. 2415Unless specified otherwise, positional arguments that specify properties 2416of parameters with pointer types can also specify the same properties of 2417the implicit C++ @code{this} argument in non-static member functions, and 2418of parameters of reference to a pointer type. For ordinary functions, 2419position one refers to the first parameter on the list. In C++ non-static 2420member functions, position one refers to the implicit @code{this} pointer. 2421The same restrictions and effects apply to function attributes used with 2422ordinary functions or C++ member functions. 2423 2424GCC also supports attributes on 2425variable declarations (@pxref{Variable Attributes}), 2426labels (@pxref{Label Attributes}), 2427enumerators (@pxref{Enumerator Attributes}), 2428statements (@pxref{Statement Attributes}), 2429and types (@pxref{Type Attributes}). 2430 2431There is some overlap between the purposes of attributes and pragmas 2432(@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been 2433found convenient to use @code{__attribute__} to achieve a natural 2434attachment of attributes to their corresponding declarations, whereas 2435@code{#pragma} is of use for compatibility with other compilers 2436or constructs that do not naturally form part of the grammar. 2437 2438In addition to the attributes documented here, 2439GCC plugins may provide their own attributes. 2440 2441@menu 2442* Common Function Attributes:: 2443* AArch64 Function Attributes:: 2444* AMD GCN Function Attributes:: 2445* ARC Function Attributes:: 2446* ARM Function Attributes:: 2447* AVR Function Attributes:: 2448* Blackfin Function Attributes:: 2449* BPF Function Attributes:: 2450* CR16 Function Attributes:: 2451* C-SKY Function Attributes:: 2452* Epiphany Function Attributes:: 2453* H8/300 Function Attributes:: 2454* IA-64 Function Attributes:: 2455* M32C Function Attributes:: 2456* M32R/D Function Attributes:: 2457* m68k Function Attributes:: 2458* MCORE Function Attributes:: 2459* MeP Function Attributes:: 2460* MicroBlaze Function Attributes:: 2461* Microsoft Windows Function Attributes:: 2462* MIPS Function Attributes:: 2463* MSP430 Function Attributes:: 2464* NDS32 Function Attributes:: 2465* Nios II Function Attributes:: 2466* Nvidia PTX Function Attributes:: 2467* PowerPC Function Attributes:: 2468* RISC-V Function Attributes:: 2469* RL78 Function Attributes:: 2470* RX Function Attributes:: 2471* S/390 Function Attributes:: 2472* SH Function Attributes:: 2473* Symbian OS Function Attributes:: 2474* V850 Function Attributes:: 2475* Visium Function Attributes:: 2476* x86 Function Attributes:: 2477* Xstormy16 Function Attributes:: 2478@end menu 2479 2480@node Common Function Attributes 2481@subsection Common Function Attributes 2482 2483The following attributes are supported on most targets. 2484 2485@table @code 2486@c Keep this table alphabetized by attribute name. Treat _ as space. 2487 2488@item access 2489@itemx access (@var{access-mode}, @var{ref-index}) 2490@itemx access (@var{access-mode}, @var{ref-index}, @var{size-index}) 2491 2492The @code{access} attribute enables the detection of invalid or unsafe 2493accesses by functions to which they apply or their callers, as well as 2494write-only accesses to objects that are never read from. Such accesses 2495may be diagnosed by warnings such as @option{-Wstringop-overflow}, 2496@option{-Wuninitialized}, @option{-Wunused}, and others. 2497 2498The @code{access} attribute specifies that a function to whose by-reference 2499arguments the attribute applies accesses the referenced object according to 2500@var{access-mode}. The @var{access-mode} argument is required and must be 2501one of three names: @code{read_only}, @code{read_write}, or @code{write_only}. 2502The remaining two are positional arguments. 2503 2504The required @var{ref-index} positional argument denotes a function 2505argument of pointer (or in C++, reference) type that is subject to 2506the access. The same pointer argument can be referenced by at most one 2507distinct @code{access} attribute. 2508 2509The optional @var{size-index} positional argument denotes a function 2510argument of integer type that specifies the maximum size of the access. 2511The size is the number of elements of the type referenced by @var{ref-index}, 2512or the number of bytes when the pointer type is @code{void*}. When no 2513@var{size-index} argument is specified, the pointer argument must be either 2514null or point to a space that is suitably aligned and large for at least one 2515object of the referenced type (this implies that a past-the-end pointer is 2516not a valid argument). The actual size of the access may be less but it 2517must not be more. 2518 2519The @code{read_only} access mode specifies that the pointer to which it 2520applies is used to read the referenced object but not write to it. Unless 2521the argument specifying the size of the access denoted by @var{size-index} 2522is zero, the referenced object must be initialized. The mode implies 2523a stronger guarantee than the @code{const} qualifier which, when cast away 2524from a pointer, does not prevent the pointed-to object from being modified. 2525Examples of the use of the @code{read_only} access mode is the argument to 2526the @code{puts} function, or the second and third arguments to 2527the @code{memcpy} function. 2528 2529@smallexample 2530__attribute__ ((access (read_only, 1))) int puts (const char*); 2531__attribute__ ((access (read_only, 1, 2))) void* memcpy (void*, const void*, size_t); 2532@end smallexample 2533 2534The @code{read_write} access mode applies to arguments of pointer types 2535without the @code{const} qualifier. It specifies that the pointer to which 2536it applies is used to both read and write the referenced object. Unless 2537the argument specifying the size of the access denoted by @var{size-index} 2538is zero, the object referenced by the pointer must be initialized. An example 2539of the use of the @code{read_write} access mode is the first argument to 2540the @code{strcat} function. 2541 2542@smallexample 2543__attribute__ ((access (read_write, 1), access (read_only, 2))) char* strcat (char*, const char*); 2544@end smallexample 2545 2546The @code{write_only} access mode applies to arguments of pointer types 2547without the @code{const} qualifier. It specifies that the pointer to which 2548it applies is used to write to the referenced object but not read from it. 2549The object referenced by the pointer need not be initialized. An example 2550of the use of the @code{write_only} access mode is the first argument to 2551the @code{strcpy} function, or the first two arguments to the @code{fgets} 2552function. 2553 2554@smallexample 2555__attribute__ ((access (write_only, 1), access (read_only, 2))) char* strcpy (char*, const char*); 2556__attribute__ ((access (write_only, 1, 2), access (read_write, 3))) int fgets (char*, int, FILE*); 2557@end smallexample 2558 2559@item alias ("@var{target}") 2560@cindex @code{alias} function attribute 2561The @code{alias} attribute causes the declaration to be emitted as an alias 2562for another symbol, which must have been previously declared with the same 2563type, and for variables, also the same size and alignment. Declaring an alias 2564with a different type than the target is undefined and may be diagnosed. As 2565an example, the following declarations: 2566 2567@smallexample 2568void __f () @{ /* @r{Do something.} */; @} 2569void f () __attribute__ ((weak, alias ("__f"))); 2570@end smallexample 2571 2572@noindent 2573define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name 2574for the target must be used. It is an error if @samp{__f} is not defined in 2575the same translation unit. 2576 2577This attribute requires assembler and object file support, 2578and may not be available on all targets. 2579 2580@item aligned 2581@itemx aligned (@var{alignment}) 2582@cindex @code{aligned} function attribute 2583The @code{aligned} attribute specifies a minimum alignment for 2584the first instruction of the function, measured in bytes. When specified, 2585@var{alignment} must be an integer constant power of 2. Specifying no 2586@var{alignment} argument implies the ideal alignment for the target. 2587The @code{__alignof__} operator can be used to determine what that is 2588(@pxref{Alignment}). The attribute has no effect when a definition for 2589the function is not provided in the same translation unit. 2590 2591The attribute cannot be used to decrease the alignment of a function 2592previously declared with a more restrictive alignment; only to increase 2593it. Attempts to do otherwise are diagnosed. Some targets specify 2594a minimum default alignment for functions that is greater than 1. On 2595such targets, specifying a less restrictive alignment is silently ignored. 2596Using the attribute overrides the effect of the @option{-falign-functions} 2597(@pxref{Optimize Options}) option for this function. 2598 2599Note that the effectiveness of @code{aligned} attributes may be 2600limited by inherent limitations in the system linker 2601and/or object file format. On some systems, the 2602linker is only able to arrange for functions to be aligned up to a 2603certain maximum alignment. (For some linkers, the maximum supported 2604alignment may be very very small.) See your linker documentation for 2605further information. 2606 2607The @code{aligned} attribute can also be used for variables and fields 2608(@pxref{Variable Attributes}.) 2609 2610@item alloc_align (@var{position}) 2611@cindex @code{alloc_align} function attribute 2612The @code{alloc_align} attribute may be applied to a function that 2613returns a pointer and takes at least one argument of an integer or 2614enumerated type. 2615It indicates that the returned pointer is aligned on a boundary given 2616by the function argument at @var{position}. Meaningful alignments are 2617powers of 2 greater than one. GCC uses this information to improve 2618pointer alignment analysis. 2619 2620The function parameter denoting the allocated alignment is specified by 2621one constant integer argument whose number is the argument of the attribute. 2622Argument numbering starts at one. 2623 2624For instance, 2625 2626@smallexample 2627void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1))); 2628@end smallexample 2629 2630@noindent 2631declares that @code{my_memalign} returns memory with minimum alignment 2632given by parameter 1. 2633 2634@item alloc_size (@var{position}) 2635@itemx alloc_size (@var{position-1}, @var{position-2}) 2636@cindex @code{alloc_size} function attribute 2637The @code{alloc_size} attribute may be applied to a function that 2638returns a pointer and takes at least one argument of an integer or 2639enumerated type. 2640It indicates that the returned pointer points to memory whose size is 2641given by the function argument at @var{position-1}, or by the product 2642of the arguments at @var{position-1} and @var{position-2}. Meaningful 2643sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this 2644information to improve the results of @code{__builtin_object_size}. 2645 2646The function parameter(s) denoting the allocated size are specified by 2647one or two integer arguments supplied to the attribute. The allocated size 2648is either the value of the single function argument specified or the product 2649of the two function arguments specified. Argument numbering starts at 2650one for ordinary functions, and at two for C++ non-static member functions. 2651 2652For instance, 2653 2654@smallexample 2655void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2))); 2656void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2))); 2657@end smallexample 2658 2659@noindent 2660declares that @code{my_calloc} returns memory of the size given by 2661the product of parameter 1 and 2 and that @code{my_realloc} returns memory 2662of the size given by parameter 2. 2663 2664@item always_inline 2665@cindex @code{always_inline} function attribute 2666Generally, functions are not inlined unless optimization is specified. 2667For functions declared inline, this attribute inlines the function 2668independent of any restrictions that otherwise apply to inlining. 2669Failure to inline such a function is diagnosed as an error. 2670Note that if such a function is called indirectly the compiler may 2671or may not inline it depending on optimization level and a failure 2672to inline an indirect call may or may not be diagnosed. 2673 2674@item artificial 2675@cindex @code{artificial} function attribute 2676This attribute is useful for small inline wrappers that if possible 2677should appear during debugging as a unit. Depending on the debug 2678info format it either means marking the function as artificial 2679or using the caller location for all instructions within the inlined 2680body. 2681 2682@item assume_aligned (@var{alignment}) 2683@itemx assume_aligned (@var{alignment}, @var{offset}) 2684@cindex @code{assume_aligned} function attribute 2685The @code{assume_aligned} attribute may be applied to a function that 2686returns a pointer. It indicates that the returned pointer is aligned 2687on a boundary given by @var{alignment}. If the attribute has two 2688arguments, the second argument is misalignment @var{offset}. Meaningful 2689values of @var{alignment} are powers of 2 greater than one. Meaningful 2690values of @var{offset} are greater than zero and less than @var{alignment}. 2691 2692For instance 2693 2694@smallexample 2695void* my_alloc1 (size_t) __attribute__((assume_aligned (16))); 2696void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8))); 2697@end smallexample 2698 2699@noindent 2700declares that @code{my_alloc1} returns 16-byte aligned pointers and 2701that @code{my_alloc2} returns a pointer whose value modulo 32 is equal 2702to 8. 2703 2704@item cold 2705@cindex @code{cold} function attribute 2706The @code{cold} attribute on functions is used to inform the compiler that 2707the function is unlikely to be executed. The function is optimized for 2708size rather than speed and on many targets it is placed into a special 2709subsection of the text section so all cold functions appear close together, 2710improving code locality of non-cold parts of program. The paths leading 2711to calls of cold functions within code are marked as unlikely by the branch 2712prediction mechanism. It is thus useful to mark functions used to handle 2713unlikely conditions, such as @code{perror}, as cold to improve optimization 2714of hot functions that do call marked functions in rare occasions. 2715 2716When profile feedback is available, via @option{-fprofile-use}, cold functions 2717are automatically detected and this attribute is ignored. 2718 2719@item const 2720@cindex @code{const} function attribute 2721@cindex functions that have no side effects 2722Calls to functions whose return value is not affected by changes to 2723the observable state of the program and that have no observable effects 2724on such state other than to return a value may lend themselves to 2725optimizations such as common subexpression elimination. Declaring such 2726functions with the @code{const} attribute allows GCC to avoid emitting 2727some calls in repeated invocations of the function with the same argument 2728values. 2729 2730For example, 2731 2732@smallexample 2733int square (int) __attribute__ ((const)); 2734@end smallexample 2735 2736@noindent 2737tells GCC that subsequent calls to function @code{square} with the same 2738argument value can be replaced by the result of the first call regardless 2739of the statements in between. 2740 2741The @code{const} attribute prohibits a function from reading objects 2742that affect its return value between successive invocations. However, 2743functions declared with the attribute can safely read objects that do 2744not change their return value, such as non-volatile constants. 2745 2746The @code{const} attribute imposes greater restrictions on a function's 2747definition than the similar @code{pure} attribute. Declaring the same 2748function with both the @code{const} and the @code{pure} attribute is 2749diagnosed. Because a const function cannot have any observable side 2750effects it does not make sense for it to return @code{void}. Declaring 2751such a function is diagnosed. 2752 2753@cindex pointer arguments 2754Note that a function that has pointer arguments and examines the data 2755pointed to must @emph{not} be declared @code{const} if the pointed-to 2756data might change between successive invocations of the function. In 2757general, since a function cannot distinguish data that might change 2758from data that cannot, const functions should never take pointer or, 2759in C++, reference arguments. Likewise, a function that calls a non-const 2760function usually must not be const itself. 2761 2762@item constructor 2763@itemx destructor 2764@itemx constructor (@var{priority}) 2765@itemx destructor (@var{priority}) 2766@cindex @code{constructor} function attribute 2767@cindex @code{destructor} function attribute 2768The @code{constructor} attribute causes the function to be called 2769automatically before execution enters @code{main ()}. Similarly, the 2770@code{destructor} attribute causes the function to be called 2771automatically after @code{main ()} completes or @code{exit ()} is 2772called. Functions with these attributes are useful for 2773initializing data that is used implicitly during the execution of 2774the program. 2775 2776On some targets the attributes also accept an integer argument to 2777specify a priority to control the order in which constructor and 2778destructor functions are run. A constructor 2779with a smaller priority number runs before a constructor with a larger 2780priority number; the opposite relationship holds for destructors. So, 2781if you have a constructor that allocates a resource and a destructor 2782that deallocates the same resource, both functions typically have the 2783same priority. The priorities for constructor and destructor 2784functions are the same as those specified for namespace-scope C++ 2785objects (@pxref{C++ Attributes}). However, at present, the order in which 2786constructors for C++ objects with static storage duration and functions 2787decorated with attribute @code{constructor} are invoked is unspecified. 2788In mixed declarations, attribute @code{init_priority} can be used to 2789impose a specific ordering. 2790 2791Using the argument forms of the @code{constructor} and @code{destructor} 2792attributes on targets where the feature is not supported is rejected with 2793an error. 2794 2795@item copy 2796@itemx copy (@var{function}) 2797@cindex @code{copy} function attribute 2798The @code{copy} attribute applies the set of attributes with which 2799@var{function} has been declared to the declaration of the function 2800to which the attribute is applied. The attribute is designed for 2801libraries that define aliases or function resolvers that are expected 2802to specify the same set of attributes as their targets. The @code{copy} 2803attribute can be used with functions, variables, or types. However, 2804the kind of symbol to which the attribute is applied (either function 2805or variable) must match the kind of symbol to which the argument refers. 2806The @code{copy} attribute copies only syntactic and semantic attributes 2807but not attributes that affect a symbol's linkage or visibility such as 2808@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} 2809and @code{target_clones} attribute are also not copied. 2810@xref{Common Type Attributes}. 2811@xref{Common Variable Attributes}. 2812 2813For example, the @var{StrongAlias} macro below makes use of the @code{alias} 2814and @code{copy} attributes to define an alias named @var{alloc} for function 2815@var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and 2816@var{nothrow}. Thanks to the @code{__typeof__} operator the alias has 2817the same type as the target function. As a result of the @code{copy} 2818attribute the alias also shares the same attributes as the target. 2819 2820@smallexample 2821#define StrongAlias(TargetFunc, AliasDecl) \ 2822 extern __typeof__ (TargetFunc) AliasDecl \ 2823 __attribute__ ((alias (#TargetFunc), copy (TargetFunc))); 2824 2825extern __attribute__ ((alloc_size (1), malloc, nothrow)) 2826 void* allocate (size_t); 2827StrongAlias (allocate, alloc); 2828@end smallexample 2829 2830@item deprecated 2831@itemx deprecated (@var{msg}) 2832@cindex @code{deprecated} function attribute 2833The @code{deprecated} attribute results in a warning if the function 2834is used anywhere in the source file. This is useful when identifying 2835functions that are expected to be removed in a future version of a 2836program. The warning also includes the location of the declaration 2837of the deprecated function, to enable users to easily find further 2838information about why the function is deprecated, or what they should 2839do instead. Note that the warnings only occurs for uses: 2840 2841@smallexample 2842int old_fn () __attribute__ ((deprecated)); 2843int old_fn (); 2844int (*fn_ptr)() = old_fn; 2845@end smallexample 2846 2847@noindent 2848results in a warning on line 3 but not line 2. The optional @var{msg} 2849argument, which must be a string, is printed in the warning if 2850present. 2851 2852The @code{deprecated} attribute can also be used for variables and 2853types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) 2854 2855The message attached to the attribute is affected by the setting of 2856the @option{-fmessage-length} option. 2857 2858@item error ("@var{message}") 2859@itemx warning ("@var{message}") 2860@cindex @code{error} function attribute 2861@cindex @code{warning} function attribute 2862If the @code{error} or @code{warning} attribute 2863is used on a function declaration and a call to such a function 2864is not eliminated through dead code elimination or other optimizations, 2865an error or warning (respectively) that includes @var{message} is diagnosed. 2866This is useful 2867for compile-time checking, especially together with @code{__builtin_constant_p} 2868and inline functions where checking the inline function arguments is not 2869possible through @code{extern char [(condition) ? 1 : -1];} tricks. 2870 2871While it is possible to leave the function undefined and thus invoke 2872a link failure (to define the function with 2873a message in @code{.gnu.warning*} section), 2874when using these attributes the problem is diagnosed 2875earlier and with exact location of the call even in presence of inline 2876functions or when not emitting debugging information. 2877 2878@item externally_visible 2879@cindex @code{externally_visible} function attribute 2880This attribute, attached to a global variable or function, nullifies 2881the effect of the @option{-fwhole-program} command-line option, so the 2882object remains visible outside the current compilation unit. 2883 2884If @option{-fwhole-program} is used together with @option{-flto} and 2885@command{gold} is used as the linker plugin, 2886@code{externally_visible} attributes are automatically added to functions 2887(not variable yet due to a current @command{gold} issue) 2888that are accessed outside of LTO objects according to resolution file 2889produced by @command{gold}. 2890For other linkers that cannot generate resolution file, 2891explicit @code{externally_visible} attributes are still necessary. 2892 2893@item flatten 2894@cindex @code{flatten} function attribute 2895Generally, inlining into a function is limited. For a function marked with 2896this attribute, every call inside this function is inlined, if possible. 2897Functions declared with attribute @code{noinline} and similar are not 2898inlined. Whether the function itself is considered for inlining depends 2899on its size and the current inlining parameters. 2900 2901@item format (@var{archetype}, @var{string-index}, @var{first-to-check}) 2902@cindex @code{format} function attribute 2903@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments 2904@opindex Wformat 2905The @code{format} attribute specifies that a function takes @code{printf}, 2906@code{scanf}, @code{strftime} or @code{strfmon} style arguments that 2907should be type-checked against a format string. For example, the 2908declaration: 2909 2910@smallexample 2911extern int 2912my_printf (void *my_object, const char *my_format, ...) 2913 __attribute__ ((format (printf, 2, 3))); 2914@end smallexample 2915 2916@noindent 2917causes the compiler to check the arguments in calls to @code{my_printf} 2918for consistency with the @code{printf} style format string argument 2919@code{my_format}. 2920 2921The parameter @var{archetype} determines how the format string is 2922interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}, 2923@code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or 2924@code{strfmon}. (You can also use @code{__printf__}, 2925@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On 2926MinGW targets, @code{ms_printf}, @code{ms_scanf}, and 2927@code{ms_strftime} are also present. 2928@var{archetype} values such as @code{printf} refer to the formats accepted 2929by the system's C runtime library, 2930while values prefixed with @samp{gnu_} always refer 2931to the formats accepted by the GNU C Library. On Microsoft Windows 2932targets, values prefixed with @samp{ms_} refer to the formats accepted by the 2933@file{msvcrt.dll} library. 2934The parameter @var{string-index} 2935specifies which argument is the format string argument (starting 2936from 1), while @var{first-to-check} is the number of the first 2937argument to check against the format string. For functions 2938where the arguments are not available to be checked (such as 2939@code{vprintf}), specify the third parameter as zero. In this case the 2940compiler only checks the format string for consistency. For 2941@code{strftime} formats, the third parameter is required to be zero. 2942Since non-static C++ methods have an implicit @code{this} argument, the 2943arguments of such methods should be counted from two, not one, when 2944giving values for @var{string-index} and @var{first-to-check}. 2945 2946In the example above, the format string (@code{my_format}) is the second 2947argument of the function @code{my_print}, and the arguments to check 2948start with the third argument, so the correct parameters for the format 2949attribute are 2 and 3. 2950 2951@opindex ffreestanding 2952@opindex fno-builtin 2953The @code{format} attribute allows you to identify your own functions 2954that take format strings as arguments, so that GCC can check the 2955calls to these functions for errors. The compiler always (unless 2956@option{-ffreestanding} or @option{-fno-builtin} is used) checks formats 2957for the standard library functions @code{printf}, @code{fprintf}, 2958@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime}, 2959@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such 2960warnings are requested (using @option{-Wformat}), so there is no need to 2961modify the header file @file{stdio.h}. In C99 mode, the functions 2962@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and 2963@code{vsscanf} are also checked. Except in strictly conforming C 2964standard modes, the X/Open function @code{strfmon} is also checked as 2965are @code{printf_unlocked} and @code{fprintf_unlocked}. 2966@xref{C Dialect Options,,Options Controlling C Dialect}. 2967 2968For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is 2969recognized in the same context. Declarations including these format attributes 2970are parsed for correct syntax, however the result of checking of such format 2971strings is not yet defined, and is not carried out by this version of the 2972compiler. 2973 2974The target may also provide additional types of format checks. 2975@xref{Target Format Checks,,Format Checks Specific to Particular 2976Target Machines}. 2977 2978@item format_arg (@var{string-index}) 2979@cindex @code{format_arg} function attribute 2980@opindex Wformat-nonliteral 2981The @code{format_arg} attribute specifies that a function takes one or 2982more format strings for a @code{printf}, @code{scanf}, @code{strftime} or 2983@code{strfmon} style function and modifies it (for example, to translate 2984it into another language), so the result can be passed to a 2985@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style 2986function (with the remaining arguments to the format function the same 2987as they would have been for the unmodified string). Multiple 2988@code{format_arg} attributes may be applied to the same function, each 2989designating a distinct parameter as a format string. For example, the 2990declaration: 2991 2992@smallexample 2993extern char * 2994my_dgettext (char *my_domain, const char *my_format) 2995 __attribute__ ((format_arg (2))); 2996@end smallexample 2997 2998@noindent 2999causes the compiler to check the arguments in calls to a @code{printf}, 3000@code{scanf}, @code{strftime} or @code{strfmon} type function, whose 3001format string argument is a call to the @code{my_dgettext} function, for 3002consistency with the format string argument @code{my_format}. If the 3003@code{format_arg} attribute had not been specified, all the compiler 3004could tell in such calls to format functions would be that the format 3005string argument is not constant; this would generate a warning when 3006@option{-Wformat-nonliteral} is used, but the calls could not be checked 3007without the attribute. 3008 3009In calls to a function declared with more than one @code{format_arg} 3010attribute, each with a distinct argument value, the corresponding 3011actual function arguments are checked against all format strings 3012designated by the attributes. This capability is designed to support 3013the GNU @code{ngettext} family of functions. 3014 3015The parameter @var{string-index} specifies which argument is the format 3016string argument (starting from one). Since non-static C++ methods have 3017an implicit @code{this} argument, the arguments of such methods should 3018be counted from two. 3019 3020The @code{format_arg} attribute allows you to identify your own 3021functions that modify format strings, so that GCC can check the 3022calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} 3023type function whose operands are a call to one of your own function. 3024The compiler always treats @code{gettext}, @code{dgettext}, and 3025@code{dcgettext} in this manner except when strict ISO C support is 3026requested by @option{-ansi} or an appropriate @option{-std} option, or 3027@option{-ffreestanding} or @option{-fno-builtin} 3028is used. @xref{C Dialect Options,,Options 3029Controlling C Dialect}. 3030 3031For Objective-C dialects, the @code{format-arg} attribute may refer to an 3032@code{NSString} reference for compatibility with the @code{format} attribute 3033above. 3034 3035The target may also allow additional types in @code{format-arg} attributes. 3036@xref{Target Format Checks,,Format Checks Specific to Particular 3037Target Machines}. 3038 3039@item gnu_inline 3040@cindex @code{gnu_inline} function attribute 3041This attribute should be used with a function that is also declared 3042with the @code{inline} keyword. It directs GCC to treat the function 3043as if it were defined in gnu90 mode even when compiling in C99 or 3044gnu99 mode. 3045 3046If the function is declared @code{extern}, then this definition of the 3047function is used only for inlining. In no case is the function 3048compiled as a standalone function, not even if you take its address 3049explicitly. Such an address becomes an external reference, as if you 3050had only declared the function, and had not defined it. This has 3051almost the effect of a macro. The way to use this is to put a 3052function definition in a header file with this attribute, and put 3053another copy of the function, without @code{extern}, in a library 3054file. The definition in the header file causes most calls to the 3055function to be inlined. If any uses of the function remain, they 3056refer to the single copy in the library. Note that the two 3057definitions of the functions need not be precisely the same, although 3058if they do not have the same effect your program may behave oddly. 3059 3060In C, if the function is neither @code{extern} nor @code{static}, then 3061the function is compiled as a standalone function, as well as being 3062inlined where possible. 3063 3064This is how GCC traditionally handled functions declared 3065@code{inline}. Since ISO C99 specifies a different semantics for 3066@code{inline}, this function attribute is provided as a transition 3067measure and as a useful feature in its own right. This attribute is 3068available in GCC 4.1.3 and later. It is available if either of the 3069preprocessor macros @code{__GNUC_GNU_INLINE__} or 3070@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline 3071Function is As Fast As a Macro}. 3072 3073In C++, this attribute does not depend on @code{extern} in any way, 3074but it still requires the @code{inline} keyword to enable its special 3075behavior. 3076 3077@item hot 3078@cindex @code{hot} function attribute 3079The @code{hot} attribute on a function is used to inform the compiler that 3080the function is a hot spot of the compiled program. The function is 3081optimized more aggressively and on many targets it is placed into a special 3082subsection of the text section so all hot functions appear close together, 3083improving locality. 3084 3085When profile feedback is available, via @option{-fprofile-use}, hot functions 3086are automatically detected and this attribute is ignored. 3087 3088@item ifunc ("@var{resolver}") 3089@cindex @code{ifunc} function attribute 3090@cindex indirect functions 3091@cindex functions that are dynamically resolved 3092The @code{ifunc} attribute is used to mark a function as an indirect 3093function using the STT_GNU_IFUNC symbol type extension to the ELF 3094standard. This allows the resolution of the symbol value to be 3095determined dynamically at load time, and an optimized version of the 3096routine to be selected for the particular processor or other system 3097characteristics determined then. To use this attribute, first define 3098the implementation functions available, and a resolver function that 3099returns a pointer to the selected implementation function. The 3100implementation functions' declarations must match the API of the 3101function being implemented. The resolver should be declared to 3102be a function taking no arguments and returning a pointer to 3103a function of the same type as the implementation. For example: 3104 3105@smallexample 3106void *my_memcpy (void *dst, const void *src, size_t len) 3107@{ 3108 @dots{} 3109 return dst; 3110@} 3111 3112static void * (*resolve_memcpy (void))(void *, const void *, size_t) 3113@{ 3114 return my_memcpy; // we will just always select this routine 3115@} 3116@end smallexample 3117 3118@noindent 3119The exported header file declaring the function the user calls would 3120contain: 3121 3122@smallexample 3123extern void *memcpy (void *, const void *, size_t); 3124@end smallexample 3125 3126@noindent 3127allowing the user to call @code{memcpy} as a regular function, unaware of 3128the actual implementation. Finally, the indirect function needs to be 3129defined in the same translation unit as the resolver function: 3130 3131@smallexample 3132void *memcpy (void *, const void *, size_t) 3133 __attribute__ ((ifunc ("resolve_memcpy"))); 3134@end smallexample 3135 3136In C++, the @code{ifunc} attribute takes a string that is the mangled name 3137of the resolver function. A C++ resolver for a non-static member function 3138of class @code{C} should be declared to return a pointer to a non-member 3139function taking pointer to @code{C} as the first argument, followed by 3140the same arguments as of the implementation function. G++ checks 3141the signatures of the two functions and issues 3142a @option{-Wattribute-alias} warning for mismatches. To suppress a warning 3143for the necessary cast from a pointer to the implementation member function 3144to the type of the corresponding non-member function use 3145the @option{-Wno-pmf-conversions} option. For example: 3146 3147@smallexample 3148class S 3149@{ 3150private: 3151 int debug_impl (int); 3152 int optimized_impl (int); 3153 3154 typedef int Func (S*, int); 3155 3156 static Func* resolver (); 3157public: 3158 3159 int interface (int); 3160@}; 3161 3162int S::debug_impl (int) @{ /* @r{@dots{}} */ @} 3163int S::optimized_impl (int) @{ /* @r{@dots{}} */ @} 3164 3165S::Func* S::resolver () 3166@{ 3167 int (S::*pimpl) (int) 3168 = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl; 3169 3170 // Cast triggers -Wno-pmf-conversions. 3171 return reinterpret_cast<Func*>(pimpl); 3172@} 3173 3174int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv"))); 3175@end smallexample 3176 3177Indirect functions cannot be weak. Binutils version 2.20.1 or higher 3178and GNU C Library version 2.11.1 are required to use this feature. 3179 3180@item interrupt 3181@itemx interrupt_handler 3182Many GCC back ends support attributes to indicate that a function is 3183an interrupt handler, which tells the compiler to generate function 3184entry and exit sequences that differ from those from regular 3185functions. The exact syntax and behavior are target-specific; 3186refer to the following subsections for details. 3187 3188@item leaf 3189@cindex @code{leaf} function attribute 3190Calls to external functions with this attribute must return to the 3191current compilation unit only by return or by exception handling. In 3192particular, a leaf function is not allowed to invoke callback functions 3193passed to it from the current compilation unit, directly call functions 3194exported by the unit, or @code{longjmp} into the unit. Leaf functions 3195might still call functions from other compilation units and thus they 3196are not necessarily leaf in the sense that they contain no function 3197calls at all. 3198 3199The attribute is intended for library functions to improve dataflow 3200analysis. The compiler takes the hint that any data not escaping the 3201current compilation unit cannot be used or modified by the leaf 3202function. For example, the @code{sin} function is a leaf function, but 3203@code{qsort} is not. 3204 3205Note that leaf functions might indirectly run a signal handler defined 3206in the current compilation unit that uses static variables. Similarly, 3207when lazy symbol resolution is in effect, leaf functions might invoke 3208indirect functions whose resolver function or implementation function is 3209defined in the current compilation unit and uses static variables. There 3210is no standard-compliant way to write such a signal handler, resolver 3211function, or implementation function, and the best that you can do is to 3212remove the @code{leaf} attribute or mark all such static variables 3213@code{volatile}. Lastly, for ELF-based systems that support symbol 3214interposition, care should be taken that functions defined in the 3215current compilation unit do not unexpectedly interpose other symbols 3216based on the defined standards mode and defined feature test macros; 3217otherwise an inadvertent callback would be added. 3218 3219The attribute has no effect on functions defined within the current 3220compilation unit. This is to allow easy merging of multiple compilation 3221units into one, for example, by using the link-time optimization. For 3222this reason the attribute is not allowed on types to annotate indirect 3223calls. 3224 3225@item malloc 3226@cindex @code{malloc} function attribute 3227@cindex functions that behave like malloc 3228This tells the compiler that a function is @code{malloc}-like, i.e., 3229that the pointer @var{P} returned by the function cannot alias any 3230other pointer valid when the function returns, and moreover no 3231pointers to valid objects occur in any storage addressed by @var{P}. In 3232addition, GCC predicts that a function with the attribute returns 3233non-null in most cases. 3234 3235Using the attribute is designed to improve optimization 3236by relying on the aliasing property it implies. Functions like @code{malloc} 3237and @code{calloc} have this property because they return a pointer to 3238uninitialized or zeroed-out, newly obtained storage. However, functions 3239like @code{realloc} do not have this property, as they may return pointers 3240to storage containing pointers to existing objects. Additionally, since 3241all such functions are assumed to return null only infrequently, callers 3242can be optimized based on that assumption. 3243 3244@item no_icf 3245@cindex @code{no_icf} function attribute 3246This function attribute prevents a functions from being merged with another 3247semantically equivalent function. 3248 3249@item no_instrument_function 3250@cindex @code{no_instrument_function} function attribute 3251@opindex finstrument-functions 3252@opindex p 3253@opindex pg 3254If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are 3255given, profiling function calls are 3256generated at entry and exit of most user-compiled functions. 3257Functions with this attribute are not so instrumented. 3258 3259@item no_profile_instrument_function 3260@cindex @code{no_profile_instrument_function} function attribute 3261The @code{no_profile_instrument_function} attribute on functions is used 3262to inform the compiler that it should not process any profile feedback based 3263optimization code instrumentation. 3264 3265@item no_reorder 3266@cindex @code{no_reorder} function attribute 3267Do not reorder functions or variables marked @code{no_reorder} 3268against each other or top level assembler statements the executable. 3269The actual order in the program will depend on the linker command 3270line. Static variables marked like this are also not removed. 3271This has a similar effect 3272as the @option{-fno-toplevel-reorder} option, but only applies to the 3273marked symbols. 3274 3275@item no_sanitize ("@var{sanitize_option}") 3276@cindex @code{no_sanitize} function attribute 3277The @code{no_sanitize} attribute on functions is used 3278to inform the compiler that it should not do sanitization of any option 3279mentioned in @var{sanitize_option}. A list of values acceptable by 3280the @option{-fsanitize} option can be provided. 3281 3282@smallexample 3283void __attribute__ ((no_sanitize ("alignment", "object-size"))) 3284f () @{ /* @r{Do something.} */; @} 3285void __attribute__ ((no_sanitize ("alignment,object-size"))) 3286g () @{ /* @r{Do something.} */; @} 3287@end smallexample 3288 3289@item no_sanitize_address 3290@itemx no_address_safety_analysis 3291@cindex @code{no_sanitize_address} function attribute 3292The @code{no_sanitize_address} attribute on functions is used 3293to inform the compiler that it should not instrument memory accesses 3294in the function when compiling with the @option{-fsanitize=address} option. 3295The @code{no_address_safety_analysis} is a deprecated alias of the 3296@code{no_sanitize_address} attribute, new code should use 3297@code{no_sanitize_address}. 3298 3299@item no_sanitize_thread 3300@cindex @code{no_sanitize_thread} function attribute 3301The @code{no_sanitize_thread} attribute on functions is used 3302to inform the compiler that it should not instrument memory accesses 3303in the function when compiling with the @option{-fsanitize=thread} option. 3304 3305@item no_sanitize_undefined 3306@cindex @code{no_sanitize_undefined} function attribute 3307The @code{no_sanitize_undefined} attribute on functions is used 3308to inform the compiler that it should not check for undefined behavior 3309in the function when compiling with the @option{-fsanitize=undefined} option. 3310 3311@item no_split_stack 3312@cindex @code{no_split_stack} function attribute 3313@opindex fsplit-stack 3314If @option{-fsplit-stack} is given, functions have a small 3315prologue which decides whether to split the stack. Functions with the 3316@code{no_split_stack} attribute do not have that prologue, and thus 3317may run with only a small amount of stack space available. 3318 3319@item no_stack_limit 3320@cindex @code{no_stack_limit} function attribute 3321This attribute locally overrides the @option{-fstack-limit-register} 3322and @option{-fstack-limit-symbol} command-line options; it has the effect 3323of disabling stack limit checking in the function it applies to. 3324 3325@item noclone 3326@cindex @code{noclone} function attribute 3327This function attribute prevents a function from being considered for 3328cloning---a mechanism that produces specialized copies of functions 3329and which is (currently) performed by interprocedural constant 3330propagation. 3331 3332@item noinline 3333@cindex @code{noinline} function attribute 3334This function attribute prevents a function from being considered for 3335inlining. 3336@c Don't enumerate the optimizations by name here; we try to be 3337@c future-compatible with this mechanism. 3338If the function does not have side effects, there are optimizations 3339other than inlining that cause function calls to be optimized away, 3340although the function call is live. To keep such calls from being 3341optimized away, put 3342@smallexample 3343asm (""); 3344@end smallexample 3345 3346@noindent 3347(@pxref{Extended Asm}) in the called function, to serve as a special 3348side effect. 3349 3350@item noipa 3351@cindex @code{noipa} function attribute 3352Disable interprocedural optimizations between the function with this 3353attribute and its callers, as if the body of the function is not available 3354when optimizing callers and the callers are unavailable when optimizing 3355the body. This attribute implies @code{noinline}, @code{noclone} and 3356@code{no_icf} attributes. However, this attribute is not equivalent 3357to a combination of other attributes, because its purpose is to suppress 3358existing and future optimizations employing interprocedural analysis, 3359including those that do not have an attribute suitable for disabling 3360them individually. This attribute is supported mainly for the purpose 3361of testing the compiler. 3362 3363@item nonnull 3364@itemx nonnull (@var{arg-index}, @dots{}) 3365@cindex @code{nonnull} function attribute 3366@cindex functions with non-null pointer arguments 3367The @code{nonnull} attribute may be applied to a function that takes at 3368least one argument of a pointer type. It indicates that the referenced 3369arguments must be non-null pointers. For instance, the declaration: 3370 3371@smallexample 3372extern void * 3373my_memcpy (void *dest, const void *src, size_t len) 3374 __attribute__((nonnull (1, 2))); 3375@end smallexample 3376 3377@noindent 3378causes the compiler to check that, in calls to @code{my_memcpy}, 3379arguments @var{dest} and @var{src} are non-null. If the compiler 3380determines that a null pointer is passed in an argument slot marked 3381as non-null, and the @option{-Wnonnull} option is enabled, a warning 3382is issued. @xref{Warning Options}. Unless disabled by 3383the @option{-fno-delete-null-pointer-checks} option the compiler may 3384also perform optimizations based on the knowledge that certain function 3385arguments cannot be null. In addition, 3386the @option{-fisolate-erroneous-paths-attribute} option can be specified 3387to have GCC transform calls with null arguments to non-null functions 3388into traps. @xref{Optimize Options}. 3389 3390If no @var{arg-index} is given to the @code{nonnull} attribute, 3391all pointer arguments are marked as non-null. To illustrate, the 3392following declaration is equivalent to the previous example: 3393 3394@smallexample 3395extern void * 3396my_memcpy (void *dest, const void *src, size_t len) 3397 __attribute__((nonnull)); 3398@end smallexample 3399 3400@item noplt 3401@cindex @code{noplt} function attribute 3402The @code{noplt} attribute is the counterpart to option @option{-fno-plt}. 3403Calls to functions marked with this attribute in position-independent code 3404do not use the PLT. 3405 3406@smallexample 3407@group 3408/* Externally defined function foo. */ 3409int foo () __attribute__ ((noplt)); 3410 3411int 3412main (/* @r{@dots{}} */) 3413@{ 3414 /* @r{@dots{}} */ 3415 foo (); 3416 /* @r{@dots{}} */ 3417@} 3418@end group 3419@end smallexample 3420 3421The @code{noplt} attribute on function @code{foo} 3422tells the compiler to assume that 3423the function @code{foo} is externally defined and that the call to 3424@code{foo} must avoid the PLT 3425in position-independent code. 3426 3427In position-dependent code, a few targets also convert calls to 3428functions that are marked to not use the PLT to use the GOT instead. 3429 3430@item noreturn 3431@cindex @code{noreturn} function attribute 3432@cindex functions that never return 3433A few standard library functions, such as @code{abort} and @code{exit}, 3434cannot return. GCC knows this automatically. Some programs define 3435their own functions that never return. You can declare them 3436@code{noreturn} to tell the compiler this fact. For example, 3437 3438@smallexample 3439@group 3440void fatal () __attribute__ ((noreturn)); 3441 3442void 3443fatal (/* @r{@dots{}} */) 3444@{ 3445 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ 3446 exit (1); 3447@} 3448@end group 3449@end smallexample 3450 3451The @code{noreturn} keyword tells the compiler to assume that 3452@code{fatal} cannot return. It can then optimize without regard to what 3453would happen if @code{fatal} ever did return. This makes slightly 3454better code. More importantly, it helps avoid spurious warnings of 3455uninitialized variables. 3456 3457The @code{noreturn} keyword does not affect the exceptional path when that 3458applies: a @code{noreturn}-marked function may still return to the caller 3459by throwing an exception or calling @code{longjmp}. 3460 3461In order to preserve backtraces, GCC will never turn calls to 3462@code{noreturn} functions into tail calls. 3463 3464Do not assume that registers saved by the calling function are 3465restored before calling the @code{noreturn} function. 3466 3467It does not make sense for a @code{noreturn} function to have a return 3468type other than @code{void}. 3469 3470@item nothrow 3471@cindex @code{nothrow} function attribute 3472The @code{nothrow} attribute is used to inform the compiler that a 3473function cannot throw an exception. For example, most functions in 3474the standard C library can be guaranteed not to throw an exception 3475with the notable exceptions of @code{qsort} and @code{bsearch} that 3476take function pointer arguments. 3477 3478@item optimize (@var{level}, @dots{}) 3479@item optimize (@var{string}, @dots{}) 3480@cindex @code{optimize} function attribute 3481The @code{optimize} attribute is used to specify that a function is to 3482be compiled with different optimization options than specified on the 3483command line. Valid arguments are constant non-negative integers and 3484strings. Each numeric argument specifies an optimization @var{level}. 3485Each @var{string} argument consists of one or more comma-separated 3486substrings. Each substring that begins with the letter @code{O} refers 3487to an optimization option such as @option{-O0} or @option{-Os}. Other 3488substrings are taken as suffixes to the @code{-f} prefix jointly 3489forming the name of an optimization option. @xref{Optimize Options}. 3490 3491@samp{#pragma GCC optimize} can be used to set optimization options 3492for more than one function. @xref{Function Specific Option Pragmas}, 3493for details about the pragma. 3494 3495Providing multiple strings as arguments separated by commas to specify 3496multiple options is equivalent to separating the option suffixes with 3497a comma (@samp{,}) within a single string. Spaces are not permitted 3498within the strings. 3499 3500Not every optimization option that starts with the @var{-f} prefix 3501specified by the attribute necessarily has an effect on the function. 3502The @code{optimize} attribute should be used for debugging purposes only. 3503It is not suitable in production code. 3504 3505@item patchable_function_entry 3506@cindex @code{patchable_function_entry} function attribute 3507@cindex extra NOP instructions at the function entry point 3508In case the target's text segment can be made writable at run time by 3509any means, padding the function entry with a number of NOPs can be 3510used to provide a universal tool for instrumentation. 3511 3512The @code{patchable_function_entry} function attribute can be used to 3513change the number of NOPs to any desired value. The two-value syntax 3514is the same as for the command-line switch 3515@option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with 3516the function entry point before the @var{M}th NOP instruction. 3517@var{M} defaults to 0 if omitted e.g.@: function entry point is before 3518the first NOP. 3519 3520If patchable function entries are enabled globally using the command-line 3521option @option{-fpatchable-function-entry=N,M}, then you must disable 3522instrumentation on all functions that are part of the instrumentation 3523framework with the attribute @code{patchable_function_entry (0)} 3524to prevent recursion. 3525 3526@item pure 3527@cindex @code{pure} function attribute 3528@cindex functions that have no side effects 3529 3530Calls to functions that have no observable effects on the state of 3531the program other than to return a value may lend themselves to optimizations 3532such as common subexpression elimination. Declaring such functions with 3533the @code{pure} attribute allows GCC to avoid emitting some calls in repeated 3534invocations of the function with the same argument values. 3535 3536The @code{pure} attribute prohibits a function from modifying the state 3537of the program that is observable by means other than inspecting 3538the function's return value. However, functions declared with the @code{pure} 3539attribute can safely read any non-volatile objects, and modify the value of 3540objects in a way that does not affect their return value or the observable 3541state of the program. 3542 3543For example, 3544 3545@smallexample 3546int hash (char *) __attribute__ ((pure)); 3547@end smallexample 3548 3549@noindent 3550tells GCC that subsequent calls to the function @code{hash} with the same 3551string can be replaced by the result of the first call provided the state 3552of the program observable by @code{hash}, including the contents of the array 3553itself, does not change in between. Even though @code{hash} takes a non-const 3554pointer argument it must not modify the array it points to, or any other object 3555whose value the rest of the program may depend on. However, the caller may 3556safely change the contents of the array between successive calls to 3557the function (doing so disables the optimization). The restriction also 3558applies to member objects referenced by the @code{this} pointer in C++ 3559non-static member functions. 3560 3561Some common examples of pure functions are @code{strlen} or @code{memcmp}. 3562Interesting non-pure functions are functions with infinite loops or those 3563depending on volatile memory or other system resource, that may change between 3564consecutive calls (such as the standard C @code{feof} function in 3565a multithreading environment). 3566 3567The @code{pure} attribute imposes similar but looser restrictions on 3568a function's definition than the @code{const} attribute: @code{pure} 3569allows the function to read any non-volatile memory, even if it changes 3570in between successive invocations of the function. Declaring the same 3571function with both the @code{pure} and the @code{const} attribute is 3572diagnosed. Because a pure function cannot have any observable side 3573effects it does not make sense for such a function to return @code{void}. 3574Declaring such a function is diagnosed. 3575 3576@item returns_nonnull 3577@cindex @code{returns_nonnull} function attribute 3578The @code{returns_nonnull} attribute specifies that the function 3579return value should be a non-null pointer. For instance, the declaration: 3580 3581@smallexample 3582extern void * 3583mymalloc (size_t len) __attribute__((returns_nonnull)); 3584@end smallexample 3585 3586@noindent 3587lets the compiler optimize callers based on the knowledge 3588that the return value will never be null. 3589 3590@item returns_twice 3591@cindex @code{returns_twice} function attribute 3592@cindex functions that return more than once 3593The @code{returns_twice} attribute tells the compiler that a function may 3594return more than one time. The compiler ensures that all registers 3595are dead before calling such a function and emits a warning about 3596the variables that may be clobbered after the second return from the 3597function. Examples of such functions are @code{setjmp} and @code{vfork}. 3598The @code{longjmp}-like counterpart of such function, if any, might need 3599to be marked with the @code{noreturn} attribute. 3600 3601@item section ("@var{section-name}") 3602@cindex @code{section} function attribute 3603@cindex functions in arbitrary sections 3604Normally, the compiler places the code it generates in the @code{text} section. 3605Sometimes, however, you need additional sections, or you need certain 3606particular functions to appear in special sections. The @code{section} 3607attribute specifies that a function lives in a particular section. 3608For example, the declaration: 3609 3610@smallexample 3611extern void foobar (void) __attribute__ ((section ("bar"))); 3612@end smallexample 3613 3614@noindent 3615puts the function @code{foobar} in the @code{bar} section. 3616 3617Some file formats do not support arbitrary sections so the @code{section} 3618attribute is not available on all platforms. 3619If you need to map the entire contents of a module to a particular 3620section, consider using the facilities of the linker instead. 3621 3622@item sentinel 3623@itemx sentinel (@var{position}) 3624@cindex @code{sentinel} function attribute 3625This function attribute indicates that an argument in a call to the function 3626is expected to be an explicit @code{NULL}. The attribute is only valid on 3627variadic functions. By default, the sentinel is expected to be the last 3628argument of the function call. If the optional @var{position} argument 3629is specified to the attribute, the sentinel must be located at 3630@var{position} counting backwards from the end of the argument list. 3631 3632@smallexample 3633__attribute__ ((sentinel)) 3634is equivalent to 3635__attribute__ ((sentinel(0))) 3636@end smallexample 3637 3638The attribute is automatically set with a position of 0 for the built-in 3639functions @code{execl} and @code{execlp}. The built-in function 3640@code{execle} has the attribute set with a position of 1. 3641 3642A valid @code{NULL} in this context is defined as zero with any object 3643pointer type. If your system defines the @code{NULL} macro with 3644an integer type then you need to add an explicit cast. During 3645installation GCC replaces the system @code{<stddef.h>} header with 3646a copy that redefines NULL appropriately. 3647 3648The warnings for missing or incorrect sentinels are enabled with 3649@option{-Wformat}. 3650 3651@item simd 3652@itemx simd("@var{mask}") 3653@cindex @code{simd} function attribute 3654This attribute enables creation of one or more function versions that 3655can process multiple arguments using SIMD instructions from a 3656single invocation. Specifying this attribute allows compiler to 3657assume that such versions are available at link time (provided 3658in the same or another translation unit). Generated versions are 3659target-dependent and described in the corresponding Vector ABI document. For 3660x86_64 target this document can be found 3661@w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}. 3662 3663The optional argument @var{mask} may have the value 3664@code{notinbranch} or @code{inbranch}, 3665and instructs the compiler to generate non-masked or masked 3666clones correspondingly. By default, all clones are generated. 3667 3668If the attribute is specified and @code{#pragma omp declare simd} is 3669present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd} 3670switch is specified, then the attribute is ignored. 3671 3672@item stack_protect 3673@cindex @code{stack_protect} function attribute 3674This attribute adds stack protection code to the function if 3675flags @option{-fstack-protector}, @option{-fstack-protector-strong} 3676or @option{-fstack-protector-explicit} are set. 3677 3678@item target (@var{string}, @dots{}) 3679@cindex @code{target} function attribute 3680Multiple target back ends implement the @code{target} attribute 3681to specify that a function is to 3682be compiled with different target options than specified on the 3683command line. One or more strings can be provided as arguments. 3684Each string consists of one or more comma-separated suffixes to 3685the @code{-m} prefix jointly forming the name of a machine-dependent 3686option. @xref{Submodel Options,,Machine-Dependent Options}. 3687 3688The @code{target} attribute can be used for instance to have a function 3689compiled with a different ISA (instruction set architecture) than the 3690default. @samp{#pragma GCC target} can be used to specify target-specific 3691options for more than one function. @xref{Function Specific Option Pragmas}, 3692for details about the pragma. 3693 3694For instance, on an x86, you could declare one function with the 3695@code{target("sse4.1,arch=core2")} attribute and another with 3696@code{target("sse4a,arch=amdfam10")}. This is equivalent to 3697compiling the first function with @option{-msse4.1} and 3698@option{-march=core2} options, and the second function with 3699@option{-msse4a} and @option{-march=amdfam10} options. It is up to you 3700to make sure that a function is only invoked on a machine that 3701supports the particular ISA it is compiled for (for example by using 3702@code{cpuid} on x86 to determine what feature bits and architecture 3703family are used). 3704 3705@smallexample 3706int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); 3707int sse3_func (void) __attribute__ ((__target__ ("sse3"))); 3708@end smallexample 3709 3710Providing multiple strings as arguments separated by commas to specify 3711multiple options is equivalent to separating the option suffixes with 3712a comma (@samp{,}) within a single string. Spaces are not permitted 3713within the strings. 3714 3715The options supported are specific to each target; refer to @ref{x86 3716Function Attributes}, @ref{PowerPC Function Attributes}, 3717@ref{ARM Function Attributes}, @ref{AArch64 Function Attributes}, 3718@ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes} 3719for details. 3720 3721@item symver ("@var{name2}@@@var{nodename}") 3722@cindex @code{symver} function attribute 3723On ELF targets this attribute creates a symbol version. The @var{name2} part 3724of the parameter is the actual name of the symbol by which it will be 3725externally referenced. The @code{nodename} portion should be the name of a 3726node specified in the version script supplied to the linker when building a 3727shared library. Versioned symbol must be defined and must be exported with 3728default visibility. 3729 3730@smallexample 3731__attribute__ ((__symver__ ("foo@@VERS_1"))) int 3732foo_v1 (void) 3733@{ 3734@} 3735@end smallexample 3736 3737Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler 3738output. 3739 3740It's an error to define multiple version of a given symbol. In such case 3741an alias can be used. 3742 3743@smallexample 3744__attribute__ ((__symver__ ("foo@@VERS_2"))) 3745__attribute__ ((alias ("foo_v1"))) 3746int symver_foo_v1 (void); 3747@end smallexample 3748 3749This example creates an alias of @code{foo_v1} with symbol name 3750@code{symver_foo_v1} which will be version @code{VERS_2} of @code{foo}. 3751 3752Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in 3753addition to creating a symbol version (as if 3754@code{"@var{name2}@@@var{nodename}"} was used) the version will be also used 3755to resolve @var{name2} by the linker. 3756 3757@item target_clones (@var{options}) 3758@cindex @code{target_clones} function attribute 3759The @code{target_clones} attribute is used to specify that a function 3760be cloned into multiple versions compiled with different target options 3761than specified on the command line. The supported options and restrictions 3762are the same as for @code{target} attribute. 3763 3764For instance, on an x86, you could compile a function with 3765@code{target_clones("sse4.1,avx")}. GCC creates two function clones, 3766one compiled with @option{-msse4.1} and another with @option{-mavx}. 3767 3768On a PowerPC, you can compile a function with 3769@code{target_clones("cpu=power9,default")}. GCC will create two 3770function clones, one compiled with @option{-mcpu=power9} and another 3771with the default options. GCC must be configured to use GLIBC 2.23 or 3772newer in order to use the @code{target_clones} attribute. 3773 3774It also creates a resolver function (see 3775the @code{ifunc} attribute above) that dynamically selects a clone 3776suitable for current architecture. The resolver is created only if there 3777is a usage of a function with @code{target_clones} attribute. 3778 3779Note that any subsequent call of a function without @code{target_clone} 3780from a @code{target_clone} caller will not lead to copying 3781(target clone) of the called function. 3782If you want to enforce such behaviour, 3783we recommend declaring the calling function with the @code{flatten} attribute? 3784 3785@item unused 3786@cindex @code{unused} function attribute 3787This attribute, attached to a function, means that the function is meant 3788to be possibly unused. GCC does not produce a warning for this 3789function. 3790 3791@item used 3792@cindex @code{used} function attribute 3793This attribute, attached to a function, means that code must be emitted 3794for the function even if it appears that the function is not referenced. 3795This is useful, for example, when the function is referenced only in 3796inline assembly. 3797 3798When applied to a member function of a C++ class template, the 3799attribute also means that the function is instantiated if the 3800class itself is instantiated. 3801 3802@item visibility ("@var{visibility_type}") 3803@cindex @code{visibility} function attribute 3804This attribute affects the linkage of the declaration to which it is attached. 3805It can be applied to variables (@pxref{Common Variable Attributes}) and types 3806(@pxref{Common Type Attributes}) as well as functions. 3807 3808There are four supported @var{visibility_type} values: default, 3809hidden, protected or internal visibility. 3810 3811@smallexample 3812void __attribute__ ((visibility ("protected"))) 3813f () @{ /* @r{Do something.} */; @} 3814int i __attribute__ ((visibility ("hidden"))); 3815@end smallexample 3816 3817The possible values of @var{visibility_type} correspond to the 3818visibility settings in the ELF gABI. 3819 3820@table @code 3821@c keep this list of visibilities in alphabetical order. 3822 3823@item default 3824Default visibility is the normal case for the object file format. 3825This value is available for the visibility attribute to override other 3826options that may change the assumed visibility of entities. 3827 3828On ELF, default visibility means that the declaration is visible to other 3829modules and, in shared libraries, means that the declared entity may be 3830overridden. 3831 3832On Darwin, default visibility means that the declaration is visible to 3833other modules. 3834 3835Default visibility corresponds to ``external linkage'' in the language. 3836 3837@item hidden 3838Hidden visibility indicates that the entity declared has a new 3839form of linkage, which we call ``hidden linkage''. Two 3840declarations of an object with hidden linkage refer to the same object 3841if they are in the same shared object. 3842 3843@item internal 3844Internal visibility is like hidden visibility, but with additional 3845processor specific semantics. Unless otherwise specified by the 3846psABI, GCC defines internal visibility to mean that a function is 3847@emph{never} called from another module. Compare this with hidden 3848functions which, while they cannot be referenced directly by other 3849modules, can be referenced indirectly via function pointers. By 3850indicating that a function cannot be called from outside the module, 3851GCC may for instance omit the load of a PIC register since it is known 3852that the calling function loaded the correct value. 3853 3854@item protected 3855Protected visibility is like default visibility except that it 3856indicates that references within the defining module bind to the 3857definition in that module. That is, the declared entity cannot be 3858overridden by another module. 3859 3860@end table 3861 3862All visibilities are supported on many, but not all, ELF targets 3863(supported when the assembler supports the @samp{.visibility} 3864pseudo-op). Default visibility is supported everywhere. Hidden 3865visibility is supported on Darwin targets. 3866 3867The visibility attribute should be applied only to declarations that 3868would otherwise have external linkage. The attribute should be applied 3869consistently, so that the same entity should not be declared with 3870different settings of the attribute. 3871 3872In C++, the visibility attribute applies to types as well as functions 3873and objects, because in C++ types have linkage. A class must not have 3874greater visibility than its non-static data member types and bases, 3875and class members default to the visibility of their class. Also, a 3876declaration without explicit visibility is limited to the visibility 3877of its type. 3878 3879In C++, you can mark member functions and static member variables of a 3880class with the visibility attribute. This is useful if you know a 3881particular method or static member variable should only be used from 3882one shared object; then you can mark it hidden while the rest of the 3883class has default visibility. Care must be taken to avoid breaking 3884the One Definition Rule; for example, it is usually not useful to mark 3885an inline method as hidden without marking the whole class as hidden. 3886 3887A C++ namespace declaration can also have the visibility attribute. 3888 3889@smallexample 3890namespace nspace1 __attribute__ ((visibility ("protected"))) 3891@{ /* @r{Do something.} */; @} 3892@end smallexample 3893 3894This attribute applies only to the particular namespace body, not to 3895other definitions of the same namespace; it is equivalent to using 3896@samp{#pragma GCC visibility} before and after the namespace 3897definition (@pxref{Visibility Pragmas}). 3898 3899In C++, if a template argument has limited visibility, this 3900restriction is implicitly propagated to the template instantiation. 3901Otherwise, template instantiations and specializations default to the 3902visibility of their template. 3903 3904If both the template and enclosing class have explicit visibility, the 3905visibility from the template is used. 3906 3907@item warn_unused_result 3908@cindex @code{warn_unused_result} function attribute 3909The @code{warn_unused_result} attribute causes a warning to be emitted 3910if a caller of the function with this attribute does not use its 3911return value. This is useful for functions where not checking 3912the result is either a security problem or always a bug, such as 3913@code{realloc}. 3914 3915@smallexample 3916int fn () __attribute__ ((warn_unused_result)); 3917int foo () 3918@{ 3919 if (fn () < 0) return -1; 3920 fn (); 3921 return 0; 3922@} 3923@end smallexample 3924 3925@noindent 3926results in warning on line 5. 3927 3928@item weak 3929@cindex @code{weak} function attribute 3930The @code{weak} attribute causes a declaration of an external symbol 3931to be emitted as a weak symbol rather than a global. This is primarily 3932useful in defining library functions that can be overridden in user code, 3933though it can also be used with non-function declarations. The overriding 3934symbol must have the same type as the weak symbol. In addition, if it 3935designates a variable it must also have the same size and alignment as 3936the weak symbol. Weak symbols are supported for ELF targets, and also 3937for a.out targets when using the GNU assembler and linker. 3938 3939@item weakref 3940@itemx weakref ("@var{target}") 3941@cindex @code{weakref} function attribute 3942The @code{weakref} attribute marks a declaration as a weak reference. 3943Without arguments, it should be accompanied by an @code{alias} attribute 3944naming the target symbol. Alternatively, @var{target} may be given as 3945an argument to @code{weakref} itself, naming the target definition of 3946the alias. The @var{target} must have the same type as the declaration. 3947In addition, if it designates a variable it must also have the same size 3948and alignment as the declaration. In either form of the declaration 3949@code{weakref} implicitly marks the declared symbol as @code{weak}. Without 3950a @var{target} given as an argument to @code{weakref} or to @code{alias}, 3951@code{weakref} is equivalent to @code{weak} (in that case the declaration 3952may be @code{extern}). 3953 3954@smallexample 3955/* Given the declaration: */ 3956extern int y (void); 3957 3958/* the following... */ 3959static int x (void) __attribute__ ((weakref ("y"))); 3960 3961/* is equivalent to... */ 3962static int x (void) __attribute__ ((weakref, alias ("y"))); 3963 3964/* or, alternatively, to... */ 3965static int x (void) __attribute__ ((weakref)); 3966static int x (void) __attribute__ ((alias ("y"))); 3967@end smallexample 3968 3969A weak reference is an alias that does not by itself require a 3970definition to be given for the target symbol. If the target symbol is 3971only referenced through weak references, then it becomes a @code{weak} 3972undefined symbol. If it is directly referenced, however, then such 3973strong references prevail, and a definition is required for the 3974symbol, not necessarily in the same translation unit. 3975 3976The effect is equivalent to moving all references to the alias to a 3977separate translation unit, renaming the alias to the aliased symbol, 3978declaring it as weak, compiling the two separate translation units and 3979performing a link with relocatable output (i.e.@: @code{ld -r}) on them. 3980 3981A declaration to which @code{weakref} is attached and that is associated 3982with a named @code{target} must be @code{static}. 3983 3984@end table 3985 3986@c This is the end of the target-independent attribute table 3987 3988@node AArch64 Function Attributes 3989@subsection AArch64 Function Attributes 3990 3991The following target-specific function attributes are available for the 3992AArch64 target. For the most part, these options mirror the behavior of 3993similar command-line options (@pxref{AArch64 Options}), but on a 3994per-function basis. 3995 3996@table @code 3997@item general-regs-only 3998@cindex @code{general-regs-only} function attribute, AArch64 3999Indicates that no floating-point or Advanced SIMD registers should be 4000used when generating code for this function. If the function explicitly 4001uses floating-point code, then the compiler gives an error. This is 4002the same behavior as that of the command-line option 4003@option{-mgeneral-regs-only}. 4004 4005@item fix-cortex-a53-835769 4006@cindex @code{fix-cortex-a53-835769} function attribute, AArch64 4007Indicates that the workaround for the Cortex-A53 erratum 835769 should be 4008applied to this function. To explicitly disable the workaround for this 4009function specify the negated form: @code{no-fix-cortex-a53-835769}. 4010This corresponds to the behavior of the command line options 4011@option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}. 4012 4013@item cmodel= 4014@cindex @code{cmodel=} function attribute, AArch64 4015Indicates that code should be generated for a particular code model for 4016this function. The behavior and permissible arguments are the same as 4017for the command line option @option{-mcmodel=}. 4018 4019@item strict-align 4020@itemx no-strict-align 4021@cindex @code{strict-align} function attribute, AArch64 4022@code{strict-align} indicates that the compiler should not assume that unaligned 4023memory references are handled by the system. To allow the compiler to assume 4024that aligned memory references are handled by the system, the inverse attribute 4025@code{no-strict-align} can be specified. The behavior is same as for the 4026command-line option @option{-mstrict-align} and @option{-mno-strict-align}. 4027 4028@item omit-leaf-frame-pointer 4029@cindex @code{omit-leaf-frame-pointer} function attribute, AArch64 4030Indicates that the frame pointer should be omitted for a leaf function call. 4031To keep the frame pointer, the inverse attribute 4032@code{no-omit-leaf-frame-pointer} can be specified. These attributes have 4033the same behavior as the command-line options @option{-momit-leaf-frame-pointer} 4034and @option{-mno-omit-leaf-frame-pointer}. 4035 4036@item tls-dialect= 4037@cindex @code{tls-dialect=} function attribute, AArch64 4038Specifies the TLS dialect to use for this function. The behavior and 4039permissible arguments are the same as for the command-line option 4040@option{-mtls-dialect=}. 4041 4042@item arch= 4043@cindex @code{arch=} function attribute, AArch64 4044Specifies the architecture version and architectural extensions to use 4045for this function. The behavior and permissible arguments are the same as 4046for the @option{-march=} command-line option. 4047 4048@item tune= 4049@cindex @code{tune=} function attribute, AArch64 4050Specifies the core for which to tune the performance of this function. 4051The behavior and permissible arguments are the same as for the @option{-mtune=} 4052command-line option. 4053 4054@item cpu= 4055@cindex @code{cpu=} function attribute, AArch64 4056Specifies the core for which to tune the performance of this function and also 4057whose architectural features to use. The behavior and valid arguments are the 4058same as for the @option{-mcpu=} command-line option. 4059 4060@item sign-return-address 4061@cindex @code{sign-return-address} function attribute, AArch64 4062Select the function scope on which return address signing will be applied. The 4063behavior and permissible arguments are the same as for the command-line option 4064@option{-msign-return-address=}. The default value is @code{none}. This 4065attribute is deprecated. The @code{branch-protection} attribute should 4066be used instead. 4067 4068@item branch-protection 4069@cindex @code{branch-protection} function attribute, AArch64 4070Select the function scope on which branch protection will be applied. The 4071behavior and permissible arguments are the same as for the command-line option 4072@option{-mbranch-protection=}. The default value is @code{none}. 4073 4074@item outline-atomics 4075@cindex @code{outline-atomics} function attribute, AArch64 4076Enable or disable calls to out-of-line helpers to implement atomic operations. 4077This corresponds to the behavior of the command line options 4078@option{-moutline-atomics} and @option{-mno-outline-atomics}. 4079 4080@end table 4081 4082The above target attributes can be specified as follows: 4083 4084@smallexample 4085__attribute__((target("@var{attr-string}"))) 4086int 4087f (int a) 4088@{ 4089 return a + 5; 4090@} 4091@end smallexample 4092 4093where @code{@var{attr-string}} is one of the attribute strings specified above. 4094 4095Additionally, the architectural extension string may be specified on its 4096own. This can be used to turn on and off particular architectural extensions 4097without having to specify a particular architecture version or core. Example: 4098 4099@smallexample 4100__attribute__((target("+crc+nocrypto"))) 4101int 4102foo (int a) 4103@{ 4104 return a + 5; 4105@} 4106@end smallexample 4107 4108In this example @code{target("+crc+nocrypto")} enables the @code{crc} 4109extension and disables the @code{crypto} extension for the function @code{foo} 4110without modifying an existing @option{-march=} or @option{-mcpu} option. 4111 4112Multiple target function attributes can be specified by separating them with 4113a comma. For example: 4114@smallexample 4115__attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53"))) 4116int 4117foo (int a) 4118@{ 4119 return a + 5; 4120@} 4121@end smallexample 4122 4123is valid and compiles function @code{foo} for ARMv8-A with @code{crc} 4124and @code{crypto} extensions and tunes it for @code{cortex-a53}. 4125 4126@subsubsection Inlining rules 4127Specifying target attributes on individual functions or performing link-time 4128optimization across translation units compiled with different target options 4129can affect function inlining rules: 4130 4131In particular, a caller function can inline a callee function only if the 4132architectural features available to the callee are a subset of the features 4133available to the caller. 4134For example: A function @code{foo} compiled with @option{-march=armv8-a+crc}, 4135or tagged with the equivalent @code{arch=armv8-a+crc} attribute, 4136can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc} 4137because the all the architectural features that function @code{bar} requires 4138are available to function @code{foo}. Conversely, function @code{bar} cannot 4139inline function @code{foo}. 4140 4141Additionally inlining a function compiled with @option{-mstrict-align} into a 4142function compiled without @code{-mstrict-align} is not allowed. 4143However, inlining a function compiled without @option{-mstrict-align} into a 4144function compiled with @option{-mstrict-align} is allowed. 4145 4146Note that CPU tuning options and attributes such as the @option{-mcpu=}, 4147@option{-mtune=} do not inhibit inlining unless the CPU specified by the 4148@option{-mcpu=} option or the @code{cpu=} attribute conflicts with the 4149architectural feature rules specified above. 4150 4151@node AMD GCN Function Attributes 4152@subsection AMD GCN Function Attributes 4153 4154These function attributes are supported by the AMD GCN back end: 4155 4156@table @code 4157@item amdgpu_hsa_kernel 4158@cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN 4159This attribute indicates that the corresponding function should be compiled as 4160a kernel function, that is an entry point that can be invoked from the host 4161via the HSA runtime library. By default functions are only callable only from 4162other GCN functions. 4163 4164This attribute is implicitly applied to any function named @code{main}, using 4165default parameters. 4166 4167Kernel functions may return an integer value, which will be written to a 4168conventional place within the HSA "kernargs" region. 4169 4170The attribute parameters configure what values are passed into the kernel 4171function by the GPU drivers, via the initial register state. Some values are 4172used by the compiler, and therefore forced on. Enabling other options may 4173break assumptions in the compiler and/or run-time libraries. 4174 4175@table @code 4176@item private_segment_buffer 4177Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to 4178locate the stack). 4179 4180@item dispatch_ptr 4181Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the 4182launch dimensions). 4183 4184@item queue_ptr 4185Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address 4186spaces). 4187 4188@item kernarg_segment_ptr 4189Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to 4190locate the kernel arguments, "kernargs"). 4191 4192@item dispatch_id 4193Set @code{enable_sgpr_dispatch_id} flag. 4194 4195@item flat_scratch_init 4196Set @code{enable_sgpr_flat_scratch_init} flag. 4197 4198@item private_segment_size 4199Set @code{enable_sgpr_private_segment_size} flag. 4200 4201@item grid_workgroup_count_X 4202Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to 4203use OpenACC/OpenMP). 4204 4205@item grid_workgroup_count_Y 4206Set @code{enable_sgpr_grid_workgroup_count_y} flag. 4207 4208@item grid_workgroup_count_Z 4209Set @code{enable_sgpr_grid_workgroup_count_z} flag. 4210 4211@item workgroup_id_X 4212Set @code{enable_sgpr_workgroup_id_x} flag. 4213 4214@item workgroup_id_Y 4215Set @code{enable_sgpr_workgroup_id_y} flag. 4216 4217@item workgroup_id_Z 4218Set @code{enable_sgpr_workgroup_id_z} flag. 4219 4220@item workgroup_info 4221Set @code{enable_sgpr_workgroup_info} flag. 4222 4223@item private_segment_wave_offset 4224Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on 4225(required to locate the stack). 4226 4227@item work_item_id_X 4228Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled). 4229 4230@item work_item_id_Y 4231Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable 4232vectorization.) 4233 4234@item work_item_id_Z 4235Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use 4236OpenACC/OpenMP). 4237 4238@end table 4239@end table 4240 4241@node ARC Function Attributes 4242@subsection ARC Function Attributes 4243 4244These function attributes are supported by the ARC back end: 4245 4246@table @code 4247@item interrupt 4248@cindex @code{interrupt} function attribute, ARC 4249Use this attribute to indicate 4250that the specified function is an interrupt handler. The compiler generates 4251function entry and exit sequences suitable for use in an interrupt handler 4252when this attribute is present. 4253 4254On the ARC, you must specify the kind of interrupt to be handled 4255in a parameter to the interrupt attribute like this: 4256 4257@smallexample 4258void f () __attribute__ ((interrupt ("ilink1"))); 4259@end smallexample 4260 4261Permissible values for this parameter are: @w{@code{ilink1}} and 4262@w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and 4263@w{@code{firq}} for ARCv2 architecture. 4264 4265@item long_call 4266@itemx medium_call 4267@itemx short_call 4268@cindex @code{long_call} function attribute, ARC 4269@cindex @code{medium_call} function attribute, ARC 4270@cindex @code{short_call} function attribute, ARC 4271@cindex indirect calls, ARC 4272These attributes specify how a particular function is called. 4273These attributes override the 4274@option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options}) 4275command-line switches and @code{#pragma long_calls} settings. 4276 4277For ARC, a function marked with the @code{long_call} attribute is 4278always called using register-indirect jump-and-link instructions, 4279thereby enabling the called function to be placed anywhere within the 428032-bit address space. A function marked with the @code{medium_call} 4281attribute will always be close enough to be called with an unconditional 4282branch-and-link instruction, which has a 25-bit offset from 4283the call site. A function marked with the @code{short_call} 4284attribute will always be close enough to be called with a conditional 4285branch-and-link instruction, which has a 21-bit offset from 4286the call site. 4287 4288@item jli_always 4289@cindex @code{jli_always} function attribute, ARC 4290Forces a particular function to be called using @code{jli} 4291instruction. The @code{jli} instruction makes use of a table stored 4292into @code{.jlitab} section, which holds the location of the functions 4293which are addressed using this instruction. 4294 4295@item jli_fixed 4296@cindex @code{jli_fixed} function attribute, ARC 4297Identical like the above one, but the location of the function in the 4298@code{jli} table is known and given as an attribute parameter. 4299 4300@item secure_call 4301@cindex @code{secure_call} function attribute, ARC 4302This attribute allows one to mark secure-code functions that are 4303callable from normal mode. The location of the secure call function 4304into the @code{sjli} table needs to be passed as argument. 4305 4306@item naked 4307@cindex @code{naked} function attribute, ARC 4308This attribute allows the compiler to construct the requisite function 4309declaration, while allowing the body of the function to be assembly 4310code. The specified function will not have prologue/epilogue 4311sequences generated by the compiler. Only basic @code{asm} statements 4312can safely be included in naked functions (@pxref{Basic Asm}). While 4313using extended @code{asm} or a mixture of basic @code{asm} and C code 4314may appear to work, they cannot be depended upon to work reliably and 4315are not supported. 4316 4317@end table 4318 4319@node ARM Function Attributes 4320@subsection ARM Function Attributes 4321 4322These function attributes are supported for ARM targets: 4323 4324@table @code 4325 4326@item general-regs-only 4327@cindex @code{general-regs-only} function attribute, ARM 4328Indicates that no floating-point or Advanced SIMD registers should be 4329used when generating code for this function. If the function explicitly 4330uses floating-point code, then the compiler gives an error. This is 4331the same behavior as that of the command-line option 4332@option{-mgeneral-regs-only}. 4333 4334@item interrupt 4335@cindex @code{interrupt} function attribute, ARM 4336Use this attribute to indicate 4337that the specified function is an interrupt handler. The compiler generates 4338function entry and exit sequences suitable for use in an interrupt handler 4339when this attribute is present. 4340 4341You can specify the kind of interrupt to be handled by 4342adding an optional parameter to the interrupt attribute like this: 4343 4344@smallexample 4345void f () __attribute__ ((interrupt ("IRQ"))); 4346@end smallexample 4347 4348@noindent 4349Permissible values for this parameter are: @code{IRQ}, @code{FIQ}, 4350@code{SWI}, @code{ABORT} and @code{UNDEF}. 4351 4352On ARMv7-M the interrupt type is ignored, and the attribute means the function 4353may be called with a word-aligned stack pointer. 4354 4355@item isr 4356@cindex @code{isr} function attribute, ARM 4357Use this attribute on ARM to write Interrupt Service Routines. This is an 4358alias to the @code{interrupt} attribute above. 4359 4360@item long_call 4361@itemx short_call 4362@cindex @code{long_call} function attribute, ARM 4363@cindex @code{short_call} function attribute, ARM 4364@cindex indirect calls, ARM 4365These attributes specify how a particular function is called. 4366These attributes override the 4367@option{-mlong-calls} (@pxref{ARM Options}) 4368command-line switch and @code{#pragma long_calls} settings. For ARM, the 4369@code{long_call} attribute indicates that the function might be far 4370away from the call site and require a different (more expensive) 4371calling sequence. The @code{short_call} attribute always places 4372the offset to the function from the call site into the @samp{BL} 4373instruction directly. 4374 4375@item naked 4376@cindex @code{naked} function attribute, ARM 4377This attribute allows the compiler to construct the 4378requisite function declaration, while allowing the body of the 4379function to be assembly code. The specified function will not have 4380prologue/epilogue sequences generated by the compiler. Only basic 4381@code{asm} statements can safely be included in naked functions 4382(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 4383basic @code{asm} and C code may appear to work, they cannot be 4384depended upon to work reliably and are not supported. 4385 4386@item pcs 4387@cindex @code{pcs} function attribute, ARM 4388 4389The @code{pcs} attribute can be used to control the calling convention 4390used for a function on ARM. The attribute takes an argument that specifies 4391the calling convention to use. 4392 4393When compiling using the AAPCS ABI (or a variant of it) then valid 4394values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In 4395order to use a variant other than @code{"aapcs"} then the compiler must 4396be permitted to use the appropriate co-processor registers (i.e., the 4397VFP registers must be available in order to use @code{"aapcs-vfp"}). 4398For example, 4399 4400@smallexample 4401/* Argument passed in r0, and result returned in r0+r1. */ 4402double f2d (float) __attribute__((pcs("aapcs"))); 4403@end smallexample 4404 4405Variadic functions always use the @code{"aapcs"} calling convention and 4406the compiler rejects attempts to specify an alternative. 4407 4408@item target (@var{options}) 4409@cindex @code{target} function attribute 4410As discussed in @ref{Common Function Attributes}, this attribute 4411allows specification of target-specific compilation options. 4412 4413On ARM, the following options are allowed: 4414 4415@table @samp 4416@item thumb 4417@cindex @code{target("thumb")} function attribute, ARM 4418Force code generation in the Thumb (T16/T32) ISA, depending on the 4419architecture level. 4420 4421@item arm 4422@cindex @code{target("arm")} function attribute, ARM 4423Force code generation in the ARM (A32) ISA. 4424 4425Functions from different modes can be inlined in the caller's mode. 4426 4427@item fpu= 4428@cindex @code{target("fpu=")} function attribute, ARM 4429Specifies the fpu for which to tune the performance of this function. 4430The behavior and permissible arguments are the same as for the @option{-mfpu=} 4431command-line option. 4432 4433@item arch= 4434@cindex @code{arch=} function attribute, ARM 4435Specifies the architecture version and architectural extensions to use 4436for this function. The behavior and permissible arguments are the same as 4437for the @option{-march=} command-line option. 4438 4439The above target attributes can be specified as follows: 4440 4441@smallexample 4442__attribute__((target("arch=armv8-a+crc"))) 4443int 4444f (int a) 4445@{ 4446 return a + 5; 4447@} 4448@end smallexample 4449 4450Additionally, the architectural extension string may be specified on its 4451own. This can be used to turn on and off particular architectural extensions 4452without having to specify a particular architecture version or core. Example: 4453 4454@smallexample 4455__attribute__((target("+crc+nocrypto"))) 4456int 4457foo (int a) 4458@{ 4459 return a + 5; 4460@} 4461@end smallexample 4462 4463In this example @code{target("+crc+nocrypto")} enables the @code{crc} 4464extension and disables the @code{crypto} extension for the function @code{foo} 4465without modifying an existing @option{-march=} or @option{-mcpu} option. 4466 4467@end table 4468 4469@end table 4470 4471@node AVR Function Attributes 4472@subsection AVR Function Attributes 4473 4474These function attributes are supported by the AVR back end: 4475 4476@table @code 4477@item interrupt 4478@cindex @code{interrupt} function attribute, AVR 4479Use this attribute to indicate 4480that the specified function is an interrupt handler. The compiler generates 4481function entry and exit sequences suitable for use in an interrupt handler 4482when this attribute is present. 4483 4484On the AVR, the hardware globally disables interrupts when an 4485interrupt is executed. The first instruction of an interrupt handler 4486declared with this attribute is a @code{SEI} instruction to 4487re-enable interrupts. See also the @code{signal} function attribute 4488that does not insert a @code{SEI} instruction. If both @code{signal} and 4489@code{interrupt} are specified for the same function, @code{signal} 4490is silently ignored. 4491 4492@item naked 4493@cindex @code{naked} function attribute, AVR 4494This attribute allows the compiler to construct the 4495requisite function declaration, while allowing the body of the 4496function to be assembly code. The specified function will not have 4497prologue/epilogue sequences generated by the compiler. Only basic 4498@code{asm} statements can safely be included in naked functions 4499(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 4500basic @code{asm} and C code may appear to work, they cannot be 4501depended upon to work reliably and are not supported. 4502 4503@item no_gccisr 4504@cindex @code{no_gccisr} function attribute, AVR 4505Do not use @code{__gcc_isr} pseudo instructions in a function with 4506the @code{interrupt} or @code{signal} attribute aka. interrupt 4507service routine (ISR). 4508Use this attribute if the preamble of the ISR prologue should always read 4509@example 4510push __zero_reg__ 4511push __tmp_reg__ 4512in __tmp_reg__, __SREG__ 4513push __tmp_reg__ 4514clr __zero_reg__ 4515@end example 4516and accordingly for the postamble of the epilogue --- no matter whether 4517the mentioned registers are actually used in the ISR or not. 4518Situations where you might want to use this attribute include: 4519@itemize @bullet 4520@item 4521Code that (effectively) clobbers bits of @code{SREG} other than the 4522@code{I}-flag by writing to the memory location of @code{SREG}. 4523@item 4524Code that uses inline assembler to jump to a different function which 4525expects (parts of) the prologue code as outlined above to be present. 4526@end itemize 4527To disable @code{__gcc_isr} generation for the whole compilation unit, 4528there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}. 4529 4530@item OS_main 4531@itemx OS_task 4532@cindex @code{OS_main} function attribute, AVR 4533@cindex @code{OS_task} function attribute, AVR 4534On AVR, functions with the @code{OS_main} or @code{OS_task} attribute 4535do not save/restore any call-saved register in their prologue/epilogue. 4536 4537The @code{OS_main} attribute can be used when there @emph{is 4538guarantee} that interrupts are disabled at the time when the function 4539is entered. This saves resources when the stack pointer has to be 4540changed to set up a frame for local variables. 4541 4542The @code{OS_task} attribute can be used when there is @emph{no 4543guarantee} that interrupts are disabled at that time when the function 4544is entered like for, e@.g@. task functions in a multi-threading operating 4545system. In that case, changing the stack pointer register is 4546guarded by save/clear/restore of the global interrupt enable flag. 4547 4548The differences to the @code{naked} function attribute are: 4549@itemize @bullet 4550@item @code{naked} functions do not have a return instruction whereas 4551@code{OS_main} and @code{OS_task} functions have a @code{RET} or 4552@code{RETI} return instruction. 4553@item @code{naked} functions do not set up a frame for local variables 4554or a frame pointer whereas @code{OS_main} and @code{OS_task} do this 4555as needed. 4556@end itemize 4557 4558@item signal 4559@cindex @code{signal} function attribute, AVR 4560Use this attribute on the AVR to indicate that the specified 4561function is an interrupt handler. The compiler generates function 4562entry and exit sequences suitable for use in an interrupt handler when this 4563attribute is present. 4564 4565See also the @code{interrupt} function attribute. 4566 4567The AVR hardware globally disables interrupts when an interrupt is executed. 4568Interrupt handler functions defined with the @code{signal} attribute 4569do not re-enable interrupts. It is save to enable interrupts in a 4570@code{signal} handler. This ``save'' only applies to the code 4571generated by the compiler and not to the IRQ layout of the 4572application which is responsibility of the application. 4573 4574If both @code{signal} and @code{interrupt} are specified for the same 4575function, @code{signal} is silently ignored. 4576@end table 4577 4578@node Blackfin Function Attributes 4579@subsection Blackfin Function Attributes 4580 4581These function attributes are supported by the Blackfin back end: 4582 4583@table @code 4584 4585@item exception_handler 4586@cindex @code{exception_handler} function attribute 4587@cindex exception handler functions, Blackfin 4588Use this attribute on the Blackfin to indicate that the specified function 4589is an exception handler. The compiler generates function entry and 4590exit sequences suitable for use in an exception handler when this 4591attribute is present. 4592 4593@item interrupt_handler 4594@cindex @code{interrupt_handler} function attribute, Blackfin 4595Use this attribute to 4596indicate that the specified function is an interrupt handler. The compiler 4597generates function entry and exit sequences suitable for use in an 4598interrupt handler when this attribute is present. 4599 4600@item kspisusp 4601@cindex @code{kspisusp} function attribute, Blackfin 4602@cindex User stack pointer in interrupts on the Blackfin 4603When used together with @code{interrupt_handler}, @code{exception_handler} 4604or @code{nmi_handler}, code is generated to load the stack pointer 4605from the USP register in the function prologue. 4606 4607@item l1_text 4608@cindex @code{l1_text} function attribute, Blackfin 4609This attribute specifies a function to be placed into L1 Instruction 4610SRAM@. The function is put into a specific section named @code{.l1.text}. 4611With @option{-mfdpic}, function calls with a such function as the callee 4612or caller uses inlined PLT. 4613 4614@item l2 4615@cindex @code{l2} function attribute, Blackfin 4616This attribute specifies a function to be placed into L2 4617SRAM. The function is put into a specific section named 4618@code{.l2.text}. With @option{-mfdpic}, callers of such functions use 4619an inlined PLT. 4620 4621@item longcall 4622@itemx shortcall 4623@cindex indirect calls, Blackfin 4624@cindex @code{longcall} function attribute, Blackfin 4625@cindex @code{shortcall} function attribute, Blackfin 4626The @code{longcall} attribute 4627indicates that the function might be far away from the call site and 4628require a different (more expensive) calling sequence. The 4629@code{shortcall} attribute indicates that the function is always close 4630enough for the shorter calling sequence to be used. These attributes 4631override the @option{-mlongcall} switch. 4632 4633@item nesting 4634@cindex @code{nesting} function attribute, Blackfin 4635@cindex Allow nesting in an interrupt handler on the Blackfin processor 4636Use this attribute together with @code{interrupt_handler}, 4637@code{exception_handler} or @code{nmi_handler} to indicate that the function 4638entry code should enable nested interrupts or exceptions. 4639 4640@item nmi_handler 4641@cindex @code{nmi_handler} function attribute, Blackfin 4642@cindex NMI handler functions on the Blackfin processor 4643Use this attribute on the Blackfin to indicate that the specified function 4644is an NMI handler. The compiler generates function entry and 4645exit sequences suitable for use in an NMI handler when this 4646attribute is present. 4647 4648@item saveall 4649@cindex @code{saveall} function attribute, Blackfin 4650@cindex save all registers on the Blackfin 4651Use this attribute to indicate that 4652all registers except the stack pointer should be saved in the prologue 4653regardless of whether they are used or not. 4654@end table 4655 4656@node BPF Function Attributes 4657@subsection BPF Function Attributes 4658 4659These function attributes are supported by the BPF back end: 4660 4661@table @code 4662@item kernel_helper 4663@cindex @code{kernel helper}, function attribute, BPF 4664use this attribute to indicate the specified function declaration is a 4665kernel helper. The helper function is passed as an argument to the 4666attribute. Example: 4667 4668@smallexample 4669int bpf_probe_read (void *dst, int size, const void *unsafe_ptr) 4670 __attribute__ ((kernel_helper (4))); 4671@end smallexample 4672@end table 4673 4674@node CR16 Function Attributes 4675@subsection CR16 Function Attributes 4676 4677These function attributes are supported by the CR16 back end: 4678 4679@table @code 4680@item interrupt 4681@cindex @code{interrupt} function attribute, CR16 4682Use this attribute to indicate 4683that the specified function is an interrupt handler. The compiler generates 4684function entry and exit sequences suitable for use in an interrupt handler 4685when this attribute is present. 4686@end table 4687 4688@node C-SKY Function Attributes 4689@subsection C-SKY Function Attributes 4690 4691These function attributes are supported by the C-SKY back end: 4692 4693@table @code 4694@item interrupt 4695@itemx isr 4696@cindex @code{interrupt} function attribute, C-SKY 4697@cindex @code{isr} function attribute, C-SKY 4698Use these attributes to indicate that the specified function 4699is an interrupt handler. 4700The compiler generates function entry and exit sequences suitable for 4701use in an interrupt handler when either of these attributes are present. 4702 4703Use of these options requires the @option{-mistack} command-line option 4704to enable support for the necessary interrupt stack instructions. They 4705are ignored with a warning otherwise. @xref{C-SKY Options}. 4706 4707@item naked 4708@cindex @code{naked} function attribute, C-SKY 4709This attribute allows the compiler to construct the 4710requisite function declaration, while allowing the body of the 4711function to be assembly code. The specified function will not have 4712prologue/epilogue sequences generated by the compiler. Only basic 4713@code{asm} statements can safely be included in naked functions 4714(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 4715basic @code{asm} and C code may appear to work, they cannot be 4716depended upon to work reliably and are not supported. 4717@end table 4718 4719 4720@node Epiphany Function Attributes 4721@subsection Epiphany Function Attributes 4722 4723These function attributes are supported by the Epiphany back end: 4724 4725@table @code 4726@item disinterrupt 4727@cindex @code{disinterrupt} function attribute, Epiphany 4728This attribute causes the compiler to emit 4729instructions to disable interrupts for the duration of the given 4730function. 4731 4732@item forwarder_section 4733@cindex @code{forwarder_section} function attribute, Epiphany 4734This attribute modifies the behavior of an interrupt handler. 4735The interrupt handler may be in external memory which cannot be 4736reached by a branch instruction, so generate a local memory trampoline 4737to transfer control. The single parameter identifies the section where 4738the trampoline is placed. 4739 4740@item interrupt 4741@cindex @code{interrupt} function attribute, Epiphany 4742Use this attribute to indicate 4743that the specified function is an interrupt handler. The compiler generates 4744function entry and exit sequences suitable for use in an interrupt handler 4745when this attribute is present. It may also generate 4746a special section with code to initialize the interrupt vector table. 4747 4748On Epiphany targets one or more optional parameters can be added like this: 4749 4750@smallexample 4751void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); 4752@end smallexample 4753 4754Permissible values for these parameters are: @w{@code{reset}}, 4755@w{@code{software_exception}}, @w{@code{page_miss}}, 4756@w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}}, 4757@w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}. 4758Multiple parameters indicate that multiple entries in the interrupt 4759vector table should be initialized for this function, i.e.@: for each 4760parameter @w{@var{name}}, a jump to the function is emitted in 4761the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted 4762entirely, in which case no interrupt vector table entry is provided. 4763 4764Note that interrupts are enabled inside the function 4765unless the @code{disinterrupt} attribute is also specified. 4766 4767The following examples are all valid uses of these attributes on 4768Epiphany targets: 4769@smallexample 4770void __attribute__ ((interrupt)) universal_handler (); 4771void __attribute__ ((interrupt ("dma1"))) dma1_handler (); 4772void __attribute__ ((interrupt ("dma0, dma1"))) 4773 universal_dma_handler (); 4774void __attribute__ ((interrupt ("timer0"), disinterrupt)) 4775 fast_timer_handler (); 4776void __attribute__ ((interrupt ("dma0, dma1"), 4777 forwarder_section ("tramp"))) 4778 external_dma_handler (); 4779@end smallexample 4780 4781@item long_call 4782@itemx short_call 4783@cindex @code{long_call} function attribute, Epiphany 4784@cindex @code{short_call} function attribute, Epiphany 4785@cindex indirect calls, Epiphany 4786These attributes specify how a particular function is called. 4787These attributes override the 4788@option{-mlong-calls} (@pxref{Adapteva Epiphany Options}) 4789command-line switch and @code{#pragma long_calls} settings. 4790@end table 4791 4792 4793@node H8/300 Function Attributes 4794@subsection H8/300 Function Attributes 4795 4796These function attributes are available for H8/300 targets: 4797 4798@table @code 4799@item function_vector 4800@cindex @code{function_vector} function attribute, H8/300 4801Use this attribute on the H8/300, H8/300H, and H8S to indicate 4802that the specified function should be called through the function vector. 4803Calling a function through the function vector reduces code size; however, 4804the function vector has a limited size (maximum 128 entries on the H8/300 4805and 64 entries on the H8/300H and H8S) 4806and shares space with the interrupt vector. 4807 4808@item interrupt_handler 4809@cindex @code{interrupt_handler} function attribute, H8/300 4810Use this attribute on the H8/300, H8/300H, and H8S to 4811indicate that the specified function is an interrupt handler. The compiler 4812generates function entry and exit sequences suitable for use in an 4813interrupt handler when this attribute is present. 4814 4815@item saveall 4816@cindex @code{saveall} function attribute, H8/300 4817@cindex save all registers on the H8/300, H8/300H, and H8S 4818Use this attribute on the H8/300, H8/300H, and H8S to indicate that 4819all registers except the stack pointer should be saved in the prologue 4820regardless of whether they are used or not. 4821@end table 4822 4823@node IA-64 Function Attributes 4824@subsection IA-64 Function Attributes 4825 4826These function attributes are supported on IA-64 targets: 4827 4828@table @code 4829@item syscall_linkage 4830@cindex @code{syscall_linkage} function attribute, IA-64 4831This attribute is used to modify the IA-64 calling convention by marking 4832all input registers as live at all function exits. This makes it possible 4833to restart a system call after an interrupt without having to save/restore 4834the input registers. This also prevents kernel data from leaking into 4835application code. 4836 4837@item version_id 4838@cindex @code{version_id} function attribute, IA-64 4839This IA-64 HP-UX attribute, attached to a global variable or function, renames a 4840symbol to contain a version string, thus allowing for function level 4841versioning. HP-UX system header files may use function level versioning 4842for some system calls. 4843 4844@smallexample 4845extern int foo () __attribute__((version_id ("20040821"))); 4846@end smallexample 4847 4848@noindent 4849Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}. 4850@end table 4851 4852@node M32C Function Attributes 4853@subsection M32C Function Attributes 4854 4855These function attributes are supported by the M32C back end: 4856 4857@table @code 4858@item bank_switch 4859@cindex @code{bank_switch} function attribute, M32C 4860When added to an interrupt handler with the M32C port, causes the 4861prologue and epilogue to use bank switching to preserve the registers 4862rather than saving them on the stack. 4863 4864@item fast_interrupt 4865@cindex @code{fast_interrupt} function attribute, M32C 4866Use this attribute on the M32C port to indicate that the specified 4867function is a fast interrupt handler. This is just like the 4868@code{interrupt} attribute, except that @code{freit} is used to return 4869instead of @code{reit}. 4870 4871@item function_vector 4872@cindex @code{function_vector} function attribute, M16C/M32C 4873On M16C/M32C targets, the @code{function_vector} attribute declares a 4874special page subroutine call function. Use of this attribute reduces 4875the code size by 2 bytes for each call generated to the 4876subroutine. The argument to the attribute is the vector number entry 4877from the special page vector table which contains the 16 low-order 4878bits of the subroutine's entry address. Each vector table has special 4879page number (18 to 255) that is used in @code{jsrs} instructions. 4880Jump addresses of the routines are generated by adding 0x0F0000 (in 4881case of M16C targets) or 0xFF0000 (in case of M32C targets), to the 48822-byte addresses set in the vector table. Therefore you need to ensure 4883that all the special page vector routines should get mapped within the 4884address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF 4885(for M32C). 4886 4887In the following example 2 bytes are saved for each call to 4888function @code{foo}. 4889 4890@smallexample 4891void foo (void) __attribute__((function_vector(0x18))); 4892void foo (void) 4893@{ 4894@} 4895 4896void bar (void) 4897@{ 4898 foo(); 4899@} 4900@end smallexample 4901 4902If functions are defined in one file and are called in another file, 4903then be sure to write this declaration in both files. 4904 4905This attribute is ignored for R8C target. 4906 4907@item interrupt 4908@cindex @code{interrupt} function attribute, M32C 4909Use this attribute to indicate 4910that the specified function is an interrupt handler. The compiler generates 4911function entry and exit sequences suitable for use in an interrupt handler 4912when this attribute is present. 4913@end table 4914 4915@node M32R/D Function Attributes 4916@subsection M32R/D Function Attributes 4917 4918These function attributes are supported by the M32R/D back end: 4919 4920@table @code 4921@item interrupt 4922@cindex @code{interrupt} function attribute, M32R/D 4923Use this attribute to indicate 4924that the specified function is an interrupt handler. The compiler generates 4925function entry and exit sequences suitable for use in an interrupt handler 4926when this attribute is present. 4927 4928@item model (@var{model-name}) 4929@cindex @code{model} function attribute, M32R/D 4930@cindex function addressability on the M32R/D 4931 4932On the M32R/D, use this attribute to set the addressability of an 4933object, and of the code generated for a function. The identifier 4934@var{model-name} is one of @code{small}, @code{medium}, or 4935@code{large}, representing each of the code models. 4936 4937Small model objects live in the lower 16MB of memory (so that their 4938addresses can be loaded with the @code{ld24} instruction), and are 4939callable with the @code{bl} instruction. 4940 4941Medium model objects may live anywhere in the 32-bit address space (the 4942compiler generates @code{seth/add3} instructions to load their addresses), 4943and are callable with the @code{bl} instruction. 4944 4945Large model objects may live anywhere in the 32-bit address space (the 4946compiler generates @code{seth/add3} instructions to load their addresses), 4947and may not be reachable with the @code{bl} instruction (the compiler 4948generates the much slower @code{seth/add3/jl} instruction sequence). 4949@end table 4950 4951@node m68k Function Attributes 4952@subsection m68k Function Attributes 4953 4954These function attributes are supported by the m68k back end: 4955 4956@table @code 4957@item interrupt 4958@itemx interrupt_handler 4959@cindex @code{interrupt} function attribute, m68k 4960@cindex @code{interrupt_handler} function attribute, m68k 4961Use this attribute to 4962indicate that the specified function is an interrupt handler. The compiler 4963generates function entry and exit sequences suitable for use in an 4964interrupt handler when this attribute is present. Either name may be used. 4965 4966@item interrupt_thread 4967@cindex @code{interrupt_thread} function attribute, fido 4968Use this attribute on fido, a subarchitecture of the m68k, to indicate 4969that the specified function is an interrupt handler that is designed 4970to run as a thread. The compiler omits generate prologue/epilogue 4971sequences and replaces the return instruction with a @code{sleep} 4972instruction. This attribute is available only on fido. 4973@end table 4974 4975@node MCORE Function Attributes 4976@subsection MCORE Function Attributes 4977 4978These function attributes are supported by the MCORE back end: 4979 4980@table @code 4981@item naked 4982@cindex @code{naked} function attribute, MCORE 4983This attribute allows the compiler to construct the 4984requisite function declaration, while allowing the body of the 4985function to be assembly code. The specified function will not have 4986prologue/epilogue sequences generated by the compiler. Only basic 4987@code{asm} statements can safely be included in naked functions 4988(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 4989basic @code{asm} and C code may appear to work, they cannot be 4990depended upon to work reliably and are not supported. 4991@end table 4992 4993@node MeP Function Attributes 4994@subsection MeP Function Attributes 4995 4996These function attributes are supported by the MeP back end: 4997 4998@table @code 4999@item disinterrupt 5000@cindex @code{disinterrupt} function attribute, MeP 5001On MeP targets, this attribute causes the compiler to emit 5002instructions to disable interrupts for the duration of the given 5003function. 5004 5005@item interrupt 5006@cindex @code{interrupt} function attribute, MeP 5007Use this attribute to indicate 5008that the specified function is an interrupt handler. The compiler generates 5009function entry and exit sequences suitable for use in an interrupt handler 5010when this attribute is present. 5011 5012@item near 5013@cindex @code{near} function attribute, MeP 5014This attribute causes the compiler to assume the called 5015function is close enough to use the normal calling convention, 5016overriding the @option{-mtf} command-line option. 5017 5018@item far 5019@cindex @code{far} function attribute, MeP 5020On MeP targets this causes the compiler to use a calling convention 5021that assumes the called function is too far away for the built-in 5022addressing modes. 5023 5024@item vliw 5025@cindex @code{vliw} function attribute, MeP 5026The @code{vliw} attribute tells the compiler to emit 5027instructions in VLIW mode instead of core mode. Note that this 5028attribute is not allowed unless a VLIW coprocessor has been configured 5029and enabled through command-line options. 5030@end table 5031 5032@node MicroBlaze Function Attributes 5033@subsection MicroBlaze Function Attributes 5034 5035These function attributes are supported on MicroBlaze targets: 5036 5037@table @code 5038@item save_volatiles 5039@cindex @code{save_volatiles} function attribute, MicroBlaze 5040Use this attribute to indicate that the function is 5041an interrupt handler. All volatile registers (in addition to non-volatile 5042registers) are saved in the function prologue. If the function is a leaf 5043function, only volatiles used by the function are saved. A normal function 5044return is generated instead of a return from interrupt. 5045 5046@item break_handler 5047@cindex @code{break_handler} function attribute, MicroBlaze 5048@cindex break handler functions 5049Use this attribute to indicate that 5050the specified function is a break handler. The compiler generates function 5051entry and exit sequences suitable for use in an break handler when this 5052attribute is present. The return from @code{break_handler} is done through 5053the @code{rtbd} instead of @code{rtsd}. 5054 5055@smallexample 5056void f () __attribute__ ((break_handler)); 5057@end smallexample 5058 5059@item interrupt_handler 5060@itemx fast_interrupt 5061@cindex @code{interrupt_handler} function attribute, MicroBlaze 5062@cindex @code{fast_interrupt} function attribute, MicroBlaze 5063These attributes indicate that the specified function is an interrupt 5064handler. Use the @code{fast_interrupt} attribute to indicate handlers 5065used in low-latency interrupt mode, and @code{interrupt_handler} for 5066interrupts that do not use low-latency handlers. In both cases, GCC 5067emits appropriate prologue code and generates a return from the handler 5068using @code{rtid} instead of @code{rtsd}. 5069@end table 5070 5071@node Microsoft Windows Function Attributes 5072@subsection Microsoft Windows Function Attributes 5073 5074The following attributes are available on Microsoft Windows and Symbian OS 5075targets. 5076 5077@table @code 5078@item dllexport 5079@cindex @code{dllexport} function attribute 5080@cindex @code{__declspec(dllexport)} 5081On Microsoft Windows targets and Symbian OS targets the 5082@code{dllexport} attribute causes the compiler to provide a global 5083pointer to a pointer in a DLL, so that it can be referenced with the 5084@code{dllimport} attribute. On Microsoft Windows targets, the pointer 5085name is formed by combining @code{_imp__} and the function or variable 5086name. 5087 5088You can use @code{__declspec(dllexport)} as a synonym for 5089@code{__attribute__ ((dllexport))} for compatibility with other 5090compilers. 5091 5092On systems that support the @code{visibility} attribute, this 5093attribute also implies ``default'' visibility. It is an error to 5094explicitly specify any other visibility. 5095 5096GCC's default behavior is to emit all inline functions with the 5097@code{dllexport} attribute. Since this can cause object file-size bloat, 5098you can use @option{-fno-keep-inline-dllexport}, which tells GCC to 5099ignore the attribute for inlined functions unless the 5100@option{-fkeep-inline-functions} flag is used instead. 5101 5102The attribute is ignored for undefined symbols. 5103 5104When applied to C++ classes, the attribute marks defined non-inlined 5105member functions and static data members as exports. Static consts 5106initialized in-class are not marked unless they are also defined 5107out-of-class. 5108 5109For Microsoft Windows targets there are alternative methods for 5110including the symbol in the DLL's export table such as using a 5111@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using 5112the @option{--export-all} linker flag. 5113 5114@item dllimport 5115@cindex @code{dllimport} function attribute 5116@cindex @code{__declspec(dllimport)} 5117On Microsoft Windows and Symbian OS targets, the @code{dllimport} 5118attribute causes the compiler to reference a function or variable via 5119a global pointer to a pointer that is set up by the DLL exporting the 5120symbol. The attribute implies @code{extern}. On Microsoft Windows 5121targets, the pointer name is formed by combining @code{_imp__} and the 5122function or variable name. 5123 5124You can use @code{__declspec(dllimport)} as a synonym for 5125@code{__attribute__ ((dllimport))} for compatibility with other 5126compilers. 5127 5128On systems that support the @code{visibility} attribute, this 5129attribute also implies ``default'' visibility. It is an error to 5130explicitly specify any other visibility. 5131 5132Currently, the attribute is ignored for inlined functions. If the 5133attribute is applied to a symbol @emph{definition}, an error is reported. 5134If a symbol previously declared @code{dllimport} is later defined, the 5135attribute is ignored in subsequent references, and a warning is emitted. 5136The attribute is also overridden by a subsequent declaration as 5137@code{dllexport}. 5138 5139When applied to C++ classes, the attribute marks non-inlined 5140member functions and static data members as imports. However, the 5141attribute is ignored for virtual methods to allow creation of vtables 5142using thunks. 5143 5144On the SH Symbian OS target the @code{dllimport} attribute also has 5145another affect---it can cause the vtable and run-time type information 5146for a class to be exported. This happens when the class has a 5147dllimported constructor or a non-inline, non-pure virtual function 5148and, for either of those two conditions, the class also has an inline 5149constructor or destructor and has a key function that is defined in 5150the current translation unit. 5151 5152For Microsoft Windows targets the use of the @code{dllimport} 5153attribute on functions is not necessary, but provides a small 5154performance benefit by eliminating a thunk in the DLL@. The use of the 5155@code{dllimport} attribute on imported variables can be avoided by passing the 5156@option{--enable-auto-import} switch to the GNU linker. As with 5157functions, using the attribute for a variable eliminates a thunk in 5158the DLL@. 5159 5160One drawback to using this attribute is that a pointer to a 5161@emph{variable} marked as @code{dllimport} cannot be used as a constant 5162address. However, a pointer to a @emph{function} with the 5163@code{dllimport} attribute can be used as a constant initializer; in 5164this case, the address of a stub function in the import lib is 5165referenced. On Microsoft Windows targets, the attribute can be disabled 5166for functions by setting the @option{-mnop-fun-dllimport} flag. 5167@end table 5168 5169@node MIPS Function Attributes 5170@subsection MIPS Function Attributes 5171 5172These function attributes are supported by the MIPS back end: 5173 5174@table @code 5175@item interrupt 5176@cindex @code{interrupt} function attribute, MIPS 5177Use this attribute to indicate that the specified function is an interrupt 5178handler. The compiler generates function entry and exit sequences suitable 5179for use in an interrupt handler when this attribute is present. 5180An optional argument is supported for the interrupt attribute which allows 5181the interrupt mode to be described. By default GCC assumes the external 5182interrupt controller (EIC) mode is in use, this can be explicitly set using 5183@code{eic}. When interrupts are non-masked then the requested Interrupt 5184Priority Level (IPL) is copied to the current IPL which has the effect of only 5185enabling higher priority interrupts. To use vectored interrupt mode use 5186the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change 5187the behavior of the non-masked interrupt support and GCC will arrange to mask 5188all interrupts from sw0 up to and including the specified interrupt vector. 5189 5190You can use the following attributes to modify the behavior 5191of an interrupt handler: 5192@table @code 5193@item use_shadow_register_set 5194@cindex @code{use_shadow_register_set} function attribute, MIPS 5195Assume that the handler uses a shadow register set, instead of 5196the main general-purpose registers. An optional argument @code{intstack} is 5197supported to indicate that the shadow register set contains a valid stack 5198pointer. 5199 5200@item keep_interrupts_masked 5201@cindex @code{keep_interrupts_masked} function attribute, MIPS 5202Keep interrupts masked for the whole function. Without this attribute, 5203GCC tries to reenable interrupts for as much of the function as it can. 5204 5205@item use_debug_exception_return 5206@cindex @code{use_debug_exception_return} function attribute, MIPS 5207Return using the @code{deret} instruction. Interrupt handlers that don't 5208have this attribute return using @code{eret} instead. 5209@end table 5210 5211You can use any combination of these attributes, as shown below: 5212@smallexample 5213void __attribute__ ((interrupt)) v0 (); 5214void __attribute__ ((interrupt, use_shadow_register_set)) v1 (); 5215void __attribute__ ((interrupt, keep_interrupts_masked)) v2 (); 5216void __attribute__ ((interrupt, use_debug_exception_return)) v3 (); 5217void __attribute__ ((interrupt, use_shadow_register_set, 5218 keep_interrupts_masked)) v4 (); 5219void __attribute__ ((interrupt, use_shadow_register_set, 5220 use_debug_exception_return)) v5 (); 5221void __attribute__ ((interrupt, keep_interrupts_masked, 5222 use_debug_exception_return)) v6 (); 5223void __attribute__ ((interrupt, use_shadow_register_set, 5224 keep_interrupts_masked, 5225 use_debug_exception_return)) v7 (); 5226void __attribute__ ((interrupt("eic"))) v8 (); 5227void __attribute__ ((interrupt("vector=hw3"))) v9 (); 5228@end smallexample 5229 5230@item long_call 5231@itemx short_call 5232@itemx near 5233@itemx far 5234@cindex indirect calls, MIPS 5235@cindex @code{long_call} function attribute, MIPS 5236@cindex @code{short_call} function attribute, MIPS 5237@cindex @code{near} function attribute, MIPS 5238@cindex @code{far} function attribute, MIPS 5239These attributes specify how a particular function is called on MIPS@. 5240The attributes override the @option{-mlong-calls} (@pxref{MIPS Options}) 5241command-line switch. The @code{long_call} and @code{far} attributes are 5242synonyms, and cause the compiler to always call 5243the function by first loading its address into a register, and then using 5244the contents of that register. The @code{short_call} and @code{near} 5245attributes are synonyms, and have the opposite 5246effect; they specify that non-PIC calls should be made using the more 5247efficient @code{jal} instruction. 5248 5249@item mips16 5250@itemx nomips16 5251@cindex @code{mips16} function attribute, MIPS 5252@cindex @code{nomips16} function attribute, MIPS 5253 5254On MIPS targets, you can use the @code{mips16} and @code{nomips16} 5255function attributes to locally select or turn off MIPS16 code generation. 5256A function with the @code{mips16} attribute is emitted as MIPS16 code, 5257while MIPS16 code generation is disabled for functions with the 5258@code{nomips16} attribute. These attributes override the 5259@option{-mips16} and @option{-mno-mips16} options on the command line 5260(@pxref{MIPS Options}). 5261 5262When compiling files containing mixed MIPS16 and non-MIPS16 code, the 5263preprocessor symbol @code{__mips16} reflects the setting on the command line, 5264not that within individual functions. Mixed MIPS16 and non-MIPS16 code 5265may interact badly with some GCC extensions such as @code{__builtin_apply} 5266(@pxref{Constructing Calls}). 5267 5268@item micromips, MIPS 5269@itemx nomicromips, MIPS 5270@cindex @code{micromips} function attribute 5271@cindex @code{nomicromips} function attribute 5272 5273On MIPS targets, you can use the @code{micromips} and @code{nomicromips} 5274function attributes to locally select or turn off microMIPS code generation. 5275A function with the @code{micromips} attribute is emitted as microMIPS code, 5276while microMIPS code generation is disabled for functions with the 5277@code{nomicromips} attribute. These attributes override the 5278@option{-mmicromips} and @option{-mno-micromips} options on the command line 5279(@pxref{MIPS Options}). 5280 5281When compiling files containing mixed microMIPS and non-microMIPS code, the 5282preprocessor symbol @code{__mips_micromips} reflects the setting on the 5283command line, 5284not that within individual functions. Mixed microMIPS and non-microMIPS code 5285may interact badly with some GCC extensions such as @code{__builtin_apply} 5286(@pxref{Constructing Calls}). 5287 5288@item nocompression 5289@cindex @code{nocompression} function attribute, MIPS 5290On MIPS targets, you can use the @code{nocompression} function attribute 5291to locally turn off MIPS16 and microMIPS code generation. This attribute 5292overrides the @option{-mips16} and @option{-mmicromips} options on the 5293command line (@pxref{MIPS Options}). 5294@end table 5295 5296@node MSP430 Function Attributes 5297@subsection MSP430 Function Attributes 5298 5299These function attributes are supported by the MSP430 back end: 5300 5301@table @code 5302@item critical 5303@cindex @code{critical} function attribute, MSP430 5304Critical functions disable interrupts upon entry and restore the 5305previous interrupt state upon exit. Critical functions cannot also 5306have the @code{naked}, @code{reentrant} or @code{interrupt} attributes. 5307 5308The MSP430 hardware ensures that interrupts are disabled on entry to 5309@code{interrupt} functions, and restores the previous interrupt state 5310on exit. The @code{critical} attribute is therefore redundant on 5311@code{interrupt} functions. 5312 5313@item interrupt 5314@cindex @code{interrupt} function attribute, MSP430 5315Use this attribute to indicate 5316that the specified function is an interrupt handler. The compiler generates 5317function entry and exit sequences suitable for use in an interrupt handler 5318when this attribute is present. 5319 5320You can provide an argument to the interrupt 5321attribute which specifies a name or number. If the argument is a 5322number it indicates the slot in the interrupt vector table (0 - 31) to 5323which this handler should be assigned. If the argument is a name it 5324is treated as a symbolic name for the vector slot. These names should 5325match up with appropriate entries in the linker script. By default 5326the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and 5327@code{reset} for vector 31 are recognized. 5328 5329@item naked 5330@cindex @code{naked} function attribute, MSP430 5331This attribute allows the compiler to construct the 5332requisite function declaration, while allowing the body of the 5333function to be assembly code. The specified function will not have 5334prologue/epilogue sequences generated by the compiler. Only basic 5335@code{asm} statements can safely be included in naked functions 5336(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5337basic @code{asm} and C code may appear to work, they cannot be 5338depended upon to work reliably and are not supported. 5339 5340@item reentrant 5341@cindex @code{reentrant} function attribute, MSP430 5342Reentrant functions disable interrupts upon entry and enable them 5343upon exit. Reentrant functions cannot also have the @code{naked} 5344or @code{critical} attributes. They can have the @code{interrupt} 5345attribute. 5346 5347@item wakeup 5348@cindex @code{wakeup} function attribute, MSP430 5349This attribute only applies to interrupt functions. It is silently 5350ignored if applied to a non-interrupt function. A wakeup interrupt 5351function will rouse the processor from any low-power state that it 5352might be in when the function exits. 5353 5354@item lower 5355@itemx upper 5356@itemx either 5357@cindex @code{lower} function attribute, MSP430 5358@cindex @code{upper} function attribute, MSP430 5359@cindex @code{either} function attribute, MSP430 5360On the MSP430 target these attributes can be used to specify whether 5361the function or variable should be placed into low memory, high 5362memory, or the placement should be left to the linker to decide. The 5363attributes are only significant if compiling for the MSP430X 5364architecture in the large memory model. 5365 5366The attributes work in conjunction with a linker script that has been 5367augmented to specify where to place sections with a @code{.lower} and 5368a @code{.upper} prefix. So, for example, as well as placing the 5369@code{.data} section, the script also specifies the placement of a 5370@code{.lower.data} and a @code{.upper.data} section. The intention 5371is that @code{lower} sections are placed into a small but easier to 5372access memory region and the upper sections are placed into a larger, but 5373slower to access, region. 5374 5375The @code{either} attribute is special. It tells the linker to place 5376the object into the corresponding @code{lower} section if there is 5377room for it. If there is insufficient room then the object is placed 5378into the corresponding @code{upper} section instead. Note that the 5379placement algorithm is not very sophisticated. It does not attempt to 5380find an optimal packing of the @code{lower} sections. It just makes 5381one pass over the objects and does the best that it can. Using the 5382@option{-ffunction-sections} and @option{-fdata-sections} command-line 5383options can help the packing, however, since they produce smaller, 5384easier to pack regions. 5385@end table 5386 5387@node NDS32 Function Attributes 5388@subsection NDS32 Function Attributes 5389 5390These function attributes are supported by the NDS32 back end: 5391 5392@table @code 5393@item exception 5394@cindex @code{exception} function attribute 5395@cindex exception handler functions, NDS32 5396Use this attribute on the NDS32 target to indicate that the specified function 5397is an exception handler. The compiler will generate corresponding sections 5398for use in an exception handler. 5399 5400@item interrupt 5401@cindex @code{interrupt} function attribute, NDS32 5402On NDS32 target, this attribute indicates that the specified function 5403is an interrupt handler. The compiler generates corresponding sections 5404for use in an interrupt handler. You can use the following attributes 5405to modify the behavior: 5406@table @code 5407@item nested 5408@cindex @code{nested} function attribute, NDS32 5409This interrupt service routine is interruptible. 5410@item not_nested 5411@cindex @code{not_nested} function attribute, NDS32 5412This interrupt service routine is not interruptible. 5413@item nested_ready 5414@cindex @code{nested_ready} function attribute, NDS32 5415This interrupt service routine is interruptible after @code{PSW.GIE} 5416(global interrupt enable) is set. This allows interrupt service routine to 5417finish some short critical code before enabling interrupts. 5418@item save_all 5419@cindex @code{save_all} function attribute, NDS32 5420The system will help save all registers into stack before entering 5421interrupt handler. 5422@item partial_save 5423@cindex @code{partial_save} function attribute, NDS32 5424The system will help save caller registers into stack before entering 5425interrupt handler. 5426@end table 5427 5428@item naked 5429@cindex @code{naked} function attribute, NDS32 5430This attribute allows the compiler to construct the 5431requisite function declaration, while allowing the body of the 5432function to be assembly code. The specified function will not have 5433prologue/epilogue sequences generated by the compiler. Only basic 5434@code{asm} statements can safely be included in naked functions 5435(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5436basic @code{asm} and C code may appear to work, they cannot be 5437depended upon to work reliably and are not supported. 5438 5439@item reset 5440@cindex @code{reset} function attribute, NDS32 5441@cindex reset handler functions 5442Use this attribute on the NDS32 target to indicate that the specified function 5443is a reset handler. The compiler will generate corresponding sections 5444for use in a reset handler. You can use the following attributes 5445to provide extra exception handling: 5446@table @code 5447@item nmi 5448@cindex @code{nmi} function attribute, NDS32 5449Provide a user-defined function to handle NMI exception. 5450@item warm 5451@cindex @code{warm} function attribute, NDS32 5452Provide a user-defined function to handle warm reset exception. 5453@end table 5454@end table 5455 5456@node Nios II Function Attributes 5457@subsection Nios II Function Attributes 5458 5459These function attributes are supported by the Nios II back end: 5460 5461@table @code 5462@item target (@var{options}) 5463@cindex @code{target} function attribute 5464As discussed in @ref{Common Function Attributes}, this attribute 5465allows specification of target-specific compilation options. 5466 5467When compiling for Nios II, the following options are allowed: 5468 5469@table @samp 5470@item custom-@var{insn}=@var{N} 5471@itemx no-custom-@var{insn} 5472@cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II 5473@cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II 5474Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a 5475custom instruction with encoding @var{N} when generating code that uses 5476@var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of 5477the custom instruction @var{insn}. 5478These target attributes correspond to the 5479@option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}} 5480command-line options, and support the same set of @var{insn} keywords. 5481@xref{Nios II Options}, for more information. 5482 5483@item custom-fpu-cfg=@var{name} 5484@cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II 5485This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}} 5486command-line option, to select a predefined set of custom instructions 5487named @var{name}. 5488@xref{Nios II Options}, for more information. 5489@end table 5490@end table 5491 5492@node Nvidia PTX Function Attributes 5493@subsection Nvidia PTX Function Attributes 5494 5495These function attributes are supported by the Nvidia PTX back end: 5496 5497@table @code 5498@item kernel 5499@cindex @code{kernel} attribute, Nvidia PTX 5500This attribute indicates that the corresponding function should be compiled 5501as a kernel function, which can be invoked from the host via the CUDA RT 5502library. 5503By default functions are only callable only from other PTX functions. 5504 5505Kernel functions must have @code{void} return type. 5506@end table 5507 5508@node PowerPC Function Attributes 5509@subsection PowerPC Function Attributes 5510 5511These function attributes are supported by the PowerPC back end: 5512 5513@table @code 5514@item longcall 5515@itemx shortcall 5516@cindex indirect calls, PowerPC 5517@cindex @code{longcall} function attribute, PowerPC 5518@cindex @code{shortcall} function attribute, PowerPC 5519The @code{longcall} attribute 5520indicates that the function might be far away from the call site and 5521require a different (more expensive) calling sequence. The 5522@code{shortcall} attribute indicates that the function is always close 5523enough for the shorter calling sequence to be used. These attributes 5524override both the @option{-mlongcall} switch and 5525the @code{#pragma longcall} setting. 5526 5527@xref{RS/6000 and PowerPC Options}, for more information on whether long 5528calls are necessary. 5529 5530@item target (@var{options}) 5531@cindex @code{target} function attribute 5532As discussed in @ref{Common Function Attributes}, this attribute 5533allows specification of target-specific compilation options. 5534 5535On the PowerPC, the following options are allowed: 5536 5537@table @samp 5538@item altivec 5539@itemx no-altivec 5540@cindex @code{target("altivec")} function attribute, PowerPC 5541Generate code that uses (does not use) AltiVec instructions. In 554232-bit code, you cannot enable AltiVec instructions unless 5543@option{-mabi=altivec} is used on the command line. 5544 5545@item cmpb 5546@itemx no-cmpb 5547@cindex @code{target("cmpb")} function attribute, PowerPC 5548Generate code that uses (does not use) the compare bytes instruction 5549implemented on the POWER6 processor and other processors that support 5550the PowerPC V2.05 architecture. 5551 5552@item dlmzb 5553@itemx no-dlmzb 5554@cindex @code{target("dlmzb")} function attribute, PowerPC 5555Generate code that uses (does not use) the string-search @samp{dlmzb} 5556instruction on the IBM 405, 440, 464 and 476 processors. This instruction is 5557generated by default when targeting those processors. 5558 5559@item fprnd 5560@itemx no-fprnd 5561@cindex @code{target("fprnd")} function attribute, PowerPC 5562Generate code that uses (does not use) the FP round to integer 5563instructions implemented on the POWER5+ processor and other processors 5564that support the PowerPC V2.03 architecture. 5565 5566@item hard-dfp 5567@itemx no-hard-dfp 5568@cindex @code{target("hard-dfp")} function attribute, PowerPC 5569Generate code that uses (does not use) the decimal floating-point 5570instructions implemented on some POWER processors. 5571 5572@item isel 5573@itemx no-isel 5574@cindex @code{target("isel")} function attribute, PowerPC 5575Generate code that uses (does not use) ISEL instruction. 5576 5577@item mfcrf 5578@itemx no-mfcrf 5579@cindex @code{target("mfcrf")} function attribute, PowerPC 5580Generate code that uses (does not use) the move from condition 5581register field instruction implemented on the POWER4 processor and 5582other processors that support the PowerPC V2.01 architecture. 5583 5584@item mulhw 5585@itemx no-mulhw 5586@cindex @code{target("mulhw")} function attribute, PowerPC 5587Generate code that uses (does not use) the half-word multiply and 5588multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors. 5589These instructions are generated by default when targeting those 5590processors. 5591 5592@item multiple 5593@itemx no-multiple 5594@cindex @code{target("multiple")} function attribute, PowerPC 5595Generate code that uses (does not use) the load multiple word 5596instructions and the store multiple word instructions. 5597 5598@item update 5599@itemx no-update 5600@cindex @code{target("update")} function attribute, PowerPC 5601Generate code that uses (does not use) the load or store instructions 5602that update the base register to the address of the calculated memory 5603location. 5604 5605@item popcntb 5606@itemx no-popcntb 5607@cindex @code{target("popcntb")} function attribute, PowerPC 5608Generate code that uses (does not use) the popcount and double-precision 5609FP reciprocal estimate instruction implemented on the POWER5 5610processor and other processors that support the PowerPC V2.02 5611architecture. 5612 5613@item popcntd 5614@itemx no-popcntd 5615@cindex @code{target("popcntd")} function attribute, PowerPC 5616Generate code that uses (does not use) the popcount instruction 5617implemented on the POWER7 processor and other processors that support 5618the PowerPC V2.06 architecture. 5619 5620@item powerpc-gfxopt 5621@itemx no-powerpc-gfxopt 5622@cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC 5623Generate code that uses (does not use) the optional PowerPC 5624architecture instructions in the Graphics group, including 5625floating-point select. 5626 5627@item powerpc-gpopt 5628@itemx no-powerpc-gpopt 5629@cindex @code{target("powerpc-gpopt")} function attribute, PowerPC 5630Generate code that uses (does not use) the optional PowerPC 5631architecture instructions in the General Purpose group, including 5632floating-point square root. 5633 5634@item recip-precision 5635@itemx no-recip-precision 5636@cindex @code{target("recip-precision")} function attribute, PowerPC 5637Assume (do not assume) that the reciprocal estimate instructions 5638provide higher-precision estimates than is mandated by the PowerPC 5639ABI. 5640 5641@item string 5642@itemx no-string 5643@cindex @code{target("string")} function attribute, PowerPC 5644Generate code that uses (does not use) the load string instructions 5645and the store string word instructions to save multiple registers and 5646do small block moves. 5647 5648@item vsx 5649@itemx no-vsx 5650@cindex @code{target("vsx")} function attribute, PowerPC 5651Generate code that uses (does not use) vector/scalar (VSX) 5652instructions, and also enable the use of built-in functions that allow 5653more direct access to the VSX instruction set. In 32-bit code, you 5654cannot enable VSX or AltiVec instructions unless 5655@option{-mabi=altivec} is used on the command line. 5656 5657@item friz 5658@itemx no-friz 5659@cindex @code{target("friz")} function attribute, PowerPC 5660Generate (do not generate) the @code{friz} instruction when the 5661@option{-funsafe-math-optimizations} option is used to optimize 5662rounding a floating-point value to 64-bit integer and back to floating 5663point. The @code{friz} instruction does not return the same value if 5664the floating-point number is too large to fit in an integer. 5665 5666@item avoid-indexed-addresses 5667@itemx no-avoid-indexed-addresses 5668@cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC 5669Generate code that tries to avoid (not avoid) the use of indexed load 5670or store instructions. 5671 5672@item paired 5673@itemx no-paired 5674@cindex @code{target("paired")} function attribute, PowerPC 5675Generate code that uses (does not use) the generation of PAIRED simd 5676instructions. 5677 5678@item longcall 5679@itemx no-longcall 5680@cindex @code{target("longcall")} function attribute, PowerPC 5681Generate code that assumes (does not assume) that all calls are far 5682away so that a longer more expensive calling sequence is required. 5683 5684@item cpu=@var{CPU} 5685@cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC 5686Specify the architecture to generate code for when compiling the 5687function. If you select the @code{target("cpu=power7")} attribute when 5688generating 32-bit code, VSX and AltiVec instructions are not generated 5689unless you use the @option{-mabi=altivec} option on the command line. 5690 5691@item tune=@var{TUNE} 5692@cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC 5693Specify the architecture to tune for when compiling the function. If 5694you do not specify the @code{target("tune=@var{TUNE}")} attribute and 5695you do specify the @code{target("cpu=@var{CPU}")} attribute, 5696compilation tunes for the @var{CPU} architecture, and not the 5697default tuning specified on the command line. 5698@end table 5699 5700On the PowerPC, the inliner does not inline a 5701function that has different target options than the caller, unless the 5702callee has a subset of the target options of the caller. 5703@end table 5704 5705@node RISC-V Function Attributes 5706@subsection RISC-V Function Attributes 5707 5708These function attributes are supported by the RISC-V back end: 5709 5710@table @code 5711@item naked 5712@cindex @code{naked} function attribute, RISC-V 5713This attribute allows the compiler to construct the 5714requisite function declaration, while allowing the body of the 5715function to be assembly code. The specified function will not have 5716prologue/epilogue sequences generated by the compiler. Only basic 5717@code{asm} statements can safely be included in naked functions 5718(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5719basic @code{asm} and C code may appear to work, they cannot be 5720depended upon to work reliably and are not supported. 5721 5722@item interrupt 5723@cindex @code{interrupt} function attribute, RISC-V 5724Use this attribute to indicate that the specified function is an interrupt 5725handler. The compiler generates function entry and exit sequences suitable 5726for use in an interrupt handler when this attribute is present. 5727 5728You can specify the kind of interrupt to be handled by adding an optional 5729parameter to the interrupt attribute like this: 5730 5731@smallexample 5732void f (void) __attribute__ ((interrupt ("user"))); 5733@end smallexample 5734 5735Permissible values for this parameter are @code{user}, @code{supervisor}, 5736and @code{machine}. If there is no parameter, then it defaults to 5737@code{machine}. 5738@end table 5739 5740@node RL78 Function Attributes 5741@subsection RL78 Function Attributes 5742 5743These function attributes are supported by the RL78 back end: 5744 5745@table @code 5746@item interrupt 5747@itemx brk_interrupt 5748@cindex @code{interrupt} function attribute, RL78 5749@cindex @code{brk_interrupt} function attribute, RL78 5750These attributes indicate 5751that the specified function is an interrupt handler. The compiler generates 5752function entry and exit sequences suitable for use in an interrupt handler 5753when this attribute is present. 5754 5755Use @code{brk_interrupt} instead of @code{interrupt} for 5756handlers intended to be used with the @code{BRK} opcode (i.e.@: those 5757that must end with @code{RETB} instead of @code{RETI}). 5758 5759@item naked 5760@cindex @code{naked} function attribute, RL78 5761This attribute allows the compiler to construct the 5762requisite function declaration, while allowing the body of the 5763function to be assembly code. The specified function will not have 5764prologue/epilogue sequences generated by the compiler. Only basic 5765@code{asm} statements can safely be included in naked functions 5766(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5767basic @code{asm} and C code may appear to work, they cannot be 5768depended upon to work reliably and are not supported. 5769@end table 5770 5771@node RX Function Attributes 5772@subsection RX Function Attributes 5773 5774These function attributes are supported by the RX back end: 5775 5776@table @code 5777@item fast_interrupt 5778@cindex @code{fast_interrupt} function attribute, RX 5779Use this attribute on the RX port to indicate that the specified 5780function is a fast interrupt handler. This is just like the 5781@code{interrupt} attribute, except that @code{freit} is used to return 5782instead of @code{reit}. 5783 5784@item interrupt 5785@cindex @code{interrupt} function attribute, RX 5786Use this attribute to indicate 5787that the specified function is an interrupt handler. The compiler generates 5788function entry and exit sequences suitable for use in an interrupt handler 5789when this attribute is present. 5790 5791On RX and RL78 targets, you may specify one or more vector numbers as arguments 5792to the attribute, as well as naming an alternate table name. 5793Parameters are handled sequentially, so one handler can be assigned to 5794multiple entries in multiple tables. One may also pass the magic 5795string @code{"$default"} which causes the function to be used for any 5796unfilled slots in the current table. 5797 5798This example shows a simple assignment of a function to one vector in 5799the default table (note that preprocessor macros may be used for 5800chip-specific symbolic vector names): 5801@smallexample 5802void __attribute__ ((interrupt (5))) txd1_handler (); 5803@end smallexample 5804 5805This example assigns a function to two slots in the default table 5806(using preprocessor macros defined elsewhere) and makes it the default 5807for the @code{dct} table: 5808@smallexample 5809void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default"))) 5810 txd1_handler (); 5811@end smallexample 5812 5813@item naked 5814@cindex @code{naked} function attribute, RX 5815This attribute allows the compiler to construct the 5816requisite function declaration, while allowing the body of the 5817function to be assembly code. The specified function will not have 5818prologue/epilogue sequences generated by the compiler. Only basic 5819@code{asm} statements can safely be included in naked functions 5820(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5821basic @code{asm} and C code may appear to work, they cannot be 5822depended upon to work reliably and are not supported. 5823 5824@item vector 5825@cindex @code{vector} function attribute, RX 5826This RX attribute is similar to the @code{interrupt} attribute, including its 5827parameters, but does not make the function an interrupt-handler type 5828function (i.e.@: it retains the normal C function calling ABI). See the 5829@code{interrupt} attribute for a description of its arguments. 5830@end table 5831 5832@node S/390 Function Attributes 5833@subsection S/390 Function Attributes 5834 5835These function attributes are supported on the S/390: 5836 5837@table @code 5838@item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label}) 5839@cindex @code{hotpatch} function attribute, S/390 5840 5841On S/390 System z targets, you can use this function attribute to 5842make GCC generate a ``hot-patching'' function prologue. If the 5843@option{-mhotpatch=} command-line option is used at the same time, 5844the @code{hotpatch} attribute takes precedence. The first of the 5845two arguments specifies the number of halfwords to be added before 5846the function label. A second argument can be used to specify the 5847number of halfwords to be added after the function label. For 5848both arguments the maximum allowed value is 1000000. 5849 5850If both arguments are zero, hotpatching is disabled. 5851 5852@item target (@var{options}) 5853@cindex @code{target} function attribute 5854As discussed in @ref{Common Function Attributes}, this attribute 5855allows specification of target-specific compilation options. 5856 5857On S/390, the following options are supported: 5858 5859@table @samp 5860@item arch= 5861@item tune= 5862@item stack-guard= 5863@item stack-size= 5864@item branch-cost= 5865@item warn-framesize= 5866@item backchain 5867@itemx no-backchain 5868@item hard-dfp 5869@itemx no-hard-dfp 5870@item hard-float 5871@itemx soft-float 5872@item htm 5873@itemx no-htm 5874@item vx 5875@itemx no-vx 5876@item packed-stack 5877@itemx no-packed-stack 5878@item small-exec 5879@itemx no-small-exec 5880@item mvcle 5881@itemx no-mvcle 5882@item warn-dynamicstack 5883@itemx no-warn-dynamicstack 5884@end table 5885 5886The options work exactly like the S/390 specific command line 5887options (without the prefix @option{-m}) except that they do not 5888change any feature macros. For example, 5889 5890@smallexample 5891@code{target("no-vx")} 5892@end smallexample 5893 5894does not undefine the @code{__VEC__} macro. 5895@end table 5896 5897@node SH Function Attributes 5898@subsection SH Function Attributes 5899 5900These function attributes are supported on the SH family of processors: 5901 5902@table @code 5903@item function_vector 5904@cindex @code{function_vector} function attribute, SH 5905@cindex calling functions through the function vector on SH2A 5906On SH2A targets, this attribute declares a function to be called using the 5907TBR relative addressing mode. The argument to this attribute is the entry 5908number of the same function in a vector table containing all the TBR 5909relative addressable functions. For correct operation the TBR must be setup 5910accordingly to point to the start of the vector table before any functions with 5911this attribute are invoked. Usually a good place to do the initialization is 5912the startup routine. The TBR relative vector table can have at max 256 function 5913entries. The jumps to these functions are generated using a SH2A specific, 5914non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD 5915from GNU binutils version 2.7 or later for this attribute to work correctly. 5916 5917In an application, for a function being called once, this attribute 5918saves at least 8 bytes of code; and if other successive calls are being 5919made to the same function, it saves 2 bytes of code per each of these 5920calls. 5921 5922@item interrupt_handler 5923@cindex @code{interrupt_handler} function attribute, SH 5924Use this attribute to 5925indicate that the specified function is an interrupt handler. The compiler 5926generates function entry and exit sequences suitable for use in an 5927interrupt handler when this attribute is present. 5928 5929@item nosave_low_regs 5930@cindex @code{nosave_low_regs} function attribute, SH 5931Use this attribute on SH targets to indicate that an @code{interrupt_handler} 5932function should not save and restore registers R0..R7. This can be used on SH3* 5933and SH4* targets that have a second R0..R7 register bank for non-reentrant 5934interrupt handlers. 5935 5936@item renesas 5937@cindex @code{renesas} function attribute, SH 5938On SH targets this attribute specifies that the function or struct follows the 5939Renesas ABI. 5940 5941@item resbank 5942@cindex @code{resbank} function attribute, SH 5943On the SH2A target, this attribute enables the high-speed register 5944saving and restoration using a register bank for @code{interrupt_handler} 5945routines. Saving to the bank is performed automatically after the CPU 5946accepts an interrupt that uses a register bank. 5947 5948The nineteen 32-bit registers comprising general register R0 to R14, 5949control register GBR, and system registers MACH, MACL, and PR and the 5950vector table address offset are saved into a register bank. Register 5951banks are stacked in first-in last-out (FILO) sequence. Restoration 5952from the bank is executed by issuing a RESBANK instruction. 5953 5954@item sp_switch 5955@cindex @code{sp_switch} function attribute, SH 5956Use this attribute on the SH to indicate an @code{interrupt_handler} 5957function should switch to an alternate stack. It expects a string 5958argument that names a global variable holding the address of the 5959alternate stack. 5960 5961@smallexample 5962void *alt_stack; 5963void f () __attribute__ ((interrupt_handler, 5964 sp_switch ("alt_stack"))); 5965@end smallexample 5966 5967@item trap_exit 5968@cindex @code{trap_exit} function attribute, SH 5969Use this attribute on the SH for an @code{interrupt_handler} to return using 5970@code{trapa} instead of @code{rte}. This attribute expects an integer 5971argument specifying the trap number to be used. 5972 5973@item trapa_handler 5974@cindex @code{trapa_handler} function attribute, SH 5975On SH targets this function attribute is similar to @code{interrupt_handler} 5976but it does not save and restore all registers. 5977@end table 5978 5979@node Symbian OS Function Attributes 5980@subsection Symbian OS Function Attributes 5981 5982@xref{Microsoft Windows Function Attributes}, for discussion of the 5983@code{dllexport} and @code{dllimport} attributes. 5984 5985@node V850 Function Attributes 5986@subsection V850 Function Attributes 5987 5988The V850 back end supports these function attributes: 5989 5990@table @code 5991@item interrupt 5992@itemx interrupt_handler 5993@cindex @code{interrupt} function attribute, V850 5994@cindex @code{interrupt_handler} function attribute, V850 5995Use these attributes to indicate 5996that the specified function is an interrupt handler. The compiler generates 5997function entry and exit sequences suitable for use in an interrupt handler 5998when either attribute is present. 5999@end table 6000 6001@node Visium Function Attributes 6002@subsection Visium Function Attributes 6003 6004These function attributes are supported by the Visium back end: 6005 6006@table @code 6007@item interrupt 6008@cindex @code{interrupt} function attribute, Visium 6009Use this attribute to indicate 6010that the specified function is an interrupt handler. The compiler generates 6011function entry and exit sequences suitable for use in an interrupt handler 6012when this attribute is present. 6013@end table 6014 6015@node x86 Function Attributes 6016@subsection x86 Function Attributes 6017 6018These function attributes are supported by the x86 back end: 6019 6020@table @code 6021@item cdecl 6022@cindex @code{cdecl} function attribute, x86-32 6023@cindex functions that pop the argument stack on x86-32 6024@opindex mrtd 6025On the x86-32 targets, the @code{cdecl} attribute causes the compiler to 6026assume that the calling function pops off the stack space used to 6027pass arguments. This is 6028useful to override the effects of the @option{-mrtd} switch. 6029 6030@item fastcall 6031@cindex @code{fastcall} function attribute, x86-32 6032@cindex functions that pop the argument stack on x86-32 6033On x86-32 targets, the @code{fastcall} attribute causes the compiler to 6034pass the first argument (if of integral type) in the register ECX and 6035the second argument (if of integral type) in the register EDX@. Subsequent 6036and other typed arguments are passed on the stack. The called function 6037pops the arguments off the stack. If the number of arguments is variable all 6038arguments are pushed on the stack. 6039 6040@item thiscall 6041@cindex @code{thiscall} function attribute, x86-32 6042@cindex functions that pop the argument stack on x86-32 6043On x86-32 targets, the @code{thiscall} attribute causes the compiler to 6044pass the first argument (if of integral type) in the register ECX. 6045Subsequent and other typed arguments are passed on the stack. The called 6046function pops the arguments off the stack. 6047If the number of arguments is variable all arguments are pushed on the 6048stack. 6049The @code{thiscall} attribute is intended for C++ non-static member functions. 6050As a GCC extension, this calling convention can be used for C functions 6051and for static member methods. 6052 6053@item ms_abi 6054@itemx sysv_abi 6055@cindex @code{ms_abi} function attribute, x86 6056@cindex @code{sysv_abi} function attribute, x86 6057 6058On 32-bit and 64-bit x86 targets, you can use an ABI attribute 6059to indicate which calling convention should be used for a function. The 6060@code{ms_abi} attribute tells the compiler to use the Microsoft ABI, 6061while the @code{sysv_abi} attribute tells the compiler to use the ABI 6062used on GNU/Linux and other systems. The default is to use the Microsoft ABI 6063when targeting Windows. On all other systems, the default is the x86/AMD ABI. 6064 6065Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently 6066requires the @option{-maccumulate-outgoing-args} option. 6067 6068@item callee_pop_aggregate_return (@var{number}) 6069@cindex @code{callee_pop_aggregate_return} function attribute, x86 6070 6071On x86-32 targets, you can use this attribute to control how 6072aggregates are returned in memory. If the caller is responsible for 6073popping the hidden pointer together with the rest of the arguments, specify 6074@var{number} equal to zero. If callee is responsible for popping the 6075hidden pointer, specify @var{number} equal to one. 6076 6077The default x86-32 ABI assumes that the callee pops the 6078stack for hidden pointer. However, on x86-32 Microsoft Windows targets, 6079the compiler assumes that the 6080caller pops the stack for hidden pointer. 6081 6082@item ms_hook_prologue 6083@cindex @code{ms_hook_prologue} function attribute, x86 6084 6085On 32-bit and 64-bit x86 targets, you can use 6086this function attribute to make GCC generate the ``hot-patching'' function 6087prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2 6088and newer. 6089 6090@item naked 6091@cindex @code{naked} function attribute, x86 6092This attribute allows the compiler to construct the 6093requisite function declaration, while allowing the body of the 6094function to be assembly code. The specified function will not have 6095prologue/epilogue sequences generated by the compiler. Only basic 6096@code{asm} statements can safely be included in naked functions 6097(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 6098basic @code{asm} and C code may appear to work, they cannot be 6099depended upon to work reliably and are not supported. 6100 6101@item regparm (@var{number}) 6102@cindex @code{regparm} function attribute, x86 6103@cindex functions that are passed arguments in registers on x86-32 6104On x86-32 targets, the @code{regparm} attribute causes the compiler to 6105pass arguments number one to @var{number} if they are of integral type 6106in registers EAX, EDX, and ECX instead of on the stack. Functions that 6107take a variable number of arguments continue to be passed all of their 6108arguments on the stack. 6109 6110Beware that on some ELF systems this attribute is unsuitable for 6111global functions in shared libraries with lazy binding (which is the 6112default). Lazy binding sends the first call via resolving code in 6113the loader, which might assume EAX, EDX and ECX can be clobbered, as 6114per the standard calling conventions. Solaris 8 is affected by this. 6115Systems with the GNU C Library version 2.1 or higher 6116and FreeBSD are believed to be 6117safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be 6118disabled with the linker or the loader if desired, to avoid the 6119problem.) 6120 6121@item sseregparm 6122@cindex @code{sseregparm} function attribute, x86 6123On x86-32 targets with SSE support, the @code{sseregparm} attribute 6124causes the compiler to pass up to 3 floating-point arguments in 6125SSE registers instead of on the stack. Functions that take a 6126variable number of arguments continue to pass all of their 6127floating-point arguments on the stack. 6128 6129@item force_align_arg_pointer 6130@cindex @code{force_align_arg_pointer} function attribute, x86 6131On x86 targets, the @code{force_align_arg_pointer} attribute may be 6132applied to individual function definitions, generating an alternate 6133prologue and epilogue that realigns the run-time stack if necessary. 6134This supports mixing legacy codes that run with a 4-byte aligned stack 6135with modern codes that keep a 16-byte stack for SSE compatibility. 6136 6137@item stdcall 6138@cindex @code{stdcall} function attribute, x86-32 6139@cindex functions that pop the argument stack on x86-32 6140On x86-32 targets, the @code{stdcall} attribute causes the compiler to 6141assume that the called function pops off the stack space used to 6142pass arguments, unless it takes a variable number of arguments. 6143 6144@item no_caller_saved_registers 6145@cindex @code{no_caller_saved_registers} function attribute, x86 6146Use this attribute to indicate that the specified function has no 6147caller-saved registers. That is, all registers are callee-saved. For 6148example, this attribute can be used for a function called from an 6149interrupt handler. The compiler generates proper function entry and 6150exit sequences to save and restore any modified registers, except for 6151the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87 6152states, the GCC option @option{-mgeneral-regs-only} should be used to 6153compile functions with @code{no_caller_saved_registers} attribute. 6154 6155@item interrupt 6156@cindex @code{interrupt} function attribute, x86 6157Use this attribute to indicate that the specified function is an 6158interrupt handler or an exception handler (depending on parameters passed 6159to the function, explained further). The compiler generates function 6160entry and exit sequences suitable for use in an interrupt handler when 6161this attribute is present. The @code{IRET} instruction, instead of the 6162@code{RET} instruction, is used to return from interrupt handlers. All 6163registers, except for the EFLAGS register which is restored by the 6164@code{IRET} instruction, are preserved by the compiler. Since GCC 6165doesn't preserve SSE, MMX nor x87 states, the GCC option 6166@option{-mgeneral-regs-only} should be used to compile interrupt and 6167exception handlers. 6168 6169Any interruptible-without-stack-switch code must be compiled with 6170@option{-mno-red-zone} since interrupt handlers can and will, because 6171of the hardware design, touch the red zone. 6172 6173An interrupt handler must be declared with a mandatory pointer 6174argument: 6175 6176@smallexample 6177struct interrupt_frame; 6178 6179__attribute__ ((interrupt)) 6180void 6181f (struct interrupt_frame *frame) 6182@{ 6183@} 6184@end smallexample 6185 6186@noindent 6187and you must define @code{struct interrupt_frame} as described in the 6188processor's manual. 6189 6190Exception handlers differ from interrupt handlers because the system 6191pushes an error code on the stack. An exception handler declaration is 6192similar to that for an interrupt handler, but with a different mandatory 6193function signature. The compiler arranges to pop the error code off the 6194stack before the @code{IRET} instruction. 6195 6196@smallexample 6197#ifdef __x86_64__ 6198typedef unsigned long long int uword_t; 6199#else 6200typedef unsigned int uword_t; 6201#endif 6202 6203struct interrupt_frame; 6204 6205__attribute__ ((interrupt)) 6206void 6207f (struct interrupt_frame *frame, uword_t error_code) 6208@{ 6209 ... 6210@} 6211@end smallexample 6212 6213Exception handlers should only be used for exceptions that push an error 6214code; you should use an interrupt handler in other cases. The system 6215will crash if the wrong kind of handler is used. 6216 6217@item target (@var{options}) 6218@cindex @code{target} function attribute 6219As discussed in @ref{Common Function Attributes}, this attribute 6220allows specification of target-specific compilation options. 6221 6222On the x86, the following options are allowed: 6223@table @samp 6224@item 3dnow 6225@itemx no-3dnow 6226@cindex @code{target("3dnow")} function attribute, x86 6227Enable/disable the generation of the 3DNow!@: instructions. 6228 6229@item 3dnowa 6230@itemx no-3dnowa 6231@cindex @code{target("3dnowa")} function attribute, x86 6232Enable/disable the generation of the enhanced 3DNow!@: instructions. 6233 6234@item abm 6235@itemx no-abm 6236@cindex @code{target("abm")} function attribute, x86 6237Enable/disable the generation of the advanced bit instructions. 6238 6239@item adx 6240@itemx no-adx 6241@cindex @code{target("adx")} function attribute, x86 6242Enable/disable the generation of the ADX instructions. 6243 6244@item aes 6245@itemx no-aes 6246@cindex @code{target("aes")} function attribute, x86 6247Enable/disable the generation of the AES instructions. 6248 6249@item avx 6250@itemx no-avx 6251@cindex @code{target("avx")} function attribute, x86 6252Enable/disable the generation of the AVX instructions. 6253 6254@item avx2 6255@itemx no-avx2 6256@cindex @code{target("avx2")} function attribute, x86 6257Enable/disable the generation of the AVX2 instructions. 6258 6259@item avx5124fmaps 6260@itemx no-avx5124fmaps 6261@cindex @code{target("avx5124fmaps")} function attribute, x86 6262Enable/disable the generation of the AVX5124FMAPS instructions. 6263 6264@item avx5124vnniw 6265@itemx no-avx5124vnniw 6266@cindex @code{target("avx5124vnniw")} function attribute, x86 6267Enable/disable the generation of the AVX5124VNNIW instructions. 6268 6269@item avx512bitalg 6270@itemx no-avx512bitalg 6271@cindex @code{target("avx512bitalg")} function attribute, x86 6272Enable/disable the generation of the AVX512BITALG instructions. 6273 6274@item avx512bw 6275@itemx no-avx512bw 6276@cindex @code{target("avx512bw")} function attribute, x86 6277Enable/disable the generation of the AVX512BW instructions. 6278 6279@item avx512cd 6280@itemx no-avx512cd 6281@cindex @code{target("avx512cd")} function attribute, x86 6282Enable/disable the generation of the AVX512CD instructions. 6283 6284@item avx512dq 6285@itemx no-avx512dq 6286@cindex @code{target("avx512dq")} function attribute, x86 6287Enable/disable the generation of the AVX512DQ instructions. 6288 6289@item avx512er 6290@itemx no-avx512er 6291@cindex @code{target("avx512er")} function attribute, x86 6292Enable/disable the generation of the AVX512ER instructions. 6293 6294@item avx512f 6295@itemx no-avx512f 6296@cindex @code{target("avx512f")} function attribute, x86 6297Enable/disable the generation of the AVX512F instructions. 6298 6299@item avx512ifma 6300@itemx no-avx512ifma 6301@cindex @code{target("avx512ifma")} function attribute, x86 6302Enable/disable the generation of the AVX512IFMA instructions. 6303 6304@item avx512pf 6305@itemx no-avx512pf 6306@cindex @code{target("avx512pf")} function attribute, x86 6307Enable/disable the generation of the AVX512PF instructions. 6308 6309@item avx512vbmi 6310@itemx no-avx512vbmi 6311@cindex @code{target("avx512vbmi")} function attribute, x86 6312Enable/disable the generation of the AVX512VBMI instructions. 6313 6314@item avx512vbmi2 6315@itemx no-avx512vbmi2 6316@cindex @code{target("avx512vbmi2")} function attribute, x86 6317Enable/disable the generation of the AVX512VBMI2 instructions. 6318 6319@item avx512vl 6320@itemx no-avx512vl 6321@cindex @code{target("avx512vl")} function attribute, x86 6322Enable/disable the generation of the AVX512VL instructions. 6323 6324@item avx512vnni 6325@itemx no-avx512vnni 6326@cindex @code{target("avx512vnni")} function attribute, x86 6327Enable/disable the generation of the AVX512VNNI instructions. 6328 6329@item avx512vpopcntdq 6330@itemx no-avx512vpopcntdq 6331@cindex @code{target("avx512vpopcntdq")} function attribute, x86 6332Enable/disable the generation of the AVX512VPOPCNTDQ instructions. 6333 6334@item bmi 6335@itemx no-bmi 6336@cindex @code{target("bmi")} function attribute, x86 6337Enable/disable the generation of the BMI instructions. 6338 6339@item bmi2 6340@itemx no-bmi2 6341@cindex @code{target("bmi2")} function attribute, x86 6342Enable/disable the generation of the BMI2 instructions. 6343 6344@item cldemote 6345@itemx no-cldemote 6346@cindex @code{target("cldemote")} function attribute, x86 6347Enable/disable the generation of the CLDEMOTE instructions. 6348 6349@item clflushopt 6350@itemx no-clflushopt 6351@cindex @code{target("clflushopt")} function attribute, x86 6352Enable/disable the generation of the CLFLUSHOPT instructions. 6353 6354@item clwb 6355@itemx no-clwb 6356@cindex @code{target("clwb")} function attribute, x86 6357Enable/disable the generation of the CLWB instructions. 6358 6359@item clzero 6360@itemx no-clzero 6361@cindex @code{target("clzero")} function attribute, x86 6362Enable/disable the generation of the CLZERO instructions. 6363 6364@item crc32 6365@itemx no-crc32 6366@cindex @code{target("crc32")} function attribute, x86 6367Enable/disable the generation of the CRC32 instructions. 6368 6369@item cx16 6370@itemx no-cx16 6371@cindex @code{target("cx16")} function attribute, x86 6372Enable/disable the generation of the CMPXCHG16B instructions. 6373 6374@item default 6375@cindex @code{target("default")} function attribute, x86 6376@xref{Function Multiversioning}, where it is used to specify the 6377default function version. 6378 6379@item f16c 6380@itemx no-f16c 6381@cindex @code{target("f16c")} function attribute, x86 6382Enable/disable the generation of the F16C instructions. 6383 6384@item fma 6385@itemx no-fma 6386@cindex @code{target("fma")} function attribute, x86 6387Enable/disable the generation of the FMA instructions. 6388 6389@item fma4 6390@itemx no-fma4 6391@cindex @code{target("fma4")} function attribute, x86 6392Enable/disable the generation of the FMA4 instructions. 6393 6394@item fsgsbase 6395@itemx no-fsgsbase 6396@cindex @code{target("fsgsbase")} function attribute, x86 6397Enable/disable the generation of the FSGSBASE instructions. 6398 6399@item fxsr 6400@itemx no-fxsr 6401@cindex @code{target("fxsr")} function attribute, x86 6402Enable/disable the generation of the FXSR instructions. 6403 6404@item gfni 6405@itemx no-gfni 6406@cindex @code{target("gfni")} function attribute, x86 6407Enable/disable the generation of the GFNI instructions. 6408 6409@item hle 6410@itemx no-hle 6411@cindex @code{target("hle")} function attribute, x86 6412Enable/disable the generation of the HLE instruction prefixes. 6413 6414@item lwp 6415@itemx no-lwp 6416@cindex @code{target("lwp")} function attribute, x86 6417Enable/disable the generation of the LWP instructions. 6418 6419@item lzcnt 6420@itemx no-lzcnt 6421@cindex @code{target("lzcnt")} function attribute, x86 6422Enable/disable the generation of the LZCNT instructions. 6423 6424@item mmx 6425@itemx no-mmx 6426@cindex @code{target("mmx")} function attribute, x86 6427Enable/disable the generation of the MMX instructions. 6428 6429@item movbe 6430@itemx no-movbe 6431@cindex @code{target("movbe")} function attribute, x86 6432Enable/disable the generation of the MOVBE instructions. 6433 6434@item movdir64b 6435@itemx no-movdir64b 6436@cindex @code{target("movdir64b")} function attribute, x86 6437Enable/disable the generation of the MOVDIR64B instructions. 6438 6439@item movdiri 6440@itemx no-movdiri 6441@cindex @code{target("movdiri")} function attribute, x86 6442Enable/disable the generation of the MOVDIRI instructions. 6443 6444@item mwaitx 6445@itemx no-mwaitx 6446@cindex @code{target("mwaitx")} function attribute, x86 6447Enable/disable the generation of the MWAITX instructions. 6448 6449@item pclmul 6450@itemx no-pclmul 6451@cindex @code{target("pclmul")} function attribute, x86 6452Enable/disable the generation of the PCLMUL instructions. 6453 6454@item pconfig 6455@itemx no-pconfig 6456@cindex @code{target("pconfig")} function attribute, x86 6457Enable/disable the generation of the PCONFIG instructions. 6458 6459@item pku 6460@itemx no-pku 6461@cindex @code{target("pku")} function attribute, x86 6462Enable/disable the generation of the PKU instructions. 6463 6464@item popcnt 6465@itemx no-popcnt 6466@cindex @code{target("popcnt")} function attribute, x86 6467Enable/disable the generation of the POPCNT instruction. 6468 6469@item prefetchwt1 6470@itemx no-prefetchwt1 6471@cindex @code{target("prefetchwt1")} function attribute, x86 6472Enable/disable the generation of the PREFETCHWT1 instructions. 6473 6474@item prfchw 6475@itemx no-prfchw 6476@cindex @code{target("prfchw")} function attribute, x86 6477Enable/disable the generation of the PREFETCHW instruction. 6478 6479@item ptwrite 6480@itemx no-ptwrite 6481@cindex @code{target("ptwrite")} function attribute, x86 6482Enable/disable the generation of the PTWRITE instructions. 6483 6484@item rdpid 6485@itemx no-rdpid 6486@cindex @code{target("rdpid")} function attribute, x86 6487Enable/disable the generation of the RDPID instructions. 6488 6489@item rdrnd 6490@itemx no-rdrnd 6491@cindex @code{target("rdrnd")} function attribute, x86 6492Enable/disable the generation of the RDRND instructions. 6493 6494@item rdseed 6495@itemx no-rdseed 6496@cindex @code{target("rdseed")} function attribute, x86 6497Enable/disable the generation of the RDSEED instructions. 6498 6499@item rtm 6500@itemx no-rtm 6501@cindex @code{target("rtm")} function attribute, x86 6502Enable/disable the generation of the RTM instructions. 6503 6504@item sahf 6505@itemx no-sahf 6506@cindex @code{target("sahf")} function attribute, x86 6507Enable/disable the generation of the SAHF instructions. 6508 6509@item sgx 6510@itemx no-sgx 6511@cindex @code{target("sgx")} function attribute, x86 6512Enable/disable the generation of the SGX instructions. 6513 6514@item sha 6515@itemx no-sha 6516@cindex @code{target("sha")} function attribute, x86 6517Enable/disable the generation of the SHA instructions. 6518 6519@item shstk 6520@itemx no-shstk 6521@cindex @code{target("shstk")} function attribute, x86 6522Enable/disable the shadow stack built-in functions from CET. 6523 6524@item sse 6525@itemx no-sse 6526@cindex @code{target("sse")} function attribute, x86 6527Enable/disable the generation of the SSE instructions. 6528 6529@item sse2 6530@itemx no-sse2 6531@cindex @code{target("sse2")} function attribute, x86 6532Enable/disable the generation of the SSE2 instructions. 6533 6534@item sse3 6535@itemx no-sse3 6536@cindex @code{target("sse3")} function attribute, x86 6537Enable/disable the generation of the SSE3 instructions. 6538 6539@item sse4 6540@itemx no-sse4 6541@cindex @code{target("sse4")} function attribute, x86 6542Enable/disable the generation of the SSE4 instructions (both SSE4.1 6543and SSE4.2). 6544 6545@item sse4.1 6546@itemx no-sse4.1 6547@cindex @code{target("sse4.1")} function attribute, x86 6548Enable/disable the generation of the sse4.1 instructions. 6549 6550@item sse4.2 6551@itemx no-sse4.2 6552@cindex @code{target("sse4.2")} function attribute, x86 6553Enable/disable the generation of the sse4.2 instructions. 6554 6555@item sse4a 6556@itemx no-sse4a 6557@cindex @code{target("sse4a")} function attribute, x86 6558Enable/disable the generation of the SSE4A instructions. 6559 6560@item ssse3 6561@itemx no-ssse3 6562@cindex @code{target("ssse3")} function attribute, x86 6563Enable/disable the generation of the SSSE3 instructions. 6564 6565@item tbm 6566@itemx no-tbm 6567@cindex @code{target("tbm")} function attribute, x86 6568Enable/disable the generation of the TBM instructions. 6569 6570@item vaes 6571@itemx no-vaes 6572@cindex @code{target("vaes")} function attribute, x86 6573Enable/disable the generation of the VAES instructions. 6574 6575@item vpclmulqdq 6576@itemx no-vpclmulqdq 6577@cindex @code{target("vpclmulqdq")} function attribute, x86 6578Enable/disable the generation of the VPCLMULQDQ instructions. 6579 6580@item waitpkg 6581@itemx no-waitpkg 6582@cindex @code{target("waitpkg")} function attribute, x86 6583Enable/disable the generation of the WAITPKG instructions. 6584 6585@item wbnoinvd 6586@itemx no-wbnoinvd 6587@cindex @code{target("wbnoinvd")} function attribute, x86 6588Enable/disable the generation of the WBNOINVD instructions. 6589 6590@item xop 6591@itemx no-xop 6592@cindex @code{target("xop")} function attribute, x86 6593Enable/disable the generation of the XOP instructions. 6594 6595@item xsave 6596@itemx no-xsave 6597@cindex @code{target("xsave")} function attribute, x86 6598Enable/disable the generation of the XSAVE instructions. 6599 6600@item xsavec 6601@itemx no-xsavec 6602@cindex @code{target("xsavec")} function attribute, x86 6603Enable/disable the generation of the XSAVEC instructions. 6604 6605@item xsaveopt 6606@itemx no-xsaveopt 6607@cindex @code{target("xsaveopt")} function attribute, x86 6608Enable/disable the generation of the XSAVEOPT instructions. 6609 6610@item xsaves 6611@itemx no-xsaves 6612@cindex @code{target("xsaves")} function attribute, x86 6613Enable/disable the generation of the XSAVES instructions. 6614 6615@item cld 6616@itemx no-cld 6617@cindex @code{target("cld")} function attribute, x86 6618Enable/disable the generation of the CLD before string moves. 6619 6620@item fancy-math-387 6621@itemx no-fancy-math-387 6622@cindex @code{target("fancy-math-387")} function attribute, x86 6623Enable/disable the generation of the @code{sin}, @code{cos}, and 6624@code{sqrt} instructions on the 387 floating-point unit. 6625 6626@item ieee-fp 6627@itemx no-ieee-fp 6628@cindex @code{target("ieee-fp")} function attribute, x86 6629Enable/disable the generation of floating point that depends on IEEE arithmetic. 6630 6631@item inline-all-stringops 6632@itemx no-inline-all-stringops 6633@cindex @code{target("inline-all-stringops")} function attribute, x86 6634Enable/disable inlining of string operations. 6635 6636@item inline-stringops-dynamically 6637@itemx no-inline-stringops-dynamically 6638@cindex @code{target("inline-stringops-dynamically")} function attribute, x86 6639Enable/disable the generation of the inline code to do small string 6640operations and calling the library routines for large operations. 6641 6642@item align-stringops 6643@itemx no-align-stringops 6644@cindex @code{target("align-stringops")} function attribute, x86 6645Do/do not align destination of inlined string operations. 6646 6647@item recip 6648@itemx no-recip 6649@cindex @code{target("recip")} function attribute, x86 6650Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS 6651instructions followed an additional Newton-Raphson step instead of 6652doing a floating-point division. 6653 6654@item arch=@var{ARCH} 6655@cindex @code{target("arch=@var{ARCH}")} function attribute, x86 6656Specify the architecture to generate code for in compiling the function. 6657 6658@item tune=@var{TUNE} 6659@cindex @code{target("tune=@var{TUNE}")} function attribute, x86 6660Specify the architecture to tune for in compiling the function. 6661 6662@item fpmath=@var{FPMATH} 6663@cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86 6664Specify which floating-point unit to use. You must specify the 6665@code{target("fpmath=sse,387")} option as 6666@code{target("fpmath=sse+387")} because the comma would separate 6667different options. 6668 6669@item indirect_branch("@var{choice}") 6670@cindex @code{indirect_branch} function attribute, x86 6671On x86 targets, the @code{indirect_branch} attribute causes the compiler 6672to convert indirect call and jump with @var{choice}. @samp{keep} 6673keeps indirect call and jump unmodified. @samp{thunk} converts indirect 6674call and jump to call and return thunk. @samp{thunk-inline} converts 6675indirect call and jump to inlined call and return thunk. 6676@samp{thunk-extern} converts indirect call and jump to external call 6677and return thunk provided in a separate object file. 6678 6679@item function_return("@var{choice}") 6680@cindex @code{function_return} function attribute, x86 6681On x86 targets, the @code{function_return} attribute causes the compiler 6682to convert function return with @var{choice}. @samp{keep} keeps function 6683return unmodified. @samp{thunk} converts function return to call and 6684return thunk. @samp{thunk-inline} converts function return to inlined 6685call and return thunk. @samp{thunk-extern} converts function return to 6686external call and return thunk provided in a separate object file. 6687 6688@item nocf_check 6689@cindex @code{nocf_check} function attribute 6690The @code{nocf_check} attribute on a function is used to inform the 6691compiler that the function's prologue should not be instrumented when 6692compiled with the @option{-fcf-protection=branch} option. The 6693compiler assumes that the function's address is a valid target for a 6694control-flow transfer. 6695 6696The @code{nocf_check} attribute on a type of pointer to function is 6697used to inform the compiler that a call through the pointer should 6698not be instrumented when compiled with the 6699@option{-fcf-protection=branch} option. The compiler assumes 6700that the function's address from the pointer is a valid target for 6701a control-flow transfer. A direct function call through a function 6702name is assumed to be a safe call thus direct calls are not 6703instrumented by the compiler. 6704 6705The @code{nocf_check} attribute is applied to an object's type. 6706In case of assignment of a function address or a function pointer to 6707another pointer, the attribute is not carried over from the right-hand 6708object's type; the type of left-hand object stays unchanged. The 6709compiler checks for @code{nocf_check} attribute mismatch and reports 6710a warning in case of mismatch. 6711 6712@smallexample 6713@{ 6714int foo (void) __attribute__(nocf_check); 6715void (*foo1)(void) __attribute__(nocf_check); 6716void (*foo2)(void); 6717 6718/* foo's address is assumed to be valid. */ 6719int 6720foo (void) 6721 6722 /* This call site is not checked for control-flow 6723 validity. */ 6724 (*foo1)(); 6725 6726 /* A warning is issued about attribute mismatch. */ 6727 foo1 = foo2; 6728 6729 /* This call site is still not checked. */ 6730 (*foo1)(); 6731 6732 /* This call site is checked. */ 6733 (*foo2)(); 6734 6735 /* A warning is issued about attribute mismatch. */ 6736 foo2 = foo1; 6737 6738 /* This call site is still checked. */ 6739 (*foo2)(); 6740 6741 return 0; 6742@} 6743@end smallexample 6744 6745@item cf_check 6746@cindex @code{cf_check} function attribute, x86 6747 6748The @code{cf_check} attribute on a function is used to inform the 6749compiler that ENDBR instruction should be placed at the function 6750entry when @option{-fcf-protection=branch} is enabled. 6751 6752@item indirect_return 6753@cindex @code{indirect_return} function attribute, x86 6754 6755The @code{indirect_return} attribute can be applied to a function, 6756as well as variable or type of function pointer to inform the 6757compiler that the function may return via indirect branch. 6758 6759@item fentry_name("@var{name}") 6760@cindex @code{fentry_name} function attribute, x86 6761On x86 targets, the @code{fentry_name} attribute sets the function to 6762call on function entry when function instrumentation is enabled 6763with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte 6764nop sequence is generated. 6765 6766@item fentry_section("@var{name}") 6767@cindex @code{fentry_section} function attribute, x86 6768On x86 targets, the @code{fentry_section} attribute sets the name 6769of the section to record function entry instrumentation calls in when 6770enabled with @option{-pg -mrecord-mcount} 6771 6772@end table 6773 6774On the x86, the inliner does not inline a 6775function that has different target options than the caller, unless the 6776callee has a subset of the target options of the caller. For example 6777a function declared with @code{target("sse3")} can inline a function 6778with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}. 6779@end table 6780 6781@node Xstormy16 Function Attributes 6782@subsection Xstormy16 Function Attributes 6783 6784These function attributes are supported by the Xstormy16 back end: 6785 6786@table @code 6787@item interrupt 6788@cindex @code{interrupt} function attribute, Xstormy16 6789Use this attribute to indicate 6790that the specified function is an interrupt handler. The compiler generates 6791function entry and exit sequences suitable for use in an interrupt handler 6792when this attribute is present. 6793@end table 6794 6795@node Variable Attributes 6796@section Specifying Attributes of Variables 6797@cindex attribute of variables 6798@cindex variable attributes 6799 6800The keyword @code{__attribute__} allows you to specify special properties 6801of variables, function parameters, or structure, union, and, in C++, class 6802members. This @code{__attribute__} keyword is followed by an attribute 6803specification enclosed in double parentheses. Some attributes are currently 6804defined generically for variables. Other attributes are defined for 6805variables on particular target systems. Other attributes are available 6806for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}), 6807enumerators (@pxref{Enumerator Attributes}), statements 6808(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}). 6809Other front ends might define more attributes 6810(@pxref{C++ Extensions,,Extensions to the C++ Language}). 6811 6812@xref{Attribute Syntax}, for details of the exact syntax for using 6813attributes. 6814 6815@menu 6816* Common Variable Attributes:: 6817* ARC Variable Attributes:: 6818* AVR Variable Attributes:: 6819* Blackfin Variable Attributes:: 6820* H8/300 Variable Attributes:: 6821* IA-64 Variable Attributes:: 6822* M32R/D Variable Attributes:: 6823* MeP Variable Attributes:: 6824* Microsoft Windows Variable Attributes:: 6825* MSP430 Variable Attributes:: 6826* Nvidia PTX Variable Attributes:: 6827* PowerPC Variable Attributes:: 6828* RL78 Variable Attributes:: 6829* V850 Variable Attributes:: 6830* x86 Variable Attributes:: 6831* Xstormy16 Variable Attributes:: 6832@end menu 6833 6834@node Common Variable Attributes 6835@subsection Common Variable Attributes 6836 6837The following attributes are supported on most targets. 6838 6839@table @code 6840 6841@item alias ("@var{target}") 6842@cindex @code{alias} variable attribute 6843The @code{alias} variable attribute causes the declaration to be emitted 6844as an alias for another symbol known as an @dfn{alias target}. Except 6845for top-level qualifiers the alias target must have the same type as 6846the alias. For instance, the following 6847 6848@smallexample 6849int var_target; 6850extern int __attribute__ ((alias ("var_target"))) var_alias; 6851@end smallexample 6852 6853@noindent 6854defines @code{var_alias} to be an alias for the @code{var_target} variable. 6855 6856It is an error if the alias target is not defined in the same translation 6857unit as the alias. 6858 6859Note that in the absence of the attribute GCC assumes that distinct 6860declarations with external linkage denote distinct objects. Using both 6861the alias and the alias target to access the same object is undefined 6862in a translation unit without a declaration of the alias with the attribute. 6863 6864This attribute requires assembler and object file support, and may not be 6865available on all targets. 6866 6867@cindex @code{aligned} variable attribute 6868@item aligned 6869@itemx aligned (@var{alignment}) 6870The @code{aligned} attribute specifies a minimum alignment for the variable 6871or structure field, measured in bytes. When specified, @var{alignment} must 6872be an integer constant power of 2. Specifying no @var{alignment} argument 6873implies the maximum alignment for the target, which is often, but by no 6874means always, 8 or 16 bytes. 6875 6876For example, the declaration: 6877 6878@smallexample 6879int x __attribute__ ((aligned (16))) = 0; 6880@end smallexample 6881 6882@noindent 6883causes the compiler to allocate the global variable @code{x} on a 688416-byte boundary. On a 68040, this could be used in conjunction with 6885an @code{asm} expression to access the @code{move16} instruction which 6886requires 16-byte aligned operands. 6887 6888You can also specify the alignment of structure fields. For example, to 6889create a double-word aligned @code{int} pair, you could write: 6890 6891@smallexample 6892struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; 6893@end smallexample 6894 6895@noindent 6896This is an alternative to creating a union with a @code{double} member, 6897which forces the union to be double-word aligned. 6898 6899As in the preceding examples, you can explicitly specify the alignment 6900(in bytes) that you wish the compiler to use for a given variable or 6901structure field. Alternatively, you can leave out the alignment factor 6902and just ask the compiler to align a variable or field to the 6903default alignment for the target architecture you are compiling for. 6904The default alignment is sufficient for all scalar types, but may not be 6905enough for all vector types on a target that supports vector operations. 6906The default alignment is fixed for a particular target ABI. 6907 6908GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__}, 6909which is the largest alignment ever used for any data type on the 6910target machine you are compiling for. For example, you could write: 6911 6912@smallexample 6913short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); 6914@end smallexample 6915 6916The compiler automatically sets the alignment for the declared 6917variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can 6918often make copy operations more efficient, because the compiler can 6919use whatever instructions copy the biggest chunks of memory when 6920performing copies to or from the variables or fields that you have 6921aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__} 6922may change depending on command-line options. 6923 6924When used on a struct, or struct member, the @code{aligned} attribute can 6925only increase the alignment; in order to decrease it, the @code{packed} 6926attribute must be specified as well. When used as part of a typedef, the 6927@code{aligned} attribute can both increase and decrease alignment, and 6928specifying the @code{packed} attribute generates a warning. 6929 6930Note that the effectiveness of @code{aligned} attributes for static 6931variables may be limited by inherent limitations in the system linker 6932and/or object file format. On some systems, the linker is 6933only able to arrange for variables to be aligned up to a certain maximum 6934alignment. (For some linkers, the maximum supported alignment may 6935be very very small.) If your linker is only able to align variables 6936up to a maximum of 8-byte alignment, then specifying @code{aligned(16)} 6937in an @code{__attribute__} still only provides you with 8-byte 6938alignment. See your linker documentation for further information. 6939 6940Stack variables are not affected by linker restrictions; GCC can properly 6941align them on any target. 6942 6943The @code{aligned} attribute can also be used for functions 6944(@pxref{Common Function Attributes}.) 6945 6946@cindex @code{warn_if_not_aligned} variable attribute 6947@item warn_if_not_aligned (@var{alignment}) 6948This attribute specifies a threshold for the structure field, measured 6949in bytes. If the structure field is aligned below the threshold, a 6950warning will be issued. For example, the declaration: 6951 6952@smallexample 6953struct foo 6954@{ 6955 int i1; 6956 int i2; 6957 unsigned long long x __attribute__ ((warn_if_not_aligned (16))); 6958@}; 6959@end smallexample 6960 6961@noindent 6962causes the compiler to issue an warning on @code{struct foo}, like 6963@samp{warning: alignment 8 of 'struct foo' is less than 16}. 6964The compiler also issues a warning, like @samp{warning: 'x' offset 69658 in 'struct foo' isn't aligned to 16}, when the structure field has 6966the misaligned offset: 6967 6968@smallexample 6969struct __attribute__ ((aligned (16))) foo 6970@{ 6971 int i1; 6972 int i2; 6973 unsigned long long x __attribute__ ((warn_if_not_aligned (16))); 6974@}; 6975@end smallexample 6976 6977This warning can be disabled by @option{-Wno-if-not-aligned}. 6978The @code{warn_if_not_aligned} attribute can also be used for types 6979(@pxref{Common Type Attributes}.) 6980 6981@item alloc_size (@var{position}) 6982@itemx alloc_size (@var{position-1}, @var{position-2}) 6983@cindex @code{alloc_size} variable attribute 6984The @code{alloc_size} variable attribute may be applied to the declaration 6985of a pointer to a function that returns a pointer and takes at least one 6986argument of an integer type. It indicates that the returned pointer points 6987to an object whose size is given by the function argument at @var{position-1}, 6988or by the product of the arguments at @var{position-1} and @var{position-2}. 6989Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other 6990sizes are disagnosed when detected. GCC uses this information to improve 6991the results of @code{__builtin_object_size}. 6992 6993For instance, the following declarations 6994 6995@smallexample 6996typedef __attribute__ ((alloc_size (1, 2))) void* 6997 (*calloc_ptr) (size_t, size_t); 6998typedef __attribute__ ((alloc_size (1))) void* 6999 (*malloc_ptr) (size_t); 7000@end smallexample 7001 7002@noindent 7003specify that @code{calloc_ptr} is a pointer of a function that, like 7004the standard C function @code{calloc}, returns an object whose size 7005is given by the product of arguments 1 and 2, and similarly, that 7006@code{malloc_ptr}, like the standard C function @code{malloc}, 7007returns an object whose size is given by argument 1 to the function. 7008 7009@item cleanup (@var{cleanup_function}) 7010@cindex @code{cleanup} variable attribute 7011The @code{cleanup} attribute runs a function when the variable goes 7012out of scope. This attribute can only be applied to auto function 7013scope variables; it may not be applied to parameters or variables 7014with static storage duration. The function must take one parameter, 7015a pointer to a type compatible with the variable. The return value 7016of the function (if any) is ignored. 7017 7018If @option{-fexceptions} is enabled, then @var{cleanup_function} 7019is run during the stack unwinding that happens during the 7020processing of the exception. Note that the @code{cleanup} attribute 7021does not allow the exception to be caught, only to perform an action. 7022It is undefined what happens if @var{cleanup_function} does not 7023return normally. 7024 7025@item common 7026@itemx nocommon 7027@cindex @code{common} variable attribute 7028@cindex @code{nocommon} variable attribute 7029@opindex fcommon 7030@opindex fno-common 7031The @code{common} attribute requests GCC to place a variable in 7032``common'' storage. The @code{nocommon} attribute requests the 7033opposite---to allocate space for it directly. 7034 7035These attributes override the default chosen by the 7036@option{-fno-common} and @option{-fcommon} flags respectively. 7037 7038@item copy 7039@itemx copy (@var{variable}) 7040@cindex @code{copy} variable attribute 7041The @code{copy} attribute applies the set of attributes with which 7042@var{variable} has been declared to the declaration of the variable 7043to which the attribute is applied. The attribute is designed for 7044libraries that define aliases that are expected to specify the same 7045set of attributes as the aliased symbols. The @code{copy} attribute 7046can be used with variables, functions or types. However, the kind 7047of symbol to which the attribute is applied (either varible or 7048function) must match the kind of symbol to which the argument refers. 7049The @code{copy} attribute copies only syntactic and semantic attributes 7050but not attributes that affect a symbol's linkage or visibility such as 7051@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} 7052attribute is also not copied. @xref{Common Function Attributes}. 7053@xref{Common Type Attributes}. 7054 7055@item deprecated 7056@itemx deprecated (@var{msg}) 7057@cindex @code{deprecated} variable attribute 7058The @code{deprecated} attribute results in a warning if the variable 7059is used anywhere in the source file. This is useful when identifying 7060variables that are expected to be removed in a future version of a 7061program. The warning also includes the location of the declaration 7062of the deprecated variable, to enable users to easily find further 7063information about why the variable is deprecated, or what they should 7064do instead. Note that the warning only occurs for uses: 7065 7066@smallexample 7067extern int old_var __attribute__ ((deprecated)); 7068extern int old_var; 7069int new_fn () @{ return old_var; @} 7070@end smallexample 7071 7072@noindent 7073results in a warning on line 3 but not line 2. The optional @var{msg} 7074argument, which must be a string, is printed in the warning if 7075present. 7076 7077The @code{deprecated} attribute can also be used for functions and 7078types (@pxref{Common Function Attributes}, 7079@pxref{Common Type Attributes}). 7080 7081The message attached to the attribute is affected by the setting of 7082the @option{-fmessage-length} option. 7083 7084@item mode (@var{mode}) 7085@cindex @code{mode} variable attribute 7086This attribute specifies the data type for the declaration---whichever 7087type corresponds to the mode @var{mode}. This in effect lets you 7088request an integer or floating-point type according to its width. 7089 7090@xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals}, 7091for a list of the possible keywords for @var{mode}. 7092You may also specify a mode of @code{byte} or @code{__byte__} to 7093indicate the mode corresponding to a one-byte integer, @code{word} or 7094@code{__word__} for the mode of a one-word integer, and @code{pointer} 7095or @code{__pointer__} for the mode used to represent pointers. 7096 7097@item nonstring 7098@cindex @code{nonstring} variable attribute 7099The @code{nonstring} variable attribute specifies that an object or member 7100declaration with type array of @code{char}, @code{signed char}, or 7101@code{unsigned char}, or pointer to such a type is intended to store 7102character arrays that do not necessarily contain a terminating @code{NUL}. 7103This is useful in detecting uses of such arrays or pointers with functions 7104that expect @code{NUL}-terminated strings, and to avoid warnings when such 7105an array or pointer is used as an argument to a bounded string manipulation 7106function such as @code{strncpy}. For example, without the attribute, GCC 7107will issue a warning for the @code{strncpy} call below because it may 7108truncate the copy without appending the terminating @code{NUL} character. 7109Using the attribute makes it possible to suppress the warning. However, 7110when the array is declared with the attribute the call to @code{strlen} is 7111diagnosed because when the array doesn't contain a @code{NUL}-terminated 7112string the call is undefined. To copy, compare, of search non-string 7113character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr}, 7114and other functions that operate on arrays of bytes. In addition, 7115calling @code{strnlen} and @code{strndup} with such arrays is safe 7116provided a suitable bound is specified, and not diagnosed. 7117 7118@smallexample 7119struct Data 7120@{ 7121 char name [32] __attribute__ ((nonstring)); 7122@}; 7123 7124int f (struct Data *pd, const char *s) 7125@{ 7126 strncpy (pd->name, s, sizeof pd->name); 7127 @dots{} 7128 return strlen (pd->name); // unsafe, gets a warning 7129@} 7130@end smallexample 7131 7132@item packed 7133@cindex @code{packed} variable attribute 7134The @code{packed} attribute specifies that a structure member should have 7135the smallest possible alignment---one bit for a bit-field and one byte 7136otherwise, unless a larger value is specified with the @code{aligned} 7137attribute. The attribute does not apply to non-member objects. 7138 7139For example in the structure below, the member array @code{x} is packed 7140so that it immediately follows @code{a} with no intervening padding: 7141 7142@smallexample 7143struct foo 7144@{ 7145 char a; 7146 int x[2] __attribute__ ((packed)); 7147@}; 7148@end smallexample 7149 7150@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the 7151@code{packed} attribute on bit-fields of type @code{char}. This has 7152been fixed in GCC 4.4 but the change can lead to differences in the 7153structure layout. See the documentation of 7154@option{-Wpacked-bitfield-compat} for more information. 7155 7156@item section ("@var{section-name}") 7157@cindex @code{section} variable attribute 7158Normally, the compiler places the objects it generates in sections like 7159@code{data} and @code{bss}. Sometimes, however, you need additional sections, 7160or you need certain particular variables to appear in special sections, 7161for example to map to special hardware. The @code{section} 7162attribute specifies that a variable (or function) lives in a particular 7163section. For example, this small program uses several specific section names: 7164 7165@smallexample 7166struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; 7167struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; 7168char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; 7169int init_data __attribute__ ((section ("INITDATA"))); 7170 7171main() 7172@{ 7173 /* @r{Initialize stack pointer} */ 7174 init_sp (stack + sizeof (stack)); 7175 7176 /* @r{Initialize initialized data} */ 7177 memcpy (&init_data, &data, &edata - &data); 7178 7179 /* @r{Turn on the serial ports} */ 7180 init_duart (&a); 7181 init_duart (&b); 7182@} 7183@end smallexample 7184 7185@noindent 7186Use the @code{section} attribute with 7187@emph{global} variables and not @emph{local} variables, 7188as shown in the example. 7189 7190You may use the @code{section} attribute with initialized or 7191uninitialized global variables but the linker requires 7192each object be defined once, with the exception that uninitialized 7193variables tentatively go in the @code{common} (or @code{bss}) section 7194and can be multiply ``defined''. Using the @code{section} attribute 7195changes what section the variable goes into and may cause the 7196linker to issue an error if an uninitialized variable has multiple 7197definitions. You can force a variable to be initialized with the 7198@option{-fno-common} flag or the @code{nocommon} attribute. 7199 7200Some file formats do not support arbitrary sections so the @code{section} 7201attribute is not available on all platforms. 7202If you need to map the entire contents of a module to a particular 7203section, consider using the facilities of the linker instead. 7204 7205@item tls_model ("@var{tls_model}") 7206@cindex @code{tls_model} variable attribute 7207The @code{tls_model} attribute sets thread-local storage model 7208(@pxref{Thread-Local}) of a particular @code{__thread} variable, 7209overriding @option{-ftls-model=} command-line switch on a per-variable 7210basis. 7211The @var{tls_model} argument should be one of @code{global-dynamic}, 7212@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. 7213 7214Not all targets support this attribute. 7215 7216@item unused 7217@cindex @code{unused} variable attribute 7218This attribute, attached to a variable, means that the variable is meant 7219to be possibly unused. GCC does not produce a warning for this 7220variable. 7221 7222@item used 7223@cindex @code{used} variable attribute 7224This attribute, attached to a variable with static storage, means that 7225the variable must be emitted even if it appears that the variable is not 7226referenced. 7227 7228When applied to a static data member of a C++ class template, the 7229attribute also means that the member is instantiated if the 7230class itself is instantiated. 7231 7232@item vector_size (@var{bytes}) 7233@cindex @code{vector_size} variable attribute 7234This attribute specifies the vector size for the type of the declared 7235variable, measured in bytes. The type to which it applies is known as 7236the @dfn{base type}. The @var{bytes} argument must be a positive 7237power-of-two multiple of the base type size. For example, the declaration: 7238 7239@smallexample 7240int foo __attribute__ ((vector_size (16))); 7241@end smallexample 7242 7243@noindent 7244causes the compiler to set the mode for @code{foo}, to be 16 bytes, 7245divided into @code{int} sized units. Assuming a 32-bit @code{int}, 7246@code{foo}'s type is a vector of four units of four bytes each, and 7247the corresponding mode of @code{foo} is @code{V4SI}. 7248@xref{Vector Extensions}, for details of manipulating vector variables. 7249 7250This attribute is only applicable to integral and floating scalars, 7251although arrays, pointers, and function return values are allowed in 7252conjunction with this construct. 7253 7254Aggregates with this attribute are invalid, even if they are of the same 7255size as a corresponding scalar. For example, the declaration: 7256 7257@smallexample 7258struct S @{ int a; @}; 7259struct S __attribute__ ((vector_size (16))) foo; 7260@end smallexample 7261 7262@noindent 7263is invalid even if the size of the structure is the same as the size of 7264the @code{int}. 7265 7266@item visibility ("@var{visibility_type}") 7267@cindex @code{visibility} variable attribute 7268This attribute affects the linkage of the declaration to which it is attached. 7269The @code{visibility} attribute is described in 7270@ref{Common Function Attributes}. 7271 7272@item weak 7273@cindex @code{weak} variable attribute 7274The @code{weak} attribute is described in 7275@ref{Common Function Attributes}. 7276 7277@item noinit 7278@cindex @code{noinit} variable attribute 7279Any data with the @code{noinit} attribute will not be initialized by 7280the C runtime startup code, or the program loader. Not initializing 7281data in this way can reduce program startup times. This attribute is 7282specific to ELF targets and relies on the linker to place such data in 7283the right location 7284 7285@end table 7286 7287@node ARC Variable Attributes 7288@subsection ARC Variable Attributes 7289 7290@table @code 7291@item aux 7292@cindex @code{aux} variable attribute, ARC 7293The @code{aux} attribute is used to directly access the ARC's 7294auxiliary register space from C. The auxilirary register number is 7295given via attribute argument. 7296 7297@end table 7298 7299@node AVR Variable Attributes 7300@subsection AVR Variable Attributes 7301 7302@table @code 7303@item progmem 7304@cindex @code{progmem} variable attribute, AVR 7305The @code{progmem} attribute is used on the AVR to place read-only 7306data in the non-volatile program memory (flash). The @code{progmem} 7307attribute accomplishes this by putting respective variables into a 7308section whose name starts with @code{.progmem}. 7309 7310This attribute works similar to the @code{section} attribute 7311but adds additional checking. 7312 7313@table @asis 7314@item @bullet{}@tie{} Ordinary AVR cores with 32 general purpose registers: 7315@code{progmem} affects the location 7316of the data but not how this data is accessed. 7317In order to read data located with the @code{progmem} attribute 7318(inline) assembler must be used. 7319@smallexample 7320/* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */ 7321#include <avr/pgmspace.h> 7322 7323/* Locate var in flash memory */ 7324const int var[2] PROGMEM = @{ 1, 2 @}; 7325 7326int read_var (int i) 7327@{ 7328 /* Access var[] by accessor macro from avr/pgmspace.h */ 7329 return (int) pgm_read_word (& var[i]); 7330@} 7331@end smallexample 7332 7333AVR is a Harvard architecture processor and data and read-only data 7334normally resides in the data memory (RAM). 7335 7336See also the @ref{AVR Named Address Spaces} section for 7337an alternate way to locate and access data in flash memory. 7338 7339@item @bullet{}@tie{} AVR cores with flash memory visible in the RAM address range: 7340On such devices, there is no need for attribute @code{progmem} or 7341@ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all. 7342Just use standard C / C++. The compiler will generate @code{LD*} 7343instructions. As flash memory is visible in the RAM address range, 7344and the default linker script does @emph{not} locate @code{.rodata} in 7345RAM, no special features are needed in order not to waste RAM for 7346read-only data or to read from flash. You might even get slightly better 7347performance by 7348avoiding @code{progmem} and @code{__flash}. This applies to devices from 7349families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for 7350an overview. 7351 7352@item @bullet{}@tie{}Reduced AVR Tiny cores like ATtiny40: 7353The compiler adds @code{0x4000} 7354to the addresses of objects and declarations in @code{progmem} and locates 7355the objects in flash memory, namely in section @code{.progmem.data}. 7356The offset is needed because the flash memory is visible in the RAM 7357address space starting at address @code{0x4000}. 7358 7359Data in @code{progmem} can be accessed by means of ordinary C@tie{}code, 7360no special functions or macros are needed. 7361 7362@smallexample 7363/* var is located in flash memory */ 7364extern const int var[2] __attribute__((progmem)); 7365 7366int read_var (int i) 7367@{ 7368 return var[i]; 7369@} 7370@end smallexample 7371 7372Please notice that on these devices, there is no need for @code{progmem} 7373at all. 7374 7375@end table 7376 7377@item io 7378@itemx io (@var{addr}) 7379@cindex @code{io} variable attribute, AVR 7380Variables with the @code{io} attribute are used to address 7381memory-mapped peripherals in the io address range. 7382If an address is specified, the variable 7383is assigned that address, and the value is interpreted as an 7384address in the data address space. 7385Example: 7386 7387@smallexample 7388volatile int porta __attribute__((io (0x22))); 7389@end smallexample 7390 7391The address specified in the address in the data address range. 7392 7393Otherwise, the variable it is not assigned an address, but the 7394compiler will still use in/out instructions where applicable, 7395assuming some other module assigns an address in the io address range. 7396Example: 7397 7398@smallexample 7399extern volatile int porta __attribute__((io)); 7400@end smallexample 7401 7402@item io_low 7403@itemx io_low (@var{addr}) 7404@cindex @code{io_low} variable attribute, AVR 7405This is like the @code{io} attribute, but additionally it informs the 7406compiler that the object lies in the lower half of the I/O area, 7407allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis} 7408instructions. 7409 7410@item address 7411@itemx address (@var{addr}) 7412@cindex @code{address} variable attribute, AVR 7413Variables with the @code{address} attribute are used to address 7414memory-mapped peripherals that may lie outside the io address range. 7415 7416@smallexample 7417volatile int porta __attribute__((address (0x600))); 7418@end smallexample 7419 7420@item absdata 7421@cindex @code{absdata} variable attribute, AVR 7422Variables in static storage and with the @code{absdata} attribute can 7423be accessed by the @code{LDS} and @code{STS} instructions which take 7424absolute addresses. 7425 7426@itemize @bullet 7427@item 7428This attribute is only supported for the reduced AVR Tiny core 7429like ATtiny40. 7430 7431@item 7432You must make sure that respective data is located in the 7433address range @code{0x40}@dots{}@code{0xbf} accessible by 7434@code{LDS} and @code{STS}. One way to achieve this as an 7435appropriate linker description file. 7436 7437@item 7438If the location does not fit the address range of @code{LDS} 7439and @code{STS}, there is currently (Binutils 2.26) just an unspecific 7440warning like 7441@quotation 7442@code{module.c:(.text+0x1c): warning: internal error: out of range error} 7443@end quotation 7444 7445@end itemize 7446 7447See also the @option{-mabsdata} @ref{AVR Options,command-line option}. 7448 7449@end table 7450 7451@node Blackfin Variable Attributes 7452@subsection Blackfin Variable Attributes 7453 7454Three attributes are currently defined for the Blackfin. 7455 7456@table @code 7457@item l1_data 7458@itemx l1_data_A 7459@itemx l1_data_B 7460@cindex @code{l1_data} variable attribute, Blackfin 7461@cindex @code{l1_data_A} variable attribute, Blackfin 7462@cindex @code{l1_data_B} variable attribute, Blackfin 7463Use these attributes on the Blackfin to place the variable into L1 Data SRAM. 7464Variables with @code{l1_data} attribute are put into the specific section 7465named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into 7466the specific section named @code{.l1.data.A}. Those with @code{l1_data_B} 7467attribute are put into the specific section named @code{.l1.data.B}. 7468 7469@item l2 7470@cindex @code{l2} variable attribute, Blackfin 7471Use this attribute on the Blackfin to place the variable into L2 SRAM. 7472Variables with @code{l2} attribute are put into the specific section 7473named @code{.l2.data}. 7474@end table 7475 7476@node H8/300 Variable Attributes 7477@subsection H8/300 Variable Attributes 7478 7479These variable attributes are available for H8/300 targets: 7480 7481@table @code 7482@item eightbit_data 7483@cindex @code{eightbit_data} variable attribute, H8/300 7484@cindex eight-bit data on the H8/300, H8/300H, and H8S 7485Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 7486variable should be placed into the eight-bit data section. 7487The compiler generates more efficient code for certain operations 7488on data in the eight-bit data area. Note the eight-bit data area is limited to 7489256 bytes of data. 7490 7491You must use GAS and GLD from GNU binutils version 2.7 or later for 7492this attribute to work correctly. 7493 7494@item tiny_data 7495@cindex @code{tiny_data} variable attribute, H8/300 7496@cindex tiny data section on the H8/300H and H8S 7497Use this attribute on the H8/300H and H8S to indicate that the specified 7498variable should be placed into the tiny data section. 7499The compiler generates more efficient code for loads and stores 7500on data in the tiny data section. Note the tiny data area is limited to 7501slightly under 32KB of data. 7502 7503@end table 7504 7505@node IA-64 Variable Attributes 7506@subsection IA-64 Variable Attributes 7507 7508The IA-64 back end supports the following variable attribute: 7509 7510@table @code 7511@item model (@var{model-name}) 7512@cindex @code{model} variable attribute, IA-64 7513 7514On IA-64, use this attribute to set the addressability of an object. 7515At present, the only supported identifier for @var{model-name} is 7516@code{small}, indicating addressability via ``small'' (22-bit) 7517addresses (so that their addresses can be loaded with the @code{addl} 7518instruction). Caveat: such addressing is by definition not position 7519independent and hence this attribute must not be used for objects 7520defined by shared libraries. 7521 7522@end table 7523 7524@node M32R/D Variable Attributes 7525@subsection M32R/D Variable Attributes 7526 7527One attribute is currently defined for the M32R/D@. 7528 7529@table @code 7530@item model (@var{model-name}) 7531@cindex @code{model-name} variable attribute, M32R/D 7532@cindex variable addressability on the M32R/D 7533Use this attribute on the M32R/D to set the addressability of an object. 7534The identifier @var{model-name} is one of @code{small}, @code{medium}, 7535or @code{large}, representing each of the code models. 7536 7537Small model objects live in the lower 16MB of memory (so that their 7538addresses can be loaded with the @code{ld24} instruction). 7539 7540Medium and large model objects may live anywhere in the 32-bit address space 7541(the compiler generates @code{seth/add3} instructions to load their 7542addresses). 7543@end table 7544 7545@node MeP Variable Attributes 7546@subsection MeP Variable Attributes 7547 7548The MeP target has a number of addressing modes and busses. The 7549@code{near} space spans the standard memory space's first 16 megabytes 7550(24 bits). The @code{far} space spans the entire 32-bit memory space. 7551The @code{based} space is a 128-byte region in the memory space that 7552is addressed relative to the @code{$tp} register. The @code{tiny} 7553space is a 65536-byte region relative to the @code{$gp} register. In 7554addition to these memory regions, the MeP target has a separate 16-bit 7555control bus which is specified with @code{cb} attributes. 7556 7557@table @code 7558 7559@item based 7560@cindex @code{based} variable attribute, MeP 7561Any variable with the @code{based} attribute is assigned to the 7562@code{.based} section, and is accessed with relative to the 7563@code{$tp} register. 7564 7565@item tiny 7566@cindex @code{tiny} variable attribute, MeP 7567Likewise, the @code{tiny} attribute assigned variables to the 7568@code{.tiny} section, relative to the @code{$gp} register. 7569 7570@item near 7571@cindex @code{near} variable attribute, MeP 7572Variables with the @code{near} attribute are assumed to have addresses 7573that fit in a 24-bit addressing mode. This is the default for large 7574variables (@code{-mtiny=4} is the default) but this attribute can 7575override @code{-mtiny=} for small variables, or override @code{-ml}. 7576 7577@item far 7578@cindex @code{far} variable attribute, MeP 7579Variables with the @code{far} attribute are addressed using a full 758032-bit address. Since this covers the entire memory space, this 7581allows modules to make no assumptions about where variables might be 7582stored. 7583 7584@item io 7585@cindex @code{io} variable attribute, MeP 7586@itemx io (@var{addr}) 7587Variables with the @code{io} attribute are used to address 7588memory-mapped peripherals. If an address is specified, the variable 7589is assigned that address, else it is not assigned an address (it is 7590assumed some other module assigns an address). Example: 7591 7592@smallexample 7593int timer_count __attribute__((io(0x123))); 7594@end smallexample 7595 7596@item cb 7597@itemx cb (@var{addr}) 7598@cindex @code{cb} variable attribute, MeP 7599Variables with the @code{cb} attribute are used to access the control 7600bus, using special instructions. @code{addr} indicates the control bus 7601address. Example: 7602 7603@smallexample 7604int cpu_clock __attribute__((cb(0x123))); 7605@end smallexample 7606 7607@end table 7608 7609@node Microsoft Windows Variable Attributes 7610@subsection Microsoft Windows Variable Attributes 7611 7612You can use these attributes on Microsoft Windows targets. 7613@ref{x86 Variable Attributes} for additional Windows compatibility 7614attributes available on all x86 targets. 7615 7616@table @code 7617@item dllimport 7618@itemx dllexport 7619@cindex @code{dllimport} variable attribute 7620@cindex @code{dllexport} variable attribute 7621The @code{dllimport} and @code{dllexport} attributes are described in 7622@ref{Microsoft Windows Function Attributes}. 7623 7624@item selectany 7625@cindex @code{selectany} variable attribute 7626The @code{selectany} attribute causes an initialized global variable to 7627have link-once semantics. When multiple definitions of the variable are 7628encountered by the linker, the first is selected and the remainder are 7629discarded. Following usage by the Microsoft compiler, the linker is told 7630@emph{not} to warn about size or content differences of the multiple 7631definitions. 7632 7633Although the primary usage of this attribute is for POD types, the 7634attribute can also be applied to global C++ objects that are initialized 7635by a constructor. In this case, the static initialization and destruction 7636code for the object is emitted in each translation defining the object, 7637but the calls to the constructor and destructor are protected by a 7638link-once guard variable. 7639 7640The @code{selectany} attribute is only available on Microsoft Windows 7641targets. You can use @code{__declspec (selectany)} as a synonym for 7642@code{__attribute__ ((selectany))} for compatibility with other 7643compilers. 7644 7645@item shared 7646@cindex @code{shared} variable attribute 7647On Microsoft Windows, in addition to putting variable definitions in a named 7648section, the section can also be shared among all running copies of an 7649executable or DLL@. For example, this small program defines shared data 7650by putting it in a named section @code{shared} and marking the section 7651shareable: 7652 7653@smallexample 7654int foo __attribute__((section ("shared"), shared)) = 0; 7655 7656int 7657main() 7658@{ 7659 /* @r{Read and write foo. All running 7660 copies see the same value.} */ 7661 return 0; 7662@} 7663@end smallexample 7664 7665@noindent 7666You may only use the @code{shared} attribute along with @code{section} 7667attribute with a fully-initialized global definition because of the way 7668linkers work. See @code{section} attribute for more information. 7669 7670The @code{shared} attribute is only available on Microsoft Windows@. 7671 7672@end table 7673 7674@node MSP430 Variable Attributes 7675@subsection MSP430 Variable Attributes 7676 7677@table @code 7678@item noinit 7679@cindex @code{noinit} variable attribute, MSP430 7680Any data with the @code{noinit} attribute will not be initialised by 7681the C runtime startup code, or the program loader. Not initialising 7682data in this way can reduce program startup times. 7683 7684@item persistent 7685@cindex @code{persistent} variable attribute, MSP430 7686Any variable with the @code{persistent} attribute will not be 7687initialised by the C runtime startup code. Instead its value will be 7688set once, when the application is loaded, and then never initialised 7689again, even if the processor is reset or the program restarts. 7690Persistent data is intended to be placed into FLASH RAM, where its 7691value will be retained across resets. The linker script being used to 7692create the application should ensure that persistent data is correctly 7693placed. 7694 7695@item upper 7696@itemx either 7697@cindex @code{upper} variable attribute, MSP430 7698@cindex @code{either} variable attribute, MSP430 7699These attributes are the same as the MSP430 function attributes of the 7700same name (@pxref{MSP430 Function Attributes}). 7701 7702@item lower 7703@cindex @code{lower} variable attribute, MSP430 7704This option behaves mostly the same as the MSP430 function attribute of the 7705same name (@pxref{MSP430 Function Attributes}), but it has some additional 7706functionality. 7707 7708If @option{-mdata-region=}@{@code{upper,either,none}@} has been passed, or 7709the @code{section} attribute is applied to a variable, the compiler will 7710generate 430X instructions to handle it. This is because the compiler has 7711to assume that the variable could get placed in the upper memory region 7712(above address 0xFFFF). Marking the variable with the @code{lower} attribute 7713informs the compiler that the variable will be placed in lower memory so it 7714is safe to use 430 instructions to handle it. 7715 7716In the case of the @code{section} attribute, the section name given 7717will be used, and the @code{.lower} prefix will not be added. 7718 7719@end table 7720 7721@node Nvidia PTX Variable Attributes 7722@subsection Nvidia PTX Variable Attributes 7723 7724These variable attributes are supported by the Nvidia PTX back end: 7725 7726@table @code 7727@item shared 7728@cindex @code{shared} attribute, Nvidia PTX 7729Use this attribute to place a variable in the @code{.shared} memory space. 7730This memory space is private to each cooperative thread array; only threads 7731within one thread block refer to the same instance of the variable. 7732The runtime does not initialize variables in this memory space. 7733@end table 7734 7735@node PowerPC Variable Attributes 7736@subsection PowerPC Variable Attributes 7737 7738Three attributes currently are defined for PowerPC configurations: 7739@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 7740 7741@cindex @code{ms_struct} variable attribute, PowerPC 7742@cindex @code{gcc_struct} variable attribute, PowerPC 7743For full documentation of the struct attributes please see the 7744documentation in @ref{x86 Variable Attributes}. 7745 7746@cindex @code{altivec} variable attribute, PowerPC 7747For documentation of @code{altivec} attribute please see the 7748documentation in @ref{PowerPC Type Attributes}. 7749 7750@node RL78 Variable Attributes 7751@subsection RL78 Variable Attributes 7752 7753@cindex @code{saddr} variable attribute, RL78 7754The RL78 back end supports the @code{saddr} variable attribute. This 7755specifies placement of the corresponding variable in the SADDR area, 7756which can be accessed more efficiently than the default memory region. 7757 7758@node V850 Variable Attributes 7759@subsection V850 Variable Attributes 7760 7761These variable attributes are supported by the V850 back end: 7762 7763@table @code 7764 7765@item sda 7766@cindex @code{sda} variable attribute, V850 7767Use this attribute to explicitly place a variable in the small data area, 7768which can hold up to 64 kilobytes. 7769 7770@item tda 7771@cindex @code{tda} variable attribute, V850 7772Use this attribute to explicitly place a variable in the tiny data area, 7773which can hold up to 256 bytes in total. 7774 7775@item zda 7776@cindex @code{zda} variable attribute, V850 7777Use this attribute to explicitly place a variable in the first 32 kilobytes 7778of memory. 7779@end table 7780 7781@node x86 Variable Attributes 7782@subsection x86 Variable Attributes 7783 7784Two attributes are currently defined for x86 configurations: 7785@code{ms_struct} and @code{gcc_struct}. 7786 7787@table @code 7788@item ms_struct 7789@itemx gcc_struct 7790@cindex @code{ms_struct} variable attribute, x86 7791@cindex @code{gcc_struct} variable attribute, x86 7792 7793If @code{packed} is used on a structure, or if bit-fields are used, 7794it may be that the Microsoft ABI lays out the structure differently 7795than the way GCC normally does. Particularly when moving packed 7796data between functions compiled with GCC and the native Microsoft compiler 7797(either via function call or as data in a file), it may be necessary to access 7798either format. 7799 7800The @code{ms_struct} and @code{gcc_struct} attributes correspond 7801to the @option{-mms-bitfields} and @option{-mno-ms-bitfields} 7802command-line options, respectively; 7803see @ref{x86 Options}, for details of how structure layout is affected. 7804@xref{x86 Type Attributes}, for information about the corresponding 7805attributes on types. 7806 7807@end table 7808 7809@node Xstormy16 Variable Attributes 7810@subsection Xstormy16 Variable Attributes 7811 7812One attribute is currently defined for xstormy16 configurations: 7813@code{below100}. 7814 7815@table @code 7816@item below100 7817@cindex @code{below100} variable attribute, Xstormy16 7818 7819If a variable has the @code{below100} attribute (@code{BELOW100} is 7820allowed also), GCC places the variable in the first 0x100 bytes of 7821memory and use special opcodes to access it. Such variables are 7822placed in either the @code{.bss_below100} section or the 7823@code{.data_below100} section. 7824 7825@end table 7826 7827@node Type Attributes 7828@section Specifying Attributes of Types 7829@cindex attribute of types 7830@cindex type attributes 7831 7832The keyword @code{__attribute__} allows you to specify various special 7833properties of types. Some type attributes apply only to structure and 7834union types, and in C++, also class types, while others can apply to 7835any type defined via a @code{typedef} declaration. Unless otherwise 7836specified, the same restrictions and effects apply to attributes regardless 7837of whether a type is a trivial structure or a C++ class with user-defined 7838constructors, destructors, or a copy assignment. 7839 7840Other attributes are defined for functions (@pxref{Function Attributes}), 7841labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator 7842Attributes}), statements (@pxref{Statement Attributes}), and for variables 7843(@pxref{Variable Attributes}). 7844 7845The @code{__attribute__} keyword is followed by an attribute specification 7846enclosed in double parentheses. 7847 7848You may specify type attributes in an enum, struct or union type 7849declaration or definition by placing them immediately after the 7850@code{struct}, @code{union} or @code{enum} keyword. You can also place 7851them just past the closing curly brace of the definition, but this is less 7852preferred because logically the type should be fully defined at 7853the closing brace. 7854 7855You can also include type attributes in a @code{typedef} declaration. 7856@xref{Attribute Syntax}, for details of the exact syntax for using 7857attributes. 7858 7859@menu 7860* Common Type Attributes:: 7861* ARC Type Attributes:: 7862* ARM Type Attributes:: 7863* MeP Type Attributes:: 7864* PowerPC Type Attributes:: 7865* x86 Type Attributes:: 7866@end menu 7867 7868@node Common Type Attributes 7869@subsection Common Type Attributes 7870 7871The following type attributes are supported on most targets. 7872 7873@table @code 7874@cindex @code{aligned} type attribute 7875@item aligned 7876@itemx aligned (@var{alignment}) 7877The @code{aligned} attribute specifies a minimum alignment (in bytes) for 7878variables of the specified type. When specified, @var{alignment} must be 7879a power of 2. Specifying no @var{alignment} argument implies the maximum 7880alignment for the target, which is often, but by no means always, 8 or 16 7881bytes. For example, the declarations: 7882 7883@smallexample 7884struct __attribute__ ((aligned (8))) S @{ short f[3]; @}; 7885typedef int more_aligned_int __attribute__ ((aligned (8))); 7886@end smallexample 7887 7888@noindent 7889force the compiler to ensure (as far as it can) that each variable whose 7890type is @code{struct S} or @code{more_aligned_int} is allocated and 7891aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all 7892variables of type @code{struct S} aligned to 8-byte boundaries allows 7893the compiler to use the @code{ldd} and @code{std} (doubleword load and 7894store) instructions when copying one variable of type @code{struct S} to 7895another, thus improving run-time efficiency. 7896 7897Note that the alignment of any given @code{struct} or @code{union} type 7898is required by the ISO C standard to be at least a perfect multiple of 7899the lowest common multiple of the alignments of all of the members of 7900the @code{struct} or @code{union} in question. This means that you @emph{can} 7901effectively adjust the alignment of a @code{struct} or @code{union} 7902type by attaching an @code{aligned} attribute to any one of the members 7903of such a type, but the notation illustrated in the example above is a 7904more obvious, intuitive, and readable way to request the compiler to 7905adjust the alignment of an entire @code{struct} or @code{union} type. 7906 7907As in the preceding example, you can explicitly specify the alignment 7908(in bytes) that you wish the compiler to use for a given @code{struct} 7909or @code{union} type. Alternatively, you can leave out the alignment factor 7910and just ask the compiler to align a type to the maximum 7911useful alignment for the target machine you are compiling for. For 7912example, you could write: 7913 7914@smallexample 7915struct __attribute__ ((aligned)) S @{ short f[3]; @}; 7916@end smallexample 7917 7918Whenever you leave out the alignment factor in an @code{aligned} 7919attribute specification, the compiler automatically sets the alignment 7920for the type to the largest alignment that is ever used for any data 7921type on the target machine you are compiling for. Doing this can often 7922make copy operations more efficient, because the compiler can use 7923whatever instructions copy the biggest chunks of memory when performing 7924copies to or from the variables that have types that you have aligned 7925this way. 7926 7927In the example above, if the size of each @code{short} is 2 bytes, then 7928the size of the entire @code{struct S} type is 6 bytes. The smallest 7929power of two that is greater than or equal to that is 8, so the 7930compiler sets the alignment for the entire @code{struct S} type to 8 7931bytes. 7932 7933Note that although you can ask the compiler to select a time-efficient 7934alignment for a given type and then declare only individual stand-alone 7935objects of that type, the compiler's ability to select a time-efficient 7936alignment is primarily useful only when you plan to create arrays of 7937variables having the relevant (efficiently aligned) type. If you 7938declare or use arrays of variables of an efficiently-aligned type, then 7939it is likely that your program also does pointer arithmetic (or 7940subscripting, which amounts to the same thing) on pointers to the 7941relevant type, and the code that the compiler generates for these 7942pointer arithmetic operations is often more efficient for 7943efficiently-aligned types than for other types. 7944 7945Note that the effectiveness of @code{aligned} attributes may be limited 7946by inherent limitations in your linker. On many systems, the linker is 7947only able to arrange for variables to be aligned up to a certain maximum 7948alignment. (For some linkers, the maximum supported alignment may 7949be very very small.) If your linker is only able to align variables 7950up to a maximum of 8-byte alignment, then specifying @code{aligned (16)} 7951in an @code{__attribute__} still only provides you with 8-byte 7952alignment. See your linker documentation for further information. 7953 7954When used on a struct, or struct member, the @code{aligned} attribute can 7955only increase the alignment; in order to decrease it, the @code{packed} 7956attribute must be specified as well. When used as part of a typedef, the 7957@code{aligned} attribute can both increase and decrease alignment, and 7958specifying the @code{packed} attribute generates a warning. 7959 7960@cindex @code{warn_if_not_aligned} type attribute 7961@item warn_if_not_aligned (@var{alignment}) 7962This attribute specifies a threshold for the structure field, measured 7963in bytes. If the structure field is aligned below the threshold, a 7964warning will be issued. For example, the declaration: 7965 7966@smallexample 7967typedef unsigned long long __u64 7968 __attribute__((aligned (4), warn_if_not_aligned (8))); 7969 7970struct foo 7971@{ 7972 int i1; 7973 int i2; 7974 __u64 x; 7975@}; 7976@end smallexample 7977 7978@noindent 7979causes the compiler to issue an warning on @code{struct foo}, like 7980@samp{warning: alignment 4 of 'struct foo' is less than 8}. 7981It is used to define @code{struct foo} in such a way that 7982@code{struct foo} has the same layout and the structure field @code{x} 7983has the same alignment when @code{__u64} is aligned at either 4 or 79848 bytes. Align @code{struct foo} to 8 bytes: 7985 7986@smallexample 7987struct __attribute__ ((aligned (8))) foo 7988@{ 7989 int i1; 7990 int i2; 7991 __u64 x; 7992@}; 7993@end smallexample 7994 7995@noindent 7996silences the warning. The compiler also issues a warning, like 7997@samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8}, 7998when the structure field has the misaligned offset: 7999 8000@smallexample 8001struct __attribute__ ((aligned (8))) foo 8002@{ 8003 int i1; 8004 int i2; 8005 int i3; 8006 __u64 x; 8007@}; 8008@end smallexample 8009 8010This warning can be disabled by @option{-Wno-if-not-aligned}. 8011 8012@item alloc_size (@var{position}) 8013@itemx alloc_size (@var{position-1}, @var{position-2}) 8014@cindex @code{alloc_size} type attribute 8015The @code{alloc_size} type attribute may be applied to the definition 8016of a type of a function that returns a pointer and takes at least one 8017argument of an integer type. It indicates that the returned pointer 8018points to an object whose size is given by the function argument at 8019@var{position-1}, or by the product of the arguments at @var{position-1} 8020and @var{position-2}. Meaningful sizes are positive values less than 8021@code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses 8022this information to improve the results of @code{__builtin_object_size}. 8023 8024For instance, the following declarations 8025 8026@smallexample 8027typedef __attribute__ ((alloc_size (1, 2))) void* 8028 calloc_type (size_t, size_t); 8029typedef __attribute__ ((alloc_size (1))) void* 8030 malloc_type (size_t); 8031@end smallexample 8032 8033@noindent 8034specify that @code{calloc_type} is a type of a function that, like 8035the standard C function @code{calloc}, returns an object whose size 8036is given by the product of arguments 1 and 2, and that 8037@code{malloc_type}, like the standard C function @code{malloc}, 8038returns an object whose size is given by argument 1 to the function. 8039 8040@item copy 8041@itemx copy (@var{expression}) 8042@cindex @code{copy} type attribute 8043The @code{copy} attribute applies the set of attributes with which 8044the type of the @var{expression} has been declared to the declaration 8045of the type to which the attribute is applied. The attribute is 8046designed for libraries that define aliases that are expected to 8047specify the same set of attributes as the aliased symbols. 8048The @code{copy} attribute can be used with types, variables, or 8049functions. However, the kind of symbol to which the attribute is 8050applied (either varible or function) must match the kind of symbol 8051to which the argument refers. 8052The @code{copy} attribute copies only syntactic and semantic attributes 8053but not attributes that affect a symbol's linkage or visibility such as 8054@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} 8055attribute is also not copied. @xref{Common Function Attributes}. 8056@xref{Common Variable Attributes}. 8057 8058For example, suppose @code{struct A} below is defined in some third 8059party library header to have the alignment requirement @code{N} and 8060to force a warning whenever a variable of the type is not so aligned 8061due to attribute @code{packed}. Specifying the @code{copy} attribute 8062on the definition on the unrelated @code{struct B} has the effect of 8063copying all relevant attributes from the type referenced by the pointer 8064expression to @code{struct B}. 8065 8066@smallexample 8067struct __attribute__ ((aligned (N), warn_if_not_aligned (N))) 8068A @{ /* @r{@dots{}} */ @}; 8069struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @}; 8070@end smallexample 8071 8072@item deprecated 8073@itemx deprecated (@var{msg}) 8074@cindex @code{deprecated} type attribute 8075The @code{deprecated} attribute results in a warning if the type 8076is used anywhere in the source file. This is useful when identifying 8077types that are expected to be removed in a future version of a program. 8078If possible, the warning also includes the location of the declaration 8079of the deprecated type, to enable users to easily find further 8080information about why the type is deprecated, or what they should do 8081instead. Note that the warnings only occur for uses and then only 8082if the type is being applied to an identifier that itself is not being 8083declared as deprecated. 8084 8085@smallexample 8086typedef int T1 __attribute__ ((deprecated)); 8087T1 x; 8088typedef T1 T2; 8089T2 y; 8090typedef T1 T3 __attribute__ ((deprecated)); 8091T3 z __attribute__ ((deprecated)); 8092@end smallexample 8093 8094@noindent 8095results in a warning on line 2 and 3 but not lines 4, 5, or 6. No 8096warning is issued for line 4 because T2 is not explicitly 8097deprecated. Line 5 has no warning because T3 is explicitly 8098deprecated. Similarly for line 6. The optional @var{msg} 8099argument, which must be a string, is printed in the warning if 8100present. Control characters in the string will be replaced with 8101escape sequences, and if the @option{-fmessage-length} option is set 8102to 0 (its default value) then any newline characters will be ignored. 8103 8104The @code{deprecated} attribute can also be used for functions and 8105variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) 8106 8107The message attached to the attribute is affected by the setting of 8108the @option{-fmessage-length} option. 8109 8110@item designated_init 8111@cindex @code{designated_init} type attribute 8112This attribute may only be applied to structure types. It indicates 8113that any initialization of an object of this type must use designated 8114initializers rather than positional initializers. The intent of this 8115attribute is to allow the programmer to indicate that a structure's 8116layout may change, and that therefore relying on positional 8117initialization will result in future breakage. 8118 8119GCC emits warnings based on this attribute by default; use 8120@option{-Wno-designated-init} to suppress them. 8121 8122@item may_alias 8123@cindex @code{may_alias} type attribute 8124Accesses through pointers to types with this attribute are not subject 8125to type-based alias analysis, but are instead assumed to be able to alias 8126any other type of objects. 8127In the context of section 6.5 paragraph 7 of the C99 standard, 8128an lvalue expression 8129dereferencing such a pointer is treated like having a character type. 8130See @option{-fstrict-aliasing} for more information on aliasing issues. 8131This extension exists to support some vector APIs, in which pointers to 8132one vector type are permitted to alias pointers to a different vector type. 8133 8134Note that an object of a type with this attribute does not have any 8135special semantics. 8136 8137Example of use: 8138 8139@smallexample 8140typedef short __attribute__ ((__may_alias__)) short_a; 8141 8142int 8143main (void) 8144@{ 8145 int a = 0x12345678; 8146 short_a *b = (short_a *) &a; 8147 8148 b[1] = 0; 8149 8150 if (a == 0x12345678) 8151 abort(); 8152 8153 exit(0); 8154@} 8155@end smallexample 8156 8157@noindent 8158If you replaced @code{short_a} with @code{short} in the variable 8159declaration, the above program would abort when compiled with 8160@option{-fstrict-aliasing}, which is on by default at @option{-O2} or 8161above. 8162 8163@item mode (@var{mode}) 8164@cindex @code{mode} type attribute 8165This attribute specifies the data type for the declaration---whichever 8166type corresponds to the mode @var{mode}. This in effect lets you 8167request an integer or floating-point type according to its width. 8168 8169@xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals}, 8170for a list of the possible keywords for @var{mode}. 8171You may also specify a mode of @code{byte} or @code{__byte__} to 8172indicate the mode corresponding to a one-byte integer, @code{word} or 8173@code{__word__} for the mode of a one-word integer, and @code{pointer} 8174or @code{__pointer__} for the mode used to represent pointers. 8175 8176@item packed 8177@cindex @code{packed} type attribute 8178This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class} 8179type definition, specifies that each of its members (other than zero-width 8180bit-fields) is placed to minimize the memory required. This is equivalent 8181to specifying the @code{packed} attribute on each of the members. 8182 8183@opindex fshort-enums 8184When attached to an @code{enum} definition, the @code{packed} attribute 8185indicates that the smallest integral type should be used. 8186Specifying the @option{-fshort-enums} flag on the command line 8187is equivalent to specifying the @code{packed} 8188attribute on all @code{enum} definitions. 8189 8190In the following example @code{struct my_packed_struct}'s members are 8191packed closely together, but the internal layout of its @code{s} member 8192is not packed---to do that, @code{struct my_unpacked_struct} needs to 8193be packed too. 8194 8195@smallexample 8196struct my_unpacked_struct 8197 @{ 8198 char c; 8199 int i; 8200 @}; 8201 8202struct __attribute__ ((__packed__)) my_packed_struct 8203 @{ 8204 char c; 8205 int i; 8206 struct my_unpacked_struct s; 8207 @}; 8208@end smallexample 8209 8210You may only specify the @code{packed} attribute on the definition 8211of an @code{enum}, @code{struct}, @code{union}, or @code{class}, 8212not on a @code{typedef} that does not also define the enumerated type, 8213structure, union, or class. 8214 8215@item scalar_storage_order ("@var{endianness}") 8216@cindex @code{scalar_storage_order} type attribute 8217When attached to a @code{union} or a @code{struct}, this attribute sets 8218the storage order, aka endianness, of the scalar fields of the type, as 8219well as the array fields whose component is scalar. The supported 8220endiannesses are @code{big-endian} and @code{little-endian}. The attribute 8221has no effects on fields which are themselves a @code{union}, a @code{struct} 8222or an array whose component is a @code{union} or a @code{struct}, and it is 8223possible for these fields to have a different scalar storage order than the 8224enclosing type. 8225 8226This attribute is supported only for targets that use a uniform default 8227scalar storage order (fortunately, most of them), i.e.@: targets that store 8228the scalars either all in big-endian or all in little-endian. 8229 8230Additional restrictions are enforced for types with the reverse scalar 8231storage order with regard to the scalar storage order of the target: 8232 8233@itemize 8234@item Taking the address of a scalar field of a @code{union} or a 8235@code{struct} with reverse scalar storage order is not permitted and yields 8236an error. 8237@item Taking the address of an array field, whose component is scalar, of 8238a @code{union} or a @code{struct} with reverse scalar storage order is 8239permitted but yields a warning, unless @option{-Wno-scalar-storage-order} 8240is specified. 8241@item Taking the address of a @code{union} or a @code{struct} with reverse 8242scalar storage order is permitted. 8243@end itemize 8244 8245These restrictions exist because the storage order attribute is lost when 8246the address of a scalar or the address of an array with scalar component is 8247taken, so storing indirectly through this address generally does not work. 8248The second case is nevertheless allowed to be able to perform a block copy 8249from or to the array. 8250 8251Moreover, the use of type punning or aliasing to toggle the storage order 8252is not supported; that is to say, a given scalar object cannot be accessed 8253through distinct types that assign a different storage order to it. 8254 8255@item transparent_union 8256@cindex @code{transparent_union} type attribute 8257 8258This attribute, attached to a @code{union} type definition, indicates 8259that any function parameter having that union type causes calls to that 8260function to be treated in a special way. 8261 8262First, the argument corresponding to a transparent union type can be of 8263any type in the union; no cast is required. Also, if the union contains 8264a pointer type, the corresponding argument can be a null pointer 8265constant or a void pointer expression; and if the union contains a void 8266pointer type, the corresponding argument can be any pointer expression. 8267If the union member type is a pointer, qualifiers like @code{const} on 8268the referenced type must be respected, just as with normal pointer 8269conversions. 8270 8271Second, the argument is passed to the function using the calling 8272conventions of the first member of the transparent union, not the calling 8273conventions of the union itself. All members of the union must have the 8274same machine representation; this is necessary for this argument passing 8275to work properly. 8276 8277Transparent unions are designed for library functions that have multiple 8278interfaces for compatibility reasons. For example, suppose the 8279@code{wait} function must accept either a value of type @code{int *} to 8280comply with POSIX, or a value of type @code{union wait *} to comply with 8281the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, 8282@code{wait} would accept both kinds of arguments, but it would also 8283accept any other pointer type and this would make argument type checking 8284less useful. Instead, @code{<sys/wait.h>} might define the interface 8285as follows: 8286 8287@smallexample 8288typedef union __attribute__ ((__transparent_union__)) 8289 @{ 8290 int *__ip; 8291 union wait *__up; 8292 @} wait_status_ptr_t; 8293 8294pid_t wait (wait_status_ptr_t); 8295@end smallexample 8296 8297@noindent 8298This interface allows either @code{int *} or @code{union wait *} 8299arguments to be passed, using the @code{int *} calling convention. 8300The program can call @code{wait} with arguments of either type: 8301 8302@smallexample 8303int w1 () @{ int w; return wait (&w); @} 8304int w2 () @{ union wait w; return wait (&w); @} 8305@end smallexample 8306 8307@noindent 8308With this interface, @code{wait}'s implementation might look like this: 8309 8310@smallexample 8311pid_t wait (wait_status_ptr_t p) 8312@{ 8313 return waitpid (-1, p.__ip, 0); 8314@} 8315@end smallexample 8316 8317@item unused 8318@cindex @code{unused} type attribute 8319When attached to a type (including a @code{union} or a @code{struct}), 8320this attribute means that variables of that type are meant to appear 8321possibly unused. GCC does not produce a warning for any variables of 8322that type, even if the variable appears to do nothing. This is often 8323the case with lock or thread classes, which are usually defined and then 8324not referenced, but contain constructors and destructors that have 8325nontrivial bookkeeping functions. 8326 8327@item vector_size (@var{bytes}) 8328@cindex @code{vector_size} type attribute 8329This attribute specifies the vector size for the type, measured in bytes. 8330The type to which it applies is known as the @dfn{base type}. The @var{bytes} 8331argument must be a positive power-of-two multiple of the base type size. For 8332example, the following declarations: 8333 8334@smallexample 8335typedef __attribute__ ((vector_size (32))) int int_vec32_t ; 8336typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t; 8337typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3]; 8338@end smallexample 8339 8340@noindent 8341define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int} 8342sized units. With @code{int} having a size of 4 bytes, the type defines 8343a vector of eight units, four bytes each. The mode of variables of type 8344@code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined 8345to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be 8346an array of three such vectors. @xref{Vector Extensions}, for details of 8347manipulating objects of vector types. 8348 8349This attribute is only applicable to integral and floating scalar types. 8350In function declarations the attribute applies to the function return 8351type. 8352 8353For example, the following: 8354@smallexample 8355__attribute__ ((vector_size (16))) float get_flt_vec16 (void); 8356@end smallexample 8357declares @code{get_flt_vec16} to be a function returning a 16-byte vector 8358with the base type @code{float}. 8359 8360@item visibility 8361@cindex @code{visibility} type attribute 8362In C++, attribute visibility (@pxref{Function Attributes}) can also be 8363applied to class, struct, union and enum types. Unlike other type 8364attributes, the attribute must appear between the initial keyword and 8365the name of the type; it cannot appear after the body of the type. 8366 8367Note that the type visibility is applied to vague linkage entities 8368associated with the class (vtable, typeinfo node, etc.). In 8369particular, if a class is thrown as an exception in one shared object 8370and caught in another, the class must have default visibility. 8371Otherwise the two shared objects are unable to use the same 8372typeinfo node and exception handling will break. 8373 8374@end table 8375 8376To specify multiple attributes, separate them by commas within the 8377double parentheses: for example, @samp{__attribute__ ((aligned (16), 8378packed))}. 8379 8380@node ARC Type Attributes 8381@subsection ARC Type Attributes 8382 8383@cindex @code{uncached} type attribute, ARC 8384Declaring objects with @code{uncached} allows you to exclude 8385data-cache participation in load and store operations on those objects 8386without involving the additional semantic implications of 8387@code{volatile}. The @code{.di} instruction suffix is used for all 8388loads and stores of data declared @code{uncached}. 8389 8390@node ARM Type Attributes 8391@subsection ARM Type Attributes 8392 8393@cindex @code{notshared} type attribute, ARM 8394On those ARM targets that support @code{dllimport} (such as Symbian 8395OS), you can use the @code{notshared} attribute to indicate that the 8396virtual table and other similar data for a class should not be 8397exported from a DLL@. For example: 8398 8399@smallexample 8400class __declspec(notshared) C @{ 8401public: 8402 __declspec(dllimport) C(); 8403 virtual void f(); 8404@} 8405 8406__declspec(dllexport) 8407C::C() @{@} 8408@end smallexample 8409 8410@noindent 8411In this code, @code{C::C} is exported from the current DLL, but the 8412virtual table for @code{C} is not exported. (You can use 8413@code{__attribute__} instead of @code{__declspec} if you prefer, but 8414most Symbian OS code uses @code{__declspec}.) 8415 8416@node MeP Type Attributes 8417@subsection MeP Type Attributes 8418 8419@cindex @code{based} type attribute, MeP 8420@cindex @code{tiny} type attribute, MeP 8421@cindex @code{near} type attribute, MeP 8422@cindex @code{far} type attribute, MeP 8423Many of the MeP variable attributes may be applied to types as well. 8424Specifically, the @code{based}, @code{tiny}, @code{near}, and 8425@code{far} attributes may be applied to either. The @code{io} and 8426@code{cb} attributes may not be applied to types. 8427 8428@node PowerPC Type Attributes 8429@subsection PowerPC Type Attributes 8430 8431Three attributes currently are defined for PowerPC configurations: 8432@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 8433 8434@cindex @code{ms_struct} type attribute, PowerPC 8435@cindex @code{gcc_struct} type attribute, PowerPC 8436For full documentation of the @code{ms_struct} and @code{gcc_struct} 8437attributes please see the documentation in @ref{x86 Type Attributes}. 8438 8439@cindex @code{altivec} type attribute, PowerPC 8440The @code{altivec} attribute allows one to declare AltiVec vector data 8441types supported by the AltiVec Programming Interface Manual. The 8442attribute requires an argument to specify one of three vector types: 8443@code{vector__}, @code{pixel__} (always followed by unsigned short), 8444and @code{bool__} (always followed by unsigned). 8445 8446@smallexample 8447__attribute__((altivec(vector__))) 8448__attribute__((altivec(pixel__))) unsigned short 8449__attribute__((altivec(bool__))) unsigned 8450@end smallexample 8451 8452These attributes mainly are intended to support the @code{__vector}, 8453@code{__pixel}, and @code{__bool} AltiVec keywords. 8454 8455@node x86 Type Attributes 8456@subsection x86 Type Attributes 8457 8458Two attributes are currently defined for x86 configurations: 8459@code{ms_struct} and @code{gcc_struct}. 8460 8461@table @code 8462 8463@item ms_struct 8464@itemx gcc_struct 8465@cindex @code{ms_struct} type attribute, x86 8466@cindex @code{gcc_struct} type attribute, x86 8467 8468If @code{packed} is used on a structure, or if bit-fields are used 8469it may be that the Microsoft ABI packs them differently 8470than GCC normally packs them. Particularly when moving packed 8471data between functions compiled with GCC and the native Microsoft compiler 8472(either via function call or as data in a file), it may be necessary to access 8473either format. 8474 8475The @code{ms_struct} and @code{gcc_struct} attributes correspond 8476to the @option{-mms-bitfields} and @option{-mno-ms-bitfields} 8477command-line options, respectively; 8478see @ref{x86 Options}, for details of how structure layout is affected. 8479@xref{x86 Variable Attributes}, for information about the corresponding 8480attributes on variables. 8481 8482@end table 8483 8484@node Label Attributes 8485@section Label Attributes 8486@cindex Label Attributes 8487 8488GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for 8489details of the exact syntax for using attributes. Other attributes are 8490available for functions (@pxref{Function Attributes}), variables 8491(@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}), 8492statements (@pxref{Statement Attributes}), and for types 8493(@pxref{Type Attributes}). 8494 8495This example uses the @code{cold} label attribute to indicate the 8496@code{ErrorHandling} branch is unlikely to be taken and that the 8497@code{ErrorHandling} label is unused: 8498 8499@smallexample 8500 8501 asm goto ("some asm" : : : : NoError); 8502 8503/* This branch (the fall-through from the asm) is less commonly used */ 8504ErrorHandling: 8505 __attribute__((cold, unused)); /* Semi-colon is required here */ 8506 printf("error\n"); 8507 return 0; 8508 8509NoError: 8510 printf("no error\n"); 8511 return 1; 8512@end smallexample 8513 8514@table @code 8515@item unused 8516@cindex @code{unused} label attribute 8517This feature is intended for program-generated code that may contain 8518unused labels, but which is compiled with @option{-Wall}. It is 8519not normally appropriate to use in it human-written code, though it 8520could be useful in cases where the code that jumps to the label is 8521contained within an @code{#ifdef} conditional. 8522 8523@item hot 8524@cindex @code{hot} label attribute 8525The @code{hot} attribute on a label is used to inform the compiler that 8526the path following the label is more likely than paths that are not so 8527annotated. This attribute is used in cases where @code{__builtin_expect} 8528cannot be used, for instance with computed goto or @code{asm goto}. 8529 8530@item cold 8531@cindex @code{cold} label attribute 8532The @code{cold} attribute on labels is used to inform the compiler that 8533the path following the label is unlikely to be executed. This attribute 8534is used in cases where @code{__builtin_expect} cannot be used, for instance 8535with computed goto or @code{asm goto}. 8536 8537@end table 8538 8539@node Enumerator Attributes 8540@section Enumerator Attributes 8541@cindex Enumerator Attributes 8542 8543GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for 8544details of the exact syntax for using attributes. Other attributes are 8545available for functions (@pxref{Function Attributes}), variables 8546(@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements 8547(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}). 8548 8549This example uses the @code{deprecated} enumerator attribute to indicate the 8550@code{oldval} enumerator is deprecated: 8551 8552@smallexample 8553enum E @{ 8554 oldval __attribute__((deprecated)), 8555 newval 8556@}; 8557 8558int 8559fn (void) 8560@{ 8561 return oldval; 8562@} 8563@end smallexample 8564 8565@table @code 8566@item deprecated 8567@cindex @code{deprecated} enumerator attribute 8568The @code{deprecated} attribute results in a warning if the enumerator 8569is used anywhere in the source file. This is useful when identifying 8570enumerators that are expected to be removed in a future version of a 8571program. The warning also includes the location of the declaration 8572of the deprecated enumerator, to enable users to easily find further 8573information about why the enumerator is deprecated, or what they should 8574do instead. Note that the warnings only occurs for uses. 8575 8576@end table 8577 8578@node Statement Attributes 8579@section Statement Attributes 8580@cindex Statement Attributes 8581 8582GCC allows attributes to be set on null statements. @xref{Attribute Syntax}, 8583for details of the exact syntax for using attributes. Other attributes are 8584available for functions (@pxref{Function Attributes}), variables 8585(@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators 8586(@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}). 8587 8588This example uses the @code{fallthrough} statement attribute to indicate that 8589the @option{-Wimplicit-fallthrough} warning should not be emitted: 8590 8591@smallexample 8592switch (cond) 8593 @{ 8594 case 1: 8595 bar (1); 8596 __attribute__((fallthrough)); 8597 case 2: 8598 @dots{} 8599 @} 8600@end smallexample 8601 8602@table @code 8603@item fallthrough 8604@cindex @code{fallthrough} statement attribute 8605The @code{fallthrough} attribute with a null statement serves as a 8606fallthrough statement. It hints to the compiler that a statement 8607that falls through to another case label, or user-defined label 8608in a switch statement is intentional and thus the 8609@option{-Wimplicit-fallthrough} warning must not trigger. The 8610fallthrough attribute may appear at most once in each attribute 8611list, and may not be mixed with other attributes. It can only 8612be used in a switch statement (the compiler will issue an error 8613otherwise), after a preceding statement and before a logically 8614succeeding case label, or user-defined label. 8615 8616@end table 8617 8618@node Attribute Syntax 8619@section Attribute Syntax 8620@cindex attribute syntax 8621 8622This section describes the syntax with which @code{__attribute__} may be 8623used, and the constructs to which attribute specifiers bind, for the C 8624language. Some details may vary for C++ and Objective-C@. Because of 8625infelicities in the grammar for attributes, some forms described here 8626may not be successfully parsed in all cases. 8627 8628There are some problems with the semantics of attributes in C++. For 8629example, there are no manglings for attributes, although they may affect 8630code generation, so problems may arise when attributed types are used in 8631conjunction with templates or overloading. Similarly, @code{typeid} 8632does not distinguish between types with different attributes. Support 8633for attributes in C++ may be restricted in future to attributes on 8634declarations only, but not on nested declarators. 8635 8636@xref{Function Attributes}, for details of the semantics of attributes 8637applying to functions. @xref{Variable Attributes}, for details of the 8638semantics of attributes applying to variables. @xref{Type Attributes}, 8639for details of the semantics of attributes applying to structure, union 8640and enumerated types. 8641@xref{Label Attributes}, for details of the semantics of attributes 8642applying to labels. 8643@xref{Enumerator Attributes}, for details of the semantics of attributes 8644applying to enumerators. 8645@xref{Statement Attributes}, for details of the semantics of attributes 8646applying to statements. 8647 8648An @dfn{attribute specifier} is of the form 8649@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} 8650is a possibly empty comma-separated sequence of @dfn{attributes}, where 8651each attribute is one of the following: 8652 8653@itemize @bullet 8654@item 8655Empty. Empty attributes are ignored. 8656 8657@item 8658An attribute name 8659(which may be an identifier such as @code{unused}, or a reserved 8660word such as @code{const}). 8661 8662@item 8663An attribute name followed by a parenthesized list of 8664parameters for the attribute. 8665These parameters take one of the following forms: 8666 8667@itemize @bullet 8668@item 8669An identifier. For example, @code{mode} attributes use this form. 8670 8671@item 8672An identifier followed by a comma and a non-empty comma-separated list 8673of expressions. For example, @code{format} attributes use this form. 8674 8675@item 8676A possibly empty comma-separated list of expressions. For example, 8677@code{format_arg} attributes use this form with the list being a single 8678integer constant expression, and @code{alias} attributes use this form 8679with the list being a single string constant. 8680@end itemize 8681@end itemize 8682 8683An @dfn{attribute specifier list} is a sequence of one or more attribute 8684specifiers, not separated by any other tokens. 8685 8686You may optionally specify attribute names with @samp{__} 8687preceding and following the name. 8688This allows you to use them in header files without 8689being concerned about a possible macro of the same name. For example, 8690you may use the attribute name @code{__noreturn__} instead of @code{noreturn}. 8691 8692 8693@subsubheading Label Attributes 8694 8695In GNU C, an attribute specifier list may appear after the colon following a 8696label, other than a @code{case} or @code{default} label. GNU C++ only permits 8697attributes on labels if the attribute specifier is immediately 8698followed by a semicolon (i.e., the label applies to an empty 8699statement). If the semicolon is missing, C++ label attributes are 8700ambiguous, as it is permissible for a declaration, which could begin 8701with an attribute list, to be labelled in C++. Declarations cannot be 8702labelled in C90 or C99, so the ambiguity does not arise there. 8703 8704@subsubheading Enumerator Attributes 8705 8706In GNU C, an attribute specifier list may appear as part of an enumerator. 8707The attribute goes after the enumeration constant, before @code{=}, if 8708present. The optional attribute in the enumerator appertains to the 8709enumeration constant. It is not possible to place the attribute after 8710the constant expression, if present. 8711 8712@subsubheading Statement Attributes 8713In GNU C, an attribute specifier list may appear as part of a null 8714statement. The attribute goes before the semicolon. 8715 8716@subsubheading Type Attributes 8717 8718An attribute specifier list may appear as part of a @code{struct}, 8719@code{union} or @code{enum} specifier. It may go either immediately 8720after the @code{struct}, @code{union} or @code{enum} keyword, or after 8721the closing brace. The former syntax is preferred. 8722Where attribute specifiers follow the closing brace, they are considered 8723to relate to the structure, union or enumerated type defined, not to any 8724enclosing declaration the type specifier appears in, and the type 8725defined is not complete until after the attribute specifiers. 8726@c Otherwise, there would be the following problems: a shift/reduce 8727@c conflict between attributes binding the struct/union/enum and 8728@c binding to the list of specifiers/qualifiers; and "aligned" 8729@c attributes could use sizeof for the structure, but the size could be 8730@c changed later by "packed" attributes. 8731 8732 8733@subsubheading All other attributes 8734 8735Otherwise, an attribute specifier appears as part of a declaration, 8736counting declarations of unnamed parameters and type names, and relates 8737to that declaration (which may be nested in another declaration, for 8738example in the case of a parameter declaration), or to a particular declarator 8739within a declaration. Where an 8740attribute specifier is applied to a parameter declared as a function or 8741an array, it should apply to the function or array rather than the 8742pointer to which the parameter is implicitly converted, but this is not 8743yet correctly implemented. 8744 8745Any list of specifiers and qualifiers at the start of a declaration may 8746contain attribute specifiers, whether or not such a list may in that 8747context contain storage class specifiers. (Some attributes, however, 8748are essentially in the nature of storage class specifiers, and only make 8749sense where storage class specifiers may be used; for example, 8750@code{section}.) There is one necessary limitation to this syntax: the 8751first old-style parameter declaration in a function definition cannot 8752begin with an attribute specifier, because such an attribute applies to 8753the function instead by syntax described below (which, however, is not 8754yet implemented in this case). In some other cases, attribute 8755specifiers are permitted by this grammar but not yet supported by the 8756compiler. All attribute specifiers in this place relate to the 8757declaration as a whole. In the obsolescent usage where a type of 8758@code{int} is implied by the absence of type specifiers, such a list of 8759specifiers and qualifiers may be an attribute specifier list with no 8760other specifiers or qualifiers. 8761 8762At present, the first parameter in a function prototype must have some 8763type specifier that is not an attribute specifier; this resolves an 8764ambiguity in the interpretation of @code{void f(int 8765(__attribute__((foo)) x))}, but is subject to change. At present, if 8766the parentheses of a function declarator contain only attributes then 8767those attributes are ignored, rather than yielding an error or warning 8768or implying a single parameter of type int, but this is subject to 8769change. 8770 8771An attribute specifier list may appear immediately before a declarator 8772(other than the first) in a comma-separated list of declarators in a 8773declaration of more than one identifier using a single list of 8774specifiers and qualifiers. Such attribute specifiers apply 8775only to the identifier before whose declarator they appear. For 8776example, in 8777 8778@smallexample 8779__attribute__((noreturn)) void d0 (void), 8780 __attribute__((format(printf, 1, 2))) d1 (const char *, ...), 8781 d2 (void); 8782@end smallexample 8783 8784@noindent 8785the @code{noreturn} attribute applies to all the functions 8786declared; the @code{format} attribute only applies to @code{d1}. 8787 8788An attribute specifier list may appear immediately before the comma, 8789@code{=} or semicolon terminating the declaration of an identifier other 8790than a function definition. Such attribute specifiers apply 8791to the declared object or function. Where an 8792assembler name for an object or function is specified (@pxref{Asm 8793Labels}), the attribute must follow the @code{asm} 8794specification. 8795 8796An attribute specifier list may, in future, be permitted to appear after 8797the declarator in a function definition (before any old-style parameter 8798declarations or the function body). 8799 8800Attribute specifiers may be mixed with type qualifiers appearing inside 8801the @code{[]} of a parameter array declarator, in the C99 construct by 8802which such qualifiers are applied to the pointer to which the array is 8803implicitly converted. Such attribute specifiers apply to the pointer, 8804not to the array, but at present this is not implemented and they are 8805ignored. 8806 8807An attribute specifier list may appear at the start of a nested 8808declarator. At present, there are some limitations in this usage: the 8809attributes correctly apply to the declarator, but for most individual 8810attributes the semantics this implies are not implemented. 8811When attribute specifiers follow the @code{*} of a pointer 8812declarator, they may be mixed with any type qualifiers present. 8813The following describes the formal semantics of this syntax. It makes the 8814most sense if you are familiar with the formal specification of 8815declarators in the ISO C standard. 8816 8817Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T 8818D1}, where @code{T} contains declaration specifiers that specify a type 8819@var{Type} (such as @code{int}) and @code{D1} is a declarator that 8820contains an identifier @var{ident}. The type specified for @var{ident} 8821for derived declarators whose type does not include an attribute 8822specifier is as in the ISO C standard. 8823 8824If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, 8825and the declaration @code{T D} specifies the type 8826``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 8827@code{T D1} specifies the type ``@var{derived-declarator-type-list} 8828@var{attribute-specifier-list} @var{Type}'' for @var{ident}. 8829 8830If @code{D1} has the form @code{* 8831@var{type-qualifier-and-attribute-specifier-list} D}, and the 8832declaration @code{T D} specifies the type 8833``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 8834@code{T D1} specifies the type ``@var{derived-declarator-type-list} 8835@var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for 8836@var{ident}. 8837 8838For example, 8839 8840@smallexample 8841void (__attribute__((noreturn)) ****f) (void); 8842@end smallexample 8843 8844@noindent 8845specifies the type ``pointer to pointer to pointer to pointer to 8846non-returning function returning @code{void}''. As another example, 8847 8848@smallexample 8849char *__attribute__((aligned(8))) *f; 8850@end smallexample 8851 8852@noindent 8853specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. 8854Note again that this does not work with most attributes; for example, 8855the usage of @samp{aligned} and @samp{noreturn} attributes given above 8856is not yet supported. 8857 8858For compatibility with existing code written for compiler versions that 8859did not implement attributes on nested declarators, some laxity is 8860allowed in the placing of attributes. If an attribute that only applies 8861to types is applied to a declaration, it is treated as applying to 8862the type of that declaration. If an attribute that only applies to 8863declarations is applied to the type of a declaration, it is treated 8864as applying to that declaration; and, for compatibility with code 8865placing the attributes immediately before the identifier declared, such 8866an attribute applied to a function return type is treated as 8867applying to the function type, and such an attribute applied to an array 8868element type is treated as applying to the array type. If an 8869attribute that only applies to function types is applied to a 8870pointer-to-function type, it is treated as applying to the pointer 8871target type; if such an attribute is applied to a function return type 8872that is not a pointer-to-function type, it is treated as applying 8873to the function type. 8874 8875@node Function Prototypes 8876@section Prototypes and Old-Style Function Definitions 8877@cindex function prototype declarations 8878@cindex old-style function definitions 8879@cindex promotion of formal parameters 8880 8881GNU C extends ISO C to allow a function prototype to override a later 8882old-style non-prototype definition. Consider the following example: 8883 8884@smallexample 8885/* @r{Use prototypes unless the compiler is old-fashioned.} */ 8886#ifdef __STDC__ 8887#define P(x) x 8888#else 8889#define P(x) () 8890#endif 8891 8892/* @r{Prototype function declaration.} */ 8893int isroot P((uid_t)); 8894 8895/* @r{Old-style function definition.} */ 8896int 8897isroot (x) /* @r{??? lossage here ???} */ 8898 uid_t x; 8899@{ 8900 return x == 0; 8901@} 8902@end smallexample 8903 8904Suppose the type @code{uid_t} happens to be @code{short}. ISO C does 8905not allow this example, because subword arguments in old-style 8906non-prototype definitions are promoted. Therefore in this example the 8907function definition's argument is really an @code{int}, which does not 8908match the prototype argument type of @code{short}. 8909 8910This restriction of ISO C makes it hard to write code that is portable 8911to traditional C compilers, because the programmer does not know 8912whether the @code{uid_t} type is @code{short}, @code{int}, or 8913@code{long}. Therefore, in cases like these GNU C allows a prototype 8914to override a later old-style definition. More precisely, in GNU C, a 8915function prototype argument type overrides the argument type specified 8916by a later old-style definition if the former type is the same as the 8917latter type before promotion. Thus in GNU C the above example is 8918equivalent to the following: 8919 8920@smallexample 8921int isroot (uid_t); 8922 8923int 8924isroot (uid_t x) 8925@{ 8926 return x == 0; 8927@} 8928@end smallexample 8929 8930@noindent 8931GNU C++ does not support old-style function definitions, so this 8932extension is irrelevant. 8933 8934@node C++ Comments 8935@section C++ Style Comments 8936@cindex @code{//} 8937@cindex C++ comments 8938@cindex comments, C++ style 8939 8940In GNU C, you may use C++ style comments, which start with @samp{//} and 8941continue until the end of the line. Many other C implementations allow 8942such comments, and they are included in the 1999 C standard. However, 8943C++ style comments are not recognized if you specify an @option{-std} 8944option specifying a version of ISO C before C99, or @option{-ansi} 8945(equivalent to @option{-std=c90}). 8946 8947@node Dollar Signs 8948@section Dollar Signs in Identifier Names 8949@cindex $ 8950@cindex dollar signs in identifier names 8951@cindex identifier names, dollar signs in 8952 8953In GNU C, you may normally use dollar signs in identifier names. 8954This is because many traditional C implementations allow such identifiers. 8955However, dollar signs in identifiers are not supported on a few target 8956machines, typically because the target assembler does not allow them. 8957 8958@node Character Escapes 8959@section The Character @key{ESC} in Constants 8960 8961You can use the sequence @samp{\e} in a string or character constant to 8962stand for the ASCII character @key{ESC}. 8963 8964@node Alignment 8965@section Determining the Alignment of Functions, Types or Variables 8966@cindex alignment 8967@cindex type alignment 8968@cindex variable alignment 8969 8970The keyword @code{__alignof__} determines the alignment requirement of 8971a function, object, or a type, or the minimum alignment usually required 8972by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}. 8973 8974For example, if the target machine requires a @code{double} value to be 8975aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. 8976This is true on many RISC machines. On more traditional machine 8977designs, @code{__alignof__ (double)} is 4 or even 2. 8978 8979Some machines never actually require alignment; they allow references to any 8980data type even at an odd address. For these machines, @code{__alignof__} 8981reports the smallest alignment that GCC gives the data type, usually as 8982mandated by the target ABI. 8983 8984If the operand of @code{__alignof__} is an lvalue rather than a type, 8985its value is the required alignment for its type, taking into account 8986any minimum alignment specified by attribute @code{aligned} 8987(@pxref{Common Variable Attributes}). For example, after this 8988declaration: 8989 8990@smallexample 8991struct foo @{ int x; char y; @} foo1; 8992@end smallexample 8993 8994@noindent 8995the value of @code{__alignof__ (foo1.y)} is 1, even though its actual 8996alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. 8997It is an error to ask for the alignment of an incomplete type other 8998than @code{void}. 8999 9000If the operand of the @code{__alignof__} expression is a function, 9001the expression evaluates to the alignment of the function which may 9002be specified by attribute @code{aligned} (@pxref{Common Function Attributes}). 9003 9004@node Inline 9005@section An Inline Function is As Fast As a Macro 9006@cindex inline functions 9007@cindex integrating function code 9008@cindex open coding 9009@cindex macros, inline alternative 9010 9011By declaring a function inline, you can direct GCC to make 9012calls to that function faster. One way GCC can achieve this is to 9013integrate that function's code into the code for its callers. This 9014makes execution faster by eliminating the function-call overhead; in 9015addition, if any of the actual argument values are constant, their 9016known values may permit simplifications at compile time so that not 9017all of the inline function's code needs to be included. The effect on 9018code size is less predictable; object code may be larger or smaller 9019with function inlining, depending on the particular case. You can 9020also direct GCC to try to integrate all ``simple enough'' functions 9021into their callers with the option @option{-finline-functions}. 9022 9023GCC implements three different semantics of declaring a function 9024inline. One is available with @option{-std=gnu89} or 9025@option{-fgnu89-inline} or when @code{gnu_inline} attribute is present 9026on all inline declarations, another when 9027@option{-std=c99}, 9028@option{-std=gnu99} or an option for a later C version is used 9029(without @option{-fgnu89-inline}), and the third 9030is used when compiling C++. 9031 9032To declare a function inline, use the @code{inline} keyword in its 9033declaration, like this: 9034 9035@smallexample 9036static inline int 9037inc (int *a) 9038@{ 9039 return (*a)++; 9040@} 9041@end smallexample 9042 9043If you are writing a header file to be included in ISO C90 programs, write 9044@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}. 9045 9046The three types of inlining behave similarly in two important cases: 9047when the @code{inline} keyword is used on a @code{static} function, 9048like the example above, and when a function is first declared without 9049using the @code{inline} keyword and then is defined with 9050@code{inline}, like this: 9051 9052@smallexample 9053extern int inc (int *a); 9054inline int 9055inc (int *a) 9056@{ 9057 return (*a)++; 9058@} 9059@end smallexample 9060 9061In both of these common cases, the program behaves the same as if you 9062had not used the @code{inline} keyword, except for its speed. 9063 9064@cindex inline functions, omission of 9065@opindex fkeep-inline-functions 9066When a function is both inline and @code{static}, if all calls to the 9067function are integrated into the caller, and the function's address is 9068never used, then the function's own assembler code is never referenced. 9069In this case, GCC does not actually output assembler code for the 9070function, unless you specify the option @option{-fkeep-inline-functions}. 9071If there is a nonintegrated call, then the function is compiled to 9072assembler code as usual. The function must also be compiled as usual if 9073the program refers to its address, because that cannot be inlined. 9074 9075@opindex Winline 9076Note that certain usages in a function definition can make it unsuitable 9077for inline substitution. Among these usages are: variadic functions, 9078use of @code{alloca}, use of computed goto (@pxref{Labels as Values}), 9079use of nonlocal goto, use of nested functions, use of @code{setjmp}, use 9080of @code{__builtin_longjmp} and use of @code{__builtin_return} or 9081@code{__builtin_apply_args}. Using @option{-Winline} warns when a 9082function marked @code{inline} could not be substituted, and gives the 9083reason for the failure. 9084 9085@cindex automatic @code{inline} for C++ member fns 9086@cindex @code{inline} automatic for C++ member fns 9087@cindex member fns, automatically @code{inline} 9088@cindex C++ member fns, automatically @code{inline} 9089@opindex fno-default-inline 9090As required by ISO C++, GCC considers member functions defined within 9091the body of a class to be marked inline even if they are 9092not explicitly declared with the @code{inline} keyword. You can 9093override this with @option{-fno-default-inline}; @pxref{C++ Dialect 9094Options,,Options Controlling C++ Dialect}. 9095 9096GCC does not inline any functions when not optimizing unless you specify 9097the @samp{always_inline} attribute for the function, like this: 9098 9099@smallexample 9100/* @r{Prototype.} */ 9101inline void foo (const char) __attribute__((always_inline)); 9102@end smallexample 9103 9104The remainder of this section is specific to GNU C90 inlining. 9105 9106@cindex non-static inline function 9107When an inline function is not @code{static}, then the compiler must assume 9108that there may be calls from other source files; since a global symbol can 9109be defined only once in any program, the function must not be defined in 9110the other source files, so the calls therein cannot be integrated. 9111Therefore, a non-@code{static} inline function is always compiled on its 9112own in the usual fashion. 9113 9114If you specify both @code{inline} and @code{extern} in the function 9115definition, then the definition is used only for inlining. In no case 9116is the function compiled on its own, not even if you refer to its 9117address explicitly. Such an address becomes an external reference, as 9118if you had only declared the function, and had not defined it. 9119 9120This combination of @code{inline} and @code{extern} has almost the 9121effect of a macro. The way to use it is to put a function definition in 9122a header file with these keywords, and put another copy of the 9123definition (lacking @code{inline} and @code{extern}) in a library file. 9124The definition in the header file causes most calls to the function 9125to be inlined. If any uses of the function remain, they refer to 9126the single copy in the library. 9127 9128@node Volatiles 9129@section When is a Volatile Object Accessed? 9130@cindex accessing volatiles 9131@cindex volatile read 9132@cindex volatile write 9133@cindex volatile access 9134 9135C has the concept of volatile objects. These are normally accessed by 9136pointers and used for accessing hardware or inter-thread 9137communication. The standard encourages compilers to refrain from 9138optimizations concerning accesses to volatile objects, but leaves it 9139implementation defined as to what constitutes a volatile access. The 9140minimum requirement is that at a sequence point all previous accesses 9141to volatile objects have stabilized and no subsequent accesses have 9142occurred. Thus an implementation is free to reorder and combine 9143volatile accesses that occur between sequence points, but cannot do 9144so for accesses across a sequence point. The use of volatile does 9145not allow you to violate the restriction on updating objects multiple 9146times between two sequence points. 9147 9148Accesses to non-volatile objects are not ordered with respect to 9149volatile accesses. You cannot use a volatile object as a memory 9150barrier to order a sequence of writes to non-volatile memory. For 9151instance: 9152 9153@smallexample 9154int *ptr = @var{something}; 9155volatile int vobj; 9156*ptr = @var{something}; 9157vobj = 1; 9158@end smallexample 9159 9160@noindent 9161Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed 9162that the write to @var{*ptr} occurs by the time the update 9163of @var{vobj} happens. If you need this guarantee, you must use 9164a stronger memory barrier such as: 9165 9166@smallexample 9167int *ptr = @var{something}; 9168volatile int vobj; 9169*ptr = @var{something}; 9170asm volatile ("" : : : "memory"); 9171vobj = 1; 9172@end smallexample 9173 9174A scalar volatile object is read when it is accessed in a void context: 9175 9176@smallexample 9177volatile int *src = @var{somevalue}; 9178*src; 9179@end smallexample 9180 9181Such expressions are rvalues, and GCC implements this as a 9182read of the volatile object being pointed to. 9183 9184Assignments are also expressions and have an rvalue. However when 9185assigning to a scalar volatile, the volatile object is not reread, 9186regardless of whether the assignment expression's rvalue is used or 9187not. If the assignment's rvalue is used, the value is that assigned 9188to the volatile object. For instance, there is no read of @var{vobj} 9189in all the following cases: 9190 9191@smallexample 9192int obj; 9193volatile int vobj; 9194vobj = @var{something}; 9195obj = vobj = @var{something}; 9196obj ? vobj = @var{onething} : vobj = @var{anotherthing}; 9197obj = (@var{something}, vobj = @var{anotherthing}); 9198@end smallexample 9199 9200If you need to read the volatile object after an assignment has 9201occurred, you must use a separate expression with an intervening 9202sequence point. 9203 9204As bit-fields are not individually addressable, volatile bit-fields may 9205be implicitly read when written to, or when adjacent bit-fields are 9206accessed. Bit-field operations may be optimized such that adjacent 9207bit-fields are only partially accessed, if they straddle a storage unit 9208boundary. For these reasons it is unwise to use volatile bit-fields to 9209access hardware. 9210 9211@node Using Assembly Language with C 9212@section How to Use Inline Assembly Language in C Code 9213@cindex @code{asm} keyword 9214@cindex assembly language in C 9215@cindex inline assembly language 9216@cindex mixing assembly language and C 9217 9218The @code{asm} keyword allows you to embed assembler instructions 9219within C code. GCC provides two forms of inline @code{asm} 9220statements. A @dfn{basic @code{asm}} statement is one with no 9221operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}} 9222statement (@pxref{Extended Asm}) includes one or more operands. 9223The extended form is preferred for mixing C and assembly language 9224within a function, but to include assembly language at 9225top level you must use basic @code{asm}. 9226 9227You can also use the @code{asm} keyword to override the assembler name 9228for a C symbol, or to place a C variable in a specific register. 9229 9230@menu 9231* Basic Asm:: Inline assembler without operands. 9232* Extended Asm:: Inline assembler with operands. 9233* Constraints:: Constraints for @code{asm} operands 9234* Asm Labels:: Specifying the assembler name to use for a C symbol. 9235* Explicit Register Variables:: Defining variables residing in specified 9236 registers. 9237* Size of an asm:: How GCC calculates the size of an @code{asm} block. 9238@end menu 9239 9240@node Basic Asm 9241@subsection Basic Asm --- Assembler Instructions Without Operands 9242@cindex basic @code{asm} 9243@cindex assembly language in C, basic 9244 9245A basic @code{asm} statement has the following syntax: 9246 9247@example 9248asm @var{asm-qualifiers} ( @var{AssemblerInstructions} ) 9249@end example 9250 9251The @code{asm} keyword is a GNU extension. 9252When writing code that can be compiled with @option{-ansi} and the 9253various @option{-std} options, use @code{__asm__} instead of 9254@code{asm} (@pxref{Alternate Keywords}). 9255 9256@subsubheading Qualifiers 9257@table @code 9258@item volatile 9259The optional @code{volatile} qualifier has no effect. 9260All basic @code{asm} blocks are implicitly volatile. 9261 9262@item inline 9263If you use the @code{inline} qualifier, then for inlining purposes the size 9264of the @code{asm} statement is taken as the smallest size possible (@pxref{Size 9265of an asm}). 9266@end table 9267 9268@subsubheading Parameters 9269@table @var 9270 9271@item AssemblerInstructions 9272This is a literal string that specifies the assembler code. The string can 9273contain any instructions recognized by the assembler, including directives. 9274GCC does not parse the assembler instructions themselves and 9275does not know what they mean or even whether they are valid assembler input. 9276 9277You may place multiple assembler instructions together in a single @code{asm} 9278string, separated by the characters normally used in assembly code for the 9279system. A combination that works in most places is a newline to break the 9280line, plus a tab character (written as @samp{\n\t}). 9281Some assemblers allow semicolons as a line separator. However, 9282note that some assembler dialects use semicolons to start a comment. 9283@end table 9284 9285@subsubheading Remarks 9286Using extended @code{asm} (@pxref{Extended Asm}) typically produces 9287smaller, safer, and more efficient code, and in most cases it is a 9288better solution than basic @code{asm}. However, there are two 9289situations where only basic @code{asm} can be used: 9290 9291@itemize @bullet 9292@item 9293Extended @code{asm} statements have to be inside a C 9294function, so to write inline assembly language at file scope (``top-level''), 9295outside of C functions, you must use basic @code{asm}. 9296You can use this technique to emit assembler directives, 9297define assembly language macros that can be invoked elsewhere in the file, 9298or write entire functions in assembly language. 9299Basic @code{asm} statements outside of functions may not use any 9300qualifiers. 9301 9302@item 9303Functions declared 9304with the @code{naked} attribute also require basic @code{asm} 9305(@pxref{Function Attributes}). 9306@end itemize 9307 9308Safely accessing C data and calling functions from basic @code{asm} is more 9309complex than it may appear. To access C data, it is better to use extended 9310@code{asm}. 9311 9312Do not expect a sequence of @code{asm} statements to remain perfectly 9313consecutive after compilation. If certain instructions need to remain 9314consecutive in the output, put them in a single multi-instruction @code{asm} 9315statement. Note that GCC's optimizers can move @code{asm} statements 9316relative to other code, including across jumps. 9317 9318@code{asm} statements may not perform jumps into other @code{asm} statements. 9319GCC does not know about these jumps, and therefore cannot take 9320account of them when deciding how to optimize. Jumps from @code{asm} to C 9321labels are only supported in extended @code{asm}. 9322 9323Under certain circumstances, GCC may duplicate (or remove duplicates of) your 9324assembly code when optimizing. This can lead to unexpected duplicate 9325symbol errors during compilation if your assembly code defines symbols or 9326labels. 9327 9328@strong{Warning:} The C standards do not specify semantics for @code{asm}, 9329making it a potential source of incompatibilities between compilers. These 9330incompatibilities may not produce compiler warnings/errors. 9331 9332GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which 9333means there is no way to communicate to the compiler what is happening 9334inside them. GCC has no visibility of symbols in the @code{asm} and may 9335discard them as unreferenced. It also does not know about side effects of 9336the assembler code, such as modifications to memory or registers. Unlike 9337some compilers, GCC assumes that no changes to general purpose registers 9338occur. This assumption may change in a future release. 9339 9340To avoid complications from future changes to the semantics and the 9341compatibility issues between compilers, consider replacing basic @code{asm} 9342with extended @code{asm}. See 9343@uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert 9344from basic asm to extended asm} for information about how to perform this 9345conversion. 9346 9347The compiler copies the assembler instructions in a basic @code{asm} 9348verbatim to the assembly language output file, without 9349processing dialects or any of the @samp{%} operators that are available with 9350extended @code{asm}. This results in minor differences between basic 9351@code{asm} strings and extended @code{asm} templates. For example, to refer to 9352registers you might use @samp{%eax} in basic @code{asm} and 9353@samp{%%eax} in extended @code{asm}. 9354 9355On targets such as x86 that support multiple assembler dialects, 9356all basic @code{asm} blocks use the assembler dialect specified by the 9357@option{-masm} command-line option (@pxref{x86 Options}). 9358Basic @code{asm} provides no 9359mechanism to provide different assembler strings for different dialects. 9360 9361For basic @code{asm} with non-empty assembler string GCC assumes 9362the assembler block does not change any general purpose registers, 9363but it may read or write any globally accessible variable. 9364 9365Here is an example of basic @code{asm} for i386: 9366 9367@example 9368/* Note that this code will not compile with -masm=intel */ 9369#define DebugBreak() asm("int $3") 9370@end example 9371 9372@node Extended Asm 9373@subsection Extended Asm - Assembler Instructions with C Expression Operands 9374@cindex extended @code{asm} 9375@cindex assembly language in C, extended 9376 9377With extended @code{asm} you can read and write C variables from 9378assembler and perform jumps from assembler code to C labels. 9379Extended @code{asm} syntax uses colons (@samp{:}) to delimit 9380the operand parameters after the assembler template: 9381 9382@example 9383asm @var{asm-qualifiers} ( @var{AssemblerTemplate} 9384 : @var{OutputOperands} 9385 @r{[} : @var{InputOperands} 9386 @r{[} : @var{Clobbers} @r{]} @r{]}) 9387 9388asm @var{asm-qualifiers} ( @var{AssemblerTemplate} 9389 : 9390 : @var{InputOperands} 9391 : @var{Clobbers} 9392 : @var{GotoLabels}) 9393@end example 9394where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the 9395first form, not). 9396 9397The @code{asm} keyword is a GNU extension. 9398When writing code that can be compiled with @option{-ansi} and the 9399various @option{-std} options, use @code{__asm__} instead of 9400@code{asm} (@pxref{Alternate Keywords}). 9401 9402@subsubheading Qualifiers 9403@table @code 9404 9405@item volatile 9406The typical use of extended @code{asm} statements is to manipulate input 9407values to produce output values. However, your @code{asm} statements may 9408also produce side effects. If so, you may need to use the @code{volatile} 9409qualifier to disable certain optimizations. @xref{Volatile}. 9410 9411@item inline 9412If you use the @code{inline} qualifier, then for inlining purposes the size 9413of the @code{asm} statement is taken as the smallest size possible 9414(@pxref{Size of an asm}). 9415 9416@item goto 9417This qualifier informs the compiler that the @code{asm} statement may 9418perform a jump to one of the labels listed in the @var{GotoLabels}. 9419@xref{GotoLabels}. 9420@end table 9421 9422@subsubheading Parameters 9423@table @var 9424@item AssemblerTemplate 9425This is a literal string that is the template for the assembler code. It is a 9426combination of fixed text and tokens that refer to the input, output, 9427and goto parameters. @xref{AssemblerTemplate}. 9428 9429@item OutputOperands 9430A comma-separated list of the C variables modified by the instructions in the 9431@var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}. 9432 9433@item InputOperands 9434A comma-separated list of C expressions read by the instructions in the 9435@var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}. 9436 9437@item Clobbers 9438A comma-separated list of registers or other values changed by the 9439@var{AssemblerTemplate}, beyond those listed as outputs. 9440An empty list is permitted. @xref{Clobbers and Scratch Registers}. 9441 9442@item GotoLabels 9443When you are using the @code{goto} form of @code{asm}, this section contains 9444the list of all C labels to which the code in the 9445@var{AssemblerTemplate} may jump. 9446@xref{GotoLabels}. 9447 9448@code{asm} statements may not perform jumps into other @code{asm} statements, 9449only to the listed @var{GotoLabels}. 9450GCC's optimizers do not know about other jumps; therefore they cannot take 9451account of them when deciding how to optimize. 9452@end table 9453 9454The total number of input + output + goto operands is limited to 30. 9455 9456@subsubheading Remarks 9457The @code{asm} statement allows you to include assembly instructions directly 9458within C code. This may help you to maximize performance in time-sensitive 9459code or to access assembly instructions that are not readily available to C 9460programs. 9461 9462Note that extended @code{asm} statements must be inside a function. Only 9463basic @code{asm} may be outside functions (@pxref{Basic Asm}). 9464Functions declared with the @code{naked} attribute also require basic 9465@code{asm} (@pxref{Function Attributes}). 9466 9467While the uses of @code{asm} are many and varied, it may help to think of an 9468@code{asm} statement as a series of low-level instructions that convert input 9469parameters to output parameters. So a simple (if not particularly useful) 9470example for i386 using @code{asm} might look like this: 9471 9472@example 9473int src = 1; 9474int dst; 9475 9476asm ("mov %1, %0\n\t" 9477 "add $1, %0" 9478 : "=r" (dst) 9479 : "r" (src)); 9480 9481printf("%d\n", dst); 9482@end example 9483 9484This code copies @code{src} to @code{dst} and add 1 to @code{dst}. 9485 9486@anchor{Volatile} 9487@subsubsection Volatile 9488@cindex volatile @code{asm} 9489@cindex @code{asm} volatile 9490 9491GCC's optimizers sometimes discard @code{asm} statements if they determine 9492there is no need for the output variables. Also, the optimizers may move 9493code out of loops if they believe that the code will always return the same 9494result (i.e.@: none of its input values change between calls). Using the 9495@code{volatile} qualifier disables these optimizations. @code{asm} statements 9496that have no output operands, including @code{asm goto} statements, 9497are implicitly volatile. 9498 9499This i386 code demonstrates a case that does not use (or require) the 9500@code{volatile} qualifier. If it is performing assertion checking, this code 9501uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is 9502unreferenced by any code. As a result, the optimizers can discard the 9503@code{asm} statement, which in turn removes the need for the entire 9504@code{DoCheck} routine. By omitting the @code{volatile} qualifier when it 9505isn't needed you allow the optimizers to produce the most efficient code 9506possible. 9507 9508@example 9509void DoCheck(uint32_t dwSomeValue) 9510@{ 9511 uint32_t dwRes; 9512 9513 // Assumes dwSomeValue is not zero. 9514 asm ("bsfl %1,%0" 9515 : "=r" (dwRes) 9516 : "r" (dwSomeValue) 9517 : "cc"); 9518 9519 assert(dwRes > 3); 9520@} 9521@end example 9522 9523The next example shows a case where the optimizers can recognize that the input 9524(@code{dwSomeValue}) never changes during the execution of the function and can 9525therefore move the @code{asm} outside the loop to produce more efficient code. 9526Again, using the @code{volatile} qualifier disables this type of optimization. 9527 9528@example 9529void do_print(uint32_t dwSomeValue) 9530@{ 9531 uint32_t dwRes; 9532 9533 for (uint32_t x=0; x < 5; x++) 9534 @{ 9535 // Assumes dwSomeValue is not zero. 9536 asm ("bsfl %1,%0" 9537 : "=r" (dwRes) 9538 : "r" (dwSomeValue) 9539 : "cc"); 9540 9541 printf("%u: %u %u\n", x, dwSomeValue, dwRes); 9542 @} 9543@} 9544@end example 9545 9546The following example demonstrates a case where you need to use the 9547@code{volatile} qualifier. 9548It uses the x86 @code{rdtsc} instruction, which reads 9549the computer's time-stamp counter. Without the @code{volatile} qualifier, 9550the optimizers might assume that the @code{asm} block will always return the 9551same value and therefore optimize away the second call. 9552 9553@example 9554uint64_t msr; 9555 9556asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. 9557 "shl $32, %%rdx\n\t" // Shift the upper bits left. 9558 "or %%rdx, %0" // 'Or' in the lower bits. 9559 : "=a" (msr) 9560 : 9561 : "rdx"); 9562 9563printf("msr: %llx\n", msr); 9564 9565// Do other work... 9566 9567// Reprint the timestamp 9568asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. 9569 "shl $32, %%rdx\n\t" // Shift the upper bits left. 9570 "or %%rdx, %0" // 'Or' in the lower bits. 9571 : "=a" (msr) 9572 : 9573 : "rdx"); 9574 9575printf("msr: %llx\n", msr); 9576@end example 9577 9578GCC's optimizers do not treat this code like the non-volatile code in the 9579earlier examples. They do not move it out of loops or omit it on the 9580assumption that the result from a previous call is still valid. 9581 9582Note that the compiler can move even @code{volatile asm} instructions relative 9583to other code, including across jump instructions. For example, on many 9584targets there is a system register that controls the rounding mode of 9585floating-point operations. Setting it with a @code{volatile asm} statement, 9586as in the following PowerPC example, does not work reliably. 9587 9588@example 9589asm volatile("mtfsf 255, %0" : : "f" (fpenv)); 9590sum = x + y; 9591@end example 9592 9593The compiler may move the addition back before the @code{volatile asm} 9594statement. To make it work as expected, add an artificial dependency to 9595the @code{asm} by referencing a variable in the subsequent code, for 9596example: 9597 9598@example 9599asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv)); 9600sum = x + y; 9601@end example 9602 9603Under certain circumstances, GCC may duplicate (or remove duplicates of) your 9604assembly code when optimizing. This can lead to unexpected duplicate symbol 9605errors during compilation if your @code{asm} code defines symbols or labels. 9606Using @samp{%=} 9607(@pxref{AssemblerTemplate}) may help resolve this problem. 9608 9609@anchor{AssemblerTemplate} 9610@subsubsection Assembler Template 9611@cindex @code{asm} assembler template 9612 9613An assembler template is a literal string containing assembler instructions. 9614The compiler replaces tokens in the template that refer 9615to inputs, outputs, and goto labels, 9616and then outputs the resulting string to the assembler. The 9617string can contain any instructions recognized by the assembler, including 9618directives. GCC does not parse the assembler instructions 9619themselves and does not know what they mean or even whether they are valid 9620assembler input. However, it does count the statements 9621(@pxref{Size of an asm}). 9622 9623You may place multiple assembler instructions together in a single @code{asm} 9624string, separated by the characters normally used in assembly code for the 9625system. A combination that works in most places is a newline to break the 9626line, plus a tab character to move to the instruction field (written as 9627@samp{\n\t}). 9628Some assemblers allow semicolons as a line separator. However, note 9629that some assembler dialects use semicolons to start a comment. 9630 9631Do not expect a sequence of @code{asm} statements to remain perfectly 9632consecutive after compilation, even when you are using the @code{volatile} 9633qualifier. If certain instructions need to remain consecutive in the output, 9634put them in a single multi-instruction @code{asm} statement. 9635 9636Accessing data from C programs without using input/output operands (such as 9637by using global symbols directly from the assembler template) may not work as 9638expected. Similarly, calling functions directly from an assembler template 9639requires a detailed understanding of the target assembler and ABI. 9640 9641Since GCC does not parse the assembler template, 9642it has no visibility of any 9643symbols it references. This may result in GCC discarding those symbols as 9644unreferenced unless they are also listed as input, output, or goto operands. 9645 9646@subsubheading Special format strings 9647 9648In addition to the tokens described by the input, output, and goto operands, 9649these tokens have special meanings in the assembler template: 9650 9651@table @samp 9652@item %% 9653Outputs a single @samp{%} into the assembler code. 9654 9655@item %= 9656Outputs a number that is unique to each instance of the @code{asm} 9657statement in the entire compilation. This option is useful when creating local 9658labels and referring to them multiple times in a single template that 9659generates multiple assembler instructions. 9660 9661@item %@{ 9662@itemx %| 9663@itemx %@} 9664Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively) 9665into the assembler code. When unescaped, these characters have special 9666meaning to indicate multiple assembler dialects, as described below. 9667@end table 9668 9669@subsubheading Multiple assembler dialects in @code{asm} templates 9670 9671On targets such as x86, GCC supports multiple assembler dialects. 9672The @option{-masm} option controls which dialect GCC uses as its 9673default for inline assembler. The target-specific documentation for the 9674@option{-masm} option contains the list of supported dialects, as well as the 9675default dialect if the option is not specified. This information may be 9676important to understand, since assembler code that works correctly when 9677compiled using one dialect will likely fail if compiled using another. 9678@xref{x86 Options}. 9679 9680If your code needs to support multiple assembler dialects (for example, if 9681you are writing public headers that need to support a variety of compilation 9682options), use constructs of this form: 9683 9684@example 9685@{ dialect0 | dialect1 | dialect2... @} 9686@end example 9687 9688This construct outputs @code{dialect0} 9689when using dialect #0 to compile the code, 9690@code{dialect1} for dialect #1, etc. If there are fewer alternatives within the 9691braces than the number of dialects the compiler supports, the construct 9692outputs nothing. 9693 9694For example, if an x86 compiler supports two dialects 9695(@samp{att}, @samp{intel}), an 9696assembler template such as this: 9697 9698@example 9699"bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2" 9700@end example 9701 9702@noindent 9703is equivalent to one of 9704 9705@example 9706"btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */} 9707"bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */} 9708@end example 9709 9710Using that same compiler, this code: 9711 9712@example 9713"xchg@{l@}\t@{%%@}ebx, %1" 9714@end example 9715 9716@noindent 9717corresponds to either 9718 9719@example 9720"xchgl\t%%ebx, %1" @r{/* att dialect */} 9721"xchg\tebx, %1" @r{/* intel dialect */} 9722@end example 9723 9724There is no support for nesting dialect alternatives. 9725 9726@anchor{OutputOperands} 9727@subsubsection Output Operands 9728@cindex @code{asm} output operands 9729 9730An @code{asm} statement has zero or more output operands indicating the names 9731of C variables modified by the assembler code. 9732 9733In this i386 example, @code{old} (referred to in the template string as 9734@code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset} 9735(@code{%2}) is an input: 9736 9737@example 9738bool old; 9739 9740__asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base. 9741 "sbb %0,%0" // Use the CF to calculate old. 9742 : "=r" (old), "+rm" (*Base) 9743 : "Ir" (Offset) 9744 : "cc"); 9745 9746return old; 9747@end example 9748 9749Operands are separated by commas. Each operand has this format: 9750 9751@example 9752@r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename}) 9753@end example 9754 9755@table @var 9756@item asmSymbolicName 9757Specifies a symbolic name for the operand. 9758Reference the name in the assembler template 9759by enclosing it in square brackets 9760(i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement 9761that contains the definition. Any valid C variable name is acceptable, 9762including names already defined in the surrounding code. No two operands 9763within the same @code{asm} statement can use the same symbolic name. 9764 9765When not using an @var{asmSymbolicName}, use the (zero-based) position 9766of the operand 9767in the list of operands in the assembler template. For example if there are 9768three output operands, use @samp{%0} in the template to refer to the first, 9769@samp{%1} for the second, and @samp{%2} for the third. 9770 9771@item constraint 9772A string constant specifying constraints on the placement of the operand; 9773@xref{Constraints}, for details. 9774 9775Output constraints must begin with either @samp{=} (a variable overwriting an 9776existing value) or @samp{+} (when reading and writing). When using 9777@samp{=}, do not assume the location contains the existing value 9778on entry to the @code{asm}, except 9779when the operand is tied to an input; @pxref{InputOperands,,Input Operands}. 9780 9781After the prefix, there must be one or more additional constraints 9782(@pxref{Constraints}) that describe where the value resides. Common 9783constraints include @samp{r} for register and @samp{m} for memory. 9784When you list more than one possible location (for example, @code{"=rm"}), 9785the compiler chooses the most efficient one based on the current context. 9786If you list as many alternates as the @code{asm} statement allows, you permit 9787the optimizers to produce the best possible code. 9788If you must use a specific register, but your Machine Constraints do not 9789provide sufficient control to select the specific register you want, 9790local register variables may provide a solution (@pxref{Local Register 9791Variables}). 9792 9793@item cvariablename 9794Specifies a C lvalue expression to hold the output, typically a variable name. 9795The enclosing parentheses are a required part of the syntax. 9796 9797@end table 9798 9799When the compiler selects the registers to use to 9800represent the output operands, it does not use any of the clobbered registers 9801(@pxref{Clobbers and Scratch Registers}). 9802 9803Output operand expressions must be lvalues. The compiler cannot check whether 9804the operands have data types that are reasonable for the instruction being 9805executed. For output expressions that are not directly addressable (for 9806example a bit-field), the constraint must allow a register. In that case, GCC 9807uses the register as the output of the @code{asm}, and then stores that 9808register into the output. 9809 9810Operands using the @samp{+} constraint modifier count as two operands 9811(that is, both as input and output) towards the total maximum of 30 operands 9812per @code{asm} statement. 9813 9814Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output 9815operands that must not overlap an input. Otherwise, 9816GCC may allocate the output operand in the same register as an unrelated 9817input operand, on the assumption that the assembler code consumes its 9818inputs before producing outputs. This assumption may be false if the assembler 9819code actually consists of more than one instruction. 9820 9821The same problem can occur if one output parameter (@var{a}) allows a register 9822constraint and another output parameter (@var{b}) allows a memory constraint. 9823The code generated by GCC to access the memory address in @var{b} can contain 9824registers which @emph{might} be shared by @var{a}, and GCC considers those 9825registers to be inputs to the asm. As above, GCC assumes that such input 9826registers are consumed before any outputs are written. This assumption may 9827result in incorrect behavior if the @code{asm} statement writes to @var{a} 9828before using 9829@var{b}. Combining the @samp{&} modifier with the register constraint on @var{a} 9830ensures that modifying @var{a} does not affect the address referenced by 9831@var{b}. Otherwise, the location of @var{b} 9832is undefined if @var{a} is modified before using @var{b}. 9833 9834@code{asm} supports operand modifiers on operands (for example @samp{%k2} 9835instead of simply @samp{%2}). Typically these qualifiers are hardware 9836dependent. The list of supported modifiers for x86 is found at 9837@ref{x86Operandmodifiers,x86 Operand modifiers}. 9838 9839If the C code that follows the @code{asm} makes no use of any of the output 9840operands, use @code{volatile} for the @code{asm} statement to prevent the 9841optimizers from discarding the @code{asm} statement as unneeded 9842(see @ref{Volatile}). 9843 9844This code makes no use of the optional @var{asmSymbolicName}. Therefore it 9845references the first output operand as @code{%0} (were there a second, it 9846would be @code{%1}, etc). The number of the first input operand is one greater 9847than that of the last output operand. In this i386 example, that makes 9848@code{Mask} referenced as @code{%1}: 9849 9850@example 9851uint32_t Mask = 1234; 9852uint32_t Index; 9853 9854 asm ("bsfl %1, %0" 9855 : "=r" (Index) 9856 : "r" (Mask) 9857 : "cc"); 9858@end example 9859 9860That code overwrites the variable @code{Index} (@samp{=}), 9861placing the value in a register (@samp{r}). 9862Using the generic @samp{r} constraint instead of a constraint for a specific 9863register allows the compiler to pick the register to use, which can result 9864in more efficient code. This may not be possible if an assembler instruction 9865requires a specific register. 9866 9867The following i386 example uses the @var{asmSymbolicName} syntax. 9868It produces the 9869same result as the code above, but some may consider it more readable or more 9870maintainable since reordering index numbers is not necessary when adding or 9871removing operands. The names @code{aIndex} and @code{aMask} 9872are only used in this example to emphasize which 9873names get used where. 9874It is acceptable to reuse the names @code{Index} and @code{Mask}. 9875 9876@example 9877uint32_t Mask = 1234; 9878uint32_t Index; 9879 9880 asm ("bsfl %[aMask], %[aIndex]" 9881 : [aIndex] "=r" (Index) 9882 : [aMask] "r" (Mask) 9883 : "cc"); 9884@end example 9885 9886Here are some more examples of output operands. 9887 9888@example 9889uint32_t c = 1; 9890uint32_t d; 9891uint32_t *e = &c; 9892 9893asm ("mov %[e], %[d]" 9894 : [d] "=rm" (d) 9895 : [e] "rm" (*e)); 9896@end example 9897 9898Here, @code{d} may either be in a register or in memory. Since the compiler 9899might already have the current value of the @code{uint32_t} location 9900pointed to by @code{e} 9901in a register, you can enable it to choose the best location 9902for @code{d} by specifying both constraints. 9903 9904@anchor{FlagOutputOperands} 9905@subsubsection Flag Output Operands 9906@cindex @code{asm} flag output operands 9907 9908Some targets have a special register that holds the ``flags'' for the 9909result of an operation or comparison. Normally, the contents of that 9910register are either unmodifed by the asm, or the @code{asm} statement is 9911considered to clobber the contents. 9912 9913On some targets, a special form of output operand exists by which 9914conditions in the flags register may be outputs of the asm. The set of 9915conditions supported are target specific, but the general rule is that 9916the output variable must be a scalar integer, and the value is boolean. 9917When supported, the target defines the preprocessor symbol 9918@code{__GCC_ASM_FLAG_OUTPUTS__}. 9919 9920Because of the special nature of the flag output operands, the constraint 9921may not include alternatives. 9922 9923Most often, the target has only one flags register, and thus is an implied 9924operand of many instructions. In this case, the operand should not be 9925referenced within the assembler template via @code{%0} etc, as there's 9926no corresponding text in the assembly language. 9927 9928@table @asis 9929@item ARM 9930@itemx AArch64 9931The flag output constraints for the ARM family are of the form 9932@samp{=@@cc@var{cond}} where @var{cond} is one of the standard 9933conditions defined in the ARM ARM for @code{ConditionHolds}. 9934 9935@table @code 9936@item eq 9937Z flag set, or equal 9938@item ne 9939Z flag clear or not equal 9940@item cs 9941@itemx hs 9942C flag set or unsigned greater than equal 9943@item cc 9944@itemx lo 9945C flag clear or unsigned less than 9946@item mi 9947N flag set or ``minus'' 9948@item pl 9949N flag clear or ``plus'' 9950@item vs 9951V flag set or signed overflow 9952@item vc 9953V flag clear 9954@item hi 9955unsigned greater than 9956@item ls 9957unsigned less than equal 9958@item ge 9959signed greater than equal 9960@item lt 9961signed less than 9962@item gt 9963signed greater than 9964@item le 9965signed less than equal 9966@end table 9967 9968The flag output constraints are not supported in thumb1 mode. 9969 9970@item x86 family 9971The flag output constraints for the x86 family are of the form 9972@samp{=@@cc@var{cond}} where @var{cond} is one of the standard 9973conditions defined in the ISA manual for @code{j@var{cc}} or 9974@code{set@var{cc}}. 9975 9976@table @code 9977@item a 9978``above'' or unsigned greater than 9979@item ae 9980``above or equal'' or unsigned greater than or equal 9981@item b 9982``below'' or unsigned less than 9983@item be 9984``below or equal'' or unsigned less than or equal 9985@item c 9986carry flag set 9987@item e 9988@itemx z 9989``equal'' or zero flag set 9990@item g 9991signed greater than 9992@item ge 9993signed greater than or equal 9994@item l 9995signed less than 9996@item le 9997signed less than or equal 9998@item o 9999overflow flag set 10000@item p 10001parity flag set 10002@item s 10003sign flag set 10004@item na 10005@itemx nae 10006@itemx nb 10007@itemx nbe 10008@itemx nc 10009@itemx ne 10010@itemx ng 10011@itemx nge 10012@itemx nl 10013@itemx nle 10014@itemx no 10015@itemx np 10016@itemx ns 10017@itemx nz 10018``not'' @var{flag}, or inverted versions of those above 10019@end table 10020 10021@end table 10022 10023@anchor{InputOperands} 10024@subsubsection Input Operands 10025@cindex @code{asm} input operands 10026@cindex @code{asm} expressions 10027 10028Input operands make values from C variables and expressions available to the 10029assembly code. 10030 10031Operands are separated by commas. Each operand has this format: 10032 10033@example 10034@r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression}) 10035@end example 10036 10037@table @var 10038@item asmSymbolicName 10039Specifies a symbolic name for the operand. 10040Reference the name in the assembler template 10041by enclosing it in square brackets 10042(i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement 10043that contains the definition. Any valid C variable name is acceptable, 10044including names already defined in the surrounding code. No two operands 10045within the same @code{asm} statement can use the same symbolic name. 10046 10047When not using an @var{asmSymbolicName}, use the (zero-based) position 10048of the operand 10049in the list of operands in the assembler template. For example if there are 10050two output operands and three inputs, 10051use @samp{%2} in the template to refer to the first input operand, 10052@samp{%3} for the second, and @samp{%4} for the third. 10053 10054@item constraint 10055A string constant specifying constraints on the placement of the operand; 10056@xref{Constraints}, for details. 10057 10058Input constraint strings may not begin with either @samp{=} or @samp{+}. 10059When you list more than one possible location (for example, @samp{"irm"}), 10060the compiler chooses the most efficient one based on the current context. 10061If you must use a specific register, but your Machine Constraints do not 10062provide sufficient control to select the specific register you want, 10063local register variables may provide a solution (@pxref{Local Register 10064Variables}). 10065 10066Input constraints can also be digits (for example, @code{"0"}). This indicates 10067that the specified input must be in the same place as the output constraint 10068at the (zero-based) index in the output constraint list. 10069When using @var{asmSymbolicName} syntax for the output operands, 10070you may use these names (enclosed in brackets @samp{[]}) instead of digits. 10071 10072@item cexpression 10073This is the C variable or expression being passed to the @code{asm} statement 10074as input. The enclosing parentheses are a required part of the syntax. 10075 10076@end table 10077 10078When the compiler selects the registers to use to represent the input 10079operands, it does not use any of the clobbered registers 10080(@pxref{Clobbers and Scratch Registers}). 10081 10082If there are no output operands but there are input operands, place two 10083consecutive colons where the output operands would go: 10084 10085@example 10086__asm__ ("some instructions" 10087 : /* No outputs. */ 10088 : "r" (Offset / 8)); 10089@end example 10090 10091@strong{Warning:} Do @emph{not} modify the contents of input-only operands 10092(except for inputs tied to outputs). The compiler assumes that on exit from 10093the @code{asm} statement these operands contain the same values as they 10094had before executing the statement. 10095It is @emph{not} possible to use clobbers 10096to inform the compiler that the values in these inputs are changing. One 10097common work-around is to tie the changing input variable to an output variable 10098that never gets used. Note, however, that if the code that follows the 10099@code{asm} statement makes no use of any of the output operands, the GCC 10100optimizers may discard the @code{asm} statement as unneeded 10101(see @ref{Volatile}). 10102 10103@code{asm} supports operand modifiers on operands (for example @samp{%k2} 10104instead of simply @samp{%2}). Typically these qualifiers are hardware 10105dependent. The list of supported modifiers for x86 is found at 10106@ref{x86Operandmodifiers,x86 Operand modifiers}. 10107 10108In this example using the fictitious @code{combine} instruction, the 10109constraint @code{"0"} for input operand 1 says that it must occupy the same 10110location as output operand 0. Only input operands may use numbers in 10111constraints, and they must each refer to an output operand. Only a number (or 10112the symbolic assembler name) in the constraint can guarantee that one operand 10113is in the same place as another. The mere fact that @code{foo} is the value of 10114both operands is not enough to guarantee that they are in the same place in 10115the generated assembler code. 10116 10117@example 10118asm ("combine %2, %0" 10119 : "=r" (foo) 10120 : "0" (foo), "g" (bar)); 10121@end example 10122 10123Here is an example using symbolic names. 10124 10125@example 10126asm ("cmoveq %1, %2, %[result]" 10127 : [result] "=r"(result) 10128 : "r" (test), "r" (new), "[result]" (old)); 10129@end example 10130 10131@anchor{Clobbers and Scratch Registers} 10132@subsubsection Clobbers and Scratch Registers 10133@cindex @code{asm} clobbers 10134@cindex @code{asm} scratch registers 10135 10136While the compiler is aware of changes to entries listed in the output 10137operands, the inline @code{asm} code may modify more than just the outputs. For 10138example, calculations may require additional registers, or the processor may 10139overwrite a register as a side effect of a particular assembler instruction. 10140In order to inform the compiler of these changes, list them in the clobber 10141list. Clobber list items are either register names or the special clobbers 10142(listed below). Each clobber list item is a string constant 10143enclosed in double quotes and separated by commas. 10144 10145Clobber descriptions may not in any way overlap with an input or output 10146operand. For example, you may not have an operand describing a register class 10147with one member when listing that register in the clobber list. Variables 10148declared to live in specific registers (@pxref{Explicit Register 10149Variables}) and used 10150as @code{asm} input or output operands must have no part mentioned in the 10151clobber description. In particular, there is no way to specify that input 10152operands get modified without also specifying them as output operands. 10153 10154When the compiler selects which registers to use to represent input and output 10155operands, it does not use any of the clobbered registers. As a result, 10156clobbered registers are available for any use in the assembler code. 10157 10158Another restriction is that the clobber list should not contain the 10159stack pointer register. This is because the compiler requires the 10160value of the stack pointer to be the same after an @code{asm} 10161statement as it was on entry to the statement. However, previous 10162versions of GCC did not enforce this rule and allowed the stack 10163pointer to appear in the list, with unclear semantics. This behavior 10164is deprecated and listing the stack pointer may become an error in 10165future versions of GCC@. 10166 10167Here is a realistic example for the VAX showing the use of clobbered 10168registers: 10169 10170@example 10171asm volatile ("movc3 %0, %1, %2" 10172 : /* No outputs. */ 10173 : "g" (from), "g" (to), "g" (count) 10174 : "r0", "r1", "r2", "r3", "r4", "r5", "memory"); 10175@end example 10176 10177Also, there are two special clobber arguments: 10178 10179@table @code 10180@item "cc" 10181The @code{"cc"} clobber indicates that the assembler code modifies the flags 10182register. On some machines, GCC represents the condition codes as a specific 10183hardware register; @code{"cc"} serves to name this register. 10184On other machines, condition code handling is different, 10185and specifying @code{"cc"} has no effect. But 10186it is valid no matter what the target. 10187 10188@item "memory" 10189The @code{"memory"} clobber tells the compiler that the assembly code 10190performs memory 10191reads or writes to items other than those listed in the input and output 10192operands (for example, accessing the memory pointed to by one of the input 10193parameters). To ensure memory contains correct values, GCC may need to flush 10194specific register values to memory before executing the @code{asm}. Further, 10195the compiler does not assume that any values read from memory before an 10196@code{asm} remain unchanged after that @code{asm}; it reloads them as 10197needed. 10198Using the @code{"memory"} clobber effectively forms a read/write 10199memory barrier for the compiler. 10200 10201Note that this clobber does not prevent the @emph{processor} from doing 10202speculative reads past the @code{asm} statement. To prevent that, you need 10203processor-specific fence instructions. 10204 10205@end table 10206 10207Flushing registers to memory has performance implications and may be 10208an issue for time-sensitive code. You can provide better information 10209to GCC to avoid this, as shown in the following examples. At a 10210minimum, aliasing rules allow GCC to know what memory @emph{doesn't} 10211need to be flushed. 10212 10213Here is a fictitious sum of squares instruction, that takes two 10214pointers to floating point values in memory and produces a floating 10215point register output. 10216Notice that @code{x}, and @code{y} both appear twice in the @code{asm} 10217parameters, once to specify memory accessed, and once to specify a 10218base register used by the @code{asm}. You won't normally be wasting a 10219register by doing this as GCC can use the same register for both 10220purposes. However, it would be foolish to use both @code{%1} and 10221@code{%3} for @code{x} in this @code{asm} and expect them to be the 10222same. In fact, @code{%3} may well not be a register. It might be a 10223symbolic memory reference to the object pointed to by @code{x}. 10224 10225@smallexample 10226asm ("sumsq %0, %1, %2" 10227 : "+f" (result) 10228 : "r" (x), "r" (y), "m" (*x), "m" (*y)); 10229@end smallexample 10230 10231Here is a fictitious @code{*z++ = *x++ * *y++} instruction. 10232Notice that the @code{x}, @code{y} and @code{z} pointer registers 10233must be specified as input/output because the @code{asm} modifies 10234them. 10235 10236@smallexample 10237asm ("vecmul %0, %1, %2" 10238 : "+r" (z), "+r" (x), "+r" (y), "=m" (*z) 10239 : "m" (*x), "m" (*y)); 10240@end smallexample 10241 10242An x86 example where the string memory argument is of unknown length. 10243 10244@smallexample 10245asm("repne scasb" 10246 : "=c" (count), "+D" (p) 10247 : "m" (*(const char (*)[]) p), "0" (-1), "a" (0)); 10248@end smallexample 10249 10250If you know the above will only be reading a ten byte array then you 10251could instead use a memory input like: 10252@code{"m" (*(const char (*)[10]) p)}. 10253 10254Here is an example of a PowerPC vector scale implemented in assembly, 10255complete with vector and condition code clobbers, and some initialized 10256offset registers that are unchanged by the @code{asm}. 10257 10258@smallexample 10259void 10260dscal (size_t n, double *x, double alpha) 10261@{ 10262 asm ("/* lots of asm here */" 10263 : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x) 10264 : "d" (alpha), "b" (32), "b" (48), "b" (64), 10265 "b" (80), "b" (96), "b" (112) 10266 : "cr0", 10267 "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39", 10268 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"); 10269@} 10270@end smallexample 10271 10272Rather than allocating fixed registers via clobbers to provide scratch 10273registers for an @code{asm} statement, an alternative is to define a 10274variable and make it an early-clobber output as with @code{a2} and 10275@code{a3} in the example below. This gives the compiler register 10276allocator more freedom. You can also define a variable and make it an 10277output tied to an input as with @code{a0} and @code{a1}, tied 10278respectively to @code{ap} and @code{lda}. Of course, with tied 10279outputs your @code{asm} can't use the input value after modifying the 10280output register since they are one and the same register. What's 10281more, if you omit the early-clobber on the output, it is possible that 10282GCC might allocate the same register to another of the inputs if GCC 10283could prove they had the same value on entry to the @code{asm}. This 10284is why @code{a1} has an early-clobber. Its tied input, @code{lda} 10285might conceivably be known to have the value 16 and without an 10286early-clobber share the same register as @code{%11}. On the other 10287hand, @code{ap} can't be the same as any of the other inputs, so an 10288early-clobber on @code{a0} is not needed. It is also not desirable in 10289this case. An early-clobber on @code{a0} would cause GCC to allocate 10290a separate register for the @code{"m" (*(const double (*)[]) ap)} 10291input. Note that tying an input to an output is the way to set up an 10292initialized temporary register modified by an @code{asm} statement. 10293An input not tied to an output is assumed by GCC to be unchanged, for 10294example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might 10295use that register in following code if the value 16 happened to be 10296needed. You can even use a normal @code{asm} output for a scratch if 10297all inputs that might share the same register are consumed before the 10298scratch is used. The VSX registers clobbered by the @code{asm} 10299statement could have used this technique except for GCC's limit on the 10300number of @code{asm} parameters. 10301 10302@smallexample 10303static void 10304dgemv_kernel_4x4 (long n, const double *ap, long lda, 10305 const double *x, double *y, double alpha) 10306@{ 10307 double *a0; 10308 double *a1; 10309 double *a2; 10310 double *a3; 10311 10312 __asm__ 10313 ( 10314 /* lots of asm here */ 10315 "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n" 10316 "#a0=%3 a1=%4 a2=%5 a3=%6" 10317 : 10318 "+m" (*(double (*)[n]) y), 10319 "+&r" (n), // 1 10320 "+b" (y), // 2 10321 "=b" (a0), // 3 10322 "=&b" (a1), // 4 10323 "=&b" (a2), // 5 10324 "=&b" (a3) // 6 10325 : 10326 "m" (*(const double (*)[n]) x), 10327 "m" (*(const double (*)[]) ap), 10328 "d" (alpha), // 9 10329 "r" (x), // 10 10330 "b" (16), // 11 10331 "3" (ap), // 12 10332 "4" (lda) // 13 10333 : 10334 "cr0", 10335 "vs32","vs33","vs34","vs35","vs36","vs37", 10336 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47" 10337 ); 10338@} 10339@end smallexample 10340 10341@anchor{GotoLabels} 10342@subsubsection Goto Labels 10343@cindex @code{asm} goto labels 10344 10345@code{asm goto} allows assembly code to jump to one or more C labels. The 10346@var{GotoLabels} section in an @code{asm goto} statement contains 10347a comma-separated 10348list of all C labels to which the assembler code may jump. GCC assumes that 10349@code{asm} execution falls through to the next statement (if this is not the 10350case, consider using the @code{__builtin_unreachable} intrinsic after the 10351@code{asm} statement). Optimization of @code{asm goto} may be improved by 10352using the @code{hot} and @code{cold} label attributes (@pxref{Label 10353Attributes}). 10354 10355An @code{asm goto} statement cannot have outputs. 10356This is due to an internal restriction of 10357the compiler: control transfer instructions cannot have outputs. 10358If the assembler code does modify anything, use the @code{"memory"} clobber 10359to force the 10360optimizers to flush all register values to memory and reload them if 10361necessary after the @code{asm} statement. 10362 10363Also note that an @code{asm goto} statement is always implicitly 10364considered volatile. 10365 10366To reference a label in the assembler template, 10367prefix it with @samp{%l} (lowercase @samp{L}) followed 10368by its (zero-based) position in @var{GotoLabels} plus the number of input 10369operands. For example, if the @code{asm} has three inputs and references two 10370labels, refer to the first label as @samp{%l3} and the second as @samp{%l4}). 10371 10372Alternately, you can reference labels using the actual C label name enclosed 10373in brackets. For example, to reference a label named @code{carry}, you can 10374use @samp{%l[carry]}. The label must still be listed in the @var{GotoLabels} 10375section when using this approach. 10376 10377Here is an example of @code{asm goto} for i386: 10378 10379@example 10380asm goto ( 10381 "btl %1, %0\n\t" 10382 "jc %l2" 10383 : /* No outputs. */ 10384 : "r" (p1), "r" (p2) 10385 : "cc" 10386 : carry); 10387 10388return 0; 10389 10390carry: 10391return 1; 10392@end example 10393 10394The following example shows an @code{asm goto} that uses a memory clobber. 10395 10396@example 10397int frob(int x) 10398@{ 10399 int y; 10400 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5" 10401 : /* No outputs. */ 10402 : "r"(x), "r"(&y) 10403 : "r5", "memory" 10404 : error); 10405 return y; 10406error: 10407 return -1; 10408@} 10409@end example 10410 10411@anchor{x86Operandmodifiers} 10412@subsubsection x86 Operand Modifiers 10413 10414References to input, output, and goto operands in the assembler template 10415of extended @code{asm} statements can use 10416modifiers to affect the way the operands are formatted in 10417the code output to the assembler. For example, the 10418following code uses the @samp{h} and @samp{b} modifiers for x86: 10419 10420@example 10421uint16_t num; 10422asm volatile ("xchg %h0, %b0" : "+a" (num) ); 10423@end example 10424 10425@noindent 10426These modifiers generate this assembler code: 10427 10428@example 10429xchg %ah, %al 10430@end example 10431 10432The rest of this discussion uses the following code for illustrative purposes. 10433 10434@example 10435int main() 10436@{ 10437 int iInt = 1; 10438 10439top: 10440 10441 asm volatile goto ("some assembler instructions here" 10442 : /* No outputs. */ 10443 : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42) 10444 : /* No clobbers. */ 10445 : top); 10446@} 10447@end example 10448 10449With no modifiers, this is what the output from the operands would be 10450for the @samp{att} and @samp{intel} dialects of assembler: 10451 10452@multitable {Operand} {$.L2} {OFFSET FLAT:.L2} 10453@headitem Operand @tab @samp{att} @tab @samp{intel} 10454@item @code{%0} 10455@tab @code{%eax} 10456@tab @code{eax} 10457@item @code{%1} 10458@tab @code{$2} 10459@tab @code{2} 10460@item @code{%3} 10461@tab @code{$.L3} 10462@tab @code{OFFSET FLAT:.L3} 10463@end multitable 10464 10465The table below shows the list of supported modifiers and their effects. 10466 10467@multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}} 10468@headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel} 10469@item @code{A} 10470@tab Print an absolute memory reference. 10471@tab @code{%A0} 10472@tab @code{*%rax} 10473@tab @code{rax} 10474@item @code{b} 10475@tab Print the QImode name of the register. 10476@tab @code{%b0} 10477@tab @code{%al} 10478@tab @code{al} 10479@item @code{c} 10480@tab Require a constant operand and print the constant expression with no punctuation. 10481@tab @code{%c1} 10482@tab @code{2} 10483@tab @code{2} 10484@item @code{E} 10485@tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit. 10486Otherwise mode is unspecified (VOIDmode). 10487@tab @code{%E1} 10488@tab @code{%(rax)} 10489@tab @code{[rax]} 10490@item @code{h} 10491@tab Print the QImode name for a ``high'' register. 10492@tab @code{%h0} 10493@tab @code{%ah} 10494@tab @code{ah} 10495@item @code{H} 10496@tab Add 8 bytes to an offsettable memory reference. Useful when accessing the 10497high 8 bytes of SSE values. For a memref in (%rax), it generates 10498@tab @code{%H0} 10499@tab @code{8(%rax)} 10500@tab @code{8[rax]} 10501@item @code{k} 10502@tab Print the SImode name of the register. 10503@tab @code{%k0} 10504@tab @code{%eax} 10505@tab @code{eax} 10506@item @code{l} 10507@tab Print the label name with no punctuation. 10508@tab @code{%l3} 10509@tab @code{.L3} 10510@tab @code{.L3} 10511@item @code{p} 10512@tab Print raw symbol name (without syntax-specific prefixes). 10513@tab @code{%p2} 10514@tab @code{42} 10515@tab @code{42} 10516@item @code{P} 10517@tab If used for a function, print the PLT suffix and generate PIC code. 10518For example, emit @code{foo@@PLT} instead of 'foo' for the function 10519foo(). If used for a constant, drop all syntax-specific prefixes and 10520issue the bare constant. See @code{p} above. 10521@item @code{q} 10522@tab Print the DImode name of the register. 10523@tab @code{%q0} 10524@tab @code{%rax} 10525@tab @code{rax} 10526@item @code{w} 10527@tab Print the HImode name of the register. 10528@tab @code{%w0} 10529@tab @code{%ax} 10530@tab @code{ax} 10531@item @code{z} 10532@tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}). 10533@tab @code{%z0} 10534@tab @code{l} 10535@tab 10536@end multitable 10537 10538@code{V} is a special modifier which prints the name of the full integer 10539register without @code{%}. 10540 10541@anchor{x86floatingpointasmoperands} 10542@subsubsection x86 Floating-Point @code{asm} Operands 10543 10544On x86 targets, there are several rules on the usage of stack-like registers 10545in the operands of an @code{asm}. These rules apply only to the operands 10546that are stack-like registers: 10547 10548@enumerate 10549@item 10550Given a set of input registers that die in an @code{asm}, it is 10551necessary to know which are implicitly popped by the @code{asm}, and 10552which must be explicitly popped by GCC@. 10553 10554An input register that is implicitly popped by the @code{asm} must be 10555explicitly clobbered, unless it is constrained to match an 10556output operand. 10557 10558@item 10559For any input register that is implicitly popped by an @code{asm}, it is 10560necessary to know how to adjust the stack to compensate for the pop. 10561If any non-popped input is closer to the top of the reg-stack than 10562the implicitly popped register, it would not be possible to know what the 10563stack looked like---it's not clear how the rest of the stack ``slides 10564up''. 10565 10566All implicitly popped input registers must be closer to the top of 10567the reg-stack than any input that is not implicitly popped. 10568 10569It is possible that if an input dies in an @code{asm}, the compiler might 10570use the input register for an output reload. Consider this example: 10571 10572@smallexample 10573asm ("foo" : "=t" (a) : "f" (b)); 10574@end smallexample 10575 10576@noindent 10577This code says that input @code{b} is not popped by the @code{asm}, and that 10578the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one 10579deeper after the @code{asm} than it was before. But, it is possible that 10580reload may think that it can use the same register for both the input and 10581the output. 10582 10583To prevent this from happening, 10584if any input operand uses the @samp{f} constraint, all output register 10585constraints must use the @samp{&} early-clobber modifier. 10586 10587The example above is correctly written as: 10588 10589@smallexample 10590asm ("foo" : "=&t" (a) : "f" (b)); 10591@end smallexample 10592 10593@item 10594Some operands need to be in particular places on the stack. All 10595output operands fall in this category---GCC has no other way to 10596know which registers the outputs appear in unless you indicate 10597this in the constraints. 10598 10599Output operands must specifically indicate which register an output 10600appears in after an @code{asm}. @samp{=f} is not allowed: the operand 10601constraints must select a class with a single register. 10602 10603@item 10604Output operands may not be ``inserted'' between existing stack registers. 10605Since no 387 opcode uses a read/write operand, all output operands 10606are dead before the @code{asm}, and are pushed by the @code{asm}. 10607It makes no sense to push anywhere but the top of the reg-stack. 10608 10609Output operands must start at the top of the reg-stack: output 10610operands may not ``skip'' a register. 10611 10612@item 10613Some @code{asm} statements may need extra stack space for internal 10614calculations. This can be guaranteed by clobbering stack registers 10615unrelated to the inputs and outputs. 10616 10617@end enumerate 10618 10619This @code{asm} 10620takes one input, which is internally popped, and produces two outputs. 10621 10622@smallexample 10623asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); 10624@end smallexample 10625 10626@noindent 10627This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode, 10628and replaces them with one output. The @code{st(1)} clobber is necessary 10629for the compiler to know that @code{fyl2xp1} pops both inputs. 10630 10631@smallexample 10632asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); 10633@end smallexample 10634 10635@lowersections 10636@include md.texi 10637@raisesections 10638 10639@node Asm Labels 10640@subsection Controlling Names Used in Assembler Code 10641@cindex assembler names for identifiers 10642@cindex names used in assembler code 10643@cindex identifiers, names in assembler code 10644 10645You can specify the name to be used in the assembler code for a C 10646function or variable by writing the @code{asm} (or @code{__asm__}) 10647keyword after the declarator. 10648It is up to you to make sure that the assembler names you choose do not 10649conflict with any other assembler symbols, or reference registers. 10650 10651@subsubheading Assembler names for data: 10652 10653This sample shows how to specify the assembler name for data: 10654 10655@smallexample 10656int foo asm ("myfoo") = 2; 10657@end smallexample 10658 10659@noindent 10660This specifies that the name to be used for the variable @code{foo} in 10661the assembler code should be @samp{myfoo} rather than the usual 10662@samp{_foo}. 10663 10664On systems where an underscore is normally prepended to the name of a C 10665variable, this feature allows you to define names for the 10666linker that do not start with an underscore. 10667 10668GCC does not support using this feature with a non-static local variable 10669since such variables do not have assembler names. If you are 10670trying to put the variable in a particular register, see 10671@ref{Explicit Register Variables}. 10672 10673@subsubheading Assembler names for functions: 10674 10675To specify the assembler name for functions, write a declaration for the 10676function before its definition and put @code{asm} there, like this: 10677 10678@smallexample 10679int func (int x, int y) asm ("MYFUNC"); 10680 10681int func (int x, int y) 10682@{ 10683 /* @r{@dots{}} */ 10684@end smallexample 10685 10686@noindent 10687This specifies that the name to be used for the function @code{func} in 10688the assembler code should be @code{MYFUNC}. 10689 10690@node Explicit Register Variables 10691@subsection Variables in Specified Registers 10692@anchor{Explicit Reg Vars} 10693@cindex explicit register variables 10694@cindex variables in specified registers 10695@cindex specified registers 10696 10697GNU C allows you to associate specific hardware registers with C 10698variables. In almost all cases, allowing the compiler to assign 10699registers produces the best code. However under certain unusual 10700circumstances, more precise control over the variable storage is 10701required. 10702 10703Both global and local variables can be associated with a register. The 10704consequences of performing this association are very different between 10705the two, as explained in the sections below. 10706 10707@menu 10708* Global Register Variables:: Variables declared at global scope. 10709* Local Register Variables:: Variables declared within a function. 10710@end menu 10711 10712@node Global Register Variables 10713@subsubsection Defining Global Register Variables 10714@anchor{Global Reg Vars} 10715@cindex global register variables 10716@cindex registers, global variables in 10717@cindex registers, global allocation 10718 10719You can define a global register variable and associate it with a specified 10720register like this: 10721 10722@smallexample 10723register int *foo asm ("r12"); 10724@end smallexample 10725 10726@noindent 10727Here @code{r12} is the name of the register that should be used. Note that 10728this is the same syntax used for defining local register variables, but for 10729a global variable the declaration appears outside a function. The 10730@code{register} keyword is required, and cannot be combined with 10731@code{static}. The register name must be a valid register name for the 10732target platform. 10733 10734Do not use type qualifiers such as @code{const} and @code{volatile}, as 10735the outcome may be contrary to expectations. In particular, using the 10736@code{volatile} qualifier does not fully prevent the compiler from 10737optimizing accesses to the register. 10738 10739Registers are a scarce resource on most systems and allowing the 10740compiler to manage their usage usually results in the best code. However, 10741under special circumstances it can make sense to reserve some globally. 10742For example this may be useful in programs such as programming language 10743interpreters that have a couple of global variables that are accessed 10744very often. 10745 10746After defining a global register variable, for the current compilation 10747unit: 10748 10749@itemize @bullet 10750@item If the register is a call-saved register, call ABI is affected: 10751the register will not be restored in function epilogue sequences after 10752the variable has been assigned. Therefore, functions cannot safely 10753return to callers that assume standard ABI. 10754@item Conversely, if the register is a call-clobbered register, making 10755calls to functions that use standard ABI may lose contents of the variable. 10756Such calls may be created by the compiler even if none are evident in 10757the original program, for example when libgcc functions are used to 10758make up for unavailable instructions. 10759@item Accesses to the variable may be optimized as usual and the register 10760remains available for allocation and use in any computations, provided that 10761observable values of the variable are not affected. 10762@item If the variable is referenced in inline assembly, the type of access 10763must be provided to the compiler via constraints (@pxref{Constraints}). 10764Accesses from basic asms are not supported. 10765@end itemize 10766 10767Note that these points @emph{only} apply to code that is compiled with the 10768definition. The behavior of code that is merely linked in (for example 10769code from libraries) is not affected. 10770 10771If you want to recompile source files that do not actually use your global 10772register variable so they do not use the specified register for any other 10773purpose, you need not actually add the global register declaration to 10774their source code. It suffices to specify the compiler option 10775@option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the 10776register. 10777 10778@subsubheading Declaring the variable 10779 10780Global register variables cannot have initial values, because an 10781executable file has no means to supply initial contents for a register. 10782 10783When selecting a register, choose one that is normally saved and 10784restored by function calls on your machine. This ensures that code 10785which is unaware of this reservation (such as library routines) will 10786restore it before returning. 10787 10788On machines with register windows, be sure to choose a global 10789register that is not affected magically by the function call mechanism. 10790 10791@subsubheading Using the variable 10792 10793@cindex @code{qsort}, and global register variables 10794When calling routines that are not aware of the reservation, be 10795cautious if those routines call back into code which uses them. As an 10796example, if you call the system library version of @code{qsort}, it may 10797clobber your registers during execution, but (if you have selected 10798appropriate registers) it will restore them before returning. However 10799it will @emph{not} restore them before calling @code{qsort}'s comparison 10800function. As a result, global values will not reliably be available to 10801the comparison function unless the @code{qsort} function itself is rebuilt. 10802 10803Similarly, it is not safe to access the global register variables from signal 10804handlers or from more than one thread of control. Unless you recompile 10805them specially for the task at hand, the system library routines may 10806temporarily use the register for other things. Furthermore, since the register 10807is not reserved exclusively for the variable, accessing it from handlers of 10808asynchronous signals may observe unrelated temporary values residing in the 10809register. 10810 10811@cindex register variable after @code{longjmp} 10812@cindex global register after @code{longjmp} 10813@cindex value after @code{longjmp} 10814@findex longjmp 10815@findex setjmp 10816On most machines, @code{longjmp} restores to each global register 10817variable the value it had at the time of the @code{setjmp}. On some 10818machines, however, @code{longjmp} does not change the value of global 10819register variables. To be portable, the function that called @code{setjmp} 10820should make other arrangements to save the values of the global register 10821variables, and to restore them in a @code{longjmp}. This way, the same 10822thing happens regardless of what @code{longjmp} does. 10823 10824@node Local Register Variables 10825@subsubsection Specifying Registers for Local Variables 10826@anchor{Local Reg Vars} 10827@cindex local variables, specifying registers 10828@cindex specifying registers for local variables 10829@cindex registers for local variables 10830 10831You can define a local register variable and associate it with a specified 10832register like this: 10833 10834@smallexample 10835register int *foo asm ("r12"); 10836@end smallexample 10837 10838@noindent 10839Here @code{r12} is the name of the register that should be used. Note 10840that this is the same syntax used for defining global register variables, 10841but for a local variable the declaration appears within a function. The 10842@code{register} keyword is required, and cannot be combined with 10843@code{static}. The register name must be a valid register name for the 10844target platform. 10845 10846Do not use type qualifiers such as @code{const} and @code{volatile}, as 10847the outcome may be contrary to expectations. In particular, when the 10848@code{const} qualifier is used, the compiler may substitute the 10849variable with its initializer in @code{asm} statements, which may cause 10850the corresponding operand to appear in a different register. 10851 10852As with global register variables, it is recommended that you choose 10853a register that is normally saved and restored by function calls on your 10854machine, so that calls to library routines will not clobber it. 10855 10856The only supported use for this feature is to specify registers 10857for input and output operands when calling Extended @code{asm} 10858(@pxref{Extended Asm}). This may be necessary if the constraints for a 10859particular machine don't provide sufficient control to select the desired 10860register. To force an operand into a register, create a local variable 10861and specify the register name after the variable's declaration. Then use 10862the local variable for the @code{asm} operand and specify any constraint 10863letter that matches the register: 10864 10865@smallexample 10866register int *p1 asm ("r0") = @dots{}; 10867register int *p2 asm ("r1") = @dots{}; 10868register int *result asm ("r0"); 10869asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 10870@end smallexample 10871 10872@emph{Warning:} In the above example, be aware that a register (for example 10873@code{r0}) can be call-clobbered by subsequent code, including function 10874calls and library calls for arithmetic operators on other variables (for 10875example the initialization of @code{p2}). In this case, use temporary 10876variables for expressions between the register assignments: 10877 10878@smallexample 10879int t1 = @dots{}; 10880register int *p1 asm ("r0") = @dots{}; 10881register int *p2 asm ("r1") = t1; 10882register int *result asm ("r0"); 10883asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 10884@end smallexample 10885 10886Defining a register variable does not reserve the register. Other than 10887when invoking the Extended @code{asm}, the contents of the specified 10888register are not guaranteed. For this reason, the following uses 10889are explicitly @emph{not} supported. If they appear to work, it is only 10890happenstance, and may stop working as intended due to (seemingly) 10891unrelated changes in surrounding code, or even minor changes in the 10892optimization of a future version of gcc: 10893 10894@itemize @bullet 10895@item Passing parameters to or from Basic @code{asm} 10896@item Passing parameters to or from Extended @code{asm} without using input 10897or output operands. 10898@item Passing parameters to or from routines written in assembler (or 10899other languages) using non-standard calling conventions. 10900@end itemize 10901 10902Some developers use Local Register Variables in an attempt to improve 10903gcc's allocation of registers, especially in large functions. In this 10904case the register name is essentially a hint to the register allocator. 10905While in some instances this can generate better code, improvements are 10906subject to the whims of the allocator/optimizers. Since there are no 10907guarantees that your improvements won't be lost, this usage of Local 10908Register Variables is discouraged. 10909 10910On the MIPS platform, there is related use for local register variables 10911with slightly different characteristics (@pxref{MIPS Coprocessors,, 10912Defining coprocessor specifics for MIPS targets, gccint, 10913GNU Compiler Collection (GCC) Internals}). 10914 10915@node Size of an asm 10916@subsection Size of an @code{asm} 10917 10918Some targets require that GCC track the size of each instruction used 10919in order to generate correct code. Because the final length of the 10920code produced by an @code{asm} statement is only known by the 10921assembler, GCC must make an estimate as to how big it will be. It 10922does this by counting the number of instructions in the pattern of the 10923@code{asm} and multiplying that by the length of the longest 10924instruction supported by that processor. (When working out the number 10925of instructions, it assumes that any occurrence of a newline or of 10926whatever statement separator character is supported by the assembler --- 10927typically @samp{;} --- indicates the end of an instruction.) 10928 10929Normally, GCC's estimate is adequate to ensure that correct 10930code is generated, but it is possible to confuse the compiler if you use 10931pseudo instructions or assembler macros that expand into multiple real 10932instructions, or if you use assembler directives that expand to more 10933space in the object file than is needed for a single instruction. 10934If this happens then the assembler may produce a diagnostic saying that 10935a label is unreachable. 10936 10937@cindex @code{asm inline} 10938This size is also used for inlining decisions. If you use @code{asm inline} 10939instead of just @code{asm}, then for inlining purposes the size of the asm 10940is taken as the minimum size, ignoring how many instructions GCC thinks it is. 10941 10942@node Alternate Keywords 10943@section Alternate Keywords 10944@cindex alternate keywords 10945@cindex keywords, alternate 10946 10947@option{-ansi} and the various @option{-std} options disable certain 10948keywords. This causes trouble when you want to use GNU C extensions, or 10949a general-purpose header file that should be usable by all programs, 10950including ISO C programs. The keywords @code{asm}, @code{typeof} and 10951@code{inline} are not available in programs compiled with 10952@option{-ansi} or @option{-std} (although @code{inline} can be used in a 10953program compiled with @option{-std=c99} or a later standard). The 10954ISO C99 keyword 10955@code{restrict} is only available when @option{-std=gnu99} (which will 10956eventually be the default) or @option{-std=c99} (or the equivalent 10957@option{-std=iso9899:1999}), or an option for a later standard 10958version, is used. 10959 10960The way to solve these problems is to put @samp{__} at the beginning and 10961end of each problematical keyword. For example, use @code{__asm__} 10962instead of @code{asm}, and @code{__inline__} instead of @code{inline}. 10963 10964Other C compilers won't accept these alternative keywords; if you want to 10965compile with another compiler, you can define the alternate keywords as 10966macros to replace them with the customary keywords. It looks like this: 10967 10968@smallexample 10969#ifndef __GNUC__ 10970#define __asm__ asm 10971#endif 10972@end smallexample 10973 10974@findex __extension__ 10975@opindex pedantic 10976@option{-pedantic} and other options cause warnings for many GNU C extensions. 10977You can 10978prevent such warnings within one expression by writing 10979@code{__extension__} before the expression. @code{__extension__} has no 10980effect aside from this. 10981 10982@node Incomplete Enums 10983@section Incomplete @code{enum} Types 10984 10985You can define an @code{enum} tag without specifying its possible values. 10986This results in an incomplete type, much like what you get if you write 10987@code{struct foo} without describing the elements. A later declaration 10988that does specify the possible values completes the type. 10989 10990You cannot allocate variables or storage using the type while it is 10991incomplete. However, you can work with pointers to that type. 10992 10993This extension may not be very useful, but it makes the handling of 10994@code{enum} more consistent with the way @code{struct} and @code{union} 10995are handled. 10996 10997This extension is not supported by GNU C++. 10998 10999@node Function Names 11000@section Function Names as Strings 11001@cindex @code{__func__} identifier 11002@cindex @code{__FUNCTION__} identifier 11003@cindex @code{__PRETTY_FUNCTION__} identifier 11004 11005GCC provides three magic constants that hold the name of the current 11006function as a string. In C++11 and later modes, all three are treated 11007as constant expressions and can be used in @code{constexpr} constexts. 11008The first of these constants is @code{__func__}, which is part of 11009the C99 standard: 11010 11011The identifier @code{__func__} is implicitly declared by the translator 11012as if, immediately following the opening brace of each function 11013definition, the declaration 11014 11015@smallexample 11016static const char __func__[] = "function-name"; 11017@end smallexample 11018 11019@noindent 11020appeared, where function-name is the name of the lexically-enclosing 11021function. This name is the unadorned name of the function. As an 11022extension, at file (or, in C++, namespace scope), @code{__func__} 11023evaluates to the empty string. 11024 11025@code{__FUNCTION__} is another name for @code{__func__}, provided for 11026backward compatibility with old versions of GCC. 11027 11028In C, @code{__PRETTY_FUNCTION__} is yet another name for 11029@code{__func__}, except that at file scope (or, in C++, namespace scope), 11030it evaluates to the string @code{"top level"}. In addition, in C++, 11031@code{__PRETTY_FUNCTION__} contains the signature of the function as 11032well as its bare name. For example, this program: 11033 11034@smallexample 11035extern "C" int printf (const char *, ...); 11036 11037class a @{ 11038 public: 11039 void sub (int i) 11040 @{ 11041 printf ("__FUNCTION__ = %s\n", __FUNCTION__); 11042 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); 11043 @} 11044@}; 11045 11046int 11047main (void) 11048@{ 11049 a ax; 11050 ax.sub (0); 11051 return 0; 11052@} 11053@end smallexample 11054 11055@noindent 11056gives this output: 11057 11058@smallexample 11059__FUNCTION__ = sub 11060__PRETTY_FUNCTION__ = void a::sub(int) 11061@end smallexample 11062 11063These identifiers are variables, not preprocessor macros, and may not 11064be used to initialize @code{char} arrays or be concatenated with string 11065literals. 11066 11067@node Return Address 11068@section Getting the Return or Frame Address of a Function 11069 11070These functions may be used to get information about the callers of a 11071function. 11072 11073@deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level}) 11074This function returns the return address of the current function, or of 11075one of its callers. The @var{level} argument is number of frames to 11076scan up the call stack. A value of @code{0} yields the return address 11077of the current function, a value of @code{1} yields the return address 11078of the caller of the current function, and so forth. When inlining 11079the expected behavior is that the function returns the address of 11080the function that is returned to. To work around this behavior use 11081the @code{noinline} function attribute. 11082 11083The @var{level} argument must be a constant integer. 11084 11085On some machines it may be impossible to determine the return address of 11086any function other than the current one; in such cases, or when the top 11087of the stack has been reached, this function returns an unspecified 11088value. In addition, @code{__builtin_frame_address} may be used 11089to determine if the top of the stack has been reached. 11090 11091Additional post-processing of the returned value may be needed, see 11092@code{__builtin_extract_return_addr}. 11093 11094The stored representation of the return address in memory may be different 11095from the address returned by @code{__builtin_return_address}. For example, 11096on AArch64 the stored address may be mangled with return address signing 11097whereas the address returned by @code{__builtin_return_address} is not. 11098 11099Calling this function with a nonzero argument can have unpredictable 11100effects, including crashing the calling program. As a result, calls 11101that are considered unsafe are diagnosed when the @option{-Wframe-address} 11102option is in effect. Such calls should only be made in debugging 11103situations. 11104 11105On targets where code addresses are representable as @code{void *}, 11106@smallexample 11107void *addr = __builtin_extract_return_addr (__builtin_return_address (0)); 11108@end smallexample 11109gives the code address where the current function would return. For example, 11110such an address may be used with @code{dladdr} or other interfaces that work 11111with code addresses. 11112@end deftypefn 11113 11114@deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr}) 11115The address as returned by @code{__builtin_return_address} may have to be fed 11116through this function to get the actual encoded address. For example, on the 1111731-bit S/390 platform the highest bit has to be masked out, or on SPARC 11118platforms an offset has to be added for the true next instruction to be 11119executed. 11120 11121If no fixup is needed, this function simply passes through @var{addr}. 11122@end deftypefn 11123 11124@deftypefn {Built-in Function} {void *} __builtin_frob_return_addr (void *@var{addr}) 11125This function does the reverse of @code{__builtin_extract_return_addr}. 11126@end deftypefn 11127 11128@deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level}) 11129This function is similar to @code{__builtin_return_address}, but it 11130returns the address of the function frame rather than the return address 11131of the function. Calling @code{__builtin_frame_address} with a value of 11132@code{0} yields the frame address of the current function, a value of 11133@code{1} yields the frame address of the caller of the current function, 11134and so forth. 11135 11136The frame is the area on the stack that holds local variables and saved 11137registers. The frame address is normally the address of the first word 11138pushed on to the stack by the function. However, the exact definition 11139depends upon the processor and the calling convention. If the processor 11140has a dedicated frame pointer register, and the function has a frame, 11141then @code{__builtin_frame_address} returns the value of the frame 11142pointer register. 11143 11144On some machines it may be impossible to determine the frame address of 11145any function other than the current one; in such cases, or when the top 11146of the stack has been reached, this function returns @code{0} if 11147the first frame pointer is properly initialized by the startup code. 11148 11149Calling this function with a nonzero argument can have unpredictable 11150effects, including crashing the calling program. As a result, calls 11151that are considered unsafe are diagnosed when the @option{-Wframe-address} 11152option is in effect. Such calls should only be made in debugging 11153situations. 11154@end deftypefn 11155 11156@node Vector Extensions 11157@section Using Vector Instructions through Built-in Functions 11158 11159On some targets, the instruction set contains SIMD vector instructions which 11160operate on multiple values contained in one large register at the same time. 11161For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used 11162this way. 11163 11164The first step in using these extensions is to provide the necessary data 11165types. This should be done using an appropriate @code{typedef}: 11166 11167@smallexample 11168typedef int v4si __attribute__ ((vector_size (16))); 11169@end smallexample 11170 11171@noindent 11172The @code{int} type specifies the @dfn{base type}, while the attribute specifies 11173the vector size for the variable, measured in bytes. For example, the 11174declaration above causes the compiler to set the mode for the @code{v4si} 11175type to be 16 bytes wide and divided into @code{int} sized units. For 11176a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the 11177corresponding mode of @code{foo} is @acronym{V4SI}. 11178 11179The @code{vector_size} attribute is only applicable to integral and 11180floating scalars, although arrays, pointers, and function return values 11181are allowed in conjunction with this construct. Only sizes that are 11182positive power-of-two multiples of the base type size are currently allowed. 11183 11184All the basic integer types can be used as base types, both as signed 11185and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, 11186@code{long long}. In addition, @code{float} and @code{double} can be 11187used to build floating-point vector types. 11188 11189Specifying a combination that is not valid for the current architecture 11190causes GCC to synthesize the instructions using a narrower mode. 11191For example, if you specify a variable of type @code{V4SI} and your 11192architecture does not allow for this specific SIMD type, GCC 11193produces code that uses 4 @code{SIs}. 11194 11195The types defined in this manner can be used with a subset of normal C 11196operations. Currently, GCC allows using the following operators 11197on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@. 11198 11199The operations behave like C++ @code{valarrays}. Addition is defined as 11200the addition of the corresponding elements of the operands. For 11201example, in the code below, each of the 4 elements in @var{a} is 11202added to the corresponding 4 elements in @var{b} and the resulting 11203vector is stored in @var{c}. 11204 11205@smallexample 11206typedef int v4si __attribute__ ((vector_size (16))); 11207 11208v4si a, b, c; 11209 11210c = a + b; 11211@end smallexample 11212 11213Subtraction, multiplication, division, and the logical operations 11214operate in a similar manner. Likewise, the result of using the unary 11215minus or complement operators on a vector type is a vector whose 11216elements are the negative or complemented values of the corresponding 11217elements in the operand. 11218 11219It is possible to use shifting operators @code{<<}, @code{>>} on 11220integer-type vectors. The operation is defined as following: @code{@{a0, 11221a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1, 11222@dots{}, an >> bn@}}@. Vector operands must have the same number of 11223elements. 11224 11225For convenience, it is allowed to use a binary vector operation 11226where one operand is a scalar. In that case the compiler transforms 11227the scalar operand into a vector where each element is the scalar from 11228the operation. The transformation happens only if the scalar could be 11229safely converted to the vector-element type. 11230Consider the following code. 11231 11232@smallexample 11233typedef int v4si __attribute__ ((vector_size (16))); 11234 11235v4si a, b, c; 11236long l; 11237 11238a = b + 1; /* a = b + @{1,1,1,1@}; */ 11239a = 2 * b; /* a = @{2,2,2,2@} * b; */ 11240 11241a = l + a; /* Error, cannot convert long to int. */ 11242@end smallexample 11243 11244Vectors can be subscripted as if the vector were an array with 11245the same number of elements and base type. Out of bound accesses 11246invoke undefined behavior at run time. Warnings for out of bound 11247accesses for vector subscription can be enabled with 11248@option{-Warray-bounds}. 11249 11250Vector comparison is supported with standard comparison 11251operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be 11252vector expressions of integer-type or real-type. Comparison between 11253integer-type vectors and real-type vectors are not supported. The 11254result of the comparison is a vector of the same width and number of 11255elements as the comparison operands with a signed integral element 11256type. 11257 11258Vectors are compared element-wise producing 0 when comparison is false 11259and -1 (constant of the appropriate type where all bits are set) 11260otherwise. Consider the following example. 11261 11262@smallexample 11263typedef int v4si __attribute__ ((vector_size (16))); 11264 11265v4si a = @{1,2,3,4@}; 11266v4si b = @{3,2,1,4@}; 11267v4si c; 11268 11269c = a > b; /* The result would be @{0, 0,-1, 0@} */ 11270c = a == b; /* The result would be @{0,-1, 0,-1@} */ 11271@end smallexample 11272 11273In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where 11274@code{b} and @code{c} are vectors of the same type and @code{a} is an 11275integer vector with the same number of elements of the same size as @code{b} 11276and @code{c}, computes all three arguments and creates a vector 11277@code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in 11278OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}. 11279As in the case of binary operations, this syntax is also accepted when 11280one of @code{b} or @code{c} is a scalar that is then transformed into a 11281vector. If both @code{b} and @code{c} are scalars and the type of 11282@code{true?b:c} has the same size as the element type of @code{a}, then 11283@code{b} and @code{c} are converted to a vector type whose elements have 11284this type and with the same number of elements as @code{a}. 11285 11286In C++, the logic operators @code{!, &&, ||} are available for vectors. 11287@code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to 11288@code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}. 11289For mixed operations between a scalar @code{s} and a vector @code{v}, 11290@code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is 11291short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}. 11292 11293@findex __builtin_shuffle 11294Vector shuffling is available using functions 11295@code{__builtin_shuffle (vec, mask)} and 11296@code{__builtin_shuffle (vec0, vec1, mask)}. 11297Both functions construct a permutation of elements from one or two 11298vectors and return a vector of the same type as the input vector(s). 11299The @var{mask} is an integral vector with the same width (@var{W}) 11300and element count (@var{N}) as the output vector. 11301 11302The elements of the input vectors are numbered in memory ordering of 11303@var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The 11304elements of @var{mask} are considered modulo @var{N} in the single-operand 11305case and modulo @math{2*@var{N}} in the two-operand case. 11306 11307Consider the following example, 11308 11309@smallexample 11310typedef int v4si __attribute__ ((vector_size (16))); 11311 11312v4si a = @{1,2,3,4@}; 11313v4si b = @{5,6,7,8@}; 11314v4si mask1 = @{0,1,1,3@}; 11315v4si mask2 = @{0,4,2,5@}; 11316v4si res; 11317 11318res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */ 11319res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */ 11320@end smallexample 11321 11322Note that @code{__builtin_shuffle} is intentionally semantically 11323compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions. 11324 11325You can declare variables and use them in function calls and returns, as 11326well as in assignments and some casts. You can specify a vector type as 11327a return type for a function. Vector types can also be used as function 11328arguments. It is possible to cast from one vector type to another, 11329provided they are of the same size (in fact, you can also cast vectors 11330to and from other datatypes of the same size). 11331 11332You cannot operate between vectors of different lengths or different 11333signedness without a cast. 11334 11335@findex __builtin_convertvector 11336Vector conversion is available using the 11337@code{__builtin_convertvector (vec, vectype)} 11338function. @var{vec} must be an expression with integral or floating 11339vector type and @var{vectype} an integral or floating vector type with the 11340same number of elements. The result has @var{vectype} type and value of 11341a C cast of every element of @var{vec} to the element type of @var{vectype}. 11342 11343Consider the following example, 11344@smallexample 11345typedef int v4si __attribute__ ((vector_size (16))); 11346typedef float v4sf __attribute__ ((vector_size (16))); 11347typedef double v4df __attribute__ ((vector_size (32))); 11348typedef unsigned long long v4di __attribute__ ((vector_size (32))); 11349 11350v4si a = @{1,-2,3,-4@}; 11351v4sf b = @{1.5f,-2.5f,3.f,7.f@}; 11352v4di c = @{1ULL,5ULL,0ULL,10ULL@}; 11353v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */ 11354/* Equivalent of: 11355 v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */ 11356v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */ 11357v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */ 11358v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */ 11359v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */ 11360@end smallexample 11361 11362@cindex vector types, using with x86 intrinsics 11363Sometimes it is desirable to write code using a mix of generic vector 11364operations (for clarity) and machine-specific vector intrinsics (to 11365access vector instructions that are not exposed via generic built-ins). 11366On x86, intrinsic functions for integer vectors typically use the same 11367vector type @code{__m128i} irrespective of how they interpret the vector, 11368making it necessary to cast their arguments and return values from/to 11369other vector types. In C, you can make use of a @code{union} type: 11370@c In C++ such type punning via a union is not allowed by the language 11371@smallexample 11372#include <immintrin.h> 11373 11374typedef unsigned char u8x16 __attribute__ ((vector_size (16))); 11375typedef unsigned int u32x4 __attribute__ ((vector_size (16))); 11376 11377typedef union @{ 11378 __m128i mm; 11379 u8x16 u8; 11380 u32x4 u32; 11381@} v128; 11382@end smallexample 11383 11384@noindent 11385for variables that can be used with both built-in operators and x86 11386intrinsics: 11387 11388@smallexample 11389v128 x, y = @{ 0 @}; 11390memcpy (&x, ptr, sizeof x); 11391y.u8 += 0x80; 11392x.mm = _mm_adds_epu8 (x.mm, y.mm); 11393x.u32 &= 0xffffff; 11394 11395/* Instead of a variable, a compound literal may be used to pass the 11396 return value of an intrinsic call to a function expecting the union: */ 11397v128 foo (v128); 11398x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@}); 11399@c This could be done implicitly with __attribute__((transparent_union)), 11400@c but GCC does not accept it for unions of vector types (PR 88955). 11401@end smallexample 11402 11403@node Offsetof 11404@section Support for @code{offsetof} 11405@findex __builtin_offsetof 11406 11407GCC implements for both C and C++ a syntactic extension to implement 11408the @code{offsetof} macro. 11409 11410@smallexample 11411primary: 11412 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" 11413 11414offsetof_member_designator: 11415 @code{identifier} 11416 | offsetof_member_designator "." @code{identifier} 11417 | offsetof_member_designator "[" @code{expr} "]" 11418@end smallexample 11419 11420This extension is sufficient such that 11421 11422@smallexample 11423#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) 11424@end smallexample 11425 11426@noindent 11427is a suitable definition of the @code{offsetof} macro. In C++, @var{type} 11428may be dependent. In either case, @var{member} may consist of a single 11429identifier, or a sequence of member accesses and array references. 11430 11431@node __sync Builtins 11432@section Legacy @code{__sync} Built-in Functions for Atomic Memory Access 11433 11434The following built-in functions 11435are intended to be compatible with those described 11436in the @cite{Intel Itanium Processor-specific Application Binary Interface}, 11437section 7.4. As such, they depart from normal GCC practice by not using 11438the @samp{__builtin_} prefix and also by being overloaded so that they 11439work on multiple types. 11440 11441The definition given in the Intel documentation allows only for the use of 11442the types @code{int}, @code{long}, @code{long long} or their unsigned 11443counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in 11444size other than the C type @code{_Bool} or the C++ type @code{bool}. 11445Operations on pointer arguments are performed as if the operands were 11446of the @code{uintptr_t} type. That is, they are not scaled by the size 11447of the type to which the pointer points. 11448 11449These functions are implemented in terms of the @samp{__atomic} 11450builtins (@pxref{__atomic Builtins}). They should not be used for new 11451code which should use the @samp{__atomic} builtins instead. 11452 11453Not all operations are supported by all target processors. If a particular 11454operation cannot be implemented on the target processor, a warning is 11455generated and a call to an external function is generated. The external 11456function carries the same name as the built-in version, 11457with an additional suffix 11458@samp{_@var{n}} where @var{n} is the size of the data type. 11459 11460@c ??? Should we have a mechanism to suppress this warning? This is almost 11461@c useful for implementing the operation under the control of an external 11462@c mutex. 11463 11464In most cases, these built-in functions are considered a @dfn{full barrier}. 11465That is, 11466no memory operand is moved across the operation, either forward or 11467backward. Further, instructions are issued as necessary to prevent the 11468processor from speculating loads across the operation and from queuing stores 11469after the operation. 11470 11471All of the routines are described in the Intel documentation to take 11472``an optional list of variables protected by the memory barrier''. It's 11473not clear what is meant by that; it could mean that @emph{only} the 11474listed variables are protected, or it could mean a list of additional 11475variables to be protected. The list is ignored by GCC which treats it as 11476empty. GCC interprets an empty list as meaning that all globally 11477accessible variables should be protected. 11478 11479@table @code 11480@item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...) 11481@itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...) 11482@itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...) 11483@itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...) 11484@itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...) 11485@itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...) 11486@findex __sync_fetch_and_add 11487@findex __sync_fetch_and_sub 11488@findex __sync_fetch_and_or 11489@findex __sync_fetch_and_and 11490@findex __sync_fetch_and_xor 11491@findex __sync_fetch_and_nand 11492These built-in functions perform the operation suggested by the name, and 11493returns the value that had previously been in memory. That is, operations 11494on integer operands have the following semantics. Operations on pointer 11495arguments are performed as if the operands were of the @code{uintptr_t} 11496type. That is, they are not scaled by the size of the type to which 11497the pointer points. 11498 11499@smallexample 11500@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} 11501@{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand 11502@end smallexample 11503 11504The object pointed to by the first argument must be of integer or pointer 11505type. It must not be a boolean type. 11506 11507@emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} 11508as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. 11509 11510@item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...) 11511@itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...) 11512@itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...) 11513@itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...) 11514@itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...) 11515@itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...) 11516@findex __sync_add_and_fetch 11517@findex __sync_sub_and_fetch 11518@findex __sync_or_and_fetch 11519@findex __sync_and_and_fetch 11520@findex __sync_xor_and_fetch 11521@findex __sync_nand_and_fetch 11522These built-in functions perform the operation suggested by the name, and 11523return the new value. That is, operations on integer operands have 11524the following semantics. Operations on pointer operands are performed as 11525if the operand's type were @code{uintptr_t}. 11526 11527@smallexample 11528@{ *ptr @var{op}= value; return *ptr; @} 11529@{ *ptr = ~(*ptr & value); return *ptr; @} // nand 11530@end smallexample 11531 11532The same constraints on arguments apply as for the corresponding 11533@code{__sync_op_and_fetch} built-in functions. 11534 11535@emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch} 11536as @code{*ptr = ~(*ptr & value)} instead of 11537@code{*ptr = ~*ptr & value}. 11538 11539@item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...) 11540@itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...) 11541@findex __sync_bool_compare_and_swap 11542@findex __sync_val_compare_and_swap 11543These built-in functions perform an atomic compare and swap. 11544That is, if the current 11545value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into 11546@code{*@var{ptr}}. 11547 11548The ``bool'' version returns @code{true} if the comparison is successful and 11549@var{newval} is written. The ``val'' version returns the contents 11550of @code{*@var{ptr}} before the operation. 11551 11552@item __sync_synchronize (...) 11553@findex __sync_synchronize 11554This built-in function issues a full memory barrier. 11555 11556@item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...) 11557@findex __sync_lock_test_and_set 11558This built-in function, as described by Intel, is not a traditional test-and-set 11559operation, but rather an atomic exchange operation. It writes @var{value} 11560into @code{*@var{ptr}}, and returns the previous contents of 11561@code{*@var{ptr}}. 11562 11563Many targets have only minimal support for such locks, and do not support 11564a full exchange operation. In this case, a target may support reduced 11565functionality here by which the @emph{only} valid value to store is the 11566immediate constant 1. The exact value actually stored in @code{*@var{ptr}} 11567is implementation defined. 11568 11569This built-in function is not a full barrier, 11570but rather an @dfn{acquire barrier}. 11571This means that references after the operation cannot move to (or be 11572speculated to) before the operation, but previous memory stores may not 11573be globally visible yet, and previous memory loads may not yet be 11574satisfied. 11575 11576@item void __sync_lock_release (@var{type} *ptr, ...) 11577@findex __sync_lock_release 11578This built-in function releases the lock acquired by 11579@code{__sync_lock_test_and_set}. 11580Normally this means writing the constant 0 to @code{*@var{ptr}}. 11581 11582This built-in function is not a full barrier, 11583but rather a @dfn{release barrier}. 11584This means that all previous memory stores are globally visible, and all 11585previous memory loads have been satisfied, but following memory reads 11586are not prevented from being speculated to before the barrier. 11587@end table 11588 11589@node __atomic Builtins 11590@section Built-in Functions for Memory Model Aware Atomic Operations 11591 11592The following built-in functions approximately match the requirements 11593for the C++11 memory model. They are all 11594identified by being prefixed with @samp{__atomic} and most are 11595overloaded so that they work with multiple types. 11596 11597These functions are intended to replace the legacy @samp{__sync} 11598builtins. The main difference is that the memory order that is requested 11599is a parameter to the functions. New code should always use the 11600@samp{__atomic} builtins rather than the @samp{__sync} builtins. 11601 11602Note that the @samp{__atomic} builtins assume that programs will 11603conform to the C++11 memory model. In particular, they assume 11604that programs are free of data races. See the C++11 standard for 11605detailed requirements. 11606 11607The @samp{__atomic} builtins can be used with any integral scalar or 11608pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral 11609types are also allowed if @samp{__int128} (@pxref{__int128}) is 11610supported by the architecture. 11611 11612The four non-arithmetic functions (load, store, exchange, and 11613compare_exchange) all have a generic version as well. This generic 11614version works on any data type. It uses the lock-free built-in function 11615if the specific data type size makes that possible; otherwise, an 11616external call is left to be resolved at run time. This external call is 11617the same format with the addition of a @samp{size_t} parameter inserted 11618as the first parameter indicating the size of the object being pointed to. 11619All objects must be the same size. 11620 11621There are 6 different memory orders that can be specified. These map 11622to the C++11 memory orders with the same names, see the C++11 standard 11623or the @uref{http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki 11624on atomic synchronization} for detailed definitions. Individual 11625targets may also support additional memory orders for use on specific 11626architectures. Refer to the target documentation for details of 11627these. 11628 11629An atomic operation can both constrain code motion and 11630be mapped to hardware instructions for synchronization between threads 11631(e.g., a fence). To which extent this happens is controlled by the 11632memory orders, which are listed here in approximately ascending order of 11633strength. The description of each memory order is only meant to roughly 11634illustrate the effects and is not a specification; see the C++11 11635memory model for precise semantics. 11636 11637@table @code 11638@item __ATOMIC_RELAXED 11639Implies no inter-thread ordering constraints. 11640@item __ATOMIC_CONSUME 11641This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE} 11642memory order because of a deficiency in C++11's semantics for 11643@code{memory_order_consume}. 11644@item __ATOMIC_ACQUIRE 11645Creates an inter-thread happens-before constraint from the release (or 11646stronger) semantic store to this acquire load. Can prevent hoisting 11647of code to before the operation. 11648@item __ATOMIC_RELEASE 11649Creates an inter-thread happens-before constraint to acquire (or stronger) 11650semantic loads that read from this release store. Can prevent sinking 11651of code to after the operation. 11652@item __ATOMIC_ACQ_REL 11653Combines the effects of both @code{__ATOMIC_ACQUIRE} and 11654@code{__ATOMIC_RELEASE}. 11655@item __ATOMIC_SEQ_CST 11656Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations. 11657@end table 11658 11659Note that in the C++11 memory model, @emph{fences} (e.g., 11660@samp{__atomic_thread_fence}) take effect in combination with other 11661atomic operations on specific memory locations (e.g., atomic loads); 11662operations on specific memory locations do not necessarily affect other 11663operations in the same way. 11664 11665Target architectures are encouraged to provide their own patterns for 11666each of the atomic built-in functions. If no target is provided, the original 11667non-memory model set of @samp{__sync} atomic built-in functions are 11668used, along with any required synchronization fences surrounding it in 11669order to achieve the proper behavior. Execution in this case is subject 11670to the same restrictions as those built-in functions. 11671 11672If there is no pattern or mechanism to provide a lock-free instruction 11673sequence, a call is made to an external routine with the same parameters 11674to be resolved at run time. 11675 11676When implementing patterns for these built-in functions, the memory order 11677parameter can be ignored as long as the pattern implements the most 11678restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory 11679orders execute correctly with this memory order but they may not execute as 11680efficiently as they could with a more appropriate implementation of the 11681relaxed requirements. 11682 11683Note that the C++11 standard allows for the memory order parameter to be 11684determined at run time rather than at compile time. These built-in 11685functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather 11686than invoke a runtime library call or inline a switch statement. This is 11687standard compliant, safe, and the simplest approach for now. 11688 11689The memory order parameter is a signed int, but only the lower 16 bits are 11690reserved for the memory order. The remainder of the signed int is reserved 11691for target use and should be 0. Use of the predefined atomic values 11692ensures proper usage. 11693 11694@deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memorder) 11695This built-in function implements an atomic load operation. It returns the 11696contents of @code{*@var{ptr}}. 11697 11698The valid memory order variants are 11699@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, 11700and @code{__ATOMIC_CONSUME}. 11701 11702@end deftypefn 11703 11704@deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder) 11705This is the generic version of an atomic load. It returns the 11706contents of @code{*@var{ptr}} in @code{*@var{ret}}. 11707 11708@end deftypefn 11709 11710@deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder) 11711This built-in function implements an atomic store operation. It writes 11712@code{@var{val}} into @code{*@var{ptr}}. 11713 11714The valid memory order variants are 11715@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}. 11716 11717@end deftypefn 11718 11719@deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder) 11720This is the generic version of an atomic store. It stores the value 11721of @code{*@var{val}} into @code{*@var{ptr}}. 11722 11723@end deftypefn 11724 11725@deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder) 11726This built-in function implements an atomic exchange operation. It writes 11727@var{val} into @code{*@var{ptr}}, and returns the previous contents of 11728@code{*@var{ptr}}. 11729 11730The valid memory order variants are 11731@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, 11732@code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}. 11733 11734@end deftypefn 11735 11736@deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder) 11737This is the generic version of an atomic exchange. It stores the 11738contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value 11739of @code{*@var{ptr}} is copied into @code{*@var{ret}}. 11740 11741@end deftypefn 11742 11743@deftypefn {Built-in Function} bool __atomic_compare_exchange_n (@var{type} *ptr, @var{type} *expected, @var{type} desired, bool weak, int success_memorder, int failure_memorder) 11744This built-in function implements an atomic compare and exchange operation. 11745This compares the contents of @code{*@var{ptr}} with the contents of 11746@code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write} 11747operation that writes @var{desired} into @code{*@var{ptr}}. If they are not 11748equal, the operation is a @emph{read} and the current contents of 11749@code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true} 11750for weak compare_exchange, which may fail spuriously, and @code{false} for 11751the strong variation, which never fails spuriously. Many targets 11752only offer the strong variation and ignore the parameter. When in doubt, use 11753the strong variation. 11754 11755If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned 11756and memory is affected according to the 11757memory order specified by @var{success_memorder}. There are no 11758restrictions on what memory order can be used here. 11759 11760Otherwise, @code{false} is returned and memory is affected according 11761to @var{failure_memorder}. This memory order cannot be 11762@code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a 11763stronger order than that specified by @var{success_memorder}. 11764 11765@end deftypefn 11766 11767@deftypefn {Built-in Function} bool __atomic_compare_exchange (@var{type} *ptr, @var{type} *expected, @var{type} *desired, bool weak, int success_memorder, int failure_memorder) 11768This built-in function implements the generic version of 11769@code{__atomic_compare_exchange}. The function is virtually identical to 11770@code{__atomic_compare_exchange_n}, except the desired value is also a 11771pointer. 11772 11773@end deftypefn 11774 11775@deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder) 11776@deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder) 11777@deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder) 11778@deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder) 11779@deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder) 11780@deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder) 11781These built-in functions perform the operation suggested by the name, and 11782return the result of the operation. Operations on pointer arguments are 11783performed as if the operands were of the @code{uintptr_t} type. That is, 11784they are not scaled by the size of the type to which the pointer points. 11785 11786@smallexample 11787@{ *ptr @var{op}= val; return *ptr; @} 11788@{ *ptr = ~(*ptr & val); return *ptr; @} // nand 11789@end smallexample 11790 11791The object pointed to by the first argument must be of integer or pointer 11792type. It must not be a boolean type. All memory orders are valid. 11793 11794@end deftypefn 11795 11796@deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder) 11797@deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder) 11798@deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder) 11799@deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder) 11800@deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder) 11801@deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder) 11802These built-in functions perform the operation suggested by the name, and 11803return the value that had previously been in @code{*@var{ptr}}. Operations 11804on pointer arguments are performed as if the operands were of 11805the @code{uintptr_t} type. That is, they are not scaled by the size of 11806the type to which the pointer points. 11807 11808@smallexample 11809@{ tmp = *ptr; *ptr @var{op}= val; return tmp; @} 11810@{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand 11811@end smallexample 11812 11813The same constraints on arguments apply as for the corresponding 11814@code{__atomic_op_fetch} built-in functions. All memory orders are valid. 11815 11816@end deftypefn 11817 11818@deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memorder) 11819 11820This built-in function performs an atomic test-and-set operation on 11821the byte at @code{*@var{ptr}}. The byte is set to some implementation 11822defined nonzero ``set'' value and the return value is @code{true} if and only 11823if the previous contents were ``set''. 11824It should be only used for operands of type @code{bool} or @code{char}. For 11825other types only part of the value may be set. 11826 11827All memory orders are valid. 11828 11829@end deftypefn 11830 11831@deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memorder) 11832 11833This built-in function performs an atomic clear operation on 11834@code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0. 11835It should be only used for operands of type @code{bool} or @code{char} and 11836in conjunction with @code{__atomic_test_and_set}. 11837For other types it may only clear partially. If the type is not @code{bool} 11838prefer using @code{__atomic_store}. 11839 11840The valid memory order variants are 11841@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and 11842@code{__ATOMIC_RELEASE}. 11843 11844@end deftypefn 11845 11846@deftypefn {Built-in Function} void __atomic_thread_fence (int memorder) 11847 11848This built-in function acts as a synchronization fence between threads 11849based on the specified memory order. 11850 11851All memory orders are valid. 11852 11853@end deftypefn 11854 11855@deftypefn {Built-in Function} void __atomic_signal_fence (int memorder) 11856 11857This built-in function acts as a synchronization fence between a thread 11858and signal handlers based in the same thread. 11859 11860All memory orders are valid. 11861 11862@end deftypefn 11863 11864@deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr) 11865 11866This built-in function returns @code{true} if objects of @var{size} bytes always 11867generate lock-free atomic instructions for the target architecture. 11868@var{size} must resolve to a compile-time constant and the result also 11869resolves to a compile-time constant. 11870 11871@var{ptr} is an optional pointer to the object that may be used to determine 11872alignment. A value of 0 indicates typical alignment should be used. The 11873compiler may also ignore this parameter. 11874 11875@smallexample 11876if (__atomic_always_lock_free (sizeof (long long), 0)) 11877@end smallexample 11878 11879@end deftypefn 11880 11881@deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr) 11882 11883This built-in function returns @code{true} if objects of @var{size} bytes always 11884generate lock-free atomic instructions for the target architecture. If 11885the built-in function is not known to be lock-free, a call is made to a 11886runtime routine named @code{__atomic_is_lock_free}. 11887 11888@var{ptr} is an optional pointer to the object that may be used to determine 11889alignment. A value of 0 indicates typical alignment should be used. The 11890compiler may also ignore this parameter. 11891@end deftypefn 11892 11893@node Integer Overflow Builtins 11894@section Built-in Functions to Perform Arithmetic with Overflow Checking 11895 11896The following built-in functions allow performing simple arithmetic operations 11897together with checking whether the operations overflowed. 11898 11899@deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 11900@deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res) 11901@deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res) 11902@deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res) 11903@deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res) 11904@deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 11905@deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) 11906 11907These built-in functions promote the first two operands into infinite precision signed 11908type and perform addition on those promoted operands. The result is then 11909cast to the type the third pointer argument points to and stored there. 11910If the stored result is equal to the infinite precision result, the built-in 11911functions return @code{false}, otherwise they return @code{true}. As the addition is 11912performed in infinite signed precision, these built-in functions have fully defined 11913behavior for all argument values. 11914 11915The first built-in function allows arbitrary integral types for operands and 11916the result type must be pointer to some integral type other than enumerated or 11917boolean type, the rest of the built-in functions have explicit integer types. 11918 11919The compiler will attempt to use hardware instructions to implement 11920these built-in functions where possible, like conditional jump on overflow 11921after addition, conditional jump on carry etc. 11922 11923@end deftypefn 11924 11925@deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 11926@deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res) 11927@deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res) 11928@deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res) 11929@deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res) 11930@deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 11931@deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) 11932 11933These built-in functions are similar to the add overflow checking built-in 11934functions above, except they perform subtraction, subtract the second argument 11935from the first one, instead of addition. 11936 11937@end deftypefn 11938 11939@deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 11940@deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res) 11941@deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res) 11942@deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res) 11943@deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res) 11944@deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 11945@deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) 11946 11947These built-in functions are similar to the add overflow checking built-in 11948functions above, except they perform multiplication, instead of addition. 11949 11950@end deftypefn 11951 11952The following built-in functions allow checking if simple arithmetic operation 11953would overflow. 11954 11955@deftypefn {Built-in Function} bool __builtin_add_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c) 11956@deftypefnx {Built-in Function} bool __builtin_sub_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c) 11957@deftypefnx {Built-in Function} bool __builtin_mul_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c) 11958 11959These built-in functions are similar to @code{__builtin_add_overflow}, 11960@code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that 11961they don't store the result of the arithmetic operation anywhere and the 11962last argument is not a pointer, but some expression with integral type other 11963than enumerated or boolean type. 11964 11965The built-in functions promote the first two operands into infinite precision signed type 11966and perform addition on those promoted operands. The result is then 11967cast to the type of the third argument. If the cast result is equal to the infinite 11968precision result, the built-in functions return @code{false}, otherwise they return @code{true}. 11969The value of the third argument is ignored, just the side effects in the third argument 11970are evaluated, and no integral argument promotions are performed on the last argument. 11971If the third argument is a bit-field, the type used for the result cast has the 11972precision and signedness of the given bit-field, rather than precision and signedness 11973of the underlying type. 11974 11975For example, the following macro can be used to portably check, at 11976compile-time, whether or not adding two constant integers will overflow, 11977and perform the addition only when it is known to be safe and not to trigger 11978a @option{-Woverflow} warning. 11979 11980@smallexample 11981#define INT_ADD_OVERFLOW_P(a, b) \ 11982 __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0) 11983 11984enum @{ 11985 A = INT_MAX, B = 3, 11986 C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B, 11987 D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0) 11988@}; 11989@end smallexample 11990 11991The compiler will attempt to use hardware instructions to implement 11992these built-in functions where possible, like conditional jump on overflow 11993after addition, conditional jump on carry etc. 11994 11995@end deftypefn 11996 11997@node x86 specific memory model extensions for transactional memory 11998@section x86-Specific Memory Model Extensions for Transactional Memory 11999 12000The x86 architecture supports additional memory ordering flags 12001to mark critical sections for hardware lock elision. 12002These must be specified in addition to an existing memory order to 12003atomic intrinsics. 12004 12005@table @code 12006@item __ATOMIC_HLE_ACQUIRE 12007Start lock elision on a lock variable. 12008Memory order must be @code{__ATOMIC_ACQUIRE} or stronger. 12009@item __ATOMIC_HLE_RELEASE 12010End lock elision on a lock variable. 12011Memory order must be @code{__ATOMIC_RELEASE} or stronger. 12012@end table 12013 12014When a lock acquire fails, it is required for good performance to abort 12015the transaction quickly. This can be done with a @code{_mm_pause}. 12016 12017@smallexample 12018#include <immintrin.h> // For _mm_pause 12019 12020int lockvar; 12021 12022/* Acquire lock with lock elision */ 12023while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE)) 12024 _mm_pause(); /* Abort failed transaction */ 12025... 12026/* Free lock with lock elision */ 12027__atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE); 12028@end smallexample 12029 12030@node Object Size Checking 12031@section Object Size Checking Built-in Functions 12032@findex __builtin_object_size 12033@findex __builtin___memcpy_chk 12034@findex __builtin___mempcpy_chk 12035@findex __builtin___memmove_chk 12036@findex __builtin___memset_chk 12037@findex __builtin___strcpy_chk 12038@findex __builtin___stpcpy_chk 12039@findex __builtin___strncpy_chk 12040@findex __builtin___strcat_chk 12041@findex __builtin___strncat_chk 12042@findex __builtin___sprintf_chk 12043@findex __builtin___snprintf_chk 12044@findex __builtin___vsprintf_chk 12045@findex __builtin___vsnprintf_chk 12046@findex __builtin___printf_chk 12047@findex __builtin___vprintf_chk 12048@findex __builtin___fprintf_chk 12049@findex __builtin___vfprintf_chk 12050 12051GCC implements a limited buffer overflow protection mechanism that can 12052prevent some buffer overflow attacks by determining the sizes of objects 12053into which data is about to be written and preventing the writes when 12054the size isn't sufficient. The built-in functions described below yield 12055the best results when used together and when optimization is enabled. 12056For example, to detect object sizes across function boundaries or to 12057follow pointer assignments through non-trivial control flow they rely 12058on various optimization passes enabled with @option{-O2}. However, to 12059a limited extent, they can be used without optimization as well. 12060 12061@deftypefn {Built-in Function} {size_t} __builtin_object_size (const void * @var{ptr}, int @var{type}) 12062is a built-in construct that returns a constant number of bytes from 12063@var{ptr} to the end of the object @var{ptr} pointer points to 12064(if known at compile time). To determine the sizes of dynamically allocated 12065objects the function relies on the allocation functions called to obtain 12066the storage to be declared with the @code{alloc_size} attribute (@pxref{Common 12067Function Attributes}). @code{__builtin_object_size} never evaluates 12068its arguments for side effects. If there are any side effects in them, it 12069returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 12070for @var{type} 2 or 3. If there are multiple objects @var{ptr} can 12071point to and all of them are known at compile time, the returned number 12072is the maximum of remaining byte counts in those objects if @var{type} & 2 is 120730 and minimum if nonzero. If it is not possible to determine which objects 12074@var{ptr} points to at compile time, @code{__builtin_object_size} should 12075return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 12076for @var{type} 2 or 3. 12077 12078@var{type} is an integer constant from 0 to 3. If the least significant 12079bit is clear, objects are whole variables, if it is set, a closest 12080surrounding subobject is considered the object a pointer points to. 12081The second bit determines if maximum or minimum of remaining bytes 12082is computed. 12083 12084@smallexample 12085struct V @{ char buf1[10]; int b; char buf2[10]; @} var; 12086char *p = &var.buf1[1], *q = &var.b; 12087 12088/* Here the object p points to is var. */ 12089assert (__builtin_object_size (p, 0) == sizeof (var) - 1); 12090/* The subobject p points to is var.buf1. */ 12091assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); 12092/* The object q points to is var. */ 12093assert (__builtin_object_size (q, 0) 12094 == (char *) (&var + 1) - (char *) &var.b); 12095/* The subobject q points to is var.b. */ 12096assert (__builtin_object_size (q, 1) == sizeof (var.b)); 12097@end smallexample 12098@end deftypefn 12099 12100There are built-in functions added for many common string operation 12101functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk} 12102built-in is provided. This built-in has an additional last argument, 12103which is the number of bytes remaining in the object the @var{dest} 12104argument points to or @code{(size_t) -1} if the size is not known. 12105 12106The built-in functions are optimized into the normal string functions 12107like @code{memcpy} if the last argument is @code{(size_t) -1} or if 12108it is known at compile time that the destination object will not 12109be overflowed. If the compiler can determine at compile time that the 12110object will always be overflowed, it issues a warning. 12111 12112The intended use can be e.g.@: 12113 12114@smallexample 12115#undef memcpy 12116#define bos0(dest) __builtin_object_size (dest, 0) 12117#define memcpy(dest, src, n) \ 12118 __builtin___memcpy_chk (dest, src, n, bos0 (dest)) 12119 12120char *volatile p; 12121char buf[10]; 12122/* It is unknown what object p points to, so this is optimized 12123 into plain memcpy - no checking is possible. */ 12124memcpy (p, "abcde", n); 12125/* Destination is known and length too. It is known at compile 12126 time there will be no overflow. */ 12127memcpy (&buf[5], "abcde", 5); 12128/* Destination is known, but the length is not known at compile time. 12129 This will result in __memcpy_chk call that can check for overflow 12130 at run time. */ 12131memcpy (&buf[5], "abcde", n); 12132/* Destination is known and it is known at compile time there will 12133 be overflow. There will be a warning and __memcpy_chk call that 12134 will abort the program at run time. */ 12135memcpy (&buf[6], "abcde", 5); 12136@end smallexample 12137 12138Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, 12139@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, 12140@code{strcat} and @code{strncat}. 12141 12142There are also checking built-in functions for formatted output functions. 12143@smallexample 12144int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...); 12145int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os, 12146 const char *fmt, ...); 12147int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt, 12148 va_list ap); 12149int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os, 12150 const char *fmt, va_list ap); 12151@end smallexample 12152 12153The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} 12154etc.@: functions and can contain implementation specific flags on what 12155additional security measures the checking function might take, such as 12156handling @code{%n} differently. 12157 12158The @var{os} argument is the object size @var{s} points to, like in the 12159other built-in functions. There is a small difference in the behavior 12160though, if @var{os} is @code{(size_t) -1}, the built-in functions are 12161optimized into the non-checking functions only if @var{flag} is 0, otherwise 12162the checking function is called with @var{os} argument set to 12163@code{(size_t) -1}. 12164 12165In addition to this, there are checking built-in functions 12166@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, 12167@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. 12168These have just one additional argument, @var{flag}, right before 12169format string @var{fmt}. If the compiler is able to optimize them to 12170@code{fputc} etc.@: functions, it does, otherwise the checking function 12171is called and the @var{flag} argument passed to it. 12172 12173@node Other Builtins 12174@section Other Built-in Functions Provided by GCC 12175@cindex built-in functions 12176@findex __builtin_alloca 12177@findex __builtin_alloca_with_align 12178@findex __builtin_alloca_with_align_and_max 12179@findex __builtin_call_with_static_chain 12180@findex __builtin_extend_pointer 12181@findex __builtin_fpclassify 12182@findex __builtin_has_attribute 12183@findex __builtin_isfinite 12184@findex __builtin_isnormal 12185@findex __builtin_isgreater 12186@findex __builtin_isgreaterequal 12187@findex __builtin_isinf_sign 12188@findex __builtin_isless 12189@findex __builtin_islessequal 12190@findex __builtin_islessgreater 12191@findex __builtin_isunordered 12192@findex __builtin_object_size 12193@findex __builtin_powi 12194@findex __builtin_powif 12195@findex __builtin_powil 12196@findex __builtin_speculation_safe_value 12197@findex _Exit 12198@findex _exit 12199@findex abort 12200@findex abs 12201@findex acos 12202@findex acosf 12203@findex acosh 12204@findex acoshf 12205@findex acoshl 12206@findex acosl 12207@findex alloca 12208@findex asin 12209@findex asinf 12210@findex asinh 12211@findex asinhf 12212@findex asinhl 12213@findex asinl 12214@findex atan 12215@findex atan2 12216@findex atan2f 12217@findex atan2l 12218@findex atanf 12219@findex atanh 12220@findex atanhf 12221@findex atanhl 12222@findex atanl 12223@findex bcmp 12224@findex bzero 12225@findex cabs 12226@findex cabsf 12227@findex cabsl 12228@findex cacos 12229@findex cacosf 12230@findex cacosh 12231@findex cacoshf 12232@findex cacoshl 12233@findex cacosl 12234@findex calloc 12235@findex carg 12236@findex cargf 12237@findex cargl 12238@findex casin 12239@findex casinf 12240@findex casinh 12241@findex casinhf 12242@findex casinhl 12243@findex casinl 12244@findex catan 12245@findex catanf 12246@findex catanh 12247@findex catanhf 12248@findex catanhl 12249@findex catanl 12250@findex cbrt 12251@findex cbrtf 12252@findex cbrtl 12253@findex ccos 12254@findex ccosf 12255@findex ccosh 12256@findex ccoshf 12257@findex ccoshl 12258@findex ccosl 12259@findex ceil 12260@findex ceilf 12261@findex ceill 12262@findex cexp 12263@findex cexpf 12264@findex cexpl 12265@findex cimag 12266@findex cimagf 12267@findex cimagl 12268@findex clog 12269@findex clogf 12270@findex clogl 12271@findex clog10 12272@findex clog10f 12273@findex clog10l 12274@findex conj 12275@findex conjf 12276@findex conjl 12277@findex copysign 12278@findex copysignf 12279@findex copysignl 12280@findex cos 12281@findex cosf 12282@findex cosh 12283@findex coshf 12284@findex coshl 12285@findex cosl 12286@findex cpow 12287@findex cpowf 12288@findex cpowl 12289@findex cproj 12290@findex cprojf 12291@findex cprojl 12292@findex creal 12293@findex crealf 12294@findex creall 12295@findex csin 12296@findex csinf 12297@findex csinh 12298@findex csinhf 12299@findex csinhl 12300@findex csinl 12301@findex csqrt 12302@findex csqrtf 12303@findex csqrtl 12304@findex ctan 12305@findex ctanf 12306@findex ctanh 12307@findex ctanhf 12308@findex ctanhl 12309@findex ctanl 12310@findex dcgettext 12311@findex dgettext 12312@findex drem 12313@findex dremf 12314@findex dreml 12315@findex erf 12316@findex erfc 12317@findex erfcf 12318@findex erfcl 12319@findex erff 12320@findex erfl 12321@findex exit 12322@findex exp 12323@findex exp10 12324@findex exp10f 12325@findex exp10l 12326@findex exp2 12327@findex exp2f 12328@findex exp2l 12329@findex expf 12330@findex expl 12331@findex expm1 12332@findex expm1f 12333@findex expm1l 12334@findex fabs 12335@findex fabsf 12336@findex fabsl 12337@findex fdim 12338@findex fdimf 12339@findex fdiml 12340@findex ffs 12341@findex floor 12342@findex floorf 12343@findex floorl 12344@findex fma 12345@findex fmaf 12346@findex fmal 12347@findex fmax 12348@findex fmaxf 12349@findex fmaxl 12350@findex fmin 12351@findex fminf 12352@findex fminl 12353@findex fmod 12354@findex fmodf 12355@findex fmodl 12356@findex fprintf 12357@findex fprintf_unlocked 12358@findex fputs 12359@findex fputs_unlocked 12360@findex free 12361@findex frexp 12362@findex frexpf 12363@findex frexpl 12364@findex fscanf 12365@findex gamma 12366@findex gammaf 12367@findex gammal 12368@findex gamma_r 12369@findex gammaf_r 12370@findex gammal_r 12371@findex gettext 12372@findex hypot 12373@findex hypotf 12374@findex hypotl 12375@findex ilogb 12376@findex ilogbf 12377@findex ilogbl 12378@findex imaxabs 12379@findex index 12380@findex isalnum 12381@findex isalpha 12382@findex isascii 12383@findex isblank 12384@findex iscntrl 12385@findex isdigit 12386@findex isgraph 12387@findex islower 12388@findex isprint 12389@findex ispunct 12390@findex isspace 12391@findex isupper 12392@findex iswalnum 12393@findex iswalpha 12394@findex iswblank 12395@findex iswcntrl 12396@findex iswdigit 12397@findex iswgraph 12398@findex iswlower 12399@findex iswprint 12400@findex iswpunct 12401@findex iswspace 12402@findex iswupper 12403@findex iswxdigit 12404@findex isxdigit 12405@findex j0 12406@findex j0f 12407@findex j0l 12408@findex j1 12409@findex j1f 12410@findex j1l 12411@findex jn 12412@findex jnf 12413@findex jnl 12414@findex labs 12415@findex ldexp 12416@findex ldexpf 12417@findex ldexpl 12418@findex lgamma 12419@findex lgammaf 12420@findex lgammal 12421@findex lgamma_r 12422@findex lgammaf_r 12423@findex lgammal_r 12424@findex llabs 12425@findex llrint 12426@findex llrintf 12427@findex llrintl 12428@findex llround 12429@findex llroundf 12430@findex llroundl 12431@findex log 12432@findex log10 12433@findex log10f 12434@findex log10l 12435@findex log1p 12436@findex log1pf 12437@findex log1pl 12438@findex log2 12439@findex log2f 12440@findex log2l 12441@findex logb 12442@findex logbf 12443@findex logbl 12444@findex logf 12445@findex logl 12446@findex lrint 12447@findex lrintf 12448@findex lrintl 12449@findex lround 12450@findex lroundf 12451@findex lroundl 12452@findex malloc 12453@findex memchr 12454@findex memcmp 12455@findex memcpy 12456@findex mempcpy 12457@findex memset 12458@findex modf 12459@findex modff 12460@findex modfl 12461@findex nearbyint 12462@findex nearbyintf 12463@findex nearbyintl 12464@findex nextafter 12465@findex nextafterf 12466@findex nextafterl 12467@findex nexttoward 12468@findex nexttowardf 12469@findex nexttowardl 12470@findex pow 12471@findex pow10 12472@findex pow10f 12473@findex pow10l 12474@findex powf 12475@findex powl 12476@findex printf 12477@findex printf_unlocked 12478@findex putchar 12479@findex puts 12480@findex realloc 12481@findex remainder 12482@findex remainderf 12483@findex remainderl 12484@findex remquo 12485@findex remquof 12486@findex remquol 12487@findex rindex 12488@findex rint 12489@findex rintf 12490@findex rintl 12491@findex round 12492@findex roundf 12493@findex roundl 12494@findex scalb 12495@findex scalbf 12496@findex scalbl 12497@findex scalbln 12498@findex scalblnf 12499@findex scalblnf 12500@findex scalbn 12501@findex scalbnf 12502@findex scanfnl 12503@findex signbit 12504@findex signbitf 12505@findex signbitl 12506@findex signbitd32 12507@findex signbitd64 12508@findex signbitd128 12509@findex significand 12510@findex significandf 12511@findex significandl 12512@findex sin 12513@findex sincos 12514@findex sincosf 12515@findex sincosl 12516@findex sinf 12517@findex sinh 12518@findex sinhf 12519@findex sinhl 12520@findex sinl 12521@findex snprintf 12522@findex sprintf 12523@findex sqrt 12524@findex sqrtf 12525@findex sqrtl 12526@findex sscanf 12527@findex stpcpy 12528@findex stpncpy 12529@findex strcasecmp 12530@findex strcat 12531@findex strchr 12532@findex strcmp 12533@findex strcpy 12534@findex strcspn 12535@findex strdup 12536@findex strfmon 12537@findex strftime 12538@findex strlen 12539@findex strncasecmp 12540@findex strncat 12541@findex strncmp 12542@findex strncpy 12543@findex strndup 12544@findex strnlen 12545@findex strpbrk 12546@findex strrchr 12547@findex strspn 12548@findex strstr 12549@findex tan 12550@findex tanf 12551@findex tanh 12552@findex tanhf 12553@findex tanhl 12554@findex tanl 12555@findex tgamma 12556@findex tgammaf 12557@findex tgammal 12558@findex toascii 12559@findex tolower 12560@findex toupper 12561@findex towlower 12562@findex towupper 12563@findex trunc 12564@findex truncf 12565@findex truncl 12566@findex vfprintf 12567@findex vfscanf 12568@findex vprintf 12569@findex vscanf 12570@findex vsnprintf 12571@findex vsprintf 12572@findex vsscanf 12573@findex y0 12574@findex y0f 12575@findex y0l 12576@findex y1 12577@findex y1f 12578@findex y1l 12579@findex yn 12580@findex ynf 12581@findex ynl 12582 12583GCC provides a large number of built-in functions other than the ones 12584mentioned above. Some of these are for internal use in the processing 12585of exceptions or variable-length argument lists and are not 12586documented here because they may change from time to time; we do not 12587recommend general use of these functions. 12588 12589The remaining functions are provided for optimization purposes. 12590 12591With the exception of built-ins that have library equivalents such as 12592the standard C library functions discussed below, or that expand to 12593library calls, GCC built-in functions are always expanded inline and 12594thus do not have corresponding entry points and their address cannot 12595be obtained. Attempting to use them in an expression other than 12596a function call results in a compile-time error. 12597 12598@opindex fno-builtin 12599GCC includes built-in versions of many of the functions in the standard 12600C library. These functions come in two forms: one whose names start with 12601the @code{__builtin_} prefix, and the other without. Both forms have the 12602same type (including prototype), the same address (when their address is 12603taken), and the same meaning as the C library functions even if you specify 12604the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these 12605functions are only optimized in certain cases; if they are not optimized in 12606a particular case, a call to the library function is emitted. 12607 12608@opindex ansi 12609@opindex std 12610Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, 12611@option{-std=c99} or @option{-std=c11}), the functions 12612@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, 12613@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, 12614@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, 12615@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, 12616@code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma}, 12617@code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext}, 12618@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, 12619@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, 12620@code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy}, 12621@code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, 12622@code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roudnevenl}, 12623@code{scalbf}, @code{scalbl}, @code{scalb}, 12624@code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, 12625@code{signbitd64}, @code{signbitd128}, @code{significandf}, 12626@code{significandl}, @code{significand}, @code{sincosf}, 12627@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, 12628@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, 12629@code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l}, 12630@code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and 12631@code{yn} 12632may be handled as built-in functions. 12633All these functions have corresponding versions 12634prefixed with @code{__builtin_}, which may be used even in strict C90 12635mode. 12636 12637The ISO C99 functions 12638@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, 12639@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, 12640@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, 12641@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, 12642@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, 12643@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, 12644@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, 12645@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, 12646@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, 12647@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, 12648@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, 12649@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, 12650@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, 12651@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, 12652@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, 12653@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, 12654@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, 12655@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, 12656@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, 12657@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, 12658@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, 12659@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, 12660@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, 12661@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, 12662@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, 12663@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, 12664@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, 12665@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, 12666@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, 12667@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, 12668@code{nextafterf}, @code{nextafterl}, @code{nextafter}, 12669@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, 12670@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, 12671@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, 12672@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, 12673@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, 12674@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, 12675@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, 12676@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} 12677are handled as built-in functions 12678except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). 12679 12680There are also built-in versions of the ISO C99 functions 12681@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, 12682@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, 12683@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, 12684@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, 12685@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, 12686@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, 12687@code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf}, 12688@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, 12689@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} 12690that are recognized in any mode since ISO C90 reserves these names for 12691the purpose to which ISO C99 puts them. All these functions have 12692corresponding versions prefixed with @code{__builtin_}. 12693 12694There are also built-in functions @code{__builtin_fabsf@var{n}}, 12695@code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and 12696@code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3 12697functions @code{fabsf@var{n}}, @code{fabsf@var{n}x}, 12698@code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported 12699types @code{_Float@var{n}} and @code{_Float@var{n}x}. 12700 12701There are also GNU extension functions @code{clog10}, @code{clog10f} and 12702@code{clog10l} which names are reserved by ISO C99 for future use. 12703All these functions have versions prefixed with @code{__builtin_}. 12704 12705The ISO C94 functions 12706@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, 12707@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, 12708@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and 12709@code{towupper} 12710are handled as built-in functions 12711except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). 12712 12713The ISO C90 functions 12714@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, 12715@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, 12716@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, 12717@code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf}, 12718@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, 12719@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, 12720@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, 12721@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, 12722@code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy}, 12723@code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar}, 12724@code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin}, 12725@code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat}, 12726@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, 12727@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, 12728@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, 12729@code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf} 12730are all recognized as built-in functions unless 12731@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} 12732is specified for an individual function). All of these functions have 12733corresponding versions prefixed with @code{__builtin_}. 12734 12735GCC provides built-in versions of the ISO C99 floating-point comparison 12736macros that avoid raising exceptions for unordered operands. They have 12737the same names as the standard macros ( @code{isgreater}, 12738@code{isgreaterequal}, @code{isless}, @code{islessequal}, 12739@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} 12740prefixed. We intend for a library implementor to be able to simply 12741@code{#define} each standard macro to its built-in equivalent. 12742In the same fashion, GCC provides @code{fpclassify}, @code{isfinite}, 12743@code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with 12744@code{__builtin_} prefixed. The @code{isinf} and @code{isnan} 12745built-in functions appear both with and without the @code{__builtin_} prefix. 12746 12747@deftypefn {Built-in Function} void *__builtin_alloca (size_t size) 12748The @code{__builtin_alloca} function must be called at block scope. 12749The function allocates an object @var{size} bytes large on the stack 12750of the calling function. The object is aligned on the default stack 12751alignment boundary for the target determined by the 12752@code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca} 12753function returns a pointer to the first byte of the allocated object. 12754The lifetime of the allocated object ends just before the calling 12755function returns to its caller. This is so even when 12756@code{__builtin_alloca} is called within a nested block. 12757 12758For example, the following function allocates eight objects of @code{n} 12759bytes each on the stack, storing a pointer to each in consecutive elements 12760of the array @code{a}. It then passes the array to function @code{g} 12761which can safely use the storage pointed to by each of the array elements. 12762 12763@smallexample 12764void f (unsigned n) 12765@{ 12766 void *a [8]; 12767 for (int i = 0; i != 8; ++i) 12768 a [i] = __builtin_alloca (n); 12769 12770 g (a, n); // @r{safe} 12771@} 12772@end smallexample 12773 12774Since the @code{__builtin_alloca} function doesn't validate its argument 12775it is the responsibility of its caller to make sure the argument doesn't 12776cause it to exceed the stack size limit. 12777The @code{__builtin_alloca} function is provided to make it possible to 12778allocate on the stack arrays of bytes with an upper bound that may be 12779computed at run time. Since C99 Variable Length Arrays offer 12780similar functionality under a portable, more convenient, and safer 12781interface they are recommended instead, in both C99 and C++ programs 12782where GCC provides them as an extension. 12783@xref{Variable Length}, for details. 12784 12785@end deftypefn 12786 12787@deftypefn {Built-in Function} void *__builtin_alloca_with_align (size_t size, size_t alignment) 12788The @code{__builtin_alloca_with_align} function must be called at block 12789scope. The function allocates an object @var{size} bytes large on 12790the stack of the calling function. The allocated object is aligned on 12791the boundary specified by the argument @var{alignment} whose unit is given 12792in bits (not bytes). The @var{size} argument must be positive and not 12793exceed the stack size limit. The @var{alignment} argument must be a constant 12794integer expression that evaluates to a power of 2 greater than or equal to 12795@code{CHAR_BIT} and less than some unspecified maximum. Invocations 12796with other values are rejected with an error indicating the valid bounds. 12797The function returns a pointer to the first byte of the allocated object. 12798The lifetime of the allocated object ends at the end of the block in which 12799the function was called. The allocated storage is released no later than 12800just before the calling function returns to its caller, but may be released 12801at the end of the block in which the function was called. 12802 12803For example, in the following function the call to @code{g} is unsafe 12804because when @code{overalign} is non-zero, the space allocated by 12805@code{__builtin_alloca_with_align} may have been released at the end 12806of the @code{if} statement in which it was called. 12807 12808@smallexample 12809void f (unsigned n, bool overalign) 12810@{ 12811 void *p; 12812 if (overalign) 12813 p = __builtin_alloca_with_align (n, 64 /* bits */); 12814 else 12815 p = __builtin_alloc (n); 12816 12817 g (p, n); // @r{unsafe} 12818@} 12819@end smallexample 12820 12821Since the @code{__builtin_alloca_with_align} function doesn't validate its 12822@var{size} argument it is the responsibility of its caller to make sure 12823the argument doesn't cause it to exceed the stack size limit. 12824The @code{__builtin_alloca_with_align} function is provided to make 12825it possible to allocate on the stack overaligned arrays of bytes with 12826an upper bound that may be computed at run time. Since C99 12827Variable Length Arrays offer the same functionality under 12828a portable, more convenient, and safer interface they are recommended 12829instead, in both C99 and C++ programs where GCC provides them as 12830an extension. @xref{Variable Length}, for details. 12831 12832@end deftypefn 12833 12834@deftypefn {Built-in Function} void *__builtin_alloca_with_align_and_max (size_t size, size_t alignment, size_t max_size) 12835Similar to @code{__builtin_alloca_with_align} but takes an extra argument 12836specifying an upper bound for @var{size} in case its value cannot be computed 12837at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage} 12838and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer 12839expression, it has no effect on code generation and no attempt is made to 12840check its compatibility with @var{size}. 12841 12842@end deftypefn 12843 12844@deftypefn {Built-in Function} bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute}) 12845The @code{__builtin_has_attribute} function evaluates to an integer constant 12846expression equal to @code{true} if the symbol or type referenced by 12847the @var{type-or-expression} argument has been declared with 12848the @var{attribute} referenced by the second argument. For 12849an @var{type-or-expression} argument that does not reference a symbol, 12850since attributes do not apply to expressions the built-in consider 12851the type of the argument. Neither argument is evaluated. 12852The @var{type-or-expression} argument is subject to the same 12853restrictions as the argument to @code{typeof} (@pxref{Typeof}). The 12854@var{attribute} argument is an attribute name optionally followed by 12855a comma-separated list of arguments enclosed in parentheses. Both forms 12856of attribute names---with and without double leading and trailing 12857underscores---are recognized. @xref{Attribute Syntax}, for details. 12858When no attribute arguments are specified for an attribute that expects 12859one or more arguments the function returns @code{true} if 12860@var{type-or-expression} has been declared with the attribute regardless 12861of the attribute argument values. Arguments provided for an attribute 12862that expects some are validated and matched up to the provided number. 12863The function returns @code{true} if all provided arguments match. For 12864example, the first call to the function below evaluates to @code{true} 12865because @code{x} is declared with the @code{aligned} attribute but 12866the second call evaluates to @code{false} because @code{x} is declared 12867@code{aligned (8)} and not @code{aligned (4)}. 12868 12869@smallexample 12870__attribute__ ((aligned (8))) int x; 12871_Static_assert (__builtin_has_attribute (x, aligned), "aligned"); 12872_Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)"); 12873@end smallexample 12874 12875Due to a limitation the @code{__builtin_has_attribute} function returns 12876@code{false} for the @code{mode} attribute even if the type or variable 12877referenced by the @var{type-or-expression} argument was declared with one. 12878The function is also not supported with labels, and in C with enumerators. 12879 12880Note that unlike the @code{__has_attribute} preprocessor operator which 12881is suitable for use in @code{#if} preprocessing directives 12882@code{__builtin_has_attribute} is an intrinsic function that is not 12883recognized in such contexts. 12884 12885@end deftypefn 12886 12887@deftypefn {Built-in Function} @var{type} __builtin_speculation_safe_value (@var{type} val, @var{type} failval) 12888 12889This built-in function can be used to help mitigate against unsafe 12890speculative execution. @var{type} may be any integral type or any 12891pointer type. 12892 12893@enumerate 12894@item 12895If the CPU is not speculatively executing the code, then @var{val} 12896is returned. 12897@item 12898If the CPU is executing speculatively then either: 12899@itemize 12900@item 12901The function may cause execution to pause until it is known that the 12902code is no-longer being executed speculatively (in which case 12903@var{val} can be returned, as above); or 12904@item 12905The function may use target-dependent speculation tracking state to cause 12906@var{failval} to be returned when it is known that speculative 12907execution has incorrectly predicted a conditional branch operation. 12908@end itemize 12909@end enumerate 12910 12911The second argument, @var{failval}, is optional and defaults to zero 12912if omitted. 12913 12914GCC defines the preprocessor macro 12915@code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been 12916updated to support this builtin. 12917 12918The built-in function can be used where a variable appears to be used in a 12919safe way, but the CPU, due to speculative execution may temporarily ignore 12920the bounds checks. Consider, for example, the following function: 12921 12922@smallexample 12923int array[500]; 12924int f (unsigned untrusted_index) 12925@{ 12926 if (untrusted_index < 500) 12927 return array[untrusted_index]; 12928 return 0; 12929@} 12930@end smallexample 12931 12932If the function is called repeatedly with @code{untrusted_index} less 12933than the limit of 500, then a branch predictor will learn that the 12934block of code that returns a value stored in @code{array} will be 12935executed. If the function is subsequently called with an 12936out-of-range value it will still try to execute that block of code 12937first until the CPU determines that the prediction was incorrect 12938(the CPU will unwind any incorrect operations at that point). 12939However, depending on how the result of the function is used, it might be 12940possible to leave traces in the cache that can reveal what was stored 12941at the out-of-bounds location. The built-in function can be used to 12942provide some protection against leaking data in this way by changing 12943the code to: 12944 12945@smallexample 12946int array[500]; 12947int f (unsigned untrusted_index) 12948@{ 12949 if (untrusted_index < 500) 12950 return array[__builtin_speculation_safe_value (untrusted_index)]; 12951 return 0; 12952@} 12953@end smallexample 12954 12955The built-in function will either cause execution to stall until the 12956conditional branch has been fully resolved, or it may permit 12957speculative execution to continue, but using 0 instead of 12958@code{untrusted_value} if that exceeds the limit. 12959 12960If accessing any memory location is potentially unsafe when speculative 12961execution is incorrect, then the code can be rewritten as 12962 12963@smallexample 12964int array[500]; 12965int f (unsigned untrusted_index) 12966@{ 12967 if (untrusted_index < 500) 12968 return *__builtin_speculation_safe_value (&array[untrusted_index], NULL); 12969 return 0; 12970@} 12971@end smallexample 12972 12973which will cause a @code{NULL} pointer to be used for the unsafe case. 12974 12975@end deftypefn 12976 12977@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2}) 12978 12979You can use the built-in function @code{__builtin_types_compatible_p} to 12980determine whether two types are the same. 12981 12982This built-in function returns 1 if the unqualified versions of the 12983types @var{type1} and @var{type2} (which are types, not expressions) are 12984compatible, 0 otherwise. The result of this built-in function can be 12985used in integer constant expressions. 12986 12987This built-in function ignores top level qualifiers (e.g., @code{const}, 12988@code{volatile}). For example, @code{int} is equivalent to @code{const 12989int}. 12990 12991The type @code{int[]} and @code{int[5]} are compatible. On the other 12992hand, @code{int} and @code{char *} are not compatible, even if the size 12993of their types, on the particular architecture are the same. Also, the 12994amount of pointer indirection is taken into account when determining 12995similarity. Consequently, @code{short *} is not similar to 12996@code{short **}. Furthermore, two types that are typedefed are 12997considered compatible if their underlying types are compatible. 12998 12999An @code{enum} type is not considered to be compatible with another 13000@code{enum} type even if both are compatible with the same integer 13001type; this is what the C standard specifies. 13002For example, @code{enum @{foo, bar@}} is not similar to 13003@code{enum @{hot, dog@}}. 13004 13005You typically use this function in code whose execution varies 13006depending on the arguments' types. For example: 13007 13008@smallexample 13009#define foo(x) \ 13010 (@{ \ 13011 typeof (x) tmp = (x); \ 13012 if (__builtin_types_compatible_p (typeof (x), long double)) \ 13013 tmp = foo_long_double (tmp); \ 13014 else if (__builtin_types_compatible_p (typeof (x), double)) \ 13015 tmp = foo_double (tmp); \ 13016 else if (__builtin_types_compatible_p (typeof (x), float)) \ 13017 tmp = foo_float (tmp); \ 13018 else \ 13019 abort (); \ 13020 tmp; \ 13021 @}) 13022@end smallexample 13023 13024@emph{Note:} This construct is only available for C@. 13025 13026@end deftypefn 13027 13028@deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp}) 13029 13030The @var{call_exp} expression must be a function call, and the 13031@var{pointer_exp} expression must be a pointer. The @var{pointer_exp} 13032is passed to the function call in the target's static chain location. 13033The result of builtin is the result of the function call. 13034 13035@emph{Note:} This builtin is only available for C@. 13036This builtin can be used to call Go closures from C. 13037 13038@end deftypefn 13039 13040@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2}) 13041 13042You can use the built-in function @code{__builtin_choose_expr} to 13043evaluate code depending on the value of a constant expression. This 13044built-in function returns @var{exp1} if @var{const_exp}, which is an 13045integer constant expression, is nonzero. Otherwise it returns @var{exp2}. 13046 13047This built-in function is analogous to the @samp{? :} operator in C, 13048except that the expression returned has its type unaltered by promotion 13049rules. Also, the built-in function does not evaluate the expression 13050that is not chosen. For example, if @var{const_exp} evaluates to @code{true}, 13051@var{exp2} is not evaluated even if it has side effects. 13052 13053This built-in function can return an lvalue if the chosen argument is an 13054lvalue. 13055 13056If @var{exp1} is returned, the return type is the same as @var{exp1}'s 13057type. Similarly, if @var{exp2} is returned, its return type is the same 13058as @var{exp2}. 13059 13060Example: 13061 13062@smallexample 13063#define foo(x) \ 13064 __builtin_choose_expr ( \ 13065 __builtin_types_compatible_p (typeof (x), double), \ 13066 foo_double (x), \ 13067 __builtin_choose_expr ( \ 13068 __builtin_types_compatible_p (typeof (x), float), \ 13069 foo_float (x), \ 13070 /* @r{The void expression results in a compile-time error} \ 13071 @r{when assigning the result to something.} */ \ 13072 (void)0)) 13073@end smallexample 13074 13075@emph{Note:} This construct is only available for C@. Furthermore, the 13076unused expression (@var{exp1} or @var{exp2} depending on the value of 13077@var{const_exp}) may still generate syntax errors. This may change in 13078future revisions. 13079 13080@end deftypefn 13081 13082@deftypefn {Built-in Function} @var{type} __builtin_tgmath (@var{functions}, @var{arguments}) 13083 13084The built-in function @code{__builtin_tgmath}, available only for C 13085and Objective-C, calls a function determined according to the rules of 13086@code{<tgmath.h>} macros. It is intended to be used in 13087implementations of that header, so that expansions of macros from that 13088header only expand each of their arguments once, to avoid problems 13089when calls to such macros are nested inside the arguments of other 13090calls to such macros; in addition, it results in better diagnostics 13091for invalid calls to @code{<tgmath.h>} macros than implementations 13092using other GNU C language features. For example, the @code{pow} 13093type-generic macro might be defined as: 13094 13095@smallexample 13096#define pow(a, b) __builtin_tgmath (powf, pow, powl, \ 13097 cpowf, cpow, cpowl, a, b) 13098@end smallexample 13099 13100The arguments to @code{__builtin_tgmath} are at least two pointers to 13101functions, followed by the arguments to the type-generic macro (which 13102will be passed as arguments to the selected function). All the 13103pointers to functions must be pointers to prototyped functions, none 13104of which may have variable arguments, and all of which must have the 13105same number of parameters; the number of parameters of the first 13106function determines how many arguments to @code{__builtin_tgmath} are 13107interpreted as function pointers, and how many as the arguments to the 13108called function. 13109 13110The types of the specified functions must all be different, but 13111related to each other in the same way as a set of functions that may 13112be selected between by a macro in @code{<tgmath.h>}. This means that 13113the functions are parameterized by a floating-point type @var{t}, 13114different for each such function. The function return types may all 13115be the same type, or they may be @var{t} for each function, or they 13116may be the real type corresponding to @var{t} for each function (if 13117some of the types @var{t} are complex). Likewise, for each parameter 13118position, the type of the parameter in that position may always be the 13119same type, or may be @var{t} for each function (this case must apply 13120for at least one parameter position), or may be the real type 13121corresponding to @var{t} for each function. 13122 13123The standard rules for @code{<tgmath.h>} macros are used to find a 13124common type @var{u} from the types of the arguments for parameters 13125whose types vary between the functions; complex integer types (a GNU 13126extension) are treated like @code{_Complex double} for this purpose 13127(or @code{_Complex _Float64} if all the function return types are the 13128same @code{_Float@var{n}} or @code{_Float@var{n}x} type). 13129If the function return types vary, or are all the same integer type, 13130the function called is the one for which @var{t} is @var{u}, and it is 13131an error if there is no such function. If the function return types 13132are all the same floating-point type, the type-generic macro is taken 13133to be one of those from TS 18661 that rounds the result to a narrower 13134type; if there is a function for which @var{t} is @var{u}, it is 13135called, and otherwise the first function, if any, for which @var{t} 13136has at least the range and precision of @var{u} is called, and it is 13137an error if there is no such function. 13138 13139@end deftypefn 13140 13141@deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag}) 13142 13143The built-in function @code{__builtin_complex} is provided for use in 13144implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and 13145@code{CMPLXL}. @var{real} and @var{imag} must have the same type, a 13146real binary floating-point type, and the result has the corresponding 13147complex type with real and imaginary parts @var{real} and @var{imag}. 13148Unlike @samp{@var{real} + I * @var{imag}}, this works even when 13149infinities, NaNs and negative zeros are involved. 13150 13151@end deftypefn 13152 13153@deftypefn {Built-in Function} int __builtin_constant_p (@var{exp}) 13154You can use the built-in function @code{__builtin_constant_p} to 13155determine if a value is known to be constant at compile time and hence 13156that GCC can perform constant-folding on expressions involving that 13157value. The argument of the function is the value to test. The function 13158returns the integer 1 if the argument is known to be a compile-time 13159constant and 0 if it is not known to be a compile-time constant. A 13160return of 0 does not indicate that the value is @emph{not} a constant, 13161but merely that GCC cannot prove it is a constant with the specified 13162value of the @option{-O} option. 13163 13164You typically use this function in an embedded application where 13165memory is a critical resource. If you have some complex calculation, 13166you may want it to be folded if it involves constants, but need to call 13167a function if it does not. For example: 13168 13169@smallexample 13170#define Scale_Value(X) \ 13171 (__builtin_constant_p (X) \ 13172 ? ((X) * SCALE + OFFSET) : Scale (X)) 13173@end smallexample 13174 13175You may use this built-in function in either a macro or an inline 13176function. However, if you use it in an inlined function and pass an 13177argument of the function as the argument to the built-in, GCC 13178never returns 1 when you call the inline function with a string constant 13179or compound literal (@pxref{Compound Literals}) and does not return 1 13180when you pass a constant numeric value to the inline function unless you 13181specify the @option{-O} option. 13182 13183You may also use @code{__builtin_constant_p} in initializers for static 13184data. For instance, you can write 13185 13186@smallexample 13187static const int table[] = @{ 13188 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, 13189 /* @r{@dots{}} */ 13190@}; 13191@end smallexample 13192 13193@noindent 13194This is an acceptable initializer even if @var{EXPRESSION} is not a 13195constant expression, including the case where 13196@code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be 13197folded to a constant but @var{EXPRESSION} contains operands that are 13198not otherwise permitted in a static initializer (for example, 13199@code{0 && foo ()}). GCC must be more conservative about evaluating the 13200built-in in this case, because it has no opportunity to perform 13201optimization. 13202@end deftypefn 13203 13204@deftypefn {Built-in Function} bool __builtin_is_constant_evaluated (void) 13205The @code{__builtin_is_constant_evaluated} function is available only 13206in C++. The built-in is intended to be used by implementations of 13207the @code{std::is_constant_evaluated} C++ function. Programs should make 13208use of the latter function rather than invoking the built-in directly. 13209 13210The main use case of the built-in is to determine whether a @code{constexpr} 13211function is being called in a @code{constexpr} context. A call to 13212the function evaluates to a core constant expression with the value 13213@code{true} if and only if it occurs within the evaluation of an expression 13214or conversion that is manifestly constant-evaluated as defined in the C++ 13215standard. Manifestly constant-evaluated contexts include constant-expressions, 13216the conditions of @code{constexpr if} statements, constraint-expressions, and 13217initializers of variables usable in constant expressions. For more details 13218refer to the latest revision of the C++ standard. 13219@end deftypefn 13220 13221@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c}) 13222@opindex fprofile-arcs 13223You may use @code{__builtin_expect} to provide the compiler with 13224branch prediction information. In general, you should prefer to 13225use actual profile feedback for this (@option{-fprofile-arcs}), as 13226programmers are notoriously bad at predicting how their programs 13227actually perform. However, there are applications in which this 13228data is hard to collect. 13229 13230The return value is the value of @var{exp}, which should be an integral 13231expression. The semantics of the built-in are that it is expected that 13232@var{exp} == @var{c}. For example: 13233 13234@smallexample 13235if (__builtin_expect (x, 0)) 13236 foo (); 13237@end smallexample 13238 13239@noindent 13240indicates that we do not expect to call @code{foo}, since 13241we expect @code{x} to be zero. Since you are limited to integral 13242expressions for @var{exp}, you should use constructions such as 13243 13244@smallexample 13245if (__builtin_expect (ptr != NULL, 1)) 13246 foo (*ptr); 13247@end smallexample 13248 13249@noindent 13250when testing pointer or floating-point values. 13251 13252For the purposes of branch prediction optimizations, the probability that 13253a @code{__builtin_expect} expression is @code{true} is controlled by GCC's 13254@code{builtin-expect-probability} parameter, which defaults to 90%. 13255 13256You can also use @code{__builtin_expect_with_probability} to explicitly 13257assign a probability value to individual expressions. If the built-in 13258is used in a loop construct, the provided probability will influence 13259the expected number of iterations made by loop optimizations. 13260@end deftypefn 13261 13262@deftypefn {Built-in Function} long __builtin_expect_with_probability 13263(long @var{exp}, long @var{c}, double @var{probability}) 13264 13265This function has the same semantics as @code{__builtin_expect}, 13266but the caller provides the expected probability that @var{exp} == @var{c}. 13267The last argument, @var{probability}, is a floating-point value in the 13268range 0.0 to 1.0, inclusive. The @var{probability} argument must be 13269constant floating-point expression. 13270@end deftypefn 13271 13272@deftypefn {Built-in Function} void __builtin_trap (void) 13273This function causes the program to exit abnormally. GCC implements 13274this function by using a target-dependent mechanism (such as 13275intentionally executing an illegal instruction) or by calling 13276@code{abort}. The mechanism used may vary from release to release so 13277you should not rely on any particular implementation. 13278@end deftypefn 13279 13280@deftypefn {Built-in Function} void __builtin_unreachable (void) 13281If control flow reaches the point of the @code{__builtin_unreachable}, 13282the program is undefined. It is useful in situations where the 13283compiler cannot deduce the unreachability of the code. 13284 13285One such case is immediately following an @code{asm} statement that 13286either never terminates, or one that transfers control elsewhere 13287and never returns. In this example, without the 13288@code{__builtin_unreachable}, GCC issues a warning that control 13289reaches the end of a non-void function. It also generates code 13290to return after the @code{asm}. 13291 13292@smallexample 13293int f (int c, int v) 13294@{ 13295 if (c) 13296 @{ 13297 return v; 13298 @} 13299 else 13300 @{ 13301 asm("jmp error_handler"); 13302 __builtin_unreachable (); 13303 @} 13304@} 13305@end smallexample 13306 13307@noindent 13308Because the @code{asm} statement unconditionally transfers control out 13309of the function, control never reaches the end of the function 13310body. The @code{__builtin_unreachable} is in fact unreachable and 13311communicates this fact to the compiler. 13312 13313Another use for @code{__builtin_unreachable} is following a call a 13314function that never returns but that is not declared 13315@code{__attribute__((noreturn))}, as in this example: 13316 13317@smallexample 13318void function_that_never_returns (void); 13319 13320int g (int c) 13321@{ 13322 if (c) 13323 @{ 13324 return 1; 13325 @} 13326 else 13327 @{ 13328 function_that_never_returns (); 13329 __builtin_unreachable (); 13330 @} 13331@} 13332@end smallexample 13333 13334@end deftypefn 13335 13336@deftypefn {Built-in Function} {void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...) 13337This function returns its first argument, and allows the compiler 13338to assume that the returned pointer is at least @var{align} bytes 13339aligned. This built-in can have either two or three arguments, 13340if it has three, the third argument should have integer type, and 13341if it is nonzero means misalignment offset. For example: 13342 13343@smallexample 13344void *x = __builtin_assume_aligned (arg, 16); 13345@end smallexample 13346 13347@noindent 13348means that the compiler can assume @code{x}, set to @code{arg}, is at least 1334916-byte aligned, while: 13350 13351@smallexample 13352void *x = __builtin_assume_aligned (arg, 32, 8); 13353@end smallexample 13354 13355@noindent 13356means that the compiler can assume for @code{x}, set to @code{arg}, that 13357@code{(char *) x - 8} is 32-byte aligned. 13358@end deftypefn 13359 13360@deftypefn {Built-in Function} int __builtin_LINE () 13361This function is the equivalent of the preprocessor @code{__LINE__} 13362macro and returns a constant integer expression that evaluates to 13363the line number of the invocation of the built-in. When used as a C++ 13364default argument for a function @var{F}, it returns the line number 13365of the call to @var{F}. 13366@end deftypefn 13367 13368@deftypefn {Built-in Function} {const char *} __builtin_FUNCTION () 13369This function is the equivalent of the @code{__FUNCTION__} symbol 13370and returns an address constant pointing to the name of the function 13371from which the built-in was invoked, or the empty string if 13372the invocation is not at function scope. When used as a C++ default 13373argument for a function @var{F}, it returns the name of @var{F}'s 13374caller or the empty string if the call was not made at function 13375scope. 13376@end deftypefn 13377 13378@deftypefn {Built-in Function} {const char *} __builtin_FILE () 13379This function is the equivalent of the preprocessor @code{__FILE__} 13380macro and returns an address constant pointing to the file name 13381containing the invocation of the built-in, or the empty string if 13382the invocation is not at function scope. When used as a C++ default 13383argument for a function @var{F}, it returns the file name of the call 13384to @var{F} or the empty string if the call was not made at function 13385scope. 13386 13387For example, in the following, each call to function @code{foo} will 13388print a line similar to @code{"file.c:123: foo: message"} with the name 13389of the file and the line number of the @code{printf} call, the name of 13390the function @code{foo}, followed by the word @code{message}. 13391 13392@smallexample 13393const char* 13394function (const char *func = __builtin_FUNCTION ()) 13395@{ 13396 return func; 13397@} 13398 13399void foo (void) 13400@{ 13401 printf ("%s:%i: %s: message\n", file (), line (), function ()); 13402@} 13403@end smallexample 13404 13405@end deftypefn 13406 13407@deftypefn {Built-in Function} void __builtin___clear_cache (void *@var{begin}, void *@var{end}) 13408This function is used to flush the processor's instruction cache for 13409the region of memory between @var{begin} inclusive and @var{end} 13410exclusive. Some targets require that the instruction cache be 13411flushed, after modifying memory containing code, in order to obtain 13412deterministic behavior. 13413 13414If the target does not require instruction cache flushes, 13415@code{__builtin___clear_cache} has no effect. Otherwise either 13416instructions are emitted in-line to clear the instruction cache or a 13417call to the @code{__clear_cache} function in libgcc is made. 13418@end deftypefn 13419 13420@deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...) 13421This function is used to minimize cache-miss latency by moving data into 13422a cache before it is accessed. 13423You can insert calls to @code{__builtin_prefetch} into code for which 13424you know addresses of data in memory that is likely to be accessed soon. 13425If the target supports them, data prefetch instructions are generated. 13426If the prefetch is done early enough before the access then the data will 13427be in the cache by the time it is accessed. 13428 13429The value of @var{addr} is the address of the memory to prefetch. 13430There are two optional arguments, @var{rw} and @var{locality}. 13431The value of @var{rw} is a compile-time constant one or zero; one 13432means that the prefetch is preparing for a write to the memory address 13433and zero, the default, means that the prefetch is preparing for a read. 13434The value @var{locality} must be a compile-time constant integer between 13435zero and three. A value of zero means that the data has no temporal 13436locality, so it need not be left in the cache after the access. A value 13437of three means that the data has a high degree of temporal locality and 13438should be left in all levels of cache possible. Values of one and two 13439mean, respectively, a low or moderate degree of temporal locality. The 13440default is three. 13441 13442@smallexample 13443for (i = 0; i < n; i++) 13444 @{ 13445 a[i] = a[i] + b[i]; 13446 __builtin_prefetch (&a[i+j], 1, 1); 13447 __builtin_prefetch (&b[i+j], 0, 1); 13448 /* @r{@dots{}} */ 13449 @} 13450@end smallexample 13451 13452Data prefetch does not generate faults if @var{addr} is invalid, but 13453the address expression itself must be valid. For example, a prefetch 13454of @code{p->next} does not fault if @code{p->next} is not a valid 13455address, but evaluation faults if @code{p} is not a valid address. 13456 13457If the target does not support data prefetch, the address expression 13458is evaluated if it includes side effects but no other code is generated 13459and GCC does not issue a warning. 13460@end deftypefn 13461 13462@deftypefn {Built-in Function}{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type}) 13463Returns the size of an object pointed to by @var{ptr}. @xref{Object Size 13464Checking}, for a detailed description of the function. 13465@end deftypefn 13466 13467@deftypefn {Built-in Function} double __builtin_huge_val (void) 13468Returns a positive infinity, if supported by the floating-point format, 13469else @code{DBL_MAX}. This function is suitable for implementing the 13470ISO C macro @code{HUGE_VAL}. 13471@end deftypefn 13472 13473@deftypefn {Built-in Function} float __builtin_huge_valf (void) 13474Similar to @code{__builtin_huge_val}, except the return type is @code{float}. 13475@end deftypefn 13476 13477@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void) 13478Similar to @code{__builtin_huge_val}, except the return 13479type is @code{long double}. 13480@end deftypefn 13481 13482@deftypefn {Built-in Function} _Float@var{n} __builtin_huge_valf@var{n} (void) 13483Similar to @code{__builtin_huge_val}, except the return type is 13484@code{_Float@var{n}}. 13485@end deftypefn 13486 13487@deftypefn {Built-in Function} _Float@var{n}x __builtin_huge_valf@var{n}x (void) 13488Similar to @code{__builtin_huge_val}, except the return type is 13489@code{_Float@var{n}x}. 13490@end deftypefn 13491 13492@deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...) 13493This built-in implements the C99 fpclassify functionality. The first 13494five int arguments should be the target library's notion of the 13495possible FP classes and are used for return values. They must be 13496constant values and they must appear in this order: @code{FP_NAN}, 13497@code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and 13498@code{FP_ZERO}. The ellipsis is for exactly one floating-point value 13499to classify. GCC treats the last argument as type-generic, which 13500means it does not do default promotion from float to double. 13501@end deftypefn 13502 13503@deftypefn {Built-in Function} double __builtin_inf (void) 13504Similar to @code{__builtin_huge_val}, except a warning is generated 13505if the target floating-point format does not support infinities. 13506@end deftypefn 13507 13508@deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void) 13509Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. 13510@end deftypefn 13511 13512@deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void) 13513Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. 13514@end deftypefn 13515 13516@deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void) 13517Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. 13518@end deftypefn 13519 13520@deftypefn {Built-in Function} float __builtin_inff (void) 13521Similar to @code{__builtin_inf}, except the return type is @code{float}. 13522This function is suitable for implementing the ISO C99 macro @code{INFINITY}. 13523@end deftypefn 13524 13525@deftypefn {Built-in Function} {long double} __builtin_infl (void) 13526Similar to @code{__builtin_inf}, except the return 13527type is @code{long double}. 13528@end deftypefn 13529 13530@deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n} (void) 13531Similar to @code{__builtin_inf}, except the return 13532type is @code{_Float@var{n}}. 13533@end deftypefn 13534 13535@deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n}x (void) 13536Similar to @code{__builtin_inf}, except the return 13537type is @code{_Float@var{n}x}. 13538@end deftypefn 13539 13540@deftypefn {Built-in Function} int __builtin_isinf_sign (...) 13541Similar to @code{isinf}, except the return value is -1 for 13542an argument of @code{-Inf} and 1 for an argument of @code{+Inf}. 13543Note while the parameter list is an 13544ellipsis, this function only accepts exactly one floating-point 13545argument. GCC treats this parameter as type-generic, which means it 13546does not do default promotion from float to double. 13547@end deftypefn 13548 13549@deftypefn {Built-in Function} double __builtin_nan (const char *str) 13550This is an implementation of the ISO C99 function @code{nan}. 13551 13552Since ISO C99 defines this function in terms of @code{strtod}, which we 13553do not implement, a description of the parsing is in order. The string 13554is parsed as by @code{strtol}; that is, the base is recognized by 13555leading @samp{0} or @samp{0x} prefixes. The number parsed is placed 13556in the significand such that the least significant bit of the number 13557is at the least significant bit of the significand. The number is 13558truncated to fit the significand field provided. The significand is 13559forced to be a quiet NaN@. 13560 13561This function, if given a string literal all of which would have been 13562consumed by @code{strtol}, is evaluated early enough that it is considered a 13563compile-time constant. 13564@end deftypefn 13565 13566@deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str) 13567Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. 13568@end deftypefn 13569 13570@deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str) 13571Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. 13572@end deftypefn 13573 13574@deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str) 13575Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. 13576@end deftypefn 13577 13578@deftypefn {Built-in Function} float __builtin_nanf (const char *str) 13579Similar to @code{__builtin_nan}, except the return type is @code{float}. 13580@end deftypefn 13581 13582@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str) 13583Similar to @code{__builtin_nan}, except the return type is @code{long double}. 13584@end deftypefn 13585 13586@deftypefn {Built-in Function} _Float@var{n} __builtin_nanf@var{n} (const char *str) 13587Similar to @code{__builtin_nan}, except the return type is 13588@code{_Float@var{n}}. 13589@end deftypefn 13590 13591@deftypefn {Built-in Function} _Float@var{n}x __builtin_nanf@var{n}x (const char *str) 13592Similar to @code{__builtin_nan}, except the return type is 13593@code{_Float@var{n}x}. 13594@end deftypefn 13595 13596@deftypefn {Built-in Function} double __builtin_nans (const char *str) 13597Similar to @code{__builtin_nan}, except the significand is forced 13598to be a signaling NaN@. The @code{nans} function is proposed by 13599@uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. 13600@end deftypefn 13601 13602@deftypefn {Built-in Function} float __builtin_nansf (const char *str) 13603Similar to @code{__builtin_nans}, except the return type is @code{float}. 13604@end deftypefn 13605 13606@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str) 13607Similar to @code{__builtin_nans}, except the return type is @code{long double}. 13608@end deftypefn 13609 13610@deftypefn {Built-in Function} _Float@var{n} __builtin_nansf@var{n} (const char *str) 13611Similar to @code{__builtin_nans}, except the return type is 13612@code{_Float@var{n}}. 13613@end deftypefn 13614 13615@deftypefn {Built-in Function} _Float@var{n}x __builtin_nansf@var{n}x (const char *str) 13616Similar to @code{__builtin_nans}, except the return type is 13617@code{_Float@var{n}x}. 13618@end deftypefn 13619 13620@deftypefn {Built-in Function} int __builtin_ffs (int x) 13621Returns one plus the index of the least significant 1-bit of @var{x}, or 13622if @var{x} is zero, returns zero. 13623@end deftypefn 13624 13625@deftypefn {Built-in Function} int __builtin_clz (unsigned int x) 13626Returns the number of leading 0-bits in @var{x}, starting at the most 13627significant bit position. If @var{x} is 0, the result is undefined. 13628@end deftypefn 13629 13630@deftypefn {Built-in Function} int __builtin_ctz (unsigned int x) 13631Returns the number of trailing 0-bits in @var{x}, starting at the least 13632significant bit position. If @var{x} is 0, the result is undefined. 13633@end deftypefn 13634 13635@deftypefn {Built-in Function} int __builtin_clrsb (int x) 13636Returns the number of leading redundant sign bits in @var{x}, i.e.@: the 13637number of bits following the most significant bit that are identical 13638to it. There are no special cases for 0 or other values. 13639@end deftypefn 13640 13641@deftypefn {Built-in Function} int __builtin_popcount (unsigned int x) 13642Returns the number of 1-bits in @var{x}. 13643@end deftypefn 13644 13645@deftypefn {Built-in Function} int __builtin_parity (unsigned int x) 13646Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} 13647modulo 2. 13648@end deftypefn 13649 13650@deftypefn {Built-in Function} int __builtin_ffsl (long) 13651Similar to @code{__builtin_ffs}, except the argument type is 13652@code{long}. 13653@end deftypefn 13654 13655@deftypefn {Built-in Function} int __builtin_clzl (unsigned long) 13656Similar to @code{__builtin_clz}, except the argument type is 13657@code{unsigned long}. 13658@end deftypefn 13659 13660@deftypefn {Built-in Function} int __builtin_ctzl (unsigned long) 13661Similar to @code{__builtin_ctz}, except the argument type is 13662@code{unsigned long}. 13663@end deftypefn 13664 13665@deftypefn {Built-in Function} int __builtin_clrsbl (long) 13666Similar to @code{__builtin_clrsb}, except the argument type is 13667@code{long}. 13668@end deftypefn 13669 13670@deftypefn {Built-in Function} int __builtin_popcountl (unsigned long) 13671Similar to @code{__builtin_popcount}, except the argument type is 13672@code{unsigned long}. 13673@end deftypefn 13674 13675@deftypefn {Built-in Function} int __builtin_parityl (unsigned long) 13676Similar to @code{__builtin_parity}, except the argument type is 13677@code{unsigned long}. 13678@end deftypefn 13679 13680@deftypefn {Built-in Function} int __builtin_ffsll (long long) 13681Similar to @code{__builtin_ffs}, except the argument type is 13682@code{long long}. 13683@end deftypefn 13684 13685@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long) 13686Similar to @code{__builtin_clz}, except the argument type is 13687@code{unsigned long long}. 13688@end deftypefn 13689 13690@deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long) 13691Similar to @code{__builtin_ctz}, except the argument type is 13692@code{unsigned long long}. 13693@end deftypefn 13694 13695@deftypefn {Built-in Function} int __builtin_clrsbll (long long) 13696Similar to @code{__builtin_clrsb}, except the argument type is 13697@code{long long}. 13698@end deftypefn 13699 13700@deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long) 13701Similar to @code{__builtin_popcount}, except the argument type is 13702@code{unsigned long long}. 13703@end deftypefn 13704 13705@deftypefn {Built-in Function} int __builtin_parityll (unsigned long long) 13706Similar to @code{__builtin_parity}, except the argument type is 13707@code{unsigned long long}. 13708@end deftypefn 13709 13710@deftypefn {Built-in Function} double __builtin_powi (double, int) 13711Returns the first argument raised to the power of the second. Unlike the 13712@code{pow} function no guarantees about precision and rounding are made. 13713@end deftypefn 13714 13715@deftypefn {Built-in Function} float __builtin_powif (float, int) 13716Similar to @code{__builtin_powi}, except the argument and return types 13717are @code{float}. 13718@end deftypefn 13719 13720@deftypefn {Built-in Function} {long double} __builtin_powil (long double, int) 13721Similar to @code{__builtin_powi}, except the argument and return types 13722are @code{long double}. 13723@end deftypefn 13724 13725@deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x) 13726Returns @var{x} with the order of the bytes reversed; for example, 13727@code{0xaabb} becomes @code{0xbbaa}. Byte here always means 13728exactly 8 bits. 13729@end deftypefn 13730 13731@deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x) 13732Similar to @code{__builtin_bswap16}, except the argument and return types 13733are 32 bit. 13734@end deftypefn 13735 13736@deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x) 13737Similar to @code{__builtin_bswap32}, except the argument and return types 13738are 64 bit. 13739@end deftypefn 13740 13741@deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x) 13742On targets where the user visible pointer size is smaller than the size 13743of an actual hardware address this function returns the extended user 13744pointer. Targets where this is true included ILP32 mode on x86_64 or 13745Aarch64. This function is mainly useful when writing inline assembly 13746code. 13747@end deftypefn 13748 13749@deftypefn {Built-in Function} int __builtin_goacc_parlevel_id (int x) 13750Returns the openacc gang, worker or vector id depending on whether @var{x} is 137510, 1 or 2. 13752@end deftypefn 13753 13754@deftypefn {Built-in Function} int __builtin_goacc_parlevel_size (int x) 13755Returns the openacc gang, worker or vector size depending on whether @var{x} is 137560, 1 or 2. 13757@end deftypefn 13758 13759@node Target Builtins 13760@section Built-in Functions Specific to Particular Target Machines 13761 13762On some target machines, GCC supports many built-in functions specific 13763to those machines. Generally these generate calls to specific machine 13764instructions, but allow the compiler to schedule those calls. 13765 13766@menu 13767* AArch64 Built-in Functions:: 13768* Alpha Built-in Functions:: 13769* Altera Nios II Built-in Functions:: 13770* ARC Built-in Functions:: 13771* ARC SIMD Built-in Functions:: 13772* ARM iWMMXt Built-in Functions:: 13773* ARM C Language Extensions (ACLE):: 13774* ARM Floating Point Status and Control Intrinsics:: 13775* ARM ARMv8-M Security Extensions:: 13776* AVR Built-in Functions:: 13777* Blackfin Built-in Functions:: 13778* BPF Built-in Functions:: 13779* FR-V Built-in Functions:: 13780* MIPS DSP Built-in Functions:: 13781* MIPS Paired-Single Support:: 13782* MIPS Loongson Built-in Functions:: 13783* MIPS SIMD Architecture (MSA) Support:: 13784* Other MIPS Built-in Functions:: 13785* MSP430 Built-in Functions:: 13786* NDS32 Built-in Functions:: 13787* picoChip Built-in Functions:: 13788* Basic PowerPC Built-in Functions:: 13789* PowerPC AltiVec/VSX Built-in Functions:: 13790* PowerPC Hardware Transactional Memory Built-in Functions:: 13791* PowerPC Atomic Memory Operation Functions:: 13792* PowerPC Matrix-Multiply Assist Built-in Functions:: 13793* RISC-V Built-in Functions:: 13794* RX Built-in Functions:: 13795* S/390 System z Built-in Functions:: 13796* SH Built-in Functions:: 13797* SPARC VIS Built-in Functions:: 13798* TI C6X Built-in Functions:: 13799* TILE-Gx Built-in Functions:: 13800* TILEPro Built-in Functions:: 13801* x86 Built-in Functions:: 13802* x86 transactional memory intrinsics:: 13803* x86 control-flow protection intrinsics:: 13804@end menu 13805 13806@node AArch64 Built-in Functions 13807@subsection AArch64 Built-in Functions 13808 13809These built-in functions are available for the AArch64 family of 13810processors. 13811@smallexample 13812unsigned int __builtin_aarch64_get_fpcr () 13813void __builtin_aarch64_set_fpcr (unsigned int) 13814unsigned int __builtin_aarch64_get_fpsr () 13815void __builtin_aarch64_set_fpsr (unsigned int) 13816@end smallexample 13817 13818@node Alpha Built-in Functions 13819@subsection Alpha Built-in Functions 13820 13821These built-in functions are available for the Alpha family of 13822processors, depending on the command-line switches used. 13823 13824The following built-in functions are always available. They 13825all generate the machine instruction that is part of the name. 13826 13827@smallexample 13828long __builtin_alpha_implver (void) 13829long __builtin_alpha_rpcc (void) 13830long __builtin_alpha_amask (long) 13831long __builtin_alpha_cmpbge (long, long) 13832long __builtin_alpha_extbl (long, long) 13833long __builtin_alpha_extwl (long, long) 13834long __builtin_alpha_extll (long, long) 13835long __builtin_alpha_extql (long, long) 13836long __builtin_alpha_extwh (long, long) 13837long __builtin_alpha_extlh (long, long) 13838long __builtin_alpha_extqh (long, long) 13839long __builtin_alpha_insbl (long, long) 13840long __builtin_alpha_inswl (long, long) 13841long __builtin_alpha_insll (long, long) 13842long __builtin_alpha_insql (long, long) 13843long __builtin_alpha_inswh (long, long) 13844long __builtin_alpha_inslh (long, long) 13845long __builtin_alpha_insqh (long, long) 13846long __builtin_alpha_mskbl (long, long) 13847long __builtin_alpha_mskwl (long, long) 13848long __builtin_alpha_mskll (long, long) 13849long __builtin_alpha_mskql (long, long) 13850long __builtin_alpha_mskwh (long, long) 13851long __builtin_alpha_msklh (long, long) 13852long __builtin_alpha_mskqh (long, long) 13853long __builtin_alpha_umulh (long, long) 13854long __builtin_alpha_zap (long, long) 13855long __builtin_alpha_zapnot (long, long) 13856@end smallexample 13857 13858The following built-in functions are always with @option{-mmax} 13859or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or 13860later. They all generate the machine instruction that is part 13861of the name. 13862 13863@smallexample 13864long __builtin_alpha_pklb (long) 13865long __builtin_alpha_pkwb (long) 13866long __builtin_alpha_unpkbl (long) 13867long __builtin_alpha_unpkbw (long) 13868long __builtin_alpha_minub8 (long, long) 13869long __builtin_alpha_minsb8 (long, long) 13870long __builtin_alpha_minuw4 (long, long) 13871long __builtin_alpha_minsw4 (long, long) 13872long __builtin_alpha_maxub8 (long, long) 13873long __builtin_alpha_maxsb8 (long, long) 13874long __builtin_alpha_maxuw4 (long, long) 13875long __builtin_alpha_maxsw4 (long, long) 13876long __builtin_alpha_perr (long, long) 13877@end smallexample 13878 13879The following built-in functions are always with @option{-mcix} 13880or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or 13881later. They all generate the machine instruction that is part 13882of the name. 13883 13884@smallexample 13885long __builtin_alpha_cttz (long) 13886long __builtin_alpha_ctlz (long) 13887long __builtin_alpha_ctpop (long) 13888@end smallexample 13889 13890The following built-in functions are available on systems that use the OSF/1 13891PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} 13892PAL calls, but when invoked with @option{-mtls-kernel}, they invoke 13893@code{rdval} and @code{wrval}. 13894 13895@smallexample 13896void *__builtin_thread_pointer (void) 13897void __builtin_set_thread_pointer (void *) 13898@end smallexample 13899 13900@node Altera Nios II Built-in Functions 13901@subsection Altera Nios II Built-in Functions 13902 13903These built-in functions are available for the Altera Nios II 13904family of processors. 13905 13906The following built-in functions are always available. They 13907all generate the machine instruction that is part of the name. 13908 13909@example 13910int __builtin_ldbio (volatile const void *) 13911int __builtin_ldbuio (volatile const void *) 13912int __builtin_ldhio (volatile const void *) 13913int __builtin_ldhuio (volatile const void *) 13914int __builtin_ldwio (volatile const void *) 13915void __builtin_stbio (volatile void *, int) 13916void __builtin_sthio (volatile void *, int) 13917void __builtin_stwio (volatile void *, int) 13918void __builtin_sync (void) 13919int __builtin_rdctl (int) 13920int __builtin_rdprs (int, int) 13921void __builtin_wrctl (int, int) 13922void __builtin_flushd (volatile void *) 13923void __builtin_flushda (volatile void *) 13924int __builtin_wrpie (int); 13925void __builtin_eni (int); 13926int __builtin_ldex (volatile const void *) 13927int __builtin_stex (volatile void *, int) 13928int __builtin_ldsex (volatile const void *) 13929int __builtin_stsex (volatile void *, int) 13930@end example 13931 13932The following built-in functions are always available. They 13933all generate a Nios II Custom Instruction. The name of the 13934function represents the types that the function takes and 13935returns. The letter before the @code{n} is the return type 13936or void if absent. The @code{n} represents the first parameter 13937to all the custom instructions, the custom instruction number. 13938The two letters after the @code{n} represent the up to two 13939parameters to the function. 13940 13941The letters represent the following data types: 13942@table @code 13943@item <no letter> 13944@code{void} for return type and no parameter for parameter types. 13945 13946@item i 13947@code{int} for return type and parameter type 13948 13949@item f 13950@code{float} for return type and parameter type 13951 13952@item p 13953@code{void *} for return type and parameter type 13954 13955@end table 13956 13957And the function names are: 13958@example 13959void __builtin_custom_n (void) 13960void __builtin_custom_ni (int) 13961void __builtin_custom_nf (float) 13962void __builtin_custom_np (void *) 13963void __builtin_custom_nii (int, int) 13964void __builtin_custom_nif (int, float) 13965void __builtin_custom_nip (int, void *) 13966void __builtin_custom_nfi (float, int) 13967void __builtin_custom_nff (float, float) 13968void __builtin_custom_nfp (float, void *) 13969void __builtin_custom_npi (void *, int) 13970void __builtin_custom_npf (void *, float) 13971void __builtin_custom_npp (void *, void *) 13972int __builtin_custom_in (void) 13973int __builtin_custom_ini (int) 13974int __builtin_custom_inf (float) 13975int __builtin_custom_inp (void *) 13976int __builtin_custom_inii (int, int) 13977int __builtin_custom_inif (int, float) 13978int __builtin_custom_inip (int, void *) 13979int __builtin_custom_infi (float, int) 13980int __builtin_custom_inff (float, float) 13981int __builtin_custom_infp (float, void *) 13982int __builtin_custom_inpi (void *, int) 13983int __builtin_custom_inpf (void *, float) 13984int __builtin_custom_inpp (void *, void *) 13985float __builtin_custom_fn (void) 13986float __builtin_custom_fni (int) 13987float __builtin_custom_fnf (float) 13988float __builtin_custom_fnp (void *) 13989float __builtin_custom_fnii (int, int) 13990float __builtin_custom_fnif (int, float) 13991float __builtin_custom_fnip (int, void *) 13992float __builtin_custom_fnfi (float, int) 13993float __builtin_custom_fnff (float, float) 13994float __builtin_custom_fnfp (float, void *) 13995float __builtin_custom_fnpi (void *, int) 13996float __builtin_custom_fnpf (void *, float) 13997float __builtin_custom_fnpp (void *, void *) 13998void * __builtin_custom_pn (void) 13999void * __builtin_custom_pni (int) 14000void * __builtin_custom_pnf (float) 14001void * __builtin_custom_pnp (void *) 14002void * __builtin_custom_pnii (int, int) 14003void * __builtin_custom_pnif (int, float) 14004void * __builtin_custom_pnip (int, void *) 14005void * __builtin_custom_pnfi (float, int) 14006void * __builtin_custom_pnff (float, float) 14007void * __builtin_custom_pnfp (float, void *) 14008void * __builtin_custom_pnpi (void *, int) 14009void * __builtin_custom_pnpf (void *, float) 14010void * __builtin_custom_pnpp (void *, void *) 14011@end example 14012 14013@node ARC Built-in Functions 14014@subsection ARC Built-in Functions 14015 14016The following built-in functions are provided for ARC targets. The 14017built-ins generate the corresponding assembly instructions. In the 14018examples given below, the generated code often requires an operand or 14019result to be in a register. Where necessary further code will be 14020generated to ensure this is true, but for brevity this is not 14021described in each case. 14022 14023@emph{Note:} Using a built-in to generate an instruction not supported 14024by a target may cause problems. At present the compiler is not 14025guaranteed to detect such misuse, and as a result an internal compiler 14026error may be generated. 14027 14028@deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval}) 14029Return 1 if @var{val} is known to have the byte alignment given 14030by @var{alignval}, otherwise return 0. 14031Note that this is different from 14032@smallexample 14033__alignof__(*(char *)@var{val}) >= alignval 14034@end smallexample 14035because __alignof__ sees only the type of the dereference, whereas 14036__builtin_arc_align uses alignment information from the pointer 14037as well as from the pointed-to type. 14038The information available will depend on optimization level. 14039@end deftypefn 14040 14041@deftypefn {Built-in Function} void __builtin_arc_brk (void) 14042Generates 14043@example 14044brk 14045@end example 14046@end deftypefn 14047 14048@deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno}) 14049The operand is the number of a register to be read. Generates: 14050@example 14051mov @var{dest}, r@var{regno} 14052@end example 14053where the value in @var{dest} will be the result returned from the 14054built-in. 14055@end deftypefn 14056 14057@deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val}) 14058The first operand is the number of a register to be written, the 14059second operand is a compile time constant to write into that 14060register. Generates: 14061@example 14062mov r@var{regno}, @var{val} 14063@end example 14064@end deftypefn 14065 14066@deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b}) 14067Only available if either @option{-mcpu=ARC700} or @option{-meA} is set. 14068Generates: 14069@example 14070divaw @var{dest}, @var{a}, @var{b} 14071@end example 14072where the value in @var{dest} will be the result returned from the 14073built-in. 14074@end deftypefn 14075 14076@deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a}) 14077Generates 14078@example 14079flag @var{a} 14080@end example 14081@end deftypefn 14082 14083@deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr}) 14084The operand, @var{auxv}, is the address of an auxiliary register and 14085must be a compile time constant. Generates: 14086@example 14087lr @var{dest}, [@var{auxr}] 14088@end example 14089Where the value in @var{dest} will be the result returned from the 14090built-in. 14091@end deftypefn 14092 14093@deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b}) 14094Only available with @option{-mmul64}. Generates: 14095@example 14096mul64 @var{a}, @var{b} 14097@end example 14098@end deftypefn 14099 14100@deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b}) 14101Only available with @option{-mmul64}. Generates: 14102@example 14103mulu64 @var{a}, @var{b} 14104@end example 14105@end deftypefn 14106 14107@deftypefn {Built-in Function} void __builtin_arc_nop (void) 14108Generates: 14109@example 14110nop 14111@end example 14112@end deftypefn 14113 14114@deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src}) 14115Only valid if the @samp{norm} instruction is available through the 14116@option{-mnorm} option or by default with @option{-mcpu=ARC700}. 14117Generates: 14118@example 14119norm @var{dest}, @var{src} 14120@end example 14121Where the value in @var{dest} will be the result returned from the 14122built-in. 14123@end deftypefn 14124 14125@deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src}) 14126Only valid if the @samp{normw} instruction is available through the 14127@option{-mnorm} option or by default with @option{-mcpu=ARC700}. 14128Generates: 14129@example 14130normw @var{dest}, @var{src} 14131@end example 14132Where the value in @var{dest} will be the result returned from the 14133built-in. 14134@end deftypefn 14135 14136@deftypefn {Built-in Function} void __builtin_arc_rtie (void) 14137Generates: 14138@example 14139rtie 14140@end example 14141@end deftypefn 14142 14143@deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a} 14144Generates: 14145@example 14146sleep @var{a} 14147@end example 14148@end deftypefn 14149 14150@deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{auxr}, unsigned int @var{val}) 14151The first argument, @var{auxv}, is the address of an auxiliary 14152register, the second argument, @var{val}, is a compile time constant 14153to be written to the register. Generates: 14154@example 14155sr @var{auxr}, [@var{val}] 14156@end example 14157@end deftypefn 14158 14159@deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src}) 14160Only valid with @option{-mswap}. Generates: 14161@example 14162swap @var{dest}, @var{src} 14163@end example 14164Where the value in @var{dest} will be the result returned from the 14165built-in. 14166@end deftypefn 14167 14168@deftypefn {Built-in Function} void __builtin_arc_swi (void) 14169Generates: 14170@example 14171swi 14172@end example 14173@end deftypefn 14174 14175@deftypefn {Built-in Function} void __builtin_arc_sync (void) 14176Only available with @option{-mcpu=ARC700}. Generates: 14177@example 14178sync 14179@end example 14180@end deftypefn 14181 14182@deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c}) 14183Only available with @option{-mcpu=ARC700}. Generates: 14184@example 14185trap_s @var{c} 14186@end example 14187@end deftypefn 14188 14189@deftypefn {Built-in Function} void __builtin_arc_unimp_s (void) 14190Only available with @option{-mcpu=ARC700}. Generates: 14191@example 14192unimp_s 14193@end example 14194@end deftypefn 14195 14196The instructions generated by the following builtins are not 14197considered as candidates for scheduling. They are not moved around by 14198the compiler during scheduling, and thus can be expected to appear 14199where they are put in the C code: 14200@example 14201__builtin_arc_brk() 14202__builtin_arc_core_read() 14203__builtin_arc_core_write() 14204__builtin_arc_flag() 14205__builtin_arc_lr() 14206__builtin_arc_sleep() 14207__builtin_arc_sr() 14208__builtin_arc_swi() 14209@end example 14210 14211@node ARC SIMD Built-in Functions 14212@subsection ARC SIMD Built-in Functions 14213 14214SIMD builtins provided by the compiler can be used to generate the 14215vector instructions. This section describes the available builtins 14216and their usage in programs. With the @option{-msimd} option, the 14217compiler provides 128-bit vector types, which can be specified using 14218the @code{vector_size} attribute. The header file @file{arc-simd.h} 14219can be included to use the following predefined types: 14220@example 14221typedef int __v4si __attribute__((vector_size(16))); 14222typedef short __v8hi __attribute__((vector_size(16))); 14223@end example 14224 14225These types can be used to define 128-bit variables. The built-in 14226functions listed in the following section can be used on these 14227variables to generate the vector operations. 14228 14229For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file 14230@file{arc-simd.h} also provides equivalent macros called 14231@code{_@var{someinsn}} that can be used for programming ease and 14232improved readability. The following macros for DMA control are also 14233provided: 14234@example 14235#define _setup_dma_in_channel_reg _vdiwr 14236#define _setup_dma_out_channel_reg _vdowr 14237@end example 14238 14239The following is a complete list of all the SIMD built-ins provided 14240for ARC, grouped by calling signature. 14241 14242The following take two @code{__v8hi} arguments and return a 14243@code{__v8hi} result: 14244@example 14245__v8hi __builtin_arc_vaddaw (__v8hi, __v8hi) 14246__v8hi __builtin_arc_vaddw (__v8hi, __v8hi) 14247__v8hi __builtin_arc_vand (__v8hi, __v8hi) 14248__v8hi __builtin_arc_vandaw (__v8hi, __v8hi) 14249__v8hi __builtin_arc_vavb (__v8hi, __v8hi) 14250__v8hi __builtin_arc_vavrb (__v8hi, __v8hi) 14251__v8hi __builtin_arc_vbic (__v8hi, __v8hi) 14252__v8hi __builtin_arc_vbicaw (__v8hi, __v8hi) 14253__v8hi __builtin_arc_vdifaw (__v8hi, __v8hi) 14254__v8hi __builtin_arc_vdifw (__v8hi, __v8hi) 14255__v8hi __builtin_arc_veqw (__v8hi, __v8hi) 14256__v8hi __builtin_arc_vh264f (__v8hi, __v8hi) 14257__v8hi __builtin_arc_vh264ft (__v8hi, __v8hi) 14258__v8hi __builtin_arc_vh264fw (__v8hi, __v8hi) 14259__v8hi __builtin_arc_vlew (__v8hi, __v8hi) 14260__v8hi __builtin_arc_vltw (__v8hi, __v8hi) 14261__v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi) 14262__v8hi __builtin_arc_vmaxw (__v8hi, __v8hi) 14263__v8hi __builtin_arc_vminaw (__v8hi, __v8hi) 14264__v8hi __builtin_arc_vminw (__v8hi, __v8hi) 14265__v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi) 14266__v8hi __builtin_arc_vmr1w (__v8hi, __v8hi) 14267__v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi) 14268__v8hi __builtin_arc_vmr2w (__v8hi, __v8hi) 14269__v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi) 14270__v8hi __builtin_arc_vmr3w (__v8hi, __v8hi) 14271__v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi) 14272__v8hi __builtin_arc_vmr4w (__v8hi, __v8hi) 14273__v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi) 14274__v8hi __builtin_arc_vmr5w (__v8hi, __v8hi) 14275__v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi) 14276__v8hi __builtin_arc_vmr6w (__v8hi, __v8hi) 14277__v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi) 14278__v8hi __builtin_arc_vmr7w (__v8hi, __v8hi) 14279__v8hi __builtin_arc_vmrb (__v8hi, __v8hi) 14280__v8hi __builtin_arc_vmulaw (__v8hi, __v8hi) 14281__v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi) 14282__v8hi __builtin_arc_vmulfw (__v8hi, __v8hi) 14283__v8hi __builtin_arc_vmulw (__v8hi, __v8hi) 14284__v8hi __builtin_arc_vnew (__v8hi, __v8hi) 14285__v8hi __builtin_arc_vor (__v8hi, __v8hi) 14286__v8hi __builtin_arc_vsubaw (__v8hi, __v8hi) 14287__v8hi __builtin_arc_vsubw (__v8hi, __v8hi) 14288__v8hi __builtin_arc_vsummw (__v8hi, __v8hi) 14289__v8hi __builtin_arc_vvc1f (__v8hi, __v8hi) 14290__v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi) 14291__v8hi __builtin_arc_vxor (__v8hi, __v8hi) 14292__v8hi __builtin_arc_vxoraw (__v8hi, __v8hi) 14293@end example 14294 14295The following take one @code{__v8hi} and one @code{int} argument and return a 14296@code{__v8hi} result: 14297 14298@example 14299__v8hi __builtin_arc_vbaddw (__v8hi, int) 14300__v8hi __builtin_arc_vbmaxw (__v8hi, int) 14301__v8hi __builtin_arc_vbminw (__v8hi, int) 14302__v8hi __builtin_arc_vbmulaw (__v8hi, int) 14303__v8hi __builtin_arc_vbmulfw (__v8hi, int) 14304__v8hi __builtin_arc_vbmulw (__v8hi, int) 14305__v8hi __builtin_arc_vbrsubw (__v8hi, int) 14306__v8hi __builtin_arc_vbsubw (__v8hi, int) 14307@end example 14308 14309The following take one @code{__v8hi} argument and one @code{int} argument which 14310must be a 3-bit compile time constant indicating a register number 14311I0-I7. They return a @code{__v8hi} result. 14312@example 14313__v8hi __builtin_arc_vasrw (__v8hi, const int) 14314__v8hi __builtin_arc_vsr8 (__v8hi, const int) 14315__v8hi __builtin_arc_vsr8aw (__v8hi, const int) 14316@end example 14317 14318The following take one @code{__v8hi} argument and one @code{int} 14319argument which must be a 6-bit compile time constant. They return a 14320@code{__v8hi} result. 14321@example 14322__v8hi __builtin_arc_vasrpwbi (__v8hi, const int) 14323__v8hi __builtin_arc_vasrrpwbi (__v8hi, const int) 14324__v8hi __builtin_arc_vasrrwi (__v8hi, const int) 14325__v8hi __builtin_arc_vasrsrwi (__v8hi, const int) 14326__v8hi __builtin_arc_vasrwi (__v8hi, const int) 14327__v8hi __builtin_arc_vsr8awi (__v8hi, const int) 14328__v8hi __builtin_arc_vsr8i (__v8hi, const int) 14329@end example 14330 14331The following take one @code{__v8hi} argument and one @code{int} argument which 14332must be a 8-bit compile time constant. They return a @code{__v8hi} 14333result. 14334@example 14335__v8hi __builtin_arc_vd6tapf (__v8hi, const int) 14336__v8hi __builtin_arc_vmvaw (__v8hi, const int) 14337__v8hi __builtin_arc_vmvw (__v8hi, const int) 14338__v8hi __builtin_arc_vmvzw (__v8hi, const int) 14339@end example 14340 14341The following take two @code{int} arguments, the second of which which 14342must be a 8-bit compile time constant. They return a @code{__v8hi} 14343result: 14344@example 14345__v8hi __builtin_arc_vmovaw (int, const int) 14346__v8hi __builtin_arc_vmovw (int, const int) 14347__v8hi __builtin_arc_vmovzw (int, const int) 14348@end example 14349 14350The following take a single @code{__v8hi} argument and return a 14351@code{__v8hi} result: 14352@example 14353__v8hi __builtin_arc_vabsaw (__v8hi) 14354__v8hi __builtin_arc_vabsw (__v8hi) 14355__v8hi __builtin_arc_vaddsuw (__v8hi) 14356__v8hi __builtin_arc_vexch1 (__v8hi) 14357__v8hi __builtin_arc_vexch2 (__v8hi) 14358__v8hi __builtin_arc_vexch4 (__v8hi) 14359__v8hi __builtin_arc_vsignw (__v8hi) 14360__v8hi __builtin_arc_vupbaw (__v8hi) 14361__v8hi __builtin_arc_vupbw (__v8hi) 14362__v8hi __builtin_arc_vupsbaw (__v8hi) 14363__v8hi __builtin_arc_vupsbw (__v8hi) 14364@end example 14365 14366The following take two @code{int} arguments and return no result: 14367@example 14368void __builtin_arc_vdirun (int, int) 14369void __builtin_arc_vdorun (int, int) 14370@end example 14371 14372The following take two @code{int} arguments and return no result. The 14373first argument must a 3-bit compile time constant indicating one of 14374the DR0-DR7 DMA setup channels: 14375@example 14376void __builtin_arc_vdiwr (const int, int) 14377void __builtin_arc_vdowr (const int, int) 14378@end example 14379 14380The following take an @code{int} argument and return no result: 14381@example 14382void __builtin_arc_vendrec (int) 14383void __builtin_arc_vrec (int) 14384void __builtin_arc_vrecrun (int) 14385void __builtin_arc_vrun (int) 14386@end example 14387 14388The following take a @code{__v8hi} argument and two @code{int} 14389arguments and return a @code{__v8hi} result. The second argument must 14390be a 3-bit compile time constants, indicating one the registers I0-I7, 14391and the third argument must be an 8-bit compile time constant. 14392 14393@emph{Note:} Although the equivalent hardware instructions do not take 14394an SIMD register as an operand, these builtins overwrite the relevant 14395bits of the @code{__v8hi} register provided as the first argument with 14396the value loaded from the @code{[Ib, u8]} location in the SDM. 14397 14398@example 14399__v8hi __builtin_arc_vld32 (__v8hi, const int, const int) 14400__v8hi __builtin_arc_vld32wh (__v8hi, const int, const int) 14401__v8hi __builtin_arc_vld32wl (__v8hi, const int, const int) 14402__v8hi __builtin_arc_vld64 (__v8hi, const int, const int) 14403@end example 14404 14405The following take two @code{int} arguments and return a @code{__v8hi} 14406result. The first argument must be a 3-bit compile time constants, 14407indicating one the registers I0-I7, and the second argument must be an 144088-bit compile time constant. 14409 14410@example 14411__v8hi __builtin_arc_vld128 (const int, const int) 14412__v8hi __builtin_arc_vld64w (const int, const int) 14413@end example 14414 14415The following take a @code{__v8hi} argument and two @code{int} 14416arguments and return no result. The second argument must be a 3-bit 14417compile time constants, indicating one the registers I0-I7, and the 14418third argument must be an 8-bit compile time constant. 14419 14420@example 14421void __builtin_arc_vst128 (__v8hi, const int, const int) 14422void __builtin_arc_vst64 (__v8hi, const int, const int) 14423@end example 14424 14425The following take a @code{__v8hi} argument and three @code{int} 14426arguments and return no result. The second argument must be a 3-bit 14427compile-time constant, identifying the 16-bit sub-register to be 14428stored, the third argument must be a 3-bit compile time constants, 14429indicating one the registers I0-I7, and the fourth argument must be an 144308-bit compile time constant. 14431 14432@example 14433void __builtin_arc_vst16_n (__v8hi, const int, const int, const int) 14434void __builtin_arc_vst32_n (__v8hi, const int, const int, const int) 14435@end example 14436 14437@node ARM iWMMXt Built-in Functions 14438@subsection ARM iWMMXt Built-in Functions 14439 14440These built-in functions are available for the ARM family of 14441processors when the @option{-mcpu=iwmmxt} switch is used: 14442 14443@smallexample 14444typedef int v2si __attribute__ ((vector_size (8))); 14445typedef short v4hi __attribute__ ((vector_size (8))); 14446typedef char v8qi __attribute__ ((vector_size (8))); 14447 14448int __builtin_arm_getwcgr0 (void) 14449void __builtin_arm_setwcgr0 (int) 14450int __builtin_arm_getwcgr1 (void) 14451void __builtin_arm_setwcgr1 (int) 14452int __builtin_arm_getwcgr2 (void) 14453void __builtin_arm_setwcgr2 (int) 14454int __builtin_arm_getwcgr3 (void) 14455void __builtin_arm_setwcgr3 (int) 14456int __builtin_arm_textrmsb (v8qi, int) 14457int __builtin_arm_textrmsh (v4hi, int) 14458int __builtin_arm_textrmsw (v2si, int) 14459int __builtin_arm_textrmub (v8qi, int) 14460int __builtin_arm_textrmuh (v4hi, int) 14461int __builtin_arm_textrmuw (v2si, int) 14462v8qi __builtin_arm_tinsrb (v8qi, int, int) 14463v4hi __builtin_arm_tinsrh (v4hi, int, int) 14464v2si __builtin_arm_tinsrw (v2si, int, int) 14465long long __builtin_arm_tmia (long long, int, int) 14466long long __builtin_arm_tmiabb (long long, int, int) 14467long long __builtin_arm_tmiabt (long long, int, int) 14468long long __builtin_arm_tmiaph (long long, int, int) 14469long long __builtin_arm_tmiatb (long long, int, int) 14470long long __builtin_arm_tmiatt (long long, int, int) 14471int __builtin_arm_tmovmskb (v8qi) 14472int __builtin_arm_tmovmskh (v4hi) 14473int __builtin_arm_tmovmskw (v2si) 14474long long __builtin_arm_waccb (v8qi) 14475long long __builtin_arm_wacch (v4hi) 14476long long __builtin_arm_waccw (v2si) 14477v8qi __builtin_arm_waddb (v8qi, v8qi) 14478v8qi __builtin_arm_waddbss (v8qi, v8qi) 14479v8qi __builtin_arm_waddbus (v8qi, v8qi) 14480v4hi __builtin_arm_waddh (v4hi, v4hi) 14481v4hi __builtin_arm_waddhss (v4hi, v4hi) 14482v4hi __builtin_arm_waddhus (v4hi, v4hi) 14483v2si __builtin_arm_waddw (v2si, v2si) 14484v2si __builtin_arm_waddwss (v2si, v2si) 14485v2si __builtin_arm_waddwus (v2si, v2si) 14486v8qi __builtin_arm_walign (v8qi, v8qi, int) 14487long long __builtin_arm_wand(long long, long long) 14488long long __builtin_arm_wandn (long long, long long) 14489v8qi __builtin_arm_wavg2b (v8qi, v8qi) 14490v8qi __builtin_arm_wavg2br (v8qi, v8qi) 14491v4hi __builtin_arm_wavg2h (v4hi, v4hi) 14492v4hi __builtin_arm_wavg2hr (v4hi, v4hi) 14493v8qi __builtin_arm_wcmpeqb (v8qi, v8qi) 14494v4hi __builtin_arm_wcmpeqh (v4hi, v4hi) 14495v2si __builtin_arm_wcmpeqw (v2si, v2si) 14496v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi) 14497v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi) 14498v2si __builtin_arm_wcmpgtsw (v2si, v2si) 14499v8qi __builtin_arm_wcmpgtub (v8qi, v8qi) 14500v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi) 14501v2si __builtin_arm_wcmpgtuw (v2si, v2si) 14502long long __builtin_arm_wmacs (long long, v4hi, v4hi) 14503long long __builtin_arm_wmacsz (v4hi, v4hi) 14504long long __builtin_arm_wmacu (long long, v4hi, v4hi) 14505long long __builtin_arm_wmacuz (v4hi, v4hi) 14506v4hi __builtin_arm_wmadds (v4hi, v4hi) 14507v4hi __builtin_arm_wmaddu (v4hi, v4hi) 14508v8qi __builtin_arm_wmaxsb (v8qi, v8qi) 14509v4hi __builtin_arm_wmaxsh (v4hi, v4hi) 14510v2si __builtin_arm_wmaxsw (v2si, v2si) 14511v8qi __builtin_arm_wmaxub (v8qi, v8qi) 14512v4hi __builtin_arm_wmaxuh (v4hi, v4hi) 14513v2si __builtin_arm_wmaxuw (v2si, v2si) 14514v8qi __builtin_arm_wminsb (v8qi, v8qi) 14515v4hi __builtin_arm_wminsh (v4hi, v4hi) 14516v2si __builtin_arm_wminsw (v2si, v2si) 14517v8qi __builtin_arm_wminub (v8qi, v8qi) 14518v4hi __builtin_arm_wminuh (v4hi, v4hi) 14519v2si __builtin_arm_wminuw (v2si, v2si) 14520v4hi __builtin_arm_wmulsm (v4hi, v4hi) 14521v4hi __builtin_arm_wmulul (v4hi, v4hi) 14522v4hi __builtin_arm_wmulum (v4hi, v4hi) 14523long long __builtin_arm_wor (long long, long long) 14524v2si __builtin_arm_wpackdss (long long, long long) 14525v2si __builtin_arm_wpackdus (long long, long long) 14526v8qi __builtin_arm_wpackhss (v4hi, v4hi) 14527v8qi __builtin_arm_wpackhus (v4hi, v4hi) 14528v4hi __builtin_arm_wpackwss (v2si, v2si) 14529v4hi __builtin_arm_wpackwus (v2si, v2si) 14530long long __builtin_arm_wrord (long long, long long) 14531long long __builtin_arm_wrordi (long long, int) 14532v4hi __builtin_arm_wrorh (v4hi, long long) 14533v4hi __builtin_arm_wrorhi (v4hi, int) 14534v2si __builtin_arm_wrorw (v2si, long long) 14535v2si __builtin_arm_wrorwi (v2si, int) 14536v2si __builtin_arm_wsadb (v2si, v8qi, v8qi) 14537v2si __builtin_arm_wsadbz (v8qi, v8qi) 14538v2si __builtin_arm_wsadh (v2si, v4hi, v4hi) 14539v2si __builtin_arm_wsadhz (v4hi, v4hi) 14540v4hi __builtin_arm_wshufh (v4hi, int) 14541long long __builtin_arm_wslld (long long, long long) 14542long long __builtin_arm_wslldi (long long, int) 14543v4hi __builtin_arm_wsllh (v4hi, long long) 14544v4hi __builtin_arm_wsllhi (v4hi, int) 14545v2si __builtin_arm_wsllw (v2si, long long) 14546v2si __builtin_arm_wsllwi (v2si, int) 14547long long __builtin_arm_wsrad (long long, long long) 14548long long __builtin_arm_wsradi (long long, int) 14549v4hi __builtin_arm_wsrah (v4hi, long long) 14550v4hi __builtin_arm_wsrahi (v4hi, int) 14551v2si __builtin_arm_wsraw (v2si, long long) 14552v2si __builtin_arm_wsrawi (v2si, int) 14553long long __builtin_arm_wsrld (long long, long long) 14554long long __builtin_arm_wsrldi (long long, int) 14555v4hi __builtin_arm_wsrlh (v4hi, long long) 14556v4hi __builtin_arm_wsrlhi (v4hi, int) 14557v2si __builtin_arm_wsrlw (v2si, long long) 14558v2si __builtin_arm_wsrlwi (v2si, int) 14559v8qi __builtin_arm_wsubb (v8qi, v8qi) 14560v8qi __builtin_arm_wsubbss (v8qi, v8qi) 14561v8qi __builtin_arm_wsubbus (v8qi, v8qi) 14562v4hi __builtin_arm_wsubh (v4hi, v4hi) 14563v4hi __builtin_arm_wsubhss (v4hi, v4hi) 14564v4hi __builtin_arm_wsubhus (v4hi, v4hi) 14565v2si __builtin_arm_wsubw (v2si, v2si) 14566v2si __builtin_arm_wsubwss (v2si, v2si) 14567v2si __builtin_arm_wsubwus (v2si, v2si) 14568v4hi __builtin_arm_wunpckehsb (v8qi) 14569v2si __builtin_arm_wunpckehsh (v4hi) 14570long long __builtin_arm_wunpckehsw (v2si) 14571v4hi __builtin_arm_wunpckehub (v8qi) 14572v2si __builtin_arm_wunpckehuh (v4hi) 14573long long __builtin_arm_wunpckehuw (v2si) 14574v4hi __builtin_arm_wunpckelsb (v8qi) 14575v2si __builtin_arm_wunpckelsh (v4hi) 14576long long __builtin_arm_wunpckelsw (v2si) 14577v4hi __builtin_arm_wunpckelub (v8qi) 14578v2si __builtin_arm_wunpckeluh (v4hi) 14579long long __builtin_arm_wunpckeluw (v2si) 14580v8qi __builtin_arm_wunpckihb (v8qi, v8qi) 14581v4hi __builtin_arm_wunpckihh (v4hi, v4hi) 14582v2si __builtin_arm_wunpckihw (v2si, v2si) 14583v8qi __builtin_arm_wunpckilb (v8qi, v8qi) 14584v4hi __builtin_arm_wunpckilh (v4hi, v4hi) 14585v2si __builtin_arm_wunpckilw (v2si, v2si) 14586long long __builtin_arm_wxor (long long, long long) 14587long long __builtin_arm_wzero () 14588@end smallexample 14589 14590 14591@node ARM C Language Extensions (ACLE) 14592@subsection ARM C Language Extensions (ACLE) 14593 14594GCC implements extensions for C as described in the ARM C Language 14595Extensions (ACLE) specification, which can be found at 14596@uref{https://developer.arm.com/documentation/ihi0053/latest/}. 14597 14598As a part of ACLE, GCC implements extensions for Advanced SIMD as described in 14599the ARM C Language Extensions Specification. The complete list of Advanced SIMD 14600intrinsics can be found at 14601@uref{https://developer.arm.com/documentation/ihi0073/latest/}. 14602The built-in intrinsics for the Advanced SIMD extension are available when 14603NEON is enabled. 14604 14605Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both 14606back ends support CRC32 intrinsics and the ARM back end supports the 14607Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit 14608floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1. 14609AArch64's back end does not have support for 16-bit floating point Advanced SIMD 14610intrinsics yet. 14611 14612See @ref{ARM Options} and @ref{AArch64 Options} for more information on the 14613availability of extensions. 14614 14615@node ARM Floating Point Status and Control Intrinsics 14616@subsection ARM Floating Point Status and Control Intrinsics 14617 14618These built-in functions are available for the ARM family of 14619processors with floating-point unit. 14620 14621@smallexample 14622unsigned int __builtin_arm_get_fpscr () 14623void __builtin_arm_set_fpscr (unsigned int) 14624@end smallexample 14625 14626@node ARM ARMv8-M Security Extensions 14627@subsection ARM ARMv8-M Security Extensions 14628 14629GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M 14630Security Extensions: Requirements on Development Tools Engineering 14631Specification, which can be found at 14632@uref{https://developer.arm.com/documentation/ecm0359818/latest/}. 14633 14634As part of the Security Extensions GCC implements two new function attributes: 14635@code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}. 14636 14637As part of the Security Extensions GCC implements the intrinsics below. FPTR 14638is used here to mean any function pointer type. 14639 14640@smallexample 14641cmse_address_info_t cmse_TT (void *) 14642cmse_address_info_t cmse_TT_fptr (FPTR) 14643cmse_address_info_t cmse_TTT (void *) 14644cmse_address_info_t cmse_TTT_fptr (FPTR) 14645cmse_address_info_t cmse_TTA (void *) 14646cmse_address_info_t cmse_TTA_fptr (FPTR) 14647cmse_address_info_t cmse_TTAT (void *) 14648cmse_address_info_t cmse_TTAT_fptr (FPTR) 14649void * cmse_check_address_range (void *, size_t, int) 14650typeof(p) cmse_nsfptr_create (FPTR p) 14651intptr_t cmse_is_nsfptr (FPTR) 14652int cmse_nonsecure_caller (void) 14653@end smallexample 14654 14655@node AVR Built-in Functions 14656@subsection AVR Built-in Functions 14657 14658For each built-in function for AVR, there is an equally named, 14659uppercase built-in macro defined. That way users can easily query if 14660or if not a specific built-in is implemented or not. For example, if 14661@code{__builtin_avr_nop} is available the macro 14662@code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise. 14663 14664@table @code 14665 14666@item void __builtin_avr_nop (void) 14667@itemx void __builtin_avr_sei (void) 14668@itemx void __builtin_avr_cli (void) 14669@itemx void __builtin_avr_sleep (void) 14670@itemx void __builtin_avr_wdr (void) 14671@itemx unsigned char __builtin_avr_swap (unsigned char) 14672@itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char) 14673@itemx int __builtin_avr_fmuls (char, char) 14674@itemx int __builtin_avr_fmulsu (char, unsigned char) 14675These built-in functions map to the respective machine 14676instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep}, 14677@code{wdr}, @code{swap}, @code{fmul}, @code{fmuls} 14678resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented 14679as library call if no hardware multiplier is available. 14680 14681@item void __builtin_avr_delay_cycles (unsigned long ticks) 14682Delay execution for @var{ticks} cycles. Note that this 14683built-in does not take into account the effect of interrupts that 14684might increase delay time. @var{ticks} must be a compile-time 14685integer constant; delays with a variable number of cycles are not supported. 14686 14687@item char __builtin_avr_flash_segment (const __memx void*) 14688This built-in takes a byte address to the 24-bit 14689@ref{AVR Named Address Spaces,address space} @code{__memx} and returns 14690the number of the flash segment (the 64 KiB chunk) where the address 14691points to. Counting starts at @code{0}. 14692If the address does not point to flash memory, return @code{-1}. 14693 14694@item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val) 14695Insert bits from @var{bits} into @var{val} and return the resulting 14696value. The nibbles of @var{map} determine how the insertion is 14697performed: Let @var{X} be the @var{n}-th nibble of @var{map} 14698@enumerate 14699@item If @var{X} is @code{0xf}, 14700then the @var{n}-th bit of @var{val} is returned unaltered. 14701 14702@item If X is in the range 0@dots{}7, 14703then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits} 14704 14705@item If X is in the range 8@dots{}@code{0xe}, 14706then the @var{n}-th result bit is undefined. 14707@end enumerate 14708 14709@noindent 14710One typical use case for this built-in is adjusting input and 14711output values to non-contiguous port layouts. Some examples: 14712 14713@smallexample 14714// same as val, bits is unused 14715__builtin_avr_insert_bits (0xffffffff, bits, val) 14716@end smallexample 14717 14718@smallexample 14719// same as bits, val is unused 14720__builtin_avr_insert_bits (0x76543210, bits, val) 14721@end smallexample 14722 14723@smallexample 14724// same as rotating bits by 4 14725__builtin_avr_insert_bits (0x32107654, bits, 0) 14726@end smallexample 14727 14728@smallexample 14729// high nibble of result is the high nibble of val 14730// low nibble of result is the low nibble of bits 14731__builtin_avr_insert_bits (0xffff3210, bits, val) 14732@end smallexample 14733 14734@smallexample 14735// reverse the bit order of bits 14736__builtin_avr_insert_bits (0x01234567, bits, 0) 14737@end smallexample 14738 14739@item void __builtin_avr_nops (unsigned count) 14740Insert @var{count} @code{NOP} instructions. 14741The number of instructions must be a compile-time integer constant. 14742 14743@end table 14744 14745@noindent 14746There are many more AVR-specific built-in functions that are used to 14747implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of 14748section 7.18a.6. You don't need to use these built-ins directly. 14749Instead, use the declarations as supplied by the @code{stdfix.h} header 14750with GNU-C99: 14751 14752@smallexample 14753#include <stdfix.h> 14754 14755// Re-interpret the bit representation of unsigned 16-bit 14756// integer @var{uval} as Q-format 0.16 value. 14757unsigned fract get_bits (uint_ur_t uval) 14758@{ 14759 return urbits (uval); 14760@} 14761@end smallexample 14762 14763@node Blackfin Built-in Functions 14764@subsection Blackfin Built-in Functions 14765 14766Currently, there are two Blackfin-specific built-in functions. These are 14767used for generating @code{CSYNC} and @code{SSYNC} machine insns without 14768using inline assembly; by using these built-in functions the compiler can 14769automatically add workarounds for hardware errata involving these 14770instructions. These functions are named as follows: 14771 14772@smallexample 14773void __builtin_bfin_csync (void) 14774void __builtin_bfin_ssync (void) 14775@end smallexample 14776 14777@node BPF Built-in Functions 14778@subsection BPF Built-in Functions 14779 14780The following built-in functions are available for eBPF targets. 14781 14782@deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_byte (unsigned long long @var{offset}) 14783Load a byte from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. 14784@end deftypefn 14785 14786@deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_half (unsigned long long @var{offset}) 14787Load 16-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. 14788@end deftypefn 14789 14790@deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_word (unsigned long long @var{offset}) 14791Load 32-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. 14792@end deftypefn 14793 14794@node FR-V Built-in Functions 14795@subsection FR-V Built-in Functions 14796 14797GCC provides many FR-V-specific built-in functions. In general, 14798these functions are intended to be compatible with those described 14799by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu 14800Semiconductor}. The two exceptions are @code{__MDUNPACKH} and 14801@code{__MBTOHE}, the GCC forms of which pass 128-bit values by 14802pointer rather than by value. 14803 14804Most of the functions are named after specific FR-V instructions. 14805Such functions are said to be ``directly mapped'' and are summarized 14806here in tabular form. 14807 14808@menu 14809* Argument Types:: 14810* Directly-mapped Integer Functions:: 14811* Directly-mapped Media Functions:: 14812* Raw read/write Functions:: 14813* Other Built-in Functions:: 14814@end menu 14815 14816@node Argument Types 14817@subsubsection Argument Types 14818 14819The arguments to the built-in functions can be divided into three groups: 14820register numbers, compile-time constants and run-time values. In order 14821to make this classification clear at a glance, the arguments and return 14822values are given the following pseudo types: 14823 14824@multitable @columnfractions .20 .30 .15 .35 14825@item Pseudo type @tab Real C type @tab Constant? @tab Description 14826@item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword 14827@item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word 14828@item @code{sw1} @tab @code{int} @tab No @tab a signed word 14829@item @code{uw2} @tab @code{unsigned long long} @tab No 14830@tab an unsigned doubleword 14831@item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword 14832@item @code{const} @tab @code{int} @tab Yes @tab an integer constant 14833@item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number 14834@item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number 14835@end multitable 14836 14837These pseudo types are not defined by GCC, they are simply a notational 14838convenience used in this manual. 14839 14840Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2} 14841and @code{sw2} are evaluated at run time. They correspond to 14842register operands in the underlying FR-V instructions. 14843 14844@code{const} arguments represent immediate operands in the underlying 14845FR-V instructions. They must be compile-time constants. 14846 14847@code{acc} arguments are evaluated at compile time and specify the number 14848of an accumulator register. For example, an @code{acc} argument of 2 14849selects the ACC2 register. 14850 14851@code{iacc} arguments are similar to @code{acc} arguments but specify the 14852number of an IACC register. See @pxref{Other Built-in Functions} 14853for more details. 14854 14855@node Directly-mapped Integer Functions 14856@subsubsection Directly-Mapped Integer Functions 14857 14858The functions listed below map directly to FR-V I-type instructions. 14859 14860@multitable @columnfractions .45 .32 .23 14861@item Function prototype @tab Example usage @tab Assembly output 14862@item @code{sw1 __ADDSS (sw1, sw1)} 14863@tab @code{@var{c} = __ADDSS (@var{a}, @var{b})} 14864@tab @code{ADDSS @var{a},@var{b},@var{c}} 14865@item @code{sw1 __SCAN (sw1, sw1)} 14866@tab @code{@var{c} = __SCAN (@var{a}, @var{b})} 14867@tab @code{SCAN @var{a},@var{b},@var{c}} 14868@item @code{sw1 __SCUTSS (sw1)} 14869@tab @code{@var{b} = __SCUTSS (@var{a})} 14870@tab @code{SCUTSS @var{a},@var{b}} 14871@item @code{sw1 __SLASS (sw1, sw1)} 14872@tab @code{@var{c} = __SLASS (@var{a}, @var{b})} 14873@tab @code{SLASS @var{a},@var{b},@var{c}} 14874@item @code{void __SMASS (sw1, sw1)} 14875@tab @code{__SMASS (@var{a}, @var{b})} 14876@tab @code{SMASS @var{a},@var{b}} 14877@item @code{void __SMSSS (sw1, sw1)} 14878@tab @code{__SMSSS (@var{a}, @var{b})} 14879@tab @code{SMSSS @var{a},@var{b}} 14880@item @code{void __SMU (sw1, sw1)} 14881@tab @code{__SMU (@var{a}, @var{b})} 14882@tab @code{SMU @var{a},@var{b}} 14883@item @code{sw2 __SMUL (sw1, sw1)} 14884@tab @code{@var{c} = __SMUL (@var{a}, @var{b})} 14885@tab @code{SMUL @var{a},@var{b},@var{c}} 14886@item @code{sw1 __SUBSS (sw1, sw1)} 14887@tab @code{@var{c} = __SUBSS (@var{a}, @var{b})} 14888@tab @code{SUBSS @var{a},@var{b},@var{c}} 14889@item @code{uw2 __UMUL (uw1, uw1)} 14890@tab @code{@var{c} = __UMUL (@var{a}, @var{b})} 14891@tab @code{UMUL @var{a},@var{b},@var{c}} 14892@end multitable 14893 14894@node Directly-mapped Media Functions 14895@subsubsection Directly-Mapped Media Functions 14896 14897The functions listed below map directly to FR-V M-type instructions. 14898 14899@multitable @columnfractions .45 .32 .23 14900@item Function prototype @tab Example usage @tab Assembly output 14901@item @code{uw1 __MABSHS (sw1)} 14902@tab @code{@var{b} = __MABSHS (@var{a})} 14903@tab @code{MABSHS @var{a},@var{b}} 14904@item @code{void __MADDACCS (acc, acc)} 14905@tab @code{__MADDACCS (@var{b}, @var{a})} 14906@tab @code{MADDACCS @var{a},@var{b}} 14907@item @code{sw1 __MADDHSS (sw1, sw1)} 14908@tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})} 14909@tab @code{MADDHSS @var{a},@var{b},@var{c}} 14910@item @code{uw1 __MADDHUS (uw1, uw1)} 14911@tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})} 14912@tab @code{MADDHUS @var{a},@var{b},@var{c}} 14913@item @code{uw1 __MAND (uw1, uw1)} 14914@tab @code{@var{c} = __MAND (@var{a}, @var{b})} 14915@tab @code{MAND @var{a},@var{b},@var{c}} 14916@item @code{void __MASACCS (acc, acc)} 14917@tab @code{__MASACCS (@var{b}, @var{a})} 14918@tab @code{MASACCS @var{a},@var{b}} 14919@item @code{uw1 __MAVEH (uw1, uw1)} 14920@tab @code{@var{c} = __MAVEH (@var{a}, @var{b})} 14921@tab @code{MAVEH @var{a},@var{b},@var{c}} 14922@item @code{uw2 __MBTOH (uw1)} 14923@tab @code{@var{b} = __MBTOH (@var{a})} 14924@tab @code{MBTOH @var{a},@var{b}} 14925@item @code{void __MBTOHE (uw1 *, uw1)} 14926@tab @code{__MBTOHE (&@var{b}, @var{a})} 14927@tab @code{MBTOHE @var{a},@var{b}} 14928@item @code{void __MCLRACC (acc)} 14929@tab @code{__MCLRACC (@var{a})} 14930@tab @code{MCLRACC @var{a}} 14931@item @code{void __MCLRACCA (void)} 14932@tab @code{__MCLRACCA ()} 14933@tab @code{MCLRACCA} 14934@item @code{uw1 __Mcop1 (uw1, uw1)} 14935@tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})} 14936@tab @code{Mcop1 @var{a},@var{b},@var{c}} 14937@item @code{uw1 __Mcop2 (uw1, uw1)} 14938@tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})} 14939@tab @code{Mcop2 @var{a},@var{b},@var{c}} 14940@item @code{uw1 __MCPLHI (uw2, const)} 14941@tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})} 14942@tab @code{MCPLHI @var{a},#@var{b},@var{c}} 14943@item @code{uw1 __MCPLI (uw2, const)} 14944@tab @code{@var{c} = __MCPLI (@var{a}, @var{b})} 14945@tab @code{MCPLI @var{a},#@var{b},@var{c}} 14946@item @code{void __MCPXIS (acc, sw1, sw1)} 14947@tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})} 14948@tab @code{MCPXIS @var{a},@var{b},@var{c}} 14949@item @code{void __MCPXIU (acc, uw1, uw1)} 14950@tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})} 14951@tab @code{MCPXIU @var{a},@var{b},@var{c}} 14952@item @code{void __MCPXRS (acc, sw1, sw1)} 14953@tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})} 14954@tab @code{MCPXRS @var{a},@var{b},@var{c}} 14955@item @code{void __MCPXRU (acc, uw1, uw1)} 14956@tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})} 14957@tab @code{MCPXRU @var{a},@var{b},@var{c}} 14958@item @code{uw1 __MCUT (acc, uw1)} 14959@tab @code{@var{c} = __MCUT (@var{a}, @var{b})} 14960@tab @code{MCUT @var{a},@var{b},@var{c}} 14961@item @code{uw1 __MCUTSS (acc, sw1)} 14962@tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})} 14963@tab @code{MCUTSS @var{a},@var{b},@var{c}} 14964@item @code{void __MDADDACCS (acc, acc)} 14965@tab @code{__MDADDACCS (@var{b}, @var{a})} 14966@tab @code{MDADDACCS @var{a},@var{b}} 14967@item @code{void __MDASACCS (acc, acc)} 14968@tab @code{__MDASACCS (@var{b}, @var{a})} 14969@tab @code{MDASACCS @var{a},@var{b}} 14970@item @code{uw2 __MDCUTSSI (acc, const)} 14971@tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})} 14972@tab @code{MDCUTSSI @var{a},#@var{b},@var{c}} 14973@item @code{uw2 __MDPACKH (uw2, uw2)} 14974@tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})} 14975@tab @code{MDPACKH @var{a},@var{b},@var{c}} 14976@item @code{uw2 __MDROTLI (uw2, const)} 14977@tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})} 14978@tab @code{MDROTLI @var{a},#@var{b},@var{c}} 14979@item @code{void __MDSUBACCS (acc, acc)} 14980@tab @code{__MDSUBACCS (@var{b}, @var{a})} 14981@tab @code{MDSUBACCS @var{a},@var{b}} 14982@item @code{void __MDUNPACKH (uw1 *, uw2)} 14983@tab @code{__MDUNPACKH (&@var{b}, @var{a})} 14984@tab @code{MDUNPACKH @var{a},@var{b}} 14985@item @code{uw2 __MEXPDHD (uw1, const)} 14986@tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})} 14987@tab @code{MEXPDHD @var{a},#@var{b},@var{c}} 14988@item @code{uw1 __MEXPDHW (uw1, const)} 14989@tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})} 14990@tab @code{MEXPDHW @var{a},#@var{b},@var{c}} 14991@item @code{uw1 __MHDSETH (uw1, const)} 14992@tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})} 14993@tab @code{MHDSETH @var{a},#@var{b},@var{c}} 14994@item @code{sw1 __MHDSETS (const)} 14995@tab @code{@var{b} = __MHDSETS (@var{a})} 14996@tab @code{MHDSETS #@var{a},@var{b}} 14997@item @code{uw1 __MHSETHIH (uw1, const)} 14998@tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})} 14999@tab @code{MHSETHIH #@var{a},@var{b}} 15000@item @code{sw1 __MHSETHIS (sw1, const)} 15001@tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})} 15002@tab @code{MHSETHIS #@var{a},@var{b}} 15003@item @code{uw1 __MHSETLOH (uw1, const)} 15004@tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})} 15005@tab @code{MHSETLOH #@var{a},@var{b}} 15006@item @code{sw1 __MHSETLOS (sw1, const)} 15007@tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})} 15008@tab @code{MHSETLOS #@var{a},@var{b}} 15009@item @code{uw1 __MHTOB (uw2)} 15010@tab @code{@var{b} = __MHTOB (@var{a})} 15011@tab @code{MHTOB @var{a},@var{b}} 15012@item @code{void __MMACHS (acc, sw1, sw1)} 15013@tab @code{__MMACHS (@var{c}, @var{a}, @var{b})} 15014@tab @code{MMACHS @var{a},@var{b},@var{c}} 15015@item @code{void __MMACHU (acc, uw1, uw1)} 15016@tab @code{__MMACHU (@var{c}, @var{a}, @var{b})} 15017@tab @code{MMACHU @var{a},@var{b},@var{c}} 15018@item @code{void __MMRDHS (acc, sw1, sw1)} 15019@tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})} 15020@tab @code{MMRDHS @var{a},@var{b},@var{c}} 15021@item @code{void __MMRDHU (acc, uw1, uw1)} 15022@tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})} 15023@tab @code{MMRDHU @var{a},@var{b},@var{c}} 15024@item @code{void __MMULHS (acc, sw1, sw1)} 15025@tab @code{__MMULHS (@var{c}, @var{a}, @var{b})} 15026@tab @code{MMULHS @var{a},@var{b},@var{c}} 15027@item @code{void __MMULHU (acc, uw1, uw1)} 15028@tab @code{__MMULHU (@var{c}, @var{a}, @var{b})} 15029@tab @code{MMULHU @var{a},@var{b},@var{c}} 15030@item @code{void __MMULXHS (acc, sw1, sw1)} 15031@tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})} 15032@tab @code{MMULXHS @var{a},@var{b},@var{c}} 15033@item @code{void __MMULXHU (acc, uw1, uw1)} 15034@tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})} 15035@tab @code{MMULXHU @var{a},@var{b},@var{c}} 15036@item @code{uw1 __MNOT (uw1)} 15037@tab @code{@var{b} = __MNOT (@var{a})} 15038@tab @code{MNOT @var{a},@var{b}} 15039@item @code{uw1 __MOR (uw1, uw1)} 15040@tab @code{@var{c} = __MOR (@var{a}, @var{b})} 15041@tab @code{MOR @var{a},@var{b},@var{c}} 15042@item @code{uw1 __MPACKH (uh, uh)} 15043@tab @code{@var{c} = __MPACKH (@var{a}, @var{b})} 15044@tab @code{MPACKH @var{a},@var{b},@var{c}} 15045@item @code{sw2 __MQADDHSS (sw2, sw2)} 15046@tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})} 15047@tab @code{MQADDHSS @var{a},@var{b},@var{c}} 15048@item @code{uw2 __MQADDHUS (uw2, uw2)} 15049@tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})} 15050@tab @code{MQADDHUS @var{a},@var{b},@var{c}} 15051@item @code{void __MQCPXIS (acc, sw2, sw2)} 15052@tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})} 15053@tab @code{MQCPXIS @var{a},@var{b},@var{c}} 15054@item @code{void __MQCPXIU (acc, uw2, uw2)} 15055@tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})} 15056@tab @code{MQCPXIU @var{a},@var{b},@var{c}} 15057@item @code{void __MQCPXRS (acc, sw2, sw2)} 15058@tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})} 15059@tab @code{MQCPXRS @var{a},@var{b},@var{c}} 15060@item @code{void __MQCPXRU (acc, uw2, uw2)} 15061@tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})} 15062@tab @code{MQCPXRU @var{a},@var{b},@var{c}} 15063@item @code{sw2 __MQLCLRHS (sw2, sw2)} 15064@tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})} 15065@tab @code{MQLCLRHS @var{a},@var{b},@var{c}} 15066@item @code{sw2 __MQLMTHS (sw2, sw2)} 15067@tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})} 15068@tab @code{MQLMTHS @var{a},@var{b},@var{c}} 15069@item @code{void __MQMACHS (acc, sw2, sw2)} 15070@tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})} 15071@tab @code{MQMACHS @var{a},@var{b},@var{c}} 15072@item @code{void __MQMACHU (acc, uw2, uw2)} 15073@tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})} 15074@tab @code{MQMACHU @var{a},@var{b},@var{c}} 15075@item @code{void __MQMACXHS (acc, sw2, sw2)} 15076@tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})} 15077@tab @code{MQMACXHS @var{a},@var{b},@var{c}} 15078@item @code{void __MQMULHS (acc, sw2, sw2)} 15079@tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})} 15080@tab @code{MQMULHS @var{a},@var{b},@var{c}} 15081@item @code{void __MQMULHU (acc, uw2, uw2)} 15082@tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})} 15083@tab @code{MQMULHU @var{a},@var{b},@var{c}} 15084@item @code{void __MQMULXHS (acc, sw2, sw2)} 15085@tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})} 15086@tab @code{MQMULXHS @var{a},@var{b},@var{c}} 15087@item @code{void __MQMULXHU (acc, uw2, uw2)} 15088@tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})} 15089@tab @code{MQMULXHU @var{a},@var{b},@var{c}} 15090@item @code{sw2 __MQSATHS (sw2, sw2)} 15091@tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})} 15092@tab @code{MQSATHS @var{a},@var{b},@var{c}} 15093@item @code{uw2 __MQSLLHI (uw2, int)} 15094@tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})} 15095@tab @code{MQSLLHI @var{a},@var{b},@var{c}} 15096@item @code{sw2 __MQSRAHI (sw2, int)} 15097@tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})} 15098@tab @code{MQSRAHI @var{a},@var{b},@var{c}} 15099@item @code{sw2 __MQSUBHSS (sw2, sw2)} 15100@tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})} 15101@tab @code{MQSUBHSS @var{a},@var{b},@var{c}} 15102@item @code{uw2 __MQSUBHUS (uw2, uw2)} 15103@tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})} 15104@tab @code{MQSUBHUS @var{a},@var{b},@var{c}} 15105@item @code{void __MQXMACHS (acc, sw2, sw2)} 15106@tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})} 15107@tab @code{MQXMACHS @var{a},@var{b},@var{c}} 15108@item @code{void __MQXMACXHS (acc, sw2, sw2)} 15109@tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})} 15110@tab @code{MQXMACXHS @var{a},@var{b},@var{c}} 15111@item @code{uw1 __MRDACC (acc)} 15112@tab @code{@var{b} = __MRDACC (@var{a})} 15113@tab @code{MRDACC @var{a},@var{b}} 15114@item @code{uw1 __MRDACCG (acc)} 15115@tab @code{@var{b} = __MRDACCG (@var{a})} 15116@tab @code{MRDACCG @var{a},@var{b}} 15117@item @code{uw1 __MROTLI (uw1, const)} 15118@tab @code{@var{c} = __MROTLI (@var{a}, @var{b})} 15119@tab @code{MROTLI @var{a},#@var{b},@var{c}} 15120@item @code{uw1 __MROTRI (uw1, const)} 15121@tab @code{@var{c} = __MROTRI (@var{a}, @var{b})} 15122@tab @code{MROTRI @var{a},#@var{b},@var{c}} 15123@item @code{sw1 __MSATHS (sw1, sw1)} 15124@tab @code{@var{c} = __MSATHS (@var{a}, @var{b})} 15125@tab @code{MSATHS @var{a},@var{b},@var{c}} 15126@item @code{uw1 __MSATHU (uw1, uw1)} 15127@tab @code{@var{c} = __MSATHU (@var{a}, @var{b})} 15128@tab @code{MSATHU @var{a},@var{b},@var{c}} 15129@item @code{uw1 __MSLLHI (uw1, const)} 15130@tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})} 15131@tab @code{MSLLHI @var{a},#@var{b},@var{c}} 15132@item @code{sw1 __MSRAHI (sw1, const)} 15133@tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})} 15134@tab @code{MSRAHI @var{a},#@var{b},@var{c}} 15135@item @code{uw1 __MSRLHI (uw1, const)} 15136@tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})} 15137@tab @code{MSRLHI @var{a},#@var{b},@var{c}} 15138@item @code{void __MSUBACCS (acc, acc)} 15139@tab @code{__MSUBACCS (@var{b}, @var{a})} 15140@tab @code{MSUBACCS @var{a},@var{b}} 15141@item @code{sw1 __MSUBHSS (sw1, sw1)} 15142@tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})} 15143@tab @code{MSUBHSS @var{a},@var{b},@var{c}} 15144@item @code{uw1 __MSUBHUS (uw1, uw1)} 15145@tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})} 15146@tab @code{MSUBHUS @var{a},@var{b},@var{c}} 15147@item @code{void __MTRAP (void)} 15148@tab @code{__MTRAP ()} 15149@tab @code{MTRAP} 15150@item @code{uw2 __MUNPACKH (uw1)} 15151@tab @code{@var{b} = __MUNPACKH (@var{a})} 15152@tab @code{MUNPACKH @var{a},@var{b}} 15153@item @code{uw1 __MWCUT (uw2, uw1)} 15154@tab @code{@var{c} = __MWCUT (@var{a}, @var{b})} 15155@tab @code{MWCUT @var{a},@var{b},@var{c}} 15156@item @code{void __MWTACC (acc, uw1)} 15157@tab @code{__MWTACC (@var{b}, @var{a})} 15158@tab @code{MWTACC @var{a},@var{b}} 15159@item @code{void __MWTACCG (acc, uw1)} 15160@tab @code{__MWTACCG (@var{b}, @var{a})} 15161@tab @code{MWTACCG @var{a},@var{b}} 15162@item @code{uw1 __MXOR (uw1, uw1)} 15163@tab @code{@var{c} = __MXOR (@var{a}, @var{b})} 15164@tab @code{MXOR @var{a},@var{b},@var{c}} 15165@end multitable 15166 15167@node Raw read/write Functions 15168@subsubsection Raw Read/Write Functions 15169 15170This sections describes built-in functions related to read and write 15171instructions to access memory. These functions generate 15172@code{membar} instructions to flush the I/O load and stores where 15173appropriate, as described in Fujitsu's manual described above. 15174 15175@table @code 15176 15177@item unsigned char __builtin_read8 (void *@var{data}) 15178@item unsigned short __builtin_read16 (void *@var{data}) 15179@item unsigned long __builtin_read32 (void *@var{data}) 15180@item unsigned long long __builtin_read64 (void *@var{data}) 15181 15182@item void __builtin_write8 (void *@var{data}, unsigned char @var{datum}) 15183@item void __builtin_write16 (void *@var{data}, unsigned short @var{datum}) 15184@item void __builtin_write32 (void *@var{data}, unsigned long @var{datum}) 15185@item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum}) 15186@end table 15187 15188@node Other Built-in Functions 15189@subsubsection Other Built-in Functions 15190 15191This section describes built-in functions that are not named after 15192a specific FR-V instruction. 15193 15194@table @code 15195@item sw2 __IACCreadll (iacc @var{reg}) 15196Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved 15197for future expansion and must be 0. 15198 15199@item sw1 __IACCreadl (iacc @var{reg}) 15200Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1. 15201Other values of @var{reg} are rejected as invalid. 15202 15203@item void __IACCsetll (iacc @var{reg}, sw2 @var{x}) 15204Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument 15205is reserved for future expansion and must be 0. 15206 15207@item void __IACCsetl (iacc @var{reg}, sw1 @var{x}) 15208Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg} 15209is 1. Other values of @var{reg} are rejected as invalid. 15210 15211@item void __data_prefetch0 (const void *@var{x}) 15212Use the @code{dcpl} instruction to load the contents of address @var{x} 15213into the data cache. 15214 15215@item void __data_prefetch (const void *@var{x}) 15216Use the @code{nldub} instruction to load the contents of address @var{x} 15217into the data cache. The instruction is issued in slot I1@. 15218@end table 15219 15220@node MIPS DSP Built-in Functions 15221@subsection MIPS DSP Built-in Functions 15222 15223The MIPS DSP Application-Specific Extension (ASE) includes new 15224instructions that are designed to improve the performance of DSP and 15225media applications. It provides instructions that operate on packed 152268-bit/16-bit integer data, Q7, Q15 and Q31 fractional data. 15227 15228GCC supports MIPS DSP operations using both the generic 15229vector extensions (@pxref{Vector Extensions}) and a collection of 15230MIPS-specific built-in functions. Both kinds of support are 15231enabled by the @option{-mdsp} command-line option. 15232 15233Revision 2 of the ASE was introduced in the second half of 2006. 15234This revision adds extra instructions to the original ASE, but is 15235otherwise backwards-compatible with it. You can select revision 2 15236using the command-line option @option{-mdspr2}; this option implies 15237@option{-mdsp}. 15238 15239The SCOUNT and POS bits of the DSP control register are global. The 15240WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and 15241POS bits. During optimization, the compiler does not delete these 15242instructions and it does not delete calls to functions containing 15243these instructions. 15244 15245At present, GCC only provides support for operations on 32-bit 15246vectors. The vector type associated with 8-bit integer data is 15247usually called @code{v4i8}, the vector type associated with Q7 15248is usually called @code{v4q7}, the vector type associated with 16-bit 15249integer data is usually called @code{v2i16}, and the vector type 15250associated with Q15 is usually called @code{v2q15}. They can be 15251defined in C as follows: 15252 15253@smallexample 15254typedef signed char v4i8 __attribute__ ((vector_size(4))); 15255typedef signed char v4q7 __attribute__ ((vector_size(4))); 15256typedef short v2i16 __attribute__ ((vector_size(4))); 15257typedef short v2q15 __attribute__ ((vector_size(4))); 15258@end smallexample 15259 15260@code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are 15261initialized in the same way as aggregates. For example: 15262 15263@smallexample 15264v4i8 a = @{1, 2, 3, 4@}; 15265v4i8 b; 15266b = (v4i8) @{5, 6, 7, 8@}; 15267 15268v2q15 c = @{0x0fcb, 0x3a75@}; 15269v2q15 d; 15270d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; 15271@end smallexample 15272 15273@emph{Note:} The CPU's endianness determines the order in which values 15274are packed. On little-endian targets, the first value is the least 15275significant and the last value is the most significant. The opposite 15276order applies to big-endian targets. For example, the code above 15277sets the lowest byte of @code{a} to @code{1} on little-endian targets 15278and @code{4} on big-endian targets. 15279 15280@emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer 15281representation. As shown in this example, the integer representation 15282of a Q7 value can be obtained by multiplying the fractional value by 15283@code{0x1.0p7}. The equivalent for Q15 values is to multiply by 15284@code{0x1.0p15}. The equivalent for Q31 values is to multiply by 15285@code{0x1.0p31}. 15286 15287The table below lists the @code{v4i8} and @code{v2q15} operations for which 15288hardware support exists. @code{a} and @code{b} are @code{v4i8} values, 15289and @code{c} and @code{d} are @code{v2q15} values. 15290 15291@multitable @columnfractions .50 .50 15292@item C code @tab MIPS instruction 15293@item @code{a + b} @tab @code{addu.qb} 15294@item @code{c + d} @tab @code{addq.ph} 15295@item @code{a - b} @tab @code{subu.qb} 15296@item @code{c - d} @tab @code{subq.ph} 15297@end multitable 15298 15299The table below lists the @code{v2i16} operation for which 15300hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are 15301@code{v2i16} values. 15302 15303@multitable @columnfractions .50 .50 15304@item C code @tab MIPS instruction 15305@item @code{e * f} @tab @code{mul.ph} 15306@end multitable 15307 15308It is easier to describe the DSP built-in functions if we first define 15309the following types: 15310 15311@smallexample 15312typedef int q31; 15313typedef int i32; 15314typedef unsigned int ui32; 15315typedef long long a64; 15316@end smallexample 15317 15318@code{q31} and @code{i32} are actually the same as @code{int}, but we 15319use @code{q31} to indicate a Q31 fractional value and @code{i32} to 15320indicate a 32-bit integer value. Similarly, @code{a64} is the same as 15321@code{long long}, but we use @code{a64} to indicate values that are 15322placed in one of the four DSP accumulators (@code{$ac0}, 15323@code{$ac1}, @code{$ac2} or @code{$ac3}). 15324 15325Also, some built-in functions prefer or require immediate numbers as 15326parameters, because the corresponding DSP instructions accept both immediate 15327numbers and register operands, or accept immediate numbers only. The 15328immediate parameters are listed as follows. 15329 15330@smallexample 15331imm0_3: 0 to 3. 15332imm0_7: 0 to 7. 15333imm0_15: 0 to 15. 15334imm0_31: 0 to 31. 15335imm0_63: 0 to 63. 15336imm0_255: 0 to 255. 15337imm_n32_31: -32 to 31. 15338imm_n512_511: -512 to 511. 15339@end smallexample 15340 15341The following built-in functions map directly to a particular MIPS DSP 15342instruction. Please refer to the architecture specification 15343for details on what each instruction does. 15344 15345@smallexample 15346v2q15 __builtin_mips_addq_ph (v2q15, v2q15) 15347v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15) 15348q31 __builtin_mips_addq_s_w (q31, q31) 15349v4i8 __builtin_mips_addu_qb (v4i8, v4i8) 15350v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8) 15351v2q15 __builtin_mips_subq_ph (v2q15, v2q15) 15352v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15) 15353q31 __builtin_mips_subq_s_w (q31, q31) 15354v4i8 __builtin_mips_subu_qb (v4i8, v4i8) 15355v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8) 15356i32 __builtin_mips_addsc (i32, i32) 15357i32 __builtin_mips_addwc (i32, i32) 15358i32 __builtin_mips_modsub (i32, i32) 15359i32 __builtin_mips_raddu_w_qb (v4i8) 15360v2q15 __builtin_mips_absq_s_ph (v2q15) 15361q31 __builtin_mips_absq_s_w (q31) 15362v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15) 15363v2q15 __builtin_mips_precrq_ph_w (q31, q31) 15364v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31) 15365v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15) 15366q31 __builtin_mips_preceq_w_phl (v2q15) 15367q31 __builtin_mips_preceq_w_phr (v2q15) 15368v2q15 __builtin_mips_precequ_ph_qbl (v4i8) 15369v2q15 __builtin_mips_precequ_ph_qbr (v4i8) 15370v2q15 __builtin_mips_precequ_ph_qbla (v4i8) 15371v2q15 __builtin_mips_precequ_ph_qbra (v4i8) 15372v2q15 __builtin_mips_preceu_ph_qbl (v4i8) 15373v2q15 __builtin_mips_preceu_ph_qbr (v4i8) 15374v2q15 __builtin_mips_preceu_ph_qbla (v4i8) 15375v2q15 __builtin_mips_preceu_ph_qbra (v4i8) 15376v4i8 __builtin_mips_shll_qb (v4i8, imm0_7) 15377v4i8 __builtin_mips_shll_qb (v4i8, i32) 15378v2q15 __builtin_mips_shll_ph (v2q15, imm0_15) 15379v2q15 __builtin_mips_shll_ph (v2q15, i32) 15380v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15) 15381v2q15 __builtin_mips_shll_s_ph (v2q15, i32) 15382q31 __builtin_mips_shll_s_w (q31, imm0_31) 15383q31 __builtin_mips_shll_s_w (q31, i32) 15384v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7) 15385v4i8 __builtin_mips_shrl_qb (v4i8, i32) 15386v2q15 __builtin_mips_shra_ph (v2q15, imm0_15) 15387v2q15 __builtin_mips_shra_ph (v2q15, i32) 15388v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15) 15389v2q15 __builtin_mips_shra_r_ph (v2q15, i32) 15390q31 __builtin_mips_shra_r_w (q31, imm0_31) 15391q31 __builtin_mips_shra_r_w (q31, i32) 15392v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15) 15393v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15) 15394v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15) 15395q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15) 15396q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15) 15397a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8) 15398a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8) 15399a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8) 15400a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8) 15401a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15) 15402a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31) 15403a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15) 15404a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31) 15405a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15) 15406a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15) 15407a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15) 15408a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15) 15409a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15) 15410i32 __builtin_mips_bitrev (i32) 15411i32 __builtin_mips_insv (i32, i32) 15412v4i8 __builtin_mips_repl_qb (imm0_255) 15413v4i8 __builtin_mips_repl_qb (i32) 15414v2q15 __builtin_mips_repl_ph (imm_n512_511) 15415v2q15 __builtin_mips_repl_ph (i32) 15416void __builtin_mips_cmpu_eq_qb (v4i8, v4i8) 15417void __builtin_mips_cmpu_lt_qb (v4i8, v4i8) 15418void __builtin_mips_cmpu_le_qb (v4i8, v4i8) 15419i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8) 15420i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8) 15421i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8) 15422void __builtin_mips_cmp_eq_ph (v2q15, v2q15) 15423void __builtin_mips_cmp_lt_ph (v2q15, v2q15) 15424void __builtin_mips_cmp_le_ph (v2q15, v2q15) 15425v4i8 __builtin_mips_pick_qb (v4i8, v4i8) 15426v2q15 __builtin_mips_pick_ph (v2q15, v2q15) 15427v2q15 __builtin_mips_packrl_ph (v2q15, v2q15) 15428i32 __builtin_mips_extr_w (a64, imm0_31) 15429i32 __builtin_mips_extr_w (a64, i32) 15430i32 __builtin_mips_extr_r_w (a64, imm0_31) 15431i32 __builtin_mips_extr_s_h (a64, i32) 15432i32 __builtin_mips_extr_rs_w (a64, imm0_31) 15433i32 __builtin_mips_extr_rs_w (a64, i32) 15434i32 __builtin_mips_extr_s_h (a64, imm0_31) 15435i32 __builtin_mips_extr_r_w (a64, i32) 15436i32 __builtin_mips_extp (a64, imm0_31) 15437i32 __builtin_mips_extp (a64, i32) 15438i32 __builtin_mips_extpdp (a64, imm0_31) 15439i32 __builtin_mips_extpdp (a64, i32) 15440a64 __builtin_mips_shilo (a64, imm_n32_31) 15441a64 __builtin_mips_shilo (a64, i32) 15442a64 __builtin_mips_mthlip (a64, i32) 15443void __builtin_mips_wrdsp (i32, imm0_63) 15444i32 __builtin_mips_rddsp (imm0_63) 15445i32 __builtin_mips_lbux (void *, i32) 15446i32 __builtin_mips_lhx (void *, i32) 15447i32 __builtin_mips_lwx (void *, i32) 15448a64 __builtin_mips_ldx (void *, i32) [MIPS64 only] 15449i32 __builtin_mips_bposge32 (void) 15450a64 __builtin_mips_madd (a64, i32, i32); 15451a64 __builtin_mips_maddu (a64, ui32, ui32); 15452a64 __builtin_mips_msub (a64, i32, i32); 15453a64 __builtin_mips_msubu (a64, ui32, ui32); 15454a64 __builtin_mips_mult (i32, i32); 15455a64 __builtin_mips_multu (ui32, ui32); 15456@end smallexample 15457 15458The following built-in functions map directly to a particular MIPS DSP REV 2 15459instruction. Please refer to the architecture specification 15460for details on what each instruction does. 15461 15462@smallexample 15463v4q7 __builtin_mips_absq_s_qb (v4q7); 15464v2i16 __builtin_mips_addu_ph (v2i16, v2i16); 15465v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16); 15466v4i8 __builtin_mips_adduh_qb (v4i8, v4i8); 15467v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8); 15468i32 __builtin_mips_append (i32, i32, imm0_31); 15469i32 __builtin_mips_balign (i32, i32, imm0_3); 15470i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8); 15471i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8); 15472i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8); 15473a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16); 15474a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16); 15475v2i16 __builtin_mips_mul_ph (v2i16, v2i16); 15476v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16); 15477q31 __builtin_mips_mulq_rs_w (q31, q31); 15478v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15); 15479q31 __builtin_mips_mulq_s_w (q31, q31); 15480a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16); 15481v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16); 15482v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31); 15483v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31); 15484i32 __builtin_mips_prepend (i32, i32, imm0_31); 15485v4i8 __builtin_mips_shra_qb (v4i8, imm0_7); 15486v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7); 15487v4i8 __builtin_mips_shra_qb (v4i8, i32); 15488v4i8 __builtin_mips_shra_r_qb (v4i8, i32); 15489v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15); 15490v2i16 __builtin_mips_shrl_ph (v2i16, i32); 15491v2i16 __builtin_mips_subu_ph (v2i16, v2i16); 15492v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16); 15493v4i8 __builtin_mips_subuh_qb (v4i8, v4i8); 15494v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8); 15495v2q15 __builtin_mips_addqh_ph (v2q15, v2q15); 15496v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15); 15497q31 __builtin_mips_addqh_w (q31, q31); 15498q31 __builtin_mips_addqh_r_w (q31, q31); 15499v2q15 __builtin_mips_subqh_ph (v2q15, v2q15); 15500v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15); 15501q31 __builtin_mips_subqh_w (q31, q31); 15502q31 __builtin_mips_subqh_r_w (q31, q31); 15503a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16); 15504a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16); 15505a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15); 15506a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15); 15507a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15); 15508a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15); 15509@end smallexample 15510 15511 15512@node MIPS Paired-Single Support 15513@subsection MIPS Paired-Single Support 15514 15515The MIPS64 architecture includes a number of instructions that 15516operate on pairs of single-precision floating-point values. 15517Each pair is packed into a 64-bit floating-point register, 15518with one element being designated the ``upper half'' and 15519the other being designated the ``lower half''. 15520 15521GCC supports paired-single operations using both the generic 15522vector extensions (@pxref{Vector Extensions}) and a collection of 15523MIPS-specific built-in functions. Both kinds of support are 15524enabled by the @option{-mpaired-single} command-line option. 15525 15526The vector type associated with paired-single values is usually 15527called @code{v2sf}. It can be defined in C as follows: 15528 15529@smallexample 15530typedef float v2sf __attribute__ ((vector_size (8))); 15531@end smallexample 15532 15533@code{v2sf} values are initialized in the same way as aggregates. 15534For example: 15535 15536@smallexample 15537v2sf a = @{1.5, 9.1@}; 15538v2sf b; 15539float e, f; 15540b = (v2sf) @{e, f@}; 15541@end smallexample 15542 15543@emph{Note:} The CPU's endianness determines which value is stored in 15544the upper half of a register and which value is stored in the lower half. 15545On little-endian targets, the first value is the lower one and the second 15546value is the upper one. The opposite order applies to big-endian targets. 15547For example, the code above sets the lower half of @code{a} to 15548@code{1.5} on little-endian targets and @code{9.1} on big-endian targets. 15549 15550@node MIPS Loongson Built-in Functions 15551@subsection MIPS Loongson Built-in Functions 15552 15553GCC provides intrinsics to access the SIMD instructions provided by the 15554ST Microelectronics Loongson-2E and -2F processors. These intrinsics, 15555available after inclusion of the @code{loongson.h} header file, 15556operate on the following 64-bit vector types: 15557 15558@itemize 15559@item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers; 15560@item @code{uint16x4_t}, a vector of four unsigned 16-bit integers; 15561@item @code{uint32x2_t}, a vector of two unsigned 32-bit integers; 15562@item @code{int8x8_t}, a vector of eight signed 8-bit integers; 15563@item @code{int16x4_t}, a vector of four signed 16-bit integers; 15564@item @code{int32x2_t}, a vector of two signed 32-bit integers. 15565@end itemize 15566 15567The intrinsics provided are listed below; each is named after the 15568machine instruction to which it corresponds, with suffixes added as 15569appropriate to distinguish intrinsics that expand to the same machine 15570instruction yet have different argument types. Refer to the architecture 15571documentation for a description of the functionality of each 15572instruction. 15573 15574@smallexample 15575int16x4_t packsswh (int32x2_t s, int32x2_t t); 15576int8x8_t packsshb (int16x4_t s, int16x4_t t); 15577uint8x8_t packushb (uint16x4_t s, uint16x4_t t); 15578uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t); 15579uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t); 15580uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t); 15581int32x2_t paddw_s (int32x2_t s, int32x2_t t); 15582int16x4_t paddh_s (int16x4_t s, int16x4_t t); 15583int8x8_t paddb_s (int8x8_t s, int8x8_t t); 15584uint64_t paddd_u (uint64_t s, uint64_t t); 15585int64_t paddd_s (int64_t s, int64_t t); 15586int16x4_t paddsh (int16x4_t s, int16x4_t t); 15587int8x8_t paddsb (int8x8_t s, int8x8_t t); 15588uint16x4_t paddush (uint16x4_t s, uint16x4_t t); 15589uint8x8_t paddusb (uint8x8_t s, uint8x8_t t); 15590uint64_t pandn_ud (uint64_t s, uint64_t t); 15591uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t); 15592uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t); 15593uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t); 15594int64_t pandn_sd (int64_t s, int64_t t); 15595int32x2_t pandn_sw (int32x2_t s, int32x2_t t); 15596int16x4_t pandn_sh (int16x4_t s, int16x4_t t); 15597int8x8_t pandn_sb (int8x8_t s, int8x8_t t); 15598uint16x4_t pavgh (uint16x4_t s, uint16x4_t t); 15599uint8x8_t pavgb (uint8x8_t s, uint8x8_t t); 15600uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t); 15601uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t); 15602uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t); 15603int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t); 15604int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t); 15605int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t); 15606uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t); 15607uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t); 15608uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t); 15609int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t); 15610int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t); 15611int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t); 15612uint16x4_t pextrh_u (uint16x4_t s, int field); 15613int16x4_t pextrh_s (int16x4_t s, int field); 15614uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t); 15615uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t); 15616uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t); 15617uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t); 15618int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t); 15619int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t); 15620int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t); 15621int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t); 15622int32x2_t pmaddhw (int16x4_t s, int16x4_t t); 15623int16x4_t pmaxsh (int16x4_t s, int16x4_t t); 15624uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t); 15625int16x4_t pminsh (int16x4_t s, int16x4_t t); 15626uint8x8_t pminub (uint8x8_t s, uint8x8_t t); 15627uint8x8_t pmovmskb_u (uint8x8_t s); 15628int8x8_t pmovmskb_s (int8x8_t s); 15629uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t); 15630int16x4_t pmulhh (int16x4_t s, int16x4_t t); 15631int16x4_t pmullh (int16x4_t s, int16x4_t t); 15632int64_t pmuluw (uint32x2_t s, uint32x2_t t); 15633uint8x8_t pasubub (uint8x8_t s, uint8x8_t t); 15634uint16x4_t biadd (uint8x8_t s); 15635uint16x4_t psadbh (uint8x8_t s, uint8x8_t t); 15636uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order); 15637int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order); 15638uint16x4_t psllh_u (uint16x4_t s, uint8_t amount); 15639int16x4_t psllh_s (int16x4_t s, uint8_t amount); 15640uint32x2_t psllw_u (uint32x2_t s, uint8_t amount); 15641int32x2_t psllw_s (int32x2_t s, uint8_t amount); 15642uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount); 15643int16x4_t psrlh_s (int16x4_t s, uint8_t amount); 15644uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount); 15645int32x2_t psrlw_s (int32x2_t s, uint8_t amount); 15646uint16x4_t psrah_u (uint16x4_t s, uint8_t amount); 15647int16x4_t psrah_s (int16x4_t s, uint8_t amount); 15648uint32x2_t psraw_u (uint32x2_t s, uint8_t amount); 15649int32x2_t psraw_s (int32x2_t s, uint8_t amount); 15650uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t); 15651uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t); 15652uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t); 15653int32x2_t psubw_s (int32x2_t s, int32x2_t t); 15654int16x4_t psubh_s (int16x4_t s, int16x4_t t); 15655int8x8_t psubb_s (int8x8_t s, int8x8_t t); 15656uint64_t psubd_u (uint64_t s, uint64_t t); 15657int64_t psubd_s (int64_t s, int64_t t); 15658int16x4_t psubsh (int16x4_t s, int16x4_t t); 15659int8x8_t psubsb (int8x8_t s, int8x8_t t); 15660uint16x4_t psubush (uint16x4_t s, uint16x4_t t); 15661uint8x8_t psubusb (uint8x8_t s, uint8x8_t t); 15662uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t); 15663uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t); 15664uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t); 15665int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t); 15666int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t); 15667int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t); 15668uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t); 15669uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t); 15670uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t); 15671int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t); 15672int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t); 15673int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t); 15674@end smallexample 15675 15676@menu 15677* Paired-Single Arithmetic:: 15678* Paired-Single Built-in Functions:: 15679* MIPS-3D Built-in Functions:: 15680@end menu 15681 15682@node Paired-Single Arithmetic 15683@subsubsection Paired-Single Arithmetic 15684 15685The table below lists the @code{v2sf} operations for which hardware 15686support exists. @code{a}, @code{b} and @code{c} are @code{v2sf} 15687values and @code{x} is an integral value. 15688 15689@multitable @columnfractions .50 .50 15690@item C code @tab MIPS instruction 15691@item @code{a + b} @tab @code{add.ps} 15692@item @code{a - b} @tab @code{sub.ps} 15693@item @code{-a} @tab @code{neg.ps} 15694@item @code{a * b} @tab @code{mul.ps} 15695@item @code{a * b + c} @tab @code{madd.ps} 15696@item @code{a * b - c} @tab @code{msub.ps} 15697@item @code{-(a * b + c)} @tab @code{nmadd.ps} 15698@item @code{-(a * b - c)} @tab @code{nmsub.ps} 15699@item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} 15700@end multitable 15701 15702Note that the multiply-accumulate instructions can be disabled 15703using the command-line option @code{-mno-fused-madd}. 15704 15705@node Paired-Single Built-in Functions 15706@subsubsection Paired-Single Built-in Functions 15707 15708The following paired-single functions map directly to a particular 15709MIPS instruction. Please refer to the architecture specification 15710for details on what each instruction does. 15711 15712@table @code 15713@item v2sf __builtin_mips_pll_ps (v2sf, v2sf) 15714Pair lower lower (@code{pll.ps}). 15715 15716@item v2sf __builtin_mips_pul_ps (v2sf, v2sf) 15717Pair upper lower (@code{pul.ps}). 15718 15719@item v2sf __builtin_mips_plu_ps (v2sf, v2sf) 15720Pair lower upper (@code{plu.ps}). 15721 15722@item v2sf __builtin_mips_puu_ps (v2sf, v2sf) 15723Pair upper upper (@code{puu.ps}). 15724 15725@item v2sf __builtin_mips_cvt_ps_s (float, float) 15726Convert pair to paired single (@code{cvt.ps.s}). 15727 15728@item float __builtin_mips_cvt_s_pl (v2sf) 15729Convert pair lower to single (@code{cvt.s.pl}). 15730 15731@item float __builtin_mips_cvt_s_pu (v2sf) 15732Convert pair upper to single (@code{cvt.s.pu}). 15733 15734@item v2sf __builtin_mips_abs_ps (v2sf) 15735Absolute value (@code{abs.ps}). 15736 15737@item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) 15738Align variable (@code{alnv.ps}). 15739 15740@emph{Note:} The value of the third parameter must be 0 or 4 15741modulo 8, otherwise the result is unpredictable. Please read the 15742instruction description for details. 15743@end table 15744 15745The following multi-instruction functions are also available. 15746In each case, @var{cond} can be any of the 16 floating-point conditions: 15747@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 15748@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, 15749@code{lt}, @code{nge}, @code{le} or @code{ngt}. 15750 15751@table @code 15752@item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15753@itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15754Conditional move based on floating-point comparison (@code{c.@var{cond}.ps}, 15755@code{movt.ps}/@code{movf.ps}). 15756 15757The @code{movt} functions return the value @var{x} computed by: 15758 15759@smallexample 15760c.@var{cond}.ps @var{cc},@var{a},@var{b} 15761mov.ps @var{x},@var{c} 15762movt.ps @var{x},@var{d},@var{cc} 15763@end smallexample 15764 15765The @code{movf} functions are similar but use @code{movf.ps} instead 15766of @code{movt.ps}. 15767 15768@item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15769@itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15770Comparison of two paired-single values (@code{c.@var{cond}.ps}, 15771@code{bc1t}/@code{bc1f}). 15772 15773These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 15774and return either the upper or lower half of the result. For example: 15775 15776@smallexample 15777v2sf a, b; 15778if (__builtin_mips_upper_c_eq_ps (a, b)) 15779 upper_halves_are_equal (); 15780else 15781 upper_halves_are_unequal (); 15782 15783if (__builtin_mips_lower_c_eq_ps (a, b)) 15784 lower_halves_are_equal (); 15785else 15786 lower_halves_are_unequal (); 15787@end smallexample 15788@end table 15789 15790@node MIPS-3D Built-in Functions 15791@subsubsection MIPS-3D Built-in Functions 15792 15793The MIPS-3D Application-Specific Extension (ASE) includes additional 15794paired-single instructions that are designed to improve the performance 15795of 3D graphics operations. Support for these instructions is controlled 15796by the @option{-mips3d} command-line option. 15797 15798The functions listed below map directly to a particular MIPS-3D 15799instruction. Please refer to the architecture specification for 15800more details on what each instruction does. 15801 15802@table @code 15803@item v2sf __builtin_mips_addr_ps (v2sf, v2sf) 15804Reduction add (@code{addr.ps}). 15805 15806@item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) 15807Reduction multiply (@code{mulr.ps}). 15808 15809@item v2sf __builtin_mips_cvt_pw_ps (v2sf) 15810Convert paired single to paired word (@code{cvt.pw.ps}). 15811 15812@item v2sf __builtin_mips_cvt_ps_pw (v2sf) 15813Convert paired word to paired single (@code{cvt.ps.pw}). 15814 15815@item float __builtin_mips_recip1_s (float) 15816@itemx double __builtin_mips_recip1_d (double) 15817@itemx v2sf __builtin_mips_recip1_ps (v2sf) 15818Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). 15819 15820@item float __builtin_mips_recip2_s (float, float) 15821@itemx double __builtin_mips_recip2_d (double, double) 15822@itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) 15823Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). 15824 15825@item float __builtin_mips_rsqrt1_s (float) 15826@itemx double __builtin_mips_rsqrt1_d (double) 15827@itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) 15828Reduced-precision reciprocal square root (sequence step 1) 15829(@code{rsqrt1.@var{fmt}}). 15830 15831@item float __builtin_mips_rsqrt2_s (float, float) 15832@itemx double __builtin_mips_rsqrt2_d (double, double) 15833@itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) 15834Reduced-precision reciprocal square root (sequence step 2) 15835(@code{rsqrt2.@var{fmt}}). 15836@end table 15837 15838The following multi-instruction functions are also available. 15839In each case, @var{cond} can be any of the 16 floating-point conditions: 15840@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 15841@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, 15842@code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. 15843 15844@table @code 15845@item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) 15846@itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) 15847Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, 15848@code{bc1t}/@code{bc1f}). 15849 15850These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} 15851or @code{cabs.@var{cond}.d} and return the result as a boolean value. 15852For example: 15853 15854@smallexample 15855float a, b; 15856if (__builtin_mips_cabs_eq_s (a, b)) 15857 true (); 15858else 15859 false (); 15860@end smallexample 15861 15862@item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15863@itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15864Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, 15865@code{bc1t}/@code{bc1f}). 15866 15867These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} 15868and return either the upper or lower half of the result. For example: 15869 15870@smallexample 15871v2sf a, b; 15872if (__builtin_mips_upper_cabs_eq_ps (a, b)) 15873 upper_halves_are_equal (); 15874else 15875 upper_halves_are_unequal (); 15876 15877if (__builtin_mips_lower_cabs_eq_ps (a, b)) 15878 lower_halves_are_equal (); 15879else 15880 lower_halves_are_unequal (); 15881@end smallexample 15882 15883@item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15884@itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15885Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, 15886@code{movt.ps}/@code{movf.ps}). 15887 15888The @code{movt} functions return the value @var{x} computed by: 15889 15890@smallexample 15891cabs.@var{cond}.ps @var{cc},@var{a},@var{b} 15892mov.ps @var{x},@var{c} 15893movt.ps @var{x},@var{d},@var{cc} 15894@end smallexample 15895 15896The @code{movf} functions are similar but use @code{movf.ps} instead 15897of @code{movt.ps}. 15898 15899@item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15900@itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15901@itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15902@itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15903Comparison of two paired-single values 15904(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 15905@code{bc1any2t}/@code{bc1any2f}). 15906 15907These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 15908or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either 15909result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}. 15910For example: 15911 15912@smallexample 15913v2sf a, b; 15914if (__builtin_mips_any_c_eq_ps (a, b)) 15915 one_is_true (); 15916else 15917 both_are_false (); 15918 15919if (__builtin_mips_all_c_eq_ps (a, b)) 15920 both_are_true (); 15921else 15922 one_is_false (); 15923@end smallexample 15924 15925@item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15926@itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15927@itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15928@itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15929Comparison of four paired-single values 15930(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 15931@code{bc1any4t}/@code{bc1any4f}). 15932 15933These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} 15934to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. 15935The @code{any} forms return @code{true} if any of the four results are @code{true} 15936and the @code{all} forms return @code{true} if all four results are @code{true}. 15937For example: 15938 15939@smallexample 15940v2sf a, b, c, d; 15941if (__builtin_mips_any_c_eq_4s (a, b, c, d)) 15942 some_are_true (); 15943else 15944 all_are_false (); 15945 15946if (__builtin_mips_all_c_eq_4s (a, b, c, d)) 15947 all_are_true (); 15948else 15949 some_are_false (); 15950@end smallexample 15951@end table 15952 15953@node MIPS SIMD Architecture (MSA) Support 15954@subsection MIPS SIMD Architecture (MSA) Support 15955 15956@menu 15957* MIPS SIMD Architecture Built-in Functions:: 15958@end menu 15959 15960GCC provides intrinsics to access the SIMD instructions provided by the 15961MSA MIPS SIMD Architecture. The interface is made available by including 15962@code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}. 15963For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic, 15964@code{__msa_*}. 15965 15966MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and 1596764-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point 15968data elements. The following vectors typedefs are included in @code{msa.h}: 15969@itemize 15970@item @code{v16i8}, a vector of sixteen signed 8-bit integers; 15971@item @code{v16u8}, a vector of sixteen unsigned 8-bit integers; 15972@item @code{v8i16}, a vector of eight signed 16-bit integers; 15973@item @code{v8u16}, a vector of eight unsigned 16-bit integers; 15974@item @code{v4i32}, a vector of four signed 32-bit integers; 15975@item @code{v4u32}, a vector of four unsigned 32-bit integers; 15976@item @code{v2i64}, a vector of two signed 64-bit integers; 15977@item @code{v2u64}, a vector of two unsigned 64-bit integers; 15978@item @code{v4f32}, a vector of four 32-bit floats; 15979@item @code{v2f64}, a vector of two 64-bit doubles. 15980@end itemize 15981 15982Instructions and corresponding built-ins may have additional restrictions and/or 15983input/output values manipulated: 15984@itemize 15985@item @code{imm0_1}, an integer literal in range 0 to 1; 15986@item @code{imm0_3}, an integer literal in range 0 to 3; 15987@item @code{imm0_7}, an integer literal in range 0 to 7; 15988@item @code{imm0_15}, an integer literal in range 0 to 15; 15989@item @code{imm0_31}, an integer literal in range 0 to 31; 15990@item @code{imm0_63}, an integer literal in range 0 to 63; 15991@item @code{imm0_255}, an integer literal in range 0 to 255; 15992@item @code{imm_n16_15}, an integer literal in range -16 to 15; 15993@item @code{imm_n512_511}, an integer literal in range -512 to 511; 15994@item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left 15995shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022; 15996@item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left 15997shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044; 15998@item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left 15999shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088; 16000@item @code{imm1_4}, an integer literal in range 1 to 4; 16001@item @code{i32, i64, u32, u64, f32, f64}, defined as follows: 16002@end itemize 16003 16004@smallexample 16005@{ 16006typedef int i32; 16007#if __LONG_MAX__ == __LONG_LONG_MAX__ 16008typedef long i64; 16009#else 16010typedef long long i64; 16011#endif 16012 16013typedef unsigned int u32; 16014#if __LONG_MAX__ == __LONG_LONG_MAX__ 16015typedef unsigned long u64; 16016#else 16017typedef unsigned long long u64; 16018#endif 16019 16020typedef double f64; 16021typedef float f32; 16022@} 16023@end smallexample 16024 16025@node MIPS SIMD Architecture Built-in Functions 16026@subsubsection MIPS SIMD Architecture Built-in Functions 16027 16028The intrinsics provided are listed below; each is named after the 16029machine instruction. 16030 16031@smallexample 16032v16i8 __builtin_msa_add_a_b (v16i8, v16i8); 16033v8i16 __builtin_msa_add_a_h (v8i16, v8i16); 16034v4i32 __builtin_msa_add_a_w (v4i32, v4i32); 16035v2i64 __builtin_msa_add_a_d (v2i64, v2i64); 16036 16037v16i8 __builtin_msa_adds_a_b (v16i8, v16i8); 16038v8i16 __builtin_msa_adds_a_h (v8i16, v8i16); 16039v4i32 __builtin_msa_adds_a_w (v4i32, v4i32); 16040v2i64 __builtin_msa_adds_a_d (v2i64, v2i64); 16041 16042v16i8 __builtin_msa_adds_s_b (v16i8, v16i8); 16043v8i16 __builtin_msa_adds_s_h (v8i16, v8i16); 16044v4i32 __builtin_msa_adds_s_w (v4i32, v4i32); 16045v2i64 __builtin_msa_adds_s_d (v2i64, v2i64); 16046 16047v16u8 __builtin_msa_adds_u_b (v16u8, v16u8); 16048v8u16 __builtin_msa_adds_u_h (v8u16, v8u16); 16049v4u32 __builtin_msa_adds_u_w (v4u32, v4u32); 16050v2u64 __builtin_msa_adds_u_d (v2u64, v2u64); 16051 16052v16i8 __builtin_msa_addv_b (v16i8, v16i8); 16053v8i16 __builtin_msa_addv_h (v8i16, v8i16); 16054v4i32 __builtin_msa_addv_w (v4i32, v4i32); 16055v2i64 __builtin_msa_addv_d (v2i64, v2i64); 16056 16057v16i8 __builtin_msa_addvi_b (v16i8, imm0_31); 16058v8i16 __builtin_msa_addvi_h (v8i16, imm0_31); 16059v4i32 __builtin_msa_addvi_w (v4i32, imm0_31); 16060v2i64 __builtin_msa_addvi_d (v2i64, imm0_31); 16061 16062v16u8 __builtin_msa_and_v (v16u8, v16u8); 16063 16064v16u8 __builtin_msa_andi_b (v16u8, imm0_255); 16065 16066v16i8 __builtin_msa_asub_s_b (v16i8, v16i8); 16067v8i16 __builtin_msa_asub_s_h (v8i16, v8i16); 16068v4i32 __builtin_msa_asub_s_w (v4i32, v4i32); 16069v2i64 __builtin_msa_asub_s_d (v2i64, v2i64); 16070 16071v16u8 __builtin_msa_asub_u_b (v16u8, v16u8); 16072v8u16 __builtin_msa_asub_u_h (v8u16, v8u16); 16073v4u32 __builtin_msa_asub_u_w (v4u32, v4u32); 16074v2u64 __builtin_msa_asub_u_d (v2u64, v2u64); 16075 16076v16i8 __builtin_msa_ave_s_b (v16i8, v16i8); 16077v8i16 __builtin_msa_ave_s_h (v8i16, v8i16); 16078v4i32 __builtin_msa_ave_s_w (v4i32, v4i32); 16079v2i64 __builtin_msa_ave_s_d (v2i64, v2i64); 16080 16081v16u8 __builtin_msa_ave_u_b (v16u8, v16u8); 16082v8u16 __builtin_msa_ave_u_h (v8u16, v8u16); 16083v4u32 __builtin_msa_ave_u_w (v4u32, v4u32); 16084v2u64 __builtin_msa_ave_u_d (v2u64, v2u64); 16085 16086v16i8 __builtin_msa_aver_s_b (v16i8, v16i8); 16087v8i16 __builtin_msa_aver_s_h (v8i16, v8i16); 16088v4i32 __builtin_msa_aver_s_w (v4i32, v4i32); 16089v2i64 __builtin_msa_aver_s_d (v2i64, v2i64); 16090 16091v16u8 __builtin_msa_aver_u_b (v16u8, v16u8); 16092v8u16 __builtin_msa_aver_u_h (v8u16, v8u16); 16093v4u32 __builtin_msa_aver_u_w (v4u32, v4u32); 16094v2u64 __builtin_msa_aver_u_d (v2u64, v2u64); 16095 16096v16u8 __builtin_msa_bclr_b (v16u8, v16u8); 16097v8u16 __builtin_msa_bclr_h (v8u16, v8u16); 16098v4u32 __builtin_msa_bclr_w (v4u32, v4u32); 16099v2u64 __builtin_msa_bclr_d (v2u64, v2u64); 16100 16101v16u8 __builtin_msa_bclri_b (v16u8, imm0_7); 16102v8u16 __builtin_msa_bclri_h (v8u16, imm0_15); 16103v4u32 __builtin_msa_bclri_w (v4u32, imm0_31); 16104v2u64 __builtin_msa_bclri_d (v2u64, imm0_63); 16105 16106v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8); 16107v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16); 16108v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32); 16109v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64); 16110 16111v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7); 16112v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15); 16113v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31); 16114v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63); 16115 16116v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8); 16117v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16); 16118v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32); 16119v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64); 16120 16121v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7); 16122v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15); 16123v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31); 16124v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63); 16125 16126v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8); 16127 16128v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255); 16129 16130v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8); 16131 16132v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255); 16133 16134v16u8 __builtin_msa_bneg_b (v16u8, v16u8); 16135v8u16 __builtin_msa_bneg_h (v8u16, v8u16); 16136v4u32 __builtin_msa_bneg_w (v4u32, v4u32); 16137v2u64 __builtin_msa_bneg_d (v2u64, v2u64); 16138 16139v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7); 16140v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15); 16141v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31); 16142v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63); 16143 16144i32 __builtin_msa_bnz_b (v16u8); 16145i32 __builtin_msa_bnz_h (v8u16); 16146i32 __builtin_msa_bnz_w (v4u32); 16147i32 __builtin_msa_bnz_d (v2u64); 16148 16149i32 __builtin_msa_bnz_v (v16u8); 16150 16151v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8); 16152 16153v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255); 16154 16155v16u8 __builtin_msa_bset_b (v16u8, v16u8); 16156v8u16 __builtin_msa_bset_h (v8u16, v8u16); 16157v4u32 __builtin_msa_bset_w (v4u32, v4u32); 16158v2u64 __builtin_msa_bset_d (v2u64, v2u64); 16159 16160v16u8 __builtin_msa_bseti_b (v16u8, imm0_7); 16161v8u16 __builtin_msa_bseti_h (v8u16, imm0_15); 16162v4u32 __builtin_msa_bseti_w (v4u32, imm0_31); 16163v2u64 __builtin_msa_bseti_d (v2u64, imm0_63); 16164 16165i32 __builtin_msa_bz_b (v16u8); 16166i32 __builtin_msa_bz_h (v8u16); 16167i32 __builtin_msa_bz_w (v4u32); 16168i32 __builtin_msa_bz_d (v2u64); 16169 16170i32 __builtin_msa_bz_v (v16u8); 16171 16172v16i8 __builtin_msa_ceq_b (v16i8, v16i8); 16173v8i16 __builtin_msa_ceq_h (v8i16, v8i16); 16174v4i32 __builtin_msa_ceq_w (v4i32, v4i32); 16175v2i64 __builtin_msa_ceq_d (v2i64, v2i64); 16176 16177v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15); 16178v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15); 16179v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15); 16180v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15); 16181 16182i32 __builtin_msa_cfcmsa (imm0_31); 16183 16184v16i8 __builtin_msa_cle_s_b (v16i8, v16i8); 16185v8i16 __builtin_msa_cle_s_h (v8i16, v8i16); 16186v4i32 __builtin_msa_cle_s_w (v4i32, v4i32); 16187v2i64 __builtin_msa_cle_s_d (v2i64, v2i64); 16188 16189v16i8 __builtin_msa_cle_u_b (v16u8, v16u8); 16190v8i16 __builtin_msa_cle_u_h (v8u16, v8u16); 16191v4i32 __builtin_msa_cle_u_w (v4u32, v4u32); 16192v2i64 __builtin_msa_cle_u_d (v2u64, v2u64); 16193 16194v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15); 16195v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15); 16196v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15); 16197v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15); 16198 16199v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31); 16200v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31); 16201v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31); 16202v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31); 16203 16204v16i8 __builtin_msa_clt_s_b (v16i8, v16i8); 16205v8i16 __builtin_msa_clt_s_h (v8i16, v8i16); 16206v4i32 __builtin_msa_clt_s_w (v4i32, v4i32); 16207v2i64 __builtin_msa_clt_s_d (v2i64, v2i64); 16208 16209v16i8 __builtin_msa_clt_u_b (v16u8, v16u8); 16210v8i16 __builtin_msa_clt_u_h (v8u16, v8u16); 16211v4i32 __builtin_msa_clt_u_w (v4u32, v4u32); 16212v2i64 __builtin_msa_clt_u_d (v2u64, v2u64); 16213 16214v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15); 16215v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15); 16216v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15); 16217v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15); 16218 16219v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31); 16220v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31); 16221v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31); 16222v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31); 16223 16224i32 __builtin_msa_copy_s_b (v16i8, imm0_15); 16225i32 __builtin_msa_copy_s_h (v8i16, imm0_7); 16226i32 __builtin_msa_copy_s_w (v4i32, imm0_3); 16227i64 __builtin_msa_copy_s_d (v2i64, imm0_1); 16228 16229u32 __builtin_msa_copy_u_b (v16i8, imm0_15); 16230u32 __builtin_msa_copy_u_h (v8i16, imm0_7); 16231u32 __builtin_msa_copy_u_w (v4i32, imm0_3); 16232u64 __builtin_msa_copy_u_d (v2i64, imm0_1); 16233 16234void __builtin_msa_ctcmsa (imm0_31, i32); 16235 16236v16i8 __builtin_msa_div_s_b (v16i8, v16i8); 16237v8i16 __builtin_msa_div_s_h (v8i16, v8i16); 16238v4i32 __builtin_msa_div_s_w (v4i32, v4i32); 16239v2i64 __builtin_msa_div_s_d (v2i64, v2i64); 16240 16241v16u8 __builtin_msa_div_u_b (v16u8, v16u8); 16242v8u16 __builtin_msa_div_u_h (v8u16, v8u16); 16243v4u32 __builtin_msa_div_u_w (v4u32, v4u32); 16244v2u64 __builtin_msa_div_u_d (v2u64, v2u64); 16245 16246v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8); 16247v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16); 16248v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32); 16249 16250v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8); 16251v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16); 16252v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32); 16253 16254v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8); 16255v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16); 16256v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32); 16257 16258v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8); 16259v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16); 16260v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32); 16261 16262v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8); 16263v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16); 16264v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32); 16265 16266v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8); 16267v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16); 16268v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32); 16269 16270v4f32 __builtin_msa_fadd_w (v4f32, v4f32); 16271v2f64 __builtin_msa_fadd_d (v2f64, v2f64); 16272 16273v4i32 __builtin_msa_fcaf_w (v4f32, v4f32); 16274v2i64 __builtin_msa_fcaf_d (v2f64, v2f64); 16275 16276v4i32 __builtin_msa_fceq_w (v4f32, v4f32); 16277v2i64 __builtin_msa_fceq_d (v2f64, v2f64); 16278 16279v4i32 __builtin_msa_fclass_w (v4f32); 16280v2i64 __builtin_msa_fclass_d (v2f64); 16281 16282v4i32 __builtin_msa_fcle_w (v4f32, v4f32); 16283v2i64 __builtin_msa_fcle_d (v2f64, v2f64); 16284 16285v4i32 __builtin_msa_fclt_w (v4f32, v4f32); 16286v2i64 __builtin_msa_fclt_d (v2f64, v2f64); 16287 16288v4i32 __builtin_msa_fcne_w (v4f32, v4f32); 16289v2i64 __builtin_msa_fcne_d (v2f64, v2f64); 16290 16291v4i32 __builtin_msa_fcor_w (v4f32, v4f32); 16292v2i64 __builtin_msa_fcor_d (v2f64, v2f64); 16293 16294v4i32 __builtin_msa_fcueq_w (v4f32, v4f32); 16295v2i64 __builtin_msa_fcueq_d (v2f64, v2f64); 16296 16297v4i32 __builtin_msa_fcule_w (v4f32, v4f32); 16298v2i64 __builtin_msa_fcule_d (v2f64, v2f64); 16299 16300v4i32 __builtin_msa_fcult_w (v4f32, v4f32); 16301v2i64 __builtin_msa_fcult_d (v2f64, v2f64); 16302 16303v4i32 __builtin_msa_fcun_w (v4f32, v4f32); 16304v2i64 __builtin_msa_fcun_d (v2f64, v2f64); 16305 16306v4i32 __builtin_msa_fcune_w (v4f32, v4f32); 16307v2i64 __builtin_msa_fcune_d (v2f64, v2f64); 16308 16309v4f32 __builtin_msa_fdiv_w (v4f32, v4f32); 16310v2f64 __builtin_msa_fdiv_d (v2f64, v2f64); 16311 16312v8i16 __builtin_msa_fexdo_h (v4f32, v4f32); 16313v4f32 __builtin_msa_fexdo_w (v2f64, v2f64); 16314 16315v4f32 __builtin_msa_fexp2_w (v4f32, v4i32); 16316v2f64 __builtin_msa_fexp2_d (v2f64, v2i64); 16317 16318v4f32 __builtin_msa_fexupl_w (v8i16); 16319v2f64 __builtin_msa_fexupl_d (v4f32); 16320 16321v4f32 __builtin_msa_fexupr_w (v8i16); 16322v2f64 __builtin_msa_fexupr_d (v4f32); 16323 16324v4f32 __builtin_msa_ffint_s_w (v4i32); 16325v2f64 __builtin_msa_ffint_s_d (v2i64); 16326 16327v4f32 __builtin_msa_ffint_u_w (v4u32); 16328v2f64 __builtin_msa_ffint_u_d (v2u64); 16329 16330v4f32 __builtin_msa_ffql_w (v8i16); 16331v2f64 __builtin_msa_ffql_d (v4i32); 16332 16333v4f32 __builtin_msa_ffqr_w (v8i16); 16334v2f64 __builtin_msa_ffqr_d (v4i32); 16335 16336v16i8 __builtin_msa_fill_b (i32); 16337v8i16 __builtin_msa_fill_h (i32); 16338v4i32 __builtin_msa_fill_w (i32); 16339v2i64 __builtin_msa_fill_d (i64); 16340 16341v4f32 __builtin_msa_flog2_w (v4f32); 16342v2f64 __builtin_msa_flog2_d (v2f64); 16343 16344v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32); 16345v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64); 16346 16347v4f32 __builtin_msa_fmax_w (v4f32, v4f32); 16348v2f64 __builtin_msa_fmax_d (v2f64, v2f64); 16349 16350v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32); 16351v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64); 16352 16353v4f32 __builtin_msa_fmin_w (v4f32, v4f32); 16354v2f64 __builtin_msa_fmin_d (v2f64, v2f64); 16355 16356v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32); 16357v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64); 16358 16359v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32); 16360v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64); 16361 16362v4f32 __builtin_msa_fmul_w (v4f32, v4f32); 16363v2f64 __builtin_msa_fmul_d (v2f64, v2f64); 16364 16365v4f32 __builtin_msa_frint_w (v4f32); 16366v2f64 __builtin_msa_frint_d (v2f64); 16367 16368v4f32 __builtin_msa_frcp_w (v4f32); 16369v2f64 __builtin_msa_frcp_d (v2f64); 16370 16371v4f32 __builtin_msa_frsqrt_w (v4f32); 16372v2f64 __builtin_msa_frsqrt_d (v2f64); 16373 16374v4i32 __builtin_msa_fsaf_w (v4f32, v4f32); 16375v2i64 __builtin_msa_fsaf_d (v2f64, v2f64); 16376 16377v4i32 __builtin_msa_fseq_w (v4f32, v4f32); 16378v2i64 __builtin_msa_fseq_d (v2f64, v2f64); 16379 16380v4i32 __builtin_msa_fsle_w (v4f32, v4f32); 16381v2i64 __builtin_msa_fsle_d (v2f64, v2f64); 16382 16383v4i32 __builtin_msa_fslt_w (v4f32, v4f32); 16384v2i64 __builtin_msa_fslt_d (v2f64, v2f64); 16385 16386v4i32 __builtin_msa_fsne_w (v4f32, v4f32); 16387v2i64 __builtin_msa_fsne_d (v2f64, v2f64); 16388 16389v4i32 __builtin_msa_fsor_w (v4f32, v4f32); 16390v2i64 __builtin_msa_fsor_d (v2f64, v2f64); 16391 16392v4f32 __builtin_msa_fsqrt_w (v4f32); 16393v2f64 __builtin_msa_fsqrt_d (v2f64); 16394 16395v4f32 __builtin_msa_fsub_w (v4f32, v4f32); 16396v2f64 __builtin_msa_fsub_d (v2f64, v2f64); 16397 16398v4i32 __builtin_msa_fsueq_w (v4f32, v4f32); 16399v2i64 __builtin_msa_fsueq_d (v2f64, v2f64); 16400 16401v4i32 __builtin_msa_fsule_w (v4f32, v4f32); 16402v2i64 __builtin_msa_fsule_d (v2f64, v2f64); 16403 16404v4i32 __builtin_msa_fsult_w (v4f32, v4f32); 16405v2i64 __builtin_msa_fsult_d (v2f64, v2f64); 16406 16407v4i32 __builtin_msa_fsun_w (v4f32, v4f32); 16408v2i64 __builtin_msa_fsun_d (v2f64, v2f64); 16409 16410v4i32 __builtin_msa_fsune_w (v4f32, v4f32); 16411v2i64 __builtin_msa_fsune_d (v2f64, v2f64); 16412 16413v4i32 __builtin_msa_ftint_s_w (v4f32); 16414v2i64 __builtin_msa_ftint_s_d (v2f64); 16415 16416v4u32 __builtin_msa_ftint_u_w (v4f32); 16417v2u64 __builtin_msa_ftint_u_d (v2f64); 16418 16419v8i16 __builtin_msa_ftq_h (v4f32, v4f32); 16420v4i32 __builtin_msa_ftq_w (v2f64, v2f64); 16421 16422v4i32 __builtin_msa_ftrunc_s_w (v4f32); 16423v2i64 __builtin_msa_ftrunc_s_d (v2f64); 16424 16425v4u32 __builtin_msa_ftrunc_u_w (v4f32); 16426v2u64 __builtin_msa_ftrunc_u_d (v2f64); 16427 16428v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8); 16429v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16); 16430v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32); 16431 16432v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8); 16433v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16); 16434v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32); 16435 16436v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8); 16437v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16); 16438v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32); 16439 16440v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8); 16441v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16); 16442v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32); 16443 16444v16i8 __builtin_msa_ilvev_b (v16i8, v16i8); 16445v8i16 __builtin_msa_ilvev_h (v8i16, v8i16); 16446v4i32 __builtin_msa_ilvev_w (v4i32, v4i32); 16447v2i64 __builtin_msa_ilvev_d (v2i64, v2i64); 16448 16449v16i8 __builtin_msa_ilvl_b (v16i8, v16i8); 16450v8i16 __builtin_msa_ilvl_h (v8i16, v8i16); 16451v4i32 __builtin_msa_ilvl_w (v4i32, v4i32); 16452v2i64 __builtin_msa_ilvl_d (v2i64, v2i64); 16453 16454v16i8 __builtin_msa_ilvod_b (v16i8, v16i8); 16455v8i16 __builtin_msa_ilvod_h (v8i16, v8i16); 16456v4i32 __builtin_msa_ilvod_w (v4i32, v4i32); 16457v2i64 __builtin_msa_ilvod_d (v2i64, v2i64); 16458 16459v16i8 __builtin_msa_ilvr_b (v16i8, v16i8); 16460v8i16 __builtin_msa_ilvr_h (v8i16, v8i16); 16461v4i32 __builtin_msa_ilvr_w (v4i32, v4i32); 16462v2i64 __builtin_msa_ilvr_d (v2i64, v2i64); 16463 16464v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32); 16465v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32); 16466v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32); 16467v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64); 16468 16469v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8); 16470v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16); 16471v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32); 16472v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64); 16473 16474v16i8 __builtin_msa_ld_b (const void *, imm_n512_511); 16475v8i16 __builtin_msa_ld_h (const void *, imm_n1024_1022); 16476v4i32 __builtin_msa_ld_w (const void *, imm_n2048_2044); 16477v2i64 __builtin_msa_ld_d (const void *, imm_n4096_4088); 16478 16479v16i8 __builtin_msa_ldi_b (imm_n512_511); 16480v8i16 __builtin_msa_ldi_h (imm_n512_511); 16481v4i32 __builtin_msa_ldi_w (imm_n512_511); 16482v2i64 __builtin_msa_ldi_d (imm_n512_511); 16483 16484v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16); 16485v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32); 16486 16487v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16); 16488v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32); 16489 16490v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8); 16491v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16); 16492v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32); 16493v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64); 16494 16495v16i8 __builtin_msa_max_a_b (v16i8, v16i8); 16496v8i16 __builtin_msa_max_a_h (v8i16, v8i16); 16497v4i32 __builtin_msa_max_a_w (v4i32, v4i32); 16498v2i64 __builtin_msa_max_a_d (v2i64, v2i64); 16499 16500v16i8 __builtin_msa_max_s_b (v16i8, v16i8); 16501v8i16 __builtin_msa_max_s_h (v8i16, v8i16); 16502v4i32 __builtin_msa_max_s_w (v4i32, v4i32); 16503v2i64 __builtin_msa_max_s_d (v2i64, v2i64); 16504 16505v16u8 __builtin_msa_max_u_b (v16u8, v16u8); 16506v8u16 __builtin_msa_max_u_h (v8u16, v8u16); 16507v4u32 __builtin_msa_max_u_w (v4u32, v4u32); 16508v2u64 __builtin_msa_max_u_d (v2u64, v2u64); 16509 16510v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15); 16511v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15); 16512v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15); 16513v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15); 16514 16515v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31); 16516v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31); 16517v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31); 16518v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31); 16519 16520v16i8 __builtin_msa_min_a_b (v16i8, v16i8); 16521v8i16 __builtin_msa_min_a_h (v8i16, v8i16); 16522v4i32 __builtin_msa_min_a_w (v4i32, v4i32); 16523v2i64 __builtin_msa_min_a_d (v2i64, v2i64); 16524 16525v16i8 __builtin_msa_min_s_b (v16i8, v16i8); 16526v8i16 __builtin_msa_min_s_h (v8i16, v8i16); 16527v4i32 __builtin_msa_min_s_w (v4i32, v4i32); 16528v2i64 __builtin_msa_min_s_d (v2i64, v2i64); 16529 16530v16u8 __builtin_msa_min_u_b (v16u8, v16u8); 16531v8u16 __builtin_msa_min_u_h (v8u16, v8u16); 16532v4u32 __builtin_msa_min_u_w (v4u32, v4u32); 16533v2u64 __builtin_msa_min_u_d (v2u64, v2u64); 16534 16535v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15); 16536v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15); 16537v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15); 16538v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15); 16539 16540v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31); 16541v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31); 16542v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31); 16543v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31); 16544 16545v16i8 __builtin_msa_mod_s_b (v16i8, v16i8); 16546v8i16 __builtin_msa_mod_s_h (v8i16, v8i16); 16547v4i32 __builtin_msa_mod_s_w (v4i32, v4i32); 16548v2i64 __builtin_msa_mod_s_d (v2i64, v2i64); 16549 16550v16u8 __builtin_msa_mod_u_b (v16u8, v16u8); 16551v8u16 __builtin_msa_mod_u_h (v8u16, v8u16); 16552v4u32 __builtin_msa_mod_u_w (v4u32, v4u32); 16553v2u64 __builtin_msa_mod_u_d (v2u64, v2u64); 16554 16555v16i8 __builtin_msa_move_v (v16i8); 16556 16557v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16); 16558v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32); 16559 16560v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16); 16561v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32); 16562 16563v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8); 16564v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16); 16565v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32); 16566v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64); 16567 16568v8i16 __builtin_msa_mul_q_h (v8i16, v8i16); 16569v4i32 __builtin_msa_mul_q_w (v4i32, v4i32); 16570 16571v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16); 16572v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32); 16573 16574v16i8 __builtin_msa_mulv_b (v16i8, v16i8); 16575v8i16 __builtin_msa_mulv_h (v8i16, v8i16); 16576v4i32 __builtin_msa_mulv_w (v4i32, v4i32); 16577v2i64 __builtin_msa_mulv_d (v2i64, v2i64); 16578 16579v16i8 __builtin_msa_nloc_b (v16i8); 16580v8i16 __builtin_msa_nloc_h (v8i16); 16581v4i32 __builtin_msa_nloc_w (v4i32); 16582v2i64 __builtin_msa_nloc_d (v2i64); 16583 16584v16i8 __builtin_msa_nlzc_b (v16i8); 16585v8i16 __builtin_msa_nlzc_h (v8i16); 16586v4i32 __builtin_msa_nlzc_w (v4i32); 16587v2i64 __builtin_msa_nlzc_d (v2i64); 16588 16589v16u8 __builtin_msa_nor_v (v16u8, v16u8); 16590 16591v16u8 __builtin_msa_nori_b (v16u8, imm0_255); 16592 16593v16u8 __builtin_msa_or_v (v16u8, v16u8); 16594 16595v16u8 __builtin_msa_ori_b (v16u8, imm0_255); 16596 16597v16i8 __builtin_msa_pckev_b (v16i8, v16i8); 16598v8i16 __builtin_msa_pckev_h (v8i16, v8i16); 16599v4i32 __builtin_msa_pckev_w (v4i32, v4i32); 16600v2i64 __builtin_msa_pckev_d (v2i64, v2i64); 16601 16602v16i8 __builtin_msa_pckod_b (v16i8, v16i8); 16603v8i16 __builtin_msa_pckod_h (v8i16, v8i16); 16604v4i32 __builtin_msa_pckod_w (v4i32, v4i32); 16605v2i64 __builtin_msa_pckod_d (v2i64, v2i64); 16606 16607v16i8 __builtin_msa_pcnt_b (v16i8); 16608v8i16 __builtin_msa_pcnt_h (v8i16); 16609v4i32 __builtin_msa_pcnt_w (v4i32); 16610v2i64 __builtin_msa_pcnt_d (v2i64); 16611 16612v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7); 16613v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15); 16614v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31); 16615v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63); 16616 16617v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7); 16618v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15); 16619v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31); 16620v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63); 16621 16622v16i8 __builtin_msa_shf_b (v16i8, imm0_255); 16623v8i16 __builtin_msa_shf_h (v8i16, imm0_255); 16624v4i32 __builtin_msa_shf_w (v4i32, imm0_255); 16625 16626v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32); 16627v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32); 16628v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32); 16629v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32); 16630 16631v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15); 16632v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7); 16633v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3); 16634v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1); 16635 16636v16i8 __builtin_msa_sll_b (v16i8, v16i8); 16637v8i16 __builtin_msa_sll_h (v8i16, v8i16); 16638v4i32 __builtin_msa_sll_w (v4i32, v4i32); 16639v2i64 __builtin_msa_sll_d (v2i64, v2i64); 16640 16641v16i8 __builtin_msa_slli_b (v16i8, imm0_7); 16642v8i16 __builtin_msa_slli_h (v8i16, imm0_15); 16643v4i32 __builtin_msa_slli_w (v4i32, imm0_31); 16644v2i64 __builtin_msa_slli_d (v2i64, imm0_63); 16645 16646v16i8 __builtin_msa_splat_b (v16i8, i32); 16647v8i16 __builtin_msa_splat_h (v8i16, i32); 16648v4i32 __builtin_msa_splat_w (v4i32, i32); 16649v2i64 __builtin_msa_splat_d (v2i64, i32); 16650 16651v16i8 __builtin_msa_splati_b (v16i8, imm0_15); 16652v8i16 __builtin_msa_splati_h (v8i16, imm0_7); 16653v4i32 __builtin_msa_splati_w (v4i32, imm0_3); 16654v2i64 __builtin_msa_splati_d (v2i64, imm0_1); 16655 16656v16i8 __builtin_msa_sra_b (v16i8, v16i8); 16657v8i16 __builtin_msa_sra_h (v8i16, v8i16); 16658v4i32 __builtin_msa_sra_w (v4i32, v4i32); 16659v2i64 __builtin_msa_sra_d (v2i64, v2i64); 16660 16661v16i8 __builtin_msa_srai_b (v16i8, imm0_7); 16662v8i16 __builtin_msa_srai_h (v8i16, imm0_15); 16663v4i32 __builtin_msa_srai_w (v4i32, imm0_31); 16664v2i64 __builtin_msa_srai_d (v2i64, imm0_63); 16665 16666v16i8 __builtin_msa_srar_b (v16i8, v16i8); 16667v8i16 __builtin_msa_srar_h (v8i16, v8i16); 16668v4i32 __builtin_msa_srar_w (v4i32, v4i32); 16669v2i64 __builtin_msa_srar_d (v2i64, v2i64); 16670 16671v16i8 __builtin_msa_srari_b (v16i8, imm0_7); 16672v8i16 __builtin_msa_srari_h (v8i16, imm0_15); 16673v4i32 __builtin_msa_srari_w (v4i32, imm0_31); 16674v2i64 __builtin_msa_srari_d (v2i64, imm0_63); 16675 16676v16i8 __builtin_msa_srl_b (v16i8, v16i8); 16677v8i16 __builtin_msa_srl_h (v8i16, v8i16); 16678v4i32 __builtin_msa_srl_w (v4i32, v4i32); 16679v2i64 __builtin_msa_srl_d (v2i64, v2i64); 16680 16681v16i8 __builtin_msa_srli_b (v16i8, imm0_7); 16682v8i16 __builtin_msa_srli_h (v8i16, imm0_15); 16683v4i32 __builtin_msa_srli_w (v4i32, imm0_31); 16684v2i64 __builtin_msa_srli_d (v2i64, imm0_63); 16685 16686v16i8 __builtin_msa_srlr_b (v16i8, v16i8); 16687v8i16 __builtin_msa_srlr_h (v8i16, v8i16); 16688v4i32 __builtin_msa_srlr_w (v4i32, v4i32); 16689v2i64 __builtin_msa_srlr_d (v2i64, v2i64); 16690 16691v16i8 __builtin_msa_srlri_b (v16i8, imm0_7); 16692v8i16 __builtin_msa_srlri_h (v8i16, imm0_15); 16693v4i32 __builtin_msa_srlri_w (v4i32, imm0_31); 16694v2i64 __builtin_msa_srlri_d (v2i64, imm0_63); 16695 16696void __builtin_msa_st_b (v16i8, void *, imm_n512_511); 16697void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022); 16698void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044); 16699void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088); 16700 16701v16i8 __builtin_msa_subs_s_b (v16i8, v16i8); 16702v8i16 __builtin_msa_subs_s_h (v8i16, v8i16); 16703v4i32 __builtin_msa_subs_s_w (v4i32, v4i32); 16704v2i64 __builtin_msa_subs_s_d (v2i64, v2i64); 16705 16706v16u8 __builtin_msa_subs_u_b (v16u8, v16u8); 16707v8u16 __builtin_msa_subs_u_h (v8u16, v8u16); 16708v4u32 __builtin_msa_subs_u_w (v4u32, v4u32); 16709v2u64 __builtin_msa_subs_u_d (v2u64, v2u64); 16710 16711v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8); 16712v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16); 16713v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32); 16714v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64); 16715 16716v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8); 16717v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16); 16718v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32); 16719v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64); 16720 16721v16i8 __builtin_msa_subv_b (v16i8, v16i8); 16722v8i16 __builtin_msa_subv_h (v8i16, v8i16); 16723v4i32 __builtin_msa_subv_w (v4i32, v4i32); 16724v2i64 __builtin_msa_subv_d (v2i64, v2i64); 16725 16726v16i8 __builtin_msa_subvi_b (v16i8, imm0_31); 16727v8i16 __builtin_msa_subvi_h (v8i16, imm0_31); 16728v4i32 __builtin_msa_subvi_w (v4i32, imm0_31); 16729v2i64 __builtin_msa_subvi_d (v2i64, imm0_31); 16730 16731v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8); 16732v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16); 16733v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32); 16734v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64); 16735 16736v16u8 __builtin_msa_xor_v (v16u8, v16u8); 16737 16738v16u8 __builtin_msa_xori_b (v16u8, imm0_255); 16739@end smallexample 16740 16741@node Other MIPS Built-in Functions 16742@subsection Other MIPS Built-in Functions 16743 16744GCC provides other MIPS-specific built-in functions: 16745 16746@table @code 16747@item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr}) 16748Insert a @samp{cache} instruction with operands @var{op} and @var{addr}. 16749GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE} 16750when this function is available. 16751 16752@item unsigned int __builtin_mips_get_fcsr (void) 16753@itemx void __builtin_mips_set_fcsr (unsigned int @var{value}) 16754Get and set the contents of the floating-point control and status register 16755(FPU control register 31). These functions are only available in hard-float 16756code but can be called in both MIPS16 and non-MIPS16 contexts. 16757 16758@code{__builtin_mips_set_fcsr} can be used to change any bit of the 16759register except the condition codes, which GCC assumes are preserved. 16760@end table 16761 16762@node MSP430 Built-in Functions 16763@subsection MSP430 Built-in Functions 16764 16765GCC provides a couple of special builtin functions to aid in the 16766writing of interrupt handlers in C. 16767 16768@table @code 16769@item __bic_SR_register_on_exit (int @var{mask}) 16770This clears the indicated bits in the saved copy of the status register 16771currently residing on the stack. This only works inside interrupt 16772handlers and the changes to the status register will only take affect 16773once the handler returns. 16774 16775@item __bis_SR_register_on_exit (int @var{mask}) 16776This sets the indicated bits in the saved copy of the status register 16777currently residing on the stack. This only works inside interrupt 16778handlers and the changes to the status register will only take affect 16779once the handler returns. 16780 16781@item __delay_cycles (long long @var{cycles}) 16782This inserts an instruction sequence that takes exactly @var{cycles} 16783cycles (between 0 and about 17E9) to complete. The inserted sequence 16784may use jumps, loops, or no-ops, and does not interfere with any other 16785instructions. Note that @var{cycles} must be a compile-time constant 16786integer - that is, you must pass a number, not a variable that may be 16787optimized to a constant later. The number of cycles delayed by this 16788builtin is exact. 16789@end table 16790 16791@node NDS32 Built-in Functions 16792@subsection NDS32 Built-in Functions 16793 16794These built-in functions are available for the NDS32 target: 16795 16796@deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr}) 16797Insert an ISYNC instruction into the instruction stream where 16798@var{addr} is an instruction address for serialization. 16799@end deftypefn 16800 16801@deftypefn {Built-in Function} void __builtin_nds32_isb (void) 16802Insert an ISB instruction into the instruction stream. 16803@end deftypefn 16804 16805@deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr}) 16806Return the content of a system register which is mapped by @var{sr}. 16807@end deftypefn 16808 16809@deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr}) 16810Return the content of a user space register which is mapped by @var{usr}. 16811@end deftypefn 16812 16813@deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr}) 16814Move the @var{value} to a system register which is mapped by @var{sr}. 16815@end deftypefn 16816 16817@deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr}) 16818Move the @var{value} to a user space register which is mapped by @var{usr}. 16819@end deftypefn 16820 16821@deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void) 16822Enable global interrupt. 16823@end deftypefn 16824 16825@deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void) 16826Disable global interrupt. 16827@end deftypefn 16828 16829@node picoChip Built-in Functions 16830@subsection picoChip Built-in Functions 16831 16832GCC provides an interface to selected machine instructions from the 16833picoChip instruction set. 16834 16835@table @code 16836@item int __builtin_sbc (int @var{value}) 16837Sign bit count. Return the number of consecutive bits in @var{value} 16838that have the same value as the sign bit. The result is the number of 16839leading sign bits minus one, giving the number of redundant sign bits in 16840@var{value}. 16841 16842@item int __builtin_byteswap (int @var{value}) 16843Byte swap. Return the result of swapping the upper and lower bytes of 16844@var{value}. 16845 16846@item int __builtin_brev (int @var{value}) 16847Bit reversal. Return the result of reversing the bits in 16848@var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1, 16849and so on. 16850 16851@item int __builtin_adds (int @var{x}, int @var{y}) 16852Saturating addition. Return the result of adding @var{x} and @var{y}, 16853storing the value 32767 if the result overflows. 16854 16855@item int __builtin_subs (int @var{x}, int @var{y}) 16856Saturating subtraction. Return the result of subtracting @var{y} from 16857@var{x}, storing the value @minus{}32768 if the result overflows. 16858 16859@item void __builtin_halt (void) 16860Halt. The processor stops execution. This built-in is useful for 16861implementing assertions. 16862 16863@end table 16864 16865@node Basic PowerPC Built-in Functions 16866@subsection Basic PowerPC Built-in Functions 16867 16868@menu 16869* Basic PowerPC Built-in Functions Available on all Configurations:: 16870* Basic PowerPC Built-in Functions Available on ISA 2.05:: 16871* Basic PowerPC Built-in Functions Available on ISA 2.06:: 16872* Basic PowerPC Built-in Functions Available on ISA 2.07:: 16873* Basic PowerPC Built-in Functions Available on ISA 3.0:: 16874@end menu 16875 16876This section describes PowerPC built-in functions that do not require 16877the inclusion of any special header files to declare prototypes or 16878provide macro definitions. The sections that follow describe 16879additional PowerPC built-in functions. 16880 16881@node Basic PowerPC Built-in Functions Available on all Configurations 16882@subsubsection Basic PowerPC Built-in Functions Available on all Configurations 16883 16884@deftypefn {Built-in Function} void __builtin_cpu_init (void) 16885This function is a @code{nop} on the PowerPC platform and is included solely 16886to maintain API compatibility with the x86 builtins. 16887@end deftypefn 16888 16889@deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname}) 16890This function returns a value of @code{1} if the run-time CPU is of type 16891@var{cpuname} and returns @code{0} otherwise 16892 16893The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer 16894which exports the hardware capability bits. GCC defines the macro 16895@code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports} 16896built-in function is fully supported. 16897 16898If GCC was configured to use a GLIBC before 2.23, the built-in 16899function @code{__builtin_cpu_is} always returns a 0 and the compiler 16900issues a warning. 16901 16902The following CPU names can be detected: 16903 16904@table @samp 16905@item power10 16906IBM POWER10 Server CPU. 16907@item power9 16908IBM POWER9 Server CPU. 16909@item power8 16910IBM POWER8 Server CPU. 16911@item power7 16912IBM POWER7 Server CPU. 16913@item power6x 16914IBM POWER6 Server CPU (RAW mode). 16915@item power6 16916IBM POWER6 Server CPU (Architected mode). 16917@item power5+ 16918IBM POWER5+ Server CPU. 16919@item power5 16920IBM POWER5 Server CPU. 16921@item ppc970 16922IBM 970 Server CPU (ie, Apple G5). 16923@item power4 16924IBM POWER4 Server CPU. 16925@item ppca2 16926IBM A2 64-bit Embedded CPU 16927@item ppc476 16928IBM PowerPC 476FP 32-bit Embedded CPU. 16929@item ppc464 16930IBM PowerPC 464 32-bit Embedded CPU. 16931@item ppc440 16932PowerPC 440 32-bit Embedded CPU. 16933@item ppc405 16934PowerPC 405 32-bit Embedded CPU. 16935@item ppc-cell-be 16936IBM PowerPC Cell Broadband Engine Architecture CPU. 16937@end table 16938 16939Here is an example: 16940@smallexample 16941#ifdef __BUILTIN_CPU_SUPPORTS__ 16942 if (__builtin_cpu_is ("power8")) 16943 @{ 16944 do_power8 (); // POWER8 specific implementation. 16945 @} 16946 else 16947#endif 16948 @{ 16949 do_generic (); // Generic implementation. 16950 @} 16951@end smallexample 16952@end deftypefn 16953 16954@deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature}) 16955This function returns a value of @code{1} if the run-time CPU supports the HWCAP 16956feature @var{feature} and returns @code{0} otherwise. 16957 16958The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or 16959newer which exports the hardware capability bits. GCC defines the 16960macro @code{__BUILTIN_CPU_SUPPORTS__} if the 16961@code{__builtin_cpu_supports} built-in function is fully supported. 16962 16963If GCC was configured to use a GLIBC before 2.23, the built-in 16964function @code{__builtin_cpu_suports} always returns a 0 and the 16965compiler issues a warning. 16966 16967The following features can be 16968detected: 16969 16970@table @samp 16971@item 4xxmac 169724xx CPU has a Multiply Accumulator. 16973@item altivec 16974CPU has a SIMD/Vector Unit. 16975@item arch_2_05 16976CPU supports ISA 2.05 (eg, POWER6) 16977@item arch_2_06 16978CPU supports ISA 2.06 (eg, POWER7) 16979@item arch_2_07 16980CPU supports ISA 2.07 (eg, POWER8) 16981@item arch_3_00 16982CPU supports ISA 3.0 (eg, POWER9) 16983@item arch_3_1 16984CPU supports ISA 3.1 (eg, POWER10) 16985@item archpmu 16986CPU supports the set of compatible performance monitoring events. 16987@item booke 16988CPU supports the Embedded ISA category. 16989@item cellbe 16990CPU has a CELL broadband engine. 16991@item darn 16992CPU supports the @code{darn} (deliver a random number) instruction. 16993@item dfp 16994CPU has a decimal floating point unit. 16995@item dscr 16996CPU supports the data stream control register. 16997@item ebb 16998CPU supports event base branching. 16999@item efpdouble 17000CPU has a SPE double precision floating point unit. 17001@item efpsingle 17002CPU has a SPE single precision floating point unit. 17003@item fpu 17004CPU has a floating point unit. 17005@item htm 17006CPU has hardware transaction memory instructions. 17007@item htm-nosc 17008Kernel aborts hardware transactions when a syscall is made. 17009@item htm-no-suspend 17010CPU supports hardware transaction memory but does not support the 17011@code{tsuspend.} instruction. 17012@item ic_snoop 17013CPU supports icache snooping capabilities. 17014@item ieee128 17015CPU supports 128-bit IEEE binary floating point instructions. 17016@item isel 17017CPU supports the integer select instruction. 17018@item mma 17019CPU supports the matrix-multiply assist instructions. 17020@item mmu 17021CPU has a memory management unit. 17022@item notb 17023CPU does not have a timebase (eg, 601 and 403gx). 17024@item pa6t 17025CPU supports the PA Semi 6T CORE ISA. 17026@item power4 17027CPU supports ISA 2.00 (eg, POWER4) 17028@item power5 17029CPU supports ISA 2.02 (eg, POWER5) 17030@item power5+ 17031CPU supports ISA 2.03 (eg, POWER5+) 17032@item power6x 17033CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr. 17034@item ppc32 17035CPU supports 32-bit mode execution. 17036@item ppc601 17037CPU supports the old POWER ISA (eg, 601) 17038@item ppc64 17039CPU supports 64-bit mode execution. 17040@item ppcle 17041CPU supports a little-endian mode that uses address swizzling. 17042@item scv 17043Kernel supports system call vectored. 17044@item smt 17045CPU support simultaneous multi-threading. 17046@item spe 17047CPU has a signal processing extension unit. 17048@item tar 17049CPU supports the target address register. 17050@item true_le 17051CPU supports true little-endian mode. 17052@item ucache 17053CPU has unified I/D cache. 17054@item vcrypto 17055CPU supports the vector cryptography instructions. 17056@item vsx 17057CPU supports the vector-scalar extension. 17058@end table 17059 17060Here is an example: 17061@smallexample 17062#ifdef __BUILTIN_CPU_SUPPORTS__ 17063 if (__builtin_cpu_supports ("fpu")) 17064 @{ 17065 asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2)); 17066 @} 17067 else 17068#endif 17069 @{ 17070 dst = __fadd (src1, src2); // Software FP addition function. 17071 @} 17072@end smallexample 17073@end deftypefn 17074 17075The following built-in functions are also available on all PowerPC 17076processors: 17077@smallexample 17078uint64_t __builtin_ppc_get_timebase (); 17079unsigned long __builtin_ppc_mftb (); 17080double __builtin_unpack_ibm128 (__ibm128, int); 17081__ibm128 __builtin_pack_ibm128 (double, double); 17082double __builtin_mffs (void); 17083void __builtin_mtfsf (const int, double); 17084void __builtin_mtfsb0 (const int); 17085void __builtin_mtfsb1 (const int); 17086void __builtin_set_fpscr_rn (int); 17087@end smallexample 17088 17089The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb} 17090functions generate instructions to read the Time Base Register. The 17091@code{__builtin_ppc_get_timebase} function may generate multiple 17092instructions and always returns the 64 bits of the Time Base Register. 17093The @code{__builtin_ppc_mftb} function always generates one instruction and 17094returns the Time Base Register value as an unsigned long, throwing away 17095the most significant word on 32-bit environments. The @code{__builtin_mffs} 17096return the value of the FPSCR register. Note, ISA 3.0 supports the 17097@code{__builtin_mffsl()} which permits software to read the control and 17098non-sticky status bits in the FSPCR without the higher latency associated with 17099accessing the sticky status bits. The @code{__builtin_mtfsf} takes a constant 171008-bit integer field mask and a double precision floating point argument 17101and generates the @code{mtfsf} (extended mnemonic) instruction to write new 17102values to selected fields of the FPSCR. The 17103@code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change 17104as an argument. The valid bit range is between 0 and 31. The builtins map to 17105the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and 17106add 32. Hence these instructions only modify the FPSCR[32:63] bits by 17107changing the specified bit to a zero or one respectively. The 17108@code{__builtin_set_fpscr_rn} builtin allows changing both of the floating 17109point rounding mode bits. The argument is a 2-bit value. The argument can 17110either be a @code{const int} or stored in a variable. The builtin uses 17111the ISA 3.0 17112instruction @code{mffscrn} if available, otherwise it reads the FPSCR, masks 17113the current rounding mode bits out and OR's in the new value. 17114 17115@node Basic PowerPC Built-in Functions Available on ISA 2.05 17116@subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05 17117 17118The basic built-in functions described in this section are 17119available on the PowerPC family of processors starting with ISA 2.05 17120or later. Unless specific options are explicitly disabled on the 17121command line, specifying option @option{-mcpu=power6} has the effect of 17122enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt}, 17123@option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb}, 17124@option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and 17125@option{-mrecip-precision} options. Specify the 17126@option{-maltivec} option explicitly in 17127combination with the above options if desired. 17128 17129The following functions require option @option{-mcmpb}. 17130@smallexample 17131unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int); 17132unsigned int __builtin_cmpb (unsigned int, unsigned int); 17133@end smallexample 17134 17135The @code{__builtin_cmpb} function 17136performs a byte-wise compare on the contents of its two arguments, 17137returning the result of the byte-wise comparison as the returned 17138value. For each byte comparison, the corresponding byte of the return 17139value holds 0xff if the input bytes are equal and 0 if the input bytes 17140are not equal. If either of the arguments to this built-in function 17141is wider than 32 bits, the function call expands into the form that 17142expects @code{unsigned long long int} arguments 17143which is only available on 64-bit targets. 17144 17145The following built-in functions are available 17146when hardware decimal floating point 17147(@option{-mhard-dfp}) is available: 17148@smallexample 17149void __builtin_set_fpscr_drn(int); 17150_Decimal64 __builtin_ddedpd (int, _Decimal64); 17151_Decimal128 __builtin_ddedpdq (int, _Decimal128); 17152_Decimal64 __builtin_denbcd (int, _Decimal64); 17153_Decimal128 __builtin_denbcdq (int, _Decimal128); 17154_Decimal64 __builtin_diex (long long, _Decimal64); 17155_Decimal128 _builtin_diexq (long long, _Decimal128); 17156_Decimal64 __builtin_dscli (_Decimal64, int); 17157_Decimal128 __builtin_dscliq (_Decimal128, int); 17158_Decimal64 __builtin_dscri (_Decimal64, int); 17159_Decimal128 __builtin_dscriq (_Decimal128, int); 17160long long __builtin_dxex (_Decimal64); 17161long long __builtin_dxexq (_Decimal128); 17162_Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long); 17163unsigned long long __builtin_unpack_dec128 (_Decimal128, int); 17164 17165The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal 17166floating point rounding mode bits. The argument is a 3-bit value. The 17167argument can either be a @code{const int} or the value can be stored in 17168a variable. 17169The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available. 17170Otherwise the builtin reads the FPSCR, masks the current decimal rounding 17171mode bits out and OR's in the new value. 17172 17173@end smallexample 17174 17175The following functions require @option{-mhard-float}, 17176@option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options. 17177 17178@smallexample 17179double __builtin_recipdiv (double, double); 17180float __builtin_recipdivf (float, float); 17181double __builtin_rsqrt (double); 17182float __builtin_rsqrtf (float); 17183@end smallexample 17184 17185The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and 17186@code{__builtin_rsqrtf} functions generate multiple instructions to 17187implement the reciprocal sqrt functionality using reciprocal sqrt 17188estimate instructions. 17189 17190The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf} 17191functions generate multiple instructions to implement division using 17192the reciprocal estimate instructions. 17193 17194The following functions require @option{-mhard-float} and 17195@option{-mmultiple} options. 17196 17197The @code{__builtin_unpack_longdouble} function takes a 17198@code{long double} argument and a compile time constant of 0 or 1. If 17199the constant is 0, the first @code{double} within the 17200@code{long double} is returned, otherwise the second @code{double} 17201is returned. The @code{__builtin_unpack_longdouble} function is only 17202available if @code{long double} uses the IBM extended double 17203representation. 17204 17205The @code{__builtin_pack_longdouble} function takes two @code{double} 17206arguments and returns a @code{long double} value that combines the two 17207arguments. The @code{__builtin_pack_longdouble} function is only 17208available if @code{long double} uses the IBM extended double 17209representation. 17210 17211The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128} 17212argument and a compile time constant of 0 or 1. If the constant is 0, 17213the first @code{double} within the @code{__ibm128} is returned, 17214otherwise the second @code{double} is returned. 17215 17216The @code{__builtin_pack_ibm128} function takes two @code{double} 17217arguments and returns a @code{__ibm128} value that combines the two 17218arguments. 17219 17220Additional built-in functions are available for the 64-bit PowerPC 17221family of processors, for efficient use of 128-bit floating point 17222(@code{__float128}) values. 17223 17224@node Basic PowerPC Built-in Functions Available on ISA 2.06 17225@subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06 17226 17227The basic built-in functions described in this section are 17228available on the PowerPC family of processors starting with ISA 2.05 17229or later. Unless specific options are explicitly disabled on the 17230command line, specifying option @option{-mcpu=power7} has the effect of 17231enabling all the same options as for @option{-mcpu=power6} in 17232addition to the @option{-maltivec}, @option{-mpopcntd}, and 17233@option{-mvsx} options. 17234 17235The following basic built-in functions require @option{-mpopcntd}: 17236@smallexample 17237unsigned int __builtin_addg6s (unsigned int, unsigned int); 17238long long __builtin_bpermd (long long, long long); 17239unsigned int __builtin_cbcdtd (unsigned int); 17240unsigned int __builtin_cdtbcd (unsigned int); 17241long long __builtin_divde (long long, long long); 17242unsigned long long __builtin_divdeu (unsigned long long, unsigned long long); 17243int __builtin_divwe (int, int); 17244unsigned int __builtin_divweu (unsigned int, unsigned int); 17245vector __int128 __builtin_pack_vector_int128 (long long, long long); 17246void __builtin_rs6000_speculation_barrier (void); 17247long long __builtin_unpack_vector_int128 (vector __int128, signed char); 17248@end smallexample 17249 17250Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions 17251require a 64-bit environment. 17252 17253The following basic built-in functions, which are also supported on 17254x86 targets, require @option{-mfloat128}. 17255@smallexample 17256__float128 __builtin_fabsq (__float128); 17257__float128 __builtin_copysignq (__float128, __float128); 17258__float128 __builtin_infq (void); 17259__float128 __builtin_huge_valq (void); 17260__float128 __builtin_nanq (void); 17261__float128 __builtin_nansq (void); 17262 17263__float128 __builtin_sqrtf128 (__float128); 17264__float128 __builtin_fmaf128 (__float128, __float128, __float128); 17265@end smallexample 17266 17267@node Basic PowerPC Built-in Functions Available on ISA 2.07 17268@subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07 17269 17270The basic built-in functions described in this section are 17271available on the PowerPC family of processors starting with ISA 2.07 17272or later. Unless specific options are explicitly disabled on the 17273command line, specifying option @option{-mcpu=power8} has the effect of 17274enabling all the same options as for @option{-mcpu=power7} in 17275addition to the @option{-mpower8-fusion}, @option{-mpower8-vector}, 17276@option{-mcrypto}, @option{-mhtm}, @option{-mquad-memory}, and 17277@option{-mquad-memory-atomic} options. 17278 17279This section intentionally empty. 17280 17281@node Basic PowerPC Built-in Functions Available on ISA 3.0 17282@subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0 17283 17284The basic built-in functions described in this section are 17285available on the PowerPC family of processors starting with ISA 3.0 17286or later. Unless specific options are explicitly disabled on the 17287command line, specifying option @option{-mcpu=power9} has the effect of 17288enabling all the same options as for @option{-mcpu=power8} in 17289addition to the @option{-misel} option. 17290 17291The following built-in functions are available on Linux 64-bit systems 17292that use the ISA 3.0 instruction set (@option{-mcpu=power9}): 17293 17294@table @code 17295@item __float128 __builtin_addf128_round_to_odd (__float128, __float128) 17296Perform a 128-bit IEEE floating point add using round to odd as the 17297rounding mode. 17298@findex __builtin_addf128_round_to_odd 17299 17300@item __float128 __builtin_subf128_round_to_odd (__float128, __float128) 17301Perform a 128-bit IEEE floating point subtract using round to odd as 17302the rounding mode. 17303@findex __builtin_subf128_round_to_odd 17304 17305@item __float128 __builtin_mulf128_round_to_odd (__float128, __float128) 17306Perform a 128-bit IEEE floating point multiply using round to odd as 17307the rounding mode. 17308@findex __builtin_mulf128_round_to_odd 17309 17310@item __float128 __builtin_divf128_round_to_odd (__float128, __float128) 17311Perform a 128-bit IEEE floating point divide using round to odd as 17312the rounding mode. 17313@findex __builtin_divf128_round_to_odd 17314 17315@item __float128 __builtin_sqrtf128_round_to_odd (__float128) 17316Perform a 128-bit IEEE floating point square root using round to odd 17317as the rounding mode. 17318@findex __builtin_sqrtf128_round_to_odd 17319 17320@item __float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128) 17321Perform a 128-bit IEEE floating point fused multiply and add operation 17322using round to odd as the rounding mode. 17323@findex __builtin_fmaf128_round_to_odd 17324 17325@item double __builtin_truncf128_round_to_odd (__float128) 17326Convert a 128-bit IEEE floating point value to @code{double} using 17327round to odd as the rounding mode. 17328@findex __builtin_truncf128_round_to_odd 17329@end table 17330 17331The following additional built-in functions are also available for the 17332PowerPC family of processors, starting with ISA 3.0 or later: 17333@smallexample 17334long long __builtin_darn (void); 17335long long __builtin_darn_raw (void); 17336int __builtin_darn_32 (void); 17337@end smallexample 17338 17339The @code{__builtin_darn} and @code{__builtin_darn_raw} 17340functions require a 1734164-bit environment supporting ISA 3.0 or later. 17342The @code{__builtin_darn} function provides a 64-bit conditioned 17343random number. The @code{__builtin_darn_raw} function provides a 1734464-bit raw random number. The @code{__builtin_darn_32} function 17345provides a 32-bit conditioned random number. 17346 17347The following additional built-in functions are also available for the 17348PowerPC family of processors, starting with ISA 3.0 or later: 17349 17350@smallexample 17351int __builtin_byte_in_set (unsigned char u, unsigned long long set); 17352int __builtin_byte_in_range (unsigned char u, unsigned int range); 17353int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges); 17354 17355int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value); 17356int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value); 17357int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value); 17358int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value); 17359 17360int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value); 17361int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value); 17362int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value); 17363int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value); 17364 17365int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value); 17366int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value); 17367int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value); 17368int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value); 17369 17370int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value); 17371int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value); 17372int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value); 17373int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value); 17374 17375double __builtin_mffsl(void); 17376 17377@end smallexample 17378The @code{__builtin_byte_in_set} function requires a 1737964-bit environment supporting ISA 3.0 or later. This function returns 17380a non-zero value if and only if its @code{u} argument exactly equals one of 17381the eight bytes contained within its 64-bit @code{set} argument. 17382 17383The @code{__builtin_byte_in_range} and 17384@code{__builtin_byte_in_either_range} require an environment 17385supporting ISA 3.0 or later. For these two functions, the 17386@code{range} argument is encoded as 4 bytes, organized as 17387@code{hi_1:lo_1:hi_2:lo_2}. 17388The @code{__builtin_byte_in_range} function returns a 17389non-zero value if and only if its @code{u} argument is within the 17390range bounded between @code{lo_2} and @code{hi_2} inclusive. 17391The @code{__builtin_byte_in_either_range} function returns non-zero if 17392and only if its @code{u} argument is within either the range bounded 17393between @code{lo_1} and @code{hi_1} inclusive or the range bounded 17394between @code{lo_2} and @code{hi_2} inclusive. 17395 17396The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value 17397if and only if the number of signficant digits of its @code{value} argument 17398is less than its @code{comparison} argument. The 17399@code{__builtin_dfp_dtstsfi_lt_dd} and 17400@code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but 17401require that the type of the @code{value} argument be 17402@code{__Decimal64} and @code{__Decimal128} respectively. 17403 17404The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value 17405if and only if the number of signficant digits of its @code{value} argument 17406is greater than its @code{comparison} argument. The 17407@code{__builtin_dfp_dtstsfi_gt_dd} and 17408@code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but 17409require that the type of the @code{value} argument be 17410@code{__Decimal64} and @code{__Decimal128} respectively. 17411 17412The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value 17413if and only if the number of signficant digits of its @code{value} argument 17414equals its @code{comparison} argument. The 17415@code{__builtin_dfp_dtstsfi_eq_dd} and 17416@code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but 17417require that the type of the @code{value} argument be 17418@code{__Decimal64} and @code{__Decimal128} respectively. 17419 17420The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value 17421if and only if its @code{value} argument has an undefined number of 17422significant digits, such as when @code{value} is an encoding of @code{NaN}. 17423The @code{__builtin_dfp_dtstsfi_ov_dd} and 17424@code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but 17425require that the type of the @code{value} argument be 17426@code{__Decimal64} and @code{__Decimal128} respectively. 17427 17428The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read 17429the FPSCR. The instruction is a lower latency version of the @code{mffs} 17430instruction. If the @code{mffsl} instruction is not available, then the 17431builtin uses the older @code{mffs} instruction to read the FPSCR. 17432 17433 17434@node PowerPC AltiVec/VSX Built-in Functions 17435@subsection PowerPC AltiVec/VSX Built-in Functions 17436 17437GCC provides an interface for the PowerPC family of processors to access 17438the AltiVec operations described in Motorola's AltiVec Programming 17439Interface Manual. The interface is made available by including 17440@code{<altivec.h>} and using @option{-maltivec} and 17441@option{-mabi=altivec}. The interface supports the following vector 17442types. 17443 17444@smallexample 17445vector unsigned char 17446vector signed char 17447vector bool char 17448 17449vector unsigned short 17450vector signed short 17451vector bool short 17452vector pixel 17453 17454vector unsigned int 17455vector signed int 17456vector bool int 17457vector float 17458@end smallexample 17459 17460GCC's implementation of the high-level language interface available from 17461C and C++ code differs from Motorola's documentation in several ways. 17462 17463@itemize @bullet 17464 17465@item 17466A vector constant is a list of constant expressions within curly braces. 17467 17468@item 17469A vector initializer requires no cast if the vector constant is of the 17470same type as the variable it is initializing. 17471 17472@item 17473If @code{signed} or @code{unsigned} is omitted, the signedness of the 17474vector type is the default signedness of the base type. The default 17475varies depending on the operating system, so a portable program should 17476always specify the signedness. 17477 17478@item 17479Compiling with @option{-maltivec} adds keywords @code{__vector}, 17480@code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and 17481@code{bool}. When compiling ISO C, the context-sensitive substitution 17482of the keywords @code{vector}, @code{pixel} and @code{bool} is 17483disabled. To use them, you must include @code{<altivec.h>} instead. 17484 17485@item 17486GCC allows using a @code{typedef} name as the type specifier for a 17487vector type, but only under the following circumstances: 17488 17489@itemize @bullet 17490 17491@item 17492When using @code{__vector} instead of @code{vector}; for example, 17493 17494@smallexample 17495typedef signed short int16; 17496__vector int16 data; 17497@end smallexample 17498 17499@item 17500When using @code{vector} in keyword-and-predefine mode; for example, 17501 17502@smallexample 17503typedef signed short int16; 17504vector int16 data; 17505@end smallexample 17506 17507Note that keyword-and-predefine mode is enabled by disabling GNU 17508extensions (e.g., by using @code{-std=c11}) and including 17509@code{<altivec.h>}. 17510@end itemize 17511 17512@item 17513For C, overloaded functions are implemented with macros so the following 17514does not work: 17515 17516@smallexample 17517 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); 17518@end smallexample 17519 17520@noindent 17521Since @code{vec_add} is a macro, the vector constant in the example 17522is treated as four separate arguments. Wrap the entire argument in 17523parentheses for this to work. 17524@end itemize 17525 17526@emph{Note:} Only the @code{<altivec.h>} interface is supported. 17527Internally, GCC uses built-in functions to achieve the functionality in 17528the aforementioned header file, but they are not supported and are 17529subject to change without notice. 17530 17531GCC complies with the OpenPOWER 64-Bit ELF V2 ABI Specification, 17532which may be found at 17533@uref{https://openpowerfoundation.org/?resource_lib=64-bit-elf-v2-abi-specification-power-architecture}. 17534Appendix A of this document lists the vector API interfaces that must be 17535provided by compliant compilers. Programmers should preferentially use 17536the interfaces described therein. However, historically GCC has provided 17537additional interfaces for access to vector instructions. These are 17538briefly described below. 17539 17540@menu 17541* PowerPC AltiVec Built-in Functions on ISA 2.05:: 17542* PowerPC AltiVec Built-in Functions Available on ISA 2.06:: 17543* PowerPC AltiVec Built-in Functions Available on ISA 2.07:: 17544* PowerPC AltiVec Built-in Functions Available on ISA 3.0:: 17545@end menu 17546 17547@node PowerPC AltiVec Built-in Functions on ISA 2.05 17548@subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05 17549 17550The following interfaces are supported for the generic and specific 17551AltiVec operations and the AltiVec predicates. In cases where there 17552is a direct mapping between generic and specific operations, only the 17553generic names are shown here, although the specific operations can also 17554be used. 17555 17556Arguments that are documented as @code{const int} require literal 17557integral values within the range required for that operation. 17558 17559@smallexample 17560vector signed char vec_abs (vector signed char); 17561vector signed short vec_abs (vector signed short); 17562vector signed int vec_abs (vector signed int); 17563vector float vec_abs (vector float); 17564 17565vector signed char vec_abss (vector signed char); 17566vector signed short vec_abss (vector signed short); 17567vector signed int vec_abss (vector signed int); 17568 17569vector signed char vec_add (vector bool char, vector signed char); 17570vector signed char vec_add (vector signed char, vector bool char); 17571vector signed char vec_add (vector signed char, vector signed char); 17572vector unsigned char vec_add (vector bool char, vector unsigned char); 17573vector unsigned char vec_add (vector unsigned char, vector bool char); 17574vector unsigned char vec_add (vector unsigned char, vector unsigned char); 17575vector signed short vec_add (vector bool short, vector signed short); 17576vector signed short vec_add (vector signed short, vector bool short); 17577vector signed short vec_add (vector signed short, vector signed short); 17578vector unsigned short vec_add (vector bool short, vector unsigned short); 17579vector unsigned short vec_add (vector unsigned short, vector bool short); 17580vector unsigned short vec_add (vector unsigned short, vector unsigned short); 17581vector signed int vec_add (vector bool int, vector signed int); 17582vector signed int vec_add (vector signed int, vector bool int); 17583vector signed int vec_add (vector signed int, vector signed int); 17584vector unsigned int vec_add (vector bool int, vector unsigned int); 17585vector unsigned int vec_add (vector unsigned int, vector bool int); 17586vector unsigned int vec_add (vector unsigned int, vector unsigned int); 17587vector float vec_add (vector float, vector float); 17588 17589vector unsigned int vec_addc (vector unsigned int, vector unsigned int); 17590 17591vector unsigned char vec_adds (vector bool char, vector unsigned char); 17592vector unsigned char vec_adds (vector unsigned char, vector bool char); 17593vector unsigned char vec_adds (vector unsigned char, vector unsigned char); 17594vector signed char vec_adds (vector bool char, vector signed char); 17595vector signed char vec_adds (vector signed char, vector bool char); 17596vector signed char vec_adds (vector signed char, vector signed char); 17597vector unsigned short vec_adds (vector bool short, vector unsigned short); 17598vector unsigned short vec_adds (vector unsigned short, vector bool short); 17599vector unsigned short vec_adds (vector unsigned short, vector unsigned short); 17600vector signed short vec_adds (vector bool short, vector signed short); 17601vector signed short vec_adds (vector signed short, vector bool short); 17602vector signed short vec_adds (vector signed short, vector signed short); 17603vector unsigned int vec_adds (vector bool int, vector unsigned int); 17604vector unsigned int vec_adds (vector unsigned int, vector bool int); 17605vector unsigned int vec_adds (vector unsigned int, vector unsigned int); 17606vector signed int vec_adds (vector bool int, vector signed int); 17607vector signed int vec_adds (vector signed int, vector bool int); 17608vector signed int vec_adds (vector signed int, vector signed int); 17609 17610int vec_all_eq (vector signed char, vector bool char); 17611int vec_all_eq (vector signed char, vector signed char); 17612int vec_all_eq (vector unsigned char, vector bool char); 17613int vec_all_eq (vector unsigned char, vector unsigned char); 17614int vec_all_eq (vector bool char, vector bool char); 17615int vec_all_eq (vector bool char, vector unsigned char); 17616int vec_all_eq (vector bool char, vector signed char); 17617int vec_all_eq (vector signed short, vector bool short); 17618int vec_all_eq (vector signed short, vector signed short); 17619int vec_all_eq (vector unsigned short, vector bool short); 17620int vec_all_eq (vector unsigned short, vector unsigned short); 17621int vec_all_eq (vector bool short, vector bool short); 17622int vec_all_eq (vector bool short, vector unsigned short); 17623int vec_all_eq (vector bool short, vector signed short); 17624int vec_all_eq (vector pixel, vector pixel); 17625int vec_all_eq (vector signed int, vector bool int); 17626int vec_all_eq (vector signed int, vector signed int); 17627int vec_all_eq (vector unsigned int, vector bool int); 17628int vec_all_eq (vector unsigned int, vector unsigned int); 17629int vec_all_eq (vector bool int, vector bool int); 17630int vec_all_eq (vector bool int, vector unsigned int); 17631int vec_all_eq (vector bool int, vector signed int); 17632int vec_all_eq (vector float, vector float); 17633 17634int vec_all_ge (vector bool char, vector unsigned char); 17635int vec_all_ge (vector unsigned char, vector bool char); 17636int vec_all_ge (vector unsigned char, vector unsigned char); 17637int vec_all_ge (vector bool char, vector signed char); 17638int vec_all_ge (vector signed char, vector bool char); 17639int vec_all_ge (vector signed char, vector signed char); 17640int vec_all_ge (vector bool short, vector unsigned short); 17641int vec_all_ge (vector unsigned short, vector bool short); 17642int vec_all_ge (vector unsigned short, vector unsigned short); 17643int vec_all_ge (vector signed short, vector signed short); 17644int vec_all_ge (vector bool short, vector signed short); 17645int vec_all_ge (vector signed short, vector bool short); 17646int vec_all_ge (vector bool int, vector unsigned int); 17647int vec_all_ge (vector unsigned int, vector bool int); 17648int vec_all_ge (vector unsigned int, vector unsigned int); 17649int vec_all_ge (vector bool int, vector signed int); 17650int vec_all_ge (vector signed int, vector bool int); 17651int vec_all_ge (vector signed int, vector signed int); 17652int vec_all_ge (vector float, vector float); 17653 17654int vec_all_gt (vector bool char, vector unsigned char); 17655int vec_all_gt (vector unsigned char, vector bool char); 17656int vec_all_gt (vector unsigned char, vector unsigned char); 17657int vec_all_gt (vector bool char, vector signed char); 17658int vec_all_gt (vector signed char, vector bool char); 17659int vec_all_gt (vector signed char, vector signed char); 17660int vec_all_gt (vector bool short, vector unsigned short); 17661int vec_all_gt (vector unsigned short, vector bool short); 17662int vec_all_gt (vector unsigned short, vector unsigned short); 17663int vec_all_gt (vector bool short, vector signed short); 17664int vec_all_gt (vector signed short, vector bool short); 17665int vec_all_gt (vector signed short, vector signed short); 17666int vec_all_gt (vector bool int, vector unsigned int); 17667int vec_all_gt (vector unsigned int, vector bool int); 17668int vec_all_gt (vector unsigned int, vector unsigned int); 17669int vec_all_gt (vector bool int, vector signed int); 17670int vec_all_gt (vector signed int, vector bool int); 17671int vec_all_gt (vector signed int, vector signed int); 17672int vec_all_gt (vector float, vector float); 17673 17674int vec_all_in (vector float, vector float); 17675 17676int vec_all_le (vector bool char, vector unsigned char); 17677int vec_all_le (vector unsigned char, vector bool char); 17678int vec_all_le (vector unsigned char, vector unsigned char); 17679int vec_all_le (vector bool char, vector signed char); 17680int vec_all_le (vector signed char, vector bool char); 17681int vec_all_le (vector signed char, vector signed char); 17682int vec_all_le (vector bool short, vector unsigned short); 17683int vec_all_le (vector unsigned short, vector bool short); 17684int vec_all_le (vector unsigned short, vector unsigned short); 17685int vec_all_le (vector bool short, vector signed short); 17686int vec_all_le (vector signed short, vector bool short); 17687int vec_all_le (vector signed short, vector signed short); 17688int vec_all_le (vector bool int, vector unsigned int); 17689int vec_all_le (vector unsigned int, vector bool int); 17690int vec_all_le (vector unsigned int, vector unsigned int); 17691int vec_all_le (vector bool int, vector signed int); 17692int vec_all_le (vector signed int, vector bool int); 17693int vec_all_le (vector signed int, vector signed int); 17694int vec_all_le (vector float, vector float); 17695 17696int vec_all_lt (vector bool char, vector unsigned char); 17697int vec_all_lt (vector unsigned char, vector bool char); 17698int vec_all_lt (vector unsigned char, vector unsigned char); 17699int vec_all_lt (vector bool char, vector signed char); 17700int vec_all_lt (vector signed char, vector bool char); 17701int vec_all_lt (vector signed char, vector signed char); 17702int vec_all_lt (vector bool short, vector unsigned short); 17703int vec_all_lt (vector unsigned short, vector bool short); 17704int vec_all_lt (vector unsigned short, vector unsigned short); 17705int vec_all_lt (vector bool short, vector signed short); 17706int vec_all_lt (vector signed short, vector bool short); 17707int vec_all_lt (vector signed short, vector signed short); 17708int vec_all_lt (vector bool int, vector unsigned int); 17709int vec_all_lt (vector unsigned int, vector bool int); 17710int vec_all_lt (vector unsigned int, vector unsigned int); 17711int vec_all_lt (vector bool int, vector signed int); 17712int vec_all_lt (vector signed int, vector bool int); 17713int vec_all_lt (vector signed int, vector signed int); 17714int vec_all_lt (vector float, vector float); 17715 17716int vec_all_nan (vector float); 17717 17718int vec_all_ne (vector signed char, vector bool char); 17719int vec_all_ne (vector signed char, vector signed char); 17720int vec_all_ne (vector unsigned char, vector bool char); 17721int vec_all_ne (vector unsigned char, vector unsigned char); 17722int vec_all_ne (vector bool char, vector bool char); 17723int vec_all_ne (vector bool char, vector unsigned char); 17724int vec_all_ne (vector bool char, vector signed char); 17725int vec_all_ne (vector signed short, vector bool short); 17726int vec_all_ne (vector signed short, vector signed short); 17727int vec_all_ne (vector unsigned short, vector bool short); 17728int vec_all_ne (vector unsigned short, vector unsigned short); 17729int vec_all_ne (vector bool short, vector bool short); 17730int vec_all_ne (vector bool short, vector unsigned short); 17731int vec_all_ne (vector bool short, vector signed short); 17732int vec_all_ne (vector pixel, vector pixel); 17733int vec_all_ne (vector signed int, vector bool int); 17734int vec_all_ne (vector signed int, vector signed int); 17735int vec_all_ne (vector unsigned int, vector bool int); 17736int vec_all_ne (vector unsigned int, vector unsigned int); 17737int vec_all_ne (vector bool int, vector bool int); 17738int vec_all_ne (vector bool int, vector unsigned int); 17739int vec_all_ne (vector bool int, vector signed int); 17740int vec_all_ne (vector float, vector float); 17741 17742int vec_all_nge (vector float, vector float); 17743 17744int vec_all_ngt (vector float, vector float); 17745 17746int vec_all_nle (vector float, vector float); 17747 17748int vec_all_nlt (vector float, vector float); 17749 17750int vec_all_numeric (vector float); 17751 17752vector float vec_and (vector float, vector float); 17753vector float vec_and (vector float, vector bool int); 17754vector float vec_and (vector bool int, vector float); 17755vector bool int vec_and (vector bool int, vector bool int); 17756vector signed int vec_and (vector bool int, vector signed int); 17757vector signed int vec_and (vector signed int, vector bool int); 17758vector signed int vec_and (vector signed int, vector signed int); 17759vector unsigned int vec_and (vector bool int, vector unsigned int); 17760vector unsigned int vec_and (vector unsigned int, vector bool int); 17761vector unsigned int vec_and (vector unsigned int, vector unsigned int); 17762vector bool short vec_and (vector bool short, vector bool short); 17763vector signed short vec_and (vector bool short, vector signed short); 17764vector signed short vec_and (vector signed short, vector bool short); 17765vector signed short vec_and (vector signed short, vector signed short); 17766vector unsigned short vec_and (vector bool short, vector unsigned short); 17767vector unsigned short vec_and (vector unsigned short, vector bool short); 17768vector unsigned short vec_and (vector unsigned short, vector unsigned short); 17769vector signed char vec_and (vector bool char, vector signed char); 17770vector bool char vec_and (vector bool char, vector bool char); 17771vector signed char vec_and (vector signed char, vector bool char); 17772vector signed char vec_and (vector signed char, vector signed char); 17773vector unsigned char vec_and (vector bool char, vector unsigned char); 17774vector unsigned char vec_and (vector unsigned char, vector bool char); 17775vector unsigned char vec_and (vector unsigned char, vector unsigned char); 17776 17777vector float vec_andc (vector float, vector float); 17778vector float vec_andc (vector float, vector bool int); 17779vector float vec_andc (vector bool int, vector float); 17780vector bool int vec_andc (vector bool int, vector bool int); 17781vector signed int vec_andc (vector bool int, vector signed int); 17782vector signed int vec_andc (vector signed int, vector bool int); 17783vector signed int vec_andc (vector signed int, vector signed int); 17784vector unsigned int vec_andc (vector bool int, vector unsigned int); 17785vector unsigned int vec_andc (vector unsigned int, vector bool int); 17786vector unsigned int vec_andc (vector unsigned int, vector unsigned int); 17787vector bool short vec_andc (vector bool short, vector bool short); 17788vector signed short vec_andc (vector bool short, vector signed short); 17789vector signed short vec_andc (vector signed short, vector bool short); 17790vector signed short vec_andc (vector signed short, vector signed short); 17791vector unsigned short vec_andc (vector bool short, vector unsigned short); 17792vector unsigned short vec_andc (vector unsigned short, vector bool short); 17793vector unsigned short vec_andc (vector unsigned short, vector unsigned short); 17794vector signed char vec_andc (vector bool char, vector signed char); 17795vector bool char vec_andc (vector bool char, vector bool char); 17796vector signed char vec_andc (vector signed char, vector bool char); 17797vector signed char vec_andc (vector signed char, vector signed char); 17798vector unsigned char vec_andc (vector bool char, vector unsigned char); 17799vector unsigned char vec_andc (vector unsigned char, vector bool char); 17800vector unsigned char vec_andc (vector unsigned char, vector unsigned char); 17801 17802int vec_any_eq (vector signed char, vector bool char); 17803int vec_any_eq (vector signed char, vector signed char); 17804int vec_any_eq (vector unsigned char, vector bool char); 17805int vec_any_eq (vector unsigned char, vector unsigned char); 17806int vec_any_eq (vector bool char, vector bool char); 17807int vec_any_eq (vector bool char, vector unsigned char); 17808int vec_any_eq (vector bool char, vector signed char); 17809int vec_any_eq (vector signed short, vector bool short); 17810int vec_any_eq (vector signed short, vector signed short); 17811int vec_any_eq (vector unsigned short, vector bool short); 17812int vec_any_eq (vector unsigned short, vector unsigned short); 17813int vec_any_eq (vector bool short, vector bool short); 17814int vec_any_eq (vector bool short, vector unsigned short); 17815int vec_any_eq (vector bool short, vector signed short); 17816int vec_any_eq (vector pixel, vector pixel); 17817int vec_any_eq (vector signed int, vector bool int); 17818int vec_any_eq (vector signed int, vector signed int); 17819int vec_any_eq (vector unsigned int, vector bool int); 17820int vec_any_eq (vector unsigned int, vector unsigned int); 17821int vec_any_eq (vector bool int, vector bool int); 17822int vec_any_eq (vector bool int, vector unsigned int); 17823int vec_any_eq (vector bool int, vector signed int); 17824int vec_any_eq (vector float, vector float); 17825 17826int vec_any_ge (vector signed char, vector bool char); 17827int vec_any_ge (vector unsigned char, vector bool char); 17828int vec_any_ge (vector unsigned char, vector unsigned char); 17829int vec_any_ge (vector signed char, vector signed char); 17830int vec_any_ge (vector bool char, vector unsigned char); 17831int vec_any_ge (vector bool char, vector signed char); 17832int vec_any_ge (vector unsigned short, vector bool short); 17833int vec_any_ge (vector unsigned short, vector unsigned short); 17834int vec_any_ge (vector signed short, vector signed short); 17835int vec_any_ge (vector signed short, vector bool short); 17836int vec_any_ge (vector bool short, vector unsigned short); 17837int vec_any_ge (vector bool short, vector signed short); 17838int vec_any_ge (vector signed int, vector bool int); 17839int vec_any_ge (vector unsigned int, vector bool int); 17840int vec_any_ge (vector unsigned int, vector unsigned int); 17841int vec_any_ge (vector signed int, vector signed int); 17842int vec_any_ge (vector bool int, vector unsigned int); 17843int vec_any_ge (vector bool int, vector signed int); 17844int vec_any_ge (vector float, vector float); 17845 17846int vec_any_gt (vector bool char, vector unsigned char); 17847int vec_any_gt (vector unsigned char, vector bool char); 17848int vec_any_gt (vector unsigned char, vector unsigned char); 17849int vec_any_gt (vector bool char, vector signed char); 17850int vec_any_gt (vector signed char, vector bool char); 17851int vec_any_gt (vector signed char, vector signed char); 17852int vec_any_gt (vector bool short, vector unsigned short); 17853int vec_any_gt (vector unsigned short, vector bool short); 17854int vec_any_gt (vector unsigned short, vector unsigned short); 17855int vec_any_gt (vector bool short, vector signed short); 17856int vec_any_gt (vector signed short, vector bool short); 17857int vec_any_gt (vector signed short, vector signed short); 17858int vec_any_gt (vector bool int, vector unsigned int); 17859int vec_any_gt (vector unsigned int, vector bool int); 17860int vec_any_gt (vector unsigned int, vector unsigned int); 17861int vec_any_gt (vector bool int, vector signed int); 17862int vec_any_gt (vector signed int, vector bool int); 17863int vec_any_gt (vector signed int, vector signed int); 17864int vec_any_gt (vector float, vector float); 17865 17866int vec_any_le (vector bool char, vector unsigned char); 17867int vec_any_le (vector unsigned char, vector bool char); 17868int vec_any_le (vector unsigned char, vector unsigned char); 17869int vec_any_le (vector bool char, vector signed char); 17870int vec_any_le (vector signed char, vector bool char); 17871int vec_any_le (vector signed char, vector signed char); 17872int vec_any_le (vector bool short, vector unsigned short); 17873int vec_any_le (vector unsigned short, vector bool short); 17874int vec_any_le (vector unsigned short, vector unsigned short); 17875int vec_any_le (vector bool short, vector signed short); 17876int vec_any_le (vector signed short, vector bool short); 17877int vec_any_le (vector signed short, vector signed short); 17878int vec_any_le (vector bool int, vector unsigned int); 17879int vec_any_le (vector unsigned int, vector bool int); 17880int vec_any_le (vector unsigned int, vector unsigned int); 17881int vec_any_le (vector bool int, vector signed int); 17882int vec_any_le (vector signed int, vector bool int); 17883int vec_any_le (vector signed int, vector signed int); 17884int vec_any_le (vector float, vector float); 17885 17886int vec_any_lt (vector bool char, vector unsigned char); 17887int vec_any_lt (vector unsigned char, vector bool char); 17888int vec_any_lt (vector unsigned char, vector unsigned char); 17889int vec_any_lt (vector bool char, vector signed char); 17890int vec_any_lt (vector signed char, vector bool char); 17891int vec_any_lt (vector signed char, vector signed char); 17892int vec_any_lt (vector bool short, vector unsigned short); 17893int vec_any_lt (vector unsigned short, vector bool short); 17894int vec_any_lt (vector unsigned short, vector unsigned short); 17895int vec_any_lt (vector bool short, vector signed short); 17896int vec_any_lt (vector signed short, vector bool short); 17897int vec_any_lt (vector signed short, vector signed short); 17898int vec_any_lt (vector bool int, vector unsigned int); 17899int vec_any_lt (vector unsigned int, vector bool int); 17900int vec_any_lt (vector unsigned int, vector unsigned int); 17901int vec_any_lt (vector bool int, vector signed int); 17902int vec_any_lt (vector signed int, vector bool int); 17903int vec_any_lt (vector signed int, vector signed int); 17904int vec_any_lt (vector float, vector float); 17905 17906int vec_any_nan (vector float); 17907 17908int vec_any_ne (vector signed char, vector bool char); 17909int vec_any_ne (vector signed char, vector signed char); 17910int vec_any_ne (vector unsigned char, vector bool char); 17911int vec_any_ne (vector unsigned char, vector unsigned char); 17912int vec_any_ne (vector bool char, vector bool char); 17913int vec_any_ne (vector bool char, vector unsigned char); 17914int vec_any_ne (vector bool char, vector signed char); 17915int vec_any_ne (vector signed short, vector bool short); 17916int vec_any_ne (vector signed short, vector signed short); 17917int vec_any_ne (vector unsigned short, vector bool short); 17918int vec_any_ne (vector unsigned short, vector unsigned short); 17919int vec_any_ne (vector bool short, vector bool short); 17920int vec_any_ne (vector bool short, vector unsigned short); 17921int vec_any_ne (vector bool short, vector signed short); 17922int vec_any_ne (vector pixel, vector pixel); 17923int vec_any_ne (vector signed int, vector bool int); 17924int vec_any_ne (vector signed int, vector signed int); 17925int vec_any_ne (vector unsigned int, vector bool int); 17926int vec_any_ne (vector unsigned int, vector unsigned int); 17927int vec_any_ne (vector bool int, vector bool int); 17928int vec_any_ne (vector bool int, vector unsigned int); 17929int vec_any_ne (vector bool int, vector signed int); 17930int vec_any_ne (vector float, vector float); 17931 17932int vec_any_nge (vector float, vector float); 17933 17934int vec_any_ngt (vector float, vector float); 17935 17936int vec_any_nle (vector float, vector float); 17937 17938int vec_any_nlt (vector float, vector float); 17939 17940int vec_any_numeric (vector float); 17941 17942int vec_any_out (vector float, vector float); 17943 17944vector unsigned char vec_avg (vector unsigned char, vector unsigned char); 17945vector signed char vec_avg (vector signed char, vector signed char); 17946vector unsigned short vec_avg (vector unsigned short, vector unsigned short); 17947vector signed short vec_avg (vector signed short, vector signed short); 17948vector unsigned int vec_avg (vector unsigned int, vector unsigned int); 17949vector signed int vec_avg (vector signed int, vector signed int); 17950 17951vector float vec_ceil (vector float); 17952 17953vector signed int vec_cmpb (vector float, vector float); 17954 17955vector bool char vec_cmpeq (vector bool char, vector bool char); 17956vector bool short vec_cmpeq (vector bool short, vector bool short); 17957vector bool int vec_cmpeq (vector bool int, vector bool int); 17958vector bool char vec_cmpeq (vector signed char, vector signed char); 17959vector bool char vec_cmpeq (vector unsigned char, vector unsigned char); 17960vector bool short vec_cmpeq (vector signed short, vector signed short); 17961vector bool short vec_cmpeq (vector unsigned short, vector unsigned short); 17962vector bool int vec_cmpeq (vector signed int, vector signed int); 17963vector bool int vec_cmpeq (vector unsigned int, vector unsigned int); 17964vector bool int vec_cmpeq (vector float, vector float); 17965 17966vector bool int vec_cmpge (vector float, vector float); 17967 17968vector bool char vec_cmpgt (vector unsigned char, vector unsigned char); 17969vector bool char vec_cmpgt (vector signed char, vector signed char); 17970vector bool short vec_cmpgt (vector unsigned short, vector unsigned short); 17971vector bool short vec_cmpgt (vector signed short, vector signed short); 17972vector bool int vec_cmpgt (vector unsigned int, vector unsigned int); 17973vector bool int vec_cmpgt (vector signed int, vector signed int); 17974vector bool int vec_cmpgt (vector float, vector float); 17975 17976vector bool int vec_cmple (vector float, vector float); 17977 17978vector bool char vec_cmplt (vector unsigned char, vector unsigned char); 17979vector bool char vec_cmplt (vector signed char, vector signed char); 17980vector bool short vec_cmplt (vector unsigned short, vector unsigned short); 17981vector bool short vec_cmplt (vector signed short, vector signed short); 17982vector bool int vec_cmplt (vector unsigned int, vector unsigned int); 17983vector bool int vec_cmplt (vector signed int, vector signed int); 17984vector bool int vec_cmplt (vector float, vector float); 17985 17986vector float vec_cpsgn (vector float, vector float); 17987 17988vector float vec_ctf (vector unsigned int, const int); 17989vector float vec_ctf (vector signed int, const int); 17990 17991vector signed int vec_cts (vector float, const int); 17992 17993vector unsigned int vec_ctu (vector float, const int); 17994 17995void vec_dss (const int); 17996 17997void vec_dssall (void); 17998 17999void vec_dst (const vector unsigned char *, int, const int); 18000void vec_dst (const vector signed char *, int, const int); 18001void vec_dst (const vector bool char *, int, const int); 18002void vec_dst (const vector unsigned short *, int, const int); 18003void vec_dst (const vector signed short *, int, const int); 18004void vec_dst (const vector bool short *, int, const int); 18005void vec_dst (const vector pixel *, int, const int); 18006void vec_dst (const vector unsigned int *, int, const int); 18007void vec_dst (const vector signed int *, int, const int); 18008void vec_dst (const vector bool int *, int, const int); 18009void vec_dst (const vector float *, int, const int); 18010void vec_dst (const unsigned char *, int, const int); 18011void vec_dst (const signed char *, int, const int); 18012void vec_dst (const unsigned short *, int, const int); 18013void vec_dst (const short *, int, const int); 18014void vec_dst (const unsigned int *, int, const int); 18015void vec_dst (const int *, int, const int); 18016void vec_dst (const float *, int, const int); 18017 18018void vec_dstst (const vector unsigned char *, int, const int); 18019void vec_dstst (const vector signed char *, int, const int); 18020void vec_dstst (const vector bool char *, int, const int); 18021void vec_dstst (const vector unsigned short *, int, const int); 18022void vec_dstst (const vector signed short *, int, const int); 18023void vec_dstst (const vector bool short *, int, const int); 18024void vec_dstst (const vector pixel *, int, const int); 18025void vec_dstst (const vector unsigned int *, int, const int); 18026void vec_dstst (const vector signed int *, int, const int); 18027void vec_dstst (const vector bool int *, int, const int); 18028void vec_dstst (const vector float *, int, const int); 18029void vec_dstst (const unsigned char *, int, const int); 18030void vec_dstst (const signed char *, int, const int); 18031void vec_dstst (const unsigned short *, int, const int); 18032void vec_dstst (const short *, int, const int); 18033void vec_dstst (const unsigned int *, int, const int); 18034void vec_dstst (const int *, int, const int); 18035void vec_dstst (const unsigned long *, int, const int); 18036void vec_dstst (const long *, int, const int); 18037void vec_dstst (const float *, int, const int); 18038 18039void vec_dststt (const vector unsigned char *, int, const int); 18040void vec_dststt (const vector signed char *, int, const int); 18041void vec_dststt (const vector bool char *, int, const int); 18042void vec_dststt (const vector unsigned short *, int, const int); 18043void vec_dststt (const vector signed short *, int, const int); 18044void vec_dststt (const vector bool short *, int, const int); 18045void vec_dststt (const vector pixel *, int, const int); 18046void vec_dststt (const vector unsigned int *, int, const int); 18047void vec_dststt (const vector signed int *, int, const int); 18048void vec_dststt (const vector bool int *, int, const int); 18049void vec_dststt (const vector float *, int, const int); 18050void vec_dststt (const unsigned char *, int, const int); 18051void vec_dststt (const signed char *, int, const int); 18052void vec_dststt (const unsigned short *, int, const int); 18053void vec_dststt (const short *, int, const int); 18054void vec_dststt (const unsigned int *, int, const int); 18055void vec_dststt (const int *, int, const int); 18056void vec_dststt (const float *, int, const int); 18057 18058void vec_dstt (const vector unsigned char *, int, const int); 18059void vec_dstt (const vector signed char *, int, const int); 18060void vec_dstt (const vector bool char *, int, const int); 18061void vec_dstt (const vector unsigned short *, int, const int); 18062void vec_dstt (const vector signed short *, int, const int); 18063void vec_dstt (const vector bool short *, int, const int); 18064void vec_dstt (const vector pixel *, int, const int); 18065void vec_dstt (const vector unsigned int *, int, const int); 18066void vec_dstt (const vector signed int *, int, const int); 18067void vec_dstt (const vector bool int *, int, const int); 18068void vec_dstt (const vector float *, int, const int); 18069void vec_dstt (const unsigned char *, int, const int); 18070void vec_dstt (const signed char *, int, const int); 18071void vec_dstt (const unsigned short *, int, const int); 18072void vec_dstt (const short *, int, const int); 18073void vec_dstt (const unsigned int *, int, const int); 18074void vec_dstt (const int *, int, const int); 18075void vec_dstt (const float *, int, const int); 18076 18077vector float vec_expte (vector float); 18078 18079vector float vec_floor (vector float); 18080 18081vector float vec_ld (int, const vector float *); 18082vector float vec_ld (int, const float *); 18083vector bool int vec_ld (int, const vector bool int *); 18084vector signed int vec_ld (int, const vector signed int *); 18085vector signed int vec_ld (int, const int *); 18086vector unsigned int vec_ld (int, const vector unsigned int *); 18087vector unsigned int vec_ld (int, const unsigned int *); 18088vector bool short vec_ld (int, const vector bool short *); 18089vector pixel vec_ld (int, const vector pixel *); 18090vector signed short vec_ld (int, const vector signed short *); 18091vector signed short vec_ld (int, const short *); 18092vector unsigned short vec_ld (int, const vector unsigned short *); 18093vector unsigned short vec_ld (int, const unsigned short *); 18094vector bool char vec_ld (int, const vector bool char *); 18095vector signed char vec_ld (int, const vector signed char *); 18096vector signed char vec_ld (int, const signed char *); 18097vector unsigned char vec_ld (int, const vector unsigned char *); 18098vector unsigned char vec_ld (int, const unsigned char *); 18099 18100vector signed char vec_lde (int, const signed char *); 18101vector unsigned char vec_lde (int, const unsigned char *); 18102vector signed short vec_lde (int, const short *); 18103vector unsigned short vec_lde (int, const unsigned short *); 18104vector float vec_lde (int, const float *); 18105vector signed int vec_lde (int, const int *); 18106vector unsigned int vec_lde (int, const unsigned int *); 18107 18108vector float vec_ldl (int, const vector float *); 18109vector float vec_ldl (int, const float *); 18110vector bool int vec_ldl (int, const vector bool int *); 18111vector signed int vec_ldl (int, const vector signed int *); 18112vector signed int vec_ldl (int, const int *); 18113vector unsigned int vec_ldl (int, const vector unsigned int *); 18114vector unsigned int vec_ldl (int, const unsigned int *); 18115vector bool short vec_ldl (int, const vector bool short *); 18116vector pixel vec_ldl (int, const vector pixel *); 18117vector signed short vec_ldl (int, const vector signed short *); 18118vector signed short vec_ldl (int, const short *); 18119vector unsigned short vec_ldl (int, const vector unsigned short *); 18120vector unsigned short vec_ldl (int, const unsigned short *); 18121vector bool char vec_ldl (int, const vector bool char *); 18122vector signed char vec_ldl (int, const vector signed char *); 18123vector signed char vec_ldl (int, const signed char *); 18124vector unsigned char vec_ldl (int, const vector unsigned char *); 18125vector unsigned char vec_ldl (int, const unsigned char *); 18126 18127vector float vec_loge (vector float); 18128 18129vector signed char vec_lvebx (int, char *); 18130vector unsigned char vec_lvebx (int, unsigned char *); 18131 18132vector signed short vec_lvehx (int, short *); 18133vector unsigned short vec_lvehx (int, unsigned short *); 18134 18135vector float vec_lvewx (int, float *); 18136vector signed int vec_lvewx (int, int *); 18137vector unsigned int vec_lvewx (int, unsigned int *); 18138 18139vector unsigned char vec_lvsl (int, const unsigned char *); 18140vector unsigned char vec_lvsl (int, const signed char *); 18141vector unsigned char vec_lvsl (int, const unsigned short *); 18142vector unsigned char vec_lvsl (int, const short *); 18143vector unsigned char vec_lvsl (int, const unsigned int *); 18144vector unsigned char vec_lvsl (int, const int *); 18145vector unsigned char vec_lvsl (int, const float *); 18146 18147vector unsigned char vec_lvsr (int, const unsigned char *); 18148vector unsigned char vec_lvsr (int, const signed char *); 18149vector unsigned char vec_lvsr (int, const unsigned short *); 18150vector unsigned char vec_lvsr (int, const short *); 18151vector unsigned char vec_lvsr (int, const unsigned int *); 18152vector unsigned char vec_lvsr (int, const int *); 18153vector unsigned char vec_lvsr (int, const float *); 18154 18155vector float vec_madd (vector float, vector float, vector float); 18156 18157vector signed short vec_madds (vector signed short, vector signed short, 18158 vector signed short); 18159 18160vector unsigned char vec_max (vector bool char, vector unsigned char); 18161vector unsigned char vec_max (vector unsigned char, vector bool char); 18162vector unsigned char vec_max (vector unsigned char, vector unsigned char); 18163vector signed char vec_max (vector bool char, vector signed char); 18164vector signed char vec_max (vector signed char, vector bool char); 18165vector signed char vec_max (vector signed char, vector signed char); 18166vector unsigned short vec_max (vector bool short, vector unsigned short); 18167vector unsigned short vec_max (vector unsigned short, vector bool short); 18168vector unsigned short vec_max (vector unsigned short, vector unsigned short); 18169vector signed short vec_max (vector bool short, vector signed short); 18170vector signed short vec_max (vector signed short, vector bool short); 18171vector signed short vec_max (vector signed short, vector signed short); 18172vector unsigned int vec_max (vector bool int, vector unsigned int); 18173vector unsigned int vec_max (vector unsigned int, vector bool int); 18174vector unsigned int vec_max (vector unsigned int, vector unsigned int); 18175vector signed int vec_max (vector bool int, vector signed int); 18176vector signed int vec_max (vector signed int, vector bool int); 18177vector signed int vec_max (vector signed int, vector signed int); 18178vector float vec_max (vector float, vector float); 18179 18180vector bool char vec_mergeh (vector bool char, vector bool char); 18181vector signed char vec_mergeh (vector signed char, vector signed char); 18182vector unsigned char vec_mergeh (vector unsigned char, vector unsigned char); 18183vector bool short vec_mergeh (vector bool short, vector bool short); 18184vector pixel vec_mergeh (vector pixel, vector pixel); 18185vector signed short vec_mergeh (vector signed short, vector signed short); 18186vector unsigned short vec_mergeh (vector unsigned short, vector unsigned short); 18187vector float vec_mergeh (vector float, vector float); 18188vector bool int vec_mergeh (vector bool int, vector bool int); 18189vector signed int vec_mergeh (vector signed int, vector signed int); 18190vector unsigned int vec_mergeh (vector unsigned int, vector unsigned int); 18191 18192vector bool char vec_mergel (vector bool char, vector bool char); 18193vector signed char vec_mergel (vector signed char, vector signed char); 18194vector unsigned char vec_mergel (vector unsigned char, vector unsigned char); 18195vector bool short vec_mergel (vector bool short, vector bool short); 18196vector pixel vec_mergel (vector pixel, vector pixel); 18197vector signed short vec_mergel (vector signed short, vector signed short); 18198vector unsigned short vec_mergel (vector unsigned short, vector unsigned short); 18199vector float vec_mergel (vector float, vector float); 18200vector bool int vec_mergel (vector bool int, vector bool int); 18201vector signed int vec_mergel (vector signed int, vector signed int); 18202vector unsigned int vec_mergel (vector unsigned int, vector unsigned int); 18203 18204vector unsigned short vec_mfvscr (void); 18205 18206vector unsigned char vec_min (vector bool char, vector unsigned char); 18207vector unsigned char vec_min (vector unsigned char, vector bool char); 18208vector unsigned char vec_min (vector unsigned char, vector unsigned char); 18209vector signed char vec_min (vector bool char, vector signed char); 18210vector signed char vec_min (vector signed char, vector bool char); 18211vector signed char vec_min (vector signed char, vector signed char); 18212vector unsigned short vec_min (vector bool short, vector unsigned short); 18213vector unsigned short vec_min (vector unsigned short, vector bool short); 18214vector unsigned short vec_min (vector unsigned short, vector unsigned short); 18215vector signed short vec_min (vector bool short, vector signed short); 18216vector signed short vec_min (vector signed short, vector bool short); 18217vector signed short vec_min (vector signed short, vector signed short); 18218vector unsigned int vec_min (vector bool int, vector unsigned int); 18219vector unsigned int vec_min (vector unsigned int, vector bool int); 18220vector unsigned int vec_min (vector unsigned int, vector unsigned int); 18221vector signed int vec_min (vector bool int, vector signed int); 18222vector signed int vec_min (vector signed int, vector bool int); 18223vector signed int vec_min (vector signed int, vector signed int); 18224vector float vec_min (vector float, vector float); 18225 18226vector signed short vec_mladd (vector signed short, vector signed short, 18227 vector signed short); 18228vector signed short vec_mladd (vector signed short, vector unsigned short, 18229 vector unsigned short); 18230vector signed short vec_mladd (vector unsigned short, vector signed short, 18231 vector signed short); 18232vector unsigned short vec_mladd (vector unsigned short, vector unsigned short, 18233 vector unsigned short); 18234 18235vector signed short vec_mradds (vector signed short, vector signed short, 18236 vector signed short); 18237 18238vector unsigned int vec_msum (vector unsigned char, vector unsigned char, 18239 vector unsigned int); 18240vector signed int vec_msum (vector signed char, vector unsigned char, 18241 vector signed int); 18242vector unsigned int vec_msum (vector unsigned short, vector unsigned short, 18243 vector unsigned int); 18244vector signed int vec_msum (vector signed short, vector signed short, 18245 vector signed int); 18246 18247vector unsigned int vec_msums (vector unsigned short, vector unsigned short, 18248 vector unsigned int); 18249vector signed int vec_msums (vector signed short, vector signed short, 18250 vector signed int); 18251 18252void vec_mtvscr (vector signed int); 18253void vec_mtvscr (vector unsigned int); 18254void vec_mtvscr (vector bool int); 18255void vec_mtvscr (vector signed short); 18256void vec_mtvscr (vector unsigned short); 18257void vec_mtvscr (vector bool short); 18258void vec_mtvscr (vector pixel); 18259void vec_mtvscr (vector signed char); 18260void vec_mtvscr (vector unsigned char); 18261void vec_mtvscr (vector bool char); 18262 18263vector float vec_mul (vector float, vector float); 18264 18265vector unsigned short vec_mule (vector unsigned char, vector unsigned char); 18266vector signed short vec_mule (vector signed char, vector signed char); 18267vector unsigned int vec_mule (vector unsigned short, vector unsigned short); 18268vector signed int vec_mule (vector signed short, vector signed short); 18269 18270vector unsigned short vec_mulo (vector unsigned char, vector unsigned char); 18271vector signed short vec_mulo (vector signed char, vector signed char); 18272vector unsigned int vec_mulo (vector unsigned short, vector unsigned short); 18273vector signed int vec_mulo (vector signed short, vector signed short); 18274 18275vector signed char vec_nabs (vector signed char); 18276vector signed short vec_nabs (vector signed short); 18277vector signed int vec_nabs (vector signed int); 18278vector float vec_nabs (vector float); 18279 18280vector float vec_nmsub (vector float, vector float, vector float); 18281 18282vector float vec_nor (vector float, vector float); 18283vector signed int vec_nor (vector signed int, vector signed int); 18284vector unsigned int vec_nor (vector unsigned int, vector unsigned int); 18285vector bool int vec_nor (vector bool int, vector bool int); 18286vector signed short vec_nor (vector signed short, vector signed short); 18287vector unsigned short vec_nor (vector unsigned short, vector unsigned short); 18288vector bool short vec_nor (vector bool short, vector bool short); 18289vector signed char vec_nor (vector signed char, vector signed char); 18290vector unsigned char vec_nor (vector unsigned char, vector unsigned char); 18291vector bool char vec_nor (vector bool char, vector bool char); 18292 18293vector float vec_or (vector float, vector float); 18294vector float vec_or (vector float, vector bool int); 18295vector float vec_or (vector bool int, vector float); 18296vector bool int vec_or (vector bool int, vector bool int); 18297vector signed int vec_or (vector bool int, vector signed int); 18298vector signed int vec_or (vector signed int, vector bool int); 18299vector signed int vec_or (vector signed int, vector signed int); 18300vector unsigned int vec_or (vector bool int, vector unsigned int); 18301vector unsigned int vec_or (vector unsigned int, vector bool int); 18302vector unsigned int vec_or (vector unsigned int, vector unsigned int); 18303vector bool short vec_or (vector bool short, vector bool short); 18304vector signed short vec_or (vector bool short, vector signed short); 18305vector signed short vec_or (vector signed short, vector bool short); 18306vector signed short vec_or (vector signed short, vector signed short); 18307vector unsigned short vec_or (vector bool short, vector unsigned short); 18308vector unsigned short vec_or (vector unsigned short, vector bool short); 18309vector unsigned short vec_or (vector unsigned short, vector unsigned short); 18310vector signed char vec_or (vector bool char, vector signed char); 18311vector bool char vec_or (vector bool char, vector bool char); 18312vector signed char vec_or (vector signed char, vector bool char); 18313vector signed char vec_or (vector signed char, vector signed char); 18314vector unsigned char vec_or (vector bool char, vector unsigned char); 18315vector unsigned char vec_or (vector unsigned char, vector bool char); 18316vector unsigned char vec_or (vector unsigned char, vector unsigned char); 18317 18318vector signed char vec_pack (vector signed short, vector signed short); 18319vector unsigned char vec_pack (vector unsigned short, vector unsigned short); 18320vector bool char vec_pack (vector bool short, vector bool short); 18321vector signed short vec_pack (vector signed int, vector signed int); 18322vector unsigned short vec_pack (vector unsigned int, vector unsigned int); 18323vector bool short vec_pack (vector bool int, vector bool int); 18324 18325vector pixel vec_packpx (vector unsigned int, vector unsigned int); 18326 18327vector unsigned char vec_packs (vector unsigned short, vector unsigned short); 18328vector signed char vec_packs (vector signed short, vector signed short); 18329vector unsigned short vec_packs (vector unsigned int, vector unsigned int); 18330vector signed short vec_packs (vector signed int, vector signed int); 18331 18332vector unsigned char vec_packsu (vector unsigned short, vector unsigned short); 18333vector unsigned char vec_packsu (vector signed short, vector signed short); 18334vector unsigned short vec_packsu (vector unsigned int, vector unsigned int); 18335vector unsigned short vec_packsu (vector signed int, vector signed int); 18336 18337vector float vec_perm (vector float, vector float, vector unsigned char); 18338vector signed int vec_perm (vector signed int, vector signed int, vector unsigned char); 18339vector unsigned int vec_perm (vector unsigned int, vector unsigned int, 18340 vector unsigned char); 18341vector bool int vec_perm (vector bool int, vector bool int, vector unsigned char); 18342vector signed short vec_perm (vector signed short, vector signed short, 18343 vector unsigned char); 18344vector unsigned short vec_perm (vector unsigned short, vector unsigned short, 18345 vector unsigned char); 18346vector bool short vec_perm (vector bool short, vector bool short, vector unsigned char); 18347vector pixel vec_perm (vector pixel, vector pixel, vector unsigned char); 18348vector signed char vec_perm (vector signed char, vector signed char, 18349 vector unsigned char); 18350vector unsigned char vec_perm (vector unsigned char, vector unsigned char, 18351 vector unsigned char); 18352vector bool char vec_perm (vector bool char, vector bool char, vector unsigned char); 18353 18354vector float vec_re (vector float); 18355 18356vector bool char vec_reve (vector bool char); 18357vector signed char vec_reve (vector signed char); 18358vector unsigned char vec_reve (vector unsigned char); 18359vector bool int vec_reve (vector bool int); 18360vector signed int vec_reve (vector signed int); 18361vector unsigned int vec_reve (vector unsigned int); 18362vector bool short vec_reve (vector bool short); 18363vector signed short vec_reve (vector signed short); 18364vector unsigned short vec_reve (vector unsigned short); 18365 18366vector signed char vec_rl (vector signed char, vector unsigned char); 18367vector unsigned char vec_rl (vector unsigned char, vector unsigned char); 18368vector signed short vec_rl (vector signed short, vector unsigned short); 18369vector unsigned short vec_rl (vector unsigned short, vector unsigned short); 18370vector signed int vec_rl (vector signed int, vector unsigned int); 18371vector unsigned int vec_rl (vector unsigned int, vector unsigned int); 18372 18373vector float vec_round (vector float); 18374 18375vector float vec_rsqrt (vector float); 18376 18377vector float vec_rsqrte (vector float); 18378 18379vector float vec_sel (vector float, vector float, vector bool int); 18380vector float vec_sel (vector float, vector float, vector unsigned int); 18381vector signed int vec_sel (vector signed int, vector signed int, vector bool int); 18382vector signed int vec_sel (vector signed int, vector signed int, vector unsigned int); 18383vector unsigned int vec_sel (vector unsigned int, vector unsigned int, vector bool int); 18384vector unsigned int vec_sel (vector unsigned int, vector unsigned int, 18385 vector unsigned int); 18386vector bool int vec_sel (vector bool int, vector bool int, vector bool int); 18387vector bool int vec_sel (vector bool int, vector bool int, vector unsigned int); 18388vector signed short vec_sel (vector signed short, vector signed short, 18389 vector bool short); 18390vector signed short vec_sel (vector signed short, vector signed short, 18391 vector unsigned short); 18392vector unsigned short vec_sel (vector unsigned short, vector unsigned short, 18393 vector bool short); 18394vector unsigned short vec_sel (vector unsigned short, vector unsigned short, 18395 vector unsigned short); 18396vector bool short vec_sel (vector bool short, vector bool short, vector bool short); 18397vector bool short vec_sel (vector bool short, vector bool short, vector unsigned short); 18398vector signed char vec_sel (vector signed char, vector signed char, vector bool char); 18399vector signed char vec_sel (vector signed char, vector signed char, 18400 vector unsigned char); 18401vector unsigned char vec_sel (vector unsigned char, vector unsigned char, 18402 vector bool char); 18403vector unsigned char vec_sel (vector unsigned char, vector unsigned char, 18404 vector unsigned char); 18405vector bool char vec_sel (vector bool char, vector bool char, vector bool char); 18406vector bool char vec_sel (vector bool char, vector bool char, vector unsigned char); 18407 18408vector signed char vec_sl (vector signed char, vector unsigned char); 18409vector unsigned char vec_sl (vector unsigned char, vector unsigned char); 18410vector signed short vec_sl (vector signed short, vector unsigned short); 18411vector unsigned short vec_sl (vector unsigned short, vector unsigned short); 18412vector signed int vec_sl (vector signed int, vector unsigned int); 18413vector unsigned int vec_sl (vector unsigned int, vector unsigned int); 18414 18415vector float vec_sld (vector float, vector float, const int); 18416vector signed int vec_sld (vector signed int, vector signed int, const int); 18417vector unsigned int vec_sld (vector unsigned int, vector unsigned int, const int); 18418vector bool int vec_sld (vector bool int, vector bool int, const int); 18419vector signed short vec_sld (vector signed short, vector signed short, const int); 18420vector unsigned short vec_sld (vector unsigned short, vector unsigned short, const int); 18421vector bool short vec_sld (vector bool short, vector bool short, const int); 18422vector pixel vec_sld (vector pixel, vector pixel, const int); 18423vector signed char vec_sld (vector signed char, vector signed char, const int); 18424vector unsigned char vec_sld (vector unsigned char, vector unsigned char, const int); 18425vector bool char vec_sld (vector bool char, vector bool char, const int); 18426 18427vector signed int vec_sll (vector signed int, vector unsigned int); 18428vector signed int vec_sll (vector signed int, vector unsigned short); 18429vector signed int vec_sll (vector signed int, vector unsigned char); 18430vector unsigned int vec_sll (vector unsigned int, vector unsigned int); 18431vector unsigned int vec_sll (vector unsigned int, vector unsigned short); 18432vector unsigned int vec_sll (vector unsigned int, vector unsigned char); 18433vector bool int vec_sll (vector bool int, vector unsigned int); 18434vector bool int vec_sll (vector bool int, vector unsigned short); 18435vector bool int vec_sll (vector bool int, vector unsigned char); 18436vector signed short vec_sll (vector signed short, vector unsigned int); 18437vector signed short vec_sll (vector signed short, vector unsigned short); 18438vector signed short vec_sll (vector signed short, vector unsigned char); 18439vector unsigned short vec_sll (vector unsigned short, vector unsigned int); 18440vector unsigned short vec_sll (vector unsigned short, vector unsigned short); 18441vector unsigned short vec_sll (vector unsigned short, vector unsigned char); 18442vector bool short vec_sll (vector bool short, vector unsigned int); 18443vector bool short vec_sll (vector bool short, vector unsigned short); 18444vector bool short vec_sll (vector bool short, vector unsigned char); 18445vector pixel vec_sll (vector pixel, vector unsigned int); 18446vector pixel vec_sll (vector pixel, vector unsigned short); 18447vector pixel vec_sll (vector pixel, vector unsigned char); 18448vector signed char vec_sll (vector signed char, vector unsigned int); 18449vector signed char vec_sll (vector signed char, vector unsigned short); 18450vector signed char vec_sll (vector signed char, vector unsigned char); 18451vector unsigned char vec_sll (vector unsigned char, vector unsigned int); 18452vector unsigned char vec_sll (vector unsigned char, vector unsigned short); 18453vector unsigned char vec_sll (vector unsigned char, vector unsigned char); 18454vector bool char vec_sll (vector bool char, vector unsigned int); 18455vector bool char vec_sll (vector bool char, vector unsigned short); 18456vector bool char vec_sll (vector bool char, vector unsigned char); 18457 18458vector float vec_slo (vector float, vector signed char); 18459vector float vec_slo (vector float, vector unsigned char); 18460vector signed int vec_slo (vector signed int, vector signed char); 18461vector signed int vec_slo (vector signed int, vector unsigned char); 18462vector unsigned int vec_slo (vector unsigned int, vector signed char); 18463vector unsigned int vec_slo (vector unsigned int, vector unsigned char); 18464vector signed short vec_slo (vector signed short, vector signed char); 18465vector signed short vec_slo (vector signed short, vector unsigned char); 18466vector unsigned short vec_slo (vector unsigned short, vector signed char); 18467vector unsigned short vec_slo (vector unsigned short, vector unsigned char); 18468vector pixel vec_slo (vector pixel, vector signed char); 18469vector pixel vec_slo (vector pixel, vector unsigned char); 18470vector signed char vec_slo (vector signed char, vector signed char); 18471vector signed char vec_slo (vector signed char, vector unsigned char); 18472vector unsigned char vec_slo (vector unsigned char, vector signed char); 18473vector unsigned char vec_slo (vector unsigned char, vector unsigned char); 18474 18475vector signed char vec_splat (vector signed char, const int); 18476vector unsigned char vec_splat (vector unsigned char, const int); 18477vector bool char vec_splat (vector bool char, const int); 18478vector signed short vec_splat (vector signed short, const int); 18479vector unsigned short vec_splat (vector unsigned short, const int); 18480vector bool short vec_splat (vector bool short, const int); 18481vector pixel vec_splat (vector pixel, const int); 18482vector float vec_splat (vector float, const int); 18483vector signed int vec_splat (vector signed int, const int); 18484vector unsigned int vec_splat (vector unsigned int, const int); 18485vector bool int vec_splat (vector bool int, const int); 18486 18487vector signed short vec_splat_s16 (const int); 18488 18489vector signed int vec_splat_s32 (const int); 18490 18491vector signed char vec_splat_s8 (const int); 18492 18493vector unsigned short vec_splat_u16 (const int); 18494 18495vector unsigned int vec_splat_u32 (const int); 18496 18497vector unsigned char vec_splat_u8 (const int); 18498 18499vector signed char vec_splats (signed char); 18500vector unsigned char vec_splats (unsigned char); 18501vector signed short vec_splats (signed short); 18502vector unsigned short vec_splats (unsigned short); 18503vector signed int vec_splats (signed int); 18504vector unsigned int vec_splats (unsigned int); 18505vector float vec_splats (float); 18506 18507vector signed char vec_sr (vector signed char, vector unsigned char); 18508vector unsigned char vec_sr (vector unsigned char, vector unsigned char); 18509vector signed short vec_sr (vector signed short, vector unsigned short); 18510vector unsigned short vec_sr (vector unsigned short, vector unsigned short); 18511vector signed int vec_sr (vector signed int, vector unsigned int); 18512vector unsigned int vec_sr (vector unsigned int, vector unsigned int); 18513 18514vector signed char vec_sra (vector signed char, vector unsigned char); 18515vector unsigned char vec_sra (vector unsigned char, vector unsigned char); 18516vector signed short vec_sra (vector signed short, vector unsigned short); 18517vector unsigned short vec_sra (vector unsigned short, vector unsigned short); 18518vector signed int vec_sra (vector signed int, vector unsigned int); 18519vector unsigned int vec_sra (vector unsigned int, vector unsigned int); 18520 18521vector signed int vec_srl (vector signed int, vector unsigned int); 18522vector signed int vec_srl (vector signed int, vector unsigned short); 18523vector signed int vec_srl (vector signed int, vector unsigned char); 18524vector unsigned int vec_srl (vector unsigned int, vector unsigned int); 18525vector unsigned int vec_srl (vector unsigned int, vector unsigned short); 18526vector unsigned int vec_srl (vector unsigned int, vector unsigned char); 18527vector bool int vec_srl (vector bool int, vector unsigned int); 18528vector bool int vec_srl (vector bool int, vector unsigned short); 18529vector bool int vec_srl (vector bool int, vector unsigned char); 18530vector signed short vec_srl (vector signed short, vector unsigned int); 18531vector signed short vec_srl (vector signed short, vector unsigned short); 18532vector signed short vec_srl (vector signed short, vector unsigned char); 18533vector unsigned short vec_srl (vector unsigned short, vector unsigned int); 18534vector unsigned short vec_srl (vector unsigned short, vector unsigned short); 18535vector unsigned short vec_srl (vector unsigned short, vector unsigned char); 18536vector bool short vec_srl (vector bool short, vector unsigned int); 18537vector bool short vec_srl (vector bool short, vector unsigned short); 18538vector bool short vec_srl (vector bool short, vector unsigned char); 18539vector pixel vec_srl (vector pixel, vector unsigned int); 18540vector pixel vec_srl (vector pixel, vector unsigned short); 18541vector pixel vec_srl (vector pixel, vector unsigned char); 18542vector signed char vec_srl (vector signed char, vector unsigned int); 18543vector signed char vec_srl (vector signed char, vector unsigned short); 18544vector signed char vec_srl (vector signed char, vector unsigned char); 18545vector unsigned char vec_srl (vector unsigned char, vector unsigned int); 18546vector unsigned char vec_srl (vector unsigned char, vector unsigned short); 18547vector unsigned char vec_srl (vector unsigned char, vector unsigned char); 18548vector bool char vec_srl (vector bool char, vector unsigned int); 18549vector bool char vec_srl (vector bool char, vector unsigned short); 18550vector bool char vec_srl (vector bool char, vector unsigned char); 18551 18552vector float vec_sro (vector float, vector signed char); 18553vector float vec_sro (vector float, vector unsigned char); 18554vector signed int vec_sro (vector signed int, vector signed char); 18555vector signed int vec_sro (vector signed int, vector unsigned char); 18556vector unsigned int vec_sro (vector unsigned int, vector signed char); 18557vector unsigned int vec_sro (vector unsigned int, vector unsigned char); 18558vector signed short vec_sro (vector signed short, vector signed char); 18559vector signed short vec_sro (vector signed short, vector unsigned char); 18560vector unsigned short vec_sro (vector unsigned short, vector signed char); 18561vector unsigned short vec_sro (vector unsigned short, vector unsigned char); 18562vector pixel vec_sro (vector pixel, vector signed char); 18563vector pixel vec_sro (vector pixel, vector unsigned char); 18564vector signed char vec_sro (vector signed char, vector signed char); 18565vector signed char vec_sro (vector signed char, vector unsigned char); 18566vector unsigned char vec_sro (vector unsigned char, vector signed char); 18567vector unsigned char vec_sro (vector unsigned char, vector unsigned char); 18568 18569void vec_st (vector float, int, vector float *); 18570void vec_st (vector float, int, float *); 18571void vec_st (vector signed int, int, vector signed int *); 18572void vec_st (vector signed int, int, int *); 18573void vec_st (vector unsigned int, int, vector unsigned int *); 18574void vec_st (vector unsigned int, int, unsigned int *); 18575void vec_st (vector bool int, int, vector bool int *); 18576void vec_st (vector bool int, int, unsigned int *); 18577void vec_st (vector bool int, int, int *); 18578void vec_st (vector signed short, int, vector signed short *); 18579void vec_st (vector signed short, int, short *); 18580void vec_st (vector unsigned short, int, vector unsigned short *); 18581void vec_st (vector unsigned short, int, unsigned short *); 18582void vec_st (vector bool short, int, vector bool short *); 18583void vec_st (vector bool short, int, unsigned short *); 18584void vec_st (vector pixel, int, vector pixel *); 18585void vec_st (vector bool short, int, short *); 18586void vec_st (vector signed char, int, vector signed char *); 18587void vec_st (vector signed char, int, signed char *); 18588void vec_st (vector unsigned char, int, vector unsigned char *); 18589void vec_st (vector unsigned char, int, unsigned char *); 18590void vec_st (vector bool char, int, vector bool char *); 18591void vec_st (vector bool char, int, unsigned char *); 18592void vec_st (vector bool char, int, signed char *); 18593 18594void vec_ste (vector signed char, int, signed char *); 18595void vec_ste (vector unsigned char, int, unsigned char *); 18596void vec_ste (vector bool char, int, signed char *); 18597void vec_ste (vector bool char, int, unsigned char *); 18598void vec_ste (vector signed short, int, short *); 18599void vec_ste (vector unsigned short, int, unsigned short *); 18600void vec_ste (vector bool short, int, short *); 18601void vec_ste (vector bool short, int, unsigned short *); 18602void vec_ste (vector pixel, int, short *); 18603void vec_ste (vector pixel, int, unsigned short *); 18604void vec_ste (vector float, int, float *); 18605void vec_ste (vector signed int, int, int *); 18606void vec_ste (vector unsigned int, int, unsigned int *); 18607void vec_ste (vector bool int, int, int *); 18608void vec_ste (vector bool int, int, unsigned int *); 18609 18610void vec_stl (vector float, int, vector float *); 18611void vec_stl (vector float, int, float *); 18612void vec_stl (vector signed int, int, vector signed int *); 18613void vec_stl (vector signed int, int, int *); 18614void vec_stl (vector unsigned int, int, vector unsigned int *); 18615void vec_stl (vector unsigned int, int, unsigned int *); 18616void vec_stl (vector bool int, int, vector bool int *); 18617void vec_stl (vector bool int, int, unsigned int *); 18618void vec_stl (vector bool int, int, int *); 18619void vec_stl (vector signed short, int, vector signed short *); 18620void vec_stl (vector signed short, int, short *); 18621void vec_stl (vector unsigned short, int, vector unsigned short *); 18622void vec_stl (vector unsigned short, int, unsigned short *); 18623void vec_stl (vector bool short, int, vector bool short *); 18624void vec_stl (vector bool short, int, unsigned short *); 18625void vec_stl (vector bool short, int, short *); 18626void vec_stl (vector pixel, int, vector pixel *); 18627void vec_stl (vector signed char, int, vector signed char *); 18628void vec_stl (vector signed char, int, signed char *); 18629void vec_stl (vector unsigned char, int, vector unsigned char *); 18630void vec_stl (vector unsigned char, int, unsigned char *); 18631void vec_stl (vector bool char, int, vector bool char *); 18632void vec_stl (vector bool char, int, unsigned char *); 18633void vec_stl (vector bool char, int, signed char *); 18634 18635void vec_stvebx (vector signed char, int, signed char *); 18636void vec_stvebx (vector unsigned char, int, unsigned char *); 18637void vec_stvebx (vector bool char, int, signed char *); 18638void vec_stvebx (vector bool char, int, unsigned char *); 18639 18640void vec_stvehx (vector signed short, int, short *); 18641void vec_stvehx (vector unsigned short, int, unsigned short *); 18642void vec_stvehx (vector bool short, int, short *); 18643void vec_stvehx (vector bool short, int, unsigned short *); 18644 18645void vec_stvewx (vector float, int, float *); 18646void vec_stvewx (vector signed int, int, int *); 18647void vec_stvewx (vector unsigned int, int, unsigned int *); 18648void vec_stvewx (vector bool int, int, int *); 18649void vec_stvewx (vector bool int, int, unsigned int *); 18650 18651vector signed char vec_sub (vector bool char, vector signed char); 18652vector signed char vec_sub (vector signed char, vector bool char); 18653vector signed char vec_sub (vector signed char, vector signed char); 18654vector unsigned char vec_sub (vector bool char, vector unsigned char); 18655vector unsigned char vec_sub (vector unsigned char, vector bool char); 18656vector unsigned char vec_sub (vector unsigned char, vector unsigned char); 18657vector signed short vec_sub (vector bool short, vector signed short); 18658vector signed short vec_sub (vector signed short, vector bool short); 18659vector signed short vec_sub (vector signed short, vector signed short); 18660vector unsigned short vec_sub (vector bool short, vector unsigned short); 18661vector unsigned short vec_sub (vector unsigned short, vector bool short); 18662vector unsigned short vec_sub (vector unsigned short, vector unsigned short); 18663vector signed int vec_sub (vector bool int, vector signed int); 18664vector signed int vec_sub (vector signed int, vector bool int); 18665vector signed int vec_sub (vector signed int, vector signed int); 18666vector unsigned int vec_sub (vector bool int, vector unsigned int); 18667vector unsigned int vec_sub (vector unsigned int, vector bool int); 18668vector unsigned int vec_sub (vector unsigned int, vector unsigned int); 18669vector float vec_sub (vector float, vector float); 18670 18671vector signed int vec_subc (vector signed int, vector signed int); 18672vector unsigned int vec_subc (vector unsigned int, vector unsigned int); 18673 18674vector signed int vec_sube (vector signed int, vector signed int, 18675 vector signed int); 18676vector unsigned int vec_sube (vector unsigned int, vector unsigned int, 18677 vector unsigned int); 18678 18679vector signed int vec_subec (vector signed int, vector signed int, 18680 vector signed int); 18681vector unsigned int vec_subec (vector unsigned int, vector unsigned int, 18682 vector unsigned int); 18683 18684vector unsigned char vec_subs (vector bool char, vector unsigned char); 18685vector unsigned char vec_subs (vector unsigned char, vector bool char); 18686vector unsigned char vec_subs (vector unsigned char, vector unsigned char); 18687vector signed char vec_subs (vector bool char, vector signed char); 18688vector signed char vec_subs (vector signed char, vector bool char); 18689vector signed char vec_subs (vector signed char, vector signed char); 18690vector unsigned short vec_subs (vector bool short, vector unsigned short); 18691vector unsigned short vec_subs (vector unsigned short, vector bool short); 18692vector unsigned short vec_subs (vector unsigned short, vector unsigned short); 18693vector signed short vec_subs (vector bool short, vector signed short); 18694vector signed short vec_subs (vector signed short, vector bool short); 18695vector signed short vec_subs (vector signed short, vector signed short); 18696vector unsigned int vec_subs (vector bool int, vector unsigned int); 18697vector unsigned int vec_subs (vector unsigned int, vector bool int); 18698vector unsigned int vec_subs (vector unsigned int, vector unsigned int); 18699vector signed int vec_subs (vector bool int, vector signed int); 18700vector signed int vec_subs (vector signed int, vector bool int); 18701vector signed int vec_subs (vector signed int, vector signed int); 18702 18703vector signed int vec_sum2s (vector signed int, vector signed int); 18704 18705vector unsigned int vec_sum4s (vector unsigned char, vector unsigned int); 18706vector signed int vec_sum4s (vector signed char, vector signed int); 18707vector signed int vec_sum4s (vector signed short, vector signed int); 18708 18709vector signed int vec_sums (vector signed int, vector signed int); 18710 18711vector float vec_trunc (vector float); 18712 18713vector signed short vec_unpackh (vector signed char); 18714vector bool short vec_unpackh (vector bool char); 18715vector signed int vec_unpackh (vector signed short); 18716vector bool int vec_unpackh (vector bool short); 18717vector unsigned int vec_unpackh (vector pixel); 18718 18719vector signed short vec_unpackl (vector signed char); 18720vector bool short vec_unpackl (vector bool char); 18721vector unsigned int vec_unpackl (vector pixel); 18722vector signed int vec_unpackl (vector signed short); 18723vector bool int vec_unpackl (vector bool short); 18724 18725vector float vec_vaddfp (vector float, vector float); 18726 18727vector signed char vec_vaddsbs (vector bool char, vector signed char); 18728vector signed char vec_vaddsbs (vector signed char, vector bool char); 18729vector signed char vec_vaddsbs (vector signed char, vector signed char); 18730 18731vector signed short vec_vaddshs (vector bool short, vector signed short); 18732vector signed short vec_vaddshs (vector signed short, vector bool short); 18733vector signed short vec_vaddshs (vector signed short, vector signed short); 18734 18735vector signed int vec_vaddsws (vector bool int, vector signed int); 18736vector signed int vec_vaddsws (vector signed int, vector bool int); 18737vector signed int vec_vaddsws (vector signed int, vector signed int); 18738 18739vector signed char vec_vaddubm (vector bool char, vector signed char); 18740vector signed char vec_vaddubm (vector signed char, vector bool char); 18741vector signed char vec_vaddubm (vector signed char, vector signed char); 18742vector unsigned char vec_vaddubm (vector bool char, vector unsigned char); 18743vector unsigned char vec_vaddubm (vector unsigned char, vector bool char); 18744vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char); 18745 18746vector unsigned char vec_vaddubs (vector bool char, vector unsigned char); 18747vector unsigned char vec_vaddubs (vector unsigned char, vector bool char); 18748vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char); 18749 18750vector signed short vec_vadduhm (vector bool short, vector signed short); 18751vector signed short vec_vadduhm (vector signed short, vector bool short); 18752vector signed short vec_vadduhm (vector signed short, vector signed short); 18753vector unsigned short vec_vadduhm (vector bool short, vector unsigned short); 18754vector unsigned short vec_vadduhm (vector unsigned short, vector bool short); 18755vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short); 18756 18757vector unsigned short vec_vadduhs (vector bool short, vector unsigned short); 18758vector unsigned short vec_vadduhs (vector unsigned short, vector bool short); 18759vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short); 18760 18761vector signed int vec_vadduwm (vector bool int, vector signed int); 18762vector signed int vec_vadduwm (vector signed int, vector bool int); 18763vector signed int vec_vadduwm (vector signed int, vector signed int); 18764vector unsigned int vec_vadduwm (vector bool int, vector unsigned int); 18765vector unsigned int vec_vadduwm (vector unsigned int, vector bool int); 18766vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int); 18767 18768vector unsigned int vec_vadduws (vector bool int, vector unsigned int); 18769vector unsigned int vec_vadduws (vector unsigned int, vector bool int); 18770vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int); 18771 18772vector signed char vec_vavgsb (vector signed char, vector signed char); 18773 18774vector signed short vec_vavgsh (vector signed short, vector signed short); 18775 18776vector signed int vec_vavgsw (vector signed int, vector signed int); 18777 18778vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char); 18779 18780vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short); 18781 18782vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int); 18783 18784vector float vec_vcfsx (vector signed int, const int); 18785 18786vector float vec_vcfux (vector unsigned int, const int); 18787 18788vector bool int vec_vcmpeqfp (vector float, vector float); 18789 18790vector bool char vec_vcmpequb (vector signed char, vector signed char); 18791vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char); 18792 18793vector bool short vec_vcmpequh (vector signed short, vector signed short); 18794vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short); 18795 18796vector bool int vec_vcmpequw (vector signed int, vector signed int); 18797vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); 18798 18799vector bool int vec_vcmpgtfp (vector float, vector float); 18800 18801vector bool char vec_vcmpgtsb (vector signed char, vector signed char); 18802 18803vector bool short vec_vcmpgtsh (vector signed short, vector signed short); 18804 18805vector bool int vec_vcmpgtsw (vector signed int, vector signed int); 18806 18807vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char); 18808 18809vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short); 18810 18811vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); 18812 18813vector float vec_vmaxfp (vector float, vector float); 18814 18815vector signed char vec_vmaxsb (vector bool char, vector signed char); 18816vector signed char vec_vmaxsb (vector signed char, vector bool char); 18817vector signed char vec_vmaxsb (vector signed char, vector signed char); 18818 18819vector signed short vec_vmaxsh (vector bool short, vector signed short); 18820vector signed short vec_vmaxsh (vector signed short, vector bool short); 18821vector signed short vec_vmaxsh (vector signed short, vector signed short); 18822 18823vector signed int vec_vmaxsw (vector bool int, vector signed int); 18824vector signed int vec_vmaxsw (vector signed int, vector bool int); 18825vector signed int vec_vmaxsw (vector signed int, vector signed int); 18826 18827vector unsigned char vec_vmaxub (vector bool char, vector unsigned char); 18828vector unsigned char vec_vmaxub (vector unsigned char, vector bool char); 18829vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char); 18830 18831vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short); 18832vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short); 18833vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short); 18834 18835vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); 18836vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); 18837vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int); 18838 18839vector float vec_vminfp (vector float, vector float); 18840 18841vector signed char vec_vminsb (vector bool char, vector signed char); 18842vector signed char vec_vminsb (vector signed char, vector bool char); 18843vector signed char vec_vminsb (vector signed char, vector signed char); 18844 18845vector signed short vec_vminsh (vector bool short, vector signed short); 18846vector signed short vec_vminsh (vector signed short, vector bool short); 18847vector signed short vec_vminsh (vector signed short, vector signed short); 18848 18849vector signed int vec_vminsw (vector bool int, vector signed int); 18850vector signed int vec_vminsw (vector signed int, vector bool int); 18851vector signed int vec_vminsw (vector signed int, vector signed int); 18852 18853vector unsigned char vec_vminub (vector bool char, vector unsigned char); 18854vector unsigned char vec_vminub (vector unsigned char, vector bool char); 18855vector unsigned char vec_vminub (vector unsigned char, vector unsigned char); 18856 18857vector unsigned short vec_vminuh (vector bool short, vector unsigned short); 18858vector unsigned short vec_vminuh (vector unsigned short, vector bool short); 18859vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short); 18860 18861vector unsigned int vec_vminuw (vector bool int, vector unsigned int); 18862vector unsigned int vec_vminuw (vector unsigned int, vector bool int); 18863vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int); 18864 18865vector bool char vec_vmrghb (vector bool char, vector bool char); 18866vector signed char vec_vmrghb (vector signed char, vector signed char); 18867vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char); 18868 18869vector bool short vec_vmrghh (vector bool short, vector bool short); 18870vector signed short vec_vmrghh (vector signed short, vector signed short); 18871vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short); 18872vector pixel vec_vmrghh (vector pixel, vector pixel); 18873 18874vector float vec_vmrghw (vector float, vector float); 18875vector bool int vec_vmrghw (vector bool int, vector bool int); 18876vector signed int vec_vmrghw (vector signed int, vector signed int); 18877vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int); 18878 18879vector bool char vec_vmrglb (vector bool char, vector bool char); 18880vector signed char vec_vmrglb (vector signed char, vector signed char); 18881vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char); 18882 18883vector bool short vec_vmrglh (vector bool short, vector bool short); 18884vector signed short vec_vmrglh (vector signed short, vector signed short); 18885vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short); 18886vector pixel vec_vmrglh (vector pixel, vector pixel); 18887 18888vector float vec_vmrglw (vector float, vector float); 18889vector signed int vec_vmrglw (vector signed int, vector signed int); 18890vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int); 18891vector bool int vec_vmrglw (vector bool int, vector bool int); 18892 18893vector signed int vec_vmsummbm (vector signed char, vector unsigned char, 18894 vector signed int); 18895 18896vector signed int vec_vmsumshm (vector signed short, vector signed short, 18897 vector signed int); 18898 18899vector signed int vec_vmsumshs (vector signed short, vector signed short, 18900 vector signed int); 18901 18902vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char, 18903 vector unsigned int); 18904 18905vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short, 18906 vector unsigned int); 18907 18908vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short, 18909 vector unsigned int); 18910 18911vector signed short vec_vmulesb (vector signed char, vector signed char); 18912 18913vector signed int vec_vmulesh (vector signed short, vector signed short); 18914 18915vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char); 18916 18917vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short); 18918 18919vector signed short vec_vmulosb (vector signed char, vector signed char); 18920 18921vector signed int vec_vmulosh (vector signed short, vector signed short); 18922 18923vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char); 18924 18925vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short); 18926 18927vector signed char vec_vpkshss (vector signed short, vector signed short); 18928 18929vector unsigned char vec_vpkshus (vector signed short, vector signed short); 18930 18931vector signed short vec_vpkswss (vector signed int, vector signed int); 18932 18933vector unsigned short vec_vpkswus (vector signed int, vector signed int); 18934 18935vector bool char vec_vpkuhum (vector bool short, vector bool short); 18936vector signed char vec_vpkuhum (vector signed short, vector signed short); 18937vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short); 18938 18939vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short); 18940 18941vector bool short vec_vpkuwum (vector bool int, vector bool int); 18942vector signed short vec_vpkuwum (vector signed int, vector signed int); 18943vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int); 18944 18945vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int); 18946 18947vector signed char vec_vrlb (vector signed char, vector unsigned char); 18948vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char); 18949 18950vector signed short vec_vrlh (vector signed short, vector unsigned short); 18951vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short); 18952 18953vector signed int vec_vrlw (vector signed int, vector unsigned int); 18954vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); 18955 18956vector signed char vec_vslb (vector signed char, vector unsigned char); 18957vector unsigned char vec_vslb (vector unsigned char, vector unsigned char); 18958 18959vector signed short vec_vslh (vector signed short, vector unsigned short); 18960vector unsigned short vec_vslh (vector unsigned short, vector unsigned short); 18961 18962vector signed int vec_vslw (vector signed int, vector unsigned int); 18963vector unsigned int vec_vslw (vector unsigned int, vector unsigned int); 18964 18965vector signed char vec_vspltb (vector signed char, const int); 18966vector unsigned char vec_vspltb (vector unsigned char, const int); 18967vector bool char vec_vspltb (vector bool char, const int); 18968 18969vector bool short vec_vsplth (vector bool short, const int); 18970vector signed short vec_vsplth (vector signed short, const int); 18971vector unsigned short vec_vsplth (vector unsigned short, const int); 18972vector pixel vec_vsplth (vector pixel, const int); 18973 18974vector float vec_vspltw (vector float, const int); 18975vector signed int vec_vspltw (vector signed int, const int); 18976vector unsigned int vec_vspltw (vector unsigned int, const int); 18977vector bool int vec_vspltw (vector bool int, const int); 18978 18979vector signed char vec_vsrab (vector signed char, vector unsigned char); 18980vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char); 18981 18982vector signed short vec_vsrah (vector signed short, vector unsigned short); 18983vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short); 18984 18985vector signed int vec_vsraw (vector signed int, vector unsigned int); 18986vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int); 18987 18988vector signed char vec_vsrb (vector signed char, vector unsigned char); 18989vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char); 18990 18991vector signed short vec_vsrh (vector signed short, vector unsigned short); 18992vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short); 18993 18994vector signed int vec_vsrw (vector signed int, vector unsigned int); 18995vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); 18996 18997vector float vec_vsubfp (vector float, vector float); 18998 18999vector signed char vec_vsubsbs (vector bool char, vector signed char); 19000vector signed char vec_vsubsbs (vector signed char, vector bool char); 19001vector signed char vec_vsubsbs (vector signed char, vector signed char); 19002 19003vector signed short vec_vsubshs (vector bool short, vector signed short); 19004vector signed short vec_vsubshs (vector signed short, vector bool short); 19005vector signed short vec_vsubshs (vector signed short, vector signed short); 19006 19007vector signed int vec_vsubsws (vector bool int, vector signed int); 19008vector signed int vec_vsubsws (vector signed int, vector bool int); 19009vector signed int vec_vsubsws (vector signed int, vector signed int); 19010 19011vector signed char vec_vsububm (vector bool char, vector signed char); 19012vector signed char vec_vsububm (vector signed char, vector bool char); 19013vector signed char vec_vsububm (vector signed char, vector signed char); 19014vector unsigned char vec_vsububm (vector bool char, vector unsigned char); 19015vector unsigned char vec_vsububm (vector unsigned char, vector bool char); 19016vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char); 19017 19018vector unsigned char vec_vsububs (vector bool char, vector unsigned char); 19019vector unsigned char vec_vsububs (vector unsigned char, vector bool char); 19020vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char); 19021 19022vector signed short vec_vsubuhm (vector bool short, vector signed short); 19023vector signed short vec_vsubuhm (vector signed short, vector bool short); 19024vector signed short vec_vsubuhm (vector signed short, vector signed short); 19025vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short); 19026vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short); 19027vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short); 19028 19029vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short); 19030vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short); 19031vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short); 19032 19033vector signed int vec_vsubuwm (vector bool int, vector signed int); 19034vector signed int vec_vsubuwm (vector signed int, vector bool int); 19035vector signed int vec_vsubuwm (vector signed int, vector signed int); 19036vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); 19037vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); 19038vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int); 19039 19040vector unsigned int vec_vsubuws (vector bool int, vector unsigned int); 19041vector unsigned int vec_vsubuws (vector unsigned int, vector bool int); 19042vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int); 19043 19044vector signed int vec_vsum4sbs (vector signed char, vector signed int); 19045 19046vector signed int vec_vsum4shs (vector signed short, vector signed int); 19047 19048vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int); 19049 19050vector unsigned int vec_vupkhpx (vector pixel); 19051 19052vector bool short vec_vupkhsb (vector bool char); 19053vector signed short vec_vupkhsb (vector signed char); 19054 19055vector bool int vec_vupkhsh (vector bool short); 19056vector signed int vec_vupkhsh (vector signed short); 19057 19058vector unsigned int vec_vupklpx (vector pixel); 19059 19060vector bool short vec_vupklsb (vector bool char); 19061vector signed short vec_vupklsb (vector signed char); 19062 19063vector bool int vec_vupklsh (vector bool short); 19064vector signed int vec_vupklsh (vector signed short); 19065 19066vector float vec_xor (vector float, vector float); 19067vector float vec_xor (vector float, vector bool int); 19068vector float vec_xor (vector bool int, vector float); 19069vector bool int vec_xor (vector bool int, vector bool int); 19070vector signed int vec_xor (vector bool int, vector signed int); 19071vector signed int vec_xor (vector signed int, vector bool int); 19072vector signed int vec_xor (vector signed int, vector signed int); 19073vector unsigned int vec_xor (vector bool int, vector unsigned int); 19074vector unsigned int vec_xor (vector unsigned int, vector bool int); 19075vector unsigned int vec_xor (vector unsigned int, vector unsigned int); 19076vector bool short vec_xor (vector bool short, vector bool short); 19077vector signed short vec_xor (vector bool short, vector signed short); 19078vector signed short vec_xor (vector signed short, vector bool short); 19079vector signed short vec_xor (vector signed short, vector signed short); 19080vector unsigned short vec_xor (vector bool short, vector unsigned short); 19081vector unsigned short vec_xor (vector unsigned short, vector bool short); 19082vector unsigned short vec_xor (vector unsigned short, vector unsigned short); 19083vector signed char vec_xor (vector bool char, vector signed char); 19084vector bool char vec_xor (vector bool char, vector bool char); 19085vector signed char vec_xor (vector signed char, vector bool char); 19086vector signed char vec_xor (vector signed char, vector signed char); 19087vector unsigned char vec_xor (vector bool char, vector unsigned char); 19088vector unsigned char vec_xor (vector unsigned char, vector bool char); 19089vector unsigned char vec_xor (vector unsigned char, vector unsigned char); 19090@end smallexample 19091 19092@node PowerPC AltiVec Built-in Functions Available on ISA 2.06 19093@subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06 19094 19095The AltiVec built-in functions described in this section are 19096available on the PowerPC family of processors starting with ISA 2.06 19097or later. These are normally enabled by adding @option{-mvsx} to the 19098command line. 19099 19100When @option{-mvsx} is used, the following additional vector types are 19101implemented. 19102 19103@smallexample 19104vector unsigned __int128 19105vector signed __int128 19106vector unsigned long long int 19107vector signed long long int 19108vector double 19109@end smallexample 19110 19111The long long types are only implemented for 64-bit code generation. 19112 19113@smallexample 19114 19115vector bool long long vec_and (vector bool long long int, vector bool long long); 19116 19117vector double vec_ctf (vector unsigned long, const int); 19118vector double vec_ctf (vector signed long, const int); 19119 19120vector signed long vec_cts (vector double, const int); 19121 19122vector unsigned long vec_ctu (vector double, const int); 19123 19124void vec_dst (const unsigned long *, int, const int); 19125void vec_dst (const long *, int, const int); 19126 19127void vec_dststt (const unsigned long *, int, const int); 19128void vec_dststt (const long *, int, const int); 19129 19130void vec_dstt (const unsigned long *, int, const int); 19131void vec_dstt (const long *, int, const int); 19132 19133vector unsigned char vec_lvsl (int, const unsigned long *); 19134vector unsigned char vec_lvsl (int, const long *); 19135 19136vector unsigned char vec_lvsr (int, const unsigned long *); 19137vector unsigned char vec_lvsr (int, const long *); 19138 19139vector double vec_mul (vector double, vector double); 19140vector long vec_mul (vector long, vector long); 19141vector unsigned long vec_mul (vector unsigned long, vector unsigned long); 19142 19143vector unsigned long long vec_mule (vector unsigned int, vector unsigned int); 19144vector signed long long vec_mule (vector signed int, vector signed int); 19145 19146vector unsigned long long vec_mulo (vector unsigned int, vector unsigned int); 19147vector signed long long vec_mulo (vector signed int, vector signed int); 19148 19149vector double vec_nabs (vector double); 19150 19151vector bool long long vec_reve (vector bool long long); 19152vector signed long long vec_reve (vector signed long long); 19153vector unsigned long long vec_reve (vector unsigned long long); 19154vector double vec_sld (vector double, vector double, const int); 19155 19156vector bool long long int vec_sld (vector bool long long int, 19157 vector bool long long int, const int); 19158vector long long int vec_sld (vector long long int, vector long long int, const int); 19159vector unsigned long long int vec_sld (vector unsigned long long int, 19160 vector unsigned long long int, const int); 19161 19162vector long long int vec_sll (vector long long int, vector unsigned char); 19163vector unsigned long long int vec_sll (vector unsigned long long int, 19164 vector unsigned char); 19165 19166vector signed long long vec_slo (vector signed long long, vector signed char); 19167vector signed long long vec_slo (vector signed long long, vector unsigned char); 19168vector unsigned long long vec_slo (vector unsigned long long, vector signed char); 19169vector unsigned long long vec_slo (vector unsigned long long, vector unsigned char); 19170 19171vector signed long vec_splat (vector signed long, const int); 19172vector unsigned long vec_splat (vector unsigned long, const int); 19173 19174vector long long int vec_srl (vector long long int, vector unsigned char); 19175vector unsigned long long int vec_srl (vector unsigned long long int, 19176 vector unsigned char); 19177 19178vector long long int vec_sro (vector long long int, vector char); 19179vector long long int vec_sro (vector long long int, vector unsigned char); 19180vector unsigned long long int vec_sro (vector unsigned long long int, vector char); 19181vector unsigned long long int vec_sro (vector unsigned long long int, 19182 vector unsigned char); 19183 19184vector signed __int128 vec_subc (vector signed __int128, vector signed __int128); 19185vector unsigned __int128 vec_subc (vector unsigned __int128, vector unsigned __int128); 19186 19187vector signed __int128 vec_sube (vector signed __int128, vector signed __int128, 19188 vector signed __int128); 19189vector unsigned __int128 vec_sube (vector unsigned __int128, vector unsigned __int128, 19190 vector unsigned __int128); 19191 19192vector signed __int128 vec_subec (vector signed __int128, vector signed __int128, 19193 vector signed __int128); 19194vector unsigned __int128 vec_subec (vector unsigned __int128, vector unsigned __int128, 19195 vector unsigned __int128); 19196 19197vector double vec_unpackh (vector float); 19198 19199vector double vec_unpackl (vector float); 19200 19201vector double vec_doublee (vector float); 19202vector double vec_doublee (vector signed int); 19203vector double vec_doublee (vector unsigned int); 19204 19205vector double vec_doubleo (vector float); 19206vector double vec_doubleo (vector signed int); 19207vector double vec_doubleo (vector unsigned int); 19208 19209vector double vec_doubleh (vector float); 19210vector double vec_doubleh (vector signed int); 19211vector double vec_doubleh (vector unsigned int); 19212 19213vector double vec_doublel (vector float); 19214vector double vec_doublel (vector signed int); 19215vector double vec_doublel (vector unsigned int); 19216 19217vector float vec_float (vector signed int); 19218vector float vec_float (vector unsigned int); 19219 19220vector float vec_float2 (vector signed long long, vector signed long long); 19221vector float vec_float2 (vector unsigned long long, vector signed long long); 19222 19223vector float vec_floate (vector double); 19224vector float vec_floate (vector signed long long); 19225vector float vec_floate (vector unsigned long long); 19226 19227vector float vec_floato (vector double); 19228vector float vec_floato (vector signed long long); 19229vector float vec_floato (vector unsigned long long); 19230 19231vector signed long long vec_signed (vector double); 19232vector signed int vec_signed (vector float); 19233 19234vector signed int vec_signede (vector double); 19235 19236vector signed int vec_signedo (vector double); 19237 19238vector signed char vec_sldw (vector signed char, vector signed char, const int); 19239vector unsigned char vec_sldw (vector unsigned char, vector unsigned char, const int); 19240vector signed short vec_sldw (vector signed short, vector signed short, const int); 19241vector unsigned short vec_sldw (vector unsigned short, 19242 vector unsigned short, const int); 19243vector signed int vec_sldw (vector signed int, vector signed int, const int); 19244vector unsigned int vec_sldw (vector unsigned int, vector unsigned int, const int); 19245vector signed long long vec_sldw (vector signed long long, 19246 vector signed long long, const int); 19247vector unsigned long long vec_sldw (vector unsigned long long, 19248 vector unsigned long long, const int); 19249 19250vector signed long long vec_unsigned (vector double); 19251vector signed int vec_unsigned (vector float); 19252 19253vector signed int vec_unsignede (vector double); 19254 19255vector signed int vec_unsignedo (vector double); 19256 19257vector double vec_abs (vector double); 19258vector double vec_add (vector double, vector double); 19259vector double vec_and (vector double, vector double); 19260vector double vec_and (vector double, vector bool long); 19261vector double vec_and (vector bool long, vector double); 19262vector long vec_and (vector long, vector long); 19263vector long vec_and (vector long, vector bool long); 19264vector long vec_and (vector bool long, vector long); 19265vector unsigned long vec_and (vector unsigned long, vector unsigned long); 19266vector unsigned long vec_and (vector unsigned long, vector bool long); 19267vector unsigned long vec_and (vector bool long, vector unsigned long); 19268vector double vec_andc (vector double, vector double); 19269vector double vec_andc (vector double, vector bool long); 19270vector double vec_andc (vector bool long, vector double); 19271vector long vec_andc (vector long, vector long); 19272vector long vec_andc (vector long, vector bool long); 19273vector long vec_andc (vector bool long, vector long); 19274vector unsigned long vec_andc (vector unsigned long, vector unsigned long); 19275vector unsigned long vec_andc (vector unsigned long, vector bool long); 19276vector unsigned long vec_andc (vector bool long, vector unsigned long); 19277vector double vec_ceil (vector double); 19278vector bool long vec_cmpeq (vector double, vector double); 19279vector bool long vec_cmpge (vector double, vector double); 19280vector bool long vec_cmpgt (vector double, vector double); 19281vector bool long vec_cmple (vector double, vector double); 19282vector bool long vec_cmplt (vector double, vector double); 19283vector double vec_cpsgn (vector double, vector double); 19284vector float vec_div (vector float, vector float); 19285vector double vec_div (vector double, vector double); 19286vector long vec_div (vector long, vector long); 19287vector unsigned long vec_div (vector unsigned long, vector unsigned long); 19288vector double vec_floor (vector double); 19289vector signed long long vec_ld (int, const vector signed long long *); 19290vector signed long long vec_ld (int, const signed long long *); 19291vector unsigned long long vec_ld (int, const vector unsigned long long *); 19292vector unsigned long long vec_ld (int, const unsigned long long *); 19293vector __int128 vec_ld (int, const vector __int128 *); 19294vector unsigned __int128 vec_ld (int, const vector unsigned __int128 *); 19295vector __int128 vec_ld (int, const __int128 *); 19296vector unsigned __int128 vec_ld (int, const unsigned __int128 *); 19297vector double vec_ld (int, const vector double *); 19298vector double vec_ld (int, const double *); 19299vector double vec_ldl (int, const vector double *); 19300vector double vec_ldl (int, const double *); 19301vector unsigned char vec_lvsl (int, const double *); 19302vector unsigned char vec_lvsr (int, const double *); 19303vector double vec_madd (vector double, vector double, vector double); 19304vector double vec_max (vector double, vector double); 19305vector signed long vec_mergeh (vector signed long, vector signed long); 19306vector signed long vec_mergeh (vector signed long, vector bool long); 19307vector signed long vec_mergeh (vector bool long, vector signed long); 19308vector unsigned long vec_mergeh (vector unsigned long, vector unsigned long); 19309vector unsigned long vec_mergeh (vector unsigned long, vector bool long); 19310vector unsigned long vec_mergeh (vector bool long, vector unsigned long); 19311vector signed long vec_mergel (vector signed long, vector signed long); 19312vector signed long vec_mergel (vector signed long, vector bool long); 19313vector signed long vec_mergel (vector bool long, vector signed long); 19314vector unsigned long vec_mergel (vector unsigned long, vector unsigned long); 19315vector unsigned long vec_mergel (vector unsigned long, vector bool long); 19316vector unsigned long vec_mergel (vector bool long, vector unsigned long); 19317vector double vec_min (vector double, vector double); 19318vector float vec_msub (vector float, vector float, vector float); 19319vector double vec_msub (vector double, vector double, vector double); 19320vector float vec_nearbyint (vector float); 19321vector double vec_nearbyint (vector double); 19322vector float vec_nmadd (vector float, vector float, vector float); 19323vector double vec_nmadd (vector double, vector double, vector double); 19324vector double vec_nmsub (vector double, vector double, vector double); 19325vector double vec_nor (vector double, vector double); 19326vector long vec_nor (vector long, vector long); 19327vector long vec_nor (vector long, vector bool long); 19328vector long vec_nor (vector bool long, vector long); 19329vector unsigned long vec_nor (vector unsigned long, vector unsigned long); 19330vector unsigned long vec_nor (vector unsigned long, vector bool long); 19331vector unsigned long vec_nor (vector bool long, vector unsigned long); 19332vector double vec_or (vector double, vector double); 19333vector double vec_or (vector double, vector bool long); 19334vector double vec_or (vector bool long, vector double); 19335vector long vec_or (vector long, vector long); 19336vector long vec_or (vector long, vector bool long); 19337vector long vec_or (vector bool long, vector long); 19338vector unsigned long vec_or (vector unsigned long, vector unsigned long); 19339vector unsigned long vec_or (vector unsigned long, vector bool long); 19340vector unsigned long vec_or (vector bool long, vector unsigned long); 19341vector double vec_perm (vector double, vector double, vector unsigned char); 19342vector long vec_perm (vector long, vector long, vector unsigned char); 19343vector unsigned long vec_perm (vector unsigned long, vector unsigned long, 19344 vector unsigned char); 19345vector bool char vec_permxor (vector bool char, vector bool char, 19346 vector bool char); 19347vector unsigned char vec_permxor (vector signed char, vector signed char, 19348 vector signed char); 19349vector unsigned char vec_permxor (vector unsigned char, vector unsigned char, 19350 vector unsigned char); 19351vector double vec_rint (vector double); 19352vector double vec_recip (vector double, vector double); 19353vector double vec_rsqrt (vector double); 19354vector double vec_rsqrte (vector double); 19355vector double vec_sel (vector double, vector double, vector bool long); 19356vector double vec_sel (vector double, vector double, vector unsigned long); 19357vector long vec_sel (vector long, vector long, vector long); 19358vector long vec_sel (vector long, vector long, vector unsigned long); 19359vector long vec_sel (vector long, vector long, vector bool long); 19360vector unsigned long vec_sel (vector unsigned long, vector unsigned long, 19361 vector long); 19362vector unsigned long vec_sel (vector unsigned long, vector unsigned long, 19363 vector unsigned long); 19364vector unsigned long vec_sel (vector unsigned long, vector unsigned long, 19365 vector bool long); 19366vector double vec_splats (double); 19367vector signed long vec_splats (signed long); 19368vector unsigned long vec_splats (unsigned long); 19369vector float vec_sqrt (vector float); 19370vector double vec_sqrt (vector double); 19371void vec_st (vector signed long long, int, vector signed long long *); 19372void vec_st (vector signed long long, int, signed long long *); 19373void vec_st (vector unsigned long long, int, vector unsigned long long *); 19374void vec_st (vector unsigned long long, int, unsigned long long *); 19375void vec_st (vector bool long long, int, vector bool long long *); 19376void vec_st (vector bool long long, int, signed long long *); 19377void vec_st (vector bool long long, int, unsigned long long *); 19378void vec_st (vector double, int, vector double *); 19379void vec_st (vector double, int, double *); 19380vector double vec_sub (vector double, vector double); 19381vector double vec_trunc (vector double); 19382vector double vec_xl (int, vector double *); 19383vector double vec_xl (int, double *); 19384vector long long vec_xl (int, vector long long *); 19385vector long long vec_xl (int, long long *); 19386vector unsigned long long vec_xl (int, vector unsigned long long *); 19387vector unsigned long long vec_xl (int, unsigned long long *); 19388vector float vec_xl (int, vector float *); 19389vector float vec_xl (int, float *); 19390vector int vec_xl (int, vector int *); 19391vector int vec_xl (int, int *); 19392vector unsigned int vec_xl (int, vector unsigned int *); 19393vector unsigned int vec_xl (int, unsigned int *); 19394vector double vec_xor (vector double, vector double); 19395vector double vec_xor (vector double, vector bool long); 19396vector double vec_xor (vector bool long, vector double); 19397vector long vec_xor (vector long, vector long); 19398vector long vec_xor (vector long, vector bool long); 19399vector long vec_xor (vector bool long, vector long); 19400vector unsigned long vec_xor (vector unsigned long, vector unsigned long); 19401vector unsigned long vec_xor (vector unsigned long, vector bool long); 19402vector unsigned long vec_xor (vector bool long, vector unsigned long); 19403void vec_xst (vector double, int, vector double *); 19404void vec_xst (vector double, int, double *); 19405void vec_xst (vector long long, int, vector long long *); 19406void vec_xst (vector long long, int, long long *); 19407void vec_xst (vector unsigned long long, int, vector unsigned long long *); 19408void vec_xst (vector unsigned long long, int, unsigned long long *); 19409void vec_xst (vector float, int, vector float *); 19410void vec_xst (vector float, int, float *); 19411void vec_xst (vector int, int, vector int *); 19412void vec_xst (vector int, int, int *); 19413void vec_xst (vector unsigned int, int, vector unsigned int *); 19414void vec_xst (vector unsigned int, int, unsigned int *); 19415int vec_all_eq (vector double, vector double); 19416int vec_all_ge (vector double, vector double); 19417int vec_all_gt (vector double, vector double); 19418int vec_all_le (vector double, vector double); 19419int vec_all_lt (vector double, vector double); 19420int vec_all_nan (vector double); 19421int vec_all_ne (vector double, vector double); 19422int vec_all_nge (vector double, vector double); 19423int vec_all_ngt (vector double, vector double); 19424int vec_all_nle (vector double, vector double); 19425int vec_all_nlt (vector double, vector double); 19426int vec_all_numeric (vector double); 19427int vec_any_eq (vector double, vector double); 19428int vec_any_ge (vector double, vector double); 19429int vec_any_gt (vector double, vector double); 19430int vec_any_le (vector double, vector double); 19431int vec_any_lt (vector double, vector double); 19432int vec_any_nan (vector double); 19433int vec_any_ne (vector double, vector double); 19434int vec_any_nge (vector double, vector double); 19435int vec_any_ngt (vector double, vector double); 19436int vec_any_nle (vector double, vector double); 19437int vec_any_nlt (vector double, vector double); 19438int vec_any_numeric (vector double); 19439 19440vector double vec_vsx_ld (int, const vector double *); 19441vector double vec_vsx_ld (int, const double *); 19442vector float vec_vsx_ld (int, const vector float *); 19443vector float vec_vsx_ld (int, const float *); 19444vector bool int vec_vsx_ld (int, const vector bool int *); 19445vector signed int vec_vsx_ld (int, const vector signed int *); 19446vector signed int vec_vsx_ld (int, const int *); 19447vector signed int vec_vsx_ld (int, const long *); 19448vector unsigned int vec_vsx_ld (int, const vector unsigned int *); 19449vector unsigned int vec_vsx_ld (int, const unsigned int *); 19450vector unsigned int vec_vsx_ld (int, const unsigned long *); 19451vector bool short vec_vsx_ld (int, const vector bool short *); 19452vector pixel vec_vsx_ld (int, const vector pixel *); 19453vector signed short vec_vsx_ld (int, const vector signed short *); 19454vector signed short vec_vsx_ld (int, const short *); 19455vector unsigned short vec_vsx_ld (int, const vector unsigned short *); 19456vector unsigned short vec_vsx_ld (int, const unsigned short *); 19457vector bool char vec_vsx_ld (int, const vector bool char *); 19458vector signed char vec_vsx_ld (int, const vector signed char *); 19459vector signed char vec_vsx_ld (int, const signed char *); 19460vector unsigned char vec_vsx_ld (int, const vector unsigned char *); 19461vector unsigned char vec_vsx_ld (int, const unsigned char *); 19462 19463void vec_vsx_st (vector double, int, vector double *); 19464void vec_vsx_st (vector double, int, double *); 19465void vec_vsx_st (vector float, int, vector float *); 19466void vec_vsx_st (vector float, int, float *); 19467void vec_vsx_st (vector signed int, int, vector signed int *); 19468void vec_vsx_st (vector signed int, int, int *); 19469void vec_vsx_st (vector unsigned int, int, vector unsigned int *); 19470void vec_vsx_st (vector unsigned int, int, unsigned int *); 19471void vec_vsx_st (vector bool int, int, vector bool int *); 19472void vec_vsx_st (vector bool int, int, unsigned int *); 19473void vec_vsx_st (vector bool int, int, int *); 19474void vec_vsx_st (vector signed short, int, vector signed short *); 19475void vec_vsx_st (vector signed short, int, short *); 19476void vec_vsx_st (vector unsigned short, int, vector unsigned short *); 19477void vec_vsx_st (vector unsigned short, int, unsigned short *); 19478void vec_vsx_st (vector bool short, int, vector bool short *); 19479void vec_vsx_st (vector bool short, int, unsigned short *); 19480void vec_vsx_st (vector pixel, int, vector pixel *); 19481void vec_vsx_st (vector pixel, int, unsigned short *); 19482void vec_vsx_st (vector pixel, int, short *); 19483void vec_vsx_st (vector bool short, int, short *); 19484void vec_vsx_st (vector signed char, int, vector signed char *); 19485void vec_vsx_st (vector signed char, int, signed char *); 19486void vec_vsx_st (vector unsigned char, int, vector unsigned char *); 19487void vec_vsx_st (vector unsigned char, int, unsigned char *); 19488void vec_vsx_st (vector bool char, int, vector bool char *); 19489void vec_vsx_st (vector bool char, int, unsigned char *); 19490void vec_vsx_st (vector bool char, int, signed char *); 19491 19492vector double vec_xxpermdi (vector double, vector double, const int); 19493vector float vec_xxpermdi (vector float, vector float, const int); 19494vector long long vec_xxpermdi (vector long long, vector long long, const int); 19495vector unsigned long long vec_xxpermdi (vector unsigned long long, 19496 vector unsigned long long, const int); 19497vector int vec_xxpermdi (vector int, vector int, const int); 19498vector unsigned int vec_xxpermdi (vector unsigned int, 19499 vector unsigned int, const int); 19500vector short vec_xxpermdi (vector short, vector short, const int); 19501vector unsigned short vec_xxpermdi (vector unsigned short, 19502 vector unsigned short, const int); 19503vector signed char vec_xxpermdi (vector signed char, vector signed char, 19504 const int); 19505vector unsigned char vec_xxpermdi (vector unsigned char, 19506 vector unsigned char, const int); 19507 19508vector double vec_xxsldi (vector double, vector double, int); 19509vector float vec_xxsldi (vector float, vector float, int); 19510vector long long vec_xxsldi (vector long long, vector long long, int); 19511vector unsigned long long vec_xxsldi (vector unsigned long long, 19512 vector unsigned long long, int); 19513vector int vec_xxsldi (vector int, vector int, int); 19514vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int); 19515vector short vec_xxsldi (vector short, vector short, int); 19516vector unsigned short vec_xxsldi (vector unsigned short, 19517 vector unsigned short, int); 19518vector signed char vec_xxsldi (vector signed char, vector signed char, int); 19519vector unsigned char vec_xxsldi (vector unsigned char, 19520 vector unsigned char, int); 19521@end smallexample 19522 19523Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always 19524generate the AltiVec @samp{LVX} and @samp{STVX} instructions even 19525if the VSX instruction set is available. The @samp{vec_vsx_ld} and 19526@samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X}, 19527@samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions. 19528 19529@node PowerPC AltiVec Built-in Functions Available on ISA 2.07 19530@subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07 19531 19532If the ISA 2.07 additions to the vector/scalar (power8-vector) 19533instruction set are available, the following additional functions are 19534available for both 32-bit and 64-bit targets. For 64-bit targets, you 19535can use @var{vector long} instead of @var{vector long long}, 19536@var{vector bool long} instead of @var{vector bool long long}, and 19537@var{vector unsigned long} instead of @var{vector unsigned long long}. 19538 19539@smallexample 19540vector signed char vec_neg (vector signed char); 19541vector signed short vec_neg (vector signed short); 19542vector signed int vec_neg (vector signed int); 19543vector signed long long vec_neg (vector signed long long); 19544vector float char vec_neg (vector float); 19545vector double vec_neg (vector double); 19546 19547vector signed int vec_signed2 (vector double, vector double); 19548 19549vector signed int vec_unsigned2 (vector double, vector double); 19550 19551vector long long vec_abs (vector long long); 19552 19553vector long long vec_add (vector long long, vector long long); 19554vector unsigned long long vec_add (vector unsigned long long, 19555 vector unsigned long long); 19556 19557int vec_all_eq (vector long long, vector long long); 19558int vec_all_eq (vector unsigned long long, vector unsigned long long); 19559int vec_all_ge (vector long long, vector long long); 19560int vec_all_ge (vector unsigned long long, vector unsigned long long); 19561int vec_all_gt (vector long long, vector long long); 19562int vec_all_gt (vector unsigned long long, vector unsigned long long); 19563int vec_all_le (vector long long, vector long long); 19564int vec_all_le (vector unsigned long long, vector unsigned long long); 19565int vec_all_lt (vector long long, vector long long); 19566int vec_all_lt (vector unsigned long long, vector unsigned long long); 19567int vec_all_ne (vector long long, vector long long); 19568int vec_all_ne (vector unsigned long long, vector unsigned long long); 19569 19570int vec_any_eq (vector long long, vector long long); 19571int vec_any_eq (vector unsigned long long, vector unsigned long long); 19572int vec_any_ge (vector long long, vector long long); 19573int vec_any_ge (vector unsigned long long, vector unsigned long long); 19574int vec_any_gt (vector long long, vector long long); 19575int vec_any_gt (vector unsigned long long, vector unsigned long long); 19576int vec_any_le (vector long long, vector long long); 19577int vec_any_le (vector unsigned long long, vector unsigned long long); 19578int vec_any_lt (vector long long, vector long long); 19579int vec_any_lt (vector unsigned long long, vector unsigned long long); 19580int vec_any_ne (vector long long, vector long long); 19581int vec_any_ne (vector unsigned long long, vector unsigned long long); 19582 19583vector bool long long vec_cmpeq (vector bool long long, vector bool long long); 19584 19585vector long long vec_eqv (vector long long, vector long long); 19586vector long long vec_eqv (vector bool long long, vector long long); 19587vector long long vec_eqv (vector long long, vector bool long long); 19588vector unsigned long long vec_eqv (vector unsigned long long, vector unsigned long long); 19589vector unsigned long long vec_eqv (vector bool long long, vector unsigned long long); 19590vector unsigned long long vec_eqv (vector unsigned long long, 19591 vector bool long long); 19592vector int vec_eqv (vector int, vector int); 19593vector int vec_eqv (vector bool int, vector int); 19594vector int vec_eqv (vector int, vector bool int); 19595vector unsigned int vec_eqv (vector unsigned int, vector unsigned int); 19596vector unsigned int vec_eqv (vector bool unsigned int, vector unsigned int); 19597vector unsigned int vec_eqv (vector unsigned int, vector bool unsigned int); 19598vector short vec_eqv (vector short, vector short); 19599vector short vec_eqv (vector bool short, vector short); 19600vector short vec_eqv (vector short, vector bool short); 19601vector unsigned short vec_eqv (vector unsigned short, vector unsigned short); 19602vector unsigned short vec_eqv (vector bool unsigned short, vector unsigned short); 19603vector unsigned short vec_eqv (vector unsigned short, vector bool unsigned short); 19604vector signed char vec_eqv (vector signed char, vector signed char); 19605vector signed char vec_eqv (vector bool signed char, vector signed char); 19606vector signed char vec_eqv (vector signed char, vector bool signed char); 19607vector unsigned char vec_eqv (vector unsigned char, vector unsigned char); 19608vector unsigned char vec_eqv (vector bool unsigned char, vector unsigned char); 19609vector unsigned char vec_eqv (vector unsigned char, vector bool unsigned char); 19610 19611vector long long vec_max (vector long long, vector long long); 19612vector unsigned long long vec_max (vector unsigned long long, 19613 vector unsigned long long); 19614 19615vector signed int vec_mergee (vector signed int, vector signed int); 19616vector unsigned int vec_mergee (vector unsigned int, vector unsigned int); 19617vector bool int vec_mergee (vector bool int, vector bool int); 19618 19619vector signed int vec_mergeo (vector signed int, vector signed int); 19620vector unsigned int vec_mergeo (vector unsigned int, vector unsigned int); 19621vector bool int vec_mergeo (vector bool int, vector bool int); 19622 19623vector long long vec_min (vector long long, vector long long); 19624vector unsigned long long vec_min (vector unsigned long long, 19625 vector unsigned long long); 19626 19627vector signed long long vec_nabs (vector signed long long); 19628 19629vector long long vec_nand (vector long long, vector long long); 19630vector long long vec_nand (vector bool long long, vector long long); 19631vector long long vec_nand (vector long long, vector bool long long); 19632vector unsigned long long vec_nand (vector unsigned long long, 19633 vector unsigned long long); 19634vector unsigned long long vec_nand (vector bool long long, vector unsigned long long); 19635vector unsigned long long vec_nand (vector unsigned long long, vector bool long long); 19636vector int vec_nand (vector int, vector int); 19637vector int vec_nand (vector bool int, vector int); 19638vector int vec_nand (vector int, vector bool int); 19639vector unsigned int vec_nand (vector unsigned int, vector unsigned int); 19640vector unsigned int vec_nand (vector bool unsigned int, vector unsigned int); 19641vector unsigned int vec_nand (vector unsigned int, vector bool unsigned int); 19642vector short vec_nand (vector short, vector short); 19643vector short vec_nand (vector bool short, vector short); 19644vector short vec_nand (vector short, vector bool short); 19645vector unsigned short vec_nand (vector unsigned short, vector unsigned short); 19646vector unsigned short vec_nand (vector bool unsigned short, vector unsigned short); 19647vector unsigned short vec_nand (vector unsigned short, vector bool unsigned short); 19648vector signed char vec_nand (vector signed char, vector signed char); 19649vector signed char vec_nand (vector bool signed char, vector signed char); 19650vector signed char vec_nand (vector signed char, vector bool signed char); 19651vector unsigned char vec_nand (vector unsigned char, vector unsigned char); 19652vector unsigned char vec_nand (vector bool unsigned char, vector unsigned char); 19653vector unsigned char vec_nand (vector unsigned char, vector bool unsigned char); 19654 19655vector long long vec_orc (vector long long, vector long long); 19656vector long long vec_orc (vector bool long long, vector long long); 19657vector long long vec_orc (vector long long, vector bool long long); 19658vector unsigned long long vec_orc (vector unsigned long long, 19659 vector unsigned long long); 19660vector unsigned long long vec_orc (vector bool long long, vector unsigned long long); 19661vector unsigned long long vec_orc (vector unsigned long long, vector bool long long); 19662vector int vec_orc (vector int, vector int); 19663vector int vec_orc (vector bool int, vector int); 19664vector int vec_orc (vector int, vector bool int); 19665vector unsigned int vec_orc (vector unsigned int, vector unsigned int); 19666vector unsigned int vec_orc (vector bool unsigned int, vector unsigned int); 19667vector unsigned int vec_orc (vector unsigned int, vector bool unsigned int); 19668vector short vec_orc (vector short, vector short); 19669vector short vec_orc (vector bool short, vector short); 19670vector short vec_orc (vector short, vector bool short); 19671vector unsigned short vec_orc (vector unsigned short, vector unsigned short); 19672vector unsigned short vec_orc (vector bool unsigned short, vector unsigned short); 19673vector unsigned short vec_orc (vector unsigned short, vector bool unsigned short); 19674vector signed char vec_orc (vector signed char, vector signed char); 19675vector signed char vec_orc (vector bool signed char, vector signed char); 19676vector signed char vec_orc (vector signed char, vector bool signed char); 19677vector unsigned char vec_orc (vector unsigned char, vector unsigned char); 19678vector unsigned char vec_orc (vector bool unsigned char, vector unsigned char); 19679vector unsigned char vec_orc (vector unsigned char, vector bool unsigned char); 19680 19681vector int vec_pack (vector long long, vector long long); 19682vector unsigned int vec_pack (vector unsigned long long, vector unsigned long long); 19683vector bool int vec_pack (vector bool long long, vector bool long long); 19684vector float vec_pack (vector double, vector double); 19685 19686vector int vec_packs (vector long long, vector long long); 19687vector unsigned int vec_packs (vector unsigned long long, vector unsigned long long); 19688 19689vector unsigned char vec_packsu (vector signed short, vector signed short) 19690vector unsigned char vec_packsu (vector unsigned short, vector unsigned short) 19691vector unsigned short int vec_packsu (vector signed int, vector signed int); 19692vector unsigned short int vec_packsu (vector unsigned int, vector unsigned int); 19693vector unsigned int vec_packsu (vector long long, vector long long); 19694vector unsigned int vec_packsu (vector unsigned long long, vector unsigned long long); 19695vector unsigned int vec_packsu (vector signed long long, vector signed long long); 19696 19697vector unsigned char vec_popcnt (vector signed char); 19698vector unsigned char vec_popcnt (vector unsigned char); 19699vector unsigned short vec_popcnt (vector signed short); 19700vector unsigned short vec_popcnt (vector unsigned short); 19701vector unsigned int vec_popcnt (vector signed int); 19702vector unsigned int vec_popcnt (vector unsigned int); 19703vector unsigned long long vec_popcnt (vector signed long long); 19704vector unsigned long long vec_popcnt (vector unsigned long long); 19705 19706vector long long vec_rl (vector long long, vector unsigned long long); 19707vector long long vec_rl (vector unsigned long long, vector unsigned long long); 19708 19709vector long long vec_sl (vector long long, vector unsigned long long); 19710vector long long vec_sl (vector unsigned long long, vector unsigned long long); 19711 19712vector long long vec_sr (vector long long, vector unsigned long long); 19713vector unsigned long long char vec_sr (vector unsigned long long, 19714 vector unsigned long long); 19715 19716vector long long vec_sra (vector long long, vector unsigned long long); 19717vector unsigned long long vec_sra (vector unsigned long long, 19718 vector unsigned long long); 19719 19720vector long long vec_sub (vector long long, vector long long); 19721vector unsigned long long vec_sub (vector unsigned long long, 19722 vector unsigned long long); 19723 19724vector long long vec_unpackh (vector int); 19725vector unsigned long long vec_unpackh (vector unsigned int); 19726 19727vector long long vec_unpackl (vector int); 19728vector unsigned long long vec_unpackl (vector unsigned int); 19729 19730vector long long vec_vaddudm (vector long long, vector long long); 19731vector long long vec_vaddudm (vector bool long long, vector long long); 19732vector long long vec_vaddudm (vector long long, vector bool long long); 19733vector unsigned long long vec_vaddudm (vector unsigned long long, 19734 vector unsigned long long); 19735vector unsigned long long vec_vaddudm (vector bool unsigned long long, 19736 vector unsigned long long); 19737vector unsigned long long vec_vaddudm (vector unsigned long long, 19738 vector bool unsigned long long); 19739 19740vector long long vec_vbpermq (vector signed char, vector signed char); 19741vector long long vec_vbpermq (vector unsigned char, vector unsigned char); 19742 19743vector unsigned char vec_bperm (vector unsigned char, vector unsigned char); 19744vector unsigned char vec_bperm (vector unsigned long long, vector unsigned char); 19745vector unsigned long long vec_bperm (vector unsigned __int128, vector unsigned char); 19746 19747vector long long vec_cntlz (vector long long); 19748vector unsigned long long vec_cntlz (vector unsigned long long); 19749vector int vec_cntlz (vector int); 19750vector unsigned int vec_cntlz (vector int); 19751vector short vec_cntlz (vector short); 19752vector unsigned short vec_cntlz (vector unsigned short); 19753vector signed char vec_cntlz (vector signed char); 19754vector unsigned char vec_cntlz (vector unsigned char); 19755 19756vector long long vec_vclz (vector long long); 19757vector unsigned long long vec_vclz (vector unsigned long long); 19758vector int vec_vclz (vector int); 19759vector unsigned int vec_vclz (vector int); 19760vector short vec_vclz (vector short); 19761vector unsigned short vec_vclz (vector unsigned short); 19762vector signed char vec_vclz (vector signed char); 19763vector unsigned char vec_vclz (vector unsigned char); 19764 19765vector signed char vec_vclzb (vector signed char); 19766vector unsigned char vec_vclzb (vector unsigned char); 19767 19768vector long long vec_vclzd (vector long long); 19769vector unsigned long long vec_vclzd (vector unsigned long long); 19770 19771vector short vec_vclzh (vector short); 19772vector unsigned short vec_vclzh (vector unsigned short); 19773 19774vector int vec_vclzw (vector int); 19775vector unsigned int vec_vclzw (vector int); 19776 19777vector signed char vec_vgbbd (vector signed char); 19778vector unsigned char vec_vgbbd (vector unsigned char); 19779 19780vector long long vec_vmaxsd (vector long long, vector long long); 19781 19782vector unsigned long long vec_vmaxud (vector unsigned long long, 19783 unsigned vector long long); 19784 19785vector long long vec_vminsd (vector long long, vector long long); 19786 19787vector unsigned long long vec_vminud (vector long long, vector long long); 19788 19789vector int vec_vpksdss (vector long long, vector long long); 19790vector unsigned int vec_vpksdss (vector long long, vector long long); 19791 19792vector unsigned int vec_vpkudus (vector unsigned long long, 19793 vector unsigned long long); 19794 19795vector int vec_vpkudum (vector long long, vector long long); 19796vector unsigned int vec_vpkudum (vector unsigned long long, 19797 vector unsigned long long); 19798vector bool int vec_vpkudum (vector bool long long, vector bool long long); 19799 19800vector long long vec_vpopcnt (vector long long); 19801vector unsigned long long vec_vpopcnt (vector unsigned long long); 19802vector int vec_vpopcnt (vector int); 19803vector unsigned int vec_vpopcnt (vector int); 19804vector short vec_vpopcnt (vector short); 19805vector unsigned short vec_vpopcnt (vector unsigned short); 19806vector signed char vec_vpopcnt (vector signed char); 19807vector unsigned char vec_vpopcnt (vector unsigned char); 19808 19809vector signed char vec_vpopcntb (vector signed char); 19810vector unsigned char vec_vpopcntb (vector unsigned char); 19811 19812vector long long vec_vpopcntd (vector long long); 19813vector unsigned long long vec_vpopcntd (vector unsigned long long); 19814 19815vector short vec_vpopcnth (vector short); 19816vector unsigned short vec_vpopcnth (vector unsigned short); 19817 19818vector int vec_vpopcntw (vector int); 19819vector unsigned int vec_vpopcntw (vector int); 19820 19821vector long long vec_vrld (vector long long, vector unsigned long long); 19822vector unsigned long long vec_vrld (vector unsigned long long, 19823 vector unsigned long long); 19824 19825vector long long vec_vsld (vector long long, vector unsigned long long); 19826vector long long vec_vsld (vector unsigned long long, 19827 vector unsigned long long); 19828 19829vector long long vec_vsrad (vector long long, vector unsigned long long); 19830vector unsigned long long vec_vsrad (vector unsigned long long, 19831 vector unsigned long long); 19832 19833vector long long vec_vsrd (vector long long, vector unsigned long long); 19834vector unsigned long long char vec_vsrd (vector unsigned long long, 19835 vector unsigned long long); 19836 19837vector long long vec_vsubudm (vector long long, vector long long); 19838vector long long vec_vsubudm (vector bool long long, vector long long); 19839vector long long vec_vsubudm (vector long long, vector bool long long); 19840vector unsigned long long vec_vsubudm (vector unsigned long long, 19841 vector unsigned long long); 19842vector unsigned long long vec_vsubudm (vector bool long long, 19843 vector unsigned long long); 19844vector unsigned long long vec_vsubudm (vector unsigned long long, 19845 vector bool long long); 19846 19847vector long long vec_vupkhsw (vector int); 19848vector unsigned long long vec_vupkhsw (vector unsigned int); 19849 19850vector long long vec_vupklsw (vector int); 19851vector unsigned long long vec_vupklsw (vector int); 19852@end smallexample 19853 19854If the ISA 2.07 additions to the vector/scalar (power8-vector) 19855instruction set are available, the following additional functions are 19856available for 64-bit targets. New vector types 19857(@var{vector __int128} and @var{vector __uint128}) are available 19858to hold the @var{__int128} and @var{__uint128} types to use these 19859builtins. 19860 19861The normal vector extract, and set operations work on 19862@var{vector __int128} and @var{vector __uint128} types, 19863but the index value must be 0. 19864 19865@smallexample 19866vector __int128 vec_vaddcuq (vector __int128, vector __int128); 19867vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128); 19868 19869vector __int128 vec_vadduqm (vector __int128, vector __int128); 19870vector __uint128 vec_vadduqm (vector __uint128, vector __uint128); 19871 19872vector __int128 vec_vaddecuq (vector __int128, vector __int128, 19873 vector __int128); 19874vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128, 19875 vector __uint128); 19876 19877vector __int128 vec_vaddeuqm (vector __int128, vector __int128, 19878 vector __int128); 19879vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128, 19880 vector __uint128); 19881 19882vector __int128 vec_vsubecuq (vector __int128, vector __int128, 19883 vector __int128); 19884vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128, 19885 vector __uint128); 19886 19887vector __int128 vec_vsubeuqm (vector __int128, vector __int128, 19888 vector __int128); 19889vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128, 19890 vector __uint128); 19891 19892vector __int128 vec_vsubcuq (vector __int128, vector __int128); 19893vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128); 19894 19895__int128 vec_vsubuqm (__int128, __int128); 19896__uint128 vec_vsubuqm (__uint128, __uint128); 19897 19898vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int); 19899int __builtin_bcdadd_lt (vector __int128, vector __int128, const int); 19900int __builtin_bcdadd_eq (vector __int128, vector __int128, const int); 19901int __builtin_bcdadd_gt (vector __int128, vector __int128, const int); 19902int __builtin_bcdadd_ov (vector __int128, vector __int128, const int); 19903vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int); 19904int __builtin_bcdsub_lt (vector __int128, vector __int128, const int); 19905int __builtin_bcdsub_eq (vector __int128, vector __int128, const int); 19906int __builtin_bcdsub_gt (vector __int128, vector __int128, const int); 19907int __builtin_bcdsub_ov (vector __int128, vector __int128, const int); 19908@end smallexample 19909 19910@node PowerPC AltiVec Built-in Functions Available on ISA 3.0 19911@subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0 19912 19913The following additional built-in functions are also available for the 19914PowerPC family of processors, starting with ISA 3.0 19915(@option{-mcpu=power9}) or later: 19916@smallexample 19917unsigned int scalar_extract_exp (double source); 19918unsigned long long int scalar_extract_exp (__ieee128 source); 19919 19920unsigned long long int scalar_extract_sig (double source); 19921unsigned __int128 scalar_extract_sig (__ieee128 source); 19922 19923double scalar_insert_exp (unsigned long long int significand, 19924 unsigned long long int exponent); 19925double scalar_insert_exp (double significand, unsigned long long int exponent); 19926 19927ieee_128 scalar_insert_exp (unsigned __int128 significand, 19928 unsigned long long int exponent); 19929ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent); 19930 19931int scalar_cmp_exp_gt (double arg1, double arg2); 19932int scalar_cmp_exp_lt (double arg1, double arg2); 19933int scalar_cmp_exp_eq (double arg1, double arg2); 19934int scalar_cmp_exp_unordered (double arg1, double arg2); 19935 19936bool scalar_test_data_class (float source, const int condition); 19937bool scalar_test_data_class (double source, const int condition); 19938bool scalar_test_data_class (__ieee128 source, const int condition); 19939 19940bool scalar_test_neg (float source); 19941bool scalar_test_neg (double source); 19942bool scalar_test_neg (__ieee128 source); 19943 19944vector _uint128_t vec_msum (vector unsigned long long, 19945 vector unsigned long long, 19946 vector _uint128_t); 19947vector _int128_t vec_msum (vector signed long long, 19948 vector signed long long, 19949 vector _int128_t); 19950@end smallexample 19951 19952The @code{scalar_extract_exp} and @code{scalar_extract_sig} 19953functions require a 64-bit environment supporting ISA 3.0 or later. 19954The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in 19955functions return the significand and the biased exponent value 19956respectively of their @code{source} arguments. 19957When supplied with a 64-bit @code{source} argument, the 19958result returned by @code{scalar_extract_sig} has 19959the @code{0x0010000000000000} bit set if the 19960function's @code{source} argument is in normalized form. 19961Otherwise, this bit is set to 0. 19962When supplied with a 128-bit @code{source} argument, the 19963@code{0x00010000000000000000000000000000} bit of the result is 19964treated similarly. 19965Note that the sign of the significand is not represented in the result 19966returned from the @code{scalar_extract_sig} function. Use the 19967@code{scalar_test_neg} function to test the sign of its @code{double} 19968argument. 19969The @code{vec_msum} functions perform a vector multiply-sum, returning 19970the result of arg1*arg2+arg3. ISA 3.0 adds support for vec_msum returning 19971a vector int128 result. 19972 19973The @code{scalar_insert_exp} 19974functions require a 64-bit environment supporting ISA 3.0 or later. 19975When supplied with a 64-bit first argument, the 19976@code{scalar_insert_exp} built-in function returns a double-precision 19977floating point value that is constructed by assembling the values of its 19978@code{significand} and @code{exponent} arguments. The sign of the 19979result is copied from the most significant bit of the 19980@code{significand} argument. The significand and exponent components 19981of the result are composed of the least significant 11 bits of the 19982@code{exponent} argument and the least significant 52 bits of the 19983@code{significand} argument respectively. 19984 19985When supplied with a 128-bit first argument, the 19986@code{scalar_insert_exp} built-in function returns a quad-precision 19987ieee floating point value. The sign bit of the result is copied from 19988the most significant bit of the @code{significand} argument. 19989The significand and exponent components of the result are composed of 19990the least significant 15 bits of the @code{exponent} argument and the 19991least significant 112 bits of the @code{significand} argument respectively. 19992 19993The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt}, 19994@code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in 19995functions return a non-zero value if @code{arg1} is greater than, less 19996than, equal to, or not comparable to @code{arg2} respectively. The 19997arguments are not comparable if one or the other equals NaN (not a 19998number). 19999 20000The @code{scalar_test_data_class} built-in function returns 1 20001if any of the condition tests enabled by the value of the 20002@code{condition} variable are true, and 0 otherwise. The 20003@code{condition} argument must be a compile-time constant integer with 20004value not exceeding 127. The 20005@code{condition} argument is encoded as a bitmask with each bit 20006enabling the testing of a different condition, as characterized by the 20007following: 20008@smallexample 200090x40 Test for NaN 200100x20 Test for +Infinity 200110x10 Test for -Infinity 200120x08 Test for +Zero 200130x04 Test for -Zero 200140x02 Test for +Denormal 200150x01 Test for -Denormal 20016@end smallexample 20017 20018The @code{scalar_test_neg} built-in function returns 1 if its 20019@code{source} argument holds a negative value, 0 otherwise. 20020 20021The following built-in functions are also available for the PowerPC family 20022of processors, starting with ISA 3.0 or later 20023(@option{-mcpu=power9}). These string functions are described 20024separately in order to group the descriptions closer to the function 20025prototypes: 20026@smallexample 20027int vec_all_nez (vector signed char, vector signed char); 20028int vec_all_nez (vector unsigned char, vector unsigned char); 20029int vec_all_nez (vector signed short, vector signed short); 20030int vec_all_nez (vector unsigned short, vector unsigned short); 20031int vec_all_nez (vector signed int, vector signed int); 20032int vec_all_nez (vector unsigned int, vector unsigned int); 20033 20034int vec_any_eqz (vector signed char, vector signed char); 20035int vec_any_eqz (vector unsigned char, vector unsigned char); 20036int vec_any_eqz (vector signed short, vector signed short); 20037int vec_any_eqz (vector unsigned short, vector unsigned short); 20038int vec_any_eqz (vector signed int, vector signed int); 20039int vec_any_eqz (vector unsigned int, vector unsigned int); 20040 20041vector bool char vec_cmpnez (vector signed char arg1, vector signed char arg2); 20042vector bool char vec_cmpnez (vector unsigned char arg1, vector unsigned char arg2); 20043vector bool short vec_cmpnez (vector signed short arg1, vector signed short arg2); 20044vector bool short vec_cmpnez (vector unsigned short arg1, vector unsigned short arg2); 20045vector bool int vec_cmpnez (vector signed int arg1, vector signed int arg2); 20046vector bool int vec_cmpnez (vector unsigned int, vector unsigned int); 20047 20048vector signed char vec_cnttz (vector signed char); 20049vector unsigned char vec_cnttz (vector unsigned char); 20050vector signed short vec_cnttz (vector signed short); 20051vector unsigned short vec_cnttz (vector unsigned short); 20052vector signed int vec_cnttz (vector signed int); 20053vector unsigned int vec_cnttz (vector unsigned int); 20054vector signed long long vec_cnttz (vector signed long long); 20055vector unsigned long long vec_cnttz (vector unsigned long long); 20056 20057signed int vec_cntlz_lsbb (vector signed char); 20058signed int vec_cntlz_lsbb (vector unsigned char); 20059 20060signed int vec_cnttz_lsbb (vector signed char); 20061signed int vec_cnttz_lsbb (vector unsigned char); 20062 20063unsigned int vec_first_match_index (vector signed char, vector signed char); 20064unsigned int vec_first_match_index (vector unsigned char, vector unsigned char); 20065unsigned int vec_first_match_index (vector signed int, vector signed int); 20066unsigned int vec_first_match_index (vector unsigned int, vector unsigned int); 20067unsigned int vec_first_match_index (vector signed short, vector signed short); 20068unsigned int vec_first_match_index (vector unsigned short, vector unsigned short); 20069unsigned int vec_first_match_or_eos_index (vector signed char, vector signed char); 20070unsigned int vec_first_match_or_eos_index (vector unsigned char, vector unsigned char); 20071unsigned int vec_first_match_or_eos_index (vector signed int, vector signed int); 20072unsigned int vec_first_match_or_eos_index (vector unsigned int, vector unsigned int); 20073unsigned int vec_first_match_or_eos_index (vector signed short, vector signed short); 20074unsigned int vec_first_match_or_eos_index (vector unsigned short, 20075 vector unsigned short); 20076unsigned int vec_first_mismatch_index (vector signed char, vector signed char); 20077unsigned int vec_first_mismatch_index (vector unsigned char, vector unsigned char); 20078unsigned int vec_first_mismatch_index (vector signed int, vector signed int); 20079unsigned int vec_first_mismatch_index (vector unsigned int, vector unsigned int); 20080unsigned int vec_first_mismatch_index (vector signed short, vector signed short); 20081unsigned int vec_first_mismatch_index (vector unsigned short, vector unsigned short); 20082unsigned int vec_first_mismatch_or_eos_index (vector signed char, vector signed char); 20083unsigned int vec_first_mismatch_or_eos_index (vector unsigned char, 20084 vector unsigned char); 20085unsigned int vec_first_mismatch_or_eos_index (vector signed int, vector signed int); 20086unsigned int vec_first_mismatch_or_eos_index (vector unsigned int, vector unsigned int); 20087unsigned int vec_first_mismatch_or_eos_index (vector signed short, vector signed short); 20088unsigned int vec_first_mismatch_or_eos_index (vector unsigned short, 20089 vector unsigned short); 20090 20091vector unsigned short vec_pack_to_short_fp32 (vector float, vector float); 20092 20093vector signed char vec_xl_be (signed long long, signed char *); 20094vector unsigned char vec_xl_be (signed long long, unsigned char *); 20095vector signed int vec_xl_be (signed long long, signed int *); 20096vector unsigned int vec_xl_be (signed long long, unsigned int *); 20097vector signed __int128 vec_xl_be (signed long long, signed __int128 *); 20098vector unsigned __int128 vec_xl_be (signed long long, unsigned __int128 *); 20099vector signed long long vec_xl_be (signed long long, signed long long *); 20100vector unsigned long long vec_xl_be (signed long long, unsigned long long *); 20101vector signed short vec_xl_be (signed long long, signed short *); 20102vector unsigned short vec_xl_be (signed long long, unsigned short *); 20103vector double vec_xl_be (signed long long, double *); 20104vector float vec_xl_be (signed long long, float *); 20105 20106vector signed char vec_xl_len (signed char *addr, size_t len); 20107vector unsigned char vec_xl_len (unsigned char *addr, size_t len); 20108vector signed int vec_xl_len (signed int *addr, size_t len); 20109vector unsigned int vec_xl_len (unsigned int *addr, size_t len); 20110vector signed __int128 vec_xl_len (signed __int128 *addr, size_t len); 20111vector unsigned __int128 vec_xl_len (unsigned __int128 *addr, size_t len); 20112vector signed long long vec_xl_len (signed long long *addr, size_t len); 20113vector unsigned long long vec_xl_len (unsigned long long *addr, size_t len); 20114vector signed short vec_xl_len (signed short *addr, size_t len); 20115vector unsigned short vec_xl_len (unsigned short *addr, size_t len); 20116vector double vec_xl_len (double *addr, size_t len); 20117vector float vec_xl_len (float *addr, size_t len); 20118 20119vector unsigned char vec_xl_len_r (unsigned char *addr, size_t len); 20120 20121void vec_xst_len (vector signed char data, signed char *addr, size_t len); 20122void vec_xst_len (vector unsigned char data, unsigned char *addr, size_t len); 20123void vec_xst_len (vector signed int data, signed int *addr, size_t len); 20124void vec_xst_len (vector unsigned int data, unsigned int *addr, size_t len); 20125void vec_xst_len (vector unsigned __int128 data, unsigned __int128 *addr, size_t len); 20126void vec_xst_len (vector signed long long data, signed long long *addr, size_t len); 20127void vec_xst_len (vector unsigned long long data, unsigned long long *addr, size_t len); 20128void vec_xst_len (vector signed short data, signed short *addr, size_t len); 20129void vec_xst_len (vector unsigned short data, unsigned short *addr, size_t len); 20130void vec_xst_len (vector signed __int128 data, signed __int128 *addr, size_t len); 20131void vec_xst_len (vector double data, double *addr, size_t len); 20132void vec_xst_len (vector float data, float *addr, size_t len); 20133 20134void vec_xst_len_r (vector unsigned char data, unsigned char *addr, size_t len); 20135 20136signed char vec_xlx (unsigned int index, vector signed char data); 20137unsigned char vec_xlx (unsigned int index, vector unsigned char data); 20138signed short vec_xlx (unsigned int index, vector signed short data); 20139unsigned short vec_xlx (unsigned int index, vector unsigned short data); 20140signed int vec_xlx (unsigned int index, vector signed int data); 20141unsigned int vec_xlx (unsigned int index, vector unsigned int data); 20142float vec_xlx (unsigned int index, vector float data); 20143 20144signed char vec_xrx (unsigned int index, vector signed char data); 20145unsigned char vec_xrx (unsigned int index, vector unsigned char data); 20146signed short vec_xrx (unsigned int index, vector signed short data); 20147unsigned short vec_xrx (unsigned int index, vector unsigned short data); 20148signed int vec_xrx (unsigned int index, vector signed int data); 20149unsigned int vec_xrx (unsigned int index, vector unsigned int data); 20150float vec_xrx (unsigned int index, vector float data); 20151@end smallexample 20152 20153The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez} 20154perform pairwise comparisons between the elements at the same 20155positions within their two vector arguments. 20156The @code{vec_all_nez} function returns a 20157non-zero value if and only if all pairwise comparisons are not 20158equal and no element of either vector argument contains a zero. 20159The @code{vec_any_eqz} function returns a 20160non-zero value if and only if at least one pairwise comparison is equal 20161or if at least one element of either vector argument contains a zero. 20162The @code{vec_cmpnez} function returns a vector of the same type as 20163its two arguments, within which each element consists of all ones to 20164denote that either the corresponding elements of the incoming arguments are 20165not equal or that at least one of the corresponding elements contains 20166zero. Otherwise, the element of the returned vector contains all zeros. 20167 20168The @code{vec_cntlz_lsbb} function returns the count of the number of 20169consecutive leading byte elements (starting from position 0 within the 20170supplied vector argument) for which the least-significant bit 20171equals zero. The @code{vec_cnttz_lsbb} function returns the count of 20172the number of consecutive trailing byte elements (starting from 20173position 15 and counting backwards within the supplied vector 20174argument) for which the least-significant bit equals zero. 20175 20176The @code{vec_xl_len} and @code{vec_xst_len} functions require a 2017764-bit environment supporting ISA 3.0 or later. The @code{vec_xl_len} 20178function loads a variable length vector from memory. The 20179@code{vec_xst_len} function stores a variable length vector to memory. 20180With both the @code{vec_xl_len} and @code{vec_xst_len} functions, the 20181@code{addr} argument represents the memory address to or from which 20182data will be transferred, and the 20183@code{len} argument represents the number of bytes to be 20184transferred, as computed by the C expression @code{min((len & 0xff), 16)}. 20185If this expression's value is not a multiple of the vector element's 20186size, the behavior of this function is undefined. 20187In the case that the underlying computer is configured to run in 20188big-endian mode, the data transfer moves bytes 0 to @code{(len - 1)} of 20189the corresponding vector. In little-endian mode, the data transfer 20190moves bytes @code{(16 - len)} to @code{15} of the corresponding 20191vector. For the load function, any bytes of the result vector that 20192are not loaded from memory are set to zero. 20193The value of the @code{addr} argument need not be aligned on a 20194multiple of the vector's element size. 20195 20196The @code{vec_xlx} and @code{vec_xrx} functions extract the single 20197element selected by the @code{index} argument from the vector 20198represented by the @code{data} argument. The @code{index} argument 20199always specifies a byte offset, regardless of the size of the vector 20200element. With @code{vec_xlx}, @code{index} is the offset of the first 20201byte of the element to be extracted. With @code{vec_xrx}, @code{index} 20202represents the last byte of the element to be extracted, measured 20203from the right end of the vector. In other words, the last byte of 20204the element to be extracted is found at position @code{(15 - index)}. 20205There is no requirement that @code{index} be a multiple of the vector 20206element size. However, if the size of the vector element added to 20207@code{index} is greater than 15, the content of the returned value is 20208undefined. 20209 20210If the ISA 3.0 instruction set additions (@option{-mcpu=power9}) 20211are available: 20212 20213@smallexample 20214vector unsigned long long vec_bperm (vector unsigned long long, vector unsigned char); 20215 20216vector bool char vec_cmpne (vector bool char, vector bool char); 20217vector bool char vec_cmpne (vector signed char, vector signed char); 20218vector bool char vec_cmpne (vector unsigned char, vector unsigned char); 20219vector bool int vec_cmpne (vector bool int, vector bool int); 20220vector bool int vec_cmpne (vector signed int, vector signed int); 20221vector bool int vec_cmpne (vector unsigned int, vector unsigned int); 20222vector bool long long vec_cmpne (vector bool long long, vector bool long long); 20223vector bool long long vec_cmpne (vector signed long long, vector signed long long); 20224vector bool long long vec_cmpne (vector unsigned long long, vector unsigned long long); 20225vector bool short vec_cmpne (vector bool short, vector bool short); 20226vector bool short vec_cmpne (vector signed short, vector signed short); 20227vector bool short vec_cmpne (vector unsigned short, vector unsigned short); 20228vector bool long long vec_cmpne (vector double, vector double); 20229vector bool int vec_cmpne (vector float, vector float); 20230 20231vector float vec_extract_fp32_from_shorth (vector unsigned short); 20232vector float vec_extract_fp32_from_shortl (vector unsigned short); 20233 20234vector long long vec_vctz (vector long long); 20235vector unsigned long long vec_vctz (vector unsigned long long); 20236vector int vec_vctz (vector int); 20237vector unsigned int vec_vctz (vector int); 20238vector short vec_vctz (vector short); 20239vector unsigned short vec_vctz (vector unsigned short); 20240vector signed char vec_vctz (vector signed char); 20241vector unsigned char vec_vctz (vector unsigned char); 20242 20243vector signed char vec_vctzb (vector signed char); 20244vector unsigned char vec_vctzb (vector unsigned char); 20245 20246vector long long vec_vctzd (vector long long); 20247vector unsigned long long vec_vctzd (vector unsigned long long); 20248 20249vector short vec_vctzh (vector short); 20250vector unsigned short vec_vctzh (vector unsigned short); 20251 20252vector int vec_vctzw (vector int); 20253vector unsigned int vec_vctzw (vector int); 20254 20255vector unsigned long long vec_extract4b (vector unsigned char, const int); 20256 20257vector unsigned char vec_insert4b (vector signed int, vector unsigned char, 20258 const int); 20259vector unsigned char vec_insert4b (vector unsigned int, vector unsigned char, 20260 const int); 20261 20262vector unsigned int vec_parity_lsbb (vector signed int); 20263vector unsigned int vec_parity_lsbb (vector unsigned int); 20264vector unsigned __int128 vec_parity_lsbb (vector signed __int128); 20265vector unsigned __int128 vec_parity_lsbb (vector unsigned __int128); 20266vector unsigned long long vec_parity_lsbb (vector signed long long); 20267vector unsigned long long vec_parity_lsbb (vector unsigned long long); 20268 20269vector int vec_vprtyb (vector int); 20270vector unsigned int vec_vprtyb (vector unsigned int); 20271vector long long vec_vprtyb (vector long long); 20272vector unsigned long long vec_vprtyb (vector unsigned long long); 20273 20274vector int vec_vprtybw (vector int); 20275vector unsigned int vec_vprtybw (vector unsigned int); 20276 20277vector long long vec_vprtybd (vector long long); 20278vector unsigned long long vec_vprtybd (vector unsigned long long); 20279@end smallexample 20280 20281On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9}) 20282are available: 20283 20284@smallexample 20285vector long vec_vprtyb (vector long); 20286vector unsigned long vec_vprtyb (vector unsigned long); 20287vector __int128 vec_vprtyb (vector __int128); 20288vector __uint128 vec_vprtyb (vector __uint128); 20289 20290vector long vec_vprtybd (vector long); 20291vector unsigned long vec_vprtybd (vector unsigned long); 20292 20293vector __int128 vec_vprtybq (vector __int128); 20294vector __uint128 vec_vprtybd (vector __uint128); 20295@end smallexample 20296 20297The following built-in vector functions are available for the PowerPC family 20298of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): 20299@smallexample 20300__vector unsigned char 20301vec_slv (__vector unsigned char src, __vector unsigned char shift_distance); 20302__vector unsigned char 20303vec_srv (__vector unsigned char src, __vector unsigned char shift_distance); 20304@end smallexample 20305 20306The @code{vec_slv} and @code{vec_srv} functions operate on 20307all of the bytes of their @code{src} and @code{shift_distance} 20308arguments in parallel. The behavior of the @code{vec_slv} is as if 20309there existed a temporary array of 17 unsigned characters 20310@code{slv_array} within which elements 0 through 15 are the same as 20311the entries in the @code{src} array and element 16 equals 0. The 20312result returned from the @code{vec_slv} function is a 20313@code{__vector} of 16 unsigned characters within which element 20314@code{i} is computed using the C expression 20315@code{0xff & (*((unsigned short *)(slv_array + i)) << (0x07 & 20316shift_distance[i]))}, 20317with this resulting value coerced to the @code{unsigned char} type. 20318The behavior of the @code{vec_srv} is as if 20319there existed a temporary array of 17 unsigned characters 20320@code{srv_array} within which element 0 equals zero and 20321elements 1 through 16 equal the elements 0 through 15 of 20322the @code{src} array. The 20323result returned from the @code{vec_srv} function is a 20324@code{__vector} of 16 unsigned characters within which element 20325@code{i} is computed using the C expression 20326@code{0xff & (*((unsigned short *)(srv_array + i)) >> 20327(0x07 & shift_distance[i]))}, 20328with this resulting value coerced to the @code{unsigned char} type. 20329 20330The following built-in functions are available for the PowerPC family 20331of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): 20332@smallexample 20333__vector unsigned char 20334vec_absd (__vector unsigned char arg1, __vector unsigned char arg2); 20335__vector unsigned short 20336vec_absd (__vector unsigned short arg1, __vector unsigned short arg2); 20337__vector unsigned int 20338vec_absd (__vector unsigned int arg1, __vector unsigned int arg2); 20339 20340__vector unsigned char 20341vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2); 20342__vector unsigned short 20343vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2); 20344__vector unsigned int 20345vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2); 20346@end smallexample 20347 20348The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and 20349@code{vec_absdw} built-in functions each computes the absolute 20350differences of the pairs of vector elements supplied in its two vector 20351arguments, placing the absolute differences into the corresponding 20352elements of the vector result. 20353 20354The following built-in functions are available for the PowerPC family 20355of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): 20356@smallexample 20357__vector unsigned int vec_extract_exp (__vector float source); 20358__vector unsigned long long int vec_extract_exp (__vector double source); 20359 20360__vector unsigned int vec_extract_sig (__vector float source); 20361__vector unsigned long long int vec_extract_sig (__vector double source); 20362 20363__vector float vec_insert_exp (__vector unsigned int significands, 20364 __vector unsigned int exponents); 20365__vector float vec_insert_exp (__vector unsigned float significands, 20366 __vector unsigned int exponents); 20367__vector double vec_insert_exp (__vector unsigned long long int significands, 20368 __vector unsigned long long int exponents); 20369__vector double vec_insert_exp (__vector unsigned double significands, 20370 __vector unsigned long long int exponents); 20371 20372__vector bool int vec_test_data_class (__vector float source, const int condition); 20373__vector bool long long int vec_test_data_class (__vector double source, 20374 const int condition); 20375@end smallexample 20376 20377The @code{vec_extract_sig} and @code{vec_extract_exp} built-in 20378functions return vectors representing the significands and biased 20379exponent values of their @code{source} arguments respectively. 20380Within the result vector returned by @code{vec_extract_sig}, the 20381@code{0x800000} bit of each vector element returned when the 20382function's @code{source} argument is of type @code{float} is set to 1 20383if the corresponding floating point value is in normalized form. 20384Otherwise, this bit is set to 0. When the @code{source} argument is 20385of type @code{double}, the @code{0x10000000000000} bit within each of 20386the result vector's elements is set according to the same rules. 20387Note that the sign of the significand is not represented in the result 20388returned from the @code{vec_extract_sig} function. To extract the 20389sign bits, use the 20390@code{vec_cpsgn} function, which returns a new vector within which all 20391of the sign bits of its second argument vector are overwritten with the 20392sign bits copied from the coresponding elements of its first argument 20393vector, and all other (non-sign) bits of the second argument vector 20394are copied unchanged into the result vector. 20395 20396The @code{vec_insert_exp} built-in functions return a vector of 20397single- or double-precision floating 20398point values constructed by assembling the values of their 20399@code{significands} and @code{exponents} arguments into the 20400corresponding elements of the returned vector. 20401The sign of each 20402element of the result is copied from the most significant bit of the 20403corresponding entry within the @code{significands} argument. 20404Note that the relevant 20405bits of the @code{significands} argument are the same, for both integer 20406and floating point types. 20407The 20408significand and exponent components of each element of the result are 20409composed of the least significant bits of the corresponding 20410@code{significands} element and the least significant bits of the 20411corresponding @code{exponents} element. 20412 20413The @code{vec_test_data_class} built-in function returns a vector 20414representing the results of testing the @code{source} vector for the 20415condition selected by the @code{condition} argument. The 20416@code{condition} argument must be a compile-time constant integer with 20417value not exceeding 127. The 20418@code{condition} argument is encoded as a bitmask with each bit 20419enabling the testing of a different condition, as characterized by the 20420following: 20421@smallexample 204220x40 Test for NaN 204230x20 Test for +Infinity 204240x10 Test for -Infinity 204250x08 Test for +Zero 204260x04 Test for -Zero 204270x02 Test for +Denormal 204280x01 Test for -Denormal 20429@end smallexample 20430 20431If any of the enabled test conditions is true, the corresponding entry 20432in the result vector is -1. Otherwise (all of the enabled test 20433conditions are false), the corresponding entry of the result vector is 0. 20434 20435The following built-in functions are available for the PowerPC family 20436of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): 20437@smallexample 20438vector unsigned int vec_rlmi (vector unsigned int, vector unsigned int, 20439 vector unsigned int); 20440vector unsigned long long vec_rlmi (vector unsigned long long, 20441 vector unsigned long long, 20442 vector unsigned long long); 20443vector unsigned int vec_rlnm (vector unsigned int, vector unsigned int, 20444 vector unsigned int); 20445vector unsigned long long vec_rlnm (vector unsigned long long, 20446 vector unsigned long long, 20447 vector unsigned long long); 20448vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int); 20449vector unsigned long long vec_vrlnm (vector unsigned long long, 20450 vector unsigned long long); 20451@end smallexample 20452 20453The result of @code{vec_rlmi} is obtained by rotating each element of 20454the first argument vector left and inserting it under mask into the 20455second argument vector. The third argument vector contains the mask 20456beginning in bits 11:15, the mask end in bits 19:23, and the shift 20457count in bits 27:31, of each element. 20458 20459The result of @code{vec_rlnm} is obtained by rotating each element of 20460the first argument vector left and ANDing it with a mask specified by 20461the second and third argument vectors. The second argument vector 20462contains the shift count for each element in the low-order byte. The 20463third argument vector contains the mask end for each element in the 20464low-order byte, with the mask begin in the next higher byte. 20465 20466The result of @code{vec_vrlnm} is obtained by rotating each element 20467of the first argument vector left and ANDing it with a mask. The 20468second argument vector contains the mask beginning in bits 11:15, 20469the mask end in bits 19:23, and the shift count in bits 27:31, 20470of each element. 20471 20472If the ISA 3.0 instruction set additions (@option{-mcpu=power9}) 20473are available: 20474@smallexample 20475vector signed bool char vec_revb (vector signed char); 20476vector signed char vec_revb (vector signed char); 20477vector unsigned char vec_revb (vector unsigned char); 20478vector bool short vec_revb (vector bool short); 20479vector short vec_revb (vector short); 20480vector unsigned short vec_revb (vector unsigned short); 20481vector bool int vec_revb (vector bool int); 20482vector int vec_revb (vector int); 20483vector unsigned int vec_revb (vector unsigned int); 20484vector float vec_revb (vector float); 20485vector bool long long vec_revb (vector bool long long); 20486vector long long vec_revb (vector long long); 20487vector unsigned long long vec_revb (vector unsigned long long); 20488vector double vec_revb (vector double); 20489@end smallexample 20490 20491On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9}) 20492are available: 20493@smallexample 20494vector long vec_revb (vector long); 20495vector unsigned long vec_revb (vector unsigned long); 20496vector __int128 vec_revb (vector __int128); 20497vector __uint128 vec_revb (vector __uint128); 20498@end smallexample 20499 20500The @code{vec_revb} built-in function reverses the bytes on an element 20501by element basis. A vector of @code{vector unsigned char} or 20502@code{vector signed char} reverses the bytes in the whole word. 20503 20504If the cryptographic instructions are enabled (@option{-mcrypto} or 20505@option{-mcpu=power8}), the following builtins are enabled. 20506 20507@smallexample 20508vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long); 20509 20510vector unsigned char vec_sbox_be (vector unsigned char); 20511 20512vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long, 20513 vector unsigned long long); 20514 20515vector unsigned char vec_cipher_be (vector unsigned char, vector unsigned char); 20516 20517vector unsigned long long __builtin_crypto_vcipherlast 20518 (vector unsigned long long, 20519 vector unsigned long long); 20520 20521vector unsigned char vec_cipherlast_be (vector unsigned char, 20522 vector unsigned char); 20523 20524vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long, 20525 vector unsigned long long); 20526 20527vector unsigned char vec_ncipher_be (vector unsigned char, 20528 vector unsigned char); 20529 20530vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long, 20531 vector unsigned long long); 20532 20533vector unsigned char vec_ncipherlast_be (vector unsigned char, 20534 vector unsigned char); 20535 20536vector unsigned char __builtin_crypto_vpermxor (vector unsigned char, 20537 vector unsigned char, 20538 vector unsigned char); 20539 20540vector unsigned short __builtin_crypto_vpermxor (vector unsigned short, 20541 vector unsigned short, 20542 vector unsigned short); 20543 20544vector unsigned int __builtin_crypto_vpermxor (vector unsigned int, 20545 vector unsigned int, 20546 vector unsigned int); 20547 20548vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long, 20549 vector unsigned long long, 20550 vector unsigned long long); 20551 20552vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char, 20553 vector unsigned char); 20554 20555vector unsigned short __builtin_crypto_vpmsumh (vector unsigned short, 20556 vector unsigned short); 20557 20558vector unsigned int __builtin_crypto_vpmsumw (vector unsigned int, 20559 vector unsigned int); 20560 20561vector unsigned long long __builtin_crypto_vpmsumd (vector unsigned long long, 20562 vector unsigned long long); 20563 20564vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long, 20565 int, int); 20566 20567vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int); 20568@end smallexample 20569 20570The second argument to @var{__builtin_crypto_vshasigmad} and 20571@var{__builtin_crypto_vshasigmaw} must be a constant 20572integer that is 0 or 1. The third argument to these built-in functions 20573must be a constant integer in the range of 0 to 15. 20574 20575If the ISA 3.0 instruction set additions 20576are enabled (@option{-mcpu=power9}), the following additional 20577functions are available for both 32-bit and 64-bit targets. 20578@smallexample 20579vector short vec_xl (int, vector short *); 20580vector short vec_xl (int, short *); 20581vector unsigned short vec_xl (int, vector unsigned short *); 20582vector unsigned short vec_xl (int, unsigned short *); 20583vector char vec_xl (int, vector char *); 20584vector char vec_xl (int, char *); 20585vector unsigned char vec_xl (int, vector unsigned char *); 20586vector unsigned char vec_xl (int, unsigned char *); 20587 20588void vec_xst (vector short, int, vector short *); 20589void vec_xst (vector short, int, short *); 20590void vec_xst (vector unsigned short, int, vector unsigned short *); 20591void vec_xst (vector unsigned short, int, unsigned short *); 20592void vec_xst (vector char, int, vector char *); 20593void vec_xst (vector char, int, char *); 20594void vec_xst (vector unsigned char, int, vector unsigned char *); 20595void vec_xst (vector unsigned char, int, unsigned char *); 20596@end smallexample 20597@node PowerPC Hardware Transactional Memory Built-in Functions 20598@subsection PowerPC Hardware Transactional Memory Built-in Functions 20599GCC provides two interfaces for accessing the Hardware Transactional 20600Memory (HTM) instructions available on some of the PowerPC family 20601of processors (eg, POWER8). The two interfaces come in a low level 20602interface, consisting of built-in functions specific to PowerPC and a 20603higher level interface consisting of inline functions that are common 20604between PowerPC and S/390. 20605 20606@subsubsection PowerPC HTM Low Level Built-in Functions 20607 20608The following low level built-in functions are available with 20609@option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later. 20610They all generate the machine instruction that is part of the name. 20611 20612The HTM builtins (with the exception of @code{__builtin_tbegin}) return 20613the full 4-bit condition register value set by their associated hardware 20614instruction. The header file @code{htmintrin.h} defines some macros that can 20615be used to decipher the return value. The @code{__builtin_tbegin} builtin 20616returns a simple @code{true} or @code{false} value depending on whether a transaction was 20617successfully started or not. The arguments of the builtins match exactly the 20618type and order of the associated hardware instruction's operands, except for 20619the @code{__builtin_tcheck} builtin, which does not take any input arguments. 20620Refer to the ISA manual for a description of each instruction's operands. 20621 20622@smallexample 20623unsigned int __builtin_tbegin (unsigned int) 20624unsigned int __builtin_tend (unsigned int) 20625 20626unsigned int __builtin_tabort (unsigned int) 20627unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int) 20628unsigned int __builtin_tabortdci (unsigned int, unsigned int, int) 20629unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int) 20630unsigned int __builtin_tabortwci (unsigned int, unsigned int, int) 20631 20632unsigned int __builtin_tcheck (void) 20633unsigned int __builtin_treclaim (unsigned int) 20634unsigned int __builtin_trechkpt (void) 20635unsigned int __builtin_tsr (unsigned int) 20636@end smallexample 20637 20638In addition to the above HTM built-ins, we have added built-ins for 20639some common extended mnemonics of the HTM instructions: 20640 20641@smallexample 20642unsigned int __builtin_tendall (void) 20643unsigned int __builtin_tresume (void) 20644unsigned int __builtin_tsuspend (void) 20645@end smallexample 20646 20647Note that the semantics of the above HTM builtins are required to mimic 20648the locking semantics used for critical sections. Builtins that are used 20649to create a new transaction or restart a suspended transaction must have 20650lock acquisition like semantics while those builtins that end or suspend a 20651transaction must have lock release like semantics. Specifically, this must 20652mimic lock semantics as specified by C++11, for example: Lock acquisition is 20653as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE) 20654that returns 0, and lock release is as-if an execution of 20655__atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an 20656implicit implementation-defined lock used for all transactions. The HTM 20657instructions associated with with the builtins inherently provide the 20658correct acquisition and release hardware barriers required. However, 20659the compiler must also be prohibited from moving loads and stores across 20660the builtins in a way that would violate their semantics. This has been 20661accomplished by adding memory barriers to the associated HTM instructions 20662(which is a conservative approach to provide acquire and release semantics). 20663Earlier versions of the compiler did not treat the HTM instructions as 20664memory barriers. A @code{__TM_FENCE__} macro has been added, which can 20665be used to determine whether the current compiler treats HTM instructions 20666as memory barriers or not. This allows the user to explicitly add memory 20667barriers to their code when using an older version of the compiler. 20668 20669The following set of built-in functions are available to gain access 20670to the HTM specific special purpose registers. 20671 20672@smallexample 20673unsigned long __builtin_get_texasr (void) 20674unsigned long __builtin_get_texasru (void) 20675unsigned long __builtin_get_tfhar (void) 20676unsigned long __builtin_get_tfiar (void) 20677 20678void __builtin_set_texasr (unsigned long); 20679void __builtin_set_texasru (unsigned long); 20680void __builtin_set_tfhar (unsigned long); 20681void __builtin_set_tfiar (unsigned long); 20682@end smallexample 20683 20684Example usage of these low level built-in functions may look like: 20685 20686@smallexample 20687#include <htmintrin.h> 20688 20689int num_retries = 10; 20690 20691while (1) 20692 @{ 20693 if (__builtin_tbegin (0)) 20694 @{ 20695 /* Transaction State Initiated. */ 20696 if (is_locked (lock)) 20697 __builtin_tabort (0); 20698 ... transaction code... 20699 __builtin_tend (0); 20700 break; 20701 @} 20702 else 20703 @{ 20704 /* Transaction State Failed. Use locks if the transaction 20705 failure is "persistent" or we've tried too many times. */ 20706 if (num_retries-- <= 0 20707 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ())) 20708 @{ 20709 acquire_lock (lock); 20710 ... non transactional fallback path... 20711 release_lock (lock); 20712 break; 20713 @} 20714 @} 20715 @} 20716@end smallexample 20717 20718One final built-in function has been added that returns the value of 20719the 2-bit Transaction State field of the Machine Status Register (MSR) 20720as stored in @code{CR0}. 20721 20722@smallexample 20723unsigned long __builtin_ttest (void) 20724@end smallexample 20725 20726This built-in can be used to determine the current transaction state 20727using the following code example: 20728 20729@smallexample 20730#include <htmintrin.h> 20731 20732unsigned char tx_state = _HTM_STATE (__builtin_ttest ()); 20733 20734if (tx_state == _HTM_TRANSACTIONAL) 20735 @{ 20736 /* Code to use in transactional state. */ 20737 @} 20738else if (tx_state == _HTM_NONTRANSACTIONAL) 20739 @{ 20740 /* Code to use in non-transactional state. */ 20741 @} 20742else if (tx_state == _HTM_SUSPENDED) 20743 @{ 20744 /* Code to use in transaction suspended state. */ 20745 @} 20746@end smallexample 20747 20748@subsubsection PowerPC HTM High Level Inline Functions 20749 20750The following high level HTM interface is made available by including 20751@code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU} 20752where CPU is `power8' or later. This interface is common between PowerPC 20753and S/390, allowing users to write one HTM source implementation that 20754can be compiled and executed on either system. 20755 20756@smallexample 20757long __TM_simple_begin (void) 20758long __TM_begin (void* const TM_buff) 20759long __TM_end (void) 20760void __TM_abort (void) 20761void __TM_named_abort (unsigned char const code) 20762void __TM_resume (void) 20763void __TM_suspend (void) 20764 20765long __TM_is_user_abort (void* const TM_buff) 20766long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code) 20767long __TM_is_illegal (void* const TM_buff) 20768long __TM_is_footprint_exceeded (void* const TM_buff) 20769long __TM_nesting_depth (void* const TM_buff) 20770long __TM_is_nested_too_deep(void* const TM_buff) 20771long __TM_is_conflict(void* const TM_buff) 20772long __TM_is_failure_persistent(void* const TM_buff) 20773long __TM_failure_address(void* const TM_buff) 20774long long __TM_failure_code(void* const TM_buff) 20775@end smallexample 20776 20777Using these common set of HTM inline functions, we can create 20778a more portable version of the HTM example in the previous 20779section that will work on either PowerPC or S/390: 20780 20781@smallexample 20782#include <htmxlintrin.h> 20783 20784int num_retries = 10; 20785TM_buff_type TM_buff; 20786 20787while (1) 20788 @{ 20789 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED) 20790 @{ 20791 /* Transaction State Initiated. */ 20792 if (is_locked (lock)) 20793 __TM_abort (); 20794 ... transaction code... 20795 __TM_end (); 20796 break; 20797 @} 20798 else 20799 @{ 20800 /* Transaction State Failed. Use locks if the transaction 20801 failure is "persistent" or we've tried too many times. */ 20802 if (num_retries-- <= 0 20803 || __TM_is_failure_persistent (TM_buff)) 20804 @{ 20805 acquire_lock (lock); 20806 ... non transactional fallback path... 20807 release_lock (lock); 20808 break; 20809 @} 20810 @} 20811 @} 20812@end smallexample 20813 20814@node PowerPC Atomic Memory Operation Functions 20815@subsection PowerPC Atomic Memory Operation Functions 20816ISA 3.0 of the PowerPC added new atomic memory operation (amo) 20817instructions. GCC provides support for these instructions in 64-bit 20818environments. All of the functions are declared in the include file 20819@code{amo.h}. 20820 20821The functions supported are: 20822 20823@smallexample 20824#include <amo.h> 20825 20826uint32_t amo_lwat_add (uint32_t *, uint32_t); 20827uint32_t amo_lwat_xor (uint32_t *, uint32_t); 20828uint32_t amo_lwat_ior (uint32_t *, uint32_t); 20829uint32_t amo_lwat_and (uint32_t *, uint32_t); 20830uint32_t amo_lwat_umax (uint32_t *, uint32_t); 20831uint32_t amo_lwat_umin (uint32_t *, uint32_t); 20832uint32_t amo_lwat_swap (uint32_t *, uint32_t); 20833 20834int32_t amo_lwat_sadd (int32_t *, int32_t); 20835int32_t amo_lwat_smax (int32_t *, int32_t); 20836int32_t amo_lwat_smin (int32_t *, int32_t); 20837int32_t amo_lwat_sswap (int32_t *, int32_t); 20838 20839uint64_t amo_ldat_add (uint64_t *, uint64_t); 20840uint64_t amo_ldat_xor (uint64_t *, uint64_t); 20841uint64_t amo_ldat_ior (uint64_t *, uint64_t); 20842uint64_t amo_ldat_and (uint64_t *, uint64_t); 20843uint64_t amo_ldat_umax (uint64_t *, uint64_t); 20844uint64_t amo_ldat_umin (uint64_t *, uint64_t); 20845uint64_t amo_ldat_swap (uint64_t *, uint64_t); 20846 20847int64_t amo_ldat_sadd (int64_t *, int64_t); 20848int64_t amo_ldat_smax (int64_t *, int64_t); 20849int64_t amo_ldat_smin (int64_t *, int64_t); 20850int64_t amo_ldat_sswap (int64_t *, int64_t); 20851 20852void amo_stwat_add (uint32_t *, uint32_t); 20853void amo_stwat_xor (uint32_t *, uint32_t); 20854void amo_stwat_ior (uint32_t *, uint32_t); 20855void amo_stwat_and (uint32_t *, uint32_t); 20856void amo_stwat_umax (uint32_t *, uint32_t); 20857void amo_stwat_umin (uint32_t *, uint32_t); 20858 20859void amo_stwat_sadd (int32_t *, int32_t); 20860void amo_stwat_smax (int32_t *, int32_t); 20861void amo_stwat_smin (int32_t *, int32_t); 20862 20863void amo_stdat_add (uint64_t *, uint64_t); 20864void amo_stdat_xor (uint64_t *, uint64_t); 20865void amo_stdat_ior (uint64_t *, uint64_t); 20866void amo_stdat_and (uint64_t *, uint64_t); 20867void amo_stdat_umax (uint64_t *, uint64_t); 20868void amo_stdat_umin (uint64_t *, uint64_t); 20869 20870void amo_stdat_sadd (int64_t *, int64_t); 20871void amo_stdat_smax (int64_t *, int64_t); 20872void amo_stdat_smin (int64_t *, int64_t); 20873@end smallexample 20874 20875@node PowerPC Matrix-Multiply Assist Built-in Functions 20876@subsection PowerPC Matrix-Multiply Assist Built-in Functions 20877ISA 3.1 of the PowerPC added new Matrix-Multiply Assist (MMA) instructions. 20878GCC provides support for these instructions through the following built-in 20879functions which are enabled with the @code{-mmma} option. The vec_t type 20880below is defined to be a normal vector unsigned char type. The uint2, uint4 20881and uint8 parameters are 2-bit, 4-bit and 8-bit unsigned integer constants 20882respectively. The compiler will verify that they are constants and that 20883their values are within range. 20884 20885The built-in functions supported are: 20886 20887@smallexample 20888void __builtin_mma_xvi4ger8 (__vector_quad *, vec_t, vec_t); 20889void __builtin_mma_xvi8ger4 (__vector_quad *, vec_t, vec_t); 20890void __builtin_mma_xvi16ger2 (__vector_quad *, vec_t, vec_t); 20891void __builtin_mma_xvi16ger2s (__vector_quad *, vec_t, vec_t); 20892void __builtin_mma_xvf16ger2 (__vector_quad *, vec_t, vec_t); 20893void __builtin_mma_xvbf16ger2 (__vector_quad *, vec_t, vec_t); 20894void __builtin_mma_xvf32ger (__vector_quad *, vec_t, vec_t); 20895 20896void __builtin_mma_xvi4ger8pp (__vector_quad *, vec_t, vec_t); 20897void __builtin_mma_xvi8ger4pp (__vector_quad *, vec_t, vec_t); 20898void __builtin_mma_xvi8ger4spp(__vector_quad *, vec_t, vec_t); 20899void __builtin_mma_xvi16ger2pp (__vector_quad *, vec_t, vec_t); 20900void __builtin_mma_xvi16ger2spp (__vector_quad *, vec_t, vec_t); 20901void __builtin_mma_xvf16ger2pp (__vector_quad *, vec_t, vec_t); 20902void __builtin_mma_xvf16ger2pn (__vector_quad *, vec_t, vec_t); 20903void __builtin_mma_xvf16ger2np (__vector_quad *, vec_t, vec_t); 20904void __builtin_mma_xvf16ger2nn (__vector_quad *, vec_t, vec_t); 20905void __builtin_mma_xvbf16ger2pp (__vector_quad *, vec_t, vec_t); 20906void __builtin_mma_xvbf16ger2pn (__vector_quad *, vec_t, vec_t); 20907void __builtin_mma_xvbf16ger2np (__vector_quad *, vec_t, vec_t); 20908void __builtin_mma_xvbf16ger2nn (__vector_quad *, vec_t, vec_t); 20909void __builtin_mma_xvf32gerpp (__vector_quad *, vec_t, vec_t); 20910void __builtin_mma_xvf32gerpn (__vector_quad *, vec_t, vec_t); 20911void __builtin_mma_xvf32gernp (__vector_quad *, vec_t, vec_t); 20912void __builtin_mma_xvf32gernn (__vector_quad *, vec_t, vec_t); 20913 20914void __builtin_mma_pmxvi4ger8 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8); 20915void __builtin_mma_pmxvi4ger8pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8); 20916 20917void __builtin_mma_pmxvi8ger4 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4); 20918void __builtin_mma_pmxvi8ger4pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4); 20919void __builtin_mma_pmxvi8ger4spp(__vector_quad *, vec_t, vec_t, uint4, uint4, uint4); 20920 20921void __builtin_mma_pmxvi16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 20922void __builtin_mma_pmxvi16ger2s (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 20923void __builtin_mma_pmxvf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 20924void __builtin_mma_pmxvbf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 20925 20926void __builtin_mma_pmxvi16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 20927void __builtin_mma_pmxvi16ger2spp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 20928void __builtin_mma_pmxvf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 20929void __builtin_mma_pmxvf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 20930void __builtin_mma_pmxvf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 20931void __builtin_mma_pmxvf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 20932void __builtin_mma_pmxvbf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 20933void __builtin_mma_pmxvbf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 20934void __builtin_mma_pmxvbf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 20935void __builtin_mma_pmxvbf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 20936 20937void __builtin_mma_pmxvf32ger (__vector_quad *, vec_t, vec_t, uint4, uint4); 20938void __builtin_mma_pmxvf32gerpp (__vector_quad *, vec_t, vec_t, uint4, uint4); 20939void __builtin_mma_pmxvf32gerpn (__vector_quad *, vec_t, vec_t, uint4, uint4); 20940void __builtin_mma_pmxvf32gernp (__vector_quad *, vec_t, vec_t, uint4, uint4); 20941void __builtin_mma_pmxvf32gernn (__vector_quad *, vec_t, vec_t, uint4, uint4); 20942 20943void __builtin_mma_xvf64ger (__vector_quad *, __vector_pair, vec_t); 20944void __builtin_mma_xvf64gerpp (__vector_quad *, __vector_pair, vec_t); 20945void __builtin_mma_xvf64gerpn (__vector_quad *, __vector_pair, vec_t); 20946void __builtin_mma_xvf64gernp (__vector_quad *, __vector_pair, vec_t); 20947void __builtin_mma_xvf64gernn (__vector_quad *, __vector_pair, vec_t); 20948 20949void __builtin_mma_pmxvf64ger (__vector_quad *, __vector_pair, vec_t, uint4, uint2); 20950void __builtin_mma_pmxvf64gerpp (__vector_quad *, __vector_pair, vec_t, uint4, uint2); 20951void __builtin_mma_pmxvf64gerpn (__vector_quad *, __vector_pair, vec_t, uint4, uint2); 20952void __builtin_mma_pmxvf64gernp (__vector_quad *, __vector_pair, vec_t, uint4, uint2); 20953void __builtin_mma_pmxvf64gernn (__vector_quad *, __vector_pair, vec_t, uint4, uint2); 20954 20955void __builtin_mma_xxmtacc (__vector_quad *); 20956void __builtin_mma_xxmfacc (__vector_quad *); 20957void __builtin_mma_xxsetaccz (__vector_quad *); 20958 20959void __builtin_mma_build_acc (__vector_quad *, vec_t, vec_t, vec_t, vec_t); 20960void __builtin_mma_disassemble_acc (void *, __vector_quad *); 20961 20962void __builtin_vsx_build_pair (__vector_pair *, vec_t, vec_t); 20963void __builtin_vsx_disassemble_pair (void *, __vector_pair *); 20964 20965vec_t __builtin_vsx_xvcvspbf16 (vec_t); 20966vec_t __builtin_vsx_xvcvbf16spn (vec_t); 20967 20968__vector_pair __builtin_vsx_lxvp (size_t, __vector_pair *); 20969void __builtin_vsx_stxvp (__vector_pair, size_t, __vector_pair *); 20970@end smallexample 20971 20972@node RISC-V Built-in Functions 20973@subsection RISC-V Built-in Functions 20974 20975These built-in functions are available for the RISC-V family of 20976processors. 20977 20978@deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void) 20979Returns the value that is currently set in the @samp{tp} register. 20980@end deftypefn 20981 20982@node RX Built-in Functions 20983@subsection RX Built-in Functions 20984GCC supports some of the RX instructions which cannot be expressed in 20985the C programming language via the use of built-in functions. The 20986following functions are supported: 20987 20988@deftypefn {Built-in Function} void __builtin_rx_brk (void) 20989Generates the @code{brk} machine instruction. 20990@end deftypefn 20991 20992@deftypefn {Built-in Function} void __builtin_rx_clrpsw (int) 20993Generates the @code{clrpsw} machine instruction to clear the specified 20994bit in the processor status word. 20995@end deftypefn 20996 20997@deftypefn {Built-in Function} void __builtin_rx_int (int) 20998Generates the @code{int} machine instruction to generate an interrupt 20999with the specified value. 21000@end deftypefn 21001 21002@deftypefn {Built-in Function} void __builtin_rx_machi (int, int) 21003Generates the @code{machi} machine instruction to add the result of 21004multiplying the top 16 bits of the two arguments into the 21005accumulator. 21006@end deftypefn 21007 21008@deftypefn {Built-in Function} void __builtin_rx_maclo (int, int) 21009Generates the @code{maclo} machine instruction to add the result of 21010multiplying the bottom 16 bits of the two arguments into the 21011accumulator. 21012@end deftypefn 21013 21014@deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int) 21015Generates the @code{mulhi} machine instruction to place the result of 21016multiplying the top 16 bits of the two arguments into the 21017accumulator. 21018@end deftypefn 21019 21020@deftypefn {Built-in Function} void __builtin_rx_mullo (int, int) 21021Generates the @code{mullo} machine instruction to place the result of 21022multiplying the bottom 16 bits of the two arguments into the 21023accumulator. 21024@end deftypefn 21025 21026@deftypefn {Built-in Function} int __builtin_rx_mvfachi (void) 21027Generates the @code{mvfachi} machine instruction to read the top 2102832 bits of the accumulator. 21029@end deftypefn 21030 21031@deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void) 21032Generates the @code{mvfacmi} machine instruction to read the middle 2103332 bits of the accumulator. 21034@end deftypefn 21035 21036@deftypefn {Built-in Function} int __builtin_rx_mvfc (int) 21037Generates the @code{mvfc} machine instruction which reads the control 21038register specified in its argument and returns its value. 21039@end deftypefn 21040 21041@deftypefn {Built-in Function} void __builtin_rx_mvtachi (int) 21042Generates the @code{mvtachi} machine instruction to set the top 2104332 bits of the accumulator. 21044@end deftypefn 21045 21046@deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int) 21047Generates the @code{mvtaclo} machine instruction to set the bottom 2104832 bits of the accumulator. 21049@end deftypefn 21050 21051@deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val) 21052Generates the @code{mvtc} machine instruction which sets control 21053register number @code{reg} to @code{val}. 21054@end deftypefn 21055 21056@deftypefn {Built-in Function} void __builtin_rx_mvtipl (int) 21057Generates the @code{mvtipl} machine instruction set the interrupt 21058priority level. 21059@end deftypefn 21060 21061@deftypefn {Built-in Function} void __builtin_rx_racw (int) 21062Generates the @code{racw} machine instruction to round the accumulator 21063according to the specified mode. 21064@end deftypefn 21065 21066@deftypefn {Built-in Function} int __builtin_rx_revw (int) 21067Generates the @code{revw} machine instruction which swaps the bytes in 21068the argument so that bits 0--7 now occupy bits 8--15 and vice versa, 21069and also bits 16--23 occupy bits 24--31 and vice versa. 21070@end deftypefn 21071 21072@deftypefn {Built-in Function} void __builtin_rx_rmpa (void) 21073Generates the @code{rmpa} machine instruction which initiates a 21074repeated multiply and accumulate sequence. 21075@end deftypefn 21076 21077@deftypefn {Built-in Function} void __builtin_rx_round (float) 21078Generates the @code{round} machine instruction which returns the 21079floating-point argument rounded according to the current rounding mode 21080set in the floating-point status word register. 21081@end deftypefn 21082 21083@deftypefn {Built-in Function} int __builtin_rx_sat (int) 21084Generates the @code{sat} machine instruction which returns the 21085saturated value of the argument. 21086@end deftypefn 21087 21088@deftypefn {Built-in Function} void __builtin_rx_setpsw (int) 21089Generates the @code{setpsw} machine instruction to set the specified 21090bit in the processor status word. 21091@end deftypefn 21092 21093@deftypefn {Built-in Function} void __builtin_rx_wait (void) 21094Generates the @code{wait} machine instruction. 21095@end deftypefn 21096 21097@node S/390 System z Built-in Functions 21098@subsection S/390 System z Built-in Functions 21099@deftypefn {Built-in Function} int __builtin_tbegin (void*) 21100Generates the @code{tbegin} machine instruction starting a 21101non-constrained hardware transaction. If the parameter is non-NULL the 21102memory area is used to store the transaction diagnostic buffer and 21103will be passed as first operand to @code{tbegin}. This buffer can be 21104defined using the @code{struct __htm_tdb} C struct defined in 21105@code{htmintrin.h} and must reside on a double-word boundary. The 21106second tbegin operand is set to @code{0xff0c}. This enables 21107save/restore of all GPRs and disables aborts for FPR and AR 21108manipulations inside the transaction body. The condition code set by 21109the tbegin instruction is returned as integer value. The tbegin 21110instruction by definition overwrites the content of all FPRs. The 21111compiler will generate code which saves and restores the FPRs. For 21112soft-float code it is recommended to used the @code{*_nofloat} 21113variant. In order to prevent a TDB from being written it is required 21114to pass a constant zero value as parameter. Passing a zero value 21115through a variable is not sufficient. Although modifications of 21116access registers inside the transaction will not trigger an 21117transaction abort it is not supported to actually modify them. Access 21118registers do not get saved when entering a transaction. They will have 21119undefined state when reaching the abort code. 21120@end deftypefn 21121 21122Macros for the possible return codes of tbegin are defined in the 21123@code{htmintrin.h} header file: 21124 21125@table @code 21126@item _HTM_TBEGIN_STARTED 21127@code{tbegin} has been executed as part of normal processing. The 21128transaction body is supposed to be executed. 21129@item _HTM_TBEGIN_INDETERMINATE 21130The transaction was aborted due to an indeterminate condition which 21131might be persistent. 21132@item _HTM_TBEGIN_TRANSIENT 21133The transaction aborted due to a transient failure. The transaction 21134should be re-executed in that case. 21135@item _HTM_TBEGIN_PERSISTENT 21136The transaction aborted due to a persistent failure. Re-execution 21137under same circumstances will not be productive. 21138@end table 21139 21140@defmac _HTM_FIRST_USER_ABORT_CODE 21141The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h} 21142specifies the first abort code which can be used for 21143@code{__builtin_tabort}. Values below this threshold are reserved for 21144machine use. 21145@end defmac 21146 21147@deftp {Data type} {struct __htm_tdb} 21148The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes 21149the structure of the transaction diagnostic block as specified in the 21150Principles of Operation manual chapter 5-91. 21151@end deftp 21152 21153@deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*) 21154Same as @code{__builtin_tbegin} but without FPR saves and restores. 21155Using this variant in code making use of FPRs will leave the FPRs in 21156undefined state when entering the transaction abort handler code. 21157@end deftypefn 21158 21159@deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int) 21160In addition to @code{__builtin_tbegin} a loop for transient failures 21161is generated. If tbegin returns a condition code of 2 the transaction 21162will be retried as often as specified in the second argument. The 21163perform processor assist instruction is used to tell the CPU about the 21164number of fails so far. 21165@end deftypefn 21166 21167@deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int) 21168Same as @code{__builtin_tbegin_retry} but without FPR saves and 21169restores. Using this variant in code making use of FPRs will leave 21170the FPRs in undefined state when entering the transaction abort 21171handler code. 21172@end deftypefn 21173 21174@deftypefn {Built-in Function} void __builtin_tbeginc (void) 21175Generates the @code{tbeginc} machine instruction starting a constrained 21176hardware transaction. The second operand is set to @code{0xff08}. 21177@end deftypefn 21178 21179@deftypefn {Built-in Function} int __builtin_tend (void) 21180Generates the @code{tend} machine instruction finishing a transaction 21181and making the changes visible to other threads. The condition code 21182generated by tend is returned as integer value. 21183@end deftypefn 21184 21185@deftypefn {Built-in Function} void __builtin_tabort (int) 21186Generates the @code{tabort} machine instruction with the specified 21187abort code. Abort codes from 0 through 255 are reserved and will 21188result in an error message. 21189@end deftypefn 21190 21191@deftypefn {Built-in Function} void __builtin_tx_assist (int) 21192Generates the @code{ppa rX,rY,1} machine instruction. Where the 21193integer parameter is loaded into rX and a value of zero is loaded into 21194rY. The integer parameter specifies the number of times the 21195transaction repeatedly aborted. 21196@end deftypefn 21197 21198@deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void) 21199Generates the @code{etnd} machine instruction. The current nesting 21200depth is returned as integer value. For a nesting depth of 0 the code 21201is not executed as part of an transaction. 21202@end deftypefn 21203 21204@deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t) 21205 21206Generates the @code{ntstg} machine instruction. The second argument 21207is written to the first arguments location. The store operation will 21208not be rolled-back in case of an transaction abort. 21209@end deftypefn 21210 21211@node SH Built-in Functions 21212@subsection SH Built-in Functions 21213The following built-in functions are supported on the SH1, SH2, SH3 and SH4 21214families of processors: 21215 21216@deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr}) 21217Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually 21218used by system code that manages threads and execution contexts. The compiler 21219normally does not generate code that modifies the contents of @samp{GBR} and 21220thus the value is preserved across function calls. Changing the @samp{GBR} 21221value in user code must be done with caution, since the compiler might use 21222@samp{GBR} in order to access thread local variables. 21223 21224@end deftypefn 21225 21226@deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void) 21227Returns the value that is currently set in the @samp{GBR} register. 21228Memory loads and stores that use the thread pointer as a base address are 21229turned into @samp{GBR} based displacement loads and stores, if possible. 21230For example: 21231@smallexample 21232struct my_tcb 21233@{ 21234 int a, b, c, d, e; 21235@}; 21236 21237int get_tcb_value (void) 21238@{ 21239 // Generate @samp{mov.l @@(8,gbr),r0} instruction 21240 return ((my_tcb*)__builtin_thread_pointer ())->c; 21241@} 21242 21243@end smallexample 21244@end deftypefn 21245 21246@deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void) 21247Returns the value that is currently set in the @samp{FPSCR} register. 21248@end deftypefn 21249 21250@deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val}) 21251Sets the @samp{FPSCR} register to the specified value @var{val}, while 21252preserving the current values of the FR, SZ and PR bits. 21253@end deftypefn 21254 21255@node SPARC VIS Built-in Functions 21256@subsection SPARC VIS Built-in Functions 21257 21258GCC supports SIMD operations on the SPARC using both the generic vector 21259extensions (@pxref{Vector Extensions}) as well as built-in functions for 21260the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} 21261switch, the VIS extension is exposed as the following built-in functions: 21262 21263@smallexample 21264typedef int v1si __attribute__ ((vector_size (4))); 21265typedef int v2si __attribute__ ((vector_size (8))); 21266typedef short v4hi __attribute__ ((vector_size (8))); 21267typedef short v2hi __attribute__ ((vector_size (4))); 21268typedef unsigned char v8qi __attribute__ ((vector_size (8))); 21269typedef unsigned char v4qi __attribute__ ((vector_size (4))); 21270 21271void __builtin_vis_write_gsr (int64_t); 21272int64_t __builtin_vis_read_gsr (void); 21273 21274void * __builtin_vis_alignaddr (void *, long); 21275void * __builtin_vis_alignaddrl (void *, long); 21276int64_t __builtin_vis_faligndatadi (int64_t, int64_t); 21277v2si __builtin_vis_faligndatav2si (v2si, v2si); 21278v4hi __builtin_vis_faligndatav4hi (v4si, v4si); 21279v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); 21280 21281v4hi __builtin_vis_fexpand (v4qi); 21282 21283v4hi __builtin_vis_fmul8x16 (v4qi, v4hi); 21284v4hi __builtin_vis_fmul8x16au (v4qi, v2hi); 21285v4hi __builtin_vis_fmul8x16al (v4qi, v2hi); 21286v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); 21287v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); 21288v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); 21289v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); 21290 21291v4qi __builtin_vis_fpack16 (v4hi); 21292v8qi __builtin_vis_fpack32 (v2si, v8qi); 21293v2hi __builtin_vis_fpackfix (v2si); 21294v8qi __builtin_vis_fpmerge (v4qi, v4qi); 21295 21296int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); 21297 21298long __builtin_vis_edge8 (void *, void *); 21299long __builtin_vis_edge8l (void *, void *); 21300long __builtin_vis_edge16 (void *, void *); 21301long __builtin_vis_edge16l (void *, void *); 21302long __builtin_vis_edge32 (void *, void *); 21303long __builtin_vis_edge32l (void *, void *); 21304 21305long __builtin_vis_fcmple16 (v4hi, v4hi); 21306long __builtin_vis_fcmple32 (v2si, v2si); 21307long __builtin_vis_fcmpne16 (v4hi, v4hi); 21308long __builtin_vis_fcmpne32 (v2si, v2si); 21309long __builtin_vis_fcmpgt16 (v4hi, v4hi); 21310long __builtin_vis_fcmpgt32 (v2si, v2si); 21311long __builtin_vis_fcmpeq16 (v4hi, v4hi); 21312long __builtin_vis_fcmpeq32 (v2si, v2si); 21313 21314v4hi __builtin_vis_fpadd16 (v4hi, v4hi); 21315v2hi __builtin_vis_fpadd16s (v2hi, v2hi); 21316v2si __builtin_vis_fpadd32 (v2si, v2si); 21317v1si __builtin_vis_fpadd32s (v1si, v1si); 21318v4hi __builtin_vis_fpsub16 (v4hi, v4hi); 21319v2hi __builtin_vis_fpsub16s (v2hi, v2hi); 21320v2si __builtin_vis_fpsub32 (v2si, v2si); 21321v1si __builtin_vis_fpsub32s (v1si, v1si); 21322 21323long __builtin_vis_array8 (long, long); 21324long __builtin_vis_array16 (long, long); 21325long __builtin_vis_array32 (long, long); 21326@end smallexample 21327 21328When you use the @option{-mvis2} switch, the VIS version 2.0 built-in 21329functions also become available: 21330 21331@smallexample 21332long __builtin_vis_bmask (long, long); 21333int64_t __builtin_vis_bshuffledi (int64_t, int64_t); 21334v2si __builtin_vis_bshufflev2si (v2si, v2si); 21335v4hi __builtin_vis_bshufflev2si (v4hi, v4hi); 21336v8qi __builtin_vis_bshufflev2si (v8qi, v8qi); 21337 21338long __builtin_vis_edge8n (void *, void *); 21339long __builtin_vis_edge8ln (void *, void *); 21340long __builtin_vis_edge16n (void *, void *); 21341long __builtin_vis_edge16ln (void *, void *); 21342long __builtin_vis_edge32n (void *, void *); 21343long __builtin_vis_edge32ln (void *, void *); 21344@end smallexample 21345 21346When you use the @option{-mvis3} switch, the VIS version 3.0 built-in 21347functions also become available: 21348 21349@smallexample 21350void __builtin_vis_cmask8 (long); 21351void __builtin_vis_cmask16 (long); 21352void __builtin_vis_cmask32 (long); 21353 21354v4hi __builtin_vis_fchksm16 (v4hi, v4hi); 21355 21356v4hi __builtin_vis_fsll16 (v4hi, v4hi); 21357v4hi __builtin_vis_fslas16 (v4hi, v4hi); 21358v4hi __builtin_vis_fsrl16 (v4hi, v4hi); 21359v4hi __builtin_vis_fsra16 (v4hi, v4hi); 21360v2si __builtin_vis_fsll16 (v2si, v2si); 21361v2si __builtin_vis_fslas16 (v2si, v2si); 21362v2si __builtin_vis_fsrl16 (v2si, v2si); 21363v2si __builtin_vis_fsra16 (v2si, v2si); 21364 21365long __builtin_vis_pdistn (v8qi, v8qi); 21366 21367v4hi __builtin_vis_fmean16 (v4hi, v4hi); 21368 21369int64_t __builtin_vis_fpadd64 (int64_t, int64_t); 21370int64_t __builtin_vis_fpsub64 (int64_t, int64_t); 21371 21372v4hi __builtin_vis_fpadds16 (v4hi, v4hi); 21373v2hi __builtin_vis_fpadds16s (v2hi, v2hi); 21374v4hi __builtin_vis_fpsubs16 (v4hi, v4hi); 21375v2hi __builtin_vis_fpsubs16s (v2hi, v2hi); 21376v2si __builtin_vis_fpadds32 (v2si, v2si); 21377v1si __builtin_vis_fpadds32s (v1si, v1si); 21378v2si __builtin_vis_fpsubs32 (v2si, v2si); 21379v1si __builtin_vis_fpsubs32s (v1si, v1si); 21380 21381long __builtin_vis_fucmple8 (v8qi, v8qi); 21382long __builtin_vis_fucmpne8 (v8qi, v8qi); 21383long __builtin_vis_fucmpgt8 (v8qi, v8qi); 21384long __builtin_vis_fucmpeq8 (v8qi, v8qi); 21385 21386float __builtin_vis_fhadds (float, float); 21387double __builtin_vis_fhaddd (double, double); 21388float __builtin_vis_fhsubs (float, float); 21389double __builtin_vis_fhsubd (double, double); 21390float __builtin_vis_fnhadds (float, float); 21391double __builtin_vis_fnhaddd (double, double); 21392 21393int64_t __builtin_vis_umulxhi (int64_t, int64_t); 21394int64_t __builtin_vis_xmulx (int64_t, int64_t); 21395int64_t __builtin_vis_xmulxhi (int64_t, int64_t); 21396@end smallexample 21397 21398When you use the @option{-mvis4} switch, the VIS version 4.0 built-in 21399functions also become available: 21400 21401@smallexample 21402v8qi __builtin_vis_fpadd8 (v8qi, v8qi); 21403v8qi __builtin_vis_fpadds8 (v8qi, v8qi); 21404v8qi __builtin_vis_fpaddus8 (v8qi, v8qi); 21405v4hi __builtin_vis_fpaddus16 (v4hi, v4hi); 21406 21407v8qi __builtin_vis_fpsub8 (v8qi, v8qi); 21408v8qi __builtin_vis_fpsubs8 (v8qi, v8qi); 21409v8qi __builtin_vis_fpsubus8 (v8qi, v8qi); 21410v4hi __builtin_vis_fpsubus16 (v4hi, v4hi); 21411 21412long __builtin_vis_fpcmple8 (v8qi, v8qi); 21413long __builtin_vis_fpcmpgt8 (v8qi, v8qi); 21414long __builtin_vis_fpcmpule16 (v4hi, v4hi); 21415long __builtin_vis_fpcmpugt16 (v4hi, v4hi); 21416long __builtin_vis_fpcmpule32 (v2si, v2si); 21417long __builtin_vis_fpcmpugt32 (v2si, v2si); 21418 21419v8qi __builtin_vis_fpmax8 (v8qi, v8qi); 21420v4hi __builtin_vis_fpmax16 (v4hi, v4hi); 21421v2si __builtin_vis_fpmax32 (v2si, v2si); 21422 21423v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi); 21424v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi); 21425v2si __builtin_vis_fpmaxu32 (v2si, v2si); 21426 21427 21428v8qi __builtin_vis_fpmin8 (v8qi, v8qi); 21429v4hi __builtin_vis_fpmin16 (v4hi, v4hi); 21430v2si __builtin_vis_fpmin32 (v2si, v2si); 21431 21432v8qi __builtin_vis_fpminu8 (v8qi, v8qi); 21433v4hi __builtin_vis_fpminu16 (v4hi, v4hi); 21434v2si __builtin_vis_fpminu32 (v2si, v2si); 21435@end smallexample 21436 21437When you use the @option{-mvis4b} switch, the VIS version 4.0B 21438built-in functions also become available: 21439 21440@smallexample 21441v8qi __builtin_vis_dictunpack8 (double, int); 21442v4hi __builtin_vis_dictunpack16 (double, int); 21443v2si __builtin_vis_dictunpack32 (double, int); 21444 21445long __builtin_vis_fpcmple8shl (v8qi, v8qi, int); 21446long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int); 21447long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int); 21448long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int); 21449 21450long __builtin_vis_fpcmple16shl (v4hi, v4hi, int); 21451long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int); 21452long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int); 21453long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int); 21454 21455long __builtin_vis_fpcmple32shl (v2si, v2si, int); 21456long __builtin_vis_fpcmpgt32shl (v2si, v2si, int); 21457long __builtin_vis_fpcmpeq32shl (v2si, v2si, int); 21458long __builtin_vis_fpcmpne32shl (v2si, v2si, int); 21459 21460long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int); 21461long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int); 21462long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int); 21463long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int); 21464long __builtin_vis_fpcmpule32shl (v2si, v2si, int); 21465long __builtin_vis_fpcmpugt32shl (v2si, v2si, int); 21466 21467long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int); 21468long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int); 21469long __builtin_vis_fpcmpde32shl (v2si, v2si, int); 21470 21471long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int); 21472long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int); 21473long __builtin_vis_fpcmpur32shl (v2si, v2si, int); 21474@end smallexample 21475 21476@node TI C6X Built-in Functions 21477@subsection TI C6X Built-in Functions 21478 21479GCC provides intrinsics to access certain instructions of the TI C6X 21480processors. These intrinsics, listed below, are available after 21481inclusion of the @code{c6x_intrinsics.h} header file. They map directly 21482to C6X instructions. 21483 21484@smallexample 21485 21486int _sadd (int, int) 21487int _ssub (int, int) 21488int _sadd2 (int, int) 21489int _ssub2 (int, int) 21490long long _mpy2 (int, int) 21491long long _smpy2 (int, int) 21492int _add4 (int, int) 21493int _sub4 (int, int) 21494int _saddu4 (int, int) 21495 21496int _smpy (int, int) 21497int _smpyh (int, int) 21498int _smpyhl (int, int) 21499int _smpylh (int, int) 21500 21501int _sshl (int, int) 21502int _subc (int, int) 21503 21504int _avg2 (int, int) 21505int _avgu4 (int, int) 21506 21507int _clrr (int, int) 21508int _extr (int, int) 21509int _extru (int, int) 21510int _abs (int) 21511int _abs2 (int) 21512 21513@end smallexample 21514 21515@node TILE-Gx Built-in Functions 21516@subsection TILE-Gx Built-in Functions 21517 21518GCC provides intrinsics to access every instruction of the TILE-Gx 21519processor. The intrinsics are of the form: 21520 21521@smallexample 21522 21523unsigned long long __insn_@var{op} (...) 21524 21525@end smallexample 21526 21527Where @var{op} is the name of the instruction. Refer to the ISA manual 21528for the complete list of instructions. 21529 21530GCC also provides intrinsics to directly access the network registers. 21531The intrinsics are: 21532 21533@smallexample 21534 21535unsigned long long __tile_idn0_receive (void) 21536unsigned long long __tile_idn1_receive (void) 21537unsigned long long __tile_udn0_receive (void) 21538unsigned long long __tile_udn1_receive (void) 21539unsigned long long __tile_udn2_receive (void) 21540unsigned long long __tile_udn3_receive (void) 21541void __tile_idn_send (unsigned long long) 21542void __tile_udn_send (unsigned long long) 21543 21544@end smallexample 21545 21546The intrinsic @code{void __tile_network_barrier (void)} is used to 21547guarantee that no network operations before it are reordered with 21548those after it. 21549 21550@node TILEPro Built-in Functions 21551@subsection TILEPro Built-in Functions 21552 21553GCC provides intrinsics to access every instruction of the TILEPro 21554processor. The intrinsics are of the form: 21555 21556@smallexample 21557 21558unsigned __insn_@var{op} (...) 21559 21560@end smallexample 21561 21562@noindent 21563where @var{op} is the name of the instruction. Refer to the ISA manual 21564for the complete list of instructions. 21565 21566GCC also provides intrinsics to directly access the network registers. 21567The intrinsics are: 21568 21569@smallexample 21570 21571unsigned __tile_idn0_receive (void) 21572unsigned __tile_idn1_receive (void) 21573unsigned __tile_sn_receive (void) 21574unsigned __tile_udn0_receive (void) 21575unsigned __tile_udn1_receive (void) 21576unsigned __tile_udn2_receive (void) 21577unsigned __tile_udn3_receive (void) 21578void __tile_idn_send (unsigned) 21579void __tile_sn_send (unsigned) 21580void __tile_udn_send (unsigned) 21581 21582@end smallexample 21583 21584The intrinsic @code{void __tile_network_barrier (void)} is used to 21585guarantee that no network operations before it are reordered with 21586those after it. 21587 21588@node x86 Built-in Functions 21589@subsection x86 Built-in Functions 21590 21591These built-in functions are available for the x86-32 and x86-64 family 21592of computers, depending on the command-line switches used. 21593 21594If you specify command-line switches such as @option{-msse}, 21595the compiler could use the extended instruction sets even if the built-ins 21596are not used explicitly in the program. For this reason, applications 21597that perform run-time CPU detection must compile separate files for each 21598supported architecture, using the appropriate flags. In particular, 21599the file containing the CPU detection code should be compiled without 21600these options. 21601 21602The following machine modes are available for use with MMX built-in functions 21603(@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers, 21604@code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a 21605vector of eight 8-bit integers. Some of the built-in functions operate on 21606MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode. 21607 21608If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector 21609of two 32-bit floating-point values. 21610 21611If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit 21612floating-point values. Some instructions use a vector of four 32-bit 21613integers, these use @code{V4SI}. Finally, some instructions operate on an 21614entire vector register, interpreting it as a 128-bit integer, these use mode 21615@code{TI}. 21616 21617The x86-32 and x86-64 family of processors use additional built-in 21618functions for efficient use of @code{TF} (@code{__float128}) 128-bit 21619floating point and @code{TC} 128-bit complex floating-point values. 21620 21621The following floating-point built-in functions are always available. All 21622of them implement the function that is part of the name. 21623 21624@smallexample 21625__float128 __builtin_fabsq (__float128) 21626__float128 __builtin_copysignq (__float128, __float128) 21627@end smallexample 21628 21629The following built-in functions are always available. 21630 21631@table @code 21632@item __float128 __builtin_infq (void) 21633Similar to @code{__builtin_inf}, except the return type is @code{__float128}. 21634@findex __builtin_infq 21635 21636@item __float128 __builtin_huge_valq (void) 21637Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}. 21638@findex __builtin_huge_valq 21639 21640@item __float128 __builtin_nanq (void) 21641Similar to @code{__builtin_nan}, except the return type is @code{__float128}. 21642@findex __builtin_nanq 21643 21644@item __float128 __builtin_nansq (void) 21645Similar to @code{__builtin_nans}, except the return type is @code{__float128}. 21646@findex __builtin_nansq 21647@end table 21648 21649The following built-in function is always available. 21650 21651@table @code 21652@item void __builtin_ia32_pause (void) 21653Generates the @code{pause} machine instruction with a compiler memory 21654barrier. 21655@end table 21656 21657The following built-in functions are always available and can be used to 21658check the target platform type. 21659 21660@deftypefn {Built-in Function} void __builtin_cpu_init (void) 21661This function runs the CPU detection code to check the type of CPU and the 21662features supported. This built-in function needs to be invoked along with the built-in functions 21663to check CPU type and features, @code{__builtin_cpu_is} and 21664@code{__builtin_cpu_supports}, only when used in a function that is 21665executed before any constructors are called. The CPU detection code is 21666automatically executed in a very high priority constructor. 21667 21668For example, this function has to be used in @code{ifunc} resolvers that 21669check for CPU type using the built-in functions @code{__builtin_cpu_is} 21670and @code{__builtin_cpu_supports}, or in constructors on targets that 21671don't support constructor priority. 21672@smallexample 21673 21674static void (*resolve_memcpy (void)) (void) 21675@{ 21676 // ifunc resolvers fire before constructors, explicitly call the init 21677 // function. 21678 __builtin_cpu_init (); 21679 if (__builtin_cpu_supports ("ssse3")) 21680 return ssse3_memcpy; // super fast memcpy with ssse3 instructions. 21681 else 21682 return default_memcpy; 21683@} 21684 21685void *memcpy (void *, const void *, size_t) 21686 __attribute__ ((ifunc ("resolve_memcpy"))); 21687@end smallexample 21688 21689@end deftypefn 21690 21691@deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname}) 21692This function returns a positive integer if the run-time CPU 21693is of type @var{cpuname} 21694and returns @code{0} otherwise. The following CPU names can be detected: 21695 21696@table @samp 21697@item amd 21698AMD CPU. 21699 21700@item intel 21701Intel CPU. 21702 21703@item atom 21704Intel Atom CPU. 21705 21706@item slm 21707Intel Silvermont CPU. 21708 21709@item core2 21710Intel Core 2 CPU. 21711 21712@item corei7 21713Intel Core i7 CPU. 21714 21715@item nehalem 21716Intel Core i7 Nehalem CPU. 21717 21718@item westmere 21719Intel Core i7 Westmere CPU. 21720 21721@item sandybridge 21722Intel Core i7 Sandy Bridge CPU. 21723 21724@item ivybridge 21725Intel Core i7 Ivy Bridge CPU. 21726 21727@item haswell 21728Intel Core i7 Haswell CPU. 21729 21730@item broadwell 21731Intel Core i7 Broadwell CPU. 21732 21733@item skylake 21734Intel Core i7 Skylake CPU. 21735 21736@item skylake-avx512 21737Intel Core i7 Skylake AVX512 CPU. 21738 21739@item cannonlake 21740Intel Core i7 Cannon Lake CPU. 21741 21742@item icelake-client 21743Intel Core i7 Ice Lake Client CPU. 21744 21745@item icelake-server 21746Intel Core i7 Ice Lake Server CPU. 21747 21748@item cascadelake 21749Intel Core i7 Cascadelake CPU. 21750 21751@item tigerlake 21752Intel Core i7 Tigerlake CPU. 21753 21754@item cooperlake 21755Intel Core i7 Cooperlake CPU. 21756 21757@item bonnell 21758Intel Atom Bonnell CPU. 21759 21760@item silvermont 21761Intel Atom Silvermont CPU. 21762 21763@item goldmont 21764Intel Atom Goldmont CPU. 21765 21766@item goldmont-plus 21767Intel Atom Goldmont Plus CPU. 21768 21769@item tremont 21770Intel Atom Tremont CPU. 21771 21772@item knl 21773Intel Knights Landing CPU. 21774 21775@item knm 21776Intel Knights Mill CPU. 21777 21778@item amdfam10h 21779AMD Family 10h CPU. 21780 21781@item barcelona 21782AMD Family 10h Barcelona CPU. 21783 21784@item shanghai 21785AMD Family 10h Shanghai CPU. 21786 21787@item istanbul 21788AMD Family 10h Istanbul CPU. 21789 21790@item btver1 21791AMD Family 14h CPU. 21792 21793@item amdfam15h 21794AMD Family 15h CPU. 21795 21796@item bdver1 21797AMD Family 15h Bulldozer version 1. 21798 21799@item bdver2 21800AMD Family 15h Bulldozer version 2. 21801 21802@item bdver3 21803AMD Family 15h Bulldozer version 3. 21804 21805@item bdver4 21806AMD Family 15h Bulldozer version 4. 21807 21808@item btver2 21809AMD Family 16h CPU. 21810 21811@item amdfam17h 21812AMD Family 17h CPU. 21813 21814@item znver1 21815AMD Family 17h Zen version 1. 21816 21817@item znver2 21818AMD Family 17h Zen version 2. 21819 21820@item amdfam19h 21821AMD Family 19h CPU. 21822 21823@item znver3 21824AMD Family 19h Zen version 3. 21825@end table 21826 21827Here is an example: 21828@smallexample 21829if (__builtin_cpu_is ("corei7")) 21830 @{ 21831 do_corei7 (); // Core i7 specific implementation. 21832 @} 21833else 21834 @{ 21835 do_generic (); // Generic implementation. 21836 @} 21837@end smallexample 21838@end deftypefn 21839 21840@deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature}) 21841This function returns a positive integer if the run-time CPU 21842supports @var{feature} 21843and returns @code{0} otherwise. The following features can be detected: 21844 21845@table @samp 21846@item cmov 21847CMOV instruction. 21848@item mmx 21849MMX instructions. 21850@item popcnt 21851POPCNT instruction. 21852@item sse 21853SSE instructions. 21854@item sse2 21855SSE2 instructions. 21856@item sse3 21857SSE3 instructions. 21858@item ssse3 21859SSSE3 instructions. 21860@item sse4.1 21861SSE4.1 instructions. 21862@item sse4.2 21863SSE4.2 instructions. 21864@item avx 21865AVX instructions. 21866@item avx2 21867AVX2 instructions. 21868@item sse4a 21869SSE4A instructions. 21870@item fma4 21871FMA4 instructions. 21872@item xop 21873XOP instructions. 21874@item fma 21875FMA instructions. 21876@item avx512f 21877AVX512F instructions. 21878@item bmi 21879BMI instructions. 21880@item bmi2 21881BMI2 instructions. 21882@item aes 21883AES instructions. 21884@item pclmul 21885PCLMUL instructions. 21886@item avx512vl 21887AVX512VL instructions. 21888@item avx512bw 21889AVX512BW instructions. 21890@item avx512dq 21891AVX512DQ instructions. 21892@item avx512cd 21893AVX512CD instructions. 21894@item avx512er 21895AVX512ER instructions. 21896@item avx512pf 21897AVX512PF instructions. 21898@item avx512vbmi 21899AVX512VBMI instructions. 21900@item avx512ifma 21901AVX512IFMA instructions. 21902@item avx5124vnniw 21903AVX5124VNNIW instructions. 21904@item avx5124fmaps 21905AVX5124FMAPS instructions. 21906@item avx512vpopcntdq 21907AVX512VPOPCNTDQ instructions. 21908@item avx512vbmi2 21909AVX512VBMI2 instructions. 21910@item gfni 21911GFNI instructions. 21912@item vpclmulqdq 21913VPCLMULQDQ instructions. 21914@item avx512vnni 21915AVX512VNNI instructions. 21916@item avx512bitalg 21917AVX512BITALG instructions. 21918@end table 21919 21920Here is an example: 21921@smallexample 21922if (__builtin_cpu_supports ("popcnt")) 21923 @{ 21924 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc"); 21925 @} 21926else 21927 @{ 21928 count = generic_countbits (n); //generic implementation. 21929 @} 21930@end smallexample 21931@end deftypefn 21932 21933 21934The following built-in functions are made available by @option{-mmmx}. 21935All of them generate the machine instruction that is part of the name. 21936 21937@smallexample 21938v8qi __builtin_ia32_paddb (v8qi, v8qi) 21939v4hi __builtin_ia32_paddw (v4hi, v4hi) 21940v2si __builtin_ia32_paddd (v2si, v2si) 21941v8qi __builtin_ia32_psubb (v8qi, v8qi) 21942v4hi __builtin_ia32_psubw (v4hi, v4hi) 21943v2si __builtin_ia32_psubd (v2si, v2si) 21944v8qi __builtin_ia32_paddsb (v8qi, v8qi) 21945v4hi __builtin_ia32_paddsw (v4hi, v4hi) 21946v8qi __builtin_ia32_psubsb (v8qi, v8qi) 21947v4hi __builtin_ia32_psubsw (v4hi, v4hi) 21948v8qi __builtin_ia32_paddusb (v8qi, v8qi) 21949v4hi __builtin_ia32_paddusw (v4hi, v4hi) 21950v8qi __builtin_ia32_psubusb (v8qi, v8qi) 21951v4hi __builtin_ia32_psubusw (v4hi, v4hi) 21952v4hi __builtin_ia32_pmullw (v4hi, v4hi) 21953v4hi __builtin_ia32_pmulhw (v4hi, v4hi) 21954di __builtin_ia32_pand (di, di) 21955di __builtin_ia32_pandn (di,di) 21956di __builtin_ia32_por (di, di) 21957di __builtin_ia32_pxor (di, di) 21958v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi) 21959v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi) 21960v2si __builtin_ia32_pcmpeqd (v2si, v2si) 21961v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi) 21962v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi) 21963v2si __builtin_ia32_pcmpgtd (v2si, v2si) 21964v8qi __builtin_ia32_punpckhbw (v8qi, v8qi) 21965v4hi __builtin_ia32_punpckhwd (v4hi, v4hi) 21966v2si __builtin_ia32_punpckhdq (v2si, v2si) 21967v8qi __builtin_ia32_punpcklbw (v8qi, v8qi) 21968v4hi __builtin_ia32_punpcklwd (v4hi, v4hi) 21969v2si __builtin_ia32_punpckldq (v2si, v2si) 21970v8qi __builtin_ia32_packsswb (v4hi, v4hi) 21971v4hi __builtin_ia32_packssdw (v2si, v2si) 21972v8qi __builtin_ia32_packuswb (v4hi, v4hi) 21973 21974v4hi __builtin_ia32_psllw (v4hi, v4hi) 21975v2si __builtin_ia32_pslld (v2si, v2si) 21976v1di __builtin_ia32_psllq (v1di, v1di) 21977v4hi __builtin_ia32_psrlw (v4hi, v4hi) 21978v2si __builtin_ia32_psrld (v2si, v2si) 21979v1di __builtin_ia32_psrlq (v1di, v1di) 21980v4hi __builtin_ia32_psraw (v4hi, v4hi) 21981v2si __builtin_ia32_psrad (v2si, v2si) 21982v4hi __builtin_ia32_psllwi (v4hi, int) 21983v2si __builtin_ia32_pslldi (v2si, int) 21984v1di __builtin_ia32_psllqi (v1di, int) 21985v4hi __builtin_ia32_psrlwi (v4hi, int) 21986v2si __builtin_ia32_psrldi (v2si, int) 21987v1di __builtin_ia32_psrlqi (v1di, int) 21988v4hi __builtin_ia32_psrawi (v4hi, int) 21989v2si __builtin_ia32_psradi (v2si, int) 21990 21991@end smallexample 21992 21993The following built-in functions are made available either with 21994@option{-msse}, or with @option{-m3dnowa}. All of them generate 21995the machine instruction that is part of the name. 21996 21997@smallexample 21998v4hi __builtin_ia32_pmulhuw (v4hi, v4hi) 21999v8qi __builtin_ia32_pavgb (v8qi, v8qi) 22000v4hi __builtin_ia32_pavgw (v4hi, v4hi) 22001v1di __builtin_ia32_psadbw (v8qi, v8qi) 22002v8qi __builtin_ia32_pmaxub (v8qi, v8qi) 22003v4hi __builtin_ia32_pmaxsw (v4hi, v4hi) 22004v8qi __builtin_ia32_pminub (v8qi, v8qi) 22005v4hi __builtin_ia32_pminsw (v4hi, v4hi) 22006int __builtin_ia32_pmovmskb (v8qi) 22007void __builtin_ia32_maskmovq (v8qi, v8qi, char *) 22008void __builtin_ia32_movntq (di *, di) 22009void __builtin_ia32_sfence (void) 22010@end smallexample 22011 22012The following built-in functions are available when @option{-msse} is used. 22013All of them generate the machine instruction that is part of the name. 22014 22015@smallexample 22016int __builtin_ia32_comieq (v4sf, v4sf) 22017int __builtin_ia32_comineq (v4sf, v4sf) 22018int __builtin_ia32_comilt (v4sf, v4sf) 22019int __builtin_ia32_comile (v4sf, v4sf) 22020int __builtin_ia32_comigt (v4sf, v4sf) 22021int __builtin_ia32_comige (v4sf, v4sf) 22022int __builtin_ia32_ucomieq (v4sf, v4sf) 22023int __builtin_ia32_ucomineq (v4sf, v4sf) 22024int __builtin_ia32_ucomilt (v4sf, v4sf) 22025int __builtin_ia32_ucomile (v4sf, v4sf) 22026int __builtin_ia32_ucomigt (v4sf, v4sf) 22027int __builtin_ia32_ucomige (v4sf, v4sf) 22028v4sf __builtin_ia32_addps (v4sf, v4sf) 22029v4sf __builtin_ia32_subps (v4sf, v4sf) 22030v4sf __builtin_ia32_mulps (v4sf, v4sf) 22031v4sf __builtin_ia32_divps (v4sf, v4sf) 22032v4sf __builtin_ia32_addss (v4sf, v4sf) 22033v4sf __builtin_ia32_subss (v4sf, v4sf) 22034v4sf __builtin_ia32_mulss (v4sf, v4sf) 22035v4sf __builtin_ia32_divss (v4sf, v4sf) 22036v4sf __builtin_ia32_cmpeqps (v4sf, v4sf) 22037v4sf __builtin_ia32_cmpltps (v4sf, v4sf) 22038v4sf __builtin_ia32_cmpleps (v4sf, v4sf) 22039v4sf __builtin_ia32_cmpgtps (v4sf, v4sf) 22040v4sf __builtin_ia32_cmpgeps (v4sf, v4sf) 22041v4sf __builtin_ia32_cmpunordps (v4sf, v4sf) 22042v4sf __builtin_ia32_cmpneqps (v4sf, v4sf) 22043v4sf __builtin_ia32_cmpnltps (v4sf, v4sf) 22044v4sf __builtin_ia32_cmpnleps (v4sf, v4sf) 22045v4sf __builtin_ia32_cmpngtps (v4sf, v4sf) 22046v4sf __builtin_ia32_cmpngeps (v4sf, v4sf) 22047v4sf __builtin_ia32_cmpordps (v4sf, v4sf) 22048v4sf __builtin_ia32_cmpeqss (v4sf, v4sf) 22049v4sf __builtin_ia32_cmpltss (v4sf, v4sf) 22050v4sf __builtin_ia32_cmpless (v4sf, v4sf) 22051v4sf __builtin_ia32_cmpunordss (v4sf, v4sf) 22052v4sf __builtin_ia32_cmpneqss (v4sf, v4sf) 22053v4sf __builtin_ia32_cmpnltss (v4sf, v4sf) 22054v4sf __builtin_ia32_cmpnless (v4sf, v4sf) 22055v4sf __builtin_ia32_cmpordss (v4sf, v4sf) 22056v4sf __builtin_ia32_maxps (v4sf, v4sf) 22057v4sf __builtin_ia32_maxss (v4sf, v4sf) 22058v4sf __builtin_ia32_minps (v4sf, v4sf) 22059v4sf __builtin_ia32_minss (v4sf, v4sf) 22060v4sf __builtin_ia32_andps (v4sf, v4sf) 22061v4sf __builtin_ia32_andnps (v4sf, v4sf) 22062v4sf __builtin_ia32_orps (v4sf, v4sf) 22063v4sf __builtin_ia32_xorps (v4sf, v4sf) 22064v4sf __builtin_ia32_movss (v4sf, v4sf) 22065v4sf __builtin_ia32_movhlps (v4sf, v4sf) 22066v4sf __builtin_ia32_movlhps (v4sf, v4sf) 22067v4sf __builtin_ia32_unpckhps (v4sf, v4sf) 22068v4sf __builtin_ia32_unpcklps (v4sf, v4sf) 22069v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si) 22070v4sf __builtin_ia32_cvtsi2ss (v4sf, int) 22071v2si __builtin_ia32_cvtps2pi (v4sf) 22072int __builtin_ia32_cvtss2si (v4sf) 22073v2si __builtin_ia32_cvttps2pi (v4sf) 22074int __builtin_ia32_cvttss2si (v4sf) 22075v4sf __builtin_ia32_rcpps (v4sf) 22076v4sf __builtin_ia32_rsqrtps (v4sf) 22077v4sf __builtin_ia32_sqrtps (v4sf) 22078v4sf __builtin_ia32_rcpss (v4sf) 22079v4sf __builtin_ia32_rsqrtss (v4sf) 22080v4sf __builtin_ia32_sqrtss (v4sf) 22081v4sf __builtin_ia32_shufps (v4sf, v4sf, int) 22082void __builtin_ia32_movntps (float *, v4sf) 22083int __builtin_ia32_movmskps (v4sf) 22084@end smallexample 22085 22086The following built-in functions are available when @option{-msse} is used. 22087 22088@table @code 22089@item v4sf __builtin_ia32_loadups (float *) 22090Generates the @code{movups} machine instruction as a load from memory. 22091@item void __builtin_ia32_storeups (float *, v4sf) 22092Generates the @code{movups} machine instruction as a store to memory. 22093@item v4sf __builtin_ia32_loadss (float *) 22094Generates the @code{movss} machine instruction as a load from memory. 22095@item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *) 22096Generates the @code{movhps} machine instruction as a load from memory. 22097@item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *) 22098Generates the @code{movlps} machine instruction as a load from memory 22099@item void __builtin_ia32_storehps (v2sf *, v4sf) 22100Generates the @code{movhps} machine instruction as a store to memory. 22101@item void __builtin_ia32_storelps (v2sf *, v4sf) 22102Generates the @code{movlps} machine instruction as a store to memory. 22103@end table 22104 22105The following built-in functions are available when @option{-msse2} is used. 22106All of them generate the machine instruction that is part of the name. 22107 22108@smallexample 22109int __builtin_ia32_comisdeq (v2df, v2df) 22110int __builtin_ia32_comisdlt (v2df, v2df) 22111int __builtin_ia32_comisdle (v2df, v2df) 22112int __builtin_ia32_comisdgt (v2df, v2df) 22113int __builtin_ia32_comisdge (v2df, v2df) 22114int __builtin_ia32_comisdneq (v2df, v2df) 22115int __builtin_ia32_ucomisdeq (v2df, v2df) 22116int __builtin_ia32_ucomisdlt (v2df, v2df) 22117int __builtin_ia32_ucomisdle (v2df, v2df) 22118int __builtin_ia32_ucomisdgt (v2df, v2df) 22119int __builtin_ia32_ucomisdge (v2df, v2df) 22120int __builtin_ia32_ucomisdneq (v2df, v2df) 22121v2df __builtin_ia32_cmpeqpd (v2df, v2df) 22122v2df __builtin_ia32_cmpltpd (v2df, v2df) 22123v2df __builtin_ia32_cmplepd (v2df, v2df) 22124v2df __builtin_ia32_cmpgtpd (v2df, v2df) 22125v2df __builtin_ia32_cmpgepd (v2df, v2df) 22126v2df __builtin_ia32_cmpunordpd (v2df, v2df) 22127v2df __builtin_ia32_cmpneqpd (v2df, v2df) 22128v2df __builtin_ia32_cmpnltpd (v2df, v2df) 22129v2df __builtin_ia32_cmpnlepd (v2df, v2df) 22130v2df __builtin_ia32_cmpngtpd (v2df, v2df) 22131v2df __builtin_ia32_cmpngepd (v2df, v2df) 22132v2df __builtin_ia32_cmpordpd (v2df, v2df) 22133v2df __builtin_ia32_cmpeqsd (v2df, v2df) 22134v2df __builtin_ia32_cmpltsd (v2df, v2df) 22135v2df __builtin_ia32_cmplesd (v2df, v2df) 22136v2df __builtin_ia32_cmpunordsd (v2df, v2df) 22137v2df __builtin_ia32_cmpneqsd (v2df, v2df) 22138v2df __builtin_ia32_cmpnltsd (v2df, v2df) 22139v2df __builtin_ia32_cmpnlesd (v2df, v2df) 22140v2df __builtin_ia32_cmpordsd (v2df, v2df) 22141v2di __builtin_ia32_paddq (v2di, v2di) 22142v2di __builtin_ia32_psubq (v2di, v2di) 22143v2df __builtin_ia32_addpd (v2df, v2df) 22144v2df __builtin_ia32_subpd (v2df, v2df) 22145v2df __builtin_ia32_mulpd (v2df, v2df) 22146v2df __builtin_ia32_divpd (v2df, v2df) 22147v2df __builtin_ia32_addsd (v2df, v2df) 22148v2df __builtin_ia32_subsd (v2df, v2df) 22149v2df __builtin_ia32_mulsd (v2df, v2df) 22150v2df __builtin_ia32_divsd (v2df, v2df) 22151v2df __builtin_ia32_minpd (v2df, v2df) 22152v2df __builtin_ia32_maxpd (v2df, v2df) 22153v2df __builtin_ia32_minsd (v2df, v2df) 22154v2df __builtin_ia32_maxsd (v2df, v2df) 22155v2df __builtin_ia32_andpd (v2df, v2df) 22156v2df __builtin_ia32_andnpd (v2df, v2df) 22157v2df __builtin_ia32_orpd (v2df, v2df) 22158v2df __builtin_ia32_xorpd (v2df, v2df) 22159v2df __builtin_ia32_movsd (v2df, v2df) 22160v2df __builtin_ia32_unpckhpd (v2df, v2df) 22161v2df __builtin_ia32_unpcklpd (v2df, v2df) 22162v16qi __builtin_ia32_paddb128 (v16qi, v16qi) 22163v8hi __builtin_ia32_paddw128 (v8hi, v8hi) 22164v4si __builtin_ia32_paddd128 (v4si, v4si) 22165v2di __builtin_ia32_paddq128 (v2di, v2di) 22166v16qi __builtin_ia32_psubb128 (v16qi, v16qi) 22167v8hi __builtin_ia32_psubw128 (v8hi, v8hi) 22168v4si __builtin_ia32_psubd128 (v4si, v4si) 22169v2di __builtin_ia32_psubq128 (v2di, v2di) 22170v8hi __builtin_ia32_pmullw128 (v8hi, v8hi) 22171v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi) 22172v2di __builtin_ia32_pand128 (v2di, v2di) 22173v2di __builtin_ia32_pandn128 (v2di, v2di) 22174v2di __builtin_ia32_por128 (v2di, v2di) 22175v2di __builtin_ia32_pxor128 (v2di, v2di) 22176v16qi __builtin_ia32_pavgb128 (v16qi, v16qi) 22177v8hi __builtin_ia32_pavgw128 (v8hi, v8hi) 22178v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi) 22179v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi) 22180v4si __builtin_ia32_pcmpeqd128 (v4si, v4si) 22181v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi) 22182v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi) 22183v4si __builtin_ia32_pcmpgtd128 (v4si, v4si) 22184v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi) 22185v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi) 22186v16qi __builtin_ia32_pminub128 (v16qi, v16qi) 22187v8hi __builtin_ia32_pminsw128 (v8hi, v8hi) 22188v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi) 22189v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi) 22190v4si __builtin_ia32_punpckhdq128 (v4si, v4si) 22191v2di __builtin_ia32_punpckhqdq128 (v2di, v2di) 22192v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi) 22193v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi) 22194v4si __builtin_ia32_punpckldq128 (v4si, v4si) 22195v2di __builtin_ia32_punpcklqdq128 (v2di, v2di) 22196v16qi __builtin_ia32_packsswb128 (v8hi, v8hi) 22197v8hi __builtin_ia32_packssdw128 (v4si, v4si) 22198v16qi __builtin_ia32_packuswb128 (v8hi, v8hi) 22199v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi) 22200void __builtin_ia32_maskmovdqu (v16qi, v16qi) 22201v2df __builtin_ia32_loadupd (double *) 22202void __builtin_ia32_storeupd (double *, v2df) 22203v2df __builtin_ia32_loadhpd (v2df, double const *) 22204v2df __builtin_ia32_loadlpd (v2df, double const *) 22205int __builtin_ia32_movmskpd (v2df) 22206int __builtin_ia32_pmovmskb128 (v16qi) 22207void __builtin_ia32_movnti (int *, int) 22208void __builtin_ia32_movnti64 (long long int *, long long int) 22209void __builtin_ia32_movntpd (double *, v2df) 22210void __builtin_ia32_movntdq (v2df *, v2df) 22211v4si __builtin_ia32_pshufd (v4si, int) 22212v8hi __builtin_ia32_pshuflw (v8hi, int) 22213v8hi __builtin_ia32_pshufhw (v8hi, int) 22214v2di __builtin_ia32_psadbw128 (v16qi, v16qi) 22215v2df __builtin_ia32_sqrtpd (v2df) 22216v2df __builtin_ia32_sqrtsd (v2df) 22217v2df __builtin_ia32_shufpd (v2df, v2df, int) 22218v2df __builtin_ia32_cvtdq2pd (v4si) 22219v4sf __builtin_ia32_cvtdq2ps (v4si) 22220v4si __builtin_ia32_cvtpd2dq (v2df) 22221v2si __builtin_ia32_cvtpd2pi (v2df) 22222v4sf __builtin_ia32_cvtpd2ps (v2df) 22223v4si __builtin_ia32_cvttpd2dq (v2df) 22224v2si __builtin_ia32_cvttpd2pi (v2df) 22225v2df __builtin_ia32_cvtpi2pd (v2si) 22226int __builtin_ia32_cvtsd2si (v2df) 22227int __builtin_ia32_cvttsd2si (v2df) 22228long long __builtin_ia32_cvtsd2si64 (v2df) 22229long long __builtin_ia32_cvttsd2si64 (v2df) 22230v4si __builtin_ia32_cvtps2dq (v4sf) 22231v2df __builtin_ia32_cvtps2pd (v4sf) 22232v4si __builtin_ia32_cvttps2dq (v4sf) 22233v2df __builtin_ia32_cvtsi2sd (v2df, int) 22234v2df __builtin_ia32_cvtsi642sd (v2df, long long) 22235v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df) 22236v2df __builtin_ia32_cvtss2sd (v2df, v4sf) 22237void __builtin_ia32_clflush (const void *) 22238void __builtin_ia32_lfence (void) 22239void __builtin_ia32_mfence (void) 22240v16qi __builtin_ia32_loaddqu (const char *) 22241void __builtin_ia32_storedqu (char *, v16qi) 22242v1di __builtin_ia32_pmuludq (v2si, v2si) 22243v2di __builtin_ia32_pmuludq128 (v4si, v4si) 22244v8hi __builtin_ia32_psllw128 (v8hi, v8hi) 22245v4si __builtin_ia32_pslld128 (v4si, v4si) 22246v2di __builtin_ia32_psllq128 (v2di, v2di) 22247v8hi __builtin_ia32_psrlw128 (v8hi, v8hi) 22248v4si __builtin_ia32_psrld128 (v4si, v4si) 22249v2di __builtin_ia32_psrlq128 (v2di, v2di) 22250v8hi __builtin_ia32_psraw128 (v8hi, v8hi) 22251v4si __builtin_ia32_psrad128 (v4si, v4si) 22252v2di __builtin_ia32_pslldqi128 (v2di, int) 22253v8hi __builtin_ia32_psllwi128 (v8hi, int) 22254v4si __builtin_ia32_pslldi128 (v4si, int) 22255v2di __builtin_ia32_psllqi128 (v2di, int) 22256v2di __builtin_ia32_psrldqi128 (v2di, int) 22257v8hi __builtin_ia32_psrlwi128 (v8hi, int) 22258v4si __builtin_ia32_psrldi128 (v4si, int) 22259v2di __builtin_ia32_psrlqi128 (v2di, int) 22260v8hi __builtin_ia32_psrawi128 (v8hi, int) 22261v4si __builtin_ia32_psradi128 (v4si, int) 22262v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi) 22263v2di __builtin_ia32_movq128 (v2di) 22264@end smallexample 22265 22266The following built-in functions are available when @option{-msse3} is used. 22267All of them generate the machine instruction that is part of the name. 22268 22269@smallexample 22270v2df __builtin_ia32_addsubpd (v2df, v2df) 22271v4sf __builtin_ia32_addsubps (v4sf, v4sf) 22272v2df __builtin_ia32_haddpd (v2df, v2df) 22273v4sf __builtin_ia32_haddps (v4sf, v4sf) 22274v2df __builtin_ia32_hsubpd (v2df, v2df) 22275v4sf __builtin_ia32_hsubps (v4sf, v4sf) 22276v16qi __builtin_ia32_lddqu (char const *) 22277void __builtin_ia32_monitor (void *, unsigned int, unsigned int) 22278v4sf __builtin_ia32_movshdup (v4sf) 22279v4sf __builtin_ia32_movsldup (v4sf) 22280void __builtin_ia32_mwait (unsigned int, unsigned int) 22281@end smallexample 22282 22283The following built-in functions are available when @option{-mssse3} is used. 22284All of them generate the machine instruction that is part of the name. 22285 22286@smallexample 22287v2si __builtin_ia32_phaddd (v2si, v2si) 22288v4hi __builtin_ia32_phaddw (v4hi, v4hi) 22289v4hi __builtin_ia32_phaddsw (v4hi, v4hi) 22290v2si __builtin_ia32_phsubd (v2si, v2si) 22291v4hi __builtin_ia32_phsubw (v4hi, v4hi) 22292v4hi __builtin_ia32_phsubsw (v4hi, v4hi) 22293v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi) 22294v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi) 22295v8qi __builtin_ia32_pshufb (v8qi, v8qi) 22296v8qi __builtin_ia32_psignb (v8qi, v8qi) 22297v2si __builtin_ia32_psignd (v2si, v2si) 22298v4hi __builtin_ia32_psignw (v4hi, v4hi) 22299v1di __builtin_ia32_palignr (v1di, v1di, int) 22300v8qi __builtin_ia32_pabsb (v8qi) 22301v2si __builtin_ia32_pabsd (v2si) 22302v4hi __builtin_ia32_pabsw (v4hi) 22303@end smallexample 22304 22305The following built-in functions are available when @option{-mssse3} is used. 22306All of them generate the machine instruction that is part of the name. 22307 22308@smallexample 22309v4si __builtin_ia32_phaddd128 (v4si, v4si) 22310v8hi __builtin_ia32_phaddw128 (v8hi, v8hi) 22311v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi) 22312v4si __builtin_ia32_phsubd128 (v4si, v4si) 22313v8hi __builtin_ia32_phsubw128 (v8hi, v8hi) 22314v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi) 22315v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi) 22316v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi) 22317v16qi __builtin_ia32_pshufb128 (v16qi, v16qi) 22318v16qi __builtin_ia32_psignb128 (v16qi, v16qi) 22319v4si __builtin_ia32_psignd128 (v4si, v4si) 22320v8hi __builtin_ia32_psignw128 (v8hi, v8hi) 22321v2di __builtin_ia32_palignr128 (v2di, v2di, int) 22322v16qi __builtin_ia32_pabsb128 (v16qi) 22323v4si __builtin_ia32_pabsd128 (v4si) 22324v8hi __builtin_ia32_pabsw128 (v8hi) 22325@end smallexample 22326 22327The following built-in functions are available when @option{-msse4.1} is 22328used. All of them generate the machine instruction that is part of the 22329name. 22330 22331@smallexample 22332v2df __builtin_ia32_blendpd (v2df, v2df, const int) 22333v4sf __builtin_ia32_blendps (v4sf, v4sf, const int) 22334v2df __builtin_ia32_blendvpd (v2df, v2df, v2df) 22335v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf) 22336v2df __builtin_ia32_dppd (v2df, v2df, const int) 22337v4sf __builtin_ia32_dpps (v4sf, v4sf, const int) 22338v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int) 22339v2di __builtin_ia32_movntdqa (v2di *); 22340v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int) 22341v8hi __builtin_ia32_packusdw128 (v4si, v4si) 22342v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi) 22343v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int) 22344v2di __builtin_ia32_pcmpeqq (v2di, v2di) 22345v8hi __builtin_ia32_phminposuw128 (v8hi) 22346v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi) 22347v4si __builtin_ia32_pmaxsd128 (v4si, v4si) 22348v4si __builtin_ia32_pmaxud128 (v4si, v4si) 22349v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi) 22350v16qi __builtin_ia32_pminsb128 (v16qi, v16qi) 22351v4si __builtin_ia32_pminsd128 (v4si, v4si) 22352v4si __builtin_ia32_pminud128 (v4si, v4si) 22353v8hi __builtin_ia32_pminuw128 (v8hi, v8hi) 22354v4si __builtin_ia32_pmovsxbd128 (v16qi) 22355v2di __builtin_ia32_pmovsxbq128 (v16qi) 22356v8hi __builtin_ia32_pmovsxbw128 (v16qi) 22357v2di __builtin_ia32_pmovsxdq128 (v4si) 22358v4si __builtin_ia32_pmovsxwd128 (v8hi) 22359v2di __builtin_ia32_pmovsxwq128 (v8hi) 22360v4si __builtin_ia32_pmovzxbd128 (v16qi) 22361v2di __builtin_ia32_pmovzxbq128 (v16qi) 22362v8hi __builtin_ia32_pmovzxbw128 (v16qi) 22363v2di __builtin_ia32_pmovzxdq128 (v4si) 22364v4si __builtin_ia32_pmovzxwd128 (v8hi) 22365v2di __builtin_ia32_pmovzxwq128 (v8hi) 22366v2di __builtin_ia32_pmuldq128 (v4si, v4si) 22367v4si __builtin_ia32_pmulld128 (v4si, v4si) 22368int __builtin_ia32_ptestc128 (v2di, v2di) 22369int __builtin_ia32_ptestnzc128 (v2di, v2di) 22370int __builtin_ia32_ptestz128 (v2di, v2di) 22371v2df __builtin_ia32_roundpd (v2df, const int) 22372v4sf __builtin_ia32_roundps (v4sf, const int) 22373v2df __builtin_ia32_roundsd (v2df, v2df, const int) 22374v4sf __builtin_ia32_roundss (v4sf, v4sf, const int) 22375@end smallexample 22376 22377The following built-in functions are available when @option{-msse4.1} is 22378used. 22379 22380@table @code 22381@item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int) 22382Generates the @code{insertps} machine instruction. 22383@item int __builtin_ia32_vec_ext_v16qi (v16qi, const int) 22384Generates the @code{pextrb} machine instruction. 22385@item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int) 22386Generates the @code{pinsrb} machine instruction. 22387@item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int) 22388Generates the @code{pinsrd} machine instruction. 22389@item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int) 22390Generates the @code{pinsrq} machine instruction in 64bit mode. 22391@end table 22392 22393The following built-in functions are changed to generate new SSE4.1 22394instructions when @option{-msse4.1} is used. 22395 22396@table @code 22397@item float __builtin_ia32_vec_ext_v4sf (v4sf, const int) 22398Generates the @code{extractps} machine instruction. 22399@item int __builtin_ia32_vec_ext_v4si (v4si, const int) 22400Generates the @code{pextrd} machine instruction. 22401@item long long __builtin_ia32_vec_ext_v2di (v2di, const int) 22402Generates the @code{pextrq} machine instruction in 64bit mode. 22403@end table 22404 22405The following built-in functions are available when @option{-msse4.2} is 22406used. All of them generate the machine instruction that is part of the 22407name. 22408 22409@smallexample 22410v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int) 22411int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int) 22412int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int) 22413int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int) 22414int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int) 22415int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int) 22416int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int) 22417v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int) 22418int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int) 22419int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int) 22420int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int) 22421int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int) 22422int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int) 22423int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int) 22424v2di __builtin_ia32_pcmpgtq (v2di, v2di) 22425@end smallexample 22426 22427The following built-in functions are available when @option{-msse4.2} is 22428used. 22429 22430@table @code 22431@item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char) 22432Generates the @code{crc32b} machine instruction. 22433@item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short) 22434Generates the @code{crc32w} machine instruction. 22435@item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int) 22436Generates the @code{crc32l} machine instruction. 22437@item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long) 22438Generates the @code{crc32q} machine instruction. 22439@end table 22440 22441The following built-in functions are changed to generate new SSE4.2 22442instructions when @option{-msse4.2} is used. 22443 22444@table @code 22445@item int __builtin_popcount (unsigned int) 22446Generates the @code{popcntl} machine instruction. 22447@item int __builtin_popcountl (unsigned long) 22448Generates the @code{popcntl} or @code{popcntq} machine instruction, 22449depending on the size of @code{unsigned long}. 22450@item int __builtin_popcountll (unsigned long long) 22451Generates the @code{popcntq} machine instruction. 22452@end table 22453 22454The following built-in functions are available when @option{-mavx} is 22455used. All of them generate the machine instruction that is part of the 22456name. 22457 22458@smallexample 22459v4df __builtin_ia32_addpd256 (v4df,v4df) 22460v8sf __builtin_ia32_addps256 (v8sf,v8sf) 22461v4df __builtin_ia32_addsubpd256 (v4df,v4df) 22462v8sf __builtin_ia32_addsubps256 (v8sf,v8sf) 22463v4df __builtin_ia32_andnpd256 (v4df,v4df) 22464v8sf __builtin_ia32_andnps256 (v8sf,v8sf) 22465v4df __builtin_ia32_andpd256 (v4df,v4df) 22466v8sf __builtin_ia32_andps256 (v8sf,v8sf) 22467v4df __builtin_ia32_blendpd256 (v4df,v4df,int) 22468v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int) 22469v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df) 22470v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf) 22471v2df __builtin_ia32_cmppd (v2df,v2df,int) 22472v4df __builtin_ia32_cmppd256 (v4df,v4df,int) 22473v4sf __builtin_ia32_cmpps (v4sf,v4sf,int) 22474v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int) 22475v2df __builtin_ia32_cmpsd (v2df,v2df,int) 22476v4sf __builtin_ia32_cmpss (v4sf,v4sf,int) 22477v4df __builtin_ia32_cvtdq2pd256 (v4si) 22478v8sf __builtin_ia32_cvtdq2ps256 (v8si) 22479v4si __builtin_ia32_cvtpd2dq256 (v4df) 22480v4sf __builtin_ia32_cvtpd2ps256 (v4df) 22481v8si __builtin_ia32_cvtps2dq256 (v8sf) 22482v4df __builtin_ia32_cvtps2pd256 (v4sf) 22483v4si __builtin_ia32_cvttpd2dq256 (v4df) 22484v8si __builtin_ia32_cvttps2dq256 (v8sf) 22485v4df __builtin_ia32_divpd256 (v4df,v4df) 22486v8sf __builtin_ia32_divps256 (v8sf,v8sf) 22487v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int) 22488v4df __builtin_ia32_haddpd256 (v4df,v4df) 22489v8sf __builtin_ia32_haddps256 (v8sf,v8sf) 22490v4df __builtin_ia32_hsubpd256 (v4df,v4df) 22491v8sf __builtin_ia32_hsubps256 (v8sf,v8sf) 22492v32qi __builtin_ia32_lddqu256 (pcchar) 22493v32qi __builtin_ia32_loaddqu256 (pcchar) 22494v4df __builtin_ia32_loadupd256 (pcdouble) 22495v8sf __builtin_ia32_loadups256 (pcfloat) 22496v2df __builtin_ia32_maskloadpd (pcv2df,v2df) 22497v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df) 22498v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf) 22499v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf) 22500void __builtin_ia32_maskstorepd (pv2df,v2df,v2df) 22501void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df) 22502void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf) 22503void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf) 22504v4df __builtin_ia32_maxpd256 (v4df,v4df) 22505v8sf __builtin_ia32_maxps256 (v8sf,v8sf) 22506v4df __builtin_ia32_minpd256 (v4df,v4df) 22507v8sf __builtin_ia32_minps256 (v8sf,v8sf) 22508v4df __builtin_ia32_movddup256 (v4df) 22509int __builtin_ia32_movmskpd256 (v4df) 22510int __builtin_ia32_movmskps256 (v8sf) 22511v8sf __builtin_ia32_movshdup256 (v8sf) 22512v8sf __builtin_ia32_movsldup256 (v8sf) 22513v4df __builtin_ia32_mulpd256 (v4df,v4df) 22514v8sf __builtin_ia32_mulps256 (v8sf,v8sf) 22515v4df __builtin_ia32_orpd256 (v4df,v4df) 22516v8sf __builtin_ia32_orps256 (v8sf,v8sf) 22517v2df __builtin_ia32_pd_pd256 (v4df) 22518v4df __builtin_ia32_pd256_pd (v2df) 22519v4sf __builtin_ia32_ps_ps256 (v8sf) 22520v8sf __builtin_ia32_ps256_ps (v4sf) 22521int __builtin_ia32_ptestc256 (v4di,v4di,ptest) 22522int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest) 22523int __builtin_ia32_ptestz256 (v4di,v4di,ptest) 22524v8sf __builtin_ia32_rcpps256 (v8sf) 22525v4df __builtin_ia32_roundpd256 (v4df,int) 22526v8sf __builtin_ia32_roundps256 (v8sf,int) 22527v8sf __builtin_ia32_rsqrtps_nr256 (v8sf) 22528v8sf __builtin_ia32_rsqrtps256 (v8sf) 22529v4df __builtin_ia32_shufpd256 (v4df,v4df,int) 22530v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int) 22531v4si __builtin_ia32_si_si256 (v8si) 22532v8si __builtin_ia32_si256_si (v4si) 22533v4df __builtin_ia32_sqrtpd256 (v4df) 22534v8sf __builtin_ia32_sqrtps_nr256 (v8sf) 22535v8sf __builtin_ia32_sqrtps256 (v8sf) 22536void __builtin_ia32_storedqu256 (pchar,v32qi) 22537void __builtin_ia32_storeupd256 (pdouble,v4df) 22538void __builtin_ia32_storeups256 (pfloat,v8sf) 22539v4df __builtin_ia32_subpd256 (v4df,v4df) 22540v8sf __builtin_ia32_subps256 (v8sf,v8sf) 22541v4df __builtin_ia32_unpckhpd256 (v4df,v4df) 22542v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf) 22543v4df __builtin_ia32_unpcklpd256 (v4df,v4df) 22544v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf) 22545v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df) 22546v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf) 22547v4df __builtin_ia32_vbroadcastsd256 (pcdouble) 22548v4sf __builtin_ia32_vbroadcastss (pcfloat) 22549v8sf __builtin_ia32_vbroadcastss256 (pcfloat) 22550v2df __builtin_ia32_vextractf128_pd256 (v4df,int) 22551v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int) 22552v4si __builtin_ia32_vextractf128_si256 (v8si,int) 22553v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int) 22554v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int) 22555v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int) 22556v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int) 22557v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int) 22558v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int) 22559v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int) 22560v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int) 22561v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int) 22562v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int) 22563v2df __builtin_ia32_vpermilpd (v2df,int) 22564v4df __builtin_ia32_vpermilpd256 (v4df,int) 22565v4sf __builtin_ia32_vpermilps (v4sf,int) 22566v8sf __builtin_ia32_vpermilps256 (v8sf,int) 22567v2df __builtin_ia32_vpermilvarpd (v2df,v2di) 22568v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di) 22569v4sf __builtin_ia32_vpermilvarps (v4sf,v4si) 22570v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si) 22571int __builtin_ia32_vtestcpd (v2df,v2df,ptest) 22572int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest) 22573int __builtin_ia32_vtestcps (v4sf,v4sf,ptest) 22574int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest) 22575int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest) 22576int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest) 22577int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest) 22578int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest) 22579int __builtin_ia32_vtestzpd (v2df,v2df,ptest) 22580int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest) 22581int __builtin_ia32_vtestzps (v4sf,v4sf,ptest) 22582int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest) 22583void __builtin_ia32_vzeroall (void) 22584void __builtin_ia32_vzeroupper (void) 22585v4df __builtin_ia32_xorpd256 (v4df,v4df) 22586v8sf __builtin_ia32_xorps256 (v8sf,v8sf) 22587@end smallexample 22588 22589The following built-in functions are available when @option{-mavx2} is 22590used. All of them generate the machine instruction that is part of the 22591name. 22592 22593@smallexample 22594v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int) 22595v32qi __builtin_ia32_pabsb256 (v32qi) 22596v16hi __builtin_ia32_pabsw256 (v16hi) 22597v8si __builtin_ia32_pabsd256 (v8si) 22598v16hi __builtin_ia32_packssdw256 (v8si,v8si) 22599v32qi __builtin_ia32_packsswb256 (v16hi,v16hi) 22600v16hi __builtin_ia32_packusdw256 (v8si,v8si) 22601v32qi __builtin_ia32_packuswb256 (v16hi,v16hi) 22602v32qi __builtin_ia32_paddb256 (v32qi,v32qi) 22603v16hi __builtin_ia32_paddw256 (v16hi,v16hi) 22604v8si __builtin_ia32_paddd256 (v8si,v8si) 22605v4di __builtin_ia32_paddq256 (v4di,v4di) 22606v32qi __builtin_ia32_paddsb256 (v32qi,v32qi) 22607v16hi __builtin_ia32_paddsw256 (v16hi,v16hi) 22608v32qi __builtin_ia32_paddusb256 (v32qi,v32qi) 22609v16hi __builtin_ia32_paddusw256 (v16hi,v16hi) 22610v4di __builtin_ia32_palignr256 (v4di,v4di,int) 22611v4di __builtin_ia32_andsi256 (v4di,v4di) 22612v4di __builtin_ia32_andnotsi256 (v4di,v4di) 22613v32qi __builtin_ia32_pavgb256 (v32qi,v32qi) 22614v16hi __builtin_ia32_pavgw256 (v16hi,v16hi) 22615v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi) 22616v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int) 22617v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi) 22618v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi) 22619v8si __builtin_ia32_pcmpeqd256 (c8si,v8si) 22620v4di __builtin_ia32_pcmpeqq256 (v4di,v4di) 22621v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi) 22622v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi) 22623v8si __builtin_ia32_pcmpgtd256 (v8si,v8si) 22624v4di __builtin_ia32_pcmpgtq256 (v4di,v4di) 22625v16hi __builtin_ia32_phaddw256 (v16hi,v16hi) 22626v8si __builtin_ia32_phaddd256 (v8si,v8si) 22627v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi) 22628v16hi __builtin_ia32_phsubw256 (v16hi,v16hi) 22629v8si __builtin_ia32_phsubd256 (v8si,v8si) 22630v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi) 22631v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi) 22632v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi) 22633v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi) 22634v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi) 22635v8si __builtin_ia32_pmaxsd256 (v8si,v8si) 22636v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi) 22637v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi) 22638v8si __builtin_ia32_pmaxud256 (v8si,v8si) 22639v32qi __builtin_ia32_pminsb256 (v32qi,v32qi) 22640v16hi __builtin_ia32_pminsw256 (v16hi,v16hi) 22641v8si __builtin_ia32_pminsd256 (v8si,v8si) 22642v32qi __builtin_ia32_pminub256 (v32qi,v32qi) 22643v16hi __builtin_ia32_pminuw256 (v16hi,v16hi) 22644v8si __builtin_ia32_pminud256 (v8si,v8si) 22645int __builtin_ia32_pmovmskb256 (v32qi) 22646v16hi __builtin_ia32_pmovsxbw256 (v16qi) 22647v8si __builtin_ia32_pmovsxbd256 (v16qi) 22648v4di __builtin_ia32_pmovsxbq256 (v16qi) 22649v8si __builtin_ia32_pmovsxwd256 (v8hi) 22650v4di __builtin_ia32_pmovsxwq256 (v8hi) 22651v4di __builtin_ia32_pmovsxdq256 (v4si) 22652v16hi __builtin_ia32_pmovzxbw256 (v16qi) 22653v8si __builtin_ia32_pmovzxbd256 (v16qi) 22654v4di __builtin_ia32_pmovzxbq256 (v16qi) 22655v8si __builtin_ia32_pmovzxwd256 (v8hi) 22656v4di __builtin_ia32_pmovzxwq256 (v8hi) 22657v4di __builtin_ia32_pmovzxdq256 (v4si) 22658v4di __builtin_ia32_pmuldq256 (v8si,v8si) 22659v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi) 22660v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi) 22661v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi) 22662v16hi __builtin_ia32_pmullw256 (v16hi,v16hi) 22663v8si __builtin_ia32_pmulld256 (v8si,v8si) 22664v4di __builtin_ia32_pmuludq256 (v8si,v8si) 22665v4di __builtin_ia32_por256 (v4di,v4di) 22666v16hi __builtin_ia32_psadbw256 (v32qi,v32qi) 22667v32qi __builtin_ia32_pshufb256 (v32qi,v32qi) 22668v8si __builtin_ia32_pshufd256 (v8si,int) 22669v16hi __builtin_ia32_pshufhw256 (v16hi,int) 22670v16hi __builtin_ia32_pshuflw256 (v16hi,int) 22671v32qi __builtin_ia32_psignb256 (v32qi,v32qi) 22672v16hi __builtin_ia32_psignw256 (v16hi,v16hi) 22673v8si __builtin_ia32_psignd256 (v8si,v8si) 22674v4di __builtin_ia32_pslldqi256 (v4di,int) 22675v16hi __builtin_ia32_psllwi256 (16hi,int) 22676v16hi __builtin_ia32_psllw256(v16hi,v8hi) 22677v8si __builtin_ia32_pslldi256 (v8si,int) 22678v8si __builtin_ia32_pslld256(v8si,v4si) 22679v4di __builtin_ia32_psllqi256 (v4di,int) 22680v4di __builtin_ia32_psllq256(v4di,v2di) 22681v16hi __builtin_ia32_psrawi256 (v16hi,int) 22682v16hi __builtin_ia32_psraw256 (v16hi,v8hi) 22683v8si __builtin_ia32_psradi256 (v8si,int) 22684v8si __builtin_ia32_psrad256 (v8si,v4si) 22685v4di __builtin_ia32_psrldqi256 (v4di, int) 22686v16hi __builtin_ia32_psrlwi256 (v16hi,int) 22687v16hi __builtin_ia32_psrlw256 (v16hi,v8hi) 22688v8si __builtin_ia32_psrldi256 (v8si,int) 22689v8si __builtin_ia32_psrld256 (v8si,v4si) 22690v4di __builtin_ia32_psrlqi256 (v4di,int) 22691v4di __builtin_ia32_psrlq256(v4di,v2di) 22692v32qi __builtin_ia32_psubb256 (v32qi,v32qi) 22693v32hi __builtin_ia32_psubw256 (v16hi,v16hi) 22694v8si __builtin_ia32_psubd256 (v8si,v8si) 22695v4di __builtin_ia32_psubq256 (v4di,v4di) 22696v32qi __builtin_ia32_psubsb256 (v32qi,v32qi) 22697v16hi __builtin_ia32_psubsw256 (v16hi,v16hi) 22698v32qi __builtin_ia32_psubusb256 (v32qi,v32qi) 22699v16hi __builtin_ia32_psubusw256 (v16hi,v16hi) 22700v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi) 22701v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi) 22702v8si __builtin_ia32_punpckhdq256 (v8si,v8si) 22703v4di __builtin_ia32_punpckhqdq256 (v4di,v4di) 22704v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi) 22705v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi) 22706v8si __builtin_ia32_punpckldq256 (v8si,v8si) 22707v4di __builtin_ia32_punpcklqdq256 (v4di,v4di) 22708v4di __builtin_ia32_pxor256 (v4di,v4di) 22709v4di __builtin_ia32_movntdqa256 (pv4di) 22710v4sf __builtin_ia32_vbroadcastss_ps (v4sf) 22711v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf) 22712v4df __builtin_ia32_vbroadcastsd_pd256 (v2df) 22713v4di __builtin_ia32_vbroadcastsi256 (v2di) 22714v4si __builtin_ia32_pblendd128 (v4si,v4si) 22715v8si __builtin_ia32_pblendd256 (v8si,v8si) 22716v32qi __builtin_ia32_pbroadcastb256 (v16qi) 22717v16hi __builtin_ia32_pbroadcastw256 (v8hi) 22718v8si __builtin_ia32_pbroadcastd256 (v4si) 22719v4di __builtin_ia32_pbroadcastq256 (v2di) 22720v16qi __builtin_ia32_pbroadcastb128 (v16qi) 22721v8hi __builtin_ia32_pbroadcastw128 (v8hi) 22722v4si __builtin_ia32_pbroadcastd128 (v4si) 22723v2di __builtin_ia32_pbroadcastq128 (v2di) 22724v8si __builtin_ia32_permvarsi256 (v8si,v8si) 22725v4df __builtin_ia32_permdf256 (v4df,int) 22726v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf) 22727v4di __builtin_ia32_permdi256 (v4di,int) 22728v4di __builtin_ia32_permti256 (v4di,v4di,int) 22729v4di __builtin_ia32_extract128i256 (v4di,int) 22730v4di __builtin_ia32_insert128i256 (v4di,v2di,int) 22731v8si __builtin_ia32_maskloadd256 (pcv8si,v8si) 22732v4di __builtin_ia32_maskloadq256 (pcv4di,v4di) 22733v4si __builtin_ia32_maskloadd (pcv4si,v4si) 22734v2di __builtin_ia32_maskloadq (pcv2di,v2di) 22735void __builtin_ia32_maskstored256 (pv8si,v8si,v8si) 22736void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di) 22737void __builtin_ia32_maskstored (pv4si,v4si,v4si) 22738void __builtin_ia32_maskstoreq (pv2di,v2di,v2di) 22739v8si __builtin_ia32_psllv8si (v8si,v8si) 22740v4si __builtin_ia32_psllv4si (v4si,v4si) 22741v4di __builtin_ia32_psllv4di (v4di,v4di) 22742v2di __builtin_ia32_psllv2di (v2di,v2di) 22743v8si __builtin_ia32_psrav8si (v8si,v8si) 22744v4si __builtin_ia32_psrav4si (v4si,v4si) 22745v8si __builtin_ia32_psrlv8si (v8si,v8si) 22746v4si __builtin_ia32_psrlv4si (v4si,v4si) 22747v4di __builtin_ia32_psrlv4di (v4di,v4di) 22748v2di __builtin_ia32_psrlv2di (v2di,v2di) 22749v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int) 22750v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int) 22751v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int) 22752v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int) 22753v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int) 22754v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int) 22755v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int) 22756v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int) 22757v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int) 22758v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int) 22759v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int) 22760v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int) 22761v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int) 22762v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int) 22763v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int) 22764v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int) 22765@end smallexample 22766 22767The following built-in functions are available when @option{-maes} is 22768used. All of them generate the machine instruction that is part of the 22769name. 22770 22771@smallexample 22772v2di __builtin_ia32_aesenc128 (v2di, v2di) 22773v2di __builtin_ia32_aesenclast128 (v2di, v2di) 22774v2di __builtin_ia32_aesdec128 (v2di, v2di) 22775v2di __builtin_ia32_aesdeclast128 (v2di, v2di) 22776v2di __builtin_ia32_aeskeygenassist128 (v2di, const int) 22777v2di __builtin_ia32_aesimc128 (v2di) 22778@end smallexample 22779 22780The following built-in function is available when @option{-mpclmul} is 22781used. 22782 22783@table @code 22784@item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int) 22785Generates the @code{pclmulqdq} machine instruction. 22786@end table 22787 22788The following built-in function is available when @option{-mfsgsbase} is 22789used. All of them generate the machine instruction that is part of the 22790name. 22791 22792@smallexample 22793unsigned int __builtin_ia32_rdfsbase32 (void) 22794unsigned long long __builtin_ia32_rdfsbase64 (void) 22795unsigned int __builtin_ia32_rdgsbase32 (void) 22796unsigned long long __builtin_ia32_rdgsbase64 (void) 22797void _writefsbase_u32 (unsigned int) 22798void _writefsbase_u64 (unsigned long long) 22799void _writegsbase_u32 (unsigned int) 22800void _writegsbase_u64 (unsigned long long) 22801@end smallexample 22802 22803The following built-in function is available when @option{-mrdrnd} is 22804used. All of them generate the machine instruction that is part of the 22805name. 22806 22807@smallexample 22808unsigned int __builtin_ia32_rdrand16_step (unsigned short *) 22809unsigned int __builtin_ia32_rdrand32_step (unsigned int *) 22810unsigned int __builtin_ia32_rdrand64_step (unsigned long long *) 22811@end smallexample 22812 22813The following built-in function is available when @option{-mptwrite} is 22814used. All of them generate the machine instruction that is part of the 22815name. 22816 22817@smallexample 22818void __builtin_ia32_ptwrite32 (unsigned) 22819void __builtin_ia32_ptwrite64 (unsigned long long) 22820@end smallexample 22821 22822The following built-in functions are available when @option{-msse4a} is used. 22823All of them generate the machine instruction that is part of the name. 22824 22825@smallexample 22826void __builtin_ia32_movntsd (double *, v2df) 22827void __builtin_ia32_movntss (float *, v4sf) 22828v2di __builtin_ia32_extrq (v2di, v16qi) 22829v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int) 22830v2di __builtin_ia32_insertq (v2di, v2di) 22831v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int) 22832@end smallexample 22833 22834The following built-in functions are available when @option{-mxop} is used. 22835@smallexample 22836v2df __builtin_ia32_vfrczpd (v2df) 22837v4sf __builtin_ia32_vfrczps (v4sf) 22838v2df __builtin_ia32_vfrczsd (v2df) 22839v4sf __builtin_ia32_vfrczss (v4sf) 22840v4df __builtin_ia32_vfrczpd256 (v4df) 22841v8sf __builtin_ia32_vfrczps256 (v8sf) 22842v2di __builtin_ia32_vpcmov (v2di, v2di, v2di) 22843v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di) 22844v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si) 22845v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi) 22846v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi) 22847v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df) 22848v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf) 22849v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di) 22850v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si) 22851v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi) 22852v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi) 22853v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df) 22854v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf) 22855v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi) 22856v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi) 22857v4si __builtin_ia32_vpcomeqd (v4si, v4si) 22858v2di __builtin_ia32_vpcomeqq (v2di, v2di) 22859v16qi __builtin_ia32_vpcomequb (v16qi, v16qi) 22860v4si __builtin_ia32_vpcomequd (v4si, v4si) 22861v2di __builtin_ia32_vpcomequq (v2di, v2di) 22862v8hi __builtin_ia32_vpcomequw (v8hi, v8hi) 22863v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi) 22864v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi) 22865v4si __builtin_ia32_vpcomfalsed (v4si, v4si) 22866v2di __builtin_ia32_vpcomfalseq (v2di, v2di) 22867v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi) 22868v4si __builtin_ia32_vpcomfalseud (v4si, v4si) 22869v2di __builtin_ia32_vpcomfalseuq (v2di, v2di) 22870v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi) 22871v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi) 22872v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi) 22873v4si __builtin_ia32_vpcomged (v4si, v4si) 22874v2di __builtin_ia32_vpcomgeq (v2di, v2di) 22875v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi) 22876v4si __builtin_ia32_vpcomgeud (v4si, v4si) 22877v2di __builtin_ia32_vpcomgeuq (v2di, v2di) 22878v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi) 22879v8hi __builtin_ia32_vpcomgew (v8hi, v8hi) 22880v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi) 22881v4si __builtin_ia32_vpcomgtd (v4si, v4si) 22882v2di __builtin_ia32_vpcomgtq (v2di, v2di) 22883v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi) 22884v4si __builtin_ia32_vpcomgtud (v4si, v4si) 22885v2di __builtin_ia32_vpcomgtuq (v2di, v2di) 22886v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi) 22887v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi) 22888v16qi __builtin_ia32_vpcomleb (v16qi, v16qi) 22889v4si __builtin_ia32_vpcomled (v4si, v4si) 22890v2di __builtin_ia32_vpcomleq (v2di, v2di) 22891v16qi __builtin_ia32_vpcomleub (v16qi, v16qi) 22892v4si __builtin_ia32_vpcomleud (v4si, v4si) 22893v2di __builtin_ia32_vpcomleuq (v2di, v2di) 22894v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi) 22895v8hi __builtin_ia32_vpcomlew (v8hi, v8hi) 22896v16qi __builtin_ia32_vpcomltb (v16qi, v16qi) 22897v4si __builtin_ia32_vpcomltd (v4si, v4si) 22898v2di __builtin_ia32_vpcomltq (v2di, v2di) 22899v16qi __builtin_ia32_vpcomltub (v16qi, v16qi) 22900v4si __builtin_ia32_vpcomltud (v4si, v4si) 22901v2di __builtin_ia32_vpcomltuq (v2di, v2di) 22902v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi) 22903v8hi __builtin_ia32_vpcomltw (v8hi, v8hi) 22904v16qi __builtin_ia32_vpcomneb (v16qi, v16qi) 22905v4si __builtin_ia32_vpcomned (v4si, v4si) 22906v2di __builtin_ia32_vpcomneq (v2di, v2di) 22907v16qi __builtin_ia32_vpcomneub (v16qi, v16qi) 22908v4si __builtin_ia32_vpcomneud (v4si, v4si) 22909v2di __builtin_ia32_vpcomneuq (v2di, v2di) 22910v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi) 22911v8hi __builtin_ia32_vpcomnew (v8hi, v8hi) 22912v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi) 22913v4si __builtin_ia32_vpcomtrued (v4si, v4si) 22914v2di __builtin_ia32_vpcomtrueq (v2di, v2di) 22915v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi) 22916v4si __builtin_ia32_vpcomtrueud (v4si, v4si) 22917v2di __builtin_ia32_vpcomtrueuq (v2di, v2di) 22918v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi) 22919v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi) 22920v4si __builtin_ia32_vphaddbd (v16qi) 22921v2di __builtin_ia32_vphaddbq (v16qi) 22922v8hi __builtin_ia32_vphaddbw (v16qi) 22923v2di __builtin_ia32_vphadddq (v4si) 22924v4si __builtin_ia32_vphaddubd (v16qi) 22925v2di __builtin_ia32_vphaddubq (v16qi) 22926v8hi __builtin_ia32_vphaddubw (v16qi) 22927v2di __builtin_ia32_vphaddudq (v4si) 22928v4si __builtin_ia32_vphadduwd (v8hi) 22929v2di __builtin_ia32_vphadduwq (v8hi) 22930v4si __builtin_ia32_vphaddwd (v8hi) 22931v2di __builtin_ia32_vphaddwq (v8hi) 22932v8hi __builtin_ia32_vphsubbw (v16qi) 22933v2di __builtin_ia32_vphsubdq (v4si) 22934v4si __builtin_ia32_vphsubwd (v8hi) 22935v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si) 22936v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di) 22937v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di) 22938v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si) 22939v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di) 22940v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di) 22941v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si) 22942v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi) 22943v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si) 22944v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi) 22945v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si) 22946v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si) 22947v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi) 22948v16qi __builtin_ia32_vprotb (v16qi, v16qi) 22949v4si __builtin_ia32_vprotd (v4si, v4si) 22950v2di __builtin_ia32_vprotq (v2di, v2di) 22951v8hi __builtin_ia32_vprotw (v8hi, v8hi) 22952v16qi __builtin_ia32_vpshab (v16qi, v16qi) 22953v4si __builtin_ia32_vpshad (v4si, v4si) 22954v2di __builtin_ia32_vpshaq (v2di, v2di) 22955v8hi __builtin_ia32_vpshaw (v8hi, v8hi) 22956v16qi __builtin_ia32_vpshlb (v16qi, v16qi) 22957v4si __builtin_ia32_vpshld (v4si, v4si) 22958v2di __builtin_ia32_vpshlq (v2di, v2di) 22959v8hi __builtin_ia32_vpshlw (v8hi, v8hi) 22960@end smallexample 22961 22962The following built-in functions are available when @option{-mfma4} is used. 22963All of them generate the machine instruction that is part of the name. 22964 22965@smallexample 22966v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df) 22967v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf) 22968v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df) 22969v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf) 22970v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df) 22971v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf) 22972v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df) 22973v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf) 22974v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df) 22975v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf) 22976v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df) 22977v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf) 22978v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df) 22979v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf) 22980v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df) 22981v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf) 22982v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df) 22983v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf) 22984v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df) 22985v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf) 22986v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df) 22987v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf) 22988v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df) 22989v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf) 22990v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df) 22991v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf) 22992v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df) 22993v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf) 22994v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df) 22995v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf) 22996v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df) 22997v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf) 22998 22999@end smallexample 23000 23001The following built-in functions are available when @option{-mlwp} is used. 23002 23003@smallexample 23004void __builtin_ia32_llwpcb16 (void *); 23005void __builtin_ia32_llwpcb32 (void *); 23006void __builtin_ia32_llwpcb64 (void *); 23007void * __builtin_ia32_llwpcb16 (void); 23008void * __builtin_ia32_llwpcb32 (void); 23009void * __builtin_ia32_llwpcb64 (void); 23010void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short) 23011void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int) 23012void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int) 23013unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short) 23014unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int) 23015unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int) 23016@end smallexample 23017 23018The following built-in functions are available when @option{-mbmi} is used. 23019All of them generate the machine instruction that is part of the name. 23020@smallexample 23021unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int); 23022unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long); 23023@end smallexample 23024 23025The following built-in functions are available when @option{-mbmi2} is used. 23026All of them generate the machine instruction that is part of the name. 23027@smallexample 23028unsigned int _bzhi_u32 (unsigned int, unsigned int) 23029unsigned int _pdep_u32 (unsigned int, unsigned int) 23030unsigned int _pext_u32 (unsigned int, unsigned int) 23031unsigned long long _bzhi_u64 (unsigned long long, unsigned long long) 23032unsigned long long _pdep_u64 (unsigned long long, unsigned long long) 23033unsigned long long _pext_u64 (unsigned long long, unsigned long long) 23034@end smallexample 23035 23036The following built-in functions are available when @option{-mlzcnt} is used. 23037All of them generate the machine instruction that is part of the name. 23038@smallexample 23039unsigned short __builtin_ia32_lzcnt_u16(unsigned short); 23040unsigned int __builtin_ia32_lzcnt_u32(unsigned int); 23041unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long); 23042@end smallexample 23043 23044The following built-in functions are available when @option{-mfxsr} is used. 23045All of them generate the machine instruction that is part of the name. 23046@smallexample 23047void __builtin_ia32_fxsave (void *) 23048void __builtin_ia32_fxrstor (void *) 23049void __builtin_ia32_fxsave64 (void *) 23050void __builtin_ia32_fxrstor64 (void *) 23051@end smallexample 23052 23053The following built-in functions are available when @option{-mxsave} is used. 23054All of them generate the machine instruction that is part of the name. 23055@smallexample 23056void __builtin_ia32_xsave (void *, long long) 23057void __builtin_ia32_xrstor (void *, long long) 23058void __builtin_ia32_xsave64 (void *, long long) 23059void __builtin_ia32_xrstor64 (void *, long long) 23060@end smallexample 23061 23062The following built-in functions are available when @option{-mxsaveopt} is used. 23063All of them generate the machine instruction that is part of the name. 23064@smallexample 23065void __builtin_ia32_xsaveopt (void *, long long) 23066void __builtin_ia32_xsaveopt64 (void *, long long) 23067@end smallexample 23068 23069The following built-in functions are available when @option{-mtbm} is used. 23070Both of them generate the immediate form of the bextr machine instruction. 23071@smallexample 23072unsigned int __builtin_ia32_bextri_u32 (unsigned int, 23073 const unsigned int); 23074unsigned long long __builtin_ia32_bextri_u64 (unsigned long long, 23075 const unsigned long long); 23076@end smallexample 23077 23078 23079The following built-in functions are available when @option{-m3dnow} is used. 23080All of them generate the machine instruction that is part of the name. 23081 23082@smallexample 23083void __builtin_ia32_femms (void) 23084v8qi __builtin_ia32_pavgusb (v8qi, v8qi) 23085v2si __builtin_ia32_pf2id (v2sf) 23086v2sf __builtin_ia32_pfacc (v2sf, v2sf) 23087v2sf __builtin_ia32_pfadd (v2sf, v2sf) 23088v2si __builtin_ia32_pfcmpeq (v2sf, v2sf) 23089v2si __builtin_ia32_pfcmpge (v2sf, v2sf) 23090v2si __builtin_ia32_pfcmpgt (v2sf, v2sf) 23091v2sf __builtin_ia32_pfmax (v2sf, v2sf) 23092v2sf __builtin_ia32_pfmin (v2sf, v2sf) 23093v2sf __builtin_ia32_pfmul (v2sf, v2sf) 23094v2sf __builtin_ia32_pfrcp (v2sf) 23095v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf) 23096v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf) 23097v2sf __builtin_ia32_pfrsqrt (v2sf) 23098v2sf __builtin_ia32_pfsub (v2sf, v2sf) 23099v2sf __builtin_ia32_pfsubr (v2sf, v2sf) 23100v2sf __builtin_ia32_pi2fd (v2si) 23101v4hi __builtin_ia32_pmulhrw (v4hi, v4hi) 23102@end smallexample 23103 23104The following built-in functions are available when @option{-m3dnowa} is used. 23105All of them generate the machine instruction that is part of the name. 23106 23107@smallexample 23108v2si __builtin_ia32_pf2iw (v2sf) 23109v2sf __builtin_ia32_pfnacc (v2sf, v2sf) 23110v2sf __builtin_ia32_pfpnacc (v2sf, v2sf) 23111v2sf __builtin_ia32_pi2fw (v2si) 23112v2sf __builtin_ia32_pswapdsf (v2sf) 23113v2si __builtin_ia32_pswapdsi (v2si) 23114@end smallexample 23115 23116The following built-in functions are available when @option{-mrtm} is used 23117They are used for restricted transactional memory. These are the internal 23118low level functions. Normally the functions in 23119@ref{x86 transactional memory intrinsics} should be used instead. 23120 23121@smallexample 23122int __builtin_ia32_xbegin () 23123void __builtin_ia32_xend () 23124void __builtin_ia32_xabort (status) 23125int __builtin_ia32_xtest () 23126@end smallexample 23127 23128The following built-in functions are available when @option{-mmwaitx} is used. 23129All of them generate the machine instruction that is part of the name. 23130@smallexample 23131void __builtin_ia32_monitorx (void *, unsigned int, unsigned int) 23132void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int) 23133@end smallexample 23134 23135The following built-in functions are available when @option{-mclzero} is used. 23136All of them generate the machine instruction that is part of the name. 23137@smallexample 23138void __builtin_i32_clzero (void *) 23139@end smallexample 23140 23141The following built-in functions are available when @option{-mpku} is used. 23142They generate reads and writes to PKRU. 23143@smallexample 23144void __builtin_ia32_wrpkru (unsigned int) 23145unsigned int __builtin_ia32_rdpkru () 23146@end smallexample 23147 23148The following built-in functions are available when @option{-mcet} or 23149@option{-mshstk} option is used. They support shadow stack 23150machine instructions from Intel Control-flow Enforcement Technology (CET). 23151Each built-in function generates the machine instruction that is part 23152of the function's name. These are the internal low-level functions. 23153Normally the functions in @ref{x86 control-flow protection intrinsics} 23154should be used instead. 23155 23156@smallexample 23157unsigned int __builtin_ia32_rdsspd (void) 23158unsigned long long __builtin_ia32_rdsspq (void) 23159void __builtin_ia32_incsspd (unsigned int) 23160void __builtin_ia32_incsspq (unsigned long long) 23161void __builtin_ia32_saveprevssp(void); 23162void __builtin_ia32_rstorssp(void *); 23163void __builtin_ia32_wrssd(unsigned int, void *); 23164void __builtin_ia32_wrssq(unsigned long long, void *); 23165void __builtin_ia32_wrussd(unsigned int, void *); 23166void __builtin_ia32_wrussq(unsigned long long, void *); 23167void __builtin_ia32_setssbsy(void); 23168void __builtin_ia32_clrssbsy(void *); 23169@end smallexample 23170 23171@node x86 transactional memory intrinsics 23172@subsection x86 Transactional Memory Intrinsics 23173 23174These hardware transactional memory intrinsics for x86 allow you to use 23175memory transactions with RTM (Restricted Transactional Memory). 23176This support is enabled with the @option{-mrtm} option. 23177For using HLE (Hardware Lock Elision) see 23178@ref{x86 specific memory model extensions for transactional memory} instead. 23179 23180A memory transaction commits all changes to memory in an atomic way, 23181as visible to other threads. If the transaction fails it is rolled back 23182and all side effects discarded. 23183 23184Generally there is no guarantee that a memory transaction ever succeeds 23185and suitable fallback code always needs to be supplied. 23186 23187@deftypefn {RTM Function} {unsigned} _xbegin () 23188Start a RTM (Restricted Transactional Memory) transaction. 23189Returns @code{_XBEGIN_STARTED} when the transaction 23190started successfully (note this is not 0, so the constant has to be 23191explicitly tested). 23192 23193If the transaction aborts, all side effects 23194are undone and an abort code encoded as a bit mask is returned. 23195The following macros are defined: 23196 23197@table @code 23198@item _XABORT_EXPLICIT 23199Transaction was explicitly aborted with @code{_xabort}. The parameter passed 23200to @code{_xabort} is available with @code{_XABORT_CODE(status)}. 23201@item _XABORT_RETRY 23202Transaction retry is possible. 23203@item _XABORT_CONFLICT 23204Transaction abort due to a memory conflict with another thread. 23205@item _XABORT_CAPACITY 23206Transaction abort due to the transaction using too much memory. 23207@item _XABORT_DEBUG 23208Transaction abort due to a debug trap. 23209@item _XABORT_NESTED 23210Transaction abort in an inner nested transaction. 23211@end table 23212 23213There is no guarantee 23214any transaction ever succeeds, so there always needs to be a valid 23215fallback path. 23216@end deftypefn 23217 23218@deftypefn {RTM Function} {void} _xend () 23219Commit the current transaction. When no transaction is active this faults. 23220All memory side effects of the transaction become visible 23221to other threads in an atomic manner. 23222@end deftypefn 23223 23224@deftypefn {RTM Function} {int} _xtest () 23225Return a nonzero value if a transaction is currently active, otherwise 0. 23226@end deftypefn 23227 23228@deftypefn {RTM Function} {void} _xabort (status) 23229Abort the current transaction. When no transaction is active this is a no-op. 23230The @var{status} is an 8-bit constant; its value is encoded in the return 23231value from @code{_xbegin}. 23232@end deftypefn 23233 23234Here is an example showing handling for @code{_XABORT_RETRY} 23235and a fallback path for other failures: 23236 23237@smallexample 23238#include <immintrin.h> 23239 23240int n_tries, max_tries; 23241unsigned status = _XABORT_EXPLICIT; 23242... 23243 23244for (n_tries = 0; n_tries < max_tries; n_tries++) 23245 @{ 23246 status = _xbegin (); 23247 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY)) 23248 break; 23249 @} 23250if (status == _XBEGIN_STARTED) 23251 @{ 23252 ... transaction code... 23253 _xend (); 23254 @} 23255else 23256 @{ 23257 ... non-transactional fallback path... 23258 @} 23259@end smallexample 23260 23261@noindent 23262Note that, in most cases, the transactional and non-transactional code 23263must synchronize together to ensure consistency. 23264 23265@node x86 control-flow protection intrinsics 23266@subsection x86 Control-Flow Protection Intrinsics 23267 23268@deftypefn {CET Function} {ret_type} _get_ssp (void) 23269Get the current value of shadow stack pointer if shadow stack support 23270from Intel CET is enabled in the hardware or @code{0} otherwise. 23271The @code{ret_type} is @code{unsigned long long} for 64-bit targets 23272and @code{unsigned int} for 32-bit targets. 23273@end deftypefn 23274 23275@deftypefn {CET Function} void _inc_ssp (unsigned int) 23276Increment the current shadow stack pointer by the size specified by the 23277function argument. The argument is masked to a byte value for security 23278reasons, so to increment by more than 255 bytes you must call the function 23279multiple times. 23280@end deftypefn 23281 23282The shadow stack unwind code looks like: 23283 23284@smallexample 23285#include <immintrin.h> 23286 23287/* Unwind the shadow stack for EH. */ 23288#define _Unwind_Frames_Extra(x) \ 23289 do \ 23290 @{ \ 23291 _Unwind_Word ssp = _get_ssp (); \ 23292 if (ssp != 0) \ 23293 @{ \ 23294 _Unwind_Word tmp = (x); \ 23295 while (tmp > 255) \ 23296 @{ \ 23297 _inc_ssp (tmp); \ 23298 tmp -= 255; \ 23299 @} \ 23300 _inc_ssp (tmp); \ 23301 @} \ 23302 @} \ 23303 while (0) 23304@end smallexample 23305 23306@noindent 23307This code runs unconditionally on all 64-bit processors. For 32-bit 23308processors the code runs on those that support multi-byte NOP instructions. 23309 23310@node Target Format Checks 23311@section Format Checks Specific to Particular Target Machines 23312 23313For some target machines, GCC supports additional options to the 23314format attribute 23315(@pxref{Function Attributes,,Declaring Attributes of Functions}). 23316 23317@menu 23318* Solaris Format Checks:: 23319* Darwin Format Checks:: 23320@end menu 23321 23322@node Solaris Format Checks 23323@subsection Solaris Format Checks 23324 23325Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format 23326check. @code{cmn_err} accepts a subset of the standard @code{printf} 23327conversions, and the two-argument @code{%b} conversion for displaying 23328bit-fields. See the Solaris man page for @code{cmn_err} for more information. 23329 23330@node Darwin Format Checks 23331@subsection Darwin Format Checks 23332 23333In addition to the full set of format archetypes (attribute format style 23334arguments such as @code{printf}, @code{scanf}, @code{strftime}, and 23335@code{strfmon}), Darwin targets also support the @code{CFString} (or 23336@code{__CFString__}) archetype in the @code{format} attribute. 23337Declarations with this archetype are parsed for correct syntax 23338and argument types. However, parsing of the format string itself and 23339validating arguments against it in calls to such functions is currently 23340not performed. 23341 23342Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may 23343also be used as format arguments. Note that the relevant headers are only likely to be 23344available on Darwin (OSX) installations. On such installations, the XCode and system 23345documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and 23346associated functions. 23347 23348@node Pragmas 23349@section Pragmas Accepted by GCC 23350@cindex pragmas 23351@cindex @code{#pragma} 23352 23353GCC supports several types of pragmas, primarily in order to compile 23354code originally written for other compilers. Note that in general 23355we do not recommend the use of pragmas; @xref{Function Attributes}, 23356for further explanation. 23357 23358The GNU C preprocessor recognizes several pragmas in addition to the 23359compiler pragmas documented here. Refer to the CPP manual for more 23360information. 23361 23362@menu 23363* AArch64 Pragmas:: 23364* ARM Pragmas:: 23365* M32C Pragmas:: 23366* MeP Pragmas:: 23367* PRU Pragmas:: 23368* RS/6000 and PowerPC Pragmas:: 23369* S/390 Pragmas:: 23370* Darwin Pragmas:: 23371* Solaris Pragmas:: 23372* Symbol-Renaming Pragmas:: 23373* Structure-Layout Pragmas:: 23374* Weak Pragmas:: 23375* Diagnostic Pragmas:: 23376* Visibility Pragmas:: 23377* Push/Pop Macro Pragmas:: 23378* Function Specific Option Pragmas:: 23379* Loop-Specific Pragmas:: 23380@end menu 23381 23382@node AArch64 Pragmas 23383@subsection AArch64 Pragmas 23384 23385The pragmas defined by the AArch64 target correspond to the AArch64 23386target function attributes. They can be specified as below: 23387@smallexample 23388#pragma GCC target("string") 23389@end smallexample 23390 23391where @code{@var{string}} can be any string accepted as an AArch64 target 23392attribute. @xref{AArch64 Function Attributes}, for more details 23393on the permissible values of @code{string}. 23394 23395@node ARM Pragmas 23396@subsection ARM Pragmas 23397 23398The ARM target defines pragmas for controlling the default addition of 23399@code{long_call} and @code{short_call} attributes to functions. 23400@xref{Function Attributes}, for information about the effects of these 23401attributes. 23402 23403@table @code 23404@item long_calls 23405@cindex pragma, long_calls 23406Set all subsequent functions to have the @code{long_call} attribute. 23407 23408@item no_long_calls 23409@cindex pragma, no_long_calls 23410Set all subsequent functions to have the @code{short_call} attribute. 23411 23412@item long_calls_off 23413@cindex pragma, long_calls_off 23414Do not affect the @code{long_call} or @code{short_call} attributes of 23415subsequent functions. 23416@end table 23417 23418@node M32C Pragmas 23419@subsection M32C Pragmas 23420 23421@table @code 23422@item GCC memregs @var{number} 23423@cindex pragma, memregs 23424Overrides the command-line option @code{-memregs=} for the current 23425file. Use with care! This pragma must be before any function in the 23426file, and mixing different memregs values in different objects may 23427make them incompatible. This pragma is useful when a 23428performance-critical function uses a memreg for temporary values, 23429as it may allow you to reduce the number of memregs used. 23430 23431@item ADDRESS @var{name} @var{address} 23432@cindex pragma, address 23433For any declared symbols matching @var{name}, this does three things 23434to that symbol: it forces the symbol to be located at the given 23435address (a number), it forces the symbol to be volatile, and it 23436changes the symbol's scope to be static. This pragma exists for 23437compatibility with other compilers, but note that the common 23438@code{1234H} numeric syntax is not supported (use @code{0x1234} 23439instead). Example: 23440 23441@smallexample 23442#pragma ADDRESS port3 0x103 23443char port3; 23444@end smallexample 23445 23446@end table 23447 23448@node MeP Pragmas 23449@subsection MeP Pragmas 23450 23451@table @code 23452 23453@item custom io_volatile (on|off) 23454@cindex pragma, custom io_volatile 23455Overrides the command-line option @code{-mio-volatile} for the current 23456file. Note that for compatibility with future GCC releases, this 23457option should only be used once before any @code{io} variables in each 23458file. 23459 23460@item GCC coprocessor available @var{registers} 23461@cindex pragma, coprocessor available 23462Specifies which coprocessor registers are available to the register 23463allocator. @var{registers} may be a single register, register range 23464separated by ellipses, or comma-separated list of those. Example: 23465 23466@smallexample 23467#pragma GCC coprocessor available $c0...$c10, $c28 23468@end smallexample 23469 23470@item GCC coprocessor call_saved @var{registers} 23471@cindex pragma, coprocessor call_saved 23472Specifies which coprocessor registers are to be saved and restored by 23473any function using them. @var{registers} may be a single register, 23474register range separated by ellipses, or comma-separated list of 23475those. Example: 23476 23477@smallexample 23478#pragma GCC coprocessor call_saved $c4...$c6, $c31 23479@end smallexample 23480 23481@item GCC coprocessor subclass '(A|B|C|D)' = @var{registers} 23482@cindex pragma, coprocessor subclass 23483Creates and defines a register class. These register classes can be 23484used by inline @code{asm} constructs. @var{registers} may be a single 23485register, register range separated by ellipses, or comma-separated 23486list of those. Example: 23487 23488@smallexample 23489#pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6 23490 23491asm ("cpfoo %0" : "=B" (x)); 23492@end smallexample 23493 23494@item GCC disinterrupt @var{name} , @var{name} @dots{} 23495@cindex pragma, disinterrupt 23496For the named functions, the compiler adds code to disable interrupts 23497for the duration of those functions. If any functions so named 23498are not encountered in the source, a warning is emitted that the pragma is 23499not used. Examples: 23500 23501@smallexample 23502#pragma disinterrupt foo 23503#pragma disinterrupt bar, grill 23504int foo () @{ @dots{} @} 23505@end smallexample 23506 23507@item GCC call @var{name} , @var{name} @dots{} 23508@cindex pragma, call 23509For the named functions, the compiler always uses a register-indirect 23510call model when calling the named functions. Examples: 23511 23512@smallexample 23513extern int foo (); 23514#pragma call foo 23515@end smallexample 23516 23517@end table 23518 23519@node PRU Pragmas 23520@subsection PRU Pragmas 23521 23522@table @code 23523 23524@item ctable_entry @var{index} @var{constant_address} 23525@cindex pragma, ctable_entry 23526Specifies that the PRU CTABLE entry given by @var{index} has the value 23527@var{constant_address}. This enables GCC to emit LBCO/SBCO instructions 23528when the load/store address is known and can be addressed with some CTABLE 23529entry. For example: 23530 23531@smallexample 23532/* will compile to "sbco Rx, 2, 0x10, 4" */ 23533#pragma ctable_entry 2 0x4802a000 23534*(unsigned int *)0x4802a010 = val; 23535@end smallexample 23536 23537@end table 23538 23539@node RS/6000 and PowerPC Pragmas 23540@subsection RS/6000 and PowerPC Pragmas 23541 23542The RS/6000 and PowerPC targets define one pragma for controlling 23543whether or not the @code{longcall} attribute is added to function 23544declarations by default. This pragma overrides the @option{-mlongcall} 23545option, but not the @code{longcall} and @code{shortcall} attributes. 23546@xref{RS/6000 and PowerPC Options}, for more information about when long 23547calls are and are not necessary. 23548 23549@table @code 23550@item longcall (1) 23551@cindex pragma, longcall 23552Apply the @code{longcall} attribute to all subsequent function 23553declarations. 23554 23555@item longcall (0) 23556Do not apply the @code{longcall} attribute to subsequent function 23557declarations. 23558@end table 23559 23560@c Describe h8300 pragmas here. 23561@c Describe sh pragmas here. 23562@c Describe v850 pragmas here. 23563 23564@node S/390 Pragmas 23565@subsection S/390 Pragmas 23566 23567The pragmas defined by the S/390 target correspond to the S/390 23568target function attributes and some the additional options: 23569 23570@table @samp 23571@item zvector 23572@itemx no-zvector 23573@end table 23574 23575Note that options of the pragma, unlike options of the target 23576attribute, do change the value of preprocessor macros like 23577@code{__VEC__}. They can be specified as below: 23578 23579@smallexample 23580#pragma GCC target("string[,string]...") 23581#pragma GCC target("string"[,"string"]...) 23582@end smallexample 23583 23584@node Darwin Pragmas 23585@subsection Darwin Pragmas 23586 23587The following pragmas are available for all architectures running the 23588Darwin operating system. These are useful for compatibility with other 23589Mac OS compilers. 23590 23591@table @code 23592@item mark @var{tokens}@dots{} 23593@cindex pragma, mark 23594This pragma is accepted, but has no effect. 23595 23596@item options align=@var{alignment} 23597@cindex pragma, options align 23598This pragma sets the alignment of fields in structures. The values of 23599@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or 23600@code{power}, to emulate PowerPC alignment. Uses of this pragma nest 23601properly; to restore the previous setting, use @code{reset} for the 23602@var{alignment}. 23603 23604@item segment @var{tokens}@dots{} 23605@cindex pragma, segment 23606This pragma is accepted, but has no effect. 23607 23608@item unused (@var{var} [, @var{var}]@dots{}) 23609@cindex pragma, unused 23610This pragma declares variables to be possibly unused. GCC does not 23611produce warnings for the listed variables. The effect is similar to 23612that of the @code{unused} attribute, except that this pragma may appear 23613anywhere within the variables' scopes. 23614@end table 23615 23616@node Solaris Pragmas 23617@subsection Solaris Pragmas 23618 23619The Solaris target supports @code{#pragma redefine_extname} 23620(@pxref{Symbol-Renaming Pragmas}). It also supports additional 23621@code{#pragma} directives for compatibility with the system compiler. 23622 23623@table @code 23624@item align @var{alignment} (@var{variable} [, @var{variable}]...) 23625@cindex pragma, align 23626 23627Increase the minimum alignment of each @var{variable} to @var{alignment}. 23628This is the same as GCC's @code{aligned} attribute @pxref{Variable 23629Attributes}). Macro expansion occurs on the arguments to this pragma 23630when compiling C and Objective-C@. It does not currently occur when 23631compiling C++, but this is a bug which may be fixed in a future 23632release. 23633 23634@item fini (@var{function} [, @var{function}]...) 23635@cindex pragma, fini 23636 23637This pragma causes each listed @var{function} to be called after 23638main, or during shared module unloading, by adding a call to the 23639@code{.fini} section. 23640 23641@item init (@var{function} [, @var{function}]...) 23642@cindex pragma, init 23643 23644This pragma causes each listed @var{function} to be called during 23645initialization (before @code{main}) or during shared module loading, by 23646adding a call to the @code{.init} section. 23647 23648@end table 23649 23650@node Symbol-Renaming Pragmas 23651@subsection Symbol-Renaming Pragmas 23652 23653GCC supports a @code{#pragma} directive that changes the name used in 23654assembly for a given declaration. While this pragma is supported on all 23655platforms, it is intended primarily to provide compatibility with the 23656Solaris system headers. This effect can also be achieved using the asm 23657labels extension (@pxref{Asm Labels}). 23658 23659@table @code 23660@item redefine_extname @var{oldname} @var{newname} 23661@cindex pragma, redefine_extname 23662 23663This pragma gives the C function @var{oldname} the assembly symbol 23664@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} 23665is defined if this pragma is available (currently on all platforms). 23666@end table 23667 23668This pragma and the @code{asm} labels extension interact in a complicated 23669manner. Here are some corner cases you may want to be aware of: 23670 23671@enumerate 23672@item This pragma silently applies only to declarations with external 23673linkage. The @code{asm} label feature does not have this restriction. 23674 23675@item In C++, this pragma silently applies only to declarations with 23676``C'' linkage. Again, @code{asm} labels do not have this restriction. 23677 23678@item If either of the ways of changing the assembly name of a 23679declaration are applied to a declaration whose assembly name has 23680already been determined (either by a previous use of one of these 23681features, or because the compiler needed the assembly name in order to 23682generate code), and the new name is different, a warning issues and 23683the name does not change. 23684 23685@item The @var{oldname} used by @code{#pragma redefine_extname} is 23686always the C-language name. 23687@end enumerate 23688 23689@node Structure-Layout Pragmas 23690@subsection Structure-Layout Pragmas 23691 23692For compatibility with Microsoft Windows compilers, GCC supports a 23693set of @code{#pragma} directives that change the maximum alignment of 23694members of structures (other than zero-width bit-fields), unions, and 23695classes subsequently defined. The @var{n} value below always is required 23696to be a small power of two and specifies the new alignment in bytes. 23697 23698@enumerate 23699@item @code{#pragma pack(@var{n})} simply sets the new alignment. 23700@item @code{#pragma pack()} sets the alignment to the one that was in 23701effect when compilation started (see also command-line option 23702@option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}). 23703@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment 23704setting on an internal stack and then optionally sets the new alignment. 23705@item @code{#pragma pack(pop)} restores the alignment setting to the one 23706saved at the top of the internal stack (and removes that stack entry). 23707Note that @code{#pragma pack([@var{n}])} does not influence this internal 23708stack; thus it is possible to have @code{#pragma pack(push)} followed by 23709multiple @code{#pragma pack(@var{n})} instances and finalized by a single 23710@code{#pragma pack(pop)}. 23711@end enumerate 23712 23713Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct} 23714directive which lays out structures and unions subsequently defined as the 23715documented @code{__attribute__ ((ms_struct))}. 23716 23717@enumerate 23718@item @code{#pragma ms_struct on} turns on the Microsoft layout. 23719@item @code{#pragma ms_struct off} turns off the Microsoft layout. 23720@item @code{#pragma ms_struct reset} goes back to the default layout. 23721@end enumerate 23722 23723Most targets also support the @code{#pragma scalar_storage_order} directive 23724which lays out structures and unions subsequently defined as the documented 23725@code{__attribute__ ((scalar_storage_order))}. 23726 23727@enumerate 23728@item @code{#pragma scalar_storage_order big-endian} sets the storage order 23729of the scalar fields to big-endian. 23730@item @code{#pragma scalar_storage_order little-endian} sets the storage order 23731of the scalar fields to little-endian. 23732@item @code{#pragma scalar_storage_order default} goes back to the endianness 23733that was in effect when compilation started (see also command-line option 23734@option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}). 23735@end enumerate 23736 23737@node Weak Pragmas 23738@subsection Weak Pragmas 23739 23740For compatibility with SVR4, GCC supports a set of @code{#pragma} 23741directives for declaring symbols to be weak, and defining weak 23742aliases. 23743 23744@table @code 23745@item #pragma weak @var{symbol} 23746@cindex pragma, weak 23747This pragma declares @var{symbol} to be weak, as if the declaration 23748had the attribute of the same name. The pragma may appear before 23749or after the declaration of @var{symbol}. It is not an error for 23750@var{symbol} to never be defined at all. 23751 23752@item #pragma weak @var{symbol1} = @var{symbol2} 23753This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. 23754It is an error if @var{symbol2} is not defined in the current 23755translation unit. 23756@end table 23757 23758@node Diagnostic Pragmas 23759@subsection Diagnostic Pragmas 23760 23761GCC allows the user to selectively enable or disable certain types of 23762diagnostics, and change the kind of the diagnostic. For example, a 23763project's policy might require that all sources compile with 23764@option{-Werror} but certain files might have exceptions allowing 23765specific types of warnings. Or, a project might selectively enable 23766diagnostics and treat them as errors depending on which preprocessor 23767macros are defined. 23768 23769@table @code 23770@item #pragma GCC diagnostic @var{kind} @var{option} 23771@cindex pragma, diagnostic 23772 23773Modifies the disposition of a diagnostic. Note that not all 23774diagnostics are modifiable; at the moment only warnings (normally 23775controlled by @samp{-W@dots{}}) can be controlled, and not all of them. 23776Use @option{-fdiagnostics-show-option} to determine which diagnostics 23777are controllable and which option controls them. 23778 23779@var{kind} is @samp{error} to treat this diagnostic as an error, 23780@samp{warning} to treat it like a warning (even if @option{-Werror} is 23781in effect), or @samp{ignored} if the diagnostic is to be ignored. 23782@var{option} is a double quoted string that matches the command-line 23783option. 23784 23785@smallexample 23786#pragma GCC diagnostic warning "-Wformat" 23787#pragma GCC diagnostic error "-Wformat" 23788#pragma GCC diagnostic ignored "-Wformat" 23789@end smallexample 23790 23791Note that these pragmas override any command-line options. GCC keeps 23792track of the location of each pragma, and issues diagnostics according 23793to the state as of that point in the source file. Thus, pragmas occurring 23794after a line do not affect diagnostics caused by that line. 23795 23796@item #pragma GCC diagnostic push 23797@itemx #pragma GCC diagnostic pop 23798 23799Causes GCC to remember the state of the diagnostics as of each 23800@code{push}, and restore to that point at each @code{pop}. If a 23801@code{pop} has no matching @code{push}, the command-line options are 23802restored. 23803 23804@smallexample 23805#pragma GCC diagnostic error "-Wuninitialized" 23806 foo(a); /* error is given for this one */ 23807#pragma GCC diagnostic push 23808#pragma GCC diagnostic ignored "-Wuninitialized" 23809 foo(b); /* no diagnostic for this one */ 23810#pragma GCC diagnostic pop 23811 foo(c); /* error is given for this one */ 23812#pragma GCC diagnostic pop 23813 foo(d); /* depends on command-line options */ 23814@end smallexample 23815 23816@end table 23817 23818GCC also offers a simple mechanism for printing messages during 23819compilation. 23820 23821@table @code 23822@item #pragma message @var{string} 23823@cindex pragma, diagnostic 23824 23825Prints @var{string} as a compiler message on compilation. The message 23826is informational only, and is neither a compilation warning nor an 23827error. Newlines can be included in the string by using the @samp{\n} 23828escape sequence. 23829 23830@smallexample 23831#pragma message "Compiling " __FILE__ "..." 23832@end smallexample 23833 23834@var{string} may be parenthesized, and is printed with location 23835information. For example, 23836 23837@smallexample 23838#define DO_PRAGMA(x) _Pragma (#x) 23839#define TODO(x) DO_PRAGMA(message ("TODO - " #x)) 23840 23841TODO(Remember to fix this) 23842@end smallexample 23843 23844@noindent 23845prints @samp{/tmp/file.c:4: note: #pragma message: 23846TODO - Remember to fix this}. 23847 23848@item #pragma GCC error @var{message} 23849@cindex pragma, diagnostic 23850Generates an error message. This pragma @emph{is} considered to 23851indicate an error in the compilation, and it will be treated as such. 23852 23853Newlines can be included in the string by using the @samp{\n} 23854escape sequence. They will be displayed as newlines even if the 23855@option{-fmessage-length} option is set to zero. 23856 23857The error is only generated if the pragma is present in the code after 23858pre-processing has been completed. It does not matter however if the 23859code containing the pragma is unreachable: 23860 23861@smallexample 23862#if 0 23863#pragma GCC error "this error is not seen" 23864#endif 23865void foo (void) 23866@{ 23867 return; 23868#pragma GCC error "this error is seen" 23869@} 23870@end smallexample 23871 23872@item #pragma GCC warning @var{message} 23873@cindex pragma, diagnostic 23874This is just like @samp{pragma GCC error} except that a warning 23875message is issued instead of an error message. Unless 23876@option{-Werror} is in effect, in which case this pragma will generate 23877an error as well. 23878 23879@end table 23880 23881@node Visibility Pragmas 23882@subsection Visibility Pragmas 23883 23884@table @code 23885@item #pragma GCC visibility push(@var{visibility}) 23886@itemx #pragma GCC visibility pop 23887@cindex pragma, visibility 23888 23889This pragma allows the user to set the visibility for multiple 23890declarations without having to give each a visibility attribute 23891(@pxref{Function Attributes}). 23892 23893In C++, @samp{#pragma GCC visibility} affects only namespace-scope 23894declarations. Class members and template specializations are not 23895affected; if you want to override the visibility for a particular 23896member or instantiation, you must use an attribute. 23897 23898@end table 23899 23900 23901@node Push/Pop Macro Pragmas 23902@subsection Push/Pop Macro Pragmas 23903 23904For compatibility with Microsoft Windows compilers, GCC supports 23905@samp{#pragma push_macro(@var{"macro_name"})} 23906and @samp{#pragma pop_macro(@var{"macro_name"})}. 23907 23908@table @code 23909@item #pragma push_macro(@var{"macro_name"}) 23910@cindex pragma, push_macro 23911This pragma saves the value of the macro named as @var{macro_name} to 23912the top of the stack for this macro. 23913 23914@item #pragma pop_macro(@var{"macro_name"}) 23915@cindex pragma, pop_macro 23916This pragma sets the value of the macro named as @var{macro_name} to 23917the value on top of the stack for this macro. If the stack for 23918@var{macro_name} is empty, the value of the macro remains unchanged. 23919@end table 23920 23921For example: 23922 23923@smallexample 23924#define X 1 23925#pragma push_macro("X") 23926#undef X 23927#define X -1 23928#pragma pop_macro("X") 23929int x [X]; 23930@end smallexample 23931 23932@noindent 23933In this example, the definition of X as 1 is saved by @code{#pragma 23934push_macro} and restored by @code{#pragma pop_macro}. 23935 23936@node Function Specific Option Pragmas 23937@subsection Function Specific Option Pragmas 23938 23939@table @code 23940@item #pragma GCC target (@var{string}, @dots{}) 23941@cindex pragma GCC target 23942 23943This pragma allows you to set target-specific options for functions 23944defined later in the source file. One or more strings can be 23945specified. Each function that is defined after this point is treated 23946as if it had been declared with one @code{target(}@var{string}@code{)} 23947attribute for each @var{string} argument. The parentheses around 23948the strings in the pragma are optional. @xref{Function Attributes}, 23949for more information about the @code{target} attribute and the attribute 23950syntax. 23951 23952The @code{#pragma GCC target} pragma is presently implemented for 23953x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only. 23954 23955@item #pragma GCC optimize (@var{string}, @dots{}) 23956@cindex pragma GCC optimize 23957 23958This pragma allows you to set global optimization options for functions 23959defined later in the source file. One or more strings can be 23960specified. Each function that is defined after this point is treated 23961as if it had been declared with one @code{optimize(}@var{string}@code{)} 23962attribute for each @var{string} argument. The parentheses around 23963the strings in the pragma are optional. @xref{Function Attributes}, 23964for more information about the @code{optimize} attribute and the attribute 23965syntax. 23966 23967@item #pragma GCC push_options 23968@itemx #pragma GCC pop_options 23969@cindex pragma GCC push_options 23970@cindex pragma GCC pop_options 23971 23972These pragmas maintain a stack of the current target and optimization 23973options. It is intended for include files where you temporarily want 23974to switch to using a different @samp{#pragma GCC target} or 23975@samp{#pragma GCC optimize} and then to pop back to the previous 23976options. 23977 23978@item #pragma GCC reset_options 23979@cindex pragma GCC reset_options 23980 23981This pragma clears the current @code{#pragma GCC target} and 23982@code{#pragma GCC optimize} to use the default switches as specified 23983on the command line. 23984 23985@end table 23986 23987@node Loop-Specific Pragmas 23988@subsection Loop-Specific Pragmas 23989 23990@table @code 23991@item #pragma GCC ivdep 23992@cindex pragma GCC ivdep 23993 23994With this pragma, the programmer asserts that there are no loop-carried 23995dependencies which would prevent consecutive iterations of 23996the following loop from executing concurrently with SIMD 23997(single instruction multiple data) instructions. 23998 23999For example, the compiler can only unconditionally vectorize the following 24000loop with the pragma: 24001 24002@smallexample 24003void foo (int n, int *a, int *b, int *c) 24004@{ 24005 int i, j; 24006#pragma GCC ivdep 24007 for (i = 0; i < n; ++i) 24008 a[i] = b[i] + c[i]; 24009@} 24010@end smallexample 24011 24012@noindent 24013In this example, using the @code{restrict} qualifier had the same 24014effect. In the following example, that would not be possible. Assume 24015@math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows 24016that it can unconditionally vectorize the following loop: 24017 24018@smallexample 24019void ignore_vec_dep (int *a, int k, int c, int m) 24020@{ 24021#pragma GCC ivdep 24022 for (int i = 0; i < m; i++) 24023 a[i] = a[i + k] * c; 24024@} 24025@end smallexample 24026 24027@item #pragma GCC unroll @var{n} 24028@cindex pragma GCC unroll @var{n} 24029 24030You can use this pragma to control how many times a loop should be unrolled. 24031It must be placed immediately before a @code{for}, @code{while} or @code{do} 24032loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows. 24033@var{n} is an integer constant expression specifying the unrolling factor. 24034The values of @math{0} and @math{1} block any unrolling of the loop. 24035 24036@end table 24037 24038@node Unnamed Fields 24039@section Unnamed Structure and Union Fields 24040@cindex @code{struct} 24041@cindex @code{union} 24042 24043As permitted by ISO C11 and for compatibility with other compilers, 24044GCC allows you to define 24045a structure or union that contains, as fields, structures and unions 24046without names. For example: 24047 24048@smallexample 24049struct @{ 24050 int a; 24051 union @{ 24052 int b; 24053 float c; 24054 @}; 24055 int d; 24056@} foo; 24057@end smallexample 24058 24059@noindent 24060In this example, you are able to access members of the unnamed 24061union with code like @samp{foo.b}. Note that only unnamed structs and 24062unions are allowed, you may not have, for example, an unnamed 24063@code{int}. 24064 24065You must never create such structures that cause ambiguous field definitions. 24066For example, in this structure: 24067 24068@smallexample 24069struct @{ 24070 int a; 24071 struct @{ 24072 int a; 24073 @}; 24074@} foo; 24075@end smallexample 24076 24077@noindent 24078it is ambiguous which @code{a} is being referred to with @samp{foo.a}. 24079The compiler gives errors for such constructs. 24080 24081@opindex fms-extensions 24082Unless @option{-fms-extensions} is used, the unnamed field must be a 24083structure or union definition without a tag (for example, @samp{struct 24084@{ int a; @};}). If @option{-fms-extensions} is used, the field may 24085also be a definition with a tag such as @samp{struct foo @{ int a; 24086@};}, a reference to a previously defined structure or union such as 24087@samp{struct foo;}, or a reference to a @code{typedef} name for a 24088previously defined structure or union type. 24089 24090@opindex fplan9-extensions 24091The option @option{-fplan9-extensions} enables 24092@option{-fms-extensions} as well as two other extensions. First, a 24093pointer to a structure is automatically converted to a pointer to an 24094anonymous field for assignments and function calls. For example: 24095 24096@smallexample 24097struct s1 @{ int a; @}; 24098struct s2 @{ struct s1; @}; 24099extern void f1 (struct s1 *); 24100void f2 (struct s2 *p) @{ f1 (p); @} 24101@end smallexample 24102 24103@noindent 24104In the call to @code{f1} inside @code{f2}, the pointer @code{p} is 24105converted into a pointer to the anonymous field. 24106 24107Second, when the type of an anonymous field is a @code{typedef} for a 24108@code{struct} or @code{union}, code may refer to the field using the 24109name of the @code{typedef}. 24110 24111@smallexample 24112typedef struct @{ int a; @} s1; 24113struct s2 @{ s1; @}; 24114s1 f1 (struct s2 *p) @{ return p->s1; @} 24115@end smallexample 24116 24117These usages are only permitted when they are not ambiguous. 24118 24119@node Thread-Local 24120@section Thread-Local Storage 24121@cindex Thread-Local Storage 24122@cindex @acronym{TLS} 24123@cindex @code{__thread} 24124 24125Thread-local storage (@acronym{TLS}) is a mechanism by which variables 24126are allocated such that there is one instance of the variable per extant 24127thread. The runtime model GCC uses to implement this originates 24128in the IA-64 processor-specific ABI, but has since been migrated 24129to other processors as well. It requires significant support from 24130the linker (@command{ld}), dynamic linker (@command{ld.so}), and 24131system libraries (@file{libc.so} and @file{libpthread.so}), so it 24132is not available everywhere. 24133 24134At the user level, the extension is visible with a new storage 24135class keyword: @code{__thread}. For example: 24136 24137@smallexample 24138__thread int i; 24139extern __thread struct state s; 24140static __thread char *p; 24141@end smallexample 24142 24143The @code{__thread} specifier may be used alone, with the @code{extern} 24144or @code{static} specifiers, but with no other storage class specifier. 24145When used with @code{extern} or @code{static}, @code{__thread} must appear 24146immediately after the other storage class specifier. 24147 24148The @code{__thread} specifier may be applied to any global, file-scoped 24149static, function-scoped static, or static data member of a class. It may 24150not be applied to block-scoped automatic or non-static data member. 24151 24152When the address-of operator is applied to a thread-local variable, it is 24153evaluated at run time and returns the address of the current thread's 24154instance of that variable. An address so obtained may be used by any 24155thread. When a thread terminates, any pointers to thread-local variables 24156in that thread become invalid. 24157 24158No static initialization may refer to the address of a thread-local variable. 24159 24160In C++, if an initializer is present for a thread-local variable, it must 24161be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ 24162standard. 24163 24164See @uref{https://www.akkadia.org/drepper/tls.pdf, 24165ELF Handling For Thread-Local Storage} for a detailed explanation of 24166the four thread-local storage addressing models, and how the runtime 24167is expected to function. 24168 24169@menu 24170* C99 Thread-Local Edits:: 24171* C++98 Thread-Local Edits:: 24172@end menu 24173 24174@node C99 Thread-Local Edits 24175@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage 24176 24177The following are a set of changes to ISO/IEC 9899:1999 (aka C99) 24178that document the exact semantics of the language extension. 24179 24180@itemize @bullet 24181@item 24182@cite{5.1.2 Execution environments} 24183 24184Add new text after paragraph 1 24185 24186@quotation 24187Within either execution environment, a @dfn{thread} is a flow of 24188control within a program. It is implementation defined whether 24189or not there may be more than one thread associated with a program. 24190It is implementation defined how threads beyond the first are 24191created, the name and type of the function called at thread 24192startup, and how threads may be terminated. However, objects 24193with thread storage duration shall be initialized before thread 24194startup. 24195@end quotation 24196 24197@item 24198@cite{6.2.4 Storage durations of objects} 24199 24200Add new text before paragraph 3 24201 24202@quotation 24203An object whose identifier is declared with the storage-class 24204specifier @w{@code{__thread}} has @dfn{thread storage duration}. 24205Its lifetime is the entire execution of the thread, and its 24206stored value is initialized only once, prior to thread startup. 24207@end quotation 24208 24209@item 24210@cite{6.4.1 Keywords} 24211 24212Add @code{__thread}. 24213 24214@item 24215@cite{6.7.1 Storage-class specifiers} 24216 24217Add @code{__thread} to the list of storage class specifiers in 24218paragraph 1. 24219 24220Change paragraph 2 to 24221 24222@quotation 24223With the exception of @code{__thread}, at most one storage-class 24224specifier may be given [@dots{}]. The @code{__thread} specifier may 24225be used alone, or immediately following @code{extern} or 24226@code{static}. 24227@end quotation 24228 24229Add new text after paragraph 6 24230 24231@quotation 24232The declaration of an identifier for a variable that has 24233block scope that specifies @code{__thread} shall also 24234specify either @code{extern} or @code{static}. 24235 24236The @code{__thread} specifier shall be used only with 24237variables. 24238@end quotation 24239@end itemize 24240 24241@node C++98 Thread-Local Edits 24242@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage 24243 24244The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) 24245that document the exact semantics of the language extension. 24246 24247@itemize @bullet 24248@item 24249@b{[intro.execution]} 24250 24251New text after paragraph 4 24252 24253@quotation 24254A @dfn{thread} is a flow of control within the abstract machine. 24255It is implementation defined whether or not there may be more than 24256one thread. 24257@end quotation 24258 24259New text after paragraph 7 24260 24261@quotation 24262It is unspecified whether additional action must be taken to 24263ensure when and whether side effects are visible to other threads. 24264@end quotation 24265 24266@item 24267@b{[lex.key]} 24268 24269Add @code{__thread}. 24270 24271@item 24272@b{[basic.start.main]} 24273 24274Add after paragraph 5 24275 24276@quotation 24277The thread that begins execution at the @code{main} function is called 24278the @dfn{main thread}. It is implementation defined how functions 24279beginning threads other than the main thread are designated or typed. 24280A function so designated, as well as the @code{main} function, is called 24281a @dfn{thread startup function}. It is implementation defined what 24282happens if a thread startup function returns. It is implementation 24283defined what happens to other threads when any thread calls @code{exit}. 24284@end quotation 24285 24286@item 24287@b{[basic.start.init]} 24288 24289Add after paragraph 4 24290 24291@quotation 24292The storage for an object of thread storage duration shall be 24293statically initialized before the first statement of the thread startup 24294function. An object of thread storage duration shall not require 24295dynamic initialization. 24296@end quotation 24297 24298@item 24299@b{[basic.start.term]} 24300 24301Add after paragraph 3 24302 24303@quotation 24304The type of an object with thread storage duration shall not have a 24305non-trivial destructor, nor shall it be an array type whose elements 24306(directly or indirectly) have non-trivial destructors. 24307@end quotation 24308 24309@item 24310@b{[basic.stc]} 24311 24312Add ``thread storage duration'' to the list in paragraph 1. 24313 24314Change paragraph 2 24315 24316@quotation 24317Thread, static, and automatic storage durations are associated with 24318objects introduced by declarations [@dots{}]. 24319@end quotation 24320 24321Add @code{__thread} to the list of specifiers in paragraph 3. 24322 24323@item 24324@b{[basic.stc.thread]} 24325 24326New section before @b{[basic.stc.static]} 24327 24328@quotation 24329The keyword @code{__thread} applied to a non-local object gives the 24330object thread storage duration. 24331 24332A local variable or class data member declared both @code{static} 24333and @code{__thread} gives the variable or member thread storage 24334duration. 24335@end quotation 24336 24337@item 24338@b{[basic.stc.static]} 24339 24340Change paragraph 1 24341 24342@quotation 24343All objects that have neither thread storage duration, dynamic 24344storage duration nor are local [@dots{}]. 24345@end quotation 24346 24347@item 24348@b{[dcl.stc]} 24349 24350Add @code{__thread} to the list in paragraph 1. 24351 24352Change paragraph 1 24353 24354@quotation 24355With the exception of @code{__thread}, at most one 24356@var{storage-class-specifier} shall appear in a given 24357@var{decl-specifier-seq}. The @code{__thread} specifier may 24358be used alone, or immediately following the @code{extern} or 24359@code{static} specifiers. [@dots{}] 24360@end quotation 24361 24362Add after paragraph 5 24363 24364@quotation 24365The @code{__thread} specifier can be applied only to the names of objects 24366and to anonymous unions. 24367@end quotation 24368 24369@item 24370@b{[class.mem]} 24371 24372Add after paragraph 6 24373 24374@quotation 24375Non-@code{static} members shall not be @code{__thread}. 24376@end quotation 24377@end itemize 24378 24379@node Binary constants 24380@section Binary Constants using the @samp{0b} Prefix 24381@cindex Binary constants using the @samp{0b} prefix 24382 24383Integer constants can be written as binary constants, consisting of a 24384sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or 24385@samp{0B}. This is particularly useful in environments that operate a 24386lot on the bit level (like microcontrollers). 24387 24388The following statements are identical: 24389 24390@smallexample 24391i = 42; 24392i = 0x2a; 24393i = 052; 24394i = 0b101010; 24395@end smallexample 24396 24397The type of these constants follows the same rules as for octal or 24398hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} 24399can be applied. 24400 24401@node C++ Extensions 24402@chapter Extensions to the C++ Language 24403@cindex extensions, C++ language 24404@cindex C++ language extensions 24405 24406The GNU compiler provides these extensions to the C++ language (and you 24407can also use most of the C language extensions in your C++ programs). If you 24408want to write code that checks whether these features are available, you can 24409test for the GNU compiler the same way as for C programs: check for a 24410predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to 24411test specifically for GNU C++ (@pxref{Common Predefined Macros,, 24412Predefined Macros,cpp,The GNU C Preprocessor}). 24413 24414@menu 24415* C++ Volatiles:: What constitutes an access to a volatile object. 24416* Restricted Pointers:: C99 restricted pointers and references. 24417* Vague Linkage:: Where G++ puts inlines, vtables and such. 24418* C++ Interface:: You can use a single C++ header file for both 24419 declarations and definitions. 24420* Template Instantiation:: Methods for ensuring that exactly one copy of 24421 each needed template instantiation is emitted. 24422* Bound member functions:: You can extract a function pointer to the 24423 method denoted by a @samp{->*} or @samp{.*} expression. 24424* C++ Attributes:: Variable, function, and type attributes for C++ only. 24425* Function Multiversioning:: Declaring multiple function versions. 24426* Type Traits:: Compiler support for type traits. 24427* C++ Concepts:: Improved support for generic programming. 24428* Deprecated Features:: Things will disappear from G++. 24429* Backwards Compatibility:: Compatibilities with earlier definitions of C++. 24430@end menu 24431 24432@node C++ Volatiles 24433@section When is a Volatile C++ Object Accessed? 24434@cindex accessing volatiles 24435@cindex volatile read 24436@cindex volatile write 24437@cindex volatile access 24438 24439The C++ standard differs from the C standard in its treatment of 24440volatile objects. It fails to specify what constitutes a volatile 24441access, except to say that C++ should behave in a similar manner to C 24442with respect to volatiles, where possible. However, the different 24443lvalueness of expressions between C and C++ complicate the behavior. 24444G++ behaves the same as GCC for volatile access, @xref{C 24445Extensions,,Volatiles}, for a description of GCC's behavior. 24446 24447The C and C++ language specifications differ when an object is 24448accessed in a void context: 24449 24450@smallexample 24451volatile int *src = @var{somevalue}; 24452*src; 24453@end smallexample 24454 24455The C++ standard specifies that such expressions do not undergo lvalue 24456to rvalue conversion, and that the type of the dereferenced object may 24457be incomplete. The C++ standard does not specify explicitly that it 24458is lvalue to rvalue conversion that is responsible for causing an 24459access. There is reason to believe that it is, because otherwise 24460certain simple expressions become undefined. However, because it 24461would surprise most programmers, G++ treats dereferencing a pointer to 24462volatile object of complete type as GCC would do for an equivalent 24463type in C@. When the object has incomplete type, G++ issues a 24464warning; if you wish to force an error, you must force a conversion to 24465rvalue with, for instance, a static cast. 24466 24467When using a reference to volatile, G++ does not treat equivalent 24468expressions as accesses to volatiles, but instead issues a warning that 24469no volatile is accessed. The rationale for this is that otherwise it 24470becomes difficult to determine where volatile access occur, and not 24471possible to ignore the return value from functions returning volatile 24472references. Again, if you wish to force a read, cast the reference to 24473an rvalue. 24474 24475G++ implements the same behavior as GCC does when assigning to a 24476volatile object---there is no reread of the assigned-to object, the 24477assigned rvalue is reused. Note that in C++ assignment expressions 24478are lvalues, and if used as an lvalue, the volatile object is 24479referred to. For instance, @var{vref} refers to @var{vobj}, as 24480expected, in the following example: 24481 24482@smallexample 24483volatile int vobj; 24484volatile int &vref = vobj = @var{something}; 24485@end smallexample 24486 24487@node Restricted Pointers 24488@section Restricting Pointer Aliasing 24489@cindex restricted pointers 24490@cindex restricted references 24491@cindex restricted this pointer 24492 24493As with the C front end, G++ understands the C99 feature of restricted pointers, 24494specified with the @code{__restrict__}, or @code{__restrict} type 24495qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} 24496language flag, @code{restrict} is not a keyword in C++. 24497 24498In addition to allowing restricted pointers, you can specify restricted 24499references, which indicate that the reference is not aliased in the local 24500context. 24501 24502@smallexample 24503void fn (int *__restrict__ rptr, int &__restrict__ rref) 24504@{ 24505 /* @r{@dots{}} */ 24506@} 24507@end smallexample 24508 24509@noindent 24510In the body of @code{fn}, @var{rptr} points to an unaliased integer and 24511@var{rref} refers to a (different) unaliased integer. 24512 24513You may also specify whether a member function's @var{this} pointer is 24514unaliased by using @code{__restrict__} as a member function qualifier. 24515 24516@smallexample 24517void T::fn () __restrict__ 24518@{ 24519 /* @r{@dots{}} */ 24520@} 24521@end smallexample 24522 24523@noindent 24524Within the body of @code{T::fn}, @var{this} has the effective 24525definition @code{T *__restrict__ const this}. Notice that the 24526interpretation of a @code{__restrict__} member function qualifier is 24527different to that of @code{const} or @code{volatile} qualifier, in that it 24528is applied to the pointer rather than the object. This is consistent with 24529other compilers that implement restricted pointers. 24530 24531As with all outermost parameter qualifiers, @code{__restrict__} is 24532ignored in function definition matching. This means you only need to 24533specify @code{__restrict__} in a function definition, rather than 24534in a function prototype as well. 24535 24536@node Vague Linkage 24537@section Vague Linkage 24538@cindex vague linkage 24539 24540There are several constructs in C++ that require space in the object 24541file but are not clearly tied to a single translation unit. We say that 24542these constructs have ``vague linkage''. Typically such constructs are 24543emitted wherever they are needed, though sometimes we can be more 24544clever. 24545 24546@table @asis 24547@item Inline Functions 24548Inline functions are typically defined in a header file which can be 24549included in many different compilations. Hopefully they can usually be 24550inlined, but sometimes an out-of-line copy is necessary, if the address 24551of the function is taken or if inlining fails. In general, we emit an 24552out-of-line copy in all translation units where one is needed. As an 24553exception, we only emit inline virtual functions with the vtable, since 24554it always requires a copy. 24555 24556Local static variables and string constants used in an inline function 24557are also considered to have vague linkage, since they must be shared 24558between all inlined and out-of-line instances of the function. 24559 24560@item VTables 24561@cindex vtable 24562C++ virtual functions are implemented in most compilers using a lookup 24563table, known as a vtable. The vtable contains pointers to the virtual 24564functions provided by a class, and each object of the class contains a 24565pointer to its vtable (or vtables, in some multiple-inheritance 24566situations). If the class declares any non-inline, non-pure virtual 24567functions, the first one is chosen as the ``key method'' for the class, 24568and the vtable is only emitted in the translation unit where the key 24569method is defined. 24570 24571@emph{Note:} If the chosen key method is later defined as inline, the 24572vtable is still emitted in every translation unit that defines it. 24573Make sure that any inline virtuals are declared inline in the class 24574body, even if they are not defined there. 24575 24576@item @code{type_info} objects 24577@cindex @code{type_info} 24578@cindex RTTI 24579C++ requires information about types to be written out in order to 24580implement @samp{dynamic_cast}, @samp{typeid} and exception handling. 24581For polymorphic classes (classes with virtual functions), the @samp{type_info} 24582object is written out along with the vtable so that @samp{dynamic_cast} 24583can determine the dynamic type of a class object at run time. For all 24584other types, we write out the @samp{type_info} object when it is used: when 24585applying @samp{typeid} to an expression, throwing an object, or 24586referring to a type in a catch clause or exception specification. 24587 24588@item Template Instantiations 24589Most everything in this section also applies to template instantiations, 24590but there are other options as well. 24591@xref{Template Instantiation,,Where's the Template?}. 24592 24593@end table 24594 24595When used with GNU ld version 2.8 or later on an ELF system such as 24596GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of 24597these constructs will be discarded at link time. This is known as 24598COMDAT support. 24599 24600On targets that don't support COMDAT, but do support weak symbols, GCC 24601uses them. This way one copy overrides all the others, but 24602the unused copies still take up space in the executable. 24603 24604For targets that do not support either COMDAT or weak symbols, 24605most entities with vague linkage are emitted as local symbols to 24606avoid duplicate definition errors from the linker. This does not happen 24607for local statics in inlines, however, as having multiple copies 24608almost certainly breaks things. 24609 24610@xref{C++ Interface,,Declarations and Definitions in One Header}, for 24611another way to control placement of these constructs. 24612 24613@node C++ Interface 24614@section C++ Interface and Implementation Pragmas 24615 24616@cindex interface and implementation headers, C++ 24617@cindex C++ interface and implementation headers 24618@cindex pragmas, interface and implementation 24619 24620@code{#pragma interface} and @code{#pragma implementation} provide the 24621user with a way of explicitly directing the compiler to emit entities 24622with vague linkage (and debugging information) in a particular 24623translation unit. 24624 24625@emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2 24626by COMDAT support and the ``key method'' heuristic 24627mentioned in @ref{Vague Linkage}. Using them can actually cause your 24628program to grow due to unnecessary out-of-line copies of inline 24629functions. 24630 24631@table @code 24632@item #pragma interface 24633@itemx #pragma interface "@var{subdir}/@var{objects}.h" 24634@kindex #pragma interface 24635Use this directive in @emph{header files} that define object classes, to save 24636space in most of the object files that use those classes. Normally, 24637local copies of certain information (backup copies of inline member 24638functions, debugging information, and the internal tables that implement 24639virtual functions) must be kept in each object file that includes class 24640definitions. You can use this pragma to avoid such duplication. When a 24641header file containing @samp{#pragma interface} is included in a 24642compilation, this auxiliary information is not generated (unless 24643the main input source file itself uses @samp{#pragma implementation}). 24644Instead, the object files contain references to be resolved at link 24645time. 24646 24647The second form of this directive is useful for the case where you have 24648multiple headers with the same name in different directories. If you 24649use this form, you must specify the same string to @samp{#pragma 24650implementation}. 24651 24652@item #pragma implementation 24653@itemx #pragma implementation "@var{objects}.h" 24654@kindex #pragma implementation 24655Use this pragma in a @emph{main input file}, when you want full output from 24656included header files to be generated (and made globally visible). The 24657included header file, in turn, should use @samp{#pragma interface}. 24658Backup copies of inline member functions, debugging information, and the 24659internal tables used to implement virtual functions are all generated in 24660implementation files. 24661 24662@cindex implied @code{#pragma implementation} 24663@cindex @code{#pragma implementation}, implied 24664@cindex naming convention, implementation headers 24665If you use @samp{#pragma implementation} with no argument, it applies to 24666an include file with the same basename@footnote{A file's @dfn{basename} 24667is the name stripped of all leading path information and of trailing 24668suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source 24669file. For example, in @file{allclass.cc}, giving just 24670@samp{#pragma implementation} 24671by itself is equivalent to @samp{#pragma implementation "allclass.h"}. 24672 24673Use the string argument if you want a single implementation file to 24674include code from multiple header files. (You must also use 24675@samp{#include} to include the header file; @samp{#pragma 24676implementation} only specifies how to use the file---it doesn't actually 24677include it.) 24678 24679There is no way to split up the contents of a single header file into 24680multiple implementation files. 24681@end table 24682 24683@cindex inlining and C++ pragmas 24684@cindex C++ pragmas, effect on inlining 24685@cindex pragmas in C++, effect on inlining 24686@samp{#pragma implementation} and @samp{#pragma interface} also have an 24687effect on function inlining. 24688 24689If you define a class in a header file marked with @samp{#pragma 24690interface}, the effect on an inline function defined in that class is 24691similar to an explicit @code{extern} declaration---the compiler emits 24692no code at all to define an independent version of the function. Its 24693definition is used only for inlining with its callers. 24694 24695@opindex fno-implement-inlines 24696Conversely, when you include the same header file in a main source file 24697that declares it as @samp{#pragma implementation}, the compiler emits 24698code for the function itself; this defines a version of the function 24699that can be found via pointers (or by callers compiled without 24700inlining). If all calls to the function can be inlined, you can avoid 24701emitting the function by compiling with @option{-fno-implement-inlines}. 24702If any calls are not inlined, you will get linker errors. 24703 24704@node Template Instantiation 24705@section Where's the Template? 24706@cindex template instantiation 24707 24708C++ templates were the first language feature to require more 24709intelligence from the environment than was traditionally found on a UNIX 24710system. Somehow the compiler and linker have to make sure that each 24711template instance occurs exactly once in the executable if it is needed, 24712and not at all otherwise. There are two basic approaches to this 24713problem, which are referred to as the Borland model and the Cfront model. 24714 24715@table @asis 24716@item Borland model 24717Borland C++ solved the template instantiation problem by adding the code 24718equivalent of common blocks to their linker; the compiler emits template 24719instances in each translation unit that uses them, and the linker 24720collapses them together. The advantage of this model is that the linker 24721only has to consider the object files themselves; there is no external 24722complexity to worry about. The disadvantage is that compilation time 24723is increased because the template code is being compiled repeatedly. 24724Code written for this model tends to include definitions of all 24725templates in the header file, since they must be seen to be 24726instantiated. 24727 24728@item Cfront model 24729The AT&T C++ translator, Cfront, solved the template instantiation 24730problem by creating the notion of a template repository, an 24731automatically maintained place where template instances are stored. A 24732more modern version of the repository works as follows: As individual 24733object files are built, the compiler places any template definitions and 24734instantiations encountered in the repository. At link time, the link 24735wrapper adds in the objects in the repository and compiles any needed 24736instances that were not previously emitted. The advantages of this 24737model are more optimal compilation speed and the ability to use the 24738system linker; to implement the Borland model a compiler vendor also 24739needs to replace the linker. The disadvantages are vastly increased 24740complexity, and thus potential for error; for some code this can be 24741just as transparent, but in practice it can been very difficult to build 24742multiple programs in one directory and one program in multiple 24743directories. Code written for this model tends to separate definitions 24744of non-inline member templates into a separate file, which should be 24745compiled separately. 24746@end table 24747 24748G++ implements the Borland model on targets where the linker supports it, 24749including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows. 24750Otherwise G++ implements neither automatic model. 24751 24752You have the following options for dealing with template instantiations: 24753 24754@enumerate 24755@item 24756Do nothing. Code written for the Borland model works fine, but 24757each translation unit contains instances of each of the templates it 24758uses. The duplicate instances will be discarded by the linker, but in 24759a large program, this can lead to an unacceptable amount of code 24760duplication in object files or shared libraries. 24761 24762Duplicate instances of a template can be avoided by defining an explicit 24763instantiation in one object file, and preventing the compiler from doing 24764implicit instantiations in any other object files by using an explicit 24765instantiation declaration, using the @code{extern template} syntax: 24766 24767@smallexample 24768extern template int max (int, int); 24769@end smallexample 24770 24771This syntax is defined in the C++ 2011 standard, but has been supported by 24772G++ and other compilers since well before 2011. 24773 24774Explicit instantiations can be used for the largest or most frequently 24775duplicated instances, without having to know exactly which other instances 24776are used in the rest of the program. You can scatter the explicit 24777instantiations throughout your program, perhaps putting them in the 24778translation units where the instances are used or the translation units 24779that define the templates themselves; you can put all of the explicit 24780instantiations you need into one big file; or you can create small files 24781like 24782 24783@smallexample 24784#include "Foo.h" 24785#include "Foo.cc" 24786 24787template class Foo<int>; 24788template ostream& operator << 24789 (ostream&, const Foo<int>&); 24790@end smallexample 24791 24792@noindent 24793for each of the instances you need, and create a template instantiation 24794library from those. 24795 24796This is the simplest option, but also offers flexibility and 24797fine-grained control when necessary. It is also the most portable 24798alternative and programs using this approach will work with most modern 24799compilers. 24800 24801@item 24802@opindex fno-implicit-templates 24803Compile your code with @option{-fno-implicit-templates} to disable the 24804implicit generation of template instances, and explicitly instantiate 24805all the ones you use. This approach requires more knowledge of exactly 24806which instances you need than do the others, but it's less 24807mysterious and allows greater control if you want to ensure that only 24808the intended instances are used. 24809 24810If you are using Cfront-model code, you can probably get away with not 24811using @option{-fno-implicit-templates} when compiling files that don't 24812@samp{#include} the member template definitions. 24813 24814If you use one big file to do the instantiations, you may want to 24815compile it without @option{-fno-implicit-templates} so you get all of the 24816instances required by your explicit instantiations (but not by any 24817other files) without having to specify them as well. 24818 24819In addition to forward declaration of explicit instantiations 24820(with @code{extern}), G++ has extended the template instantiation 24821syntax to support instantiation of the compiler support data for a 24822template class (i.e.@: the vtable) without instantiating any of its 24823members (with @code{inline}), and instantiation of only the static data 24824members of a template class, without the support data or member 24825functions (with @code{static}): 24826 24827@smallexample 24828inline template class Foo<int>; 24829static template class Foo<int>; 24830@end smallexample 24831@end enumerate 24832 24833@node Bound member functions 24834@section Extracting the Function Pointer from a Bound Pointer to Member Function 24835@cindex pmf 24836@cindex pointer to member function 24837@cindex bound pointer to member function 24838 24839In C++, pointer to member functions (PMFs) are implemented using a wide 24840pointer of sorts to handle all the possible call mechanisms; the PMF 24841needs to store information about how to adjust the @samp{this} pointer, 24842and if the function pointed to is virtual, where to find the vtable, and 24843where in the vtable to look for the member function. If you are using 24844PMFs in an inner loop, you should really reconsider that decision. If 24845that is not an option, you can extract the pointer to the function that 24846would be called for a given object/PMF pair and call it directly inside 24847the inner loop, to save a bit of time. 24848 24849Note that you still pay the penalty for the call through a 24850function pointer; on most modern architectures, such a call defeats the 24851branch prediction features of the CPU@. This is also true of normal 24852virtual function calls. 24853 24854The syntax for this extension is 24855 24856@smallexample 24857extern A a; 24858extern int (A::*fp)(); 24859typedef int (*fptr)(A *); 24860 24861fptr p = (fptr)(a.*fp); 24862@end smallexample 24863 24864For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), 24865no object is needed to obtain the address of the function. They can be 24866converted to function pointers directly: 24867 24868@smallexample 24869fptr p1 = (fptr)(&A::foo); 24870@end smallexample 24871 24872@opindex Wno-pmf-conversions 24873You must specify @option{-Wno-pmf-conversions} to use this extension. 24874 24875@node C++ Attributes 24876@section C++-Specific Variable, Function, and Type Attributes 24877 24878Some attributes only make sense for C++ programs. 24879 24880@table @code 24881@item abi_tag ("@var{tag}", ...) 24882@cindex @code{abi_tag} function attribute 24883@cindex @code{abi_tag} variable attribute 24884@cindex @code{abi_tag} type attribute 24885The @code{abi_tag} attribute can be applied to a function, variable, or class 24886declaration. It modifies the mangled name of the entity to 24887incorporate the tag name, in order to distinguish the function or 24888class from an earlier version with a different ABI; perhaps the class 24889has changed size, or the function has a different return type that is 24890not encoded in the mangled name. 24891 24892The attribute can also be applied to an inline namespace, but does not 24893affect the mangled name of the namespace; in this case it is only used 24894for @option{-Wabi-tag} warnings and automatic tagging of functions and 24895variables. Tagging inline namespaces is generally preferable to 24896tagging individual declarations, but the latter is sometimes 24897necessary, such as when only certain members of a class need to be 24898tagged. 24899 24900The argument can be a list of strings of arbitrary length. The 24901strings are sorted on output, so the order of the list is 24902unimportant. 24903 24904A redeclaration of an entity must not add new ABI tags, 24905since doing so would change the mangled name. 24906 24907The ABI tags apply to a name, so all instantiations and 24908specializations of a template have the same tags. The attribute will 24909be ignored if applied to an explicit specialization or instantiation. 24910 24911The @option{-Wabi-tag} flag enables a warning about a class which does 24912not have all the ABI tags used by its subobjects and virtual functions; for users with code 24913that needs to coexist with an earlier ABI, using this option can help 24914to find all affected types that need to be tagged. 24915 24916When a type involving an ABI tag is used as the type of a variable or 24917return type of a function where that tag is not already present in the 24918signature of the function, the tag is automatically applied to the 24919variable or function. @option{-Wabi-tag} also warns about this 24920situation; this warning can be avoided by explicitly tagging the 24921variable or function or moving it into a tagged inline namespace. 24922 24923@item init_priority (@var{priority}) 24924@cindex @code{init_priority} variable attribute 24925 24926In Standard C++, objects defined at namespace scope are guaranteed to be 24927initialized in an order in strict accordance with that of their definitions 24928@emph{in a given translation unit}. No guarantee is made for initializations 24929across translation units. However, GNU C++ allows users to control the 24930order of initialization of objects defined at namespace scope with the 24931@code{init_priority} attribute by specifying a relative @var{priority}, 24932a constant integral expression currently bounded between 101 and 65535 24933inclusive. Lower numbers indicate a higher priority. 24934 24935In the following example, @code{A} would normally be created before 24936@code{B}, but the @code{init_priority} attribute reverses that order: 24937 24938@smallexample 24939Some_Class A __attribute__ ((init_priority (2000))); 24940Some_Class B __attribute__ ((init_priority (543))); 24941@end smallexample 24942 24943@noindent 24944Note that the particular values of @var{priority} do not matter; only their 24945relative ordering. 24946 24947@item warn_unused 24948@cindex @code{warn_unused} type attribute 24949 24950For C++ types with non-trivial constructors and/or destructors it is 24951impossible for the compiler to determine whether a variable of this 24952type is truly unused if it is not referenced. This type attribute 24953informs the compiler that variables of this type should be warned 24954about if they appear to be unused, just like variables of fundamental 24955types. 24956 24957This attribute is appropriate for types which just represent a value, 24958such as @code{std::string}; it is not appropriate for types which 24959control a resource, such as @code{std::lock_guard}. 24960 24961This attribute is also accepted in C, but it is unnecessary because C 24962does not have constructors or destructors. 24963 24964@end table 24965 24966@node Function Multiversioning 24967@section Function Multiversioning 24968@cindex function versions 24969 24970With the GNU C++ front end, for x86 targets, you may specify multiple 24971versions of a function, where each function is specialized for a 24972specific target feature. At runtime, the appropriate version of the 24973function is automatically executed depending on the characteristics of 24974the execution platform. Here is an example. 24975 24976@smallexample 24977__attribute__ ((target ("default"))) 24978int foo () 24979@{ 24980 // The default version of foo. 24981 return 0; 24982@} 24983 24984__attribute__ ((target ("sse4.2"))) 24985int foo () 24986@{ 24987 // foo version for SSE4.2 24988 return 1; 24989@} 24990 24991__attribute__ ((target ("arch=atom"))) 24992int foo () 24993@{ 24994 // foo version for the Intel ATOM processor 24995 return 2; 24996@} 24997 24998__attribute__ ((target ("arch=amdfam10"))) 24999int foo () 25000@{ 25001 // foo version for the AMD Family 0x10 processors. 25002 return 3; 25003@} 25004 25005int main () 25006@{ 25007 int (*p)() = &foo; 25008 assert ((*p) () == foo ()); 25009 return 0; 25010@} 25011@end smallexample 25012 25013In the above example, four versions of function foo are created. The 25014first version of foo with the target attribute "default" is the default 25015version. This version gets executed when no other target specific 25016version qualifies for execution on a particular platform. A new version 25017of foo is created by using the same function signature but with a 25018different target string. Function foo is called or a pointer to it is 25019taken just like a regular function. GCC takes care of doing the 25020dispatching to call the right version at runtime. Refer to the 25021@uref{http://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on 25022Function Multiversioning} for more details. 25023 25024@node Type Traits 25025@section Type Traits 25026 25027The C++ front end implements syntactic extensions that allow 25028compile-time determination of 25029various characteristics of a type (or of a 25030pair of types). 25031 25032@table @code 25033@item __has_nothrow_assign (type) 25034If @code{type} is @code{const}-qualified or is a reference type then 25035the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)} 25036is @code{true} then the trait is @code{true}, else if @code{type} is 25037a cv-qualified class or union type with copy assignment operators that are 25038known not to throw an exception then the trait is @code{true}, else it is 25039@code{false}. 25040Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25041@code{void}, or an array of unknown bound. 25042 25043@item __has_nothrow_copy (type) 25044If @code{__has_trivial_copy (type)} is @code{true} then the trait is 25045@code{true}, else if @code{type} is a cv-qualified class or union type 25046with copy constructors that are known not to throw an exception then 25047the trait is @code{true}, else it is @code{false}. 25048Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25049@code{void}, or an array of unknown bound. 25050 25051@item __has_nothrow_constructor (type) 25052If @code{__has_trivial_constructor (type)} is @code{true} then the trait 25053is @code{true}, else if @code{type} is a cv class or union type (or array 25054thereof) with a default constructor that is known not to throw an 25055exception then the trait is @code{true}, else it is @code{false}. 25056Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25057@code{void}, or an array of unknown bound. 25058 25059@item __has_trivial_assign (type) 25060If @code{type} is @code{const}- qualified or is a reference type then 25061the trait is @code{false}. Otherwise if @code{__is_pod (type)} is 25062@code{true} then the trait is @code{true}, else if @code{type} is 25063a cv-qualified class or union type with a trivial copy assignment 25064([class.copy]) then the trait is @code{true}, else it is @code{false}. 25065Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25066@code{void}, or an array of unknown bound. 25067 25068@item __has_trivial_copy (type) 25069If @code{__is_pod (type)} is @code{true} or @code{type} is a reference 25070type then the trait is @code{true}, else if @code{type} is a cv class 25071or union type with a trivial copy constructor ([class.copy]) then the trait 25072is @code{true}, else it is @code{false}. Requires: @code{type} shall be 25073a complete type, (possibly cv-qualified) @code{void}, or an array of unknown 25074bound. 25075 25076@item __has_trivial_constructor (type) 25077If @code{__is_pod (type)} is @code{true} then the trait is @code{true}, 25078else if @code{type} is a cv-qualified class or union type (or array thereof) 25079with a trivial default constructor ([class.ctor]) then the trait is @code{true}, 25080else it is @code{false}. 25081Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25082@code{void}, or an array of unknown bound. 25083 25084@item __has_trivial_destructor (type) 25085If @code{__is_pod (type)} is @code{true} or @code{type} is a reference type 25086then the trait is @code{true}, else if @code{type} is a cv class or union 25087type (or array thereof) with a trivial destructor ([class.dtor]) then 25088the trait is @code{true}, else it is @code{false}. 25089Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25090@code{void}, or an array of unknown bound. 25091 25092@item __has_virtual_destructor (type) 25093If @code{type} is a class type with a virtual destructor 25094([class.dtor]) then the trait is @code{true}, else it is @code{false}. 25095Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25096@code{void}, or an array of unknown bound. 25097 25098@item __is_abstract (type) 25099If @code{type} is an abstract class ([class.abstract]) then the trait 25100is @code{true}, else it is @code{false}. 25101Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25102@code{void}, or an array of unknown bound. 25103 25104@item __is_base_of (base_type, derived_type) 25105If @code{base_type} is a base class of @code{derived_type} 25106([class.derived]) then the trait is @code{true}, otherwise it is @code{false}. 25107Top-level cv-qualifications of @code{base_type} and 25108@code{derived_type} are ignored. For the purposes of this trait, a 25109class type is considered is own base. 25110Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)} 25111are @code{true} and @code{base_type} and @code{derived_type} are not the same 25112type (disregarding cv-qualifiers), @code{derived_type} shall be a complete 25113type. A diagnostic is produced if this requirement is not met. 25114 25115@item __is_class (type) 25116If @code{type} is a cv-qualified class type, and not a union type 25117([basic.compound]) the trait is @code{true}, else it is @code{false}. 25118 25119@item __is_empty (type) 25120If @code{__is_class (type)} is @code{false} then the trait is @code{false}. 25121Otherwise @code{type} is considered empty if and only if: @code{type} 25122has no non-static data members, or all non-static data members, if 25123any, are bit-fields of length 0, and @code{type} has no virtual 25124members, and @code{type} has no virtual base classes, and @code{type} 25125has no base classes @code{base_type} for which 25126@code{__is_empty (base_type)} is @code{false}. 25127Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25128@code{void}, or an array of unknown bound. 25129 25130@item __is_enum (type) 25131If @code{type} is a cv enumeration type ([basic.compound]) the trait is 25132@code{true}, else it is @code{false}. 25133 25134@item __is_literal_type (type) 25135If @code{type} is a literal type ([basic.types]) the trait is 25136@code{true}, else it is @code{false}. 25137Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25138@code{void}, or an array of unknown bound. 25139 25140@item __is_pod (type) 25141If @code{type} is a cv POD type ([basic.types]) then the trait is @code{true}, 25142else it is @code{false}. 25143Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25144@code{void}, or an array of unknown bound. 25145 25146@item __is_polymorphic (type) 25147If @code{type} is a polymorphic class ([class.virtual]) then the trait 25148is @code{true}, else it is @code{false}. 25149Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25150@code{void}, or an array of unknown bound. 25151 25152@item __is_standard_layout (type) 25153If @code{type} is a standard-layout type ([basic.types]) the trait is 25154@code{true}, else it is @code{false}. 25155Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25156@code{void}, or an array of unknown bound. 25157 25158@item __is_trivial (type) 25159If @code{type} is a trivial type ([basic.types]) the trait is 25160@code{true}, else it is @code{false}. 25161Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25162@code{void}, or an array of unknown bound. 25163 25164@item __is_union (type) 25165If @code{type} is a cv union type ([basic.compound]) the trait is 25166@code{true}, else it is @code{false}. 25167 25168@item __underlying_type (type) 25169The underlying type of @code{type}. 25170Requires: @code{type} shall be an enumeration type ([dcl.enum]). 25171 25172@item __integer_pack (length) 25173When used as the pattern of a pack expansion within a template 25174definition, expands to a template argument pack containing integers 25175from @code{0} to @code{length-1}. This is provided for efficient 25176implementation of @code{std::make_integer_sequence}. 25177 25178@end table 25179 25180 25181@node C++ Concepts 25182@section C++ Concepts 25183 25184C++ concepts provide much-improved support for generic programming. In 25185particular, they allow the specification of constraints on template arguments. 25186The constraints are used to extend the usual overloading and partial 25187specialization capabilities of the language, allowing generic data structures 25188and algorithms to be ``refined'' based on their properties rather than their 25189type names. 25190 25191The following keywords are reserved for concepts. 25192 25193@table @code 25194@item assumes 25195States an expression as an assumption, and if possible, verifies that the 25196assumption is valid. For example, @code{assume(n > 0)}. 25197 25198@item axiom 25199Introduces an axiom definition. Axioms introduce requirements on values. 25200 25201@item forall 25202Introduces a universally quantified object in an axiom. For example, 25203@code{forall (int n) n + 0 == n}). 25204 25205@item concept 25206Introduces a concept definition. Concepts are sets of syntactic and semantic 25207requirements on types and their values. 25208 25209@item requires 25210Introduces constraints on template arguments or requirements for a member 25211function of a class template. 25212 25213@end table 25214 25215The front end also exposes a number of internal mechanism that can be used 25216to simplify the writing of type traits. Note that some of these traits are 25217likely to be removed in the future. 25218 25219@table @code 25220@item __is_same (type1, type2) 25221A binary type trait: @code{true} whenever the type arguments are the same. 25222 25223@end table 25224 25225 25226@node Deprecated Features 25227@section Deprecated Features 25228 25229In the past, the GNU C++ compiler was extended to experiment with new 25230features, at a time when the C++ language was still evolving. Now that 25231the C++ standard is complete, some of those features are superseded by 25232superior alternatives. Using the old features might cause a warning in 25233some cases that the feature will be dropped in the future. In other 25234cases, the feature might be gone already. 25235 25236G++ allows a virtual function returning @samp{void *} to be overridden 25237by one returning a different pointer type. This extension to the 25238covariant return type rules is now deprecated and will be removed from a 25239future version. 25240 25241The use of default arguments in function pointers, function typedefs 25242and other places where they are not permitted by the standard is 25243deprecated and will be removed from a future version of G++. 25244 25245G++ allows floating-point literals to appear in integral constant expressions, 25246e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} } 25247This extension is deprecated and will be removed from a future version. 25248 25249G++ allows static data members of const floating-point type to be declared 25250with an initializer in a class definition. The standard only allows 25251initializers for static members of const integral types and const 25252enumeration types so this extension has been deprecated and will be removed 25253from a future version. 25254 25255G++ allows attributes to follow a parenthesized direct initializer, 25256e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension 25257has been ignored since G++ 3.3 and is deprecated. 25258 25259G++ allows anonymous structs and unions to have members that are not 25260public non-static data members (i.e.@: fields). These extensions are 25261deprecated. 25262 25263@node Backwards Compatibility 25264@section Backwards Compatibility 25265@cindex Backwards Compatibility 25266@cindex ARM [Annotated C++ Reference Manual] 25267 25268Now that there is a definitive ISO standard C++, G++ has a specification 25269to adhere to. The C++ language evolved over time, and features that 25270used to be acceptable in previous drafts of the standard, such as the ARM 25271[Annotated C++ Reference Manual], are no longer accepted. In order to allow 25272compilation of C++ written to such drafts, G++ contains some backwards 25273compatibilities. @emph{All such backwards compatibility features are 25274liable to disappear in future versions of G++.} They should be considered 25275deprecated. @xref{Deprecated Features}. 25276 25277@table @code 25278 25279@item Implicit C language 25280Old C system header files did not contain an @code{extern "C" @{@dots{}@}} 25281scope to set the language. On such systems, all system header files are 25282implicitly scoped inside a C language scope. Such headers must 25283correctly prototype function argument types, there is no leeway for 25284@code{()} to indicate an unspecified set of arguments. 25285 25286@end table 25287 25288@c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd 25289@c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr 25290