1c Copyright (C) 1988-2019 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} {size_t} __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, SPU, 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 SPU Named Address Spaces 1577@cindex @code{__ea} SPU Named Address Spaces 1578 1579On the SPU target variables may be declared as 1580belonging to another address space by qualifying the type with the 1581@code{__ea} address space identifier: 1582 1583@smallexample 1584extern int __ea i; 1585@end smallexample 1586 1587@noindent 1588The compiler generates special code to access the variable @code{i}. 1589It may use runtime library 1590support, or generate special machine instructions to access that address 1591space. 1592 1593@subsection x86 Named Address Spaces 1594@cindex x86 named address spaces 1595 1596On the x86 target, variables may be declared as being relative 1597to the @code{%fs} or @code{%gs} segments. 1598 1599@table @code 1600@item __seg_fs 1601@itemx __seg_gs 1602@cindex @code{__seg_fs} x86 named address space 1603@cindex @code{__seg_gs} x86 named address space 1604The object is accessed with the respective segment override prefix. 1605 1606The respective segment base must be set via some method specific to 1607the operating system. Rather than require an expensive system call 1608to retrieve the segment base, these address spaces are not considered 1609to be subspaces of the generic (flat) address space. This means that 1610explicit casts are required to convert pointers between these address 1611spaces and the generic address space. In practice the application 1612should cast to @code{uintptr_t} and apply the segment base offset 1613that it installed previously. 1614 1615The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are 1616defined when these address spaces are supported. 1617@end table 1618 1619@node Zero Length 1620@section Arrays of Length Zero 1621@cindex arrays of length zero 1622@cindex zero-length arrays 1623@cindex length-zero arrays 1624@cindex flexible array members 1625 1626Declaring zero-length arrays is allowed in GNU C as an extension. 1627A zero-length array can be useful as the last element of a structure 1628that is really a header for a variable-length object: 1629 1630@smallexample 1631struct line @{ 1632 int length; 1633 char contents[0]; 1634@}; 1635 1636struct line *thisline = (struct line *) 1637 malloc (sizeof (struct line) + this_length); 1638thisline->length = this_length; 1639@end smallexample 1640 1641Although the size of a zero-length array is zero, an array member of 1642this kind may increase the size of the enclosing type as a result of tail 1643padding. The offset of a zero-length array member from the beginning 1644of the enclosing structure is the same as the offset of an array with 1645one or more elements of the same type. The alignment of a zero-length 1646array is the same as the alignment of its elements. 1647 1648Declaring zero-length arrays in other contexts, including as interior 1649members of structure objects or as non-member objects, is discouraged. 1650Accessing elements of zero-length arrays declared in such contexts is 1651undefined and may be diagnosed. 1652 1653In the absence of the zero-length array extension, in ISO C90 1654the @code{contents} array in the example above would typically be declared 1655to have a single element. Unlike a zero-length array which only contributes 1656to the size of the enclosing structure for the purposes of alignment, 1657a one-element array always occupies at least as much space as a single 1658object of the type. Although using one-element arrays this way is 1659discouraged, GCC handles accesses to trailing one-element array members 1660analogously to zero-length arrays. 1661 1662The preferred mechanism to declare variable-length types like 1663@code{struct line} above is the ISO C99 @dfn{flexible array member}, 1664with slightly different syntax and semantics: 1665 1666@itemize @bullet 1667@item 1668Flexible array members are written as @code{contents[]} without 1669the @code{0}. 1670 1671@item 1672Flexible array members have incomplete type, and so the @code{sizeof} 1673operator may not be applied. As a quirk of the original implementation 1674of zero-length arrays, @code{sizeof} evaluates to zero. 1675 1676@item 1677Flexible array members may only appear as the last member of a 1678@code{struct} that is otherwise non-empty. 1679 1680@item 1681A structure containing a flexible array member, or a union containing 1682such a structure (possibly recursively), may not be a member of a 1683structure or an element of an array. (However, these uses are 1684permitted by GCC as extensions.) 1685@end itemize 1686 1687Non-empty initialization of zero-length 1688arrays is treated like any case where there are more initializer 1689elements than the array holds, in that a suitable warning about ``excess 1690elements in array'' is given, and the excess elements (all of them, in 1691this case) are ignored. 1692 1693GCC allows static initialization of flexible array members. 1694This is equivalent to defining a new structure containing the original 1695structure followed by an array of sufficient size to contain the data. 1696E.g.@: in the following, @code{f1} is constructed as if it were declared 1697like @code{f2}. 1698 1699@smallexample 1700struct f1 @{ 1701 int x; int y[]; 1702@} f1 = @{ 1, @{ 2, 3, 4 @} @}; 1703 1704struct f2 @{ 1705 struct f1 f1; int data[3]; 1706@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; 1707@end smallexample 1708 1709@noindent 1710The convenience of this extension is that @code{f1} has the desired 1711type, eliminating the need to consistently refer to @code{f2.f1}. 1712 1713This has symmetry with normal static arrays, in that an array of 1714unknown size is also written with @code{[]}. 1715 1716Of course, this extension only makes sense if the extra data comes at 1717the end of a top-level object, as otherwise we would be overwriting 1718data at subsequent offsets. To avoid undue complication and confusion 1719with initialization of deeply nested arrays, we simply disallow any 1720non-empty initialization except when the structure is the top-level 1721object. For example: 1722 1723@smallexample 1724struct foo @{ int x; int y[]; @}; 1725struct bar @{ struct foo z; @}; 1726 1727struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} 1728struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1729struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} 1730struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1731@end smallexample 1732 1733@node Empty Structures 1734@section Structures with No Members 1735@cindex empty structures 1736@cindex zero-size structures 1737 1738GCC permits a C structure to have no members: 1739 1740@smallexample 1741struct empty @{ 1742@}; 1743@end smallexample 1744 1745The structure has size zero. In C++, empty structures are part 1746of the language. G++ treats empty structures as if they had a single 1747member of type @code{char}. 1748 1749@node Variable Length 1750@section Arrays of Variable Length 1751@cindex variable-length arrays 1752@cindex arrays of variable length 1753@cindex VLAs 1754 1755Variable-length automatic arrays are allowed in ISO C99, and as an 1756extension GCC accepts them in C90 mode and in C++. These arrays are 1757declared like any other automatic arrays, but with a length that is not 1758a constant expression. The storage is allocated at the point of 1759declaration and deallocated when the block scope containing the declaration 1760exits. For 1761example: 1762 1763@smallexample 1764FILE * 1765concat_fopen (char *s1, char *s2, char *mode) 1766@{ 1767 char str[strlen (s1) + strlen (s2) + 1]; 1768 strcpy (str, s1); 1769 strcat (str, s2); 1770 return fopen (str, mode); 1771@} 1772@end smallexample 1773 1774@cindex scope of a variable length array 1775@cindex variable-length array scope 1776@cindex deallocating variable length arrays 1777Jumping or breaking out of the scope of the array name deallocates the 1778storage. Jumping into the scope is not allowed; you get an error 1779message for it. 1780 1781@cindex variable-length array in a structure 1782As an extension, GCC accepts variable-length arrays as a member of 1783a structure or a union. For example: 1784 1785@smallexample 1786void 1787foo (int n) 1788@{ 1789 struct S @{ int x[n]; @}; 1790@} 1791@end smallexample 1792 1793@cindex @code{alloca} vs variable-length arrays 1794You can use the function @code{alloca} to get an effect much like 1795variable-length arrays. The function @code{alloca} is available in 1796many other C implementations (but not in all). On the other hand, 1797variable-length arrays are more elegant. 1798 1799There are other differences between these two methods. Space allocated 1800with @code{alloca} exists until the containing @emph{function} returns. 1801The space for a variable-length array is deallocated as soon as the array 1802name's scope ends, unless you also use @code{alloca} in this scope. 1803 1804You can also use variable-length arrays as arguments to functions: 1805 1806@smallexample 1807struct entry 1808tester (int len, char data[len][len]) 1809@{ 1810 /* @r{@dots{}} */ 1811@} 1812@end smallexample 1813 1814The length of an array is computed once when the storage is allocated 1815and is remembered for the scope of the array in case you access it with 1816@code{sizeof}. 1817 1818If you want to pass the array first and the length afterward, you can 1819use a forward declaration in the parameter list---another GNU extension. 1820 1821@smallexample 1822struct entry 1823tester (int len; char data[len][len], int len) 1824@{ 1825 /* @r{@dots{}} */ 1826@} 1827@end smallexample 1828 1829@cindex parameter forward declaration 1830The @samp{int len} before the semicolon is a @dfn{parameter forward 1831declaration}, and it serves the purpose of making the name @code{len} 1832known when the declaration of @code{data} is parsed. 1833 1834You can write any number of such parameter forward declarations in the 1835parameter list. They can be separated by commas or semicolons, but the 1836last one must end with a semicolon, which is followed by the ``real'' 1837parameter declarations. Each forward declaration must match a ``real'' 1838declaration in parameter name and data type. ISO C99 does not support 1839parameter forward declarations. 1840 1841@node Variadic Macros 1842@section Macros with a Variable Number of Arguments. 1843@cindex variable number of arguments 1844@cindex macro with variable arguments 1845@cindex rest argument (in macro) 1846@cindex variadic macros 1847 1848In the ISO C standard of 1999, a macro can be declared to accept a 1849variable number of arguments much as a function can. The syntax for 1850defining the macro is similar to that of a function. Here is an 1851example: 1852 1853@smallexample 1854#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) 1855@end smallexample 1856 1857@noindent 1858Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of 1859such a macro, it represents the zero or more tokens until the closing 1860parenthesis that ends the invocation, including any commas. This set of 1861tokens replaces the identifier @code{__VA_ARGS__} in the macro body 1862wherever it appears. See the CPP manual for more information. 1863 1864GCC has long supported variadic macros, and used a different syntax that 1865allowed you to give a name to the variable arguments just like any other 1866argument. Here is an example: 1867 1868@smallexample 1869#define debug(format, args...) fprintf (stderr, format, args) 1870@end smallexample 1871 1872@noindent 1873This is in all ways equivalent to the ISO C example above, but arguably 1874more readable and descriptive. 1875 1876GNU CPP has two further variadic macro extensions, and permits them to 1877be used with either of the above forms of macro definition. 1878 1879In standard C, you are not allowed to leave the variable argument out 1880entirely; but you are allowed to pass an empty argument. For example, 1881this invocation is invalid in ISO C, because there is no comma after 1882the string: 1883 1884@smallexample 1885debug ("A message") 1886@end smallexample 1887 1888GNU CPP permits you to completely omit the variable arguments in this 1889way. In the above examples, the compiler would complain, though since 1890the expansion of the macro still has the extra comma after the format 1891string. 1892 1893To help solve this problem, CPP behaves specially for variable arguments 1894used with the token paste operator, @samp{##}. If instead you write 1895 1896@smallexample 1897#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) 1898@end smallexample 1899 1900@noindent 1901and if the variable arguments are omitted or empty, the @samp{##} 1902operator causes the preprocessor to remove the comma before it. If you 1903do provide some variable arguments in your macro invocation, GNU CPP 1904does not complain about the paste operation and instead places the 1905variable arguments after the comma. Just like any other pasted macro 1906argument, these arguments are not macro expanded. 1907 1908@node Escaped Newlines 1909@section Slightly Looser Rules for Escaped Newlines 1910@cindex escaped newlines 1911@cindex newlines (escaped) 1912 1913The preprocessor treatment of escaped newlines is more relaxed 1914than that specified by the C90 standard, which requires the newline 1915to immediately follow a backslash. 1916GCC's implementation allows whitespace in the form 1917of spaces, horizontal and vertical tabs, and form feeds between the 1918backslash and the subsequent newline. The preprocessor issues a 1919warning, but treats it as a valid escaped newline and combines the two 1920lines to form a single logical line. This works within comments and 1921tokens, as well as between tokens. Comments are @emph{not} treated as 1922whitespace for the purposes of this relaxation, since they have not 1923yet been replaced with spaces. 1924 1925@node Subscripting 1926@section Non-Lvalue Arrays May Have Subscripts 1927@cindex subscripting 1928@cindex arrays, non-lvalue 1929 1930@cindex subscripting and function values 1931In ISO C99, arrays that are not lvalues still decay to pointers, and 1932may be subscripted, although they may not be modified or used after 1933the next sequence point and the unary @samp{&} operator may not be 1934applied to them. As an extension, GNU C allows such arrays to be 1935subscripted in C90 mode, though otherwise they do not decay to 1936pointers outside C99 mode. For example, 1937this is valid in GNU C though not valid in C90: 1938 1939@smallexample 1940@group 1941struct foo @{int a[4];@}; 1942 1943struct foo f(); 1944 1945bar (int index) 1946@{ 1947 return f().a[index]; 1948@} 1949@end group 1950@end smallexample 1951 1952@node Pointer Arith 1953@section Arithmetic on @code{void}- and Function-Pointers 1954@cindex void pointers, arithmetic 1955@cindex void, size of pointer to 1956@cindex function pointers, arithmetic 1957@cindex function, size of pointer to 1958 1959In GNU C, addition and subtraction operations are supported on pointers to 1960@code{void} and on pointers to functions. This is done by treating the 1961size of a @code{void} or of a function as 1. 1962 1963A consequence of this is that @code{sizeof} is also allowed on @code{void} 1964and on function types, and returns 1. 1965 1966@opindex Wpointer-arith 1967The option @option{-Wpointer-arith} requests a warning if these extensions 1968are used. 1969 1970@node Variadic Pointer Args 1971@section Pointer Arguments in Variadic Functions 1972@cindex pointer arguments in variadic functions 1973@cindex variadic functions, pointer arguments 1974 1975Standard C requires that pointer types used with @code{va_arg} in 1976functions with variable argument lists either must be compatible with 1977that of the actual argument, or that one type must be a pointer to 1978@code{void} and the other a pointer to a character type. GNU C 1979implements the POSIX XSI extension that additionally permits the use 1980of @code{va_arg} with a pointer type to receive arguments of any other 1981pointer type. 1982 1983In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used 1984to consume an argument of any pointer type. 1985 1986@node Pointers to Arrays 1987@section Pointers to Arrays with Qualifiers Work as Expected 1988@cindex pointers to arrays 1989@cindex const qualifier 1990 1991In GNU C, pointers to arrays with qualifiers work similar to pointers 1992to other qualified types. For example, a value of type @code{int (*)[5]} 1993can be used to initialize a variable of type @code{const int (*)[5]}. 1994These types are incompatible in ISO C because the @code{const} qualifier 1995is formally attached to the element type of the array and not the 1996array itself. 1997 1998@smallexample 1999extern void 2000transpose (int N, int M, double out[M][N], const double in[N][M]); 2001double x[3][2]; 2002double y[2][3]; 2003@r{@dots{}} 2004transpose(3, 2, y, x); 2005@end smallexample 2006 2007@node Initializers 2008@section Non-Constant Initializers 2009@cindex initializers, non-constant 2010@cindex non-constant initializers 2011 2012As in standard C++ and ISO C99, the elements of an aggregate initializer for an 2013automatic variable are not required to be constant expressions in GNU C@. 2014Here is an example of an initializer with run-time varying elements: 2015 2016@smallexample 2017foo (float f, float g) 2018@{ 2019 float beat_freqs[2] = @{ f-g, f+g @}; 2020 /* @r{@dots{}} */ 2021@} 2022@end smallexample 2023 2024@node Compound Literals 2025@section Compound Literals 2026@cindex constructor expressions 2027@cindex initializations in expressions 2028@cindex structures, constructor expression 2029@cindex expressions, constructor 2030@cindex compound literals 2031@c The GNU C name for what C99 calls compound literals was "constructor expressions". 2032 2033A compound literal looks like a cast of a brace-enclosed aggregate 2034initializer list. Its value is an object of the type specified in 2035the cast, containing the elements specified in the initializer. 2036Unlike the result of a cast, a compound literal is an lvalue. ISO 2037C99 and later support compound literals. As an extension, GCC 2038supports compound literals also in C90 mode and in C++, although 2039as explained below, the C++ semantics are somewhat different. 2040 2041Usually, the specified type of a compound literal is a structure. Assume 2042that @code{struct foo} and @code{structure} are declared as shown: 2043 2044@smallexample 2045struct foo @{int a; char b[2];@} structure; 2046@end smallexample 2047 2048@noindent 2049Here is an example of constructing a @code{struct foo} with a compound literal: 2050 2051@smallexample 2052structure = ((struct foo) @{x + y, 'a', 0@}); 2053@end smallexample 2054 2055@noindent 2056This is equivalent to writing the following: 2057 2058@smallexample 2059@{ 2060 struct foo temp = @{x + y, 'a', 0@}; 2061 structure = temp; 2062@} 2063@end smallexample 2064 2065You can also construct an array, though this is dangerous in C++, as 2066explained below. If all the elements of the compound literal are 2067(made up of) simple constant expressions suitable for use in 2068initializers of objects of static storage duration, then the compound 2069literal can be coerced to a pointer to its first element and used in 2070such an initializer, as shown here: 2071 2072@smallexample 2073char **foo = (char *[]) @{ "x", "y", "z" @}; 2074@end smallexample 2075 2076Compound literals for scalar types and union types are also allowed. In 2077the following example the variable @code{i} is initialized to the value 2078@code{2}, the result of incrementing the unnamed object created by 2079the compound literal. 2080 2081@smallexample 2082int i = ++(int) @{ 1 @}; 2083@end smallexample 2084 2085As a GNU extension, GCC allows initialization of objects with static storage 2086duration by compound literals (which is not possible in ISO C99 because 2087the initializer is not a constant). 2088It is handled as if the object were initialized only with the brace-enclosed 2089list if the types of the compound literal and the object match. 2090The elements of the compound literal must be constant. 2091If the object being initialized has array type of unknown size, the size is 2092determined by the size of the compound literal. 2093 2094@smallexample 2095static struct foo x = (struct foo) @{1, 'a', 'b'@}; 2096static int y[] = (int []) @{1, 2, 3@}; 2097static int z[] = (int [3]) @{1@}; 2098@end smallexample 2099 2100@noindent 2101The above lines are equivalent to the following: 2102@smallexample 2103static struct foo x = @{1, 'a', 'b'@}; 2104static int y[] = @{1, 2, 3@}; 2105static int z[] = @{1, 0, 0@}; 2106@end smallexample 2107 2108In C, a compound literal designates an unnamed object with static or 2109automatic storage duration. In C++, a compound literal designates a 2110temporary object that only lives until the end of its full-expression. 2111As a result, well-defined C code that takes the address of a subobject 2112of a compound literal can be undefined in C++, so G++ rejects 2113the conversion of a temporary array to a pointer. For instance, if 2114the array compound literal example above appeared inside a function, 2115any subsequent use of @code{foo} in C++ would have undefined behavior 2116because the lifetime of the array ends after the declaration of @code{foo}. 2117 2118As an optimization, G++ sometimes gives array compound literals longer 2119lifetimes: when the array either appears outside a function or has 2120a @code{const}-qualified type. If @code{foo} and its initializer had 2121elements of type @code{char *const} rather than @code{char *}, or if 2122@code{foo} were a global variable, the array would have static storage 2123duration. But it is probably safest just to avoid the use of array 2124compound literals in C++ code. 2125 2126@node Designated Inits 2127@section Designated Initializers 2128@cindex initializers with labeled elements 2129@cindex labeled elements in initializers 2130@cindex case labels in initializers 2131@cindex designated initializers 2132 2133Standard C90 requires the elements of an initializer to appear in a fixed 2134order, the same as the order of the elements in the array or structure 2135being initialized. 2136 2137In ISO C99 you can give the elements in any order, specifying the array 2138indices or structure field names they apply to, and GNU C allows this as 2139an extension in C90 mode as well. This extension is not 2140implemented in GNU C++. 2141 2142To specify an array index, write 2143@samp{[@var{index}] =} before the element value. For example, 2144 2145@smallexample 2146int a[6] = @{ [4] = 29, [2] = 15 @}; 2147@end smallexample 2148 2149@noindent 2150is equivalent to 2151 2152@smallexample 2153int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; 2154@end smallexample 2155 2156@noindent 2157The index values must be constant expressions, even if the array being 2158initialized is automatic. 2159 2160An alternative syntax for this that has been obsolete since GCC 2.5 but 2161GCC still accepts is to write @samp{[@var{index}]} before the element 2162value, with no @samp{=}. 2163 2164To initialize a range of elements to the same value, write 2165@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU 2166extension. For example, 2167 2168@smallexample 2169int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; 2170@end smallexample 2171 2172@noindent 2173If the value in it has side effects, the side effects happen only once, 2174not for each initialized field by the range initializer. 2175 2176@noindent 2177Note that the length of the array is the highest value specified 2178plus one. 2179 2180In a structure initializer, specify the name of a field to initialize 2181with @samp{.@var{fieldname} =} before the element value. For example, 2182given the following structure, 2183 2184@smallexample 2185struct point @{ int x, y; @}; 2186@end smallexample 2187 2188@noindent 2189the following initialization 2190 2191@smallexample 2192struct point p = @{ .y = yvalue, .x = xvalue @}; 2193@end smallexample 2194 2195@noindent 2196is equivalent to 2197 2198@smallexample 2199struct point p = @{ xvalue, yvalue @}; 2200@end smallexample 2201 2202Another syntax that has the same meaning, obsolete since GCC 2.5, is 2203@samp{@var{fieldname}:}, as shown here: 2204 2205@smallexample 2206struct point p = @{ y: yvalue, x: xvalue @}; 2207@end smallexample 2208 2209Omitted fields are implicitly initialized the same as for objects 2210that have static storage duration. 2211 2212@cindex designators 2213The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a 2214@dfn{designator}. You can also use a designator (or the obsolete colon 2215syntax) when initializing a union, to specify which element of the union 2216should be used. For example, 2217 2218@smallexample 2219union foo @{ int i; double d; @}; 2220 2221union foo f = @{ .d = 4 @}; 2222@end smallexample 2223 2224@noindent 2225converts 4 to a @code{double} to store it in the union using 2226the second element. By contrast, casting 4 to type @code{union foo} 2227stores it into the union as the integer @code{i}, since it is 2228an integer. @xref{Cast to Union}. 2229 2230You can combine this technique of naming elements with ordinary C 2231initialization of successive elements. Each initializer element that 2232does not have a designator applies to the next consecutive element of the 2233array or structure. For example, 2234 2235@smallexample 2236int a[6] = @{ [1] = v1, v2, [4] = v4 @}; 2237@end smallexample 2238 2239@noindent 2240is equivalent to 2241 2242@smallexample 2243int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; 2244@end smallexample 2245 2246Labeling the elements of an array initializer is especially useful 2247when the indices are characters or belong to an @code{enum} type. 2248For example: 2249 2250@smallexample 2251int whitespace[256] 2252 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, 2253 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; 2254@end smallexample 2255 2256@cindex designator lists 2257You can also write a series of @samp{.@var{fieldname}} and 2258@samp{[@var{index}]} designators before an @samp{=} to specify a 2259nested subobject to initialize; the list is taken relative to the 2260subobject corresponding to the closest surrounding brace pair. For 2261example, with the @samp{struct point} declaration above: 2262 2263@smallexample 2264struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; 2265@end smallexample 2266 2267If the same field is initialized multiple times, or overlapping 2268fields of a union are initialized, the value from the last 2269initialization is used. When a field of a union is itself a structure, 2270the entire structure from the last field initialized is used. If any previous 2271initializer has side effect, it is unspecified whether the side effect 2272happens or not. Currently, GCC discards the side-effecting 2273initializer expressions and issues a warning. 2274 2275@node Case Ranges 2276@section Case Ranges 2277@cindex case ranges 2278@cindex ranges in case statements 2279 2280You can specify a range of consecutive values in a single @code{case} label, 2281like this: 2282 2283@smallexample 2284case @var{low} ... @var{high}: 2285@end smallexample 2286 2287@noindent 2288This has the same effect as the proper number of individual @code{case} 2289labels, one for each integer value from @var{low} to @var{high}, inclusive. 2290 2291This feature is especially useful for ranges of ASCII character codes: 2292 2293@smallexample 2294case 'A' ... 'Z': 2295@end smallexample 2296 2297@strong{Be careful:} Write spaces around the @code{...}, for otherwise 2298it may be parsed wrong when you use it with integer values. For example, 2299write this: 2300 2301@smallexample 2302case 1 ... 5: 2303@end smallexample 2304 2305@noindent 2306rather than this: 2307 2308@smallexample 2309case 1...5: 2310@end smallexample 2311 2312@node Cast to Union 2313@section Cast to a Union Type 2314@cindex cast to a union 2315@cindex union, casting to a 2316 2317A cast to a union type is a C extension not available in C++. It looks 2318just like ordinary casts with the constraint that the type specified is 2319a union type. You can specify the type either with the @code{union} 2320keyword or with a @code{typedef} name that refers to a union. The result 2321of a cast to a union is a temporary rvalue of the union type with a member 2322whose type matches that of the operand initialized to the value of 2323the operand. The effect of a cast to a union is similar to a compound 2324literal except that it yields an rvalue like standard casts do. 2325@xref{Compound Literals}. 2326 2327Expressions that may be cast to the union type are those whose type matches 2328at least one of the members of the union. Thus, given the following union 2329and variables: 2330 2331@smallexample 2332union foo @{ int i; double d; @}; 2333int x; 2334double y; 2335union foo z; 2336@end smallexample 2337 2338@noindent 2339both @code{x} and @code{y} can be cast to type @code{union foo} and 2340the following assignments 2341@smallexample 2342 z = (union foo) x; 2343 z = (union foo) y; 2344@end smallexample 2345are shorthand equivalents of these 2346@smallexample 2347 z = (union foo) @{ .i = x @}; 2348 z = (union foo) @{ .d = y @}; 2349@end smallexample 2350 2351However, @code{(union foo) FLT_MAX;} is not a valid cast because the union 2352has no member of type @code{float}. 2353 2354Using the cast as the right-hand side of an assignment to a variable of 2355union type is equivalent to storing in a member of the union with 2356the same type 2357 2358@smallexample 2359union foo u; 2360/* @r{@dots{}} */ 2361u = (union foo) x @equiv{} u.i = x 2362u = (union foo) y @equiv{} u.d = y 2363@end smallexample 2364 2365You can also use the union cast as a function argument: 2366 2367@smallexample 2368void hack (union foo); 2369/* @r{@dots{}} */ 2370hack ((union foo) x); 2371@end smallexample 2372 2373@node Mixed Declarations 2374@section Mixed Declarations and Code 2375@cindex mixed declarations and code 2376@cindex declarations, mixed with code 2377@cindex code, mixed with declarations 2378 2379ISO C99 and ISO C++ allow declarations and code to be freely mixed 2380within compound statements. As an extension, GNU C also allows this in 2381C90 mode. For example, you could do: 2382 2383@smallexample 2384int i; 2385/* @r{@dots{}} */ 2386i++; 2387int j = i + 2; 2388@end smallexample 2389 2390Each identifier is visible from where it is declared until the end of 2391the enclosing block. 2392 2393@node Function Attributes 2394@section Declaring Attributes of Functions 2395@cindex function attributes 2396@cindex declaring attributes of functions 2397@cindex @code{volatile} applied to function 2398@cindex @code{const} applied to function 2399 2400In GNU C and C++, you can use function attributes to specify certain 2401function properties that may help the compiler optimize calls or 2402check code more carefully for correctness. For example, you 2403can use attributes to specify that a function never returns 2404(@code{noreturn}), returns a value depending only on the values of 2405its arguments (@code{const}), or has @code{printf}-style arguments 2406(@code{format}). 2407 2408You can also use attributes to control memory placement, code 2409generation options or call/return conventions within the function 2410being annotated. Many of these attributes are target-specific. For 2411example, many targets support attributes for defining interrupt 2412handler functions, which typically must follow special register usage 2413and return conventions. Such attributes are described in the subsection 2414for each target. However, a considerable number of attributes are 2415supported by most, if not all targets. Those are described in 2416the @ref{Common Function Attributes} section. 2417 2418Function attributes are introduced by the @code{__attribute__} keyword 2419in the declaration of a function, followed by an attribute specification 2420enclosed in double parentheses. You can specify multiple attributes in 2421a declaration by separating them by commas within the double parentheses 2422or by immediately following one attribute specification with another. 2423@xref{Attribute Syntax}, for the exact rules on attribute syntax and 2424placement. Compatible attribute specifications on distinct declarations 2425of the same function are merged. An attribute specification that is not 2426compatible with attributes already applied to a declaration of the same 2427function is ignored with a warning. 2428 2429Some function attributes take one or more arguments that refer to 2430the function's parameters by their positions within the function parameter 2431list. Such attribute arguments are referred to as @dfn{positional arguments}. 2432Unless specified otherwise, positional arguments that specify properties 2433of parameters with pointer types can also specify the same properties of 2434the implicit C++ @code{this} argument in non-static member functions, and 2435of parameters of reference to a pointer type. For ordinary functions, 2436position one refers to the first parameter on the list. In C++ non-static 2437member functions, position one refers to the implicit @code{this} pointer. 2438The same restrictions and effects apply to function attributes used with 2439ordinary functions or C++ member functions. 2440 2441GCC also supports attributes on 2442variable declarations (@pxref{Variable Attributes}), 2443labels (@pxref{Label Attributes}), 2444enumerators (@pxref{Enumerator Attributes}), 2445statements (@pxref{Statement Attributes}), 2446and types (@pxref{Type Attributes}). 2447 2448There is some overlap between the purposes of attributes and pragmas 2449(@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been 2450found convenient to use @code{__attribute__} to achieve a natural 2451attachment of attributes to their corresponding declarations, whereas 2452@code{#pragma} is of use for compatibility with other compilers 2453or constructs that do not naturally form part of the grammar. 2454 2455In addition to the attributes documented here, 2456GCC plugins may provide their own attributes. 2457 2458@menu 2459* Common Function Attributes:: 2460* AArch64 Function Attributes:: 2461* AMD GCN Function Attributes:: 2462* ARC Function Attributes:: 2463* ARM Function Attributes:: 2464* AVR Function Attributes:: 2465* Blackfin Function Attributes:: 2466* CR16 Function Attributes:: 2467* C-SKY Function Attributes:: 2468* Epiphany Function Attributes:: 2469* H8/300 Function Attributes:: 2470* IA-64 Function Attributes:: 2471* M32C Function Attributes:: 2472* M32R/D Function Attributes:: 2473* m68k Function Attributes:: 2474* MCORE Function Attributes:: 2475* MeP Function Attributes:: 2476* MicroBlaze Function Attributes:: 2477* Microsoft Windows Function Attributes:: 2478* MIPS Function Attributes:: 2479* MSP430 Function Attributes:: 2480* NDS32 Function Attributes:: 2481* Nios II Function Attributes:: 2482* Nvidia PTX Function Attributes:: 2483* PowerPC Function Attributes:: 2484* RISC-V Function Attributes:: 2485* RL78 Function Attributes:: 2486* RX Function Attributes:: 2487* S/390 Function Attributes:: 2488* SH Function Attributes:: 2489* SPU Function Attributes:: 2490* Symbian OS Function Attributes:: 2491* V850 Function Attributes:: 2492* Visium Function Attributes:: 2493* x86 Function Attributes:: 2494* Xstormy16 Function Attributes:: 2495@end menu 2496 2497@node Common Function Attributes 2498@subsection Common Function Attributes 2499 2500The following attributes are supported on most targets. 2501 2502@table @code 2503@c Keep this table alphabetized by attribute name. Treat _ as space. 2504 2505@item alias ("@var{target}") 2506@cindex @code{alias} function attribute 2507The @code{alias} attribute causes the declaration to be emitted as an 2508alias for another symbol, which must be specified. For instance, 2509 2510@smallexample 2511void __f () @{ /* @r{Do something.} */; @} 2512void f () __attribute__ ((weak, alias ("__f"))); 2513@end smallexample 2514 2515@noindent 2516defines @samp{f} to be a weak alias for @samp{__f}. In C++, the 2517mangled name for the target must be used. It is an error if @samp{__f} 2518is not defined in the same translation unit. 2519 2520This attribute requires assembler and object file support, 2521and may not be available on all targets. 2522 2523@item aligned 2524@itemx aligned (@var{alignment}) 2525@cindex @code{aligned} function attribute 2526The @code{aligned} attribute specifies a minimum alignment for 2527the first instruction of the function, measured in bytes. When specified, 2528@var{alignment} must be an integer constant power of 2. Specifying no 2529@var{alignment} argument implies the ideal alignment for the target. 2530The @code{__alignof__} operator can be used to determine what that is 2531(@pxref{Alignment}). The attribute has no effect when a definition for 2532the function is not provided in the same translation unit. 2533 2534The attribute cannot be used to decrease the alignment of a function 2535previously declared with a more restrictive alignment; only to increase 2536it. Attempts to do otherwise are diagnosed. Some targets specify 2537a minimum default alignment for functions that is greater than 1. On 2538such targets, specifying a less restrictive alignment is silently ignored. 2539Using the attribute overrides the effect of the @option{-falign-functions} 2540(@pxref{Optimize Options}) option for this function. 2541 2542Note that the effectiveness of @code{aligned} attributes may be 2543limited by inherent limitations in the system linker 2544and/or object file format. On some systems, the 2545linker is only able to arrange for functions to be aligned up to a 2546certain maximum alignment. (For some linkers, the maximum supported 2547alignment may be very very small.) See your linker documentation for 2548further information. 2549 2550The @code{aligned} attribute can also be used for variables and fields 2551(@pxref{Variable Attributes}.) 2552 2553@item alloc_align (@var{position}) 2554@cindex @code{alloc_align} function attribute 2555The @code{alloc_align} attribute may be applied to a function that 2556returns a pointer and takes at least one argument of an integer or 2557enumerated type. 2558It indicates that the returned pointer is aligned on a boundary given 2559by the function argument at @var{position}. Meaningful alignments are 2560powers of 2 greater than one. GCC uses this information to improve 2561pointer alignment analysis. 2562 2563The function parameter denoting the allocated alignment is specified by 2564one constant integer argument whose number is the argument of the attribute. 2565Argument numbering starts at one. 2566 2567For instance, 2568 2569@smallexample 2570void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1))); 2571@end smallexample 2572 2573@noindent 2574declares that @code{my_memalign} returns memory with minimum alignment 2575given by parameter 1. 2576 2577@item alloc_size (@var{position}) 2578@itemx alloc_size (@var{position-1}, @var{position-2}) 2579@cindex @code{alloc_size} function attribute 2580The @code{alloc_size} attribute may be applied to a function that 2581returns a pointer and takes at least one argument of an integer or 2582enumerated type. 2583It indicates that the returned pointer points to memory whose size is 2584given by the function argument at @var{position-1}, or by the product 2585of the arguments at @var{position-1} and @var{position-2}. Meaningful 2586sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this 2587information to improve the results of @code{__builtin_object_size}. 2588 2589The function parameter(s) denoting the allocated size are specified by 2590one or two integer arguments supplied to the attribute. The allocated size 2591is either the value of the single function argument specified or the product 2592of the two function arguments specified. Argument numbering starts at 2593one for ordinary functions, and at two for C++ non-static member functions. 2594 2595For instance, 2596 2597@smallexample 2598void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2))); 2599void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2))); 2600@end smallexample 2601 2602@noindent 2603declares that @code{my_calloc} returns memory of the size given by 2604the product of parameter 1 and 2 and that @code{my_realloc} returns memory 2605of the size given by parameter 2. 2606 2607@item always_inline 2608@cindex @code{always_inline} function attribute 2609Generally, functions are not inlined unless optimization is specified. 2610For functions declared inline, this attribute inlines the function 2611independent of any restrictions that otherwise apply to inlining. 2612Failure to inline such a function is diagnosed as an error. 2613Note that if such a function is called indirectly the compiler may 2614or may not inline it depending on optimization level and a failure 2615to inline an indirect call may or may not be diagnosed. 2616 2617@item artificial 2618@cindex @code{artificial} function attribute 2619This attribute is useful for small inline wrappers that if possible 2620should appear during debugging as a unit. Depending on the debug 2621info format it either means marking the function as artificial 2622or using the caller location for all instructions within the inlined 2623body. 2624 2625@item assume_aligned (@var{alignment}) 2626@itemx assume_aligned (@var{alignment}, @var{offset}) 2627@cindex @code{assume_aligned} function attribute 2628The @code{assume_aligned} attribute may be applied to a function that 2629returns a pointer. It indicates that the returned pointer is aligned 2630on a boundary given by @var{alignment}. If the attribute has two 2631arguments, the second argument is misalignment @var{offset}. Meaningful 2632values of @var{alignment} are powers of 2 greater than one. Meaningful 2633values of @var{offset} are greater than zero and less than @var{alignment}. 2634 2635For instance 2636 2637@smallexample 2638void* my_alloc1 (size_t) __attribute__((assume_aligned (16))); 2639void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8))); 2640@end smallexample 2641 2642@noindent 2643declares that @code{my_alloc1} returns 16-byte aligned pointers and 2644that @code{my_alloc2} returns a pointer whose value modulo 32 is equal 2645to 8. 2646 2647@item cold 2648@cindex @code{cold} function attribute 2649The @code{cold} attribute on functions is used to inform the compiler that 2650the function is unlikely to be executed. The function is optimized for 2651size rather than speed and on many targets it is placed into a special 2652subsection of the text section so all cold functions appear close together, 2653improving code locality of non-cold parts of program. The paths leading 2654to calls of cold functions within code are marked as unlikely by the branch 2655prediction mechanism. It is thus useful to mark functions used to handle 2656unlikely conditions, such as @code{perror}, as cold to improve optimization 2657of hot functions that do call marked functions in rare occasions. 2658 2659When profile feedback is available, via @option{-fprofile-use}, cold functions 2660are automatically detected and this attribute is ignored. 2661 2662@item const 2663@cindex @code{const} function attribute 2664@cindex functions that have no side effects 2665Calls to functions whose return value is not affected by changes to 2666the observable state of the program and that have no observable effects 2667on such state other than to return a value may lend themselves to 2668optimizations such as common subexpression elimination. Declaring such 2669functions with the @code{const} attribute allows GCC to avoid emitting 2670some calls in repeated invocations of the function with the same argument 2671values. 2672 2673For example, 2674 2675@smallexample 2676int square (int) __attribute__ ((const)); 2677@end smallexample 2678 2679@noindent 2680tells GCC that subsequent calls to function @code{square} with the same 2681argument value can be replaced by the result of the first call regardless 2682of the statements in between. 2683 2684The @code{const} attribute prohibits a function from reading objects 2685that affect its return value between successive invocations. However, 2686functions declared with the attribute can safely read objects that do 2687not change their return value, such as non-volatile constants. 2688 2689The @code{const} attribute imposes greater restrictions on a function's 2690definition than the similar @code{pure} attribute. Declaring the same 2691function with both the @code{const} and the @code{pure} attribute is 2692diagnosed. Because a const function cannot have any observable side 2693effects it does not make sense for it to return @code{void}. Declaring 2694such a function is diagnosed. 2695 2696@cindex pointer arguments 2697Note that a function that has pointer arguments and examines the data 2698pointed to must @emph{not} be declared @code{const} if the pointed-to 2699data might change between successive invocations of the function. In 2700general, since a function cannot distinguish data that might change 2701from data that cannot, const functions should never take pointer or, 2702in C++, reference arguments. Likewise, a function that calls a non-const 2703function usually must not be const itself. 2704 2705@item constructor 2706@itemx destructor 2707@itemx constructor (@var{priority}) 2708@itemx destructor (@var{priority}) 2709@cindex @code{constructor} function attribute 2710@cindex @code{destructor} function attribute 2711The @code{constructor} attribute causes the function to be called 2712automatically before execution enters @code{main ()}. Similarly, the 2713@code{destructor} attribute causes the function to be called 2714automatically after @code{main ()} completes or @code{exit ()} is 2715called. Functions with these attributes are useful for 2716initializing data that is used implicitly during the execution of 2717the program. 2718 2719On some targets the attributes also accept an integer argument to 2720specify a priority to control the order in which constructor and 2721destructor functions are run. A constructor 2722with a smaller priority number runs before a constructor with a larger 2723priority number; the opposite relationship holds for destructors. So, 2724if you have a constructor that allocates a resource and a destructor 2725that deallocates the same resource, both functions typically have the 2726same priority. The priorities for constructor and destructor 2727functions are the same as those specified for namespace-scope C++ 2728objects (@pxref{C++ Attributes}). However, at present, the order in which 2729constructors for C++ objects with static storage duration and functions 2730decorated with attribute @code{constructor} are invoked is unspecified. 2731In mixed declarations, attribute @code{init_priority} can be used to 2732impose a specific ordering. 2733 2734Using the argument forms of the @code{constructor} and @code{destructor} 2735attributes on targets where the feature is not supported is rejected with 2736an error. 2737 2738@item copy 2739@itemx copy (@var{function}) 2740@cindex @code{copy} function attribute 2741The @code{copy} attribute applies the set of attributes with which 2742@var{function} has been declared to the declaration of the function 2743to which the attribute is applied. The attribute is designed for 2744libraries that define aliases or function resolvers that are expected 2745to specify the same set of attributes as their targets. The @code{copy} 2746attribute can be used with functions, variables, or types. However, 2747the kind of symbol to which the attribute is applied (either function 2748or variable) must match the kind of symbol to which the argument refers. 2749The @code{copy} attribute copies only syntactic and semantic attributes 2750but not attributes that affect a symbol's linkage or visibility such as 2751@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} 2752attribute is also not copied. @xref{Common Type Attributes}. 2753@xref{Common Variable Attributes}. 2754 2755For example, the @var{StrongAlias} macro below makes use of the @code{alias} 2756and @code{copy} attributes to define an alias named @var{alloc} for function 2757@var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and 2758@var{nothrow}. Thanks to the @code{__typeof__} operator the alias has 2759the same type as the target function. As a result of the @code{copy} 2760attribute the alias also shares the same attributes as the target. 2761 2762@smallexample 2763#define StrongAlias(TagetFunc, AliasDecl) \ 2764 extern __typeof__ (TargetFunc) AliasDecl \ 2765 __attribute__ ((alias (#TargetFunc), copy (TargetFunc))); 2766 2767extern __attribute__ ((alloc_size (1), malloc, nothrow)) 2768 void* allocate (size_t); 2769StrongAlias (allocate, alloc); 2770@end smallexample 2771 2772@item deprecated 2773@itemx deprecated (@var{msg}) 2774@cindex @code{deprecated} function attribute 2775The @code{deprecated} attribute results in a warning if the function 2776is used anywhere in the source file. This is useful when identifying 2777functions that are expected to be removed in a future version of a 2778program. The warning also includes the location of the declaration 2779of the deprecated function, to enable users to easily find further 2780information about why the function is deprecated, or what they should 2781do instead. Note that the warnings only occurs for uses: 2782 2783@smallexample 2784int old_fn () __attribute__ ((deprecated)); 2785int old_fn (); 2786int (*fn_ptr)() = old_fn; 2787@end smallexample 2788 2789@noindent 2790results in a warning on line 3 but not line 2. The optional @var{msg} 2791argument, which must be a string, is printed in the warning if 2792present. 2793 2794The @code{deprecated} attribute can also be used for variables and 2795types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) 2796 2797The message attached to the attribute is affected by the setting of 2798the @option{-fmessage-length} option. 2799 2800@item error ("@var{message}") 2801@itemx warning ("@var{message}") 2802@cindex @code{error} function attribute 2803@cindex @code{warning} function attribute 2804If the @code{error} or @code{warning} attribute 2805is used on a function declaration and a call to such a function 2806is not eliminated through dead code elimination or other optimizations, 2807an error or warning (respectively) that includes @var{message} is diagnosed. 2808This is useful 2809for compile-time checking, especially together with @code{__builtin_constant_p} 2810and inline functions where checking the inline function arguments is not 2811possible through @code{extern char [(condition) ? 1 : -1];} tricks. 2812 2813While it is possible to leave the function undefined and thus invoke 2814a link failure (to define the function with 2815a message in @code{.gnu.warning*} section), 2816when using these attributes the problem is diagnosed 2817earlier and with exact location of the call even in presence of inline 2818functions or when not emitting debugging information. 2819 2820@item externally_visible 2821@cindex @code{externally_visible} function attribute 2822This attribute, attached to a global variable or function, nullifies 2823the effect of the @option{-fwhole-program} command-line option, so the 2824object remains visible outside the current compilation unit. 2825 2826If @option{-fwhole-program} is used together with @option{-flto} and 2827@command{gold} is used as the linker plugin, 2828@code{externally_visible} attributes are automatically added to functions 2829(not variable yet due to a current @command{gold} issue) 2830that are accessed outside of LTO objects according to resolution file 2831produced by @command{gold}. 2832For other linkers that cannot generate resolution file, 2833explicit @code{externally_visible} attributes are still necessary. 2834 2835@item flatten 2836@cindex @code{flatten} function attribute 2837Generally, inlining into a function is limited. For a function marked with 2838this attribute, every call inside this function is inlined, if possible. 2839Functions declared with attribute @code{noinline} and similar are not 2840inlined. Whether the function itself is considered for inlining depends 2841on its size and the current inlining parameters. 2842 2843@item format (@var{archetype}, @var{string-index}, @var{first-to-check}) 2844@cindex @code{format} function attribute 2845@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments 2846@opindex Wformat 2847The @code{format} attribute specifies that a function takes @code{printf}, 2848@code{scanf}, @code{strftime} or @code{strfmon} style arguments that 2849should be type-checked against a format string. For example, the 2850declaration: 2851 2852@smallexample 2853extern int 2854my_printf (void *my_object, const char *my_format, ...) 2855 __attribute__ ((format (printf, 2, 3))); 2856@end smallexample 2857 2858@noindent 2859causes the compiler to check the arguments in calls to @code{my_printf} 2860for consistency with the @code{printf} style format string argument 2861@code{my_format}. 2862 2863The parameter @var{archetype} determines how the format string is 2864interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}, 2865@code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or 2866@code{strfmon}. (You can also use @code{__printf__}, 2867@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On 2868MinGW targets, @code{ms_printf}, @code{ms_scanf}, and 2869@code{ms_strftime} are also present. 2870@var{archetype} values such as @code{printf} refer to the formats accepted 2871by the system's C runtime library, 2872while values prefixed with @samp{gnu_} always refer 2873to the formats accepted by the GNU C Library. On Microsoft Windows 2874targets, values prefixed with @samp{ms_} refer to the formats accepted by the 2875@file{msvcrt.dll} library. 2876The parameter @var{string-index} 2877specifies which argument is the format string argument (starting 2878from 1), while @var{first-to-check} is the number of the first 2879argument to check against the format string. For functions 2880where the arguments are not available to be checked (such as 2881@code{vprintf}), specify the third parameter as zero. In this case the 2882compiler only checks the format string for consistency. For 2883@code{strftime} formats, the third parameter is required to be zero. 2884Since non-static C++ methods have an implicit @code{this} argument, the 2885arguments of such methods should be counted from two, not one, when 2886giving values for @var{string-index} and @var{first-to-check}. 2887 2888In the example above, the format string (@code{my_format}) is the second 2889argument of the function @code{my_print}, and the arguments to check 2890start with the third argument, so the correct parameters for the format 2891attribute are 2 and 3. 2892 2893@opindex ffreestanding 2894@opindex fno-builtin 2895The @code{format} attribute allows you to identify your own functions 2896that take format strings as arguments, so that GCC can check the 2897calls to these functions for errors. The compiler always (unless 2898@option{-ffreestanding} or @option{-fno-builtin} is used) checks formats 2899for the standard library functions @code{printf}, @code{fprintf}, 2900@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime}, 2901@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such 2902warnings are requested (using @option{-Wformat}), so there is no need to 2903modify the header file @file{stdio.h}. In C99 mode, the functions 2904@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and 2905@code{vsscanf} are also checked. Except in strictly conforming C 2906standard modes, the X/Open function @code{strfmon} is also checked as 2907are @code{printf_unlocked} and @code{fprintf_unlocked}. 2908@xref{C Dialect Options,,Options Controlling C Dialect}. 2909 2910For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is 2911recognized in the same context. Declarations including these format attributes 2912are parsed for correct syntax, however the result of checking of such format 2913strings is not yet defined, and is not carried out by this version of the 2914compiler. 2915 2916The target may also provide additional types of format checks. 2917@xref{Target Format Checks,,Format Checks Specific to Particular 2918Target Machines}. 2919 2920@item format_arg (@var{string-index}) 2921@cindex @code{format_arg} function attribute 2922@opindex Wformat-nonliteral 2923The @code{format_arg} attribute specifies that a function takes one or 2924more format strings for a @code{printf}, @code{scanf}, @code{strftime} or 2925@code{strfmon} style function and modifies it (for example, to translate 2926it into another language), so the result can be passed to a 2927@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style 2928function (with the remaining arguments to the format function the same 2929as they would have been for the unmodified string). Multiple 2930@code{format_arg} attributes may be applied to the same function, each 2931designating a distinct parameter as a format string. For example, the 2932declaration: 2933 2934@smallexample 2935extern char * 2936my_dgettext (char *my_domain, const char *my_format) 2937 __attribute__ ((format_arg (2))); 2938@end smallexample 2939 2940@noindent 2941causes the compiler to check the arguments in calls to a @code{printf}, 2942@code{scanf}, @code{strftime} or @code{strfmon} type function, whose 2943format string argument is a call to the @code{my_dgettext} function, for 2944consistency with the format string argument @code{my_format}. If the 2945@code{format_arg} attribute had not been specified, all the compiler 2946could tell in such calls to format functions would be that the format 2947string argument is not constant; this would generate a warning when 2948@option{-Wformat-nonliteral} is used, but the calls could not be checked 2949without the attribute. 2950 2951In calls to a function declared with more than one @code{format_arg} 2952attribute, each with a distinct argument value, the corresponding 2953actual function arguments are checked against all format strings 2954designated by the attributes. This capability is designed to support 2955the GNU @code{ngettext} family of functions. 2956 2957The parameter @var{string-index} specifies which argument is the format 2958string argument (starting from one). Since non-static C++ methods have 2959an implicit @code{this} argument, the arguments of such methods should 2960be counted from two. 2961 2962The @code{format_arg} attribute allows you to identify your own 2963functions that modify format strings, so that GCC can check the 2964calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} 2965type function whose operands are a call to one of your own function. 2966The compiler always treats @code{gettext}, @code{dgettext}, and 2967@code{dcgettext} in this manner except when strict ISO C support is 2968requested by @option{-ansi} or an appropriate @option{-std} option, or 2969@option{-ffreestanding} or @option{-fno-builtin} 2970is used. @xref{C Dialect Options,,Options 2971Controlling C Dialect}. 2972 2973For Objective-C dialects, the @code{format-arg} attribute may refer to an 2974@code{NSString} reference for compatibility with the @code{format} attribute 2975above. 2976 2977The target may also allow additional types in @code{format-arg} attributes. 2978@xref{Target Format Checks,,Format Checks Specific to Particular 2979Target Machines}. 2980 2981@item gnu_inline 2982@cindex @code{gnu_inline} function attribute 2983This attribute should be used with a function that is also declared 2984with the @code{inline} keyword. It directs GCC to treat the function 2985as if it were defined in gnu90 mode even when compiling in C99 or 2986gnu99 mode. 2987 2988If the function is declared @code{extern}, then this definition of the 2989function is used only for inlining. In no case is the function 2990compiled as a standalone function, not even if you take its address 2991explicitly. Such an address becomes an external reference, as if you 2992had only declared the function, and had not defined it. This has 2993almost the effect of a macro. The way to use this is to put a 2994function definition in a header file with this attribute, and put 2995another copy of the function, without @code{extern}, in a library 2996file. The definition in the header file causes most calls to the 2997function to be inlined. If any uses of the function remain, they 2998refer to the single copy in the library. Note that the two 2999definitions of the functions need not be precisely the same, although 3000if they do not have the same effect your program may behave oddly. 3001 3002In C, if the function is neither @code{extern} nor @code{static}, then 3003the function is compiled as a standalone function, as well as being 3004inlined where possible. 3005 3006This is how GCC traditionally handled functions declared 3007@code{inline}. Since ISO C99 specifies a different semantics for 3008@code{inline}, this function attribute is provided as a transition 3009measure and as a useful feature in its own right. This attribute is 3010available in GCC 4.1.3 and later. It is available if either of the 3011preprocessor macros @code{__GNUC_GNU_INLINE__} or 3012@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline 3013Function is As Fast As a Macro}. 3014 3015In C++, this attribute does not depend on @code{extern} in any way, 3016but it still requires the @code{inline} keyword to enable its special 3017behavior. 3018 3019@item hot 3020@cindex @code{hot} function attribute 3021The @code{hot} attribute on a function is used to inform the compiler that 3022the function is a hot spot of the compiled program. The function is 3023optimized more aggressively and on many targets it is placed into a special 3024subsection of the text section so all hot functions appear close together, 3025improving locality. 3026 3027When profile feedback is available, via @option{-fprofile-use}, hot functions 3028are automatically detected and this attribute is ignored. 3029 3030@item ifunc ("@var{resolver}") 3031@cindex @code{ifunc} function attribute 3032@cindex indirect functions 3033@cindex functions that are dynamically resolved 3034The @code{ifunc} attribute is used to mark a function as an indirect 3035function using the STT_GNU_IFUNC symbol type extension to the ELF 3036standard. This allows the resolution of the symbol value to be 3037determined dynamically at load time, and an optimized version of the 3038routine to be selected for the particular processor or other system 3039characteristics determined then. To use this attribute, first define 3040the implementation functions available, and a resolver function that 3041returns a pointer to the selected implementation function. The 3042implementation functions' declarations must match the API of the 3043function being implemented. The resolver should be declared to 3044be a function taking no arguments and returning a pointer to 3045a function of the same type as the implementation. For example: 3046 3047@smallexample 3048void *my_memcpy (void *dst, const void *src, size_t len) 3049@{ 3050 @dots{} 3051 return dst; 3052@} 3053 3054static void * (*resolve_memcpy (void))(void *, const void *, size_t) 3055@{ 3056 return my_memcpy; // we will just always select this routine 3057@} 3058@end smallexample 3059 3060@noindent 3061The exported header file declaring the function the user calls would 3062contain: 3063 3064@smallexample 3065extern void *memcpy (void *, const void *, size_t); 3066@end smallexample 3067 3068@noindent 3069allowing the user to call @code{memcpy} as a regular function, unaware of 3070the actual implementation. Finally, the indirect function needs to be 3071defined in the same translation unit as the resolver function: 3072 3073@smallexample 3074void *memcpy (void *, const void *, size_t) 3075 __attribute__ ((ifunc ("resolve_memcpy"))); 3076@end smallexample 3077 3078In C++, the @code{ifunc} attribute takes a string that is the mangled name 3079of the resolver function. A C++ resolver for a non-static member function 3080of class @code{C} should be declared to return a pointer to a non-member 3081function taking pointer to @code{C} as the first argument, followed by 3082the same arguments as of the implementation function. G++ checks 3083the signatures of the two functions and issues 3084a @option{-Wattribute-alias} warning for mismatches. To suppress a warning 3085for the necessary cast from a pointer to the implementation member function 3086to the type of the corresponding non-member function use 3087the @option{-Wno-pmf-conversions} option. For example: 3088 3089@smallexample 3090class S 3091@{ 3092private: 3093 int debug_impl (int); 3094 int optimized_impl (int); 3095 3096 typedef int Func (S*, int); 3097 3098 static Func* resolver (); 3099public: 3100 3101 int interface (int); 3102@}; 3103 3104int S::debug_impl (int) @{ /* @r{@dots{}} */ @} 3105int S::optimized_impl (int) @{ /* @r{@dots{}} */ @} 3106 3107S::Func* S::resolver () 3108@{ 3109 int (S::*pimpl) (int) 3110 = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl; 3111 3112 // Cast triggers -Wno-pmf-conversions. 3113 return reinterpret_cast<Func*>(pimpl); 3114@} 3115 3116int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv"))); 3117@end smallexample 3118 3119Indirect functions cannot be weak. Binutils version 2.20.1 or higher 3120and GNU C Library version 2.11.1 are required to use this feature. 3121 3122@item interrupt 3123@itemx interrupt_handler 3124Many GCC back ends support attributes to indicate that a function is 3125an interrupt handler, which tells the compiler to generate function 3126entry and exit sequences that differ from those from regular 3127functions. The exact syntax and behavior are target-specific; 3128refer to the following subsections for details. 3129 3130@item leaf 3131@cindex @code{leaf} function attribute 3132Calls to external functions with this attribute must return to the 3133current compilation unit only by return or by exception handling. In 3134particular, a leaf function is not allowed to invoke callback functions 3135passed to it from the current compilation unit, directly call functions 3136exported by the unit, or @code{longjmp} into the unit. Leaf functions 3137might still call functions from other compilation units and thus they 3138are not necessarily leaf in the sense that they contain no function 3139calls at all. 3140 3141The attribute is intended for library functions to improve dataflow 3142analysis. The compiler takes the hint that any data not escaping the 3143current compilation unit cannot be used or modified by the leaf 3144function. For example, the @code{sin} function is a leaf function, but 3145@code{qsort} is not. 3146 3147Note that leaf functions might indirectly run a signal handler defined 3148in the current compilation unit that uses static variables. Similarly, 3149when lazy symbol resolution is in effect, leaf functions might invoke 3150indirect functions whose resolver function or implementation function is 3151defined in the current compilation unit and uses static variables. There 3152is no standard-compliant way to write such a signal handler, resolver 3153function, or implementation function, and the best that you can do is to 3154remove the @code{leaf} attribute or mark all such static variables 3155@code{volatile}. Lastly, for ELF-based systems that support symbol 3156interposition, care should be taken that functions defined in the 3157current compilation unit do not unexpectedly interpose other symbols 3158based on the defined standards mode and defined feature test macros; 3159otherwise an inadvertent callback would be added. 3160 3161The attribute has no effect on functions defined within the current 3162compilation unit. This is to allow easy merging of multiple compilation 3163units into one, for example, by using the link-time optimization. For 3164this reason the attribute is not allowed on types to annotate indirect 3165calls. 3166 3167@item malloc 3168@cindex @code{malloc} function attribute 3169@cindex functions that behave like malloc 3170This tells the compiler that a function is @code{malloc}-like, i.e., 3171that the pointer @var{P} returned by the function cannot alias any 3172other pointer valid when the function returns, and moreover no 3173pointers to valid objects occur in any storage addressed by @var{P}. 3174 3175Using this attribute can improve optimization. Compiler predicts 3176that a function with the attribute returns non-null in most cases. 3177Functions like 3178@code{malloc} and @code{calloc} have this property because they return 3179a pointer to uninitialized or zeroed-out storage. However, functions 3180like @code{realloc} do not have this property, as they can return a 3181pointer to storage containing pointers. 3182 3183@item no_icf 3184@cindex @code{no_icf} function attribute 3185This function attribute prevents a functions from being merged with another 3186semantically equivalent function. 3187 3188@item no_instrument_function 3189@cindex @code{no_instrument_function} function attribute 3190@opindex finstrument-functions 3191@opindex p 3192@opindex pg 3193If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are 3194given, profiling function calls are 3195generated at entry and exit of most user-compiled functions. 3196Functions with this attribute are not so instrumented. 3197 3198@item no_profile_instrument_function 3199@cindex @code{no_profile_instrument_function} function attribute 3200The @code{no_profile_instrument_function} attribute on functions is used 3201to inform the compiler that it should not process any profile feedback based 3202optimization code instrumentation. 3203 3204@item no_reorder 3205@cindex @code{no_reorder} function attribute 3206Do not reorder functions or variables marked @code{no_reorder} 3207against each other or top level assembler statements the executable. 3208The actual order in the program will depend on the linker command 3209line. Static variables marked like this are also not removed. 3210This has a similar effect 3211as the @option{-fno-toplevel-reorder} option, but only applies to the 3212marked symbols. 3213 3214@item no_sanitize ("@var{sanitize_option}") 3215@cindex @code{no_sanitize} function attribute 3216The @code{no_sanitize} attribute on functions is used 3217to inform the compiler that it should not do sanitization of all options 3218mentioned in @var{sanitize_option}. A list of values acceptable by 3219@option{-fsanitize} option can be provided. 3220 3221@smallexample 3222void __attribute__ ((no_sanitize ("alignment", "object-size"))) 3223f () @{ /* @r{Do something.} */; @} 3224void __attribute__ ((no_sanitize ("alignment,object-size"))) 3225g () @{ /* @r{Do something.} */; @} 3226@end smallexample 3227 3228@item no_sanitize_address 3229@itemx no_address_safety_analysis 3230@cindex @code{no_sanitize_address} function attribute 3231The @code{no_sanitize_address} attribute on functions is used 3232to inform the compiler that it should not instrument memory accesses 3233in the function when compiling with the @option{-fsanitize=address} option. 3234The @code{no_address_safety_analysis} is a deprecated alias of the 3235@code{no_sanitize_address} attribute, new code should use 3236@code{no_sanitize_address}. 3237 3238@item no_sanitize_thread 3239@cindex @code{no_sanitize_thread} function attribute 3240The @code{no_sanitize_thread} attribute on functions is used 3241to inform the compiler that it should not instrument memory accesses 3242in the function when compiling with the @option{-fsanitize=thread} option. 3243 3244@item no_sanitize_undefined 3245@cindex @code{no_sanitize_undefined} function attribute 3246The @code{no_sanitize_undefined} attribute on functions is used 3247to inform the compiler that it should not check for undefined behavior 3248in the function when compiling with the @option{-fsanitize=undefined} option. 3249 3250@item no_split_stack 3251@cindex @code{no_split_stack} function attribute 3252@opindex fsplit-stack 3253If @option{-fsplit-stack} is given, functions have a small 3254prologue which decides whether to split the stack. Functions with the 3255@code{no_split_stack} attribute do not have that prologue, and thus 3256may run with only a small amount of stack space available. 3257 3258@item no_stack_limit 3259@cindex @code{no_stack_limit} function attribute 3260This attribute locally overrides the @option{-fstack-limit-register} 3261and @option{-fstack-limit-symbol} command-line options; it has the effect 3262of disabling stack limit checking in the function it applies to. 3263 3264@item noclone 3265@cindex @code{noclone} function attribute 3266This function attribute prevents a function from being considered for 3267cloning---a mechanism that produces specialized copies of functions 3268and which is (currently) performed by interprocedural constant 3269propagation. 3270 3271@item noinline 3272@cindex @code{noinline} function attribute 3273This function attribute prevents a function from being considered for 3274inlining. 3275@c Don't enumerate the optimizations by name here; we try to be 3276@c future-compatible with this mechanism. 3277If the function does not have side effects, there are optimizations 3278other than inlining that cause function calls to be optimized away, 3279although the function call is live. To keep such calls from being 3280optimized away, put 3281@smallexample 3282asm (""); 3283@end smallexample 3284 3285@noindent 3286(@pxref{Extended Asm}) in the called function, to serve as a special 3287side effect. 3288 3289@item noipa 3290@cindex @code{noipa} function attribute 3291Disable interprocedural optimizations between the function with this 3292attribute and its callers, as if the body of the function is not available 3293when optimizing callers and the callers are unavailable when optimizing 3294the body. This attribute implies @code{noinline}, @code{noclone} and 3295@code{no_icf} attributes. However, this attribute is not equivalent 3296to a combination of other attributes, because its purpose is to suppress 3297existing and future optimizations employing interprocedural analysis, 3298including those that do not have an attribute suitable for disabling 3299them individually. This attribute is supported mainly for the purpose 3300of testing the compiler. 3301 3302@item nonnull 3303@itemx nonnull (@var{arg-index}, @dots{}) 3304@cindex @code{nonnull} function attribute 3305@cindex functions with non-null pointer arguments 3306The @code{nonnull} attribute may be applied to a function that takes at 3307least one argument of a pointer type. It indicates that the referenced 3308arguments must be non-null pointers. For instance, the declaration: 3309 3310@smallexample 3311extern void * 3312my_memcpy (void *dest, const void *src, size_t len) 3313 __attribute__((nonnull (1, 2))); 3314@end smallexample 3315 3316@noindent 3317causes the compiler to check that, in calls to @code{my_memcpy}, 3318arguments @var{dest} and @var{src} are non-null. If the compiler 3319determines that a null pointer is passed in an argument slot marked 3320as non-null, and the @option{-Wnonnull} option is enabled, a warning 3321is issued. @xref{Warning Options}. Unless disabled by 3322the @option{-fno-delete-null-pointer-checks} option the compiler may 3323also perform optimizations based on the knowledge that certain function 3324arguments cannot be null. In addition, 3325the @option{-fisolate-erroneous-paths-attribute} option can be specified 3326to have GCC transform calls with null arguments to non-null functions 3327into traps. @xref{Optimize Options}. 3328 3329If no @var{arg-index} is given to the @code{nonnull} attribute, 3330all pointer arguments are marked as non-null. To illustrate, the 3331following declaration is equivalent to the previous example: 3332 3333@smallexample 3334extern void * 3335my_memcpy (void *dest, const void *src, size_t len) 3336 __attribute__((nonnull)); 3337@end smallexample 3338 3339@item noplt 3340@cindex @code{noplt} function attribute 3341The @code{noplt} attribute is the counterpart to option @option{-fno-plt}. 3342Calls to functions marked with this attribute in position-independent code 3343do not use the PLT. 3344 3345@smallexample 3346@group 3347/* Externally defined function foo. */ 3348int foo () __attribute__ ((noplt)); 3349 3350int 3351main (/* @r{@dots{}} */) 3352@{ 3353 /* @r{@dots{}} */ 3354 foo (); 3355 /* @r{@dots{}} */ 3356@} 3357@end group 3358@end smallexample 3359 3360The @code{noplt} attribute on function @code{foo} 3361tells the compiler to assume that 3362the function @code{foo} is externally defined and that the call to 3363@code{foo} must avoid the PLT 3364in position-independent code. 3365 3366In position-dependent code, a few targets also convert calls to 3367functions that are marked to not use the PLT to use the GOT instead. 3368 3369@item noreturn 3370@cindex @code{noreturn} function attribute 3371@cindex functions that never return 3372A few standard library functions, such as @code{abort} and @code{exit}, 3373cannot return. GCC knows this automatically. Some programs define 3374their own functions that never return. You can declare them 3375@code{noreturn} to tell the compiler this fact. For example, 3376 3377@smallexample 3378@group 3379void fatal () __attribute__ ((noreturn)); 3380 3381void 3382fatal (/* @r{@dots{}} */) 3383@{ 3384 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ 3385 exit (1); 3386@} 3387@end group 3388@end smallexample 3389 3390The @code{noreturn} keyword tells the compiler to assume that 3391@code{fatal} cannot return. It can then optimize without regard to what 3392would happen if @code{fatal} ever did return. This makes slightly 3393better code. More importantly, it helps avoid spurious warnings of 3394uninitialized variables. 3395 3396The @code{noreturn} keyword does not affect the exceptional path when that 3397applies: a @code{noreturn}-marked function may still return to the caller 3398by throwing an exception or calling @code{longjmp}. 3399 3400In order to preserve backtraces, GCC will never turn calls to 3401@code{noreturn} functions into tail calls. 3402 3403Do not assume that registers saved by the calling function are 3404restored before calling the @code{noreturn} function. 3405 3406It does not make sense for a @code{noreturn} function to have a return 3407type other than @code{void}. 3408 3409@item nothrow 3410@cindex @code{nothrow} function attribute 3411The @code{nothrow} attribute is used to inform the compiler that a 3412function cannot throw an exception. For example, most functions in 3413the standard C library can be guaranteed not to throw an exception 3414with the notable exceptions of @code{qsort} and @code{bsearch} that 3415take function pointer arguments. 3416 3417@item optimize (@var{level}, @dots{}) 3418@item optimize (@var{string}, @dots{}) 3419@cindex @code{optimize} function attribute 3420The @code{optimize} attribute is used to specify that a function is to 3421be compiled with different optimization options than specified on the 3422command line. Valid arguments are constant non-negative integers and 3423strings. Each numeric argument specifies an optimization @var{level}. 3424Each @var{string} argument consists of one or more comma-separated 3425substrings. Each substring that begins with the letter @code{O} refers 3426to an optimization option such as @option{-O0} or @option{-Os}. Other 3427substrings are taken as suffixes to the @code{-f} prefix jointly 3428forming the name of an optimization option. @xref{Optimize Options}. 3429 3430@samp{#pragma GCC optimize} can be used to set optimization options 3431for more than one function. @xref{Function Specific Option Pragmas}, 3432for details about the pragma. 3433 3434Providing multiple strings as arguments separated by commas to specify 3435multiple options is equivalent to separating the option suffixes with 3436a comma (@samp{,}) within a single string. Spaces are not permitted 3437within the strings. 3438 3439Not every optimization option that starts with the @var{-f} prefix 3440specified by the attribute necessarily has an effect on the function. 3441The @code{optimize} attribute should be used for debugging purposes only. 3442It is not suitable in production code. 3443 3444@item patchable_function_entry 3445@cindex @code{patchable_function_entry} function attribute 3446@cindex extra NOP instructions at the function entry point 3447In case the target's text segment can be made writable at run time by 3448any means, padding the function entry with a number of NOPs can be 3449used to provide a universal tool for instrumentation. 3450 3451The @code{patchable_function_entry} function attribute can be used to 3452change the number of NOPs to any desired value. The two-value syntax 3453is the same as for the command-line switch 3454@option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with 3455the function entry point before the @var{M}th NOP instruction. 3456@var{M} defaults to 0 if omitted e.g.@: function entry point is before 3457the first NOP. 3458 3459If patchable function entries are enabled globally using the command-line 3460option @option{-fpatchable-function-entry=N,M}, then you must disable 3461instrumentation on all functions that are part of the instrumentation 3462framework with the attribute @code{patchable_function_entry (0)} 3463to prevent recursion. 3464 3465@item pure 3466@cindex @code{pure} function attribute 3467@cindex functions that have no side effects 3468 3469Calls to functions that have no observable effects on the state of 3470the program other than to return a value may lend themselves to optimizations 3471such as common subexpression elimination. Declaring such functions with 3472the @code{pure} attribute allows GCC to avoid emitting some calls in repeated 3473invocations of the function with the same argument values. 3474 3475The @code{pure} attribute prohibits a function from modifying the state 3476of the program that is observable by means other than inspecting 3477the function's return value. However, functions declared with the @code{pure} 3478attribute can safely read any non-volatile objects, and modify the value of 3479objects in a way that does not affect their return value or the observable 3480state of the program. 3481 3482For example, 3483 3484@smallexample 3485int hash (char *) __attribute__ ((pure)); 3486@end smallexample 3487 3488@noindent 3489tells GCC that subsequent calls to the function @code{hash} with the same 3490string can be replaced by the result of the first call provided the state 3491of the program observable by @code{hash}, including the contents of the array 3492itself, does not change in between. Even though @code{hash} takes a non-const 3493pointer argument it must not modify the array it points to, or any other object 3494whose value the rest of the program may depend on. However, the caller may 3495safely change the contents of the array between successive calls to 3496the function (doing so disables the optimization). The restriction also 3497applies to member objects referenced by the @code{this} pointer in C++ 3498non-static member functions. 3499 3500Some common examples of pure functions are @code{strlen} or @code{memcmp}. 3501Interesting non-pure functions are functions with infinite loops or those 3502depending on volatile memory or other system resource, that may change between 3503consecutive calls (such as the standard C @code{feof} function in 3504a multithreading environment). 3505 3506The @code{pure} attribute imposes similar but looser restrictions on 3507a function's definition than the @code{const} attribute: @code{pure} 3508allows the function to read any non-volatile memory, even if it changes 3509in between successive invocations of the function. Declaring the same 3510function with both the @code{pure} and the @code{const} attribute is 3511diagnosed. Because a pure function cannot have any observable side 3512effects it does not make sense for such a function to return @code{void}. 3513Declaring such a function is diagnosed. 3514 3515@item returns_nonnull 3516@cindex @code{returns_nonnull} function attribute 3517The @code{returns_nonnull} attribute specifies that the function 3518return value should be a non-null pointer. For instance, the declaration: 3519 3520@smallexample 3521extern void * 3522mymalloc (size_t len) __attribute__((returns_nonnull)); 3523@end smallexample 3524 3525@noindent 3526lets the compiler optimize callers based on the knowledge 3527that the return value will never be null. 3528 3529@item returns_twice 3530@cindex @code{returns_twice} function attribute 3531@cindex functions that return more than once 3532The @code{returns_twice} attribute tells the compiler that a function may 3533return more than one time. The compiler ensures that all registers 3534are dead before calling such a function and emits a warning about 3535the variables that may be clobbered after the second return from the 3536function. Examples of such functions are @code{setjmp} and @code{vfork}. 3537The @code{longjmp}-like counterpart of such function, if any, might need 3538to be marked with the @code{noreturn} attribute. 3539 3540@item section ("@var{section-name}") 3541@cindex @code{section} function attribute 3542@cindex functions in arbitrary sections 3543Normally, the compiler places the code it generates in the @code{text} section. 3544Sometimes, however, you need additional sections, or you need certain 3545particular functions to appear in special sections. The @code{section} 3546attribute specifies that a function lives in a particular section. 3547For example, the declaration: 3548 3549@smallexample 3550extern void foobar (void) __attribute__ ((section ("bar"))); 3551@end smallexample 3552 3553@noindent 3554puts the function @code{foobar} in the @code{bar} section. 3555 3556Some file formats do not support arbitrary sections so the @code{section} 3557attribute is not available on all platforms. 3558If you need to map the entire contents of a module to a particular 3559section, consider using the facilities of the linker instead. 3560 3561@item sentinel 3562@itemx sentinel (@var{position}) 3563@cindex @code{sentinel} function attribute 3564This function attribute indicates that an argument in a call to the function 3565is expected to be an explicit @code{NULL}. The attribute is only valid on 3566variadic functions. By default, the sentinel is expected to be the last 3567argument of the function call. If the optional @var{position} argument 3568is specified to the attribute, the sentinel must be located at 3569@var{position} counting backwards from the end of the argument list. 3570 3571@smallexample 3572__attribute__ ((sentinel)) 3573is equivalent to 3574__attribute__ ((sentinel(0))) 3575@end smallexample 3576 3577The attribute is automatically set with a position of 0 for the built-in 3578functions @code{execl} and @code{execlp}. The built-in function 3579@code{execle} has the attribute set with a position of 1. 3580 3581A valid @code{NULL} in this context is defined as zero with any object 3582pointer type. If your system defines the @code{NULL} macro with 3583an integer type then you need to add an explicit cast. During 3584installation GCC replaces the system @code{<stddef.h>} header with 3585a copy that redefines NULL appropriately. 3586 3587The warnings for missing or incorrect sentinels are enabled with 3588@option{-Wformat}. 3589 3590@item simd 3591@itemx simd("@var{mask}") 3592@cindex @code{simd} function attribute 3593This attribute enables creation of one or more function versions that 3594can process multiple arguments using SIMD instructions from a 3595single invocation. Specifying this attribute allows compiler to 3596assume that such versions are available at link time (provided 3597in the same or another translation unit). Generated versions are 3598target-dependent and described in the corresponding Vector ABI document. For 3599x86_64 target this document can be found 3600@w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}. 3601 3602The optional argument @var{mask} may have the value 3603@code{notinbranch} or @code{inbranch}, 3604and instructs the compiler to generate non-masked or masked 3605clones correspondingly. By default, all clones are generated. 3606 3607If the attribute is specified and @code{#pragma omp declare simd} is 3608present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd} 3609switch is specified, then the attribute is ignored. 3610 3611@item stack_protect 3612@cindex @code{stack_protect} function attribute 3613This attribute adds stack protection code to the function if 3614flags @option{-fstack-protector}, @option{-fstack-protector-strong} 3615or @option{-fstack-protector-explicit} are set. 3616 3617@item target (@var{string}, @dots{}) 3618@cindex @code{target} function attribute 3619Multiple target back ends implement the @code{target} attribute 3620to specify that a function is to 3621be compiled with different target options than specified on the 3622command line. One or more strings can be provided as arguments. 3623Each string consists of one or more comma-separated suffixes to 3624the @code{-m} prefix jointly forming the name of a machine-dependent 3625option. @xref{Submodel Options,,Machine-Dependent Options}. 3626 3627The @code{target} attribute can be used for instance to have a function 3628compiled with a different ISA (instruction set architecture) than the 3629default. @samp{#pragma GCC target} can be used to specify target-specific 3630options for more than one function. @xref{Function Specific Option Pragmas}, 3631for details about the pragma. 3632 3633For instance, on an x86, you could declare one function with the 3634@code{target("sse4.1,arch=core2")} attribute and another with 3635@code{target("sse4a,arch=amdfam10")}. This is equivalent to 3636compiling the first function with @option{-msse4.1} and 3637@option{-march=core2} options, and the second function with 3638@option{-msse4a} and @option{-march=amdfam10} options. It is up to you 3639to make sure that a function is only invoked on a machine that 3640supports the particular ISA it is compiled for (for example by using 3641@code{cpuid} on x86 to determine what feature bits and architecture 3642family are used). 3643 3644@smallexample 3645int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); 3646int sse3_func (void) __attribute__ ((__target__ ("sse3"))); 3647@end smallexample 3648 3649Providing multiple strings as arguments separated by commas to specify 3650multiple options is equivalent to separating the option suffixes with 3651a comma (@samp{,}) within a single string. Spaces are not permitted 3652within the strings. 3653 3654The options supported are specific to each target; refer to @ref{x86 3655Function Attributes}, @ref{PowerPC Function Attributes}, 3656@ref{ARM Function Attributes}, @ref{AArch64 Function Attributes}, 3657@ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes} 3658for details. 3659 3660@item target_clones (@var{options}) 3661@cindex @code{target_clones} function attribute 3662The @code{target_clones} attribute is used to specify that a function 3663be cloned into multiple versions compiled with different target options 3664than specified on the command line. The supported options and restrictions 3665are the same as for @code{target} attribute. 3666 3667For instance, on an x86, you could compile a function with 3668@code{target_clones("sse4.1,avx")}. GCC creates two function clones, 3669one compiled with @option{-msse4.1} and another with @option{-mavx}. 3670 3671On a PowerPC, you can compile a function with 3672@code{target_clones("cpu=power9,default")}. GCC will create two 3673function clones, one compiled with @option{-mcpu=power9} and another 3674with the default options. GCC must be configured to use GLIBC 2.23 or 3675newer in order to use the @code{target_clones} attribute. 3676 3677It also creates a resolver function (see 3678the @code{ifunc} attribute above) that dynamically selects a clone 3679suitable for current architecture. The resolver is created only if there 3680is a usage of a function with @code{target_clones} attribute. 3681 3682@item unused 3683@cindex @code{unused} function attribute 3684This attribute, attached to a function, means that the function is meant 3685to be possibly unused. GCC does not produce a warning for this 3686function. 3687 3688@item used 3689@cindex @code{used} function attribute 3690This attribute, attached to a function, means that code must be emitted 3691for the function even if it appears that the function is not referenced. 3692This is useful, for example, when the function is referenced only in 3693inline assembly. 3694 3695When applied to a member function of a C++ class template, the 3696attribute also means that the function is instantiated if the 3697class itself is instantiated. 3698 3699@item visibility ("@var{visibility_type}") 3700@cindex @code{visibility} function attribute 3701This attribute affects the linkage of the declaration to which it is attached. 3702It can be applied to variables (@pxref{Common Variable Attributes}) and types 3703(@pxref{Common Type Attributes}) as well as functions. 3704 3705There are four supported @var{visibility_type} values: default, 3706hidden, protected or internal visibility. 3707 3708@smallexample 3709void __attribute__ ((visibility ("protected"))) 3710f () @{ /* @r{Do something.} */; @} 3711int i __attribute__ ((visibility ("hidden"))); 3712@end smallexample 3713 3714The possible values of @var{visibility_type} correspond to the 3715visibility settings in the ELF gABI. 3716 3717@table @code 3718@c keep this list of visibilities in alphabetical order. 3719 3720@item default 3721Default visibility is the normal case for the object file format. 3722This value is available for the visibility attribute to override other 3723options that may change the assumed visibility of entities. 3724 3725On ELF, default visibility means that the declaration is visible to other 3726modules and, in shared libraries, means that the declared entity may be 3727overridden. 3728 3729On Darwin, default visibility means that the declaration is visible to 3730other modules. 3731 3732Default visibility corresponds to ``external linkage'' in the language. 3733 3734@item hidden 3735Hidden visibility indicates that the entity declared has a new 3736form of linkage, which we call ``hidden linkage''. Two 3737declarations of an object with hidden linkage refer to the same object 3738if they are in the same shared object. 3739 3740@item internal 3741Internal visibility is like hidden visibility, but with additional 3742processor specific semantics. Unless otherwise specified by the 3743psABI, GCC defines internal visibility to mean that a function is 3744@emph{never} called from another module. Compare this with hidden 3745functions which, while they cannot be referenced directly by other 3746modules, can be referenced indirectly via function pointers. By 3747indicating that a function cannot be called from outside the module, 3748GCC may for instance omit the load of a PIC register since it is known 3749that the calling function loaded the correct value. 3750 3751@item protected 3752Protected visibility is like default visibility except that it 3753indicates that references within the defining module bind to the 3754definition in that module. That is, the declared entity cannot be 3755overridden by another module. 3756 3757@end table 3758 3759All visibilities are supported on many, but not all, ELF targets 3760(supported when the assembler supports the @samp{.visibility} 3761pseudo-op). Default visibility is supported everywhere. Hidden 3762visibility is supported on Darwin targets. 3763 3764The visibility attribute should be applied only to declarations that 3765would otherwise have external linkage. The attribute should be applied 3766consistently, so that the same entity should not be declared with 3767different settings of the attribute. 3768 3769In C++, the visibility attribute applies to types as well as functions 3770and objects, because in C++ types have linkage. A class must not have 3771greater visibility than its non-static data member types and bases, 3772and class members default to the visibility of their class. Also, a 3773declaration without explicit visibility is limited to the visibility 3774of its type. 3775 3776In C++, you can mark member functions and static member variables of a 3777class with the visibility attribute. This is useful if you know a 3778particular method or static member variable should only be used from 3779one shared object; then you can mark it hidden while the rest of the 3780class has default visibility. Care must be taken to avoid breaking 3781the One Definition Rule; for example, it is usually not useful to mark 3782an inline method as hidden without marking the whole class as hidden. 3783 3784A C++ namespace declaration can also have the visibility attribute. 3785 3786@smallexample 3787namespace nspace1 __attribute__ ((visibility ("protected"))) 3788@{ /* @r{Do something.} */; @} 3789@end smallexample 3790 3791This attribute applies only to the particular namespace body, not to 3792other definitions of the same namespace; it is equivalent to using 3793@samp{#pragma GCC visibility} before and after the namespace 3794definition (@pxref{Visibility Pragmas}). 3795 3796In C++, if a template argument has limited visibility, this 3797restriction is implicitly propagated to the template instantiation. 3798Otherwise, template instantiations and specializations default to the 3799visibility of their template. 3800 3801If both the template and enclosing class have explicit visibility, the 3802visibility from the template is used. 3803 3804@item warn_unused_result 3805@cindex @code{warn_unused_result} function attribute 3806The @code{warn_unused_result} attribute causes a warning to be emitted 3807if a caller of the function with this attribute does not use its 3808return value. This is useful for functions where not checking 3809the result is either a security problem or always a bug, such as 3810@code{realloc}. 3811 3812@smallexample 3813int fn () __attribute__ ((warn_unused_result)); 3814int foo () 3815@{ 3816 if (fn () < 0) return -1; 3817 fn (); 3818 return 0; 3819@} 3820@end smallexample 3821 3822@noindent 3823results in warning on line 5. 3824 3825@item weak 3826@cindex @code{weak} function attribute 3827The @code{weak} attribute causes the declaration to be emitted as a weak 3828symbol rather than a global. This is primarily useful in defining 3829library functions that can be overridden in user code, though it can 3830also be used with non-function declarations. Weak symbols are supported 3831for ELF targets, and also for a.out targets when using the GNU assembler 3832and linker. 3833 3834@item weakref 3835@itemx weakref ("@var{target}") 3836@cindex @code{weakref} function attribute 3837The @code{weakref} attribute marks a declaration as a weak reference. 3838Without arguments, it should be accompanied by an @code{alias} attribute 3839naming the target symbol. Optionally, the @var{target} may be given as 3840an argument to @code{weakref} itself. In either case, @code{weakref} 3841implicitly marks the declaration as @code{weak}. Without a 3842@var{target}, given as an argument to @code{weakref} or to @code{alias}, 3843@code{weakref} is equivalent to @code{weak}. 3844 3845@smallexample 3846static int x() __attribute__ ((weakref ("y"))); 3847/* is equivalent to... */ 3848static int x() __attribute__ ((weak, weakref, alias ("y"))); 3849/* and to... */ 3850static int x() __attribute__ ((weakref)); 3851static int x() __attribute__ ((alias ("y"))); 3852@end smallexample 3853 3854A weak reference is an alias that does not by itself require a 3855definition to be given for the target symbol. If the target symbol is 3856only referenced through weak references, then it becomes a @code{weak} 3857undefined symbol. If it is directly referenced, however, then such 3858strong references prevail, and a definition is required for the 3859symbol, not necessarily in the same translation unit. 3860 3861The effect is equivalent to moving all references to the alias to a 3862separate translation unit, renaming the alias to the aliased symbol, 3863declaring it as weak, compiling the two separate translation units and 3864performing a link with relocatable output (ie: @code{ld -r}) on them. 3865 3866At present, a declaration to which @code{weakref} is attached can 3867only be @code{static}. 3868 3869 3870@end table 3871 3872@c This is the end of the target-independent attribute table 3873 3874@node AArch64 Function Attributes 3875@subsection AArch64 Function Attributes 3876 3877The following target-specific function attributes are available for the 3878AArch64 target. For the most part, these options mirror the behavior of 3879similar command-line options (@pxref{AArch64 Options}), but on a 3880per-function basis. 3881 3882@table @code 3883@item general-regs-only 3884@cindex @code{general-regs-only} function attribute, AArch64 3885Indicates that no floating-point or Advanced SIMD registers should be 3886used when generating code for this function. If the function explicitly 3887uses floating-point code, then the compiler gives an error. This is 3888the same behavior as that of the command-line option 3889@option{-mgeneral-regs-only}. 3890 3891@item fix-cortex-a53-835769 3892@cindex @code{fix-cortex-a53-835769} function attribute, AArch64 3893Indicates that the workaround for the Cortex-A53 erratum 835769 should be 3894applied to this function. To explicitly disable the workaround for this 3895function specify the negated form: @code{no-fix-cortex-a53-835769}. 3896This corresponds to the behavior of the command line options 3897@option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}. 3898 3899@item cmodel= 3900@cindex @code{cmodel=} function attribute, AArch64 3901Indicates that code should be generated for a particular code model for 3902this function. The behavior and permissible arguments are the same as 3903for the command line option @option{-mcmodel=}. 3904 3905@item strict-align 3906@itemx no-strict-align 3907@cindex @code{strict-align} function attribute, AArch64 3908@code{strict-align} indicates that the compiler should not assume that unaligned 3909memory references are handled by the system. To allow the compiler to assume 3910that aligned memory references are handled by the system, the inverse attribute 3911@code{no-strict-align} can be specified. The behavior is same as for the 3912command-line option @option{-mstrict-align} and @option{-mno-strict-align}. 3913 3914@item omit-leaf-frame-pointer 3915@cindex @code{omit-leaf-frame-pointer} function attribute, AArch64 3916Indicates that the frame pointer should be omitted for a leaf function call. 3917To keep the frame pointer, the inverse attribute 3918@code{no-omit-leaf-frame-pointer} can be specified. These attributes have 3919the same behavior as the command-line options @option{-momit-leaf-frame-pointer} 3920and @option{-mno-omit-leaf-frame-pointer}. 3921 3922@item tls-dialect= 3923@cindex @code{tls-dialect=} function attribute, AArch64 3924Specifies the TLS dialect to use for this function. The behavior and 3925permissible arguments are the same as for the command-line option 3926@option{-mtls-dialect=}. 3927 3928@item arch= 3929@cindex @code{arch=} function attribute, AArch64 3930Specifies the architecture version and architectural extensions to use 3931for this function. The behavior and permissible arguments are the same as 3932for the @option{-march=} command-line option. 3933 3934@item tune= 3935@cindex @code{tune=} function attribute, AArch64 3936Specifies the core for which to tune the performance of this function. 3937The behavior and permissible arguments are the same as for the @option{-mtune=} 3938command-line option. 3939 3940@item cpu= 3941@cindex @code{cpu=} function attribute, AArch64 3942Specifies the core for which to tune the performance of this function and also 3943whose architectural features to use. The behavior and valid arguments are the 3944same as for the @option{-mcpu=} command-line option. 3945 3946@item sign-return-address 3947@cindex @code{sign-return-address} function attribute, AArch64 3948Select the function scope on which return address signing will be applied. The 3949behavior and permissible arguments are the same as for the command-line option 3950@option{-msign-return-address=}. The default value is @code{none}. This 3951attribute is deprecated. The @code{branch-protection} attribute should 3952be used instead. 3953 3954@item branch-protection 3955@cindex @code{branch-protection} function attribute, AArch64 3956Select the function scope on which branch protection will be applied. The 3957behavior and permissible arguments are the same as for the command-line option 3958@option{-mbranch-protection=}. The default value is @code{none}. 3959 3960@end table 3961 3962The above target attributes can be specified as follows: 3963 3964@smallexample 3965__attribute__((target("@var{attr-string}"))) 3966int 3967f (int a) 3968@{ 3969 return a + 5; 3970@} 3971@end smallexample 3972 3973where @code{@var{attr-string}} is one of the attribute strings specified above. 3974 3975Additionally, the architectural extension string may be specified on its 3976own. This can be used to turn on and off particular architectural extensions 3977without having to specify a particular architecture version or core. Example: 3978 3979@smallexample 3980__attribute__((target("+crc+nocrypto"))) 3981int 3982foo (int a) 3983@{ 3984 return a + 5; 3985@} 3986@end smallexample 3987 3988In this example @code{target("+crc+nocrypto")} enables the @code{crc} 3989extension and disables the @code{crypto} extension for the function @code{foo} 3990without modifying an existing @option{-march=} or @option{-mcpu} option. 3991 3992Multiple target function attributes can be specified by separating them with 3993a comma. For example: 3994@smallexample 3995__attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53"))) 3996int 3997foo (int a) 3998@{ 3999 return a + 5; 4000@} 4001@end smallexample 4002 4003is valid and compiles function @code{foo} for ARMv8-A with @code{crc} 4004and @code{crypto} extensions and tunes it for @code{cortex-a53}. 4005 4006@subsubsection Inlining rules 4007Specifying target attributes on individual functions or performing link-time 4008optimization across translation units compiled with different target options 4009can affect function inlining rules: 4010 4011In particular, a caller function can inline a callee function only if the 4012architectural features available to the callee are a subset of the features 4013available to the caller. 4014For example: A function @code{foo} compiled with @option{-march=armv8-a+crc}, 4015or tagged with the equivalent @code{arch=armv8-a+crc} attribute, 4016can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc} 4017because the all the architectural features that function @code{bar} requires 4018are available to function @code{foo}. Conversely, function @code{bar} cannot 4019inline function @code{foo}. 4020 4021Additionally inlining a function compiled with @option{-mstrict-align} into a 4022function compiled without @code{-mstrict-align} is not allowed. 4023However, inlining a function compiled without @option{-mstrict-align} into a 4024function compiled with @option{-mstrict-align} is allowed. 4025 4026Note that CPU tuning options and attributes such as the @option{-mcpu=}, 4027@option{-mtune=} do not inhibit inlining unless the CPU specified by the 4028@option{-mcpu=} option or the @code{cpu=} attribute conflicts with the 4029architectural feature rules specified above. 4030 4031@node AMD GCN Function Attributes 4032@subsection AMD GCN Function Attributes 4033 4034These function attributes are supported by the AMD GCN back end: 4035 4036@table @code 4037@item amdgpu_hsa_kernel 4038@cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN 4039This attribute indicates that the corresponding function should be compiled as 4040a kernel function, that is an entry point that can be invoked from the host 4041via the HSA runtime library. By default functions are only callable only from 4042other GCN functions. 4043 4044This attribute is implicitly applied to any function named @code{main}, using 4045default parameters. 4046 4047Kernel functions may return an integer value, which will be written to a 4048conventional place within the HSA "kernargs" region. 4049 4050The attribute parameters configure what values are passed into the kernel 4051function by the GPU drivers, via the initial register state. Some values are 4052used by the compiler, and therefore forced on. Enabling other options may 4053break assumptions in the compiler and/or run-time libraries. 4054 4055@table @code 4056@item private_segment_buffer 4057Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to 4058locate the stack). 4059 4060@item dispatch_ptr 4061Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the 4062launch dimensions). 4063 4064@item queue_ptr 4065Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address 4066spaces). 4067 4068@item kernarg_segment_ptr 4069Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to 4070locate the kernel arguments, "kernargs"). 4071 4072@item dispatch_id 4073Set @code{enable_sgpr_dispatch_id} flag. 4074 4075@item flat_scratch_init 4076Set @code{enable_sgpr_flat_scratch_init} flag. 4077 4078@item private_segment_size 4079Set @code{enable_sgpr_private_segment_size} flag. 4080 4081@item grid_workgroup_count_X 4082Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to 4083use OpenACC/OpenMP). 4084 4085@item grid_workgroup_count_Y 4086Set @code{enable_sgpr_grid_workgroup_count_y} flag. 4087 4088@item grid_workgroup_count_Z 4089Set @code{enable_sgpr_grid_workgroup_count_z} flag. 4090 4091@item workgroup_id_X 4092Set @code{enable_sgpr_workgroup_id_x} flag. 4093 4094@item workgroup_id_Y 4095Set @code{enable_sgpr_workgroup_id_y} flag. 4096 4097@item workgroup_id_Z 4098Set @code{enable_sgpr_workgroup_id_z} flag. 4099 4100@item workgroup_info 4101Set @code{enable_sgpr_workgroup_info} flag. 4102 4103@item private_segment_wave_offset 4104Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on 4105(required to locate the stack). 4106 4107@item work_item_id_X 4108Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled). 4109 4110@item work_item_id_Y 4111Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable 4112vectorization.) 4113 4114@item work_item_id_Z 4115Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use 4116OpenACC/OpenMP). 4117 4118@end table 4119@end table 4120 4121@node ARC Function Attributes 4122@subsection ARC Function Attributes 4123 4124These function attributes are supported by the ARC back end: 4125 4126@table @code 4127@item interrupt 4128@cindex @code{interrupt} function attribute, ARC 4129Use this attribute to indicate 4130that the specified function is an interrupt handler. The compiler generates 4131function entry and exit sequences suitable for use in an interrupt handler 4132when this attribute is present. 4133 4134On the ARC, you must specify the kind of interrupt to be handled 4135in a parameter to the interrupt attribute like this: 4136 4137@smallexample 4138void f () __attribute__ ((interrupt ("ilink1"))); 4139@end smallexample 4140 4141Permissible values for this parameter are: @w{@code{ilink1}} and 4142@w{@code{ilink2}}. 4143 4144@item long_call 4145@itemx medium_call 4146@itemx short_call 4147@cindex @code{long_call} function attribute, ARC 4148@cindex @code{medium_call} function attribute, ARC 4149@cindex @code{short_call} function attribute, ARC 4150@cindex indirect calls, ARC 4151These attributes specify how a particular function is called. 4152These attributes override the 4153@option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options}) 4154command-line switches and @code{#pragma long_calls} settings. 4155 4156For ARC, a function marked with the @code{long_call} attribute is 4157always called using register-indirect jump-and-link instructions, 4158thereby enabling the called function to be placed anywhere within the 415932-bit address space. A function marked with the @code{medium_call} 4160attribute will always be close enough to be called with an unconditional 4161branch-and-link instruction, which has a 25-bit offset from 4162the call site. A function marked with the @code{short_call} 4163attribute will always be close enough to be called with a conditional 4164branch-and-link instruction, which has a 21-bit offset from 4165the call site. 4166 4167@item jli_always 4168@cindex @code{jli_always} function attribute, ARC 4169Forces a particular function to be called using @code{jli} 4170instruction. The @code{jli} instruction makes use of a table stored 4171into @code{.jlitab} section, which holds the location of the functions 4172which are addressed using this instruction. 4173 4174@item jli_fixed 4175@cindex @code{jli_fixed} function attribute, ARC 4176Identical like the above one, but the location of the function in the 4177@code{jli} table is known and given as an attribute parameter. 4178 4179@item secure_call 4180@cindex @code{secure_call} function attribute, ARC 4181This attribute allows one to mark secure-code functions that are 4182callable from normal mode. The location of the secure call function 4183into the @code{sjli} table needs to be passed as argument. 4184 4185@end table 4186 4187@node ARM Function Attributes 4188@subsection ARM Function Attributes 4189 4190These function attributes are supported for ARM targets: 4191 4192@table @code 4193 4194@item general-regs-only 4195@cindex @code{general-regs-only} function attribute, ARM 4196Indicates that no floating-point or Advanced SIMD registers should be 4197used when generating code for this function. If the function explicitly 4198uses floating-point code, then the compiler gives an error. This is 4199the same behavior as that of the command-line option 4200@option{-mgeneral-regs-only}. 4201 4202@item interrupt 4203@cindex @code{interrupt} function attribute, ARM 4204Use this attribute to indicate 4205that the specified function is an interrupt handler. The compiler generates 4206function entry and exit sequences suitable for use in an interrupt handler 4207when this attribute is present. 4208 4209You can specify the kind of interrupt to be handled by 4210adding an optional parameter to the interrupt attribute like this: 4211 4212@smallexample 4213void f () __attribute__ ((interrupt ("IRQ"))); 4214@end smallexample 4215 4216@noindent 4217Permissible values for this parameter are: @code{IRQ}, @code{FIQ}, 4218@code{SWI}, @code{ABORT} and @code{UNDEF}. 4219 4220On ARMv7-M the interrupt type is ignored, and the attribute means the function 4221may be called with a word-aligned stack pointer. 4222 4223@item isr 4224@cindex @code{isr} function attribute, ARM 4225Use this attribute on ARM to write Interrupt Service Routines. This is an 4226alias to the @code{interrupt} attribute above. 4227 4228@item long_call 4229@itemx short_call 4230@cindex @code{long_call} function attribute, ARM 4231@cindex @code{short_call} function attribute, ARM 4232@cindex indirect calls, ARM 4233These attributes specify how a particular function is called. 4234These attributes override the 4235@option{-mlong-calls} (@pxref{ARM Options}) 4236command-line switch and @code{#pragma long_calls} settings. For ARM, the 4237@code{long_call} attribute indicates that the function might be far 4238away from the call site and require a different (more expensive) 4239calling sequence. The @code{short_call} attribute always places 4240the offset to the function from the call site into the @samp{BL} 4241instruction directly. 4242 4243@item naked 4244@cindex @code{naked} function attribute, ARM 4245This attribute allows the compiler to construct the 4246requisite function declaration, while allowing the body of the 4247function to be assembly code. The specified function will not have 4248prologue/epilogue sequences generated by the compiler. Only basic 4249@code{asm} statements can safely be included in naked functions 4250(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 4251basic @code{asm} and C code may appear to work, they cannot be 4252depended upon to work reliably and are not supported. 4253 4254@item pcs 4255@cindex @code{pcs} function attribute, ARM 4256 4257The @code{pcs} attribute can be used to control the calling convention 4258used for a function on ARM. The attribute takes an argument that specifies 4259the calling convention to use. 4260 4261When compiling using the AAPCS ABI (or a variant of it) then valid 4262values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In 4263order to use a variant other than @code{"aapcs"} then the compiler must 4264be permitted to use the appropriate co-processor registers (i.e., the 4265VFP registers must be available in order to use @code{"aapcs-vfp"}). 4266For example, 4267 4268@smallexample 4269/* Argument passed in r0, and result returned in r0+r1. */ 4270double f2d (float) __attribute__((pcs("aapcs"))); 4271@end smallexample 4272 4273Variadic functions always use the @code{"aapcs"} calling convention and 4274the compiler rejects attempts to specify an alternative. 4275 4276@item target (@var{options}) 4277@cindex @code{target} function attribute 4278As discussed in @ref{Common Function Attributes}, this attribute 4279allows specification of target-specific compilation options. 4280 4281On ARM, the following options are allowed: 4282 4283@table @samp 4284@item thumb 4285@cindex @code{target("thumb")} function attribute, ARM 4286Force code generation in the Thumb (T16/T32) ISA, depending on the 4287architecture level. 4288 4289@item arm 4290@cindex @code{target("arm")} function attribute, ARM 4291Force code generation in the ARM (A32) ISA. 4292 4293Functions from different modes can be inlined in the caller's mode. 4294 4295@item fpu= 4296@cindex @code{target("fpu=")} function attribute, ARM 4297Specifies the fpu for which to tune the performance of this function. 4298The behavior and permissible arguments are the same as for the @option{-mfpu=} 4299command-line option. 4300 4301@item arch= 4302@cindex @code{arch=} function attribute, ARM 4303Specifies the architecture version and architectural extensions to use 4304for this function. The behavior and permissible arguments are the same as 4305for the @option{-march=} command-line option. 4306 4307The above target attributes can be specified as follows: 4308 4309@smallexample 4310__attribute__((target("arch=armv8-a+crc"))) 4311int 4312f (int a) 4313@{ 4314 return a + 5; 4315@} 4316@end smallexample 4317 4318Additionally, the architectural extension string may be specified on its 4319own. This can be used to turn on and off particular architectural extensions 4320without having to specify a particular architecture version or core. Example: 4321 4322@smallexample 4323__attribute__((target("+crc+nocrypto"))) 4324int 4325foo (int a) 4326@{ 4327 return a + 5; 4328@} 4329@end smallexample 4330 4331In this example @code{target("+crc+nocrypto")} enables the @code{crc} 4332extension and disables the @code{crypto} extension for the function @code{foo} 4333without modifying an existing @option{-march=} or @option{-mcpu} option. 4334 4335@end table 4336 4337@end table 4338 4339@node AVR Function Attributes 4340@subsection AVR Function Attributes 4341 4342These function attributes are supported by the AVR back end: 4343 4344@table @code 4345@item interrupt 4346@cindex @code{interrupt} function attribute, AVR 4347Use this attribute to indicate 4348that the specified function is an interrupt handler. The compiler generates 4349function entry and exit sequences suitable for use in an interrupt handler 4350when this attribute is present. 4351 4352On the AVR, the hardware globally disables interrupts when an 4353interrupt is executed. The first instruction of an interrupt handler 4354declared with this attribute is a @code{SEI} instruction to 4355re-enable interrupts. See also the @code{signal} function attribute 4356that does not insert a @code{SEI} instruction. If both @code{signal} and 4357@code{interrupt} are specified for the same function, @code{signal} 4358is silently ignored. 4359 4360@item naked 4361@cindex @code{naked} function attribute, AVR 4362This attribute allows the compiler to construct the 4363requisite function declaration, while allowing the body of the 4364function to be assembly code. The specified function will not have 4365prologue/epilogue sequences generated by the compiler. Only basic 4366@code{asm} statements can safely be included in naked functions 4367(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 4368basic @code{asm} and C code may appear to work, they cannot be 4369depended upon to work reliably and are not supported. 4370 4371@item no_gccisr 4372@cindex @code{no_gccisr} function attribute, AVR 4373Do not use @code{__gcc_isr} pseudo instructions in a function with 4374the @code{interrupt} or @code{signal} attribute aka. interrupt 4375service routine (ISR). 4376Use this attribute if the preamble of the ISR prologue should always read 4377@example 4378push __zero_reg__ 4379push __tmp_reg__ 4380in __tmp_reg__, __SREG__ 4381push __tmp_reg__ 4382clr __zero_reg__ 4383@end example 4384and accordingly for the postamble of the epilogue --- no matter whether 4385the mentioned registers are actually used in the ISR or not. 4386Situations where you might want to use this attribute include: 4387@itemize @bullet 4388@item 4389Code that (effectively) clobbers bits of @code{SREG} other than the 4390@code{I}-flag by writing to the memory location of @code{SREG}. 4391@item 4392Code that uses inline assembler to jump to a different function which 4393expects (parts of) the prologue code as outlined above to be present. 4394@end itemize 4395To disable @code{__gcc_isr} generation for the whole compilation unit, 4396there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}. 4397 4398@item OS_main 4399@itemx OS_task 4400@cindex @code{OS_main} function attribute, AVR 4401@cindex @code{OS_task} function attribute, AVR 4402On AVR, functions with the @code{OS_main} or @code{OS_task} attribute 4403do not save/restore any call-saved register in their prologue/epilogue. 4404 4405The @code{OS_main} attribute can be used when there @emph{is 4406guarantee} that interrupts are disabled at the time when the function 4407is entered. This saves resources when the stack pointer has to be 4408changed to set up a frame for local variables. 4409 4410The @code{OS_task} attribute can be used when there is @emph{no 4411guarantee} that interrupts are disabled at that time when the function 4412is entered like for, e@.g@. task functions in a multi-threading operating 4413system. In that case, changing the stack pointer register is 4414guarded by save/clear/restore of the global interrupt enable flag. 4415 4416The differences to the @code{naked} function attribute are: 4417@itemize @bullet 4418@item @code{naked} functions do not have a return instruction whereas 4419@code{OS_main} and @code{OS_task} functions have a @code{RET} or 4420@code{RETI} return instruction. 4421@item @code{naked} functions do not set up a frame for local variables 4422or a frame pointer whereas @code{OS_main} and @code{OS_task} do this 4423as needed. 4424@end itemize 4425 4426@item signal 4427@cindex @code{signal} function attribute, AVR 4428Use this attribute on the AVR to indicate that the specified 4429function is an interrupt handler. The compiler generates function 4430entry and exit sequences suitable for use in an interrupt handler when this 4431attribute is present. 4432 4433See also the @code{interrupt} function attribute. 4434 4435The AVR hardware globally disables interrupts when an interrupt is executed. 4436Interrupt handler functions defined with the @code{signal} attribute 4437do not re-enable interrupts. It is save to enable interrupts in a 4438@code{signal} handler. This ``save'' only applies to the code 4439generated by the compiler and not to the IRQ layout of the 4440application which is responsibility of the application. 4441 4442If both @code{signal} and @code{interrupt} are specified for the same 4443function, @code{signal} is silently ignored. 4444@end table 4445 4446@node Blackfin Function Attributes 4447@subsection Blackfin Function Attributes 4448 4449These function attributes are supported by the Blackfin back end: 4450 4451@table @code 4452 4453@item exception_handler 4454@cindex @code{exception_handler} function attribute 4455@cindex exception handler functions, Blackfin 4456Use this attribute on the Blackfin to indicate that the specified function 4457is an exception handler. The compiler generates function entry and 4458exit sequences suitable for use in an exception handler when this 4459attribute is present. 4460 4461@item interrupt_handler 4462@cindex @code{interrupt_handler} function attribute, Blackfin 4463Use this attribute to 4464indicate that the specified function is an interrupt handler. The compiler 4465generates function entry and exit sequences suitable for use in an 4466interrupt handler when this attribute is present. 4467 4468@item kspisusp 4469@cindex @code{kspisusp} function attribute, Blackfin 4470@cindex User stack pointer in interrupts on the Blackfin 4471When used together with @code{interrupt_handler}, @code{exception_handler} 4472or @code{nmi_handler}, code is generated to load the stack pointer 4473from the USP register in the function prologue. 4474 4475@item l1_text 4476@cindex @code{l1_text} function attribute, Blackfin 4477This attribute specifies a function to be placed into L1 Instruction 4478SRAM@. The function is put into a specific section named @code{.l1.text}. 4479With @option{-mfdpic}, function calls with a such function as the callee 4480or caller uses inlined PLT. 4481 4482@item l2 4483@cindex @code{l2} function attribute, Blackfin 4484This attribute specifies a function to be placed into L2 4485SRAM. The function is put into a specific section named 4486@code{.l2.text}. With @option{-mfdpic}, callers of such functions use 4487an inlined PLT. 4488 4489@item longcall 4490@itemx shortcall 4491@cindex indirect calls, Blackfin 4492@cindex @code{longcall} function attribute, Blackfin 4493@cindex @code{shortcall} function attribute, Blackfin 4494The @code{longcall} attribute 4495indicates that the function might be far away from the call site and 4496require a different (more expensive) calling sequence. The 4497@code{shortcall} attribute indicates that the function is always close 4498enough for the shorter calling sequence to be used. These attributes 4499override the @option{-mlongcall} switch. 4500 4501@item nesting 4502@cindex @code{nesting} function attribute, Blackfin 4503@cindex Allow nesting in an interrupt handler on the Blackfin processor 4504Use this attribute together with @code{interrupt_handler}, 4505@code{exception_handler} or @code{nmi_handler} to indicate that the function 4506entry code should enable nested interrupts or exceptions. 4507 4508@item nmi_handler 4509@cindex @code{nmi_handler} function attribute, Blackfin 4510@cindex NMI handler functions on the Blackfin processor 4511Use this attribute on the Blackfin to indicate that the specified function 4512is an NMI handler. The compiler generates function entry and 4513exit sequences suitable for use in an NMI handler when this 4514attribute is present. 4515 4516@item saveall 4517@cindex @code{saveall} function attribute, Blackfin 4518@cindex save all registers on the Blackfin 4519Use this attribute to indicate that 4520all registers except the stack pointer should be saved in the prologue 4521regardless of whether they are used or not. 4522@end table 4523 4524@node CR16 Function Attributes 4525@subsection CR16 Function Attributes 4526 4527These function attributes are supported by the CR16 back end: 4528 4529@table @code 4530@item interrupt 4531@cindex @code{interrupt} function attribute, CR16 4532Use this attribute to indicate 4533that the specified function is an interrupt handler. The compiler generates 4534function entry and exit sequences suitable for use in an interrupt handler 4535when this attribute is present. 4536@end table 4537 4538@node C-SKY Function Attributes 4539@subsection C-SKY Function Attributes 4540 4541These function attributes are supported by the C-SKY back end: 4542 4543@table @code 4544@item interrupt 4545@itemx isr 4546@cindex @code{interrupt} function attribute, C-SKY 4547@cindex @code{isr} function attribute, C-SKY 4548Use these attributes to indicate that the specified function 4549is an interrupt handler. 4550The compiler generates function entry and exit sequences suitable for 4551use in an interrupt handler when either of these attributes are present. 4552 4553Use of these options requires the @option{-mistack} command-line option 4554to enable support for the necessary interrupt stack instructions. They 4555are ignored with a warning otherwise. @xref{C-SKY Options}. 4556 4557@item naked 4558@cindex @code{naked} function attribute, C-SKY 4559This attribute allows the compiler to construct the 4560requisite function declaration, while allowing the body of the 4561function to be assembly code. The specified function will not have 4562prologue/epilogue sequences generated by the compiler. Only basic 4563@code{asm} statements can safely be included in naked functions 4564(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 4565basic @code{asm} and C code may appear to work, they cannot be 4566depended upon to work reliably and are not supported. 4567@end table 4568 4569 4570@node Epiphany Function Attributes 4571@subsection Epiphany Function Attributes 4572 4573These function attributes are supported by the Epiphany back end: 4574 4575@table @code 4576@item disinterrupt 4577@cindex @code{disinterrupt} function attribute, Epiphany 4578This attribute causes the compiler to emit 4579instructions to disable interrupts for the duration of the given 4580function. 4581 4582@item forwarder_section 4583@cindex @code{forwarder_section} function attribute, Epiphany 4584This attribute modifies the behavior of an interrupt handler. 4585The interrupt handler may be in external memory which cannot be 4586reached by a branch instruction, so generate a local memory trampoline 4587to transfer control. The single parameter identifies the section where 4588the trampoline is placed. 4589 4590@item interrupt 4591@cindex @code{interrupt} function attribute, Epiphany 4592Use this attribute to indicate 4593that the specified function is an interrupt handler. The compiler generates 4594function entry and exit sequences suitable for use in an interrupt handler 4595when this attribute is present. It may also generate 4596a special section with code to initialize the interrupt vector table. 4597 4598On Epiphany targets one or more optional parameters can be added like this: 4599 4600@smallexample 4601void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); 4602@end smallexample 4603 4604Permissible values for these parameters are: @w{@code{reset}}, 4605@w{@code{software_exception}}, @w{@code{page_miss}}, 4606@w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}}, 4607@w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}. 4608Multiple parameters indicate that multiple entries in the interrupt 4609vector table should be initialized for this function, i.e.@: for each 4610parameter @w{@var{name}}, a jump to the function is emitted in 4611the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted 4612entirely, in which case no interrupt vector table entry is provided. 4613 4614Note that interrupts are enabled inside the function 4615unless the @code{disinterrupt} attribute is also specified. 4616 4617The following examples are all valid uses of these attributes on 4618Epiphany targets: 4619@smallexample 4620void __attribute__ ((interrupt)) universal_handler (); 4621void __attribute__ ((interrupt ("dma1"))) dma1_handler (); 4622void __attribute__ ((interrupt ("dma0, dma1"))) 4623 universal_dma_handler (); 4624void __attribute__ ((interrupt ("timer0"), disinterrupt)) 4625 fast_timer_handler (); 4626void __attribute__ ((interrupt ("dma0, dma1"), 4627 forwarder_section ("tramp"))) 4628 external_dma_handler (); 4629@end smallexample 4630 4631@item long_call 4632@itemx short_call 4633@cindex @code{long_call} function attribute, Epiphany 4634@cindex @code{short_call} function attribute, Epiphany 4635@cindex indirect calls, Epiphany 4636These attributes specify how a particular function is called. 4637These attributes override the 4638@option{-mlong-calls} (@pxref{Adapteva Epiphany Options}) 4639command-line switch and @code{#pragma long_calls} settings. 4640@end table 4641 4642 4643@node H8/300 Function Attributes 4644@subsection H8/300 Function Attributes 4645 4646These function attributes are available for H8/300 targets: 4647 4648@table @code 4649@item function_vector 4650@cindex @code{function_vector} function attribute, H8/300 4651Use this attribute on the H8/300, H8/300H, and H8S to indicate 4652that the specified function should be called through the function vector. 4653Calling a function through the function vector reduces code size; however, 4654the function vector has a limited size (maximum 128 entries on the H8/300 4655and 64 entries on the H8/300H and H8S) 4656and shares space with the interrupt vector. 4657 4658@item interrupt_handler 4659@cindex @code{interrupt_handler} function attribute, H8/300 4660Use this attribute on the H8/300, H8/300H, and H8S to 4661indicate that the specified function is an interrupt handler. The compiler 4662generates function entry and exit sequences suitable for use in an 4663interrupt handler when this attribute is present. 4664 4665@item saveall 4666@cindex @code{saveall} function attribute, H8/300 4667@cindex save all registers on the H8/300, H8/300H, and H8S 4668Use this attribute on the H8/300, H8/300H, and H8S to indicate that 4669all registers except the stack pointer should be saved in the prologue 4670regardless of whether they are used or not. 4671@end table 4672 4673@node IA-64 Function Attributes 4674@subsection IA-64 Function Attributes 4675 4676These function attributes are supported on IA-64 targets: 4677 4678@table @code 4679@item syscall_linkage 4680@cindex @code{syscall_linkage} function attribute, IA-64 4681This attribute is used to modify the IA-64 calling convention by marking 4682all input registers as live at all function exits. This makes it possible 4683to restart a system call after an interrupt without having to save/restore 4684the input registers. This also prevents kernel data from leaking into 4685application code. 4686 4687@item version_id 4688@cindex @code{version_id} function attribute, IA-64 4689This IA-64 HP-UX attribute, attached to a global variable or function, renames a 4690symbol to contain a version string, thus allowing for function level 4691versioning. HP-UX system header files may use function level versioning 4692for some system calls. 4693 4694@smallexample 4695extern int foo () __attribute__((version_id ("20040821"))); 4696@end smallexample 4697 4698@noindent 4699Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}. 4700@end table 4701 4702@node M32C Function Attributes 4703@subsection M32C Function Attributes 4704 4705These function attributes are supported by the M32C back end: 4706 4707@table @code 4708@item bank_switch 4709@cindex @code{bank_switch} function attribute, M32C 4710When added to an interrupt handler with the M32C port, causes the 4711prologue and epilogue to use bank switching to preserve the registers 4712rather than saving them on the stack. 4713 4714@item fast_interrupt 4715@cindex @code{fast_interrupt} function attribute, M32C 4716Use this attribute on the M32C port to indicate that the specified 4717function is a fast interrupt handler. This is just like the 4718@code{interrupt} attribute, except that @code{freit} is used to return 4719instead of @code{reit}. 4720 4721@item function_vector 4722@cindex @code{function_vector} function attribute, M16C/M32C 4723On M16C/M32C targets, the @code{function_vector} attribute declares a 4724special page subroutine call function. Use of this attribute reduces 4725the code size by 2 bytes for each call generated to the 4726subroutine. The argument to the attribute is the vector number entry 4727from the special page vector table which contains the 16 low-order 4728bits of the subroutine's entry address. Each vector table has special 4729page number (18 to 255) that is used in @code{jsrs} instructions. 4730Jump addresses of the routines are generated by adding 0x0F0000 (in 4731case of M16C targets) or 0xFF0000 (in case of M32C targets), to the 47322-byte addresses set in the vector table. Therefore you need to ensure 4733that all the special page vector routines should get mapped within the 4734address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF 4735(for M32C). 4736 4737In the following example 2 bytes are saved for each call to 4738function @code{foo}. 4739 4740@smallexample 4741void foo (void) __attribute__((function_vector(0x18))); 4742void foo (void) 4743@{ 4744@} 4745 4746void bar (void) 4747@{ 4748 foo(); 4749@} 4750@end smallexample 4751 4752If functions are defined in one file and are called in another file, 4753then be sure to write this declaration in both files. 4754 4755This attribute is ignored for R8C target. 4756 4757@item interrupt 4758@cindex @code{interrupt} function attribute, M32C 4759Use this attribute to indicate 4760that the specified function is an interrupt handler. The compiler generates 4761function entry and exit sequences suitable for use in an interrupt handler 4762when this attribute is present. 4763@end table 4764 4765@node M32R/D Function Attributes 4766@subsection M32R/D Function Attributes 4767 4768These function attributes are supported by the M32R/D back end: 4769 4770@table @code 4771@item interrupt 4772@cindex @code{interrupt} function attribute, M32R/D 4773Use this attribute to indicate 4774that the specified function is an interrupt handler. The compiler generates 4775function entry and exit sequences suitable for use in an interrupt handler 4776when this attribute is present. 4777 4778@item model (@var{model-name}) 4779@cindex @code{model} function attribute, M32R/D 4780@cindex function addressability on the M32R/D 4781 4782On the M32R/D, use this attribute to set the addressability of an 4783object, and of the code generated for a function. The identifier 4784@var{model-name} is one of @code{small}, @code{medium}, or 4785@code{large}, representing each of the code models. 4786 4787Small model objects live in the lower 16MB of memory (so that their 4788addresses can be loaded with the @code{ld24} instruction), and are 4789callable with the @code{bl} instruction. 4790 4791Medium model objects may live anywhere in the 32-bit address space (the 4792compiler generates @code{seth/add3} instructions to load their addresses), 4793and are callable with the @code{bl} instruction. 4794 4795Large model objects may live anywhere in the 32-bit address space (the 4796compiler generates @code{seth/add3} instructions to load their addresses), 4797and may not be reachable with the @code{bl} instruction (the compiler 4798generates the much slower @code{seth/add3/jl} instruction sequence). 4799@end table 4800 4801@node m68k Function Attributes 4802@subsection m68k Function Attributes 4803 4804These function attributes are supported by the m68k back end: 4805 4806@table @code 4807@item interrupt 4808@itemx interrupt_handler 4809@cindex @code{interrupt} function attribute, m68k 4810@cindex @code{interrupt_handler} function attribute, m68k 4811Use this attribute to 4812indicate that the specified function is an interrupt handler. The compiler 4813generates function entry and exit sequences suitable for use in an 4814interrupt handler when this attribute is present. Either name may be used. 4815 4816@item interrupt_thread 4817@cindex @code{interrupt_thread} function attribute, fido 4818Use this attribute on fido, a subarchitecture of the m68k, to indicate 4819that the specified function is an interrupt handler that is designed 4820to run as a thread. The compiler omits generate prologue/epilogue 4821sequences and replaces the return instruction with a @code{sleep} 4822instruction. This attribute is available only on fido. 4823@end table 4824 4825@node MCORE Function Attributes 4826@subsection MCORE Function Attributes 4827 4828These function attributes are supported by the MCORE back end: 4829 4830@table @code 4831@item naked 4832@cindex @code{naked} function attribute, MCORE 4833This attribute allows the compiler to construct the 4834requisite function declaration, while allowing the body of the 4835function to be assembly code. The specified function will not have 4836prologue/epilogue sequences generated by the compiler. Only basic 4837@code{asm} statements can safely be included in naked functions 4838(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 4839basic @code{asm} and C code may appear to work, they cannot be 4840depended upon to work reliably and are not supported. 4841@end table 4842 4843@node MeP Function Attributes 4844@subsection MeP Function Attributes 4845 4846These function attributes are supported by the MeP back end: 4847 4848@table @code 4849@item disinterrupt 4850@cindex @code{disinterrupt} function attribute, MeP 4851On MeP targets, this attribute causes the compiler to emit 4852instructions to disable interrupts for the duration of the given 4853function. 4854 4855@item interrupt 4856@cindex @code{interrupt} function attribute, MeP 4857Use this attribute to indicate 4858that the specified function is an interrupt handler. The compiler generates 4859function entry and exit sequences suitable for use in an interrupt handler 4860when this attribute is present. 4861 4862@item near 4863@cindex @code{near} function attribute, MeP 4864This attribute causes the compiler to assume the called 4865function is close enough to use the normal calling convention, 4866overriding the @option{-mtf} command-line option. 4867 4868@item far 4869@cindex @code{far} function attribute, MeP 4870On MeP targets this causes the compiler to use a calling convention 4871that assumes the called function is too far away for the built-in 4872addressing modes. 4873 4874@item vliw 4875@cindex @code{vliw} function attribute, MeP 4876The @code{vliw} attribute tells the compiler to emit 4877instructions in VLIW mode instead of core mode. Note that this 4878attribute is not allowed unless a VLIW coprocessor has been configured 4879and enabled through command-line options. 4880@end table 4881 4882@node MicroBlaze Function Attributes 4883@subsection MicroBlaze Function Attributes 4884 4885These function attributes are supported on MicroBlaze targets: 4886 4887@table @code 4888@item save_volatiles 4889@cindex @code{save_volatiles} function attribute, MicroBlaze 4890Use this attribute to indicate that the function is 4891an interrupt handler. All volatile registers (in addition to non-volatile 4892registers) are saved in the function prologue. If the function is a leaf 4893function, only volatiles used by the function are saved. A normal function 4894return is generated instead of a return from interrupt. 4895 4896@item break_handler 4897@cindex @code{break_handler} function attribute, MicroBlaze 4898@cindex break handler functions 4899Use this attribute to indicate that 4900the specified function is a break handler. The compiler generates function 4901entry and exit sequences suitable for use in an break handler when this 4902attribute is present. The return from @code{break_handler} is done through 4903the @code{rtbd} instead of @code{rtsd}. 4904 4905@smallexample 4906void f () __attribute__ ((break_handler)); 4907@end smallexample 4908 4909@item interrupt_handler 4910@itemx fast_interrupt 4911@cindex @code{interrupt_handler} function attribute, MicroBlaze 4912@cindex @code{fast_interrupt} function attribute, MicroBlaze 4913These attributes indicate that the specified function is an interrupt 4914handler. Use the @code{fast_interrupt} attribute to indicate handlers 4915used in low-latency interrupt mode, and @code{interrupt_handler} for 4916interrupts that do not use low-latency handlers. In both cases, GCC 4917emits appropriate prologue code and generates a return from the handler 4918using @code{rtid} instead of @code{rtsd}. 4919@end table 4920 4921@node Microsoft Windows Function Attributes 4922@subsection Microsoft Windows Function Attributes 4923 4924The following attributes are available on Microsoft Windows and Symbian OS 4925targets. 4926 4927@table @code 4928@item dllexport 4929@cindex @code{dllexport} function attribute 4930@cindex @code{__declspec(dllexport)} 4931On Microsoft Windows targets and Symbian OS targets the 4932@code{dllexport} attribute causes the compiler to provide a global 4933pointer to a pointer in a DLL, so that it can be referenced with the 4934@code{dllimport} attribute. On Microsoft Windows targets, the pointer 4935name is formed by combining @code{_imp__} and the function or variable 4936name. 4937 4938You can use @code{__declspec(dllexport)} as a synonym for 4939@code{__attribute__ ((dllexport))} for compatibility with other 4940compilers. 4941 4942On systems that support the @code{visibility} attribute, this 4943attribute also implies ``default'' visibility. It is an error to 4944explicitly specify any other visibility. 4945 4946GCC's default behavior is to emit all inline functions with the 4947@code{dllexport} attribute. Since this can cause object file-size bloat, 4948you can use @option{-fno-keep-inline-dllexport}, which tells GCC to 4949ignore the attribute for inlined functions unless the 4950@option{-fkeep-inline-functions} flag is used instead. 4951 4952The attribute is ignored for undefined symbols. 4953 4954When applied to C++ classes, the attribute marks defined non-inlined 4955member functions and static data members as exports. Static consts 4956initialized in-class are not marked unless they are also defined 4957out-of-class. 4958 4959For Microsoft Windows targets there are alternative methods for 4960including the symbol in the DLL's export table such as using a 4961@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using 4962the @option{--export-all} linker flag. 4963 4964@item dllimport 4965@cindex @code{dllimport} function attribute 4966@cindex @code{__declspec(dllimport)} 4967On Microsoft Windows and Symbian OS targets, the @code{dllimport} 4968attribute causes the compiler to reference a function or variable via 4969a global pointer to a pointer that is set up by the DLL exporting the 4970symbol. The attribute implies @code{extern}. On Microsoft Windows 4971targets, the pointer name is formed by combining @code{_imp__} and the 4972function or variable name. 4973 4974You can use @code{__declspec(dllimport)} as a synonym for 4975@code{__attribute__ ((dllimport))} for compatibility with other 4976compilers. 4977 4978On systems that support the @code{visibility} attribute, this 4979attribute also implies ``default'' visibility. It is an error to 4980explicitly specify any other visibility. 4981 4982Currently, the attribute is ignored for inlined functions. If the 4983attribute is applied to a symbol @emph{definition}, an error is reported. 4984If a symbol previously declared @code{dllimport} is later defined, the 4985attribute is ignored in subsequent references, and a warning is emitted. 4986The attribute is also overridden by a subsequent declaration as 4987@code{dllexport}. 4988 4989When applied to C++ classes, the attribute marks non-inlined 4990member functions and static data members as imports. However, the 4991attribute is ignored for virtual methods to allow creation of vtables 4992using thunks. 4993 4994On the SH Symbian OS target the @code{dllimport} attribute also has 4995another affect---it can cause the vtable and run-time type information 4996for a class to be exported. This happens when the class has a 4997dllimported constructor or a non-inline, non-pure virtual function 4998and, for either of those two conditions, the class also has an inline 4999constructor or destructor and has a key function that is defined in 5000the current translation unit. 5001 5002For Microsoft Windows targets the use of the @code{dllimport} 5003attribute on functions is not necessary, but provides a small 5004performance benefit by eliminating a thunk in the DLL@. The use of the 5005@code{dllimport} attribute on imported variables can be avoided by passing the 5006@option{--enable-auto-import} switch to the GNU linker. As with 5007functions, using the attribute for a variable eliminates a thunk in 5008the DLL@. 5009 5010One drawback to using this attribute is that a pointer to a 5011@emph{variable} marked as @code{dllimport} cannot be used as a constant 5012address. However, a pointer to a @emph{function} with the 5013@code{dllimport} attribute can be used as a constant initializer; in 5014this case, the address of a stub function in the import lib is 5015referenced. On Microsoft Windows targets, the attribute can be disabled 5016for functions by setting the @option{-mnop-fun-dllimport} flag. 5017@end table 5018 5019@node MIPS Function Attributes 5020@subsection MIPS Function Attributes 5021 5022These function attributes are supported by the MIPS back end: 5023 5024@table @code 5025@item interrupt 5026@cindex @code{interrupt} function attribute, MIPS 5027Use this attribute to indicate that the specified function is an interrupt 5028handler. The compiler generates function entry and exit sequences suitable 5029for use in an interrupt handler when this attribute is present. 5030An optional argument is supported for the interrupt attribute which allows 5031the interrupt mode to be described. By default GCC assumes the external 5032interrupt controller (EIC) mode is in use, this can be explicitly set using 5033@code{eic}. When interrupts are non-masked then the requested Interrupt 5034Priority Level (IPL) is copied to the current IPL which has the effect of only 5035enabling higher priority interrupts. To use vectored interrupt mode use 5036the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change 5037the behavior of the non-masked interrupt support and GCC will arrange to mask 5038all interrupts from sw0 up to and including the specified interrupt vector. 5039 5040You can use the following attributes to modify the behavior 5041of an interrupt handler: 5042@table @code 5043@item use_shadow_register_set 5044@cindex @code{use_shadow_register_set} function attribute, MIPS 5045Assume that the handler uses a shadow register set, instead of 5046the main general-purpose registers. An optional argument @code{intstack} is 5047supported to indicate that the shadow register set contains a valid stack 5048pointer. 5049 5050@item keep_interrupts_masked 5051@cindex @code{keep_interrupts_masked} function attribute, MIPS 5052Keep interrupts masked for the whole function. Without this attribute, 5053GCC tries to reenable interrupts for as much of the function as it can. 5054 5055@item use_debug_exception_return 5056@cindex @code{use_debug_exception_return} function attribute, MIPS 5057Return using the @code{deret} instruction. Interrupt handlers that don't 5058have this attribute return using @code{eret} instead. 5059@end table 5060 5061You can use any combination of these attributes, as shown below: 5062@smallexample 5063void __attribute__ ((interrupt)) v0 (); 5064void __attribute__ ((interrupt, use_shadow_register_set)) v1 (); 5065void __attribute__ ((interrupt, keep_interrupts_masked)) v2 (); 5066void __attribute__ ((interrupt, use_debug_exception_return)) v3 (); 5067void __attribute__ ((interrupt, use_shadow_register_set, 5068 keep_interrupts_masked)) v4 (); 5069void __attribute__ ((interrupt, use_shadow_register_set, 5070 use_debug_exception_return)) v5 (); 5071void __attribute__ ((interrupt, keep_interrupts_masked, 5072 use_debug_exception_return)) v6 (); 5073void __attribute__ ((interrupt, use_shadow_register_set, 5074 keep_interrupts_masked, 5075 use_debug_exception_return)) v7 (); 5076void __attribute__ ((interrupt("eic"))) v8 (); 5077void __attribute__ ((interrupt("vector=hw3"))) v9 (); 5078@end smallexample 5079 5080@item long_call 5081@itemx short_call 5082@itemx near 5083@itemx far 5084@cindex indirect calls, MIPS 5085@cindex @code{long_call} function attribute, MIPS 5086@cindex @code{short_call} function attribute, MIPS 5087@cindex @code{near} function attribute, MIPS 5088@cindex @code{far} function attribute, MIPS 5089These attributes specify how a particular function is called on MIPS@. 5090The attributes override the @option{-mlong-calls} (@pxref{MIPS Options}) 5091command-line switch. The @code{long_call} and @code{far} attributes are 5092synonyms, and cause the compiler to always call 5093the function by first loading its address into a register, and then using 5094the contents of that register. The @code{short_call} and @code{near} 5095attributes are synonyms, and have the opposite 5096effect; they specify that non-PIC calls should be made using the more 5097efficient @code{jal} instruction. 5098 5099@item mips16 5100@itemx nomips16 5101@cindex @code{mips16} function attribute, MIPS 5102@cindex @code{nomips16} function attribute, MIPS 5103 5104On MIPS targets, you can use the @code{mips16} and @code{nomips16} 5105function attributes to locally select or turn off MIPS16 code generation. 5106A function with the @code{mips16} attribute is emitted as MIPS16 code, 5107while MIPS16 code generation is disabled for functions with the 5108@code{nomips16} attribute. These attributes override the 5109@option{-mips16} and @option{-mno-mips16} options on the command line 5110(@pxref{MIPS Options}). 5111 5112When compiling files containing mixed MIPS16 and non-MIPS16 code, the 5113preprocessor symbol @code{__mips16} reflects the setting on the command line, 5114not that within individual functions. Mixed MIPS16 and non-MIPS16 code 5115may interact badly with some GCC extensions such as @code{__builtin_apply} 5116(@pxref{Constructing Calls}). 5117 5118@item micromips, MIPS 5119@itemx nomicromips, MIPS 5120@cindex @code{micromips} function attribute 5121@cindex @code{nomicromips} function attribute 5122 5123On MIPS targets, you can use the @code{micromips} and @code{nomicromips} 5124function attributes to locally select or turn off microMIPS code generation. 5125A function with the @code{micromips} attribute is emitted as microMIPS code, 5126while microMIPS code generation is disabled for functions with the 5127@code{nomicromips} attribute. These attributes override the 5128@option{-mmicromips} and @option{-mno-micromips} options on the command line 5129(@pxref{MIPS Options}). 5130 5131When compiling files containing mixed microMIPS and non-microMIPS code, the 5132preprocessor symbol @code{__mips_micromips} reflects the setting on the 5133command line, 5134not that within individual functions. Mixed microMIPS and non-microMIPS code 5135may interact badly with some GCC extensions such as @code{__builtin_apply} 5136(@pxref{Constructing Calls}). 5137 5138@item nocompression 5139@cindex @code{nocompression} function attribute, MIPS 5140On MIPS targets, you can use the @code{nocompression} function attribute 5141to locally turn off MIPS16 and microMIPS code generation. This attribute 5142overrides the @option{-mips16} and @option{-mmicromips} options on the 5143command line (@pxref{MIPS Options}). 5144@end table 5145 5146@node MSP430 Function Attributes 5147@subsection MSP430 Function Attributes 5148 5149These function attributes are supported by the MSP430 back end: 5150 5151@table @code 5152@item critical 5153@cindex @code{critical} function attribute, MSP430 5154Critical functions disable interrupts upon entry and restore the 5155previous interrupt state upon exit. Critical functions cannot also 5156have the @code{naked}, @code{reentrant} or @code{interrupt} attributes. 5157 5158The MSP430 hardware ensures that interrupts are disabled on entry to 5159@code{interrupt} functions, and restores the previous interrupt state 5160on exit. The @code{critical} attribute is therefore redundant on 5161@code{interrupt} functions. 5162 5163@item interrupt 5164@cindex @code{interrupt} function attribute, MSP430 5165Use this attribute to indicate 5166that the specified function is an interrupt handler. The compiler generates 5167function entry and exit sequences suitable for use in an interrupt handler 5168when this attribute is present. 5169 5170You can provide an argument to the interrupt 5171attribute which specifies a name or number. If the argument is a 5172number it indicates the slot in the interrupt vector table (0 - 31) to 5173which this handler should be assigned. If the argument is a name it 5174is treated as a symbolic name for the vector slot. These names should 5175match up with appropriate entries in the linker script. By default 5176the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and 5177@code{reset} for vector 31 are recognized. 5178 5179@item naked 5180@cindex @code{naked} function attribute, MSP430 5181This attribute allows the compiler to construct the 5182requisite function declaration, while allowing the body of the 5183function to be assembly code. The specified function will not have 5184prologue/epilogue sequences generated by the compiler. Only basic 5185@code{asm} statements can safely be included in naked functions 5186(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5187basic @code{asm} and C code may appear to work, they cannot be 5188depended upon to work reliably and are not supported. 5189 5190@item reentrant 5191@cindex @code{reentrant} function attribute, MSP430 5192Reentrant functions disable interrupts upon entry and enable them 5193upon exit. Reentrant functions cannot also have the @code{naked} 5194or @code{critical} attributes. They can have the @code{interrupt} 5195attribute. 5196 5197@item wakeup 5198@cindex @code{wakeup} function attribute, MSP430 5199This attribute only applies to interrupt functions. It is silently 5200ignored if applied to a non-interrupt function. A wakeup interrupt 5201function will rouse the processor from any low-power state that it 5202might be in when the function exits. 5203 5204@item lower 5205@itemx upper 5206@itemx either 5207@cindex @code{lower} function attribute, MSP430 5208@cindex @code{upper} function attribute, MSP430 5209@cindex @code{either} function attribute, MSP430 5210On the MSP430 target these attributes can be used to specify whether 5211the function or variable should be placed into low memory, high 5212memory, or the placement should be left to the linker to decide. The 5213attributes are only significant if compiling for the MSP430X 5214architecture. 5215 5216The attributes work in conjunction with a linker script that has been 5217augmented to specify where to place sections with a @code{.lower} and 5218a @code{.upper} prefix. So, for example, as well as placing the 5219@code{.data} section, the script also specifies the placement of a 5220@code{.lower.data} and a @code{.upper.data} section. The intention 5221is that @code{lower} sections are placed into a small but easier to 5222access memory region and the upper sections are placed into a larger, but 5223slower to access, region. 5224 5225The @code{either} attribute is special. It tells the linker to place 5226the object into the corresponding @code{lower} section if there is 5227room for it. If there is insufficient room then the object is placed 5228into the corresponding @code{upper} section instead. Note that the 5229placement algorithm is not very sophisticated. It does not attempt to 5230find an optimal packing of the @code{lower} sections. It just makes 5231one pass over the objects and does the best that it can. Using the 5232@option{-ffunction-sections} and @option{-fdata-sections} command-line 5233options can help the packing, however, since they produce smaller, 5234easier to pack regions. 5235@end table 5236 5237@node NDS32 Function Attributes 5238@subsection NDS32 Function Attributes 5239 5240These function attributes are supported by the NDS32 back end: 5241 5242@table @code 5243@item exception 5244@cindex @code{exception} function attribute 5245@cindex exception handler functions, NDS32 5246Use this attribute on the NDS32 target to indicate that the specified function 5247is an exception handler. The compiler will generate corresponding sections 5248for use in an exception handler. 5249 5250@item interrupt 5251@cindex @code{interrupt} function attribute, NDS32 5252On NDS32 target, this attribute indicates that the specified function 5253is an interrupt handler. The compiler generates corresponding sections 5254for use in an interrupt handler. You can use the following attributes 5255to modify the behavior: 5256@table @code 5257@item nested 5258@cindex @code{nested} function attribute, NDS32 5259This interrupt service routine is interruptible. 5260@item not_nested 5261@cindex @code{not_nested} function attribute, NDS32 5262This interrupt service routine is not interruptible. 5263@item nested_ready 5264@cindex @code{nested_ready} function attribute, NDS32 5265This interrupt service routine is interruptible after @code{PSW.GIE} 5266(global interrupt enable) is set. This allows interrupt service routine to 5267finish some short critical code before enabling interrupts. 5268@item save_all 5269@cindex @code{save_all} function attribute, NDS32 5270The system will help save all registers into stack before entering 5271interrupt handler. 5272@item partial_save 5273@cindex @code{partial_save} function attribute, NDS32 5274The system will help save caller registers into stack before entering 5275interrupt handler. 5276@end table 5277 5278@item naked 5279@cindex @code{naked} function attribute, NDS32 5280This attribute allows the compiler to construct the 5281requisite function declaration, while allowing the body of the 5282function to be assembly code. The specified function will not have 5283prologue/epilogue sequences generated by the compiler. Only basic 5284@code{asm} statements can safely be included in naked functions 5285(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5286basic @code{asm} and C code may appear to work, they cannot be 5287depended upon to work reliably and are not supported. 5288 5289@item reset 5290@cindex @code{reset} function attribute, NDS32 5291@cindex reset handler functions 5292Use this attribute on the NDS32 target to indicate that the specified function 5293is a reset handler. The compiler will generate corresponding sections 5294for use in a reset handler. You can use the following attributes 5295to provide extra exception handling: 5296@table @code 5297@item nmi 5298@cindex @code{nmi} function attribute, NDS32 5299Provide a user-defined function to handle NMI exception. 5300@item warm 5301@cindex @code{warm} function attribute, NDS32 5302Provide a user-defined function to handle warm reset exception. 5303@end table 5304@end table 5305 5306@node Nios II Function Attributes 5307@subsection Nios II Function Attributes 5308 5309These function attributes are supported by the Nios II back end: 5310 5311@table @code 5312@item target (@var{options}) 5313@cindex @code{target} function attribute 5314As discussed in @ref{Common Function Attributes}, this attribute 5315allows specification of target-specific compilation options. 5316 5317When compiling for Nios II, the following options are allowed: 5318 5319@table @samp 5320@item custom-@var{insn}=@var{N} 5321@itemx no-custom-@var{insn} 5322@cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II 5323@cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II 5324Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a 5325custom instruction with encoding @var{N} when generating code that uses 5326@var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of 5327the custom instruction @var{insn}. 5328These target attributes correspond to the 5329@option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}} 5330command-line options, and support the same set of @var{insn} keywords. 5331@xref{Nios II Options}, for more information. 5332 5333@item custom-fpu-cfg=@var{name} 5334@cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II 5335This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}} 5336command-line option, to select a predefined set of custom instructions 5337named @var{name}. 5338@xref{Nios II Options}, for more information. 5339@end table 5340@end table 5341 5342@node Nvidia PTX Function Attributes 5343@subsection Nvidia PTX Function Attributes 5344 5345These function attributes are supported by the Nvidia PTX back end: 5346 5347@table @code 5348@item kernel 5349@cindex @code{kernel} attribute, Nvidia PTX 5350This attribute indicates that the corresponding function should be compiled 5351as a kernel function, which can be invoked from the host via the CUDA RT 5352library. 5353By default functions are only callable only from other PTX functions. 5354 5355Kernel functions must have @code{void} return type. 5356@end table 5357 5358@node PowerPC Function Attributes 5359@subsection PowerPC Function Attributes 5360 5361These function attributes are supported by the PowerPC back end: 5362 5363@table @code 5364@item longcall 5365@itemx shortcall 5366@cindex indirect calls, PowerPC 5367@cindex @code{longcall} function attribute, PowerPC 5368@cindex @code{shortcall} function attribute, PowerPC 5369The @code{longcall} attribute 5370indicates that the function might be far away from the call site and 5371require a different (more expensive) calling sequence. The 5372@code{shortcall} attribute indicates that the function is always close 5373enough for the shorter calling sequence to be used. These attributes 5374override both the @option{-mlongcall} switch and 5375the @code{#pragma longcall} setting. 5376 5377@xref{RS/6000 and PowerPC Options}, for more information on whether long 5378calls are necessary. 5379 5380@item target (@var{options}) 5381@cindex @code{target} function attribute 5382As discussed in @ref{Common Function Attributes}, this attribute 5383allows specification of target-specific compilation options. 5384 5385On the PowerPC, the following options are allowed: 5386 5387@table @samp 5388@item altivec 5389@itemx no-altivec 5390@cindex @code{target("altivec")} function attribute, PowerPC 5391Generate code that uses (does not use) AltiVec instructions. In 539232-bit code, you cannot enable AltiVec instructions unless 5393@option{-mabi=altivec} is used on the command line. 5394 5395@item cmpb 5396@itemx no-cmpb 5397@cindex @code{target("cmpb")} function attribute, PowerPC 5398Generate code that uses (does not use) the compare bytes instruction 5399implemented on the POWER6 processor and other processors that support 5400the PowerPC V2.05 architecture. 5401 5402@item dlmzb 5403@itemx no-dlmzb 5404@cindex @code{target("dlmzb")} function attribute, PowerPC 5405Generate code that uses (does not use) the string-search @samp{dlmzb} 5406instruction on the IBM 405, 440, 464 and 476 processors. This instruction is 5407generated by default when targeting those processors. 5408 5409@item fprnd 5410@itemx no-fprnd 5411@cindex @code{target("fprnd")} function attribute, PowerPC 5412Generate code that uses (does not use) the FP round to integer 5413instructions implemented on the POWER5+ processor and other processors 5414that support the PowerPC V2.03 architecture. 5415 5416@item hard-dfp 5417@itemx no-hard-dfp 5418@cindex @code{target("hard-dfp")} function attribute, PowerPC 5419Generate code that uses (does not use) the decimal floating-point 5420instructions implemented on some POWER processors. 5421 5422@item isel 5423@itemx no-isel 5424@cindex @code{target("isel")} function attribute, PowerPC 5425Generate code that uses (does not use) ISEL instruction. 5426 5427@item mfcrf 5428@itemx no-mfcrf 5429@cindex @code{target("mfcrf")} function attribute, PowerPC 5430Generate code that uses (does not use) the move from condition 5431register field instruction implemented on the POWER4 processor and 5432other processors that support the PowerPC V2.01 architecture. 5433 5434@item mfpgpr 5435@itemx no-mfpgpr 5436@cindex @code{target("mfpgpr")} function attribute, PowerPC 5437Generate code that uses (does not use) the FP move to/from general 5438purpose register instructions implemented on the POWER6X processor and 5439other processors that support the extended PowerPC V2.05 architecture. 5440 5441@item mulhw 5442@itemx no-mulhw 5443@cindex @code{target("mulhw")} function attribute, PowerPC 5444Generate code that uses (does not use) the half-word multiply and 5445multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors. 5446These instructions are generated by default when targeting those 5447processors. 5448 5449@item multiple 5450@itemx no-multiple 5451@cindex @code{target("multiple")} function attribute, PowerPC 5452Generate code that uses (does not use) the load multiple word 5453instructions and the store multiple word instructions. 5454 5455@item update 5456@itemx no-update 5457@cindex @code{target("update")} function attribute, PowerPC 5458Generate code that uses (does not use) the load or store instructions 5459that update the base register to the address of the calculated memory 5460location. 5461 5462@item popcntb 5463@itemx no-popcntb 5464@cindex @code{target("popcntb")} function attribute, PowerPC 5465Generate code that uses (does not use) the popcount and double-precision 5466FP reciprocal estimate instruction implemented on the POWER5 5467processor and other processors that support the PowerPC V2.02 5468architecture. 5469 5470@item popcntd 5471@itemx no-popcntd 5472@cindex @code{target("popcntd")} function attribute, PowerPC 5473Generate code that uses (does not use) the popcount instruction 5474implemented on the POWER7 processor and other processors that support 5475the PowerPC V2.06 architecture. 5476 5477@item powerpc-gfxopt 5478@itemx no-powerpc-gfxopt 5479@cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC 5480Generate code that uses (does not use) the optional PowerPC 5481architecture instructions in the Graphics group, including 5482floating-point select. 5483 5484@item powerpc-gpopt 5485@itemx no-powerpc-gpopt 5486@cindex @code{target("powerpc-gpopt")} function attribute, PowerPC 5487Generate code that uses (does not use) the optional PowerPC 5488architecture instructions in the General Purpose group, including 5489floating-point square root. 5490 5491@item recip-precision 5492@itemx no-recip-precision 5493@cindex @code{target("recip-precision")} function attribute, PowerPC 5494Assume (do not assume) that the reciprocal estimate instructions 5495provide higher-precision estimates than is mandated by the PowerPC 5496ABI. 5497 5498@item string 5499@itemx no-string 5500@cindex @code{target("string")} function attribute, PowerPC 5501Generate code that uses (does not use) the load string instructions 5502and the store string word instructions to save multiple registers and 5503do small block moves. 5504 5505@item vsx 5506@itemx no-vsx 5507@cindex @code{target("vsx")} function attribute, PowerPC 5508Generate code that uses (does not use) vector/scalar (VSX) 5509instructions, and also enable the use of built-in functions that allow 5510more direct access to the VSX instruction set. In 32-bit code, you 5511cannot enable VSX or AltiVec instructions unless 5512@option{-mabi=altivec} is used on the command line. 5513 5514@item friz 5515@itemx no-friz 5516@cindex @code{target("friz")} function attribute, PowerPC 5517Generate (do not generate) the @code{friz} instruction when the 5518@option{-funsafe-math-optimizations} option is used to optimize 5519rounding a floating-point value to 64-bit integer and back to floating 5520point. The @code{friz} instruction does not return the same value if 5521the floating-point number is too large to fit in an integer. 5522 5523@item avoid-indexed-addresses 5524@itemx no-avoid-indexed-addresses 5525@cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC 5526Generate code that tries to avoid (not avoid) the use of indexed load 5527or store instructions. 5528 5529@item paired 5530@itemx no-paired 5531@cindex @code{target("paired")} function attribute, PowerPC 5532Generate code that uses (does not use) the generation of PAIRED simd 5533instructions. 5534 5535@item longcall 5536@itemx no-longcall 5537@cindex @code{target("longcall")} function attribute, PowerPC 5538Generate code that assumes (does not assume) that all calls are far 5539away so that a longer more expensive calling sequence is required. 5540 5541@item cpu=@var{CPU} 5542@cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC 5543Specify the architecture to generate code for when compiling the 5544function. If you select the @code{target("cpu=power7")} attribute when 5545generating 32-bit code, VSX and AltiVec instructions are not generated 5546unless you use the @option{-mabi=altivec} option on the command line. 5547 5548@item tune=@var{TUNE} 5549@cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC 5550Specify the architecture to tune for when compiling the function. If 5551you do not specify the @code{target("tune=@var{TUNE}")} attribute and 5552you do specify the @code{target("cpu=@var{CPU}")} attribute, 5553compilation tunes for the @var{CPU} architecture, and not the 5554default tuning specified on the command line. 5555@end table 5556 5557On the PowerPC, the inliner does not inline a 5558function that has different target options than the caller, unless the 5559callee has a subset of the target options of the caller. 5560@end table 5561 5562@node RISC-V Function Attributes 5563@subsection RISC-V Function Attributes 5564 5565These function attributes are supported by the RISC-V back end: 5566 5567@table @code 5568@item naked 5569@cindex @code{naked} function attribute, RISC-V 5570This attribute allows the compiler to construct the 5571requisite function declaration, while allowing the body of the 5572function to be assembly code. The specified function will not have 5573prologue/epilogue sequences generated by the compiler. Only basic 5574@code{asm} statements can safely be included in naked functions 5575(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5576basic @code{asm} and C code may appear to work, they cannot be 5577depended upon to work reliably and are not supported. 5578 5579@item interrupt 5580@cindex @code{interrupt} function attribute, RISC-V 5581Use this attribute to indicate that the specified function is an interrupt 5582handler. The compiler generates function entry and exit sequences suitable 5583for use in an interrupt handler when this attribute is present. 5584 5585You can specify the kind of interrupt to be handled by adding an optional 5586parameter to the interrupt attribute like this: 5587 5588@smallexample 5589void f (void) __attribute__ ((interrupt ("user"))); 5590@end smallexample 5591 5592Permissible values for this parameter are @code{user}, @code{supervisor}, 5593and @code{machine}. If there is no parameter, then it defaults to 5594@code{machine}. 5595@end table 5596 5597@node RL78 Function Attributes 5598@subsection RL78 Function Attributes 5599 5600These function attributes are supported by the RL78 back end: 5601 5602@table @code 5603@item interrupt 5604@itemx brk_interrupt 5605@cindex @code{interrupt} function attribute, RL78 5606@cindex @code{brk_interrupt} function attribute, RL78 5607These attributes indicate 5608that the specified function is an interrupt handler. The compiler generates 5609function entry and exit sequences suitable for use in an interrupt handler 5610when this attribute is present. 5611 5612Use @code{brk_interrupt} instead of @code{interrupt} for 5613handlers intended to be used with the @code{BRK} opcode (i.e.@: those 5614that must end with @code{RETB} instead of @code{RETI}). 5615 5616@item naked 5617@cindex @code{naked} function attribute, RL78 5618This attribute allows the compiler to construct the 5619requisite function declaration, while allowing the body of the 5620function to be assembly code. The specified function will not have 5621prologue/epilogue sequences generated by the compiler. Only basic 5622@code{asm} statements can safely be included in naked functions 5623(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5624basic @code{asm} and C code may appear to work, they cannot be 5625depended upon to work reliably and are not supported. 5626@end table 5627 5628@node RX Function Attributes 5629@subsection RX Function Attributes 5630 5631These function attributes are supported by the RX back end: 5632 5633@table @code 5634@item fast_interrupt 5635@cindex @code{fast_interrupt} function attribute, RX 5636Use this attribute on the RX port to indicate that the specified 5637function is a fast interrupt handler. This is just like the 5638@code{interrupt} attribute, except that @code{freit} is used to return 5639instead of @code{reit}. 5640 5641@item interrupt 5642@cindex @code{interrupt} function attribute, RX 5643Use this attribute to indicate 5644that the specified function is an interrupt handler. The compiler generates 5645function entry and exit sequences suitable for use in an interrupt handler 5646when this attribute is present. 5647 5648On RX and RL78 targets, you may specify one or more vector numbers as arguments 5649to the attribute, as well as naming an alternate table name. 5650Parameters are handled sequentially, so one handler can be assigned to 5651multiple entries in multiple tables. One may also pass the magic 5652string @code{"$default"} which causes the function to be used for any 5653unfilled slots in the current table. 5654 5655This example shows a simple assignment of a function to one vector in 5656the default table (note that preprocessor macros may be used for 5657chip-specific symbolic vector names): 5658@smallexample 5659void __attribute__ ((interrupt (5))) txd1_handler (); 5660@end smallexample 5661 5662This example assigns a function to two slots in the default table 5663(using preprocessor macros defined elsewhere) and makes it the default 5664for the @code{dct} table: 5665@smallexample 5666void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default"))) 5667 txd1_handler (); 5668@end smallexample 5669 5670@item naked 5671@cindex @code{naked} function attribute, RX 5672This attribute allows the compiler to construct the 5673requisite function declaration, while allowing the body of the 5674function to be assembly code. The specified function will not have 5675prologue/epilogue sequences generated by the compiler. Only basic 5676@code{asm} statements can safely be included in naked functions 5677(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5678basic @code{asm} and C code may appear to work, they cannot be 5679depended upon to work reliably and are not supported. 5680 5681@item vector 5682@cindex @code{vector} function attribute, RX 5683This RX attribute is similar to the @code{interrupt} attribute, including its 5684parameters, but does not make the function an interrupt-handler type 5685function (i.e.@: it retains the normal C function calling ABI). See the 5686@code{interrupt} attribute for a description of its arguments. 5687@end table 5688 5689@node S/390 Function Attributes 5690@subsection S/390 Function Attributes 5691 5692These function attributes are supported on the S/390: 5693 5694@table @code 5695@item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label}) 5696@cindex @code{hotpatch} function attribute, S/390 5697 5698On S/390 System z targets, you can use this function attribute to 5699make GCC generate a ``hot-patching'' function prologue. If the 5700@option{-mhotpatch=} command-line option is used at the same time, 5701the @code{hotpatch} attribute takes precedence. The first of the 5702two arguments specifies the number of halfwords to be added before 5703the function label. A second argument can be used to specify the 5704number of halfwords to be added after the function label. For 5705both arguments the maximum allowed value is 1000000. 5706 5707If both arguments are zero, hotpatching is disabled. 5708 5709@item target (@var{options}) 5710@cindex @code{target} function attribute 5711As discussed in @ref{Common Function Attributes}, this attribute 5712allows specification of target-specific compilation options. 5713 5714On S/390, the following options are supported: 5715 5716@table @samp 5717@item arch= 5718@item tune= 5719@item stack-guard= 5720@item stack-size= 5721@item branch-cost= 5722@item warn-framesize= 5723@item backchain 5724@itemx no-backchain 5725@item hard-dfp 5726@itemx no-hard-dfp 5727@item hard-float 5728@itemx soft-float 5729@item htm 5730@itemx no-htm 5731@item vx 5732@itemx no-vx 5733@item packed-stack 5734@itemx no-packed-stack 5735@item small-exec 5736@itemx no-small-exec 5737@item mvcle 5738@itemx no-mvcle 5739@item warn-dynamicstack 5740@itemx no-warn-dynamicstack 5741@end table 5742 5743The options work exactly like the S/390 specific command line 5744options (without the prefix @option{-m}) except that they do not 5745change any feature macros. For example, 5746 5747@smallexample 5748@code{target("no-vx")} 5749@end smallexample 5750 5751does not undefine the @code{__VEC__} macro. 5752@end table 5753 5754@node SH Function Attributes 5755@subsection SH Function Attributes 5756 5757These function attributes are supported on the SH family of processors: 5758 5759@table @code 5760@item function_vector 5761@cindex @code{function_vector} function attribute, SH 5762@cindex calling functions through the function vector on SH2A 5763On SH2A targets, this attribute declares a function to be called using the 5764TBR relative addressing mode. The argument to this attribute is the entry 5765number of the same function in a vector table containing all the TBR 5766relative addressable functions. For correct operation the TBR must be setup 5767accordingly to point to the start of the vector table before any functions with 5768this attribute are invoked. Usually a good place to do the initialization is 5769the startup routine. The TBR relative vector table can have at max 256 function 5770entries. The jumps to these functions are generated using a SH2A specific, 5771non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD 5772from GNU binutils version 2.7 or later for this attribute to work correctly. 5773 5774In an application, for a function being called once, this attribute 5775saves at least 8 bytes of code; and if other successive calls are being 5776made to the same function, it saves 2 bytes of code per each of these 5777calls. 5778 5779@item interrupt_handler 5780@cindex @code{interrupt_handler} function attribute, SH 5781Use this attribute to 5782indicate that the specified function is an interrupt handler. The compiler 5783generates function entry and exit sequences suitable for use in an 5784interrupt handler when this attribute is present. 5785 5786@item nosave_low_regs 5787@cindex @code{nosave_low_regs} function attribute, SH 5788Use this attribute on SH targets to indicate that an @code{interrupt_handler} 5789function should not save and restore registers R0..R7. This can be used on SH3* 5790and SH4* targets that have a second R0..R7 register bank for non-reentrant 5791interrupt handlers. 5792 5793@item renesas 5794@cindex @code{renesas} function attribute, SH 5795On SH targets this attribute specifies that the function or struct follows the 5796Renesas ABI. 5797 5798@item resbank 5799@cindex @code{resbank} function attribute, SH 5800On the SH2A target, this attribute enables the high-speed register 5801saving and restoration using a register bank for @code{interrupt_handler} 5802routines. Saving to the bank is performed automatically after the CPU 5803accepts an interrupt that uses a register bank. 5804 5805The nineteen 32-bit registers comprising general register R0 to R14, 5806control register GBR, and system registers MACH, MACL, and PR and the 5807vector table address offset are saved into a register bank. Register 5808banks are stacked in first-in last-out (FILO) sequence. Restoration 5809from the bank is executed by issuing a RESBANK instruction. 5810 5811@item sp_switch 5812@cindex @code{sp_switch} function attribute, SH 5813Use this attribute on the SH to indicate an @code{interrupt_handler} 5814function should switch to an alternate stack. It expects a string 5815argument that names a global variable holding the address of the 5816alternate stack. 5817 5818@smallexample 5819void *alt_stack; 5820void f () __attribute__ ((interrupt_handler, 5821 sp_switch ("alt_stack"))); 5822@end smallexample 5823 5824@item trap_exit 5825@cindex @code{trap_exit} function attribute, SH 5826Use this attribute on the SH for an @code{interrupt_handler} to return using 5827@code{trapa} instead of @code{rte}. This attribute expects an integer 5828argument specifying the trap number to be used. 5829 5830@item trapa_handler 5831@cindex @code{trapa_handler} function attribute, SH 5832On SH targets this function attribute is similar to @code{interrupt_handler} 5833but it does not save and restore all registers. 5834@end table 5835 5836@node SPU Function Attributes 5837@subsection SPU Function Attributes 5838 5839These function attributes are supported by the SPU back end: 5840 5841@table @code 5842@item naked 5843@cindex @code{naked} function attribute, SPU 5844This attribute allows the compiler to construct the 5845requisite function declaration, while allowing the body of the 5846function to be assembly code. The specified function will not have 5847prologue/epilogue sequences generated by the compiler. Only basic 5848@code{asm} statements can safely be included in naked functions 5849(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5850basic @code{asm} and C code may appear to work, they cannot be 5851depended upon to work reliably and are not supported. 5852@end table 5853 5854@node Symbian OS Function Attributes 5855@subsection Symbian OS Function Attributes 5856 5857@xref{Microsoft Windows Function Attributes}, for discussion of the 5858@code{dllexport} and @code{dllimport} attributes. 5859 5860@node V850 Function Attributes 5861@subsection V850 Function Attributes 5862 5863The V850 back end supports these function attributes: 5864 5865@table @code 5866@item interrupt 5867@itemx interrupt_handler 5868@cindex @code{interrupt} function attribute, V850 5869@cindex @code{interrupt_handler} function attribute, V850 5870Use these attributes to indicate 5871that the specified function is an interrupt handler. The compiler generates 5872function entry and exit sequences suitable for use in an interrupt handler 5873when either attribute is present. 5874@end table 5875 5876@node Visium Function Attributes 5877@subsection Visium Function Attributes 5878 5879These function attributes are supported by the Visium back end: 5880 5881@table @code 5882@item interrupt 5883@cindex @code{interrupt} function attribute, Visium 5884Use this attribute to indicate 5885that the specified function is an interrupt handler. The compiler generates 5886function entry and exit sequences suitable for use in an interrupt handler 5887when this attribute is present. 5888@end table 5889 5890@node x86 Function Attributes 5891@subsection x86 Function Attributes 5892 5893These function attributes are supported by the x86 back end: 5894 5895@table @code 5896@item cdecl 5897@cindex @code{cdecl} function attribute, x86-32 5898@cindex functions that pop the argument stack on x86-32 5899@opindex mrtd 5900On the x86-32 targets, the @code{cdecl} attribute causes the compiler to 5901assume that the calling function pops off the stack space used to 5902pass arguments. This is 5903useful to override the effects of the @option{-mrtd} switch. 5904 5905@item fastcall 5906@cindex @code{fastcall} function attribute, x86-32 5907@cindex functions that pop the argument stack on x86-32 5908On x86-32 targets, the @code{fastcall} attribute causes the compiler to 5909pass the first argument (if of integral type) in the register ECX and 5910the second argument (if of integral type) in the register EDX@. Subsequent 5911and other typed arguments are passed on the stack. The called function 5912pops the arguments off the stack. If the number of arguments is variable all 5913arguments are pushed on the stack. 5914 5915@item thiscall 5916@cindex @code{thiscall} function attribute, x86-32 5917@cindex functions that pop the argument stack on x86-32 5918On x86-32 targets, the @code{thiscall} attribute causes the compiler to 5919pass the first argument (if of integral type) in the register ECX. 5920Subsequent and other typed arguments are passed on the stack. The called 5921function pops the arguments off the stack. 5922If the number of arguments is variable all arguments are pushed on the 5923stack. 5924The @code{thiscall} attribute is intended for C++ non-static member functions. 5925As a GCC extension, this calling convention can be used for C functions 5926and for static member methods. 5927 5928@item ms_abi 5929@itemx sysv_abi 5930@cindex @code{ms_abi} function attribute, x86 5931@cindex @code{sysv_abi} function attribute, x86 5932 5933On 32-bit and 64-bit x86 targets, you can use an ABI attribute 5934to indicate which calling convention should be used for a function. The 5935@code{ms_abi} attribute tells the compiler to use the Microsoft ABI, 5936while the @code{sysv_abi} attribute tells the compiler to use the ABI 5937used on GNU/Linux and other systems. The default is to use the Microsoft ABI 5938when targeting Windows. On all other systems, the default is the x86/AMD ABI. 5939 5940Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently 5941requires the @option{-maccumulate-outgoing-args} option. 5942 5943@item callee_pop_aggregate_return (@var{number}) 5944@cindex @code{callee_pop_aggregate_return} function attribute, x86 5945 5946On x86-32 targets, you can use this attribute to control how 5947aggregates are returned in memory. If the caller is responsible for 5948popping the hidden pointer together with the rest of the arguments, specify 5949@var{number} equal to zero. If callee is responsible for popping the 5950hidden pointer, specify @var{number} equal to one. 5951 5952The default x86-32 ABI assumes that the callee pops the 5953stack for hidden pointer. However, on x86-32 Microsoft Windows targets, 5954the compiler assumes that the 5955caller pops the stack for hidden pointer. 5956 5957@item ms_hook_prologue 5958@cindex @code{ms_hook_prologue} function attribute, x86 5959 5960On 32-bit and 64-bit x86 targets, you can use 5961this function attribute to make GCC generate the ``hot-patching'' function 5962prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2 5963and newer. 5964 5965@item naked 5966@cindex @code{naked} function attribute, x86 5967This attribute allows the compiler to construct the 5968requisite function declaration, while allowing the body of the 5969function to be assembly code. The specified function will not have 5970prologue/epilogue sequences generated by the compiler. Only basic 5971@code{asm} statements can safely be included in naked functions 5972(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5973basic @code{asm} and C code may appear to work, they cannot be 5974depended upon to work reliably and are not supported. 5975 5976@item regparm (@var{number}) 5977@cindex @code{regparm} function attribute, x86 5978@cindex functions that are passed arguments in registers on x86-32 5979On x86-32 targets, the @code{regparm} attribute causes the compiler to 5980pass arguments number one to @var{number} if they are of integral type 5981in registers EAX, EDX, and ECX instead of on the stack. Functions that 5982take a variable number of arguments continue to be passed all of their 5983arguments on the stack. 5984 5985Beware that on some ELF systems this attribute is unsuitable for 5986global functions in shared libraries with lazy binding (which is the 5987default). Lazy binding sends the first call via resolving code in 5988the loader, which might assume EAX, EDX and ECX can be clobbered, as 5989per the standard calling conventions. Solaris 8 is affected by this. 5990Systems with the GNU C Library version 2.1 or higher 5991and FreeBSD are believed to be 5992safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be 5993disabled with the linker or the loader if desired, to avoid the 5994problem.) 5995 5996@item sseregparm 5997@cindex @code{sseregparm} function attribute, x86 5998On x86-32 targets with SSE support, the @code{sseregparm} attribute 5999causes the compiler to pass up to 3 floating-point arguments in 6000SSE registers instead of on the stack. Functions that take a 6001variable number of arguments continue to pass all of their 6002floating-point arguments on the stack. 6003 6004@item force_align_arg_pointer 6005@cindex @code{force_align_arg_pointer} function attribute, x86 6006On x86 targets, the @code{force_align_arg_pointer} attribute may be 6007applied to individual function definitions, generating an alternate 6008prologue and epilogue that realigns the run-time stack if necessary. 6009This supports mixing legacy codes that run with a 4-byte aligned stack 6010with modern codes that keep a 16-byte stack for SSE compatibility. 6011 6012@item stdcall 6013@cindex @code{stdcall} function attribute, x86-32 6014@cindex functions that pop the argument stack on x86-32 6015On x86-32 targets, the @code{stdcall} attribute causes the compiler to 6016assume that the called function pops off the stack space used to 6017pass arguments, unless it takes a variable number of arguments. 6018 6019@item no_caller_saved_registers 6020@cindex @code{no_caller_saved_registers} function attribute, x86 6021Use this attribute to indicate that the specified function has no 6022caller-saved registers. That is, all registers are callee-saved. For 6023example, this attribute can be used for a function called from an 6024interrupt handler. The compiler generates proper function entry and 6025exit sequences to save and restore any modified registers, except for 6026the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87 6027states, the GCC option @option{-mgeneral-regs-only} should be used to 6028compile functions with @code{no_caller_saved_registers} attribute. 6029 6030@item interrupt 6031@cindex @code{interrupt} function attribute, x86 6032Use this attribute to indicate that the specified function is an 6033interrupt handler or an exception handler (depending on parameters passed 6034to the function, explained further). The compiler generates function 6035entry and exit sequences suitable for use in an interrupt handler when 6036this attribute is present. The @code{IRET} instruction, instead of the 6037@code{RET} instruction, is used to return from interrupt handlers. All 6038registers, except for the EFLAGS register which is restored by the 6039@code{IRET} instruction, are preserved by the compiler. Since GCC 6040doesn't preserve SSE, MMX nor x87 states, the GCC option 6041@option{-mgeneral-regs-only} should be used to compile interrupt and 6042exception handlers. 6043 6044Any interruptible-without-stack-switch code must be compiled with 6045@option{-mno-red-zone} since interrupt handlers can and will, because 6046of the hardware design, touch the red zone. 6047 6048An interrupt handler must be declared with a mandatory pointer 6049argument: 6050 6051@smallexample 6052struct interrupt_frame; 6053 6054__attribute__ ((interrupt)) 6055void 6056f (struct interrupt_frame *frame) 6057@{ 6058@} 6059@end smallexample 6060 6061@noindent 6062and you must define @code{struct interrupt_frame} as described in the 6063processor's manual. 6064 6065Exception handlers differ from interrupt handlers because the system 6066pushes an error code on the stack. An exception handler declaration is 6067similar to that for an interrupt handler, but with a different mandatory 6068function signature. The compiler arranges to pop the error code off the 6069stack before the @code{IRET} instruction. 6070 6071@smallexample 6072#ifdef __x86_64__ 6073typedef unsigned long long int uword_t; 6074#else 6075typedef unsigned int uword_t; 6076#endif 6077 6078struct interrupt_frame; 6079 6080__attribute__ ((interrupt)) 6081void 6082f (struct interrupt_frame *frame, uword_t error_code) 6083@{ 6084 ... 6085@} 6086@end smallexample 6087 6088Exception handlers should only be used for exceptions that push an error 6089code; you should use an interrupt handler in other cases. The system 6090will crash if the wrong kind of handler is used. 6091 6092@item target (@var{options}) 6093@cindex @code{target} function attribute 6094As discussed in @ref{Common Function Attributes}, this attribute 6095allows specification of target-specific compilation options. 6096 6097On the x86, the following options are allowed: 6098@table @samp 6099@item 3dnow 6100@itemx no-3dnow 6101@cindex @code{target("3dnow")} function attribute, x86 6102Enable/disable the generation of the 3DNow!@: instructions. 6103 6104@item 3dnowa 6105@itemx no-3dnowa 6106@cindex @code{target("3dnowa")} function attribute, x86 6107Enable/disable the generation of the enhanced 3DNow!@: instructions. 6108 6109@item abm 6110@itemx no-abm 6111@cindex @code{target("abm")} function attribute, x86 6112Enable/disable the generation of the advanced bit instructions. 6113 6114@item adx 6115@itemx no-adx 6116@cindex @code{target("adx")} function attribute, x86 6117Enable/disable the generation of the ADX instructions. 6118 6119@item aes 6120@itemx no-aes 6121@cindex @code{target("aes")} function attribute, x86 6122Enable/disable the generation of the AES instructions. 6123 6124@item avx 6125@itemx no-avx 6126@cindex @code{target("avx")} function attribute, x86 6127Enable/disable the generation of the AVX instructions. 6128 6129@item avx2 6130@itemx no-avx2 6131@cindex @code{target("avx2")} function attribute, x86 6132Enable/disable the generation of the AVX2 instructions. 6133 6134@item avx5124fmaps 6135@itemx no-avx5124fmaps 6136@cindex @code{target("avx5124fmaps")} function attribute, x86 6137Enable/disable the generation of the AVX5124FMAPS instructions. 6138 6139@item avx5124vnniw 6140@itemx no-avx5124vnniw 6141@cindex @code{target("avx5124vnniw")} function attribute, x86 6142Enable/disable the generation of the AVX5124VNNIW instructions. 6143 6144@item avx512bitalg 6145@itemx no-avx512bitalg 6146@cindex @code{target("avx512bitalg")} function attribute, x86 6147Enable/disable the generation of the AVX512BITALG instructions. 6148 6149@item avx512bw 6150@itemx no-avx512bw 6151@cindex @code{target("avx512bw")} function attribute, x86 6152Enable/disable the generation of the AVX512BW instructions. 6153 6154@item avx512cd 6155@itemx no-avx512cd 6156@cindex @code{target("avx512cd")} function attribute, x86 6157Enable/disable the generation of the AVX512CD instructions. 6158 6159@item avx512dq 6160@itemx no-avx512dq 6161@cindex @code{target("avx512dq")} function attribute, x86 6162Enable/disable the generation of the AVX512DQ instructions. 6163 6164@item avx512er 6165@itemx no-avx512er 6166@cindex @code{target("avx512er")} function attribute, x86 6167Enable/disable the generation of the AVX512ER instructions. 6168 6169@item avx512f 6170@itemx no-avx512f 6171@cindex @code{target("avx512f")} function attribute, x86 6172Enable/disable the generation of the AVX512F instructions. 6173 6174@item avx512ifma 6175@itemx no-avx512ifma 6176@cindex @code{target("avx512ifma")} function attribute, x86 6177Enable/disable the generation of the AVX512IFMA instructions. 6178 6179@item avx512pf 6180@itemx no-avx512pf 6181@cindex @code{target("avx512pf")} function attribute, x86 6182Enable/disable the generation of the AVX512PF instructions. 6183 6184@item avx512vbmi 6185@itemx no-avx512vbmi 6186@cindex @code{target("avx512vbmi")} function attribute, x86 6187Enable/disable the generation of the AVX512VBMI instructions. 6188 6189@item avx512vbmi2 6190@itemx no-avx512vbmi2 6191@cindex @code{target("avx512vbmi2")} function attribute, x86 6192Enable/disable the generation of the AVX512VBMI2 instructions. 6193 6194@item avx512vl 6195@itemx no-avx512vl 6196@cindex @code{target("avx512vl")} function attribute, x86 6197Enable/disable the generation of the AVX512VL instructions. 6198 6199@item avx512vnni 6200@itemx no-avx512vnni 6201@cindex @code{target("avx512vnni")} function attribute, x86 6202Enable/disable the generation of the AVX512VNNI instructions. 6203 6204@item avx512vpopcntdq 6205@itemx no-avx512vpopcntdq 6206@cindex @code{target("avx512vpopcntdq")} function attribute, x86 6207Enable/disable the generation of the AVX512VPOPCNTDQ instructions. 6208 6209@item bmi 6210@itemx no-bmi 6211@cindex @code{target("bmi")} function attribute, x86 6212Enable/disable the generation of the BMI instructions. 6213 6214@item bmi2 6215@itemx no-bmi2 6216@cindex @code{target("bmi2")} function attribute, x86 6217Enable/disable the generation of the BMI2 instructions. 6218 6219@item cldemote 6220@itemx no-cldemote 6221@cindex @code{target("cldemote")} function attribute, x86 6222Enable/disable the generation of the CLDEMOTE instructions. 6223 6224@item clflushopt 6225@itemx no-clflushopt 6226@cindex @code{target("clflushopt")} function attribute, x86 6227Enable/disable the generation of the CLFLUSHOPT instructions. 6228 6229@item clwb 6230@itemx no-clwb 6231@cindex @code{target("clwb")} function attribute, x86 6232Enable/disable the generation of the CLWB instructions. 6233 6234@item clzero 6235@itemx no-clzero 6236@cindex @code{target("clzero")} function attribute, x86 6237Enable/disable the generation of the CLZERO instructions. 6238 6239@item crc32 6240@itemx no-crc32 6241@cindex @code{target("crc32")} function attribute, x86 6242Enable/disable the generation of the CRC32 instructions. 6243 6244@item cx16 6245@itemx no-cx16 6246@cindex @code{target("cx16")} function attribute, x86 6247Enable/disable the generation of the CMPXCHG16B instructions. 6248 6249@item default 6250@cindex @code{target("default")} function attribute, x86 6251@xref{Function Multiversioning}, where it is used to specify the 6252default function version. 6253 6254@item f16c 6255@itemx no-f16c 6256@cindex @code{target("f16c")} function attribute, x86 6257Enable/disable the generation of the F16C instructions. 6258 6259@item fma 6260@itemx no-fma 6261@cindex @code{target("fma")} function attribute, x86 6262Enable/disable the generation of the FMA instructions. 6263 6264@item fma4 6265@itemx no-fma4 6266@cindex @code{target("fma4")} function attribute, x86 6267Enable/disable the generation of the FMA4 instructions. 6268 6269@item fsgsbase 6270@itemx no-fsgsbase 6271@cindex @code{target("fsgsbase")} function attribute, x86 6272Enable/disable the generation of the FSGSBASE instructions. 6273 6274@item fxsr 6275@itemx no-fxsr 6276@cindex @code{target("fxsr")} function attribute, x86 6277Enable/disable the generation of the FXSR instructions. 6278 6279@item gfni 6280@itemx no-gfni 6281@cindex @code{target("gfni")} function attribute, x86 6282Enable/disable the generation of the GFNI instructions. 6283 6284@item hle 6285@itemx no-hle 6286@cindex @code{target("hle")} function attribute, x86 6287Enable/disable the generation of the HLE instruction prefixes. 6288 6289@item lwp 6290@itemx no-lwp 6291@cindex @code{target("lwp")} function attribute, x86 6292Enable/disable the generation of the LWP instructions. 6293 6294@item lzcnt 6295@itemx no-lzcnt 6296@cindex @code{target("lzcnt")} function attribute, x86 6297Enable/disable the generation of the LZCNT instructions. 6298 6299@item mmx 6300@itemx no-mmx 6301@cindex @code{target("mmx")} function attribute, x86 6302Enable/disable the generation of the MMX instructions. 6303 6304@item movbe 6305@itemx no-movbe 6306@cindex @code{target("movbe")} function attribute, x86 6307Enable/disable the generation of the MOVBE instructions. 6308 6309@item movdir64b 6310@itemx no-movdir64b 6311@cindex @code{target("movdir64b")} function attribute, x86 6312Enable/disable the generation of the MOVDIR64B instructions. 6313 6314@item movdiri 6315@itemx no-movdiri 6316@cindex @code{target("movdiri")} function attribute, x86 6317Enable/disable the generation of the MOVDIRI instructions. 6318 6319@item mwaitx 6320@itemx no-mwaitx 6321@cindex @code{target("mwaitx")} function attribute, x86 6322Enable/disable the generation of the MWAITX instructions. 6323 6324@item pclmul 6325@itemx no-pclmul 6326@cindex @code{target("pclmul")} function attribute, x86 6327Enable/disable the generation of the PCLMUL instructions. 6328 6329@item pconfig 6330@itemx no-pconfig 6331@cindex @code{target("pconfig")} function attribute, x86 6332Enable/disable the generation of the PCONFIG instructions. 6333 6334@item pku 6335@itemx no-pku 6336@cindex @code{target("pku")} function attribute, x86 6337Enable/disable the generation of the PKU instructions. 6338 6339@item popcnt 6340@itemx no-popcnt 6341@cindex @code{target("popcnt")} function attribute, x86 6342Enable/disable the generation of the POPCNT instruction. 6343 6344@item prefetchwt1 6345@itemx no-prefetchwt1 6346@cindex @code{target("prefetchwt1")} function attribute, x86 6347Enable/disable the generation of the PREFETCHWT1 instructions. 6348 6349@item prfchw 6350@itemx no-prfchw 6351@cindex @code{target("prfchw")} function attribute, x86 6352Enable/disable the generation of the PREFETCHW instruction. 6353 6354@item ptwrite 6355@itemx no-ptwrite 6356@cindex @code{target("ptwrite")} function attribute, x86 6357Enable/disable the generation of the PTWRITE instructions. 6358 6359@item rdpid 6360@itemx no-rdpid 6361@cindex @code{target("rdpid")} function attribute, x86 6362Enable/disable the generation of the RDPID instructions. 6363 6364@item rdrnd 6365@itemx no-rdrnd 6366@cindex @code{target("rdrnd")} function attribute, x86 6367Enable/disable the generation of the RDRND instructions. 6368 6369@item rdseed 6370@itemx no-rdseed 6371@cindex @code{target("rdseed")} function attribute, x86 6372Enable/disable the generation of the RDSEED instructions. 6373 6374@item rtm 6375@itemx no-rtm 6376@cindex @code{target("rtm")} function attribute, x86 6377Enable/disable the generation of the RTM instructions. 6378 6379@item sahf 6380@itemx no-sahf 6381@cindex @code{target("sahf")} function attribute, x86 6382Enable/disable the generation of the SAHF instructions. 6383 6384@item sgx 6385@itemx no-sgx 6386@cindex @code{target("sgx")} function attribute, x86 6387Enable/disable the generation of the SGX instructions. 6388 6389@item sha 6390@itemx no-sha 6391@cindex @code{target("sha")} function attribute, x86 6392Enable/disable the generation of the SHA instructions. 6393 6394@item shstk 6395@itemx no-shstk 6396@cindex @code{target("shstk")} function attribute, x86 6397Enable/disable the shadow stack built-in functions from CET. 6398 6399@item sse 6400@itemx no-sse 6401@cindex @code{target("sse")} function attribute, x86 6402Enable/disable the generation of the SSE instructions. 6403 6404@item sse2 6405@itemx no-sse2 6406@cindex @code{target("sse2")} function attribute, x86 6407Enable/disable the generation of the SSE2 instructions. 6408 6409@item sse3 6410@itemx no-sse3 6411@cindex @code{target("sse3")} function attribute, x86 6412Enable/disable the generation of the SSE3 instructions. 6413 6414@item sse4 6415@itemx no-sse4 6416@cindex @code{target("sse4")} function attribute, x86 6417Enable/disable the generation of the SSE4 instructions (both SSE4.1 6418and SSE4.2). 6419 6420@item sse4.1 6421@itemx no-sse4.1 6422@cindex @code{target("sse4.1")} function attribute, x86 6423Enable/disable the generation of the sse4.1 instructions. 6424 6425@item sse4.2 6426@itemx no-sse4.2 6427@cindex @code{target("sse4.2")} function attribute, x86 6428Enable/disable the generation of the sse4.2 instructions. 6429 6430@item sse4a 6431@itemx no-sse4a 6432@cindex @code{target("sse4a")} function attribute, x86 6433Enable/disable the generation of the SSE4A instructions. 6434 6435@item ssse3 6436@itemx no-ssse3 6437@cindex @code{target("ssse3")} function attribute, x86 6438Enable/disable the generation of the SSSE3 instructions. 6439 6440@item tbm 6441@itemx no-tbm 6442@cindex @code{target("tbm")} function attribute, x86 6443Enable/disable the generation of the TBM instructions. 6444 6445@item vaes 6446@itemx no-vaes 6447@cindex @code{target("vaes")} function attribute, x86 6448Enable/disable the generation of the VAES instructions. 6449 6450@item vpclmulqdq 6451@itemx no-vpclmulqdq 6452@cindex @code{target("vpclmulqdq")} function attribute, x86 6453Enable/disable the generation of the VPCLMULQDQ instructions. 6454 6455@item waitpkg 6456@itemx no-waitpkg 6457@cindex @code{target("waitpkg")} function attribute, x86 6458Enable/disable the generation of the WAITPKG instructions. 6459 6460@item wbnoinvd 6461@itemx no-wbnoinvd 6462@cindex @code{target("wbnoinvd")} function attribute, x86 6463Enable/disable the generation of the WBNOINVD instructions. 6464 6465@item xop 6466@itemx no-xop 6467@cindex @code{target("xop")} function attribute, x86 6468Enable/disable the generation of the XOP instructions. 6469 6470@item xsave 6471@itemx no-xsave 6472@cindex @code{target("xsave")} function attribute, x86 6473Enable/disable the generation of the XSAVE instructions. 6474 6475@item xsavec 6476@itemx no-xsavec 6477@cindex @code{target("xsavec")} function attribute, x86 6478Enable/disable the generation of the XSAVEC instructions. 6479 6480@item xsaveopt 6481@itemx no-xsaveopt 6482@cindex @code{target("xsaveopt")} function attribute, x86 6483Enable/disable the generation of the XSAVEOPT instructions. 6484 6485@item xsaves 6486@itemx no-xsaves 6487@cindex @code{target("xsaves")} function attribute, x86 6488Enable/disable the generation of the XSAVES instructions. 6489 6490@item cld 6491@itemx no-cld 6492@cindex @code{target("cld")} function attribute, x86 6493Enable/disable the generation of the CLD before string moves. 6494 6495@item fancy-math-387 6496@itemx no-fancy-math-387 6497@cindex @code{target("fancy-math-387")} function attribute, x86 6498Enable/disable the generation of the @code{sin}, @code{cos}, and 6499@code{sqrt} instructions on the 387 floating-point unit. 6500 6501@item ieee-fp 6502@itemx no-ieee-fp 6503@cindex @code{target("ieee-fp")} function attribute, x86 6504Enable/disable the generation of floating point that depends on IEEE arithmetic. 6505 6506@item inline-all-stringops 6507@itemx no-inline-all-stringops 6508@cindex @code{target("inline-all-stringops")} function attribute, x86 6509Enable/disable inlining of string operations. 6510 6511@item inline-stringops-dynamically 6512@itemx no-inline-stringops-dynamically 6513@cindex @code{target("inline-stringops-dynamically")} function attribute, x86 6514Enable/disable the generation of the inline code to do small string 6515operations and calling the library routines for large operations. 6516 6517@item align-stringops 6518@itemx no-align-stringops 6519@cindex @code{target("align-stringops")} function attribute, x86 6520Do/do not align destination of inlined string operations. 6521 6522@item recip 6523@itemx no-recip 6524@cindex @code{target("recip")} function attribute, x86 6525Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS 6526instructions followed an additional Newton-Raphson step instead of 6527doing a floating-point division. 6528 6529@item arch=@var{ARCH} 6530@cindex @code{target("arch=@var{ARCH}")} function attribute, x86 6531Specify the architecture to generate code for in compiling the function. 6532 6533@item tune=@var{TUNE} 6534@cindex @code{target("tune=@var{TUNE}")} function attribute, x86 6535Specify the architecture to tune for in compiling the function. 6536 6537@item fpmath=@var{FPMATH} 6538@cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86 6539Specify which floating-point unit to use. You must specify the 6540@code{target("fpmath=sse,387")} option as 6541@code{target("fpmath=sse+387")} because the comma would separate 6542different options. 6543 6544@item indirect_branch("@var{choice}") 6545@cindex @code{indirect_branch} function attribute, x86 6546On x86 targets, the @code{indirect_branch} attribute causes the compiler 6547to convert indirect call and jump with @var{choice}. @samp{keep} 6548keeps indirect call and jump unmodified. @samp{thunk} converts indirect 6549call and jump to call and return thunk. @samp{thunk-inline} converts 6550indirect call and jump to inlined call and return thunk. 6551@samp{thunk-extern} converts indirect call and jump to external call 6552and return thunk provided in a separate object file. 6553 6554@item function_return("@var{choice}") 6555@cindex @code{function_return} function attribute, x86 6556On x86 targets, the @code{function_return} attribute causes the compiler 6557to convert function return with @var{choice}. @samp{keep} keeps function 6558return unmodified. @samp{thunk} converts function return to call and 6559return thunk. @samp{thunk-inline} converts function return to inlined 6560call and return thunk. @samp{thunk-extern} converts function return to 6561external call and return thunk provided in a separate object file. 6562 6563@item nocf_check 6564@cindex @code{nocf_check} function attribute 6565The @code{nocf_check} attribute on a function is used to inform the 6566compiler that the function's prologue should not be instrumented when 6567compiled with the @option{-fcf-protection=branch} option. The 6568compiler assumes that the function's address is a valid target for a 6569control-flow transfer. 6570 6571The @code{nocf_check} attribute on a type of pointer to function is 6572used to inform the compiler that a call through the pointer should 6573not be instrumented when compiled with the 6574@option{-fcf-protection=branch} option. The compiler assumes 6575that the function's address from the pointer is a valid target for 6576a control-flow transfer. A direct function call through a function 6577name is assumed to be a safe call thus direct calls are not 6578instrumented by the compiler. 6579 6580The @code{nocf_check} attribute is applied to an object's type. 6581In case of assignment of a function address or a function pointer to 6582another pointer, the attribute is not carried over from the right-hand 6583object's type; the type of left-hand object stays unchanged. The 6584compiler checks for @code{nocf_check} attribute mismatch and reports 6585a warning in case of mismatch. 6586 6587@smallexample 6588@{ 6589int foo (void) __attribute__(nocf_check); 6590void (*foo1)(void) __attribute__(nocf_check); 6591void (*foo2)(void); 6592 6593/* foo's address is assumed to be valid. */ 6594int 6595foo (void) 6596 6597 /* This call site is not checked for control-flow 6598 validity. */ 6599 (*foo1)(); 6600 6601 /* A warning is issued about attribute mismatch. */ 6602 foo1 = foo2; 6603 6604 /* This call site is still not checked. */ 6605 (*foo1)(); 6606 6607 /* This call site is checked. */ 6608 (*foo2)(); 6609 6610 /* A warning is issued about attribute mismatch. */ 6611 foo2 = foo1; 6612 6613 /* This call site is still checked. */ 6614 (*foo2)(); 6615 6616 return 0; 6617@} 6618@end smallexample 6619 6620@item cf_check 6621@cindex @code{cf_check} function attribute, x86 6622 6623The @code{cf_check} attribute on a function is used to inform the 6624compiler that ENDBR instruction should be placed at the function 6625entry when @option{-fcf-protection=branch} is enabled. 6626 6627@item indirect_return 6628@cindex @code{indirect_return} function attribute, x86 6629 6630The @code{indirect_return} attribute can be applied to a function, 6631as well as variable or type of function pointer to inform the 6632compiler that the function may return via indirect branch. 6633 6634@item fentry_name("@var{name}") 6635@cindex @code{fentry_name} function attribute, x86 6636On x86 targets, the @code{fentry_name} attribute sets the function to 6637call on function entry when function instrumentation is enabled 6638with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte 6639nop sequence is generated. 6640 6641@item fentry_section("@var{name}") 6642@cindex @code{fentry_section} function attribute, x86 6643On x86 targets, the @code{fentry_section} attribute sets the name 6644of the section to record function entry instrumentation calls in when 6645enabled with @option{-pg -mrecord-mcount} 6646 6647@end table 6648 6649On the x86, the inliner does not inline a 6650function that has different target options than the caller, unless the 6651callee has a subset of the target options of the caller. For example 6652a function declared with @code{target("sse3")} can inline a function 6653with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}. 6654@end table 6655 6656@node Xstormy16 Function Attributes 6657@subsection Xstormy16 Function Attributes 6658 6659These function attributes are supported by the Xstormy16 back end: 6660 6661@table @code 6662@item interrupt 6663@cindex @code{interrupt} function attribute, Xstormy16 6664Use this attribute to indicate 6665that the specified function is an interrupt handler. The compiler generates 6666function entry and exit sequences suitable for use in an interrupt handler 6667when this attribute is present. 6668@end table 6669 6670@node Variable Attributes 6671@section Specifying Attributes of Variables 6672@cindex attribute of variables 6673@cindex variable attributes 6674 6675The keyword @code{__attribute__} allows you to specify special properties 6676of variables, function parameters, or structure, union, and, in C++, class 6677members. This @code{__attribute__} keyword is followed by an attribute 6678specification enclosed in double parentheses. Some attributes are currently 6679defined generically for variables. Other attributes are defined for 6680variables on particular target systems. Other attributes are available 6681for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}), 6682enumerators (@pxref{Enumerator Attributes}), statements 6683(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}). 6684Other front ends might define more attributes 6685(@pxref{C++ Extensions,,Extensions to the C++ Language}). 6686 6687@xref{Attribute Syntax}, for details of the exact syntax for using 6688attributes. 6689 6690@menu 6691* Common Variable Attributes:: 6692* ARC Variable Attributes:: 6693* AVR Variable Attributes:: 6694* Blackfin Variable Attributes:: 6695* H8/300 Variable Attributes:: 6696* IA-64 Variable Attributes:: 6697* M32R/D Variable Attributes:: 6698* MeP Variable Attributes:: 6699* Microsoft Windows Variable Attributes:: 6700* MSP430 Variable Attributes:: 6701* Nvidia PTX Variable Attributes:: 6702* PowerPC Variable Attributes:: 6703* RL78 Variable Attributes:: 6704* SPU Variable Attributes:: 6705* V850 Variable Attributes:: 6706* x86 Variable Attributes:: 6707* Xstormy16 Variable Attributes:: 6708@end menu 6709 6710@node Common Variable Attributes 6711@subsection Common Variable Attributes 6712 6713The following attributes are supported on most targets. 6714 6715@table @code 6716@cindex @code{aligned} variable attribute 6717@item aligned 6718@itemx aligned (@var{alignment}) 6719The @code{aligned} attribute specifies a minimum alignment for the variable 6720or structure field, measured in bytes. When specified, @var{alignment} must 6721be an integer constant power of 2. Specifying no @var{alignment} argument 6722implies the maximum alignment for the target, which is often, but by no 6723means always, 8 or 16 bytes. 6724 6725For example, the declaration: 6726 6727@smallexample 6728int x __attribute__ ((aligned (16))) = 0; 6729@end smallexample 6730 6731@noindent 6732causes the compiler to allocate the global variable @code{x} on a 673316-byte boundary. On a 68040, this could be used in conjunction with 6734an @code{asm} expression to access the @code{move16} instruction which 6735requires 16-byte aligned operands. 6736 6737You can also specify the alignment of structure fields. For example, to 6738create a double-word aligned @code{int} pair, you could write: 6739 6740@smallexample 6741struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; 6742@end smallexample 6743 6744@noindent 6745This is an alternative to creating a union with a @code{double} member, 6746which forces the union to be double-word aligned. 6747 6748As in the preceding examples, you can explicitly specify the alignment 6749(in bytes) that you wish the compiler to use for a given variable or 6750structure field. Alternatively, you can leave out the alignment factor 6751and just ask the compiler to align a variable or field to the 6752default alignment for the target architecture you are compiling for. 6753The default alignment is sufficient for all scalar types, but may not be 6754enough for all vector types on a target that supports vector operations. 6755The default alignment is fixed for a particular target ABI. 6756 6757GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__}, 6758which is the largest alignment ever used for any data type on the 6759target machine you are compiling for. For example, you could write: 6760 6761@smallexample 6762short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); 6763@end smallexample 6764 6765The compiler automatically sets the alignment for the declared 6766variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can 6767often make copy operations more efficient, because the compiler can 6768use whatever instructions copy the biggest chunks of memory when 6769performing copies to or from the variables or fields that you have 6770aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__} 6771may change depending on command-line options. 6772 6773When used on a struct, or struct member, the @code{aligned} attribute can 6774only increase the alignment; in order to decrease it, the @code{packed} 6775attribute must be specified as well. When used as part of a typedef, the 6776@code{aligned} attribute can both increase and decrease alignment, and 6777specifying the @code{packed} attribute generates a warning. 6778 6779Note that the effectiveness of @code{aligned} attributes for static 6780variables may be limited by inherent limitations in the system linker 6781and/or object file format. On some systems, the linker is 6782only able to arrange for variables to be aligned up to a certain maximum 6783alignment. (For some linkers, the maximum supported alignment may 6784be very very small.) If your linker is only able to align variables 6785up to a maximum of 8-byte alignment, then specifying @code{aligned(16)} 6786in an @code{__attribute__} still only provides you with 8-byte 6787alignment. See your linker documentation for further information. 6788 6789Stack variables are not affected by linker restrictions; GCC can properly 6790align them on any target. 6791 6792The @code{aligned} attribute can also be used for functions 6793(@pxref{Common Function Attributes}.) 6794 6795@cindex @code{warn_if_not_aligned} variable attribute 6796@item warn_if_not_aligned (@var{alignment}) 6797This attribute specifies a threshold for the structure field, measured 6798in bytes. If the structure field is aligned below the threshold, a 6799warning will be issued. For example, the declaration: 6800 6801@smallexample 6802struct foo 6803@{ 6804 int i1; 6805 int i2; 6806 unsigned long long x __attribute__ ((warn_if_not_aligned (16))); 6807@}; 6808@end smallexample 6809 6810@noindent 6811causes the compiler to issue an warning on @code{struct foo}, like 6812@samp{warning: alignment 8 of 'struct foo' is less than 16}. 6813The compiler also issues a warning, like @samp{warning: 'x' offset 68148 in 'struct foo' isn't aligned to 16}, when the structure field has 6815the misaligned offset: 6816 6817@smallexample 6818struct __attribute__ ((aligned (16))) foo 6819@{ 6820 int i1; 6821 int i2; 6822 unsigned long long x __attribute__ ((warn_if_not_aligned (16))); 6823@}; 6824@end smallexample 6825 6826This warning can be disabled by @option{-Wno-if-not-aligned}. 6827The @code{warn_if_not_aligned} attribute can also be used for types 6828(@pxref{Common Type Attributes}.) 6829 6830@item alloc_size (@var{position}) 6831@itemx alloc_size (@var{position-1}, @var{position-2}) 6832@cindex @code{alloc_size} variable attribute 6833The @code{alloc_size} variable attribute may be applied to the declaration 6834of a pointer to a function that returns a pointer and takes at least one 6835argument of an integer type. It indicates that the returned pointer points 6836to an object whose size is given by the function argument at @var{position-1}, 6837or by the product of the arguments at @var{position-1} and @var{position-2}. 6838Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other 6839sizes are disagnosed when detected. GCC uses this information to improve 6840the results of @code{__builtin_object_size}. 6841 6842For instance, the following declarations 6843 6844@smallexample 6845typedef __attribute__ ((alloc_size (1, 2))) void* 6846 (*calloc_ptr) (size_t, size_t); 6847typedef __attribute__ ((alloc_size (1))) void* 6848 (*malloc_ptr) (size_t); 6849@end smallexample 6850 6851@noindent 6852specify that @code{calloc_ptr} is a pointer of a function that, like 6853the standard C function @code{calloc}, returns an object whose size 6854is given by the product of arguments 1 and 2, and similarly, that 6855@code{malloc_ptr}, like the standard C function @code{malloc}, 6856returns an object whose size is given by argument 1 to the function. 6857 6858@item cleanup (@var{cleanup_function}) 6859@cindex @code{cleanup} variable attribute 6860The @code{cleanup} attribute runs a function when the variable goes 6861out of scope. This attribute can only be applied to auto function 6862scope variables; it may not be applied to parameters or variables 6863with static storage duration. The function must take one parameter, 6864a pointer to a type compatible with the variable. The return value 6865of the function (if any) is ignored. 6866 6867If @option{-fexceptions} is enabled, then @var{cleanup_function} 6868is run during the stack unwinding that happens during the 6869processing of the exception. Note that the @code{cleanup} attribute 6870does not allow the exception to be caught, only to perform an action. 6871It is undefined what happens if @var{cleanup_function} does not 6872return normally. 6873 6874@item common 6875@itemx nocommon 6876@cindex @code{common} variable attribute 6877@cindex @code{nocommon} variable attribute 6878@opindex fcommon 6879@opindex fno-common 6880The @code{common} attribute requests GCC to place a variable in 6881``common'' storage. The @code{nocommon} attribute requests the 6882opposite---to allocate space for it directly. 6883 6884These attributes override the default chosen by the 6885@option{-fno-common} and @option{-fcommon} flags respectively. 6886 6887@item copy 6888@itemx copy (@var{variable}) 6889@cindex @code{copy} variable attribute 6890The @code{copy} attribute applies the set of attributes with which 6891@var{variable} has been declared to the declaration of the variable 6892to which the attribute is applied. The attribute is designed for 6893libraries that define aliases that are expected to specify the same 6894set of attributes as the aliased symbols. The @code{copy} attribute 6895can be used with variables, functions or types. However, the kind 6896of symbol to which the attribute is applied (either varible or 6897function) must match the kind of symbol to which the argument refers. 6898The @code{copy} attribute copies only syntactic and semantic attributes 6899but not attributes that affect a symbol's linkage or visibility such as 6900@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} 6901attribute is also not copied. @xref{Common Function Attributes}. 6902@xref{Common Type Attributes}. 6903 6904@item deprecated 6905@itemx deprecated (@var{msg}) 6906@cindex @code{deprecated} variable attribute 6907The @code{deprecated} attribute results in a warning if the variable 6908is used anywhere in the source file. This is useful when identifying 6909variables that are expected to be removed in a future version of a 6910program. The warning also includes the location of the declaration 6911of the deprecated variable, to enable users to easily find further 6912information about why the variable is deprecated, or what they should 6913do instead. Note that the warning only occurs for uses: 6914 6915@smallexample 6916extern int old_var __attribute__ ((deprecated)); 6917extern int old_var; 6918int new_fn () @{ return old_var; @} 6919@end smallexample 6920 6921@noindent 6922results in a warning on line 3 but not line 2. The optional @var{msg} 6923argument, which must be a string, is printed in the warning if 6924present. 6925 6926The @code{deprecated} attribute can also be used for functions and 6927types (@pxref{Common Function Attributes}, 6928@pxref{Common Type Attributes}). 6929 6930The message attached to the attribute is affected by the setting of 6931the @option{-fmessage-length} option. 6932 6933@item mode (@var{mode}) 6934@cindex @code{mode} variable attribute 6935This attribute specifies the data type for the declaration---whichever 6936type corresponds to the mode @var{mode}. This in effect lets you 6937request an integer or floating-point type according to its width. 6938 6939@xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals}, 6940for a list of the possible keywords for @var{mode}. 6941You may also specify a mode of @code{byte} or @code{__byte__} to 6942indicate the mode corresponding to a one-byte integer, @code{word} or 6943@code{__word__} for the mode of a one-word integer, and @code{pointer} 6944or @code{__pointer__} for the mode used to represent pointers. 6945 6946@item nonstring 6947@cindex @code{nonstring} variable attribute 6948The @code{nonstring} variable attribute specifies that an object or member 6949declaration with type array of @code{char}, @code{signed char}, or 6950@code{unsigned char}, or pointer to such a type is intended to store 6951character arrays that do not necessarily contain a terminating @code{NUL}. 6952This is useful in detecting uses of such arrays or pointers with functions 6953that expect @code{NUL}-terminated strings, and to avoid warnings when such 6954an array or pointer is used as an argument to a bounded string manipulation 6955function such as @code{strncpy}. For example, without the attribute, GCC 6956will issue a warning for the @code{strncpy} call below because it may 6957truncate the copy without appending the terminating @code{NUL} character. 6958Using the attribute makes it possible to suppress the warning. However, 6959when the array is declared with the attribute the call to @code{strlen} is 6960diagnosed because when the array doesn't contain a @code{NUL}-terminated 6961string the call is undefined. To copy, compare, of search non-string 6962character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr}, 6963and other functions that operate on arrays of bytes. In addition, 6964calling @code{strnlen} and @code{strndup} with such arrays is safe 6965provided a suitable bound is specified, and not diagnosed. 6966 6967@smallexample 6968struct Data 6969@{ 6970 char name [32] __attribute__ ((nonstring)); 6971@}; 6972 6973int f (struct Data *pd, const char *s) 6974@{ 6975 strncpy (pd->name, s, sizeof pd->name); 6976 @dots{} 6977 return strlen (pd->name); // unsafe, gets a warning 6978@} 6979@end smallexample 6980 6981@item packed 6982@cindex @code{packed} variable attribute 6983The @code{packed} attribute specifies that a structure member should have 6984the smallest possible alignment---one bit for a bit-field and one byte 6985otherwise, unless a larger value is specified with the @code{aligned} 6986attribute. The attribute does not apply to non-member objects. 6987 6988For example in the structure below, the member array @code{x} is packed 6989so that it immediately follows @code{a} with no intervening padding: 6990 6991@smallexample 6992struct foo 6993@{ 6994 char a; 6995 int x[2] __attribute__ ((packed)); 6996@}; 6997@end smallexample 6998 6999@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the 7000@code{packed} attribute on bit-fields of type @code{char}. This has 7001been fixed in GCC 4.4 but the change can lead to differences in the 7002structure layout. See the documentation of 7003@option{-Wpacked-bitfield-compat} for more information. 7004 7005@item section ("@var{section-name}") 7006@cindex @code{section} variable attribute 7007Normally, the compiler places the objects it generates in sections like 7008@code{data} and @code{bss}. Sometimes, however, you need additional sections, 7009or you need certain particular variables to appear in special sections, 7010for example to map to special hardware. The @code{section} 7011attribute specifies that a variable (or function) lives in a particular 7012section. For example, this small program uses several specific section names: 7013 7014@smallexample 7015struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; 7016struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; 7017char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; 7018int init_data __attribute__ ((section ("INITDATA"))); 7019 7020main() 7021@{ 7022 /* @r{Initialize stack pointer} */ 7023 init_sp (stack + sizeof (stack)); 7024 7025 /* @r{Initialize initialized data} */ 7026 memcpy (&init_data, &data, &edata - &data); 7027 7028 /* @r{Turn on the serial ports} */ 7029 init_duart (&a); 7030 init_duart (&b); 7031@} 7032@end smallexample 7033 7034@noindent 7035Use the @code{section} attribute with 7036@emph{global} variables and not @emph{local} variables, 7037as shown in the example. 7038 7039You may use the @code{section} attribute with initialized or 7040uninitialized global variables but the linker requires 7041each object be defined once, with the exception that uninitialized 7042variables tentatively go in the @code{common} (or @code{bss}) section 7043and can be multiply ``defined''. Using the @code{section} attribute 7044changes what section the variable goes into and may cause the 7045linker to issue an error if an uninitialized variable has multiple 7046definitions. You can force a variable to be initialized with the 7047@option{-fno-common} flag or the @code{nocommon} attribute. 7048 7049Some file formats do not support arbitrary sections so the @code{section} 7050attribute is not available on all platforms. 7051If you need to map the entire contents of a module to a particular 7052section, consider using the facilities of the linker instead. 7053 7054@item tls_model ("@var{tls_model}") 7055@cindex @code{tls_model} variable attribute 7056The @code{tls_model} attribute sets thread-local storage model 7057(@pxref{Thread-Local}) of a particular @code{__thread} variable, 7058overriding @option{-ftls-model=} command-line switch on a per-variable 7059basis. 7060The @var{tls_model} argument should be one of @code{global-dynamic}, 7061@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. 7062 7063Not all targets support this attribute. 7064 7065@item unused 7066@cindex @code{unused} variable attribute 7067This attribute, attached to a variable, means that the variable is meant 7068to be possibly unused. GCC does not produce a warning for this 7069variable. 7070 7071@item used 7072@cindex @code{used} variable attribute 7073This attribute, attached to a variable with static storage, means that 7074the variable must be emitted even if it appears that the variable is not 7075referenced. 7076 7077When applied to a static data member of a C++ class template, the 7078attribute also means that the member is instantiated if the 7079class itself is instantiated. 7080 7081@item vector_size (@var{bytes}) 7082@cindex @code{vector_size} variable attribute 7083This attribute specifies the vector size for the type of the declared 7084variable, measured in bytes. The type to which it applies is known as 7085the @dfn{base type}. The @var{bytes} argument must be a positive 7086power-of-two multiple of the base type size. For example, the declaration: 7087 7088@smallexample 7089int foo __attribute__ ((vector_size (16))); 7090@end smallexample 7091 7092@noindent 7093causes the compiler to set the mode for @code{foo}, to be 16 bytes, 7094divided into @code{int} sized units. Assuming a 32-bit @code{int}, 7095@code{foo}'s type is a vector of four units of four bytes each, and 7096the corresponding mode of @code{foo} is @code{V4SI}. 7097@xref{Vector Extensions} for details of manipulating vector variables. 7098 7099This attribute is only applicable to integral and floating scalars, 7100although arrays, pointers, and function return values are allowed in 7101conjunction with this construct. 7102 7103Aggregates with this attribute are invalid, even if they are of the same 7104size as a corresponding scalar. For example, the declaration: 7105 7106@smallexample 7107struct S @{ int a; @}; 7108struct S __attribute__ ((vector_size (16))) foo; 7109@end smallexample 7110 7111@noindent 7112is invalid even if the size of the structure is the same as the size of 7113the @code{int}. 7114 7115@item visibility ("@var{visibility_type}") 7116@cindex @code{visibility} variable attribute 7117This attribute affects the linkage of the declaration to which it is attached. 7118The @code{visibility} attribute is described in 7119@ref{Common Function Attributes}. 7120 7121@item weak 7122@cindex @code{weak} variable attribute 7123The @code{weak} attribute is described in 7124@ref{Common Function Attributes}. 7125 7126@end table 7127 7128@node ARC Variable Attributes 7129@subsection ARC Variable Attributes 7130 7131@table @code 7132@item aux 7133@cindex @code{aux} variable attribute, ARC 7134The @code{aux} attribute is used to directly access the ARC's 7135auxiliary register space from C. The auxilirary register number is 7136given via attribute argument. 7137 7138@end table 7139 7140@node AVR Variable Attributes 7141@subsection AVR Variable Attributes 7142 7143@table @code 7144@item progmem 7145@cindex @code{progmem} variable attribute, AVR 7146The @code{progmem} attribute is used on the AVR to place read-only 7147data in the non-volatile program memory (flash). The @code{progmem} 7148attribute accomplishes this by putting respective variables into a 7149section whose name starts with @code{.progmem}. 7150 7151This attribute works similar to the @code{section} attribute 7152but adds additional checking. 7153 7154@table @asis 7155@item @bullet{}@tie{} Ordinary AVR cores with 32 general purpose registers: 7156@code{progmem} affects the location 7157of the data but not how this data is accessed. 7158In order to read data located with the @code{progmem} attribute 7159(inline) assembler must be used. 7160@smallexample 7161/* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */ 7162#include <avr/pgmspace.h> 7163 7164/* Locate var in flash memory */ 7165const int var[2] PROGMEM = @{ 1, 2 @}; 7166 7167int read_var (int i) 7168@{ 7169 /* Access var[] by accessor macro from avr/pgmspace.h */ 7170 return (int) pgm_read_word (& var[i]); 7171@} 7172@end smallexample 7173 7174AVR is a Harvard architecture processor and data and read-only data 7175normally resides in the data memory (RAM). 7176 7177See also the @ref{AVR Named Address Spaces} section for 7178an alternate way to locate and access data in flash memory. 7179 7180@item @bullet{}@tie{} AVR cores with flash memory visible in the RAM address range: 7181On such devices, there is no need for attribute @code{progmem} or 7182@ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all. 7183Just use standard C / C++. The compiler will generate @code{LD*} 7184instructions. As flash memory is visible in the RAM address range, 7185and the default linker script does @emph{not} locate @code{.rodata} in 7186RAM, no special features are needed in order not to waste RAM for 7187read-only data or to read from flash. You might even get slightly better 7188performance by 7189avoiding @code{progmem} and @code{__flash}. This applies to devices from 7190families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for 7191an overview. 7192 7193@item @bullet{}@tie{}Reduced AVR Tiny cores like ATtiny40: 7194The compiler adds @code{0x4000} 7195to the addresses of objects and declarations in @code{progmem} and locates 7196the objects in flash memory, namely in section @code{.progmem.data}. 7197The offset is needed because the flash memory is visible in the RAM 7198address space starting at address @code{0x4000}. 7199 7200Data in @code{progmem} can be accessed by means of ordinary C@tie{}code, 7201no special functions or macros are needed. 7202 7203@smallexample 7204/* var is located in flash memory */ 7205extern const int var[2] __attribute__((progmem)); 7206 7207int read_var (int i) 7208@{ 7209 return var[i]; 7210@} 7211@end smallexample 7212 7213Please notice that on these devices, there is no need for @code{progmem} 7214at all. 7215 7216@end table 7217 7218@item io 7219@itemx io (@var{addr}) 7220@cindex @code{io} variable attribute, AVR 7221Variables with the @code{io} attribute are used to address 7222memory-mapped peripherals in the io address range. 7223If an address is specified, the variable 7224is assigned that address, and the value is interpreted as an 7225address in the data address space. 7226Example: 7227 7228@smallexample 7229volatile int porta __attribute__((io (0x22))); 7230@end smallexample 7231 7232The address specified in the address in the data address range. 7233 7234Otherwise, the variable it is not assigned an address, but the 7235compiler will still use in/out instructions where applicable, 7236assuming some other module assigns an address in the io address range. 7237Example: 7238 7239@smallexample 7240extern volatile int porta __attribute__((io)); 7241@end smallexample 7242 7243@item io_low 7244@itemx io_low (@var{addr}) 7245@cindex @code{io_low} variable attribute, AVR 7246This is like the @code{io} attribute, but additionally it informs the 7247compiler that the object lies in the lower half of the I/O area, 7248allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis} 7249instructions. 7250 7251@item address 7252@itemx address (@var{addr}) 7253@cindex @code{address} variable attribute, AVR 7254Variables with the @code{address} attribute are used to address 7255memory-mapped peripherals that may lie outside the io address range. 7256 7257@smallexample 7258volatile int porta __attribute__((address (0x600))); 7259@end smallexample 7260 7261@item absdata 7262@cindex @code{absdata} variable attribute, AVR 7263Variables in static storage and with the @code{absdata} attribute can 7264be accessed by the @code{LDS} and @code{STS} instructions which take 7265absolute addresses. 7266 7267@itemize @bullet 7268@item 7269This attribute is only supported for the reduced AVR Tiny core 7270like ATtiny40. 7271 7272@item 7273You must make sure that respective data is located in the 7274address range @code{0x40}@dots{}@code{0xbf} accessible by 7275@code{LDS} and @code{STS}. One way to achieve this as an 7276appropriate linker description file. 7277 7278@item 7279If the location does not fit the address range of @code{LDS} 7280and @code{STS}, there is currently (Binutils 2.26) just an unspecific 7281warning like 7282@quotation 7283@code{module.c:(.text+0x1c): warning: internal error: out of range error} 7284@end quotation 7285 7286@end itemize 7287 7288See also the @option{-mabsdata} @ref{AVR Options,command-line option}. 7289 7290@end table 7291 7292@node Blackfin Variable Attributes 7293@subsection Blackfin Variable Attributes 7294 7295Three attributes are currently defined for the Blackfin. 7296 7297@table @code 7298@item l1_data 7299@itemx l1_data_A 7300@itemx l1_data_B 7301@cindex @code{l1_data} variable attribute, Blackfin 7302@cindex @code{l1_data_A} variable attribute, Blackfin 7303@cindex @code{l1_data_B} variable attribute, Blackfin 7304Use these attributes on the Blackfin to place the variable into L1 Data SRAM. 7305Variables with @code{l1_data} attribute are put into the specific section 7306named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into 7307the specific section named @code{.l1.data.A}. Those with @code{l1_data_B} 7308attribute are put into the specific section named @code{.l1.data.B}. 7309 7310@item l2 7311@cindex @code{l2} variable attribute, Blackfin 7312Use this attribute on the Blackfin to place the variable into L2 SRAM. 7313Variables with @code{l2} attribute are put into the specific section 7314named @code{.l2.data}. 7315@end table 7316 7317@node H8/300 Variable Attributes 7318@subsection H8/300 Variable Attributes 7319 7320These variable attributes are available for H8/300 targets: 7321 7322@table @code 7323@item eightbit_data 7324@cindex @code{eightbit_data} variable attribute, H8/300 7325@cindex eight-bit data on the H8/300, H8/300H, and H8S 7326Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 7327variable should be placed into the eight-bit data section. 7328The compiler generates more efficient code for certain operations 7329on data in the eight-bit data area. Note the eight-bit data area is limited to 7330256 bytes of data. 7331 7332You must use GAS and GLD from GNU binutils version 2.7 or later for 7333this attribute to work correctly. 7334 7335@item tiny_data 7336@cindex @code{tiny_data} variable attribute, H8/300 7337@cindex tiny data section on the H8/300H and H8S 7338Use this attribute on the H8/300H and H8S to indicate that the specified 7339variable should be placed into the tiny data section. 7340The compiler generates more efficient code for loads and stores 7341on data in the tiny data section. Note the tiny data area is limited to 7342slightly under 32KB of data. 7343 7344@end table 7345 7346@node IA-64 Variable Attributes 7347@subsection IA-64 Variable Attributes 7348 7349The IA-64 back end supports the following variable attribute: 7350 7351@table @code 7352@item model (@var{model-name}) 7353@cindex @code{model} variable attribute, IA-64 7354 7355On IA-64, use this attribute to set the addressability of an object. 7356At present, the only supported identifier for @var{model-name} is 7357@code{small}, indicating addressability via ``small'' (22-bit) 7358addresses (so that their addresses can be loaded with the @code{addl} 7359instruction). Caveat: such addressing is by definition not position 7360independent and hence this attribute must not be used for objects 7361defined by shared libraries. 7362 7363@end table 7364 7365@node M32R/D Variable Attributes 7366@subsection M32R/D Variable Attributes 7367 7368One attribute is currently defined for the M32R/D@. 7369 7370@table @code 7371@item model (@var{model-name}) 7372@cindex @code{model-name} variable attribute, M32R/D 7373@cindex variable addressability on the M32R/D 7374Use this attribute on the M32R/D to set the addressability of an object. 7375The identifier @var{model-name} is one of @code{small}, @code{medium}, 7376or @code{large}, representing each of the code models. 7377 7378Small model objects live in the lower 16MB of memory (so that their 7379addresses can be loaded with the @code{ld24} instruction). 7380 7381Medium and large model objects may live anywhere in the 32-bit address space 7382(the compiler generates @code{seth/add3} instructions to load their 7383addresses). 7384@end table 7385 7386@node MeP Variable Attributes 7387@subsection MeP Variable Attributes 7388 7389The MeP target has a number of addressing modes and busses. The 7390@code{near} space spans the standard memory space's first 16 megabytes 7391(24 bits). The @code{far} space spans the entire 32-bit memory space. 7392The @code{based} space is a 128-byte region in the memory space that 7393is addressed relative to the @code{$tp} register. The @code{tiny} 7394space is a 65536-byte region relative to the @code{$gp} register. In 7395addition to these memory regions, the MeP target has a separate 16-bit 7396control bus which is specified with @code{cb} attributes. 7397 7398@table @code 7399 7400@item based 7401@cindex @code{based} variable attribute, MeP 7402Any variable with the @code{based} attribute is assigned to the 7403@code{.based} section, and is accessed with relative to the 7404@code{$tp} register. 7405 7406@item tiny 7407@cindex @code{tiny} variable attribute, MeP 7408Likewise, the @code{tiny} attribute assigned variables to the 7409@code{.tiny} section, relative to the @code{$gp} register. 7410 7411@item near 7412@cindex @code{near} variable attribute, MeP 7413Variables with the @code{near} attribute are assumed to have addresses 7414that fit in a 24-bit addressing mode. This is the default for large 7415variables (@code{-mtiny=4} is the default) but this attribute can 7416override @code{-mtiny=} for small variables, or override @code{-ml}. 7417 7418@item far 7419@cindex @code{far} variable attribute, MeP 7420Variables with the @code{far} attribute are addressed using a full 742132-bit address. Since this covers the entire memory space, this 7422allows modules to make no assumptions about where variables might be 7423stored. 7424 7425@item io 7426@cindex @code{io} variable attribute, MeP 7427@itemx io (@var{addr}) 7428Variables with the @code{io} attribute are used to address 7429memory-mapped peripherals. If an address is specified, the variable 7430is assigned that address, else it is not assigned an address (it is 7431assumed some other module assigns an address). Example: 7432 7433@smallexample 7434int timer_count __attribute__((io(0x123))); 7435@end smallexample 7436 7437@item cb 7438@itemx cb (@var{addr}) 7439@cindex @code{cb} variable attribute, MeP 7440Variables with the @code{cb} attribute are used to access the control 7441bus, using special instructions. @code{addr} indicates the control bus 7442address. Example: 7443 7444@smallexample 7445int cpu_clock __attribute__((cb(0x123))); 7446@end smallexample 7447 7448@end table 7449 7450@node Microsoft Windows Variable Attributes 7451@subsection Microsoft Windows Variable Attributes 7452 7453You can use these attributes on Microsoft Windows targets. 7454@ref{x86 Variable Attributes} for additional Windows compatibility 7455attributes available on all x86 targets. 7456 7457@table @code 7458@item dllimport 7459@itemx dllexport 7460@cindex @code{dllimport} variable attribute 7461@cindex @code{dllexport} variable attribute 7462The @code{dllimport} and @code{dllexport} attributes are described in 7463@ref{Microsoft Windows Function Attributes}. 7464 7465@item selectany 7466@cindex @code{selectany} variable attribute 7467The @code{selectany} attribute causes an initialized global variable to 7468have link-once semantics. When multiple definitions of the variable are 7469encountered by the linker, the first is selected and the remainder are 7470discarded. Following usage by the Microsoft compiler, the linker is told 7471@emph{not} to warn about size or content differences of the multiple 7472definitions. 7473 7474Although the primary usage of this attribute is for POD types, the 7475attribute can also be applied to global C++ objects that are initialized 7476by a constructor. In this case, the static initialization and destruction 7477code for the object is emitted in each translation defining the object, 7478but the calls to the constructor and destructor are protected by a 7479link-once guard variable. 7480 7481The @code{selectany} attribute is only available on Microsoft Windows 7482targets. You can use @code{__declspec (selectany)} as a synonym for 7483@code{__attribute__ ((selectany))} for compatibility with other 7484compilers. 7485 7486@item shared 7487@cindex @code{shared} variable attribute 7488On Microsoft Windows, in addition to putting variable definitions in a named 7489section, the section can also be shared among all running copies of an 7490executable or DLL@. For example, this small program defines shared data 7491by putting it in a named section @code{shared} and marking the section 7492shareable: 7493 7494@smallexample 7495int foo __attribute__((section ("shared"), shared)) = 0; 7496 7497int 7498main() 7499@{ 7500 /* @r{Read and write foo. All running 7501 copies see the same value.} */ 7502 return 0; 7503@} 7504@end smallexample 7505 7506@noindent 7507You may only use the @code{shared} attribute along with @code{section} 7508attribute with a fully-initialized global definition because of the way 7509linkers work. See @code{section} attribute for more information. 7510 7511The @code{shared} attribute is only available on Microsoft Windows@. 7512 7513@end table 7514 7515@node MSP430 Variable Attributes 7516@subsection MSP430 Variable Attributes 7517 7518@table @code 7519@item noinit 7520@cindex @code{noinit} variable attribute, MSP430 7521Any data with the @code{noinit} attribute will not be initialised by 7522the C runtime startup code, or the program loader. Not initialising 7523data in this way can reduce program startup times. 7524 7525@item persistent 7526@cindex @code{persistent} variable attribute, MSP430 7527Any variable with the @code{persistent} attribute will not be 7528initialised by the C runtime startup code. Instead its value will be 7529set once, when the application is loaded, and then never initialised 7530again, even if the processor is reset or the program restarts. 7531Persistent data is intended to be placed into FLASH RAM, where its 7532value will be retained across resets. The linker script being used to 7533create the application should ensure that persistent data is correctly 7534placed. 7535 7536@item lower 7537@itemx upper 7538@itemx either 7539@cindex @code{lower} variable attribute, MSP430 7540@cindex @code{upper} variable attribute, MSP430 7541@cindex @code{either} variable attribute, MSP430 7542These attributes are the same as the MSP430 function attributes of the 7543same name (@pxref{MSP430 Function Attributes}). 7544These attributes can be applied to both functions and variables. 7545@end table 7546 7547@node Nvidia PTX Variable Attributes 7548@subsection Nvidia PTX Variable Attributes 7549 7550These variable attributes are supported by the Nvidia PTX back end: 7551 7552@table @code 7553@item shared 7554@cindex @code{shared} attribute, Nvidia PTX 7555Use this attribute to place a variable in the @code{.shared} memory space. 7556This memory space is private to each cooperative thread array; only threads 7557within one thread block refer to the same instance of the variable. 7558The runtime does not initialize variables in this memory space. 7559@end table 7560 7561@node PowerPC Variable Attributes 7562@subsection PowerPC Variable Attributes 7563 7564Three attributes currently are defined for PowerPC configurations: 7565@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 7566 7567@cindex @code{ms_struct} variable attribute, PowerPC 7568@cindex @code{gcc_struct} variable attribute, PowerPC 7569For full documentation of the struct attributes please see the 7570documentation in @ref{x86 Variable Attributes}. 7571 7572@cindex @code{altivec} variable attribute, PowerPC 7573For documentation of @code{altivec} attribute please see the 7574documentation in @ref{PowerPC Type Attributes}. 7575 7576@node RL78 Variable Attributes 7577@subsection RL78 Variable Attributes 7578 7579@cindex @code{saddr} variable attribute, RL78 7580The RL78 back end supports the @code{saddr} variable attribute. This 7581specifies placement of the corresponding variable in the SADDR area, 7582which can be accessed more efficiently than the default memory region. 7583 7584@node SPU Variable Attributes 7585@subsection SPU Variable Attributes 7586 7587@cindex @code{spu_vector} variable attribute, SPU 7588The SPU supports the @code{spu_vector} attribute for variables. For 7589documentation of this attribute please see the documentation in 7590@ref{SPU Type Attributes}. 7591 7592@node V850 Variable Attributes 7593@subsection V850 Variable Attributes 7594 7595These variable attributes are supported by the V850 back end: 7596 7597@table @code 7598 7599@item sda 7600@cindex @code{sda} variable attribute, V850 7601Use this attribute to explicitly place a variable in the small data area, 7602which can hold up to 64 kilobytes. 7603 7604@item tda 7605@cindex @code{tda} variable attribute, V850 7606Use this attribute to explicitly place a variable in the tiny data area, 7607which can hold up to 256 bytes in total. 7608 7609@item zda 7610@cindex @code{zda} variable attribute, V850 7611Use this attribute to explicitly place a variable in the first 32 kilobytes 7612of memory. 7613@end table 7614 7615@node x86 Variable Attributes 7616@subsection x86 Variable Attributes 7617 7618Two attributes are currently defined for x86 configurations: 7619@code{ms_struct} and @code{gcc_struct}. 7620 7621@table @code 7622@item ms_struct 7623@itemx gcc_struct 7624@cindex @code{ms_struct} variable attribute, x86 7625@cindex @code{gcc_struct} variable attribute, x86 7626 7627If @code{packed} is used on a structure, or if bit-fields are used, 7628it may be that the Microsoft ABI lays out the structure differently 7629than the way GCC normally does. Particularly when moving packed 7630data between functions compiled with GCC and the native Microsoft compiler 7631(either via function call or as data in a file), it may be necessary to access 7632either format. 7633 7634The @code{ms_struct} and @code{gcc_struct} attributes correspond 7635to the @option{-mms-bitfields} and @option{-mno-ms-bitfields} 7636command-line options, respectively; 7637see @ref{x86 Options}, for details of how structure layout is affected. 7638@xref{x86 Type Attributes}, for information about the corresponding 7639attributes on types. 7640 7641@end table 7642 7643@node Xstormy16 Variable Attributes 7644@subsection Xstormy16 Variable Attributes 7645 7646One attribute is currently defined for xstormy16 configurations: 7647@code{below100}. 7648 7649@table @code 7650@item below100 7651@cindex @code{below100} variable attribute, Xstormy16 7652 7653If a variable has the @code{below100} attribute (@code{BELOW100} is 7654allowed also), GCC places the variable in the first 0x100 bytes of 7655memory and use special opcodes to access it. Such variables are 7656placed in either the @code{.bss_below100} section or the 7657@code{.data_below100} section. 7658 7659@end table 7660 7661@node Type Attributes 7662@section Specifying Attributes of Types 7663@cindex attribute of types 7664@cindex type attributes 7665 7666The keyword @code{__attribute__} allows you to specify various special 7667properties of types. Some type attributes apply only to structure and 7668union types, and in C++, also class types, while others can apply to 7669any type defined via a @code{typedef} declaration. Unless otherwise 7670specified, the same restrictions and effects apply to attributes regardless 7671of whether a type is a trivial structure or a C++ class with user-defined 7672constructors, destructors, or a copy assignment. 7673 7674Other attributes are defined for functions (@pxref{Function Attributes}), 7675labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator 7676Attributes}), statements (@pxref{Statement Attributes}), and for variables 7677(@pxref{Variable Attributes}). 7678 7679The @code{__attribute__} keyword is followed by an attribute specification 7680enclosed in double parentheses. 7681 7682You may specify type attributes in an enum, struct or union type 7683declaration or definition by placing them immediately after the 7684@code{struct}, @code{union} or @code{enum} keyword. You can also place 7685them just past the closing curly brace of the definition, but this is less 7686preferred because logically the type should be fully defined at 7687the closing brace. 7688 7689You can also include type attributes in a @code{typedef} declaration. 7690@xref{Attribute Syntax}, for details of the exact syntax for using 7691attributes. 7692 7693@menu 7694* Common Type Attributes:: 7695* ARC Type Attributes:: 7696* ARM Type Attributes:: 7697* MeP Type Attributes:: 7698* PowerPC Type Attributes:: 7699* SPU Type Attributes:: 7700* x86 Type Attributes:: 7701@end menu 7702 7703@node Common Type Attributes 7704@subsection Common Type Attributes 7705 7706The following type attributes are supported on most targets. 7707 7708@table @code 7709@cindex @code{aligned} type attribute 7710@item aligned 7711@itemx aligned (@var{alignment}) 7712The @code{aligned} attribute specifies a minimum alignment (in bytes) for 7713variables of the specified type. When specified, @var{alignment} must be 7714a power of 2. Specifying no @var{alignment} argument implies the maximum 7715alignment for the target, which is often, but by no means always, 8 or 16 7716bytes. For example, the declarations: 7717 7718@smallexample 7719struct __attribute__ ((aligned (8))) S @{ short f[3]; @}; 7720typedef int more_aligned_int __attribute__ ((aligned (8))); 7721@end smallexample 7722 7723@noindent 7724force the compiler to ensure (as far as it can) that each variable whose 7725type is @code{struct S} or @code{more_aligned_int} is allocated and 7726aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all 7727variables of type @code{struct S} aligned to 8-byte boundaries allows 7728the compiler to use the @code{ldd} and @code{std} (doubleword load and 7729store) instructions when copying one variable of type @code{struct S} to 7730another, thus improving run-time efficiency. 7731 7732Note that the alignment of any given @code{struct} or @code{union} type 7733is required by the ISO C standard to be at least a perfect multiple of 7734the lowest common multiple of the alignments of all of the members of 7735the @code{struct} or @code{union} in question. This means that you @emph{can} 7736effectively adjust the alignment of a @code{struct} or @code{union} 7737type by attaching an @code{aligned} attribute to any one of the members 7738of such a type, but the notation illustrated in the example above is a 7739more obvious, intuitive, and readable way to request the compiler to 7740adjust the alignment of an entire @code{struct} or @code{union} type. 7741 7742As in the preceding example, you can explicitly specify the alignment 7743(in bytes) that you wish the compiler to use for a given @code{struct} 7744or @code{union} type. Alternatively, you can leave out the alignment factor 7745and just ask the compiler to align a type to the maximum 7746useful alignment for the target machine you are compiling for. For 7747example, you could write: 7748 7749@smallexample 7750struct __attribute__ ((aligned)) S @{ short f[3]; @}; 7751@end smallexample 7752 7753Whenever you leave out the alignment factor in an @code{aligned} 7754attribute specification, the compiler automatically sets the alignment 7755for the type to the largest alignment that is ever used for any data 7756type on the target machine you are compiling for. Doing this can often 7757make copy operations more efficient, because the compiler can use 7758whatever instructions copy the biggest chunks of memory when performing 7759copies to or from the variables that have types that you have aligned 7760this way. 7761 7762In the example above, if the size of each @code{short} is 2 bytes, then 7763the size of the entire @code{struct S} type is 6 bytes. The smallest 7764power of two that is greater than or equal to that is 8, so the 7765compiler sets the alignment for the entire @code{struct S} type to 8 7766bytes. 7767 7768Note that although you can ask the compiler to select a time-efficient 7769alignment for a given type and then declare only individual stand-alone 7770objects of that type, the compiler's ability to select a time-efficient 7771alignment is primarily useful only when you plan to create arrays of 7772variables having the relevant (efficiently aligned) type. If you 7773declare or use arrays of variables of an efficiently-aligned type, then 7774it is likely that your program also does pointer arithmetic (or 7775subscripting, which amounts to the same thing) on pointers to the 7776relevant type, and the code that the compiler generates for these 7777pointer arithmetic operations is often more efficient for 7778efficiently-aligned types than for other types. 7779 7780Note that the effectiveness of @code{aligned} attributes may be limited 7781by inherent limitations in your linker. On many systems, the linker is 7782only able to arrange for variables to be aligned up to a certain maximum 7783alignment. (For some linkers, the maximum supported alignment may 7784be very very small.) If your linker is only able to align variables 7785up to a maximum of 8-byte alignment, then specifying @code{aligned (16)} 7786in an @code{__attribute__} still only provides you with 8-byte 7787alignment. See your linker documentation for further information. 7788 7789When used on a struct, or struct member, the @code{aligned} attribute can 7790only increase the alignment; in order to decrease it, the @code{packed} 7791attribute must be specified as well. When used as part of a typedef, the 7792@code{aligned} attribute can both increase and decrease alignment, and 7793specifying the @code{packed} attribute generates a warning. 7794 7795@cindex @code{warn_if_not_aligned} type attribute 7796@item warn_if_not_aligned (@var{alignment}) 7797This attribute specifies a threshold for the structure field, measured 7798in bytes. If the structure field is aligned below the threshold, a 7799warning will be issued. For example, the declaration: 7800 7801@smallexample 7802typedef unsigned long long __u64 7803 __attribute__((aligned (4), warn_if_not_aligned (8))); 7804 7805struct foo 7806@{ 7807 int i1; 7808 int i2; 7809 __u64 x; 7810@}; 7811@end smallexample 7812 7813@noindent 7814causes the compiler to issue an warning on @code{struct foo}, like 7815@samp{warning: alignment 4 of 'struct foo' is less than 8}. 7816It is used to define @code{struct foo} in such a way that 7817@code{struct foo} has the same layout and the structure field @code{x} 7818has the same alignment when @code{__u64} is aligned at either 4 or 78198 bytes. Align @code{struct foo} to 8 bytes: 7820 7821@smallexample 7822struct __attribute__ ((aligned (8))) foo 7823@{ 7824 int i1; 7825 int i2; 7826 __u64 x; 7827@}; 7828@end smallexample 7829 7830@noindent 7831silences the warning. The compiler also issues a warning, like 7832@samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8}, 7833when the structure field has the misaligned offset: 7834 7835@smallexample 7836struct __attribute__ ((aligned (8))) foo 7837@{ 7838 int i1; 7839 int i2; 7840 int i3; 7841 __u64 x; 7842@}; 7843@end smallexample 7844 7845This warning can be disabled by @option{-Wno-if-not-aligned}. 7846 7847@item alloc_size (@var{position}) 7848@itemx alloc_size (@var{position-1}, @var{position-2}) 7849@cindex @code{alloc_size} type attribute 7850The @code{alloc_size} type attribute may be applied to the definition 7851of a type of a function that returns a pointer and takes at least one 7852argument of an integer type. It indicates that the returned pointer 7853points to an object whose size is given by the function argument at 7854@var{position-1}, or by the product of the arguments at @var{position-1} 7855and @var{position-2}. Meaningful sizes are positive values less than 7856@code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses 7857this information to improve the results of @code{__builtin_object_size}. 7858 7859For instance, the following declarations 7860 7861@smallexample 7862typedef __attribute__ ((alloc_size (1, 2))) void* 7863 calloc_type (size_t, size_t); 7864typedef __attribute__ ((alloc_size (1))) void* 7865 malloc_type (size_t); 7866@end smallexample 7867 7868@noindent 7869specify that @code{calloc_type} is a type of a function that, like 7870the standard C function @code{calloc}, returns an object whose size 7871is given by the product of arguments 1 and 2, and that 7872@code{malloc_type}, like the standard C function @code{malloc}, 7873returns an object whose size is given by argument 1 to the function. 7874 7875@item copy 7876@itemx copy (@var{expression}) 7877@cindex @code{copy} type attribute 7878The @code{copy} attribute applies the set of attributes with which 7879the type of the @var{expression} has been declared to the declaration 7880of the type to which the attribute is applied. The attribute is 7881designed for libraries that define aliases that are expected to 7882specify the same set of attributes as the aliased symbols. 7883The @code{copy} attribute can be used with types, variables, or 7884functions. However, the kind of symbol to which the attribute is 7885applied (either varible or function) must match the kind of symbol 7886to which the argument refers. 7887The @code{copy} attribute copies only syntactic and semantic attributes 7888but not attributes that affect a symbol's linkage or visibility such as 7889@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} 7890attribute is also not copied. @xref{Common Function Attributes}. 7891@xref{Common Variable Attributes}. 7892 7893For example, suppose @code{struct A} below is defined in some third 7894party library header to have the alignment requirement @code{N} and 7895to force a warning whenever a variable of the type is not so aligned 7896due to attribute @code{packed}. Specifying the @code{copy} attribute 7897on the definition on the unrelated @code{struct B} has the effect of 7898copying all relevant attributes from the type referenced by the pointer 7899expression to @code{struct B}. 7900 7901@smallexample 7902struct __attribute__ ((aligned (N), warn_if_not_aligned (N))) 7903A @{ /* @r{@dots{}} */ @}; 7904struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @}; 7905@end smallexample 7906 7907@item deprecated 7908@itemx deprecated (@var{msg}) 7909@cindex @code{deprecated} type attribute 7910The @code{deprecated} attribute results in a warning if the type 7911is used anywhere in the source file. This is useful when identifying 7912types that are expected to be removed in a future version of a program. 7913If possible, the warning also includes the location of the declaration 7914of the deprecated type, to enable users to easily find further 7915information about why the type is deprecated, or what they should do 7916instead. Note that the warnings only occur for uses and then only 7917if the type is being applied to an identifier that itself is not being 7918declared as deprecated. 7919 7920@smallexample 7921typedef int T1 __attribute__ ((deprecated)); 7922T1 x; 7923typedef T1 T2; 7924T2 y; 7925typedef T1 T3 __attribute__ ((deprecated)); 7926T3 z __attribute__ ((deprecated)); 7927@end smallexample 7928 7929@noindent 7930results in a warning on line 2 and 3 but not lines 4, 5, or 6. No 7931warning is issued for line 4 because T2 is not explicitly 7932deprecated. Line 5 has no warning because T3 is explicitly 7933deprecated. Similarly for line 6. The optional @var{msg} 7934argument, which must be a string, is printed in the warning if 7935present. Control characters in the string will be replaced with 7936escape sequences, and if the @option{-fmessage-length} option is set 7937to 0 (its default value) then any newline characters will be ignored. 7938 7939The @code{deprecated} attribute can also be used for functions and 7940variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) 7941 7942The message attached to the attribute is affected by the setting of 7943the @option{-fmessage-length} option. 7944 7945@item designated_init 7946@cindex @code{designated_init} type attribute 7947This attribute may only be applied to structure types. It indicates 7948that any initialization of an object of this type must use designated 7949initializers rather than positional initializers. The intent of this 7950attribute is to allow the programmer to indicate that a structure's 7951layout may change, and that therefore relying on positional 7952initialization will result in future breakage. 7953 7954GCC emits warnings based on this attribute by default; use 7955@option{-Wno-designated-init} to suppress them. 7956 7957@item may_alias 7958@cindex @code{may_alias} type attribute 7959Accesses through pointers to types with this attribute are not subject 7960to type-based alias analysis, but are instead assumed to be able to alias 7961any other type of objects. 7962In the context of section 6.5 paragraph 7 of the C99 standard, 7963an lvalue expression 7964dereferencing such a pointer is treated like having a character type. 7965See @option{-fstrict-aliasing} for more information on aliasing issues. 7966This extension exists to support some vector APIs, in which pointers to 7967one vector type are permitted to alias pointers to a different vector type. 7968 7969Note that an object of a type with this attribute does not have any 7970special semantics. 7971 7972Example of use: 7973 7974@smallexample 7975typedef short __attribute__ ((__may_alias__)) short_a; 7976 7977int 7978main (void) 7979@{ 7980 int a = 0x12345678; 7981 short_a *b = (short_a *) &a; 7982 7983 b[1] = 0; 7984 7985 if (a == 0x12345678) 7986 abort(); 7987 7988 exit(0); 7989@} 7990@end smallexample 7991 7992@noindent 7993If you replaced @code{short_a} with @code{short} in the variable 7994declaration, the above program would abort when compiled with 7995@option{-fstrict-aliasing}, which is on by default at @option{-O2} or 7996above. 7997 7998@item mode (@var{mode}) 7999@cindex @code{mode} type attribute 8000This attribute specifies the data type for the declaration---whichever 8001type corresponds to the mode @var{mode}. This in effect lets you 8002request an integer or floating-point type according to its width. 8003 8004@xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals}, 8005for a list of the possible keywords for @var{mode}. 8006You may also specify a mode of @code{byte} or @code{__byte__} to 8007indicate the mode corresponding to a one-byte integer, @code{word} or 8008@code{__word__} for the mode of a one-word integer, and @code{pointer} 8009or @code{__pointer__} for the mode used to represent pointers. 8010 8011@item packed 8012@cindex @code{packed} type attribute 8013This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class} 8014type definition, specifies that each of its members (other than zero-width 8015bit-fields) is placed to minimize the memory required. This is equivalent 8016to specifying the @code{packed} attribute on each of the members. 8017 8018@opindex fshort-enums 8019When attached to an @code{enum} definition, the @code{packed} attribute 8020indicates that the smallest integral type should be used. 8021Specifying the @option{-fshort-enums} flag on the command line 8022is equivalent to specifying the @code{packed} 8023attribute on all @code{enum} definitions. 8024 8025In the following example @code{struct my_packed_struct}'s members are 8026packed closely together, but the internal layout of its @code{s} member 8027is not packed---to do that, @code{struct my_unpacked_struct} needs to 8028be packed too. 8029 8030@smallexample 8031struct my_unpacked_struct 8032 @{ 8033 char c; 8034 int i; 8035 @}; 8036 8037struct __attribute__ ((__packed__)) my_packed_struct 8038 @{ 8039 char c; 8040 int i; 8041 struct my_unpacked_struct s; 8042 @}; 8043@end smallexample 8044 8045You may only specify the @code{packed} attribute on the definition 8046of an @code{enum}, @code{struct}, @code{union}, or @code{class}, 8047not on a @code{typedef} that does not also define the enumerated type, 8048structure, union, or class. 8049 8050@item scalar_storage_order ("@var{endianness}") 8051@cindex @code{scalar_storage_order} type attribute 8052When attached to a @code{union} or a @code{struct}, this attribute sets 8053the storage order, aka endianness, of the scalar fields of the type, as 8054well as the array fields whose component is scalar. The supported 8055endiannesses are @code{big-endian} and @code{little-endian}. The attribute 8056has no effects on fields which are themselves a @code{union}, a @code{struct} 8057or an array whose component is a @code{union} or a @code{struct}, and it is 8058possible for these fields to have a different scalar storage order than the 8059enclosing type. 8060 8061This attribute is supported only for targets that use a uniform default 8062scalar storage order (fortunately, most of them), i.e.@: targets that store 8063the scalars either all in big-endian or all in little-endian. 8064 8065Additional restrictions are enforced for types with the reverse scalar 8066storage order with regard to the scalar storage order of the target: 8067 8068@itemize 8069@item Taking the address of a scalar field of a @code{union} or a 8070@code{struct} with reverse scalar storage order is not permitted and yields 8071an error. 8072@item Taking the address of an array field, whose component is scalar, of 8073a @code{union} or a @code{struct} with reverse scalar storage order is 8074permitted but yields a warning, unless @option{-Wno-scalar-storage-order} 8075is specified. 8076@item Taking the address of a @code{union} or a @code{struct} with reverse 8077scalar storage order is permitted. 8078@end itemize 8079 8080These restrictions exist because the storage order attribute is lost when 8081the address of a scalar or the address of an array with scalar component is 8082taken, so storing indirectly through this address generally does not work. 8083The second case is nevertheless allowed to be able to perform a block copy 8084from or to the array. 8085 8086Moreover, the use of type punning or aliasing to toggle the storage order 8087is not supported; that is to say, a given scalar object cannot be accessed 8088through distinct types that assign a different storage order to it. 8089 8090@item transparent_union 8091@cindex @code{transparent_union} type attribute 8092 8093This attribute, attached to a @code{union} type definition, indicates 8094that any function parameter having that union type causes calls to that 8095function to be treated in a special way. 8096 8097First, the argument corresponding to a transparent union type can be of 8098any type in the union; no cast is required. Also, if the union contains 8099a pointer type, the corresponding argument can be a null pointer 8100constant or a void pointer expression; and if the union contains a void 8101pointer type, the corresponding argument can be any pointer expression. 8102If the union member type is a pointer, qualifiers like @code{const} on 8103the referenced type must be respected, just as with normal pointer 8104conversions. 8105 8106Second, the argument is passed to the function using the calling 8107conventions of the first member of the transparent union, not the calling 8108conventions of the union itself. All members of the union must have the 8109same machine representation; this is necessary for this argument passing 8110to work properly. 8111 8112Transparent unions are designed for library functions that have multiple 8113interfaces for compatibility reasons. For example, suppose the 8114@code{wait} function must accept either a value of type @code{int *} to 8115comply with POSIX, or a value of type @code{union wait *} to comply with 8116the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, 8117@code{wait} would accept both kinds of arguments, but it would also 8118accept any other pointer type and this would make argument type checking 8119less useful. Instead, @code{<sys/wait.h>} might define the interface 8120as follows: 8121 8122@smallexample 8123typedef union __attribute__ ((__transparent_union__)) 8124 @{ 8125 int *__ip; 8126 union wait *__up; 8127 @} wait_status_ptr_t; 8128 8129pid_t wait (wait_status_ptr_t); 8130@end smallexample 8131 8132@noindent 8133This interface allows either @code{int *} or @code{union wait *} 8134arguments to be passed, using the @code{int *} calling convention. 8135The program can call @code{wait} with arguments of either type: 8136 8137@smallexample 8138int w1 () @{ int w; return wait (&w); @} 8139int w2 () @{ union wait w; return wait (&w); @} 8140@end smallexample 8141 8142@noindent 8143With this interface, @code{wait}'s implementation might look like this: 8144 8145@smallexample 8146pid_t wait (wait_status_ptr_t p) 8147@{ 8148 return waitpid (-1, p.__ip, 0); 8149@} 8150@end smallexample 8151 8152@item unused 8153@cindex @code{unused} type attribute 8154When attached to a type (including a @code{union} or a @code{struct}), 8155this attribute means that variables of that type are meant to appear 8156possibly unused. GCC does not produce a warning for any variables of 8157that type, even if the variable appears to do nothing. This is often 8158the case with lock or thread classes, which are usually defined and then 8159not referenced, but contain constructors and destructors that have 8160nontrivial bookkeeping functions. 8161 8162@item vector_size (@var{bytes}) 8163@cindex @code{vector_size} type attribute 8164This attribute specifies the vector size for the type, measured in bytes. 8165The type to which it applies is known as the @dfn{base type}. The @var{bytes} 8166argument must be a positive power-of-two multiple of the base type size. For 8167example, the following declarations: 8168 8169@smallexample 8170typedef __attribute__ ((vector_size (32))) int int_vec32_t ; 8171typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t; 8172typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3]; 8173@end smallexample 8174 8175@noindent 8176define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int} 8177sized units. With @code{int} having a size of 4 bytes, the type defines 8178a vector of eight units, four bytes each. The mode of variables of type 8179@code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined 8180to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be 8181an array of three such vectors. @xref{Vector Extensions} for details of 8182manipulating objects of vector types. 8183 8184This attribute is only applicable to integral and floating scalar types. 8185In function declarations the attribute applies to the function return 8186type. 8187 8188For example, the following: 8189@smallexample 8190__attribute__ ((vector_size (16))) float get_flt_vec16 (void); 8191@end smallexample 8192declares @code{get_flt_vec16} to be a function returning a 16-byte vector 8193with the base type @code{float}. 8194 8195@item visibility 8196@cindex @code{visibility} type attribute 8197In C++, attribute visibility (@pxref{Function Attributes}) can also be 8198applied to class, struct, union and enum types. Unlike other type 8199attributes, the attribute must appear between the initial keyword and 8200the name of the type; it cannot appear after the body of the type. 8201 8202Note that the type visibility is applied to vague linkage entities 8203associated with the class (vtable, typeinfo node, etc.). In 8204particular, if a class is thrown as an exception in one shared object 8205and caught in another, the class must have default visibility. 8206Otherwise the two shared objects are unable to use the same 8207typeinfo node and exception handling will break. 8208 8209@end table 8210 8211To specify multiple attributes, separate them by commas within the 8212double parentheses: for example, @samp{__attribute__ ((aligned (16), 8213packed))}. 8214 8215@node ARC Type Attributes 8216@subsection ARC Type Attributes 8217 8218@cindex @code{uncached} type attribute, ARC 8219Declaring objects with @code{uncached} allows you to exclude 8220data-cache participation in load and store operations on those objects 8221without involving the additional semantic implications of 8222@code{volatile}. The @code{.di} instruction suffix is used for all 8223loads and stores of data declared @code{uncached}. 8224 8225@node ARM Type Attributes 8226@subsection ARM Type Attributes 8227 8228@cindex @code{notshared} type attribute, ARM 8229On those ARM targets that support @code{dllimport} (such as Symbian 8230OS), you can use the @code{notshared} attribute to indicate that the 8231virtual table and other similar data for a class should not be 8232exported from a DLL@. For example: 8233 8234@smallexample 8235class __declspec(notshared) C @{ 8236public: 8237 __declspec(dllimport) C(); 8238 virtual void f(); 8239@} 8240 8241__declspec(dllexport) 8242C::C() @{@} 8243@end smallexample 8244 8245@noindent 8246In this code, @code{C::C} is exported from the current DLL, but the 8247virtual table for @code{C} is not exported. (You can use 8248@code{__attribute__} instead of @code{__declspec} if you prefer, but 8249most Symbian OS code uses @code{__declspec}.) 8250 8251@node MeP Type Attributes 8252@subsection MeP Type Attributes 8253 8254@cindex @code{based} type attribute, MeP 8255@cindex @code{tiny} type attribute, MeP 8256@cindex @code{near} type attribute, MeP 8257@cindex @code{far} type attribute, MeP 8258Many of the MeP variable attributes may be applied to types as well. 8259Specifically, the @code{based}, @code{tiny}, @code{near}, and 8260@code{far} attributes may be applied to either. The @code{io} and 8261@code{cb} attributes may not be applied to types. 8262 8263@node PowerPC Type Attributes 8264@subsection PowerPC Type Attributes 8265 8266Three attributes currently are defined for PowerPC configurations: 8267@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 8268 8269@cindex @code{ms_struct} type attribute, PowerPC 8270@cindex @code{gcc_struct} type attribute, PowerPC 8271For full documentation of the @code{ms_struct} and @code{gcc_struct} 8272attributes please see the documentation in @ref{x86 Type Attributes}. 8273 8274@cindex @code{altivec} type attribute, PowerPC 8275The @code{altivec} attribute allows one to declare AltiVec vector data 8276types supported by the AltiVec Programming Interface Manual. The 8277attribute requires an argument to specify one of three vector types: 8278@code{vector__}, @code{pixel__} (always followed by unsigned short), 8279and @code{bool__} (always followed by unsigned). 8280 8281@smallexample 8282__attribute__((altivec(vector__))) 8283__attribute__((altivec(pixel__))) unsigned short 8284__attribute__((altivec(bool__))) unsigned 8285@end smallexample 8286 8287These attributes mainly are intended to support the @code{__vector}, 8288@code{__pixel}, and @code{__bool} AltiVec keywords. 8289 8290@node SPU Type Attributes 8291@subsection SPU Type Attributes 8292 8293@cindex @code{spu_vector} type attribute, SPU 8294The SPU supports the @code{spu_vector} attribute for types. This attribute 8295allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU 8296Language Extensions Specification. It is intended to support the 8297@code{__vector} keyword. 8298 8299@node x86 Type Attributes 8300@subsection x86 Type Attributes 8301 8302Two attributes are currently defined for x86 configurations: 8303@code{ms_struct} and @code{gcc_struct}. 8304 8305@table @code 8306 8307@item ms_struct 8308@itemx gcc_struct 8309@cindex @code{ms_struct} type attribute, x86 8310@cindex @code{gcc_struct} type attribute, x86 8311 8312If @code{packed} is used on a structure, or if bit-fields are used 8313it may be that the Microsoft ABI packs them differently 8314than GCC normally packs them. Particularly when moving packed 8315data between functions compiled with GCC and the native Microsoft compiler 8316(either via function call or as data in a file), it may be necessary to access 8317either format. 8318 8319The @code{ms_struct} and @code{gcc_struct} attributes correspond 8320to the @option{-mms-bitfields} and @option{-mno-ms-bitfields} 8321command-line options, respectively; 8322see @ref{x86 Options}, for details of how structure layout is affected. 8323@xref{x86 Variable Attributes}, for information about the corresponding 8324attributes on variables. 8325 8326@end table 8327 8328@node Label Attributes 8329@section Label Attributes 8330@cindex Label Attributes 8331 8332GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for 8333details of the exact syntax for using attributes. Other attributes are 8334available for functions (@pxref{Function Attributes}), variables 8335(@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}), 8336statements (@pxref{Statement Attributes}), and for types 8337(@pxref{Type Attributes}). 8338 8339This example uses the @code{cold} label attribute to indicate the 8340@code{ErrorHandling} branch is unlikely to be taken and that the 8341@code{ErrorHandling} label is unused: 8342 8343@smallexample 8344 8345 asm goto ("some asm" : : : : NoError); 8346 8347/* This branch (the fall-through from the asm) is less commonly used */ 8348ErrorHandling: 8349 __attribute__((cold, unused)); /* Semi-colon is required here */ 8350 printf("error\n"); 8351 return 0; 8352 8353NoError: 8354 printf("no error\n"); 8355 return 1; 8356@end smallexample 8357 8358@table @code 8359@item unused 8360@cindex @code{unused} label attribute 8361This feature is intended for program-generated code that may contain 8362unused labels, but which is compiled with @option{-Wall}. It is 8363not normally appropriate to use in it human-written code, though it 8364could be useful in cases where the code that jumps to the label is 8365contained within an @code{#ifdef} conditional. 8366 8367@item hot 8368@cindex @code{hot} label attribute 8369The @code{hot} attribute on a label is used to inform the compiler that 8370the path following the label is more likely than paths that are not so 8371annotated. This attribute is used in cases where @code{__builtin_expect} 8372cannot be used, for instance with computed goto or @code{asm goto}. 8373 8374@item cold 8375@cindex @code{cold} label attribute 8376The @code{cold} attribute on labels is used to inform the compiler that 8377the path following the label is unlikely to be executed. This attribute 8378is used in cases where @code{__builtin_expect} cannot be used, for instance 8379with computed goto or @code{asm goto}. 8380 8381@end table 8382 8383@node Enumerator Attributes 8384@section Enumerator Attributes 8385@cindex Enumerator Attributes 8386 8387GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for 8388details of the exact syntax for using attributes. Other attributes are 8389available for functions (@pxref{Function Attributes}), variables 8390(@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements 8391(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}). 8392 8393This example uses the @code{deprecated} enumerator attribute to indicate the 8394@code{oldval} enumerator is deprecated: 8395 8396@smallexample 8397enum E @{ 8398 oldval __attribute__((deprecated)), 8399 newval 8400@}; 8401 8402int 8403fn (void) 8404@{ 8405 return oldval; 8406@} 8407@end smallexample 8408 8409@table @code 8410@item deprecated 8411@cindex @code{deprecated} enumerator attribute 8412The @code{deprecated} attribute results in a warning if the enumerator 8413is used anywhere in the source file. This is useful when identifying 8414enumerators that are expected to be removed in a future version of a 8415program. The warning also includes the location of the declaration 8416of the deprecated enumerator, to enable users to easily find further 8417information about why the enumerator is deprecated, or what they should 8418do instead. Note that the warnings only occurs for uses. 8419 8420@end table 8421 8422@node Statement Attributes 8423@section Statement Attributes 8424@cindex Statement Attributes 8425 8426GCC allows attributes to be set on null statements. @xref{Attribute Syntax}, 8427for details of the exact syntax for using attributes. Other attributes are 8428available for functions (@pxref{Function Attributes}), variables 8429(@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators 8430(@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}). 8431 8432This example uses the @code{fallthrough} statement attribute to indicate that 8433the @option{-Wimplicit-fallthrough} warning should not be emitted: 8434 8435@smallexample 8436switch (cond) 8437 @{ 8438 case 1: 8439 bar (1); 8440 __attribute__((fallthrough)); 8441 case 2: 8442 @dots{} 8443 @} 8444@end smallexample 8445 8446@table @code 8447@item fallthrough 8448@cindex @code{fallthrough} statement attribute 8449The @code{fallthrough} attribute with a null statement serves as a 8450fallthrough statement. It hints to the compiler that a statement 8451that falls through to another case label, or user-defined label 8452in a switch statement is intentional and thus the 8453@option{-Wimplicit-fallthrough} warning must not trigger. The 8454fallthrough attribute may appear at most once in each attribute 8455list, and may not be mixed with other attributes. It can only 8456be used in a switch statement (the compiler will issue an error 8457otherwise), after a preceding statement and before a logically 8458succeeding case label, or user-defined label. 8459 8460@end table 8461 8462@node Attribute Syntax 8463@section Attribute Syntax 8464@cindex attribute syntax 8465 8466This section describes the syntax with which @code{__attribute__} may be 8467used, and the constructs to which attribute specifiers bind, for the C 8468language. Some details may vary for C++ and Objective-C@. Because of 8469infelicities in the grammar for attributes, some forms described here 8470may not be successfully parsed in all cases. 8471 8472There are some problems with the semantics of attributes in C++. For 8473example, there are no manglings for attributes, although they may affect 8474code generation, so problems may arise when attributed types are used in 8475conjunction with templates or overloading. Similarly, @code{typeid} 8476does not distinguish between types with different attributes. Support 8477for attributes in C++ may be restricted in future to attributes on 8478declarations only, but not on nested declarators. 8479 8480@xref{Function Attributes}, for details of the semantics of attributes 8481applying to functions. @xref{Variable Attributes}, for details of the 8482semantics of attributes applying to variables. @xref{Type Attributes}, 8483for details of the semantics of attributes applying to structure, union 8484and enumerated types. 8485@xref{Label Attributes}, for details of the semantics of attributes 8486applying to labels. 8487@xref{Enumerator Attributes}, for details of the semantics of attributes 8488applying to enumerators. 8489@xref{Statement Attributes}, for details of the semantics of attributes 8490applying to statements. 8491 8492An @dfn{attribute specifier} is of the form 8493@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} 8494is a possibly empty comma-separated sequence of @dfn{attributes}, where 8495each attribute is one of the following: 8496 8497@itemize @bullet 8498@item 8499Empty. Empty attributes are ignored. 8500 8501@item 8502An attribute name 8503(which may be an identifier such as @code{unused}, or a reserved 8504word such as @code{const}). 8505 8506@item 8507An attribute name followed by a parenthesized list of 8508parameters for the attribute. 8509These parameters take one of the following forms: 8510 8511@itemize @bullet 8512@item 8513An identifier. For example, @code{mode} attributes use this form. 8514 8515@item 8516An identifier followed by a comma and a non-empty comma-separated list 8517of expressions. For example, @code{format} attributes use this form. 8518 8519@item 8520A possibly empty comma-separated list of expressions. For example, 8521@code{format_arg} attributes use this form with the list being a single 8522integer constant expression, and @code{alias} attributes use this form 8523with the list being a single string constant. 8524@end itemize 8525@end itemize 8526 8527An @dfn{attribute specifier list} is a sequence of one or more attribute 8528specifiers, not separated by any other tokens. 8529 8530You may optionally specify attribute names with @samp{__} 8531preceding and following the name. 8532This allows you to use them in header files without 8533being concerned about a possible macro of the same name. For example, 8534you may use the attribute name @code{__noreturn__} instead of @code{noreturn}. 8535 8536 8537@subsubheading Label Attributes 8538 8539In GNU C, an attribute specifier list may appear after the colon following a 8540label, other than a @code{case} or @code{default} label. GNU C++ only permits 8541attributes on labels if the attribute specifier is immediately 8542followed by a semicolon (i.e., the label applies to an empty 8543statement). If the semicolon is missing, C++ label attributes are 8544ambiguous, as it is permissible for a declaration, which could begin 8545with an attribute list, to be labelled in C++. Declarations cannot be 8546labelled in C90 or C99, so the ambiguity does not arise there. 8547 8548@subsubheading Enumerator Attributes 8549 8550In GNU C, an attribute specifier list may appear as part of an enumerator. 8551The attribute goes after the enumeration constant, before @code{=}, if 8552present. The optional attribute in the enumerator appertains to the 8553enumeration constant. It is not possible to place the attribute after 8554the constant expression, if present. 8555 8556@subsubheading Statement Attributes 8557In GNU C, an attribute specifier list may appear as part of a null 8558statement. The attribute goes before the semicolon. 8559 8560@subsubheading Type Attributes 8561 8562An attribute specifier list may appear as part of a @code{struct}, 8563@code{union} or @code{enum} specifier. It may go either immediately 8564after the @code{struct}, @code{union} or @code{enum} keyword, or after 8565the closing brace. The former syntax is preferred. 8566Where attribute specifiers follow the closing brace, they are considered 8567to relate to the structure, union or enumerated type defined, not to any 8568enclosing declaration the type specifier appears in, and the type 8569defined is not complete until after the attribute specifiers. 8570@c Otherwise, there would be the following problems: a shift/reduce 8571@c conflict between attributes binding the struct/union/enum and 8572@c binding to the list of specifiers/qualifiers; and "aligned" 8573@c attributes could use sizeof for the structure, but the size could be 8574@c changed later by "packed" attributes. 8575 8576 8577@subsubheading All other attributes 8578 8579Otherwise, an attribute specifier appears as part of a declaration, 8580counting declarations of unnamed parameters and type names, and relates 8581to that declaration (which may be nested in another declaration, for 8582example in the case of a parameter declaration), or to a particular declarator 8583within a declaration. Where an 8584attribute specifier is applied to a parameter declared as a function or 8585an array, it should apply to the function or array rather than the 8586pointer to which the parameter is implicitly converted, but this is not 8587yet correctly implemented. 8588 8589Any list of specifiers and qualifiers at the start of a declaration may 8590contain attribute specifiers, whether or not such a list may in that 8591context contain storage class specifiers. (Some attributes, however, 8592are essentially in the nature of storage class specifiers, and only make 8593sense where storage class specifiers may be used; for example, 8594@code{section}.) There is one necessary limitation to this syntax: the 8595first old-style parameter declaration in a function definition cannot 8596begin with an attribute specifier, because such an attribute applies to 8597the function instead by syntax described below (which, however, is not 8598yet implemented in this case). In some other cases, attribute 8599specifiers are permitted by this grammar but not yet supported by the 8600compiler. All attribute specifiers in this place relate to the 8601declaration as a whole. In the obsolescent usage where a type of 8602@code{int} is implied by the absence of type specifiers, such a list of 8603specifiers and qualifiers may be an attribute specifier list with no 8604other specifiers or qualifiers. 8605 8606At present, the first parameter in a function prototype must have some 8607type specifier that is not an attribute specifier; this resolves an 8608ambiguity in the interpretation of @code{void f(int 8609(__attribute__((foo)) x))}, but is subject to change. At present, if 8610the parentheses of a function declarator contain only attributes then 8611those attributes are ignored, rather than yielding an error or warning 8612or implying a single parameter of type int, but this is subject to 8613change. 8614 8615An attribute specifier list may appear immediately before a declarator 8616(other than the first) in a comma-separated list of declarators in a 8617declaration of more than one identifier using a single list of 8618specifiers and qualifiers. Such attribute specifiers apply 8619only to the identifier before whose declarator they appear. For 8620example, in 8621 8622@smallexample 8623__attribute__((noreturn)) void d0 (void), 8624 __attribute__((format(printf, 1, 2))) d1 (const char *, ...), 8625 d2 (void); 8626@end smallexample 8627 8628@noindent 8629the @code{noreturn} attribute applies to all the functions 8630declared; the @code{format} attribute only applies to @code{d1}. 8631 8632An attribute specifier list may appear immediately before the comma, 8633@code{=} or semicolon terminating the declaration of an identifier other 8634than a function definition. Such attribute specifiers apply 8635to the declared object or function. Where an 8636assembler name for an object or function is specified (@pxref{Asm 8637Labels}), the attribute must follow the @code{asm} 8638specification. 8639 8640An attribute specifier list may, in future, be permitted to appear after 8641the declarator in a function definition (before any old-style parameter 8642declarations or the function body). 8643 8644Attribute specifiers may be mixed with type qualifiers appearing inside 8645the @code{[]} of a parameter array declarator, in the C99 construct by 8646which such qualifiers are applied to the pointer to which the array is 8647implicitly converted. Such attribute specifiers apply to the pointer, 8648not to the array, but at present this is not implemented and they are 8649ignored. 8650 8651An attribute specifier list may appear at the start of a nested 8652declarator. At present, there are some limitations in this usage: the 8653attributes correctly apply to the declarator, but for most individual 8654attributes the semantics this implies are not implemented. 8655When attribute specifiers follow the @code{*} of a pointer 8656declarator, they may be mixed with any type qualifiers present. 8657The following describes the formal semantics of this syntax. It makes the 8658most sense if you are familiar with the formal specification of 8659declarators in the ISO C standard. 8660 8661Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T 8662D1}, where @code{T} contains declaration specifiers that specify a type 8663@var{Type} (such as @code{int}) and @code{D1} is a declarator that 8664contains an identifier @var{ident}. The type specified for @var{ident} 8665for derived declarators whose type does not include an attribute 8666specifier is as in the ISO C standard. 8667 8668If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, 8669and the declaration @code{T D} specifies the type 8670``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 8671@code{T D1} specifies the type ``@var{derived-declarator-type-list} 8672@var{attribute-specifier-list} @var{Type}'' for @var{ident}. 8673 8674If @code{D1} has the form @code{* 8675@var{type-qualifier-and-attribute-specifier-list} D}, and the 8676declaration @code{T D} specifies the type 8677``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 8678@code{T D1} specifies the type ``@var{derived-declarator-type-list} 8679@var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for 8680@var{ident}. 8681 8682For example, 8683 8684@smallexample 8685void (__attribute__((noreturn)) ****f) (void); 8686@end smallexample 8687 8688@noindent 8689specifies the type ``pointer to pointer to pointer to pointer to 8690non-returning function returning @code{void}''. As another example, 8691 8692@smallexample 8693char *__attribute__((aligned(8))) *f; 8694@end smallexample 8695 8696@noindent 8697specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. 8698Note again that this does not work with most attributes; for example, 8699the usage of @samp{aligned} and @samp{noreturn} attributes given above 8700is not yet supported. 8701 8702For compatibility with existing code written for compiler versions that 8703did not implement attributes on nested declarators, some laxity is 8704allowed in the placing of attributes. If an attribute that only applies 8705to types is applied to a declaration, it is treated as applying to 8706the type of that declaration. If an attribute that only applies to 8707declarations is applied to the type of a declaration, it is treated 8708as applying to that declaration; and, for compatibility with code 8709placing the attributes immediately before the identifier declared, such 8710an attribute applied to a function return type is treated as 8711applying to the function type, and such an attribute applied to an array 8712element type is treated as applying to the array type. If an 8713attribute that only applies to function types is applied to a 8714pointer-to-function type, it is treated as applying to the pointer 8715target type; if such an attribute is applied to a function return type 8716that is not a pointer-to-function type, it is treated as applying 8717to the function type. 8718 8719@node Function Prototypes 8720@section Prototypes and Old-Style Function Definitions 8721@cindex function prototype declarations 8722@cindex old-style function definitions 8723@cindex promotion of formal parameters 8724 8725GNU C extends ISO C to allow a function prototype to override a later 8726old-style non-prototype definition. Consider the following example: 8727 8728@smallexample 8729/* @r{Use prototypes unless the compiler is old-fashioned.} */ 8730#ifdef __STDC__ 8731#define P(x) x 8732#else 8733#define P(x) () 8734#endif 8735 8736/* @r{Prototype function declaration.} */ 8737int isroot P((uid_t)); 8738 8739/* @r{Old-style function definition.} */ 8740int 8741isroot (x) /* @r{??? lossage here ???} */ 8742 uid_t x; 8743@{ 8744 return x == 0; 8745@} 8746@end smallexample 8747 8748Suppose the type @code{uid_t} happens to be @code{short}. ISO C does 8749not allow this example, because subword arguments in old-style 8750non-prototype definitions are promoted. Therefore in this example the 8751function definition's argument is really an @code{int}, which does not 8752match the prototype argument type of @code{short}. 8753 8754This restriction of ISO C makes it hard to write code that is portable 8755to traditional C compilers, because the programmer does not know 8756whether the @code{uid_t} type is @code{short}, @code{int}, or 8757@code{long}. Therefore, in cases like these GNU C allows a prototype 8758to override a later old-style definition. More precisely, in GNU C, a 8759function prototype argument type overrides the argument type specified 8760by a later old-style definition if the former type is the same as the 8761latter type before promotion. Thus in GNU C the above example is 8762equivalent to the following: 8763 8764@smallexample 8765int isroot (uid_t); 8766 8767int 8768isroot (uid_t x) 8769@{ 8770 return x == 0; 8771@} 8772@end smallexample 8773 8774@noindent 8775GNU C++ does not support old-style function definitions, so this 8776extension is irrelevant. 8777 8778@node C++ Comments 8779@section C++ Style Comments 8780@cindex @code{//} 8781@cindex C++ comments 8782@cindex comments, C++ style 8783 8784In GNU C, you may use C++ style comments, which start with @samp{//} and 8785continue until the end of the line. Many other C implementations allow 8786such comments, and they are included in the 1999 C standard. However, 8787C++ style comments are not recognized if you specify an @option{-std} 8788option specifying a version of ISO C before C99, or @option{-ansi} 8789(equivalent to @option{-std=c90}). 8790 8791@node Dollar Signs 8792@section Dollar Signs in Identifier Names 8793@cindex $ 8794@cindex dollar signs in identifier names 8795@cindex identifier names, dollar signs in 8796 8797In GNU C, you may normally use dollar signs in identifier names. 8798This is because many traditional C implementations allow such identifiers. 8799However, dollar signs in identifiers are not supported on a few target 8800machines, typically because the target assembler does not allow them. 8801 8802@node Character Escapes 8803@section The Character @key{ESC} in Constants 8804 8805You can use the sequence @samp{\e} in a string or character constant to 8806stand for the ASCII character @key{ESC}. 8807 8808@node Alignment 8809@section Determining the Alignment of Functions, Types or Variables 8810@cindex alignment 8811@cindex type alignment 8812@cindex variable alignment 8813 8814The keyword @code{__alignof__} determines the alignment requirement of 8815a function, object, or a type, or the minimum alignment usually required 8816by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}. 8817 8818For example, if the target machine requires a @code{double} value to be 8819aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. 8820This is true on many RISC machines. On more traditional machine 8821designs, @code{__alignof__ (double)} is 4 or even 2. 8822 8823Some machines never actually require alignment; they allow references to any 8824data type even at an odd address. For these machines, @code{__alignof__} 8825reports the smallest alignment that GCC gives the data type, usually as 8826mandated by the target ABI. 8827 8828If the operand of @code{__alignof__} is an lvalue rather than a type, 8829its value is the required alignment for its type, taking into account 8830any minimum alignment specified by attribute @code{aligned} 8831(@pxref{Common Variable Attributes}). For example, after this 8832declaration: 8833 8834@smallexample 8835struct foo @{ int x; char y; @} foo1; 8836@end smallexample 8837 8838@noindent 8839the value of @code{__alignof__ (foo1.y)} is 1, even though its actual 8840alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. 8841It is an error to ask for the alignment of an incomplete type other 8842than @code{void}. 8843 8844If the operand of the @code{__alignof__} expression is a function, 8845the expression evaluates to the alignment of the function which may 8846be specified by attribute @code{aligned} (@pxref{Common Function Attributes}). 8847 8848@node Inline 8849@section An Inline Function is As Fast As a Macro 8850@cindex inline functions 8851@cindex integrating function code 8852@cindex open coding 8853@cindex macros, inline alternative 8854 8855By declaring a function inline, you can direct GCC to make 8856calls to that function faster. One way GCC can achieve this is to 8857integrate that function's code into the code for its callers. This 8858makes execution faster by eliminating the function-call overhead; in 8859addition, if any of the actual argument values are constant, their 8860known values may permit simplifications at compile time so that not 8861all of the inline function's code needs to be included. The effect on 8862code size is less predictable; object code may be larger or smaller 8863with function inlining, depending on the particular case. You can 8864also direct GCC to try to integrate all ``simple enough'' functions 8865into their callers with the option @option{-finline-functions}. 8866 8867GCC implements three different semantics of declaring a function 8868inline. One is available with @option{-std=gnu89} or 8869@option{-fgnu89-inline} or when @code{gnu_inline} attribute is present 8870on all inline declarations, another when 8871@option{-std=c99}, 8872@option{-std=gnu99} or an option for a later C version is used 8873(without @option{-fgnu89-inline}), and the third 8874is used when compiling C++. 8875 8876To declare a function inline, use the @code{inline} keyword in its 8877declaration, like this: 8878 8879@smallexample 8880static inline int 8881inc (int *a) 8882@{ 8883 return (*a)++; 8884@} 8885@end smallexample 8886 8887If you are writing a header file to be included in ISO C90 programs, write 8888@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}. 8889 8890The three types of inlining behave similarly in two important cases: 8891when the @code{inline} keyword is used on a @code{static} function, 8892like the example above, and when a function is first declared without 8893using the @code{inline} keyword and then is defined with 8894@code{inline}, like this: 8895 8896@smallexample 8897extern int inc (int *a); 8898inline int 8899inc (int *a) 8900@{ 8901 return (*a)++; 8902@} 8903@end smallexample 8904 8905In both of these common cases, the program behaves the same as if you 8906had not used the @code{inline} keyword, except for its speed. 8907 8908@cindex inline functions, omission of 8909@opindex fkeep-inline-functions 8910When a function is both inline and @code{static}, if all calls to the 8911function are integrated into the caller, and the function's address is 8912never used, then the function's own assembler code is never referenced. 8913In this case, GCC does not actually output assembler code for the 8914function, unless you specify the option @option{-fkeep-inline-functions}. 8915If there is a nonintegrated call, then the function is compiled to 8916assembler code as usual. The function must also be compiled as usual if 8917the program refers to its address, because that cannot be inlined. 8918 8919@opindex Winline 8920Note that certain usages in a function definition can make it unsuitable 8921for inline substitution. Among these usages are: variadic functions, 8922use of @code{alloca}, use of computed goto (@pxref{Labels as Values}), 8923use of nonlocal goto, use of nested functions, use of @code{setjmp}, use 8924of @code{__builtin_longjmp} and use of @code{__builtin_return} or 8925@code{__builtin_apply_args}. Using @option{-Winline} warns when a 8926function marked @code{inline} could not be substituted, and gives the 8927reason for the failure. 8928 8929@cindex automatic @code{inline} for C++ member fns 8930@cindex @code{inline} automatic for C++ member fns 8931@cindex member fns, automatically @code{inline} 8932@cindex C++ member fns, automatically @code{inline} 8933@opindex fno-default-inline 8934As required by ISO C++, GCC considers member functions defined within 8935the body of a class to be marked inline even if they are 8936not explicitly declared with the @code{inline} keyword. You can 8937override this with @option{-fno-default-inline}; @pxref{C++ Dialect 8938Options,,Options Controlling C++ Dialect}. 8939 8940GCC does not inline any functions when not optimizing unless you specify 8941the @samp{always_inline} attribute for the function, like this: 8942 8943@smallexample 8944/* @r{Prototype.} */ 8945inline void foo (const char) __attribute__((always_inline)); 8946@end smallexample 8947 8948The remainder of this section is specific to GNU C90 inlining. 8949 8950@cindex non-static inline function 8951When an inline function is not @code{static}, then the compiler must assume 8952that there may be calls from other source files; since a global symbol can 8953be defined only once in any program, the function must not be defined in 8954the other source files, so the calls therein cannot be integrated. 8955Therefore, a non-@code{static} inline function is always compiled on its 8956own in the usual fashion. 8957 8958If you specify both @code{inline} and @code{extern} in the function 8959definition, then the definition is used only for inlining. In no case 8960is the function compiled on its own, not even if you refer to its 8961address explicitly. Such an address becomes an external reference, as 8962if you had only declared the function, and had not defined it. 8963 8964This combination of @code{inline} and @code{extern} has almost the 8965effect of a macro. The way to use it is to put a function definition in 8966a header file with these keywords, and put another copy of the 8967definition (lacking @code{inline} and @code{extern}) in a library file. 8968The definition in the header file causes most calls to the function 8969to be inlined. If any uses of the function remain, they refer to 8970the single copy in the library. 8971 8972@node Volatiles 8973@section When is a Volatile Object Accessed? 8974@cindex accessing volatiles 8975@cindex volatile read 8976@cindex volatile write 8977@cindex volatile access 8978 8979C has the concept of volatile objects. These are normally accessed by 8980pointers and used for accessing hardware or inter-thread 8981communication. The standard encourages compilers to refrain from 8982optimizations concerning accesses to volatile objects, but leaves it 8983implementation defined as to what constitutes a volatile access. The 8984minimum requirement is that at a sequence point all previous accesses 8985to volatile objects have stabilized and no subsequent accesses have 8986occurred. Thus an implementation is free to reorder and combine 8987volatile accesses that occur between sequence points, but cannot do 8988so for accesses across a sequence point. The use of volatile does 8989not allow you to violate the restriction on updating objects multiple 8990times between two sequence points. 8991 8992Accesses to non-volatile objects are not ordered with respect to 8993volatile accesses. You cannot use a volatile object as a memory 8994barrier to order a sequence of writes to non-volatile memory. For 8995instance: 8996 8997@smallexample 8998int *ptr = @var{something}; 8999volatile int vobj; 9000*ptr = @var{something}; 9001vobj = 1; 9002@end smallexample 9003 9004@noindent 9005Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed 9006that the write to @var{*ptr} occurs by the time the update 9007of @var{vobj} happens. If you need this guarantee, you must use 9008a stronger memory barrier such as: 9009 9010@smallexample 9011int *ptr = @var{something}; 9012volatile int vobj; 9013*ptr = @var{something}; 9014asm volatile ("" : : : "memory"); 9015vobj = 1; 9016@end smallexample 9017 9018A scalar volatile object is read when it is accessed in a void context: 9019 9020@smallexample 9021volatile int *src = @var{somevalue}; 9022*src; 9023@end smallexample 9024 9025Such expressions are rvalues, and GCC implements this as a 9026read of the volatile object being pointed to. 9027 9028Assignments are also expressions and have an rvalue. However when 9029assigning to a scalar volatile, the volatile object is not reread, 9030regardless of whether the assignment expression's rvalue is used or 9031not. If the assignment's rvalue is used, the value is that assigned 9032to the volatile object. For instance, there is no read of @var{vobj} 9033in all the following cases: 9034 9035@smallexample 9036int obj; 9037volatile int vobj; 9038vobj = @var{something}; 9039obj = vobj = @var{something}; 9040obj ? vobj = @var{onething} : vobj = @var{anotherthing}; 9041obj = (@var{something}, vobj = @var{anotherthing}); 9042@end smallexample 9043 9044If you need to read the volatile object after an assignment has 9045occurred, you must use a separate expression with an intervening 9046sequence point. 9047 9048As bit-fields are not individually addressable, volatile bit-fields may 9049be implicitly read when written to, or when adjacent bit-fields are 9050accessed. Bit-field operations may be optimized such that adjacent 9051bit-fields are only partially accessed, if they straddle a storage unit 9052boundary. For these reasons it is unwise to use volatile bit-fields to 9053access hardware. 9054 9055@node Using Assembly Language with C 9056@section How to Use Inline Assembly Language in C Code 9057@cindex @code{asm} keyword 9058@cindex assembly language in C 9059@cindex inline assembly language 9060@cindex mixing assembly language and C 9061 9062The @code{asm} keyword allows you to embed assembler instructions 9063within C code. GCC provides two forms of inline @code{asm} 9064statements. A @dfn{basic @code{asm}} statement is one with no 9065operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}} 9066statement (@pxref{Extended Asm}) includes one or more operands. 9067The extended form is preferred for mixing C and assembly language 9068within a function, but to include assembly language at 9069top level you must use basic @code{asm}. 9070 9071You can also use the @code{asm} keyword to override the assembler name 9072for a C symbol, or to place a C variable in a specific register. 9073 9074@menu 9075* Basic Asm:: Inline assembler without operands. 9076* Extended Asm:: Inline assembler with operands. 9077* Constraints:: Constraints for @code{asm} operands 9078* Asm Labels:: Specifying the assembler name to use for a C symbol. 9079* Explicit Register Variables:: Defining variables residing in specified 9080 registers. 9081* Size of an asm:: How GCC calculates the size of an @code{asm} block. 9082@end menu 9083 9084@node Basic Asm 9085@subsection Basic Asm --- Assembler Instructions Without Operands 9086@cindex basic @code{asm} 9087@cindex assembly language in C, basic 9088 9089A basic @code{asm} statement has the following syntax: 9090 9091@example 9092asm @var{asm-qualifiers} ( @var{AssemblerInstructions} ) 9093@end example 9094 9095The @code{asm} keyword is a GNU extension. 9096When writing code that can be compiled with @option{-ansi} and the 9097various @option{-std} options, use @code{__asm__} instead of 9098@code{asm} (@pxref{Alternate Keywords}). 9099 9100@subsubheading Qualifiers 9101@table @code 9102@item volatile 9103The optional @code{volatile} qualifier has no effect. 9104All basic @code{asm} blocks are implicitly volatile. 9105 9106@item inline 9107If you use the @code{inline} qualifier, then for inlining purposes the size 9108of the @code{asm} statement is taken as the smallest size possible (@pxref{Size 9109of an asm}). 9110@end table 9111 9112@subsubheading Parameters 9113@table @var 9114 9115@item AssemblerInstructions 9116This is a literal string that specifies the assembler code. The string can 9117contain any instructions recognized by the assembler, including directives. 9118GCC does not parse the assembler instructions themselves and 9119does not know what they mean or even whether they are valid assembler input. 9120 9121You may place multiple assembler instructions together in a single @code{asm} 9122string, separated by the characters normally used in assembly code for the 9123system. A combination that works in most places is a newline to break the 9124line, plus a tab character (written as @samp{\n\t}). 9125Some assemblers allow semicolons as a line separator. However, 9126note that some assembler dialects use semicolons to start a comment. 9127@end table 9128 9129@subsubheading Remarks 9130Using extended @code{asm} (@pxref{Extended Asm}) typically produces 9131smaller, safer, and more efficient code, and in most cases it is a 9132better solution than basic @code{asm}. However, there are two 9133situations where only basic @code{asm} can be used: 9134 9135@itemize @bullet 9136@item 9137Extended @code{asm} statements have to be inside a C 9138function, so to write inline assembly language at file scope (``top-level''), 9139outside of C functions, you must use basic @code{asm}. 9140You can use this technique to emit assembler directives, 9141define assembly language macros that can be invoked elsewhere in the file, 9142or write entire functions in assembly language. 9143Basic @code{asm} statements outside of functions may not use any 9144qualifiers. 9145 9146@item 9147Functions declared 9148with the @code{naked} attribute also require basic @code{asm} 9149(@pxref{Function Attributes}). 9150@end itemize 9151 9152Safely accessing C data and calling functions from basic @code{asm} is more 9153complex than it may appear. To access C data, it is better to use extended 9154@code{asm}. 9155 9156Do not expect a sequence of @code{asm} statements to remain perfectly 9157consecutive after compilation. If certain instructions need to remain 9158consecutive in the output, put them in a single multi-instruction @code{asm} 9159statement. Note that GCC's optimizers can move @code{asm} statements 9160relative to other code, including across jumps. 9161 9162@code{asm} statements may not perform jumps into other @code{asm} statements. 9163GCC does not know about these jumps, and therefore cannot take 9164account of them when deciding how to optimize. Jumps from @code{asm} to C 9165labels are only supported in extended @code{asm}. 9166 9167Under certain circumstances, GCC may duplicate (or remove duplicates of) your 9168assembly code when optimizing. This can lead to unexpected duplicate 9169symbol errors during compilation if your assembly code defines symbols or 9170labels. 9171 9172@strong{Warning:} The C standards do not specify semantics for @code{asm}, 9173making it a potential source of incompatibilities between compilers. These 9174incompatibilities may not produce compiler warnings/errors. 9175 9176GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which 9177means there is no way to communicate to the compiler what is happening 9178inside them. GCC has no visibility of symbols in the @code{asm} and may 9179discard them as unreferenced. It also does not know about side effects of 9180the assembler code, such as modifications to memory or registers. Unlike 9181some compilers, GCC assumes that no changes to general purpose registers 9182occur. This assumption may change in a future release. 9183 9184To avoid complications from future changes to the semantics and the 9185compatibility issues between compilers, consider replacing basic @code{asm} 9186with extended @code{asm}. See 9187@uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert 9188from basic asm to extended asm} for information about how to perform this 9189conversion. 9190 9191The compiler copies the assembler instructions in a basic @code{asm} 9192verbatim to the assembly language output file, without 9193processing dialects or any of the @samp{%} operators that are available with 9194extended @code{asm}. This results in minor differences between basic 9195@code{asm} strings and extended @code{asm} templates. For example, to refer to 9196registers you might use @samp{%eax} in basic @code{asm} and 9197@samp{%%eax} in extended @code{asm}. 9198 9199On targets such as x86 that support multiple assembler dialects, 9200all basic @code{asm} blocks use the assembler dialect specified by the 9201@option{-masm} command-line option (@pxref{x86 Options}). 9202Basic @code{asm} provides no 9203mechanism to provide different assembler strings for different dialects. 9204 9205For basic @code{asm} with non-empty assembler string GCC assumes 9206the assembler block does not change any general purpose registers, 9207but it may read or write any globally accessible variable. 9208 9209Here is an example of basic @code{asm} for i386: 9210 9211@example 9212/* Note that this code will not compile with -masm=intel */ 9213#define DebugBreak() asm("int $3") 9214@end example 9215 9216@node Extended Asm 9217@subsection Extended Asm - Assembler Instructions with C Expression Operands 9218@cindex extended @code{asm} 9219@cindex assembly language in C, extended 9220 9221With extended @code{asm} you can read and write C variables from 9222assembler and perform jumps from assembler code to C labels. 9223Extended @code{asm} syntax uses colons (@samp{:}) to delimit 9224the operand parameters after the assembler template: 9225 9226@example 9227asm @var{asm-qualifiers} ( @var{AssemblerTemplate} 9228 : @var{OutputOperands} 9229 @r{[} : @var{InputOperands} 9230 @r{[} : @var{Clobbers} @r{]} @r{]}) 9231 9232asm @var{asm-qualifiers} ( @var{AssemblerTemplate} 9233 : 9234 : @var{InputOperands} 9235 : @var{Clobbers} 9236 : @var{GotoLabels}) 9237@end example 9238where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the 9239first form, not). 9240 9241The @code{asm} keyword is a GNU extension. 9242When writing code that can be compiled with @option{-ansi} and the 9243various @option{-std} options, use @code{__asm__} instead of 9244@code{asm} (@pxref{Alternate Keywords}). 9245 9246@subsubheading Qualifiers 9247@table @code 9248 9249@item volatile 9250The typical use of extended @code{asm} statements is to manipulate input 9251values to produce output values. However, your @code{asm} statements may 9252also produce side effects. If so, you may need to use the @code{volatile} 9253qualifier to disable certain optimizations. @xref{Volatile}. 9254 9255@item inline 9256If you use the @code{inline} qualifier, then for inlining purposes the size 9257of the @code{asm} statement is taken as the smallest size possible 9258(@pxref{Size of an asm}). 9259 9260@item goto 9261This qualifier informs the compiler that the @code{asm} statement may 9262perform a jump to one of the labels listed in the @var{GotoLabels}. 9263@xref{GotoLabels}. 9264@end table 9265 9266@subsubheading Parameters 9267@table @var 9268@item AssemblerTemplate 9269This is a literal string that is the template for the assembler code. It is a 9270combination of fixed text and tokens that refer to the input, output, 9271and goto parameters. @xref{AssemblerTemplate}. 9272 9273@item OutputOperands 9274A comma-separated list of the C variables modified by the instructions in the 9275@var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}. 9276 9277@item InputOperands 9278A comma-separated list of C expressions read by the instructions in the 9279@var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}. 9280 9281@item Clobbers 9282A comma-separated list of registers or other values changed by the 9283@var{AssemblerTemplate}, beyond those listed as outputs. 9284An empty list is permitted. @xref{Clobbers and Scratch Registers}. 9285 9286@item GotoLabels 9287When you are using the @code{goto} form of @code{asm}, this section contains 9288the list of all C labels to which the code in the 9289@var{AssemblerTemplate} may jump. 9290@xref{GotoLabels}. 9291 9292@code{asm} statements may not perform jumps into other @code{asm} statements, 9293only to the listed @var{GotoLabels}. 9294GCC's optimizers do not know about other jumps; therefore they cannot take 9295account of them when deciding how to optimize. 9296@end table 9297 9298The total number of input + output + goto operands is limited to 30. 9299 9300@subsubheading Remarks 9301The @code{asm} statement allows you to include assembly instructions directly 9302within C code. This may help you to maximize performance in time-sensitive 9303code or to access assembly instructions that are not readily available to C 9304programs. 9305 9306Note that extended @code{asm} statements must be inside a function. Only 9307basic @code{asm} may be outside functions (@pxref{Basic Asm}). 9308Functions declared with the @code{naked} attribute also require basic 9309@code{asm} (@pxref{Function Attributes}). 9310 9311While the uses of @code{asm} are many and varied, it may help to think of an 9312@code{asm} statement as a series of low-level instructions that convert input 9313parameters to output parameters. So a simple (if not particularly useful) 9314example for i386 using @code{asm} might look like this: 9315 9316@example 9317int src = 1; 9318int dst; 9319 9320asm ("mov %1, %0\n\t" 9321 "add $1, %0" 9322 : "=r" (dst) 9323 : "r" (src)); 9324 9325printf("%d\n", dst); 9326@end example 9327 9328This code copies @code{src} to @code{dst} and add 1 to @code{dst}. 9329 9330@anchor{Volatile} 9331@subsubsection Volatile 9332@cindex volatile @code{asm} 9333@cindex @code{asm} volatile 9334 9335GCC's optimizers sometimes discard @code{asm} statements if they determine 9336there is no need for the output variables. Also, the optimizers may move 9337code out of loops if they believe that the code will always return the same 9338result (i.e.@: none of its input values change between calls). Using the 9339@code{volatile} qualifier disables these optimizations. @code{asm} statements 9340that have no output operands, including @code{asm goto} statements, 9341are implicitly volatile. 9342 9343This i386 code demonstrates a case that does not use (or require) the 9344@code{volatile} qualifier. If it is performing assertion checking, this code 9345uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is 9346unreferenced by any code. As a result, the optimizers can discard the 9347@code{asm} statement, which in turn removes the need for the entire 9348@code{DoCheck} routine. By omitting the @code{volatile} qualifier when it 9349isn't needed you allow the optimizers to produce the most efficient code 9350possible. 9351 9352@example 9353void DoCheck(uint32_t dwSomeValue) 9354@{ 9355 uint32_t dwRes; 9356 9357 // Assumes dwSomeValue is not zero. 9358 asm ("bsfl %1,%0" 9359 : "=r" (dwRes) 9360 : "r" (dwSomeValue) 9361 : "cc"); 9362 9363 assert(dwRes > 3); 9364@} 9365@end example 9366 9367The next example shows a case where the optimizers can recognize that the input 9368(@code{dwSomeValue}) never changes during the execution of the function and can 9369therefore move the @code{asm} outside the loop to produce more efficient code. 9370Again, using the @code{volatile} qualifier disables this type of optimization. 9371 9372@example 9373void do_print(uint32_t dwSomeValue) 9374@{ 9375 uint32_t dwRes; 9376 9377 for (uint32_t x=0; x < 5; x++) 9378 @{ 9379 // Assumes dwSomeValue is not zero. 9380 asm ("bsfl %1,%0" 9381 : "=r" (dwRes) 9382 : "r" (dwSomeValue) 9383 : "cc"); 9384 9385 printf("%u: %u %u\n", x, dwSomeValue, dwRes); 9386 @} 9387@} 9388@end example 9389 9390The following example demonstrates a case where you need to use the 9391@code{volatile} qualifier. 9392It uses the x86 @code{rdtsc} instruction, which reads 9393the computer's time-stamp counter. Without the @code{volatile} qualifier, 9394the optimizers might assume that the @code{asm} block will always return the 9395same value and therefore optimize away the second call. 9396 9397@example 9398uint64_t msr; 9399 9400asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. 9401 "shl $32, %%rdx\n\t" // Shift the upper bits left. 9402 "or %%rdx, %0" // 'Or' in the lower bits. 9403 : "=a" (msr) 9404 : 9405 : "rdx"); 9406 9407printf("msr: %llx\n", msr); 9408 9409// Do other work... 9410 9411// Reprint the timestamp 9412asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. 9413 "shl $32, %%rdx\n\t" // Shift the upper bits left. 9414 "or %%rdx, %0" // 'Or' in the lower bits. 9415 : "=a" (msr) 9416 : 9417 : "rdx"); 9418 9419printf("msr: %llx\n", msr); 9420@end example 9421 9422GCC's optimizers do not treat this code like the non-volatile code in the 9423earlier examples. They do not move it out of loops or omit it on the 9424assumption that the result from a previous call is still valid. 9425 9426Note that the compiler can move even @code{volatile asm} instructions relative 9427to other code, including across jump instructions. For example, on many 9428targets there is a system register that controls the rounding mode of 9429floating-point operations. Setting it with a @code{volatile asm} statement, 9430as in the following PowerPC example, does not work reliably. 9431 9432@example 9433asm volatile("mtfsf 255, %0" : : "f" (fpenv)); 9434sum = x + y; 9435@end example 9436 9437The compiler may move the addition back before the @code{volatile asm} 9438statement. To make it work as expected, add an artificial dependency to 9439the @code{asm} by referencing a variable in the subsequent code, for 9440example: 9441 9442@example 9443asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv)); 9444sum = x + y; 9445@end example 9446 9447Under certain circumstances, GCC may duplicate (or remove duplicates of) your 9448assembly code when optimizing. This can lead to unexpected duplicate symbol 9449errors during compilation if your @code{asm} code defines symbols or labels. 9450Using @samp{%=} 9451(@pxref{AssemblerTemplate}) may help resolve this problem. 9452 9453@anchor{AssemblerTemplate} 9454@subsubsection Assembler Template 9455@cindex @code{asm} assembler template 9456 9457An assembler template is a literal string containing assembler instructions. 9458The compiler replaces tokens in the template that refer 9459to inputs, outputs, and goto labels, 9460and then outputs the resulting string to the assembler. The 9461string can contain any instructions recognized by the assembler, including 9462directives. GCC does not parse the assembler instructions 9463themselves and does not know what they mean or even whether they are valid 9464assembler input. However, it does count the statements 9465(@pxref{Size of an asm}). 9466 9467You may place multiple assembler instructions together in a single @code{asm} 9468string, separated by the characters normally used in assembly code for the 9469system. A combination that works in most places is a newline to break the 9470line, plus a tab character to move to the instruction field (written as 9471@samp{\n\t}). 9472Some assemblers allow semicolons as a line separator. However, note 9473that some assembler dialects use semicolons to start a comment. 9474 9475Do not expect a sequence of @code{asm} statements to remain perfectly 9476consecutive after compilation, even when you are using the @code{volatile} 9477qualifier. If certain instructions need to remain consecutive in the output, 9478put them in a single multi-instruction @code{asm} statement. 9479 9480Accessing data from C programs without using input/output operands (such as 9481by using global symbols directly from the assembler template) may not work as 9482expected. Similarly, calling functions directly from an assembler template 9483requires a detailed understanding of the target assembler and ABI. 9484 9485Since GCC does not parse the assembler template, 9486it has no visibility of any 9487symbols it references. This may result in GCC discarding those symbols as 9488unreferenced unless they are also listed as input, output, or goto operands. 9489 9490@subsubheading Special format strings 9491 9492In addition to the tokens described by the input, output, and goto operands, 9493these tokens have special meanings in the assembler template: 9494 9495@table @samp 9496@item %% 9497Outputs a single @samp{%} into the assembler code. 9498 9499@item %= 9500Outputs a number that is unique to each instance of the @code{asm} 9501statement in the entire compilation. This option is useful when creating local 9502labels and referring to them multiple times in a single template that 9503generates multiple assembler instructions. 9504 9505@item %@{ 9506@itemx %| 9507@itemx %@} 9508Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively) 9509into the assembler code. When unescaped, these characters have special 9510meaning to indicate multiple assembler dialects, as described below. 9511@end table 9512 9513@subsubheading Multiple assembler dialects in @code{asm} templates 9514 9515On targets such as x86, GCC supports multiple assembler dialects. 9516The @option{-masm} option controls which dialect GCC uses as its 9517default for inline assembler. The target-specific documentation for the 9518@option{-masm} option contains the list of supported dialects, as well as the 9519default dialect if the option is not specified. This information may be 9520important to understand, since assembler code that works correctly when 9521compiled using one dialect will likely fail if compiled using another. 9522@xref{x86 Options}. 9523 9524If your code needs to support multiple assembler dialects (for example, if 9525you are writing public headers that need to support a variety of compilation 9526options), use constructs of this form: 9527 9528@example 9529@{ dialect0 | dialect1 | dialect2... @} 9530@end example 9531 9532This construct outputs @code{dialect0} 9533when using dialect #0 to compile the code, 9534@code{dialect1} for dialect #1, etc. If there are fewer alternatives within the 9535braces than the number of dialects the compiler supports, the construct 9536outputs nothing. 9537 9538For example, if an x86 compiler supports two dialects 9539(@samp{att}, @samp{intel}), an 9540assembler template such as this: 9541 9542@example 9543"bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2" 9544@end example 9545 9546@noindent 9547is equivalent to one of 9548 9549@example 9550"btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */} 9551"bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */} 9552@end example 9553 9554Using that same compiler, this code: 9555 9556@example 9557"xchg@{l@}\t@{%%@}ebx, %1" 9558@end example 9559 9560@noindent 9561corresponds to either 9562 9563@example 9564"xchgl\t%%ebx, %1" @r{/* att dialect */} 9565"xchg\tebx, %1" @r{/* intel dialect */} 9566@end example 9567 9568There is no support for nesting dialect alternatives. 9569 9570@anchor{OutputOperands} 9571@subsubsection Output Operands 9572@cindex @code{asm} output operands 9573 9574An @code{asm} statement has zero or more output operands indicating the names 9575of C variables modified by the assembler code. 9576 9577In this i386 example, @code{old} (referred to in the template string as 9578@code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset} 9579(@code{%2}) is an input: 9580 9581@example 9582bool old; 9583 9584__asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base. 9585 "sbb %0,%0" // Use the CF to calculate old. 9586 : "=r" (old), "+rm" (*Base) 9587 : "Ir" (Offset) 9588 : "cc"); 9589 9590return old; 9591@end example 9592 9593Operands are separated by commas. Each operand has this format: 9594 9595@example 9596@r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename}) 9597@end example 9598 9599@table @var 9600@item asmSymbolicName 9601Specifies a symbolic name for the operand. 9602Reference the name in the assembler template 9603by enclosing it in square brackets 9604(i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement 9605that contains the definition. Any valid C variable name is acceptable, 9606including names already defined in the surrounding code. No two operands 9607within the same @code{asm} statement can use the same symbolic name. 9608 9609When not using an @var{asmSymbolicName}, use the (zero-based) position 9610of the operand 9611in the list of operands in the assembler template. For example if there are 9612three output operands, use @samp{%0} in the template to refer to the first, 9613@samp{%1} for the second, and @samp{%2} for the third. 9614 9615@item constraint 9616A string constant specifying constraints on the placement of the operand; 9617@xref{Constraints}, for details. 9618 9619Output constraints must begin with either @samp{=} (a variable overwriting an 9620existing value) or @samp{+} (when reading and writing). When using 9621@samp{=}, do not assume the location contains the existing value 9622on entry to the @code{asm}, except 9623when the operand is tied to an input; @pxref{InputOperands,,Input Operands}. 9624 9625After the prefix, there must be one or more additional constraints 9626(@pxref{Constraints}) that describe where the value resides. Common 9627constraints include @samp{r} for register and @samp{m} for memory. 9628When you list more than one possible location (for example, @code{"=rm"}), 9629the compiler chooses the most efficient one based on the current context. 9630If you list as many alternates as the @code{asm} statement allows, you permit 9631the optimizers to produce the best possible code. 9632If you must use a specific register, but your Machine Constraints do not 9633provide sufficient control to select the specific register you want, 9634local register variables may provide a solution (@pxref{Local Register 9635Variables}). 9636 9637@item cvariablename 9638Specifies a C lvalue expression to hold the output, typically a variable name. 9639The enclosing parentheses are a required part of the syntax. 9640 9641@end table 9642 9643When the compiler selects the registers to use to 9644represent the output operands, it does not use any of the clobbered registers 9645(@pxref{Clobbers and Scratch Registers}). 9646 9647Output operand expressions must be lvalues. The compiler cannot check whether 9648the operands have data types that are reasonable for the instruction being 9649executed. For output expressions that are not directly addressable (for 9650example a bit-field), the constraint must allow a register. In that case, GCC 9651uses the register as the output of the @code{asm}, and then stores that 9652register into the output. 9653 9654Operands using the @samp{+} constraint modifier count as two operands 9655(that is, both as input and output) towards the total maximum of 30 operands 9656per @code{asm} statement. 9657 9658Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output 9659operands that must not overlap an input. Otherwise, 9660GCC may allocate the output operand in the same register as an unrelated 9661input operand, on the assumption that the assembler code consumes its 9662inputs before producing outputs. This assumption may be false if the assembler 9663code actually consists of more than one instruction. 9664 9665The same problem can occur if one output parameter (@var{a}) allows a register 9666constraint and another output parameter (@var{b}) allows a memory constraint. 9667The code generated by GCC to access the memory address in @var{b} can contain 9668registers which @emph{might} be shared by @var{a}, and GCC considers those 9669registers to be inputs to the asm. As above, GCC assumes that such input 9670registers are consumed before any outputs are written. This assumption may 9671result in incorrect behavior if the @code{asm} statement writes to @var{a} 9672before using 9673@var{b}. Combining the @samp{&} modifier with the register constraint on @var{a} 9674ensures that modifying @var{a} does not affect the address referenced by 9675@var{b}. Otherwise, the location of @var{b} 9676is undefined if @var{a} is modified before using @var{b}. 9677 9678@code{asm} supports operand modifiers on operands (for example @samp{%k2} 9679instead of simply @samp{%2}). Typically these qualifiers are hardware 9680dependent. The list of supported modifiers for x86 is found at 9681@ref{x86Operandmodifiers,x86 Operand modifiers}. 9682 9683If the C code that follows the @code{asm} makes no use of any of the output 9684operands, use @code{volatile} for the @code{asm} statement to prevent the 9685optimizers from discarding the @code{asm} statement as unneeded 9686(see @ref{Volatile}). 9687 9688This code makes no use of the optional @var{asmSymbolicName}. Therefore it 9689references the first output operand as @code{%0} (were there a second, it 9690would be @code{%1}, etc). The number of the first input operand is one greater 9691than that of the last output operand. In this i386 example, that makes 9692@code{Mask} referenced as @code{%1}: 9693 9694@example 9695uint32_t Mask = 1234; 9696uint32_t Index; 9697 9698 asm ("bsfl %1, %0" 9699 : "=r" (Index) 9700 : "r" (Mask) 9701 : "cc"); 9702@end example 9703 9704That code overwrites the variable @code{Index} (@samp{=}), 9705placing the value in a register (@samp{r}). 9706Using the generic @samp{r} constraint instead of a constraint for a specific 9707register allows the compiler to pick the register to use, which can result 9708in more efficient code. This may not be possible if an assembler instruction 9709requires a specific register. 9710 9711The following i386 example uses the @var{asmSymbolicName} syntax. 9712It produces the 9713same result as the code above, but some may consider it more readable or more 9714maintainable since reordering index numbers is not necessary when adding or 9715removing operands. The names @code{aIndex} and @code{aMask} 9716are only used in this example to emphasize which 9717names get used where. 9718It is acceptable to reuse the names @code{Index} and @code{Mask}. 9719 9720@example 9721uint32_t Mask = 1234; 9722uint32_t Index; 9723 9724 asm ("bsfl %[aMask], %[aIndex]" 9725 : [aIndex] "=r" (Index) 9726 : [aMask] "r" (Mask) 9727 : "cc"); 9728@end example 9729 9730Here are some more examples of output operands. 9731 9732@example 9733uint32_t c = 1; 9734uint32_t d; 9735uint32_t *e = &c; 9736 9737asm ("mov %[e], %[d]" 9738 : [d] "=rm" (d) 9739 : [e] "rm" (*e)); 9740@end example 9741 9742Here, @code{d} may either be in a register or in memory. Since the compiler 9743might already have the current value of the @code{uint32_t} location 9744pointed to by @code{e} 9745in a register, you can enable it to choose the best location 9746for @code{d} by specifying both constraints. 9747 9748@anchor{FlagOutputOperands} 9749@subsubsection Flag Output Operands 9750@cindex @code{asm} flag output operands 9751 9752Some targets have a special register that holds the ``flags'' for the 9753result of an operation or comparison. Normally, the contents of that 9754register are either unmodifed by the asm, or the @code{asm} statement is 9755considered to clobber the contents. 9756 9757On some targets, a special form of output operand exists by which 9758conditions in the flags register may be outputs of the asm. The set of 9759conditions supported are target specific, but the general rule is that 9760the output variable must be a scalar integer, and the value is boolean. 9761When supported, the target defines the preprocessor symbol 9762@code{__GCC_ASM_FLAG_OUTPUTS__}. 9763 9764Because of the special nature of the flag output operands, the constraint 9765may not include alternatives. 9766 9767Most often, the target has only one flags register, and thus is an implied 9768operand of many instructions. In this case, the operand should not be 9769referenced within the assembler template via @code{%0} etc, as there's 9770no corresponding text in the assembly language. 9771 9772@table @asis 9773@item x86 family 9774The flag output constraints for the x86 family are of the form 9775@samp{=@@cc@var{cond}} where @var{cond} is one of the standard 9776conditions defined in the ISA manual for @code{j@var{cc}} or 9777@code{set@var{cc}}. 9778 9779@table @code 9780@item a 9781``above'' or unsigned greater than 9782@item ae 9783``above or equal'' or unsigned greater than or equal 9784@item b 9785``below'' or unsigned less than 9786@item be 9787``below or equal'' or unsigned less than or equal 9788@item c 9789carry flag set 9790@item e 9791@itemx z 9792``equal'' or zero flag set 9793@item g 9794signed greater than 9795@item ge 9796signed greater than or equal 9797@item l 9798signed less than 9799@item le 9800signed less than or equal 9801@item o 9802overflow flag set 9803@item p 9804parity flag set 9805@item s 9806sign flag set 9807@item na 9808@itemx nae 9809@itemx nb 9810@itemx nbe 9811@itemx nc 9812@itemx ne 9813@itemx ng 9814@itemx nge 9815@itemx nl 9816@itemx nle 9817@itemx no 9818@itemx np 9819@itemx ns 9820@itemx nz 9821``not'' @var{flag}, or inverted versions of those above 9822@end table 9823 9824@end table 9825 9826@anchor{InputOperands} 9827@subsubsection Input Operands 9828@cindex @code{asm} input operands 9829@cindex @code{asm} expressions 9830 9831Input operands make values from C variables and expressions available to the 9832assembly code. 9833 9834Operands are separated by commas. Each operand has this format: 9835 9836@example 9837@r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression}) 9838@end example 9839 9840@table @var 9841@item asmSymbolicName 9842Specifies a symbolic name for the operand. 9843Reference the name in the assembler template 9844by enclosing it in square brackets 9845(i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement 9846that contains the definition. Any valid C variable name is acceptable, 9847including names already defined in the surrounding code. No two operands 9848within the same @code{asm} statement can use the same symbolic name. 9849 9850When not using an @var{asmSymbolicName}, use the (zero-based) position 9851of the operand 9852in the list of operands in the assembler template. For example if there are 9853two output operands and three inputs, 9854use @samp{%2} in the template to refer to the first input operand, 9855@samp{%3} for the second, and @samp{%4} for the third. 9856 9857@item constraint 9858A string constant specifying constraints on the placement of the operand; 9859@xref{Constraints}, for details. 9860 9861Input constraint strings may not begin with either @samp{=} or @samp{+}. 9862When you list more than one possible location (for example, @samp{"irm"}), 9863the compiler chooses the most efficient one based on the current context. 9864If you must use a specific register, but your Machine Constraints do not 9865provide sufficient control to select the specific register you want, 9866local register variables may provide a solution (@pxref{Local Register 9867Variables}). 9868 9869Input constraints can also be digits (for example, @code{"0"}). This indicates 9870that the specified input must be in the same place as the output constraint 9871at the (zero-based) index in the output constraint list. 9872When using @var{asmSymbolicName} syntax for the output operands, 9873you may use these names (enclosed in brackets @samp{[]}) instead of digits. 9874 9875@item cexpression 9876This is the C variable or expression being passed to the @code{asm} statement 9877as input. The enclosing parentheses are a required part of the syntax. 9878 9879@end table 9880 9881When the compiler selects the registers to use to represent the input 9882operands, it does not use any of the clobbered registers 9883(@pxref{Clobbers and Scratch Registers}). 9884 9885If there are no output operands but there are input operands, place two 9886consecutive colons where the output operands would go: 9887 9888@example 9889__asm__ ("some instructions" 9890 : /* No outputs. */ 9891 : "r" (Offset / 8)); 9892@end example 9893 9894@strong{Warning:} Do @emph{not} modify the contents of input-only operands 9895(except for inputs tied to outputs). The compiler assumes that on exit from 9896the @code{asm} statement these operands contain the same values as they 9897had before executing the statement. 9898It is @emph{not} possible to use clobbers 9899to inform the compiler that the values in these inputs are changing. One 9900common work-around is to tie the changing input variable to an output variable 9901that never gets used. Note, however, that if the code that follows the 9902@code{asm} statement makes no use of any of the output operands, the GCC 9903optimizers may discard the @code{asm} statement as unneeded 9904(see @ref{Volatile}). 9905 9906@code{asm} supports operand modifiers on operands (for example @samp{%k2} 9907instead of simply @samp{%2}). Typically these qualifiers are hardware 9908dependent. The list of supported modifiers for x86 is found at 9909@ref{x86Operandmodifiers,x86 Operand modifiers}. 9910 9911In this example using the fictitious @code{combine} instruction, the 9912constraint @code{"0"} for input operand 1 says that it must occupy the same 9913location as output operand 0. Only input operands may use numbers in 9914constraints, and they must each refer to an output operand. Only a number (or 9915the symbolic assembler name) in the constraint can guarantee that one operand 9916is in the same place as another. The mere fact that @code{foo} is the value of 9917both operands is not enough to guarantee that they are in the same place in 9918the generated assembler code. 9919 9920@example 9921asm ("combine %2, %0" 9922 : "=r" (foo) 9923 : "0" (foo), "g" (bar)); 9924@end example 9925 9926Here is an example using symbolic names. 9927 9928@example 9929asm ("cmoveq %1, %2, %[result]" 9930 : [result] "=r"(result) 9931 : "r" (test), "r" (new), "[result]" (old)); 9932@end example 9933 9934@anchor{Clobbers and Scratch Registers} 9935@subsubsection Clobbers and Scratch Registers 9936@cindex @code{asm} clobbers 9937@cindex @code{asm} scratch registers 9938 9939While the compiler is aware of changes to entries listed in the output 9940operands, the inline @code{asm} code may modify more than just the outputs. For 9941example, calculations may require additional registers, or the processor may 9942overwrite a register as a side effect of a particular assembler instruction. 9943In order to inform the compiler of these changes, list them in the clobber 9944list. Clobber list items are either register names or the special clobbers 9945(listed below). Each clobber list item is a string constant 9946enclosed in double quotes and separated by commas. 9947 9948Clobber descriptions may not in any way overlap with an input or output 9949operand. For example, you may not have an operand describing a register class 9950with one member when listing that register in the clobber list. Variables 9951declared to live in specific registers (@pxref{Explicit Register 9952Variables}) and used 9953as @code{asm} input or output operands must have no part mentioned in the 9954clobber description. In particular, there is no way to specify that input 9955operands get modified without also specifying them as output operands. 9956 9957When the compiler selects which registers to use to represent input and output 9958operands, it does not use any of the clobbered registers. As a result, 9959clobbered registers are available for any use in the assembler code. 9960 9961Another restriction is that the clobber list should not contain the 9962stack pointer register. This is because the compiler requires the 9963value of the stack pointer to be the same after an @code{asm} 9964statement as it was on entry to the statement. However, previous 9965versions of GCC did not enforce this rule and allowed the stack 9966pointer to appear in the list, with unclear semantics. This behavior 9967is deprecated and listing the stack pointer may become an error in 9968future versions of GCC@. 9969 9970Here is a realistic example for the VAX showing the use of clobbered 9971registers: 9972 9973@example 9974asm volatile ("movc3 %0, %1, %2" 9975 : /* No outputs. */ 9976 : "g" (from), "g" (to), "g" (count) 9977 : "r0", "r1", "r2", "r3", "r4", "r5", "memory"); 9978@end example 9979 9980Also, there are two special clobber arguments: 9981 9982@table @code 9983@item "cc" 9984The @code{"cc"} clobber indicates that the assembler code modifies the flags 9985register. On some machines, GCC represents the condition codes as a specific 9986hardware register; @code{"cc"} serves to name this register. 9987On other machines, condition code handling is different, 9988and specifying @code{"cc"} has no effect. But 9989it is valid no matter what the target. 9990 9991@item "memory" 9992The @code{"memory"} clobber tells the compiler that the assembly code 9993performs memory 9994reads or writes to items other than those listed in the input and output 9995operands (for example, accessing the memory pointed to by one of the input 9996parameters). To ensure memory contains correct values, GCC may need to flush 9997specific register values to memory before executing the @code{asm}. Further, 9998the compiler does not assume that any values read from memory before an 9999@code{asm} remain unchanged after that @code{asm}; it reloads them as 10000needed. 10001Using the @code{"memory"} clobber effectively forms a read/write 10002memory barrier for the compiler. 10003 10004Note that this clobber does not prevent the @emph{processor} from doing 10005speculative reads past the @code{asm} statement. To prevent that, you need 10006processor-specific fence instructions. 10007 10008@end table 10009 10010Flushing registers to memory has performance implications and may be 10011an issue for time-sensitive code. You can provide better information 10012to GCC to avoid this, as shown in the following examples. At a 10013minimum, aliasing rules allow GCC to know what memory @emph{doesn't} 10014need to be flushed. 10015 10016Here is a fictitious sum of squares instruction, that takes two 10017pointers to floating point values in memory and produces a floating 10018point register output. 10019Notice that @code{x}, and @code{y} both appear twice in the @code{asm} 10020parameters, once to specify memory accessed, and once to specify a 10021base register used by the @code{asm}. You won't normally be wasting a 10022register by doing this as GCC can use the same register for both 10023purposes. However, it would be foolish to use both @code{%1} and 10024@code{%3} for @code{x} in this @code{asm} and expect them to be the 10025same. In fact, @code{%3} may well not be a register. It might be a 10026symbolic memory reference to the object pointed to by @code{x}. 10027 10028@smallexample 10029asm ("sumsq %0, %1, %2" 10030 : "+f" (result) 10031 : "r" (x), "r" (y), "m" (*x), "m" (*y)); 10032@end smallexample 10033 10034Here is a fictitious @code{*z++ = *x++ * *y++} instruction. 10035Notice that the @code{x}, @code{y} and @code{z} pointer registers 10036must be specified as input/output because the @code{asm} modifies 10037them. 10038 10039@smallexample 10040asm ("vecmul %0, %1, %2" 10041 : "+r" (z), "+r" (x), "+r" (y), "=m" (*z) 10042 : "m" (*x), "m" (*y)); 10043@end smallexample 10044 10045An x86 example where the string memory argument is of unknown length. 10046 10047@smallexample 10048asm("repne scasb" 10049 : "=c" (count), "+D" (p) 10050 : "m" (*(const char (*)[]) p), "0" (-1), "a" (0)); 10051@end smallexample 10052 10053If you know the above will only be reading a ten byte array then you 10054could instead use a memory input like: 10055@code{"m" (*(const char (*)[10]) p)}. 10056 10057Here is an example of a PowerPC vector scale implemented in assembly, 10058complete with vector and condition code clobbers, and some initialized 10059offset registers that are unchanged by the @code{asm}. 10060 10061@smallexample 10062void 10063dscal (size_t n, double *x, double alpha) 10064@{ 10065 asm ("/* lots of asm here */" 10066 : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x) 10067 : "d" (alpha), "b" (32), "b" (48), "b" (64), 10068 "b" (80), "b" (96), "b" (112) 10069 : "cr0", 10070 "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39", 10071 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"); 10072@} 10073@end smallexample 10074 10075Rather than allocating fixed registers via clobbers to provide scratch 10076registers for an @code{asm} statement, an alternative is to define a 10077variable and make it an early-clobber output as with @code{a2} and 10078@code{a3} in the example below. This gives the compiler register 10079allocator more freedom. You can also define a variable and make it an 10080output tied to an input as with @code{a0} and @code{a1}, tied 10081respectively to @code{ap} and @code{lda}. Of course, with tied 10082outputs your @code{asm} can't use the input value after modifying the 10083output register since they are one and the same register. What's 10084more, if you omit the early-clobber on the output, it is possible that 10085GCC might allocate the same register to another of the inputs if GCC 10086could prove they had the same value on entry to the @code{asm}. This 10087is why @code{a1} has an early-clobber. Its tied input, @code{lda} 10088might conceivably be known to have the value 16 and without an 10089early-clobber share the same register as @code{%11}. On the other 10090hand, @code{ap} can't be the same as any of the other inputs, so an 10091early-clobber on @code{a0} is not needed. It is also not desirable in 10092this case. An early-clobber on @code{a0} would cause GCC to allocate 10093a separate register for the @code{"m" (*(const double (*)[]) ap)} 10094input. Note that tying an input to an output is the way to set up an 10095initialized temporary register modified by an @code{asm} statement. 10096An input not tied to an output is assumed by GCC to be unchanged, for 10097example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might 10098use that register in following code if the value 16 happened to be 10099needed. You can even use a normal @code{asm} output for a scratch if 10100all inputs that might share the same register are consumed before the 10101scratch is used. The VSX registers clobbered by the @code{asm} 10102statement could have used this technique except for GCC's limit on the 10103number of @code{asm} parameters. 10104 10105@smallexample 10106static void 10107dgemv_kernel_4x4 (long n, const double *ap, long lda, 10108 const double *x, double *y, double alpha) 10109@{ 10110 double *a0; 10111 double *a1; 10112 double *a2; 10113 double *a3; 10114 10115 __asm__ 10116 ( 10117 /* lots of asm here */ 10118 "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n" 10119 "#a0=%3 a1=%4 a2=%5 a3=%6" 10120 : 10121 "+m" (*(double (*)[n]) y), 10122 "+&r" (n), // 1 10123 "+b" (y), // 2 10124 "=b" (a0), // 3 10125 "=&b" (a1), // 4 10126 "=&b" (a2), // 5 10127 "=&b" (a3) // 6 10128 : 10129 "m" (*(const double (*)[n]) x), 10130 "m" (*(const double (*)[]) ap), 10131 "d" (alpha), // 9 10132 "r" (x), // 10 10133 "b" (16), // 11 10134 "3" (ap), // 12 10135 "4" (lda) // 13 10136 : 10137 "cr0", 10138 "vs32","vs33","vs34","vs35","vs36","vs37", 10139 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47" 10140 ); 10141@} 10142@end smallexample 10143 10144@anchor{GotoLabels} 10145@subsubsection Goto Labels 10146@cindex @code{asm} goto labels 10147 10148@code{asm goto} allows assembly code to jump to one or more C labels. The 10149@var{GotoLabels} section in an @code{asm goto} statement contains 10150a comma-separated 10151list of all C labels to which the assembler code may jump. GCC assumes that 10152@code{asm} execution falls through to the next statement (if this is not the 10153case, consider using the @code{__builtin_unreachable} intrinsic after the 10154@code{asm} statement). Optimization of @code{asm goto} may be improved by 10155using the @code{hot} and @code{cold} label attributes (@pxref{Label 10156Attributes}). 10157 10158An @code{asm goto} statement cannot have outputs. 10159This is due to an internal restriction of 10160the compiler: control transfer instructions cannot have outputs. 10161If the assembler code does modify anything, use the @code{"memory"} clobber 10162to force the 10163optimizers to flush all register values to memory and reload them if 10164necessary after the @code{asm} statement. 10165 10166Also note that an @code{asm goto} statement is always implicitly 10167considered volatile. 10168 10169To reference a label in the assembler template, 10170prefix it with @samp{%l} (lowercase @samp{L}) followed 10171by its (zero-based) position in @var{GotoLabels} plus the number of input 10172operands. For example, if the @code{asm} has three inputs and references two 10173labels, refer to the first label as @samp{%l3} and the second as @samp{%l4}). 10174 10175Alternately, you can reference labels using the actual C label name enclosed 10176in brackets. For example, to reference a label named @code{carry}, you can 10177use @samp{%l[carry]}. The label must still be listed in the @var{GotoLabels} 10178section when using this approach. 10179 10180Here is an example of @code{asm goto} for i386: 10181 10182@example 10183asm goto ( 10184 "btl %1, %0\n\t" 10185 "jc %l2" 10186 : /* No outputs. */ 10187 : "r" (p1), "r" (p2) 10188 : "cc" 10189 : carry); 10190 10191return 0; 10192 10193carry: 10194return 1; 10195@end example 10196 10197The following example shows an @code{asm goto} that uses a memory clobber. 10198 10199@example 10200int frob(int x) 10201@{ 10202 int y; 10203 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5" 10204 : /* No outputs. */ 10205 : "r"(x), "r"(&y) 10206 : "r5", "memory" 10207 : error); 10208 return y; 10209error: 10210 return -1; 10211@} 10212@end example 10213 10214@anchor{x86Operandmodifiers} 10215@subsubsection x86 Operand Modifiers 10216 10217References to input, output, and goto operands in the assembler template 10218of extended @code{asm} statements can use 10219modifiers to affect the way the operands are formatted in 10220the code output to the assembler. For example, the 10221following code uses the @samp{h} and @samp{b} modifiers for x86: 10222 10223@example 10224uint16_t num; 10225asm volatile ("xchg %h0, %b0" : "+a" (num) ); 10226@end example 10227 10228@noindent 10229These modifiers generate this assembler code: 10230 10231@example 10232xchg %ah, %al 10233@end example 10234 10235The rest of this discussion uses the following code for illustrative purposes. 10236 10237@example 10238int main() 10239@{ 10240 int iInt = 1; 10241 10242top: 10243 10244 asm volatile goto ("some assembler instructions here" 10245 : /* No outputs. */ 10246 : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42) 10247 : /* No clobbers. */ 10248 : top); 10249@} 10250@end example 10251 10252With no modifiers, this is what the output from the operands would be 10253for the @samp{att} and @samp{intel} dialects of assembler: 10254 10255@multitable {Operand} {$.L2} {OFFSET FLAT:.L2} 10256@headitem Operand @tab @samp{att} @tab @samp{intel} 10257@item @code{%0} 10258@tab @code{%eax} 10259@tab @code{eax} 10260@item @code{%1} 10261@tab @code{$2} 10262@tab @code{2} 10263@item @code{%3} 10264@tab @code{$.L3} 10265@tab @code{OFFSET FLAT:.L3} 10266@end multitable 10267 10268The table below shows the list of supported modifiers and their effects. 10269 10270@multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}} 10271@headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel} 10272@item @code{a} 10273@tab Print an absolute memory reference. 10274@tab @code{%A0} 10275@tab @code{*%rax} 10276@tab @code{rax} 10277@item @code{b} 10278@tab Print the QImode name of the register. 10279@tab @code{%b0} 10280@tab @code{%al} 10281@tab @code{al} 10282@item @code{c} 10283@tab Require a constant operand and print the constant expression with no punctuation. 10284@tab @code{%c1} 10285@tab @code{2} 10286@tab @code{2} 10287@item @code{E} 10288@tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit. 10289Otherwise mode is unspecified (VOIDmode). 10290@tab @code{%E1} 10291@tab @code{%(rax)} 10292@tab @code{[rax]} 10293@item @code{h} 10294@tab Print the QImode name for a ``high'' register. 10295@tab @code{%h0} 10296@tab @code{%ah} 10297@tab @code{ah} 10298@item @code{H} 10299@tab Add 8 bytes to an offsettable memory reference. Useful when accessing the 10300high 8 bytes of SSE values. For a memref in (%rax), it generates 10301@tab @code{%H0} 10302@tab @code{8(%rax)} 10303@tab @code{8[rax]} 10304@item @code{k} 10305@tab Print the SImode name of the register. 10306@tab @code{%k0} 10307@tab @code{%eax} 10308@tab @code{eax} 10309@item @code{l} 10310@tab Print the label name with no punctuation. 10311@tab @code{%l3} 10312@tab @code{.L3} 10313@tab @code{.L3} 10314@item @code{p} 10315@tab Print raw symbol name (without syntax-specific prefixes). 10316@tab @code{%p2} 10317@tab @code{42} 10318@tab @code{42} 10319@item @code{P} 10320@tab If used for a function, print the PLT suffix and generate PIC code. 10321For example, emit @code{foo@@PLT} instead of 'foo' for the function 10322foo(). If used for a constant, drop all syntax-specific prefixes and 10323issue the bare constant. See @code{p} above. 10324@item @code{q} 10325@tab Print the DImode name of the register. 10326@tab @code{%q0} 10327@tab @code{%rax} 10328@tab @code{rax} 10329@item @code{w} 10330@tab Print the HImode name of the register. 10331@tab @code{%w0} 10332@tab @code{%ax} 10333@tab @code{ax} 10334@item @code{z} 10335@tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}). 10336@tab @code{%z0} 10337@tab @code{l} 10338@tab 10339@end multitable 10340 10341@code{V} is a special modifier which prints the name of the full integer 10342register without @code{%}. 10343 10344@anchor{x86floatingpointasmoperands} 10345@subsubsection x86 Floating-Point @code{asm} Operands 10346 10347On x86 targets, there are several rules on the usage of stack-like registers 10348in the operands of an @code{asm}. These rules apply only to the operands 10349that are stack-like registers: 10350 10351@enumerate 10352@item 10353Given a set of input registers that die in an @code{asm}, it is 10354necessary to know which are implicitly popped by the @code{asm}, and 10355which must be explicitly popped by GCC@. 10356 10357An input register that is implicitly popped by the @code{asm} must be 10358explicitly clobbered, unless it is constrained to match an 10359output operand. 10360 10361@item 10362For any input register that is implicitly popped by an @code{asm}, it is 10363necessary to know how to adjust the stack to compensate for the pop. 10364If any non-popped input is closer to the top of the reg-stack than 10365the implicitly popped register, it would not be possible to know what the 10366stack looked like---it's not clear how the rest of the stack ``slides 10367up''. 10368 10369All implicitly popped input registers must be closer to the top of 10370the reg-stack than any input that is not implicitly popped. 10371 10372It is possible that if an input dies in an @code{asm}, the compiler might 10373use the input register for an output reload. Consider this example: 10374 10375@smallexample 10376asm ("foo" : "=t" (a) : "f" (b)); 10377@end smallexample 10378 10379@noindent 10380This code says that input @code{b} is not popped by the @code{asm}, and that 10381the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one 10382deeper after the @code{asm} than it was before. But, it is possible that 10383reload may think that it can use the same register for both the input and 10384the output. 10385 10386To prevent this from happening, 10387if any input operand uses the @samp{f} constraint, all output register 10388constraints must use the @samp{&} early-clobber modifier. 10389 10390The example above is correctly written as: 10391 10392@smallexample 10393asm ("foo" : "=&t" (a) : "f" (b)); 10394@end smallexample 10395 10396@item 10397Some operands need to be in particular places on the stack. All 10398output operands fall in this category---GCC has no other way to 10399know which registers the outputs appear in unless you indicate 10400this in the constraints. 10401 10402Output operands must specifically indicate which register an output 10403appears in after an @code{asm}. @samp{=f} is not allowed: the operand 10404constraints must select a class with a single register. 10405 10406@item 10407Output operands may not be ``inserted'' between existing stack registers. 10408Since no 387 opcode uses a read/write operand, all output operands 10409are dead before the @code{asm}, and are pushed by the @code{asm}. 10410It makes no sense to push anywhere but the top of the reg-stack. 10411 10412Output operands must start at the top of the reg-stack: output 10413operands may not ``skip'' a register. 10414 10415@item 10416Some @code{asm} statements may need extra stack space for internal 10417calculations. This can be guaranteed by clobbering stack registers 10418unrelated to the inputs and outputs. 10419 10420@end enumerate 10421 10422This @code{asm} 10423takes one input, which is internally popped, and produces two outputs. 10424 10425@smallexample 10426asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); 10427@end smallexample 10428 10429@noindent 10430This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode, 10431and replaces them with one output. The @code{st(1)} clobber is necessary 10432for the compiler to know that @code{fyl2xp1} pops both inputs. 10433 10434@smallexample 10435asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); 10436@end smallexample 10437 10438@lowersections 10439@include md.texi 10440@raisesections 10441 10442@node Asm Labels 10443@subsection Controlling Names Used in Assembler Code 10444@cindex assembler names for identifiers 10445@cindex names used in assembler code 10446@cindex identifiers, names in assembler code 10447 10448You can specify the name to be used in the assembler code for a C 10449function or variable by writing the @code{asm} (or @code{__asm__}) 10450keyword after the declarator. 10451It is up to you to make sure that the assembler names you choose do not 10452conflict with any other assembler symbols, or reference registers. 10453 10454@subsubheading Assembler names for data: 10455 10456This sample shows how to specify the assembler name for data: 10457 10458@smallexample 10459int foo asm ("myfoo") = 2; 10460@end smallexample 10461 10462@noindent 10463This specifies that the name to be used for the variable @code{foo} in 10464the assembler code should be @samp{myfoo} rather than the usual 10465@samp{_foo}. 10466 10467On systems where an underscore is normally prepended to the name of a C 10468variable, this feature allows you to define names for the 10469linker that do not start with an underscore. 10470 10471GCC does not support using this feature with a non-static local variable 10472since such variables do not have assembler names. If you are 10473trying to put the variable in a particular register, see 10474@ref{Explicit Register Variables}. 10475 10476@subsubheading Assembler names for functions: 10477 10478To specify the assembler name for functions, write a declaration for the 10479function before its definition and put @code{asm} there, like this: 10480 10481@smallexample 10482int func (int x, int y) asm ("MYFUNC"); 10483 10484int func (int x, int y) 10485@{ 10486 /* @r{@dots{}} */ 10487@end smallexample 10488 10489@noindent 10490This specifies that the name to be used for the function @code{func} in 10491the assembler code should be @code{MYFUNC}. 10492 10493@node Explicit Register Variables 10494@subsection Variables in Specified Registers 10495@anchor{Explicit Reg Vars} 10496@cindex explicit register variables 10497@cindex variables in specified registers 10498@cindex specified registers 10499 10500GNU C allows you to associate specific hardware registers with C 10501variables. In almost all cases, allowing the compiler to assign 10502registers produces the best code. However under certain unusual 10503circumstances, more precise control over the variable storage is 10504required. 10505 10506Both global and local variables can be associated with a register. The 10507consequences of performing this association are very different between 10508the two, as explained in the sections below. 10509 10510@menu 10511* Global Register Variables:: Variables declared at global scope. 10512* Local Register Variables:: Variables declared within a function. 10513@end menu 10514 10515@node Global Register Variables 10516@subsubsection Defining Global Register Variables 10517@anchor{Global Reg Vars} 10518@cindex global register variables 10519@cindex registers, global variables in 10520@cindex registers, global allocation 10521 10522You can define a global register variable and associate it with a specified 10523register like this: 10524 10525@smallexample 10526register int *foo asm ("r12"); 10527@end smallexample 10528 10529@noindent 10530Here @code{r12} is the name of the register that should be used. Note that 10531this is the same syntax used for defining local register variables, but for 10532a global variable the declaration appears outside a function. The 10533@code{register} keyword is required, and cannot be combined with 10534@code{static}. The register name must be a valid register name for the 10535target platform. 10536 10537Do not use type qualifiers such as @code{const} and @code{volatile}, as 10538the outcome may be contrary to expectations. In particular, using the 10539@code{volatile} qualifier does not fully prevent the compiler from 10540optimizing accesses to the register. 10541 10542Registers are a scarce resource on most systems and allowing the 10543compiler to manage their usage usually results in the best code. However, 10544under special circumstances it can make sense to reserve some globally. 10545For example this may be useful in programs such as programming language 10546interpreters that have a couple of global variables that are accessed 10547very often. 10548 10549After defining a global register variable, for the current compilation 10550unit: 10551 10552@itemize @bullet 10553@item If the register is a call-saved register, call ABI is affected: 10554the register will not be restored in function epilogue sequences after 10555the variable has been assigned. Therefore, functions cannot safely 10556return to callers that assume standard ABI. 10557@item Conversely, if the register is a call-clobbered register, making 10558calls to functions that use standard ABI may lose contents of the variable. 10559Such calls may be created by the compiler even if none are evident in 10560the original program, for example when libgcc functions are used to 10561make up for unavailable instructions. 10562@item Accesses to the variable may be optimized as usual and the register 10563remains available for allocation and use in any computations, provided that 10564observable values of the variable are not affected. 10565@item If the variable is referenced in inline assembly, the type of access 10566must be provided to the compiler via constraints (@pxref{Constraints}). 10567Accesses from basic asms are not supported. 10568@end itemize 10569 10570Note that these points @emph{only} apply to code that is compiled with the 10571definition. The behavior of code that is merely linked in (for example 10572code from libraries) is not affected. 10573 10574If you want to recompile source files that do not actually use your global 10575register variable so they do not use the specified register for any other 10576purpose, you need not actually add the global register declaration to 10577their source code. It suffices to specify the compiler option 10578@option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the 10579register. 10580 10581@subsubheading Declaring the variable 10582 10583Global register variables cannot have initial values, because an 10584executable file has no means to supply initial contents for a register. 10585 10586When selecting a register, choose one that is normally saved and 10587restored by function calls on your machine. This ensures that code 10588which is unaware of this reservation (such as library routines) will 10589restore it before returning. 10590 10591On machines with register windows, be sure to choose a global 10592register that is not affected magically by the function call mechanism. 10593 10594@subsubheading Using the variable 10595 10596@cindex @code{qsort}, and global register variables 10597When calling routines that are not aware of the reservation, be 10598cautious if those routines call back into code which uses them. As an 10599example, if you call the system library version of @code{qsort}, it may 10600clobber your registers during execution, but (if you have selected 10601appropriate registers) it will restore them before returning. However 10602it will @emph{not} restore them before calling @code{qsort}'s comparison 10603function. As a result, global values will not reliably be available to 10604the comparison function unless the @code{qsort} function itself is rebuilt. 10605 10606Similarly, it is not safe to access the global register variables from signal 10607handlers or from more than one thread of control. Unless you recompile 10608them specially for the task at hand, the system library routines may 10609temporarily use the register for other things. Furthermore, since the register 10610is not reserved exclusively for the variable, accessing it from handlers of 10611asynchronous signals may observe unrelated temporary values residing in the 10612register. 10613 10614@cindex register variable after @code{longjmp} 10615@cindex global register after @code{longjmp} 10616@cindex value after @code{longjmp} 10617@findex longjmp 10618@findex setjmp 10619On most machines, @code{longjmp} restores to each global register 10620variable the value it had at the time of the @code{setjmp}. On some 10621machines, however, @code{longjmp} does not change the value of global 10622register variables. To be portable, the function that called @code{setjmp} 10623should make other arrangements to save the values of the global register 10624variables, and to restore them in a @code{longjmp}. This way, the same 10625thing happens regardless of what @code{longjmp} does. 10626 10627@node Local Register Variables 10628@subsubsection Specifying Registers for Local Variables 10629@anchor{Local Reg Vars} 10630@cindex local variables, specifying registers 10631@cindex specifying registers for local variables 10632@cindex registers for local variables 10633 10634You can define a local register variable and associate it with a specified 10635register like this: 10636 10637@smallexample 10638register int *foo asm ("r12"); 10639@end smallexample 10640 10641@noindent 10642Here @code{r12} is the name of the register that should be used. Note 10643that this is the same syntax used for defining global register variables, 10644but for a local variable the declaration appears within a function. The 10645@code{register} keyword is required, and cannot be combined with 10646@code{static}. The register name must be a valid register name for the 10647target platform. 10648 10649Do not use type qualifiers such as @code{const} and @code{volatile}, as 10650the outcome may be contrary to expectations. In particular, when the 10651@code{const} qualifier is used, the compiler may substitute the 10652variable with its initializer in @code{asm} statements, which may cause 10653the corresponding operand to appear in a different register. 10654 10655As with global register variables, it is recommended that you choose 10656a register that is normally saved and restored by function calls on your 10657machine, so that calls to library routines will not clobber it. 10658 10659The only supported use for this feature is to specify registers 10660for input and output operands when calling Extended @code{asm} 10661(@pxref{Extended Asm}). This may be necessary if the constraints for a 10662particular machine don't provide sufficient control to select the desired 10663register. To force an operand into a register, create a local variable 10664and specify the register name after the variable's declaration. Then use 10665the local variable for the @code{asm} operand and specify any constraint 10666letter that matches the register: 10667 10668@smallexample 10669register int *p1 asm ("r0") = @dots{}; 10670register int *p2 asm ("r1") = @dots{}; 10671register int *result asm ("r0"); 10672asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 10673@end smallexample 10674 10675@emph{Warning:} In the above example, be aware that a register (for example 10676@code{r0}) can be call-clobbered by subsequent code, including function 10677calls and library calls for arithmetic operators on other variables (for 10678example the initialization of @code{p2}). In this case, use temporary 10679variables for expressions between the register assignments: 10680 10681@smallexample 10682int t1 = @dots{}; 10683register int *p1 asm ("r0") = @dots{}; 10684register int *p2 asm ("r1") = t1; 10685register int *result asm ("r0"); 10686asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 10687@end smallexample 10688 10689Defining a register variable does not reserve the register. Other than 10690when invoking the Extended @code{asm}, the contents of the specified 10691register are not guaranteed. For this reason, the following uses 10692are explicitly @emph{not} supported. If they appear to work, it is only 10693happenstance, and may stop working as intended due to (seemingly) 10694unrelated changes in surrounding code, or even minor changes in the 10695optimization of a future version of gcc: 10696 10697@itemize @bullet 10698@item Passing parameters to or from Basic @code{asm} 10699@item Passing parameters to or from Extended @code{asm} without using input 10700or output operands. 10701@item Passing parameters to or from routines written in assembler (or 10702other languages) using non-standard calling conventions. 10703@end itemize 10704 10705Some developers use Local Register Variables in an attempt to improve 10706gcc's allocation of registers, especially in large functions. In this 10707case the register name is essentially a hint to the register allocator. 10708While in some instances this can generate better code, improvements are 10709subject to the whims of the allocator/optimizers. Since there are no 10710guarantees that your improvements won't be lost, this usage of Local 10711Register Variables is discouraged. 10712 10713On the MIPS platform, there is related use for local register variables 10714with slightly different characteristics (@pxref{MIPS Coprocessors,, 10715Defining coprocessor specifics for MIPS targets, gccint, 10716GNU Compiler Collection (GCC) Internals}). 10717 10718@node Size of an asm 10719@subsection Size of an @code{asm} 10720 10721Some targets require that GCC track the size of each instruction used 10722in order to generate correct code. Because the final length of the 10723code produced by an @code{asm} statement is only known by the 10724assembler, GCC must make an estimate as to how big it will be. It 10725does this by counting the number of instructions in the pattern of the 10726@code{asm} and multiplying that by the length of the longest 10727instruction supported by that processor. (When working out the number 10728of instructions, it assumes that any occurrence of a newline or of 10729whatever statement separator character is supported by the assembler --- 10730typically @samp{;} --- indicates the end of an instruction.) 10731 10732Normally, GCC's estimate is adequate to ensure that correct 10733code is generated, but it is possible to confuse the compiler if you use 10734pseudo instructions or assembler macros that expand into multiple real 10735instructions, or if you use assembler directives that expand to more 10736space in the object file than is needed for a single instruction. 10737If this happens then the assembler may produce a diagnostic saying that 10738a label is unreachable. 10739 10740@cindex @code{asm inline} 10741This size is also used for inlining decisions. If you use @code{asm inline} 10742instead of just @code{asm}, then for inlining purposes the size of the asm 10743is taken as the minimum size, ignoring how many instructions GCC thinks it is. 10744 10745@node Alternate Keywords 10746@section Alternate Keywords 10747@cindex alternate keywords 10748@cindex keywords, alternate 10749 10750@option{-ansi} and the various @option{-std} options disable certain 10751keywords. This causes trouble when you want to use GNU C extensions, or 10752a general-purpose header file that should be usable by all programs, 10753including ISO C programs. The keywords @code{asm}, @code{typeof} and 10754@code{inline} are not available in programs compiled with 10755@option{-ansi} or @option{-std} (although @code{inline} can be used in a 10756program compiled with @option{-std=c99} or @option{-std=c11}). The 10757ISO C99 keyword 10758@code{restrict} is only available when @option{-std=gnu99} (which will 10759eventually be the default) or @option{-std=c99} (or the equivalent 10760@option{-std=iso9899:1999}), or an option for a later standard 10761version, is used. 10762 10763The way to solve these problems is to put @samp{__} at the beginning and 10764end of each problematical keyword. For example, use @code{__asm__} 10765instead of @code{asm}, and @code{__inline__} instead of @code{inline}. 10766 10767Other C compilers won't accept these alternative keywords; if you want to 10768compile with another compiler, you can define the alternate keywords as 10769macros to replace them with the customary keywords. It looks like this: 10770 10771@smallexample 10772#ifndef __GNUC__ 10773#define __asm__ asm 10774#endif 10775@end smallexample 10776 10777@findex __extension__ 10778@opindex pedantic 10779@option{-pedantic} and other options cause warnings for many GNU C extensions. 10780You can 10781prevent such warnings within one expression by writing 10782@code{__extension__} before the expression. @code{__extension__} has no 10783effect aside from this. 10784 10785@node Incomplete Enums 10786@section Incomplete @code{enum} Types 10787 10788You can define an @code{enum} tag without specifying its possible values. 10789This results in an incomplete type, much like what you get if you write 10790@code{struct foo} without describing the elements. A later declaration 10791that does specify the possible values completes the type. 10792 10793You cannot allocate variables or storage using the type while it is 10794incomplete. However, you can work with pointers to that type. 10795 10796This extension may not be very useful, but it makes the handling of 10797@code{enum} more consistent with the way @code{struct} and @code{union} 10798are handled. 10799 10800This extension is not supported by GNU C++. 10801 10802@node Function Names 10803@section Function Names as Strings 10804@cindex @code{__func__} identifier 10805@cindex @code{__FUNCTION__} identifier 10806@cindex @code{__PRETTY_FUNCTION__} identifier 10807 10808GCC provides three magic constants that hold the name of the current 10809function as a string. In C++11 and later modes, all three are treated 10810as constant expressions and can be used in @code{constexpr} constexts. 10811The first of these constants is @code{__func__}, which is part of 10812the C99 standard: 10813 10814The identifier @code{__func__} is implicitly declared by the translator 10815as if, immediately following the opening brace of each function 10816definition, the declaration 10817 10818@smallexample 10819static const char __func__[] = "function-name"; 10820@end smallexample 10821 10822@noindent 10823appeared, where function-name is the name of the lexically-enclosing 10824function. This name is the unadorned name of the function. As an 10825extension, at file (or, in C++, namespace scope), @code{__func__} 10826evaluates to the empty string. 10827 10828@code{__FUNCTION__} is another name for @code{__func__}, provided for 10829backward compatibility with old versions of GCC. 10830 10831In C, @code{__PRETTY_FUNCTION__} is yet another name for 10832@code{__func__}, except that at file (or, in C++, namespace scope), 10833it evaluates to the string @code{"top level"}. In addition, in C++, 10834@code{__PRETTY_FUNCTION__} contains the signature of the function as 10835well as its bare name. For example, this program: 10836 10837@smallexample 10838extern "C" int printf (const char *, ...); 10839 10840class a @{ 10841 public: 10842 void sub (int i) 10843 @{ 10844 printf ("__FUNCTION__ = %s\n", __FUNCTION__); 10845 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); 10846 @} 10847@}; 10848 10849int 10850main (void) 10851@{ 10852 a ax; 10853 ax.sub (0); 10854 return 0; 10855@} 10856@end smallexample 10857 10858@noindent 10859gives this output: 10860 10861@smallexample 10862__FUNCTION__ = sub 10863__PRETTY_FUNCTION__ = void a::sub(int) 10864@end smallexample 10865 10866These identifiers are variables, not preprocessor macros, and may not 10867be used to initialize @code{char} arrays or be concatenated with string 10868literals. 10869 10870@node Return Address 10871@section Getting the Return or Frame Address of a Function 10872 10873These functions may be used to get information about the callers of a 10874function. 10875 10876@deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level}) 10877This function returns the return address of the current function, or of 10878one of its callers. The @var{level} argument is number of frames to 10879scan up the call stack. A value of @code{0} yields the return address 10880of the current function, a value of @code{1} yields the return address 10881of the caller of the current function, and so forth. When inlining 10882the expected behavior is that the function returns the address of 10883the function that is returned to. To work around this behavior use 10884the @code{noinline} function attribute. 10885 10886The @var{level} argument must be a constant integer. 10887 10888On some machines it may be impossible to determine the return address of 10889any function other than the current one; in such cases, or when the top 10890of the stack has been reached, this function returns @code{0} or a 10891random value. In addition, @code{__builtin_frame_address} may be used 10892to determine if the top of the stack has been reached. 10893 10894Additional post-processing of the returned value may be needed, see 10895@code{__builtin_extract_return_addr}. 10896 10897Calling this function with a nonzero argument can have unpredictable 10898effects, including crashing the calling program. As a result, calls 10899that are considered unsafe are diagnosed when the @option{-Wframe-address} 10900option is in effect. Such calls should only be made in debugging 10901situations. 10902@end deftypefn 10903 10904@deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr}) 10905The address as returned by @code{__builtin_return_address} may have to be fed 10906through this function to get the actual encoded address. For example, on the 1090731-bit S/390 platform the highest bit has to be masked out, or on SPARC 10908platforms an offset has to be added for the true next instruction to be 10909executed. 10910 10911If no fixup is needed, this function simply passes through @var{addr}. 10912@end deftypefn 10913 10914@deftypefn {Built-in Function} {void *} __builtin_frob_return_address (void *@var{addr}) 10915This function does the reverse of @code{__builtin_extract_return_addr}. 10916@end deftypefn 10917 10918@deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level}) 10919This function is similar to @code{__builtin_return_address}, but it 10920returns the address of the function frame rather than the return address 10921of the function. Calling @code{__builtin_frame_address} with a value of 10922@code{0} yields the frame address of the current function, a value of 10923@code{1} yields the frame address of the caller of the current function, 10924and so forth. 10925 10926The frame is the area on the stack that holds local variables and saved 10927registers. The frame address is normally the address of the first word 10928pushed on to the stack by the function. However, the exact definition 10929depends upon the processor and the calling convention. If the processor 10930has a dedicated frame pointer register, and the function has a frame, 10931then @code{__builtin_frame_address} returns the value of the frame 10932pointer register. 10933 10934On some machines it may be impossible to determine the frame address of 10935any function other than the current one; in such cases, or when the top 10936of the stack has been reached, this function returns @code{0} if 10937the first frame pointer is properly initialized by the startup code. 10938 10939Calling this function with a nonzero argument can have unpredictable 10940effects, including crashing the calling program. As a result, calls 10941that are considered unsafe are diagnosed when the @option{-Wframe-address} 10942option is in effect. Such calls should only be made in debugging 10943situations. 10944@end deftypefn 10945 10946@node Vector Extensions 10947@section Using Vector Instructions through Built-in Functions 10948 10949On some targets, the instruction set contains SIMD vector instructions which 10950operate on multiple values contained in one large register at the same time. 10951For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used 10952this way. 10953 10954The first step in using these extensions is to provide the necessary data 10955types. This should be done using an appropriate @code{typedef}: 10956 10957@smallexample 10958typedef int v4si __attribute__ ((vector_size (16))); 10959@end smallexample 10960 10961@noindent 10962The @code{int} type specifies the @dfn{base type}, while the attribute specifies 10963the vector size for the variable, measured in bytes. For example, the 10964declaration above causes the compiler to set the mode for the @code{v4si} 10965type to be 16 bytes wide and divided into @code{int} sized units. For 10966a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the 10967corresponding mode of @code{foo} is @acronym{V4SI}. 10968 10969The @code{vector_size} attribute is only applicable to integral and 10970floating scalars, although arrays, pointers, and function return values 10971are allowed in conjunction with this construct. Only sizes that are 10972positive power-of-two multiples of the base type size are currently allowed. 10973 10974All the basic integer types can be used as base types, both as signed 10975and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, 10976@code{long long}. In addition, @code{float} and @code{double} can be 10977used to build floating-point vector types. 10978 10979Specifying a combination that is not valid for the current architecture 10980causes GCC to synthesize the instructions using a narrower mode. 10981For example, if you specify a variable of type @code{V4SI} and your 10982architecture does not allow for this specific SIMD type, GCC 10983produces code that uses 4 @code{SIs}. 10984 10985The types defined in this manner can be used with a subset of normal C 10986operations. Currently, GCC allows using the following operators 10987on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@. 10988 10989The operations behave like C++ @code{valarrays}. Addition is defined as 10990the addition of the corresponding elements of the operands. For 10991example, in the code below, each of the 4 elements in @var{a} is 10992added to the corresponding 4 elements in @var{b} and the resulting 10993vector is stored in @var{c}. 10994 10995@smallexample 10996typedef int v4si __attribute__ ((vector_size (16))); 10997 10998v4si a, b, c; 10999 11000c = a + b; 11001@end smallexample 11002 11003Subtraction, multiplication, division, and the logical operations 11004operate in a similar manner. Likewise, the result of using the unary 11005minus or complement operators on a vector type is a vector whose 11006elements are the negative or complemented values of the corresponding 11007elements in the operand. 11008 11009It is possible to use shifting operators @code{<<}, @code{>>} on 11010integer-type vectors. The operation is defined as following: @code{@{a0, 11011a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1, 11012@dots{}, an >> bn@}}@. Vector operands must have the same number of 11013elements. 11014 11015For convenience, it is allowed to use a binary vector operation 11016where one operand is a scalar. In that case the compiler transforms 11017the scalar operand into a vector where each element is the scalar from 11018the operation. The transformation happens only if the scalar could be 11019safely converted to the vector-element type. 11020Consider the following code. 11021 11022@smallexample 11023typedef int v4si __attribute__ ((vector_size (16))); 11024 11025v4si a, b, c; 11026long l; 11027 11028a = b + 1; /* a = b + @{1,1,1,1@}; */ 11029a = 2 * b; /* a = @{2,2,2,2@} * b; */ 11030 11031a = l + a; /* Error, cannot convert long to int. */ 11032@end smallexample 11033 11034Vectors can be subscripted as if the vector were an array with 11035the same number of elements and base type. Out of bound accesses 11036invoke undefined behavior at run time. Warnings for out of bound 11037accesses for vector subscription can be enabled with 11038@option{-Warray-bounds}. 11039 11040Vector comparison is supported with standard comparison 11041operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be 11042vector expressions of integer-type or real-type. Comparison between 11043integer-type vectors and real-type vectors are not supported. The 11044result of the comparison is a vector of the same width and number of 11045elements as the comparison operands with a signed integral element 11046type. 11047 11048Vectors are compared element-wise producing 0 when comparison is false 11049and -1 (constant of the appropriate type where all bits are set) 11050otherwise. Consider the following example. 11051 11052@smallexample 11053typedef int v4si __attribute__ ((vector_size (16))); 11054 11055v4si a = @{1,2,3,4@}; 11056v4si b = @{3,2,1,4@}; 11057v4si c; 11058 11059c = a > b; /* The result would be @{0, 0,-1, 0@} */ 11060c = a == b; /* The result would be @{0,-1, 0,-1@} */ 11061@end smallexample 11062 11063In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where 11064@code{b} and @code{c} are vectors of the same type and @code{a} is an 11065integer vector with the same number of elements of the same size as @code{b} 11066and @code{c}, computes all three arguments and creates a vector 11067@code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in 11068OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}. 11069As in the case of binary operations, this syntax is also accepted when 11070one of @code{b} or @code{c} is a scalar that is then transformed into a 11071vector. If both @code{b} and @code{c} are scalars and the type of 11072@code{true?b:c} has the same size as the element type of @code{a}, then 11073@code{b} and @code{c} are converted to a vector type whose elements have 11074this type and with the same number of elements as @code{a}. 11075 11076In C++, the logic operators @code{!, &&, ||} are available for vectors. 11077@code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to 11078@code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}. 11079For mixed operations between a scalar @code{s} and a vector @code{v}, 11080@code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is 11081short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}. 11082 11083@findex __builtin_shuffle 11084Vector shuffling is available using functions 11085@code{__builtin_shuffle (vec, mask)} and 11086@code{__builtin_shuffle (vec0, vec1, mask)}. 11087Both functions construct a permutation of elements from one or two 11088vectors and return a vector of the same type as the input vector(s). 11089The @var{mask} is an integral vector with the same width (@var{W}) 11090and element count (@var{N}) as the output vector. 11091 11092The elements of the input vectors are numbered in memory ordering of 11093@var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The 11094elements of @var{mask} are considered modulo @var{N} in the single-operand 11095case and modulo @math{2*@var{N}} in the two-operand case. 11096 11097Consider the following example, 11098 11099@smallexample 11100typedef int v4si __attribute__ ((vector_size (16))); 11101 11102v4si a = @{1,2,3,4@}; 11103v4si b = @{5,6,7,8@}; 11104v4si mask1 = @{0,1,1,3@}; 11105v4si mask2 = @{0,4,2,5@}; 11106v4si res; 11107 11108res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */ 11109res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */ 11110@end smallexample 11111 11112Note that @code{__builtin_shuffle} is intentionally semantically 11113compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions. 11114 11115You can declare variables and use them in function calls and returns, as 11116well as in assignments and some casts. You can specify a vector type as 11117a return type for a function. Vector types can also be used as function 11118arguments. It is possible to cast from one vector type to another, 11119provided they are of the same size (in fact, you can also cast vectors 11120to and from other datatypes of the same size). 11121 11122You cannot operate between vectors of different lengths or different 11123signedness without a cast. 11124 11125@findex __builtin_convertvector 11126Vector conversion is available using the 11127@code{__builtin_convertvector (vec, vectype)} 11128function. @var{vec} must be an expression with integral or floating 11129vector type and @var{vectype} an integral or floating vector type with the 11130same number of elements. The result has @var{vectype} type and value of 11131a C cast of every element of @var{vec} to the element type of @var{vectype}. 11132 11133Consider the following example, 11134@smallexample 11135typedef int v4si __attribute__ ((vector_size (16))); 11136typedef float v4sf __attribute__ ((vector_size (16))); 11137typedef double v4df __attribute__ ((vector_size (32))); 11138typedef unsigned long long v4di __attribute__ ((vector_size (32))); 11139 11140v4si a = @{1,-2,3,-4@}; 11141v4sf b = @{1.5f,-2.5f,3.f,7.f@}; 11142v4di c = @{1ULL,5ULL,0ULL,10ULL@}; 11143v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */ 11144/* Equivalent of: 11145 v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */ 11146v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */ 11147v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */ 11148v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */ 11149v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */ 11150@end smallexample 11151 11152@cindex vector types, using with x86 intrinsics 11153Sometimes it is desirable to write code using a mix of generic vector 11154operations (for clarity) and machine-specific vector intrinsics (to 11155access vector instructions that are not exposed via generic built-ins). 11156On x86, intrinsic functions for integer vectors typically use the same 11157vector type @code{__m128i} irrespective of how they interpret the vector, 11158making it necessary to cast their arguments and return values from/to 11159other vector types. In C, you can make use of a @code{union} type: 11160@c In C++ such type punning via a union is not allowed by the language 11161@smallexample 11162#include <immintrin.h> 11163 11164typedef unsigned char u8x16 __attribute__ ((vector_size (16))); 11165typedef unsigned int u32x4 __attribute__ ((vector_size (16))); 11166 11167typedef union @{ 11168 __m128i mm; 11169 u8x16 u8; 11170 u32x4 u32; 11171@} v128; 11172@end smallexample 11173 11174@noindent 11175for variables that can be used with both built-in operators and x86 11176intrinsics: 11177 11178@smallexample 11179v128 x, y = @{ 0 @}; 11180memcpy (&x, ptr, sizeof x); 11181y.u8 += 0x80; 11182x.mm = _mm_adds_epu8 (x.mm, y.mm); 11183x.u32 &= 0xffffff; 11184 11185/* Instead of a variable, a compound literal may be used to pass the 11186 return value of an intrinsic call to a function expecting the union: */ 11187v128 foo (v128); 11188x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@}); 11189@c This could be done implicitly with __attribute__((transparent_union)), 11190@c but GCC does not accept it for unions of vector types (PR 88955). 11191@end smallexample 11192 11193@node Offsetof 11194@section Support for @code{offsetof} 11195@findex __builtin_offsetof 11196 11197GCC implements for both C and C++ a syntactic extension to implement 11198the @code{offsetof} macro. 11199 11200@smallexample 11201primary: 11202 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" 11203 11204offsetof_member_designator: 11205 @code{identifier} 11206 | offsetof_member_designator "." @code{identifier} 11207 | offsetof_member_designator "[" @code{expr} "]" 11208@end smallexample 11209 11210This extension is sufficient such that 11211 11212@smallexample 11213#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) 11214@end smallexample 11215 11216@noindent 11217is a suitable definition of the @code{offsetof} macro. In C++, @var{type} 11218may be dependent. In either case, @var{member} may consist of a single 11219identifier, or a sequence of member accesses and array references. 11220 11221@node __sync Builtins 11222@section Legacy @code{__sync} Built-in Functions for Atomic Memory Access 11223 11224The following built-in functions 11225are intended to be compatible with those described 11226in the @cite{Intel Itanium Processor-specific Application Binary Interface}, 11227section 7.4. As such, they depart from normal GCC practice by not using 11228the @samp{__builtin_} prefix and also by being overloaded so that they 11229work on multiple types. 11230 11231The definition given in the Intel documentation allows only for the use of 11232the types @code{int}, @code{long}, @code{long long} or their unsigned 11233counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in 11234size other than the C type @code{_Bool} or the C++ type @code{bool}. 11235Operations on pointer arguments are performed as if the operands were 11236of the @code{uintptr_t} type. That is, they are not scaled by the size 11237of the type to which the pointer points. 11238 11239These functions are implemented in terms of the @samp{__atomic} 11240builtins (@pxref{__atomic Builtins}). They should not be used for new 11241code which should use the @samp{__atomic} builtins instead. 11242 11243Not all operations are supported by all target processors. If a particular 11244operation cannot be implemented on the target processor, a warning is 11245generated and a call to an external function is generated. The external 11246function carries the same name as the built-in version, 11247with an additional suffix 11248@samp{_@var{n}} where @var{n} is the size of the data type. 11249 11250@c ??? Should we have a mechanism to suppress this warning? This is almost 11251@c useful for implementing the operation under the control of an external 11252@c mutex. 11253 11254In most cases, these built-in functions are considered a @dfn{full barrier}. 11255That is, 11256no memory operand is moved across the operation, either forward or 11257backward. Further, instructions are issued as necessary to prevent the 11258processor from speculating loads across the operation and from queuing stores 11259after the operation. 11260 11261All of the routines are described in the Intel documentation to take 11262``an optional list of variables protected by the memory barrier''. It's 11263not clear what is meant by that; it could mean that @emph{only} the 11264listed variables are protected, or it could mean a list of additional 11265variables to be protected. The list is ignored by GCC which treats it as 11266empty. GCC interprets an empty list as meaning that all globally 11267accessible variables should be protected. 11268 11269@table @code 11270@item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...) 11271@itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...) 11272@itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...) 11273@itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...) 11274@itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...) 11275@itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...) 11276@findex __sync_fetch_and_add 11277@findex __sync_fetch_and_sub 11278@findex __sync_fetch_and_or 11279@findex __sync_fetch_and_and 11280@findex __sync_fetch_and_xor 11281@findex __sync_fetch_and_nand 11282These built-in functions perform the operation suggested by the name, and 11283returns the value that had previously been in memory. That is, operations 11284on integer operands have the following semantics. Operations on pointer 11285arguments are performed as if the operands were of the @code{uintptr_t} 11286type. That is, they are not scaled by the size of the type to which 11287the pointer points. 11288 11289@smallexample 11290@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} 11291@{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand 11292@end smallexample 11293 11294The object pointed to by the first argument must be of integer or pointer 11295type. It must not be a boolean type. 11296 11297@emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} 11298as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. 11299 11300@item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...) 11301@itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...) 11302@itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...) 11303@itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...) 11304@itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...) 11305@itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...) 11306@findex __sync_add_and_fetch 11307@findex __sync_sub_and_fetch 11308@findex __sync_or_and_fetch 11309@findex __sync_and_and_fetch 11310@findex __sync_xor_and_fetch 11311@findex __sync_nand_and_fetch 11312These built-in functions perform the operation suggested by the name, and 11313return the new value. That is, operations on integer operands have 11314the following semantics. Operations on pointer operands are performed as 11315if the operand's type were @code{uintptr_t}. 11316 11317@smallexample 11318@{ *ptr @var{op}= value; return *ptr; @} 11319@{ *ptr = ~(*ptr & value); return *ptr; @} // nand 11320@end smallexample 11321 11322The same constraints on arguments apply as for the corresponding 11323@code{__sync_op_and_fetch} built-in functions. 11324 11325@emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch} 11326as @code{*ptr = ~(*ptr & value)} instead of 11327@code{*ptr = ~*ptr & value}. 11328 11329@item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...) 11330@itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...) 11331@findex __sync_bool_compare_and_swap 11332@findex __sync_val_compare_and_swap 11333These built-in functions perform an atomic compare and swap. 11334That is, if the current 11335value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into 11336@code{*@var{ptr}}. 11337 11338The ``bool'' version returns @code{true} if the comparison is successful and 11339@var{newval} is written. The ``val'' version returns the contents 11340of @code{*@var{ptr}} before the operation. 11341 11342@item __sync_synchronize (...) 11343@findex __sync_synchronize 11344This built-in function issues a full memory barrier. 11345 11346@item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...) 11347@findex __sync_lock_test_and_set 11348This built-in function, as described by Intel, is not a traditional test-and-set 11349operation, but rather an atomic exchange operation. It writes @var{value} 11350into @code{*@var{ptr}}, and returns the previous contents of 11351@code{*@var{ptr}}. 11352 11353Many targets have only minimal support for such locks, and do not support 11354a full exchange operation. In this case, a target may support reduced 11355functionality here by which the @emph{only} valid value to store is the 11356immediate constant 1. The exact value actually stored in @code{*@var{ptr}} 11357is implementation defined. 11358 11359This built-in function is not a full barrier, 11360but rather an @dfn{acquire barrier}. 11361This means that references after the operation cannot move to (or be 11362speculated to) before the operation, but previous memory stores may not 11363be globally visible yet, and previous memory loads may not yet be 11364satisfied. 11365 11366@item void __sync_lock_release (@var{type} *ptr, ...) 11367@findex __sync_lock_release 11368This built-in function releases the lock acquired by 11369@code{__sync_lock_test_and_set}. 11370Normally this means writing the constant 0 to @code{*@var{ptr}}. 11371 11372This built-in function is not a full barrier, 11373but rather a @dfn{release barrier}. 11374This means that all previous memory stores are globally visible, and all 11375previous memory loads have been satisfied, but following memory reads 11376are not prevented from being speculated to before the barrier. 11377@end table 11378 11379@node __atomic Builtins 11380@section Built-in Functions for Memory Model Aware Atomic Operations 11381 11382The following built-in functions approximately match the requirements 11383for the C++11 memory model. They are all 11384identified by being prefixed with @samp{__atomic} and most are 11385overloaded so that they work with multiple types. 11386 11387These functions are intended to replace the legacy @samp{__sync} 11388builtins. The main difference is that the memory order that is requested 11389is a parameter to the functions. New code should always use the 11390@samp{__atomic} builtins rather than the @samp{__sync} builtins. 11391 11392Note that the @samp{__atomic} builtins assume that programs will 11393conform to the C++11 memory model. In particular, they assume 11394that programs are free of data races. See the C++11 standard for 11395detailed requirements. 11396 11397The @samp{__atomic} builtins can be used with any integral scalar or 11398pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral 11399types are also allowed if @samp{__int128} (@pxref{__int128}) is 11400supported by the architecture. 11401 11402The four non-arithmetic functions (load, store, exchange, and 11403compare_exchange) all have a generic version as well. This generic 11404version works on any data type. It uses the lock-free built-in function 11405if the specific data type size makes that possible; otherwise, an 11406external call is left to be resolved at run time. This external call is 11407the same format with the addition of a @samp{size_t} parameter inserted 11408as the first parameter indicating the size of the object being pointed to. 11409All objects must be the same size. 11410 11411There are 6 different memory orders that can be specified. These map 11412to the C++11 memory orders with the same names, see the C++11 standard 11413or the @uref{http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki 11414on atomic synchronization} for detailed definitions. Individual 11415targets may also support additional memory orders for use on specific 11416architectures. Refer to the target documentation for details of 11417these. 11418 11419An atomic operation can both constrain code motion and 11420be mapped to hardware instructions for synchronization between threads 11421(e.g., a fence). To which extent this happens is controlled by the 11422memory orders, which are listed here in approximately ascending order of 11423strength. The description of each memory order is only meant to roughly 11424illustrate the effects and is not a specification; see the C++11 11425memory model for precise semantics. 11426 11427@table @code 11428@item __ATOMIC_RELAXED 11429Implies no inter-thread ordering constraints. 11430@item __ATOMIC_CONSUME 11431This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE} 11432memory order because of a deficiency in C++11's semantics for 11433@code{memory_order_consume}. 11434@item __ATOMIC_ACQUIRE 11435Creates an inter-thread happens-before constraint from the release (or 11436stronger) semantic store to this acquire load. Can prevent hoisting 11437of code to before the operation. 11438@item __ATOMIC_RELEASE 11439Creates an inter-thread happens-before constraint to acquire (or stronger) 11440semantic loads that read from this release store. Can prevent sinking 11441of code to after the operation. 11442@item __ATOMIC_ACQ_REL 11443Combines the effects of both @code{__ATOMIC_ACQUIRE} and 11444@code{__ATOMIC_RELEASE}. 11445@item __ATOMIC_SEQ_CST 11446Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations. 11447@end table 11448 11449Note that in the C++11 memory model, @emph{fences} (e.g., 11450@samp{__atomic_thread_fence}) take effect in combination with other 11451atomic operations on specific memory locations (e.g., atomic loads); 11452operations on specific memory locations do not necessarily affect other 11453operations in the same way. 11454 11455Target architectures are encouraged to provide their own patterns for 11456each of the atomic built-in functions. If no target is provided, the original 11457non-memory model set of @samp{__sync} atomic built-in functions are 11458used, along with any required synchronization fences surrounding it in 11459order to achieve the proper behavior. Execution in this case is subject 11460to the same restrictions as those built-in functions. 11461 11462If there is no pattern or mechanism to provide a lock-free instruction 11463sequence, a call is made to an external routine with the same parameters 11464to be resolved at run time. 11465 11466When implementing patterns for these built-in functions, the memory order 11467parameter can be ignored as long as the pattern implements the most 11468restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory 11469orders execute correctly with this memory order but they may not execute as 11470efficiently as they could with a more appropriate implementation of the 11471relaxed requirements. 11472 11473Note that the C++11 standard allows for the memory order parameter to be 11474determined at run time rather than at compile time. These built-in 11475functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather 11476than invoke a runtime library call or inline a switch statement. This is 11477standard compliant, safe, and the simplest approach for now. 11478 11479The memory order parameter is a signed int, but only the lower 16 bits are 11480reserved for the memory order. The remainder of the signed int is reserved 11481for target use and should be 0. Use of the predefined atomic values 11482ensures proper usage. 11483 11484@deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memorder) 11485This built-in function implements an atomic load operation. It returns the 11486contents of @code{*@var{ptr}}. 11487 11488The valid memory order variants are 11489@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, 11490and @code{__ATOMIC_CONSUME}. 11491 11492@end deftypefn 11493 11494@deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder) 11495This is the generic version of an atomic load. It returns the 11496contents of @code{*@var{ptr}} in @code{*@var{ret}}. 11497 11498@end deftypefn 11499 11500@deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder) 11501This built-in function implements an atomic store operation. It writes 11502@code{@var{val}} into @code{*@var{ptr}}. 11503 11504The valid memory order variants are 11505@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}. 11506 11507@end deftypefn 11508 11509@deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder) 11510This is the generic version of an atomic store. It stores the value 11511of @code{*@var{val}} into @code{*@var{ptr}}. 11512 11513@end deftypefn 11514 11515@deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder) 11516This built-in function implements an atomic exchange operation. It writes 11517@var{val} into @code{*@var{ptr}}, and returns the previous contents of 11518@code{*@var{ptr}}. 11519 11520The valid memory order variants are 11521@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, 11522@code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}. 11523 11524@end deftypefn 11525 11526@deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder) 11527This is the generic version of an atomic exchange. It stores the 11528contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value 11529of @code{*@var{ptr}} is copied into @code{*@var{ret}}. 11530 11531@end deftypefn 11532 11533@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) 11534This built-in function implements an atomic compare and exchange operation. 11535This compares the contents of @code{*@var{ptr}} with the contents of 11536@code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write} 11537operation that writes @var{desired} into @code{*@var{ptr}}. If they are not 11538equal, the operation is a @emph{read} and the current contents of 11539@code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true} 11540for weak compare_exchange, which may fail spuriously, and @code{false} for 11541the strong variation, which never fails spuriously. Many targets 11542only offer the strong variation and ignore the parameter. When in doubt, use 11543the strong variation. 11544 11545If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned 11546and memory is affected according to the 11547memory order specified by @var{success_memorder}. There are no 11548restrictions on what memory order can be used here. 11549 11550Otherwise, @code{false} is returned and memory is affected according 11551to @var{failure_memorder}. This memory order cannot be 11552@code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a 11553stronger order than that specified by @var{success_memorder}. 11554 11555@end deftypefn 11556 11557@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) 11558This built-in function implements the generic version of 11559@code{__atomic_compare_exchange}. The function is virtually identical to 11560@code{__atomic_compare_exchange_n}, except the desired value is also a 11561pointer. 11562 11563@end deftypefn 11564 11565@deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder) 11566@deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder) 11567@deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder) 11568@deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder) 11569@deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder) 11570@deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder) 11571These built-in functions perform the operation suggested by the name, and 11572return the result of the operation. Operations on pointer arguments are 11573performed as if the operands were of the @code{uintptr_t} type. That is, 11574they are not scaled by the size of the type to which the pointer points. 11575 11576@smallexample 11577@{ *ptr @var{op}= val; return *ptr; @} 11578@{ *ptr = ~(*ptr & val); return *ptr; @} // nand 11579@end smallexample 11580 11581The object pointed to by the first argument must be of integer or pointer 11582type. It must not be a boolean type. All memory orders are valid. 11583 11584@end deftypefn 11585 11586@deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder) 11587@deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder) 11588@deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder) 11589@deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder) 11590@deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder) 11591@deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder) 11592These built-in functions perform the operation suggested by the name, and 11593return the value that had previously been in @code{*@var{ptr}}. Operations 11594on pointer arguments are performed as if the operands were of 11595the @code{uintptr_t} type. That is, they are not scaled by the size of 11596the type to which the pointer points. 11597 11598@smallexample 11599@{ tmp = *ptr; *ptr @var{op}= val; return tmp; @} 11600@{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand 11601@end smallexample 11602 11603The same constraints on arguments apply as for the corresponding 11604@code{__atomic_op_fetch} built-in functions. All memory orders are valid. 11605 11606@end deftypefn 11607 11608@deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memorder) 11609 11610This built-in function performs an atomic test-and-set operation on 11611the byte at @code{*@var{ptr}}. The byte is set to some implementation 11612defined nonzero ``set'' value and the return value is @code{true} if and only 11613if the previous contents were ``set''. 11614It should be only used for operands of type @code{bool} or @code{char}. For 11615other types only part of the value may be set. 11616 11617All memory orders are valid. 11618 11619@end deftypefn 11620 11621@deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memorder) 11622 11623This built-in function performs an atomic clear operation on 11624@code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0. 11625It should be only used for operands of type @code{bool} or @code{char} and 11626in conjunction with @code{__atomic_test_and_set}. 11627For other types it may only clear partially. If the type is not @code{bool} 11628prefer using @code{__atomic_store}. 11629 11630The valid memory order variants are 11631@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and 11632@code{__ATOMIC_RELEASE}. 11633 11634@end deftypefn 11635 11636@deftypefn {Built-in Function} void __atomic_thread_fence (int memorder) 11637 11638This built-in function acts as a synchronization fence between threads 11639based on the specified memory order. 11640 11641All memory orders are valid. 11642 11643@end deftypefn 11644 11645@deftypefn {Built-in Function} void __atomic_signal_fence (int memorder) 11646 11647This built-in function acts as a synchronization fence between a thread 11648and signal handlers based in the same thread. 11649 11650All memory orders are valid. 11651 11652@end deftypefn 11653 11654@deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr) 11655 11656This built-in function returns @code{true} if objects of @var{size} bytes always 11657generate lock-free atomic instructions for the target architecture. 11658@var{size} must resolve to a compile-time constant and the result also 11659resolves to a compile-time constant. 11660 11661@var{ptr} is an optional pointer to the object that may be used to determine 11662alignment. A value of 0 indicates typical alignment should be used. The 11663compiler may also ignore this parameter. 11664 11665@smallexample 11666if (__atomic_always_lock_free (sizeof (long long), 0)) 11667@end smallexample 11668 11669@end deftypefn 11670 11671@deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr) 11672 11673This built-in function returns @code{true} if objects of @var{size} bytes always 11674generate lock-free atomic instructions for the target architecture. If 11675the built-in function is not known to be lock-free, a call is made to a 11676runtime routine named @code{__atomic_is_lock_free}. 11677 11678@var{ptr} is an optional pointer to the object that may be used to determine 11679alignment. A value of 0 indicates typical alignment should be used. The 11680compiler may also ignore this parameter. 11681@end deftypefn 11682 11683@node Integer Overflow Builtins 11684@section Built-in Functions to Perform Arithmetic with Overflow Checking 11685 11686The following built-in functions allow performing simple arithmetic operations 11687together with checking whether the operations overflowed. 11688 11689@deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 11690@deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res) 11691@deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res) 11692@deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res) 11693@deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res) 11694@deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 11695@deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) 11696 11697These built-in functions promote the first two operands into infinite precision signed 11698type and perform addition on those promoted operands. The result is then 11699cast to the type the third pointer argument points to and stored there. 11700If the stored result is equal to the infinite precision result, the built-in 11701functions return @code{false}, otherwise they return @code{true}. As the addition is 11702performed in infinite signed precision, these built-in functions have fully defined 11703behavior for all argument values. 11704 11705The first built-in function allows arbitrary integral types for operands and 11706the result type must be pointer to some integral type other than enumerated or 11707boolean type, the rest of the built-in functions have explicit integer types. 11708 11709The compiler will attempt to use hardware instructions to implement 11710these built-in functions where possible, like conditional jump on overflow 11711after addition, conditional jump on carry etc. 11712 11713@end deftypefn 11714 11715@deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 11716@deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res) 11717@deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res) 11718@deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res) 11719@deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res) 11720@deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 11721@deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) 11722 11723These built-in functions are similar to the add overflow checking built-in 11724functions above, except they perform subtraction, subtract the second argument 11725from the first one, instead of addition. 11726 11727@end deftypefn 11728 11729@deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 11730@deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res) 11731@deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res) 11732@deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res) 11733@deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res) 11734@deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 11735@deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) 11736 11737These built-in functions are similar to the add overflow checking built-in 11738functions above, except they perform multiplication, instead of addition. 11739 11740@end deftypefn 11741 11742The following built-in functions allow checking if simple arithmetic operation 11743would overflow. 11744 11745@deftypefn {Built-in Function} bool __builtin_add_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c) 11746@deftypefnx {Built-in Function} bool __builtin_sub_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c) 11747@deftypefnx {Built-in Function} bool __builtin_mul_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c) 11748 11749These built-in functions are similar to @code{__builtin_add_overflow}, 11750@code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that 11751they don't store the result of the arithmetic operation anywhere and the 11752last argument is not a pointer, but some expression with integral type other 11753than enumerated or boolean type. 11754 11755The built-in functions promote the first two operands into infinite precision signed type 11756and perform addition on those promoted operands. The result is then 11757cast to the type of the third argument. If the cast result is equal to the infinite 11758precision result, the built-in functions return @code{false}, otherwise they return @code{true}. 11759The value of the third argument is ignored, just the side effects in the third argument 11760are evaluated, and no integral argument promotions are performed on the last argument. 11761If the third argument is a bit-field, the type used for the result cast has the 11762precision and signedness of the given bit-field, rather than precision and signedness 11763of the underlying type. 11764 11765For example, the following macro can be used to portably check, at 11766compile-time, whether or not adding two constant integers will overflow, 11767and perform the addition only when it is known to be safe and not to trigger 11768a @option{-Woverflow} warning. 11769 11770@smallexample 11771#define INT_ADD_OVERFLOW_P(a, b) \ 11772 __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0) 11773 11774enum @{ 11775 A = INT_MAX, B = 3, 11776 C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B, 11777 D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0) 11778@}; 11779@end smallexample 11780 11781The compiler will attempt to use hardware instructions to implement 11782these built-in functions where possible, like conditional jump on overflow 11783after addition, conditional jump on carry etc. 11784 11785@end deftypefn 11786 11787@node x86 specific memory model extensions for transactional memory 11788@section x86-Specific Memory Model Extensions for Transactional Memory 11789 11790The x86 architecture supports additional memory ordering flags 11791to mark critical sections for hardware lock elision. 11792These must be specified in addition to an existing memory order to 11793atomic intrinsics. 11794 11795@table @code 11796@item __ATOMIC_HLE_ACQUIRE 11797Start lock elision on a lock variable. 11798Memory order must be @code{__ATOMIC_ACQUIRE} or stronger. 11799@item __ATOMIC_HLE_RELEASE 11800End lock elision on a lock variable. 11801Memory order must be @code{__ATOMIC_RELEASE} or stronger. 11802@end table 11803 11804When a lock acquire fails, it is required for good performance to abort 11805the transaction quickly. This can be done with a @code{_mm_pause}. 11806 11807@smallexample 11808#include <immintrin.h> // For _mm_pause 11809 11810int lockvar; 11811 11812/* Acquire lock with lock elision */ 11813while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE)) 11814 _mm_pause(); /* Abort failed transaction */ 11815... 11816/* Free lock with lock elision */ 11817__atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE); 11818@end smallexample 11819 11820@node Object Size Checking 11821@section Object Size Checking Built-in Functions 11822@findex __builtin_object_size 11823@findex __builtin___memcpy_chk 11824@findex __builtin___mempcpy_chk 11825@findex __builtin___memmove_chk 11826@findex __builtin___memset_chk 11827@findex __builtin___strcpy_chk 11828@findex __builtin___stpcpy_chk 11829@findex __builtin___strncpy_chk 11830@findex __builtin___strcat_chk 11831@findex __builtin___strncat_chk 11832@findex __builtin___sprintf_chk 11833@findex __builtin___snprintf_chk 11834@findex __builtin___vsprintf_chk 11835@findex __builtin___vsnprintf_chk 11836@findex __builtin___printf_chk 11837@findex __builtin___vprintf_chk 11838@findex __builtin___fprintf_chk 11839@findex __builtin___vfprintf_chk 11840 11841GCC implements a limited buffer overflow protection mechanism that can 11842prevent some buffer overflow attacks by determining the sizes of objects 11843into which data is about to be written and preventing the writes when 11844the size isn't sufficient. The built-in functions described below yield 11845the best results when used together and when optimization is enabled. 11846For example, to detect object sizes across function boundaries or to 11847follow pointer assignments through non-trivial control flow they rely 11848on various optimization passes enabled with @option{-O2}. However, to 11849a limited extent, they can be used without optimization as well. 11850 11851@deftypefn {Built-in Function} {size_t} __builtin_object_size (const void * @var{ptr}, int @var{type}) 11852is a built-in construct that returns a constant number of bytes from 11853@var{ptr} to the end of the object @var{ptr} pointer points to 11854(if known at compile time). To determine the sizes of dynamically allocated 11855objects the function relies on the allocation functions called to obtain 11856the storage to be declared with the @code{alloc_size} attribute (@pxref{Common 11857Function Attributes}). @code{__builtin_object_size} never evaluates 11858its arguments for side effects. If there are any side effects in them, it 11859returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 11860for @var{type} 2 or 3. If there are multiple objects @var{ptr} can 11861point to and all of them are known at compile time, the returned number 11862is the maximum of remaining byte counts in those objects if @var{type} & 2 is 118630 and minimum if nonzero. If it is not possible to determine which objects 11864@var{ptr} points to at compile time, @code{__builtin_object_size} should 11865return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 11866for @var{type} 2 or 3. 11867 11868@var{type} is an integer constant from 0 to 3. If the least significant 11869bit is clear, objects are whole variables, if it is set, a closest 11870surrounding subobject is considered the object a pointer points to. 11871The second bit determines if maximum or minimum of remaining bytes 11872is computed. 11873 11874@smallexample 11875struct V @{ char buf1[10]; int b; char buf2[10]; @} var; 11876char *p = &var.buf1[1], *q = &var.b; 11877 11878/* Here the object p points to is var. */ 11879assert (__builtin_object_size (p, 0) == sizeof (var) - 1); 11880/* The subobject p points to is var.buf1. */ 11881assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); 11882/* The object q points to is var. */ 11883assert (__builtin_object_size (q, 0) 11884 == (char *) (&var + 1) - (char *) &var.b); 11885/* The subobject q points to is var.b. */ 11886assert (__builtin_object_size (q, 1) == sizeof (var.b)); 11887@end smallexample 11888@end deftypefn 11889 11890There are built-in functions added for many common string operation 11891functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk} 11892built-in is provided. This built-in has an additional last argument, 11893which is the number of bytes remaining in the object the @var{dest} 11894argument points to or @code{(size_t) -1} if the size is not known. 11895 11896The built-in functions are optimized into the normal string functions 11897like @code{memcpy} if the last argument is @code{(size_t) -1} or if 11898it is known at compile time that the destination object will not 11899be overflowed. If the compiler can determine at compile time that the 11900object will always be overflowed, it issues a warning. 11901 11902The intended use can be e.g.@: 11903 11904@smallexample 11905#undef memcpy 11906#define bos0(dest) __builtin_object_size (dest, 0) 11907#define memcpy(dest, src, n) \ 11908 __builtin___memcpy_chk (dest, src, n, bos0 (dest)) 11909 11910char *volatile p; 11911char buf[10]; 11912/* It is unknown what object p points to, so this is optimized 11913 into plain memcpy - no checking is possible. */ 11914memcpy (p, "abcde", n); 11915/* Destination is known and length too. It is known at compile 11916 time there will be no overflow. */ 11917memcpy (&buf[5], "abcde", 5); 11918/* Destination is known, but the length is not known at compile time. 11919 This will result in __memcpy_chk call that can check for overflow 11920 at run time. */ 11921memcpy (&buf[5], "abcde", n); 11922/* Destination is known and it is known at compile time there will 11923 be overflow. There will be a warning and __memcpy_chk call that 11924 will abort the program at run time. */ 11925memcpy (&buf[6], "abcde", 5); 11926@end smallexample 11927 11928Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, 11929@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, 11930@code{strcat} and @code{strncat}. 11931 11932There are also checking built-in functions for formatted output functions. 11933@smallexample 11934int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...); 11935int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os, 11936 const char *fmt, ...); 11937int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt, 11938 va_list ap); 11939int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os, 11940 const char *fmt, va_list ap); 11941@end smallexample 11942 11943The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} 11944etc.@: functions and can contain implementation specific flags on what 11945additional security measures the checking function might take, such as 11946handling @code{%n} differently. 11947 11948The @var{os} argument is the object size @var{s} points to, like in the 11949other built-in functions. There is a small difference in the behavior 11950though, if @var{os} is @code{(size_t) -1}, the built-in functions are 11951optimized into the non-checking functions only if @var{flag} is 0, otherwise 11952the checking function is called with @var{os} argument set to 11953@code{(size_t) -1}. 11954 11955In addition to this, there are checking built-in functions 11956@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, 11957@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. 11958These have just one additional argument, @var{flag}, right before 11959format string @var{fmt}. If the compiler is able to optimize them to 11960@code{fputc} etc.@: functions, it does, otherwise the checking function 11961is called and the @var{flag} argument passed to it. 11962 11963@node Other Builtins 11964@section Other Built-in Functions Provided by GCC 11965@cindex built-in functions 11966@findex __builtin_alloca 11967@findex __builtin_alloca_with_align 11968@findex __builtin_alloca_with_align_and_max 11969@findex __builtin_call_with_static_chain 11970@findex __builtin_extend_pointer 11971@findex __builtin_fpclassify 11972@findex __builtin_has_attribute 11973@findex __builtin_isfinite 11974@findex __builtin_isnormal 11975@findex __builtin_isgreater 11976@findex __builtin_isgreaterequal 11977@findex __builtin_isinf_sign 11978@findex __builtin_isless 11979@findex __builtin_islessequal 11980@findex __builtin_islessgreater 11981@findex __builtin_isunordered 11982@findex __builtin_object_size 11983@findex __builtin_powi 11984@findex __builtin_powif 11985@findex __builtin_powil 11986@findex __builtin_speculation_safe_value 11987@findex _Exit 11988@findex _exit 11989@findex abort 11990@findex abs 11991@findex acos 11992@findex acosf 11993@findex acosh 11994@findex acoshf 11995@findex acoshl 11996@findex acosl 11997@findex alloca 11998@findex asin 11999@findex asinf 12000@findex asinh 12001@findex asinhf 12002@findex asinhl 12003@findex asinl 12004@findex atan 12005@findex atan2 12006@findex atan2f 12007@findex atan2l 12008@findex atanf 12009@findex atanh 12010@findex atanhf 12011@findex atanhl 12012@findex atanl 12013@findex bcmp 12014@findex bzero 12015@findex cabs 12016@findex cabsf 12017@findex cabsl 12018@findex cacos 12019@findex cacosf 12020@findex cacosh 12021@findex cacoshf 12022@findex cacoshl 12023@findex cacosl 12024@findex calloc 12025@findex carg 12026@findex cargf 12027@findex cargl 12028@findex casin 12029@findex casinf 12030@findex casinh 12031@findex casinhf 12032@findex casinhl 12033@findex casinl 12034@findex catan 12035@findex catanf 12036@findex catanh 12037@findex catanhf 12038@findex catanhl 12039@findex catanl 12040@findex cbrt 12041@findex cbrtf 12042@findex cbrtl 12043@findex ccos 12044@findex ccosf 12045@findex ccosh 12046@findex ccoshf 12047@findex ccoshl 12048@findex ccosl 12049@findex ceil 12050@findex ceilf 12051@findex ceill 12052@findex cexp 12053@findex cexpf 12054@findex cexpl 12055@findex cimag 12056@findex cimagf 12057@findex cimagl 12058@findex clog 12059@findex clogf 12060@findex clogl 12061@findex clog10 12062@findex clog10f 12063@findex clog10l 12064@findex conj 12065@findex conjf 12066@findex conjl 12067@findex copysign 12068@findex copysignf 12069@findex copysignl 12070@findex cos 12071@findex cosf 12072@findex cosh 12073@findex coshf 12074@findex coshl 12075@findex cosl 12076@findex cpow 12077@findex cpowf 12078@findex cpowl 12079@findex cproj 12080@findex cprojf 12081@findex cprojl 12082@findex creal 12083@findex crealf 12084@findex creall 12085@findex csin 12086@findex csinf 12087@findex csinh 12088@findex csinhf 12089@findex csinhl 12090@findex csinl 12091@findex csqrt 12092@findex csqrtf 12093@findex csqrtl 12094@findex ctan 12095@findex ctanf 12096@findex ctanh 12097@findex ctanhf 12098@findex ctanhl 12099@findex ctanl 12100@findex dcgettext 12101@findex dgettext 12102@findex drem 12103@findex dremf 12104@findex dreml 12105@findex erf 12106@findex erfc 12107@findex erfcf 12108@findex erfcl 12109@findex erff 12110@findex erfl 12111@findex exit 12112@findex exp 12113@findex exp10 12114@findex exp10f 12115@findex exp10l 12116@findex exp2 12117@findex exp2f 12118@findex exp2l 12119@findex expf 12120@findex expl 12121@findex expm1 12122@findex expm1f 12123@findex expm1l 12124@findex fabs 12125@findex fabsf 12126@findex fabsl 12127@findex fdim 12128@findex fdimf 12129@findex fdiml 12130@findex ffs 12131@findex floor 12132@findex floorf 12133@findex floorl 12134@findex fma 12135@findex fmaf 12136@findex fmal 12137@findex fmax 12138@findex fmaxf 12139@findex fmaxl 12140@findex fmin 12141@findex fminf 12142@findex fminl 12143@findex fmod 12144@findex fmodf 12145@findex fmodl 12146@findex fprintf 12147@findex fprintf_unlocked 12148@findex fputs 12149@findex fputs_unlocked 12150@findex frexp 12151@findex frexpf 12152@findex frexpl 12153@findex fscanf 12154@findex gamma 12155@findex gammaf 12156@findex gammal 12157@findex gamma_r 12158@findex gammaf_r 12159@findex gammal_r 12160@findex gettext 12161@findex hypot 12162@findex hypotf 12163@findex hypotl 12164@findex ilogb 12165@findex ilogbf 12166@findex ilogbl 12167@findex imaxabs 12168@findex index 12169@findex isalnum 12170@findex isalpha 12171@findex isascii 12172@findex isblank 12173@findex iscntrl 12174@findex isdigit 12175@findex isgraph 12176@findex islower 12177@findex isprint 12178@findex ispunct 12179@findex isspace 12180@findex isupper 12181@findex iswalnum 12182@findex iswalpha 12183@findex iswblank 12184@findex iswcntrl 12185@findex iswdigit 12186@findex iswgraph 12187@findex iswlower 12188@findex iswprint 12189@findex iswpunct 12190@findex iswspace 12191@findex iswupper 12192@findex iswxdigit 12193@findex isxdigit 12194@findex j0 12195@findex j0f 12196@findex j0l 12197@findex j1 12198@findex j1f 12199@findex j1l 12200@findex jn 12201@findex jnf 12202@findex jnl 12203@findex labs 12204@findex ldexp 12205@findex ldexpf 12206@findex ldexpl 12207@findex lgamma 12208@findex lgammaf 12209@findex lgammal 12210@findex lgamma_r 12211@findex lgammaf_r 12212@findex lgammal_r 12213@findex llabs 12214@findex llrint 12215@findex llrintf 12216@findex llrintl 12217@findex llround 12218@findex llroundf 12219@findex llroundl 12220@findex log 12221@findex log10 12222@findex log10f 12223@findex log10l 12224@findex log1p 12225@findex log1pf 12226@findex log1pl 12227@findex log2 12228@findex log2f 12229@findex log2l 12230@findex logb 12231@findex logbf 12232@findex logbl 12233@findex logf 12234@findex logl 12235@findex lrint 12236@findex lrintf 12237@findex lrintl 12238@findex lround 12239@findex lroundf 12240@findex lroundl 12241@findex malloc 12242@findex memchr 12243@findex memcmp 12244@findex memcpy 12245@findex mempcpy 12246@findex memset 12247@findex modf 12248@findex modff 12249@findex modfl 12250@findex nearbyint 12251@findex nearbyintf 12252@findex nearbyintl 12253@findex nextafter 12254@findex nextafterf 12255@findex nextafterl 12256@findex nexttoward 12257@findex nexttowardf 12258@findex nexttowardl 12259@findex pow 12260@findex pow10 12261@findex pow10f 12262@findex pow10l 12263@findex powf 12264@findex powl 12265@findex printf 12266@findex printf_unlocked 12267@findex putchar 12268@findex puts 12269@findex remainder 12270@findex remainderf 12271@findex remainderl 12272@findex remquo 12273@findex remquof 12274@findex remquol 12275@findex rindex 12276@findex rint 12277@findex rintf 12278@findex rintl 12279@findex round 12280@findex roundf 12281@findex roundl 12282@findex scalb 12283@findex scalbf 12284@findex scalbl 12285@findex scalbln 12286@findex scalblnf 12287@findex scalblnf 12288@findex scalbn 12289@findex scalbnf 12290@findex scanfnl 12291@findex signbit 12292@findex signbitf 12293@findex signbitl 12294@findex signbitd32 12295@findex signbitd64 12296@findex signbitd128 12297@findex significand 12298@findex significandf 12299@findex significandl 12300@findex sin 12301@findex sincos 12302@findex sincosf 12303@findex sincosl 12304@findex sinf 12305@findex sinh 12306@findex sinhf 12307@findex sinhl 12308@findex sinl 12309@findex snprintf 12310@findex sprintf 12311@findex sqrt 12312@findex sqrtf 12313@findex sqrtl 12314@findex sscanf 12315@findex stpcpy 12316@findex stpncpy 12317@findex strcasecmp 12318@findex strcat 12319@findex strchr 12320@findex strcmp 12321@findex strcpy 12322@findex strcspn 12323@findex strdup 12324@findex strfmon 12325@findex strftime 12326@findex strlen 12327@findex strncasecmp 12328@findex strncat 12329@findex strncmp 12330@findex strncpy 12331@findex strndup 12332@findex strnlen 12333@findex strpbrk 12334@findex strrchr 12335@findex strspn 12336@findex strstr 12337@findex tan 12338@findex tanf 12339@findex tanh 12340@findex tanhf 12341@findex tanhl 12342@findex tanl 12343@findex tgamma 12344@findex tgammaf 12345@findex tgammal 12346@findex toascii 12347@findex tolower 12348@findex toupper 12349@findex towlower 12350@findex towupper 12351@findex trunc 12352@findex truncf 12353@findex truncl 12354@findex vfprintf 12355@findex vfscanf 12356@findex vprintf 12357@findex vscanf 12358@findex vsnprintf 12359@findex vsprintf 12360@findex vsscanf 12361@findex y0 12362@findex y0f 12363@findex y0l 12364@findex y1 12365@findex y1f 12366@findex y1l 12367@findex yn 12368@findex ynf 12369@findex ynl 12370 12371GCC provides a large number of built-in functions other than the ones 12372mentioned above. Some of these are for internal use in the processing 12373of exceptions or variable-length argument lists and are not 12374documented here because they may change from time to time; we do not 12375recommend general use of these functions. 12376 12377The remaining functions are provided for optimization purposes. 12378 12379With the exception of built-ins that have library equivalents such as 12380the standard C library functions discussed below, or that expand to 12381library calls, GCC built-in functions are always expanded inline and 12382thus do not have corresponding entry points and their address cannot 12383be obtained. Attempting to use them in an expression other than 12384a function call results in a compile-time error. 12385 12386@opindex fno-builtin 12387GCC includes built-in versions of many of the functions in the standard 12388C library. These functions come in two forms: one whose names start with 12389the @code{__builtin_} prefix, and the other without. Both forms have the 12390same type (including prototype), the same address (when their address is 12391taken), and the same meaning as the C library functions even if you specify 12392the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these 12393functions are only optimized in certain cases; if they are not optimized in 12394a particular case, a call to the library function is emitted. 12395 12396@opindex ansi 12397@opindex std 12398Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, 12399@option{-std=c99} or @option{-std=c11}), the functions 12400@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, 12401@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, 12402@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, 12403@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, 12404@code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma}, 12405@code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext}, 12406@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, 12407@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, 12408@code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy}, 12409@code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, 12410@code{rindex}, @code{scalbf}, @code{scalbl}, @code{scalb}, 12411@code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, 12412@code{signbitd64}, @code{signbitd128}, @code{significandf}, 12413@code{significandl}, @code{significand}, @code{sincosf}, 12414@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, 12415@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, 12416@code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l}, 12417@code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and 12418@code{yn} 12419may be handled as built-in functions. 12420All these functions have corresponding versions 12421prefixed with @code{__builtin_}, which may be used even in strict C90 12422mode. 12423 12424The ISO C99 functions 12425@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, 12426@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, 12427@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, 12428@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, 12429@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, 12430@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, 12431@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, 12432@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, 12433@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, 12434@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, 12435@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, 12436@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, 12437@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, 12438@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, 12439@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, 12440@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, 12441@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, 12442@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, 12443@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, 12444@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, 12445@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, 12446@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, 12447@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, 12448@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, 12449@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, 12450@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, 12451@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, 12452@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, 12453@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, 12454@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, 12455@code{nextafterf}, @code{nextafterl}, @code{nextafter}, 12456@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, 12457@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, 12458@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, 12459@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, 12460@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, 12461@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, 12462@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, 12463@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} 12464are handled as built-in functions 12465except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). 12466 12467There are also built-in versions of the ISO C99 functions 12468@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, 12469@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, 12470@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, 12471@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, 12472@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, 12473@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, 12474@code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf}, 12475@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, 12476@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} 12477that are recognized in any mode since ISO C90 reserves these names for 12478the purpose to which ISO C99 puts them. All these functions have 12479corresponding versions prefixed with @code{__builtin_}. 12480 12481There are also built-in functions @code{__builtin_fabsf@var{n}}, 12482@code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and 12483@code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3 12484functions @code{fabsf@var{n}}, @code{fabsf@var{n}x}, 12485@code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported 12486types @code{_Float@var{n}} and @code{_Float@var{n}x}. 12487 12488There are also GNU extension functions @code{clog10}, @code{clog10f} and 12489@code{clog10l} which names are reserved by ISO C99 for future use. 12490All these functions have versions prefixed with @code{__builtin_}. 12491 12492The ISO C94 functions 12493@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, 12494@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, 12495@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and 12496@code{towupper} 12497are handled as built-in functions 12498except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). 12499 12500The ISO C90 functions 12501@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, 12502@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, 12503@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, 12504@code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf}, 12505@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, 12506@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, 12507@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, 12508@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, 12509@code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy}, 12510@code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar}, 12511@code{puts}, @code{scanf}, @code{sinh}, @code{sin}, @code{snprintf}, 12512@code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat}, 12513@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, 12514@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, 12515@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, 12516@code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf} 12517are all recognized as built-in functions unless 12518@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} 12519is specified for an individual function). All of these functions have 12520corresponding versions prefixed with @code{__builtin_}. 12521 12522GCC provides built-in versions of the ISO C99 floating-point comparison 12523macros that avoid raising exceptions for unordered operands. They have 12524the same names as the standard macros ( @code{isgreater}, 12525@code{isgreaterequal}, @code{isless}, @code{islessequal}, 12526@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} 12527prefixed. We intend for a library implementor to be able to simply 12528@code{#define} each standard macro to its built-in equivalent. 12529In the same fashion, GCC provides @code{fpclassify}, @code{isfinite}, 12530@code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with 12531@code{__builtin_} prefixed. The @code{isinf} and @code{isnan} 12532built-in functions appear both with and without the @code{__builtin_} prefix. 12533 12534@deftypefn {Built-in Function} void *__builtin_alloca (size_t size) 12535The @code{__builtin_alloca} function must be called at block scope. 12536The function allocates an object @var{size} bytes large on the stack 12537of the calling function. The object is aligned on the default stack 12538alignment boundary for the target determined by the 12539@code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca} 12540function returns a pointer to the first byte of the allocated object. 12541The lifetime of the allocated object ends just before the calling 12542function returns to its caller. This is so even when 12543@code{__builtin_alloca} is called within a nested block. 12544 12545For example, the following function allocates eight objects of @code{n} 12546bytes each on the stack, storing a pointer to each in consecutive elements 12547of the array @code{a}. It then passes the array to function @code{g} 12548which can safely use the storage pointed to by each of the array elements. 12549 12550@smallexample 12551void f (unsigned n) 12552@{ 12553 void *a [8]; 12554 for (int i = 0; i != 8; ++i) 12555 a [i] = __builtin_alloca (n); 12556 12557 g (a, n); // @r{safe} 12558@} 12559@end smallexample 12560 12561Since the @code{__builtin_alloca} function doesn't validate its argument 12562it is the responsibility of its caller to make sure the argument doesn't 12563cause it to exceed the stack size limit. 12564The @code{__builtin_alloca} function is provided to make it possible to 12565allocate on the stack arrays of bytes with an upper bound that may be 12566computed at run time. Since C99 Variable Length Arrays offer 12567similar functionality under a portable, more convenient, and safer 12568interface they are recommended instead, in both C99 and C++ programs 12569where GCC provides them as an extension. 12570@xref{Variable Length}, for details. 12571 12572@end deftypefn 12573 12574@deftypefn {Built-in Function} void *__builtin_alloca_with_align (size_t size, size_t alignment) 12575The @code{__builtin_alloca_with_align} function must be called at block 12576scope. The function allocates an object @var{size} bytes large on 12577the stack of the calling function. The allocated object is aligned on 12578the boundary specified by the argument @var{alignment} whose unit is given 12579in bits (not bytes). The @var{size} argument must be positive and not 12580exceed the stack size limit. The @var{alignment} argument must be a constant 12581integer expression that evaluates to a power of 2 greater than or equal to 12582@code{CHAR_BIT} and less than some unspecified maximum. Invocations 12583with other values are rejected with an error indicating the valid bounds. 12584The function returns a pointer to the first byte of the allocated object. 12585The lifetime of the allocated object ends at the end of the block in which 12586the function was called. The allocated storage is released no later than 12587just before the calling function returns to its caller, but may be released 12588at the end of the block in which the function was called. 12589 12590For example, in the following function the call to @code{g} is unsafe 12591because when @code{overalign} is non-zero, the space allocated by 12592@code{__builtin_alloca_with_align} may have been released at the end 12593of the @code{if} statement in which it was called. 12594 12595@smallexample 12596void f (unsigned n, bool overalign) 12597@{ 12598 void *p; 12599 if (overalign) 12600 p = __builtin_alloca_with_align (n, 64 /* bits */); 12601 else 12602 p = __builtin_alloc (n); 12603 12604 g (p, n); // @r{unsafe} 12605@} 12606@end smallexample 12607 12608Since the @code{__builtin_alloca_with_align} function doesn't validate its 12609@var{size} argument it is the responsibility of its caller to make sure 12610the argument doesn't cause it to exceed the stack size limit. 12611The @code{__builtin_alloca_with_align} function is provided to make 12612it possible to allocate on the stack overaligned arrays of bytes with 12613an upper bound that may be computed at run time. Since C99 12614Variable Length Arrays offer the same functionality under 12615a portable, more convenient, and safer interface they are recommended 12616instead, in both C99 and C++ programs where GCC provides them as 12617an extension. @xref{Variable Length}, for details. 12618 12619@end deftypefn 12620 12621@deftypefn {Built-in Function} void *__builtin_alloca_with_align_and_max (size_t size, size_t alignment, size_t max_size) 12622Similar to @code{__builtin_alloca_with_align} but takes an extra argument 12623specifying an upper bound for @var{size} in case its value cannot be computed 12624at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage} 12625and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer 12626expression, it has no effect on code generation and no attempt is made to 12627check its compatibility with @var{size}. 12628 12629@end deftypefn 12630 12631@deftypefn {Built-in Function} bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute}) 12632The @code{__builtin_has_attribute} function evaluates to an integer constant 12633expression equal to @code{true} if the symbol or type referenced by 12634the @var{type-or-expression} argument has been declared with 12635the @var{attribute} referenced by the second argument. For 12636an @var{type-or-expression} argument that does not reference a symbol, 12637since attributes do not apply to expressions the built-in consider 12638the type of the argument. Neither argument is evaluated. 12639The @var{type-or-expression} argument is subject to the same 12640restrictions as the argument to @code{typeof} (@pxref{Typeof}). The 12641@var{attribute} argument is an attribute name optionally followed by 12642a comma-separated list of arguments enclosed in parentheses. Both forms 12643of attribute names---with and without double leading and trailing 12644underscores---are recognized. @xref{Attribute Syntax}, for details. 12645When no attribute arguments are specified for an attribute that expects 12646one or more arguments the function returns @code{true} if 12647@var{type-or-expression} has been declared with the attribute regardless 12648of the attribute argument values. Arguments provided for an attribute 12649that expects some are validated and matched up to the provided number. 12650The function returns @code{true} if all provided arguments match. For 12651example, the first call to the function below evaluates to @code{true} 12652because @code{x} is declared with the @code{aligned} attribute but 12653the second call evaluates to @code{false} because @code{x} is declared 12654@code{aligned (8)} and not @code{aligned (4)}. 12655 12656@smallexample 12657__attribute__ ((aligned (8))) int x; 12658_Static_assert (__builtin_has_attribute (x, aligned), "aligned"); 12659_Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)"); 12660@end smallexample 12661 12662Due to a limitation the @code{__builtin_has_attribute} function returns 12663@code{false} for the @code{mode} attribute even if the type or variable 12664referenced by the @var{type-or-expression} argument was declared with one. 12665The function is also not supported with labels, and in C with enumerators. 12666 12667Note that unlike the @code{__has_attribute} preprocessor operator which 12668is suitable for use in @code{#if} preprocessing directives 12669@code{__builtin_has_attribute} is an intrinsic function that is not 12670recognized in such contexts. 12671 12672@end deftypefn 12673 12674@deftypefn {Built-in Function} @var{type} __builtin_speculation_safe_value (@var{type} val, @var{type} failval) 12675 12676This built-in function can be used to help mitigate against unsafe 12677speculative execution. @var{type} may be any integral type or any 12678pointer type. 12679 12680@enumerate 12681@item 12682If the CPU is not speculatively executing the code, then @var{val} 12683is returned. 12684@item 12685If the CPU is executing speculatively then either: 12686@itemize 12687@item 12688The function may cause execution to pause until it is known that the 12689code is no-longer being executed speculatively (in which case 12690@var{val} can be returned, as above); or 12691@item 12692The function may use target-dependent speculation tracking state to cause 12693@var{failval} to be returned when it is known that speculative 12694execution has incorrectly predicted a conditional branch operation. 12695@end itemize 12696@end enumerate 12697 12698The second argument, @var{failval}, is optional and defaults to zero 12699if omitted. 12700 12701GCC defines the preprocessor macro 12702@code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been 12703updated to support this builtin. 12704 12705The built-in function can be used where a variable appears to be used in a 12706safe way, but the CPU, due to speculative execution may temporarily ignore 12707the bounds checks. Consider, for example, the following function: 12708 12709@smallexample 12710int array[500]; 12711int f (unsigned untrusted_index) 12712@{ 12713 if (untrusted_index < 500) 12714 return array[untrusted_index]; 12715 return 0; 12716@} 12717@end smallexample 12718 12719If the function is called repeatedly with @code{untrusted_index} less 12720than the limit of 500, then a branch predictor will learn that the 12721block of code that returns a value stored in @code{array} will be 12722executed. If the function is subsequently called with an 12723out-of-range value it will still try to execute that block of code 12724first until the CPU determines that the prediction was incorrect 12725(the CPU will unwind any incorrect operations at that point). 12726However, depending on how the result of the function is used, it might be 12727possible to leave traces in the cache that can reveal what was stored 12728at the out-of-bounds location. The built-in function can be used to 12729provide some protection against leaking data in this way by changing 12730the code to: 12731 12732@smallexample 12733int array[500]; 12734int f (unsigned untrusted_index) 12735@{ 12736 if (untrusted_index < 500) 12737 return array[__builtin_speculation_safe_value (untrusted_index)]; 12738 return 0; 12739@} 12740@end smallexample 12741 12742The built-in function will either cause execution to stall until the 12743conditional branch has been fully resolved, or it may permit 12744speculative execution to continue, but using 0 instead of 12745@code{untrusted_value} if that exceeds the limit. 12746 12747If accessing any memory location is potentially unsafe when speculative 12748execution is incorrect, then the code can be rewritten as 12749 12750@smallexample 12751int array[500]; 12752int f (unsigned untrusted_index) 12753@{ 12754 if (untrusted_index < 500) 12755 return *__builtin_speculation_safe_value (&array[untrusted_index], NULL); 12756 return 0; 12757@} 12758@end smallexample 12759 12760which will cause a @code{NULL} pointer to be used for the unsafe case. 12761 12762@end deftypefn 12763 12764@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2}) 12765 12766You can use the built-in function @code{__builtin_types_compatible_p} to 12767determine whether two types are the same. 12768 12769This built-in function returns 1 if the unqualified versions of the 12770types @var{type1} and @var{type2} (which are types, not expressions) are 12771compatible, 0 otherwise. The result of this built-in function can be 12772used in integer constant expressions. 12773 12774This built-in function ignores top level qualifiers (e.g., @code{const}, 12775@code{volatile}). For example, @code{int} is equivalent to @code{const 12776int}. 12777 12778The type @code{int[]} and @code{int[5]} are compatible. On the other 12779hand, @code{int} and @code{char *} are not compatible, even if the size 12780of their types, on the particular architecture are the same. Also, the 12781amount of pointer indirection is taken into account when determining 12782similarity. Consequently, @code{short *} is not similar to 12783@code{short **}. Furthermore, two types that are typedefed are 12784considered compatible if their underlying types are compatible. 12785 12786An @code{enum} type is not considered to be compatible with another 12787@code{enum} type even if both are compatible with the same integer 12788type; this is what the C standard specifies. 12789For example, @code{enum @{foo, bar@}} is not similar to 12790@code{enum @{hot, dog@}}. 12791 12792You typically use this function in code whose execution varies 12793depending on the arguments' types. For example: 12794 12795@smallexample 12796#define foo(x) \ 12797 (@{ \ 12798 typeof (x) tmp = (x); \ 12799 if (__builtin_types_compatible_p (typeof (x), long double)) \ 12800 tmp = foo_long_double (tmp); \ 12801 else if (__builtin_types_compatible_p (typeof (x), double)) \ 12802 tmp = foo_double (tmp); \ 12803 else if (__builtin_types_compatible_p (typeof (x), float)) \ 12804 tmp = foo_float (tmp); \ 12805 else \ 12806 abort (); \ 12807 tmp; \ 12808 @}) 12809@end smallexample 12810 12811@emph{Note:} This construct is only available for C@. 12812 12813@end deftypefn 12814 12815@deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp}) 12816 12817The @var{call_exp} expression must be a function call, and the 12818@var{pointer_exp} expression must be a pointer. The @var{pointer_exp} 12819is passed to the function call in the target's static chain location. 12820The result of builtin is the result of the function call. 12821 12822@emph{Note:} This builtin is only available for C@. 12823This builtin can be used to call Go closures from C. 12824 12825@end deftypefn 12826 12827@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2}) 12828 12829You can use the built-in function @code{__builtin_choose_expr} to 12830evaluate code depending on the value of a constant expression. This 12831built-in function returns @var{exp1} if @var{const_exp}, which is an 12832integer constant expression, is nonzero. Otherwise it returns @var{exp2}. 12833 12834This built-in function is analogous to the @samp{? :} operator in C, 12835except that the expression returned has its type unaltered by promotion 12836rules. Also, the built-in function does not evaluate the expression 12837that is not chosen. For example, if @var{const_exp} evaluates to @code{true}, 12838@var{exp2} is not evaluated even if it has side effects. 12839 12840This built-in function can return an lvalue if the chosen argument is an 12841lvalue. 12842 12843If @var{exp1} is returned, the return type is the same as @var{exp1}'s 12844type. Similarly, if @var{exp2} is returned, its return type is the same 12845as @var{exp2}. 12846 12847Example: 12848 12849@smallexample 12850#define foo(x) \ 12851 __builtin_choose_expr ( \ 12852 __builtin_types_compatible_p (typeof (x), double), \ 12853 foo_double (x), \ 12854 __builtin_choose_expr ( \ 12855 __builtin_types_compatible_p (typeof (x), float), \ 12856 foo_float (x), \ 12857 /* @r{The void expression results in a compile-time error} \ 12858 @r{when assigning the result to something.} */ \ 12859 (void)0)) 12860@end smallexample 12861 12862@emph{Note:} This construct is only available for C@. Furthermore, the 12863unused expression (@var{exp1} or @var{exp2} depending on the value of 12864@var{const_exp}) may still generate syntax errors. This may change in 12865future revisions. 12866 12867@end deftypefn 12868 12869@deftypefn {Built-in Function} @var{type} __builtin_tgmath (@var{functions}, @var{arguments}) 12870 12871The built-in function @code{__builtin_tgmath}, available only for C 12872and Objective-C, calls a function determined according to the rules of 12873@code{<tgmath.h>} macros. It is intended to be used in 12874implementations of that header, so that expansions of macros from that 12875header only expand each of their arguments once, to avoid problems 12876when calls to such macros are nested inside the arguments of other 12877calls to such macros; in addition, it results in better diagnostics 12878for invalid calls to @code{<tgmath.h>} macros than implementations 12879using other GNU C language features. For example, the @code{pow} 12880type-generic macro might be defined as: 12881 12882@smallexample 12883#define pow(a, b) __builtin_tgmath (powf, pow, powl, \ 12884 cpowf, cpow, cpowl, a, b) 12885@end smallexample 12886 12887The arguments to @code{__builtin_tgmath} are at least two pointers to 12888functions, followed by the arguments to the type-generic macro (which 12889will be passed as arguments to the selected function). All the 12890pointers to functions must be pointers to prototyped functions, none 12891of which may have variable arguments, and all of which must have the 12892same number of parameters; the number of parameters of the first 12893function determines how many arguments to @code{__builtin_tgmath} are 12894interpreted as function pointers, and how many as the arguments to the 12895called function. 12896 12897The types of the specified functions must all be different, but 12898related to each other in the same way as a set of functions that may 12899be selected between by a macro in @code{<tgmath.h>}. This means that 12900the functions are parameterized by a floating-point type @var{t}, 12901different for each such function. The function return types may all 12902be the same type, or they may be @var{t} for each function, or they 12903may be the real type corresponding to @var{t} for each function (if 12904some of the types @var{t} are complex). Likewise, for each parameter 12905position, the type of the parameter in that position may always be the 12906same type, or may be @var{t} for each function (this case must apply 12907for at least one parameter position), or may be the real type 12908corresponding to @var{t} for each function. 12909 12910The standard rules for @code{<tgmath.h>} macros are used to find a 12911common type @var{u} from the types of the arguments for parameters 12912whose types vary between the functions; complex integer types (a GNU 12913extension) are treated like @code{_Complex double} for this purpose 12914(or @code{_Complex _Float64} if all the function return types are the 12915same @code{_Float@var{n}} or @code{_Float@var{n}x} type). 12916If the function return types vary, or are all the same integer type, 12917the function called is the one for which @var{t} is @var{u}, and it is 12918an error if there is no such function. If the function return types 12919are all the same floating-point type, the type-generic macro is taken 12920to be one of those from TS 18661 that rounds the result to a narrower 12921type; if there is a function for which @var{t} is @var{u}, it is 12922called, and otherwise the first function, if any, for which @var{t} 12923has at least the range and precision of @var{u} is called, and it is 12924an error if there is no such function. 12925 12926@end deftypefn 12927 12928@deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag}) 12929 12930The built-in function @code{__builtin_complex} is provided for use in 12931implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and 12932@code{CMPLXL}. @var{real} and @var{imag} must have the same type, a 12933real binary floating-point type, and the result has the corresponding 12934complex type with real and imaginary parts @var{real} and @var{imag}. 12935Unlike @samp{@var{real} + I * @var{imag}}, this works even when 12936infinities, NaNs and negative zeros are involved. 12937 12938@end deftypefn 12939 12940@deftypefn {Built-in Function} int __builtin_constant_p (@var{exp}) 12941You can use the built-in function @code{__builtin_constant_p} to 12942determine if a value is known to be constant at compile time and hence 12943that GCC can perform constant-folding on expressions involving that 12944value. The argument of the function is the value to test. The function 12945returns the integer 1 if the argument is known to be a compile-time 12946constant and 0 if it is not known to be a compile-time constant. A 12947return of 0 does not indicate that the value is @emph{not} a constant, 12948but merely that GCC cannot prove it is a constant with the specified 12949value of the @option{-O} option. 12950 12951You typically use this function in an embedded application where 12952memory is a critical resource. If you have some complex calculation, 12953you may want it to be folded if it involves constants, but need to call 12954a function if it does not. For example: 12955 12956@smallexample 12957#define Scale_Value(X) \ 12958 (__builtin_constant_p (X) \ 12959 ? ((X) * SCALE + OFFSET) : Scale (X)) 12960@end smallexample 12961 12962You may use this built-in function in either a macro or an inline 12963function. However, if you use it in an inlined function and pass an 12964argument of the function as the argument to the built-in, GCC 12965never returns 1 when you call the inline function with a string constant 12966or compound literal (@pxref{Compound Literals}) and does not return 1 12967when you pass a constant numeric value to the inline function unless you 12968specify the @option{-O} option. 12969 12970You may also use @code{__builtin_constant_p} in initializers for static 12971data. For instance, you can write 12972 12973@smallexample 12974static const int table[] = @{ 12975 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, 12976 /* @r{@dots{}} */ 12977@}; 12978@end smallexample 12979 12980@noindent 12981This is an acceptable initializer even if @var{EXPRESSION} is not a 12982constant expression, including the case where 12983@code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be 12984folded to a constant but @var{EXPRESSION} contains operands that are 12985not otherwise permitted in a static initializer (for example, 12986@code{0 && foo ()}). GCC must be more conservative about evaluating the 12987built-in in this case, because it has no opportunity to perform 12988optimization. 12989@end deftypefn 12990 12991@deftypefn {Built-in Function} bool __builtin_is_constant_evaluated (void) 12992The @code{__builtin_is_constant_evaluated} function is available only 12993in C++. The built-in is intended to be used by implementations of 12994the @code{std::is_constant_evaluated} C++ function. Programs should make 12995use of the latter function rather than invoking the built-in directly. 12996 12997The main use case of the built-in is to determine whether a @code{constexpr} 12998function is being called in a @code{constexpr} context. A call to 12999the function evaluates to a core constant expression with the value 13000@code{true} if and only if it occurs within the evaluation of an expression 13001or conversion that is manifestly constant-evaluated as defined in the C++ 13002standard. Manifestly constant-evaluated contexts include constant-expressions, 13003the conditions of @code{constexpr if} statements, constraint-expressions, and 13004initializers of variables usable in constant expressions. For more details 13005refer to the latest revision of the C++ standard. 13006@end deftypefn 13007 13008@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c}) 13009@opindex fprofile-arcs 13010You may use @code{__builtin_expect} to provide the compiler with 13011branch prediction information. In general, you should prefer to 13012use actual profile feedback for this (@option{-fprofile-arcs}), as 13013programmers are notoriously bad at predicting how their programs 13014actually perform. However, there are applications in which this 13015data is hard to collect. 13016 13017The return value is the value of @var{exp}, which should be an integral 13018expression. The semantics of the built-in are that it is expected that 13019@var{exp} == @var{c}. For example: 13020 13021@smallexample 13022if (__builtin_expect (x, 0)) 13023 foo (); 13024@end smallexample 13025 13026@noindent 13027indicates that we do not expect to call @code{foo}, since 13028we expect @code{x} to be zero. Since you are limited to integral 13029expressions for @var{exp}, you should use constructions such as 13030 13031@smallexample 13032if (__builtin_expect (ptr != NULL, 1)) 13033 foo (*ptr); 13034@end smallexample 13035 13036@noindent 13037when testing pointer or floating-point values. 13038 13039For the purposes of branch prediction optimizations, the probability that 13040a @code{__builtin_expect} expression is @code{true} is controlled by GCC's 13041@code{builtin-expect-probability} parameter, which defaults to 90%. 13042You can also use @code{__builtin_expect_with_probability} to explicitly 13043assign a probability value to individual expressions. 13044@end deftypefn 13045 13046@deftypefn {Built-in Function} long __builtin_expect_with_probability 13047(long @var{exp}, long @var{c}, double @var{probability}) 13048 13049This function has the same semantics as @code{__builtin_expect}, 13050but the caller provides the expected probability that @var{exp} == @var{c}. 13051The last argument, @var{probability}, is a floating-point value in the 13052range 0.0 to 1.0, inclusive. The @var{probability} argument must be 13053constant floating-point expression. 13054@end deftypefn 13055 13056@deftypefn {Built-in Function} void __builtin_trap (void) 13057This function causes the program to exit abnormally. GCC implements 13058this function by using a target-dependent mechanism (such as 13059intentionally executing an illegal instruction) or by calling 13060@code{abort}. The mechanism used may vary from release to release so 13061you should not rely on any particular implementation. 13062@end deftypefn 13063 13064@deftypefn {Built-in Function} void __builtin_unreachable (void) 13065If control flow reaches the point of the @code{__builtin_unreachable}, 13066the program is undefined. It is useful in situations where the 13067compiler cannot deduce the unreachability of the code. 13068 13069One such case is immediately following an @code{asm} statement that 13070either never terminates, or one that transfers control elsewhere 13071and never returns. In this example, without the 13072@code{__builtin_unreachable}, GCC issues a warning that control 13073reaches the end of a non-void function. It also generates code 13074to return after the @code{asm}. 13075 13076@smallexample 13077int f (int c, int v) 13078@{ 13079 if (c) 13080 @{ 13081 return v; 13082 @} 13083 else 13084 @{ 13085 asm("jmp error_handler"); 13086 __builtin_unreachable (); 13087 @} 13088@} 13089@end smallexample 13090 13091@noindent 13092Because the @code{asm} statement unconditionally transfers control out 13093of the function, control never reaches the end of the function 13094body. The @code{__builtin_unreachable} is in fact unreachable and 13095communicates this fact to the compiler. 13096 13097Another use for @code{__builtin_unreachable} is following a call a 13098function that never returns but that is not declared 13099@code{__attribute__((noreturn))}, as in this example: 13100 13101@smallexample 13102void function_that_never_returns (void); 13103 13104int g (int c) 13105@{ 13106 if (c) 13107 @{ 13108 return 1; 13109 @} 13110 else 13111 @{ 13112 function_that_never_returns (); 13113 __builtin_unreachable (); 13114 @} 13115@} 13116@end smallexample 13117 13118@end deftypefn 13119 13120@deftypefn {Built-in Function} {void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...) 13121This function returns its first argument, and allows the compiler 13122to assume that the returned pointer is at least @var{align} bytes 13123aligned. This built-in can have either two or three arguments, 13124if it has three, the third argument should have integer type, and 13125if it is nonzero means misalignment offset. For example: 13126 13127@smallexample 13128void *x = __builtin_assume_aligned (arg, 16); 13129@end smallexample 13130 13131@noindent 13132means that the compiler can assume @code{x}, set to @code{arg}, is at least 1313316-byte aligned, while: 13134 13135@smallexample 13136void *x = __builtin_assume_aligned (arg, 32, 8); 13137@end smallexample 13138 13139@noindent 13140means that the compiler can assume for @code{x}, set to @code{arg}, that 13141@code{(char *) x - 8} is 32-byte aligned. 13142@end deftypefn 13143 13144@deftypefn {Built-in Function} int __builtin_LINE () 13145This function is the equivalent of the preprocessor @code{__LINE__} 13146macro and returns a constant integer expression that evaluates to 13147the line number of the invocation of the built-in. When used as a C++ 13148default argument for a function @var{F}, it returns the line number 13149of the call to @var{F}. 13150@end deftypefn 13151 13152@deftypefn {Built-in Function} {const char *} __builtin_FUNCTION () 13153This function is the equivalent of the @code{__FUNCTION__} symbol 13154and returns an address constant pointing to the name of the function 13155from which the built-in was invoked, or the empty string if 13156the invocation is not at function scope. When used as a C++ default 13157argument for a function @var{F}, it returns the name of @var{F}'s 13158caller or the empty string if the call was not made at function 13159scope. 13160@end deftypefn 13161 13162@deftypefn {Built-in Function} {const char *} __builtin_FILE () 13163This function is the equivalent of the preprocessor @code{__FILE__} 13164macro and returns an address constant pointing to the file name 13165containing the invocation of the built-in, or the empty string if 13166the invocation is not at function scope. When used as a C++ default 13167argument for a function @var{F}, it returns the file name of the call 13168to @var{F} or the empty string if the call was not made at function 13169scope. 13170 13171For example, in the following, each call to function @code{foo} will 13172print a line similar to @code{"file.c:123: foo: message"} with the name 13173of the file and the line number of the @code{printf} call, the name of 13174the function @code{foo}, followed by the word @code{message}. 13175 13176@smallexample 13177const char* 13178function (const char *func = __builtin_FUNCTION ()) 13179@{ 13180 return func; 13181@} 13182 13183void foo (void) 13184@{ 13185 printf ("%s:%i: %s: message\n", file (), line (), function ()); 13186@} 13187@end smallexample 13188 13189@end deftypefn 13190 13191@deftypefn {Built-in Function} void __builtin___clear_cache (void *@var{begin}, void *@var{end}) 13192This function is used to flush the processor's instruction cache for 13193the region of memory between @var{begin} inclusive and @var{end} 13194exclusive. Some targets require that the instruction cache be 13195flushed, after modifying memory containing code, in order to obtain 13196deterministic behavior. 13197 13198If the target does not require instruction cache flushes, 13199@code{__builtin___clear_cache} has no effect. Otherwise either 13200instructions are emitted in-line to clear the instruction cache or a 13201call to the @code{__clear_cache} function in libgcc is made. 13202@end deftypefn 13203 13204@deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...) 13205This function is used to minimize cache-miss latency by moving data into 13206a cache before it is accessed. 13207You can insert calls to @code{__builtin_prefetch} into code for which 13208you know addresses of data in memory that is likely to be accessed soon. 13209If the target supports them, data prefetch instructions are generated. 13210If the prefetch is done early enough before the access then the data will 13211be in the cache by the time it is accessed. 13212 13213The value of @var{addr} is the address of the memory to prefetch. 13214There are two optional arguments, @var{rw} and @var{locality}. 13215The value of @var{rw} is a compile-time constant one or zero; one 13216means that the prefetch is preparing for a write to the memory address 13217and zero, the default, means that the prefetch is preparing for a read. 13218The value @var{locality} must be a compile-time constant integer between 13219zero and three. A value of zero means that the data has no temporal 13220locality, so it need not be left in the cache after the access. A value 13221of three means that the data has a high degree of temporal locality and 13222should be left in all levels of cache possible. Values of one and two 13223mean, respectively, a low or moderate degree of temporal locality. The 13224default is three. 13225 13226@smallexample 13227for (i = 0; i < n; i++) 13228 @{ 13229 a[i] = a[i] + b[i]; 13230 __builtin_prefetch (&a[i+j], 1, 1); 13231 __builtin_prefetch (&b[i+j], 0, 1); 13232 /* @r{@dots{}} */ 13233 @} 13234@end smallexample 13235 13236Data prefetch does not generate faults if @var{addr} is invalid, but 13237the address expression itself must be valid. For example, a prefetch 13238of @code{p->next} does not fault if @code{p->next} is not a valid 13239address, but evaluation faults if @code{p} is not a valid address. 13240 13241If the target does not support data prefetch, the address expression 13242is evaluated if it includes side effects but no other code is generated 13243and GCC does not issue a warning. 13244@end deftypefn 13245 13246@deftypefn {Built-in Function}{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type}) 13247Returns the size of an object pointed to by @var{ptr}. @xref{Object Size 13248Checking}, for a detailed description of the function. 13249@end deftypefn 13250 13251@deftypefn {Built-in Function} double __builtin_huge_val (void) 13252Returns a positive infinity, if supported by the floating-point format, 13253else @code{DBL_MAX}. This function is suitable for implementing the 13254ISO C macro @code{HUGE_VAL}. 13255@end deftypefn 13256 13257@deftypefn {Built-in Function} float __builtin_huge_valf (void) 13258Similar to @code{__builtin_huge_val}, except the return type is @code{float}. 13259@end deftypefn 13260 13261@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void) 13262Similar to @code{__builtin_huge_val}, except the return 13263type is @code{long double}. 13264@end deftypefn 13265 13266@deftypefn {Built-in Function} _Float@var{n} __builtin_huge_valf@var{n} (void) 13267Similar to @code{__builtin_huge_val}, except the return type is 13268@code{_Float@var{n}}. 13269@end deftypefn 13270 13271@deftypefn {Built-in Function} _Float@var{n}x __builtin_huge_valf@var{n}x (void) 13272Similar to @code{__builtin_huge_val}, except the return type is 13273@code{_Float@var{n}x}. 13274@end deftypefn 13275 13276@deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...) 13277This built-in implements the C99 fpclassify functionality. The first 13278five int arguments should be the target library's notion of the 13279possible FP classes and are used for return values. They must be 13280constant values and they must appear in this order: @code{FP_NAN}, 13281@code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and 13282@code{FP_ZERO}. The ellipsis is for exactly one floating-point value 13283to classify. GCC treats the last argument as type-generic, which 13284means it does not do default promotion from float to double. 13285@end deftypefn 13286 13287@deftypefn {Built-in Function} double __builtin_inf (void) 13288Similar to @code{__builtin_huge_val}, except a warning is generated 13289if the target floating-point format does not support infinities. 13290@end deftypefn 13291 13292@deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void) 13293Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. 13294@end deftypefn 13295 13296@deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void) 13297Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. 13298@end deftypefn 13299 13300@deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void) 13301Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. 13302@end deftypefn 13303 13304@deftypefn {Built-in Function} float __builtin_inff (void) 13305Similar to @code{__builtin_inf}, except the return type is @code{float}. 13306This function is suitable for implementing the ISO C99 macro @code{INFINITY}. 13307@end deftypefn 13308 13309@deftypefn {Built-in Function} {long double} __builtin_infl (void) 13310Similar to @code{__builtin_inf}, except the return 13311type is @code{long double}. 13312@end deftypefn 13313 13314@deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n} (void) 13315Similar to @code{__builtin_inf}, except the return 13316type is @code{_Float@var{n}}. 13317@end deftypefn 13318 13319@deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n}x (void) 13320Similar to @code{__builtin_inf}, except the return 13321type is @code{_Float@var{n}x}. 13322@end deftypefn 13323 13324@deftypefn {Built-in Function} int __builtin_isinf_sign (...) 13325Similar to @code{isinf}, except the return value is -1 for 13326an argument of @code{-Inf} and 1 for an argument of @code{+Inf}. 13327Note while the parameter list is an 13328ellipsis, this function only accepts exactly one floating-point 13329argument. GCC treats this parameter as type-generic, which means it 13330does not do default promotion from float to double. 13331@end deftypefn 13332 13333@deftypefn {Built-in Function} double __builtin_nan (const char *str) 13334This is an implementation of the ISO C99 function @code{nan}. 13335 13336Since ISO C99 defines this function in terms of @code{strtod}, which we 13337do not implement, a description of the parsing is in order. The string 13338is parsed as by @code{strtol}; that is, the base is recognized by 13339leading @samp{0} or @samp{0x} prefixes. The number parsed is placed 13340in the significand such that the least significant bit of the number 13341is at the least significant bit of the significand. The number is 13342truncated to fit the significand field provided. The significand is 13343forced to be a quiet NaN@. 13344 13345This function, if given a string literal all of which would have been 13346consumed by @code{strtol}, is evaluated early enough that it is considered a 13347compile-time constant. 13348@end deftypefn 13349 13350@deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str) 13351Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. 13352@end deftypefn 13353 13354@deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str) 13355Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. 13356@end deftypefn 13357 13358@deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str) 13359Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. 13360@end deftypefn 13361 13362@deftypefn {Built-in Function} float __builtin_nanf (const char *str) 13363Similar to @code{__builtin_nan}, except the return type is @code{float}. 13364@end deftypefn 13365 13366@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str) 13367Similar to @code{__builtin_nan}, except the return type is @code{long double}. 13368@end deftypefn 13369 13370@deftypefn {Built-in Function} _Float@var{n} __builtin_nanf@var{n} (const char *str) 13371Similar to @code{__builtin_nan}, except the return type is 13372@code{_Float@var{n}}. 13373@end deftypefn 13374 13375@deftypefn {Built-in Function} _Float@var{n}x __builtin_nanf@var{n}x (const char *str) 13376Similar to @code{__builtin_nan}, except the return type is 13377@code{_Float@var{n}x}. 13378@end deftypefn 13379 13380@deftypefn {Built-in Function} double __builtin_nans (const char *str) 13381Similar to @code{__builtin_nan}, except the significand is forced 13382to be a signaling NaN@. The @code{nans} function is proposed by 13383@uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. 13384@end deftypefn 13385 13386@deftypefn {Built-in Function} float __builtin_nansf (const char *str) 13387Similar to @code{__builtin_nans}, except the return type is @code{float}. 13388@end deftypefn 13389 13390@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str) 13391Similar to @code{__builtin_nans}, except the return type is @code{long double}. 13392@end deftypefn 13393 13394@deftypefn {Built-in Function} _Float@var{n} __builtin_nansf@var{n} (const char *str) 13395Similar to @code{__builtin_nans}, except the return type is 13396@code{_Float@var{n}}. 13397@end deftypefn 13398 13399@deftypefn {Built-in Function} _Float@var{n}x __builtin_nansf@var{n}x (const char *str) 13400Similar to @code{__builtin_nans}, except the return type is 13401@code{_Float@var{n}x}. 13402@end deftypefn 13403 13404@deftypefn {Built-in Function} int __builtin_ffs (int x) 13405Returns one plus the index of the least significant 1-bit of @var{x}, or 13406if @var{x} is zero, returns zero. 13407@end deftypefn 13408 13409@deftypefn {Built-in Function} int __builtin_clz (unsigned int x) 13410Returns the number of leading 0-bits in @var{x}, starting at the most 13411significant bit position. If @var{x} is 0, the result is undefined. 13412@end deftypefn 13413 13414@deftypefn {Built-in Function} int __builtin_ctz (unsigned int x) 13415Returns the number of trailing 0-bits in @var{x}, starting at the least 13416significant bit position. If @var{x} is 0, the result is undefined. 13417@end deftypefn 13418 13419@deftypefn {Built-in Function} int __builtin_clrsb (int x) 13420Returns the number of leading redundant sign bits in @var{x}, i.e.@: the 13421number of bits following the most significant bit that are identical 13422to it. There are no special cases for 0 or other values. 13423@end deftypefn 13424 13425@deftypefn {Built-in Function} int __builtin_popcount (unsigned int x) 13426Returns the number of 1-bits in @var{x}. 13427@end deftypefn 13428 13429@deftypefn {Built-in Function} int __builtin_parity (unsigned int x) 13430Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} 13431modulo 2. 13432@end deftypefn 13433 13434@deftypefn {Built-in Function} int __builtin_ffsl (long) 13435Similar to @code{__builtin_ffs}, except the argument type is 13436@code{long}. 13437@end deftypefn 13438 13439@deftypefn {Built-in Function} int __builtin_clzl (unsigned long) 13440Similar to @code{__builtin_clz}, except the argument type is 13441@code{unsigned long}. 13442@end deftypefn 13443 13444@deftypefn {Built-in Function} int __builtin_ctzl (unsigned long) 13445Similar to @code{__builtin_ctz}, except the argument type is 13446@code{unsigned long}. 13447@end deftypefn 13448 13449@deftypefn {Built-in Function} int __builtin_clrsbl (long) 13450Similar to @code{__builtin_clrsb}, except the argument type is 13451@code{long}. 13452@end deftypefn 13453 13454@deftypefn {Built-in Function} int __builtin_popcountl (unsigned long) 13455Similar to @code{__builtin_popcount}, except the argument type is 13456@code{unsigned long}. 13457@end deftypefn 13458 13459@deftypefn {Built-in Function} int __builtin_parityl (unsigned long) 13460Similar to @code{__builtin_parity}, except the argument type is 13461@code{unsigned long}. 13462@end deftypefn 13463 13464@deftypefn {Built-in Function} int __builtin_ffsll (long long) 13465Similar to @code{__builtin_ffs}, except the argument type is 13466@code{long long}. 13467@end deftypefn 13468 13469@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long) 13470Similar to @code{__builtin_clz}, except the argument type is 13471@code{unsigned long long}. 13472@end deftypefn 13473 13474@deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long) 13475Similar to @code{__builtin_ctz}, except the argument type is 13476@code{unsigned long long}. 13477@end deftypefn 13478 13479@deftypefn {Built-in Function} int __builtin_clrsbll (long long) 13480Similar to @code{__builtin_clrsb}, except the argument type is 13481@code{long long}. 13482@end deftypefn 13483 13484@deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long) 13485Similar to @code{__builtin_popcount}, except the argument type is 13486@code{unsigned long long}. 13487@end deftypefn 13488 13489@deftypefn {Built-in Function} int __builtin_parityll (unsigned long long) 13490Similar to @code{__builtin_parity}, except the argument type is 13491@code{unsigned long long}. 13492@end deftypefn 13493 13494@deftypefn {Built-in Function} double __builtin_powi (double, int) 13495Returns the first argument raised to the power of the second. Unlike the 13496@code{pow} function no guarantees about precision and rounding are made. 13497@end deftypefn 13498 13499@deftypefn {Built-in Function} float __builtin_powif (float, int) 13500Similar to @code{__builtin_powi}, except the argument and return types 13501are @code{float}. 13502@end deftypefn 13503 13504@deftypefn {Built-in Function} {long double} __builtin_powil (long double, int) 13505Similar to @code{__builtin_powi}, except the argument and return types 13506are @code{long double}. 13507@end deftypefn 13508 13509@deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x) 13510Returns @var{x} with the order of the bytes reversed; for example, 13511@code{0xaabb} becomes @code{0xbbaa}. Byte here always means 13512exactly 8 bits. 13513@end deftypefn 13514 13515@deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x) 13516Similar to @code{__builtin_bswap16}, except the argument and return types 13517are 32 bit. 13518@end deftypefn 13519 13520@deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x) 13521Similar to @code{__builtin_bswap32}, except the argument and return types 13522are 64 bit. 13523@end deftypefn 13524 13525@deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x) 13526On targets where the user visible pointer size is smaller than the size 13527of an actual hardware address this function returns the extended user 13528pointer. Targets where this is true included ILP32 mode on x86_64 or 13529Aarch64. This function is mainly useful when writing inline assembly 13530code. 13531@end deftypefn 13532 13533@deftypefn {Built-in Function} int __builtin_goacc_parlevel_id (int x) 13534Returns the openacc gang, worker or vector id depending on whether @var{x} is 135350, 1 or 2. 13536@end deftypefn 13537 13538@deftypefn {Built-in Function} int __builtin_goacc_parlevel_size (int x) 13539Returns the openacc gang, worker or vector size depending on whether @var{x} is 135400, 1 or 2. 13541@end deftypefn 13542 13543@node Target Builtins 13544@section Built-in Functions Specific to Particular Target Machines 13545 13546On some target machines, GCC supports many built-in functions specific 13547to those machines. Generally these generate calls to specific machine 13548instructions, but allow the compiler to schedule those calls. 13549 13550@menu 13551* AArch64 Built-in Functions:: 13552* Alpha Built-in Functions:: 13553* Altera Nios II Built-in Functions:: 13554* ARC Built-in Functions:: 13555* ARC SIMD Built-in Functions:: 13556* ARM iWMMXt Built-in Functions:: 13557* ARM C Language Extensions (ACLE):: 13558* ARM Floating Point Status and Control Intrinsics:: 13559* ARM ARMv8-M Security Extensions:: 13560* AVR Built-in Functions:: 13561* Blackfin Built-in Functions:: 13562* FR-V Built-in Functions:: 13563* MIPS DSP Built-in Functions:: 13564* MIPS Paired-Single Support:: 13565* MIPS Loongson Built-in Functions:: 13566* MIPS SIMD Architecture (MSA) Support:: 13567* Other MIPS Built-in Functions:: 13568* MSP430 Built-in Functions:: 13569* NDS32 Built-in Functions:: 13570* picoChip Built-in Functions:: 13571* Basic PowerPC Built-in Functions:: 13572* PowerPC AltiVec/VSX Built-in Functions:: 13573* PowerPC Hardware Transactional Memory Built-in Functions:: 13574* PowerPC Atomic Memory Operation Functions:: 13575* RX Built-in Functions:: 13576* S/390 System z Built-in Functions:: 13577* SH Built-in Functions:: 13578* SPARC VIS Built-in Functions:: 13579* SPU Built-in Functions:: 13580* TI C6X Built-in Functions:: 13581* TILE-Gx Built-in Functions:: 13582* TILEPro Built-in Functions:: 13583* x86 Built-in Functions:: 13584* x86 transactional memory intrinsics:: 13585* x86 control-flow protection intrinsics:: 13586@end menu 13587 13588@node AArch64 Built-in Functions 13589@subsection AArch64 Built-in Functions 13590 13591These built-in functions are available for the AArch64 family of 13592processors. 13593@smallexample 13594unsigned int __builtin_aarch64_get_fpcr () 13595void __builtin_aarch64_set_fpcr (unsigned int) 13596unsigned int __builtin_aarch64_get_fpsr () 13597void __builtin_aarch64_set_fpsr (unsigned int) 13598@end smallexample 13599 13600@node Alpha Built-in Functions 13601@subsection Alpha Built-in Functions 13602 13603These built-in functions are available for the Alpha family of 13604processors, depending on the command-line switches used. 13605 13606The following built-in functions are always available. They 13607all generate the machine instruction that is part of the name. 13608 13609@smallexample 13610long __builtin_alpha_implver (void) 13611long __builtin_alpha_rpcc (void) 13612long __builtin_alpha_amask (long) 13613long __builtin_alpha_cmpbge (long, long) 13614long __builtin_alpha_extbl (long, long) 13615long __builtin_alpha_extwl (long, long) 13616long __builtin_alpha_extll (long, long) 13617long __builtin_alpha_extql (long, long) 13618long __builtin_alpha_extwh (long, long) 13619long __builtin_alpha_extlh (long, long) 13620long __builtin_alpha_extqh (long, long) 13621long __builtin_alpha_insbl (long, long) 13622long __builtin_alpha_inswl (long, long) 13623long __builtin_alpha_insll (long, long) 13624long __builtin_alpha_insql (long, long) 13625long __builtin_alpha_inswh (long, long) 13626long __builtin_alpha_inslh (long, long) 13627long __builtin_alpha_insqh (long, long) 13628long __builtin_alpha_mskbl (long, long) 13629long __builtin_alpha_mskwl (long, long) 13630long __builtin_alpha_mskll (long, long) 13631long __builtin_alpha_mskql (long, long) 13632long __builtin_alpha_mskwh (long, long) 13633long __builtin_alpha_msklh (long, long) 13634long __builtin_alpha_mskqh (long, long) 13635long __builtin_alpha_umulh (long, long) 13636long __builtin_alpha_zap (long, long) 13637long __builtin_alpha_zapnot (long, long) 13638@end smallexample 13639 13640The following built-in functions are always with @option{-mmax} 13641or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or 13642later. They all generate the machine instruction that is part 13643of the name. 13644 13645@smallexample 13646long __builtin_alpha_pklb (long) 13647long __builtin_alpha_pkwb (long) 13648long __builtin_alpha_unpkbl (long) 13649long __builtin_alpha_unpkbw (long) 13650long __builtin_alpha_minub8 (long, long) 13651long __builtin_alpha_minsb8 (long, long) 13652long __builtin_alpha_minuw4 (long, long) 13653long __builtin_alpha_minsw4 (long, long) 13654long __builtin_alpha_maxub8 (long, long) 13655long __builtin_alpha_maxsb8 (long, long) 13656long __builtin_alpha_maxuw4 (long, long) 13657long __builtin_alpha_maxsw4 (long, long) 13658long __builtin_alpha_perr (long, long) 13659@end smallexample 13660 13661The following built-in functions are always with @option{-mcix} 13662or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or 13663later. They all generate the machine instruction that is part 13664of the name. 13665 13666@smallexample 13667long __builtin_alpha_cttz (long) 13668long __builtin_alpha_ctlz (long) 13669long __builtin_alpha_ctpop (long) 13670@end smallexample 13671 13672The following built-in functions are available on systems that use the OSF/1 13673PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} 13674PAL calls, but when invoked with @option{-mtls-kernel}, they invoke 13675@code{rdval} and @code{wrval}. 13676 13677@smallexample 13678void *__builtin_thread_pointer (void) 13679void __builtin_set_thread_pointer (void *) 13680@end smallexample 13681 13682@node Altera Nios II Built-in Functions 13683@subsection Altera Nios II Built-in Functions 13684 13685These built-in functions are available for the Altera Nios II 13686family of processors. 13687 13688The following built-in functions are always available. They 13689all generate the machine instruction that is part of the name. 13690 13691@example 13692int __builtin_ldbio (volatile const void *) 13693int __builtin_ldbuio (volatile const void *) 13694int __builtin_ldhio (volatile const void *) 13695int __builtin_ldhuio (volatile const void *) 13696int __builtin_ldwio (volatile const void *) 13697void __builtin_stbio (volatile void *, int) 13698void __builtin_sthio (volatile void *, int) 13699void __builtin_stwio (volatile void *, int) 13700void __builtin_sync (void) 13701int __builtin_rdctl (int) 13702int __builtin_rdprs (int, int) 13703void __builtin_wrctl (int, int) 13704void __builtin_flushd (volatile void *) 13705void __builtin_flushda (volatile void *) 13706int __builtin_wrpie (int); 13707void __builtin_eni (int); 13708int __builtin_ldex (volatile const void *) 13709int __builtin_stex (volatile void *, int) 13710int __builtin_ldsex (volatile const void *) 13711int __builtin_stsex (volatile void *, int) 13712@end example 13713 13714The following built-in functions are always available. They 13715all generate a Nios II Custom Instruction. The name of the 13716function represents the types that the function takes and 13717returns. The letter before the @code{n} is the return type 13718or void if absent. The @code{n} represents the first parameter 13719to all the custom instructions, the custom instruction number. 13720The two letters after the @code{n} represent the up to two 13721parameters to the function. 13722 13723The letters represent the following data types: 13724@table @code 13725@item <no letter> 13726@code{void} for return type and no parameter for parameter types. 13727 13728@item i 13729@code{int} for return type and parameter type 13730 13731@item f 13732@code{float} for return type and parameter type 13733 13734@item p 13735@code{void *} for return type and parameter type 13736 13737@end table 13738 13739And the function names are: 13740@example 13741void __builtin_custom_n (void) 13742void __builtin_custom_ni (int) 13743void __builtin_custom_nf (float) 13744void __builtin_custom_np (void *) 13745void __builtin_custom_nii (int, int) 13746void __builtin_custom_nif (int, float) 13747void __builtin_custom_nip (int, void *) 13748void __builtin_custom_nfi (float, int) 13749void __builtin_custom_nff (float, float) 13750void __builtin_custom_nfp (float, void *) 13751void __builtin_custom_npi (void *, int) 13752void __builtin_custom_npf (void *, float) 13753void __builtin_custom_npp (void *, void *) 13754int __builtin_custom_in (void) 13755int __builtin_custom_ini (int) 13756int __builtin_custom_inf (float) 13757int __builtin_custom_inp (void *) 13758int __builtin_custom_inii (int, int) 13759int __builtin_custom_inif (int, float) 13760int __builtin_custom_inip (int, void *) 13761int __builtin_custom_infi (float, int) 13762int __builtin_custom_inff (float, float) 13763int __builtin_custom_infp (float, void *) 13764int __builtin_custom_inpi (void *, int) 13765int __builtin_custom_inpf (void *, float) 13766int __builtin_custom_inpp (void *, void *) 13767float __builtin_custom_fn (void) 13768float __builtin_custom_fni (int) 13769float __builtin_custom_fnf (float) 13770float __builtin_custom_fnp (void *) 13771float __builtin_custom_fnii (int, int) 13772float __builtin_custom_fnif (int, float) 13773float __builtin_custom_fnip (int, void *) 13774float __builtin_custom_fnfi (float, int) 13775float __builtin_custom_fnff (float, float) 13776float __builtin_custom_fnfp (float, void *) 13777float __builtin_custom_fnpi (void *, int) 13778float __builtin_custom_fnpf (void *, float) 13779float __builtin_custom_fnpp (void *, void *) 13780void * __builtin_custom_pn (void) 13781void * __builtin_custom_pni (int) 13782void * __builtin_custom_pnf (float) 13783void * __builtin_custom_pnp (void *) 13784void * __builtin_custom_pnii (int, int) 13785void * __builtin_custom_pnif (int, float) 13786void * __builtin_custom_pnip (int, void *) 13787void * __builtin_custom_pnfi (float, int) 13788void * __builtin_custom_pnff (float, float) 13789void * __builtin_custom_pnfp (float, void *) 13790void * __builtin_custom_pnpi (void *, int) 13791void * __builtin_custom_pnpf (void *, float) 13792void * __builtin_custom_pnpp (void *, void *) 13793@end example 13794 13795@node ARC Built-in Functions 13796@subsection ARC Built-in Functions 13797 13798The following built-in functions are provided for ARC targets. The 13799built-ins generate the corresponding assembly instructions. In the 13800examples given below, the generated code often requires an operand or 13801result to be in a register. Where necessary further code will be 13802generated to ensure this is true, but for brevity this is not 13803described in each case. 13804 13805@emph{Note:} Using a built-in to generate an instruction not supported 13806by a target may cause problems. At present the compiler is not 13807guaranteed to detect such misuse, and as a result an internal compiler 13808error may be generated. 13809 13810@deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval}) 13811Return 1 if @var{val} is known to have the byte alignment given 13812by @var{alignval}, otherwise return 0. 13813Note that this is different from 13814@smallexample 13815__alignof__(*(char *)@var{val}) >= alignval 13816@end smallexample 13817because __alignof__ sees only the type of the dereference, whereas 13818__builtin_arc_align uses alignment information from the pointer 13819as well as from the pointed-to type. 13820The information available will depend on optimization level. 13821@end deftypefn 13822 13823@deftypefn {Built-in Function} void __builtin_arc_brk (void) 13824Generates 13825@example 13826brk 13827@end example 13828@end deftypefn 13829 13830@deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno}) 13831The operand is the number of a register to be read. Generates: 13832@example 13833mov @var{dest}, r@var{regno} 13834@end example 13835where the value in @var{dest} will be the result returned from the 13836built-in. 13837@end deftypefn 13838 13839@deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val}) 13840The first operand is the number of a register to be written, the 13841second operand is a compile time constant to write into that 13842register. Generates: 13843@example 13844mov r@var{regno}, @var{val} 13845@end example 13846@end deftypefn 13847 13848@deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b}) 13849Only available if either @option{-mcpu=ARC700} or @option{-meA} is set. 13850Generates: 13851@example 13852divaw @var{dest}, @var{a}, @var{b} 13853@end example 13854where the value in @var{dest} will be the result returned from the 13855built-in. 13856@end deftypefn 13857 13858@deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a}) 13859Generates 13860@example 13861flag @var{a} 13862@end example 13863@end deftypefn 13864 13865@deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr}) 13866The operand, @var{auxv}, is the address of an auxiliary register and 13867must be a compile time constant. Generates: 13868@example 13869lr @var{dest}, [@var{auxr}] 13870@end example 13871Where the value in @var{dest} will be the result returned from the 13872built-in. 13873@end deftypefn 13874 13875@deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b}) 13876Only available with @option{-mmul64}. Generates: 13877@example 13878mul64 @var{a}, @var{b} 13879@end example 13880@end deftypefn 13881 13882@deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b}) 13883Only available with @option{-mmul64}. Generates: 13884@example 13885mulu64 @var{a}, @var{b} 13886@end example 13887@end deftypefn 13888 13889@deftypefn {Built-in Function} void __builtin_arc_nop (void) 13890Generates: 13891@example 13892nop 13893@end example 13894@end deftypefn 13895 13896@deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src}) 13897Only valid if the @samp{norm} instruction is available through the 13898@option{-mnorm} option or by default with @option{-mcpu=ARC700}. 13899Generates: 13900@example 13901norm @var{dest}, @var{src} 13902@end example 13903Where the value in @var{dest} will be the result returned from the 13904built-in. 13905@end deftypefn 13906 13907@deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src}) 13908Only valid if the @samp{normw} instruction is available through the 13909@option{-mnorm} option or by default with @option{-mcpu=ARC700}. 13910Generates: 13911@example 13912normw @var{dest}, @var{src} 13913@end example 13914Where the value in @var{dest} will be the result returned from the 13915built-in. 13916@end deftypefn 13917 13918@deftypefn {Built-in Function} void __builtin_arc_rtie (void) 13919Generates: 13920@example 13921rtie 13922@end example 13923@end deftypefn 13924 13925@deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a} 13926Generates: 13927@example 13928sleep @var{a} 13929@end example 13930@end deftypefn 13931 13932@deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{auxr}, unsigned int @var{val}) 13933The first argument, @var{auxv}, is the address of an auxiliary 13934register, the second argument, @var{val}, is a compile time constant 13935to be written to the register. Generates: 13936@example 13937sr @var{auxr}, [@var{val}] 13938@end example 13939@end deftypefn 13940 13941@deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src}) 13942Only valid with @option{-mswap}. Generates: 13943@example 13944swap @var{dest}, @var{src} 13945@end example 13946Where the value in @var{dest} will be the result returned from the 13947built-in. 13948@end deftypefn 13949 13950@deftypefn {Built-in Function} void __builtin_arc_swi (void) 13951Generates: 13952@example 13953swi 13954@end example 13955@end deftypefn 13956 13957@deftypefn {Built-in Function} void __builtin_arc_sync (void) 13958Only available with @option{-mcpu=ARC700}. Generates: 13959@example 13960sync 13961@end example 13962@end deftypefn 13963 13964@deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c}) 13965Only available with @option{-mcpu=ARC700}. Generates: 13966@example 13967trap_s @var{c} 13968@end example 13969@end deftypefn 13970 13971@deftypefn {Built-in Function} void __builtin_arc_unimp_s (void) 13972Only available with @option{-mcpu=ARC700}. Generates: 13973@example 13974unimp_s 13975@end example 13976@end deftypefn 13977 13978The instructions generated by the following builtins are not 13979considered as candidates for scheduling. They are not moved around by 13980the compiler during scheduling, and thus can be expected to appear 13981where they are put in the C code: 13982@example 13983__builtin_arc_brk() 13984__builtin_arc_core_read() 13985__builtin_arc_core_write() 13986__builtin_arc_flag() 13987__builtin_arc_lr() 13988__builtin_arc_sleep() 13989__builtin_arc_sr() 13990__builtin_arc_swi() 13991@end example 13992 13993@node ARC SIMD Built-in Functions 13994@subsection ARC SIMD Built-in Functions 13995 13996SIMD builtins provided by the compiler can be used to generate the 13997vector instructions. This section describes the available builtins 13998and their usage in programs. With the @option{-msimd} option, the 13999compiler provides 128-bit vector types, which can be specified using 14000the @code{vector_size} attribute. The header file @file{arc-simd.h} 14001can be included to use the following predefined types: 14002@example 14003typedef int __v4si __attribute__((vector_size(16))); 14004typedef short __v8hi __attribute__((vector_size(16))); 14005@end example 14006 14007These types can be used to define 128-bit variables. The built-in 14008functions listed in the following section can be used on these 14009variables to generate the vector operations. 14010 14011For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file 14012@file{arc-simd.h} also provides equivalent macros called 14013@code{_@var{someinsn}} that can be used for programming ease and 14014improved readability. The following macros for DMA control are also 14015provided: 14016@example 14017#define _setup_dma_in_channel_reg _vdiwr 14018#define _setup_dma_out_channel_reg _vdowr 14019@end example 14020 14021The following is a complete list of all the SIMD built-ins provided 14022for ARC, grouped by calling signature. 14023 14024The following take two @code{__v8hi} arguments and return a 14025@code{__v8hi} result: 14026@example 14027__v8hi __builtin_arc_vaddaw (__v8hi, __v8hi) 14028__v8hi __builtin_arc_vaddw (__v8hi, __v8hi) 14029__v8hi __builtin_arc_vand (__v8hi, __v8hi) 14030__v8hi __builtin_arc_vandaw (__v8hi, __v8hi) 14031__v8hi __builtin_arc_vavb (__v8hi, __v8hi) 14032__v8hi __builtin_arc_vavrb (__v8hi, __v8hi) 14033__v8hi __builtin_arc_vbic (__v8hi, __v8hi) 14034__v8hi __builtin_arc_vbicaw (__v8hi, __v8hi) 14035__v8hi __builtin_arc_vdifaw (__v8hi, __v8hi) 14036__v8hi __builtin_arc_vdifw (__v8hi, __v8hi) 14037__v8hi __builtin_arc_veqw (__v8hi, __v8hi) 14038__v8hi __builtin_arc_vh264f (__v8hi, __v8hi) 14039__v8hi __builtin_arc_vh264ft (__v8hi, __v8hi) 14040__v8hi __builtin_arc_vh264fw (__v8hi, __v8hi) 14041__v8hi __builtin_arc_vlew (__v8hi, __v8hi) 14042__v8hi __builtin_arc_vltw (__v8hi, __v8hi) 14043__v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi) 14044__v8hi __builtin_arc_vmaxw (__v8hi, __v8hi) 14045__v8hi __builtin_arc_vminaw (__v8hi, __v8hi) 14046__v8hi __builtin_arc_vminw (__v8hi, __v8hi) 14047__v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi) 14048__v8hi __builtin_arc_vmr1w (__v8hi, __v8hi) 14049__v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi) 14050__v8hi __builtin_arc_vmr2w (__v8hi, __v8hi) 14051__v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi) 14052__v8hi __builtin_arc_vmr3w (__v8hi, __v8hi) 14053__v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi) 14054__v8hi __builtin_arc_vmr4w (__v8hi, __v8hi) 14055__v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi) 14056__v8hi __builtin_arc_vmr5w (__v8hi, __v8hi) 14057__v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi) 14058__v8hi __builtin_arc_vmr6w (__v8hi, __v8hi) 14059__v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi) 14060__v8hi __builtin_arc_vmr7w (__v8hi, __v8hi) 14061__v8hi __builtin_arc_vmrb (__v8hi, __v8hi) 14062__v8hi __builtin_arc_vmulaw (__v8hi, __v8hi) 14063__v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi) 14064__v8hi __builtin_arc_vmulfw (__v8hi, __v8hi) 14065__v8hi __builtin_arc_vmulw (__v8hi, __v8hi) 14066__v8hi __builtin_arc_vnew (__v8hi, __v8hi) 14067__v8hi __builtin_arc_vor (__v8hi, __v8hi) 14068__v8hi __builtin_arc_vsubaw (__v8hi, __v8hi) 14069__v8hi __builtin_arc_vsubw (__v8hi, __v8hi) 14070__v8hi __builtin_arc_vsummw (__v8hi, __v8hi) 14071__v8hi __builtin_arc_vvc1f (__v8hi, __v8hi) 14072__v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi) 14073__v8hi __builtin_arc_vxor (__v8hi, __v8hi) 14074__v8hi __builtin_arc_vxoraw (__v8hi, __v8hi) 14075@end example 14076 14077The following take one @code{__v8hi} and one @code{int} argument and return a 14078@code{__v8hi} result: 14079 14080@example 14081__v8hi __builtin_arc_vbaddw (__v8hi, int) 14082__v8hi __builtin_arc_vbmaxw (__v8hi, int) 14083__v8hi __builtin_arc_vbminw (__v8hi, int) 14084__v8hi __builtin_arc_vbmulaw (__v8hi, int) 14085__v8hi __builtin_arc_vbmulfw (__v8hi, int) 14086__v8hi __builtin_arc_vbmulw (__v8hi, int) 14087__v8hi __builtin_arc_vbrsubw (__v8hi, int) 14088__v8hi __builtin_arc_vbsubw (__v8hi, int) 14089@end example 14090 14091The following take one @code{__v8hi} argument and one @code{int} argument which 14092must be a 3-bit compile time constant indicating a register number 14093I0-I7. They return a @code{__v8hi} result. 14094@example 14095__v8hi __builtin_arc_vasrw (__v8hi, const int) 14096__v8hi __builtin_arc_vsr8 (__v8hi, const int) 14097__v8hi __builtin_arc_vsr8aw (__v8hi, const int) 14098@end example 14099 14100The following take one @code{__v8hi} argument and one @code{int} 14101argument which must be a 6-bit compile time constant. They return a 14102@code{__v8hi} result. 14103@example 14104__v8hi __builtin_arc_vasrpwbi (__v8hi, const int) 14105__v8hi __builtin_arc_vasrrpwbi (__v8hi, const int) 14106__v8hi __builtin_arc_vasrrwi (__v8hi, const int) 14107__v8hi __builtin_arc_vasrsrwi (__v8hi, const int) 14108__v8hi __builtin_arc_vasrwi (__v8hi, const int) 14109__v8hi __builtin_arc_vsr8awi (__v8hi, const int) 14110__v8hi __builtin_arc_vsr8i (__v8hi, const int) 14111@end example 14112 14113The following take one @code{__v8hi} argument and one @code{int} argument which 14114must be a 8-bit compile time constant. They return a @code{__v8hi} 14115result. 14116@example 14117__v8hi __builtin_arc_vd6tapf (__v8hi, const int) 14118__v8hi __builtin_arc_vmvaw (__v8hi, const int) 14119__v8hi __builtin_arc_vmvw (__v8hi, const int) 14120__v8hi __builtin_arc_vmvzw (__v8hi, const int) 14121@end example 14122 14123The following take two @code{int} arguments, the second of which which 14124must be a 8-bit compile time constant. They return a @code{__v8hi} 14125result: 14126@example 14127__v8hi __builtin_arc_vmovaw (int, const int) 14128__v8hi __builtin_arc_vmovw (int, const int) 14129__v8hi __builtin_arc_vmovzw (int, const int) 14130@end example 14131 14132The following take a single @code{__v8hi} argument and return a 14133@code{__v8hi} result: 14134@example 14135__v8hi __builtin_arc_vabsaw (__v8hi) 14136__v8hi __builtin_arc_vabsw (__v8hi) 14137__v8hi __builtin_arc_vaddsuw (__v8hi) 14138__v8hi __builtin_arc_vexch1 (__v8hi) 14139__v8hi __builtin_arc_vexch2 (__v8hi) 14140__v8hi __builtin_arc_vexch4 (__v8hi) 14141__v8hi __builtin_arc_vsignw (__v8hi) 14142__v8hi __builtin_arc_vupbaw (__v8hi) 14143__v8hi __builtin_arc_vupbw (__v8hi) 14144__v8hi __builtin_arc_vupsbaw (__v8hi) 14145__v8hi __builtin_arc_vupsbw (__v8hi) 14146@end example 14147 14148The following take two @code{int} arguments and return no result: 14149@example 14150void __builtin_arc_vdirun (int, int) 14151void __builtin_arc_vdorun (int, int) 14152@end example 14153 14154The following take two @code{int} arguments and return no result. The 14155first argument must a 3-bit compile time constant indicating one of 14156the DR0-DR7 DMA setup channels: 14157@example 14158void __builtin_arc_vdiwr (const int, int) 14159void __builtin_arc_vdowr (const int, int) 14160@end example 14161 14162The following take an @code{int} argument and return no result: 14163@example 14164void __builtin_arc_vendrec (int) 14165void __builtin_arc_vrec (int) 14166void __builtin_arc_vrecrun (int) 14167void __builtin_arc_vrun (int) 14168@end example 14169 14170The following take a @code{__v8hi} argument and two @code{int} 14171arguments and return a @code{__v8hi} result. The second argument must 14172be a 3-bit compile time constants, indicating one the registers I0-I7, 14173and the third argument must be an 8-bit compile time constant. 14174 14175@emph{Note:} Although the equivalent hardware instructions do not take 14176an SIMD register as an operand, these builtins overwrite the relevant 14177bits of the @code{__v8hi} register provided as the first argument with 14178the value loaded from the @code{[Ib, u8]} location in the SDM. 14179 14180@example 14181__v8hi __builtin_arc_vld32 (__v8hi, const int, const int) 14182__v8hi __builtin_arc_vld32wh (__v8hi, const int, const int) 14183__v8hi __builtin_arc_vld32wl (__v8hi, const int, const int) 14184__v8hi __builtin_arc_vld64 (__v8hi, const int, const int) 14185@end example 14186 14187The following take two @code{int} arguments and return a @code{__v8hi} 14188result. The first argument must be a 3-bit compile time constants, 14189indicating one the registers I0-I7, and the second argument must be an 141908-bit compile time constant. 14191 14192@example 14193__v8hi __builtin_arc_vld128 (const int, const int) 14194__v8hi __builtin_arc_vld64w (const int, const int) 14195@end example 14196 14197The following take a @code{__v8hi} argument and two @code{int} 14198arguments and return no result. The second argument must be a 3-bit 14199compile time constants, indicating one the registers I0-I7, and the 14200third argument must be an 8-bit compile time constant. 14201 14202@example 14203void __builtin_arc_vst128 (__v8hi, const int, const int) 14204void __builtin_arc_vst64 (__v8hi, const int, const int) 14205@end example 14206 14207The following take a @code{__v8hi} argument and three @code{int} 14208arguments and return no result. The second argument must be a 3-bit 14209compile-time constant, identifying the 16-bit sub-register to be 14210stored, the third argument must be a 3-bit compile time constants, 14211indicating one the registers I0-I7, and the fourth argument must be an 142128-bit compile time constant. 14213 14214@example 14215void __builtin_arc_vst16_n (__v8hi, const int, const int, const int) 14216void __builtin_arc_vst32_n (__v8hi, const int, const int, const int) 14217@end example 14218 14219@node ARM iWMMXt Built-in Functions 14220@subsection ARM iWMMXt Built-in Functions 14221 14222These built-in functions are available for the ARM family of 14223processors when the @option{-mcpu=iwmmxt} switch is used: 14224 14225@smallexample 14226typedef int v2si __attribute__ ((vector_size (8))); 14227typedef short v4hi __attribute__ ((vector_size (8))); 14228typedef char v8qi __attribute__ ((vector_size (8))); 14229 14230int __builtin_arm_getwcgr0 (void) 14231void __builtin_arm_setwcgr0 (int) 14232int __builtin_arm_getwcgr1 (void) 14233void __builtin_arm_setwcgr1 (int) 14234int __builtin_arm_getwcgr2 (void) 14235void __builtin_arm_setwcgr2 (int) 14236int __builtin_arm_getwcgr3 (void) 14237void __builtin_arm_setwcgr3 (int) 14238int __builtin_arm_textrmsb (v8qi, int) 14239int __builtin_arm_textrmsh (v4hi, int) 14240int __builtin_arm_textrmsw (v2si, int) 14241int __builtin_arm_textrmub (v8qi, int) 14242int __builtin_arm_textrmuh (v4hi, int) 14243int __builtin_arm_textrmuw (v2si, int) 14244v8qi __builtin_arm_tinsrb (v8qi, int, int) 14245v4hi __builtin_arm_tinsrh (v4hi, int, int) 14246v2si __builtin_arm_tinsrw (v2si, int, int) 14247long long __builtin_arm_tmia (long long, int, int) 14248long long __builtin_arm_tmiabb (long long, int, int) 14249long long __builtin_arm_tmiabt (long long, int, int) 14250long long __builtin_arm_tmiaph (long long, int, int) 14251long long __builtin_arm_tmiatb (long long, int, int) 14252long long __builtin_arm_tmiatt (long long, int, int) 14253int __builtin_arm_tmovmskb (v8qi) 14254int __builtin_arm_tmovmskh (v4hi) 14255int __builtin_arm_tmovmskw (v2si) 14256long long __builtin_arm_waccb (v8qi) 14257long long __builtin_arm_wacch (v4hi) 14258long long __builtin_arm_waccw (v2si) 14259v8qi __builtin_arm_waddb (v8qi, v8qi) 14260v8qi __builtin_arm_waddbss (v8qi, v8qi) 14261v8qi __builtin_arm_waddbus (v8qi, v8qi) 14262v4hi __builtin_arm_waddh (v4hi, v4hi) 14263v4hi __builtin_arm_waddhss (v4hi, v4hi) 14264v4hi __builtin_arm_waddhus (v4hi, v4hi) 14265v2si __builtin_arm_waddw (v2si, v2si) 14266v2si __builtin_arm_waddwss (v2si, v2si) 14267v2si __builtin_arm_waddwus (v2si, v2si) 14268v8qi __builtin_arm_walign (v8qi, v8qi, int) 14269long long __builtin_arm_wand(long long, long long) 14270long long __builtin_arm_wandn (long long, long long) 14271v8qi __builtin_arm_wavg2b (v8qi, v8qi) 14272v8qi __builtin_arm_wavg2br (v8qi, v8qi) 14273v4hi __builtin_arm_wavg2h (v4hi, v4hi) 14274v4hi __builtin_arm_wavg2hr (v4hi, v4hi) 14275v8qi __builtin_arm_wcmpeqb (v8qi, v8qi) 14276v4hi __builtin_arm_wcmpeqh (v4hi, v4hi) 14277v2si __builtin_arm_wcmpeqw (v2si, v2si) 14278v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi) 14279v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi) 14280v2si __builtin_arm_wcmpgtsw (v2si, v2si) 14281v8qi __builtin_arm_wcmpgtub (v8qi, v8qi) 14282v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi) 14283v2si __builtin_arm_wcmpgtuw (v2si, v2si) 14284long long __builtin_arm_wmacs (long long, v4hi, v4hi) 14285long long __builtin_arm_wmacsz (v4hi, v4hi) 14286long long __builtin_arm_wmacu (long long, v4hi, v4hi) 14287long long __builtin_arm_wmacuz (v4hi, v4hi) 14288v4hi __builtin_arm_wmadds (v4hi, v4hi) 14289v4hi __builtin_arm_wmaddu (v4hi, v4hi) 14290v8qi __builtin_arm_wmaxsb (v8qi, v8qi) 14291v4hi __builtin_arm_wmaxsh (v4hi, v4hi) 14292v2si __builtin_arm_wmaxsw (v2si, v2si) 14293v8qi __builtin_arm_wmaxub (v8qi, v8qi) 14294v4hi __builtin_arm_wmaxuh (v4hi, v4hi) 14295v2si __builtin_arm_wmaxuw (v2si, v2si) 14296v8qi __builtin_arm_wminsb (v8qi, v8qi) 14297v4hi __builtin_arm_wminsh (v4hi, v4hi) 14298v2si __builtin_arm_wminsw (v2si, v2si) 14299v8qi __builtin_arm_wminub (v8qi, v8qi) 14300v4hi __builtin_arm_wminuh (v4hi, v4hi) 14301v2si __builtin_arm_wminuw (v2si, v2si) 14302v4hi __builtin_arm_wmulsm (v4hi, v4hi) 14303v4hi __builtin_arm_wmulul (v4hi, v4hi) 14304v4hi __builtin_arm_wmulum (v4hi, v4hi) 14305long long __builtin_arm_wor (long long, long long) 14306v2si __builtin_arm_wpackdss (long long, long long) 14307v2si __builtin_arm_wpackdus (long long, long long) 14308v8qi __builtin_arm_wpackhss (v4hi, v4hi) 14309v8qi __builtin_arm_wpackhus (v4hi, v4hi) 14310v4hi __builtin_arm_wpackwss (v2si, v2si) 14311v4hi __builtin_arm_wpackwus (v2si, v2si) 14312long long __builtin_arm_wrord (long long, long long) 14313long long __builtin_arm_wrordi (long long, int) 14314v4hi __builtin_arm_wrorh (v4hi, long long) 14315v4hi __builtin_arm_wrorhi (v4hi, int) 14316v2si __builtin_arm_wrorw (v2si, long long) 14317v2si __builtin_arm_wrorwi (v2si, int) 14318v2si __builtin_arm_wsadb (v2si, v8qi, v8qi) 14319v2si __builtin_arm_wsadbz (v8qi, v8qi) 14320v2si __builtin_arm_wsadh (v2si, v4hi, v4hi) 14321v2si __builtin_arm_wsadhz (v4hi, v4hi) 14322v4hi __builtin_arm_wshufh (v4hi, int) 14323long long __builtin_arm_wslld (long long, long long) 14324long long __builtin_arm_wslldi (long long, int) 14325v4hi __builtin_arm_wsllh (v4hi, long long) 14326v4hi __builtin_arm_wsllhi (v4hi, int) 14327v2si __builtin_arm_wsllw (v2si, long long) 14328v2si __builtin_arm_wsllwi (v2si, int) 14329long long __builtin_arm_wsrad (long long, long long) 14330long long __builtin_arm_wsradi (long long, int) 14331v4hi __builtin_arm_wsrah (v4hi, long long) 14332v4hi __builtin_arm_wsrahi (v4hi, int) 14333v2si __builtin_arm_wsraw (v2si, long long) 14334v2si __builtin_arm_wsrawi (v2si, int) 14335long long __builtin_arm_wsrld (long long, long long) 14336long long __builtin_arm_wsrldi (long long, int) 14337v4hi __builtin_arm_wsrlh (v4hi, long long) 14338v4hi __builtin_arm_wsrlhi (v4hi, int) 14339v2si __builtin_arm_wsrlw (v2si, long long) 14340v2si __builtin_arm_wsrlwi (v2si, int) 14341v8qi __builtin_arm_wsubb (v8qi, v8qi) 14342v8qi __builtin_arm_wsubbss (v8qi, v8qi) 14343v8qi __builtin_arm_wsubbus (v8qi, v8qi) 14344v4hi __builtin_arm_wsubh (v4hi, v4hi) 14345v4hi __builtin_arm_wsubhss (v4hi, v4hi) 14346v4hi __builtin_arm_wsubhus (v4hi, v4hi) 14347v2si __builtin_arm_wsubw (v2si, v2si) 14348v2si __builtin_arm_wsubwss (v2si, v2si) 14349v2si __builtin_arm_wsubwus (v2si, v2si) 14350v4hi __builtin_arm_wunpckehsb (v8qi) 14351v2si __builtin_arm_wunpckehsh (v4hi) 14352long long __builtin_arm_wunpckehsw (v2si) 14353v4hi __builtin_arm_wunpckehub (v8qi) 14354v2si __builtin_arm_wunpckehuh (v4hi) 14355long long __builtin_arm_wunpckehuw (v2si) 14356v4hi __builtin_arm_wunpckelsb (v8qi) 14357v2si __builtin_arm_wunpckelsh (v4hi) 14358long long __builtin_arm_wunpckelsw (v2si) 14359v4hi __builtin_arm_wunpckelub (v8qi) 14360v2si __builtin_arm_wunpckeluh (v4hi) 14361long long __builtin_arm_wunpckeluw (v2si) 14362v8qi __builtin_arm_wunpckihb (v8qi, v8qi) 14363v4hi __builtin_arm_wunpckihh (v4hi, v4hi) 14364v2si __builtin_arm_wunpckihw (v2si, v2si) 14365v8qi __builtin_arm_wunpckilb (v8qi, v8qi) 14366v4hi __builtin_arm_wunpckilh (v4hi, v4hi) 14367v2si __builtin_arm_wunpckilw (v2si, v2si) 14368long long __builtin_arm_wxor (long long, long long) 14369long long __builtin_arm_wzero () 14370@end smallexample 14371 14372 14373@node ARM C Language Extensions (ACLE) 14374@subsection ARM C Language Extensions (ACLE) 14375 14376GCC implements extensions for C as described in the ARM C Language 14377Extensions (ACLE) specification, which can be found at 14378@uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf}. 14379 14380As a part of ACLE, GCC implements extensions for Advanced SIMD as described in 14381the ARM C Language Extensions Specification. The complete list of Advanced SIMD 14382intrinsics can be found at 14383@uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0073a/IHI0073A_arm_neon_intrinsics_ref.pdf}. 14384The built-in intrinsics for the Advanced SIMD extension are available when 14385NEON is enabled. 14386 14387Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both 14388back ends support CRC32 intrinsics and the ARM back end supports the 14389Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit 14390floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1. 14391AArch64's back end does not have support for 16-bit floating point Advanced SIMD 14392intrinsics yet. 14393 14394See @ref{ARM Options} and @ref{AArch64 Options} for more information on the 14395availability of extensions. 14396 14397@node ARM Floating Point Status and Control Intrinsics 14398@subsection ARM Floating Point Status and Control Intrinsics 14399 14400These built-in functions are available for the ARM family of 14401processors with floating-point unit. 14402 14403@smallexample 14404unsigned int __builtin_arm_get_fpscr () 14405void __builtin_arm_set_fpscr (unsigned int) 14406@end smallexample 14407 14408@node ARM ARMv8-M Security Extensions 14409@subsection ARM ARMv8-M Security Extensions 14410 14411GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M 14412Security Extensions: Requirements on Development Tools Engineering 14413Specification, which can be found at 14414@uref{http://infocenter.arm.com/help/topic/com.arm.doc.ecm0359818/ECM0359818_armv8m_security_extensions_reqs_on_dev_tools_1_0.pdf}. 14415 14416As part of the Security Extensions GCC implements two new function attributes: 14417@code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}. 14418 14419As part of the Security Extensions GCC implements the intrinsics below. FPTR 14420is used here to mean any function pointer type. 14421 14422@smallexample 14423cmse_address_info_t cmse_TT (void *) 14424cmse_address_info_t cmse_TT_fptr (FPTR) 14425cmse_address_info_t cmse_TTT (void *) 14426cmse_address_info_t cmse_TTT_fptr (FPTR) 14427cmse_address_info_t cmse_TTA (void *) 14428cmse_address_info_t cmse_TTA_fptr (FPTR) 14429cmse_address_info_t cmse_TTAT (void *) 14430cmse_address_info_t cmse_TTAT_fptr (FPTR) 14431void * cmse_check_address_range (void *, size_t, int) 14432typeof(p) cmse_nsfptr_create (FPTR p) 14433intptr_t cmse_is_nsfptr (FPTR) 14434int cmse_nonsecure_caller (void) 14435@end smallexample 14436 14437@node AVR Built-in Functions 14438@subsection AVR Built-in Functions 14439 14440For each built-in function for AVR, there is an equally named, 14441uppercase built-in macro defined. That way users can easily query if 14442or if not a specific built-in is implemented or not. For example, if 14443@code{__builtin_avr_nop} is available the macro 14444@code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise. 14445 14446@table @code 14447 14448@item void __builtin_avr_nop (void) 14449@itemx void __builtin_avr_sei (void) 14450@itemx void __builtin_avr_cli (void) 14451@itemx void __builtin_avr_sleep (void) 14452@itemx void __builtin_avr_wdr (void) 14453@itemx unsigned char __builtin_avr_swap (unsigned char) 14454@itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char) 14455@itemx int __builtin_avr_fmuls (char, char) 14456@itemx int __builtin_avr_fmulsu (char, unsigned char) 14457These built-in functions map to the respective machine 14458instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep}, 14459@code{wdr}, @code{swap}, @code{fmul}, @code{fmuls} 14460resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented 14461as library call if no hardware multiplier is available. 14462 14463@item void __builtin_avr_delay_cycles (unsigned long ticks) 14464Delay execution for @var{ticks} cycles. Note that this 14465built-in does not take into account the effect of interrupts that 14466might increase delay time. @var{ticks} must be a compile-time 14467integer constant; delays with a variable number of cycles are not supported. 14468 14469@item char __builtin_avr_flash_segment (const __memx void*) 14470This built-in takes a byte address to the 24-bit 14471@ref{AVR Named Address Spaces,address space} @code{__memx} and returns 14472the number of the flash segment (the 64 KiB chunk) where the address 14473points to. Counting starts at @code{0}. 14474If the address does not point to flash memory, return @code{-1}. 14475 14476@item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val) 14477Insert bits from @var{bits} into @var{val} and return the resulting 14478value. The nibbles of @var{map} determine how the insertion is 14479performed: Let @var{X} be the @var{n}-th nibble of @var{map} 14480@enumerate 14481@item If @var{X} is @code{0xf}, 14482then the @var{n}-th bit of @var{val} is returned unaltered. 14483 14484@item If X is in the range 0@dots{}7, 14485then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits} 14486 14487@item If X is in the range 8@dots{}@code{0xe}, 14488then the @var{n}-th result bit is undefined. 14489@end enumerate 14490 14491@noindent 14492One typical use case for this built-in is adjusting input and 14493output values to non-contiguous port layouts. Some examples: 14494 14495@smallexample 14496// same as val, bits is unused 14497__builtin_avr_insert_bits (0xffffffff, bits, val) 14498@end smallexample 14499 14500@smallexample 14501// same as bits, val is unused 14502__builtin_avr_insert_bits (0x76543210, bits, val) 14503@end smallexample 14504 14505@smallexample 14506// same as rotating bits by 4 14507__builtin_avr_insert_bits (0x32107654, bits, 0) 14508@end smallexample 14509 14510@smallexample 14511// high nibble of result is the high nibble of val 14512// low nibble of result is the low nibble of bits 14513__builtin_avr_insert_bits (0xffff3210, bits, val) 14514@end smallexample 14515 14516@smallexample 14517// reverse the bit order of bits 14518__builtin_avr_insert_bits (0x01234567, bits, 0) 14519@end smallexample 14520 14521@item void __builtin_avr_nops (unsigned count) 14522Insert @var{count} @code{NOP} instructions. 14523The number of instructions must be a compile-time integer constant. 14524 14525@end table 14526 14527@noindent 14528There are many more AVR-specific built-in functions that are used to 14529implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of 14530section 7.18a.6. You don't need to use these built-ins directly. 14531Instead, use the declarations as supplied by the @code{stdfix.h} header 14532with GNU-C99: 14533 14534@smallexample 14535#include <stdfix.h> 14536 14537// Re-interpret the bit representation of unsigned 16-bit 14538// integer @var{uval} as Q-format 0.16 value. 14539unsigned fract get_bits (uint_ur_t uval) 14540@{ 14541 return urbits (uval); 14542@} 14543@end smallexample 14544 14545@node Blackfin Built-in Functions 14546@subsection Blackfin Built-in Functions 14547 14548Currently, there are two Blackfin-specific built-in functions. These are 14549used for generating @code{CSYNC} and @code{SSYNC} machine insns without 14550using inline assembly; by using these built-in functions the compiler can 14551automatically add workarounds for hardware errata involving these 14552instructions. These functions are named as follows: 14553 14554@smallexample 14555void __builtin_bfin_csync (void) 14556void __builtin_bfin_ssync (void) 14557@end smallexample 14558 14559@node FR-V Built-in Functions 14560@subsection FR-V Built-in Functions 14561 14562GCC provides many FR-V-specific built-in functions. In general, 14563these functions are intended to be compatible with those described 14564by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu 14565Semiconductor}. The two exceptions are @code{__MDUNPACKH} and 14566@code{__MBTOHE}, the GCC forms of which pass 128-bit values by 14567pointer rather than by value. 14568 14569Most of the functions are named after specific FR-V instructions. 14570Such functions are said to be ``directly mapped'' and are summarized 14571here in tabular form. 14572 14573@menu 14574* Argument Types:: 14575* Directly-mapped Integer Functions:: 14576* Directly-mapped Media Functions:: 14577* Raw read/write Functions:: 14578* Other Built-in Functions:: 14579@end menu 14580 14581@node Argument Types 14582@subsubsection Argument Types 14583 14584The arguments to the built-in functions can be divided into three groups: 14585register numbers, compile-time constants and run-time values. In order 14586to make this classification clear at a glance, the arguments and return 14587values are given the following pseudo types: 14588 14589@multitable @columnfractions .20 .30 .15 .35 14590@item Pseudo type @tab Real C type @tab Constant? @tab Description 14591@item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword 14592@item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word 14593@item @code{sw1} @tab @code{int} @tab No @tab a signed word 14594@item @code{uw2} @tab @code{unsigned long long} @tab No 14595@tab an unsigned doubleword 14596@item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword 14597@item @code{const} @tab @code{int} @tab Yes @tab an integer constant 14598@item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number 14599@item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number 14600@end multitable 14601 14602These pseudo types are not defined by GCC, they are simply a notational 14603convenience used in this manual. 14604 14605Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2} 14606and @code{sw2} are evaluated at run time. They correspond to 14607register operands in the underlying FR-V instructions. 14608 14609@code{const} arguments represent immediate operands in the underlying 14610FR-V instructions. They must be compile-time constants. 14611 14612@code{acc} arguments are evaluated at compile time and specify the number 14613of an accumulator register. For example, an @code{acc} argument of 2 14614selects the ACC2 register. 14615 14616@code{iacc} arguments are similar to @code{acc} arguments but specify the 14617number of an IACC register. See @pxref{Other Built-in Functions} 14618for more details. 14619 14620@node Directly-mapped Integer Functions 14621@subsubsection Directly-Mapped Integer Functions 14622 14623The functions listed below map directly to FR-V I-type instructions. 14624 14625@multitable @columnfractions .45 .32 .23 14626@item Function prototype @tab Example usage @tab Assembly output 14627@item @code{sw1 __ADDSS (sw1, sw1)} 14628@tab @code{@var{c} = __ADDSS (@var{a}, @var{b})} 14629@tab @code{ADDSS @var{a},@var{b},@var{c}} 14630@item @code{sw1 __SCAN (sw1, sw1)} 14631@tab @code{@var{c} = __SCAN (@var{a}, @var{b})} 14632@tab @code{SCAN @var{a},@var{b},@var{c}} 14633@item @code{sw1 __SCUTSS (sw1)} 14634@tab @code{@var{b} = __SCUTSS (@var{a})} 14635@tab @code{SCUTSS @var{a},@var{b}} 14636@item @code{sw1 __SLASS (sw1, sw1)} 14637@tab @code{@var{c} = __SLASS (@var{a}, @var{b})} 14638@tab @code{SLASS @var{a},@var{b},@var{c}} 14639@item @code{void __SMASS (sw1, sw1)} 14640@tab @code{__SMASS (@var{a}, @var{b})} 14641@tab @code{SMASS @var{a},@var{b}} 14642@item @code{void __SMSSS (sw1, sw1)} 14643@tab @code{__SMSSS (@var{a}, @var{b})} 14644@tab @code{SMSSS @var{a},@var{b}} 14645@item @code{void __SMU (sw1, sw1)} 14646@tab @code{__SMU (@var{a}, @var{b})} 14647@tab @code{SMU @var{a},@var{b}} 14648@item @code{sw2 __SMUL (sw1, sw1)} 14649@tab @code{@var{c} = __SMUL (@var{a}, @var{b})} 14650@tab @code{SMUL @var{a},@var{b},@var{c}} 14651@item @code{sw1 __SUBSS (sw1, sw1)} 14652@tab @code{@var{c} = __SUBSS (@var{a}, @var{b})} 14653@tab @code{SUBSS @var{a},@var{b},@var{c}} 14654@item @code{uw2 __UMUL (uw1, uw1)} 14655@tab @code{@var{c} = __UMUL (@var{a}, @var{b})} 14656@tab @code{UMUL @var{a},@var{b},@var{c}} 14657@end multitable 14658 14659@node Directly-mapped Media Functions 14660@subsubsection Directly-Mapped Media Functions 14661 14662The functions listed below map directly to FR-V M-type instructions. 14663 14664@multitable @columnfractions .45 .32 .23 14665@item Function prototype @tab Example usage @tab Assembly output 14666@item @code{uw1 __MABSHS (sw1)} 14667@tab @code{@var{b} = __MABSHS (@var{a})} 14668@tab @code{MABSHS @var{a},@var{b}} 14669@item @code{void __MADDACCS (acc, acc)} 14670@tab @code{__MADDACCS (@var{b}, @var{a})} 14671@tab @code{MADDACCS @var{a},@var{b}} 14672@item @code{sw1 __MADDHSS (sw1, sw1)} 14673@tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})} 14674@tab @code{MADDHSS @var{a},@var{b},@var{c}} 14675@item @code{uw1 __MADDHUS (uw1, uw1)} 14676@tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})} 14677@tab @code{MADDHUS @var{a},@var{b},@var{c}} 14678@item @code{uw1 __MAND (uw1, uw1)} 14679@tab @code{@var{c} = __MAND (@var{a}, @var{b})} 14680@tab @code{MAND @var{a},@var{b},@var{c}} 14681@item @code{void __MASACCS (acc, acc)} 14682@tab @code{__MASACCS (@var{b}, @var{a})} 14683@tab @code{MASACCS @var{a},@var{b}} 14684@item @code{uw1 __MAVEH (uw1, uw1)} 14685@tab @code{@var{c} = __MAVEH (@var{a}, @var{b})} 14686@tab @code{MAVEH @var{a},@var{b},@var{c}} 14687@item @code{uw2 __MBTOH (uw1)} 14688@tab @code{@var{b} = __MBTOH (@var{a})} 14689@tab @code{MBTOH @var{a},@var{b}} 14690@item @code{void __MBTOHE (uw1 *, uw1)} 14691@tab @code{__MBTOHE (&@var{b}, @var{a})} 14692@tab @code{MBTOHE @var{a},@var{b}} 14693@item @code{void __MCLRACC (acc)} 14694@tab @code{__MCLRACC (@var{a})} 14695@tab @code{MCLRACC @var{a}} 14696@item @code{void __MCLRACCA (void)} 14697@tab @code{__MCLRACCA ()} 14698@tab @code{MCLRACCA} 14699@item @code{uw1 __Mcop1 (uw1, uw1)} 14700@tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})} 14701@tab @code{Mcop1 @var{a},@var{b},@var{c}} 14702@item @code{uw1 __Mcop2 (uw1, uw1)} 14703@tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})} 14704@tab @code{Mcop2 @var{a},@var{b},@var{c}} 14705@item @code{uw1 __MCPLHI (uw2, const)} 14706@tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})} 14707@tab @code{MCPLHI @var{a},#@var{b},@var{c}} 14708@item @code{uw1 __MCPLI (uw2, const)} 14709@tab @code{@var{c} = __MCPLI (@var{a}, @var{b})} 14710@tab @code{MCPLI @var{a},#@var{b},@var{c}} 14711@item @code{void __MCPXIS (acc, sw1, sw1)} 14712@tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})} 14713@tab @code{MCPXIS @var{a},@var{b},@var{c}} 14714@item @code{void __MCPXIU (acc, uw1, uw1)} 14715@tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})} 14716@tab @code{MCPXIU @var{a},@var{b},@var{c}} 14717@item @code{void __MCPXRS (acc, sw1, sw1)} 14718@tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})} 14719@tab @code{MCPXRS @var{a},@var{b},@var{c}} 14720@item @code{void __MCPXRU (acc, uw1, uw1)} 14721@tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})} 14722@tab @code{MCPXRU @var{a},@var{b},@var{c}} 14723@item @code{uw1 __MCUT (acc, uw1)} 14724@tab @code{@var{c} = __MCUT (@var{a}, @var{b})} 14725@tab @code{MCUT @var{a},@var{b},@var{c}} 14726@item @code{uw1 __MCUTSS (acc, sw1)} 14727@tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})} 14728@tab @code{MCUTSS @var{a},@var{b},@var{c}} 14729@item @code{void __MDADDACCS (acc, acc)} 14730@tab @code{__MDADDACCS (@var{b}, @var{a})} 14731@tab @code{MDADDACCS @var{a},@var{b}} 14732@item @code{void __MDASACCS (acc, acc)} 14733@tab @code{__MDASACCS (@var{b}, @var{a})} 14734@tab @code{MDASACCS @var{a},@var{b}} 14735@item @code{uw2 __MDCUTSSI (acc, const)} 14736@tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})} 14737@tab @code{MDCUTSSI @var{a},#@var{b},@var{c}} 14738@item @code{uw2 __MDPACKH (uw2, uw2)} 14739@tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})} 14740@tab @code{MDPACKH @var{a},@var{b},@var{c}} 14741@item @code{uw2 __MDROTLI (uw2, const)} 14742@tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})} 14743@tab @code{MDROTLI @var{a},#@var{b},@var{c}} 14744@item @code{void __MDSUBACCS (acc, acc)} 14745@tab @code{__MDSUBACCS (@var{b}, @var{a})} 14746@tab @code{MDSUBACCS @var{a},@var{b}} 14747@item @code{void __MDUNPACKH (uw1 *, uw2)} 14748@tab @code{__MDUNPACKH (&@var{b}, @var{a})} 14749@tab @code{MDUNPACKH @var{a},@var{b}} 14750@item @code{uw2 __MEXPDHD (uw1, const)} 14751@tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})} 14752@tab @code{MEXPDHD @var{a},#@var{b},@var{c}} 14753@item @code{uw1 __MEXPDHW (uw1, const)} 14754@tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})} 14755@tab @code{MEXPDHW @var{a},#@var{b},@var{c}} 14756@item @code{uw1 __MHDSETH (uw1, const)} 14757@tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})} 14758@tab @code{MHDSETH @var{a},#@var{b},@var{c}} 14759@item @code{sw1 __MHDSETS (const)} 14760@tab @code{@var{b} = __MHDSETS (@var{a})} 14761@tab @code{MHDSETS #@var{a},@var{b}} 14762@item @code{uw1 __MHSETHIH (uw1, const)} 14763@tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})} 14764@tab @code{MHSETHIH #@var{a},@var{b}} 14765@item @code{sw1 __MHSETHIS (sw1, const)} 14766@tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})} 14767@tab @code{MHSETHIS #@var{a},@var{b}} 14768@item @code{uw1 __MHSETLOH (uw1, const)} 14769@tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})} 14770@tab @code{MHSETLOH #@var{a},@var{b}} 14771@item @code{sw1 __MHSETLOS (sw1, const)} 14772@tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})} 14773@tab @code{MHSETLOS #@var{a},@var{b}} 14774@item @code{uw1 __MHTOB (uw2)} 14775@tab @code{@var{b} = __MHTOB (@var{a})} 14776@tab @code{MHTOB @var{a},@var{b}} 14777@item @code{void __MMACHS (acc, sw1, sw1)} 14778@tab @code{__MMACHS (@var{c}, @var{a}, @var{b})} 14779@tab @code{MMACHS @var{a},@var{b},@var{c}} 14780@item @code{void __MMACHU (acc, uw1, uw1)} 14781@tab @code{__MMACHU (@var{c}, @var{a}, @var{b})} 14782@tab @code{MMACHU @var{a},@var{b},@var{c}} 14783@item @code{void __MMRDHS (acc, sw1, sw1)} 14784@tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})} 14785@tab @code{MMRDHS @var{a},@var{b},@var{c}} 14786@item @code{void __MMRDHU (acc, uw1, uw1)} 14787@tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})} 14788@tab @code{MMRDHU @var{a},@var{b},@var{c}} 14789@item @code{void __MMULHS (acc, sw1, sw1)} 14790@tab @code{__MMULHS (@var{c}, @var{a}, @var{b})} 14791@tab @code{MMULHS @var{a},@var{b},@var{c}} 14792@item @code{void __MMULHU (acc, uw1, uw1)} 14793@tab @code{__MMULHU (@var{c}, @var{a}, @var{b})} 14794@tab @code{MMULHU @var{a},@var{b},@var{c}} 14795@item @code{void __MMULXHS (acc, sw1, sw1)} 14796@tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})} 14797@tab @code{MMULXHS @var{a},@var{b},@var{c}} 14798@item @code{void __MMULXHU (acc, uw1, uw1)} 14799@tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})} 14800@tab @code{MMULXHU @var{a},@var{b},@var{c}} 14801@item @code{uw1 __MNOT (uw1)} 14802@tab @code{@var{b} = __MNOT (@var{a})} 14803@tab @code{MNOT @var{a},@var{b}} 14804@item @code{uw1 __MOR (uw1, uw1)} 14805@tab @code{@var{c} = __MOR (@var{a}, @var{b})} 14806@tab @code{MOR @var{a},@var{b},@var{c}} 14807@item @code{uw1 __MPACKH (uh, uh)} 14808@tab @code{@var{c} = __MPACKH (@var{a}, @var{b})} 14809@tab @code{MPACKH @var{a},@var{b},@var{c}} 14810@item @code{sw2 __MQADDHSS (sw2, sw2)} 14811@tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})} 14812@tab @code{MQADDHSS @var{a},@var{b},@var{c}} 14813@item @code{uw2 __MQADDHUS (uw2, uw2)} 14814@tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})} 14815@tab @code{MQADDHUS @var{a},@var{b},@var{c}} 14816@item @code{void __MQCPXIS (acc, sw2, sw2)} 14817@tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})} 14818@tab @code{MQCPXIS @var{a},@var{b},@var{c}} 14819@item @code{void __MQCPXIU (acc, uw2, uw2)} 14820@tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})} 14821@tab @code{MQCPXIU @var{a},@var{b},@var{c}} 14822@item @code{void __MQCPXRS (acc, sw2, sw2)} 14823@tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})} 14824@tab @code{MQCPXRS @var{a},@var{b},@var{c}} 14825@item @code{void __MQCPXRU (acc, uw2, uw2)} 14826@tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})} 14827@tab @code{MQCPXRU @var{a},@var{b},@var{c}} 14828@item @code{sw2 __MQLCLRHS (sw2, sw2)} 14829@tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})} 14830@tab @code{MQLCLRHS @var{a},@var{b},@var{c}} 14831@item @code{sw2 __MQLMTHS (sw2, sw2)} 14832@tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})} 14833@tab @code{MQLMTHS @var{a},@var{b},@var{c}} 14834@item @code{void __MQMACHS (acc, sw2, sw2)} 14835@tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})} 14836@tab @code{MQMACHS @var{a},@var{b},@var{c}} 14837@item @code{void __MQMACHU (acc, uw2, uw2)} 14838@tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})} 14839@tab @code{MQMACHU @var{a},@var{b},@var{c}} 14840@item @code{void __MQMACXHS (acc, sw2, sw2)} 14841@tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})} 14842@tab @code{MQMACXHS @var{a},@var{b},@var{c}} 14843@item @code{void __MQMULHS (acc, sw2, sw2)} 14844@tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})} 14845@tab @code{MQMULHS @var{a},@var{b},@var{c}} 14846@item @code{void __MQMULHU (acc, uw2, uw2)} 14847@tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})} 14848@tab @code{MQMULHU @var{a},@var{b},@var{c}} 14849@item @code{void __MQMULXHS (acc, sw2, sw2)} 14850@tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})} 14851@tab @code{MQMULXHS @var{a},@var{b},@var{c}} 14852@item @code{void __MQMULXHU (acc, uw2, uw2)} 14853@tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})} 14854@tab @code{MQMULXHU @var{a},@var{b},@var{c}} 14855@item @code{sw2 __MQSATHS (sw2, sw2)} 14856@tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})} 14857@tab @code{MQSATHS @var{a},@var{b},@var{c}} 14858@item @code{uw2 __MQSLLHI (uw2, int)} 14859@tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})} 14860@tab @code{MQSLLHI @var{a},@var{b},@var{c}} 14861@item @code{sw2 __MQSRAHI (sw2, int)} 14862@tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})} 14863@tab @code{MQSRAHI @var{a},@var{b},@var{c}} 14864@item @code{sw2 __MQSUBHSS (sw2, sw2)} 14865@tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})} 14866@tab @code{MQSUBHSS @var{a},@var{b},@var{c}} 14867@item @code{uw2 __MQSUBHUS (uw2, uw2)} 14868@tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})} 14869@tab @code{MQSUBHUS @var{a},@var{b},@var{c}} 14870@item @code{void __MQXMACHS (acc, sw2, sw2)} 14871@tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})} 14872@tab @code{MQXMACHS @var{a},@var{b},@var{c}} 14873@item @code{void __MQXMACXHS (acc, sw2, sw2)} 14874@tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})} 14875@tab @code{MQXMACXHS @var{a},@var{b},@var{c}} 14876@item @code{uw1 __MRDACC (acc)} 14877@tab @code{@var{b} = __MRDACC (@var{a})} 14878@tab @code{MRDACC @var{a},@var{b}} 14879@item @code{uw1 __MRDACCG (acc)} 14880@tab @code{@var{b} = __MRDACCG (@var{a})} 14881@tab @code{MRDACCG @var{a},@var{b}} 14882@item @code{uw1 __MROTLI (uw1, const)} 14883@tab @code{@var{c} = __MROTLI (@var{a}, @var{b})} 14884@tab @code{MROTLI @var{a},#@var{b},@var{c}} 14885@item @code{uw1 __MROTRI (uw1, const)} 14886@tab @code{@var{c} = __MROTRI (@var{a}, @var{b})} 14887@tab @code{MROTRI @var{a},#@var{b},@var{c}} 14888@item @code{sw1 __MSATHS (sw1, sw1)} 14889@tab @code{@var{c} = __MSATHS (@var{a}, @var{b})} 14890@tab @code{MSATHS @var{a},@var{b},@var{c}} 14891@item @code{uw1 __MSATHU (uw1, uw1)} 14892@tab @code{@var{c} = __MSATHU (@var{a}, @var{b})} 14893@tab @code{MSATHU @var{a},@var{b},@var{c}} 14894@item @code{uw1 __MSLLHI (uw1, const)} 14895@tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})} 14896@tab @code{MSLLHI @var{a},#@var{b},@var{c}} 14897@item @code{sw1 __MSRAHI (sw1, const)} 14898@tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})} 14899@tab @code{MSRAHI @var{a},#@var{b},@var{c}} 14900@item @code{uw1 __MSRLHI (uw1, const)} 14901@tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})} 14902@tab @code{MSRLHI @var{a},#@var{b},@var{c}} 14903@item @code{void __MSUBACCS (acc, acc)} 14904@tab @code{__MSUBACCS (@var{b}, @var{a})} 14905@tab @code{MSUBACCS @var{a},@var{b}} 14906@item @code{sw1 __MSUBHSS (sw1, sw1)} 14907@tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})} 14908@tab @code{MSUBHSS @var{a},@var{b},@var{c}} 14909@item @code{uw1 __MSUBHUS (uw1, uw1)} 14910@tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})} 14911@tab @code{MSUBHUS @var{a},@var{b},@var{c}} 14912@item @code{void __MTRAP (void)} 14913@tab @code{__MTRAP ()} 14914@tab @code{MTRAP} 14915@item @code{uw2 __MUNPACKH (uw1)} 14916@tab @code{@var{b} = __MUNPACKH (@var{a})} 14917@tab @code{MUNPACKH @var{a},@var{b}} 14918@item @code{uw1 __MWCUT (uw2, uw1)} 14919@tab @code{@var{c} = __MWCUT (@var{a}, @var{b})} 14920@tab @code{MWCUT @var{a},@var{b},@var{c}} 14921@item @code{void __MWTACC (acc, uw1)} 14922@tab @code{__MWTACC (@var{b}, @var{a})} 14923@tab @code{MWTACC @var{a},@var{b}} 14924@item @code{void __MWTACCG (acc, uw1)} 14925@tab @code{__MWTACCG (@var{b}, @var{a})} 14926@tab @code{MWTACCG @var{a},@var{b}} 14927@item @code{uw1 __MXOR (uw1, uw1)} 14928@tab @code{@var{c} = __MXOR (@var{a}, @var{b})} 14929@tab @code{MXOR @var{a},@var{b},@var{c}} 14930@end multitable 14931 14932@node Raw read/write Functions 14933@subsubsection Raw Read/Write Functions 14934 14935This sections describes built-in functions related to read and write 14936instructions to access memory. These functions generate 14937@code{membar} instructions to flush the I/O load and stores where 14938appropriate, as described in Fujitsu's manual described above. 14939 14940@table @code 14941 14942@item unsigned char __builtin_read8 (void *@var{data}) 14943@item unsigned short __builtin_read16 (void *@var{data}) 14944@item unsigned long __builtin_read32 (void *@var{data}) 14945@item unsigned long long __builtin_read64 (void *@var{data}) 14946 14947@item void __builtin_write8 (void *@var{data}, unsigned char @var{datum}) 14948@item void __builtin_write16 (void *@var{data}, unsigned short @var{datum}) 14949@item void __builtin_write32 (void *@var{data}, unsigned long @var{datum}) 14950@item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum}) 14951@end table 14952 14953@node Other Built-in Functions 14954@subsubsection Other Built-in Functions 14955 14956This section describes built-in functions that are not named after 14957a specific FR-V instruction. 14958 14959@table @code 14960@item sw2 __IACCreadll (iacc @var{reg}) 14961Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved 14962for future expansion and must be 0. 14963 14964@item sw1 __IACCreadl (iacc @var{reg}) 14965Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1. 14966Other values of @var{reg} are rejected as invalid. 14967 14968@item void __IACCsetll (iacc @var{reg}, sw2 @var{x}) 14969Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument 14970is reserved for future expansion and must be 0. 14971 14972@item void __IACCsetl (iacc @var{reg}, sw1 @var{x}) 14973Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg} 14974is 1. Other values of @var{reg} are rejected as invalid. 14975 14976@item void __data_prefetch0 (const void *@var{x}) 14977Use the @code{dcpl} instruction to load the contents of address @var{x} 14978into the data cache. 14979 14980@item void __data_prefetch (const void *@var{x}) 14981Use the @code{nldub} instruction to load the contents of address @var{x} 14982into the data cache. The instruction is issued in slot I1@. 14983@end table 14984 14985@node MIPS DSP Built-in Functions 14986@subsection MIPS DSP Built-in Functions 14987 14988The MIPS DSP Application-Specific Extension (ASE) includes new 14989instructions that are designed to improve the performance of DSP and 14990media applications. It provides instructions that operate on packed 149918-bit/16-bit integer data, Q7, Q15 and Q31 fractional data. 14992 14993GCC supports MIPS DSP operations using both the generic 14994vector extensions (@pxref{Vector Extensions}) and a collection of 14995MIPS-specific built-in functions. Both kinds of support are 14996enabled by the @option{-mdsp} command-line option. 14997 14998Revision 2 of the ASE was introduced in the second half of 2006. 14999This revision adds extra instructions to the original ASE, but is 15000otherwise backwards-compatible with it. You can select revision 2 15001using the command-line option @option{-mdspr2}; this option implies 15002@option{-mdsp}. 15003 15004The SCOUNT and POS bits of the DSP control register are global. The 15005WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and 15006POS bits. During optimization, the compiler does not delete these 15007instructions and it does not delete calls to functions containing 15008these instructions. 15009 15010At present, GCC only provides support for operations on 32-bit 15011vectors. The vector type associated with 8-bit integer data is 15012usually called @code{v4i8}, the vector type associated with Q7 15013is usually called @code{v4q7}, the vector type associated with 16-bit 15014integer data is usually called @code{v2i16}, and the vector type 15015associated with Q15 is usually called @code{v2q15}. They can be 15016defined in C as follows: 15017 15018@smallexample 15019typedef signed char v4i8 __attribute__ ((vector_size(4))); 15020typedef signed char v4q7 __attribute__ ((vector_size(4))); 15021typedef short v2i16 __attribute__ ((vector_size(4))); 15022typedef short v2q15 __attribute__ ((vector_size(4))); 15023@end smallexample 15024 15025@code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are 15026initialized in the same way as aggregates. For example: 15027 15028@smallexample 15029v4i8 a = @{1, 2, 3, 4@}; 15030v4i8 b; 15031b = (v4i8) @{5, 6, 7, 8@}; 15032 15033v2q15 c = @{0x0fcb, 0x3a75@}; 15034v2q15 d; 15035d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; 15036@end smallexample 15037 15038@emph{Note:} The CPU's endianness determines the order in which values 15039are packed. On little-endian targets, the first value is the least 15040significant and the last value is the most significant. The opposite 15041order applies to big-endian targets. For example, the code above 15042sets the lowest byte of @code{a} to @code{1} on little-endian targets 15043and @code{4} on big-endian targets. 15044 15045@emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer 15046representation. As shown in this example, the integer representation 15047of a Q7 value can be obtained by multiplying the fractional value by 15048@code{0x1.0p7}. The equivalent for Q15 values is to multiply by 15049@code{0x1.0p15}. The equivalent for Q31 values is to multiply by 15050@code{0x1.0p31}. 15051 15052The table below lists the @code{v4i8} and @code{v2q15} operations for which 15053hardware support exists. @code{a} and @code{b} are @code{v4i8} values, 15054and @code{c} and @code{d} are @code{v2q15} values. 15055 15056@multitable @columnfractions .50 .50 15057@item C code @tab MIPS instruction 15058@item @code{a + b} @tab @code{addu.qb} 15059@item @code{c + d} @tab @code{addq.ph} 15060@item @code{a - b} @tab @code{subu.qb} 15061@item @code{c - d} @tab @code{subq.ph} 15062@end multitable 15063 15064The table below lists the @code{v2i16} operation for which 15065hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are 15066@code{v2i16} values. 15067 15068@multitable @columnfractions .50 .50 15069@item C code @tab MIPS instruction 15070@item @code{e * f} @tab @code{mul.ph} 15071@end multitable 15072 15073It is easier to describe the DSP built-in functions if we first define 15074the following types: 15075 15076@smallexample 15077typedef int q31; 15078typedef int i32; 15079typedef unsigned int ui32; 15080typedef long long a64; 15081@end smallexample 15082 15083@code{q31} and @code{i32} are actually the same as @code{int}, but we 15084use @code{q31} to indicate a Q31 fractional value and @code{i32} to 15085indicate a 32-bit integer value. Similarly, @code{a64} is the same as 15086@code{long long}, but we use @code{a64} to indicate values that are 15087placed in one of the four DSP accumulators (@code{$ac0}, 15088@code{$ac1}, @code{$ac2} or @code{$ac3}). 15089 15090Also, some built-in functions prefer or require immediate numbers as 15091parameters, because the corresponding DSP instructions accept both immediate 15092numbers and register operands, or accept immediate numbers only. The 15093immediate parameters are listed as follows. 15094 15095@smallexample 15096imm0_3: 0 to 3. 15097imm0_7: 0 to 7. 15098imm0_15: 0 to 15. 15099imm0_31: 0 to 31. 15100imm0_63: 0 to 63. 15101imm0_255: 0 to 255. 15102imm_n32_31: -32 to 31. 15103imm_n512_511: -512 to 511. 15104@end smallexample 15105 15106The following built-in functions map directly to a particular MIPS DSP 15107instruction. Please refer to the architecture specification 15108for details on what each instruction does. 15109 15110@smallexample 15111v2q15 __builtin_mips_addq_ph (v2q15, v2q15) 15112v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15) 15113q31 __builtin_mips_addq_s_w (q31, q31) 15114v4i8 __builtin_mips_addu_qb (v4i8, v4i8) 15115v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8) 15116v2q15 __builtin_mips_subq_ph (v2q15, v2q15) 15117v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15) 15118q31 __builtin_mips_subq_s_w (q31, q31) 15119v4i8 __builtin_mips_subu_qb (v4i8, v4i8) 15120v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8) 15121i32 __builtin_mips_addsc (i32, i32) 15122i32 __builtin_mips_addwc (i32, i32) 15123i32 __builtin_mips_modsub (i32, i32) 15124i32 __builtin_mips_raddu_w_qb (v4i8) 15125v2q15 __builtin_mips_absq_s_ph (v2q15) 15126q31 __builtin_mips_absq_s_w (q31) 15127v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15) 15128v2q15 __builtin_mips_precrq_ph_w (q31, q31) 15129v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31) 15130v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15) 15131q31 __builtin_mips_preceq_w_phl (v2q15) 15132q31 __builtin_mips_preceq_w_phr (v2q15) 15133v2q15 __builtin_mips_precequ_ph_qbl (v4i8) 15134v2q15 __builtin_mips_precequ_ph_qbr (v4i8) 15135v2q15 __builtin_mips_precequ_ph_qbla (v4i8) 15136v2q15 __builtin_mips_precequ_ph_qbra (v4i8) 15137v2q15 __builtin_mips_preceu_ph_qbl (v4i8) 15138v2q15 __builtin_mips_preceu_ph_qbr (v4i8) 15139v2q15 __builtin_mips_preceu_ph_qbla (v4i8) 15140v2q15 __builtin_mips_preceu_ph_qbra (v4i8) 15141v4i8 __builtin_mips_shll_qb (v4i8, imm0_7) 15142v4i8 __builtin_mips_shll_qb (v4i8, i32) 15143v2q15 __builtin_mips_shll_ph (v2q15, imm0_15) 15144v2q15 __builtin_mips_shll_ph (v2q15, i32) 15145v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15) 15146v2q15 __builtin_mips_shll_s_ph (v2q15, i32) 15147q31 __builtin_mips_shll_s_w (q31, imm0_31) 15148q31 __builtin_mips_shll_s_w (q31, i32) 15149v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7) 15150v4i8 __builtin_mips_shrl_qb (v4i8, i32) 15151v2q15 __builtin_mips_shra_ph (v2q15, imm0_15) 15152v2q15 __builtin_mips_shra_ph (v2q15, i32) 15153v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15) 15154v2q15 __builtin_mips_shra_r_ph (v2q15, i32) 15155q31 __builtin_mips_shra_r_w (q31, imm0_31) 15156q31 __builtin_mips_shra_r_w (q31, i32) 15157v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15) 15158v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15) 15159v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15) 15160q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15) 15161q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15) 15162a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8) 15163a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8) 15164a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8) 15165a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8) 15166a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15) 15167a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31) 15168a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15) 15169a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31) 15170a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15) 15171a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15) 15172a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15) 15173a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15) 15174a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15) 15175i32 __builtin_mips_bitrev (i32) 15176i32 __builtin_mips_insv (i32, i32) 15177v4i8 __builtin_mips_repl_qb (imm0_255) 15178v4i8 __builtin_mips_repl_qb (i32) 15179v2q15 __builtin_mips_repl_ph (imm_n512_511) 15180v2q15 __builtin_mips_repl_ph (i32) 15181void __builtin_mips_cmpu_eq_qb (v4i8, v4i8) 15182void __builtin_mips_cmpu_lt_qb (v4i8, v4i8) 15183void __builtin_mips_cmpu_le_qb (v4i8, v4i8) 15184i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8) 15185i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8) 15186i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8) 15187void __builtin_mips_cmp_eq_ph (v2q15, v2q15) 15188void __builtin_mips_cmp_lt_ph (v2q15, v2q15) 15189void __builtin_mips_cmp_le_ph (v2q15, v2q15) 15190v4i8 __builtin_mips_pick_qb (v4i8, v4i8) 15191v2q15 __builtin_mips_pick_ph (v2q15, v2q15) 15192v2q15 __builtin_mips_packrl_ph (v2q15, v2q15) 15193i32 __builtin_mips_extr_w (a64, imm0_31) 15194i32 __builtin_mips_extr_w (a64, i32) 15195i32 __builtin_mips_extr_r_w (a64, imm0_31) 15196i32 __builtin_mips_extr_s_h (a64, i32) 15197i32 __builtin_mips_extr_rs_w (a64, imm0_31) 15198i32 __builtin_mips_extr_rs_w (a64, i32) 15199i32 __builtin_mips_extr_s_h (a64, imm0_31) 15200i32 __builtin_mips_extr_r_w (a64, i32) 15201i32 __builtin_mips_extp (a64, imm0_31) 15202i32 __builtin_mips_extp (a64, i32) 15203i32 __builtin_mips_extpdp (a64, imm0_31) 15204i32 __builtin_mips_extpdp (a64, i32) 15205a64 __builtin_mips_shilo (a64, imm_n32_31) 15206a64 __builtin_mips_shilo (a64, i32) 15207a64 __builtin_mips_mthlip (a64, i32) 15208void __builtin_mips_wrdsp (i32, imm0_63) 15209i32 __builtin_mips_rddsp (imm0_63) 15210i32 __builtin_mips_lbux (void *, i32) 15211i32 __builtin_mips_lhx (void *, i32) 15212i32 __builtin_mips_lwx (void *, i32) 15213a64 __builtin_mips_ldx (void *, i32) [MIPS64 only] 15214i32 __builtin_mips_bposge32 (void) 15215a64 __builtin_mips_madd (a64, i32, i32); 15216a64 __builtin_mips_maddu (a64, ui32, ui32); 15217a64 __builtin_mips_msub (a64, i32, i32); 15218a64 __builtin_mips_msubu (a64, ui32, ui32); 15219a64 __builtin_mips_mult (i32, i32); 15220a64 __builtin_mips_multu (ui32, ui32); 15221@end smallexample 15222 15223The following built-in functions map directly to a particular MIPS DSP REV 2 15224instruction. Please refer to the architecture specification 15225for details on what each instruction does. 15226 15227@smallexample 15228v4q7 __builtin_mips_absq_s_qb (v4q7); 15229v2i16 __builtin_mips_addu_ph (v2i16, v2i16); 15230v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16); 15231v4i8 __builtin_mips_adduh_qb (v4i8, v4i8); 15232v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8); 15233i32 __builtin_mips_append (i32, i32, imm0_31); 15234i32 __builtin_mips_balign (i32, i32, imm0_3); 15235i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8); 15236i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8); 15237i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8); 15238a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16); 15239a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16); 15240v2i16 __builtin_mips_mul_ph (v2i16, v2i16); 15241v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16); 15242q31 __builtin_mips_mulq_rs_w (q31, q31); 15243v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15); 15244q31 __builtin_mips_mulq_s_w (q31, q31); 15245a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16); 15246v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16); 15247v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31); 15248v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31); 15249i32 __builtin_mips_prepend (i32, i32, imm0_31); 15250v4i8 __builtin_mips_shra_qb (v4i8, imm0_7); 15251v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7); 15252v4i8 __builtin_mips_shra_qb (v4i8, i32); 15253v4i8 __builtin_mips_shra_r_qb (v4i8, i32); 15254v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15); 15255v2i16 __builtin_mips_shrl_ph (v2i16, i32); 15256v2i16 __builtin_mips_subu_ph (v2i16, v2i16); 15257v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16); 15258v4i8 __builtin_mips_subuh_qb (v4i8, v4i8); 15259v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8); 15260v2q15 __builtin_mips_addqh_ph (v2q15, v2q15); 15261v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15); 15262q31 __builtin_mips_addqh_w (q31, q31); 15263q31 __builtin_mips_addqh_r_w (q31, q31); 15264v2q15 __builtin_mips_subqh_ph (v2q15, v2q15); 15265v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15); 15266q31 __builtin_mips_subqh_w (q31, q31); 15267q31 __builtin_mips_subqh_r_w (q31, q31); 15268a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16); 15269a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16); 15270a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15); 15271a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15); 15272a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15); 15273a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15); 15274@end smallexample 15275 15276 15277@node MIPS Paired-Single Support 15278@subsection MIPS Paired-Single Support 15279 15280The MIPS64 architecture includes a number of instructions that 15281operate on pairs of single-precision floating-point values. 15282Each pair is packed into a 64-bit floating-point register, 15283with one element being designated the ``upper half'' and 15284the other being designated the ``lower half''. 15285 15286GCC supports paired-single operations using both the generic 15287vector extensions (@pxref{Vector Extensions}) and a collection of 15288MIPS-specific built-in functions. Both kinds of support are 15289enabled by the @option{-mpaired-single} command-line option. 15290 15291The vector type associated with paired-single values is usually 15292called @code{v2sf}. It can be defined in C as follows: 15293 15294@smallexample 15295typedef float v2sf __attribute__ ((vector_size (8))); 15296@end smallexample 15297 15298@code{v2sf} values are initialized in the same way as aggregates. 15299For example: 15300 15301@smallexample 15302v2sf a = @{1.5, 9.1@}; 15303v2sf b; 15304float e, f; 15305b = (v2sf) @{e, f@}; 15306@end smallexample 15307 15308@emph{Note:} The CPU's endianness determines which value is stored in 15309the upper half of a register and which value is stored in the lower half. 15310On little-endian targets, the first value is the lower one and the second 15311value is the upper one. The opposite order applies to big-endian targets. 15312For example, the code above sets the lower half of @code{a} to 15313@code{1.5} on little-endian targets and @code{9.1} on big-endian targets. 15314 15315@node MIPS Loongson Built-in Functions 15316@subsection MIPS Loongson Built-in Functions 15317 15318GCC provides intrinsics to access the SIMD instructions provided by the 15319ST Microelectronics Loongson-2E and -2F processors. These intrinsics, 15320available after inclusion of the @code{loongson.h} header file, 15321operate on the following 64-bit vector types: 15322 15323@itemize 15324@item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers; 15325@item @code{uint16x4_t}, a vector of four unsigned 16-bit integers; 15326@item @code{uint32x2_t}, a vector of two unsigned 32-bit integers; 15327@item @code{int8x8_t}, a vector of eight signed 8-bit integers; 15328@item @code{int16x4_t}, a vector of four signed 16-bit integers; 15329@item @code{int32x2_t}, a vector of two signed 32-bit integers. 15330@end itemize 15331 15332The intrinsics provided are listed below; each is named after the 15333machine instruction to which it corresponds, with suffixes added as 15334appropriate to distinguish intrinsics that expand to the same machine 15335instruction yet have different argument types. Refer to the architecture 15336documentation for a description of the functionality of each 15337instruction. 15338 15339@smallexample 15340int16x4_t packsswh (int32x2_t s, int32x2_t t); 15341int8x8_t packsshb (int16x4_t s, int16x4_t t); 15342uint8x8_t packushb (uint16x4_t s, uint16x4_t t); 15343uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t); 15344uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t); 15345uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t); 15346int32x2_t paddw_s (int32x2_t s, int32x2_t t); 15347int16x4_t paddh_s (int16x4_t s, int16x4_t t); 15348int8x8_t paddb_s (int8x8_t s, int8x8_t t); 15349uint64_t paddd_u (uint64_t s, uint64_t t); 15350int64_t paddd_s (int64_t s, int64_t t); 15351int16x4_t paddsh (int16x4_t s, int16x4_t t); 15352int8x8_t paddsb (int8x8_t s, int8x8_t t); 15353uint16x4_t paddush (uint16x4_t s, uint16x4_t t); 15354uint8x8_t paddusb (uint8x8_t s, uint8x8_t t); 15355uint64_t pandn_ud (uint64_t s, uint64_t t); 15356uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t); 15357uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t); 15358uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t); 15359int64_t pandn_sd (int64_t s, int64_t t); 15360int32x2_t pandn_sw (int32x2_t s, int32x2_t t); 15361int16x4_t pandn_sh (int16x4_t s, int16x4_t t); 15362int8x8_t pandn_sb (int8x8_t s, int8x8_t t); 15363uint16x4_t pavgh (uint16x4_t s, uint16x4_t t); 15364uint8x8_t pavgb (uint8x8_t s, uint8x8_t t); 15365uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t); 15366uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t); 15367uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t); 15368int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t); 15369int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t); 15370int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t); 15371uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t); 15372uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t); 15373uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t); 15374int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t); 15375int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t); 15376int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t); 15377uint16x4_t pextrh_u (uint16x4_t s, int field); 15378int16x4_t pextrh_s (int16x4_t s, int field); 15379uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t); 15380uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t); 15381uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t); 15382uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t); 15383int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t); 15384int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t); 15385int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t); 15386int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t); 15387int32x2_t pmaddhw (int16x4_t s, int16x4_t t); 15388int16x4_t pmaxsh (int16x4_t s, int16x4_t t); 15389uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t); 15390int16x4_t pminsh (int16x4_t s, int16x4_t t); 15391uint8x8_t pminub (uint8x8_t s, uint8x8_t t); 15392uint8x8_t pmovmskb_u (uint8x8_t s); 15393int8x8_t pmovmskb_s (int8x8_t s); 15394uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t); 15395int16x4_t pmulhh (int16x4_t s, int16x4_t t); 15396int16x4_t pmullh (int16x4_t s, int16x4_t t); 15397int64_t pmuluw (uint32x2_t s, uint32x2_t t); 15398uint8x8_t pasubub (uint8x8_t s, uint8x8_t t); 15399uint16x4_t biadd (uint8x8_t s); 15400uint16x4_t psadbh (uint8x8_t s, uint8x8_t t); 15401uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order); 15402int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order); 15403uint16x4_t psllh_u (uint16x4_t s, uint8_t amount); 15404int16x4_t psllh_s (int16x4_t s, uint8_t amount); 15405uint32x2_t psllw_u (uint32x2_t s, uint8_t amount); 15406int32x2_t psllw_s (int32x2_t s, uint8_t amount); 15407uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount); 15408int16x4_t psrlh_s (int16x4_t s, uint8_t amount); 15409uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount); 15410int32x2_t psrlw_s (int32x2_t s, uint8_t amount); 15411uint16x4_t psrah_u (uint16x4_t s, uint8_t amount); 15412int16x4_t psrah_s (int16x4_t s, uint8_t amount); 15413uint32x2_t psraw_u (uint32x2_t s, uint8_t amount); 15414int32x2_t psraw_s (int32x2_t s, uint8_t amount); 15415uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t); 15416uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t); 15417uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t); 15418int32x2_t psubw_s (int32x2_t s, int32x2_t t); 15419int16x4_t psubh_s (int16x4_t s, int16x4_t t); 15420int8x8_t psubb_s (int8x8_t s, int8x8_t t); 15421uint64_t psubd_u (uint64_t s, uint64_t t); 15422int64_t psubd_s (int64_t s, int64_t t); 15423int16x4_t psubsh (int16x4_t s, int16x4_t t); 15424int8x8_t psubsb (int8x8_t s, int8x8_t t); 15425uint16x4_t psubush (uint16x4_t s, uint16x4_t t); 15426uint8x8_t psubusb (uint8x8_t s, uint8x8_t t); 15427uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t); 15428uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t); 15429uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t); 15430int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t); 15431int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t); 15432int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t); 15433uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t); 15434uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t); 15435uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t); 15436int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t); 15437int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t); 15438int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t); 15439@end smallexample 15440 15441@menu 15442* Paired-Single Arithmetic:: 15443* Paired-Single Built-in Functions:: 15444* MIPS-3D Built-in Functions:: 15445@end menu 15446 15447@node Paired-Single Arithmetic 15448@subsubsection Paired-Single Arithmetic 15449 15450The table below lists the @code{v2sf} operations for which hardware 15451support exists. @code{a}, @code{b} and @code{c} are @code{v2sf} 15452values and @code{x} is an integral value. 15453 15454@multitable @columnfractions .50 .50 15455@item C code @tab MIPS instruction 15456@item @code{a + b} @tab @code{add.ps} 15457@item @code{a - b} @tab @code{sub.ps} 15458@item @code{-a} @tab @code{neg.ps} 15459@item @code{a * b} @tab @code{mul.ps} 15460@item @code{a * b + c} @tab @code{madd.ps} 15461@item @code{a * b - c} @tab @code{msub.ps} 15462@item @code{-(a * b + c)} @tab @code{nmadd.ps} 15463@item @code{-(a * b - c)} @tab @code{nmsub.ps} 15464@item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} 15465@end multitable 15466 15467Note that the multiply-accumulate instructions can be disabled 15468using the command-line option @code{-mno-fused-madd}. 15469 15470@node Paired-Single Built-in Functions 15471@subsubsection Paired-Single Built-in Functions 15472 15473The following paired-single functions map directly to a particular 15474MIPS instruction. Please refer to the architecture specification 15475for details on what each instruction does. 15476 15477@table @code 15478@item v2sf __builtin_mips_pll_ps (v2sf, v2sf) 15479Pair lower lower (@code{pll.ps}). 15480 15481@item v2sf __builtin_mips_pul_ps (v2sf, v2sf) 15482Pair upper lower (@code{pul.ps}). 15483 15484@item v2sf __builtin_mips_plu_ps (v2sf, v2sf) 15485Pair lower upper (@code{plu.ps}). 15486 15487@item v2sf __builtin_mips_puu_ps (v2sf, v2sf) 15488Pair upper upper (@code{puu.ps}). 15489 15490@item v2sf __builtin_mips_cvt_ps_s (float, float) 15491Convert pair to paired single (@code{cvt.ps.s}). 15492 15493@item float __builtin_mips_cvt_s_pl (v2sf) 15494Convert pair lower to single (@code{cvt.s.pl}). 15495 15496@item float __builtin_mips_cvt_s_pu (v2sf) 15497Convert pair upper to single (@code{cvt.s.pu}). 15498 15499@item v2sf __builtin_mips_abs_ps (v2sf) 15500Absolute value (@code{abs.ps}). 15501 15502@item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) 15503Align variable (@code{alnv.ps}). 15504 15505@emph{Note:} The value of the third parameter must be 0 or 4 15506modulo 8, otherwise the result is unpredictable. Please read the 15507instruction description for details. 15508@end table 15509 15510The following multi-instruction functions are also available. 15511In each case, @var{cond} can be any of the 16 floating-point conditions: 15512@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 15513@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, 15514@code{lt}, @code{nge}, @code{le} or @code{ngt}. 15515 15516@table @code 15517@item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15518@itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15519Conditional move based on floating-point comparison (@code{c.@var{cond}.ps}, 15520@code{movt.ps}/@code{movf.ps}). 15521 15522The @code{movt} functions return the value @var{x} computed by: 15523 15524@smallexample 15525c.@var{cond}.ps @var{cc},@var{a},@var{b} 15526mov.ps @var{x},@var{c} 15527movt.ps @var{x},@var{d},@var{cc} 15528@end smallexample 15529 15530The @code{movf} functions are similar but use @code{movf.ps} instead 15531of @code{movt.ps}. 15532 15533@item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15534@itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15535Comparison of two paired-single values (@code{c.@var{cond}.ps}, 15536@code{bc1t}/@code{bc1f}). 15537 15538These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 15539and return either the upper or lower half of the result. For example: 15540 15541@smallexample 15542v2sf a, b; 15543if (__builtin_mips_upper_c_eq_ps (a, b)) 15544 upper_halves_are_equal (); 15545else 15546 upper_halves_are_unequal (); 15547 15548if (__builtin_mips_lower_c_eq_ps (a, b)) 15549 lower_halves_are_equal (); 15550else 15551 lower_halves_are_unequal (); 15552@end smallexample 15553@end table 15554 15555@node MIPS-3D Built-in Functions 15556@subsubsection MIPS-3D Built-in Functions 15557 15558The MIPS-3D Application-Specific Extension (ASE) includes additional 15559paired-single instructions that are designed to improve the performance 15560of 3D graphics operations. Support for these instructions is controlled 15561by the @option{-mips3d} command-line option. 15562 15563The functions listed below map directly to a particular MIPS-3D 15564instruction. Please refer to the architecture specification for 15565more details on what each instruction does. 15566 15567@table @code 15568@item v2sf __builtin_mips_addr_ps (v2sf, v2sf) 15569Reduction add (@code{addr.ps}). 15570 15571@item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) 15572Reduction multiply (@code{mulr.ps}). 15573 15574@item v2sf __builtin_mips_cvt_pw_ps (v2sf) 15575Convert paired single to paired word (@code{cvt.pw.ps}). 15576 15577@item v2sf __builtin_mips_cvt_ps_pw (v2sf) 15578Convert paired word to paired single (@code{cvt.ps.pw}). 15579 15580@item float __builtin_mips_recip1_s (float) 15581@itemx double __builtin_mips_recip1_d (double) 15582@itemx v2sf __builtin_mips_recip1_ps (v2sf) 15583Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). 15584 15585@item float __builtin_mips_recip2_s (float, float) 15586@itemx double __builtin_mips_recip2_d (double, double) 15587@itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) 15588Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). 15589 15590@item float __builtin_mips_rsqrt1_s (float) 15591@itemx double __builtin_mips_rsqrt1_d (double) 15592@itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) 15593Reduced-precision reciprocal square root (sequence step 1) 15594(@code{rsqrt1.@var{fmt}}). 15595 15596@item float __builtin_mips_rsqrt2_s (float, float) 15597@itemx double __builtin_mips_rsqrt2_d (double, double) 15598@itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) 15599Reduced-precision reciprocal square root (sequence step 2) 15600(@code{rsqrt2.@var{fmt}}). 15601@end table 15602 15603The following multi-instruction functions are also available. 15604In each case, @var{cond} can be any of the 16 floating-point conditions: 15605@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 15606@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, 15607@code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. 15608 15609@table @code 15610@item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) 15611@itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) 15612Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, 15613@code{bc1t}/@code{bc1f}). 15614 15615These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} 15616or @code{cabs.@var{cond}.d} and return the result as a boolean value. 15617For example: 15618 15619@smallexample 15620float a, b; 15621if (__builtin_mips_cabs_eq_s (a, b)) 15622 true (); 15623else 15624 false (); 15625@end smallexample 15626 15627@item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15628@itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15629Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, 15630@code{bc1t}/@code{bc1f}). 15631 15632These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} 15633and return either the upper or lower half of the result. For example: 15634 15635@smallexample 15636v2sf a, b; 15637if (__builtin_mips_upper_cabs_eq_ps (a, b)) 15638 upper_halves_are_equal (); 15639else 15640 upper_halves_are_unequal (); 15641 15642if (__builtin_mips_lower_cabs_eq_ps (a, b)) 15643 lower_halves_are_equal (); 15644else 15645 lower_halves_are_unequal (); 15646@end smallexample 15647 15648@item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15649@itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15650Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, 15651@code{movt.ps}/@code{movf.ps}). 15652 15653The @code{movt} functions return the value @var{x} computed by: 15654 15655@smallexample 15656cabs.@var{cond}.ps @var{cc},@var{a},@var{b} 15657mov.ps @var{x},@var{c} 15658movt.ps @var{x},@var{d},@var{cc} 15659@end smallexample 15660 15661The @code{movf} functions are similar but use @code{movf.ps} instead 15662of @code{movt.ps}. 15663 15664@item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15665@itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15666@itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15667@itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 15668Comparison of two paired-single values 15669(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 15670@code{bc1any2t}/@code{bc1any2f}). 15671 15672These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 15673or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either 15674result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}. 15675For example: 15676 15677@smallexample 15678v2sf a, b; 15679if (__builtin_mips_any_c_eq_ps (a, b)) 15680 one_is_true (); 15681else 15682 both_are_false (); 15683 15684if (__builtin_mips_all_c_eq_ps (a, b)) 15685 both_are_true (); 15686else 15687 one_is_false (); 15688@end smallexample 15689 15690@item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15691@itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15692@itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15693@itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 15694Comparison of four paired-single values 15695(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 15696@code{bc1any4t}/@code{bc1any4f}). 15697 15698These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} 15699to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. 15700The @code{any} forms return @code{true} if any of the four results are @code{true} 15701and the @code{all} forms return @code{true} if all four results are @code{true}. 15702For example: 15703 15704@smallexample 15705v2sf a, b, c, d; 15706if (__builtin_mips_any_c_eq_4s (a, b, c, d)) 15707 some_are_true (); 15708else 15709 all_are_false (); 15710 15711if (__builtin_mips_all_c_eq_4s (a, b, c, d)) 15712 all_are_true (); 15713else 15714 some_are_false (); 15715@end smallexample 15716@end table 15717 15718@node MIPS SIMD Architecture (MSA) Support 15719@subsection MIPS SIMD Architecture (MSA) Support 15720 15721@menu 15722* MIPS SIMD Architecture Built-in Functions:: 15723@end menu 15724 15725GCC provides intrinsics to access the SIMD instructions provided by the 15726MSA MIPS SIMD Architecture. The interface is made available by including 15727@code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}. 15728For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic, 15729@code{__msa_*}. 15730 15731MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and 1573264-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point 15733data elements. The following vectors typedefs are included in @code{msa.h}: 15734@itemize 15735@item @code{v16i8}, a vector of sixteen signed 8-bit integers; 15736@item @code{v16u8}, a vector of sixteen unsigned 8-bit integers; 15737@item @code{v8i16}, a vector of eight signed 16-bit integers; 15738@item @code{v8u16}, a vector of eight unsigned 16-bit integers; 15739@item @code{v4i32}, a vector of four signed 32-bit integers; 15740@item @code{v4u32}, a vector of four unsigned 32-bit integers; 15741@item @code{v2i64}, a vector of two signed 64-bit integers; 15742@item @code{v2u64}, a vector of two unsigned 64-bit integers; 15743@item @code{v4f32}, a vector of four 32-bit floats; 15744@item @code{v2f64}, a vector of two 64-bit doubles. 15745@end itemize 15746 15747Instructions and corresponding built-ins may have additional restrictions and/or 15748input/output values manipulated: 15749@itemize 15750@item @code{imm0_1}, an integer literal in range 0 to 1; 15751@item @code{imm0_3}, an integer literal in range 0 to 3; 15752@item @code{imm0_7}, an integer literal in range 0 to 7; 15753@item @code{imm0_15}, an integer literal in range 0 to 15; 15754@item @code{imm0_31}, an integer literal in range 0 to 31; 15755@item @code{imm0_63}, an integer literal in range 0 to 63; 15756@item @code{imm0_255}, an integer literal in range 0 to 255; 15757@item @code{imm_n16_15}, an integer literal in range -16 to 15; 15758@item @code{imm_n512_511}, an integer literal in range -512 to 511; 15759@item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left 15760shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022; 15761@item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left 15762shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044; 15763@item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left 15764shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088; 15765@item @code{imm1_4}, an integer literal in range 1 to 4; 15766@item @code{i32, i64, u32, u64, f32, f64}, defined as follows: 15767@end itemize 15768 15769@smallexample 15770@{ 15771typedef int i32; 15772#if __LONG_MAX__ == __LONG_LONG_MAX__ 15773typedef long i64; 15774#else 15775typedef long long i64; 15776#endif 15777 15778typedef unsigned int u32; 15779#if __LONG_MAX__ == __LONG_LONG_MAX__ 15780typedef unsigned long u64; 15781#else 15782typedef unsigned long long u64; 15783#endif 15784 15785typedef double f64; 15786typedef float f32; 15787@} 15788@end smallexample 15789 15790@node MIPS SIMD Architecture Built-in Functions 15791@subsubsection MIPS SIMD Architecture Built-in Functions 15792 15793The intrinsics provided are listed below; each is named after the 15794machine instruction. 15795 15796@smallexample 15797v16i8 __builtin_msa_add_a_b (v16i8, v16i8); 15798v8i16 __builtin_msa_add_a_h (v8i16, v8i16); 15799v4i32 __builtin_msa_add_a_w (v4i32, v4i32); 15800v2i64 __builtin_msa_add_a_d (v2i64, v2i64); 15801 15802v16i8 __builtin_msa_adds_a_b (v16i8, v16i8); 15803v8i16 __builtin_msa_adds_a_h (v8i16, v8i16); 15804v4i32 __builtin_msa_adds_a_w (v4i32, v4i32); 15805v2i64 __builtin_msa_adds_a_d (v2i64, v2i64); 15806 15807v16i8 __builtin_msa_adds_s_b (v16i8, v16i8); 15808v8i16 __builtin_msa_adds_s_h (v8i16, v8i16); 15809v4i32 __builtin_msa_adds_s_w (v4i32, v4i32); 15810v2i64 __builtin_msa_adds_s_d (v2i64, v2i64); 15811 15812v16u8 __builtin_msa_adds_u_b (v16u8, v16u8); 15813v8u16 __builtin_msa_adds_u_h (v8u16, v8u16); 15814v4u32 __builtin_msa_adds_u_w (v4u32, v4u32); 15815v2u64 __builtin_msa_adds_u_d (v2u64, v2u64); 15816 15817v16i8 __builtin_msa_addv_b (v16i8, v16i8); 15818v8i16 __builtin_msa_addv_h (v8i16, v8i16); 15819v4i32 __builtin_msa_addv_w (v4i32, v4i32); 15820v2i64 __builtin_msa_addv_d (v2i64, v2i64); 15821 15822v16i8 __builtin_msa_addvi_b (v16i8, imm0_31); 15823v8i16 __builtin_msa_addvi_h (v8i16, imm0_31); 15824v4i32 __builtin_msa_addvi_w (v4i32, imm0_31); 15825v2i64 __builtin_msa_addvi_d (v2i64, imm0_31); 15826 15827v16u8 __builtin_msa_and_v (v16u8, v16u8); 15828 15829v16u8 __builtin_msa_andi_b (v16u8, imm0_255); 15830 15831v16i8 __builtin_msa_asub_s_b (v16i8, v16i8); 15832v8i16 __builtin_msa_asub_s_h (v8i16, v8i16); 15833v4i32 __builtin_msa_asub_s_w (v4i32, v4i32); 15834v2i64 __builtin_msa_asub_s_d (v2i64, v2i64); 15835 15836v16u8 __builtin_msa_asub_u_b (v16u8, v16u8); 15837v8u16 __builtin_msa_asub_u_h (v8u16, v8u16); 15838v4u32 __builtin_msa_asub_u_w (v4u32, v4u32); 15839v2u64 __builtin_msa_asub_u_d (v2u64, v2u64); 15840 15841v16i8 __builtin_msa_ave_s_b (v16i8, v16i8); 15842v8i16 __builtin_msa_ave_s_h (v8i16, v8i16); 15843v4i32 __builtin_msa_ave_s_w (v4i32, v4i32); 15844v2i64 __builtin_msa_ave_s_d (v2i64, v2i64); 15845 15846v16u8 __builtin_msa_ave_u_b (v16u8, v16u8); 15847v8u16 __builtin_msa_ave_u_h (v8u16, v8u16); 15848v4u32 __builtin_msa_ave_u_w (v4u32, v4u32); 15849v2u64 __builtin_msa_ave_u_d (v2u64, v2u64); 15850 15851v16i8 __builtin_msa_aver_s_b (v16i8, v16i8); 15852v8i16 __builtin_msa_aver_s_h (v8i16, v8i16); 15853v4i32 __builtin_msa_aver_s_w (v4i32, v4i32); 15854v2i64 __builtin_msa_aver_s_d (v2i64, v2i64); 15855 15856v16u8 __builtin_msa_aver_u_b (v16u8, v16u8); 15857v8u16 __builtin_msa_aver_u_h (v8u16, v8u16); 15858v4u32 __builtin_msa_aver_u_w (v4u32, v4u32); 15859v2u64 __builtin_msa_aver_u_d (v2u64, v2u64); 15860 15861v16u8 __builtin_msa_bclr_b (v16u8, v16u8); 15862v8u16 __builtin_msa_bclr_h (v8u16, v8u16); 15863v4u32 __builtin_msa_bclr_w (v4u32, v4u32); 15864v2u64 __builtin_msa_bclr_d (v2u64, v2u64); 15865 15866v16u8 __builtin_msa_bclri_b (v16u8, imm0_7); 15867v8u16 __builtin_msa_bclri_h (v8u16, imm0_15); 15868v4u32 __builtin_msa_bclri_w (v4u32, imm0_31); 15869v2u64 __builtin_msa_bclri_d (v2u64, imm0_63); 15870 15871v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8); 15872v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16); 15873v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32); 15874v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64); 15875 15876v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7); 15877v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15); 15878v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31); 15879v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63); 15880 15881v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8); 15882v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16); 15883v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32); 15884v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64); 15885 15886v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7); 15887v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15); 15888v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31); 15889v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63); 15890 15891v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8); 15892 15893v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255); 15894 15895v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8); 15896 15897v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255); 15898 15899v16u8 __builtin_msa_bneg_b (v16u8, v16u8); 15900v8u16 __builtin_msa_bneg_h (v8u16, v8u16); 15901v4u32 __builtin_msa_bneg_w (v4u32, v4u32); 15902v2u64 __builtin_msa_bneg_d (v2u64, v2u64); 15903 15904v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7); 15905v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15); 15906v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31); 15907v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63); 15908 15909i32 __builtin_msa_bnz_b (v16u8); 15910i32 __builtin_msa_bnz_h (v8u16); 15911i32 __builtin_msa_bnz_w (v4u32); 15912i32 __builtin_msa_bnz_d (v2u64); 15913 15914i32 __builtin_msa_bnz_v (v16u8); 15915 15916v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8); 15917 15918v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255); 15919 15920v16u8 __builtin_msa_bset_b (v16u8, v16u8); 15921v8u16 __builtin_msa_bset_h (v8u16, v8u16); 15922v4u32 __builtin_msa_bset_w (v4u32, v4u32); 15923v2u64 __builtin_msa_bset_d (v2u64, v2u64); 15924 15925v16u8 __builtin_msa_bseti_b (v16u8, imm0_7); 15926v8u16 __builtin_msa_bseti_h (v8u16, imm0_15); 15927v4u32 __builtin_msa_bseti_w (v4u32, imm0_31); 15928v2u64 __builtin_msa_bseti_d (v2u64, imm0_63); 15929 15930i32 __builtin_msa_bz_b (v16u8); 15931i32 __builtin_msa_bz_h (v8u16); 15932i32 __builtin_msa_bz_w (v4u32); 15933i32 __builtin_msa_bz_d (v2u64); 15934 15935i32 __builtin_msa_bz_v (v16u8); 15936 15937v16i8 __builtin_msa_ceq_b (v16i8, v16i8); 15938v8i16 __builtin_msa_ceq_h (v8i16, v8i16); 15939v4i32 __builtin_msa_ceq_w (v4i32, v4i32); 15940v2i64 __builtin_msa_ceq_d (v2i64, v2i64); 15941 15942v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15); 15943v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15); 15944v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15); 15945v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15); 15946 15947i32 __builtin_msa_cfcmsa (imm0_31); 15948 15949v16i8 __builtin_msa_cle_s_b (v16i8, v16i8); 15950v8i16 __builtin_msa_cle_s_h (v8i16, v8i16); 15951v4i32 __builtin_msa_cle_s_w (v4i32, v4i32); 15952v2i64 __builtin_msa_cle_s_d (v2i64, v2i64); 15953 15954v16i8 __builtin_msa_cle_u_b (v16u8, v16u8); 15955v8i16 __builtin_msa_cle_u_h (v8u16, v8u16); 15956v4i32 __builtin_msa_cle_u_w (v4u32, v4u32); 15957v2i64 __builtin_msa_cle_u_d (v2u64, v2u64); 15958 15959v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15); 15960v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15); 15961v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15); 15962v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15); 15963 15964v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31); 15965v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31); 15966v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31); 15967v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31); 15968 15969v16i8 __builtin_msa_clt_s_b (v16i8, v16i8); 15970v8i16 __builtin_msa_clt_s_h (v8i16, v8i16); 15971v4i32 __builtin_msa_clt_s_w (v4i32, v4i32); 15972v2i64 __builtin_msa_clt_s_d (v2i64, v2i64); 15973 15974v16i8 __builtin_msa_clt_u_b (v16u8, v16u8); 15975v8i16 __builtin_msa_clt_u_h (v8u16, v8u16); 15976v4i32 __builtin_msa_clt_u_w (v4u32, v4u32); 15977v2i64 __builtin_msa_clt_u_d (v2u64, v2u64); 15978 15979v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15); 15980v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15); 15981v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15); 15982v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15); 15983 15984v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31); 15985v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31); 15986v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31); 15987v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31); 15988 15989i32 __builtin_msa_copy_s_b (v16i8, imm0_15); 15990i32 __builtin_msa_copy_s_h (v8i16, imm0_7); 15991i32 __builtin_msa_copy_s_w (v4i32, imm0_3); 15992i64 __builtin_msa_copy_s_d (v2i64, imm0_1); 15993 15994u32 __builtin_msa_copy_u_b (v16i8, imm0_15); 15995u32 __builtin_msa_copy_u_h (v8i16, imm0_7); 15996u32 __builtin_msa_copy_u_w (v4i32, imm0_3); 15997u64 __builtin_msa_copy_u_d (v2i64, imm0_1); 15998 15999void __builtin_msa_ctcmsa (imm0_31, i32); 16000 16001v16i8 __builtin_msa_div_s_b (v16i8, v16i8); 16002v8i16 __builtin_msa_div_s_h (v8i16, v8i16); 16003v4i32 __builtin_msa_div_s_w (v4i32, v4i32); 16004v2i64 __builtin_msa_div_s_d (v2i64, v2i64); 16005 16006v16u8 __builtin_msa_div_u_b (v16u8, v16u8); 16007v8u16 __builtin_msa_div_u_h (v8u16, v8u16); 16008v4u32 __builtin_msa_div_u_w (v4u32, v4u32); 16009v2u64 __builtin_msa_div_u_d (v2u64, v2u64); 16010 16011v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8); 16012v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16); 16013v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32); 16014 16015v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8); 16016v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16); 16017v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32); 16018 16019v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8); 16020v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16); 16021v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32); 16022 16023v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8); 16024v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16); 16025v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32); 16026 16027v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8); 16028v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16); 16029v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32); 16030 16031v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8); 16032v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16); 16033v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32); 16034 16035v4f32 __builtin_msa_fadd_w (v4f32, v4f32); 16036v2f64 __builtin_msa_fadd_d (v2f64, v2f64); 16037 16038v4i32 __builtin_msa_fcaf_w (v4f32, v4f32); 16039v2i64 __builtin_msa_fcaf_d (v2f64, v2f64); 16040 16041v4i32 __builtin_msa_fceq_w (v4f32, v4f32); 16042v2i64 __builtin_msa_fceq_d (v2f64, v2f64); 16043 16044v4i32 __builtin_msa_fclass_w (v4f32); 16045v2i64 __builtin_msa_fclass_d (v2f64); 16046 16047v4i32 __builtin_msa_fcle_w (v4f32, v4f32); 16048v2i64 __builtin_msa_fcle_d (v2f64, v2f64); 16049 16050v4i32 __builtin_msa_fclt_w (v4f32, v4f32); 16051v2i64 __builtin_msa_fclt_d (v2f64, v2f64); 16052 16053v4i32 __builtin_msa_fcne_w (v4f32, v4f32); 16054v2i64 __builtin_msa_fcne_d (v2f64, v2f64); 16055 16056v4i32 __builtin_msa_fcor_w (v4f32, v4f32); 16057v2i64 __builtin_msa_fcor_d (v2f64, v2f64); 16058 16059v4i32 __builtin_msa_fcueq_w (v4f32, v4f32); 16060v2i64 __builtin_msa_fcueq_d (v2f64, v2f64); 16061 16062v4i32 __builtin_msa_fcule_w (v4f32, v4f32); 16063v2i64 __builtin_msa_fcule_d (v2f64, v2f64); 16064 16065v4i32 __builtin_msa_fcult_w (v4f32, v4f32); 16066v2i64 __builtin_msa_fcult_d (v2f64, v2f64); 16067 16068v4i32 __builtin_msa_fcun_w (v4f32, v4f32); 16069v2i64 __builtin_msa_fcun_d (v2f64, v2f64); 16070 16071v4i32 __builtin_msa_fcune_w (v4f32, v4f32); 16072v2i64 __builtin_msa_fcune_d (v2f64, v2f64); 16073 16074v4f32 __builtin_msa_fdiv_w (v4f32, v4f32); 16075v2f64 __builtin_msa_fdiv_d (v2f64, v2f64); 16076 16077v8i16 __builtin_msa_fexdo_h (v4f32, v4f32); 16078v4f32 __builtin_msa_fexdo_w (v2f64, v2f64); 16079 16080v4f32 __builtin_msa_fexp2_w (v4f32, v4i32); 16081v2f64 __builtin_msa_fexp2_d (v2f64, v2i64); 16082 16083v4f32 __builtin_msa_fexupl_w (v8i16); 16084v2f64 __builtin_msa_fexupl_d (v4f32); 16085 16086v4f32 __builtin_msa_fexupr_w (v8i16); 16087v2f64 __builtin_msa_fexupr_d (v4f32); 16088 16089v4f32 __builtin_msa_ffint_s_w (v4i32); 16090v2f64 __builtin_msa_ffint_s_d (v2i64); 16091 16092v4f32 __builtin_msa_ffint_u_w (v4u32); 16093v2f64 __builtin_msa_ffint_u_d (v2u64); 16094 16095v4f32 __builtin_msa_ffql_w (v8i16); 16096v2f64 __builtin_msa_ffql_d (v4i32); 16097 16098v4f32 __builtin_msa_ffqr_w (v8i16); 16099v2f64 __builtin_msa_ffqr_d (v4i32); 16100 16101v16i8 __builtin_msa_fill_b (i32); 16102v8i16 __builtin_msa_fill_h (i32); 16103v4i32 __builtin_msa_fill_w (i32); 16104v2i64 __builtin_msa_fill_d (i64); 16105 16106v4f32 __builtin_msa_flog2_w (v4f32); 16107v2f64 __builtin_msa_flog2_d (v2f64); 16108 16109v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32); 16110v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64); 16111 16112v4f32 __builtin_msa_fmax_w (v4f32, v4f32); 16113v2f64 __builtin_msa_fmax_d (v2f64, v2f64); 16114 16115v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32); 16116v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64); 16117 16118v4f32 __builtin_msa_fmin_w (v4f32, v4f32); 16119v2f64 __builtin_msa_fmin_d (v2f64, v2f64); 16120 16121v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32); 16122v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64); 16123 16124v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32); 16125v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64); 16126 16127v4f32 __builtin_msa_fmul_w (v4f32, v4f32); 16128v2f64 __builtin_msa_fmul_d (v2f64, v2f64); 16129 16130v4f32 __builtin_msa_frint_w (v4f32); 16131v2f64 __builtin_msa_frint_d (v2f64); 16132 16133v4f32 __builtin_msa_frcp_w (v4f32); 16134v2f64 __builtin_msa_frcp_d (v2f64); 16135 16136v4f32 __builtin_msa_frsqrt_w (v4f32); 16137v2f64 __builtin_msa_frsqrt_d (v2f64); 16138 16139v4i32 __builtin_msa_fsaf_w (v4f32, v4f32); 16140v2i64 __builtin_msa_fsaf_d (v2f64, v2f64); 16141 16142v4i32 __builtin_msa_fseq_w (v4f32, v4f32); 16143v2i64 __builtin_msa_fseq_d (v2f64, v2f64); 16144 16145v4i32 __builtin_msa_fsle_w (v4f32, v4f32); 16146v2i64 __builtin_msa_fsle_d (v2f64, v2f64); 16147 16148v4i32 __builtin_msa_fslt_w (v4f32, v4f32); 16149v2i64 __builtin_msa_fslt_d (v2f64, v2f64); 16150 16151v4i32 __builtin_msa_fsne_w (v4f32, v4f32); 16152v2i64 __builtin_msa_fsne_d (v2f64, v2f64); 16153 16154v4i32 __builtin_msa_fsor_w (v4f32, v4f32); 16155v2i64 __builtin_msa_fsor_d (v2f64, v2f64); 16156 16157v4f32 __builtin_msa_fsqrt_w (v4f32); 16158v2f64 __builtin_msa_fsqrt_d (v2f64); 16159 16160v4f32 __builtin_msa_fsub_w (v4f32, v4f32); 16161v2f64 __builtin_msa_fsub_d (v2f64, v2f64); 16162 16163v4i32 __builtin_msa_fsueq_w (v4f32, v4f32); 16164v2i64 __builtin_msa_fsueq_d (v2f64, v2f64); 16165 16166v4i32 __builtin_msa_fsule_w (v4f32, v4f32); 16167v2i64 __builtin_msa_fsule_d (v2f64, v2f64); 16168 16169v4i32 __builtin_msa_fsult_w (v4f32, v4f32); 16170v2i64 __builtin_msa_fsult_d (v2f64, v2f64); 16171 16172v4i32 __builtin_msa_fsun_w (v4f32, v4f32); 16173v2i64 __builtin_msa_fsun_d (v2f64, v2f64); 16174 16175v4i32 __builtin_msa_fsune_w (v4f32, v4f32); 16176v2i64 __builtin_msa_fsune_d (v2f64, v2f64); 16177 16178v4i32 __builtin_msa_ftint_s_w (v4f32); 16179v2i64 __builtin_msa_ftint_s_d (v2f64); 16180 16181v4u32 __builtin_msa_ftint_u_w (v4f32); 16182v2u64 __builtin_msa_ftint_u_d (v2f64); 16183 16184v8i16 __builtin_msa_ftq_h (v4f32, v4f32); 16185v4i32 __builtin_msa_ftq_w (v2f64, v2f64); 16186 16187v4i32 __builtin_msa_ftrunc_s_w (v4f32); 16188v2i64 __builtin_msa_ftrunc_s_d (v2f64); 16189 16190v4u32 __builtin_msa_ftrunc_u_w (v4f32); 16191v2u64 __builtin_msa_ftrunc_u_d (v2f64); 16192 16193v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8); 16194v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16); 16195v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32); 16196 16197v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8); 16198v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16); 16199v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32); 16200 16201v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8); 16202v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16); 16203v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32); 16204 16205v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8); 16206v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16); 16207v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32); 16208 16209v16i8 __builtin_msa_ilvev_b (v16i8, v16i8); 16210v8i16 __builtin_msa_ilvev_h (v8i16, v8i16); 16211v4i32 __builtin_msa_ilvev_w (v4i32, v4i32); 16212v2i64 __builtin_msa_ilvev_d (v2i64, v2i64); 16213 16214v16i8 __builtin_msa_ilvl_b (v16i8, v16i8); 16215v8i16 __builtin_msa_ilvl_h (v8i16, v8i16); 16216v4i32 __builtin_msa_ilvl_w (v4i32, v4i32); 16217v2i64 __builtin_msa_ilvl_d (v2i64, v2i64); 16218 16219v16i8 __builtin_msa_ilvod_b (v16i8, v16i8); 16220v8i16 __builtin_msa_ilvod_h (v8i16, v8i16); 16221v4i32 __builtin_msa_ilvod_w (v4i32, v4i32); 16222v2i64 __builtin_msa_ilvod_d (v2i64, v2i64); 16223 16224v16i8 __builtin_msa_ilvr_b (v16i8, v16i8); 16225v8i16 __builtin_msa_ilvr_h (v8i16, v8i16); 16226v4i32 __builtin_msa_ilvr_w (v4i32, v4i32); 16227v2i64 __builtin_msa_ilvr_d (v2i64, v2i64); 16228 16229v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32); 16230v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32); 16231v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32); 16232v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64); 16233 16234v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8); 16235v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16); 16236v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32); 16237v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64); 16238 16239v16i8 __builtin_msa_ld_b (void *, imm_n512_511); 16240v8i16 __builtin_msa_ld_h (void *, imm_n1024_1022); 16241v4i32 __builtin_msa_ld_w (void *, imm_n2048_2044); 16242v2i64 __builtin_msa_ld_d (void *, imm_n4096_4088); 16243 16244v16i8 __builtin_msa_ldi_b (imm_n512_511); 16245v8i16 __builtin_msa_ldi_h (imm_n512_511); 16246v4i32 __builtin_msa_ldi_w (imm_n512_511); 16247v2i64 __builtin_msa_ldi_d (imm_n512_511); 16248 16249v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16); 16250v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32); 16251 16252v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16); 16253v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32); 16254 16255v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8); 16256v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16); 16257v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32); 16258v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64); 16259 16260v16i8 __builtin_msa_max_a_b (v16i8, v16i8); 16261v8i16 __builtin_msa_max_a_h (v8i16, v8i16); 16262v4i32 __builtin_msa_max_a_w (v4i32, v4i32); 16263v2i64 __builtin_msa_max_a_d (v2i64, v2i64); 16264 16265v16i8 __builtin_msa_max_s_b (v16i8, v16i8); 16266v8i16 __builtin_msa_max_s_h (v8i16, v8i16); 16267v4i32 __builtin_msa_max_s_w (v4i32, v4i32); 16268v2i64 __builtin_msa_max_s_d (v2i64, v2i64); 16269 16270v16u8 __builtin_msa_max_u_b (v16u8, v16u8); 16271v8u16 __builtin_msa_max_u_h (v8u16, v8u16); 16272v4u32 __builtin_msa_max_u_w (v4u32, v4u32); 16273v2u64 __builtin_msa_max_u_d (v2u64, v2u64); 16274 16275v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15); 16276v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15); 16277v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15); 16278v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15); 16279 16280v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31); 16281v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31); 16282v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31); 16283v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31); 16284 16285v16i8 __builtin_msa_min_a_b (v16i8, v16i8); 16286v8i16 __builtin_msa_min_a_h (v8i16, v8i16); 16287v4i32 __builtin_msa_min_a_w (v4i32, v4i32); 16288v2i64 __builtin_msa_min_a_d (v2i64, v2i64); 16289 16290v16i8 __builtin_msa_min_s_b (v16i8, v16i8); 16291v8i16 __builtin_msa_min_s_h (v8i16, v8i16); 16292v4i32 __builtin_msa_min_s_w (v4i32, v4i32); 16293v2i64 __builtin_msa_min_s_d (v2i64, v2i64); 16294 16295v16u8 __builtin_msa_min_u_b (v16u8, v16u8); 16296v8u16 __builtin_msa_min_u_h (v8u16, v8u16); 16297v4u32 __builtin_msa_min_u_w (v4u32, v4u32); 16298v2u64 __builtin_msa_min_u_d (v2u64, v2u64); 16299 16300v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15); 16301v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15); 16302v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15); 16303v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15); 16304 16305v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31); 16306v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31); 16307v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31); 16308v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31); 16309 16310v16i8 __builtin_msa_mod_s_b (v16i8, v16i8); 16311v8i16 __builtin_msa_mod_s_h (v8i16, v8i16); 16312v4i32 __builtin_msa_mod_s_w (v4i32, v4i32); 16313v2i64 __builtin_msa_mod_s_d (v2i64, v2i64); 16314 16315v16u8 __builtin_msa_mod_u_b (v16u8, v16u8); 16316v8u16 __builtin_msa_mod_u_h (v8u16, v8u16); 16317v4u32 __builtin_msa_mod_u_w (v4u32, v4u32); 16318v2u64 __builtin_msa_mod_u_d (v2u64, v2u64); 16319 16320v16i8 __builtin_msa_move_v (v16i8); 16321 16322v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16); 16323v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32); 16324 16325v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16); 16326v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32); 16327 16328v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8); 16329v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16); 16330v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32); 16331v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64); 16332 16333v8i16 __builtin_msa_mul_q_h (v8i16, v8i16); 16334v4i32 __builtin_msa_mul_q_w (v4i32, v4i32); 16335 16336v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16); 16337v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32); 16338 16339v16i8 __builtin_msa_mulv_b (v16i8, v16i8); 16340v8i16 __builtin_msa_mulv_h (v8i16, v8i16); 16341v4i32 __builtin_msa_mulv_w (v4i32, v4i32); 16342v2i64 __builtin_msa_mulv_d (v2i64, v2i64); 16343 16344v16i8 __builtin_msa_nloc_b (v16i8); 16345v8i16 __builtin_msa_nloc_h (v8i16); 16346v4i32 __builtin_msa_nloc_w (v4i32); 16347v2i64 __builtin_msa_nloc_d (v2i64); 16348 16349v16i8 __builtin_msa_nlzc_b (v16i8); 16350v8i16 __builtin_msa_nlzc_h (v8i16); 16351v4i32 __builtin_msa_nlzc_w (v4i32); 16352v2i64 __builtin_msa_nlzc_d (v2i64); 16353 16354v16u8 __builtin_msa_nor_v (v16u8, v16u8); 16355 16356v16u8 __builtin_msa_nori_b (v16u8, imm0_255); 16357 16358v16u8 __builtin_msa_or_v (v16u8, v16u8); 16359 16360v16u8 __builtin_msa_ori_b (v16u8, imm0_255); 16361 16362v16i8 __builtin_msa_pckev_b (v16i8, v16i8); 16363v8i16 __builtin_msa_pckev_h (v8i16, v8i16); 16364v4i32 __builtin_msa_pckev_w (v4i32, v4i32); 16365v2i64 __builtin_msa_pckev_d (v2i64, v2i64); 16366 16367v16i8 __builtin_msa_pckod_b (v16i8, v16i8); 16368v8i16 __builtin_msa_pckod_h (v8i16, v8i16); 16369v4i32 __builtin_msa_pckod_w (v4i32, v4i32); 16370v2i64 __builtin_msa_pckod_d (v2i64, v2i64); 16371 16372v16i8 __builtin_msa_pcnt_b (v16i8); 16373v8i16 __builtin_msa_pcnt_h (v8i16); 16374v4i32 __builtin_msa_pcnt_w (v4i32); 16375v2i64 __builtin_msa_pcnt_d (v2i64); 16376 16377v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7); 16378v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15); 16379v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31); 16380v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63); 16381 16382v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7); 16383v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15); 16384v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31); 16385v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63); 16386 16387v16i8 __builtin_msa_shf_b (v16i8, imm0_255); 16388v8i16 __builtin_msa_shf_h (v8i16, imm0_255); 16389v4i32 __builtin_msa_shf_w (v4i32, imm0_255); 16390 16391v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32); 16392v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32); 16393v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32); 16394v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32); 16395 16396v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15); 16397v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7); 16398v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3); 16399v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1); 16400 16401v16i8 __builtin_msa_sll_b (v16i8, v16i8); 16402v8i16 __builtin_msa_sll_h (v8i16, v8i16); 16403v4i32 __builtin_msa_sll_w (v4i32, v4i32); 16404v2i64 __builtin_msa_sll_d (v2i64, v2i64); 16405 16406v16i8 __builtin_msa_slli_b (v16i8, imm0_7); 16407v8i16 __builtin_msa_slli_h (v8i16, imm0_15); 16408v4i32 __builtin_msa_slli_w (v4i32, imm0_31); 16409v2i64 __builtin_msa_slli_d (v2i64, imm0_63); 16410 16411v16i8 __builtin_msa_splat_b (v16i8, i32); 16412v8i16 __builtin_msa_splat_h (v8i16, i32); 16413v4i32 __builtin_msa_splat_w (v4i32, i32); 16414v2i64 __builtin_msa_splat_d (v2i64, i32); 16415 16416v16i8 __builtin_msa_splati_b (v16i8, imm0_15); 16417v8i16 __builtin_msa_splati_h (v8i16, imm0_7); 16418v4i32 __builtin_msa_splati_w (v4i32, imm0_3); 16419v2i64 __builtin_msa_splati_d (v2i64, imm0_1); 16420 16421v16i8 __builtin_msa_sra_b (v16i8, v16i8); 16422v8i16 __builtin_msa_sra_h (v8i16, v8i16); 16423v4i32 __builtin_msa_sra_w (v4i32, v4i32); 16424v2i64 __builtin_msa_sra_d (v2i64, v2i64); 16425 16426v16i8 __builtin_msa_srai_b (v16i8, imm0_7); 16427v8i16 __builtin_msa_srai_h (v8i16, imm0_15); 16428v4i32 __builtin_msa_srai_w (v4i32, imm0_31); 16429v2i64 __builtin_msa_srai_d (v2i64, imm0_63); 16430 16431v16i8 __builtin_msa_srar_b (v16i8, v16i8); 16432v8i16 __builtin_msa_srar_h (v8i16, v8i16); 16433v4i32 __builtin_msa_srar_w (v4i32, v4i32); 16434v2i64 __builtin_msa_srar_d (v2i64, v2i64); 16435 16436v16i8 __builtin_msa_srari_b (v16i8, imm0_7); 16437v8i16 __builtin_msa_srari_h (v8i16, imm0_15); 16438v4i32 __builtin_msa_srari_w (v4i32, imm0_31); 16439v2i64 __builtin_msa_srari_d (v2i64, imm0_63); 16440 16441v16i8 __builtin_msa_srl_b (v16i8, v16i8); 16442v8i16 __builtin_msa_srl_h (v8i16, v8i16); 16443v4i32 __builtin_msa_srl_w (v4i32, v4i32); 16444v2i64 __builtin_msa_srl_d (v2i64, v2i64); 16445 16446v16i8 __builtin_msa_srli_b (v16i8, imm0_7); 16447v8i16 __builtin_msa_srli_h (v8i16, imm0_15); 16448v4i32 __builtin_msa_srli_w (v4i32, imm0_31); 16449v2i64 __builtin_msa_srli_d (v2i64, imm0_63); 16450 16451v16i8 __builtin_msa_srlr_b (v16i8, v16i8); 16452v8i16 __builtin_msa_srlr_h (v8i16, v8i16); 16453v4i32 __builtin_msa_srlr_w (v4i32, v4i32); 16454v2i64 __builtin_msa_srlr_d (v2i64, v2i64); 16455 16456v16i8 __builtin_msa_srlri_b (v16i8, imm0_7); 16457v8i16 __builtin_msa_srlri_h (v8i16, imm0_15); 16458v4i32 __builtin_msa_srlri_w (v4i32, imm0_31); 16459v2i64 __builtin_msa_srlri_d (v2i64, imm0_63); 16460 16461void __builtin_msa_st_b (v16i8, void *, imm_n512_511); 16462void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022); 16463void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044); 16464void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088); 16465 16466v16i8 __builtin_msa_subs_s_b (v16i8, v16i8); 16467v8i16 __builtin_msa_subs_s_h (v8i16, v8i16); 16468v4i32 __builtin_msa_subs_s_w (v4i32, v4i32); 16469v2i64 __builtin_msa_subs_s_d (v2i64, v2i64); 16470 16471v16u8 __builtin_msa_subs_u_b (v16u8, v16u8); 16472v8u16 __builtin_msa_subs_u_h (v8u16, v8u16); 16473v4u32 __builtin_msa_subs_u_w (v4u32, v4u32); 16474v2u64 __builtin_msa_subs_u_d (v2u64, v2u64); 16475 16476v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8); 16477v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16); 16478v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32); 16479v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64); 16480 16481v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8); 16482v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16); 16483v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32); 16484v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64); 16485 16486v16i8 __builtin_msa_subv_b (v16i8, v16i8); 16487v8i16 __builtin_msa_subv_h (v8i16, v8i16); 16488v4i32 __builtin_msa_subv_w (v4i32, v4i32); 16489v2i64 __builtin_msa_subv_d (v2i64, v2i64); 16490 16491v16i8 __builtin_msa_subvi_b (v16i8, imm0_31); 16492v8i16 __builtin_msa_subvi_h (v8i16, imm0_31); 16493v4i32 __builtin_msa_subvi_w (v4i32, imm0_31); 16494v2i64 __builtin_msa_subvi_d (v2i64, imm0_31); 16495 16496v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8); 16497v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16); 16498v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32); 16499v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64); 16500 16501v16u8 __builtin_msa_xor_v (v16u8, v16u8); 16502 16503v16u8 __builtin_msa_xori_b (v16u8, imm0_255); 16504@end smallexample 16505 16506@node Other MIPS Built-in Functions 16507@subsection Other MIPS Built-in Functions 16508 16509GCC provides other MIPS-specific built-in functions: 16510 16511@table @code 16512@item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr}) 16513Insert a @samp{cache} instruction with operands @var{op} and @var{addr}. 16514GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE} 16515when this function is available. 16516 16517@item unsigned int __builtin_mips_get_fcsr (void) 16518@itemx void __builtin_mips_set_fcsr (unsigned int @var{value}) 16519Get and set the contents of the floating-point control and status register 16520(FPU control register 31). These functions are only available in hard-float 16521code but can be called in both MIPS16 and non-MIPS16 contexts. 16522 16523@code{__builtin_mips_set_fcsr} can be used to change any bit of the 16524register except the condition codes, which GCC assumes are preserved. 16525@end table 16526 16527@node MSP430 Built-in Functions 16528@subsection MSP430 Built-in Functions 16529 16530GCC provides a couple of special builtin functions to aid in the 16531writing of interrupt handlers in C. 16532 16533@table @code 16534@item __bic_SR_register_on_exit (int @var{mask}) 16535This clears the indicated bits in the saved copy of the status register 16536currently residing on the stack. This only works inside interrupt 16537handlers and the changes to the status register will only take affect 16538once the handler returns. 16539 16540@item __bis_SR_register_on_exit (int @var{mask}) 16541This sets the indicated bits in the saved copy of the status register 16542currently residing on the stack. This only works inside interrupt 16543handlers and the changes to the status register will only take affect 16544once the handler returns. 16545 16546@item __delay_cycles (long long @var{cycles}) 16547This inserts an instruction sequence that takes exactly @var{cycles} 16548cycles (between 0 and about 17E9) to complete. The inserted sequence 16549may use jumps, loops, or no-ops, and does not interfere with any other 16550instructions. Note that @var{cycles} must be a compile-time constant 16551integer - that is, you must pass a number, not a variable that may be 16552optimized to a constant later. The number of cycles delayed by this 16553builtin is exact. 16554@end table 16555 16556@node NDS32 Built-in Functions 16557@subsection NDS32 Built-in Functions 16558 16559These built-in functions are available for the NDS32 target: 16560 16561@deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr}) 16562Insert an ISYNC instruction into the instruction stream where 16563@var{addr} is an instruction address for serialization. 16564@end deftypefn 16565 16566@deftypefn {Built-in Function} void __builtin_nds32_isb (void) 16567Insert an ISB instruction into the instruction stream. 16568@end deftypefn 16569 16570@deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr}) 16571Return the content of a system register which is mapped by @var{sr}. 16572@end deftypefn 16573 16574@deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr}) 16575Return the content of a user space register which is mapped by @var{usr}. 16576@end deftypefn 16577 16578@deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr}) 16579Move the @var{value} to a system register which is mapped by @var{sr}. 16580@end deftypefn 16581 16582@deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr}) 16583Move the @var{value} to a user space register which is mapped by @var{usr}. 16584@end deftypefn 16585 16586@deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void) 16587Enable global interrupt. 16588@end deftypefn 16589 16590@deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void) 16591Disable global interrupt. 16592@end deftypefn 16593 16594@node picoChip Built-in Functions 16595@subsection picoChip Built-in Functions 16596 16597GCC provides an interface to selected machine instructions from the 16598picoChip instruction set. 16599 16600@table @code 16601@item int __builtin_sbc (int @var{value}) 16602Sign bit count. Return the number of consecutive bits in @var{value} 16603that have the same value as the sign bit. The result is the number of 16604leading sign bits minus one, giving the number of redundant sign bits in 16605@var{value}. 16606 16607@item int __builtin_byteswap (int @var{value}) 16608Byte swap. Return the result of swapping the upper and lower bytes of 16609@var{value}. 16610 16611@item int __builtin_brev (int @var{value}) 16612Bit reversal. Return the result of reversing the bits in 16613@var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1, 16614and so on. 16615 16616@item int __builtin_adds (int @var{x}, int @var{y}) 16617Saturating addition. Return the result of adding @var{x} and @var{y}, 16618storing the value 32767 if the result overflows. 16619 16620@item int __builtin_subs (int @var{x}, int @var{y}) 16621Saturating subtraction. Return the result of subtracting @var{y} from 16622@var{x}, storing the value @minus{}32768 if the result overflows. 16623 16624@item void __builtin_halt (void) 16625Halt. The processor stops execution. This built-in is useful for 16626implementing assertions. 16627 16628@end table 16629 16630@node Basic PowerPC Built-in Functions 16631@subsection Basic PowerPC Built-in Functions 16632 16633@menu 16634* Basic PowerPC Built-in Functions Available on all Configurations:: 16635* Basic PowerPC Built-in Functions Available on ISA 2.05:: 16636* Basic PowerPC Built-in Functions Available on ISA 2.06:: 16637* Basic PowerPC Built-in Functions Available on ISA 2.07:: 16638* Basic PowerPC Built-in Functions Available on ISA 3.0:: 16639@end menu 16640 16641This section describes PowerPC built-in functions that do not require 16642the inclusion of any special header files to declare prototypes or 16643provide macro definitions. The sections that follow describe 16644additional PowerPC built-in functions. 16645 16646@node Basic PowerPC Built-in Functions Available on all Configurations 16647@subsubsection Basic PowerPC Built-in Functions Available on all Configurations 16648 16649@deftypefn {Built-in Function} void __builtin_cpu_init (void) 16650This function is a @code{nop} on the PowerPC platform and is included solely 16651to maintain API compatibility with the x86 builtins. 16652@end deftypefn 16653 16654@deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname}) 16655This function returns a value of @code{1} if the run-time CPU is of type 16656@var{cpuname} and returns @code{0} otherwise 16657 16658The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer 16659which exports the hardware capability bits. GCC defines the macro 16660@code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports} 16661built-in function is fully supported. 16662 16663If GCC was configured to use a GLIBC before 2.23, the built-in 16664function @code{__builtin_cpu_is} always returns a 0 and the compiler 16665issues a warning. 16666 16667The following CPU names can be detected: 16668 16669@table @samp 16670@item power9 16671IBM POWER9 Server CPU. 16672@item power8 16673IBM POWER8 Server CPU. 16674@item power7 16675IBM POWER7 Server CPU. 16676@item power6x 16677IBM POWER6 Server CPU (RAW mode). 16678@item power6 16679IBM POWER6 Server CPU (Architected mode). 16680@item power5+ 16681IBM POWER5+ Server CPU. 16682@item power5 16683IBM POWER5 Server CPU. 16684@item ppc970 16685IBM 970 Server CPU (ie, Apple G5). 16686@item power4 16687IBM POWER4 Server CPU. 16688@item ppca2 16689IBM A2 64-bit Embedded CPU 16690@item ppc476 16691IBM PowerPC 476FP 32-bit Embedded CPU. 16692@item ppc464 16693IBM PowerPC 464 32-bit Embedded CPU. 16694@item ppc440 16695PowerPC 440 32-bit Embedded CPU. 16696@item ppc405 16697PowerPC 405 32-bit Embedded CPU. 16698@item ppc-cell-be 16699IBM PowerPC Cell Broadband Engine Architecture CPU. 16700@end table 16701 16702Here is an example: 16703@smallexample 16704#ifdef __BUILTIN_CPU_SUPPORTS__ 16705 if (__builtin_cpu_is ("power8")) 16706 @{ 16707 do_power8 (); // POWER8 specific implementation. 16708 @} 16709 else 16710#endif 16711 @{ 16712 do_generic (); // Generic implementation. 16713 @} 16714@end smallexample 16715@end deftypefn 16716 16717@deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature}) 16718This function returns a value of @code{1} if the run-time CPU supports the HWCAP 16719feature @var{feature} and returns @code{0} otherwise. 16720 16721The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or 16722newer which exports the hardware capability bits. GCC defines the 16723macro @code{__BUILTIN_CPU_SUPPORTS__} if the 16724@code{__builtin_cpu_supports} built-in function is fully supported. 16725 16726If GCC was configured to use a GLIBC before 2.23, the built-in 16727function @code{__builtin_cpu_suports} always returns a 0 and the 16728compiler issues a warning. 16729 16730The following features can be 16731detected: 16732 16733@table @samp 16734@item 4xxmac 167354xx CPU has a Multiply Accumulator. 16736@item altivec 16737CPU has a SIMD/Vector Unit. 16738@item arch_2_05 16739CPU supports ISA 2.05 (eg, POWER6) 16740@item arch_2_06 16741CPU supports ISA 2.06 (eg, POWER7) 16742@item arch_2_07 16743CPU supports ISA 2.07 (eg, POWER8) 16744@item arch_3_00 16745CPU supports ISA 3.0 (eg, POWER9) 16746@item archpmu 16747CPU supports the set of compatible performance monitoring events. 16748@item booke 16749CPU supports the Embedded ISA category. 16750@item cellbe 16751CPU has a CELL broadband engine. 16752@item darn 16753CPU supports the @code{darn} (deliver a random number) instruction. 16754@item dfp 16755CPU has a decimal floating point unit. 16756@item dscr 16757CPU supports the data stream control register. 16758@item ebb 16759CPU supports event base branching. 16760@item efpdouble 16761CPU has a SPE double precision floating point unit. 16762@item efpsingle 16763CPU has a SPE single precision floating point unit. 16764@item fpu 16765CPU has a floating point unit. 16766@item htm 16767CPU has hardware transaction memory instructions. 16768@item htm-nosc 16769Kernel aborts hardware transactions when a syscall is made. 16770@item htm-no-suspend 16771CPU supports hardware transaction memory but does not support the 16772@code{tsuspend.} instruction. 16773@item ic_snoop 16774CPU supports icache snooping capabilities. 16775@item ieee128 16776CPU supports 128-bit IEEE binary floating point instructions. 16777@item isel 16778CPU supports the integer select instruction. 16779@item mmu 16780CPU has a memory management unit. 16781@item notb 16782CPU does not have a timebase (eg, 601 and 403gx). 16783@item pa6t 16784CPU supports the PA Semi 6T CORE ISA. 16785@item power4 16786CPU supports ISA 2.00 (eg, POWER4) 16787@item power5 16788CPU supports ISA 2.02 (eg, POWER5) 16789@item power5+ 16790CPU supports ISA 2.03 (eg, POWER5+) 16791@item power6x 16792CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr. 16793@item ppc32 16794CPU supports 32-bit mode execution. 16795@item ppc601 16796CPU supports the old POWER ISA (eg, 601) 16797@item ppc64 16798CPU supports 64-bit mode execution. 16799@item ppcle 16800CPU supports a little-endian mode that uses address swizzling. 16801@item scv 16802Kernel supports system call vectored. 16803@item smt 16804CPU support simultaneous multi-threading. 16805@item spe 16806CPU has a signal processing extension unit. 16807@item tar 16808CPU supports the target address register. 16809@item true_le 16810CPU supports true little-endian mode. 16811@item ucache 16812CPU has unified I/D cache. 16813@item vcrypto 16814CPU supports the vector cryptography instructions. 16815@item vsx 16816CPU supports the vector-scalar extension. 16817@end table 16818 16819Here is an example: 16820@smallexample 16821#ifdef __BUILTIN_CPU_SUPPORTS__ 16822 if (__builtin_cpu_supports ("fpu")) 16823 @{ 16824 asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2)); 16825 @} 16826 else 16827#endif 16828 @{ 16829 dst = __fadd (src1, src2); // Software FP addition function. 16830 @} 16831@end smallexample 16832@end deftypefn 16833 16834The following built-in functions are also available on all PowerPC 16835processors: 16836@smallexample 16837uint64_t __builtin_ppc_get_timebase (); 16838unsigned long __builtin_ppc_mftb (); 16839double __builtin_unpack_ibm128 (__ibm128, int); 16840__ibm128 __builtin_pack_ibm128 (double, double); 16841double __builtin_mffs (void); 16842void __builtin_mtfsb0 (const int); 16843void __builtin_mtfsb1 (const int); 16844void __builtin_set_fpscr_rn (int); 16845@end smallexample 16846 16847The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb} 16848functions generate instructions to read the Time Base Register. The 16849@code{__builtin_ppc_get_timebase} function may generate multiple 16850instructions and always returns the 64 bits of the Time Base Register. 16851The @code{__builtin_ppc_mftb} function always generates one instruction and 16852returns the Time Base Register value as an unsigned long, throwing away 16853the most significant word on 32-bit environments. The @code{__builtin_mffs} 16854return the value of the FPSCR register. Note, ISA 3.0 supports the 16855@code{__builtin_mffsl()} which permits software to read the control and 16856non-sticky status bits in the FSPCR without the higher latency associated with 16857accessing the sticky status bits. The 16858@code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change 16859as an argument. The valid bit range is between 0 and 31. The builtins map to 16860the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and 16861add 32. Hence these instructions only modify the FPSCR[32:63] bits by 16862changing the specified bit to a zero or one respectively. The 16863@code{__builtin_set_fpscr_rn} builtin allows changing both of the floating 16864point rounding mode bits. The argument is a 2-bit value. The argument can 16865either be a @code{const int} or stored in a variable. The builtin uses 16866the ISA 3.0 16867instruction @code{mffscrn} if available, otherwise it reads the FPSCR, masks 16868the current rounding mode bits out and OR's in the new value. 16869 16870@node Basic PowerPC Built-in Functions Available on ISA 2.05 16871@subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05 16872 16873The basic built-in functions described in this section are 16874available on the PowerPC family of processors starting with ISA 2.05 16875or later. Unless specific options are explicitly disabled on the 16876command line, specifying option @option{-mcpu=power6} has the effect of 16877enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt}, 16878@option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb}, 16879@option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and 16880@option{-mrecip-precision} options. Specify the 16881@option{-maltivec} and @option{-mfpgpr} options explicitly in 16882combination with the above options if they are desired. 16883 16884The following functions require option @option{-mcmpb}. 16885@smallexample 16886unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int); 16887unsigned int __builtin_cmpb (unsigned int, unsigned int); 16888@end smallexample 16889 16890The @code{__builtin_cmpb} function 16891performs a byte-wise compare on the contents of its two arguments, 16892returning the result of the byte-wise comparison as the returned 16893value. For each byte comparison, the corresponding byte of the return 16894value holds 0xff if the input bytes are equal and 0 if the input bytes 16895are not equal. If either of the arguments to this built-in function 16896is wider than 32 bits, the function call expands into the form that 16897expects @code{unsigned long long int} arguments 16898which is only available on 64-bit targets. 16899 16900The following built-in functions are available 16901when hardware decimal floating point 16902(@option{-mhard-dfp}) is available: 16903@smallexample 16904void __builtin_set_fpscr_drn(int); 16905_Decimal64 __builtin_ddedpd (int, _Decimal64); 16906_Decimal128 __builtin_ddedpdq (int, _Decimal128); 16907_Decimal64 __builtin_denbcd (int, _Decimal64); 16908_Decimal128 __builtin_denbcdq (int, _Decimal128); 16909_Decimal64 __builtin_diex (long long, _Decimal64); 16910_Decimal128 _builtin_diexq (long long, _Decimal128); 16911_Decimal64 __builtin_dscli (_Decimal64, int); 16912_Decimal128 __builtin_dscliq (_Decimal128, int); 16913_Decimal64 __builtin_dscri (_Decimal64, int); 16914_Decimal128 __builtin_dscriq (_Decimal128, int); 16915long long __builtin_dxex (_Decimal64); 16916long long __builtin_dxexq (_Decimal128); 16917_Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long); 16918unsigned long long __builtin_unpack_dec128 (_Decimal128, int); 16919 16920The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal 16921floating point rounding mode bits. The argument is a 3-bit value. The 16922argument can either be a @code{const int} or the value can be stored in 16923a variable. 16924The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available. 16925Otherwise the builtin reads the FPSCR, masks the current decimal rounding 16926mode bits out and OR's in the new value. 16927 16928@end smallexample 16929 16930The following functions require @option{-mhard-float}, 16931@option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options. 16932 16933@smallexample 16934double __builtin_recipdiv (double, double); 16935float __builtin_recipdivf (float, float); 16936double __builtin_rsqrt (double); 16937float __builtin_rsqrtf (float); 16938@end smallexample 16939 16940The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and 16941@code{__builtin_rsqrtf} functions generate multiple instructions to 16942implement the reciprocal sqrt functionality using reciprocal sqrt 16943estimate instructions. 16944 16945The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf} 16946functions generate multiple instructions to implement division using 16947the reciprocal estimate instructions. 16948 16949The following functions require @option{-mhard-float} and 16950@option{-mmultiple} options. 16951 16952The @code{__builtin_unpack_longdouble} function takes a 16953@code{long double} argument and a compile time constant of 0 or 1. If 16954the constant is 0, the first @code{double} within the 16955@code{long double} is returned, otherwise the second @code{double} 16956is returned. The @code{__builtin_unpack_longdouble} function is only 16957available if @code{long double} uses the IBM extended double 16958representation. 16959 16960The @code{__builtin_pack_longdouble} function takes two @code{double} 16961arguments and returns a @code{long double} value that combines the two 16962arguments. The @code{__builtin_pack_longdouble} function is only 16963available if @code{long double} uses the IBM extended double 16964representation. 16965 16966The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128} 16967argument and a compile time constant of 0 or 1. If the constant is 0, 16968the first @code{double} within the @code{__ibm128} is returned, 16969otherwise the second @code{double} is returned. 16970 16971The @code{__builtin_pack_ibm128} function takes two @code{double} 16972arguments and returns a @code{__ibm128} value that combines the two 16973arguments. 16974 16975Additional built-in functions are available for the 64-bit PowerPC 16976family of processors, for efficient use of 128-bit floating point 16977(@code{__float128}) values. 16978 16979@node Basic PowerPC Built-in Functions Available on ISA 2.06 16980@subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06 16981 16982The basic built-in functions described in this section are 16983available on the PowerPC family of processors starting with ISA 2.05 16984or later. Unless specific options are explicitly disabled on the 16985command line, specifying option @option{-mcpu=power7} has the effect of 16986enabling all the same options as for @option{-mcpu=power6} in 16987addition to the @option{-maltivec}, @option{-mpopcntd}, and 16988@option{-mvsx} options. 16989 16990The following basic built-in functions require @option{-mpopcntd}: 16991@smallexample 16992unsigned int __builtin_addg6s (unsigned int, unsigned int); 16993long long __builtin_bpermd (long long, long long); 16994unsigned int __builtin_cbcdtd (unsigned int); 16995unsigned int __builtin_cdtbcd (unsigned int); 16996long long __builtin_divde (long long, long long); 16997unsigned long long __builtin_divdeu (unsigned long long, unsigned long long); 16998int __builtin_divwe (int, int); 16999unsigned int __builtin_divweu (unsigned int, unsigned int); 17000vector __int128 __builtin_pack_vector_int128 (long long, long long); 17001void __builtin_rs6000_speculation_barrier (void); 17002long long __builtin_unpack_vector_int128 (vector __int128, signed char); 17003@end smallexample 17004 17005Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions 17006require a 64-bit environment. 17007 17008The following basic built-in functions, which are also supported on 17009x86 targets, require @option{-mfloat128}. 17010@smallexample 17011__float128 __builtin_fabsq (__float128); 17012__float128 __builtin_copysignq (__float128, __float128); 17013__float128 __builtin_infq (void); 17014__float128 __builtin_huge_valq (void); 17015__float128 __builtin_nanq (void); 17016__float128 __builtin_nansq (void); 17017 17018__float128 __builtin_sqrtf128 (__float128); 17019__float128 __builtin_fmaf128 (__float128, __float128, __float128); 17020@end smallexample 17021 17022@node Basic PowerPC Built-in Functions Available on ISA 2.07 17023@subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07 17024 17025The basic built-in functions described in this section are 17026available on the PowerPC family of processors starting with ISA 2.07 17027or later. Unless specific options are explicitly disabled on the 17028command line, specifying option @option{-mcpu=power8} has the effect of 17029enabling all the same options as for @option{-mcpu=power7} in 17030addition to the @option{-mpower8-fusion}, @option{-mpower8-vector}, 17031@option{-mcrypto}, @option{-mhtm}, @option{-mquad-memory}, and 17032@option{-mquad-memory-atomic} options. 17033 17034This section intentionally empty. 17035 17036@node Basic PowerPC Built-in Functions Available on ISA 3.0 17037@subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0 17038 17039The basic built-in functions described in this section are 17040available on the PowerPC family of processors starting with ISA 3.0 17041or later. Unless specific options are explicitly disabled on the 17042command line, specifying option @option{-mcpu=power9} has the effect of 17043enabling all the same options as for @option{-mcpu=power8} in 17044addition to the @option{-misel} option. 17045 17046The following built-in functions are available on Linux 64-bit systems 17047that use the ISA 3.0 instruction set (@option{-mcpu=power9}): 17048 17049@table @code 17050@item __float128 __builtin_addf128_round_to_odd (__float128, __float128) 17051Perform a 128-bit IEEE floating point add using round to odd as the 17052rounding mode. 17053@findex __builtin_addf128_round_to_odd 17054 17055@item __float128 __builtin_subf128_round_to_odd (__float128, __float128) 17056Perform a 128-bit IEEE floating point subtract using round to odd as 17057the rounding mode. 17058@findex __builtin_subf128_round_to_odd 17059 17060@item __float128 __builtin_mulf128_round_to_odd (__float128, __float128) 17061Perform a 128-bit IEEE floating point multiply using round to odd as 17062the rounding mode. 17063@findex __builtin_mulf128_round_to_odd 17064 17065@item __float128 __builtin_divf128_round_to_odd (__float128, __float128) 17066Perform a 128-bit IEEE floating point divide using round to odd as 17067the rounding mode. 17068@findex __builtin_divf128_round_to_odd 17069 17070@item __float128 __builtin_sqrtf128_round_to_odd (__float128) 17071Perform a 128-bit IEEE floating point square root using round to odd 17072as the rounding mode. 17073@findex __builtin_sqrtf128_round_to_odd 17074 17075@item __float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128) 17076Perform a 128-bit IEEE floating point fused multiply and add operation 17077using round to odd as the rounding mode. 17078@findex __builtin_fmaf128_round_to_odd 17079 17080@item double __builtin_truncf128_round_to_odd (__float128) 17081Convert a 128-bit IEEE floating point value to @code{double} using 17082round to odd as the rounding mode. 17083@findex __builtin_truncf128_round_to_odd 17084@end table 17085 17086The following additional built-in functions are also available for the 17087PowerPC family of processors, starting with ISA 3.0 or later: 17088@smallexample 17089long long __builtin_darn (void); 17090long long __builtin_darn_raw (void); 17091int __builtin_darn_32 (void); 17092@end smallexample 17093 17094The @code{__builtin_darn} and @code{__builtin_darn_raw} 17095functions require a 1709664-bit environment supporting ISA 3.0 or later. 17097The @code{__builtin_darn} function provides a 64-bit conditioned 17098random number. The @code{__builtin_darn_raw} function provides a 1709964-bit raw random number. The @code{__builtin_darn_32} function 17100provides a 32-bit conditioned random number. 17101 17102The following additional built-in functions are also available for the 17103PowerPC family of processors, starting with ISA 3.0 or later: 17104 17105@smallexample 17106int __builtin_byte_in_set (unsigned char u, unsigned long long set); 17107int __builtin_byte_in_range (unsigned char u, unsigned int range); 17108int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges); 17109 17110int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value); 17111int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value); 17112int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value); 17113int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value); 17114 17115int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value); 17116int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value); 17117int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value); 17118int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value); 17119 17120int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value); 17121int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value); 17122int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value); 17123int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value); 17124 17125int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value); 17126int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value); 17127int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value); 17128int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value); 17129 17130double __builtin_mffsl(void); 17131 17132@end smallexample 17133The @code{__builtin_byte_in_set} function requires a 1713464-bit environment supporting ISA 3.0 or later. This function returns 17135a non-zero value if and only if its @code{u} argument exactly equals one of 17136the eight bytes contained within its 64-bit @code{set} argument. 17137 17138The @code{__builtin_byte_in_range} and 17139@code{__builtin_byte_in_either_range} require an environment 17140supporting ISA 3.0 or later. For these two functions, the 17141@code{range} argument is encoded as 4 bytes, organized as 17142@code{hi_1:lo_1:hi_2:lo_2}. 17143The @code{__builtin_byte_in_range} function returns a 17144non-zero value if and only if its @code{u} argument is within the 17145range bounded between @code{lo_2} and @code{hi_2} inclusive. 17146The @code{__builtin_byte_in_either_range} function returns non-zero if 17147and only if its @code{u} argument is within either the range bounded 17148between @code{lo_1} and @code{hi_1} inclusive or the range bounded 17149between @code{lo_2} and @code{hi_2} inclusive. 17150 17151The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value 17152if and only if the number of signficant digits of its @code{value} argument 17153is less than its @code{comparison} argument. The 17154@code{__builtin_dfp_dtstsfi_lt_dd} and 17155@code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but 17156require that the type of the @code{value} argument be 17157@code{__Decimal64} and @code{__Decimal128} respectively. 17158 17159The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value 17160if and only if the number of signficant digits of its @code{value} argument 17161is greater than its @code{comparison} argument. The 17162@code{__builtin_dfp_dtstsfi_gt_dd} and 17163@code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but 17164require that the type of the @code{value} argument be 17165@code{__Decimal64} and @code{__Decimal128} respectively. 17166 17167The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value 17168if and only if the number of signficant digits of its @code{value} argument 17169equals its @code{comparison} argument. The 17170@code{__builtin_dfp_dtstsfi_eq_dd} and 17171@code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but 17172require that the type of the @code{value} argument be 17173@code{__Decimal64} and @code{__Decimal128} respectively. 17174 17175The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value 17176if and only if its @code{value} argument has an undefined number of 17177significant digits, such as when @code{value} is an encoding of @code{NaN}. 17178The @code{__builtin_dfp_dtstsfi_ov_dd} and 17179@code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but 17180require that the type of the @code{value} argument be 17181@code{__Decimal64} and @code{__Decimal128} respectively. 17182 17183The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read 17184the FPSCR. The instruction is a lower latency version of the @code{mffs} 17185instruction. If the @code{mffsl} instruction is not available, then the 17186builtin uses the older @code{mffs} instruction to read the FPSCR. 17187 17188 17189@node PowerPC AltiVec/VSX Built-in Functions 17190@subsection PowerPC AltiVec/VSX Built-in Functions 17191 17192GCC provides an interface for the PowerPC family of processors to access 17193the AltiVec operations described in Motorola's AltiVec Programming 17194Interface Manual. The interface is made available by including 17195@code{<altivec.h>} and using @option{-maltivec} and 17196@option{-mabi=altivec}. The interface supports the following vector 17197types. 17198 17199@smallexample 17200vector unsigned char 17201vector signed char 17202vector bool char 17203 17204vector unsigned short 17205vector signed short 17206vector bool short 17207vector pixel 17208 17209vector unsigned int 17210vector signed int 17211vector bool int 17212vector float 17213@end smallexample 17214 17215GCC's implementation of the high-level language interface available from 17216C and C++ code differs from Motorola's documentation in several ways. 17217 17218@itemize @bullet 17219 17220@item 17221A vector constant is a list of constant expressions within curly braces. 17222 17223@item 17224A vector initializer requires no cast if the vector constant is of the 17225same type as the variable it is initializing. 17226 17227@item 17228If @code{signed} or @code{unsigned} is omitted, the signedness of the 17229vector type is the default signedness of the base type. The default 17230varies depending on the operating system, so a portable program should 17231always specify the signedness. 17232 17233@item 17234Compiling with @option{-maltivec} adds keywords @code{__vector}, 17235@code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and 17236@code{bool}. When compiling ISO C, the context-sensitive substitution 17237of the keywords @code{vector}, @code{pixel} and @code{bool} is 17238disabled. To use them, you must include @code{<altivec.h>} instead. 17239 17240@item 17241GCC allows using a @code{typedef} name as the type specifier for a 17242vector type, but only under the following circumstances: 17243 17244@itemize @bullet 17245 17246@item 17247When using @code{__vector} instead of @code{vector}; for example, 17248 17249@smallexample 17250typedef signed short int16; 17251__vector int16 data; 17252@end smallexample 17253 17254@item 17255When using @code{vector} in keyword-and-predefine mode; for example, 17256 17257@smallexample 17258typedef signed short int16; 17259vector int16 data; 17260@end smallexample 17261 17262Note that keyword-and-predefine mode is enabled by disabling GNU 17263extensions (e.g., by using @code{-std=c11}) and including 17264@code{<altivec.h>}. 17265@end itemize 17266 17267@item 17268For C, overloaded functions are implemented with macros so the following 17269does not work: 17270 17271@smallexample 17272 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); 17273@end smallexample 17274 17275@noindent 17276Since @code{vec_add} is a macro, the vector constant in the example 17277is treated as four separate arguments. Wrap the entire argument in 17278parentheses for this to work. 17279@end itemize 17280 17281@emph{Note:} Only the @code{<altivec.h>} interface is supported. 17282Internally, GCC uses built-in functions to achieve the functionality in 17283the aforementioned header file, but they are not supported and are 17284subject to change without notice. 17285 17286GCC complies with the OpenPOWER 64-Bit ELF V2 ABI Specification, 17287which may be found at 17288@uref{http://openpowerfoundation.org/wp-content/uploads/resources/leabi-prd/content/index.html}. 17289Appendix A of this document lists the vector API interfaces that must be 17290provided by compliant compilers. Programmers should preferentially use 17291the interfaces described therein. However, historically GCC has provided 17292additional interfaces for access to vector instructions. These are 17293briefly described below. 17294 17295@menu 17296* PowerPC AltiVec Built-in Functions on ISA 2.05:: 17297* PowerPC AltiVec Built-in Functions Available on ISA 2.06:: 17298* PowerPC AltiVec Built-in Functions Available on ISA 2.07:: 17299* PowerPC AltiVec Built-in Functions Available on ISA 3.0:: 17300@end menu 17301 17302@node PowerPC AltiVec Built-in Functions on ISA 2.05 17303@subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05 17304 17305The following interfaces are supported for the generic and specific 17306AltiVec operations and the AltiVec predicates. In cases where there 17307is a direct mapping between generic and specific operations, only the 17308generic names are shown here, although the specific operations can also 17309be used. 17310 17311Arguments that are documented as @code{const int} require literal 17312integral values within the range required for that operation. 17313 17314@smallexample 17315vector signed char vec_abs (vector signed char); 17316vector signed short vec_abs (vector signed short); 17317vector signed int vec_abs (vector signed int); 17318vector float vec_abs (vector float); 17319 17320vector signed char vec_abss (vector signed char); 17321vector signed short vec_abss (vector signed short); 17322vector signed int vec_abss (vector signed int); 17323 17324vector signed char vec_add (vector bool char, vector signed char); 17325vector signed char vec_add (vector signed char, vector bool char); 17326vector signed char vec_add (vector signed char, vector signed char); 17327vector unsigned char vec_add (vector bool char, vector unsigned char); 17328vector unsigned char vec_add (vector unsigned char, vector bool char); 17329vector unsigned char vec_add (vector unsigned char, vector unsigned char); 17330vector signed short vec_add (vector bool short, vector signed short); 17331vector signed short vec_add (vector signed short, vector bool short); 17332vector signed short vec_add (vector signed short, vector signed short); 17333vector unsigned short vec_add (vector bool short, vector unsigned short); 17334vector unsigned short vec_add (vector unsigned short, vector bool short); 17335vector unsigned short vec_add (vector unsigned short, vector unsigned short); 17336vector signed int vec_add (vector bool int, vector signed int); 17337vector signed int vec_add (vector signed int, vector bool int); 17338vector signed int vec_add (vector signed int, vector signed int); 17339vector unsigned int vec_add (vector bool int, vector unsigned int); 17340vector unsigned int vec_add (vector unsigned int, vector bool int); 17341vector unsigned int vec_add (vector unsigned int, vector unsigned int); 17342vector float vec_add (vector float, vector float); 17343 17344vector unsigned int vec_addc (vector unsigned int, vector unsigned int); 17345 17346vector unsigned char vec_adds (vector bool char, vector unsigned char); 17347vector unsigned char vec_adds (vector unsigned char, vector bool char); 17348vector unsigned char vec_adds (vector unsigned char, vector unsigned char); 17349vector signed char vec_adds (vector bool char, vector signed char); 17350vector signed char vec_adds (vector signed char, vector bool char); 17351vector signed char vec_adds (vector signed char, vector signed char); 17352vector unsigned short vec_adds (vector bool short, vector unsigned short); 17353vector unsigned short vec_adds (vector unsigned short, vector bool short); 17354vector unsigned short vec_adds (vector unsigned short, vector unsigned short); 17355vector signed short vec_adds (vector bool short, vector signed short); 17356vector signed short vec_adds (vector signed short, vector bool short); 17357vector signed short vec_adds (vector signed short, vector signed short); 17358vector unsigned int vec_adds (vector bool int, vector unsigned int); 17359vector unsigned int vec_adds (vector unsigned int, vector bool int); 17360vector unsigned int vec_adds (vector unsigned int, vector unsigned int); 17361vector signed int vec_adds (vector bool int, vector signed int); 17362vector signed int vec_adds (vector signed int, vector bool int); 17363vector signed int vec_adds (vector signed int, vector signed int); 17364 17365int vec_all_eq (vector signed char, vector bool char); 17366int vec_all_eq (vector signed char, vector signed char); 17367int vec_all_eq (vector unsigned char, vector bool char); 17368int vec_all_eq (vector unsigned char, vector unsigned char); 17369int vec_all_eq (vector bool char, vector bool char); 17370int vec_all_eq (vector bool char, vector unsigned char); 17371int vec_all_eq (vector bool char, vector signed char); 17372int vec_all_eq (vector signed short, vector bool short); 17373int vec_all_eq (vector signed short, vector signed short); 17374int vec_all_eq (vector unsigned short, vector bool short); 17375int vec_all_eq (vector unsigned short, vector unsigned short); 17376int vec_all_eq (vector bool short, vector bool short); 17377int vec_all_eq (vector bool short, vector unsigned short); 17378int vec_all_eq (vector bool short, vector signed short); 17379int vec_all_eq (vector pixel, vector pixel); 17380int vec_all_eq (vector signed int, vector bool int); 17381int vec_all_eq (vector signed int, vector signed int); 17382int vec_all_eq (vector unsigned int, vector bool int); 17383int vec_all_eq (vector unsigned int, vector unsigned int); 17384int vec_all_eq (vector bool int, vector bool int); 17385int vec_all_eq (vector bool int, vector unsigned int); 17386int vec_all_eq (vector bool int, vector signed int); 17387int vec_all_eq (vector float, vector float); 17388 17389int vec_all_ge (vector bool char, vector unsigned char); 17390int vec_all_ge (vector unsigned char, vector bool char); 17391int vec_all_ge (vector unsigned char, vector unsigned char); 17392int vec_all_ge (vector bool char, vector signed char); 17393int vec_all_ge (vector signed char, vector bool char); 17394int vec_all_ge (vector signed char, vector signed char); 17395int vec_all_ge (vector bool short, vector unsigned short); 17396int vec_all_ge (vector unsigned short, vector bool short); 17397int vec_all_ge (vector unsigned short, vector unsigned short); 17398int vec_all_ge (vector signed short, vector signed short); 17399int vec_all_ge (vector bool short, vector signed short); 17400int vec_all_ge (vector signed short, vector bool short); 17401int vec_all_ge (vector bool int, vector unsigned int); 17402int vec_all_ge (vector unsigned int, vector bool int); 17403int vec_all_ge (vector unsigned int, vector unsigned int); 17404int vec_all_ge (vector bool int, vector signed int); 17405int vec_all_ge (vector signed int, vector bool int); 17406int vec_all_ge (vector signed int, vector signed int); 17407int vec_all_ge (vector float, vector float); 17408 17409int vec_all_gt (vector bool char, vector unsigned char); 17410int vec_all_gt (vector unsigned char, vector bool char); 17411int vec_all_gt (vector unsigned char, vector unsigned char); 17412int vec_all_gt (vector bool char, vector signed char); 17413int vec_all_gt (vector signed char, vector bool char); 17414int vec_all_gt (vector signed char, vector signed char); 17415int vec_all_gt (vector bool short, vector unsigned short); 17416int vec_all_gt (vector unsigned short, vector bool short); 17417int vec_all_gt (vector unsigned short, vector unsigned short); 17418int vec_all_gt (vector bool short, vector signed short); 17419int vec_all_gt (vector signed short, vector bool short); 17420int vec_all_gt (vector signed short, vector signed short); 17421int vec_all_gt (vector bool int, vector unsigned int); 17422int vec_all_gt (vector unsigned int, vector bool int); 17423int vec_all_gt (vector unsigned int, vector unsigned int); 17424int vec_all_gt (vector bool int, vector signed int); 17425int vec_all_gt (vector signed int, vector bool int); 17426int vec_all_gt (vector signed int, vector signed int); 17427int vec_all_gt (vector float, vector float); 17428 17429int vec_all_in (vector float, vector float); 17430 17431int vec_all_le (vector bool char, vector unsigned char); 17432int vec_all_le (vector unsigned char, vector bool char); 17433int vec_all_le (vector unsigned char, vector unsigned char); 17434int vec_all_le (vector bool char, vector signed char); 17435int vec_all_le (vector signed char, vector bool char); 17436int vec_all_le (vector signed char, vector signed char); 17437int vec_all_le (vector bool short, vector unsigned short); 17438int vec_all_le (vector unsigned short, vector bool short); 17439int vec_all_le (vector unsigned short, vector unsigned short); 17440int vec_all_le (vector bool short, vector signed short); 17441int vec_all_le (vector signed short, vector bool short); 17442int vec_all_le (vector signed short, vector signed short); 17443int vec_all_le (vector bool int, vector unsigned int); 17444int vec_all_le (vector unsigned int, vector bool int); 17445int vec_all_le (vector unsigned int, vector unsigned int); 17446int vec_all_le (vector bool int, vector signed int); 17447int vec_all_le (vector signed int, vector bool int); 17448int vec_all_le (vector signed int, vector signed int); 17449int vec_all_le (vector float, vector float); 17450 17451int vec_all_lt (vector bool char, vector unsigned char); 17452int vec_all_lt (vector unsigned char, vector bool char); 17453int vec_all_lt (vector unsigned char, vector unsigned char); 17454int vec_all_lt (vector bool char, vector signed char); 17455int vec_all_lt (vector signed char, vector bool char); 17456int vec_all_lt (vector signed char, vector signed char); 17457int vec_all_lt (vector bool short, vector unsigned short); 17458int vec_all_lt (vector unsigned short, vector bool short); 17459int vec_all_lt (vector unsigned short, vector unsigned short); 17460int vec_all_lt (vector bool short, vector signed short); 17461int vec_all_lt (vector signed short, vector bool short); 17462int vec_all_lt (vector signed short, vector signed short); 17463int vec_all_lt (vector bool int, vector unsigned int); 17464int vec_all_lt (vector unsigned int, vector bool int); 17465int vec_all_lt (vector unsigned int, vector unsigned int); 17466int vec_all_lt (vector bool int, vector signed int); 17467int vec_all_lt (vector signed int, vector bool int); 17468int vec_all_lt (vector signed int, vector signed int); 17469int vec_all_lt (vector float, vector float); 17470 17471int vec_all_nan (vector float); 17472 17473int vec_all_ne (vector signed char, vector bool char); 17474int vec_all_ne (vector signed char, vector signed char); 17475int vec_all_ne (vector unsigned char, vector bool char); 17476int vec_all_ne (vector unsigned char, vector unsigned char); 17477int vec_all_ne (vector bool char, vector bool char); 17478int vec_all_ne (vector bool char, vector unsigned char); 17479int vec_all_ne (vector bool char, vector signed char); 17480int vec_all_ne (vector signed short, vector bool short); 17481int vec_all_ne (vector signed short, vector signed short); 17482int vec_all_ne (vector unsigned short, vector bool short); 17483int vec_all_ne (vector unsigned short, vector unsigned short); 17484int vec_all_ne (vector bool short, vector bool short); 17485int vec_all_ne (vector bool short, vector unsigned short); 17486int vec_all_ne (vector bool short, vector signed short); 17487int vec_all_ne (vector pixel, vector pixel); 17488int vec_all_ne (vector signed int, vector bool int); 17489int vec_all_ne (vector signed int, vector signed int); 17490int vec_all_ne (vector unsigned int, vector bool int); 17491int vec_all_ne (vector unsigned int, vector unsigned int); 17492int vec_all_ne (vector bool int, vector bool int); 17493int vec_all_ne (vector bool int, vector unsigned int); 17494int vec_all_ne (vector bool int, vector signed int); 17495int vec_all_ne (vector float, vector float); 17496 17497int vec_all_nge (vector float, vector float); 17498 17499int vec_all_ngt (vector float, vector float); 17500 17501int vec_all_nle (vector float, vector float); 17502 17503int vec_all_nlt (vector float, vector float); 17504 17505int vec_all_numeric (vector float); 17506 17507vector float vec_and (vector float, vector float); 17508vector float vec_and (vector float, vector bool int); 17509vector float vec_and (vector bool int, vector float); 17510vector bool int vec_and (vector bool int, vector bool int); 17511vector signed int vec_and (vector bool int, vector signed int); 17512vector signed int vec_and (vector signed int, vector bool int); 17513vector signed int vec_and (vector signed int, vector signed int); 17514vector unsigned int vec_and (vector bool int, vector unsigned int); 17515vector unsigned int vec_and (vector unsigned int, vector bool int); 17516vector unsigned int vec_and (vector unsigned int, vector unsigned int); 17517vector bool short vec_and (vector bool short, vector bool short); 17518vector signed short vec_and (vector bool short, vector signed short); 17519vector signed short vec_and (vector signed short, vector bool short); 17520vector signed short vec_and (vector signed short, vector signed short); 17521vector unsigned short vec_and (vector bool short, vector unsigned short); 17522vector unsigned short vec_and (vector unsigned short, vector bool short); 17523vector unsigned short vec_and (vector unsigned short, vector unsigned short); 17524vector signed char vec_and (vector bool char, vector signed char); 17525vector bool char vec_and (vector bool char, vector bool char); 17526vector signed char vec_and (vector signed char, vector bool char); 17527vector signed char vec_and (vector signed char, vector signed char); 17528vector unsigned char vec_and (vector bool char, vector unsigned char); 17529vector unsigned char vec_and (vector unsigned char, vector bool char); 17530vector unsigned char vec_and (vector unsigned char, vector unsigned char); 17531 17532vector float vec_andc (vector float, vector float); 17533vector float vec_andc (vector float, vector bool int); 17534vector float vec_andc (vector bool int, vector float); 17535vector bool int vec_andc (vector bool int, vector bool int); 17536vector signed int vec_andc (vector bool int, vector signed int); 17537vector signed int vec_andc (vector signed int, vector bool int); 17538vector signed int vec_andc (vector signed int, vector signed int); 17539vector unsigned int vec_andc (vector bool int, vector unsigned int); 17540vector unsigned int vec_andc (vector unsigned int, vector bool int); 17541vector unsigned int vec_andc (vector unsigned int, vector unsigned int); 17542vector bool short vec_andc (vector bool short, vector bool short); 17543vector signed short vec_andc (vector bool short, vector signed short); 17544vector signed short vec_andc (vector signed short, vector bool short); 17545vector signed short vec_andc (vector signed short, vector signed short); 17546vector unsigned short vec_andc (vector bool short, vector unsigned short); 17547vector unsigned short vec_andc (vector unsigned short, vector bool short); 17548vector unsigned short vec_andc (vector unsigned short, vector unsigned short); 17549vector signed char vec_andc (vector bool char, vector signed char); 17550vector bool char vec_andc (vector bool char, vector bool char); 17551vector signed char vec_andc (vector signed char, vector bool char); 17552vector signed char vec_andc (vector signed char, vector signed char); 17553vector unsigned char vec_andc (vector bool char, vector unsigned char); 17554vector unsigned char vec_andc (vector unsigned char, vector bool char); 17555vector unsigned char vec_andc (vector unsigned char, vector unsigned char); 17556 17557int vec_any_eq (vector signed char, vector bool char); 17558int vec_any_eq (vector signed char, vector signed char); 17559int vec_any_eq (vector unsigned char, vector bool char); 17560int vec_any_eq (vector unsigned char, vector unsigned char); 17561int vec_any_eq (vector bool char, vector bool char); 17562int vec_any_eq (vector bool char, vector unsigned char); 17563int vec_any_eq (vector bool char, vector signed char); 17564int vec_any_eq (vector signed short, vector bool short); 17565int vec_any_eq (vector signed short, vector signed short); 17566int vec_any_eq (vector unsigned short, vector bool short); 17567int vec_any_eq (vector unsigned short, vector unsigned short); 17568int vec_any_eq (vector bool short, vector bool short); 17569int vec_any_eq (vector bool short, vector unsigned short); 17570int vec_any_eq (vector bool short, vector signed short); 17571int vec_any_eq (vector pixel, vector pixel); 17572int vec_any_eq (vector signed int, vector bool int); 17573int vec_any_eq (vector signed int, vector signed int); 17574int vec_any_eq (vector unsigned int, vector bool int); 17575int vec_any_eq (vector unsigned int, vector unsigned int); 17576int vec_any_eq (vector bool int, vector bool int); 17577int vec_any_eq (vector bool int, vector unsigned int); 17578int vec_any_eq (vector bool int, vector signed int); 17579int vec_any_eq (vector float, vector float); 17580 17581int vec_any_ge (vector signed char, vector bool char); 17582int vec_any_ge (vector unsigned char, vector bool char); 17583int vec_any_ge (vector unsigned char, vector unsigned char); 17584int vec_any_ge (vector signed char, vector signed char); 17585int vec_any_ge (vector bool char, vector unsigned char); 17586int vec_any_ge (vector bool char, vector signed char); 17587int vec_any_ge (vector unsigned short, vector bool short); 17588int vec_any_ge (vector unsigned short, vector unsigned short); 17589int vec_any_ge (vector signed short, vector signed short); 17590int vec_any_ge (vector signed short, vector bool short); 17591int vec_any_ge (vector bool short, vector unsigned short); 17592int vec_any_ge (vector bool short, vector signed short); 17593int vec_any_ge (vector signed int, vector bool int); 17594int vec_any_ge (vector unsigned int, vector bool int); 17595int vec_any_ge (vector unsigned int, vector unsigned int); 17596int vec_any_ge (vector signed int, vector signed int); 17597int vec_any_ge (vector bool int, vector unsigned int); 17598int vec_any_ge (vector bool int, vector signed int); 17599int vec_any_ge (vector float, vector float); 17600 17601int vec_any_gt (vector bool char, vector unsigned char); 17602int vec_any_gt (vector unsigned char, vector bool char); 17603int vec_any_gt (vector unsigned char, vector unsigned char); 17604int vec_any_gt (vector bool char, vector signed char); 17605int vec_any_gt (vector signed char, vector bool char); 17606int vec_any_gt (vector signed char, vector signed char); 17607int vec_any_gt (vector bool short, vector unsigned short); 17608int vec_any_gt (vector unsigned short, vector bool short); 17609int vec_any_gt (vector unsigned short, vector unsigned short); 17610int vec_any_gt (vector bool short, vector signed short); 17611int vec_any_gt (vector signed short, vector bool short); 17612int vec_any_gt (vector signed short, vector signed short); 17613int vec_any_gt (vector bool int, vector unsigned int); 17614int vec_any_gt (vector unsigned int, vector bool int); 17615int vec_any_gt (vector unsigned int, vector unsigned int); 17616int vec_any_gt (vector bool int, vector signed int); 17617int vec_any_gt (vector signed int, vector bool int); 17618int vec_any_gt (vector signed int, vector signed int); 17619int vec_any_gt (vector float, vector float); 17620 17621int vec_any_le (vector bool char, vector unsigned char); 17622int vec_any_le (vector unsigned char, vector bool char); 17623int vec_any_le (vector unsigned char, vector unsigned char); 17624int vec_any_le (vector bool char, vector signed char); 17625int vec_any_le (vector signed char, vector bool char); 17626int vec_any_le (vector signed char, vector signed char); 17627int vec_any_le (vector bool short, vector unsigned short); 17628int vec_any_le (vector unsigned short, vector bool short); 17629int vec_any_le (vector unsigned short, vector unsigned short); 17630int vec_any_le (vector bool short, vector signed short); 17631int vec_any_le (vector signed short, vector bool short); 17632int vec_any_le (vector signed short, vector signed short); 17633int vec_any_le (vector bool int, vector unsigned int); 17634int vec_any_le (vector unsigned int, vector bool int); 17635int vec_any_le (vector unsigned int, vector unsigned int); 17636int vec_any_le (vector bool int, vector signed int); 17637int vec_any_le (vector signed int, vector bool int); 17638int vec_any_le (vector signed int, vector signed int); 17639int vec_any_le (vector float, vector float); 17640 17641int vec_any_lt (vector bool char, vector unsigned char); 17642int vec_any_lt (vector unsigned char, vector bool char); 17643int vec_any_lt (vector unsigned char, vector unsigned char); 17644int vec_any_lt (vector bool char, vector signed char); 17645int vec_any_lt (vector signed char, vector bool char); 17646int vec_any_lt (vector signed char, vector signed char); 17647int vec_any_lt (vector bool short, vector unsigned short); 17648int vec_any_lt (vector unsigned short, vector bool short); 17649int vec_any_lt (vector unsigned short, vector unsigned short); 17650int vec_any_lt (vector bool short, vector signed short); 17651int vec_any_lt (vector signed short, vector bool short); 17652int vec_any_lt (vector signed short, vector signed short); 17653int vec_any_lt (vector bool int, vector unsigned int); 17654int vec_any_lt (vector unsigned int, vector bool int); 17655int vec_any_lt (vector unsigned int, vector unsigned int); 17656int vec_any_lt (vector bool int, vector signed int); 17657int vec_any_lt (vector signed int, vector bool int); 17658int vec_any_lt (vector signed int, vector signed int); 17659int vec_any_lt (vector float, vector float); 17660 17661int vec_any_nan (vector float); 17662 17663int vec_any_ne (vector signed char, vector bool char); 17664int vec_any_ne (vector signed char, vector signed char); 17665int vec_any_ne (vector unsigned char, vector bool char); 17666int vec_any_ne (vector unsigned char, vector unsigned char); 17667int vec_any_ne (vector bool char, vector bool char); 17668int vec_any_ne (vector bool char, vector unsigned char); 17669int vec_any_ne (vector bool char, vector signed char); 17670int vec_any_ne (vector signed short, vector bool short); 17671int vec_any_ne (vector signed short, vector signed short); 17672int vec_any_ne (vector unsigned short, vector bool short); 17673int vec_any_ne (vector unsigned short, vector unsigned short); 17674int vec_any_ne (vector bool short, vector bool short); 17675int vec_any_ne (vector bool short, vector unsigned short); 17676int vec_any_ne (vector bool short, vector signed short); 17677int vec_any_ne (vector pixel, vector pixel); 17678int vec_any_ne (vector signed int, vector bool int); 17679int vec_any_ne (vector signed int, vector signed int); 17680int vec_any_ne (vector unsigned int, vector bool int); 17681int vec_any_ne (vector unsigned int, vector unsigned int); 17682int vec_any_ne (vector bool int, vector bool int); 17683int vec_any_ne (vector bool int, vector unsigned int); 17684int vec_any_ne (vector bool int, vector signed int); 17685int vec_any_ne (vector float, vector float); 17686 17687int vec_any_nge (vector float, vector float); 17688 17689int vec_any_ngt (vector float, vector float); 17690 17691int vec_any_nle (vector float, vector float); 17692 17693int vec_any_nlt (vector float, vector float); 17694 17695int vec_any_numeric (vector float); 17696 17697int vec_any_out (vector float, vector float); 17698 17699vector unsigned char vec_avg (vector unsigned char, vector unsigned char); 17700vector signed char vec_avg (vector signed char, vector signed char); 17701vector unsigned short vec_avg (vector unsigned short, vector unsigned short); 17702vector signed short vec_avg (vector signed short, vector signed short); 17703vector unsigned int vec_avg (vector unsigned int, vector unsigned int); 17704vector signed int vec_avg (vector signed int, vector signed int); 17705 17706vector float vec_ceil (vector float); 17707 17708vector signed int vec_cmpb (vector float, vector float); 17709 17710vector bool char vec_cmpeq (vector bool char, vector bool char); 17711vector bool short vec_cmpeq (vector bool short, vector bool short); 17712vector bool int vec_cmpeq (vector bool int, vector bool int); 17713vector bool char vec_cmpeq (vector signed char, vector signed char); 17714vector bool char vec_cmpeq (vector unsigned char, vector unsigned char); 17715vector bool short vec_cmpeq (vector signed short, vector signed short); 17716vector bool short vec_cmpeq (vector unsigned short, vector unsigned short); 17717vector bool int vec_cmpeq (vector signed int, vector signed int); 17718vector bool int vec_cmpeq (vector unsigned int, vector unsigned int); 17719vector bool int vec_cmpeq (vector float, vector float); 17720 17721vector bool int vec_cmpge (vector float, vector float); 17722 17723vector bool char vec_cmpgt (vector unsigned char, vector unsigned char); 17724vector bool char vec_cmpgt (vector signed char, vector signed char); 17725vector bool short vec_cmpgt (vector unsigned short, vector unsigned short); 17726vector bool short vec_cmpgt (vector signed short, vector signed short); 17727vector bool int vec_cmpgt (vector unsigned int, vector unsigned int); 17728vector bool int vec_cmpgt (vector signed int, vector signed int); 17729vector bool int vec_cmpgt (vector float, vector float); 17730 17731vector bool int vec_cmple (vector float, vector float); 17732 17733vector bool char vec_cmplt (vector unsigned char, vector unsigned char); 17734vector bool char vec_cmplt (vector signed char, vector signed char); 17735vector bool short vec_cmplt (vector unsigned short, vector unsigned short); 17736vector bool short vec_cmplt (vector signed short, vector signed short); 17737vector bool int vec_cmplt (vector unsigned int, vector unsigned int); 17738vector bool int vec_cmplt (vector signed int, vector signed int); 17739vector bool int vec_cmplt (vector float, vector float); 17740 17741vector float vec_cpsgn (vector float, vector float); 17742 17743vector float vec_ctf (vector unsigned int, const int); 17744vector float vec_ctf (vector signed int, const int); 17745 17746vector signed int vec_cts (vector float, const int); 17747 17748vector unsigned int vec_ctu (vector float, const int); 17749 17750void vec_dss (const int); 17751 17752void vec_dssall (void); 17753 17754void vec_dst (const vector unsigned char *, int, const int); 17755void vec_dst (const vector signed char *, int, const int); 17756void vec_dst (const vector bool char *, int, const int); 17757void vec_dst (const vector unsigned short *, int, const int); 17758void vec_dst (const vector signed short *, int, const int); 17759void vec_dst (const vector bool short *, int, const int); 17760void vec_dst (const vector pixel *, int, const int); 17761void vec_dst (const vector unsigned int *, int, const int); 17762void vec_dst (const vector signed int *, int, const int); 17763void vec_dst (const vector bool int *, int, const int); 17764void vec_dst (const vector float *, int, const int); 17765void vec_dst (const unsigned char *, int, const int); 17766void vec_dst (const signed char *, int, const int); 17767void vec_dst (const unsigned short *, int, const int); 17768void vec_dst (const short *, int, const int); 17769void vec_dst (const unsigned int *, int, const int); 17770void vec_dst (const int *, int, const int); 17771void vec_dst (const float *, int, const int); 17772 17773void vec_dstst (const vector unsigned char *, int, const int); 17774void vec_dstst (const vector signed char *, int, const int); 17775void vec_dstst (const vector bool char *, int, const int); 17776void vec_dstst (const vector unsigned short *, int, const int); 17777void vec_dstst (const vector signed short *, int, const int); 17778void vec_dstst (const vector bool short *, int, const int); 17779void vec_dstst (const vector pixel *, int, const int); 17780void vec_dstst (const vector unsigned int *, int, const int); 17781void vec_dstst (const vector signed int *, int, const int); 17782void vec_dstst (const vector bool int *, int, const int); 17783void vec_dstst (const vector float *, int, const int); 17784void vec_dstst (const unsigned char *, int, const int); 17785void vec_dstst (const signed char *, int, const int); 17786void vec_dstst (const unsigned short *, int, const int); 17787void vec_dstst (const short *, int, const int); 17788void vec_dstst (const unsigned int *, int, const int); 17789void vec_dstst (const int *, int, const int); 17790void vec_dstst (const unsigned long *, int, const int); 17791void vec_dstst (const long *, int, const int); 17792void vec_dstst (const float *, int, const int); 17793 17794void vec_dststt (const vector unsigned char *, int, const int); 17795void vec_dststt (const vector signed char *, int, const int); 17796void vec_dststt (const vector bool char *, int, const int); 17797void vec_dststt (const vector unsigned short *, int, const int); 17798void vec_dststt (const vector signed short *, int, const int); 17799void vec_dststt (const vector bool short *, int, const int); 17800void vec_dststt (const vector pixel *, int, const int); 17801void vec_dststt (const vector unsigned int *, int, const int); 17802void vec_dststt (const vector signed int *, int, const int); 17803void vec_dststt (const vector bool int *, int, const int); 17804void vec_dststt (const vector float *, int, const int); 17805void vec_dststt (const unsigned char *, int, const int); 17806void vec_dststt (const signed char *, int, const int); 17807void vec_dststt (const unsigned short *, int, const int); 17808void vec_dststt (const short *, int, const int); 17809void vec_dststt (const unsigned int *, int, const int); 17810void vec_dststt (const int *, int, const int); 17811void vec_dststt (const float *, int, const int); 17812 17813void vec_dstt (const vector unsigned char *, int, const int); 17814void vec_dstt (const vector signed char *, int, const int); 17815void vec_dstt (const vector bool char *, int, const int); 17816void vec_dstt (const vector unsigned short *, int, const int); 17817void vec_dstt (const vector signed short *, int, const int); 17818void vec_dstt (const vector bool short *, int, const int); 17819void vec_dstt (const vector pixel *, int, const int); 17820void vec_dstt (const vector unsigned int *, int, const int); 17821void vec_dstt (const vector signed int *, int, const int); 17822void vec_dstt (const vector bool int *, int, const int); 17823void vec_dstt (const vector float *, int, const int); 17824void vec_dstt (const unsigned char *, int, const int); 17825void vec_dstt (const signed char *, int, const int); 17826void vec_dstt (const unsigned short *, int, const int); 17827void vec_dstt (const short *, int, const int); 17828void vec_dstt (const unsigned int *, int, const int); 17829void vec_dstt (const int *, int, const int); 17830void vec_dstt (const float *, int, const int); 17831 17832vector float vec_expte (vector float); 17833 17834vector float vec_floor (vector float); 17835 17836vector float vec_ld (int, const vector float *); 17837vector float vec_ld (int, const float *); 17838vector bool int vec_ld (int, const vector bool int *); 17839vector signed int vec_ld (int, const vector signed int *); 17840vector signed int vec_ld (int, const int *); 17841vector unsigned int vec_ld (int, const vector unsigned int *); 17842vector unsigned int vec_ld (int, const unsigned int *); 17843vector bool short vec_ld (int, const vector bool short *); 17844vector pixel vec_ld (int, const vector pixel *); 17845vector signed short vec_ld (int, const vector signed short *); 17846vector signed short vec_ld (int, const short *); 17847vector unsigned short vec_ld (int, const vector unsigned short *); 17848vector unsigned short vec_ld (int, const unsigned short *); 17849vector bool char vec_ld (int, const vector bool char *); 17850vector signed char vec_ld (int, const vector signed char *); 17851vector signed char vec_ld (int, const signed char *); 17852vector unsigned char vec_ld (int, const vector unsigned char *); 17853vector unsigned char vec_ld (int, const unsigned char *); 17854 17855vector signed char vec_lde (int, const signed char *); 17856vector unsigned char vec_lde (int, const unsigned char *); 17857vector signed short vec_lde (int, const short *); 17858vector unsigned short vec_lde (int, const unsigned short *); 17859vector float vec_lde (int, const float *); 17860vector signed int vec_lde (int, const int *); 17861vector unsigned int vec_lde (int, const unsigned int *); 17862 17863vector float vec_ldl (int, const vector float *); 17864vector float vec_ldl (int, const float *); 17865vector bool int vec_ldl (int, const vector bool int *); 17866vector signed int vec_ldl (int, const vector signed int *); 17867vector signed int vec_ldl (int, const int *); 17868vector unsigned int vec_ldl (int, const vector unsigned int *); 17869vector unsigned int vec_ldl (int, const unsigned int *); 17870vector bool short vec_ldl (int, const vector bool short *); 17871vector pixel vec_ldl (int, const vector pixel *); 17872vector signed short vec_ldl (int, const vector signed short *); 17873vector signed short vec_ldl (int, const short *); 17874vector unsigned short vec_ldl (int, const vector unsigned short *); 17875vector unsigned short vec_ldl (int, const unsigned short *); 17876vector bool char vec_ldl (int, const vector bool char *); 17877vector signed char vec_ldl (int, const vector signed char *); 17878vector signed char vec_ldl (int, const signed char *); 17879vector unsigned char vec_ldl (int, const vector unsigned char *); 17880vector unsigned char vec_ldl (int, const unsigned char *); 17881 17882vector float vec_loge (vector float); 17883 17884vector signed char vec_lvebx (int, char *); 17885vector unsigned char vec_lvebx (int, unsigned char *); 17886 17887vector signed short vec_lvehx (int, short *); 17888vector unsigned short vec_lvehx (int, unsigned short *); 17889 17890vector float vec_lvewx (int, float *); 17891vector signed int vec_lvewx (int, int *); 17892vector unsigned int vec_lvewx (int, unsigned int *); 17893 17894vector unsigned char vec_lvsl (int, const unsigned char *); 17895vector unsigned char vec_lvsl (int, const signed char *); 17896vector unsigned char vec_lvsl (int, const unsigned short *); 17897vector unsigned char vec_lvsl (int, const short *); 17898vector unsigned char vec_lvsl (int, const unsigned int *); 17899vector unsigned char vec_lvsl (int, const int *); 17900vector unsigned char vec_lvsl (int, const float *); 17901 17902vector unsigned char vec_lvsr (int, const unsigned char *); 17903vector unsigned char vec_lvsr (int, const signed char *); 17904vector unsigned char vec_lvsr (int, const unsigned short *); 17905vector unsigned char vec_lvsr (int, const short *); 17906vector unsigned char vec_lvsr (int, const unsigned int *); 17907vector unsigned char vec_lvsr (int, const int *); 17908vector unsigned char vec_lvsr (int, const float *); 17909 17910vector float vec_madd (vector float, vector float, vector float); 17911 17912vector signed short vec_madds (vector signed short, vector signed short, 17913 vector signed short); 17914 17915vector unsigned char vec_max (vector bool char, vector unsigned char); 17916vector unsigned char vec_max (vector unsigned char, vector bool char); 17917vector unsigned char vec_max (vector unsigned char, vector unsigned char); 17918vector signed char vec_max (vector bool char, vector signed char); 17919vector signed char vec_max (vector signed char, vector bool char); 17920vector signed char vec_max (vector signed char, vector signed char); 17921vector unsigned short vec_max (vector bool short, vector unsigned short); 17922vector unsigned short vec_max (vector unsigned short, vector bool short); 17923vector unsigned short vec_max (vector unsigned short, vector unsigned short); 17924vector signed short vec_max (vector bool short, vector signed short); 17925vector signed short vec_max (vector signed short, vector bool short); 17926vector signed short vec_max (vector signed short, vector signed short); 17927vector unsigned int vec_max (vector bool int, vector unsigned int); 17928vector unsigned int vec_max (vector unsigned int, vector bool int); 17929vector unsigned int vec_max (vector unsigned int, vector unsigned int); 17930vector signed int vec_max (vector bool int, vector signed int); 17931vector signed int vec_max (vector signed int, vector bool int); 17932vector signed int vec_max (vector signed int, vector signed int); 17933vector float vec_max (vector float, vector float); 17934 17935vector bool char vec_mergeh (vector bool char, vector bool char); 17936vector signed char vec_mergeh (vector signed char, vector signed char); 17937vector unsigned char vec_mergeh (vector unsigned char, vector unsigned char); 17938vector bool short vec_mergeh (vector bool short, vector bool short); 17939vector pixel vec_mergeh (vector pixel, vector pixel); 17940vector signed short vec_mergeh (vector signed short, vector signed short); 17941vector unsigned short vec_mergeh (vector unsigned short, vector unsigned short); 17942vector float vec_mergeh (vector float, vector float); 17943vector bool int vec_mergeh (vector bool int, vector bool int); 17944vector signed int vec_mergeh (vector signed int, vector signed int); 17945vector unsigned int vec_mergeh (vector unsigned int, vector unsigned int); 17946 17947vector bool char vec_mergel (vector bool char, vector bool char); 17948vector signed char vec_mergel (vector signed char, vector signed char); 17949vector unsigned char vec_mergel (vector unsigned char, vector unsigned char); 17950vector bool short vec_mergel (vector bool short, vector bool short); 17951vector pixel vec_mergel (vector pixel, vector pixel); 17952vector signed short vec_mergel (vector signed short, vector signed short); 17953vector unsigned short vec_mergel (vector unsigned short, vector unsigned short); 17954vector float vec_mergel (vector float, vector float); 17955vector bool int vec_mergel (vector bool int, vector bool int); 17956vector signed int vec_mergel (vector signed int, vector signed int); 17957vector unsigned int vec_mergel (vector unsigned int, vector unsigned int); 17958 17959vector unsigned short vec_mfvscr (void); 17960 17961vector unsigned char vec_min (vector bool char, vector unsigned char); 17962vector unsigned char vec_min (vector unsigned char, vector bool char); 17963vector unsigned char vec_min (vector unsigned char, vector unsigned char); 17964vector signed char vec_min (vector bool char, vector signed char); 17965vector signed char vec_min (vector signed char, vector bool char); 17966vector signed char vec_min (vector signed char, vector signed char); 17967vector unsigned short vec_min (vector bool short, vector unsigned short); 17968vector unsigned short vec_min (vector unsigned short, vector bool short); 17969vector unsigned short vec_min (vector unsigned short, vector unsigned short); 17970vector signed short vec_min (vector bool short, vector signed short); 17971vector signed short vec_min (vector signed short, vector bool short); 17972vector signed short vec_min (vector signed short, vector signed short); 17973vector unsigned int vec_min (vector bool int, vector unsigned int); 17974vector unsigned int vec_min (vector unsigned int, vector bool int); 17975vector unsigned int vec_min (vector unsigned int, vector unsigned int); 17976vector signed int vec_min (vector bool int, vector signed int); 17977vector signed int vec_min (vector signed int, vector bool int); 17978vector signed int vec_min (vector signed int, vector signed int); 17979vector float vec_min (vector float, vector float); 17980 17981vector signed short vec_mladd (vector signed short, vector signed short, 17982 vector signed short); 17983vector signed short vec_mladd (vector signed short, vector unsigned short, 17984 vector unsigned short); 17985vector signed short vec_mladd (vector unsigned short, vector signed short, 17986 vector signed short); 17987vector unsigned short vec_mladd (vector unsigned short, vector unsigned short, 17988 vector unsigned short); 17989 17990vector signed short vec_mradds (vector signed short, vector signed short, 17991 vector signed short); 17992 17993vector unsigned int vec_msum (vector unsigned char, vector unsigned char, 17994 vector unsigned int); 17995vector signed int vec_msum (vector signed char, vector unsigned char, 17996 vector signed int); 17997vector unsigned int vec_msum (vector unsigned short, vector unsigned short, 17998 vector unsigned int); 17999vector signed int vec_msum (vector signed short, vector signed short, 18000 vector signed int); 18001 18002vector unsigned int vec_msums (vector unsigned short, vector unsigned short, 18003 vector unsigned int); 18004vector signed int vec_msums (vector signed short, vector signed short, 18005 vector signed int); 18006 18007void vec_mtvscr (vector signed int); 18008void vec_mtvscr (vector unsigned int); 18009void vec_mtvscr (vector bool int); 18010void vec_mtvscr (vector signed short); 18011void vec_mtvscr (vector unsigned short); 18012void vec_mtvscr (vector bool short); 18013void vec_mtvscr (vector pixel); 18014void vec_mtvscr (vector signed char); 18015void vec_mtvscr (vector unsigned char); 18016void vec_mtvscr (vector bool char); 18017 18018vector float vec_mul (vector float, vector float); 18019 18020vector unsigned short vec_mule (vector unsigned char, vector unsigned char); 18021vector signed short vec_mule (vector signed char, vector signed char); 18022vector unsigned int vec_mule (vector unsigned short, vector unsigned short); 18023vector signed int vec_mule (vector signed short, vector signed short); 18024 18025vector unsigned short vec_mulo (vector unsigned char, vector unsigned char); 18026vector signed short vec_mulo (vector signed char, vector signed char); 18027vector unsigned int vec_mulo (vector unsigned short, vector unsigned short); 18028vector signed int vec_mulo (vector signed short, vector signed short); 18029 18030vector signed char vec_nabs (vector signed char); 18031vector signed short vec_nabs (vector signed short); 18032vector signed int vec_nabs (vector signed int); 18033vector float vec_nabs (vector float); 18034 18035vector float vec_nmsub (vector float, vector float, vector float); 18036 18037vector float vec_nor (vector float, vector float); 18038vector signed int vec_nor (vector signed int, vector signed int); 18039vector unsigned int vec_nor (vector unsigned int, vector unsigned int); 18040vector bool int vec_nor (vector bool int, vector bool int); 18041vector signed short vec_nor (vector signed short, vector signed short); 18042vector unsigned short vec_nor (vector unsigned short, vector unsigned short); 18043vector bool short vec_nor (vector bool short, vector bool short); 18044vector signed char vec_nor (vector signed char, vector signed char); 18045vector unsigned char vec_nor (vector unsigned char, vector unsigned char); 18046vector bool char vec_nor (vector bool char, vector bool char); 18047 18048vector float vec_or (vector float, vector float); 18049vector float vec_or (vector float, vector bool int); 18050vector float vec_or (vector bool int, vector float); 18051vector bool int vec_or (vector bool int, vector bool int); 18052vector signed int vec_or (vector bool int, vector signed int); 18053vector signed int vec_or (vector signed int, vector bool int); 18054vector signed int vec_or (vector signed int, vector signed int); 18055vector unsigned int vec_or (vector bool int, vector unsigned int); 18056vector unsigned int vec_or (vector unsigned int, vector bool int); 18057vector unsigned int vec_or (vector unsigned int, vector unsigned int); 18058vector bool short vec_or (vector bool short, vector bool short); 18059vector signed short vec_or (vector bool short, vector signed short); 18060vector signed short vec_or (vector signed short, vector bool short); 18061vector signed short vec_or (vector signed short, vector signed short); 18062vector unsigned short vec_or (vector bool short, vector unsigned short); 18063vector unsigned short vec_or (vector unsigned short, vector bool short); 18064vector unsigned short vec_or (vector unsigned short, vector unsigned short); 18065vector signed char vec_or (vector bool char, vector signed char); 18066vector bool char vec_or (vector bool char, vector bool char); 18067vector signed char vec_or (vector signed char, vector bool char); 18068vector signed char vec_or (vector signed char, vector signed char); 18069vector unsigned char vec_or (vector bool char, vector unsigned char); 18070vector unsigned char vec_or (vector unsigned char, vector bool char); 18071vector unsigned char vec_or (vector unsigned char, vector unsigned char); 18072 18073vector signed char vec_pack (vector signed short, vector signed short); 18074vector unsigned char vec_pack (vector unsigned short, vector unsigned short); 18075vector bool char vec_pack (vector bool short, vector bool short); 18076vector signed short vec_pack (vector signed int, vector signed int); 18077vector unsigned short vec_pack (vector unsigned int, vector unsigned int); 18078vector bool short vec_pack (vector bool int, vector bool int); 18079 18080vector pixel vec_packpx (vector unsigned int, vector unsigned int); 18081 18082vector unsigned char vec_packs (vector unsigned short, vector unsigned short); 18083vector signed char vec_packs (vector signed short, vector signed short); 18084vector unsigned short vec_packs (vector unsigned int, vector unsigned int); 18085vector signed short vec_packs (vector signed int, vector signed int); 18086 18087vector unsigned char vec_packsu (vector unsigned short, vector unsigned short); 18088vector unsigned char vec_packsu (vector signed short, vector signed short); 18089vector unsigned short vec_packsu (vector unsigned int, vector unsigned int); 18090vector unsigned short vec_packsu (vector signed int, vector signed int); 18091 18092vector float vec_perm (vector float, vector float, vector unsigned char); 18093vector signed int vec_perm (vector signed int, vector signed int, vector unsigned char); 18094vector unsigned int vec_perm (vector unsigned int, vector unsigned int, 18095 vector unsigned char); 18096vector bool int vec_perm (vector bool int, vector bool int, vector unsigned char); 18097vector signed short vec_perm (vector signed short, vector signed short, 18098 vector unsigned char); 18099vector unsigned short vec_perm (vector unsigned short, vector unsigned short, 18100 vector unsigned char); 18101vector bool short vec_perm (vector bool short, vector bool short, vector unsigned char); 18102vector pixel vec_perm (vector pixel, vector pixel, vector unsigned char); 18103vector signed char vec_perm (vector signed char, vector signed char, 18104 vector unsigned char); 18105vector unsigned char vec_perm (vector unsigned char, vector unsigned char, 18106 vector unsigned char); 18107vector bool char vec_perm (vector bool char, vector bool char, vector unsigned char); 18108 18109vector float vec_re (vector float); 18110 18111vector bool char vec_reve (vector bool char); 18112vector signed char vec_reve (vector signed char); 18113vector unsigned char vec_reve (vector unsigned char); 18114vector bool int vec_reve (vector bool int); 18115vector signed int vec_reve (vector signed int); 18116vector unsigned int vec_reve (vector unsigned int); 18117vector bool short vec_reve (vector bool short); 18118vector signed short vec_reve (vector signed short); 18119vector unsigned short vec_reve (vector unsigned short); 18120 18121vector signed char vec_rl (vector signed char, vector unsigned char); 18122vector unsigned char vec_rl (vector unsigned char, vector unsigned char); 18123vector signed short vec_rl (vector signed short, vector unsigned short); 18124vector unsigned short vec_rl (vector unsigned short, vector unsigned short); 18125vector signed int vec_rl (vector signed int, vector unsigned int); 18126vector unsigned int vec_rl (vector unsigned int, vector unsigned int); 18127 18128vector float vec_round (vector float); 18129 18130vector float vec_rsqrt (vector float); 18131 18132vector float vec_rsqrte (vector float); 18133 18134vector float vec_sel (vector float, vector float, vector bool int); 18135vector float vec_sel (vector float, vector float, vector unsigned int); 18136vector signed int vec_sel (vector signed int, vector signed int, vector bool int); 18137vector signed int vec_sel (vector signed int, vector signed int, vector unsigned int); 18138vector unsigned int vec_sel (vector unsigned int, vector unsigned int, vector bool int); 18139vector unsigned int vec_sel (vector unsigned int, vector unsigned int, 18140 vector unsigned int); 18141vector bool int vec_sel (vector bool int, vector bool int, vector bool int); 18142vector bool int vec_sel (vector bool int, vector bool int, vector unsigned int); 18143vector signed short vec_sel (vector signed short, vector signed short, 18144 vector bool short); 18145vector signed short vec_sel (vector signed short, vector signed short, 18146 vector unsigned short); 18147vector unsigned short vec_sel (vector unsigned short, vector unsigned short, 18148 vector bool short); 18149vector unsigned short vec_sel (vector unsigned short, vector unsigned short, 18150 vector unsigned short); 18151vector bool short vec_sel (vector bool short, vector bool short, vector bool short); 18152vector bool short vec_sel (vector bool short, vector bool short, vector unsigned short); 18153vector signed char vec_sel (vector signed char, vector signed char, vector bool char); 18154vector signed char vec_sel (vector signed char, vector signed char, 18155 vector unsigned char); 18156vector unsigned char vec_sel (vector unsigned char, vector unsigned char, 18157 vector bool char); 18158vector unsigned char vec_sel (vector unsigned char, vector unsigned char, 18159 vector unsigned char); 18160vector bool char vec_sel (vector bool char, vector bool char, vector bool char); 18161vector bool char vec_sel (vector bool char, vector bool char, vector unsigned char); 18162 18163vector signed char vec_sl (vector signed char, vector unsigned char); 18164vector unsigned char vec_sl (vector unsigned char, vector unsigned char); 18165vector signed short vec_sl (vector signed short, vector unsigned short); 18166vector unsigned short vec_sl (vector unsigned short, vector unsigned short); 18167vector signed int vec_sl (vector signed int, vector unsigned int); 18168vector unsigned int vec_sl (vector unsigned int, vector unsigned int); 18169 18170vector float vec_sld (vector float, vector float, const int); 18171vector signed int vec_sld (vector signed int, vector signed int, const int); 18172vector unsigned int vec_sld (vector unsigned int, vector unsigned int, const int); 18173vector bool int vec_sld (vector bool int, vector bool int, const int); 18174vector signed short vec_sld (vector signed short, vector signed short, const int); 18175vector unsigned short vec_sld (vector unsigned short, vector unsigned short, const int); 18176vector bool short vec_sld (vector bool short, vector bool short, const int); 18177vector pixel vec_sld (vector pixel, vector pixel, const int); 18178vector signed char vec_sld (vector signed char, vector signed char, const int); 18179vector unsigned char vec_sld (vector unsigned char, vector unsigned char, const int); 18180vector bool char vec_sld (vector bool char, vector bool char, const int); 18181 18182vector signed int vec_sll (vector signed int, vector unsigned int); 18183vector signed int vec_sll (vector signed int, vector unsigned short); 18184vector signed int vec_sll (vector signed int, vector unsigned char); 18185vector unsigned int vec_sll (vector unsigned int, vector unsigned int); 18186vector unsigned int vec_sll (vector unsigned int, vector unsigned short); 18187vector unsigned int vec_sll (vector unsigned int, vector unsigned char); 18188vector bool int vec_sll (vector bool int, vector unsigned int); 18189vector bool int vec_sll (vector bool int, vector unsigned short); 18190vector bool int vec_sll (vector bool int, vector unsigned char); 18191vector signed short vec_sll (vector signed short, vector unsigned int); 18192vector signed short vec_sll (vector signed short, vector unsigned short); 18193vector signed short vec_sll (vector signed short, vector unsigned char); 18194vector unsigned short vec_sll (vector unsigned short, vector unsigned int); 18195vector unsigned short vec_sll (vector unsigned short, vector unsigned short); 18196vector unsigned short vec_sll (vector unsigned short, vector unsigned char); 18197vector bool short vec_sll (vector bool short, vector unsigned int); 18198vector bool short vec_sll (vector bool short, vector unsigned short); 18199vector bool short vec_sll (vector bool short, vector unsigned char); 18200vector pixel vec_sll (vector pixel, vector unsigned int); 18201vector pixel vec_sll (vector pixel, vector unsigned short); 18202vector pixel vec_sll (vector pixel, vector unsigned char); 18203vector signed char vec_sll (vector signed char, vector unsigned int); 18204vector signed char vec_sll (vector signed char, vector unsigned short); 18205vector signed char vec_sll (vector signed char, vector unsigned char); 18206vector unsigned char vec_sll (vector unsigned char, vector unsigned int); 18207vector unsigned char vec_sll (vector unsigned char, vector unsigned short); 18208vector unsigned char vec_sll (vector unsigned char, vector unsigned char); 18209vector bool char vec_sll (vector bool char, vector unsigned int); 18210vector bool char vec_sll (vector bool char, vector unsigned short); 18211vector bool char vec_sll (vector bool char, vector unsigned char); 18212 18213vector float vec_slo (vector float, vector signed char); 18214vector float vec_slo (vector float, vector unsigned char); 18215vector signed int vec_slo (vector signed int, vector signed char); 18216vector signed int vec_slo (vector signed int, vector unsigned char); 18217vector unsigned int vec_slo (vector unsigned int, vector signed char); 18218vector unsigned int vec_slo (vector unsigned int, vector unsigned char); 18219vector signed short vec_slo (vector signed short, vector signed char); 18220vector signed short vec_slo (vector signed short, vector unsigned char); 18221vector unsigned short vec_slo (vector unsigned short, vector signed char); 18222vector unsigned short vec_slo (vector unsigned short, vector unsigned char); 18223vector pixel vec_slo (vector pixel, vector signed char); 18224vector pixel vec_slo (vector pixel, vector unsigned char); 18225vector signed char vec_slo (vector signed char, vector signed char); 18226vector signed char vec_slo (vector signed char, vector unsigned char); 18227vector unsigned char vec_slo (vector unsigned char, vector signed char); 18228vector unsigned char vec_slo (vector unsigned char, vector unsigned char); 18229 18230vector signed char vec_splat (vector signed char, const int); 18231vector unsigned char vec_splat (vector unsigned char, const int); 18232vector bool char vec_splat (vector bool char, const int); 18233vector signed short vec_splat (vector signed short, const int); 18234vector unsigned short vec_splat (vector unsigned short, const int); 18235vector bool short vec_splat (vector bool short, const int); 18236vector pixel vec_splat (vector pixel, const int); 18237vector float vec_splat (vector float, const int); 18238vector signed int vec_splat (vector signed int, const int); 18239vector unsigned int vec_splat (vector unsigned int, const int); 18240vector bool int vec_splat (vector bool int, const int); 18241 18242vector signed short vec_splat_s16 (const int); 18243 18244vector signed int vec_splat_s32 (const int); 18245 18246vector signed char vec_splat_s8 (const int); 18247 18248vector unsigned short vec_splat_u16 (const int); 18249 18250vector unsigned int vec_splat_u32 (const int); 18251 18252vector unsigned char vec_splat_u8 (const int); 18253 18254vector signed char vec_splats (signed char); 18255vector unsigned char vec_splats (unsigned char); 18256vector signed short vec_splats (signed short); 18257vector unsigned short vec_splats (unsigned short); 18258vector signed int vec_splats (signed int); 18259vector unsigned int vec_splats (unsigned int); 18260vector float vec_splats (float); 18261 18262vector signed char vec_sr (vector signed char, vector unsigned char); 18263vector unsigned char vec_sr (vector unsigned char, vector unsigned char); 18264vector signed short vec_sr (vector signed short, vector unsigned short); 18265vector unsigned short vec_sr (vector unsigned short, vector unsigned short); 18266vector signed int vec_sr (vector signed int, vector unsigned int); 18267vector unsigned int vec_sr (vector unsigned int, vector unsigned int); 18268 18269vector signed char vec_sra (vector signed char, vector unsigned char); 18270vector unsigned char vec_sra (vector unsigned char, vector unsigned char); 18271vector signed short vec_sra (vector signed short, vector unsigned short); 18272vector unsigned short vec_sra (vector unsigned short, vector unsigned short); 18273vector signed int vec_sra (vector signed int, vector unsigned int); 18274vector unsigned int vec_sra (vector unsigned int, vector unsigned int); 18275 18276vector signed int vec_srl (vector signed int, vector unsigned int); 18277vector signed int vec_srl (vector signed int, vector unsigned short); 18278vector signed int vec_srl (vector signed int, vector unsigned char); 18279vector unsigned int vec_srl (vector unsigned int, vector unsigned int); 18280vector unsigned int vec_srl (vector unsigned int, vector unsigned short); 18281vector unsigned int vec_srl (vector unsigned int, vector unsigned char); 18282vector bool int vec_srl (vector bool int, vector unsigned int); 18283vector bool int vec_srl (vector bool int, vector unsigned short); 18284vector bool int vec_srl (vector bool int, vector unsigned char); 18285vector signed short vec_srl (vector signed short, vector unsigned int); 18286vector signed short vec_srl (vector signed short, vector unsigned short); 18287vector signed short vec_srl (vector signed short, vector unsigned char); 18288vector unsigned short vec_srl (vector unsigned short, vector unsigned int); 18289vector unsigned short vec_srl (vector unsigned short, vector unsigned short); 18290vector unsigned short vec_srl (vector unsigned short, vector unsigned char); 18291vector bool short vec_srl (vector bool short, vector unsigned int); 18292vector bool short vec_srl (vector bool short, vector unsigned short); 18293vector bool short vec_srl (vector bool short, vector unsigned char); 18294vector pixel vec_srl (vector pixel, vector unsigned int); 18295vector pixel vec_srl (vector pixel, vector unsigned short); 18296vector pixel vec_srl (vector pixel, vector unsigned char); 18297vector signed char vec_srl (vector signed char, vector unsigned int); 18298vector signed char vec_srl (vector signed char, vector unsigned short); 18299vector signed char vec_srl (vector signed char, vector unsigned char); 18300vector unsigned char vec_srl (vector unsigned char, vector unsigned int); 18301vector unsigned char vec_srl (vector unsigned char, vector unsigned short); 18302vector unsigned char vec_srl (vector unsigned char, vector unsigned char); 18303vector bool char vec_srl (vector bool char, vector unsigned int); 18304vector bool char vec_srl (vector bool char, vector unsigned short); 18305vector bool char vec_srl (vector bool char, vector unsigned char); 18306 18307vector float vec_sro (vector float, vector signed char); 18308vector float vec_sro (vector float, vector unsigned char); 18309vector signed int vec_sro (vector signed int, vector signed char); 18310vector signed int vec_sro (vector signed int, vector unsigned char); 18311vector unsigned int vec_sro (vector unsigned int, vector signed char); 18312vector unsigned int vec_sro (vector unsigned int, vector unsigned char); 18313vector signed short vec_sro (vector signed short, vector signed char); 18314vector signed short vec_sro (vector signed short, vector unsigned char); 18315vector unsigned short vec_sro (vector unsigned short, vector signed char); 18316vector unsigned short vec_sro (vector unsigned short, vector unsigned char); 18317vector pixel vec_sro (vector pixel, vector signed char); 18318vector pixel vec_sro (vector pixel, vector unsigned char); 18319vector signed char vec_sro (vector signed char, vector signed char); 18320vector signed char vec_sro (vector signed char, vector unsigned char); 18321vector unsigned char vec_sro (vector unsigned char, vector signed char); 18322vector unsigned char vec_sro (vector unsigned char, vector unsigned char); 18323 18324void vec_st (vector float, int, vector float *); 18325void vec_st (vector float, int, float *); 18326void vec_st (vector signed int, int, vector signed int *); 18327void vec_st (vector signed int, int, int *); 18328void vec_st (vector unsigned int, int, vector unsigned int *); 18329void vec_st (vector unsigned int, int, unsigned int *); 18330void vec_st (vector bool int, int, vector bool int *); 18331void vec_st (vector bool int, int, unsigned int *); 18332void vec_st (vector bool int, int, int *); 18333void vec_st (vector signed short, int, vector signed short *); 18334void vec_st (vector signed short, int, short *); 18335void vec_st (vector unsigned short, int, vector unsigned short *); 18336void vec_st (vector unsigned short, int, unsigned short *); 18337void vec_st (vector bool short, int, vector bool short *); 18338void vec_st (vector bool short, int, unsigned short *); 18339void vec_st (vector pixel, int, vector pixel *); 18340void vec_st (vector bool short, int, short *); 18341void vec_st (vector signed char, int, vector signed char *); 18342void vec_st (vector signed char, int, signed char *); 18343void vec_st (vector unsigned char, int, vector unsigned char *); 18344void vec_st (vector unsigned char, int, unsigned char *); 18345void vec_st (vector bool char, int, vector bool char *); 18346void vec_st (vector bool char, int, unsigned char *); 18347void vec_st (vector bool char, int, signed char *); 18348 18349void vec_ste (vector signed char, int, signed char *); 18350void vec_ste (vector unsigned char, int, unsigned char *); 18351void vec_ste (vector bool char, int, signed char *); 18352void vec_ste (vector bool char, int, unsigned char *); 18353void vec_ste (vector signed short, int, short *); 18354void vec_ste (vector unsigned short, int, unsigned short *); 18355void vec_ste (vector bool short, int, short *); 18356void vec_ste (vector bool short, int, unsigned short *); 18357void vec_ste (vector pixel, int, short *); 18358void vec_ste (vector pixel, int, unsigned short *); 18359void vec_ste (vector float, int, float *); 18360void vec_ste (vector signed int, int, int *); 18361void vec_ste (vector unsigned int, int, unsigned int *); 18362void vec_ste (vector bool int, int, int *); 18363void vec_ste (vector bool int, int, unsigned int *); 18364 18365void vec_stl (vector float, int, vector float *); 18366void vec_stl (vector float, int, float *); 18367void vec_stl (vector signed int, int, vector signed int *); 18368void vec_stl (vector signed int, int, int *); 18369void vec_stl (vector unsigned int, int, vector unsigned int *); 18370void vec_stl (vector unsigned int, int, unsigned int *); 18371void vec_stl (vector bool int, int, vector bool int *); 18372void vec_stl (vector bool int, int, unsigned int *); 18373void vec_stl (vector bool int, int, int *); 18374void vec_stl (vector signed short, int, vector signed short *); 18375void vec_stl (vector signed short, int, short *); 18376void vec_stl (vector unsigned short, int, vector unsigned short *); 18377void vec_stl (vector unsigned short, int, unsigned short *); 18378void vec_stl (vector bool short, int, vector bool short *); 18379void vec_stl (vector bool short, int, unsigned short *); 18380void vec_stl (vector bool short, int, short *); 18381void vec_stl (vector pixel, int, vector pixel *); 18382void vec_stl (vector signed char, int, vector signed char *); 18383void vec_stl (vector signed char, int, signed char *); 18384void vec_stl (vector unsigned char, int, vector unsigned char *); 18385void vec_stl (vector unsigned char, int, unsigned char *); 18386void vec_stl (vector bool char, int, vector bool char *); 18387void vec_stl (vector bool char, int, unsigned char *); 18388void vec_stl (vector bool char, int, signed char *); 18389 18390void vec_stvebx (vector signed char, int, signed char *); 18391void vec_stvebx (vector unsigned char, int, unsigned char *); 18392void vec_stvebx (vector bool char, int, signed char *); 18393void vec_stvebx (vector bool char, int, unsigned char *); 18394 18395void vec_stvehx (vector signed short, int, short *); 18396void vec_stvehx (vector unsigned short, int, unsigned short *); 18397void vec_stvehx (vector bool short, int, short *); 18398void vec_stvehx (vector bool short, int, unsigned short *); 18399 18400void vec_stvewx (vector float, int, float *); 18401void vec_stvewx (vector signed int, int, int *); 18402void vec_stvewx (vector unsigned int, int, unsigned int *); 18403void vec_stvewx (vector bool int, int, int *); 18404void vec_stvewx (vector bool int, int, unsigned int *); 18405 18406vector signed char vec_sub (vector bool char, vector signed char); 18407vector signed char vec_sub (vector signed char, vector bool char); 18408vector signed char vec_sub (vector signed char, vector signed char); 18409vector unsigned char vec_sub (vector bool char, vector unsigned char); 18410vector unsigned char vec_sub (vector unsigned char, vector bool char); 18411vector unsigned char vec_sub (vector unsigned char, vector unsigned char); 18412vector signed short vec_sub (vector bool short, vector signed short); 18413vector signed short vec_sub (vector signed short, vector bool short); 18414vector signed short vec_sub (vector signed short, vector signed short); 18415vector unsigned short vec_sub (vector bool short, vector unsigned short); 18416vector unsigned short vec_sub (vector unsigned short, vector bool short); 18417vector unsigned short vec_sub (vector unsigned short, vector unsigned short); 18418vector signed int vec_sub (vector bool int, vector signed int); 18419vector signed int vec_sub (vector signed int, vector bool int); 18420vector signed int vec_sub (vector signed int, vector signed int); 18421vector unsigned int vec_sub (vector bool int, vector unsigned int); 18422vector unsigned int vec_sub (vector unsigned int, vector bool int); 18423vector unsigned int vec_sub (vector unsigned int, vector unsigned int); 18424vector float vec_sub (vector float, vector float); 18425 18426vector signed int vec_subc (vector signed int, vector signed int); 18427vector unsigned int vec_subc (vector unsigned int, vector unsigned int); 18428 18429vector signed int vec_sube (vector signed int, vector signed int, 18430 vector signed int); 18431vector unsigned int vec_sube (vector unsigned int, vector unsigned int, 18432 vector unsigned int); 18433 18434vector signed int vec_subec (vector signed int, vector signed int, 18435 vector signed int); 18436vector unsigned int vec_subec (vector unsigned int, vector unsigned int, 18437 vector unsigned int); 18438 18439vector unsigned char vec_subs (vector bool char, vector unsigned char); 18440vector unsigned char vec_subs (vector unsigned char, vector bool char); 18441vector unsigned char vec_subs (vector unsigned char, vector unsigned char); 18442vector signed char vec_subs (vector bool char, vector signed char); 18443vector signed char vec_subs (vector signed char, vector bool char); 18444vector signed char vec_subs (vector signed char, vector signed char); 18445vector unsigned short vec_subs (vector bool short, vector unsigned short); 18446vector unsigned short vec_subs (vector unsigned short, vector bool short); 18447vector unsigned short vec_subs (vector unsigned short, vector unsigned short); 18448vector signed short vec_subs (vector bool short, vector signed short); 18449vector signed short vec_subs (vector signed short, vector bool short); 18450vector signed short vec_subs (vector signed short, vector signed short); 18451vector unsigned int vec_subs (vector bool int, vector unsigned int); 18452vector unsigned int vec_subs (vector unsigned int, vector bool int); 18453vector unsigned int vec_subs (vector unsigned int, vector unsigned int); 18454vector signed int vec_subs (vector bool int, vector signed int); 18455vector signed int vec_subs (vector signed int, vector bool int); 18456vector signed int vec_subs (vector signed int, vector signed int); 18457 18458vector signed int vec_sum2s (vector signed int, vector signed int); 18459 18460vector unsigned int vec_sum4s (vector unsigned char, vector unsigned int); 18461vector signed int vec_sum4s (vector signed char, vector signed int); 18462vector signed int vec_sum4s (vector signed short, vector signed int); 18463 18464vector signed int vec_sums (vector signed int, vector signed int); 18465 18466vector float vec_trunc (vector float); 18467 18468vector signed short vec_unpackh (vector signed char); 18469vector bool short vec_unpackh (vector bool char); 18470vector signed int vec_unpackh (vector signed short); 18471vector bool int vec_unpackh (vector bool short); 18472vector unsigned int vec_unpackh (vector pixel); 18473 18474vector signed short vec_unpackl (vector signed char); 18475vector bool short vec_unpackl (vector bool char); 18476vector unsigned int vec_unpackl (vector pixel); 18477vector signed int vec_unpackl (vector signed short); 18478vector bool int vec_unpackl (vector bool short); 18479 18480vector float vec_vaddfp (vector float, vector float); 18481 18482vector signed char vec_vaddsbs (vector bool char, vector signed char); 18483vector signed char vec_vaddsbs (vector signed char, vector bool char); 18484vector signed char vec_vaddsbs (vector signed char, vector signed char); 18485 18486vector signed short vec_vaddshs (vector bool short, vector signed short); 18487vector signed short vec_vaddshs (vector signed short, vector bool short); 18488vector signed short vec_vaddshs (vector signed short, vector signed short); 18489 18490vector signed int vec_vaddsws (vector bool int, vector signed int); 18491vector signed int vec_vaddsws (vector signed int, vector bool int); 18492vector signed int vec_vaddsws (vector signed int, vector signed int); 18493 18494vector signed char vec_vaddubm (vector bool char, vector signed char); 18495vector signed char vec_vaddubm (vector signed char, vector bool char); 18496vector signed char vec_vaddubm (vector signed char, vector signed char); 18497vector unsigned char vec_vaddubm (vector bool char, vector unsigned char); 18498vector unsigned char vec_vaddubm (vector unsigned char, vector bool char); 18499vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char); 18500 18501vector unsigned char vec_vaddubs (vector bool char, vector unsigned char); 18502vector unsigned char vec_vaddubs (vector unsigned char, vector bool char); 18503vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char); 18504 18505vector signed short vec_vadduhm (vector bool short, vector signed short); 18506vector signed short vec_vadduhm (vector signed short, vector bool short); 18507vector signed short vec_vadduhm (vector signed short, vector signed short); 18508vector unsigned short vec_vadduhm (vector bool short, vector unsigned short); 18509vector unsigned short vec_vadduhm (vector unsigned short, vector bool short); 18510vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short); 18511 18512vector unsigned short vec_vadduhs (vector bool short, vector unsigned short); 18513vector unsigned short vec_vadduhs (vector unsigned short, vector bool short); 18514vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short); 18515 18516vector signed int vec_vadduwm (vector bool int, vector signed int); 18517vector signed int vec_vadduwm (vector signed int, vector bool int); 18518vector signed int vec_vadduwm (vector signed int, vector signed int); 18519vector unsigned int vec_vadduwm (vector bool int, vector unsigned int); 18520vector unsigned int vec_vadduwm (vector unsigned int, vector bool int); 18521vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int); 18522 18523vector unsigned int vec_vadduws (vector bool int, vector unsigned int); 18524vector unsigned int vec_vadduws (vector unsigned int, vector bool int); 18525vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int); 18526 18527vector signed char vec_vavgsb (vector signed char, vector signed char); 18528 18529vector signed short vec_vavgsh (vector signed short, vector signed short); 18530 18531vector signed int vec_vavgsw (vector signed int, vector signed int); 18532 18533vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char); 18534 18535vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short); 18536 18537vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int); 18538 18539vector float vec_vcfsx (vector signed int, const int); 18540 18541vector float vec_vcfux (vector unsigned int, const int); 18542 18543vector bool int vec_vcmpeqfp (vector float, vector float); 18544 18545vector bool char vec_vcmpequb (vector signed char, vector signed char); 18546vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char); 18547 18548vector bool short vec_vcmpequh (vector signed short, vector signed short); 18549vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short); 18550 18551vector bool int vec_vcmpequw (vector signed int, vector signed int); 18552vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); 18553 18554vector bool int vec_vcmpgtfp (vector float, vector float); 18555 18556vector bool char vec_vcmpgtsb (vector signed char, vector signed char); 18557 18558vector bool short vec_vcmpgtsh (vector signed short, vector signed short); 18559 18560vector bool int vec_vcmpgtsw (vector signed int, vector signed int); 18561 18562vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char); 18563 18564vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short); 18565 18566vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); 18567 18568vector float vec_vmaxfp (vector float, vector float); 18569 18570vector signed char vec_vmaxsb (vector bool char, vector signed char); 18571vector signed char vec_vmaxsb (vector signed char, vector bool char); 18572vector signed char vec_vmaxsb (vector signed char, vector signed char); 18573 18574vector signed short vec_vmaxsh (vector bool short, vector signed short); 18575vector signed short vec_vmaxsh (vector signed short, vector bool short); 18576vector signed short vec_vmaxsh (vector signed short, vector signed short); 18577 18578vector signed int vec_vmaxsw (vector bool int, vector signed int); 18579vector signed int vec_vmaxsw (vector signed int, vector bool int); 18580vector signed int vec_vmaxsw (vector signed int, vector signed int); 18581 18582vector unsigned char vec_vmaxub (vector bool char, vector unsigned char); 18583vector unsigned char vec_vmaxub (vector unsigned char, vector bool char); 18584vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char); 18585 18586vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short); 18587vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short); 18588vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short); 18589 18590vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); 18591vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); 18592vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int); 18593 18594vector float vec_vminfp (vector float, vector float); 18595 18596vector signed char vec_vminsb (vector bool char, vector signed char); 18597vector signed char vec_vminsb (vector signed char, vector bool char); 18598vector signed char vec_vminsb (vector signed char, vector signed char); 18599 18600vector signed short vec_vminsh (vector bool short, vector signed short); 18601vector signed short vec_vminsh (vector signed short, vector bool short); 18602vector signed short vec_vminsh (vector signed short, vector signed short); 18603 18604vector signed int vec_vminsw (vector bool int, vector signed int); 18605vector signed int vec_vminsw (vector signed int, vector bool int); 18606vector signed int vec_vminsw (vector signed int, vector signed int); 18607 18608vector unsigned char vec_vminub (vector bool char, vector unsigned char); 18609vector unsigned char vec_vminub (vector unsigned char, vector bool char); 18610vector unsigned char vec_vminub (vector unsigned char, vector unsigned char); 18611 18612vector unsigned short vec_vminuh (vector bool short, vector unsigned short); 18613vector unsigned short vec_vminuh (vector unsigned short, vector bool short); 18614vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short); 18615 18616vector unsigned int vec_vminuw (vector bool int, vector unsigned int); 18617vector unsigned int vec_vminuw (vector unsigned int, vector bool int); 18618vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int); 18619 18620vector bool char vec_vmrghb (vector bool char, vector bool char); 18621vector signed char vec_vmrghb (vector signed char, vector signed char); 18622vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char); 18623 18624vector bool short vec_vmrghh (vector bool short, vector bool short); 18625vector signed short vec_vmrghh (vector signed short, vector signed short); 18626vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short); 18627vector pixel vec_vmrghh (vector pixel, vector pixel); 18628 18629vector float vec_vmrghw (vector float, vector float); 18630vector bool int vec_vmrghw (vector bool int, vector bool int); 18631vector signed int vec_vmrghw (vector signed int, vector signed int); 18632vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int); 18633 18634vector bool char vec_vmrglb (vector bool char, vector bool char); 18635vector signed char vec_vmrglb (vector signed char, vector signed char); 18636vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char); 18637 18638vector bool short vec_vmrglh (vector bool short, vector bool short); 18639vector signed short vec_vmrglh (vector signed short, vector signed short); 18640vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short); 18641vector pixel vec_vmrglh (vector pixel, vector pixel); 18642 18643vector float vec_vmrglw (vector float, vector float); 18644vector signed int vec_vmrglw (vector signed int, vector signed int); 18645vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int); 18646vector bool int vec_vmrglw (vector bool int, vector bool int); 18647 18648vector signed int vec_vmsummbm (vector signed char, vector unsigned char, 18649 vector signed int); 18650 18651vector signed int vec_vmsumshm (vector signed short, vector signed short, 18652 vector signed int); 18653 18654vector signed int vec_vmsumshs (vector signed short, vector signed short, 18655 vector signed int); 18656 18657vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char, 18658 vector unsigned int); 18659 18660vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short, 18661 vector unsigned int); 18662 18663vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short, 18664 vector unsigned int); 18665 18666vector signed short vec_vmulesb (vector signed char, vector signed char); 18667 18668vector signed int vec_vmulesh (vector signed short, vector signed short); 18669 18670vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char); 18671 18672vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short); 18673 18674vector signed short vec_vmulosb (vector signed char, vector signed char); 18675 18676vector signed int vec_vmulosh (vector signed short, vector signed short); 18677 18678vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char); 18679 18680vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short); 18681 18682vector signed char vec_vpkshss (vector signed short, vector signed short); 18683 18684vector unsigned char vec_vpkshus (vector signed short, vector signed short); 18685 18686vector signed short vec_vpkswss (vector signed int, vector signed int); 18687 18688vector unsigned short vec_vpkswus (vector signed int, vector signed int); 18689 18690vector bool char vec_vpkuhum (vector bool short, vector bool short); 18691vector signed char vec_vpkuhum (vector signed short, vector signed short); 18692vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short); 18693 18694vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short); 18695 18696vector bool short vec_vpkuwum (vector bool int, vector bool int); 18697vector signed short vec_vpkuwum (vector signed int, vector signed int); 18698vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int); 18699 18700vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int); 18701 18702vector signed char vec_vrlb (vector signed char, vector unsigned char); 18703vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char); 18704 18705vector signed short vec_vrlh (vector signed short, vector unsigned short); 18706vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short); 18707 18708vector signed int vec_vrlw (vector signed int, vector unsigned int); 18709vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); 18710 18711vector signed char vec_vslb (vector signed char, vector unsigned char); 18712vector unsigned char vec_vslb (vector unsigned char, vector unsigned char); 18713 18714vector signed short vec_vslh (vector signed short, vector unsigned short); 18715vector unsigned short vec_vslh (vector unsigned short, vector unsigned short); 18716 18717vector signed int vec_vslw (vector signed int, vector unsigned int); 18718vector unsigned int vec_vslw (vector unsigned int, vector unsigned int); 18719 18720vector signed char vec_vspltb (vector signed char, const int); 18721vector unsigned char vec_vspltb (vector unsigned char, const int); 18722vector bool char vec_vspltb (vector bool char, const int); 18723 18724vector bool short vec_vsplth (vector bool short, const int); 18725vector signed short vec_vsplth (vector signed short, const int); 18726vector unsigned short vec_vsplth (vector unsigned short, const int); 18727vector pixel vec_vsplth (vector pixel, const int); 18728 18729vector float vec_vspltw (vector float, const int); 18730vector signed int vec_vspltw (vector signed int, const int); 18731vector unsigned int vec_vspltw (vector unsigned int, const int); 18732vector bool int vec_vspltw (vector bool int, const int); 18733 18734vector signed char vec_vsrab (vector signed char, vector unsigned char); 18735vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char); 18736 18737vector signed short vec_vsrah (vector signed short, vector unsigned short); 18738vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short); 18739 18740vector signed int vec_vsraw (vector signed int, vector unsigned int); 18741vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int); 18742 18743vector signed char vec_vsrb (vector signed char, vector unsigned char); 18744vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char); 18745 18746vector signed short vec_vsrh (vector signed short, vector unsigned short); 18747vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short); 18748 18749vector signed int vec_vsrw (vector signed int, vector unsigned int); 18750vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); 18751 18752vector float vec_vsubfp (vector float, vector float); 18753 18754vector signed char vec_vsubsbs (vector bool char, vector signed char); 18755vector signed char vec_vsubsbs (vector signed char, vector bool char); 18756vector signed char vec_vsubsbs (vector signed char, vector signed char); 18757 18758vector signed short vec_vsubshs (vector bool short, vector signed short); 18759vector signed short vec_vsubshs (vector signed short, vector bool short); 18760vector signed short vec_vsubshs (vector signed short, vector signed short); 18761 18762vector signed int vec_vsubsws (vector bool int, vector signed int); 18763vector signed int vec_vsubsws (vector signed int, vector bool int); 18764vector signed int vec_vsubsws (vector signed int, vector signed int); 18765 18766vector signed char vec_vsububm (vector bool char, vector signed char); 18767vector signed char vec_vsububm (vector signed char, vector bool char); 18768vector signed char vec_vsububm (vector signed char, vector signed char); 18769vector unsigned char vec_vsububm (vector bool char, vector unsigned char); 18770vector unsigned char vec_vsububm (vector unsigned char, vector bool char); 18771vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char); 18772 18773vector unsigned char vec_vsububs (vector bool char, vector unsigned char); 18774vector unsigned char vec_vsububs (vector unsigned char, vector bool char); 18775vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char); 18776 18777vector signed short vec_vsubuhm (vector bool short, vector signed short); 18778vector signed short vec_vsubuhm (vector signed short, vector bool short); 18779vector signed short vec_vsubuhm (vector signed short, vector signed short); 18780vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short); 18781vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short); 18782vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short); 18783 18784vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short); 18785vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short); 18786vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short); 18787 18788vector signed int vec_vsubuwm (vector bool int, vector signed int); 18789vector signed int vec_vsubuwm (vector signed int, vector bool int); 18790vector signed int vec_vsubuwm (vector signed int, vector signed int); 18791vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); 18792vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); 18793vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int); 18794 18795vector unsigned int vec_vsubuws (vector bool int, vector unsigned int); 18796vector unsigned int vec_vsubuws (vector unsigned int, vector bool int); 18797vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int); 18798 18799vector signed int vec_vsum4sbs (vector signed char, vector signed int); 18800 18801vector signed int vec_vsum4shs (vector signed short, vector signed int); 18802 18803vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int); 18804 18805vector unsigned int vec_vupkhpx (vector pixel); 18806 18807vector bool short vec_vupkhsb (vector bool char); 18808vector signed short vec_vupkhsb (vector signed char); 18809 18810vector bool int vec_vupkhsh (vector bool short); 18811vector signed int vec_vupkhsh (vector signed short); 18812 18813vector unsigned int vec_vupklpx (vector pixel); 18814 18815vector bool short vec_vupklsb (vector bool char); 18816vector signed short vec_vupklsb (vector signed char); 18817 18818vector bool int vec_vupklsh (vector bool short); 18819vector signed int vec_vupklsh (vector signed short); 18820 18821vector float vec_xor (vector float, vector float); 18822vector float vec_xor (vector float, vector bool int); 18823vector float vec_xor (vector bool int, vector float); 18824vector bool int vec_xor (vector bool int, vector bool int); 18825vector signed int vec_xor (vector bool int, vector signed int); 18826vector signed int vec_xor (vector signed int, vector bool int); 18827vector signed int vec_xor (vector signed int, vector signed int); 18828vector unsigned int vec_xor (vector bool int, vector unsigned int); 18829vector unsigned int vec_xor (vector unsigned int, vector bool int); 18830vector unsigned int vec_xor (vector unsigned int, vector unsigned int); 18831vector bool short vec_xor (vector bool short, vector bool short); 18832vector signed short vec_xor (vector bool short, vector signed short); 18833vector signed short vec_xor (vector signed short, vector bool short); 18834vector signed short vec_xor (vector signed short, vector signed short); 18835vector unsigned short vec_xor (vector bool short, vector unsigned short); 18836vector unsigned short vec_xor (vector unsigned short, vector bool short); 18837vector unsigned short vec_xor (vector unsigned short, vector unsigned short); 18838vector signed char vec_xor (vector bool char, vector signed char); 18839vector bool char vec_xor (vector bool char, vector bool char); 18840vector signed char vec_xor (vector signed char, vector bool char); 18841vector signed char vec_xor (vector signed char, vector signed char); 18842vector unsigned char vec_xor (vector bool char, vector unsigned char); 18843vector unsigned char vec_xor (vector unsigned char, vector bool char); 18844vector unsigned char vec_xor (vector unsigned char, vector unsigned char); 18845@end smallexample 18846 18847@node PowerPC AltiVec Built-in Functions Available on ISA 2.06 18848@subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06 18849 18850The AltiVec built-in functions described in this section are 18851available on the PowerPC family of processors starting with ISA 2.06 18852or later. These are normally enabled by adding @option{-mvsx} to the 18853command line. 18854 18855When @option{-mvsx} is used, the following additional vector types are 18856implemented. 18857 18858@smallexample 18859vector unsigned __int128 18860vector signed __int128 18861vector unsigned long long int 18862vector signed long long int 18863vector double 18864@end smallexample 18865 18866The long long types are only implemented for 64-bit code generation. 18867 18868@smallexample 18869 18870vector bool long long vec_and (vector bool long long int, vector bool long long); 18871 18872vector double vec_ctf (vector unsigned long, const int); 18873vector double vec_ctf (vector signed long, const int); 18874 18875vector signed long vec_cts (vector double, const int); 18876 18877vector unsigned long vec_ctu (vector double, const int); 18878 18879void vec_dst (const unsigned long *, int, const int); 18880void vec_dst (const long *, int, const int); 18881 18882void vec_dststt (const unsigned long *, int, const int); 18883void vec_dststt (const long *, int, const int); 18884 18885void vec_dstt (const unsigned long *, int, const int); 18886void vec_dstt (const long *, int, const int); 18887 18888vector unsigned char vec_lvsl (int, const unsigned long *); 18889vector unsigned char vec_lvsl (int, const long *); 18890 18891vector unsigned char vec_lvsr (int, const unsigned long *); 18892vector unsigned char vec_lvsr (int, const long *); 18893 18894vector double vec_mul (vector double, vector double); 18895vector long vec_mul (vector long, vector long); 18896vector unsigned long vec_mul (vector unsigned long, vector unsigned long); 18897 18898vector unsigned long long vec_mule (vector unsigned int, vector unsigned int); 18899vector signed long long vec_mule (vector signed int, vector signed int); 18900 18901vector unsigned long long vec_mulo (vector unsigned int, vector unsigned int); 18902vector signed long long vec_mulo (vector signed int, vector signed int); 18903 18904vector double vec_nabs (vector double); 18905 18906vector bool long long vec_reve (vector bool long long); 18907vector signed long long vec_reve (vector signed long long); 18908vector unsigned long long vec_reve (vector unsigned long long); 18909vector double vec_sld (vector double, vector double, const int); 18910 18911vector bool long long int vec_sld (vector bool long long int, 18912 vector bool long long int, const int); 18913vector long long int vec_sld (vector long long int, vector long long int, const int); 18914vector unsigned long long int vec_sld (vector unsigned long long int, 18915 vector unsigned long long int, const int); 18916 18917vector long long int vec_sll (vector long long int, vector unsigned char); 18918vector unsigned long long int vec_sll (vector unsigned long long int, 18919 vector unsigned char); 18920 18921vector signed long long vec_slo (vector signed long long, vector signed char); 18922vector signed long long vec_slo (vector signed long long, vector unsigned char); 18923vector unsigned long long vec_slo (vector unsigned long long, vector signed char); 18924vector unsigned long long vec_slo (vector unsigned long long, vector unsigned char); 18925 18926vector signed long vec_splat (vector signed long, const int); 18927vector unsigned long vec_splat (vector unsigned long, const int); 18928 18929vector long long int vec_srl (vector long long int, vector unsigned char); 18930vector unsigned long long int vec_srl (vector unsigned long long int, 18931 vector unsigned char); 18932 18933vector long long int vec_sro (vector long long int, vector char); 18934vector long long int vec_sro (vector long long int, vector unsigned char); 18935vector unsigned long long int vec_sro (vector unsigned long long int, vector char); 18936vector unsigned long long int vec_sro (vector unsigned long long int, 18937 vector unsigned char); 18938 18939vector signed __int128 vec_subc (vector signed __int128, vector signed __int128); 18940vector unsigned __int128 vec_subc (vector unsigned __int128, vector unsigned __int128); 18941 18942vector signed __int128 vec_sube (vector signed __int128, vector signed __int128, 18943 vector signed __int128); 18944vector unsigned __int128 vec_sube (vector unsigned __int128, vector unsigned __int128, 18945 vector unsigned __int128); 18946 18947vector signed __int128 vec_subec (vector signed __int128, vector signed __int128, 18948 vector signed __int128); 18949vector unsigned __int128 vec_subec (vector unsigned __int128, vector unsigned __int128, 18950 vector unsigned __int128); 18951 18952vector double vec_unpackh (vector float); 18953 18954vector double vec_unpackl (vector float); 18955 18956vector double vec_doublee (vector float); 18957vector double vec_doublee (vector signed int); 18958vector double vec_doublee (vector unsigned int); 18959 18960vector double vec_doubleo (vector float); 18961vector double vec_doubleo (vector signed int); 18962vector double vec_doubleo (vector unsigned int); 18963 18964vector double vec_doubleh (vector float); 18965vector double vec_doubleh (vector signed int); 18966vector double vec_doubleh (vector unsigned int); 18967 18968vector double vec_doublel (vector float); 18969vector double vec_doublel (vector signed int); 18970vector double vec_doublel (vector unsigned int); 18971 18972vector float vec_float (vector signed int); 18973vector float vec_float (vector unsigned int); 18974 18975vector float vec_float2 (vector signed long long, vector signed long long); 18976vector float vec_float2 (vector unsigned long long, vector signed long long); 18977 18978vector float vec_floate (vector double); 18979vector float vec_floate (vector signed long long); 18980vector float vec_floate (vector unsigned long long); 18981 18982vector float vec_floato (vector double); 18983vector float vec_floato (vector signed long long); 18984vector float vec_floato (vector unsigned long long); 18985 18986vector signed long long vec_signed (vector double); 18987vector signed int vec_signed (vector float); 18988 18989vector signed int vec_signede (vector double); 18990 18991vector signed int vec_signedo (vector double); 18992 18993vector signed char vec_sldw (vector signed char, vector signed char, const int); 18994vector unsigned char vec_sldw (vector unsigned char, vector unsigned char, const int); 18995vector signed short vec_sldw (vector signed short, vector signed short, const int); 18996vector unsigned short vec_sldw (vector unsigned short, 18997 vector unsigned short, const int); 18998vector signed int vec_sldw (vector signed int, vector signed int, const int); 18999vector unsigned int vec_sldw (vector unsigned int, vector unsigned int, const int); 19000vector signed long long vec_sldw (vector signed long long, 19001 vector signed long long, const int); 19002vector unsigned long long vec_sldw (vector unsigned long long, 19003 vector unsigned long long, const int); 19004 19005vector signed long long vec_unsigned (vector double); 19006vector signed int vec_unsigned (vector float); 19007 19008vector signed int vec_unsignede (vector double); 19009 19010vector signed int vec_unsignedo (vector double); 19011 19012vector double vec_abs (vector double); 19013vector double vec_add (vector double, vector double); 19014vector double vec_and (vector double, vector double); 19015vector double vec_and (vector double, vector bool long); 19016vector double vec_and (vector bool long, vector double); 19017vector long vec_and (vector long, vector long); 19018vector long vec_and (vector long, vector bool long); 19019vector long vec_and (vector bool long, vector long); 19020vector unsigned long vec_and (vector unsigned long, vector unsigned long); 19021vector unsigned long vec_and (vector unsigned long, vector bool long); 19022vector unsigned long vec_and (vector bool long, vector unsigned long); 19023vector double vec_andc (vector double, vector double); 19024vector double vec_andc (vector double, vector bool long); 19025vector double vec_andc (vector bool long, vector double); 19026vector long vec_andc (vector long, vector long); 19027vector long vec_andc (vector long, vector bool long); 19028vector long vec_andc (vector bool long, vector long); 19029vector unsigned long vec_andc (vector unsigned long, vector unsigned long); 19030vector unsigned long vec_andc (vector unsigned long, vector bool long); 19031vector unsigned long vec_andc (vector bool long, vector unsigned long); 19032vector double vec_ceil (vector double); 19033vector bool long vec_cmpeq (vector double, vector double); 19034vector bool long vec_cmpge (vector double, vector double); 19035vector bool long vec_cmpgt (vector double, vector double); 19036vector bool long vec_cmple (vector double, vector double); 19037vector bool long vec_cmplt (vector double, vector double); 19038vector double vec_cpsgn (vector double, vector double); 19039vector float vec_div (vector float, vector float); 19040vector double vec_div (vector double, vector double); 19041vector long vec_div (vector long, vector long); 19042vector unsigned long vec_div (vector unsigned long, vector unsigned long); 19043vector double vec_floor (vector double); 19044vector signed long long vec_ld (int, const vector signed long long *); 19045vector signed long long vec_ld (int, const signed long long *); 19046vector unsigned long long vec_ld (int, const vector unsigned long long *); 19047vector unsigned long long vec_ld (int, const unsigned long long *); 19048vector __int128 vec_ld (int, const vector __int128 *); 19049vector unsigned __int128 vec_ld (int, const vector unsigned __int128 *); 19050vector __int128 vec_ld (int, const __int128 *); 19051vector unsigned __int128 vec_ld (int, const unsigned __int128 *); 19052vector double vec_ld (int, const vector double *); 19053vector double vec_ld (int, const double *); 19054vector double vec_ldl (int, const vector double *); 19055vector double vec_ldl (int, const double *); 19056vector unsigned char vec_lvsl (int, const double *); 19057vector unsigned char vec_lvsr (int, const double *); 19058vector double vec_madd (vector double, vector double, vector double); 19059vector double vec_max (vector double, vector double); 19060vector signed long vec_mergeh (vector signed long, vector signed long); 19061vector signed long vec_mergeh (vector signed long, vector bool long); 19062vector signed long vec_mergeh (vector bool long, vector signed long); 19063vector unsigned long vec_mergeh (vector unsigned long, vector unsigned long); 19064vector unsigned long vec_mergeh (vector unsigned long, vector bool long); 19065vector unsigned long vec_mergeh (vector bool long, vector unsigned long); 19066vector signed long vec_mergel (vector signed long, vector signed long); 19067vector signed long vec_mergel (vector signed long, vector bool long); 19068vector signed long vec_mergel (vector bool long, vector signed long); 19069vector unsigned long vec_mergel (vector unsigned long, vector unsigned long); 19070vector unsigned long vec_mergel (vector unsigned long, vector bool long); 19071vector unsigned long vec_mergel (vector bool long, vector unsigned long); 19072vector double vec_min (vector double, vector double); 19073vector float vec_msub (vector float, vector float, vector float); 19074vector double vec_msub (vector double, vector double, vector double); 19075vector float vec_nearbyint (vector float); 19076vector double vec_nearbyint (vector double); 19077vector float vec_nmadd (vector float, vector float, vector float); 19078vector double vec_nmadd (vector double, vector double, vector double); 19079vector double vec_nmsub (vector double, vector double, vector double); 19080vector double vec_nor (vector double, vector double); 19081vector long vec_nor (vector long, vector long); 19082vector long vec_nor (vector long, vector bool long); 19083vector long vec_nor (vector bool long, vector long); 19084vector unsigned long vec_nor (vector unsigned long, vector unsigned long); 19085vector unsigned long vec_nor (vector unsigned long, vector bool long); 19086vector unsigned long vec_nor (vector bool long, vector unsigned long); 19087vector double vec_or (vector double, vector double); 19088vector double vec_or (vector double, vector bool long); 19089vector double vec_or (vector bool long, vector double); 19090vector long vec_or (vector long, vector long); 19091vector long vec_or (vector long, vector bool long); 19092vector long vec_or (vector bool long, vector long); 19093vector unsigned long vec_or (vector unsigned long, vector unsigned long); 19094vector unsigned long vec_or (vector unsigned long, vector bool long); 19095vector unsigned long vec_or (vector bool long, vector unsigned long); 19096vector double vec_perm (vector double, vector double, vector unsigned char); 19097vector long vec_perm (vector long, vector long, vector unsigned char); 19098vector unsigned long vec_perm (vector unsigned long, vector unsigned long, 19099 vector unsigned char); 19100vector bool char vec_permxor (vector bool char, vector bool char, 19101 vector bool char); 19102vector unsigned char vec_permxor (vector signed char, vector signed char, 19103 vector signed char); 19104vector unsigned char vec_permxor (vector unsigned char, vector unsigned char, 19105 vector unsigned char); 19106vector double vec_rint (vector double); 19107vector double vec_recip (vector double, vector double); 19108vector double vec_rsqrt (vector double); 19109vector double vec_rsqrte (vector double); 19110vector double vec_sel (vector double, vector double, vector bool long); 19111vector double vec_sel (vector double, vector double, vector unsigned long); 19112vector long vec_sel (vector long, vector long, vector long); 19113vector long vec_sel (vector long, vector long, vector unsigned long); 19114vector long vec_sel (vector long, vector long, vector bool long); 19115vector unsigned long vec_sel (vector unsigned long, vector unsigned long, 19116 vector long); 19117vector unsigned long vec_sel (vector unsigned long, vector unsigned long, 19118 vector unsigned long); 19119vector unsigned long vec_sel (vector unsigned long, vector unsigned long, 19120 vector bool long); 19121vector double vec_splats (double); 19122vector signed long vec_splats (signed long); 19123vector unsigned long vec_splats (unsigned long); 19124vector float vec_sqrt (vector float); 19125vector double vec_sqrt (vector double); 19126void vec_st (vector signed long long, int, vector signed long long *); 19127void vec_st (vector signed long long, int, signed long long *); 19128void vec_st (vector unsigned long long, int, vector unsigned long long *); 19129void vec_st (vector unsigned long long, int, unsigned long long *); 19130void vec_st (vector bool long long, int, vector bool long long *); 19131void vec_st (vector bool long long, int, signed long long *); 19132void vec_st (vector bool long long, int, unsigned long long *); 19133void vec_st (vector double, int, vector double *); 19134void vec_st (vector double, int, double *); 19135vector double vec_sub (vector double, vector double); 19136vector double vec_trunc (vector double); 19137vector double vec_xl (int, vector double *); 19138vector double vec_xl (int, double *); 19139vector long long vec_xl (int, vector long long *); 19140vector long long vec_xl (int, long long *); 19141vector unsigned long long vec_xl (int, vector unsigned long long *); 19142vector unsigned long long vec_xl (int, unsigned long long *); 19143vector float vec_xl (int, vector float *); 19144vector float vec_xl (int, float *); 19145vector int vec_xl (int, vector int *); 19146vector int vec_xl (int, int *); 19147vector unsigned int vec_xl (int, vector unsigned int *); 19148vector unsigned int vec_xl (int, unsigned int *); 19149vector double vec_xor (vector double, vector double); 19150vector double vec_xor (vector double, vector bool long); 19151vector double vec_xor (vector bool long, vector double); 19152vector long vec_xor (vector long, vector long); 19153vector long vec_xor (vector long, vector bool long); 19154vector long vec_xor (vector bool long, vector long); 19155vector unsigned long vec_xor (vector unsigned long, vector unsigned long); 19156vector unsigned long vec_xor (vector unsigned long, vector bool long); 19157vector unsigned long vec_xor (vector bool long, vector unsigned long); 19158void vec_xst (vector double, int, vector double *); 19159void vec_xst (vector double, int, double *); 19160void vec_xst (vector long long, int, vector long long *); 19161void vec_xst (vector long long, int, long long *); 19162void vec_xst (vector unsigned long long, int, vector unsigned long long *); 19163void vec_xst (vector unsigned long long, int, unsigned long long *); 19164void vec_xst (vector float, int, vector float *); 19165void vec_xst (vector float, int, float *); 19166void vec_xst (vector int, int, vector int *); 19167void vec_xst (vector int, int, int *); 19168void vec_xst (vector unsigned int, int, vector unsigned int *); 19169void vec_xst (vector unsigned int, int, unsigned int *); 19170int vec_all_eq (vector double, vector double); 19171int vec_all_ge (vector double, vector double); 19172int vec_all_gt (vector double, vector double); 19173int vec_all_le (vector double, vector double); 19174int vec_all_lt (vector double, vector double); 19175int vec_all_nan (vector double); 19176int vec_all_ne (vector double, vector double); 19177int vec_all_nge (vector double, vector double); 19178int vec_all_ngt (vector double, vector double); 19179int vec_all_nle (vector double, vector double); 19180int vec_all_nlt (vector double, vector double); 19181int vec_all_numeric (vector double); 19182int vec_any_eq (vector double, vector double); 19183int vec_any_ge (vector double, vector double); 19184int vec_any_gt (vector double, vector double); 19185int vec_any_le (vector double, vector double); 19186int vec_any_lt (vector double, vector double); 19187int vec_any_nan (vector double); 19188int vec_any_ne (vector double, vector double); 19189int vec_any_nge (vector double, vector double); 19190int vec_any_ngt (vector double, vector double); 19191int vec_any_nle (vector double, vector double); 19192int vec_any_nlt (vector double, vector double); 19193int vec_any_numeric (vector double); 19194 19195vector double vec_vsx_ld (int, const vector double *); 19196vector double vec_vsx_ld (int, const double *); 19197vector float vec_vsx_ld (int, const vector float *); 19198vector float vec_vsx_ld (int, const float *); 19199vector bool int vec_vsx_ld (int, const vector bool int *); 19200vector signed int vec_vsx_ld (int, const vector signed int *); 19201vector signed int vec_vsx_ld (int, const int *); 19202vector signed int vec_vsx_ld (int, const long *); 19203vector unsigned int vec_vsx_ld (int, const vector unsigned int *); 19204vector unsigned int vec_vsx_ld (int, const unsigned int *); 19205vector unsigned int vec_vsx_ld (int, const unsigned long *); 19206vector bool short vec_vsx_ld (int, const vector bool short *); 19207vector pixel vec_vsx_ld (int, const vector pixel *); 19208vector signed short vec_vsx_ld (int, const vector signed short *); 19209vector signed short vec_vsx_ld (int, const short *); 19210vector unsigned short vec_vsx_ld (int, const vector unsigned short *); 19211vector unsigned short vec_vsx_ld (int, const unsigned short *); 19212vector bool char vec_vsx_ld (int, const vector bool char *); 19213vector signed char vec_vsx_ld (int, const vector signed char *); 19214vector signed char vec_vsx_ld (int, const signed char *); 19215vector unsigned char vec_vsx_ld (int, const vector unsigned char *); 19216vector unsigned char vec_vsx_ld (int, const unsigned char *); 19217 19218void vec_vsx_st (vector double, int, vector double *); 19219void vec_vsx_st (vector double, int, double *); 19220void vec_vsx_st (vector float, int, vector float *); 19221void vec_vsx_st (vector float, int, float *); 19222void vec_vsx_st (vector signed int, int, vector signed int *); 19223void vec_vsx_st (vector signed int, int, int *); 19224void vec_vsx_st (vector unsigned int, int, vector unsigned int *); 19225void vec_vsx_st (vector unsigned int, int, unsigned int *); 19226void vec_vsx_st (vector bool int, int, vector bool int *); 19227void vec_vsx_st (vector bool int, int, unsigned int *); 19228void vec_vsx_st (vector bool int, int, int *); 19229void vec_vsx_st (vector signed short, int, vector signed short *); 19230void vec_vsx_st (vector signed short, int, short *); 19231void vec_vsx_st (vector unsigned short, int, vector unsigned short *); 19232void vec_vsx_st (vector unsigned short, int, unsigned short *); 19233void vec_vsx_st (vector bool short, int, vector bool short *); 19234void vec_vsx_st (vector bool short, int, unsigned short *); 19235void vec_vsx_st (vector pixel, int, vector pixel *); 19236void vec_vsx_st (vector pixel, int, unsigned short *); 19237void vec_vsx_st (vector pixel, int, short *); 19238void vec_vsx_st (vector bool short, int, short *); 19239void vec_vsx_st (vector signed char, int, vector signed char *); 19240void vec_vsx_st (vector signed char, int, signed char *); 19241void vec_vsx_st (vector unsigned char, int, vector unsigned char *); 19242void vec_vsx_st (vector unsigned char, int, unsigned char *); 19243void vec_vsx_st (vector bool char, int, vector bool char *); 19244void vec_vsx_st (vector bool char, int, unsigned char *); 19245void vec_vsx_st (vector bool char, int, signed char *); 19246 19247vector double vec_xxpermdi (vector double, vector double, const int); 19248vector float vec_xxpermdi (vector float, vector float, const int); 19249vector long long vec_xxpermdi (vector long long, vector long long, const int); 19250vector unsigned long long vec_xxpermdi (vector unsigned long long, 19251 vector unsigned long long, const int); 19252vector int vec_xxpermdi (vector int, vector int, const int); 19253vector unsigned int vec_xxpermdi (vector unsigned int, 19254 vector unsigned int, const int); 19255vector short vec_xxpermdi (vector short, vector short, const int); 19256vector unsigned short vec_xxpermdi (vector unsigned short, 19257 vector unsigned short, const int); 19258vector signed char vec_xxpermdi (vector signed char, vector signed char, 19259 const int); 19260vector unsigned char vec_xxpermdi (vector unsigned char, 19261 vector unsigned char, const int); 19262 19263vector double vec_xxsldi (vector double, vector double, int); 19264vector float vec_xxsldi (vector float, vector float, int); 19265vector long long vec_xxsldi (vector long long, vector long long, int); 19266vector unsigned long long vec_xxsldi (vector unsigned long long, 19267 vector unsigned long long, int); 19268vector int vec_xxsldi (vector int, vector int, int); 19269vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int); 19270vector short vec_xxsldi (vector short, vector short, int); 19271vector unsigned short vec_xxsldi (vector unsigned short, 19272 vector unsigned short, int); 19273vector signed char vec_xxsldi (vector signed char, vector signed char, int); 19274vector unsigned char vec_xxsldi (vector unsigned char, 19275 vector unsigned char, int); 19276@end smallexample 19277 19278Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always 19279generate the AltiVec @samp{LVX} and @samp{STVX} instructions even 19280if the VSX instruction set is available. The @samp{vec_vsx_ld} and 19281@samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X}, 19282@samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions. 19283 19284@node PowerPC AltiVec Built-in Functions Available on ISA 2.07 19285@subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07 19286 19287If the ISA 2.07 additions to the vector/scalar (power8-vector) 19288instruction set are available, the following additional functions are 19289available for both 32-bit and 64-bit targets. For 64-bit targets, you 19290can use @var{vector long} instead of @var{vector long long}, 19291@var{vector bool long} instead of @var{vector bool long long}, and 19292@var{vector unsigned long} instead of @var{vector unsigned long long}. 19293 19294@smallexample 19295vector signed char vec_neg (vector signed char); 19296vector signed short vec_neg (vector signed short); 19297vector signed int vec_neg (vector signed int); 19298vector signed long long vec_neg (vector signed long long); 19299vector float char vec_neg (vector float); 19300vector double vec_neg (vector double); 19301 19302vector signed int vec_signed2 (vector double, vector double); 19303 19304vector signed int vec_unsigned2 (vector double, vector double); 19305 19306vector long long vec_abs (vector long long); 19307 19308vector long long vec_add (vector long long, vector long long); 19309vector unsigned long long vec_add (vector unsigned long long, 19310 vector unsigned long long); 19311 19312int vec_all_eq (vector long long, vector long long); 19313int vec_all_eq (vector unsigned long long, vector unsigned long long); 19314int vec_all_ge (vector long long, vector long long); 19315int vec_all_ge (vector unsigned long long, vector unsigned long long); 19316int vec_all_gt (vector long long, vector long long); 19317int vec_all_gt (vector unsigned long long, vector unsigned long long); 19318int vec_all_le (vector long long, vector long long); 19319int vec_all_le (vector unsigned long long, vector unsigned long long); 19320int vec_all_lt (vector long long, vector long long); 19321int vec_all_lt (vector unsigned long long, vector unsigned long long); 19322int vec_all_ne (vector long long, vector long long); 19323int vec_all_ne (vector unsigned long long, vector unsigned long long); 19324 19325int vec_any_eq (vector long long, vector long long); 19326int vec_any_eq (vector unsigned long long, vector unsigned long long); 19327int vec_any_ge (vector long long, vector long long); 19328int vec_any_ge (vector unsigned long long, vector unsigned long long); 19329int vec_any_gt (vector long long, vector long long); 19330int vec_any_gt (vector unsigned long long, vector unsigned long long); 19331int vec_any_le (vector long long, vector long long); 19332int vec_any_le (vector unsigned long long, vector unsigned long long); 19333int vec_any_lt (vector long long, vector long long); 19334int vec_any_lt (vector unsigned long long, vector unsigned long long); 19335int vec_any_ne (vector long long, vector long long); 19336int vec_any_ne (vector unsigned long long, vector unsigned long long); 19337 19338vector bool long long vec_cmpeq (vector bool long long, vector bool long long); 19339 19340vector long long vec_eqv (vector long long, vector long long); 19341vector long long vec_eqv (vector bool long long, vector long long); 19342vector long long vec_eqv (vector long long, vector bool long long); 19343vector unsigned long long vec_eqv (vector unsigned long long, vector unsigned long long); 19344vector unsigned long long vec_eqv (vector bool long long, vector unsigned long long); 19345vector unsigned long long vec_eqv (vector unsigned long long, 19346 vector bool long long); 19347vector int vec_eqv (vector int, vector int); 19348vector int vec_eqv (vector bool int, vector int); 19349vector int vec_eqv (vector int, vector bool int); 19350vector unsigned int vec_eqv (vector unsigned int, vector unsigned int); 19351vector unsigned int vec_eqv (vector bool unsigned int, vector unsigned int); 19352vector unsigned int vec_eqv (vector unsigned int, vector bool unsigned int); 19353vector short vec_eqv (vector short, vector short); 19354vector short vec_eqv (vector bool short, vector short); 19355vector short vec_eqv (vector short, vector bool short); 19356vector unsigned short vec_eqv (vector unsigned short, vector unsigned short); 19357vector unsigned short vec_eqv (vector bool unsigned short, vector unsigned short); 19358vector unsigned short vec_eqv (vector unsigned short, vector bool unsigned short); 19359vector signed char vec_eqv (vector signed char, vector signed char); 19360vector signed char vec_eqv (vector bool signed char, vector signed char); 19361vector signed char vec_eqv (vector signed char, vector bool signed char); 19362vector unsigned char vec_eqv (vector unsigned char, vector unsigned char); 19363vector unsigned char vec_eqv (vector bool unsigned char, vector unsigned char); 19364vector unsigned char vec_eqv (vector unsigned char, vector bool unsigned char); 19365 19366vector long long vec_max (vector long long, vector long long); 19367vector unsigned long long vec_max (vector unsigned long long, 19368 vector unsigned long long); 19369 19370vector signed int vec_mergee (vector signed int, vector signed int); 19371vector unsigned int vec_mergee (vector unsigned int, vector unsigned int); 19372vector bool int vec_mergee (vector bool int, vector bool int); 19373 19374vector signed int vec_mergeo (vector signed int, vector signed int); 19375vector unsigned int vec_mergeo (vector unsigned int, vector unsigned int); 19376vector bool int vec_mergeo (vector bool int, vector bool int); 19377 19378vector long long vec_min (vector long long, vector long long); 19379vector unsigned long long vec_min (vector unsigned long long, 19380 vector unsigned long long); 19381 19382vector signed long long vec_nabs (vector signed long long); 19383 19384vector long long vec_nand (vector long long, vector long long); 19385vector long long vec_nand (vector bool long long, vector long long); 19386vector long long vec_nand (vector long long, vector bool long long); 19387vector unsigned long long vec_nand (vector unsigned long long, 19388 vector unsigned long long); 19389vector unsigned long long vec_nand (vector bool long long, vector unsigned long long); 19390vector unsigned long long vec_nand (vector unsigned long long, vector bool long long); 19391vector int vec_nand (vector int, vector int); 19392vector int vec_nand (vector bool int, vector int); 19393vector int vec_nand (vector int, vector bool int); 19394vector unsigned int vec_nand (vector unsigned int, vector unsigned int); 19395vector unsigned int vec_nand (vector bool unsigned int, vector unsigned int); 19396vector unsigned int vec_nand (vector unsigned int, vector bool unsigned int); 19397vector short vec_nand (vector short, vector short); 19398vector short vec_nand (vector bool short, vector short); 19399vector short vec_nand (vector short, vector bool short); 19400vector unsigned short vec_nand (vector unsigned short, vector unsigned short); 19401vector unsigned short vec_nand (vector bool unsigned short, vector unsigned short); 19402vector unsigned short vec_nand (vector unsigned short, vector bool unsigned short); 19403vector signed char vec_nand (vector signed char, vector signed char); 19404vector signed char vec_nand (vector bool signed char, vector signed char); 19405vector signed char vec_nand (vector signed char, vector bool signed char); 19406vector unsigned char vec_nand (vector unsigned char, vector unsigned char); 19407vector unsigned char vec_nand (vector bool unsigned char, vector unsigned char); 19408vector unsigned char vec_nand (vector unsigned char, vector bool unsigned char); 19409 19410vector long long vec_orc (vector long long, vector long long); 19411vector long long vec_orc (vector bool long long, vector long long); 19412vector long long vec_orc (vector long long, vector bool long long); 19413vector unsigned long long vec_orc (vector unsigned long long, 19414 vector unsigned long long); 19415vector unsigned long long vec_orc (vector bool long long, vector unsigned long long); 19416vector unsigned long long vec_orc (vector unsigned long long, vector bool long long); 19417vector int vec_orc (vector int, vector int); 19418vector int vec_orc (vector bool int, vector int); 19419vector int vec_orc (vector int, vector bool int); 19420vector unsigned int vec_orc (vector unsigned int, vector unsigned int); 19421vector unsigned int vec_orc (vector bool unsigned int, vector unsigned int); 19422vector unsigned int vec_orc (vector unsigned int, vector bool unsigned int); 19423vector short vec_orc (vector short, vector short); 19424vector short vec_orc (vector bool short, vector short); 19425vector short vec_orc (vector short, vector bool short); 19426vector unsigned short vec_orc (vector unsigned short, vector unsigned short); 19427vector unsigned short vec_orc (vector bool unsigned short, vector unsigned short); 19428vector unsigned short vec_orc (vector unsigned short, vector bool unsigned short); 19429vector signed char vec_orc (vector signed char, vector signed char); 19430vector signed char vec_orc (vector bool signed char, vector signed char); 19431vector signed char vec_orc (vector signed char, vector bool signed char); 19432vector unsigned char vec_orc (vector unsigned char, vector unsigned char); 19433vector unsigned char vec_orc (vector bool unsigned char, vector unsigned char); 19434vector unsigned char vec_orc (vector unsigned char, vector bool unsigned char); 19435 19436vector int vec_pack (vector long long, vector long long); 19437vector unsigned int vec_pack (vector unsigned long long, vector unsigned long long); 19438vector bool int vec_pack (vector bool long long, vector bool long long); 19439vector float vec_pack (vector double, vector double); 19440 19441vector int vec_packs (vector long long, vector long long); 19442vector unsigned int vec_packs (vector unsigned long long, vector unsigned long long); 19443 19444vector unsigned char vec_packsu (vector signed short, vector signed short) 19445vector unsigned char vec_packsu (vector unsigned short, vector unsigned short) 19446vector unsigned short int vec_packsu (vector signed int, vector signed int); 19447vector unsigned short int vec_packsu (vector unsigned int, vector unsigned int); 19448vector unsigned int vec_packsu (vector long long, vector long long); 19449vector unsigned int vec_packsu (vector unsigned long long, vector unsigned long long); 19450vector unsigned int vec_packsu (vector signed long long, vector signed long long); 19451 19452vector unsigned char vec_popcnt (vector signed char); 19453vector unsigned char vec_popcnt (vector unsigned char); 19454vector unsigned short vec_popcnt (vector signed short); 19455vector unsigned short vec_popcnt (vector unsigned short); 19456vector unsigned int vec_popcnt (vector signed int); 19457vector unsigned int vec_popcnt (vector unsigned int); 19458vector unsigned long long vec_popcnt (vector signed long long); 19459vector unsigned long long vec_popcnt (vector unsigned long long); 19460 19461vector long long vec_rl (vector long long, vector unsigned long long); 19462vector long long vec_rl (vector unsigned long long, vector unsigned long long); 19463 19464vector long long vec_sl (vector long long, vector unsigned long long); 19465vector long long vec_sl (vector unsigned long long, vector unsigned long long); 19466 19467vector long long vec_sr (vector long long, vector unsigned long long); 19468vector unsigned long long char vec_sr (vector unsigned long long, 19469 vector unsigned long long); 19470 19471vector long long vec_sra (vector long long, vector unsigned long long); 19472vector unsigned long long vec_sra (vector unsigned long long, 19473 vector unsigned long long); 19474 19475vector long long vec_sub (vector long long, vector long long); 19476vector unsigned long long vec_sub (vector unsigned long long, 19477 vector unsigned long long); 19478 19479vector long long vec_unpackh (vector int); 19480vector unsigned long long vec_unpackh (vector unsigned int); 19481 19482vector long long vec_unpackl (vector int); 19483vector unsigned long long vec_unpackl (vector unsigned int); 19484 19485vector long long vec_vaddudm (vector long long, vector long long); 19486vector long long vec_vaddudm (vector bool long long, vector long long); 19487vector long long vec_vaddudm (vector long long, vector bool long long); 19488vector unsigned long long vec_vaddudm (vector unsigned long long, 19489 vector unsigned long long); 19490vector unsigned long long vec_vaddudm (vector bool unsigned long long, 19491 vector unsigned long long); 19492vector unsigned long long vec_vaddudm (vector unsigned long long, 19493 vector bool unsigned long long); 19494 19495vector long long vec_vbpermq (vector signed char, vector signed char); 19496vector long long vec_vbpermq (vector unsigned char, vector unsigned char); 19497 19498vector unsigned char vec_bperm (vector unsigned char, vector unsigned char); 19499vector unsigned char vec_bperm (vector unsigned long long, vector unsigned char); 19500vector unsigned long long vec_bperm (vector unsigned __int128, vector unsigned char); 19501 19502vector long long vec_cntlz (vector long long); 19503vector unsigned long long vec_cntlz (vector unsigned long long); 19504vector int vec_cntlz (vector int); 19505vector unsigned int vec_cntlz (vector int); 19506vector short vec_cntlz (vector short); 19507vector unsigned short vec_cntlz (vector unsigned short); 19508vector signed char vec_cntlz (vector signed char); 19509vector unsigned char vec_cntlz (vector unsigned char); 19510 19511vector long long vec_vclz (vector long long); 19512vector unsigned long long vec_vclz (vector unsigned long long); 19513vector int vec_vclz (vector int); 19514vector unsigned int vec_vclz (vector int); 19515vector short vec_vclz (vector short); 19516vector unsigned short vec_vclz (vector unsigned short); 19517vector signed char vec_vclz (vector signed char); 19518vector unsigned char vec_vclz (vector unsigned char); 19519 19520vector signed char vec_vclzb (vector signed char); 19521vector unsigned char vec_vclzb (vector unsigned char); 19522 19523vector long long vec_vclzd (vector long long); 19524vector unsigned long long vec_vclzd (vector unsigned long long); 19525 19526vector short vec_vclzh (vector short); 19527vector unsigned short vec_vclzh (vector unsigned short); 19528 19529vector int vec_vclzw (vector int); 19530vector unsigned int vec_vclzw (vector int); 19531 19532vector signed char vec_vgbbd (vector signed char); 19533vector unsigned char vec_vgbbd (vector unsigned char); 19534 19535vector long long vec_vmaxsd (vector long long, vector long long); 19536 19537vector unsigned long long vec_vmaxud (vector unsigned long long, 19538 unsigned vector long long); 19539 19540vector long long vec_vminsd (vector long long, vector long long); 19541 19542vector unsigned long long vec_vminud (vector long long, vector long long); 19543 19544vector int vec_vpksdss (vector long long, vector long long); 19545vector unsigned int vec_vpksdss (vector long long, vector long long); 19546 19547vector unsigned int vec_vpkudus (vector unsigned long long, 19548 vector unsigned long long); 19549 19550vector int vec_vpkudum (vector long long, vector long long); 19551vector unsigned int vec_vpkudum (vector unsigned long long, 19552 vector unsigned long long); 19553vector bool int vec_vpkudum (vector bool long long, vector bool long long); 19554 19555vector long long vec_vpopcnt (vector long long); 19556vector unsigned long long vec_vpopcnt (vector unsigned long long); 19557vector int vec_vpopcnt (vector int); 19558vector unsigned int vec_vpopcnt (vector int); 19559vector short vec_vpopcnt (vector short); 19560vector unsigned short vec_vpopcnt (vector unsigned short); 19561vector signed char vec_vpopcnt (vector signed char); 19562vector unsigned char vec_vpopcnt (vector unsigned char); 19563 19564vector signed char vec_vpopcntb (vector signed char); 19565vector unsigned char vec_vpopcntb (vector unsigned char); 19566 19567vector long long vec_vpopcntd (vector long long); 19568vector unsigned long long vec_vpopcntd (vector unsigned long long); 19569 19570vector short vec_vpopcnth (vector short); 19571vector unsigned short vec_vpopcnth (vector unsigned short); 19572 19573vector int vec_vpopcntw (vector int); 19574vector unsigned int vec_vpopcntw (vector int); 19575 19576vector long long vec_vrld (vector long long, vector unsigned long long); 19577vector unsigned long long vec_vrld (vector unsigned long long, 19578 vector unsigned long long); 19579 19580vector long long vec_vsld (vector long long, vector unsigned long long); 19581vector long long vec_vsld (vector unsigned long long, 19582 vector unsigned long long); 19583 19584vector long long vec_vsrad (vector long long, vector unsigned long long); 19585vector unsigned long long vec_vsrad (vector unsigned long long, 19586 vector unsigned long long); 19587 19588vector long long vec_vsrd (vector long long, vector unsigned long long); 19589vector unsigned long long char vec_vsrd (vector unsigned long long, 19590 vector unsigned long long); 19591 19592vector long long vec_vsubudm (vector long long, vector long long); 19593vector long long vec_vsubudm (vector bool long long, vector long long); 19594vector long long vec_vsubudm (vector long long, vector bool long long); 19595vector unsigned long long vec_vsubudm (vector unsigned long long, 19596 vector unsigned long long); 19597vector unsigned long long vec_vsubudm (vector bool long long, 19598 vector unsigned long long); 19599vector unsigned long long vec_vsubudm (vector unsigned long long, 19600 vector bool long long); 19601 19602vector long long vec_vupkhsw (vector int); 19603vector unsigned long long vec_vupkhsw (vector unsigned int); 19604 19605vector long long vec_vupklsw (vector int); 19606vector unsigned long long vec_vupklsw (vector int); 19607@end smallexample 19608 19609If the ISA 2.07 additions to the vector/scalar (power8-vector) 19610instruction set are available, the following additional functions are 19611available for 64-bit targets. New vector types 19612(@var{vector __int128} and @var{vector __uint128}) are available 19613to hold the @var{__int128} and @var{__uint128} types to use these 19614builtins. 19615 19616The normal vector extract, and set operations work on 19617@var{vector __int128} and @var{vector __uint128} types, 19618but the index value must be 0. 19619 19620@smallexample 19621vector __int128 vec_vaddcuq (vector __int128, vector __int128); 19622vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128); 19623 19624vector __int128 vec_vadduqm (vector __int128, vector __int128); 19625vector __uint128 vec_vadduqm (vector __uint128, vector __uint128); 19626 19627vector __int128 vec_vaddecuq (vector __int128, vector __int128, 19628 vector __int128); 19629vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128, 19630 vector __uint128); 19631 19632vector __int128 vec_vaddeuqm (vector __int128, vector __int128, 19633 vector __int128); 19634vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128, 19635 vector __uint128); 19636 19637vector __int128 vec_vsubecuq (vector __int128, vector __int128, 19638 vector __int128); 19639vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128, 19640 vector __uint128); 19641 19642vector __int128 vec_vsubeuqm (vector __int128, vector __int128, 19643 vector __int128); 19644vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128, 19645 vector __uint128); 19646 19647vector __int128 vec_vsubcuq (vector __int128, vector __int128); 19648vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128); 19649 19650__int128 vec_vsubuqm (__int128, __int128); 19651__uint128 vec_vsubuqm (__uint128, __uint128); 19652 19653vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int); 19654int __builtin_bcdadd_lt (vector __int128, vector __int128, const int); 19655int __builtin_bcdadd_eq (vector __int128, vector __int128, const int); 19656int __builtin_bcdadd_gt (vector __int128, vector __int128, const int); 19657int __builtin_bcdadd_ov (vector __int128, vector __int128, const int); 19658vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int); 19659int __builtin_bcdsub_lt (vector __int128, vector __int128, const int); 19660int __builtin_bcdsub_eq (vector __int128, vector __int128, const int); 19661int __builtin_bcdsub_gt (vector __int128, vector __int128, const int); 19662int __builtin_bcdsub_ov (vector __int128, vector __int128, const int); 19663@end smallexample 19664 19665@node PowerPC AltiVec Built-in Functions Available on ISA 3.0 19666@subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0 19667 19668The following additional built-in functions are also available for the 19669PowerPC family of processors, starting with ISA 3.0 19670(@option{-mcpu=power9}) or later: 19671@smallexample 19672unsigned int scalar_extract_exp (double source); 19673unsigned long long int scalar_extract_exp (__ieee128 source); 19674 19675unsigned long long int scalar_extract_sig (double source); 19676unsigned __int128 scalar_extract_sig (__ieee128 source); 19677 19678double scalar_insert_exp (unsigned long long int significand, 19679 unsigned long long int exponent); 19680double scalar_insert_exp (double significand, unsigned long long int exponent); 19681 19682ieee_128 scalar_insert_exp (unsigned __int128 significand, 19683 unsigned long long int exponent); 19684ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent); 19685 19686int scalar_cmp_exp_gt (double arg1, double arg2); 19687int scalar_cmp_exp_lt (double arg1, double arg2); 19688int scalar_cmp_exp_eq (double arg1, double arg2); 19689int scalar_cmp_exp_unordered (double arg1, double arg2); 19690 19691bool scalar_test_data_class (float source, const int condition); 19692bool scalar_test_data_class (double source, const int condition); 19693bool scalar_test_data_class (__ieee128 source, const int condition); 19694 19695bool scalar_test_neg (float source); 19696bool scalar_test_neg (double source); 19697bool scalar_test_neg (__ieee128 source); 19698@end smallexample 19699 19700The @code{scalar_extract_exp} and @code{scalar_extract_sig} 19701functions require a 64-bit environment supporting ISA 3.0 or later. 19702The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in 19703functions return the significand and the biased exponent value 19704respectively of their @code{source} arguments. 19705When supplied with a 64-bit @code{source} argument, the 19706result returned by @code{scalar_extract_sig} has 19707the @code{0x0010000000000000} bit set if the 19708function's @code{source} argument is in normalized form. 19709Otherwise, this bit is set to 0. 19710When supplied with a 128-bit @code{source} argument, the 19711@code{0x00010000000000000000000000000000} bit of the result is 19712treated similarly. 19713Note that the sign of the significand is not represented in the result 19714returned from the @code{scalar_extract_sig} function. Use the 19715@code{scalar_test_neg} function to test the sign of its @code{double} 19716argument. 19717 19718The @code{scalar_insert_exp} 19719functions require a 64-bit environment supporting ISA 3.0 or later. 19720When supplied with a 64-bit first argument, the 19721@code{scalar_insert_exp} built-in function returns a double-precision 19722floating point value that is constructed by assembling the values of its 19723@code{significand} and @code{exponent} arguments. The sign of the 19724result is copied from the most significant bit of the 19725@code{significand} argument. The significand and exponent components 19726of the result are composed of the least significant 11 bits of the 19727@code{exponent} argument and the least significant 52 bits of the 19728@code{significand} argument respectively. 19729 19730When supplied with a 128-bit first argument, the 19731@code{scalar_insert_exp} built-in function returns a quad-precision 19732ieee floating point value. The sign bit of the result is copied from 19733the most significant bit of the @code{significand} argument. 19734The significand and exponent components of the result are composed of 19735the least significant 15 bits of the @code{exponent} argument and the 19736least significant 112 bits of the @code{significand} argument respectively. 19737 19738The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt}, 19739@code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in 19740functions return a non-zero value if @code{arg1} is greater than, less 19741than, equal to, or not comparable to @code{arg2} respectively. The 19742arguments are not comparable if one or the other equals NaN (not a 19743number). 19744 19745The @code{scalar_test_data_class} built-in function returns 1 19746if any of the condition tests enabled by the value of the 19747@code{condition} variable are true, and 0 otherwise. The 19748@code{condition} argument must be a compile-time constant integer with 19749value not exceeding 127. The 19750@code{condition} argument is encoded as a bitmask with each bit 19751enabling the testing of a different condition, as characterized by the 19752following: 19753@smallexample 197540x40 Test for NaN 197550x20 Test for +Infinity 197560x10 Test for -Infinity 197570x08 Test for +Zero 197580x04 Test for -Zero 197590x02 Test for +Denormal 197600x01 Test for -Denormal 19761@end smallexample 19762 19763The @code{scalar_test_neg} built-in function returns 1 if its 19764@code{source} argument holds a negative value, 0 otherwise. 19765 19766The following built-in functions are also available for the PowerPC family 19767of processors, starting with ISA 3.0 or later 19768(@option{-mcpu=power9}). These string functions are described 19769separately in order to group the descriptions closer to the function 19770prototypes: 19771@smallexample 19772int vec_all_nez (vector signed char, vector signed char); 19773int vec_all_nez (vector unsigned char, vector unsigned char); 19774int vec_all_nez (vector signed short, vector signed short); 19775int vec_all_nez (vector unsigned short, vector unsigned short); 19776int vec_all_nez (vector signed int, vector signed int); 19777int vec_all_nez (vector unsigned int, vector unsigned int); 19778 19779int vec_any_eqz (vector signed char, vector signed char); 19780int vec_any_eqz (vector unsigned char, vector unsigned char); 19781int vec_any_eqz (vector signed short, vector signed short); 19782int vec_any_eqz (vector unsigned short, vector unsigned short); 19783int vec_any_eqz (vector signed int, vector signed int); 19784int vec_any_eqz (vector unsigned int, vector unsigned int); 19785 19786vector bool char vec_cmpnez (vector signed char arg1, vector signed char arg2); 19787vector bool char vec_cmpnez (vector unsigned char arg1, vector unsigned char arg2); 19788vector bool short vec_cmpnez (vector signed short arg1, vector signed short arg2); 19789vector bool short vec_cmpnez (vector unsigned short arg1, vector unsigned short arg2); 19790vector bool int vec_cmpnez (vector signed int arg1, vector signed int arg2); 19791vector bool int vec_cmpnez (vector unsigned int, vector unsigned int); 19792 19793vector signed char vec_cnttz (vector signed char); 19794vector unsigned char vec_cnttz (vector unsigned char); 19795vector signed short vec_cnttz (vector signed short); 19796vector unsigned short vec_cnttz (vector unsigned short); 19797vector signed int vec_cnttz (vector signed int); 19798vector unsigned int vec_cnttz (vector unsigned int); 19799vector signed long long vec_cnttz (vector signed long long); 19800vector unsigned long long vec_cnttz (vector unsigned long long); 19801 19802signed int vec_cntlz_lsbb (vector signed char); 19803signed int vec_cntlz_lsbb (vector unsigned char); 19804 19805signed int vec_cnttz_lsbb (vector signed char); 19806signed int vec_cnttz_lsbb (vector unsigned char); 19807 19808unsigned int vec_first_match_index (vector signed char, vector signed char); 19809unsigned int vec_first_match_index (vector unsigned char, vector unsigned char); 19810unsigned int vec_first_match_index (vector signed int, vector signed int); 19811unsigned int vec_first_match_index (vector unsigned int, vector unsigned int); 19812unsigned int vec_first_match_index (vector signed short, vector signed short); 19813unsigned int vec_first_match_index (vector unsigned short, vector unsigned short); 19814unsigned int vec_first_match_or_eos_index (vector signed char, vector signed char); 19815unsigned int vec_first_match_or_eos_index (vector unsigned char, vector unsigned char); 19816unsigned int vec_first_match_or_eos_index (vector signed int, vector signed int); 19817unsigned int vec_first_match_or_eos_index (vector unsigned int, vector unsigned int); 19818unsigned int vec_first_match_or_eos_index (vector signed short, vector signed short); 19819unsigned int vec_first_match_or_eos_index (vector unsigned short, 19820 vector unsigned short); 19821unsigned int vec_first_mismatch_index (vector signed char, vector signed char); 19822unsigned int vec_first_mismatch_index (vector unsigned char, vector unsigned char); 19823unsigned int vec_first_mismatch_index (vector signed int, vector signed int); 19824unsigned int vec_first_mismatch_index (vector unsigned int, vector unsigned int); 19825unsigned int vec_first_mismatch_index (vector signed short, vector signed short); 19826unsigned int vec_first_mismatch_index (vector unsigned short, vector unsigned short); 19827unsigned int vec_first_mismatch_or_eos_index (vector signed char, vector signed char); 19828unsigned int vec_first_mismatch_or_eos_index (vector unsigned char, 19829 vector unsigned char); 19830unsigned int vec_first_mismatch_or_eos_index (vector signed int, vector signed int); 19831unsigned int vec_first_mismatch_or_eos_index (vector unsigned int, vector unsigned int); 19832unsigned int vec_first_mismatch_or_eos_index (vector signed short, vector signed short); 19833unsigned int vec_first_mismatch_or_eos_index (vector unsigned short, 19834 vector unsigned short); 19835 19836vector unsigned short vec_pack_to_short_fp32 (vector float, vector float); 19837 19838vector signed char vec_xl_be (signed long long, signed char *); 19839vector unsigned char vec_xl_be (signed long long, unsigned char *); 19840vector signed int vec_xl_be (signed long long, signed int *); 19841vector unsigned int vec_xl_be (signed long long, unsigned int *); 19842vector signed __int128 vec_xl_be (signed long long, signed __int128 *); 19843vector unsigned __int128 vec_xl_be (signed long long, unsigned __int128 *); 19844vector signed long long vec_xl_be (signed long long, signed long long *); 19845vector unsigned long long vec_xl_be (signed long long, unsigned long long *); 19846vector signed short vec_xl_be (signed long long, signed short *); 19847vector unsigned short vec_xl_be (signed long long, unsigned short *); 19848vector double vec_xl_be (signed long long, double *); 19849vector float vec_xl_be (signed long long, float *); 19850 19851vector signed char vec_xl_len (signed char *addr, size_t len); 19852vector unsigned char vec_xl_len (unsigned char *addr, size_t len); 19853vector signed int vec_xl_len (signed int *addr, size_t len); 19854vector unsigned int vec_xl_len (unsigned int *addr, size_t len); 19855vector signed __int128 vec_xl_len (signed __int128 *addr, size_t len); 19856vector unsigned __int128 vec_xl_len (unsigned __int128 *addr, size_t len); 19857vector signed long long vec_xl_len (signed long long *addr, size_t len); 19858vector unsigned long long vec_xl_len (unsigned long long *addr, size_t len); 19859vector signed short vec_xl_len (signed short *addr, size_t len); 19860vector unsigned short vec_xl_len (unsigned short *addr, size_t len); 19861vector double vec_xl_len (double *addr, size_t len); 19862vector float vec_xl_len (float *addr, size_t len); 19863 19864vector unsigned char vec_xl_len_r (unsigned char *addr, size_t len); 19865 19866void vec_xst_len (vector signed char data, signed char *addr, size_t len); 19867void vec_xst_len (vector unsigned char data, unsigned char *addr, size_t len); 19868void vec_xst_len (vector signed int data, signed int *addr, size_t len); 19869void vec_xst_len (vector unsigned int data, unsigned int *addr, size_t len); 19870void vec_xst_len (vector unsigned __int128 data, unsigned __int128 *addr, size_t len); 19871void vec_xst_len (vector signed long long data, signed long long *addr, size_t len); 19872void vec_xst_len (vector unsigned long long data, unsigned long long *addr, size_t len); 19873void vec_xst_len (vector signed short data, signed short *addr, size_t len); 19874void vec_xst_len (vector unsigned short data, unsigned short *addr, size_t len); 19875void vec_xst_len (vector signed __int128 data, signed __int128 *addr, size_t len); 19876void vec_xst_len (vector double data, double *addr, size_t len); 19877void vec_xst_len (vector float data, float *addr, size_t len); 19878 19879void vec_xst_len_r (vector unsigned char data, unsigned char *addr, size_t len); 19880 19881signed char vec_xlx (unsigned int index, vector signed char data); 19882unsigned char vec_xlx (unsigned int index, vector unsigned char data); 19883signed short vec_xlx (unsigned int index, vector signed short data); 19884unsigned short vec_xlx (unsigned int index, vector unsigned short data); 19885signed int vec_xlx (unsigned int index, vector signed int data); 19886unsigned int vec_xlx (unsigned int index, vector unsigned int data); 19887float vec_xlx (unsigned int index, vector float data); 19888 19889signed char vec_xrx (unsigned int index, vector signed char data); 19890unsigned char vec_xrx (unsigned int index, vector unsigned char data); 19891signed short vec_xrx (unsigned int index, vector signed short data); 19892unsigned short vec_xrx (unsigned int index, vector unsigned short data); 19893signed int vec_xrx (unsigned int index, vector signed int data); 19894unsigned int vec_xrx (unsigned int index, vector unsigned int data); 19895float vec_xrx (unsigned int index, vector float data); 19896@end smallexample 19897 19898The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez} 19899perform pairwise comparisons between the elements at the same 19900positions within their two vector arguments. 19901The @code{vec_all_nez} function returns a 19902non-zero value if and only if all pairwise comparisons are not 19903equal and no element of either vector argument contains a zero. 19904The @code{vec_any_eqz} function returns a 19905non-zero value if and only if at least one pairwise comparison is equal 19906or if at least one element of either vector argument contains a zero. 19907The @code{vec_cmpnez} function returns a vector of the same type as 19908its two arguments, within which each element consists of all ones to 19909denote that either the corresponding elements of the incoming arguments are 19910not equal or that at least one of the corresponding elements contains 19911zero. Otherwise, the element of the returned vector contains all zeros. 19912 19913The @code{vec_cntlz_lsbb} function returns the count of the number of 19914consecutive leading byte elements (starting from position 0 within the 19915supplied vector argument) for which the least-significant bit 19916equals zero. The @code{vec_cnttz_lsbb} function returns the count of 19917the number of consecutive trailing byte elements (starting from 19918position 15 and counting backwards within the supplied vector 19919argument) for which the least-significant bit equals zero. 19920 19921The @code{vec_xl_len} and @code{vec_xst_len} functions require a 1992264-bit environment supporting ISA 3.0 or later. The @code{vec_xl_len} 19923function loads a variable length vector from memory. The 19924@code{vec_xst_len} function stores a variable length vector to memory. 19925With both the @code{vec_xl_len} and @code{vec_xst_len} functions, the 19926@code{addr} argument represents the memory address to or from which 19927data will be transferred, and the 19928@code{len} argument represents the number of bytes to be 19929transferred, as computed by the C expression @code{min((len & 0xff), 16)}. 19930If this expression's value is not a multiple of the vector element's 19931size, the behavior of this function is undefined. 19932In the case that the underlying computer is configured to run in 19933big-endian mode, the data transfer moves bytes 0 to @code{(len - 1)} of 19934the corresponding vector. In little-endian mode, the data transfer 19935moves bytes @code{(16 - len)} to @code{15} of the corresponding 19936vector. For the load function, any bytes of the result vector that 19937are not loaded from memory are set to zero. 19938The value of the @code{addr} argument need not be aligned on a 19939multiple of the vector's element size. 19940 19941The @code{vec_xlx} and @code{vec_xrx} functions extract the single 19942element selected by the @code{index} argument from the vector 19943represented by the @code{data} argument. The @code{index} argument 19944always specifies a byte offset, regardless of the size of the vector 19945element. With @code{vec_xlx}, @code{index} is the offset of the first 19946byte of the element to be extracted. With @code{vec_xrx}, @code{index} 19947represents the last byte of the element to be extracted, measured 19948from the right end of the vector. In other words, the last byte of 19949the element to be extracted is found at position @code{(15 - index)}. 19950There is no requirement that @code{index} be a multiple of the vector 19951element size. However, if the size of the vector element added to 19952@code{index} is greater than 15, the content of the returned value is 19953undefined. 19954 19955If the ISA 3.0 instruction set additions (@option{-mcpu=power9}) 19956are available: 19957 19958@smallexample 19959vector unsigned long long vec_bperm (vector unsigned long long, vector unsigned char); 19960 19961vector bool char vec_cmpne (vector bool char, vector bool char); 19962vector bool char vec_cmpne (vector signed char, vector signed char); 19963vector bool char vec_cmpne (vector unsigned char, vector unsigned char); 19964vector bool int vec_cmpne (vector bool int, vector bool int); 19965vector bool int vec_cmpne (vector signed int, vector signed int); 19966vector bool int vec_cmpne (vector unsigned int, vector unsigned int); 19967vector bool long long vec_cmpne (vector bool long long, vector bool long long); 19968vector bool long long vec_cmpne (vector signed long long, vector signed long long); 19969vector bool long long vec_cmpne (vector unsigned long long, vector unsigned long long); 19970vector bool short vec_cmpne (vector bool short, vector bool short); 19971vector bool short vec_cmpne (vector signed short, vector signed short); 19972vector bool short vec_cmpne (vector unsigned short, vector unsigned short); 19973vector bool long long vec_cmpne (vector double, vector double); 19974vector bool int vec_cmpne (vector float, vector float); 19975 19976vector float vec_extract_fp32_from_shorth (vector unsigned short); 19977vector float vec_extract_fp32_from_shortl (vector unsigned short); 19978 19979vector long long vec_vctz (vector long long); 19980vector unsigned long long vec_vctz (vector unsigned long long); 19981vector int vec_vctz (vector int); 19982vector unsigned int vec_vctz (vector int); 19983vector short vec_vctz (vector short); 19984vector unsigned short vec_vctz (vector unsigned short); 19985vector signed char vec_vctz (vector signed char); 19986vector unsigned char vec_vctz (vector unsigned char); 19987 19988vector signed char vec_vctzb (vector signed char); 19989vector unsigned char vec_vctzb (vector unsigned char); 19990 19991vector long long vec_vctzd (vector long long); 19992vector unsigned long long vec_vctzd (vector unsigned long long); 19993 19994vector short vec_vctzh (vector short); 19995vector unsigned short vec_vctzh (vector unsigned short); 19996 19997vector int vec_vctzw (vector int); 19998vector unsigned int vec_vctzw (vector int); 19999 20000vector unsigned long long vec_extract4b (vector unsigned char, const int); 20001 20002vector unsigned char vec_insert4b (vector signed int, vector unsigned char, 20003 const int); 20004vector unsigned char vec_insert4b (vector unsigned int, vector unsigned char, 20005 const int); 20006 20007vector unsigned int vec_parity_lsbb (vector signed int); 20008vector unsigned int vec_parity_lsbb (vector unsigned int); 20009vector unsigned __int128 vec_parity_lsbb (vector signed __int128); 20010vector unsigned __int128 vec_parity_lsbb (vector unsigned __int128); 20011vector unsigned long long vec_parity_lsbb (vector signed long long); 20012vector unsigned long long vec_parity_lsbb (vector unsigned long long); 20013 20014vector int vec_vprtyb (vector int); 20015vector unsigned int vec_vprtyb (vector unsigned int); 20016vector long long vec_vprtyb (vector long long); 20017vector unsigned long long vec_vprtyb (vector unsigned long long); 20018 20019vector int vec_vprtybw (vector int); 20020vector unsigned int vec_vprtybw (vector unsigned int); 20021 20022vector long long vec_vprtybd (vector long long); 20023vector unsigned long long vec_vprtybd (vector unsigned long long); 20024@end smallexample 20025 20026On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9}) 20027are available: 20028 20029@smallexample 20030vector long vec_vprtyb (vector long); 20031vector unsigned long vec_vprtyb (vector unsigned long); 20032vector __int128 vec_vprtyb (vector __int128); 20033vector __uint128 vec_vprtyb (vector __uint128); 20034 20035vector long vec_vprtybd (vector long); 20036vector unsigned long vec_vprtybd (vector unsigned long); 20037 20038vector __int128 vec_vprtybq (vector __int128); 20039vector __uint128 vec_vprtybd (vector __uint128); 20040@end smallexample 20041 20042The following built-in vector functions are available for the PowerPC family 20043of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): 20044@smallexample 20045__vector unsigned char 20046vec_slv (__vector unsigned char src, __vector unsigned char shift_distance); 20047__vector unsigned char 20048vec_srv (__vector unsigned char src, __vector unsigned char shift_distance); 20049@end smallexample 20050 20051The @code{vec_slv} and @code{vec_srv} functions operate on 20052all of the bytes of their @code{src} and @code{shift_distance} 20053arguments in parallel. The behavior of the @code{vec_slv} is as if 20054there existed a temporary array of 17 unsigned characters 20055@code{slv_array} within which elements 0 through 15 are the same as 20056the entries in the @code{src} array and element 16 equals 0. The 20057result returned from the @code{vec_slv} function is a 20058@code{__vector} of 16 unsigned characters within which element 20059@code{i} is computed using the C expression 20060@code{0xff & (*((unsigned short *)(slv_array + i)) << (0x07 & 20061shift_distance[i]))}, 20062with this resulting value coerced to the @code{unsigned char} type. 20063The behavior of the @code{vec_srv} is as if 20064there existed a temporary array of 17 unsigned characters 20065@code{srv_array} within which element 0 equals zero and 20066elements 1 through 16 equal the elements 0 through 15 of 20067the @code{src} array. The 20068result returned from the @code{vec_srv} function is a 20069@code{__vector} of 16 unsigned characters within which element 20070@code{i} is computed using the C expression 20071@code{0xff & (*((unsigned short *)(srv_array + i)) >> 20072(0x07 & shift_distance[i]))}, 20073with this resulting value coerced to the @code{unsigned char} type. 20074 20075The following built-in functions are available for the PowerPC family 20076of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): 20077@smallexample 20078__vector unsigned char 20079vec_absd (__vector unsigned char arg1, __vector unsigned char arg2); 20080__vector unsigned short 20081vec_absd (__vector unsigned short arg1, __vector unsigned short arg2); 20082__vector unsigned int 20083vec_absd (__vector unsigned int arg1, __vector unsigned int arg2); 20084 20085__vector unsigned char 20086vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2); 20087__vector unsigned short 20088vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2); 20089__vector unsigned int 20090vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2); 20091@end smallexample 20092 20093The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and 20094@code{vec_absdw} built-in functions each computes the absolute 20095differences of the pairs of vector elements supplied in its two vector 20096arguments, placing the absolute differences into the corresponding 20097elements of the vector result. 20098 20099The following built-in functions are available for the PowerPC family 20100of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): 20101@smallexample 20102__vector unsigned int vec_extract_exp (__vector float source); 20103__vector unsigned long long int vec_extract_exp (__vector double source); 20104 20105__vector unsigned int vec_extract_sig (__vector float source); 20106__vector unsigned long long int vec_extract_sig (__vector double source); 20107 20108__vector float vec_insert_exp (__vector unsigned int significands, 20109 __vector unsigned int exponents); 20110__vector float vec_insert_exp (__vector unsigned float significands, 20111 __vector unsigned int exponents); 20112__vector double vec_insert_exp (__vector unsigned long long int significands, 20113 __vector unsigned long long int exponents); 20114__vector double vec_insert_exp (__vector unsigned double significands, 20115 __vector unsigned long long int exponents); 20116 20117__vector bool int vec_test_data_class (__vector float source, const int condition); 20118__vector bool long long int vec_test_data_class (__vector double source, 20119 const int condition); 20120@end smallexample 20121 20122The @code{vec_extract_sig} and @code{vec_extract_exp} built-in 20123functions return vectors representing the significands and biased 20124exponent values of their @code{source} arguments respectively. 20125Within the result vector returned by @code{vec_extract_sig}, the 20126@code{0x800000} bit of each vector element returned when the 20127function's @code{source} argument is of type @code{float} is set to 1 20128if the corresponding floating point value is in normalized form. 20129Otherwise, this bit is set to 0. When the @code{source} argument is 20130of type @code{double}, the @code{0x10000000000000} bit within each of 20131the result vector's elements is set according to the same rules. 20132Note that the sign of the significand is not represented in the result 20133returned from the @code{vec_extract_sig} function. To extract the 20134sign bits, use the 20135@code{vec_cpsgn} function, which returns a new vector within which all 20136of the sign bits of its second argument vector are overwritten with the 20137sign bits copied from the coresponding elements of its first argument 20138vector, and all other (non-sign) bits of the second argument vector 20139are copied unchanged into the result vector. 20140 20141The @code{vec_insert_exp} built-in functions return a vector of 20142single- or double-precision floating 20143point values constructed by assembling the values of their 20144@code{significands} and @code{exponents} arguments into the 20145corresponding elements of the returned vector. 20146The sign of each 20147element of the result is copied from the most significant bit of the 20148corresponding entry within the @code{significands} argument. 20149Note that the relevant 20150bits of the @code{significands} argument are the same, for both integer 20151and floating point types. 20152The 20153significand and exponent components of each element of the result are 20154composed of the least significant bits of the corresponding 20155@code{significands} element and the least significant bits of the 20156corresponding @code{exponents} element. 20157 20158The @code{vec_test_data_class} built-in function returns a vector 20159representing the results of testing the @code{source} vector for the 20160condition selected by the @code{condition} argument. The 20161@code{condition} argument must be a compile-time constant integer with 20162value not exceeding 127. The 20163@code{condition} argument is encoded as a bitmask with each bit 20164enabling the testing of a different condition, as characterized by the 20165following: 20166@smallexample 201670x40 Test for NaN 201680x20 Test for +Infinity 201690x10 Test for -Infinity 201700x08 Test for +Zero 201710x04 Test for -Zero 201720x02 Test for +Denormal 201730x01 Test for -Denormal 20174@end smallexample 20175 20176If any of the enabled test conditions is true, the corresponding entry 20177in the result vector is -1. Otherwise (all of the enabled test 20178conditions are false), the corresponding entry of the result vector is 0. 20179 20180The following built-in functions are available for the PowerPC family 20181of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): 20182@smallexample 20183vector unsigned int vec_rlmi (vector unsigned int, vector unsigned int, 20184 vector unsigned int); 20185vector unsigned long long vec_rlmi (vector unsigned long long, 20186 vector unsigned long long, 20187 vector unsigned long long); 20188vector unsigned int vec_rlnm (vector unsigned int, vector unsigned int, 20189 vector unsigned int); 20190vector unsigned long long vec_rlnm (vector unsigned long long, 20191 vector unsigned long long, 20192 vector unsigned long long); 20193vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int); 20194vector unsigned long long vec_vrlnm (vector unsigned long long, 20195 vector unsigned long long); 20196@end smallexample 20197 20198The result of @code{vec_rlmi} is obtained by rotating each element of 20199the first argument vector left and inserting it under mask into the 20200second argument vector. The third argument vector contains the mask 20201beginning in bits 11:15, the mask end in bits 19:23, and the shift 20202count in bits 27:31, of each element. 20203 20204The result of @code{vec_rlnm} is obtained by rotating each element of 20205the first argument vector left and ANDing it with a mask specified by 20206the second and third argument vectors. The second argument vector 20207contains the shift count for each element in the low-order byte. The 20208third argument vector contains the mask end for each element in the 20209low-order byte, with the mask begin in the next higher byte. 20210 20211The result of @code{vec_vrlnm} is obtained by rotating each element 20212of the first argument vector left and ANDing it with a mask. The 20213second argument vector contains the mask beginning in bits 11:15, 20214the mask end in bits 19:23, and the shift count in bits 27:31, 20215of each element. 20216 20217If the ISA 3.0 instruction set additions (@option{-mcpu=power9}) 20218are available: 20219@smallexample 20220vector signed bool char vec_revb (vector signed char); 20221vector signed char vec_revb (vector signed char); 20222vector unsigned char vec_revb (vector unsigned char); 20223vector bool short vec_revb (vector bool short); 20224vector short vec_revb (vector short); 20225vector unsigned short vec_revb (vector unsigned short); 20226vector bool int vec_revb (vector bool int); 20227vector int vec_revb (vector int); 20228vector unsigned int vec_revb (vector unsigned int); 20229vector float vec_revb (vector float); 20230vector bool long long vec_revb (vector bool long long); 20231vector long long vec_revb (vector long long); 20232vector unsigned long long vec_revb (vector unsigned long long); 20233vector double vec_revb (vector double); 20234@end smallexample 20235 20236On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9}) 20237are available: 20238@smallexample 20239vector long vec_revb (vector long); 20240vector unsigned long vec_revb (vector unsigned long); 20241vector __int128 vec_revb (vector __int128); 20242vector __uint128 vec_revb (vector __uint128); 20243@end smallexample 20244 20245The @code{vec_revb} built-in function reverses the bytes on an element 20246by element basis. A vector of @code{vector unsigned char} or 20247@code{vector signed char} reverses the bytes in the whole word. 20248 20249If the cryptographic instructions are enabled (@option{-mcrypto} or 20250@option{-mcpu=power8}), the following builtins are enabled. 20251 20252@smallexample 20253vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long); 20254 20255vector unsigned char vec_sbox_be (vector unsigned char); 20256 20257vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long, 20258 vector unsigned long long); 20259 20260vector unsigned char vec_cipher_be (vector unsigned char, vector unsigned char); 20261 20262vector unsigned long long __builtin_crypto_vcipherlast 20263 (vector unsigned long long, 20264 vector unsigned long long); 20265 20266vector unsigned char vec_cipherlast_be (vector unsigned char, 20267 vector unsigned char); 20268 20269vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long, 20270 vector unsigned long long); 20271 20272vector unsigned char vec_ncipher_be (vector unsigned char, 20273 vector unsigned char); 20274 20275vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long, 20276 vector unsigned long long); 20277 20278vector unsigned char vec_ncipherlast_be (vector unsigned char, 20279 vector unsigned char); 20280 20281vector unsigned char __builtin_crypto_vpermxor (vector unsigned char, 20282 vector unsigned char, 20283 vector unsigned char); 20284 20285vector unsigned short __builtin_crypto_vpermxor (vector unsigned short, 20286 vector unsigned short, 20287 vector unsigned short); 20288 20289vector unsigned int __builtin_crypto_vpermxor (vector unsigned int, 20290 vector unsigned int, 20291 vector unsigned int); 20292 20293vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long, 20294 vector unsigned long long, 20295 vector unsigned long long); 20296 20297vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char, 20298 vector unsigned char); 20299 20300vector unsigned short __builtin_crypto_vpmsumb (vector unsigned short, 20301 vector unsigned short); 20302 20303vector unsigned int __builtin_crypto_vpmsumb (vector unsigned int, 20304 vector unsigned int); 20305 20306vector unsigned long long __builtin_crypto_vpmsumb (vector unsigned long long, 20307 vector unsigned long long); 20308 20309vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long, 20310 int, int); 20311 20312vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int); 20313@end smallexample 20314 20315The second argument to @var{__builtin_crypto_vshasigmad} and 20316@var{__builtin_crypto_vshasigmaw} must be a constant 20317integer that is 0 or 1. The third argument to these built-in functions 20318must be a constant integer in the range of 0 to 15. 20319 20320If the ISA 3.0 instruction set additions 20321are enabled (@option{-mcpu=power9}), the following additional 20322functions are available for both 32-bit and 64-bit targets. 20323@smallexample 20324vector short vec_xl (int, vector short *); 20325vector short vec_xl (int, short *); 20326vector unsigned short vec_xl (int, vector unsigned short *); 20327vector unsigned short vec_xl (int, unsigned short *); 20328vector char vec_xl (int, vector char *); 20329vector char vec_xl (int, char *); 20330vector unsigned char vec_xl (int, vector unsigned char *); 20331vector unsigned char vec_xl (int, unsigned char *); 20332 20333void vec_xst (vector short, int, vector short *); 20334void vec_xst (vector short, int, short *); 20335void vec_xst (vector unsigned short, int, vector unsigned short *); 20336void vec_xst (vector unsigned short, int, unsigned short *); 20337void vec_xst (vector char, int, vector char *); 20338void vec_xst (vector char, int, char *); 20339void vec_xst (vector unsigned char, int, vector unsigned char *); 20340void vec_xst (vector unsigned char, int, unsigned char *); 20341@end smallexample 20342@node PowerPC Hardware Transactional Memory Built-in Functions 20343@subsection PowerPC Hardware Transactional Memory Built-in Functions 20344GCC provides two interfaces for accessing the Hardware Transactional 20345Memory (HTM) instructions available on some of the PowerPC family 20346of processors (eg, POWER8). The two interfaces come in a low level 20347interface, consisting of built-in functions specific to PowerPC and a 20348higher level interface consisting of inline functions that are common 20349between PowerPC and S/390. 20350 20351@subsubsection PowerPC HTM Low Level Built-in Functions 20352 20353The following low level built-in functions are available with 20354@option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later. 20355They all generate the machine instruction that is part of the name. 20356 20357The HTM builtins (with the exception of @code{__builtin_tbegin}) return 20358the full 4-bit condition register value set by their associated hardware 20359instruction. The header file @code{htmintrin.h} defines some macros that can 20360be used to decipher the return value. The @code{__builtin_tbegin} builtin 20361returns a simple @code{true} or @code{false} value depending on whether a transaction was 20362successfully started or not. The arguments of the builtins match exactly the 20363type and order of the associated hardware instruction's operands, except for 20364the @code{__builtin_tcheck} builtin, which does not take any input arguments. 20365Refer to the ISA manual for a description of each instruction's operands. 20366 20367@smallexample 20368unsigned int __builtin_tbegin (unsigned int) 20369unsigned int __builtin_tend (unsigned int) 20370 20371unsigned int __builtin_tabort (unsigned int) 20372unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int) 20373unsigned int __builtin_tabortdci (unsigned int, unsigned int, int) 20374unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int) 20375unsigned int __builtin_tabortwci (unsigned int, unsigned int, int) 20376 20377unsigned int __builtin_tcheck (void) 20378unsigned int __builtin_treclaim (unsigned int) 20379unsigned int __builtin_trechkpt (void) 20380unsigned int __builtin_tsr (unsigned int) 20381@end smallexample 20382 20383In addition to the above HTM built-ins, we have added built-ins for 20384some common extended mnemonics of the HTM instructions: 20385 20386@smallexample 20387unsigned int __builtin_tendall (void) 20388unsigned int __builtin_tresume (void) 20389unsigned int __builtin_tsuspend (void) 20390@end smallexample 20391 20392Note that the semantics of the above HTM builtins are required to mimic 20393the locking semantics used for critical sections. Builtins that are used 20394to create a new transaction or restart a suspended transaction must have 20395lock acquisition like semantics while those builtins that end or suspend a 20396transaction must have lock release like semantics. Specifically, this must 20397mimic lock semantics as specified by C++11, for example: Lock acquisition is 20398as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE) 20399that returns 0, and lock release is as-if an execution of 20400__atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an 20401implicit implementation-defined lock used for all transactions. The HTM 20402instructions associated with with the builtins inherently provide the 20403correct acquisition and release hardware barriers required. However, 20404the compiler must also be prohibited from moving loads and stores across 20405the builtins in a way that would violate their semantics. This has been 20406accomplished by adding memory barriers to the associated HTM instructions 20407(which is a conservative approach to provide acquire and release semantics). 20408Earlier versions of the compiler did not treat the HTM instructions as 20409memory barriers. A @code{__TM_FENCE__} macro has been added, which can 20410be used to determine whether the current compiler treats HTM instructions 20411as memory barriers or not. This allows the user to explicitly add memory 20412barriers to their code when using an older version of the compiler. 20413 20414The following set of built-in functions are available to gain access 20415to the HTM specific special purpose registers. 20416 20417@smallexample 20418unsigned long __builtin_get_texasr (void) 20419unsigned long __builtin_get_texasru (void) 20420unsigned long __builtin_get_tfhar (void) 20421unsigned long __builtin_get_tfiar (void) 20422 20423void __builtin_set_texasr (unsigned long); 20424void __builtin_set_texasru (unsigned long); 20425void __builtin_set_tfhar (unsigned long); 20426void __builtin_set_tfiar (unsigned long); 20427@end smallexample 20428 20429Example usage of these low level built-in functions may look like: 20430 20431@smallexample 20432#include <htmintrin.h> 20433 20434int num_retries = 10; 20435 20436while (1) 20437 @{ 20438 if (__builtin_tbegin (0)) 20439 @{ 20440 /* Transaction State Initiated. */ 20441 if (is_locked (lock)) 20442 __builtin_tabort (0); 20443 ... transaction code... 20444 __builtin_tend (0); 20445 break; 20446 @} 20447 else 20448 @{ 20449 /* Transaction State Failed. Use locks if the transaction 20450 failure is "persistent" or we've tried too many times. */ 20451 if (num_retries-- <= 0 20452 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ())) 20453 @{ 20454 acquire_lock (lock); 20455 ... non transactional fallback path... 20456 release_lock (lock); 20457 break; 20458 @} 20459 @} 20460 @} 20461@end smallexample 20462 20463One final built-in function has been added that returns the value of 20464the 2-bit Transaction State field of the Machine Status Register (MSR) 20465as stored in @code{CR0}. 20466 20467@smallexample 20468unsigned long __builtin_ttest (void) 20469@end smallexample 20470 20471This built-in can be used to determine the current transaction state 20472using the following code example: 20473 20474@smallexample 20475#include <htmintrin.h> 20476 20477unsigned char tx_state = _HTM_STATE (__builtin_ttest ()); 20478 20479if (tx_state == _HTM_TRANSACTIONAL) 20480 @{ 20481 /* Code to use in transactional state. */ 20482 @} 20483else if (tx_state == _HTM_NONTRANSACTIONAL) 20484 @{ 20485 /* Code to use in non-transactional state. */ 20486 @} 20487else if (tx_state == _HTM_SUSPENDED) 20488 @{ 20489 /* Code to use in transaction suspended state. */ 20490 @} 20491@end smallexample 20492 20493@subsubsection PowerPC HTM High Level Inline Functions 20494 20495The following high level HTM interface is made available by including 20496@code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU} 20497where CPU is `power8' or later. This interface is common between PowerPC 20498and S/390, allowing users to write one HTM source implementation that 20499can be compiled and executed on either system. 20500 20501@smallexample 20502long __TM_simple_begin (void) 20503long __TM_begin (void* const TM_buff) 20504long __TM_end (void) 20505void __TM_abort (void) 20506void __TM_named_abort (unsigned char const code) 20507void __TM_resume (void) 20508void __TM_suspend (void) 20509 20510long __TM_is_user_abort (void* const TM_buff) 20511long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code) 20512long __TM_is_illegal (void* const TM_buff) 20513long __TM_is_footprint_exceeded (void* const TM_buff) 20514long __TM_nesting_depth (void* const TM_buff) 20515long __TM_is_nested_too_deep(void* const TM_buff) 20516long __TM_is_conflict(void* const TM_buff) 20517long __TM_is_failure_persistent(void* const TM_buff) 20518long __TM_failure_address(void* const TM_buff) 20519long long __TM_failure_code(void* const TM_buff) 20520@end smallexample 20521 20522Using these common set of HTM inline functions, we can create 20523a more portable version of the HTM example in the previous 20524section that will work on either PowerPC or S/390: 20525 20526@smallexample 20527#include <htmxlintrin.h> 20528 20529int num_retries = 10; 20530TM_buff_type TM_buff; 20531 20532while (1) 20533 @{ 20534 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED) 20535 @{ 20536 /* Transaction State Initiated. */ 20537 if (is_locked (lock)) 20538 __TM_abort (); 20539 ... transaction code... 20540 __TM_end (); 20541 break; 20542 @} 20543 else 20544 @{ 20545 /* Transaction State Failed. Use locks if the transaction 20546 failure is "persistent" or we've tried too many times. */ 20547 if (num_retries-- <= 0 20548 || __TM_is_failure_persistent (TM_buff)) 20549 @{ 20550 acquire_lock (lock); 20551 ... non transactional fallback path... 20552 release_lock (lock); 20553 break; 20554 @} 20555 @} 20556 @} 20557@end smallexample 20558 20559@node PowerPC Atomic Memory Operation Functions 20560@subsection PowerPC Atomic Memory Operation Functions 20561ISA 3.0 of the PowerPC added new atomic memory operation (amo) 20562instructions. GCC provides support for these instructions in 64-bit 20563environments. All of the functions are declared in the include file 20564@code{amo.h}. 20565 20566The functions supported are: 20567 20568@smallexample 20569#include <amo.h> 20570 20571uint32_t amo_lwat_add (uint32_t *, uint32_t); 20572uint32_t amo_lwat_xor (uint32_t *, uint32_t); 20573uint32_t amo_lwat_ior (uint32_t *, uint32_t); 20574uint32_t amo_lwat_and (uint32_t *, uint32_t); 20575uint32_t amo_lwat_umax (uint32_t *, uint32_t); 20576uint32_t amo_lwat_umin (uint32_t *, uint32_t); 20577uint32_t amo_lwat_swap (uint32_t *, uint32_t); 20578 20579int32_t amo_lwat_sadd (int32_t *, int32_t); 20580int32_t amo_lwat_smax (int32_t *, int32_t); 20581int32_t amo_lwat_smin (int32_t *, int32_t); 20582int32_t amo_lwat_sswap (int32_t *, int32_t); 20583 20584uint64_t amo_ldat_add (uint64_t *, uint64_t); 20585uint64_t amo_ldat_xor (uint64_t *, uint64_t); 20586uint64_t amo_ldat_ior (uint64_t *, uint64_t); 20587uint64_t amo_ldat_and (uint64_t *, uint64_t); 20588uint64_t amo_ldat_umax (uint64_t *, uint64_t); 20589uint64_t amo_ldat_umin (uint64_t *, uint64_t); 20590uint64_t amo_ldat_swap (uint64_t *, uint64_t); 20591 20592int64_t amo_ldat_sadd (int64_t *, int64_t); 20593int64_t amo_ldat_smax (int64_t *, int64_t); 20594int64_t amo_ldat_smin (int64_t *, int64_t); 20595int64_t amo_ldat_sswap (int64_t *, int64_t); 20596 20597void amo_stwat_add (uint32_t *, uint32_t); 20598void amo_stwat_xor (uint32_t *, uint32_t); 20599void amo_stwat_ior (uint32_t *, uint32_t); 20600void amo_stwat_and (uint32_t *, uint32_t); 20601void amo_stwat_umax (uint32_t *, uint32_t); 20602void amo_stwat_umin (uint32_t *, uint32_t); 20603 20604void amo_stwat_sadd (int32_t *, int32_t); 20605void amo_stwat_smax (int32_t *, int32_t); 20606void amo_stwat_smin (int32_t *, int32_t); 20607 20608void amo_stdat_add (uint64_t *, uint64_t); 20609void amo_stdat_xor (uint64_t *, uint64_t); 20610void amo_stdat_ior (uint64_t *, uint64_t); 20611void amo_stdat_and (uint64_t *, uint64_t); 20612void amo_stdat_umax (uint64_t *, uint64_t); 20613void amo_stdat_umin (uint64_t *, uint64_t); 20614 20615void amo_stdat_sadd (int64_t *, int64_t); 20616void amo_stdat_smax (int64_t *, int64_t); 20617void amo_stdat_smin (int64_t *, int64_t); 20618@end smallexample 20619 20620@node RX Built-in Functions 20621@subsection RX Built-in Functions 20622GCC supports some of the RX instructions which cannot be expressed in 20623the C programming language via the use of built-in functions. The 20624following functions are supported: 20625 20626@deftypefn {Built-in Function} void __builtin_rx_brk (void) 20627Generates the @code{brk} machine instruction. 20628@end deftypefn 20629 20630@deftypefn {Built-in Function} void __builtin_rx_clrpsw (int) 20631Generates the @code{clrpsw} machine instruction to clear the specified 20632bit in the processor status word. 20633@end deftypefn 20634 20635@deftypefn {Built-in Function} void __builtin_rx_int (int) 20636Generates the @code{int} machine instruction to generate an interrupt 20637with the specified value. 20638@end deftypefn 20639 20640@deftypefn {Built-in Function} void __builtin_rx_machi (int, int) 20641Generates the @code{machi} machine instruction to add the result of 20642multiplying the top 16 bits of the two arguments into the 20643accumulator. 20644@end deftypefn 20645 20646@deftypefn {Built-in Function} void __builtin_rx_maclo (int, int) 20647Generates the @code{maclo} machine instruction to add the result of 20648multiplying the bottom 16 bits of the two arguments into the 20649accumulator. 20650@end deftypefn 20651 20652@deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int) 20653Generates the @code{mulhi} machine instruction to place the result of 20654multiplying the top 16 bits of the two arguments into the 20655accumulator. 20656@end deftypefn 20657 20658@deftypefn {Built-in Function} void __builtin_rx_mullo (int, int) 20659Generates the @code{mullo} machine instruction to place the result of 20660multiplying the bottom 16 bits of the two arguments into the 20661accumulator. 20662@end deftypefn 20663 20664@deftypefn {Built-in Function} int __builtin_rx_mvfachi (void) 20665Generates the @code{mvfachi} machine instruction to read the top 2066632 bits of the accumulator. 20667@end deftypefn 20668 20669@deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void) 20670Generates the @code{mvfacmi} machine instruction to read the middle 2067132 bits of the accumulator. 20672@end deftypefn 20673 20674@deftypefn {Built-in Function} int __builtin_rx_mvfc (int) 20675Generates the @code{mvfc} machine instruction which reads the control 20676register specified in its argument and returns its value. 20677@end deftypefn 20678 20679@deftypefn {Built-in Function} void __builtin_rx_mvtachi (int) 20680Generates the @code{mvtachi} machine instruction to set the top 2068132 bits of the accumulator. 20682@end deftypefn 20683 20684@deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int) 20685Generates the @code{mvtaclo} machine instruction to set the bottom 2068632 bits of the accumulator. 20687@end deftypefn 20688 20689@deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val) 20690Generates the @code{mvtc} machine instruction which sets control 20691register number @code{reg} to @code{val}. 20692@end deftypefn 20693 20694@deftypefn {Built-in Function} void __builtin_rx_mvtipl (int) 20695Generates the @code{mvtipl} machine instruction set the interrupt 20696priority level. 20697@end deftypefn 20698 20699@deftypefn {Built-in Function} void __builtin_rx_racw (int) 20700Generates the @code{racw} machine instruction to round the accumulator 20701according to the specified mode. 20702@end deftypefn 20703 20704@deftypefn {Built-in Function} int __builtin_rx_revw (int) 20705Generates the @code{revw} machine instruction which swaps the bytes in 20706the argument so that bits 0--7 now occupy bits 8--15 and vice versa, 20707and also bits 16--23 occupy bits 24--31 and vice versa. 20708@end deftypefn 20709 20710@deftypefn {Built-in Function} void __builtin_rx_rmpa (void) 20711Generates the @code{rmpa} machine instruction which initiates a 20712repeated multiply and accumulate sequence. 20713@end deftypefn 20714 20715@deftypefn {Built-in Function} void __builtin_rx_round (float) 20716Generates the @code{round} machine instruction which returns the 20717floating-point argument rounded according to the current rounding mode 20718set in the floating-point status word register. 20719@end deftypefn 20720 20721@deftypefn {Built-in Function} int __builtin_rx_sat (int) 20722Generates the @code{sat} machine instruction which returns the 20723saturated value of the argument. 20724@end deftypefn 20725 20726@deftypefn {Built-in Function} void __builtin_rx_setpsw (int) 20727Generates the @code{setpsw} machine instruction to set the specified 20728bit in the processor status word. 20729@end deftypefn 20730 20731@deftypefn {Built-in Function} void __builtin_rx_wait (void) 20732Generates the @code{wait} machine instruction. 20733@end deftypefn 20734 20735@node S/390 System z Built-in Functions 20736@subsection S/390 System z Built-in Functions 20737@deftypefn {Built-in Function} int __builtin_tbegin (void*) 20738Generates the @code{tbegin} machine instruction starting a 20739non-constrained hardware transaction. If the parameter is non-NULL the 20740memory area is used to store the transaction diagnostic buffer and 20741will be passed as first operand to @code{tbegin}. This buffer can be 20742defined using the @code{struct __htm_tdb} C struct defined in 20743@code{htmintrin.h} and must reside on a double-word boundary. The 20744second tbegin operand is set to @code{0xff0c}. This enables 20745save/restore of all GPRs and disables aborts for FPR and AR 20746manipulations inside the transaction body. The condition code set by 20747the tbegin instruction is returned as integer value. The tbegin 20748instruction by definition overwrites the content of all FPRs. The 20749compiler will generate code which saves and restores the FPRs. For 20750soft-float code it is recommended to used the @code{*_nofloat} 20751variant. In order to prevent a TDB from being written it is required 20752to pass a constant zero value as parameter. Passing a zero value 20753through a variable is not sufficient. Although modifications of 20754access registers inside the transaction will not trigger an 20755transaction abort it is not supported to actually modify them. Access 20756registers do not get saved when entering a transaction. They will have 20757undefined state when reaching the abort code. 20758@end deftypefn 20759 20760Macros for the possible return codes of tbegin are defined in the 20761@code{htmintrin.h} header file: 20762 20763@table @code 20764@item _HTM_TBEGIN_STARTED 20765@code{tbegin} has been executed as part of normal processing. The 20766transaction body is supposed to be executed. 20767@item _HTM_TBEGIN_INDETERMINATE 20768The transaction was aborted due to an indeterminate condition which 20769might be persistent. 20770@item _HTM_TBEGIN_TRANSIENT 20771The transaction aborted due to a transient failure. The transaction 20772should be re-executed in that case. 20773@item _HTM_TBEGIN_PERSISTENT 20774The transaction aborted due to a persistent failure. Re-execution 20775under same circumstances will not be productive. 20776@end table 20777 20778@defmac _HTM_FIRST_USER_ABORT_CODE 20779The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h} 20780specifies the first abort code which can be used for 20781@code{__builtin_tabort}. Values below this threshold are reserved for 20782machine use. 20783@end defmac 20784 20785@deftp {Data type} {struct __htm_tdb} 20786The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes 20787the structure of the transaction diagnostic block as specified in the 20788Principles of Operation manual chapter 5-91. 20789@end deftp 20790 20791@deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*) 20792Same as @code{__builtin_tbegin} but without FPR saves and restores. 20793Using this variant in code making use of FPRs will leave the FPRs in 20794undefined state when entering the transaction abort handler code. 20795@end deftypefn 20796 20797@deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int) 20798In addition to @code{__builtin_tbegin} a loop for transient failures 20799is generated. If tbegin returns a condition code of 2 the transaction 20800will be retried as often as specified in the second argument. The 20801perform processor assist instruction is used to tell the CPU about the 20802number of fails so far. 20803@end deftypefn 20804 20805@deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int) 20806Same as @code{__builtin_tbegin_retry} but without FPR saves and 20807restores. Using this variant in code making use of FPRs will leave 20808the FPRs in undefined state when entering the transaction abort 20809handler code. 20810@end deftypefn 20811 20812@deftypefn {Built-in Function} void __builtin_tbeginc (void) 20813Generates the @code{tbeginc} machine instruction starting a constrained 20814hardware transaction. The second operand is set to @code{0xff08}. 20815@end deftypefn 20816 20817@deftypefn {Built-in Function} int __builtin_tend (void) 20818Generates the @code{tend} machine instruction finishing a transaction 20819and making the changes visible to other threads. The condition code 20820generated by tend is returned as integer value. 20821@end deftypefn 20822 20823@deftypefn {Built-in Function} void __builtin_tabort (int) 20824Generates the @code{tabort} machine instruction with the specified 20825abort code. Abort codes from 0 through 255 are reserved and will 20826result in an error message. 20827@end deftypefn 20828 20829@deftypefn {Built-in Function} void __builtin_tx_assist (int) 20830Generates the @code{ppa rX,rY,1} machine instruction. Where the 20831integer parameter is loaded into rX and a value of zero is loaded into 20832rY. The integer parameter specifies the number of times the 20833transaction repeatedly aborted. 20834@end deftypefn 20835 20836@deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void) 20837Generates the @code{etnd} machine instruction. The current nesting 20838depth is returned as integer value. For a nesting depth of 0 the code 20839is not executed as part of an transaction. 20840@end deftypefn 20841 20842@deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t) 20843 20844Generates the @code{ntstg} machine instruction. The second argument 20845is written to the first arguments location. The store operation will 20846not be rolled-back in case of an transaction abort. 20847@end deftypefn 20848 20849@node SH Built-in Functions 20850@subsection SH Built-in Functions 20851The following built-in functions are supported on the SH1, SH2, SH3 and SH4 20852families of processors: 20853 20854@deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr}) 20855Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually 20856used by system code that manages threads and execution contexts. The compiler 20857normally does not generate code that modifies the contents of @samp{GBR} and 20858thus the value is preserved across function calls. Changing the @samp{GBR} 20859value in user code must be done with caution, since the compiler might use 20860@samp{GBR} in order to access thread local variables. 20861 20862@end deftypefn 20863 20864@deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void) 20865Returns the value that is currently set in the @samp{GBR} register. 20866Memory loads and stores that use the thread pointer as a base address are 20867turned into @samp{GBR} based displacement loads and stores, if possible. 20868For example: 20869@smallexample 20870struct my_tcb 20871@{ 20872 int a, b, c, d, e; 20873@}; 20874 20875int get_tcb_value (void) 20876@{ 20877 // Generate @samp{mov.l @@(8,gbr),r0} instruction 20878 return ((my_tcb*)__builtin_thread_pointer ())->c; 20879@} 20880 20881@end smallexample 20882@end deftypefn 20883 20884@deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void) 20885Returns the value that is currently set in the @samp{FPSCR} register. 20886@end deftypefn 20887 20888@deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val}) 20889Sets the @samp{FPSCR} register to the specified value @var{val}, while 20890preserving the current values of the FR, SZ and PR bits. 20891@end deftypefn 20892 20893@node SPARC VIS Built-in Functions 20894@subsection SPARC VIS Built-in Functions 20895 20896GCC supports SIMD operations on the SPARC using both the generic vector 20897extensions (@pxref{Vector Extensions}) as well as built-in functions for 20898the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} 20899switch, the VIS extension is exposed as the following built-in functions: 20900 20901@smallexample 20902typedef int v1si __attribute__ ((vector_size (4))); 20903typedef int v2si __attribute__ ((vector_size (8))); 20904typedef short v4hi __attribute__ ((vector_size (8))); 20905typedef short v2hi __attribute__ ((vector_size (4))); 20906typedef unsigned char v8qi __attribute__ ((vector_size (8))); 20907typedef unsigned char v4qi __attribute__ ((vector_size (4))); 20908 20909void __builtin_vis_write_gsr (int64_t); 20910int64_t __builtin_vis_read_gsr (void); 20911 20912void * __builtin_vis_alignaddr (void *, long); 20913void * __builtin_vis_alignaddrl (void *, long); 20914int64_t __builtin_vis_faligndatadi (int64_t, int64_t); 20915v2si __builtin_vis_faligndatav2si (v2si, v2si); 20916v4hi __builtin_vis_faligndatav4hi (v4si, v4si); 20917v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); 20918 20919v4hi __builtin_vis_fexpand (v4qi); 20920 20921v4hi __builtin_vis_fmul8x16 (v4qi, v4hi); 20922v4hi __builtin_vis_fmul8x16au (v4qi, v2hi); 20923v4hi __builtin_vis_fmul8x16al (v4qi, v2hi); 20924v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); 20925v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); 20926v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); 20927v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); 20928 20929v4qi __builtin_vis_fpack16 (v4hi); 20930v8qi __builtin_vis_fpack32 (v2si, v8qi); 20931v2hi __builtin_vis_fpackfix (v2si); 20932v8qi __builtin_vis_fpmerge (v4qi, v4qi); 20933 20934int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); 20935 20936long __builtin_vis_edge8 (void *, void *); 20937long __builtin_vis_edge8l (void *, void *); 20938long __builtin_vis_edge16 (void *, void *); 20939long __builtin_vis_edge16l (void *, void *); 20940long __builtin_vis_edge32 (void *, void *); 20941long __builtin_vis_edge32l (void *, void *); 20942 20943long __builtin_vis_fcmple16 (v4hi, v4hi); 20944long __builtin_vis_fcmple32 (v2si, v2si); 20945long __builtin_vis_fcmpne16 (v4hi, v4hi); 20946long __builtin_vis_fcmpne32 (v2si, v2si); 20947long __builtin_vis_fcmpgt16 (v4hi, v4hi); 20948long __builtin_vis_fcmpgt32 (v2si, v2si); 20949long __builtin_vis_fcmpeq16 (v4hi, v4hi); 20950long __builtin_vis_fcmpeq32 (v2si, v2si); 20951 20952v4hi __builtin_vis_fpadd16 (v4hi, v4hi); 20953v2hi __builtin_vis_fpadd16s (v2hi, v2hi); 20954v2si __builtin_vis_fpadd32 (v2si, v2si); 20955v1si __builtin_vis_fpadd32s (v1si, v1si); 20956v4hi __builtin_vis_fpsub16 (v4hi, v4hi); 20957v2hi __builtin_vis_fpsub16s (v2hi, v2hi); 20958v2si __builtin_vis_fpsub32 (v2si, v2si); 20959v1si __builtin_vis_fpsub32s (v1si, v1si); 20960 20961long __builtin_vis_array8 (long, long); 20962long __builtin_vis_array16 (long, long); 20963long __builtin_vis_array32 (long, long); 20964@end smallexample 20965 20966When you use the @option{-mvis2} switch, the VIS version 2.0 built-in 20967functions also become available: 20968 20969@smallexample 20970long __builtin_vis_bmask (long, long); 20971int64_t __builtin_vis_bshuffledi (int64_t, int64_t); 20972v2si __builtin_vis_bshufflev2si (v2si, v2si); 20973v4hi __builtin_vis_bshufflev2si (v4hi, v4hi); 20974v8qi __builtin_vis_bshufflev2si (v8qi, v8qi); 20975 20976long __builtin_vis_edge8n (void *, void *); 20977long __builtin_vis_edge8ln (void *, void *); 20978long __builtin_vis_edge16n (void *, void *); 20979long __builtin_vis_edge16ln (void *, void *); 20980long __builtin_vis_edge32n (void *, void *); 20981long __builtin_vis_edge32ln (void *, void *); 20982@end smallexample 20983 20984When you use the @option{-mvis3} switch, the VIS version 3.0 built-in 20985functions also become available: 20986 20987@smallexample 20988void __builtin_vis_cmask8 (long); 20989void __builtin_vis_cmask16 (long); 20990void __builtin_vis_cmask32 (long); 20991 20992v4hi __builtin_vis_fchksm16 (v4hi, v4hi); 20993 20994v4hi __builtin_vis_fsll16 (v4hi, v4hi); 20995v4hi __builtin_vis_fslas16 (v4hi, v4hi); 20996v4hi __builtin_vis_fsrl16 (v4hi, v4hi); 20997v4hi __builtin_vis_fsra16 (v4hi, v4hi); 20998v2si __builtin_vis_fsll16 (v2si, v2si); 20999v2si __builtin_vis_fslas16 (v2si, v2si); 21000v2si __builtin_vis_fsrl16 (v2si, v2si); 21001v2si __builtin_vis_fsra16 (v2si, v2si); 21002 21003long __builtin_vis_pdistn (v8qi, v8qi); 21004 21005v4hi __builtin_vis_fmean16 (v4hi, v4hi); 21006 21007int64_t __builtin_vis_fpadd64 (int64_t, int64_t); 21008int64_t __builtin_vis_fpsub64 (int64_t, int64_t); 21009 21010v4hi __builtin_vis_fpadds16 (v4hi, v4hi); 21011v2hi __builtin_vis_fpadds16s (v2hi, v2hi); 21012v4hi __builtin_vis_fpsubs16 (v4hi, v4hi); 21013v2hi __builtin_vis_fpsubs16s (v2hi, v2hi); 21014v2si __builtin_vis_fpadds32 (v2si, v2si); 21015v1si __builtin_vis_fpadds32s (v1si, v1si); 21016v2si __builtin_vis_fpsubs32 (v2si, v2si); 21017v1si __builtin_vis_fpsubs32s (v1si, v1si); 21018 21019long __builtin_vis_fucmple8 (v8qi, v8qi); 21020long __builtin_vis_fucmpne8 (v8qi, v8qi); 21021long __builtin_vis_fucmpgt8 (v8qi, v8qi); 21022long __builtin_vis_fucmpeq8 (v8qi, v8qi); 21023 21024float __builtin_vis_fhadds (float, float); 21025double __builtin_vis_fhaddd (double, double); 21026float __builtin_vis_fhsubs (float, float); 21027double __builtin_vis_fhsubd (double, double); 21028float __builtin_vis_fnhadds (float, float); 21029double __builtin_vis_fnhaddd (double, double); 21030 21031int64_t __builtin_vis_umulxhi (int64_t, int64_t); 21032int64_t __builtin_vis_xmulx (int64_t, int64_t); 21033int64_t __builtin_vis_xmulxhi (int64_t, int64_t); 21034@end smallexample 21035 21036When you use the @option{-mvis4} switch, the VIS version 4.0 built-in 21037functions also become available: 21038 21039@smallexample 21040v8qi __builtin_vis_fpadd8 (v8qi, v8qi); 21041v8qi __builtin_vis_fpadds8 (v8qi, v8qi); 21042v8qi __builtin_vis_fpaddus8 (v8qi, v8qi); 21043v4hi __builtin_vis_fpaddus16 (v4hi, v4hi); 21044 21045v8qi __builtin_vis_fpsub8 (v8qi, v8qi); 21046v8qi __builtin_vis_fpsubs8 (v8qi, v8qi); 21047v8qi __builtin_vis_fpsubus8 (v8qi, v8qi); 21048v4hi __builtin_vis_fpsubus16 (v4hi, v4hi); 21049 21050long __builtin_vis_fpcmple8 (v8qi, v8qi); 21051long __builtin_vis_fpcmpgt8 (v8qi, v8qi); 21052long __builtin_vis_fpcmpule16 (v4hi, v4hi); 21053long __builtin_vis_fpcmpugt16 (v4hi, v4hi); 21054long __builtin_vis_fpcmpule32 (v2si, v2si); 21055long __builtin_vis_fpcmpugt32 (v2si, v2si); 21056 21057v8qi __builtin_vis_fpmax8 (v8qi, v8qi); 21058v4hi __builtin_vis_fpmax16 (v4hi, v4hi); 21059v2si __builtin_vis_fpmax32 (v2si, v2si); 21060 21061v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi); 21062v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi); 21063v2si __builtin_vis_fpmaxu32 (v2si, v2si); 21064 21065 21066v8qi __builtin_vis_fpmin8 (v8qi, v8qi); 21067v4hi __builtin_vis_fpmin16 (v4hi, v4hi); 21068v2si __builtin_vis_fpmin32 (v2si, v2si); 21069 21070v8qi __builtin_vis_fpminu8 (v8qi, v8qi); 21071v4hi __builtin_vis_fpminu16 (v4hi, v4hi); 21072v2si __builtin_vis_fpminu32 (v2si, v2si); 21073@end smallexample 21074 21075When you use the @option{-mvis4b} switch, the VIS version 4.0B 21076built-in functions also become available: 21077 21078@smallexample 21079v8qi __builtin_vis_dictunpack8 (double, int); 21080v4hi __builtin_vis_dictunpack16 (double, int); 21081v2si __builtin_vis_dictunpack32 (double, int); 21082 21083long __builtin_vis_fpcmple8shl (v8qi, v8qi, int); 21084long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int); 21085long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int); 21086long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int); 21087 21088long __builtin_vis_fpcmple16shl (v4hi, v4hi, int); 21089long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int); 21090long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int); 21091long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int); 21092 21093long __builtin_vis_fpcmple32shl (v2si, v2si, int); 21094long __builtin_vis_fpcmpgt32shl (v2si, v2si, int); 21095long __builtin_vis_fpcmpeq32shl (v2si, v2si, int); 21096long __builtin_vis_fpcmpne32shl (v2si, v2si, int); 21097 21098long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int); 21099long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int); 21100long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int); 21101long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int); 21102long __builtin_vis_fpcmpule32shl (v2si, v2si, int); 21103long __builtin_vis_fpcmpugt32shl (v2si, v2si, int); 21104 21105long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int); 21106long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int); 21107long __builtin_vis_fpcmpde32shl (v2si, v2si, int); 21108 21109long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int); 21110long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int); 21111long __builtin_vis_fpcmpur32shl (v2si, v2si, int); 21112@end smallexample 21113 21114@node SPU Built-in Functions 21115@subsection SPU Built-in Functions 21116 21117GCC provides extensions for the SPU processor as described in the 21118Sony/Toshiba/IBM SPU Language Extensions Specification. GCC's 21119implementation differs in several ways. 21120 21121@itemize @bullet 21122 21123@item 21124The optional extension of specifying vector constants in parentheses is 21125not supported. 21126 21127@item 21128A vector initializer requires no cast if the vector constant is of the 21129same type as the variable it is initializing. 21130 21131@item 21132If @code{signed} or @code{unsigned} is omitted, the signedness of the 21133vector type is the default signedness of the base type. The default 21134varies depending on the operating system, so a portable program should 21135always specify the signedness. 21136 21137@item 21138By default, the keyword @code{__vector} is added. The macro 21139@code{vector} is defined in @code{<spu_intrinsics.h>} and can be 21140undefined. 21141 21142@item 21143GCC allows using a @code{typedef} name as the type specifier for a 21144vector type. 21145 21146@item 21147For C, overloaded functions are implemented with macros so the following 21148does not work: 21149 21150@smallexample 21151 spu_add ((vector signed int)@{1, 2, 3, 4@}, foo); 21152@end smallexample 21153 21154@noindent 21155Since @code{spu_add} is a macro, the vector constant in the example 21156is treated as four separate arguments. Wrap the entire argument in 21157parentheses for this to work. 21158 21159@item 21160The extended version of @code{__builtin_expect} is not supported. 21161 21162@end itemize 21163 21164@emph{Note:} Only the interface described in the aforementioned 21165specification is supported. Internally, GCC uses built-in functions to 21166implement the required functionality, but these are not supported and 21167are subject to change without notice. 21168 21169@node TI C6X Built-in Functions 21170@subsection TI C6X Built-in Functions 21171 21172GCC provides intrinsics to access certain instructions of the TI C6X 21173processors. These intrinsics, listed below, are available after 21174inclusion of the @code{c6x_intrinsics.h} header file. They map directly 21175to C6X instructions. 21176 21177@smallexample 21178 21179int _sadd (int, int) 21180int _ssub (int, int) 21181int _sadd2 (int, int) 21182int _ssub2 (int, int) 21183long long _mpy2 (int, int) 21184long long _smpy2 (int, int) 21185int _add4 (int, int) 21186int _sub4 (int, int) 21187int _saddu4 (int, int) 21188 21189int _smpy (int, int) 21190int _smpyh (int, int) 21191int _smpyhl (int, int) 21192int _smpylh (int, int) 21193 21194int _sshl (int, int) 21195int _subc (int, int) 21196 21197int _avg2 (int, int) 21198int _avgu4 (int, int) 21199 21200int _clrr (int, int) 21201int _extr (int, int) 21202int _extru (int, int) 21203int _abs (int) 21204int _abs2 (int) 21205 21206@end smallexample 21207 21208@node TILE-Gx Built-in Functions 21209@subsection TILE-Gx Built-in Functions 21210 21211GCC provides intrinsics to access every instruction of the TILE-Gx 21212processor. The intrinsics are of the form: 21213 21214@smallexample 21215 21216unsigned long long __insn_@var{op} (...) 21217 21218@end smallexample 21219 21220Where @var{op} is the name of the instruction. Refer to the ISA manual 21221for the complete list of instructions. 21222 21223GCC also provides intrinsics to directly access the network registers. 21224The intrinsics are: 21225 21226@smallexample 21227 21228unsigned long long __tile_idn0_receive (void) 21229unsigned long long __tile_idn1_receive (void) 21230unsigned long long __tile_udn0_receive (void) 21231unsigned long long __tile_udn1_receive (void) 21232unsigned long long __tile_udn2_receive (void) 21233unsigned long long __tile_udn3_receive (void) 21234void __tile_idn_send (unsigned long long) 21235void __tile_udn_send (unsigned long long) 21236 21237@end smallexample 21238 21239The intrinsic @code{void __tile_network_barrier (void)} is used to 21240guarantee that no network operations before it are reordered with 21241those after it. 21242 21243@node TILEPro Built-in Functions 21244@subsection TILEPro Built-in Functions 21245 21246GCC provides intrinsics to access every instruction of the TILEPro 21247processor. The intrinsics are of the form: 21248 21249@smallexample 21250 21251unsigned __insn_@var{op} (...) 21252 21253@end smallexample 21254 21255@noindent 21256where @var{op} is the name of the instruction. Refer to the ISA manual 21257for the complete list of instructions. 21258 21259GCC also provides intrinsics to directly access the network registers. 21260The intrinsics are: 21261 21262@smallexample 21263 21264unsigned __tile_idn0_receive (void) 21265unsigned __tile_idn1_receive (void) 21266unsigned __tile_sn_receive (void) 21267unsigned __tile_udn0_receive (void) 21268unsigned __tile_udn1_receive (void) 21269unsigned __tile_udn2_receive (void) 21270unsigned __tile_udn3_receive (void) 21271void __tile_idn_send (unsigned) 21272void __tile_sn_send (unsigned) 21273void __tile_udn_send (unsigned) 21274 21275@end smallexample 21276 21277The intrinsic @code{void __tile_network_barrier (void)} is used to 21278guarantee that no network operations before it are reordered with 21279those after it. 21280 21281@node x86 Built-in Functions 21282@subsection x86 Built-in Functions 21283 21284These built-in functions are available for the x86-32 and x86-64 family 21285of computers, depending on the command-line switches used. 21286 21287If you specify command-line switches such as @option{-msse}, 21288the compiler could use the extended instruction sets even if the built-ins 21289are not used explicitly in the program. For this reason, applications 21290that perform run-time CPU detection must compile separate files for each 21291supported architecture, using the appropriate flags. In particular, 21292the file containing the CPU detection code should be compiled without 21293these options. 21294 21295The following machine modes are available for use with MMX built-in functions 21296(@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers, 21297@code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a 21298vector of eight 8-bit integers. Some of the built-in functions operate on 21299MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode. 21300 21301If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector 21302of two 32-bit floating-point values. 21303 21304If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit 21305floating-point values. Some instructions use a vector of four 32-bit 21306integers, these use @code{V4SI}. Finally, some instructions operate on an 21307entire vector register, interpreting it as a 128-bit integer, these use mode 21308@code{TI}. 21309 21310The x86-32 and x86-64 family of processors use additional built-in 21311functions for efficient use of @code{TF} (@code{__float128}) 128-bit 21312floating point and @code{TC} 128-bit complex floating-point values. 21313 21314The following floating-point built-in functions are always available. All 21315of them implement the function that is part of the name. 21316 21317@smallexample 21318__float128 __builtin_fabsq (__float128) 21319__float128 __builtin_copysignq (__float128, __float128) 21320@end smallexample 21321 21322The following built-in functions are always available. 21323 21324@table @code 21325@item __float128 __builtin_infq (void) 21326Similar to @code{__builtin_inf}, except the return type is @code{__float128}. 21327@findex __builtin_infq 21328 21329@item __float128 __builtin_huge_valq (void) 21330Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}. 21331@findex __builtin_huge_valq 21332 21333@item __float128 __builtin_nanq (void) 21334Similar to @code{__builtin_nan}, except the return type is @code{__float128}. 21335@findex __builtin_nanq 21336 21337@item __float128 __builtin_nansq (void) 21338Similar to @code{__builtin_nans}, except the return type is @code{__float128}. 21339@findex __builtin_nansq 21340@end table 21341 21342The following built-in function is always available. 21343 21344@table @code 21345@item void __builtin_ia32_pause (void) 21346Generates the @code{pause} machine instruction with a compiler memory 21347barrier. 21348@end table 21349 21350The following built-in functions are always available and can be used to 21351check the target platform type. 21352 21353@deftypefn {Built-in Function} void __builtin_cpu_init (void) 21354This function runs the CPU detection code to check the type of CPU and the 21355features supported. This built-in function needs to be invoked along with the built-in functions 21356to check CPU type and features, @code{__builtin_cpu_is} and 21357@code{__builtin_cpu_supports}, only when used in a function that is 21358executed before any constructors are called. The CPU detection code is 21359automatically executed in a very high priority constructor. 21360 21361For example, this function has to be used in @code{ifunc} resolvers that 21362check for CPU type using the built-in functions @code{__builtin_cpu_is} 21363and @code{__builtin_cpu_supports}, or in constructors on targets that 21364don't support constructor priority. 21365@smallexample 21366 21367static void (*resolve_memcpy (void)) (void) 21368@{ 21369 // ifunc resolvers fire before constructors, explicitly call the init 21370 // function. 21371 __builtin_cpu_init (); 21372 if (__builtin_cpu_supports ("ssse3")) 21373 return ssse3_memcpy; // super fast memcpy with ssse3 instructions. 21374 else 21375 return default_memcpy; 21376@} 21377 21378void *memcpy (void *, const void *, size_t) 21379 __attribute__ ((ifunc ("resolve_memcpy"))); 21380@end smallexample 21381 21382@end deftypefn 21383 21384@deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname}) 21385This function returns a positive integer if the run-time CPU 21386is of type @var{cpuname} 21387and returns @code{0} otherwise. The following CPU names can be detected: 21388 21389@table @samp 21390@item amd 21391AMD CPU. 21392 21393@item intel 21394Intel CPU. 21395 21396@item atom 21397Intel Atom CPU. 21398 21399@item slm 21400Intel Silvermont CPU. 21401 21402@item core2 21403Intel Core 2 CPU. 21404 21405@item corei7 21406Intel Core i7 CPU. 21407 21408@item nehalem 21409Intel Core i7 Nehalem CPU. 21410 21411@item westmere 21412Intel Core i7 Westmere CPU. 21413 21414@item sandybridge 21415Intel Core i7 Sandy Bridge CPU. 21416 21417@item ivybridge 21418Intel Core i7 Ivy Bridge CPU. 21419 21420@item haswell 21421Intel Core i7 Haswell CPU. 21422 21423@item broadwell 21424Intel Core i7 Broadwell CPU. 21425 21426@item skylake 21427Intel Core i7 Skylake CPU. 21428 21429@item skylake-avx512 21430Intel Core i7 Skylake AVX512 CPU. 21431 21432@item cannonlake 21433Intel Core i7 Cannon Lake CPU. 21434 21435@item icelake-client 21436Intel Core i7 Ice Lake Client CPU. 21437 21438@item icelake-server 21439Intel Core i7 Ice Lake Server CPU. 21440 21441@item cascadelake 21442Intel Core i7 Cascadelake CPU. 21443 21444@item bonnell 21445Intel Atom Bonnell CPU. 21446 21447@item silvermont 21448Intel Atom Silvermont CPU. 21449 21450@item goldmont 21451Intel Atom Goldmont CPU. 21452 21453@item goldmont-plus 21454Intel Atom Goldmont Plus CPU. 21455 21456@item tremont 21457Intel Atom Tremont CPU. 21458 21459@item knl 21460Intel Knights Landing CPU. 21461 21462@item knm 21463Intel Knights Mill CPU. 21464 21465@item amdfam10h 21466AMD Family 10h CPU. 21467 21468@item barcelona 21469AMD Family 10h Barcelona CPU. 21470 21471@item shanghai 21472AMD Family 10h Shanghai CPU. 21473 21474@item istanbul 21475AMD Family 10h Istanbul CPU. 21476 21477@item btver1 21478AMD Family 14h CPU. 21479 21480@item amdfam15h 21481AMD Family 15h CPU. 21482 21483@item bdver1 21484AMD Family 15h Bulldozer version 1. 21485 21486@item bdver2 21487AMD Family 15h Bulldozer version 2. 21488 21489@item bdver3 21490AMD Family 15h Bulldozer version 3. 21491 21492@item bdver4 21493AMD Family 15h Bulldozer version 4. 21494 21495@item btver2 21496AMD Family 16h CPU. 21497 21498@item amdfam17h 21499AMD Family 17h CPU. 21500 21501@item znver1 21502AMD Family 17h Zen version 1. 21503 21504@item znver2 21505AMD Family 17h Zen version 2. 21506@end table 21507 21508Here is an example: 21509@smallexample 21510if (__builtin_cpu_is ("corei7")) 21511 @{ 21512 do_corei7 (); // Core i7 specific implementation. 21513 @} 21514else 21515 @{ 21516 do_generic (); // Generic implementation. 21517 @} 21518@end smallexample 21519@end deftypefn 21520 21521@deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature}) 21522This function returns a positive integer if the run-time CPU 21523supports @var{feature} 21524and returns @code{0} otherwise. The following features can be detected: 21525 21526@table @samp 21527@item cmov 21528CMOV instruction. 21529@item mmx 21530MMX instructions. 21531@item popcnt 21532POPCNT instruction. 21533@item sse 21534SSE instructions. 21535@item sse2 21536SSE2 instructions. 21537@item sse3 21538SSE3 instructions. 21539@item ssse3 21540SSSE3 instructions. 21541@item sse4.1 21542SSE4.1 instructions. 21543@item sse4.2 21544SSE4.2 instructions. 21545@item avx 21546AVX instructions. 21547@item avx2 21548AVX2 instructions. 21549@item sse4a 21550SSE4A instructions. 21551@item fma4 21552FMA4 instructions. 21553@item xop 21554XOP instructions. 21555@item fma 21556FMA instructions. 21557@item avx512f 21558AVX512F instructions. 21559@item bmi 21560BMI instructions. 21561@item bmi2 21562BMI2 instructions. 21563@item aes 21564AES instructions. 21565@item pclmul 21566PCLMUL instructions. 21567@item avx512vl 21568AVX512VL instructions. 21569@item avx512bw 21570AVX512BW instructions. 21571@item avx512dq 21572AVX512DQ instructions. 21573@item avx512cd 21574AVX512CD instructions. 21575@item avx512er 21576AVX512ER instructions. 21577@item avx512pf 21578AVX512PF instructions. 21579@item avx512vbmi 21580AVX512VBMI instructions. 21581@item avx512ifma 21582AVX512IFMA instructions. 21583@item avx5124vnniw 21584AVX5124VNNIW instructions. 21585@item avx5124fmaps 21586AVX5124FMAPS instructions. 21587@item avx512vpopcntdq 21588AVX512VPOPCNTDQ instructions. 21589@item avx512vbmi2 21590AVX512VBMI2 instructions. 21591@item gfni 21592GFNI instructions. 21593@item vpclmulqdq 21594VPCLMULQDQ instructions. 21595@item avx512vnni 21596AVX512VNNI instructions. 21597@item avx512bitalg 21598AVX512BITALG instructions. 21599@end table 21600 21601Here is an example: 21602@smallexample 21603if (__builtin_cpu_supports ("popcnt")) 21604 @{ 21605 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc"); 21606 @} 21607else 21608 @{ 21609 count = generic_countbits (n); //generic implementation. 21610 @} 21611@end smallexample 21612@end deftypefn 21613 21614 21615The following built-in functions are made available by @option{-mmmx}. 21616All of them generate the machine instruction that is part of the name. 21617 21618@smallexample 21619v8qi __builtin_ia32_paddb (v8qi, v8qi) 21620v4hi __builtin_ia32_paddw (v4hi, v4hi) 21621v2si __builtin_ia32_paddd (v2si, v2si) 21622v8qi __builtin_ia32_psubb (v8qi, v8qi) 21623v4hi __builtin_ia32_psubw (v4hi, v4hi) 21624v2si __builtin_ia32_psubd (v2si, v2si) 21625v8qi __builtin_ia32_paddsb (v8qi, v8qi) 21626v4hi __builtin_ia32_paddsw (v4hi, v4hi) 21627v8qi __builtin_ia32_psubsb (v8qi, v8qi) 21628v4hi __builtin_ia32_psubsw (v4hi, v4hi) 21629v8qi __builtin_ia32_paddusb (v8qi, v8qi) 21630v4hi __builtin_ia32_paddusw (v4hi, v4hi) 21631v8qi __builtin_ia32_psubusb (v8qi, v8qi) 21632v4hi __builtin_ia32_psubusw (v4hi, v4hi) 21633v4hi __builtin_ia32_pmullw (v4hi, v4hi) 21634v4hi __builtin_ia32_pmulhw (v4hi, v4hi) 21635di __builtin_ia32_pand (di, di) 21636di __builtin_ia32_pandn (di,di) 21637di __builtin_ia32_por (di, di) 21638di __builtin_ia32_pxor (di, di) 21639v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi) 21640v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi) 21641v2si __builtin_ia32_pcmpeqd (v2si, v2si) 21642v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi) 21643v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi) 21644v2si __builtin_ia32_pcmpgtd (v2si, v2si) 21645v8qi __builtin_ia32_punpckhbw (v8qi, v8qi) 21646v4hi __builtin_ia32_punpckhwd (v4hi, v4hi) 21647v2si __builtin_ia32_punpckhdq (v2si, v2si) 21648v8qi __builtin_ia32_punpcklbw (v8qi, v8qi) 21649v4hi __builtin_ia32_punpcklwd (v4hi, v4hi) 21650v2si __builtin_ia32_punpckldq (v2si, v2si) 21651v8qi __builtin_ia32_packsswb (v4hi, v4hi) 21652v4hi __builtin_ia32_packssdw (v2si, v2si) 21653v8qi __builtin_ia32_packuswb (v4hi, v4hi) 21654 21655v4hi __builtin_ia32_psllw (v4hi, v4hi) 21656v2si __builtin_ia32_pslld (v2si, v2si) 21657v1di __builtin_ia32_psllq (v1di, v1di) 21658v4hi __builtin_ia32_psrlw (v4hi, v4hi) 21659v2si __builtin_ia32_psrld (v2si, v2si) 21660v1di __builtin_ia32_psrlq (v1di, v1di) 21661v4hi __builtin_ia32_psraw (v4hi, v4hi) 21662v2si __builtin_ia32_psrad (v2si, v2si) 21663v4hi __builtin_ia32_psllwi (v4hi, int) 21664v2si __builtin_ia32_pslldi (v2si, int) 21665v1di __builtin_ia32_psllqi (v1di, int) 21666v4hi __builtin_ia32_psrlwi (v4hi, int) 21667v2si __builtin_ia32_psrldi (v2si, int) 21668v1di __builtin_ia32_psrlqi (v1di, int) 21669v4hi __builtin_ia32_psrawi (v4hi, int) 21670v2si __builtin_ia32_psradi (v2si, int) 21671 21672@end smallexample 21673 21674The following built-in functions are made available either with 21675@option{-msse}, or with @option{-m3dnowa}. All of them generate 21676the machine instruction that is part of the name. 21677 21678@smallexample 21679v4hi __builtin_ia32_pmulhuw (v4hi, v4hi) 21680v8qi __builtin_ia32_pavgb (v8qi, v8qi) 21681v4hi __builtin_ia32_pavgw (v4hi, v4hi) 21682v1di __builtin_ia32_psadbw (v8qi, v8qi) 21683v8qi __builtin_ia32_pmaxub (v8qi, v8qi) 21684v4hi __builtin_ia32_pmaxsw (v4hi, v4hi) 21685v8qi __builtin_ia32_pminub (v8qi, v8qi) 21686v4hi __builtin_ia32_pminsw (v4hi, v4hi) 21687int __builtin_ia32_pmovmskb (v8qi) 21688void __builtin_ia32_maskmovq (v8qi, v8qi, char *) 21689void __builtin_ia32_movntq (di *, di) 21690void __builtin_ia32_sfence (void) 21691@end smallexample 21692 21693The following built-in functions are available when @option{-msse} is used. 21694All of them generate the machine instruction that is part of the name. 21695 21696@smallexample 21697int __builtin_ia32_comieq (v4sf, v4sf) 21698int __builtin_ia32_comineq (v4sf, v4sf) 21699int __builtin_ia32_comilt (v4sf, v4sf) 21700int __builtin_ia32_comile (v4sf, v4sf) 21701int __builtin_ia32_comigt (v4sf, v4sf) 21702int __builtin_ia32_comige (v4sf, v4sf) 21703int __builtin_ia32_ucomieq (v4sf, v4sf) 21704int __builtin_ia32_ucomineq (v4sf, v4sf) 21705int __builtin_ia32_ucomilt (v4sf, v4sf) 21706int __builtin_ia32_ucomile (v4sf, v4sf) 21707int __builtin_ia32_ucomigt (v4sf, v4sf) 21708int __builtin_ia32_ucomige (v4sf, v4sf) 21709v4sf __builtin_ia32_addps (v4sf, v4sf) 21710v4sf __builtin_ia32_subps (v4sf, v4sf) 21711v4sf __builtin_ia32_mulps (v4sf, v4sf) 21712v4sf __builtin_ia32_divps (v4sf, v4sf) 21713v4sf __builtin_ia32_addss (v4sf, v4sf) 21714v4sf __builtin_ia32_subss (v4sf, v4sf) 21715v4sf __builtin_ia32_mulss (v4sf, v4sf) 21716v4sf __builtin_ia32_divss (v4sf, v4sf) 21717v4sf __builtin_ia32_cmpeqps (v4sf, v4sf) 21718v4sf __builtin_ia32_cmpltps (v4sf, v4sf) 21719v4sf __builtin_ia32_cmpleps (v4sf, v4sf) 21720v4sf __builtin_ia32_cmpgtps (v4sf, v4sf) 21721v4sf __builtin_ia32_cmpgeps (v4sf, v4sf) 21722v4sf __builtin_ia32_cmpunordps (v4sf, v4sf) 21723v4sf __builtin_ia32_cmpneqps (v4sf, v4sf) 21724v4sf __builtin_ia32_cmpnltps (v4sf, v4sf) 21725v4sf __builtin_ia32_cmpnleps (v4sf, v4sf) 21726v4sf __builtin_ia32_cmpngtps (v4sf, v4sf) 21727v4sf __builtin_ia32_cmpngeps (v4sf, v4sf) 21728v4sf __builtin_ia32_cmpordps (v4sf, v4sf) 21729v4sf __builtin_ia32_cmpeqss (v4sf, v4sf) 21730v4sf __builtin_ia32_cmpltss (v4sf, v4sf) 21731v4sf __builtin_ia32_cmpless (v4sf, v4sf) 21732v4sf __builtin_ia32_cmpunordss (v4sf, v4sf) 21733v4sf __builtin_ia32_cmpneqss (v4sf, v4sf) 21734v4sf __builtin_ia32_cmpnltss (v4sf, v4sf) 21735v4sf __builtin_ia32_cmpnless (v4sf, v4sf) 21736v4sf __builtin_ia32_cmpordss (v4sf, v4sf) 21737v4sf __builtin_ia32_maxps (v4sf, v4sf) 21738v4sf __builtin_ia32_maxss (v4sf, v4sf) 21739v4sf __builtin_ia32_minps (v4sf, v4sf) 21740v4sf __builtin_ia32_minss (v4sf, v4sf) 21741v4sf __builtin_ia32_andps (v4sf, v4sf) 21742v4sf __builtin_ia32_andnps (v4sf, v4sf) 21743v4sf __builtin_ia32_orps (v4sf, v4sf) 21744v4sf __builtin_ia32_xorps (v4sf, v4sf) 21745v4sf __builtin_ia32_movss (v4sf, v4sf) 21746v4sf __builtin_ia32_movhlps (v4sf, v4sf) 21747v4sf __builtin_ia32_movlhps (v4sf, v4sf) 21748v4sf __builtin_ia32_unpckhps (v4sf, v4sf) 21749v4sf __builtin_ia32_unpcklps (v4sf, v4sf) 21750v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si) 21751v4sf __builtin_ia32_cvtsi2ss (v4sf, int) 21752v2si __builtin_ia32_cvtps2pi (v4sf) 21753int __builtin_ia32_cvtss2si (v4sf) 21754v2si __builtin_ia32_cvttps2pi (v4sf) 21755int __builtin_ia32_cvttss2si (v4sf) 21756v4sf __builtin_ia32_rcpps (v4sf) 21757v4sf __builtin_ia32_rsqrtps (v4sf) 21758v4sf __builtin_ia32_sqrtps (v4sf) 21759v4sf __builtin_ia32_rcpss (v4sf) 21760v4sf __builtin_ia32_rsqrtss (v4sf) 21761v4sf __builtin_ia32_sqrtss (v4sf) 21762v4sf __builtin_ia32_shufps (v4sf, v4sf, int) 21763void __builtin_ia32_movntps (float *, v4sf) 21764int __builtin_ia32_movmskps (v4sf) 21765@end smallexample 21766 21767The following built-in functions are available when @option{-msse} is used. 21768 21769@table @code 21770@item v4sf __builtin_ia32_loadups (float *) 21771Generates the @code{movups} machine instruction as a load from memory. 21772@item void __builtin_ia32_storeups (float *, v4sf) 21773Generates the @code{movups} machine instruction as a store to memory. 21774@item v4sf __builtin_ia32_loadss (float *) 21775Generates the @code{movss} machine instruction as a load from memory. 21776@item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *) 21777Generates the @code{movhps} machine instruction as a load from memory. 21778@item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *) 21779Generates the @code{movlps} machine instruction as a load from memory 21780@item void __builtin_ia32_storehps (v2sf *, v4sf) 21781Generates the @code{movhps} machine instruction as a store to memory. 21782@item void __builtin_ia32_storelps (v2sf *, v4sf) 21783Generates the @code{movlps} machine instruction as a store to memory. 21784@end table 21785 21786The following built-in functions are available when @option{-msse2} is used. 21787All of them generate the machine instruction that is part of the name. 21788 21789@smallexample 21790int __builtin_ia32_comisdeq (v2df, v2df) 21791int __builtin_ia32_comisdlt (v2df, v2df) 21792int __builtin_ia32_comisdle (v2df, v2df) 21793int __builtin_ia32_comisdgt (v2df, v2df) 21794int __builtin_ia32_comisdge (v2df, v2df) 21795int __builtin_ia32_comisdneq (v2df, v2df) 21796int __builtin_ia32_ucomisdeq (v2df, v2df) 21797int __builtin_ia32_ucomisdlt (v2df, v2df) 21798int __builtin_ia32_ucomisdle (v2df, v2df) 21799int __builtin_ia32_ucomisdgt (v2df, v2df) 21800int __builtin_ia32_ucomisdge (v2df, v2df) 21801int __builtin_ia32_ucomisdneq (v2df, v2df) 21802v2df __builtin_ia32_cmpeqpd (v2df, v2df) 21803v2df __builtin_ia32_cmpltpd (v2df, v2df) 21804v2df __builtin_ia32_cmplepd (v2df, v2df) 21805v2df __builtin_ia32_cmpgtpd (v2df, v2df) 21806v2df __builtin_ia32_cmpgepd (v2df, v2df) 21807v2df __builtin_ia32_cmpunordpd (v2df, v2df) 21808v2df __builtin_ia32_cmpneqpd (v2df, v2df) 21809v2df __builtin_ia32_cmpnltpd (v2df, v2df) 21810v2df __builtin_ia32_cmpnlepd (v2df, v2df) 21811v2df __builtin_ia32_cmpngtpd (v2df, v2df) 21812v2df __builtin_ia32_cmpngepd (v2df, v2df) 21813v2df __builtin_ia32_cmpordpd (v2df, v2df) 21814v2df __builtin_ia32_cmpeqsd (v2df, v2df) 21815v2df __builtin_ia32_cmpltsd (v2df, v2df) 21816v2df __builtin_ia32_cmplesd (v2df, v2df) 21817v2df __builtin_ia32_cmpunordsd (v2df, v2df) 21818v2df __builtin_ia32_cmpneqsd (v2df, v2df) 21819v2df __builtin_ia32_cmpnltsd (v2df, v2df) 21820v2df __builtin_ia32_cmpnlesd (v2df, v2df) 21821v2df __builtin_ia32_cmpordsd (v2df, v2df) 21822v2di __builtin_ia32_paddq (v2di, v2di) 21823v2di __builtin_ia32_psubq (v2di, v2di) 21824v2df __builtin_ia32_addpd (v2df, v2df) 21825v2df __builtin_ia32_subpd (v2df, v2df) 21826v2df __builtin_ia32_mulpd (v2df, v2df) 21827v2df __builtin_ia32_divpd (v2df, v2df) 21828v2df __builtin_ia32_addsd (v2df, v2df) 21829v2df __builtin_ia32_subsd (v2df, v2df) 21830v2df __builtin_ia32_mulsd (v2df, v2df) 21831v2df __builtin_ia32_divsd (v2df, v2df) 21832v2df __builtin_ia32_minpd (v2df, v2df) 21833v2df __builtin_ia32_maxpd (v2df, v2df) 21834v2df __builtin_ia32_minsd (v2df, v2df) 21835v2df __builtin_ia32_maxsd (v2df, v2df) 21836v2df __builtin_ia32_andpd (v2df, v2df) 21837v2df __builtin_ia32_andnpd (v2df, v2df) 21838v2df __builtin_ia32_orpd (v2df, v2df) 21839v2df __builtin_ia32_xorpd (v2df, v2df) 21840v2df __builtin_ia32_movsd (v2df, v2df) 21841v2df __builtin_ia32_unpckhpd (v2df, v2df) 21842v2df __builtin_ia32_unpcklpd (v2df, v2df) 21843v16qi __builtin_ia32_paddb128 (v16qi, v16qi) 21844v8hi __builtin_ia32_paddw128 (v8hi, v8hi) 21845v4si __builtin_ia32_paddd128 (v4si, v4si) 21846v2di __builtin_ia32_paddq128 (v2di, v2di) 21847v16qi __builtin_ia32_psubb128 (v16qi, v16qi) 21848v8hi __builtin_ia32_psubw128 (v8hi, v8hi) 21849v4si __builtin_ia32_psubd128 (v4si, v4si) 21850v2di __builtin_ia32_psubq128 (v2di, v2di) 21851v8hi __builtin_ia32_pmullw128 (v8hi, v8hi) 21852v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi) 21853v2di __builtin_ia32_pand128 (v2di, v2di) 21854v2di __builtin_ia32_pandn128 (v2di, v2di) 21855v2di __builtin_ia32_por128 (v2di, v2di) 21856v2di __builtin_ia32_pxor128 (v2di, v2di) 21857v16qi __builtin_ia32_pavgb128 (v16qi, v16qi) 21858v8hi __builtin_ia32_pavgw128 (v8hi, v8hi) 21859v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi) 21860v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi) 21861v4si __builtin_ia32_pcmpeqd128 (v4si, v4si) 21862v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi) 21863v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi) 21864v4si __builtin_ia32_pcmpgtd128 (v4si, v4si) 21865v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi) 21866v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi) 21867v16qi __builtin_ia32_pminub128 (v16qi, v16qi) 21868v8hi __builtin_ia32_pminsw128 (v8hi, v8hi) 21869v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi) 21870v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi) 21871v4si __builtin_ia32_punpckhdq128 (v4si, v4si) 21872v2di __builtin_ia32_punpckhqdq128 (v2di, v2di) 21873v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi) 21874v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi) 21875v4si __builtin_ia32_punpckldq128 (v4si, v4si) 21876v2di __builtin_ia32_punpcklqdq128 (v2di, v2di) 21877v16qi __builtin_ia32_packsswb128 (v8hi, v8hi) 21878v8hi __builtin_ia32_packssdw128 (v4si, v4si) 21879v16qi __builtin_ia32_packuswb128 (v8hi, v8hi) 21880v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi) 21881void __builtin_ia32_maskmovdqu (v16qi, v16qi) 21882v2df __builtin_ia32_loadupd (double *) 21883void __builtin_ia32_storeupd (double *, v2df) 21884v2df __builtin_ia32_loadhpd (v2df, double const *) 21885v2df __builtin_ia32_loadlpd (v2df, double const *) 21886int __builtin_ia32_movmskpd (v2df) 21887int __builtin_ia32_pmovmskb128 (v16qi) 21888void __builtin_ia32_movnti (int *, int) 21889void __builtin_ia32_movnti64 (long long int *, long long int) 21890void __builtin_ia32_movntpd (double *, v2df) 21891void __builtin_ia32_movntdq (v2df *, v2df) 21892v4si __builtin_ia32_pshufd (v4si, int) 21893v8hi __builtin_ia32_pshuflw (v8hi, int) 21894v8hi __builtin_ia32_pshufhw (v8hi, int) 21895v2di __builtin_ia32_psadbw128 (v16qi, v16qi) 21896v2df __builtin_ia32_sqrtpd (v2df) 21897v2df __builtin_ia32_sqrtsd (v2df) 21898v2df __builtin_ia32_shufpd (v2df, v2df, int) 21899v2df __builtin_ia32_cvtdq2pd (v4si) 21900v4sf __builtin_ia32_cvtdq2ps (v4si) 21901v4si __builtin_ia32_cvtpd2dq (v2df) 21902v2si __builtin_ia32_cvtpd2pi (v2df) 21903v4sf __builtin_ia32_cvtpd2ps (v2df) 21904v4si __builtin_ia32_cvttpd2dq (v2df) 21905v2si __builtin_ia32_cvttpd2pi (v2df) 21906v2df __builtin_ia32_cvtpi2pd (v2si) 21907int __builtin_ia32_cvtsd2si (v2df) 21908int __builtin_ia32_cvttsd2si (v2df) 21909long long __builtin_ia32_cvtsd2si64 (v2df) 21910long long __builtin_ia32_cvttsd2si64 (v2df) 21911v4si __builtin_ia32_cvtps2dq (v4sf) 21912v2df __builtin_ia32_cvtps2pd (v4sf) 21913v4si __builtin_ia32_cvttps2dq (v4sf) 21914v2df __builtin_ia32_cvtsi2sd (v2df, int) 21915v2df __builtin_ia32_cvtsi642sd (v2df, long long) 21916v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df) 21917v2df __builtin_ia32_cvtss2sd (v2df, v4sf) 21918void __builtin_ia32_clflush (const void *) 21919void __builtin_ia32_lfence (void) 21920void __builtin_ia32_mfence (void) 21921v16qi __builtin_ia32_loaddqu (const char *) 21922void __builtin_ia32_storedqu (char *, v16qi) 21923v1di __builtin_ia32_pmuludq (v2si, v2si) 21924v2di __builtin_ia32_pmuludq128 (v4si, v4si) 21925v8hi __builtin_ia32_psllw128 (v8hi, v8hi) 21926v4si __builtin_ia32_pslld128 (v4si, v4si) 21927v2di __builtin_ia32_psllq128 (v2di, v2di) 21928v8hi __builtin_ia32_psrlw128 (v8hi, v8hi) 21929v4si __builtin_ia32_psrld128 (v4si, v4si) 21930v2di __builtin_ia32_psrlq128 (v2di, v2di) 21931v8hi __builtin_ia32_psraw128 (v8hi, v8hi) 21932v4si __builtin_ia32_psrad128 (v4si, v4si) 21933v2di __builtin_ia32_pslldqi128 (v2di, int) 21934v8hi __builtin_ia32_psllwi128 (v8hi, int) 21935v4si __builtin_ia32_pslldi128 (v4si, int) 21936v2di __builtin_ia32_psllqi128 (v2di, int) 21937v2di __builtin_ia32_psrldqi128 (v2di, int) 21938v8hi __builtin_ia32_psrlwi128 (v8hi, int) 21939v4si __builtin_ia32_psrldi128 (v4si, int) 21940v2di __builtin_ia32_psrlqi128 (v2di, int) 21941v8hi __builtin_ia32_psrawi128 (v8hi, int) 21942v4si __builtin_ia32_psradi128 (v4si, int) 21943v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi) 21944v2di __builtin_ia32_movq128 (v2di) 21945@end smallexample 21946 21947The following built-in functions are available when @option{-msse3} is used. 21948All of them generate the machine instruction that is part of the name. 21949 21950@smallexample 21951v2df __builtin_ia32_addsubpd (v2df, v2df) 21952v4sf __builtin_ia32_addsubps (v4sf, v4sf) 21953v2df __builtin_ia32_haddpd (v2df, v2df) 21954v4sf __builtin_ia32_haddps (v4sf, v4sf) 21955v2df __builtin_ia32_hsubpd (v2df, v2df) 21956v4sf __builtin_ia32_hsubps (v4sf, v4sf) 21957v16qi __builtin_ia32_lddqu (char const *) 21958void __builtin_ia32_monitor (void *, unsigned int, unsigned int) 21959v4sf __builtin_ia32_movshdup (v4sf) 21960v4sf __builtin_ia32_movsldup (v4sf) 21961void __builtin_ia32_mwait (unsigned int, unsigned int) 21962@end smallexample 21963 21964The following built-in functions are available when @option{-mssse3} is used. 21965All of them generate the machine instruction that is part of the name. 21966 21967@smallexample 21968v2si __builtin_ia32_phaddd (v2si, v2si) 21969v4hi __builtin_ia32_phaddw (v4hi, v4hi) 21970v4hi __builtin_ia32_phaddsw (v4hi, v4hi) 21971v2si __builtin_ia32_phsubd (v2si, v2si) 21972v4hi __builtin_ia32_phsubw (v4hi, v4hi) 21973v4hi __builtin_ia32_phsubsw (v4hi, v4hi) 21974v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi) 21975v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi) 21976v8qi __builtin_ia32_pshufb (v8qi, v8qi) 21977v8qi __builtin_ia32_psignb (v8qi, v8qi) 21978v2si __builtin_ia32_psignd (v2si, v2si) 21979v4hi __builtin_ia32_psignw (v4hi, v4hi) 21980v1di __builtin_ia32_palignr (v1di, v1di, int) 21981v8qi __builtin_ia32_pabsb (v8qi) 21982v2si __builtin_ia32_pabsd (v2si) 21983v4hi __builtin_ia32_pabsw (v4hi) 21984@end smallexample 21985 21986The following built-in functions are available when @option{-mssse3} is used. 21987All of them generate the machine instruction that is part of the name. 21988 21989@smallexample 21990v4si __builtin_ia32_phaddd128 (v4si, v4si) 21991v8hi __builtin_ia32_phaddw128 (v8hi, v8hi) 21992v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi) 21993v4si __builtin_ia32_phsubd128 (v4si, v4si) 21994v8hi __builtin_ia32_phsubw128 (v8hi, v8hi) 21995v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi) 21996v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi) 21997v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi) 21998v16qi __builtin_ia32_pshufb128 (v16qi, v16qi) 21999v16qi __builtin_ia32_psignb128 (v16qi, v16qi) 22000v4si __builtin_ia32_psignd128 (v4si, v4si) 22001v8hi __builtin_ia32_psignw128 (v8hi, v8hi) 22002v2di __builtin_ia32_palignr128 (v2di, v2di, int) 22003v16qi __builtin_ia32_pabsb128 (v16qi) 22004v4si __builtin_ia32_pabsd128 (v4si) 22005v8hi __builtin_ia32_pabsw128 (v8hi) 22006@end smallexample 22007 22008The following built-in functions are available when @option{-msse4.1} is 22009used. All of them generate the machine instruction that is part of the 22010name. 22011 22012@smallexample 22013v2df __builtin_ia32_blendpd (v2df, v2df, const int) 22014v4sf __builtin_ia32_blendps (v4sf, v4sf, const int) 22015v2df __builtin_ia32_blendvpd (v2df, v2df, v2df) 22016v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf) 22017v2df __builtin_ia32_dppd (v2df, v2df, const int) 22018v4sf __builtin_ia32_dpps (v4sf, v4sf, const int) 22019v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int) 22020v2di __builtin_ia32_movntdqa (v2di *); 22021v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int) 22022v8hi __builtin_ia32_packusdw128 (v4si, v4si) 22023v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi) 22024v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int) 22025v2di __builtin_ia32_pcmpeqq (v2di, v2di) 22026v8hi __builtin_ia32_phminposuw128 (v8hi) 22027v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi) 22028v4si __builtin_ia32_pmaxsd128 (v4si, v4si) 22029v4si __builtin_ia32_pmaxud128 (v4si, v4si) 22030v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi) 22031v16qi __builtin_ia32_pminsb128 (v16qi, v16qi) 22032v4si __builtin_ia32_pminsd128 (v4si, v4si) 22033v4si __builtin_ia32_pminud128 (v4si, v4si) 22034v8hi __builtin_ia32_pminuw128 (v8hi, v8hi) 22035v4si __builtin_ia32_pmovsxbd128 (v16qi) 22036v2di __builtin_ia32_pmovsxbq128 (v16qi) 22037v8hi __builtin_ia32_pmovsxbw128 (v16qi) 22038v2di __builtin_ia32_pmovsxdq128 (v4si) 22039v4si __builtin_ia32_pmovsxwd128 (v8hi) 22040v2di __builtin_ia32_pmovsxwq128 (v8hi) 22041v4si __builtin_ia32_pmovzxbd128 (v16qi) 22042v2di __builtin_ia32_pmovzxbq128 (v16qi) 22043v8hi __builtin_ia32_pmovzxbw128 (v16qi) 22044v2di __builtin_ia32_pmovzxdq128 (v4si) 22045v4si __builtin_ia32_pmovzxwd128 (v8hi) 22046v2di __builtin_ia32_pmovzxwq128 (v8hi) 22047v2di __builtin_ia32_pmuldq128 (v4si, v4si) 22048v4si __builtin_ia32_pmulld128 (v4si, v4si) 22049int __builtin_ia32_ptestc128 (v2di, v2di) 22050int __builtin_ia32_ptestnzc128 (v2di, v2di) 22051int __builtin_ia32_ptestz128 (v2di, v2di) 22052v2df __builtin_ia32_roundpd (v2df, const int) 22053v4sf __builtin_ia32_roundps (v4sf, const int) 22054v2df __builtin_ia32_roundsd (v2df, v2df, const int) 22055v4sf __builtin_ia32_roundss (v4sf, v4sf, const int) 22056@end smallexample 22057 22058The following built-in functions are available when @option{-msse4.1} is 22059used. 22060 22061@table @code 22062@item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int) 22063Generates the @code{insertps} machine instruction. 22064@item int __builtin_ia32_vec_ext_v16qi (v16qi, const int) 22065Generates the @code{pextrb} machine instruction. 22066@item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int) 22067Generates the @code{pinsrb} machine instruction. 22068@item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int) 22069Generates the @code{pinsrd} machine instruction. 22070@item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int) 22071Generates the @code{pinsrq} machine instruction in 64bit mode. 22072@end table 22073 22074The following built-in functions are changed to generate new SSE4.1 22075instructions when @option{-msse4.1} is used. 22076 22077@table @code 22078@item float __builtin_ia32_vec_ext_v4sf (v4sf, const int) 22079Generates the @code{extractps} machine instruction. 22080@item int __builtin_ia32_vec_ext_v4si (v4si, const int) 22081Generates the @code{pextrd} machine instruction. 22082@item long long __builtin_ia32_vec_ext_v2di (v2di, const int) 22083Generates the @code{pextrq} machine instruction in 64bit mode. 22084@end table 22085 22086The following built-in functions are available when @option{-msse4.2} is 22087used. All of them generate the machine instruction that is part of the 22088name. 22089 22090@smallexample 22091v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int) 22092int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int) 22093int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int) 22094int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int) 22095int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int) 22096int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int) 22097int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int) 22098v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int) 22099int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int) 22100int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int) 22101int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int) 22102int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int) 22103int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int) 22104int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int) 22105v2di __builtin_ia32_pcmpgtq (v2di, v2di) 22106@end smallexample 22107 22108The following built-in functions are available when @option{-msse4.2} is 22109used. 22110 22111@table @code 22112@item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char) 22113Generates the @code{crc32b} machine instruction. 22114@item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short) 22115Generates the @code{crc32w} machine instruction. 22116@item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int) 22117Generates the @code{crc32l} machine instruction. 22118@item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long) 22119Generates the @code{crc32q} machine instruction. 22120@end table 22121 22122The following built-in functions are changed to generate new SSE4.2 22123instructions when @option{-msse4.2} is used. 22124 22125@table @code 22126@item int __builtin_popcount (unsigned int) 22127Generates the @code{popcntl} machine instruction. 22128@item int __builtin_popcountl (unsigned long) 22129Generates the @code{popcntl} or @code{popcntq} machine instruction, 22130depending on the size of @code{unsigned long}. 22131@item int __builtin_popcountll (unsigned long long) 22132Generates the @code{popcntq} machine instruction. 22133@end table 22134 22135The following built-in functions are available when @option{-mavx} is 22136used. All of them generate the machine instruction that is part of the 22137name. 22138 22139@smallexample 22140v4df __builtin_ia32_addpd256 (v4df,v4df) 22141v8sf __builtin_ia32_addps256 (v8sf,v8sf) 22142v4df __builtin_ia32_addsubpd256 (v4df,v4df) 22143v8sf __builtin_ia32_addsubps256 (v8sf,v8sf) 22144v4df __builtin_ia32_andnpd256 (v4df,v4df) 22145v8sf __builtin_ia32_andnps256 (v8sf,v8sf) 22146v4df __builtin_ia32_andpd256 (v4df,v4df) 22147v8sf __builtin_ia32_andps256 (v8sf,v8sf) 22148v4df __builtin_ia32_blendpd256 (v4df,v4df,int) 22149v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int) 22150v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df) 22151v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf) 22152v2df __builtin_ia32_cmppd (v2df,v2df,int) 22153v4df __builtin_ia32_cmppd256 (v4df,v4df,int) 22154v4sf __builtin_ia32_cmpps (v4sf,v4sf,int) 22155v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int) 22156v2df __builtin_ia32_cmpsd (v2df,v2df,int) 22157v4sf __builtin_ia32_cmpss (v4sf,v4sf,int) 22158v4df __builtin_ia32_cvtdq2pd256 (v4si) 22159v8sf __builtin_ia32_cvtdq2ps256 (v8si) 22160v4si __builtin_ia32_cvtpd2dq256 (v4df) 22161v4sf __builtin_ia32_cvtpd2ps256 (v4df) 22162v8si __builtin_ia32_cvtps2dq256 (v8sf) 22163v4df __builtin_ia32_cvtps2pd256 (v4sf) 22164v4si __builtin_ia32_cvttpd2dq256 (v4df) 22165v8si __builtin_ia32_cvttps2dq256 (v8sf) 22166v4df __builtin_ia32_divpd256 (v4df,v4df) 22167v8sf __builtin_ia32_divps256 (v8sf,v8sf) 22168v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int) 22169v4df __builtin_ia32_haddpd256 (v4df,v4df) 22170v8sf __builtin_ia32_haddps256 (v8sf,v8sf) 22171v4df __builtin_ia32_hsubpd256 (v4df,v4df) 22172v8sf __builtin_ia32_hsubps256 (v8sf,v8sf) 22173v32qi __builtin_ia32_lddqu256 (pcchar) 22174v32qi __builtin_ia32_loaddqu256 (pcchar) 22175v4df __builtin_ia32_loadupd256 (pcdouble) 22176v8sf __builtin_ia32_loadups256 (pcfloat) 22177v2df __builtin_ia32_maskloadpd (pcv2df,v2df) 22178v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df) 22179v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf) 22180v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf) 22181void __builtin_ia32_maskstorepd (pv2df,v2df,v2df) 22182void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df) 22183void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf) 22184void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf) 22185v4df __builtin_ia32_maxpd256 (v4df,v4df) 22186v8sf __builtin_ia32_maxps256 (v8sf,v8sf) 22187v4df __builtin_ia32_minpd256 (v4df,v4df) 22188v8sf __builtin_ia32_minps256 (v8sf,v8sf) 22189v4df __builtin_ia32_movddup256 (v4df) 22190int __builtin_ia32_movmskpd256 (v4df) 22191int __builtin_ia32_movmskps256 (v8sf) 22192v8sf __builtin_ia32_movshdup256 (v8sf) 22193v8sf __builtin_ia32_movsldup256 (v8sf) 22194v4df __builtin_ia32_mulpd256 (v4df,v4df) 22195v8sf __builtin_ia32_mulps256 (v8sf,v8sf) 22196v4df __builtin_ia32_orpd256 (v4df,v4df) 22197v8sf __builtin_ia32_orps256 (v8sf,v8sf) 22198v2df __builtin_ia32_pd_pd256 (v4df) 22199v4df __builtin_ia32_pd256_pd (v2df) 22200v4sf __builtin_ia32_ps_ps256 (v8sf) 22201v8sf __builtin_ia32_ps256_ps (v4sf) 22202int __builtin_ia32_ptestc256 (v4di,v4di,ptest) 22203int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest) 22204int __builtin_ia32_ptestz256 (v4di,v4di,ptest) 22205v8sf __builtin_ia32_rcpps256 (v8sf) 22206v4df __builtin_ia32_roundpd256 (v4df,int) 22207v8sf __builtin_ia32_roundps256 (v8sf,int) 22208v8sf __builtin_ia32_rsqrtps_nr256 (v8sf) 22209v8sf __builtin_ia32_rsqrtps256 (v8sf) 22210v4df __builtin_ia32_shufpd256 (v4df,v4df,int) 22211v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int) 22212v4si __builtin_ia32_si_si256 (v8si) 22213v8si __builtin_ia32_si256_si (v4si) 22214v4df __builtin_ia32_sqrtpd256 (v4df) 22215v8sf __builtin_ia32_sqrtps_nr256 (v8sf) 22216v8sf __builtin_ia32_sqrtps256 (v8sf) 22217void __builtin_ia32_storedqu256 (pchar,v32qi) 22218void __builtin_ia32_storeupd256 (pdouble,v4df) 22219void __builtin_ia32_storeups256 (pfloat,v8sf) 22220v4df __builtin_ia32_subpd256 (v4df,v4df) 22221v8sf __builtin_ia32_subps256 (v8sf,v8sf) 22222v4df __builtin_ia32_unpckhpd256 (v4df,v4df) 22223v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf) 22224v4df __builtin_ia32_unpcklpd256 (v4df,v4df) 22225v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf) 22226v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df) 22227v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf) 22228v4df __builtin_ia32_vbroadcastsd256 (pcdouble) 22229v4sf __builtin_ia32_vbroadcastss (pcfloat) 22230v8sf __builtin_ia32_vbroadcastss256 (pcfloat) 22231v2df __builtin_ia32_vextractf128_pd256 (v4df,int) 22232v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int) 22233v4si __builtin_ia32_vextractf128_si256 (v8si,int) 22234v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int) 22235v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int) 22236v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int) 22237v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int) 22238v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int) 22239v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int) 22240v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int) 22241v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int) 22242v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int) 22243v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int) 22244v2df __builtin_ia32_vpermilpd (v2df,int) 22245v4df __builtin_ia32_vpermilpd256 (v4df,int) 22246v4sf __builtin_ia32_vpermilps (v4sf,int) 22247v8sf __builtin_ia32_vpermilps256 (v8sf,int) 22248v2df __builtin_ia32_vpermilvarpd (v2df,v2di) 22249v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di) 22250v4sf __builtin_ia32_vpermilvarps (v4sf,v4si) 22251v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si) 22252int __builtin_ia32_vtestcpd (v2df,v2df,ptest) 22253int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest) 22254int __builtin_ia32_vtestcps (v4sf,v4sf,ptest) 22255int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest) 22256int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest) 22257int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest) 22258int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest) 22259int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest) 22260int __builtin_ia32_vtestzpd (v2df,v2df,ptest) 22261int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest) 22262int __builtin_ia32_vtestzps (v4sf,v4sf,ptest) 22263int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest) 22264void __builtin_ia32_vzeroall (void) 22265void __builtin_ia32_vzeroupper (void) 22266v4df __builtin_ia32_xorpd256 (v4df,v4df) 22267v8sf __builtin_ia32_xorps256 (v8sf,v8sf) 22268@end smallexample 22269 22270The following built-in functions are available when @option{-mavx2} is 22271used. All of them generate the machine instruction that is part of the 22272name. 22273 22274@smallexample 22275v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int) 22276v32qi __builtin_ia32_pabsb256 (v32qi) 22277v16hi __builtin_ia32_pabsw256 (v16hi) 22278v8si __builtin_ia32_pabsd256 (v8si) 22279v16hi __builtin_ia32_packssdw256 (v8si,v8si) 22280v32qi __builtin_ia32_packsswb256 (v16hi,v16hi) 22281v16hi __builtin_ia32_packusdw256 (v8si,v8si) 22282v32qi __builtin_ia32_packuswb256 (v16hi,v16hi) 22283v32qi __builtin_ia32_paddb256 (v32qi,v32qi) 22284v16hi __builtin_ia32_paddw256 (v16hi,v16hi) 22285v8si __builtin_ia32_paddd256 (v8si,v8si) 22286v4di __builtin_ia32_paddq256 (v4di,v4di) 22287v32qi __builtin_ia32_paddsb256 (v32qi,v32qi) 22288v16hi __builtin_ia32_paddsw256 (v16hi,v16hi) 22289v32qi __builtin_ia32_paddusb256 (v32qi,v32qi) 22290v16hi __builtin_ia32_paddusw256 (v16hi,v16hi) 22291v4di __builtin_ia32_palignr256 (v4di,v4di,int) 22292v4di __builtin_ia32_andsi256 (v4di,v4di) 22293v4di __builtin_ia32_andnotsi256 (v4di,v4di) 22294v32qi __builtin_ia32_pavgb256 (v32qi,v32qi) 22295v16hi __builtin_ia32_pavgw256 (v16hi,v16hi) 22296v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi) 22297v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int) 22298v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi) 22299v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi) 22300v8si __builtin_ia32_pcmpeqd256 (c8si,v8si) 22301v4di __builtin_ia32_pcmpeqq256 (v4di,v4di) 22302v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi) 22303v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi) 22304v8si __builtin_ia32_pcmpgtd256 (v8si,v8si) 22305v4di __builtin_ia32_pcmpgtq256 (v4di,v4di) 22306v16hi __builtin_ia32_phaddw256 (v16hi,v16hi) 22307v8si __builtin_ia32_phaddd256 (v8si,v8si) 22308v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi) 22309v16hi __builtin_ia32_phsubw256 (v16hi,v16hi) 22310v8si __builtin_ia32_phsubd256 (v8si,v8si) 22311v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi) 22312v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi) 22313v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi) 22314v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi) 22315v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi) 22316v8si __builtin_ia32_pmaxsd256 (v8si,v8si) 22317v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi) 22318v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi) 22319v8si __builtin_ia32_pmaxud256 (v8si,v8si) 22320v32qi __builtin_ia32_pminsb256 (v32qi,v32qi) 22321v16hi __builtin_ia32_pminsw256 (v16hi,v16hi) 22322v8si __builtin_ia32_pminsd256 (v8si,v8si) 22323v32qi __builtin_ia32_pminub256 (v32qi,v32qi) 22324v16hi __builtin_ia32_pminuw256 (v16hi,v16hi) 22325v8si __builtin_ia32_pminud256 (v8si,v8si) 22326int __builtin_ia32_pmovmskb256 (v32qi) 22327v16hi __builtin_ia32_pmovsxbw256 (v16qi) 22328v8si __builtin_ia32_pmovsxbd256 (v16qi) 22329v4di __builtin_ia32_pmovsxbq256 (v16qi) 22330v8si __builtin_ia32_pmovsxwd256 (v8hi) 22331v4di __builtin_ia32_pmovsxwq256 (v8hi) 22332v4di __builtin_ia32_pmovsxdq256 (v4si) 22333v16hi __builtin_ia32_pmovzxbw256 (v16qi) 22334v8si __builtin_ia32_pmovzxbd256 (v16qi) 22335v4di __builtin_ia32_pmovzxbq256 (v16qi) 22336v8si __builtin_ia32_pmovzxwd256 (v8hi) 22337v4di __builtin_ia32_pmovzxwq256 (v8hi) 22338v4di __builtin_ia32_pmovzxdq256 (v4si) 22339v4di __builtin_ia32_pmuldq256 (v8si,v8si) 22340v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi) 22341v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi) 22342v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi) 22343v16hi __builtin_ia32_pmullw256 (v16hi,v16hi) 22344v8si __builtin_ia32_pmulld256 (v8si,v8si) 22345v4di __builtin_ia32_pmuludq256 (v8si,v8si) 22346v4di __builtin_ia32_por256 (v4di,v4di) 22347v16hi __builtin_ia32_psadbw256 (v32qi,v32qi) 22348v32qi __builtin_ia32_pshufb256 (v32qi,v32qi) 22349v8si __builtin_ia32_pshufd256 (v8si,int) 22350v16hi __builtin_ia32_pshufhw256 (v16hi,int) 22351v16hi __builtin_ia32_pshuflw256 (v16hi,int) 22352v32qi __builtin_ia32_psignb256 (v32qi,v32qi) 22353v16hi __builtin_ia32_psignw256 (v16hi,v16hi) 22354v8si __builtin_ia32_psignd256 (v8si,v8si) 22355v4di __builtin_ia32_pslldqi256 (v4di,int) 22356v16hi __builtin_ia32_psllwi256 (16hi,int) 22357v16hi __builtin_ia32_psllw256(v16hi,v8hi) 22358v8si __builtin_ia32_pslldi256 (v8si,int) 22359v8si __builtin_ia32_pslld256(v8si,v4si) 22360v4di __builtin_ia32_psllqi256 (v4di,int) 22361v4di __builtin_ia32_psllq256(v4di,v2di) 22362v16hi __builtin_ia32_psrawi256 (v16hi,int) 22363v16hi __builtin_ia32_psraw256 (v16hi,v8hi) 22364v8si __builtin_ia32_psradi256 (v8si,int) 22365v8si __builtin_ia32_psrad256 (v8si,v4si) 22366v4di __builtin_ia32_psrldqi256 (v4di, int) 22367v16hi __builtin_ia32_psrlwi256 (v16hi,int) 22368v16hi __builtin_ia32_psrlw256 (v16hi,v8hi) 22369v8si __builtin_ia32_psrldi256 (v8si,int) 22370v8si __builtin_ia32_psrld256 (v8si,v4si) 22371v4di __builtin_ia32_psrlqi256 (v4di,int) 22372v4di __builtin_ia32_psrlq256(v4di,v2di) 22373v32qi __builtin_ia32_psubb256 (v32qi,v32qi) 22374v32hi __builtin_ia32_psubw256 (v16hi,v16hi) 22375v8si __builtin_ia32_psubd256 (v8si,v8si) 22376v4di __builtin_ia32_psubq256 (v4di,v4di) 22377v32qi __builtin_ia32_psubsb256 (v32qi,v32qi) 22378v16hi __builtin_ia32_psubsw256 (v16hi,v16hi) 22379v32qi __builtin_ia32_psubusb256 (v32qi,v32qi) 22380v16hi __builtin_ia32_psubusw256 (v16hi,v16hi) 22381v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi) 22382v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi) 22383v8si __builtin_ia32_punpckhdq256 (v8si,v8si) 22384v4di __builtin_ia32_punpckhqdq256 (v4di,v4di) 22385v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi) 22386v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi) 22387v8si __builtin_ia32_punpckldq256 (v8si,v8si) 22388v4di __builtin_ia32_punpcklqdq256 (v4di,v4di) 22389v4di __builtin_ia32_pxor256 (v4di,v4di) 22390v4di __builtin_ia32_movntdqa256 (pv4di) 22391v4sf __builtin_ia32_vbroadcastss_ps (v4sf) 22392v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf) 22393v4df __builtin_ia32_vbroadcastsd_pd256 (v2df) 22394v4di __builtin_ia32_vbroadcastsi256 (v2di) 22395v4si __builtin_ia32_pblendd128 (v4si,v4si) 22396v8si __builtin_ia32_pblendd256 (v8si,v8si) 22397v32qi __builtin_ia32_pbroadcastb256 (v16qi) 22398v16hi __builtin_ia32_pbroadcastw256 (v8hi) 22399v8si __builtin_ia32_pbroadcastd256 (v4si) 22400v4di __builtin_ia32_pbroadcastq256 (v2di) 22401v16qi __builtin_ia32_pbroadcastb128 (v16qi) 22402v8hi __builtin_ia32_pbroadcastw128 (v8hi) 22403v4si __builtin_ia32_pbroadcastd128 (v4si) 22404v2di __builtin_ia32_pbroadcastq128 (v2di) 22405v8si __builtin_ia32_permvarsi256 (v8si,v8si) 22406v4df __builtin_ia32_permdf256 (v4df,int) 22407v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf) 22408v4di __builtin_ia32_permdi256 (v4di,int) 22409v4di __builtin_ia32_permti256 (v4di,v4di,int) 22410v4di __builtin_ia32_extract128i256 (v4di,int) 22411v4di __builtin_ia32_insert128i256 (v4di,v2di,int) 22412v8si __builtin_ia32_maskloadd256 (pcv8si,v8si) 22413v4di __builtin_ia32_maskloadq256 (pcv4di,v4di) 22414v4si __builtin_ia32_maskloadd (pcv4si,v4si) 22415v2di __builtin_ia32_maskloadq (pcv2di,v2di) 22416void __builtin_ia32_maskstored256 (pv8si,v8si,v8si) 22417void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di) 22418void __builtin_ia32_maskstored (pv4si,v4si,v4si) 22419void __builtin_ia32_maskstoreq (pv2di,v2di,v2di) 22420v8si __builtin_ia32_psllv8si (v8si,v8si) 22421v4si __builtin_ia32_psllv4si (v4si,v4si) 22422v4di __builtin_ia32_psllv4di (v4di,v4di) 22423v2di __builtin_ia32_psllv2di (v2di,v2di) 22424v8si __builtin_ia32_psrav8si (v8si,v8si) 22425v4si __builtin_ia32_psrav4si (v4si,v4si) 22426v8si __builtin_ia32_psrlv8si (v8si,v8si) 22427v4si __builtin_ia32_psrlv4si (v4si,v4si) 22428v4di __builtin_ia32_psrlv4di (v4di,v4di) 22429v2di __builtin_ia32_psrlv2di (v2di,v2di) 22430v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int) 22431v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int) 22432v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int) 22433v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int) 22434v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int) 22435v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int) 22436v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int) 22437v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int) 22438v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int) 22439v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int) 22440v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int) 22441v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int) 22442v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int) 22443v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int) 22444v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int) 22445v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int) 22446@end smallexample 22447 22448The following built-in functions are available when @option{-maes} is 22449used. All of them generate the machine instruction that is part of the 22450name. 22451 22452@smallexample 22453v2di __builtin_ia32_aesenc128 (v2di, v2di) 22454v2di __builtin_ia32_aesenclast128 (v2di, v2di) 22455v2di __builtin_ia32_aesdec128 (v2di, v2di) 22456v2di __builtin_ia32_aesdeclast128 (v2di, v2di) 22457v2di __builtin_ia32_aeskeygenassist128 (v2di, const int) 22458v2di __builtin_ia32_aesimc128 (v2di) 22459@end smallexample 22460 22461The following built-in function is available when @option{-mpclmul} is 22462used. 22463 22464@table @code 22465@item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int) 22466Generates the @code{pclmulqdq} machine instruction. 22467@end table 22468 22469The following built-in function is available when @option{-mfsgsbase} is 22470used. All of them generate the machine instruction that is part of the 22471name. 22472 22473@smallexample 22474unsigned int __builtin_ia32_rdfsbase32 (void) 22475unsigned long long __builtin_ia32_rdfsbase64 (void) 22476unsigned int __builtin_ia32_rdgsbase32 (void) 22477unsigned long long __builtin_ia32_rdgsbase64 (void) 22478void _writefsbase_u32 (unsigned int) 22479void _writefsbase_u64 (unsigned long long) 22480void _writegsbase_u32 (unsigned int) 22481void _writegsbase_u64 (unsigned long long) 22482@end smallexample 22483 22484The following built-in function is available when @option{-mrdrnd} is 22485used. All of them generate the machine instruction that is part of the 22486name. 22487 22488@smallexample 22489unsigned int __builtin_ia32_rdrand16_step (unsigned short *) 22490unsigned int __builtin_ia32_rdrand32_step (unsigned int *) 22491unsigned int __builtin_ia32_rdrand64_step (unsigned long long *) 22492@end smallexample 22493 22494The following built-in function is available when @option{-mptwrite} is 22495used. All of them generate the machine instruction that is part of the 22496name. 22497 22498@smallexample 22499void __builtin_ia32_ptwrite32 (unsigned) 22500void __builtin_ia32_ptwrite64 (unsigned long long) 22501@end smallexample 22502 22503The following built-in functions are available when @option{-msse4a} is used. 22504All of them generate the machine instruction that is part of the name. 22505 22506@smallexample 22507void __builtin_ia32_movntsd (double *, v2df) 22508void __builtin_ia32_movntss (float *, v4sf) 22509v2di __builtin_ia32_extrq (v2di, v16qi) 22510v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int) 22511v2di __builtin_ia32_insertq (v2di, v2di) 22512v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int) 22513@end smallexample 22514 22515The following built-in functions are available when @option{-mxop} is used. 22516@smallexample 22517v2df __builtin_ia32_vfrczpd (v2df) 22518v4sf __builtin_ia32_vfrczps (v4sf) 22519v2df __builtin_ia32_vfrczsd (v2df) 22520v4sf __builtin_ia32_vfrczss (v4sf) 22521v4df __builtin_ia32_vfrczpd256 (v4df) 22522v8sf __builtin_ia32_vfrczps256 (v8sf) 22523v2di __builtin_ia32_vpcmov (v2di, v2di, v2di) 22524v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di) 22525v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si) 22526v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi) 22527v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi) 22528v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df) 22529v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf) 22530v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di) 22531v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si) 22532v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi) 22533v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi) 22534v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df) 22535v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf) 22536v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi) 22537v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi) 22538v4si __builtin_ia32_vpcomeqd (v4si, v4si) 22539v2di __builtin_ia32_vpcomeqq (v2di, v2di) 22540v16qi __builtin_ia32_vpcomequb (v16qi, v16qi) 22541v4si __builtin_ia32_vpcomequd (v4si, v4si) 22542v2di __builtin_ia32_vpcomequq (v2di, v2di) 22543v8hi __builtin_ia32_vpcomequw (v8hi, v8hi) 22544v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi) 22545v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi) 22546v4si __builtin_ia32_vpcomfalsed (v4si, v4si) 22547v2di __builtin_ia32_vpcomfalseq (v2di, v2di) 22548v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi) 22549v4si __builtin_ia32_vpcomfalseud (v4si, v4si) 22550v2di __builtin_ia32_vpcomfalseuq (v2di, v2di) 22551v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi) 22552v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi) 22553v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi) 22554v4si __builtin_ia32_vpcomged (v4si, v4si) 22555v2di __builtin_ia32_vpcomgeq (v2di, v2di) 22556v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi) 22557v4si __builtin_ia32_vpcomgeud (v4si, v4si) 22558v2di __builtin_ia32_vpcomgeuq (v2di, v2di) 22559v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi) 22560v8hi __builtin_ia32_vpcomgew (v8hi, v8hi) 22561v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi) 22562v4si __builtin_ia32_vpcomgtd (v4si, v4si) 22563v2di __builtin_ia32_vpcomgtq (v2di, v2di) 22564v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi) 22565v4si __builtin_ia32_vpcomgtud (v4si, v4si) 22566v2di __builtin_ia32_vpcomgtuq (v2di, v2di) 22567v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi) 22568v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi) 22569v16qi __builtin_ia32_vpcomleb (v16qi, v16qi) 22570v4si __builtin_ia32_vpcomled (v4si, v4si) 22571v2di __builtin_ia32_vpcomleq (v2di, v2di) 22572v16qi __builtin_ia32_vpcomleub (v16qi, v16qi) 22573v4si __builtin_ia32_vpcomleud (v4si, v4si) 22574v2di __builtin_ia32_vpcomleuq (v2di, v2di) 22575v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi) 22576v8hi __builtin_ia32_vpcomlew (v8hi, v8hi) 22577v16qi __builtin_ia32_vpcomltb (v16qi, v16qi) 22578v4si __builtin_ia32_vpcomltd (v4si, v4si) 22579v2di __builtin_ia32_vpcomltq (v2di, v2di) 22580v16qi __builtin_ia32_vpcomltub (v16qi, v16qi) 22581v4si __builtin_ia32_vpcomltud (v4si, v4si) 22582v2di __builtin_ia32_vpcomltuq (v2di, v2di) 22583v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi) 22584v8hi __builtin_ia32_vpcomltw (v8hi, v8hi) 22585v16qi __builtin_ia32_vpcomneb (v16qi, v16qi) 22586v4si __builtin_ia32_vpcomned (v4si, v4si) 22587v2di __builtin_ia32_vpcomneq (v2di, v2di) 22588v16qi __builtin_ia32_vpcomneub (v16qi, v16qi) 22589v4si __builtin_ia32_vpcomneud (v4si, v4si) 22590v2di __builtin_ia32_vpcomneuq (v2di, v2di) 22591v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi) 22592v8hi __builtin_ia32_vpcomnew (v8hi, v8hi) 22593v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi) 22594v4si __builtin_ia32_vpcomtrued (v4si, v4si) 22595v2di __builtin_ia32_vpcomtrueq (v2di, v2di) 22596v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi) 22597v4si __builtin_ia32_vpcomtrueud (v4si, v4si) 22598v2di __builtin_ia32_vpcomtrueuq (v2di, v2di) 22599v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi) 22600v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi) 22601v4si __builtin_ia32_vphaddbd (v16qi) 22602v2di __builtin_ia32_vphaddbq (v16qi) 22603v8hi __builtin_ia32_vphaddbw (v16qi) 22604v2di __builtin_ia32_vphadddq (v4si) 22605v4si __builtin_ia32_vphaddubd (v16qi) 22606v2di __builtin_ia32_vphaddubq (v16qi) 22607v8hi __builtin_ia32_vphaddubw (v16qi) 22608v2di __builtin_ia32_vphaddudq (v4si) 22609v4si __builtin_ia32_vphadduwd (v8hi) 22610v2di __builtin_ia32_vphadduwq (v8hi) 22611v4si __builtin_ia32_vphaddwd (v8hi) 22612v2di __builtin_ia32_vphaddwq (v8hi) 22613v8hi __builtin_ia32_vphsubbw (v16qi) 22614v2di __builtin_ia32_vphsubdq (v4si) 22615v4si __builtin_ia32_vphsubwd (v8hi) 22616v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si) 22617v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di) 22618v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di) 22619v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si) 22620v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di) 22621v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di) 22622v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si) 22623v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi) 22624v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si) 22625v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi) 22626v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si) 22627v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si) 22628v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi) 22629v16qi __builtin_ia32_vprotb (v16qi, v16qi) 22630v4si __builtin_ia32_vprotd (v4si, v4si) 22631v2di __builtin_ia32_vprotq (v2di, v2di) 22632v8hi __builtin_ia32_vprotw (v8hi, v8hi) 22633v16qi __builtin_ia32_vpshab (v16qi, v16qi) 22634v4si __builtin_ia32_vpshad (v4si, v4si) 22635v2di __builtin_ia32_vpshaq (v2di, v2di) 22636v8hi __builtin_ia32_vpshaw (v8hi, v8hi) 22637v16qi __builtin_ia32_vpshlb (v16qi, v16qi) 22638v4si __builtin_ia32_vpshld (v4si, v4si) 22639v2di __builtin_ia32_vpshlq (v2di, v2di) 22640v8hi __builtin_ia32_vpshlw (v8hi, v8hi) 22641@end smallexample 22642 22643The following built-in functions are available when @option{-mfma4} is used. 22644All of them generate the machine instruction that is part of the name. 22645 22646@smallexample 22647v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df) 22648v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf) 22649v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df) 22650v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf) 22651v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df) 22652v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf) 22653v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df) 22654v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf) 22655v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df) 22656v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf) 22657v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df) 22658v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf) 22659v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df) 22660v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf) 22661v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df) 22662v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf) 22663v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df) 22664v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf) 22665v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df) 22666v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf) 22667v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df) 22668v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf) 22669v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df) 22670v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf) 22671v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df) 22672v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf) 22673v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df) 22674v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf) 22675v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df) 22676v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf) 22677v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df) 22678v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf) 22679 22680@end smallexample 22681 22682The following built-in functions are available when @option{-mlwp} is used. 22683 22684@smallexample 22685void __builtin_ia32_llwpcb16 (void *); 22686void __builtin_ia32_llwpcb32 (void *); 22687void __builtin_ia32_llwpcb64 (void *); 22688void * __builtin_ia32_llwpcb16 (void); 22689void * __builtin_ia32_llwpcb32 (void); 22690void * __builtin_ia32_llwpcb64 (void); 22691void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short) 22692void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int) 22693void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int) 22694unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short) 22695unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int) 22696unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int) 22697@end smallexample 22698 22699The following built-in functions are available when @option{-mbmi} is used. 22700All of them generate the machine instruction that is part of the name. 22701@smallexample 22702unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int); 22703unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long); 22704@end smallexample 22705 22706The following built-in functions are available when @option{-mbmi2} is used. 22707All of them generate the machine instruction that is part of the name. 22708@smallexample 22709unsigned int _bzhi_u32 (unsigned int, unsigned int) 22710unsigned int _pdep_u32 (unsigned int, unsigned int) 22711unsigned int _pext_u32 (unsigned int, unsigned int) 22712unsigned long long _bzhi_u64 (unsigned long long, unsigned long long) 22713unsigned long long _pdep_u64 (unsigned long long, unsigned long long) 22714unsigned long long _pext_u64 (unsigned long long, unsigned long long) 22715@end smallexample 22716 22717The following built-in functions are available when @option{-mlzcnt} is used. 22718All of them generate the machine instruction that is part of the name. 22719@smallexample 22720unsigned short __builtin_ia32_lzcnt_u16(unsigned short); 22721unsigned int __builtin_ia32_lzcnt_u32(unsigned int); 22722unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long); 22723@end smallexample 22724 22725The following built-in functions are available when @option{-mfxsr} is used. 22726All of them generate the machine instruction that is part of the name. 22727@smallexample 22728void __builtin_ia32_fxsave (void *) 22729void __builtin_ia32_fxrstor (void *) 22730void __builtin_ia32_fxsave64 (void *) 22731void __builtin_ia32_fxrstor64 (void *) 22732@end smallexample 22733 22734The following built-in functions are available when @option{-mxsave} is used. 22735All of them generate the machine instruction that is part of the name. 22736@smallexample 22737void __builtin_ia32_xsave (void *, long long) 22738void __builtin_ia32_xrstor (void *, long long) 22739void __builtin_ia32_xsave64 (void *, long long) 22740void __builtin_ia32_xrstor64 (void *, long long) 22741@end smallexample 22742 22743The following built-in functions are available when @option{-mxsaveopt} is used. 22744All of them generate the machine instruction that is part of the name. 22745@smallexample 22746void __builtin_ia32_xsaveopt (void *, long long) 22747void __builtin_ia32_xsaveopt64 (void *, long long) 22748@end smallexample 22749 22750The following built-in functions are available when @option{-mtbm} is used. 22751Both of them generate the immediate form of the bextr machine instruction. 22752@smallexample 22753unsigned int __builtin_ia32_bextri_u32 (unsigned int, 22754 const unsigned int); 22755unsigned long long __builtin_ia32_bextri_u64 (unsigned long long, 22756 const unsigned long long); 22757@end smallexample 22758 22759 22760The following built-in functions are available when @option{-m3dnow} is used. 22761All of them generate the machine instruction that is part of the name. 22762 22763@smallexample 22764void __builtin_ia32_femms (void) 22765v8qi __builtin_ia32_pavgusb (v8qi, v8qi) 22766v2si __builtin_ia32_pf2id (v2sf) 22767v2sf __builtin_ia32_pfacc (v2sf, v2sf) 22768v2sf __builtin_ia32_pfadd (v2sf, v2sf) 22769v2si __builtin_ia32_pfcmpeq (v2sf, v2sf) 22770v2si __builtin_ia32_pfcmpge (v2sf, v2sf) 22771v2si __builtin_ia32_pfcmpgt (v2sf, v2sf) 22772v2sf __builtin_ia32_pfmax (v2sf, v2sf) 22773v2sf __builtin_ia32_pfmin (v2sf, v2sf) 22774v2sf __builtin_ia32_pfmul (v2sf, v2sf) 22775v2sf __builtin_ia32_pfrcp (v2sf) 22776v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf) 22777v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf) 22778v2sf __builtin_ia32_pfrsqrt (v2sf) 22779v2sf __builtin_ia32_pfsub (v2sf, v2sf) 22780v2sf __builtin_ia32_pfsubr (v2sf, v2sf) 22781v2sf __builtin_ia32_pi2fd (v2si) 22782v4hi __builtin_ia32_pmulhrw (v4hi, v4hi) 22783@end smallexample 22784 22785The following built-in functions are available when @option{-m3dnowa} is used. 22786All of them generate the machine instruction that is part of the name. 22787 22788@smallexample 22789v2si __builtin_ia32_pf2iw (v2sf) 22790v2sf __builtin_ia32_pfnacc (v2sf, v2sf) 22791v2sf __builtin_ia32_pfpnacc (v2sf, v2sf) 22792v2sf __builtin_ia32_pi2fw (v2si) 22793v2sf __builtin_ia32_pswapdsf (v2sf) 22794v2si __builtin_ia32_pswapdsi (v2si) 22795@end smallexample 22796 22797The following built-in functions are available when @option{-mrtm} is used 22798They are used for restricted transactional memory. These are the internal 22799low level functions. Normally the functions in 22800@ref{x86 transactional memory intrinsics} should be used instead. 22801 22802@smallexample 22803int __builtin_ia32_xbegin () 22804void __builtin_ia32_xend () 22805void __builtin_ia32_xabort (status) 22806int __builtin_ia32_xtest () 22807@end smallexample 22808 22809The following built-in functions are available when @option{-mmwaitx} is used. 22810All of them generate the machine instruction that is part of the name. 22811@smallexample 22812void __builtin_ia32_monitorx (void *, unsigned int, unsigned int) 22813void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int) 22814@end smallexample 22815 22816The following built-in functions are available when @option{-mclzero} is used. 22817All of them generate the machine instruction that is part of the name. 22818@smallexample 22819void __builtin_i32_clzero (void *) 22820@end smallexample 22821 22822The following built-in functions are available when @option{-mpku} is used. 22823They generate reads and writes to PKRU. 22824@smallexample 22825void __builtin_ia32_wrpkru (unsigned int) 22826unsigned int __builtin_ia32_rdpkru () 22827@end smallexample 22828 22829The following built-in functions are available when @option{-mcet} or 22830@option{-mshstk} option is used. They support shadow stack 22831machine instructions from Intel Control-flow Enforcement Technology (CET). 22832Each built-in function generates the machine instruction that is part 22833of the function's name. These are the internal low-level functions. 22834Normally the functions in @ref{x86 control-flow protection intrinsics} 22835should be used instead. 22836 22837@smallexample 22838unsigned int __builtin_ia32_rdsspd (void) 22839unsigned long long __builtin_ia32_rdsspq (void) 22840void __builtin_ia32_incsspd (unsigned int) 22841void __builtin_ia32_incsspq (unsigned long long) 22842void __builtin_ia32_saveprevssp(void); 22843void __builtin_ia32_rstorssp(void *); 22844void __builtin_ia32_wrssd(unsigned int, void *); 22845void __builtin_ia32_wrssq(unsigned long long, void *); 22846void __builtin_ia32_wrussd(unsigned int, void *); 22847void __builtin_ia32_wrussq(unsigned long long, void *); 22848void __builtin_ia32_setssbsy(void); 22849void __builtin_ia32_clrssbsy(void *); 22850@end smallexample 22851 22852@node x86 transactional memory intrinsics 22853@subsection x86 Transactional Memory Intrinsics 22854 22855These hardware transactional memory intrinsics for x86 allow you to use 22856memory transactions with RTM (Restricted Transactional Memory). 22857This support is enabled with the @option{-mrtm} option. 22858For using HLE (Hardware Lock Elision) see 22859@ref{x86 specific memory model extensions for transactional memory} instead. 22860 22861A memory transaction commits all changes to memory in an atomic way, 22862as visible to other threads. If the transaction fails it is rolled back 22863and all side effects discarded. 22864 22865Generally there is no guarantee that a memory transaction ever succeeds 22866and suitable fallback code always needs to be supplied. 22867 22868@deftypefn {RTM Function} {unsigned} _xbegin () 22869Start a RTM (Restricted Transactional Memory) transaction. 22870Returns @code{_XBEGIN_STARTED} when the transaction 22871started successfully (note this is not 0, so the constant has to be 22872explicitly tested). 22873 22874If the transaction aborts, all side effects 22875are undone and an abort code encoded as a bit mask is returned. 22876The following macros are defined: 22877 22878@table @code 22879@item _XABORT_EXPLICIT 22880Transaction was explicitly aborted with @code{_xabort}. The parameter passed 22881to @code{_xabort} is available with @code{_XABORT_CODE(status)}. 22882@item _XABORT_RETRY 22883Transaction retry is possible. 22884@item _XABORT_CONFLICT 22885Transaction abort due to a memory conflict with another thread. 22886@item _XABORT_CAPACITY 22887Transaction abort due to the transaction using too much memory. 22888@item _XABORT_DEBUG 22889Transaction abort due to a debug trap. 22890@item _XABORT_NESTED 22891Transaction abort in an inner nested transaction. 22892@end table 22893 22894There is no guarantee 22895any transaction ever succeeds, so there always needs to be a valid 22896fallback path. 22897@end deftypefn 22898 22899@deftypefn {RTM Function} {void} _xend () 22900Commit the current transaction. When no transaction is active this faults. 22901All memory side effects of the transaction become visible 22902to other threads in an atomic manner. 22903@end deftypefn 22904 22905@deftypefn {RTM Function} {int} _xtest () 22906Return a nonzero value if a transaction is currently active, otherwise 0. 22907@end deftypefn 22908 22909@deftypefn {RTM Function} {void} _xabort (status) 22910Abort the current transaction. When no transaction is active this is a no-op. 22911The @var{status} is an 8-bit constant; its value is encoded in the return 22912value from @code{_xbegin}. 22913@end deftypefn 22914 22915Here is an example showing handling for @code{_XABORT_RETRY} 22916and a fallback path for other failures: 22917 22918@smallexample 22919#include <immintrin.h> 22920 22921int n_tries, max_tries; 22922unsigned status = _XABORT_EXPLICIT; 22923... 22924 22925for (n_tries = 0; n_tries < max_tries; n_tries++) 22926 @{ 22927 status = _xbegin (); 22928 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY)) 22929 break; 22930 @} 22931if (status == _XBEGIN_STARTED) 22932 @{ 22933 ... transaction code... 22934 _xend (); 22935 @} 22936else 22937 @{ 22938 ... non-transactional fallback path... 22939 @} 22940@end smallexample 22941 22942@noindent 22943Note that, in most cases, the transactional and non-transactional code 22944must synchronize together to ensure consistency. 22945 22946@node x86 control-flow protection intrinsics 22947@subsection x86 Control-Flow Protection Intrinsics 22948 22949@deftypefn {CET Function} {ret_type} _get_ssp (void) 22950Get the current value of shadow stack pointer if shadow stack support 22951from Intel CET is enabled in the hardware or @code{0} otherwise. 22952The @code{ret_type} is @code{unsigned long long} for 64-bit targets 22953and @code{unsigned int} for 32-bit targets. 22954@end deftypefn 22955 22956@deftypefn {CET Function} void _inc_ssp (unsigned int) 22957Increment the current shadow stack pointer by the size specified by the 22958function argument. The argument is masked to a byte value for security 22959reasons, so to increment by more than 255 bytes you must call the function 22960multiple times. 22961@end deftypefn 22962 22963The shadow stack unwind code looks like: 22964 22965@smallexample 22966#include <immintrin.h> 22967 22968/* Unwind the shadow stack for EH. */ 22969#define _Unwind_Frames_Extra(x) \ 22970 do \ 22971 @{ \ 22972 _Unwind_Word ssp = _get_ssp (); \ 22973 if (ssp != 0) \ 22974 @{ \ 22975 _Unwind_Word tmp = (x); \ 22976 while (tmp > 255) \ 22977 @{ \ 22978 _inc_ssp (tmp); \ 22979 tmp -= 255; \ 22980 @} \ 22981 _inc_ssp (tmp); \ 22982 @} \ 22983 @} \ 22984 while (0) 22985@end smallexample 22986 22987@noindent 22988This code runs unconditionally on all 64-bit processors. For 32-bit 22989processors the code runs on those that support multi-byte NOP instructions. 22990 22991@node Target Format Checks 22992@section Format Checks Specific to Particular Target Machines 22993 22994For some target machines, GCC supports additional options to the 22995format attribute 22996(@pxref{Function Attributes,,Declaring Attributes of Functions}). 22997 22998@menu 22999* Solaris Format Checks:: 23000* Darwin Format Checks:: 23001@end menu 23002 23003@node Solaris Format Checks 23004@subsection Solaris Format Checks 23005 23006Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format 23007check. @code{cmn_err} accepts a subset of the standard @code{printf} 23008conversions, and the two-argument @code{%b} conversion for displaying 23009bit-fields. See the Solaris man page for @code{cmn_err} for more information. 23010 23011@node Darwin Format Checks 23012@subsection Darwin Format Checks 23013 23014In addition to the full set of format archetypes (attribute format style 23015arguments such as @code{printf}, @code{scanf}, @code{strftime}, and 23016@code{strfmon}), Darwin targets also support the @code{CFString} (or 23017@code{__CFString__}) archetype in the @code{format} attribute. 23018Declarations with this archetype are parsed for correct syntax 23019and argument types. However, parsing of the format string itself and 23020validating arguments against it in calls to such functions is currently 23021not performed. 23022 23023Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may 23024also be used as format arguments. Note that the relevant headers are only likely to be 23025available on Darwin (OSX) installations. On such installations, the XCode and system 23026documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and 23027associated functions. 23028 23029@node Pragmas 23030@section Pragmas Accepted by GCC 23031@cindex pragmas 23032@cindex @code{#pragma} 23033 23034GCC supports several types of pragmas, primarily in order to compile 23035code originally written for other compilers. Note that in general 23036we do not recommend the use of pragmas; @xref{Function Attributes}, 23037for further explanation. 23038 23039The GNU C preprocessor recognizes several pragmas in addition to the 23040compiler pragmas documented here. Refer to the CPP manual for more 23041information. 23042 23043@menu 23044* AArch64 Pragmas:: 23045* ARM Pragmas:: 23046* M32C Pragmas:: 23047* MeP Pragmas:: 23048* RS/6000 and PowerPC Pragmas:: 23049* S/390 Pragmas:: 23050* Darwin Pragmas:: 23051* Solaris Pragmas:: 23052* Symbol-Renaming Pragmas:: 23053* Structure-Layout Pragmas:: 23054* Weak Pragmas:: 23055* Diagnostic Pragmas:: 23056* Visibility Pragmas:: 23057* Push/Pop Macro Pragmas:: 23058* Function Specific Option Pragmas:: 23059* Loop-Specific Pragmas:: 23060@end menu 23061 23062@node AArch64 Pragmas 23063@subsection AArch64 Pragmas 23064 23065The pragmas defined by the AArch64 target correspond to the AArch64 23066target function attributes. They can be specified as below: 23067@smallexample 23068#pragma GCC target("string") 23069@end smallexample 23070 23071where @code{@var{string}} can be any string accepted as an AArch64 target 23072attribute. @xref{AArch64 Function Attributes}, for more details 23073on the permissible values of @code{string}. 23074 23075@node ARM Pragmas 23076@subsection ARM Pragmas 23077 23078The ARM target defines pragmas for controlling the default addition of 23079@code{long_call} and @code{short_call} attributes to functions. 23080@xref{Function Attributes}, for information about the effects of these 23081attributes. 23082 23083@table @code 23084@item long_calls 23085@cindex pragma, long_calls 23086Set all subsequent functions to have the @code{long_call} attribute. 23087 23088@item no_long_calls 23089@cindex pragma, no_long_calls 23090Set all subsequent functions to have the @code{short_call} attribute. 23091 23092@item long_calls_off 23093@cindex pragma, long_calls_off 23094Do not affect the @code{long_call} or @code{short_call} attributes of 23095subsequent functions. 23096@end table 23097 23098@node M32C Pragmas 23099@subsection M32C Pragmas 23100 23101@table @code 23102@item GCC memregs @var{number} 23103@cindex pragma, memregs 23104Overrides the command-line option @code{-memregs=} for the current 23105file. Use with care! This pragma must be before any function in the 23106file, and mixing different memregs values in different objects may 23107make them incompatible. This pragma is useful when a 23108performance-critical function uses a memreg for temporary values, 23109as it may allow you to reduce the number of memregs used. 23110 23111@item ADDRESS @var{name} @var{address} 23112@cindex pragma, address 23113For any declared symbols matching @var{name}, this does three things 23114to that symbol: it forces the symbol to be located at the given 23115address (a number), it forces the symbol to be volatile, and it 23116changes the symbol's scope to be static. This pragma exists for 23117compatibility with other compilers, but note that the common 23118@code{1234H} numeric syntax is not supported (use @code{0x1234} 23119instead). Example: 23120 23121@smallexample 23122#pragma ADDRESS port3 0x103 23123char port3; 23124@end smallexample 23125 23126@end table 23127 23128@node MeP Pragmas 23129@subsection MeP Pragmas 23130 23131@table @code 23132 23133@item custom io_volatile (on|off) 23134@cindex pragma, custom io_volatile 23135Overrides the command-line option @code{-mio-volatile} for the current 23136file. Note that for compatibility with future GCC releases, this 23137option should only be used once before any @code{io} variables in each 23138file. 23139 23140@item GCC coprocessor available @var{registers} 23141@cindex pragma, coprocessor available 23142Specifies which coprocessor registers are available to the register 23143allocator. @var{registers} may be a single register, register range 23144separated by ellipses, or comma-separated list of those. Example: 23145 23146@smallexample 23147#pragma GCC coprocessor available $c0...$c10, $c28 23148@end smallexample 23149 23150@item GCC coprocessor call_saved @var{registers} 23151@cindex pragma, coprocessor call_saved 23152Specifies which coprocessor registers are to be saved and restored by 23153any function using them. @var{registers} may be a single register, 23154register range separated by ellipses, or comma-separated list of 23155those. Example: 23156 23157@smallexample 23158#pragma GCC coprocessor call_saved $c4...$c6, $c31 23159@end smallexample 23160 23161@item GCC coprocessor subclass '(A|B|C|D)' = @var{registers} 23162@cindex pragma, coprocessor subclass 23163Creates and defines a register class. These register classes can be 23164used by inline @code{asm} constructs. @var{registers} may be a single 23165register, register range separated by ellipses, or comma-separated 23166list of those. Example: 23167 23168@smallexample 23169#pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6 23170 23171asm ("cpfoo %0" : "=B" (x)); 23172@end smallexample 23173 23174@item GCC disinterrupt @var{name} , @var{name} @dots{} 23175@cindex pragma, disinterrupt 23176For the named functions, the compiler adds code to disable interrupts 23177for the duration of those functions. If any functions so named 23178are not encountered in the source, a warning is emitted that the pragma is 23179not used. Examples: 23180 23181@smallexample 23182#pragma disinterrupt foo 23183#pragma disinterrupt bar, grill 23184int foo () @{ @dots{} @} 23185@end smallexample 23186 23187@item GCC call @var{name} , @var{name} @dots{} 23188@cindex pragma, call 23189For the named functions, the compiler always uses a register-indirect 23190call model when calling the named functions. Examples: 23191 23192@smallexample 23193extern int foo (); 23194#pragma call foo 23195@end smallexample 23196 23197@end table 23198 23199@node RS/6000 and PowerPC Pragmas 23200@subsection RS/6000 and PowerPC Pragmas 23201 23202The RS/6000 and PowerPC targets define one pragma for controlling 23203whether or not the @code{longcall} attribute is added to function 23204declarations by default. This pragma overrides the @option{-mlongcall} 23205option, but not the @code{longcall} and @code{shortcall} attributes. 23206@xref{RS/6000 and PowerPC Options}, for more information about when long 23207calls are and are not necessary. 23208 23209@table @code 23210@item longcall (1) 23211@cindex pragma, longcall 23212Apply the @code{longcall} attribute to all subsequent function 23213declarations. 23214 23215@item longcall (0) 23216Do not apply the @code{longcall} attribute to subsequent function 23217declarations. 23218@end table 23219 23220@c Describe h8300 pragmas here. 23221@c Describe sh pragmas here. 23222@c Describe v850 pragmas here. 23223 23224@node S/390 Pragmas 23225@subsection S/390 Pragmas 23226 23227The pragmas defined by the S/390 target correspond to the S/390 23228target function attributes and some the additional options: 23229 23230@table @samp 23231@item zvector 23232@itemx no-zvector 23233@end table 23234 23235Note that options of the pragma, unlike options of the target 23236attribute, do change the value of preprocessor macros like 23237@code{__VEC__}. They can be specified as below: 23238 23239@smallexample 23240#pragma GCC target("string[,string]...") 23241#pragma GCC target("string"[,"string"]...) 23242@end smallexample 23243 23244@node Darwin Pragmas 23245@subsection Darwin Pragmas 23246 23247The following pragmas are available for all architectures running the 23248Darwin operating system. These are useful for compatibility with other 23249Mac OS compilers. 23250 23251@table @code 23252@item mark @var{tokens}@dots{} 23253@cindex pragma, mark 23254This pragma is accepted, but has no effect. 23255 23256@item options align=@var{alignment} 23257@cindex pragma, options align 23258This pragma sets the alignment of fields in structures. The values of 23259@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or 23260@code{power}, to emulate PowerPC alignment. Uses of this pragma nest 23261properly; to restore the previous setting, use @code{reset} for the 23262@var{alignment}. 23263 23264@item segment @var{tokens}@dots{} 23265@cindex pragma, segment 23266This pragma is accepted, but has no effect. 23267 23268@item unused (@var{var} [, @var{var}]@dots{}) 23269@cindex pragma, unused 23270This pragma declares variables to be possibly unused. GCC does not 23271produce warnings for the listed variables. The effect is similar to 23272that of the @code{unused} attribute, except that this pragma may appear 23273anywhere within the variables' scopes. 23274@end table 23275 23276@node Solaris Pragmas 23277@subsection Solaris Pragmas 23278 23279The Solaris target supports @code{#pragma redefine_extname} 23280(@pxref{Symbol-Renaming Pragmas}). It also supports additional 23281@code{#pragma} directives for compatibility with the system compiler. 23282 23283@table @code 23284@item align @var{alignment} (@var{variable} [, @var{variable}]...) 23285@cindex pragma, align 23286 23287Increase the minimum alignment of each @var{variable} to @var{alignment}. 23288This is the same as GCC's @code{aligned} attribute @pxref{Variable 23289Attributes}). Macro expansion occurs on the arguments to this pragma 23290when compiling C and Objective-C@. It does not currently occur when 23291compiling C++, but this is a bug which may be fixed in a future 23292release. 23293 23294@item fini (@var{function} [, @var{function}]...) 23295@cindex pragma, fini 23296 23297This pragma causes each listed @var{function} to be called after 23298main, or during shared module unloading, by adding a call to the 23299@code{.fini} section. 23300 23301@item init (@var{function} [, @var{function}]...) 23302@cindex pragma, init 23303 23304This pragma causes each listed @var{function} to be called during 23305initialization (before @code{main}) or during shared module loading, by 23306adding a call to the @code{.init} section. 23307 23308@end table 23309 23310@node Symbol-Renaming Pragmas 23311@subsection Symbol-Renaming Pragmas 23312 23313GCC supports a @code{#pragma} directive that changes the name used in 23314assembly for a given declaration. While this pragma is supported on all 23315platforms, it is intended primarily to provide compatibility with the 23316Solaris system headers. This effect can also be achieved using the asm 23317labels extension (@pxref{Asm Labels}). 23318 23319@table @code 23320@item redefine_extname @var{oldname} @var{newname} 23321@cindex pragma, redefine_extname 23322 23323This pragma gives the C function @var{oldname} the assembly symbol 23324@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} 23325is defined if this pragma is available (currently on all platforms). 23326@end table 23327 23328This pragma and the @code{asm} labels extension interact in a complicated 23329manner. Here are some corner cases you may want to be aware of: 23330 23331@enumerate 23332@item This pragma silently applies only to declarations with external 23333linkage. The @code{asm} label feature does not have this restriction. 23334 23335@item In C++, this pragma silently applies only to declarations with 23336``C'' linkage. Again, @code{asm} labels do not have this restriction. 23337 23338@item If either of the ways of changing the assembly name of a 23339declaration are applied to a declaration whose assembly name has 23340already been determined (either by a previous use of one of these 23341features, or because the compiler needed the assembly name in order to 23342generate code), and the new name is different, a warning issues and 23343the name does not change. 23344 23345@item The @var{oldname} used by @code{#pragma redefine_extname} is 23346always the C-language name. 23347@end enumerate 23348 23349@node Structure-Layout Pragmas 23350@subsection Structure-Layout Pragmas 23351 23352For compatibility with Microsoft Windows compilers, GCC supports a 23353set of @code{#pragma} directives that change the maximum alignment of 23354members of structures (other than zero-width bit-fields), unions, and 23355classes subsequently defined. The @var{n} value below always is required 23356to be a small power of two and specifies the new alignment in bytes. 23357 23358@enumerate 23359@item @code{#pragma pack(@var{n})} simply sets the new alignment. 23360@item @code{#pragma pack()} sets the alignment to the one that was in 23361effect when compilation started (see also command-line option 23362@option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}). 23363@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment 23364setting on an internal stack and then optionally sets the new alignment. 23365@item @code{#pragma pack(pop)} restores the alignment setting to the one 23366saved at the top of the internal stack (and removes that stack entry). 23367Note that @code{#pragma pack([@var{n}])} does not influence this internal 23368stack; thus it is possible to have @code{#pragma pack(push)} followed by 23369multiple @code{#pragma pack(@var{n})} instances and finalized by a single 23370@code{#pragma pack(pop)}. 23371@end enumerate 23372 23373Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct} 23374directive which lays out structures and unions subsequently defined as the 23375documented @code{__attribute__ ((ms_struct))}. 23376 23377@enumerate 23378@item @code{#pragma ms_struct on} turns on the Microsoft layout. 23379@item @code{#pragma ms_struct off} turns off the Microsoft layout. 23380@item @code{#pragma ms_struct reset} goes back to the default layout. 23381@end enumerate 23382 23383Most targets also support the @code{#pragma scalar_storage_order} directive 23384which lays out structures and unions subsequently defined as the documented 23385@code{__attribute__ ((scalar_storage_order))}. 23386 23387@enumerate 23388@item @code{#pragma scalar_storage_order big-endian} sets the storage order 23389of the scalar fields to big-endian. 23390@item @code{#pragma scalar_storage_order little-endian} sets the storage order 23391of the scalar fields to little-endian. 23392@item @code{#pragma scalar_storage_order default} goes back to the endianness 23393that was in effect when compilation started (see also command-line option 23394@option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}). 23395@end enumerate 23396 23397@node Weak Pragmas 23398@subsection Weak Pragmas 23399 23400For compatibility with SVR4, GCC supports a set of @code{#pragma} 23401directives for declaring symbols to be weak, and defining weak 23402aliases. 23403 23404@table @code 23405@item #pragma weak @var{symbol} 23406@cindex pragma, weak 23407This pragma declares @var{symbol} to be weak, as if the declaration 23408had the attribute of the same name. The pragma may appear before 23409or after the declaration of @var{symbol}. It is not an error for 23410@var{symbol} to never be defined at all. 23411 23412@item #pragma weak @var{symbol1} = @var{symbol2} 23413This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. 23414It is an error if @var{symbol2} is not defined in the current 23415translation unit. 23416@end table 23417 23418@node Diagnostic Pragmas 23419@subsection Diagnostic Pragmas 23420 23421GCC allows the user to selectively enable or disable certain types of 23422diagnostics, and change the kind of the diagnostic. For example, a 23423project's policy might require that all sources compile with 23424@option{-Werror} but certain files might have exceptions allowing 23425specific types of warnings. Or, a project might selectively enable 23426diagnostics and treat them as errors depending on which preprocessor 23427macros are defined. 23428 23429@table @code 23430@item #pragma GCC diagnostic @var{kind} @var{option} 23431@cindex pragma, diagnostic 23432 23433Modifies the disposition of a diagnostic. Note that not all 23434diagnostics are modifiable; at the moment only warnings (normally 23435controlled by @samp{-W@dots{}}) can be controlled, and not all of them. 23436Use @option{-fdiagnostics-show-option} to determine which diagnostics 23437are controllable and which option controls them. 23438 23439@var{kind} is @samp{error} to treat this diagnostic as an error, 23440@samp{warning} to treat it like a warning (even if @option{-Werror} is 23441in effect), or @samp{ignored} if the diagnostic is to be ignored. 23442@var{option} is a double quoted string that matches the command-line 23443option. 23444 23445@smallexample 23446#pragma GCC diagnostic warning "-Wformat" 23447#pragma GCC diagnostic error "-Wformat" 23448#pragma GCC diagnostic ignored "-Wformat" 23449@end smallexample 23450 23451Note that these pragmas override any command-line options. GCC keeps 23452track of the location of each pragma, and issues diagnostics according 23453to the state as of that point in the source file. Thus, pragmas occurring 23454after a line do not affect diagnostics caused by that line. 23455 23456@item #pragma GCC diagnostic push 23457@itemx #pragma GCC diagnostic pop 23458 23459Causes GCC to remember the state of the diagnostics as of each 23460@code{push}, and restore to that point at each @code{pop}. If a 23461@code{pop} has no matching @code{push}, the command-line options are 23462restored. 23463 23464@smallexample 23465#pragma GCC diagnostic error "-Wuninitialized" 23466 foo(a); /* error is given for this one */ 23467#pragma GCC diagnostic push 23468#pragma GCC diagnostic ignored "-Wuninitialized" 23469 foo(b); /* no diagnostic for this one */ 23470#pragma GCC diagnostic pop 23471 foo(c); /* error is given for this one */ 23472#pragma GCC diagnostic pop 23473 foo(d); /* depends on command-line options */ 23474@end smallexample 23475 23476@end table 23477 23478GCC also offers a simple mechanism for printing messages during 23479compilation. 23480 23481@table @code 23482@item #pragma message @var{string} 23483@cindex pragma, diagnostic 23484 23485Prints @var{string} as a compiler message on compilation. The message 23486is informational only, and is neither a compilation warning nor an 23487error. Newlines can be included in the string by using the @samp{\n} 23488escape sequence. 23489 23490@smallexample 23491#pragma message "Compiling " __FILE__ "..." 23492@end smallexample 23493 23494@var{string} may be parenthesized, and is printed with location 23495information. For example, 23496 23497@smallexample 23498#define DO_PRAGMA(x) _Pragma (#x) 23499#define TODO(x) DO_PRAGMA(message ("TODO - " #x)) 23500 23501TODO(Remember to fix this) 23502@end smallexample 23503 23504@noindent 23505prints @samp{/tmp/file.c:4: note: #pragma message: 23506TODO - Remember to fix this}. 23507 23508@item #pragma GCC error @var{message} 23509@cindex pragma, diagnostic 23510Generates an error message. This pragma @emph{is} considered to 23511indicate an error in the compilation, and it will be treated as such. 23512 23513Newlines can be included in the string by using the @samp{\n} 23514escape sequence. They will be displayed as newlines even if the 23515@option{-fmessage-length} option is set to zero. 23516 23517The error is only generated if the pragma is present in the code after 23518pre-processing has been completed. It does not matter however if the 23519code containing the pragma is unreachable: 23520 23521@smallexample 23522#if 0 23523#pragma GCC error "this error is not seen" 23524#endif 23525void foo (void) 23526@{ 23527 return; 23528#pragma GCC error "this error is seen" 23529@} 23530@end smallexample 23531 23532@item #pragma GCC warning @var{message} 23533@cindex pragma, diagnostic 23534This is just like @samp{pragma GCC error} except that a warning 23535message is issued instead of an error message. Unless 23536@option{-Werror} is in effect, in which case this pragma will generate 23537an error as well. 23538 23539@end table 23540 23541@node Visibility Pragmas 23542@subsection Visibility Pragmas 23543 23544@table @code 23545@item #pragma GCC visibility push(@var{visibility}) 23546@itemx #pragma GCC visibility pop 23547@cindex pragma, visibility 23548 23549This pragma allows the user to set the visibility for multiple 23550declarations without having to give each a visibility attribute 23551(@pxref{Function Attributes}). 23552 23553In C++, @samp{#pragma GCC visibility} affects only namespace-scope 23554declarations. Class members and template specializations are not 23555affected; if you want to override the visibility for a particular 23556member or instantiation, you must use an attribute. 23557 23558@end table 23559 23560 23561@node Push/Pop Macro Pragmas 23562@subsection Push/Pop Macro Pragmas 23563 23564For compatibility with Microsoft Windows compilers, GCC supports 23565@samp{#pragma push_macro(@var{"macro_name"})} 23566and @samp{#pragma pop_macro(@var{"macro_name"})}. 23567 23568@table @code 23569@item #pragma push_macro(@var{"macro_name"}) 23570@cindex pragma, push_macro 23571This pragma saves the value of the macro named as @var{macro_name} to 23572the top of the stack for this macro. 23573 23574@item #pragma pop_macro(@var{"macro_name"}) 23575@cindex pragma, pop_macro 23576This pragma sets the value of the macro named as @var{macro_name} to 23577the value on top of the stack for this macro. If the stack for 23578@var{macro_name} is empty, the value of the macro remains unchanged. 23579@end table 23580 23581For example: 23582 23583@smallexample 23584#define X 1 23585#pragma push_macro("X") 23586#undef X 23587#define X -1 23588#pragma pop_macro("X") 23589int x [X]; 23590@end smallexample 23591 23592@noindent 23593In this example, the definition of X as 1 is saved by @code{#pragma 23594push_macro} and restored by @code{#pragma pop_macro}. 23595 23596@node Function Specific Option Pragmas 23597@subsection Function Specific Option Pragmas 23598 23599@table @code 23600@item #pragma GCC target (@var{string}, @dots{}) 23601@cindex pragma GCC target 23602 23603This pragma allows you to set target-specific options for functions 23604defined later in the source file. One or more strings can be 23605specified. Each function that is defined after this point is treated 23606as if it had been declared with one @code{target(}@var{string}@code{)} 23607attribute for each @var{string} argument. The parentheses around 23608the strings in the pragma are optional. @xref{Function Attributes}, 23609for more information about the @code{target} attribute and the attribute 23610syntax. 23611 23612The @code{#pragma GCC target} pragma is presently implemented for 23613x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only. 23614 23615@item #pragma GCC optimize (@var{string}, @dots{}) 23616@cindex pragma GCC optimize 23617 23618This pragma allows you to set global optimization options for functions 23619defined later in the source file. One or more strings can be 23620specified. Each function that is defined after this point is treated 23621as if it had been declared with one @code{optimize(}@var{string}@code{)} 23622attribute for each @var{string} argument. The parentheses around 23623the strings in the pragma are optional. @xref{Function Attributes}, 23624for more information about the @code{optimize} attribute and the attribute 23625syntax. 23626 23627@item #pragma GCC push_options 23628@itemx #pragma GCC pop_options 23629@cindex pragma GCC push_options 23630@cindex pragma GCC pop_options 23631 23632These pragmas maintain a stack of the current target and optimization 23633options. It is intended for include files where you temporarily want 23634to switch to using a different @samp{#pragma GCC target} or 23635@samp{#pragma GCC optimize} and then to pop back to the previous 23636options. 23637 23638@item #pragma GCC reset_options 23639@cindex pragma GCC reset_options 23640 23641This pragma clears the current @code{#pragma GCC target} and 23642@code{#pragma GCC optimize} to use the default switches as specified 23643on the command line. 23644 23645@end table 23646 23647@node Loop-Specific Pragmas 23648@subsection Loop-Specific Pragmas 23649 23650@table @code 23651@item #pragma GCC ivdep 23652@cindex pragma GCC ivdep 23653 23654With this pragma, the programmer asserts that there are no loop-carried 23655dependencies which would prevent consecutive iterations of 23656the following loop from executing concurrently with SIMD 23657(single instruction multiple data) instructions. 23658 23659For example, the compiler can only unconditionally vectorize the following 23660loop with the pragma: 23661 23662@smallexample 23663void foo (int n, int *a, int *b, int *c) 23664@{ 23665 int i, j; 23666#pragma GCC ivdep 23667 for (i = 0; i < n; ++i) 23668 a[i] = b[i] + c[i]; 23669@} 23670@end smallexample 23671 23672@noindent 23673In this example, using the @code{restrict} qualifier had the same 23674effect. In the following example, that would not be possible. Assume 23675@math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows 23676that it can unconditionally vectorize the following loop: 23677 23678@smallexample 23679void ignore_vec_dep (int *a, int k, int c, int m) 23680@{ 23681#pragma GCC ivdep 23682 for (int i = 0; i < m; i++) 23683 a[i] = a[i + k] * c; 23684@} 23685@end smallexample 23686 23687@item #pragma GCC unroll @var{n} 23688@cindex pragma GCC unroll @var{n} 23689 23690You can use this pragma to control how many times a loop should be unrolled. 23691It must be placed immediately before a @code{for}, @code{while} or @code{do} 23692loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows. 23693@var{n} is an integer constant expression specifying the unrolling factor. 23694The values of @math{0} and @math{1} block any unrolling of the loop. 23695 23696@end table 23697 23698@node Unnamed Fields 23699@section Unnamed Structure and Union Fields 23700@cindex @code{struct} 23701@cindex @code{union} 23702 23703As permitted by ISO C11 and for compatibility with other compilers, 23704GCC allows you to define 23705a structure or union that contains, as fields, structures and unions 23706without names. For example: 23707 23708@smallexample 23709struct @{ 23710 int a; 23711 union @{ 23712 int b; 23713 float c; 23714 @}; 23715 int d; 23716@} foo; 23717@end smallexample 23718 23719@noindent 23720In this example, you are able to access members of the unnamed 23721union with code like @samp{foo.b}. Note that only unnamed structs and 23722unions are allowed, you may not have, for example, an unnamed 23723@code{int}. 23724 23725You must never create such structures that cause ambiguous field definitions. 23726For example, in this structure: 23727 23728@smallexample 23729struct @{ 23730 int a; 23731 struct @{ 23732 int a; 23733 @}; 23734@} foo; 23735@end smallexample 23736 23737@noindent 23738it is ambiguous which @code{a} is being referred to with @samp{foo.a}. 23739The compiler gives errors for such constructs. 23740 23741@opindex fms-extensions 23742Unless @option{-fms-extensions} is used, the unnamed field must be a 23743structure or union definition without a tag (for example, @samp{struct 23744@{ int a; @};}). If @option{-fms-extensions} is used, the field may 23745also be a definition with a tag such as @samp{struct foo @{ int a; 23746@};}, a reference to a previously defined structure or union such as 23747@samp{struct foo;}, or a reference to a @code{typedef} name for a 23748previously defined structure or union type. 23749 23750@opindex fplan9-extensions 23751The option @option{-fplan9-extensions} enables 23752@option{-fms-extensions} as well as two other extensions. First, a 23753pointer to a structure is automatically converted to a pointer to an 23754anonymous field for assignments and function calls. For example: 23755 23756@smallexample 23757struct s1 @{ int a; @}; 23758struct s2 @{ struct s1; @}; 23759extern void f1 (struct s1 *); 23760void f2 (struct s2 *p) @{ f1 (p); @} 23761@end smallexample 23762 23763@noindent 23764In the call to @code{f1} inside @code{f2}, the pointer @code{p} is 23765converted into a pointer to the anonymous field. 23766 23767Second, when the type of an anonymous field is a @code{typedef} for a 23768@code{struct} or @code{union}, code may refer to the field using the 23769name of the @code{typedef}. 23770 23771@smallexample 23772typedef struct @{ int a; @} s1; 23773struct s2 @{ s1; @}; 23774s1 f1 (struct s2 *p) @{ return p->s1; @} 23775@end smallexample 23776 23777These usages are only permitted when they are not ambiguous. 23778 23779@node Thread-Local 23780@section Thread-Local Storage 23781@cindex Thread-Local Storage 23782@cindex @acronym{TLS} 23783@cindex @code{__thread} 23784 23785Thread-local storage (@acronym{TLS}) is a mechanism by which variables 23786are allocated such that there is one instance of the variable per extant 23787thread. The runtime model GCC uses to implement this originates 23788in the IA-64 processor-specific ABI, but has since been migrated 23789to other processors as well. It requires significant support from 23790the linker (@command{ld}), dynamic linker (@command{ld.so}), and 23791system libraries (@file{libc.so} and @file{libpthread.so}), so it 23792is not available everywhere. 23793 23794At the user level, the extension is visible with a new storage 23795class keyword: @code{__thread}. For example: 23796 23797@smallexample 23798__thread int i; 23799extern __thread struct state s; 23800static __thread char *p; 23801@end smallexample 23802 23803The @code{__thread} specifier may be used alone, with the @code{extern} 23804or @code{static} specifiers, but with no other storage class specifier. 23805When used with @code{extern} or @code{static}, @code{__thread} must appear 23806immediately after the other storage class specifier. 23807 23808The @code{__thread} specifier may be applied to any global, file-scoped 23809static, function-scoped static, or static data member of a class. It may 23810not be applied to block-scoped automatic or non-static data member. 23811 23812When the address-of operator is applied to a thread-local variable, it is 23813evaluated at run time and returns the address of the current thread's 23814instance of that variable. An address so obtained may be used by any 23815thread. When a thread terminates, any pointers to thread-local variables 23816in that thread become invalid. 23817 23818No static initialization may refer to the address of a thread-local variable. 23819 23820In C++, if an initializer is present for a thread-local variable, it must 23821be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ 23822standard. 23823 23824See @uref{https://www.akkadia.org/drepper/tls.pdf, 23825ELF Handling For Thread-Local Storage} for a detailed explanation of 23826the four thread-local storage addressing models, and how the runtime 23827is expected to function. 23828 23829@menu 23830* C99 Thread-Local Edits:: 23831* C++98 Thread-Local Edits:: 23832@end menu 23833 23834@node C99 Thread-Local Edits 23835@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage 23836 23837The following are a set of changes to ISO/IEC 9899:1999 (aka C99) 23838that document the exact semantics of the language extension. 23839 23840@itemize @bullet 23841@item 23842@cite{5.1.2 Execution environments} 23843 23844Add new text after paragraph 1 23845 23846@quotation 23847Within either execution environment, a @dfn{thread} is a flow of 23848control within a program. It is implementation defined whether 23849or not there may be more than one thread associated with a program. 23850It is implementation defined how threads beyond the first are 23851created, the name and type of the function called at thread 23852startup, and how threads may be terminated. However, objects 23853with thread storage duration shall be initialized before thread 23854startup. 23855@end quotation 23856 23857@item 23858@cite{6.2.4 Storage durations of objects} 23859 23860Add new text before paragraph 3 23861 23862@quotation 23863An object whose identifier is declared with the storage-class 23864specifier @w{@code{__thread}} has @dfn{thread storage duration}. 23865Its lifetime is the entire execution of the thread, and its 23866stored value is initialized only once, prior to thread startup. 23867@end quotation 23868 23869@item 23870@cite{6.4.1 Keywords} 23871 23872Add @code{__thread}. 23873 23874@item 23875@cite{6.7.1 Storage-class specifiers} 23876 23877Add @code{__thread} to the list of storage class specifiers in 23878paragraph 1. 23879 23880Change paragraph 2 to 23881 23882@quotation 23883With the exception of @code{__thread}, at most one storage-class 23884specifier may be given [@dots{}]. The @code{__thread} specifier may 23885be used alone, or immediately following @code{extern} or 23886@code{static}. 23887@end quotation 23888 23889Add new text after paragraph 6 23890 23891@quotation 23892The declaration of an identifier for a variable that has 23893block scope that specifies @code{__thread} shall also 23894specify either @code{extern} or @code{static}. 23895 23896The @code{__thread} specifier shall be used only with 23897variables. 23898@end quotation 23899@end itemize 23900 23901@node C++98 Thread-Local Edits 23902@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage 23903 23904The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) 23905that document the exact semantics of the language extension. 23906 23907@itemize @bullet 23908@item 23909@b{[intro.execution]} 23910 23911New text after paragraph 4 23912 23913@quotation 23914A @dfn{thread} is a flow of control within the abstract machine. 23915It is implementation defined whether or not there may be more than 23916one thread. 23917@end quotation 23918 23919New text after paragraph 7 23920 23921@quotation 23922It is unspecified whether additional action must be taken to 23923ensure when and whether side effects are visible to other threads. 23924@end quotation 23925 23926@item 23927@b{[lex.key]} 23928 23929Add @code{__thread}. 23930 23931@item 23932@b{[basic.start.main]} 23933 23934Add after paragraph 5 23935 23936@quotation 23937The thread that begins execution at the @code{main} function is called 23938the @dfn{main thread}. It is implementation defined how functions 23939beginning threads other than the main thread are designated or typed. 23940A function so designated, as well as the @code{main} function, is called 23941a @dfn{thread startup function}. It is implementation defined what 23942happens if a thread startup function returns. It is implementation 23943defined what happens to other threads when any thread calls @code{exit}. 23944@end quotation 23945 23946@item 23947@b{[basic.start.init]} 23948 23949Add after paragraph 4 23950 23951@quotation 23952The storage for an object of thread storage duration shall be 23953statically initialized before the first statement of the thread startup 23954function. An object of thread storage duration shall not require 23955dynamic initialization. 23956@end quotation 23957 23958@item 23959@b{[basic.start.term]} 23960 23961Add after paragraph 3 23962 23963@quotation 23964The type of an object with thread storage duration shall not have a 23965non-trivial destructor, nor shall it be an array type whose elements 23966(directly or indirectly) have non-trivial destructors. 23967@end quotation 23968 23969@item 23970@b{[basic.stc]} 23971 23972Add ``thread storage duration'' to the list in paragraph 1. 23973 23974Change paragraph 2 23975 23976@quotation 23977Thread, static, and automatic storage durations are associated with 23978objects introduced by declarations [@dots{}]. 23979@end quotation 23980 23981Add @code{__thread} to the list of specifiers in paragraph 3. 23982 23983@item 23984@b{[basic.stc.thread]} 23985 23986New section before @b{[basic.stc.static]} 23987 23988@quotation 23989The keyword @code{__thread} applied to a non-local object gives the 23990object thread storage duration. 23991 23992A local variable or class data member declared both @code{static} 23993and @code{__thread} gives the variable or member thread storage 23994duration. 23995@end quotation 23996 23997@item 23998@b{[basic.stc.static]} 23999 24000Change paragraph 1 24001 24002@quotation 24003All objects that have neither thread storage duration, dynamic 24004storage duration nor are local [@dots{}]. 24005@end quotation 24006 24007@item 24008@b{[dcl.stc]} 24009 24010Add @code{__thread} to the list in paragraph 1. 24011 24012Change paragraph 1 24013 24014@quotation 24015With the exception of @code{__thread}, at most one 24016@var{storage-class-specifier} shall appear in a given 24017@var{decl-specifier-seq}. The @code{__thread} specifier may 24018be used alone, or immediately following the @code{extern} or 24019@code{static} specifiers. [@dots{}] 24020@end quotation 24021 24022Add after paragraph 5 24023 24024@quotation 24025The @code{__thread} specifier can be applied only to the names of objects 24026and to anonymous unions. 24027@end quotation 24028 24029@item 24030@b{[class.mem]} 24031 24032Add after paragraph 6 24033 24034@quotation 24035Non-@code{static} members shall not be @code{__thread}. 24036@end quotation 24037@end itemize 24038 24039@node Binary constants 24040@section Binary Constants using the @samp{0b} Prefix 24041@cindex Binary constants using the @samp{0b} prefix 24042 24043Integer constants can be written as binary constants, consisting of a 24044sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or 24045@samp{0B}. This is particularly useful in environments that operate a 24046lot on the bit level (like microcontrollers). 24047 24048The following statements are identical: 24049 24050@smallexample 24051i = 42; 24052i = 0x2a; 24053i = 052; 24054i = 0b101010; 24055@end smallexample 24056 24057The type of these constants follows the same rules as for octal or 24058hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} 24059can be applied. 24060 24061@node C++ Extensions 24062@chapter Extensions to the C++ Language 24063@cindex extensions, C++ language 24064@cindex C++ language extensions 24065 24066The GNU compiler provides these extensions to the C++ language (and you 24067can also use most of the C language extensions in your C++ programs). If you 24068want to write code that checks whether these features are available, you can 24069test for the GNU compiler the same way as for C programs: check for a 24070predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to 24071test specifically for GNU C++ (@pxref{Common Predefined Macros,, 24072Predefined Macros,cpp,The GNU C Preprocessor}). 24073 24074@menu 24075* C++ Volatiles:: What constitutes an access to a volatile object. 24076* Restricted Pointers:: C99 restricted pointers and references. 24077* Vague Linkage:: Where G++ puts inlines, vtables and such. 24078* C++ Interface:: You can use a single C++ header file for both 24079 declarations and definitions. 24080* Template Instantiation:: Methods for ensuring that exactly one copy of 24081 each needed template instantiation is emitted. 24082* Bound member functions:: You can extract a function pointer to the 24083 method denoted by a @samp{->*} or @samp{.*} expression. 24084* C++ Attributes:: Variable, function, and type attributes for C++ only. 24085* Function Multiversioning:: Declaring multiple function versions. 24086* Type Traits:: Compiler support for type traits. 24087* C++ Concepts:: Improved support for generic programming. 24088* Deprecated Features:: Things will disappear from G++. 24089* Backwards Compatibility:: Compatibilities with earlier definitions of C++. 24090@end menu 24091 24092@node C++ Volatiles 24093@section When is a Volatile C++ Object Accessed? 24094@cindex accessing volatiles 24095@cindex volatile read 24096@cindex volatile write 24097@cindex volatile access 24098 24099The C++ standard differs from the C standard in its treatment of 24100volatile objects. It fails to specify what constitutes a volatile 24101access, except to say that C++ should behave in a similar manner to C 24102with respect to volatiles, where possible. However, the different 24103lvalueness of expressions between C and C++ complicate the behavior. 24104G++ behaves the same as GCC for volatile access, @xref{C 24105Extensions,,Volatiles}, for a description of GCC's behavior. 24106 24107The C and C++ language specifications differ when an object is 24108accessed in a void context: 24109 24110@smallexample 24111volatile int *src = @var{somevalue}; 24112*src; 24113@end smallexample 24114 24115The C++ standard specifies that such expressions do not undergo lvalue 24116to rvalue conversion, and that the type of the dereferenced object may 24117be incomplete. The C++ standard does not specify explicitly that it 24118is lvalue to rvalue conversion that is responsible for causing an 24119access. There is reason to believe that it is, because otherwise 24120certain simple expressions become undefined. However, because it 24121would surprise most programmers, G++ treats dereferencing a pointer to 24122volatile object of complete type as GCC would do for an equivalent 24123type in C@. When the object has incomplete type, G++ issues a 24124warning; if you wish to force an error, you must force a conversion to 24125rvalue with, for instance, a static cast. 24126 24127When using a reference to volatile, G++ does not treat equivalent 24128expressions as accesses to volatiles, but instead issues a warning that 24129no volatile is accessed. The rationale for this is that otherwise it 24130becomes difficult to determine where volatile access occur, and not 24131possible to ignore the return value from functions returning volatile 24132references. Again, if you wish to force a read, cast the reference to 24133an rvalue. 24134 24135G++ implements the same behavior as GCC does when assigning to a 24136volatile object---there is no reread of the assigned-to object, the 24137assigned rvalue is reused. Note that in C++ assignment expressions 24138are lvalues, and if used as an lvalue, the volatile object is 24139referred to. For instance, @var{vref} refers to @var{vobj}, as 24140expected, in the following example: 24141 24142@smallexample 24143volatile int vobj; 24144volatile int &vref = vobj = @var{something}; 24145@end smallexample 24146 24147@node Restricted Pointers 24148@section Restricting Pointer Aliasing 24149@cindex restricted pointers 24150@cindex restricted references 24151@cindex restricted this pointer 24152 24153As with the C front end, G++ understands the C99 feature of restricted pointers, 24154specified with the @code{__restrict__}, or @code{__restrict} type 24155qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} 24156language flag, @code{restrict} is not a keyword in C++. 24157 24158In addition to allowing restricted pointers, you can specify restricted 24159references, which indicate that the reference is not aliased in the local 24160context. 24161 24162@smallexample 24163void fn (int *__restrict__ rptr, int &__restrict__ rref) 24164@{ 24165 /* @r{@dots{}} */ 24166@} 24167@end smallexample 24168 24169@noindent 24170In the body of @code{fn}, @var{rptr} points to an unaliased integer and 24171@var{rref} refers to a (different) unaliased integer. 24172 24173You may also specify whether a member function's @var{this} pointer is 24174unaliased by using @code{__restrict__} as a member function qualifier. 24175 24176@smallexample 24177void T::fn () __restrict__ 24178@{ 24179 /* @r{@dots{}} */ 24180@} 24181@end smallexample 24182 24183@noindent 24184Within the body of @code{T::fn}, @var{this} has the effective 24185definition @code{T *__restrict__ const this}. Notice that the 24186interpretation of a @code{__restrict__} member function qualifier is 24187different to that of @code{const} or @code{volatile} qualifier, in that it 24188is applied to the pointer rather than the object. This is consistent with 24189other compilers that implement restricted pointers. 24190 24191As with all outermost parameter qualifiers, @code{__restrict__} is 24192ignored in function definition matching. This means you only need to 24193specify @code{__restrict__} in a function definition, rather than 24194in a function prototype as well. 24195 24196@node Vague Linkage 24197@section Vague Linkage 24198@cindex vague linkage 24199 24200There are several constructs in C++ that require space in the object 24201file but are not clearly tied to a single translation unit. We say that 24202these constructs have ``vague linkage''. Typically such constructs are 24203emitted wherever they are needed, though sometimes we can be more 24204clever. 24205 24206@table @asis 24207@item Inline Functions 24208Inline functions are typically defined in a header file which can be 24209included in many different compilations. Hopefully they can usually be 24210inlined, but sometimes an out-of-line copy is necessary, if the address 24211of the function is taken or if inlining fails. In general, we emit an 24212out-of-line copy in all translation units where one is needed. As an 24213exception, we only emit inline virtual functions with the vtable, since 24214it always requires a copy. 24215 24216Local static variables and string constants used in an inline function 24217are also considered to have vague linkage, since they must be shared 24218between all inlined and out-of-line instances of the function. 24219 24220@item VTables 24221@cindex vtable 24222C++ virtual functions are implemented in most compilers using a lookup 24223table, known as a vtable. The vtable contains pointers to the virtual 24224functions provided by a class, and each object of the class contains a 24225pointer to its vtable (or vtables, in some multiple-inheritance 24226situations). If the class declares any non-inline, non-pure virtual 24227functions, the first one is chosen as the ``key method'' for the class, 24228and the vtable is only emitted in the translation unit where the key 24229method is defined. 24230 24231@emph{Note:} If the chosen key method is later defined as inline, the 24232vtable is still emitted in every translation unit that defines it. 24233Make sure that any inline virtuals are declared inline in the class 24234body, even if they are not defined there. 24235 24236@item @code{type_info} objects 24237@cindex @code{type_info} 24238@cindex RTTI 24239C++ requires information about types to be written out in order to 24240implement @samp{dynamic_cast}, @samp{typeid} and exception handling. 24241For polymorphic classes (classes with virtual functions), the @samp{type_info} 24242object is written out along with the vtable so that @samp{dynamic_cast} 24243can determine the dynamic type of a class object at run time. For all 24244other types, we write out the @samp{type_info} object when it is used: when 24245applying @samp{typeid} to an expression, throwing an object, or 24246referring to a type in a catch clause or exception specification. 24247 24248@item Template Instantiations 24249Most everything in this section also applies to template instantiations, 24250but there are other options as well. 24251@xref{Template Instantiation,,Where's the Template?}. 24252 24253@end table 24254 24255When used with GNU ld version 2.8 or later on an ELF system such as 24256GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of 24257these constructs will be discarded at link time. This is known as 24258COMDAT support. 24259 24260On targets that don't support COMDAT, but do support weak symbols, GCC 24261uses them. This way one copy overrides all the others, but 24262the unused copies still take up space in the executable. 24263 24264For targets that do not support either COMDAT or weak symbols, 24265most entities with vague linkage are emitted as local symbols to 24266avoid duplicate definition errors from the linker. This does not happen 24267for local statics in inlines, however, as having multiple copies 24268almost certainly breaks things. 24269 24270@xref{C++ Interface,,Declarations and Definitions in One Header}, for 24271another way to control placement of these constructs. 24272 24273@node C++ Interface 24274@section C++ Interface and Implementation Pragmas 24275 24276@cindex interface and implementation headers, C++ 24277@cindex C++ interface and implementation headers 24278@cindex pragmas, interface and implementation 24279 24280@code{#pragma interface} and @code{#pragma implementation} provide the 24281user with a way of explicitly directing the compiler to emit entities 24282with vague linkage (and debugging information) in a particular 24283translation unit. 24284 24285@emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2 24286by COMDAT support and the ``key method'' heuristic 24287mentioned in @ref{Vague Linkage}. Using them can actually cause your 24288program to grow due to unnecessary out-of-line copies of inline 24289functions. 24290 24291@table @code 24292@item #pragma interface 24293@itemx #pragma interface "@var{subdir}/@var{objects}.h" 24294@kindex #pragma interface 24295Use this directive in @emph{header files} that define object classes, to save 24296space in most of the object files that use those classes. Normally, 24297local copies of certain information (backup copies of inline member 24298functions, debugging information, and the internal tables that implement 24299virtual functions) must be kept in each object file that includes class 24300definitions. You can use this pragma to avoid such duplication. When a 24301header file containing @samp{#pragma interface} is included in a 24302compilation, this auxiliary information is not generated (unless 24303the main input source file itself uses @samp{#pragma implementation}). 24304Instead, the object files contain references to be resolved at link 24305time. 24306 24307The second form of this directive is useful for the case where you have 24308multiple headers with the same name in different directories. If you 24309use this form, you must specify the same string to @samp{#pragma 24310implementation}. 24311 24312@item #pragma implementation 24313@itemx #pragma implementation "@var{objects}.h" 24314@kindex #pragma implementation 24315Use this pragma in a @emph{main input file}, when you want full output from 24316included header files to be generated (and made globally visible). The 24317included header file, in turn, should use @samp{#pragma interface}. 24318Backup copies of inline member functions, debugging information, and the 24319internal tables used to implement virtual functions are all generated in 24320implementation files. 24321 24322@cindex implied @code{#pragma implementation} 24323@cindex @code{#pragma implementation}, implied 24324@cindex naming convention, implementation headers 24325If you use @samp{#pragma implementation} with no argument, it applies to 24326an include file with the same basename@footnote{A file's @dfn{basename} 24327is the name stripped of all leading path information and of trailing 24328suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source 24329file. For example, in @file{allclass.cc}, giving just 24330@samp{#pragma implementation} 24331by itself is equivalent to @samp{#pragma implementation "allclass.h"}. 24332 24333Use the string argument if you want a single implementation file to 24334include code from multiple header files. (You must also use 24335@samp{#include} to include the header file; @samp{#pragma 24336implementation} only specifies how to use the file---it doesn't actually 24337include it.) 24338 24339There is no way to split up the contents of a single header file into 24340multiple implementation files. 24341@end table 24342 24343@cindex inlining and C++ pragmas 24344@cindex C++ pragmas, effect on inlining 24345@cindex pragmas in C++, effect on inlining 24346@samp{#pragma implementation} and @samp{#pragma interface} also have an 24347effect on function inlining. 24348 24349If you define a class in a header file marked with @samp{#pragma 24350interface}, the effect on an inline function defined in that class is 24351similar to an explicit @code{extern} declaration---the compiler emits 24352no code at all to define an independent version of the function. Its 24353definition is used only for inlining with its callers. 24354 24355@opindex fno-implement-inlines 24356Conversely, when you include the same header file in a main source file 24357that declares it as @samp{#pragma implementation}, the compiler emits 24358code for the function itself; this defines a version of the function 24359that can be found via pointers (or by callers compiled without 24360inlining). If all calls to the function can be inlined, you can avoid 24361emitting the function by compiling with @option{-fno-implement-inlines}. 24362If any calls are not inlined, you will get linker errors. 24363 24364@node Template Instantiation 24365@section Where's the Template? 24366@cindex template instantiation 24367 24368C++ templates were the first language feature to require more 24369intelligence from the environment than was traditionally found on a UNIX 24370system. Somehow the compiler and linker have to make sure that each 24371template instance occurs exactly once in the executable if it is needed, 24372and not at all otherwise. There are two basic approaches to this 24373problem, which are referred to as the Borland model and the Cfront model. 24374 24375@table @asis 24376@item Borland model 24377Borland C++ solved the template instantiation problem by adding the code 24378equivalent of common blocks to their linker; the compiler emits template 24379instances in each translation unit that uses them, and the linker 24380collapses them together. The advantage of this model is that the linker 24381only has to consider the object files themselves; there is no external 24382complexity to worry about. The disadvantage is that compilation time 24383is increased because the template code is being compiled repeatedly. 24384Code written for this model tends to include definitions of all 24385templates in the header file, since they must be seen to be 24386instantiated. 24387 24388@item Cfront model 24389The AT&T C++ translator, Cfront, solved the template instantiation 24390problem by creating the notion of a template repository, an 24391automatically maintained place where template instances are stored. A 24392more modern version of the repository works as follows: As individual 24393object files are built, the compiler places any template definitions and 24394instantiations encountered in the repository. At link time, the link 24395wrapper adds in the objects in the repository and compiles any needed 24396instances that were not previously emitted. The advantages of this 24397model are more optimal compilation speed and the ability to use the 24398system linker; to implement the Borland model a compiler vendor also 24399needs to replace the linker. The disadvantages are vastly increased 24400complexity, and thus potential for error; for some code this can be 24401just as transparent, but in practice it can been very difficult to build 24402multiple programs in one directory and one program in multiple 24403directories. Code written for this model tends to separate definitions 24404of non-inline member templates into a separate file, which should be 24405compiled separately. 24406@end table 24407 24408G++ implements the Borland model on targets where the linker supports it, 24409including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows. 24410Otherwise G++ implements neither automatic model. 24411 24412You have the following options for dealing with template instantiations: 24413 24414@enumerate 24415@item 24416Do nothing. Code written for the Borland model works fine, but 24417each translation unit contains instances of each of the templates it 24418uses. The duplicate instances will be discarded by the linker, but in 24419a large program, this can lead to an unacceptable amount of code 24420duplication in object files or shared libraries. 24421 24422Duplicate instances of a template can be avoided by defining an explicit 24423instantiation in one object file, and preventing the compiler from doing 24424implicit instantiations in any other object files by using an explicit 24425instantiation declaration, using the @code{extern template} syntax: 24426 24427@smallexample 24428extern template int max (int, int); 24429@end smallexample 24430 24431This syntax is defined in the C++ 2011 standard, but has been supported by 24432G++ and other compilers since well before 2011. 24433 24434Explicit instantiations can be used for the largest or most frequently 24435duplicated instances, without having to know exactly which other instances 24436are used in the rest of the program. You can scatter the explicit 24437instantiations throughout your program, perhaps putting them in the 24438translation units where the instances are used or the translation units 24439that define the templates themselves; you can put all of the explicit 24440instantiations you need into one big file; or you can create small files 24441like 24442 24443@smallexample 24444#include "Foo.h" 24445#include "Foo.cc" 24446 24447template class Foo<int>; 24448template ostream& operator << 24449 (ostream&, const Foo<int>&); 24450@end smallexample 24451 24452@noindent 24453for each of the instances you need, and create a template instantiation 24454library from those. 24455 24456This is the simplest option, but also offers flexibility and 24457fine-grained control when necessary. It is also the most portable 24458alternative and programs using this approach will work with most modern 24459compilers. 24460 24461@item 24462@opindex frepo 24463Compile your template-using code with @option{-frepo}. The compiler 24464generates files with the extension @samp{.rpo} listing all of the 24465template instantiations used in the corresponding object files that 24466could be instantiated there; the link wrapper, @samp{collect2}, 24467then updates the @samp{.rpo} files to tell the compiler where to place 24468those instantiations and rebuild any affected object files. The 24469link-time overhead is negligible after the first pass, as the compiler 24470continues to place the instantiations in the same files. 24471 24472This can be a suitable option for application code written for the Borland 24473model, as it usually just works. Code written for the Cfront model 24474needs to be modified so that the template definitions are available at 24475one or more points of instantiation; usually this is as simple as adding 24476@code{#include <tmethods.cc>} to the end of each template header. 24477 24478For library code, if you want the library to provide all of the template 24479instantiations it needs, just try to link all of its object files 24480together; the link will fail, but cause the instantiations to be 24481generated as a side effect. Be warned, however, that this may cause 24482conflicts if multiple libraries try to provide the same instantiations. 24483For greater control, use explicit instantiation as described in the next 24484option. 24485 24486@item 24487@opindex fno-implicit-templates 24488Compile your code with @option{-fno-implicit-templates} to disable the 24489implicit generation of template instances, and explicitly instantiate 24490all the ones you use. This approach requires more knowledge of exactly 24491which instances you need than do the others, but it's less 24492mysterious and allows greater control if you want to ensure that only 24493the intended instances are used. 24494 24495If you are using Cfront-model code, you can probably get away with not 24496using @option{-fno-implicit-templates} when compiling files that don't 24497@samp{#include} the member template definitions. 24498 24499If you use one big file to do the instantiations, you may want to 24500compile it without @option{-fno-implicit-templates} so you get all of the 24501instances required by your explicit instantiations (but not by any 24502other files) without having to specify them as well. 24503 24504In addition to forward declaration of explicit instantiations 24505(with @code{extern}), G++ has extended the template instantiation 24506syntax to support instantiation of the compiler support data for a 24507template class (i.e.@: the vtable) without instantiating any of its 24508members (with @code{inline}), and instantiation of only the static data 24509members of a template class, without the support data or member 24510functions (with @code{static}): 24511 24512@smallexample 24513inline template class Foo<int>; 24514static template class Foo<int>; 24515@end smallexample 24516@end enumerate 24517 24518@node Bound member functions 24519@section Extracting the Function Pointer from a Bound Pointer to Member Function 24520@cindex pmf 24521@cindex pointer to member function 24522@cindex bound pointer to member function 24523 24524In C++, pointer to member functions (PMFs) are implemented using a wide 24525pointer of sorts to handle all the possible call mechanisms; the PMF 24526needs to store information about how to adjust the @samp{this} pointer, 24527and if the function pointed to is virtual, where to find the vtable, and 24528where in the vtable to look for the member function. If you are using 24529PMFs in an inner loop, you should really reconsider that decision. If 24530that is not an option, you can extract the pointer to the function that 24531would be called for a given object/PMF pair and call it directly inside 24532the inner loop, to save a bit of time. 24533 24534Note that you still pay the penalty for the call through a 24535function pointer; on most modern architectures, such a call defeats the 24536branch prediction features of the CPU@. This is also true of normal 24537virtual function calls. 24538 24539The syntax for this extension is 24540 24541@smallexample 24542extern A a; 24543extern int (A::*fp)(); 24544typedef int (*fptr)(A *); 24545 24546fptr p = (fptr)(a.*fp); 24547@end smallexample 24548 24549For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), 24550no object is needed to obtain the address of the function. They can be 24551converted to function pointers directly: 24552 24553@smallexample 24554fptr p1 = (fptr)(&A::foo); 24555@end smallexample 24556 24557@opindex Wno-pmf-conversions 24558You must specify @option{-Wno-pmf-conversions} to use this extension. 24559 24560@node C++ Attributes 24561@section C++-Specific Variable, Function, and Type Attributes 24562 24563Some attributes only make sense for C++ programs. 24564 24565@table @code 24566@item abi_tag ("@var{tag}", ...) 24567@cindex @code{abi_tag} function attribute 24568@cindex @code{abi_tag} variable attribute 24569@cindex @code{abi_tag} type attribute 24570The @code{abi_tag} attribute can be applied to a function, variable, or class 24571declaration. It modifies the mangled name of the entity to 24572incorporate the tag name, in order to distinguish the function or 24573class from an earlier version with a different ABI; perhaps the class 24574has changed size, or the function has a different return type that is 24575not encoded in the mangled name. 24576 24577The attribute can also be applied to an inline namespace, but does not 24578affect the mangled name of the namespace; in this case it is only used 24579for @option{-Wabi-tag} warnings and automatic tagging of functions and 24580variables. Tagging inline namespaces is generally preferable to 24581tagging individual declarations, but the latter is sometimes 24582necessary, such as when only certain members of a class need to be 24583tagged. 24584 24585The argument can be a list of strings of arbitrary length. The 24586strings are sorted on output, so the order of the list is 24587unimportant. 24588 24589A redeclaration of an entity must not add new ABI tags, 24590since doing so would change the mangled name. 24591 24592The ABI tags apply to a name, so all instantiations and 24593specializations of a template have the same tags. The attribute will 24594be ignored if applied to an explicit specialization or instantiation. 24595 24596The @option{-Wabi-tag} flag enables a warning about a class which does 24597not have all the ABI tags used by its subobjects and virtual functions; for users with code 24598that needs to coexist with an earlier ABI, using this option can help 24599to find all affected types that need to be tagged. 24600 24601When a type involving an ABI tag is used as the type of a variable or 24602return type of a function where that tag is not already present in the 24603signature of the function, the tag is automatically applied to the 24604variable or function. @option{-Wabi-tag} also warns about this 24605situation; this warning can be avoided by explicitly tagging the 24606variable or function or moving it into a tagged inline namespace. 24607 24608@item init_priority (@var{priority}) 24609@cindex @code{init_priority} variable attribute 24610 24611In Standard C++, objects defined at namespace scope are guaranteed to be 24612initialized in an order in strict accordance with that of their definitions 24613@emph{in a given translation unit}. No guarantee is made for initializations 24614across translation units. However, GNU C++ allows users to control the 24615order of initialization of objects defined at namespace scope with the 24616@code{init_priority} attribute by specifying a relative @var{priority}, 24617a constant integral expression currently bounded between 101 and 65535 24618inclusive. Lower numbers indicate a higher priority. 24619 24620In the following example, @code{A} would normally be created before 24621@code{B}, but the @code{init_priority} attribute reverses that order: 24622 24623@smallexample 24624Some_Class A __attribute__ ((init_priority (2000))); 24625Some_Class B __attribute__ ((init_priority (543))); 24626@end smallexample 24627 24628@noindent 24629Note that the particular values of @var{priority} do not matter; only their 24630relative ordering. 24631 24632@item warn_unused 24633@cindex @code{warn_unused} type attribute 24634 24635For C++ types with non-trivial constructors and/or destructors it is 24636impossible for the compiler to determine whether a variable of this 24637type is truly unused if it is not referenced. This type attribute 24638informs the compiler that variables of this type should be warned 24639about if they appear to be unused, just like variables of fundamental 24640types. 24641 24642This attribute is appropriate for types which just represent a value, 24643such as @code{std::string}; it is not appropriate for types which 24644control a resource, such as @code{std::lock_guard}. 24645 24646This attribute is also accepted in C, but it is unnecessary because C 24647does not have constructors or destructors. 24648 24649@end table 24650 24651@node Function Multiversioning 24652@section Function Multiversioning 24653@cindex function versions 24654 24655With the GNU C++ front end, for x86 targets, you may specify multiple 24656versions of a function, where each function is specialized for a 24657specific target feature. At runtime, the appropriate version of the 24658function is automatically executed depending on the characteristics of 24659the execution platform. Here is an example. 24660 24661@smallexample 24662__attribute__ ((target ("default"))) 24663int foo () 24664@{ 24665 // The default version of foo. 24666 return 0; 24667@} 24668 24669__attribute__ ((target ("sse4.2"))) 24670int foo () 24671@{ 24672 // foo version for SSE4.2 24673 return 1; 24674@} 24675 24676__attribute__ ((target ("arch=atom"))) 24677int foo () 24678@{ 24679 // foo version for the Intel ATOM processor 24680 return 2; 24681@} 24682 24683__attribute__ ((target ("arch=amdfam10"))) 24684int foo () 24685@{ 24686 // foo version for the AMD Family 0x10 processors. 24687 return 3; 24688@} 24689 24690int main () 24691@{ 24692 int (*p)() = &foo; 24693 assert ((*p) () == foo ()); 24694 return 0; 24695@} 24696@end smallexample 24697 24698In the above example, four versions of function foo are created. The 24699first version of foo with the target attribute "default" is the default 24700version. This version gets executed when no other target specific 24701version qualifies for execution on a particular platform. A new version 24702of foo is created by using the same function signature but with a 24703different target string. Function foo is called or a pointer to it is 24704taken just like a regular function. GCC takes care of doing the 24705dispatching to call the right version at runtime. Refer to the 24706@uref{http://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on 24707Function Multiversioning} for more details. 24708 24709@node Type Traits 24710@section Type Traits 24711 24712The C++ front end implements syntactic extensions that allow 24713compile-time determination of 24714various characteristics of a type (or of a 24715pair of types). 24716 24717@table @code 24718@item __has_nothrow_assign (type) 24719If @code{type} is @code{const}-qualified or is a reference type then 24720the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)} 24721is @code{true} then the trait is @code{true}, else if @code{type} is 24722a cv-qualified class or union type with copy assignment operators that are 24723known not to throw an exception then the trait is @code{true}, else it is 24724@code{false}. 24725Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24726@code{void}, or an array of unknown bound. 24727 24728@item __has_nothrow_copy (type) 24729If @code{__has_trivial_copy (type)} is @code{true} then the trait is 24730@code{true}, else if @code{type} is a cv-qualified class or union type 24731with copy constructors that are known not to throw an exception then 24732the trait is @code{true}, else it is @code{false}. 24733Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24734@code{void}, or an array of unknown bound. 24735 24736@item __has_nothrow_constructor (type) 24737If @code{__has_trivial_constructor (type)} is @code{true} then the trait 24738is @code{true}, else if @code{type} is a cv class or union type (or array 24739thereof) with a default constructor that is known not to throw an 24740exception then the trait is @code{true}, else it is @code{false}. 24741Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24742@code{void}, or an array of unknown bound. 24743 24744@item __has_trivial_assign (type) 24745If @code{type} is @code{const}- qualified or is a reference type then 24746the trait is @code{false}. Otherwise if @code{__is_pod (type)} is 24747@code{true} then the trait is @code{true}, else if @code{type} is 24748a cv-qualified class or union type with a trivial copy assignment 24749([class.copy]) then the trait is @code{true}, else it is @code{false}. 24750Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24751@code{void}, or an array of unknown bound. 24752 24753@item __has_trivial_copy (type) 24754If @code{__is_pod (type)} is @code{true} or @code{type} is a reference 24755type then the trait is @code{true}, else if @code{type} is a cv class 24756or union type with a trivial copy constructor ([class.copy]) then the trait 24757is @code{true}, else it is @code{false}. Requires: @code{type} shall be 24758a complete type, (possibly cv-qualified) @code{void}, or an array of unknown 24759bound. 24760 24761@item __has_trivial_constructor (type) 24762If @code{__is_pod (type)} is @code{true} then the trait is @code{true}, 24763else if @code{type} is a cv-qualified class or union type (or array thereof) 24764with a trivial default constructor ([class.ctor]) then the trait is @code{true}, 24765else it is @code{false}. 24766Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24767@code{void}, or an array of unknown bound. 24768 24769@item __has_trivial_destructor (type) 24770If @code{__is_pod (type)} is @code{true} or @code{type} is a reference type 24771then the trait is @code{true}, else if @code{type} is a cv class or union 24772type (or array thereof) with a trivial destructor ([class.dtor]) then 24773the trait is @code{true}, else it is @code{false}. 24774Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24775@code{void}, or an array of unknown bound. 24776 24777@item __has_virtual_destructor (type) 24778If @code{type} is a class type with a virtual destructor 24779([class.dtor]) then the trait is @code{true}, else it is @code{false}. 24780Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24781@code{void}, or an array of unknown bound. 24782 24783@item __is_abstract (type) 24784If @code{type} is an abstract class ([class.abstract]) then the trait 24785is @code{true}, else it is @code{false}. 24786Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24787@code{void}, or an array of unknown bound. 24788 24789@item __is_base_of (base_type, derived_type) 24790If @code{base_type} is a base class of @code{derived_type} 24791([class.derived]) then the trait is @code{true}, otherwise it is @code{false}. 24792Top-level cv-qualifications of @code{base_type} and 24793@code{derived_type} are ignored. For the purposes of this trait, a 24794class type is considered is own base. 24795Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)} 24796are @code{true} and @code{base_type} and @code{derived_type} are not the same 24797type (disregarding cv-qualifiers), @code{derived_type} shall be a complete 24798type. A diagnostic is produced if this requirement is not met. 24799 24800@item __is_class (type) 24801If @code{type} is a cv-qualified class type, and not a union type 24802([basic.compound]) the trait is @code{true}, else it is @code{false}. 24803 24804@item __is_empty (type) 24805If @code{__is_class (type)} is @code{false} then the trait is @code{false}. 24806Otherwise @code{type} is considered empty if and only if: @code{type} 24807has no non-static data members, or all non-static data members, if 24808any, are bit-fields of length 0, and @code{type} has no virtual 24809members, and @code{type} has no virtual base classes, and @code{type} 24810has no base classes @code{base_type} for which 24811@code{__is_empty (base_type)} is @code{false}. 24812Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24813@code{void}, or an array of unknown bound. 24814 24815@item __is_enum (type) 24816If @code{type} is a cv enumeration type ([basic.compound]) the trait is 24817@code{true}, else it is @code{false}. 24818 24819@item __is_literal_type (type) 24820If @code{type} is a literal type ([basic.types]) the trait is 24821@code{true}, else it is @code{false}. 24822Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24823@code{void}, or an array of unknown bound. 24824 24825@item __is_pod (type) 24826If @code{type} is a cv POD type ([basic.types]) then the trait is @code{true}, 24827else it is @code{false}. 24828Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24829@code{void}, or an array of unknown bound. 24830 24831@item __is_polymorphic (type) 24832If @code{type} is a polymorphic class ([class.virtual]) then the trait 24833is @code{true}, else it is @code{false}. 24834Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24835@code{void}, or an array of unknown bound. 24836 24837@item __is_standard_layout (type) 24838If @code{type} is a standard-layout type ([basic.types]) the trait is 24839@code{true}, else it is @code{false}. 24840Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24841@code{void}, or an array of unknown bound. 24842 24843@item __is_trivial (type) 24844If @code{type} is a trivial type ([basic.types]) the trait is 24845@code{true}, else it is @code{false}. 24846Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24847@code{void}, or an array of unknown bound. 24848 24849@item __is_union (type) 24850If @code{type} is a cv union type ([basic.compound]) the trait is 24851@code{true}, else it is @code{false}. 24852 24853@item __underlying_type (type) 24854The underlying type of @code{type}. 24855Requires: @code{type} shall be an enumeration type ([dcl.enum]). 24856 24857@item __integer_pack (length) 24858When used as the pattern of a pack expansion within a template 24859definition, expands to a template argument pack containing integers 24860from @code{0} to @code{length-1}. This is provided for efficient 24861implementation of @code{std::make_integer_sequence}. 24862 24863@end table 24864 24865 24866@node C++ Concepts 24867@section C++ Concepts 24868 24869C++ concepts provide much-improved support for generic programming. In 24870particular, they allow the specification of constraints on template arguments. 24871The constraints are used to extend the usual overloading and partial 24872specialization capabilities of the language, allowing generic data structures 24873and algorithms to be ``refined'' based on their properties rather than their 24874type names. 24875 24876The following keywords are reserved for concepts. 24877 24878@table @code 24879@item assumes 24880States an expression as an assumption, and if possible, verifies that the 24881assumption is valid. For example, @code{assume(n > 0)}. 24882 24883@item axiom 24884Introduces an axiom definition. Axioms introduce requirements on values. 24885 24886@item forall 24887Introduces a universally quantified object in an axiom. For example, 24888@code{forall (int n) n + 0 == n}). 24889 24890@item concept 24891Introduces a concept definition. Concepts are sets of syntactic and semantic 24892requirements on types and their values. 24893 24894@item requires 24895Introduces constraints on template arguments or requirements for a member 24896function of a class template. 24897 24898@end table 24899 24900The front end also exposes a number of internal mechanism that can be used 24901to simplify the writing of type traits. Note that some of these traits are 24902likely to be removed in the future. 24903 24904@table @code 24905@item __is_same (type1, type2) 24906A binary type trait: @code{true} whenever the type arguments are the same. 24907 24908@end table 24909 24910 24911@node Deprecated Features 24912@section Deprecated Features 24913 24914In the past, the GNU C++ compiler was extended to experiment with new 24915features, at a time when the C++ language was still evolving. Now that 24916the C++ standard is complete, some of those features are superseded by 24917superior alternatives. Using the old features might cause a warning in 24918some cases that the feature will be dropped in the future. In other 24919cases, the feature might be gone already. 24920 24921G++ allows a virtual function returning @samp{void *} to be overridden 24922by one returning a different pointer type. This extension to the 24923covariant return type rules is now deprecated and will be removed from a 24924future version. 24925 24926The use of default arguments in function pointers, function typedefs 24927and other places where they are not permitted by the standard is 24928deprecated and will be removed from a future version of G++. 24929 24930G++ allows floating-point literals to appear in integral constant expressions, 24931e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} } 24932This extension is deprecated and will be removed from a future version. 24933 24934G++ allows static data members of const floating-point type to be declared 24935with an initializer in a class definition. The standard only allows 24936initializers for static members of const integral types and const 24937enumeration types so this extension has been deprecated and will be removed 24938from a future version. 24939 24940G++ allows attributes to follow a parenthesized direct initializer, 24941e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension 24942has been ignored since G++ 3.3 and is deprecated. 24943 24944G++ allows anonymous structs and unions to have members that are not 24945public non-static data members (i.e.@: fields). These extensions are 24946deprecated. 24947 24948@node Backwards Compatibility 24949@section Backwards Compatibility 24950@cindex Backwards Compatibility 24951@cindex ARM [Annotated C++ Reference Manual] 24952 24953Now that there is a definitive ISO standard C++, G++ has a specification 24954to adhere to. The C++ language evolved over time, and features that 24955used to be acceptable in previous drafts of the standard, such as the ARM 24956[Annotated C++ Reference Manual], are no longer accepted. In order to allow 24957compilation of C++ written to such drafts, G++ contains some backwards 24958compatibilities. @emph{All such backwards compatibility features are 24959liable to disappear in future versions of G++.} They should be considered 24960deprecated. @xref{Deprecated Features}. 24961 24962@table @code 24963 24964@item Implicit C language 24965Old C system header files did not contain an @code{extern "C" @{@dots{}@}} 24966scope to set the language. On such systems, all system header files are 24967implicitly scoped inside a C language scope. Such headers must 24968correctly prototype function argument types, there is no leeway for 24969@code{()} to indicate an unspecified set of arguments. 24970 24971@end table 24972 24973@c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd 24974@c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr 24975